Refactor documentation structure and enhance SDK guides

This comprehensive update restructures the documentation for better user experience and provides enhanced SDK integration guides:

**Documentation Structure Improvements:**
- Restructured landing page with user-friendly introduction and clear pathways
- Created new getting-started section with welcome.mdx and concepts organization
- Updated navigation structure in astro.config.mjs for better hierarchy
- Applied refined red text standards across all how-to guides for visual consistency

**SDK Documentation Enhancements:**
- Enhanced setup-agent-server.mdx with environment configuration and error handling patterns
- Enhanced setup-agent-client.mdx with comprehensive boilerplate integration
- Fixed critical SDK import paths and method names to match actual @torus-network/sdk implementation
- Added production-ready examples with proper async patterns and environment variables

**New Guides and Features:**
- Added complete manage-capabilities guide with create and delete functionality
- Implemented segment-based capability deletion with cascade logic explanation
- Updated all allocator references from standalone URLs to portal-based locations
- Fixed terminology from "Allocator Page" to "Allocator tab" throughout documentation

**Technical Improvements:**
- Fixed RedText component spacing issue to prevent floating punctuation
- Updated folder structure from participants/ to holders/ for clarity
- Added proper coming soon markers for incomplete guides
- Enhanced cross-references and internal linking consistency

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: Sipher

astro.config.mjs

