Reorganize documentation with System section first and improve navigation structure

[Sipher]

Summary

• Reorganize documentation structure to prioritize System section in both explanations and how-to guides
• Move System section to first position before Holders, Builders, and Goal Leaders
• Reorder recursive delegation to come before emission and capability permissions for better conceptual
  flow
• Add descriptive explanations to all how-to guide entries in table of contents
• Consolidate all permission-related documents under unified System architecture

Changes Made

Navigation Structure Updates

• Explanations: System → Holders → Builders → Goal Leaders (was: Holders → Builders → Goal Leaders →
  System)
• How-to Guides: System → Holders → Builders → Goal Leaders (was: Holders → Builders → Goal Leaders →
  System)

System Section Reordering

Updated order in all locations:

1. Control Space
2. Permission System
3. Recursive Delegation (moved up from position 5)
4. Emission Permissions
5. Capability Permissions

Enhanced Table of Contents

• Added concise explanations to all how-to guides (matching explanations section style)
• Optimized descriptions for single-line display in frontend
• Updated System Management section to appear first in how-to guides

Files Modified

• astro.config.mjs - Navigation structure and ordering
• src/content/docs/explanations/table-of-contents.mdx - Section reordering and structure
• src/content/docs/how-to-guides/table-of-contents.mdx - Added descriptions and reordered sections

Impact

• Improved user experience with logical documentation flow (System fundamentals first)
• Better discoverability of core architectural concepts
• Consistent ordering across all documentation sections
• Enhanced navigation with descriptive guide summaries

Summary by CodeRabbit

• Documentation
  • Added System Architecture and System Management sections with dedicated pages for permissions, delegation, and related workflows.
  • Consolidated permission topics under System, removing duplicates from Builders and Goal Leaders.
  • Updated links across explanations and how-to guides to point to the new System paths.
  • Enhanced tables of contents with concise descriptions for entries; streamlined Root Leaders items.
  • Minor homepage copy cleanup to tighten the introduction.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Reorganizes documentation to centralize permission-related topics under new System sections in navigation, explanations, and how-to guides. Updates numerous links from goal-leaders/builders paths to system paths. Revamps How-to Guides and Explanations tables of contents. Removes one sentence from the homepage. No code or runtime logic changes.

Changes

Cohort / File(s)	Summary
Navigation & sidebar astro.config.mjs	Adds System subsections under Explanations and How-to Guides; removes duplicated permission items from Builders and Goal Leaders sections.
Explanations: link retargeting src/content/docs/explanations/builders/agent-registration.mdx, .../explanations/goal-leaders/emission-proposals.mdx, .../explanations/system/recursive-delegation.mdx	Updates links from goal-leaders paths to system paths; deduplicates Permission System bullet; adjusts Aside links to system pages.
Explanations TOC src/content/docs/explanations/table-of-contents.mdx	Introduces System Architecture section; removes permission-related items from Builders and Root Goal-Setters and Leaders sections.
How-to Guides (Builders) src/content/docs/how-to-guides/builders/manage-capabilities.mdx, .../how-to-guides/builders/manage-your-agent.mdx	Points Manage Permissions and Recursive Delegation links to system paths.
How-to Guides (System) src/content/docs/how-to-guides/system/create-capability-permission.mdx, .../system/create-emission-permission.mdx, .../system/create-permission.mdx, .../system/manage-permissions.mdx	Updates internal links to system namespace for permission system, recursive delegation, and create/manage permission flows.
How-to Guides TOC overhaul src/content/docs/how-to-guides/table-of-contents.mdx	Adds System Management section; converts many entries to descriptive links; restructures Root Goal-Setters and Leaders section.
Homepage tweak src/content/docs/index.mdx	Removes one sentence from introduction; no other edits.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• New hover functionality #27 — Also restructures sidebar/navigation in astro.config.mjs and adjusts TOC entries.
• v06 doc bump version #32 — Migrates permission and recursive-delegation links to system/ paths similar to this reorganization.
• Dev #24 — Updates sidebar config and MDX links related to permission documentation, overlapping file areas.

Poem

I hop through docs, rearranging lanes,
Permissions nest in System’s cozy plains.
Old trails reroute, new signs align,
Breadcrumbs crisp as morning pine.
With links in sync and headings bright—
Thump-thump! the roadmap feels just right.
🐇✨

Tip

🔌 Remote MCP (Model Context Protocol) integration is now available!

Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between ce28b68 and 99d997c.

📒 Files selected for processing (13)

• astro.config.mjs (2 hunks)
• src/content/docs/explanations/builders/agent-registration.mdx (1 hunks)
• src/content/docs/explanations/goal-leaders/emission-proposals.mdx (1 hunks)
• src/content/docs/explanations/system/recursive-delegation.mdx (1 hunks)
• src/content/docs/explanations/table-of-contents.mdx (1 hunks)
• src/content/docs/how-to-guides/builders/manage-capabilities.mdx (2 hunks)
• src/content/docs/how-to-guides/builders/manage-your-agent.mdx (1 hunks)
• src/content/docs/how-to-guides/system/create-capability-permission.mdx (2 hunks)
• src/content/docs/how-to-guides/system/create-emission-permission.mdx (1 hunks)
• src/content/docs/how-to-guides/system/create-permission.mdx (1 hunks)
• src/content/docs/how-to-guides/system/manage-permissions.mdx (1 hunks)
• src/content/docs/how-to-guides/table-of-contents.mdx (1 hunks)
• src/content/docs/index.mdx (0 hunks)

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch dev

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

• Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

• Visit our Status Page to check the current availability of CodeRabbit.
• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.