Conversation
…and development guides for clarity and consistency
…nd setup guide, removing the old overview file
WalkthroughThis update reorganizes and clarifies the Torus documentation. It introduces new and restructured guides for web app setup, updates navigation and sidebar configurations, revises several documentation pages for clarity, and replaces outdated URLs and references. Some documentation files are renamed or deleted, and navigation links are adjusted throughout for consistency. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Docs Site
participant Torus Portal
User->>Docs Site: Accesses documentation
Docs Site-->>User: Presents updated sidebar and navigation
User->>Docs Site: Follows "Web Apps Overview and Setup"
Docs Site-->>User: Shows setup guide, prerequisites, and instructions
User->>Docs Site: Navigates agent management docs
Docs Site-->>User: Displays revised agent roles and application processes
User->>Torus Portal: Uses interface as described in quick guide
Torus Portal-->>User: Provides permission management features
Possibly related PRs
Poem
✨ Finishing Touches
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: 3
🧹 Nitpick comments (19)
src/content/docs/network/running-node.mdx (1)
21-21: Use commit-pinned URL to prevent future link rotLinking to
mainrisks 404s if the file is renamed or the default branch changes.
Prefer a permalink to a specific commit or tag, e.g.-[using Nix](https://github.com/renlabs-dev/torus-substrate/blob/main/docs/nix.md) +[using Nix](https://github.com/renlabs-dev/torus-substrate/blob/<commit-or-tag>/docs/nix.md)This keeps historical docs stable.
src/content/docs/getting-started/setup-cli.mdx (1)
149-150: Anchor text is stale – keep capitalization consistent with footnote label
[torus cli Discord channel]renders, but the product is branded “Torus CLI”.
Recommend:-If you have any questions, feel free to ask on the [torus cli Discord channel]. +If you have any questions, feel free to ask on the [Torus CLI Discord channel].…and update the footnote label accordingly to avoid confusion.
src/content/docs/concepts/network-overview.mdx (1)
13-13: Extraneous blank lineThe added blank line is harmless but unnecessary noise in git history; feel free to drop it.
src/content/docs/agents/server-setup.mdx (1)
237-244: Clarify default network and offer testnet fallbackThe inline comment now states the default is
['wss://api.torus.network'](mainnet).
Nearly every quick-start snippet earlier in the docs still references testnet endpoints. To avoid developer confusion, add a short sentence after the interface or an<Aside type="tip">explaining how to switch towss://api.testnet.torus.networkfor staging environments.src/content/docs/v05/permissions.mdx (1)
67-75: Consistency in terminologyCard #1 says “capability instantiation”, while the body of this page (and other docs) refers to “capability permissions”. Recommend harmonising the wording to avoid users thinking “instantiation” is a distinct concept.
src/content/docs/concepts/governance-dao.mdx (2)
4-10: Prev/next navigation can break if slug changes
/agents/register-agentis mapped in the sidebar, so 👍.
If that page is later moved again, these hard-coded links will stale-out.
Optional: deriveprev/nextfrom the sidebar tree instead of duplicating slugs manually.
83-85: Card path trailing slash & description mismatch
- The link includes a trailing
/(/agents/apply-root-agent/) whereas the sidebar uses/agents/apply-root-agent. Astro will usually normalise, but being consistent avoids duplicate canonical URLs.- Description still says “register an agent” – this page is specifically about whitelist / root-agent application.
- href="/agents/apply-root-agent/" - description="Learn how to register an agent in Torus." + href="/agents/apply-root-agent" + description="Apply to become a root agent via DAO whitelist."astro.config.mjs (1)
29-32: Minor: Alphabetical ordering improves scan-abilityInside “Getting Started”, items are almost alphabetical except this new entry. Placing “Concepts & Terminology” after “Introduction” but before “Setup CLI” maintains the pattern.
Totally optional; ignore if ordering is intentional.
src/content/docs/agents/apply-root-agent.mdx (1)
22-27: Tighten phrasing for easier scanningThe three consecutive sentences repeat “root agent” four times and run long. Consider compressing to improve readability:
-Root agents can be used to set goals under which swarms of agents can form. -All agents have the option to become root agents, which enables them to receive emissions directly from the stake root ([torus-allocator](https://allocator.torus.network/)). Otherwise, they act like normal agents. -Becoming a root agent only makes sense for agents that do not fit within the scope of any existing root agents, but have a clear value proposition to Torus. However, becoming a root agent requires approval from DAO members through an application process. +Any agent may apply to become a **root agent** – an anchor that swarms of sub-agents can rally around. +A root agent receives emissions directly from the stake-root ([torus-allocator](https://allocator.torus.network/)) but otherwise behaves like a normal agent. +Apply only if your agent’s scope is not covered by an existing root agent and you can articulate clear value to Torus. Approval is granted via DAO vote.src/content/docs/v05/capability-permissions.mdx (1)
194-196: Add main-net/test-net guidanceYou switched the primary RPC to
wss://api.torus.network, but the surrounding doc never tells users how to target testnet. A quick tip box would reduce confusion.src/content/docs/agents/demand-signaling.mdx (2)
24-29: Minor wording & flowSentence is long and slightly ambiguous. Consider tightening:
-The **"create signal"** feature on the Portal allows root agents to express in a technical and economical way their demand for specialized capabilities from other agents. +The **“Create Signal”** feature lets **root agents** publicly declare — in both technical and economic terms — their demand for specialised capabilities supplied by other agents.
41-43: Capitalize badge text consistentlyCard titles elsewhere use Title Case (“Root Agent”), here the body uses sentence case. For consistency:
-You must be a root agent in Torus. +You must be a Root Agent in Torus.src/content/docs/development/web-apps-install-and-run(old).mdx (3)
110-112: Typo: “builded” → “built”- needs to be builded + needs to be built
137-139: Typo: “aswell” → “as well”
85-92: Port mapping duplicates-pflag
-p 1337:1337already sets the container port; the trailingpostgres -p 1337is redundant and may confuse newcomers.- -p 1337:1337 \ - -d postgres:16-alpine \ - postgres -p 1337 + -p 1337:1337 \ + -d postgres:16-alpinesrc/content/docs/development/web-apps-overview-and-setup.mdx (2)
217-218: Typo: “dependant” → “dependent”; possessive “its”-otherwise dependant packages may typecheck its sources +otherwise dependent packages may type-check its sources
31-37: Hyphenate “Docker Tip” heading for consistencyMinor style nit:
-##### Docker Tip +##### Docker-Tipsrc/content/docs/agents/management.mdx (1)
59-60: Spelling & phrasing-The CLI method is deprecated and could pottentially lead to errors. It is on -your own risk. +The CLI method is deprecated and could potentially lead to errors. Use it at +your own risk.src/content/docs/web-apps/torus-portal.mdx (1)
60-62: Minor copy tweak for clarityThe note currently reads as one long sentence. A quick re-phrase improves readability:
-Always check dependency warnings before deleting capabilities - you cannot delete capabilities with active delegations. +Always check dependency warnings before deleting capabilities. +Capabilities that still have active delegations cannot be deleted.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (17)
astro.config.mjs(3 hunks)src/content/docs/agents/apply-root-agent.mdx(2 hunks)src/content/docs/agents/demand-signaling.mdx(2 hunks)src/content/docs/agents/management.mdx(8 hunks)src/content/docs/agents/register-agent.mdx(1 hunks)src/content/docs/agents/server-setup.mdx(2 hunks)src/content/docs/concepts/governance-dao.mdx(2 hunks)src/content/docs/concepts/network-overview.mdx(1 hunks)src/content/docs/development/guide.mdx(0 hunks)src/content/docs/development/web-apps-install-and-run(old).mdx(1 hunks)src/content/docs/development/web-apps-overview-and-setup.mdx(1 hunks)src/content/docs/getting-started/setup-cli.mdx(2 hunks)src/content/docs/network/running-node.mdx(1 hunks)src/content/docs/v05/capability-permissions.mdx(3 hunks)src/content/docs/v05/emission-permissions.mdx(1 hunks)src/content/docs/v05/permissions.mdx(1 hunks)src/content/docs/web-apps/torus-portal.mdx(1 hunks)
💤 Files with no reviewable changes (1)
- src/content/docs/development/guide.mdx
🧰 Additional context used
🪛 LanguageTool
src/content/docs/development/web-apps-overview-and-setup.mdx
[style] ~62-~62: Consider using a more concise synonym.
Context: ...ide> ## Frameworks & Libraries We use a variety of frameworks and libraries to build our w...
(A_VARIETY_OF)
[uncategorized] ~81-~81: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...& ci/cd - ISSUE_TEMPLATE Template for open source contributors - DISCUSSION_TEMPLATE Te...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[uncategorized] ~82-~82: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...rs - DISCUSSION_TEMPLATE Template for open source contributors - .vscode - ... Extensio...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🔇 Additional comments (8)
src/content/docs/getting-started/setup-cli.mdx (1)
162-164: Verify new Discord URLThe hard-coded channel link points to a guild/channel pair. Discord URLs can break if the channel is deleted or permissions change.
Please confirm the link is publicly accessible with “Read Messages” for everyone.src/content/docs/v05/emission-permissions.mdx (1)
125-131: Verification Successful: Linked pages exist
Both/v05/permissionsand/v05/control-spaceresolve to existing files:
- src/content/docs/v05/permissions.mdx
- src/content/docs/v05/control-space.mdx
No further changes needed.
src/content/docs/agents/server-setup.mdx (1)
820-835: Validate new doc slugs before mergeBoth
/agents/register-agentand/v05/permissionsare new paths. A quick grep shows the side-bar config already adopts them, but if the physical MDX files were renamed without redirects the existing external backlinks will 404.Consider adding redirects in
astro.config.mjs(redirectsarray ) or keeping a dummy stub file with front-matterredirect: truepointing to the new slug.astro.config.mjs (1)
85-87: Double-check slug matches file nameSidebar slug
development/web-apps-overview-and-setupmust exactly match the new MDX filename (web-apps-overview-and-setup.mdx). A single char mismatch leads to a 404 in production builds because Astro doesn’t warn.src/content/docs/agents/apply-root-agent.mdx (1)
68-68: Verify updated DAO URL
https://dao.torus.network/whitelist-applicationslooks correct, but the path previously was/whitelist. Please check the deployed DAO UI before merging to avoid broken onboarding links.src/content/docs/v05/capability-permissions.mdx (2)
155-159: Confirm new production-portal URLs before publishingThe doc now points to
portal.torus.network. If the production portal is not yet public, or if registration still occurs on the testnet sub-domain, readers will hit a dead link.-Use [https://portal.torus.network/register-capability](https://portal.torus.network/register-capability) -Use [https://portal.torus.network/create-permission](https://portal.torus.network/create-permission) +# ⚠ verify endpoints exist in production before merge +# Use https://portal.torus.network/register-capability +# Use https://portal.torus.network/create-permission
346-347: Check link rename consistency
/agents/register-agentreplaces/agents/register.
Double-check all inbound links and sidebar entries were updated to the new slug to avoid 404s.src/content/docs/web-apps/torus-portal.mdx (1)
6-6: Double-check component import path
CardGridandLinkCardwere recently renamed toCardsGrid/Cards.Linkin Starlight v0.13+.
If your project upgraded, this import will break the build. Please confirm you’re on a version that still exports these symbols.
| link: /concepts/governance-dao | ||
| label: Governance & DAO |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Ensure the new “prev” slug exists
/concepts/governance-dao must be present in the built site; otherwise the “← Previous” navigation link breaks.
🏁 Script executed:
#!/bin/bash
# Check that the target MDX file exists in the repo
fd --max-depth 4 --full-path 'concepts' -t f -e mdx -x grep -Hn '^title:' {} | grep -i 'Governance & DAO'Length of output: 107
🏁 Script executed:
#!/bin/bash
# Search for any MDX file containing “governance-dao” in its path or content (filename, slug, title, etc.)
rg -Hn 'governance-dao' -g '*.mdx'Length of output: 191
Missing “prev” page: /concepts/governance-dao not found
The slug /concepts/governance-dao is referenced in src/content/docs/agents/register-agent.mdx but there’s no corresponding MDX file under src/content/docs/concepts/. This will break the “← Previous” navigation link.
Please add or rename the file so it matches the slug, for example:
src/content/docs/concepts/governance-dao.mdx
🤖 Prompt for AI Agents
In src/content/docs/agents/register-agent.mdx around lines 5 to 6, the "prev"
page link points to /concepts/governance-dao, but there is no corresponding MDX
file at src/content/docs/concepts/governance-dao.mdx. To fix this, create a new
MDX file named governance-dao.mdx in the src/content/docs/concepts/ directory or
rename an existing file to match this slug so the previous navigation link works
correctly.
| ```bash git clone git@github.com:renlabs-dev/torus-ts.git ``` Clone | ||
| using the web URL. | ||
| </TabItem> | ||
| <TabItem label="HTTPS"> | ||
| ```bash https://github.com/renlabs-dev/torus-ts.git ``` Use a | ||
| password-protected SSH key. | ||
| </TabItem> |
There was a problem hiding this comment.
Code-fence formatting breaks rendering
Markdown will treat everything after the opening back-ticks as part of the same line. Insert a newline after the triple back-ticks and move the language identifier inside the fence.
-```bash git clone git@github.com:renlabs-dev/torus-ts.git ```
+```bash
+git clone git@github.com:renlabs-dev/torus-ts.git
+```Repeat for HTTPS & GitHub-CLI examples.
🤖 Prompt for AI Agents
In src/content/docs/development/web-apps-install-and-run(old).mdx around lines
40 to 46, the code fences for the bash commands are incorrectly formatted by
placing the language identifier and command on the same line after the opening
triple back-ticks. Fix this by placing the language identifier (bash)
immediately after the opening triple back-ticks on its own line, then put the
command on the next line, and close the fence with triple back-ticks on a new
line. Apply this correction to all code blocks in this section including HTTPS
and GitHub-CLI examples.
| title="Capability Permissions" | ||
| href="/advanced/namespace-permissions" | ||
| description="Understand service access control" | ||
| /> |
There was a problem hiding this comment.
Fix broken link — href doesn’t match the target document
The link card is labelled “Capability Permissions”, but it points to /advanced/namespace-permissions.
Unless the document was intentionally renamed, this will 404 and confuse readers.
- title="Capability Permissions"
- href="/advanced/namespace-permissions"
+ title="Capability Permissions"
+ href="/advanced/capability-permissions"📝 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="Capability Permissions" | |
| href="/advanced/namespace-permissions" | |
| description="Understand service access control" | |
| /> | |
| title="Capability Permissions" | |
| href="/advanced/capability-permissions" | |
| description="Understand service access control" | |
| /> |
🤖 Prompt for AI Agents
In src/content/docs/web-apps/torus-portal.mdx around lines 71 to 74, the href
attribute in the link card labeled "Capability Permissions" points to
/advanced/namespace-permissions, which is incorrect and causes a 404 error.
Update the href to the correct path that matches the "Capability Permissions"
document to ensure the link directs to the intended target and avoids confusion.
3 participants
Summary by CodeRabbit