@@ -25,12 +25,9 @@ export default defineConfig({
         {
           label: "Getting Started",
           items: [
-            { label: "Introduction", slug: "index" },
+            { label: "Welcome", slug: "index" },
             { label: "Tokenomics", slug: "getting-started/tokenomics" },
-            {
-              label: "Concepts & Terminology",
-              slug: "getting-started/concepts",
-            },
+            { label: "Understanding Torus", slug: "getting-started/concepts" },
           ],
         },
         {
@@ -55,10 +52,10 @@ export default defineConfig({
               collapsed: false,
               items: [
                 { label: "Agent Registration", slug: "explanations/builders/agent-registration" },
-                { label: "Agent Server", slug: "explanations/builders/agent-server" },
-                { label: "Agent Client", slug: "explanations/builders/agent-client" },
                 { label: "Agent Editing", slug: "explanations/builders/agent-editing" },
                 { label: "Demand Signaling", slug: "explanations/builders/demand-signaling" },
+                { label: "Agent Server", slug: "explanations/builders/agent-server" },
+                { label: "Agent Client", slug: "explanations/builders/agent-client" },
               ],
             },
             {
@@ -78,21 +75,23 @@ export default defineConfig({
               label: "Holders",
               collapsed: false,
               items: [
-                { label: "Setup a Wallet", slug: "how-to-guides/participants/setup-a-wallet" },
-                { label: "Bridge from Base", slug: "how-to-guides/participants/bridge-from-base" },
-                { label: "Stake your Torus", slug: "how-to-guides/participants/stake-your-torus" },
+                { label: "Setup a Wallet", slug: "how-to-guides/holders/setup-a-wallet" },
+                { label: "Bridge from Base", slug: "how-to-guides/holders/bridge-from-base" },
+                { label: "Stake your Torus", slug: "how-to-guides/holders/stake-your-torus" },
               ],
             },
             {
               label: "Builders",
               collapsed: false,
               items: [
-                { label: "Setup CLI", slug: "how-to-guides/builders/setup-cli" },
                 { label: "Register an Agent", slug: "how-to-guides/builders/register-an-agent" },
-                { label: "Setup Agent Server", slug: "how-to-guides/builders/setup-agent-server" },
-                { label: "Setup Agent Client", slug: "how-to-guides/builders/setup-agent-client" },
                 { label: "Edit your Agent", slug: "how-to-guides/builders/edit-your-agent" },
+                { label: "Manage Capabilities", slug: "how-to-guides/builders/manage-capabilities" },
                 { label: "Create a Signal", slug: "how-to-guides/builders/create-signal" },
+                // { label: "Manage Permissions", slug: "how-to-guides/builders/manage-permissions" },
+                // { label: "Delegate Emission Streams", slug: "how-to-guides/builders/delegate-emission-streams" },
+                { label: "Setup Agent Server", slug: "how-to-guides/builders/setup-agent-server" },
+                { label: "Setup Agent Client", slug: "how-to-guides/builders/setup-agent-client" },
               ],
             },
             {
@@ -104,15 +103,6 @@ export default defineConfig({
             },
           ],
         },
-        // {
-        //   label: "Web Apps",
-        //   items: [
-        //     { label: "Torus Portal", slug: "web-apps/torus-portal" },
-        //     { label: "Torus Allocator", slug: "web-apps/torus-allocator" },
-        //     { label: "Torus Wallet", slug: "web-apps/torus-wallet" },
-        //     { label: "Torus DAO", slug: "web-apps/torus-dao" },
-        //   ],
-        // },
         {
           label: "Development",
           items: [
@@ -135,6 +125,7 @@ export default defineConfig({
               label: "CLI Reference",
               collapsed: false,
               items: [
+                { label: "Setup CLI", slug: "development/cli/setup-cli" },
                 { label: "Key Management", slug: "development/cli/key-management" },
                 { label: "Balance Operations", slug: "development/cli/balance-operations" },
               ],

public/images/how-to-guide/manage-capabilities/create-capability-confirm-information.png

@@ -0,0 +1,18 @@
+---
+export interface Props {
+  variant?: 'attention' | 'light' | 'soft';
+  class?: string;
+}
+
+const { variant = 'light', class: className = '' } = Astro.props;
+
+const variantClasses = {
+  attention: 'text-red-attention',
+  light: 'text-red-light', 
+  soft: 'text-red-soft'
+};
+
+const redClass = variantClasses[variant];
+---
+
+<span class={`${redClass} ${className}`} style="display: inline;"><slot /></span>

public/images/how-to-guide/manage-capabilities/delete-capability-confirm-information.png

@@ -110,8 +110,6 @@ The CLI enables developers and power users to manage Torus operations from the c
 
 </Steps>
 
-{/* 
-
 ## Basic CLI Usage
 
 Now that you have the CLI installed, here are the main command categories:
@@ -139,10 +137,10 @@ torus misc circulating-supply   # Total supply info
 
 Now that you have the CLI set up, you can:
 
-- **Register an agent**: Use [agent registration](https://docs.torus.network/how-to-guides/builders/register-an-agent/) to create your first agent
-- **Manage keys**: Learn about [key management](https://docs.torus.network/development/cli/key-management/) for secure operations
-- **Check balances**: Use [balance operations](https://docs.torus.network/development/cli/balance-operations/) to monitor your tokens
-- **Build integrations**: Set up [agent servers](https://docs.torus.network/how-to-guides/builders/setup-agent-server/) for programmatic interactions
+- **Register an agent**: Use [agent registration](/how-to-guides/builders/register-an-agent/) to create your first agent
+- **Manage keys**: Learn about [key management](/development/cli/key-management/) for secure operations
+- **Check balances**: Use [balance operations](/development/cli/balance-operations/) to monitor your tokens
+- **Build integrations**: Set up [agent servers](/how-to-guides/builders/setup-agent-server/) for programmatic interactions
 
  Connect with the community:
 - [Discord](https://discord.gg/torus) — Technical discussions, support, and announcements
@@ -155,9 +153,9 @@ Now that you have the CLI set up, you can:
 
 <CardGrid>
   <Card title="Key Management" icon="seti:key">
-    <a href="/cli/key-management">Learn to create and manage your keys</a>
+    <a href="/development/cli/key-management">Learn to create and manage your keys</a>
   </Card>
   <Card title="Balance Operations" icon="seti:shell">
-    <a href="/cli/balance-operations">Transfer tokens and manage staking</a>
+    <a href="/development/cli/balance-operations">Transfer tokens and manage staking</a>
   </Card>
-</CardGrid> */}
+</CardGrid>

src/components/RedText.astro

@@ -18,7 +18,7 @@ The ecosystem is built using a monorepo with [Turborepo](https://turbo.build/rep
 
 <Aside type="tip">
   To access environments pointing to the testnet nodes, add the `.testnet`
-  subdomain to the URL, eg. `https://allocator.testnet.torus.network/`
+  subdomain to the URL, eg. `https://portal.testnet.torus.network/root-allocator`
 </Aside>
 
 ## Prerequisites

…ocs/how-to-guides/builders/setup-cli.mdx …ntent/docs/development/cli/setup-cli.mdxsrc/content/docs/how-to-guides/builders/setup-cli.mdx renamed to src/content/docs/development/cli/setup-cli.mdx src/content/docs/how-to-guides/builders/setup-cli.mdx renamed to src/content/docs/development/cli/setup-cli.mdx

@@ -6,7 +6,7 @@ description: Learn how to query the stake weight between keys
 import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components";
 
 Our API allows you to retrieve information about the stake allocation between keys and agents.
-You can query this data by making a GET request to: `https://allocator.torus.network/api/allocated-weight`.
+You can query this data by making a GET request to: `https://portal.torus.network/api/allocated-weight`.
 
 ## API Response Format
 
@@ -29,12 +29,12 @@ The API response has the following structure:
 
         To filter the response for a specific allocating key, append the userKey query parameter to the API endpoint:
 
-        ```allocator.torus.network/api/allocated-weight?userKey=<SS58Address>```
+        ```portal.torus.network/api/allocated-weight?userKey=<SS58Address>```
     - Filter by Agent Key
 
         To filter the response for specific agents, append the agentKey query parameter to the API endpoint:
 
-        ```allocator.torus.network/api/allocated-weight?agentKey=<SS58Address>```
+        ```portal.torus.network/api/allocated-weight?agentKey=<SS58Address>```
 
 
     <Aside type="note">

src/content/docs/development/web/overview-and-setup.mdx

@@ -38,14 +38,14 @@ The burn mechanism maintains network quality by creating economic barriers to sp
 
 ### Discovery and Capabilities
 
-Registered agents become discoverable through the public agent registry and can be viewed on the [Allocator page](https://allocator.torus.network/).
+Registered agents become discoverable through the public agent registry and can be viewed on the [Allocator tab](https://portal.torus.network/root-allocator).
 They can participate in the permission system, create named capabilities for other agents to invoke, and engage in governance proposals.
 Agent metadata is stored off-chain via IPFS but referenced on-chain through content hashes.
 
 ### Related Concepts
 
 - **[Root Agents](https://docs.torus.network/explanations/root-agents/root-agents/)** - Agents that receive emissions directly
-- **[Permission System](https://docs.torus.network/v05/permissions/)** - How agents interact and delegate authority
+- **[Permission System](https://docs.torus.network/explanations/v05/permissions/)** - How agents interact and delegate authority
 - **[Governance & DAO](https://docs.torus.network/explanations/v05/governance-dao/)** - Understanding DAO decision-making processes
 
 <Aside type="tip" title="Ready to Register?">

src/content/docs/development/web/querying-data.mdx

@@ -0,0 +1,80 @@
+---
+title: Concepts & Terminology
+description: Key terms and concepts used throughout the Torus ecosystem
+---
+
+import { Aside } from "@astrojs/starlight/components";
+
+
+This glossary defines the key terms and concepts used throughout Torus documentation. Understanding these terms will help you navigate the ecosystem more effectively.
+
+## Core Concepts
+
+### Agent
+An autonomous entity in the Torus network that can perform actions, provide services, and participate in swarms. Agents can be registered users, automated services, or any entity capable of interacting with the protocol.
+
+### Swarm
+A coordinated group of agents working together toward a common goal. Swarms form organically around specific objectives and can operate at multiple scales within the network.
+
+### Hypergraph
+The emergent network structure formed by all agents, their relationships, permissions, and interactions. The hypergraph represents the complete state of coordination within Torus.
+
+### Root Agent
+A special type of agent with elevated permissions to receive emissions directly from the protocol and set goals for swarm formation. Root agents lead major initiatives and coordinate large-scale activities.
+
+## Permissions & Capabilities
+
+### Capability
+A specific function or service that an agent can provide to others. Capabilities are registered on-chain and define what an agent can do within the network.
+
+### Permission
+The right to use or delegate a specific capability. Permissions can be granted, revoked, and delegated between agents to enable complex coordination patterns.
+
+### Delegation
+The process of granting permission to use a capability to another agent. Delegation enables specialization and collaborative work within swarms.
+
+### Control Space
+The coordination layer where agents register capabilities, manage permissions, and coordinate activities. It serves as the control plane for the entire network.
+
+## Economic Terms
+
+### TORUS Token
+The native token of the Torus network used for staking, governance, and accessing network services.
+
+### Staking
+The process of locking TORUS tokens to participate in network security and earn rewards. Staked tokens can be allocated to support specific agents.
+
+### Emissions
+Token rewards distributed to agents and stakeholders based on their contributions to the network. Emissions flow from root agents to the broader ecosystem.
+
+### Allocation
+The distribution of staked tokens to support specific agents or initiatives. Allocations determine how emissions flow through the network.
+
+## Technical Terms
+
+### Agent Server
+A service that hosts agent capabilities and provides APIs for other agents to interact with. Agent servers make capabilities discoverable and usable across the network.
+
+### Agent Client
+A component that allows agents to discover and interact with capabilities provided by other agents. Clients handle authentication and communication protocols.
+
+### Signal
+A message broadcast by an agent expressing demand for specific capabilities or announcing the availability of services. Signals help coordinate supply and demand within swarms.
+
+### Substrate
+The blockchain framework that powers the Torus network. Substrate provides the runtime environment for the protocol's core functionality.
+
+## Governance Terms
+
+### DAO (Decentralized Autonomous Organization)
+The governance structure through which major protocol decisions are made. The Torus DAO enables stakeholder participation in network evolution.
+
+### Proposal
+A formal suggestion for protocol changes, new features, or resource allocation submitted to the DAO for consideration and voting.
+
+### Governance Token
+TORUS tokens used for voting on proposals and participating in decentralized governance processes.
+
+<Aside>
+**New terms being added regularly.** As the Torus ecosystem evolves, new concepts and terminology emerge. Check back here for updates or suggest additions through our community channels.
+</Aside>