update the welcome file to be easier to digest the documentation #21
Conversation
…ation, and bridging processes for improved user experience
…istration, and root agents for enhanced user understanding and experience
…setting up agent client and server with clear instructions and examples
… specificity and cohesion across documentation
…rus" references for clarity and consistency across guides
…nding of agent systems and related concepts in Torus documentation
… registration, demand signaling, and root agents documentation
…ders, enhancing hierarchy and clarity in Torus guides
…on from the Torus getting started section
…ion page in the start-here section of Torus guides
…warnings to documentation
…pment directory; update links accordingly
…s; delete outdated files and improve clarity in navigation
…items for improved clarity and navigation consistency
…CLI setup guide; include related images and links updates
…ious how-to guides for enhanced readability and emphasis
…ment configuration, and improve endpoint structure
…nd add new concepts for improved understanding of Torus workflow
WalkthroughThis update implements a comprehensive reorganization and relabeling of the Torus documentation site's sidebar configuration, introduces several new how-to guides and glossary pages, deletes outdated or redundant documentation, and enhances visual emphasis in guides through a new Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant DocsSidebar
participant GuidePage
participant RedText
participant CSS
User->>DocsSidebar: Navigates documentation sidebar
DocsSidebar-->>User: Shows reorganized, relabeled sections and links
User->>GuidePage: Opens a how-to or concept guide
GuidePage->>RedText: Renders emphasized instructions
RedText->>CSS: Applies new red text styles
GuidePage-->>User: Displays updated content and navigation
User->>GuidePage: Follows updated links
GuidePage-->>User: Navigates to correct, reorganized documentation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ Finishing Touches
🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🔭 Outside diff range comments (1)
src/content/docs/explanations/v05/control-space.mdx (1)
6-8: Drop unused component imports introduced by card-grid removal.
CardGrid,LinkCard, andAsideare no longer referenced in this document. Keeping them may trigger unused-import lints in MDX builds.-import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components"; +// No component imports needed after card-grid removal
🧹 Nitpick comments (21)
src/content/docs/web-apps (deprecated)/torus-portal.mdx (1)
48-49: Prefer relative doc links to keep builds portable
Hard-coding the absolute path (/how-to-guides/root-agents/become-a-root-agent) ties the site to the current base URL. If the docs are hosted under a different base path (e.g., staging), the link breaks.-**Register Agent**: Basic agent registration (different from [root agent registration](/how-to-guides/root-agents/become-a-root-agent)) +**Register Agent**: Basic agent registration (different from [root agent registration](../../how-to-guides/root-agents/become-a-root-agent))src/content/docs/development/cli/balance-operations.mdx (1)
44-46: Minor wording improvement for clarity
Consider possessive form to read more naturally.-You can also specify the name of the key, if it's located on your disk. Same as in transferring or staking. +You can also specify the key’s name if it is located on your disk, just as when transferring or staking.src/content/docs/getting-started/tokenomics.mdx (1)
13-13: Alt-text typo: “Tekenomics” → “Tokenomics”
Alt text is part of accessibility; fixing the typo helps screen-reader users.-<Image src={graph} alt="Tekenomics Graph" width="1080" /> +<Image src={graph} alt="Tokenomics Graph" width="1080" />src/content/docs/development/network/running-node.mdx (1)
88-88: Consider linking to the actual config files for quicker discoveryThe new bullet point is helpful, but readers may not know where “the appropriate files” live. Adding a relative path or a link to, e.g.
torus-node/config/*.json, would make the tip actionable.src/content/docs/explanations/v05/permissions.mdx (1)
61-63: Heading now lacks cross-links that existed beforeRemoving the three LinkCards under “Enforcement Authority System” breaks quick navigation to related pages (Control Space, Capability Permissions, Concepts). If the intent wasn’t to de-emphasise them, consider keeping a compact list or adding inline links to preserve discoverability.
src/content/docs/development/web/querying-data.mdx (1)
32-37: Add protocol prefix to sample endpoints.
The two example endpoints omithttps://, which may confuse copy-paste users.-```portal.torus.network/api/allocated-weight?userKey=<SS58Address>``` +```https://portal.torus.network/api/allocated-weight?userKey=<SS58Address>``` … -```portal.torus.network/api/allocated-weight?agentKey=<SS58Address>``` +```https://portal.torus.network/api/allocated-weight?agentKey=<SS58Address>```src/components/RedText.astro (1)
18-18: Consider semantic HTML and accessibility.While the implementation works, consider potential improvements for better semantics and accessibility:
-<span class={`${redClass} ${className}`} style="display: inline;"><slot /></span> +<span class={`${redClass} ${className}`} style="display: inline;" role="emphasis"><slot /></span>Adding
role="emphasis"provides better semantic meaning for screen readers, though this is a minor enhancement since the visual styling already conveys emphasis.src/content/docs/how-to-guides/holders/setup-a-wallet.mdx (1)
153-154: Consider converting single-item list to plain paragraphWith only one “What’s Next?” action remaining, a bullet list is visually noisy.
Optional, but switching to plain text improves readability.src/content/docs/how-to-guides/start-here.mdx (1)
42-45: Placeholders are clear, but consider tracking tickets“Manage Permissions” and “Delegate Emission Streams” are marked coming soon.
Create follow-up issues so these docs don’t get forgotten.src/content/docs/development/start-here.mdx (1)
54-60: Minor copy nit: “open-source” as adjectiveWhen “open-source” precedes a noun (e.g., “open-source code”) style guides recommend the hyphen.
Totally optional.-Explore the open source code to understand implementation details: +Explore the open-source code to understand implementation details:src/tailwind.css (2)
57-94: Duplicate@layer componentsblocks → merge for maintainabilityYou open two separate
@layer components { … }blocks back-to-back.
Tailwind merges them at build-time, but keeping a single block improves readability and avoids accidental rule shadowing.-@layer components { - /* content-links */ -} - -/* Explicitly keep sidebar navigation in original colors */ -@layer components { - /* nav-links */ -} +@layer components { + /* content-links */ + + /* --- sidebar / nav links -------------------------------------------- */ +}
96-112: Hard-coded red hex values – favour Tailwind theme tokens & verify dark-mode contrastUsing raw hex codes forfeits Tailwind’s colour-palette configurability and any future theme customisation (e.g. dark mode).
- .text-red-attention { color: #ef4444 !important; } + .text-red-attention { @apply text-red-500 !important; }Also ensure these reds meet WCAG contrast on both light & dark backgrounds.
Consider exposing them viatheme.extend.colors.attentionintailwind.config.jsfor consistency.src/content/docs/how-to-guides/builders/edit-your-agent.mdx (1)
58-67: Consider letting<Steps>handle numberingManually prefixing each step with
1.,2.… often leads to drift when authors reorder items.
<Steps>usually renders an ordered list; plain markdown bullets inside are sufficient:<Steps> -1. **Find your Agent …** +**Find your Agent …**This keeps markup minimal and avoids duplicate numbers in generated HTML.
src/content/docs/getting-started/concepts.mdx (2)
16-17: Spelling: “granularily” → “granularly”Minor typo in the narrative paragraph.
21-22: Spelling: “implemention” → “implementation”-The v0.5 is a pragmatic, growth oriented and limited implemention +The v0.5 is a pragmatic, growth-oriented and limited implementationsrc/content/docs/index.mdx (1)
15-15: Fix grammar: "Setup" should be "Set up" in this context.In this sentence structure, "set up" should be used as a verb phrase rather than the noun "setup".
-- **For Token Holders** — [Setup a Wallet, Stake TORUS, earn rewards](https://docs.torus.network/how-to-guides/holders/setup-a-wallet/) +- **For Token Holders** — [Set up a Wallet, Stake TORUS, earn rewards](https://docs.torus.network/how-to-guides/holders/setup-a-wallet/)src/content/docs/how-to-guides/builders/manage-permissions.mdx (2)
6-14: UnusedRedTextimport generates build warnings
import RedText …is never referenced in this document. Starlight treats unused MDX component imports as errors in strict mode.-import RedText from '/src/components/RedText.astro';Remove or reference
RedTextsomewhere (e.g., to highlight caution notes).
1-4: Content duplication withcreate-permission.mdxBoth guides cover “create/manage permissions” with near-identical step lists. Consider consolidating into one authoritative guide or clearly separating scopes (Create vs Manage) to avoid user confusion and long-term maintenance burden.
src/content/docs/how-to-guides/builders/setup-agent-server.mdx (3)
58-64: Plain-text mnemonic in.envis a security red flagStoring a wallet mnemonic unencrypted on disk is risky. At minimum:
• Add
.envto.gitignorein the guide
• Recommend using a secrets manager (1Password, Vault,doppler run -- …) for production deployments.Readers tend to copy guides verbatim—let’s keep them safe.
78-86: Non-null assertion hides missing env vars
process.env.AGENT_KEY!satisfies TypeScript but still passesundefinedat runtime if the variable is absent, leading to subtle failures.const agentKey = process.env.AGENT_KEY; if (!agentKey) throw new Error("AGENT_KEY not set"); … agent: new Agent({ agentKey, … })Explicit checks provide clearer errors for readers following the tutorial.
141-144: Mixed numeric/string port typesYou parse
PORTas number for the Agent but log it later as a possibly-string env var. Cast once and reuse to avoid mismatched types:-const port = process.env.PORT || 3000; +const port = Number(process.env.PORT ?? 3000);
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
public/images/how-to-guide/manage-capabilities/create-capability-confirm-information.pngis excluded by!**/*.pngpublic/images/how-to-guide/manage-capabilities/delete-capability-confirm-information.pngis excluded by!**/*.png
📒 Files selected for processing (46)
astro.config.mjs(4 hunks)src/components/RedText.astro(1 hunks)src/content/docs/concepts/agents.mdx(0 hunks)src/content/docs/concepts/network-overview.mdx(0 hunks)src/content/docs/development/cli/balance-operations.mdx(1 hunks)src/content/docs/development/cli/key-management.mdx(2 hunks)src/content/docs/development/cli/setup-cli.mdx(2 hunks)src/content/docs/development/network/global-parameters.mdx(1 hunks)src/content/docs/development/network/running-node.mdx(1 hunks)src/content/docs/development/start-here.mdx(1 hunks)src/content/docs/development/web-apps-install-and-run(old).mdx(0 hunks)src/content/docs/development/web-apps-overview(old).mdx(0 hunks)src/content/docs/development/web/overview-and-setup.mdx(2 hunks)src/content/docs/development/web/querying-data.mdx(2 hunks)src/content/docs/explanations/builders/agent-registration.mdx(2 hunks)src/content/docs/explanations/builders/demand-signaling.mdx(1 hunks)src/content/docs/explanations/root-agents/root-agents.mdx(1 hunks)src/content/docs/explanations/start-here.mdx(1 hunks)src/content/docs/explanations/v05/capability-permissions.mdx(0 hunks)src/content/docs/explanations/v05/control-space.mdx(1 hunks)src/content/docs/explanations/v05/emission-permissions.mdx(0 hunks)src/content/docs/explanations/v05/governance-dao.mdx(2 hunks)src/content/docs/explanations/v05/permissions.mdx(1 hunks)src/content/docs/getting-started/concepts-terminology.mdx(1 hunks)src/content/docs/getting-started/concepts.mdx(1 hunks)src/content/docs/getting-started/tokenomics.mdx(1 hunks)src/content/docs/how-to-guides/builders/create-permission.mdx(1 hunks)src/content/docs/how-to-guides/builders/create-signal.mdx(4 hunks)src/content/docs/how-to-guides/builders/delegate-emission-streams.mdx(1 hunks)src/content/docs/how-to-guides/builders/edit-your-agent.mdx(5 hunks)src/content/docs/how-to-guides/builders/manage-capabilities.mdx(1 hunks)src/content/docs/how-to-guides/builders/manage-permissions.mdx(1 hunks)src/content/docs/how-to-guides/builders/register-an-agent.mdx(4 hunks)src/content/docs/how-to-guides/builders/setup-agent-client.mdx(2 hunks)src/content/docs/how-to-guides/builders/setup-agent-server.mdx(3 hunks)src/content/docs/how-to-guides/holders/bridge-from-base.mdx(7 hunks)src/content/docs/how-to-guides/holders/setup-a-wallet.mdx(5 hunks)src/content/docs/how-to-guides/holders/stake-your-torus.mdx(7 hunks)src/content/docs/how-to-guides/root-agents/become-a-root-agent.mdx(4 hunks)src/content/docs/how-to-guides/start-here.mdx(3 hunks)src/content/docs/index.mdx(1 hunks)src/content/docs/web-apps (deprecated)/torus-allocator.mdx(1 hunks)src/content/docs/web-apps (deprecated)/torus-dao.mdx(0 hunks)src/content/docs/web-apps (deprecated)/torus-portal.mdx(1 hunks)src/content/docs/web-apps (deprecated)/torus-wallet.mdx(1 hunks)src/tailwind.css(1 hunks)
💤 Files with no reviewable changes (7)
- src/content/docs/explanations/v05/capability-permissions.mdx
- src/content/docs/web-apps (deprecated)/torus-dao.mdx
- src/content/docs/explanations/v05/emission-permissions.mdx
- src/content/docs/concepts/agents.mdx
- src/content/docs/development/web-apps-overview(old).mdx
- src/content/docs/development/web-apps-install-and-run(old).mdx
- src/content/docs/concepts/network-overview.mdx
🧰 Additional context used
🪛 LanguageTool
src/content/docs/development/start-here.mdx
[uncategorized] ~56-~56: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...em news ### Core Projects Explore the open source code to understand implementation detai...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
src/content/docs/getting-started/concepts.mdx
[grammar] ~16-~16: Ensure spelling is correct
Context: ...n & delegation system enables agents to granularily specialize while remaining aligned acro...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
src/content/docs/index.mdx
[grammar] ~15-~15: Ensure spelling is correct
Context: ...stuff done - For Token Holders — [Setup a Wallet, Stake TORUS, earn rewards](ht...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (59)
src/content/docs/development/network/global-parameters.mdx (1)
87-89: Nothing to flag – formatting tweak looks good
Closing fence alignment is correct and doesn’t affect rendering.src/content/docs/development/web/overview-and-setup.mdx (2)
20-22: Nice catch updating the testnet URL
The newportal.testnet.torus.network/root-allocatoraddress matches the rebranded Portal.
55-57: Typographic apostrophe fixed – thanks
No further action needed.src/content/docs/web-apps (deprecated)/torus-wallet.mdx (1)
74-76: Internal link correctly updated to the new hierarchyThe new
/development/cli/balance-operationspath aligns with the re-org and renders fine under the site root. No further action needed.src/content/docs/web-apps (deprecated)/torus-allocator.mdx (1)
39-39: Allocator URL refresh looks goodSwitching to
https://portal.torus.network/root-allocatorreflects the new portal location. Verified that the link resolves.src/content/docs/explanations/builders/demand-signaling.mdx (1)
38-38: Tokenomics link path updated — looks correctThe new
/getting-started/tokenomics/target matches the reorganised docs. No issues spotted.src/content/docs/development/cli/key-management.mdx (2)
48-50: Inline comment improves clarity – no further action needed.
The additional comment succinctly explains the purpose oftorus key list; this is helpful for newcomers.
72-72: Sentence reads well – LGTM.
No issues spotted with the new explanatory line.src/content/docs/explanations/root-agents/root-agents.mdx (1)
34-36: Confirm updated paths resolve correctly.
The new absolute URLs look correct, but a quick manual click-test (or link-checker run) will prevent broken docs once deployed.src/content/docs/how-to-guides/root-agents/become-a-root-agent.mdx (3)
13-13: LGTM: Component import added correctly.The RedText component import is properly added and will be used consistently throughout the file for visual emphasis.
67-67: Good use of RedText component for UI emphasis.The RedText component with "light" variant is appropriately used to highlight key UI button labels ("Connect Wallet" and "Submit Proposal"), improving visual guidance for users.
Also applies to: 88-88
46-46: URLs Consistency VerifiedAll occurrences of the old “participants” and “bridge-to-base” links have been removed, and the new “holders/setup-a-wallet” and “holders/bridge-from-base” URLs are now used uniformly across the documentation (e.g., start-here.mdx, become-a-root-agent.mdx, register-an-agent.mdx, edit-your-agent.mdx, stake-your-torus.mdx, index.mdx). No further updates are required.
src/content/docs/explanations/start-here.mdx (1)
20-31: Excellent documentation organization improvement.The new "v0.5 Related Topics" section effectively consolidates key technical concepts in a logical flow:
- Control Space (foundation)
- Permission System (core interactions)
- Capability/Emission Permissions (specific mechanisms)
- Governance & DAO (decision-making)
This structure helps users understand the technical hierarchy and relationships between concepts.
src/components/RedText.astro (2)
2-5: Well-designed component interface.The Props interface is clean and provides appropriate flexibility with optional variant selection and custom class support.
7-16: Solid implementation with good defaults.The component implementation follows best practices:
- Destructuring with sensible defaults
- Clear variant-to-class mapping
- Proper variable naming
The logic is straightforward and maintainable.
src/content/docs/development/cli/setup-cli.mdx (2)
140-143: URL updates align with documentation restructuring.The path updates correctly reflect the new documentation structure:
- CLI paths moved from
/cli/to/development/cli/- Consistent relative path usage
- Links properly updated to match the new sidebar organization
156-160: Consistent path updates in related topics.The CardGrid links are properly updated to match the new
/development/cli/structure, maintaining consistency throughout the documentation.src/content/docs/explanations/builders/agent-registration.mdx (3)
20-27: Excellent addition of critical user guidance.The caution aside about agent name immutability is crucial information that prevents costly user mistakes. The explanation clearly communicates:
- The permanence of the decision
- The technical reasoning (permission system consistency)
- The practical impact (identity confusion prevention)
This proactive guidance will save users from registration regrets.
41-41: URL correction improves accuracy.The update from "Allocator page" at
allocator.torus.networkto "Allocator tab" atportal.torus.network/root-allocatorreflects the current infrastructure and provides users with the correct location.
48-49: Documentation links updated for v0.5 structure.The URLs have been updated to point to the new
explanations/v05/paths, maintaining consistency with the overall documentation restructuring.src/content/docs/how-to-guides/holders/setup-a-wallet.mdx (1)
21-24: Import looks goodNo issues with the new
RedTextimport; path resolves to the components folder and keeps tree-shaking intact.src/content/docs/how-to-guides/holders/bridge-from-base.mdx (2)
74-80: Sequential numbering resets – double-check rendered outputInside the
<Steps>component you restart at1.after having used1.&2.previously.
IfStepsrenders native<ol>elements this will appear as1, 1, 2.
Either rely on automatic numbering (1.for every item) or continue the manual sequence to avoid confusion.
70-80: Good use of RedText for critical UI cuesAll new highlights use the correct
variant="light"prop and clearly draw attention to error-prone actions.src/content/docs/how-to-guides/builders/create-signal.mdx (1)
52-57: LGTM – emphasis reads well
RedTextis used sparingly and improves scannability without over-styling the content.src/content/docs/how-to-guides/start-here.mdx (1)
22-30: Holder section link updates look correctNew slug structure (
/holders/) matches the sidebar re-org—no broken links detected.src/content/docs/development/start-here.mdx (1)
19-44: Solid structure for new developer landing pageClear breakout between Web, CLI and Infra keeps onboarding tight. No structural issues found.
src/content/docs/how-to-guides/builders/edit-your-agent.mdx (1)
15-16: Import path may break without a configured Vite alias
import RedText from '/src/components/RedText.astro';is an absolute path from the filesystem root.
Unless you have a/src ↦ <repoRoot>/srcalias, this will fail in production builds.-import RedText from '/src/components/RedText.astro'; +import RedText from '../../components/RedText.astro';(or use the alias defined in
tsconfig.json/vite.config.tssuch as@/components/RedText.astro)src/content/docs/how-to-guides/builders/register-an-agent.mdx (1)
14-15: Same absolute-path import caveat as aboveEnsure the
/src/components/RedText.astroalias exists or switch to a relative/aliased path.src/content/docs/getting-started/concepts-terminology.mdx (1)
1-81: Well-structured glossary – good additionContent reads clearly, sections are logically grouped, and the aside makes future maintenance explicit. Nice work.
src/content/docs/how-to-guides/builders/setup-agent-client.mdx (6)
12-12: LGTM! Component import follows correct pattern.The RedText component import is properly structured and aligns with the new styling system being introduced across the documentation.
46-51: Excellent improvement in dependency management.The addition of
dotenvand@types/nodeshows proper consideration for environment management and TypeScript development. This is a significant security improvement over hardcoded credentials.
57-61: Good security practice with environment variables.The
.envfile structure properly separates sensitive configuration from code. The variable naming is clear and follows common conventions.
72-91: Robust client creation with proper error handling.The asynchronous
createClientfunction demonstrates excellent practices:
- Environment validation before proceeding
- Clear error messages
- Proper error propagation
- Informative logging
This is a significant improvement over simpler initialization patterns.
97-117: Well-structured API call wrapper with comprehensive error handling.The
callAgentfunction encapsulates API calls effectively with:
- Request logging for debugging
- Explicit success/failure handling
- Detailed error information
- Consistent error propagation
This pattern makes the SDK easier to use and debug.
123-150: Complete example demonstrates real-world usage patterns.The
mainfunction provides a practical example showing:
- Proper initialization flow
- Multiple API calls
- Error handling with process exit
- Clear logging throughout
This gives developers a solid foundation to build upon.
src/content/docs/index.mdx (4)
7-7: LGTM! Component import follows established pattern.The RedText component import is consistent with other documentation files and properly structured.
9-11: Clear and engaging introduction.The restructured introduction effectively communicates Torus's value proposition while remaining accessible to different user types.
23-25: Well-organized "Understand more" section.The hierarchical approach from concepts to tokenomics to detailed explanations provides a logical learning path for users.
43-44: Effective use of RedText component for navigation guidance.The styling helps draw attention to different documentation paths while maintaining readability.
src/content/docs/how-to-guides/holders/stake-your-torus.mdx (5)
14-14: Consistent component import pattern.The RedText component import follows the established pattern used across other documentation files.
47-47: Updated links reflect new documentation structure.The URL changes to
/how-to-guides/holders/paths align with the sidebar reorganization and improve navigation consistency.Also applies to: 51-51
61-61: Effective use of RedText for UI element emphasis.The RedText component appropriately highlights interactive elements like buttons and tabs, making the instructions clearer for users following the guide.
Also applies to: 65-65, 77-78, 91-91
105-105: Terminology update from "Allocator App" to "Allocator Tab" improves accuracy.The updated terminology better reflects the actual UI structure and provides more precise guidance to users.
Also applies to: 121-121
163-164: Updated links maintain consistency with new documentation structure.The link updates to the "Allocator tab" and tokenomics section align with the overall documentation reorganization.
src/content/docs/how-to-guides/builders/manage-capabilities.mdx (6)
6-17: Well-organized imports and assets.The component imports are properly structured and the image assets follow consistent naming conventions for the capability management workflow.
18-26: Clear introduction explaining the value proposition.The opening effectively explains both what capabilities are and why managing them matters, covering both the collaborative benefits and security considerations.
63-82: Comprehensive validation rules with clear examples.The capability path validation section provides:
- Clear character restrictions
- Multiple valid examples showing different patterns
- Invalid examples with specific explanations
- Proper use of RedText for emphasis
This gives users concrete guidance to avoid common mistakes.
86-95: Helpful REST method explanations.The REST method descriptions provide practical context for each option, including specific use cases. This helps users choose the appropriate method for their capability.
124-135: Excellent explanation of segment-based deletion.The deletion logic explanation with concrete examples helps users understand the cascading effect of capability deletion. The visual cues (green/red segments) mentioned align well with the UI design.
137-141: Appropriate warning for destructive operations.The caution aside properly emphasizes the permanent nature of capability deletion and potential impact on integrations. This prevents accidental destructive actions.
astro.config.mjs (7)
28-31: Improved Getting Started section structure.The label updates ("Welcome" instead of "Introduction", "Understanding Torus" instead of "Concepts & Terminology") create clearer, more welcoming entry points for new users.
40-48: Better organization with v0.5 versioning.Moving version-specific content under a dedicated "v0.5" subsection provides clear context and prepares for future version documentation organization.
57-59: Updated builder section reflects current focus.The addition of "Agent Server" and "Agent Client" items aligns with the comprehensive guides being added for these topics.
62-62: Clear terminology: "Goal Leaders" instead of "Leaders".The more specific label helps users understand the role and context better than the generic "Leaders" term.
78-81: Consistent path structure for holder guides.The updated slugs create a clear hierarchy under "how-to-guides/holders/" and the new "Manage Capabilities" item reflects the comprehensive guide being added.
Also applies to: 89-89
91-92: Appropriate use of comments for incomplete features.Commenting out the incomplete guides ("Manage Permissions", "Delegate Emission Streams") while keeping them visible in the code shows good planning for future additions.
109-141: Well-structured Development section consolidation.The reorganization of CLI & Tools content into a comprehensive "Development" section with logical subsections (Web Apps, CLI Reference, Network Operations) creates better information architecture and user navigation.
src/content/docs/how-to-guides/builders/delegate-emission-streams.mdx (1)
6-15: Verify absolute import path forRedText
import RedText from '/src/components/RedText.astro'uses a leading slash which Astro resolves only when an alias for/→ project root is configured. In a default Starlight setup this resolves to the site root at runtime and 404s.Safer, alias-agnostic import:
-import RedText from '/src/components/RedText.astro'; +import RedText from '../../../components/RedText.astro';(or configure
import.meta.env.BASE_URLalias).Broken imports cause the whole page to fail hydration.
src/content/docs/how-to-guides/builders/setup-agent-server.mdx (1)
68-74: Import path may be incorrect for current SDKPlease confirm that
@torus-network/sdk/agentis a published sub-path export. If not, change to:-import { Agent } from "@torus-network/sdk/agent"; +import { Agent } from "@torus-network/sdk";A wrong sub-path breaks TypeScript resolution and runtime ESM loading.
| description: Learn how to query the stake weight between keys | ||
| --- | ||
|
|
||
| import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components"; |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Prune unused component imports.
CardGrid and LinkCard are not utilised in this file; only Aside is required.
-import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components";
+import { Aside } from "@astrojs/starlight/components";📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components"; | |
| import { Aside } from "@astrojs/starlight/components"; |
🤖 Prompt for AI Agents
In src/content/docs/development/web/querying-data.mdx at line 6, remove the
unused imports CardGrid and LinkCard from the import statement, leaving only
Aside imported from "@astrojs/starlight/components" to clean up the code and
avoid unnecessary imports.
| label: Register an Agent | ||
| --- | ||
|
|
||
| import { Tabs, TabItem, Aside, LinkCard } from "@astrojs/starlight/components"; |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Remove unused LinkCard import.
Since link-cards were deleted, LinkCard isn’t used. Trim the import to avoid MDX compile warnings.
-import { Tabs, TabItem, Aside, LinkCard } from "@astrojs/starlight/components";
+import { Tabs, TabItem, Aside } from "@astrojs/starlight/components";📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| import { Tabs, TabItem, Aside, LinkCard } from "@astrojs/starlight/components"; | |
| import { Tabs, TabItem, Aside } from "@astrojs/starlight/components"; |
🤖 Prompt for AI Agents
In src/content/docs/explanations/v05/governance-dao.mdx at line 6, the import
statement includes LinkCard which is no longer used because link-cards were
deleted. Remove LinkCard from the import list to prevent MDX compile warnings
and keep the code clean.
| --- | ||
| title: Manage Permissions | ||
| description: Step-by-step guide to creating, editing, and managing permissions in Torus's recursive delegation system. | ||
| --- |
There was a problem hiding this comment.
Filename ↔︎ front-matter title mismatch will break routing & produce duplicate slugs
The file is named create-permission.mdx but declares
title: Manage Permissions.
With another file already called manage-permissions.mdx, Starlight will generate two pages whose slugs collide (/manage-permissions/), or worse, one will shadow the other depending on build order.
Either:
- title: Manage Permissions
+ title: Create Permissionor rename the file to manage-permissions.mdx and delete/merge the duplicate.
Failing to fix this will cause broken links like /how-to-guides/builders/create-permission at the bottom of other guides.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| title: Manage Permissions | |
| description: Step-by-step guide to creating, editing, and managing permissions in Torus's recursive delegation system. | |
| --- | |
| --- | |
| title: Create Permission | |
| description: Step-by-step guide to creating, editing, and managing permissions in Torus's recursive delegation system. | |
| --- |
🤖 Prompt for AI Agents
In src/content/docs/how-to-guides/builders/create-permission.mdx lines 1 to 4,
the front-matter title "Manage Permissions" does not match the filename
"create-permission.mdx", causing slug conflicts with an existing
"manage-permissions.mdx" file. To fix this, either rename this file to
"manage-permissions.mdx" and merge or delete duplicates, or update the
front-matter title to match the current filename to ensure unique slugs and
prevent routing issues.
| 6. **Check your Agent on the [Allocator tab](https://portal.torus.network/root-allocator?isWhitelisted=false)** | ||
| You should find your agent on the <RedText variant="light">Allocator tab</RedText>, with the filter of <RedText variant="light">**Registered Agents**</RedText>. | ||
| <ClickableImage src={registeredAgents} alt="Allocator tab" /> | ||
|
|
||
| 6. **All Done** | ||
| You've now successfully registered an Agent on Torus. |
There was a problem hiding this comment.
Duplicate step number – breaks ordered lists
There are two “6.” steps. Renumber the “All Done” section.
-6. **All Done**
+7. **All Done** 📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 6. **Check your Agent on the [Allocator tab](https://portal.torus.network/root-allocator?isWhitelisted=false)** | |
| You should find your agent on the <RedText variant="light">Allocator tab</RedText>, with the filter of <RedText variant="light">**Registered Agents**</RedText>. | |
| <ClickableImage src={registeredAgents} alt="Allocator tab" /> | |
| 6. **All Done** | |
| You've now successfully registered an Agent on Torus. | |
| 6. **Check your Agent on the [Allocator tab](https://portal.torus.network/root-allocator?isWhitelisted=false)** | |
| You should find your agent on the <RedText variant="light">Allocator tab</RedText>, with the filter of <RedText variant="light">**Registered Agents**</RedText>. | |
| <ClickableImage src={registeredAgents} alt="Allocator tab" /> | |
| 7. **All Done** | |
| You've now successfully registered an Agent on Torus. |
🤖 Prompt for AI Agents
In src/content/docs/how-to-guides/builders/register-an-agent.mdx around lines
115 to 120, there are two steps numbered "6." which breaks the ordered list
formatting. Change the second "6." in the "All Done" section to "7." to maintain
proper sequential numbering in the list.
| 3. **Search for Torus and activate it** | ||
| Click on the search bar, type Torus, and select it from the list. Make sure to enable it so it appears in your list of active tokens. | ||
| Click on the search bar, type Torus, and select it from the list. <RedText varian="light">Make sure to enable it</RedText> so it appears in your list of active tokens. | ||
| <ClickableImage src={subwalletSearchTorusNetwork} alt="SubWallet search for Torus button" /> |
There was a problem hiding this comment.
Fix typo in RedText prop or the component will render incorrectly
varian="light" is missing the t. At build-time this will likely throw an Astro/React prop-validation error and the highlight won’t appear.
-<RedText varian="light">Make sure to enable it</RedText>
+<RedText variant="light">Make sure to enable it</RedText>📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 3. **Search for Torus and activate it** | |
| Click on the search bar, type Torus, and select it from the list. Make sure to enable it so it appears in your list of active tokens. | |
| Click on the search bar, type Torus, and select it from the list. <RedText varian="light">Make sure to enable it</RedText> so it appears in your list of active tokens. | |
| <ClickableImage src={subwalletSearchTorusNetwork} alt="SubWallet search for Torus button" /> | |
| 3. **Search for Torus and activate it** | |
| Click on the search bar, type Torus, and select it from the list. <RedText variant="light">Make sure to enable it</RedText> so it appears in your list of active tokens. | |
| <ClickableImage src={subwalletSearchTorusNetwork} alt="SubWallet search for Torus button" /> |
🤖 Prompt for AI Agents
In src/content/docs/how-to-guides/holders/setup-a-wallet.mdx around lines 125 to
127, the RedText component has a typo in the prop name "varian" which should be
corrected to "variant" to ensure proper rendering and avoid build-time errors.
Update the prop name from "varian" to "variant" in the RedText component usage.
| .sl-markdown-content a, | ||
| .starlight-aside a, | ||
| article a, | ||
| main a, | ||
| p a, | ||
| ul:not(nav ul) li a, | ||
| ol:not(nav ol) li a { | ||
| color: #3b82f6 !important; /* Tailwind blue-500 - soft blue */ |
There was a problem hiding this comment.
:not() selector is invalid and silently ignored
ul:not(nav ul) / ol:not(nav ol) break the CSS Grammar because the argument of :not() cannot include a descendant combinator ( ).
As a result, the selector is ignored – the link colour rule never applies to list items, defeating the intent.
- ul:not(nav ul) li a,
- ol:not(nav ol) li a {
+ /* exclude lists that are *inside* a nav element */
+ ul:not(nav ul) li a, /* <-- invalid */
+ ol:not(nav ol) li a { /* <-- invalid */
+
+ /* Suggested fix */
+ ul:not(:where(nav ul)) li a,
+ ol:not(:where(nav ol)) li a {(The :where() hack preserves specificity while allowing the descendant.)
Please adjust – or switch to a utility class generated with @apply to avoid brittle selectors altogether.
Also applies to: 38-40
🤖 Prompt for AI Agents
In src/tailwind.css around lines 34 to 41, the selectors using :not() with
descendant combinators like ul:not(nav ul) and ol:not(nav ol) are invalid and
ignored by CSS. Replace these selectors with valid alternatives, such as using
:where() to maintain specificity without descendant combinators, or refactor the
styling to use utility classes with @apply to avoid brittle selectors. Update
all occurrences on lines 38 to 40 similarly.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
src/content/docs/getting-started/concepts.mdx (3)
6-6: Remove or actually use the imported UI components
CardGrid,LinkCard, andAsideare imported but never referenced, which will trigger an “unused export” / bundle-size warning in Starlight builds.
Drop the import or integrate the components (e.g. as a sidebar call-out or further-reading grid).
8-8: Duplicate top-level heading – omit the manual#Starlight automatically renders the page title from the front-matter
title:field.
Keeping the manual# Layer1 …results in two H1s, harming semantics and accessibility.
Simply delete the Markdown heading.-# Layer1 self-assembling & self-optimizing autonomous super-swarm
27-28: Clean up wording in the v0.5 sectionMinor language fixes improve professionalism:
-The v0.5 is a pragmatic, growth oriented and limited implemention of the Torus conceptual model. -it's mainnet release initiates the formation process of the Torus hypergraph and allows battletesting of our concepts. +The v0.5 release is a pragmatic, growth-oriented and limited implementation of the Torus conceptual model. +Its mainnet launch initiates the formation of the Torus hypergraph and allows battle-testing of our concepts.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
astro.config.mjs(4 hunks)src/content/docs/getting-started/concepts.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- astro.config.mjs
🧰 Additional context used
🪛 LanguageTool
src/content/docs/getting-started/concepts.mdx
[grammar] ~21-~21: Ensure spelling is correct
Context: ...n & delegation system enables agents to granularily specialize while remaining aligned acro...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
| Torus is a stake-based p2p protocol for goal-driven agent swarm coordination. | ||
| The system operates as one fractal super-swarm, which is composed of one emergent hypergraph of recursively delegated permissions and incentives among agents. | ||
| warms are subgraphs, and can form at any position in the hypergraph. | ||
|
|
||
| The biological analogy for the stake root is the genome, where the genetic library is stored offchain in the evolving minds of the stakeholders and the Torus memeplex, continuously mutating, and the onchain stake-based control mechanism is the gene regulatory system, translating how the genetic library can express itself onto the Torus | ||
| The Torus hypergraph emerges from and aligns back to the stake root, tethering the system to the interests of stake. | ||
| orus aligns towards the central point of stake, while stake is decentralized representing the system as a whole, effectively aligning it to itself. | ||
|
|
||
| --- | ||
| ### Emissions | ||
|
|
||
| Emissions are the continuous distribution of TORUS tokens to agents based on their utility and stake allocation. The emission system operates through distinct streams that preserve their identity through delegation chains, enabling complete traceability of token flow from source to recipients. | ||
|
|
||
| Agents can delegate portions of their emissions to other agents through stream-based allocations (percentage-based) or fixed amount allocations, creating complex economic coordination structures. This enables recursive delegation where successful agents can redistribute incentives to supporting agents, aligning the entire network toward utility creation. | ||
|
|
||
| --- | ||
| ### Namespace | ||
|
|
||
| A namespace is a hierarchical naming system that enables agents to organize and delegate access to their capabilities and services. Using dot-separated paths (like `agent.alice.memory.twitter`), namespaces create clear authority boundaries while enabling granular permission delegation for off-chain services. | ||
| Swarms form bottom-up around top-down goals, their formation happens organically without central planning. | ||
| Swarms operate as self-assembling multi-scale competency architectures, | ||
| ollectively navigating towards complex goals with full autonomy at every level and open competition at every edge. | ||
|
|
||
| Namespaces represent the *potential* for creating new controls, acting as genetic templates from which specific permissions can emerge. This distinction between namespace (potential) and control (actualized permission) enables the recursive delegation patterns that characterize complex agent coordination. | ||
| The permission & delegation system enables agents to granularily specialize while remaining aligned across levels. | ||
| Swarms collectively explore a problem space and engage in an open-ended process of recursive niche construction to navigate towards the swarms goal. |
There was a problem hiding this comment.
Fix multiple typos and stray leading spaces
Several lines contain copy-paste artefacts or spelling mistakes that hurt credibility.
- warms are subgraphs, and can form at any position in the hypergraph.
- orus aligns towards the central point of stake, while stake is decentralized representing the system as a whole, effectively aligning it to itself.
+Swarms are subgraphs and can form at any position in the hypergraph.
+Torus aligns towards the central point of stake, while stake is decentralized, representing the system as a whole and effectively aligning it to itself.
- ollectively navigating towards complex goals with full autonomy at every level and open competition at every edge.
+collectively navigating towards complex goals with full autonomy at every level and open competition at every edge.
-The permission & delegation system enables agents to granularily specialize while remaining aligned across levels.
+The permission & delegation system enables agents to granularly specialize while remaining aligned across levels.
-Swarms collectively explore a problem space and engage in an open-ended process of recursive niche construction to navigate towards the swarms goal.
+Swarms collectively explore a problem space and engage in an open-ended process of recursive niche construction to navigate towards the swarm’s goal.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Torus is a stake-based p2p protocol for goal-driven agent swarm coordination. | |
| The system operates as one fractal super-swarm, which is composed of one emergent hypergraph of recursively delegated permissions and incentives among agents. | |
| warms are subgraphs, and can form at any position in the hypergraph. | |
| The biological analogy for the stake root is the genome, where the genetic library is stored offchain in the evolving minds of the stakeholders and the Torus memeplex, continuously mutating, and the onchain stake-based control mechanism is the gene regulatory system, translating how the genetic library can express itself onto the Torus | |
| The Torus hypergraph emerges from and aligns back to the stake root, tethering the system to the interests of stake. | |
| orus aligns towards the central point of stake, while stake is decentralized representing the system as a whole, effectively aligning it to itself. | |
| --- | |
| ### Emissions | |
| Emissions are the continuous distribution of TORUS tokens to agents based on their utility and stake allocation. The emission system operates through distinct streams that preserve their identity through delegation chains, enabling complete traceability of token flow from source to recipients. | |
| Agents can delegate portions of their emissions to other agents through stream-based allocations (percentage-based) or fixed amount allocations, creating complex economic coordination structures. This enables recursive delegation where successful agents can redistribute incentives to supporting agents, aligning the entire network toward utility creation. | |
| --- | |
| ### Namespace | |
| A namespace is a hierarchical naming system that enables agents to organize and delegate access to their capabilities and services. Using dot-separated paths (like `agent.alice.memory.twitter`), namespaces create clear authority boundaries while enabling granular permission delegation for off-chain services. | |
| Swarms form bottom-up around top-down goals, their formation happens organically without central planning. | |
| Swarms operate as self-assembling multi-scale competency architectures, | |
| ollectively navigating towards complex goals with full autonomy at every level and open competition at every edge. | |
| Namespaces represent the *potential* for creating new controls, acting as genetic templates from which specific permissions can emerge. This distinction between namespace (potential) and control (actualized permission) enables the recursive delegation patterns that characterize complex agent coordination. | |
| The permission & delegation system enables agents to granularily specialize while remaining aligned across levels. | |
| Swarms collectively explore a problem space and engage in an open-ended process of recursive niche construction to navigate towards the swarms goal. | |
| Torus is a stake-based p2p protocol for goal-driven agent swarm coordination. | |
| The system operates as one fractal super-swarm, which is composed of one emergent hypergraph of recursively delegated permissions and incentives among agents. | |
| Swarms are subgraphs and can form at any position in the hypergraph. | |
| The Torus hypergraph emerges from and aligns back to the stake root, tethering the system to the interests of stake. | |
| Torus aligns towards the central point of stake, while stake is decentralized, representing the system as a whole and effectively aligning it to itself. | |
| Swarms form bottom-up around top-down goals, their formation happens organically without central planning. | |
| Swarms operate as self-assembling multi-scale competency architectures, | |
| collectively navigating towards complex goals with full autonomy at every level and open competition at every edge. | |
| The permission & delegation system enables agents to granularly specialize while remaining aligned across levels. | |
| Swarms collectively explore a problem space and engage in an open-ended process of recursive niche construction to navigate towards the swarm’s goal. |
🧰 Tools
🪛 LanguageTool
[grammar] ~21-~21: Ensure spelling is correct
Context: ...n & delegation system enables agents to granularily specialize while remaining aligned acro...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
In src/content/docs/getting-started/concepts.mdx around lines 10 to 22, fix
multiple typos and remove stray leading spaces at the start of lines. Correct
misspellings such as "stake-based" instead of "stake-based," "swarms" instead of
"warms," and "collectively" instead of "ollectively." Also, ensure proper
capitalization and spacing, for example, "Torus" instead of "orus," and remove
any unintended line breaks or spaces that disrupt sentence flow.
Summary by CodeRabbit
New Features
Documentation
Style
Bug Fixes