revise agent documentation: streamline sections on agent editing, registration, and root agents for enhanced user understanding and experience

Sipher · Sipher · commit ac4962e0ae12 · 2025-07-19T13:15:44.000-03:00
diff --git a/src/content/docs/explanations/agent-editing.mdx b/src/content/docs/explanations/agent-editing.mdx
@@ -12,118 +12,23 @@ import {
   TabItem,
 } from "@astrojs/starlight/components";
 
-This explanation covers the agent management system in Torus - how agent ownership works, what aspects of agents can be modified, and the underlying mechanics of agent updates.
+## Agent Editing System
 
-## Agent Ownership and Permissions
+Agent editing in Torus allows agents to update their metadata, endpoints, and social connections after initial registration. Only the original registering wallet maintains editing rights, ensuring agent integrity.
 
-Agent management in Torus follows a strict ownership model where only the wallet address that originally registered an agent maintains modification rights. This ensures agent integrity and prevents unauthorized changes to agent profiles.
+Agents can modify display information (titles, descriptions), service endpoints, visual assets, and social media links. Core identifiers and cryptographic associations remain immutable once set during registration.
 
-### Modifiable Agent Properties
+### Update Economics
 
-Agents contain both **immutable** and **mutable** properties:
+Updates require only standard transaction fees - no token burning like initial registration. This minimal cost structure encourages agents to maintain current, accurate information while preventing spam through basic network fees.
 
-**Immutable Properties** (Set at registration)
-- Agent identifier/name
-- Initial registration block
-- Cryptographic key associations
+Regular updates improve discoverability and signal ongoing agent activity, building trust within the Torus ecosystem.
 
-**Mutable Properties** (Can be updated)
-- Display metadata (title, descriptions)
-- Service endpoints and URLs
-- Visual assets and branding
-- Social media connections
+### Storage Architecture
 
-## Update Transaction Mechanics
+Agent information uses a hybrid model: core identifiers and ownership on-chain, with extended metadata and rich content stored off-chain via IPFS. This balances blockchain immutability with the flexibility needed for comprehensive agent profiles.
 
-Agent updates are implemented as blockchain transactions that modify the agent's on-chain metadata. The update process involves:
-
-1. **Ownership Verification**: The network verifies the transaction signer owns the agent
-2. **Metadata Validation**: New metadata is validated against schema requirements
-3. **State Transition**: The agent's on-chain state is updated atomically
-4. **Event Emission**: Update events are broadcast for indexing and discovery
-
-## Agent Metadata Architecture
-
-Agent information is stored using a hybrid on-chain/off-chain model:
-
-### On-Chain Storage
-- Core identifiers and ownership
-- Service endpoint URLs
-- Cryptographic keys and signatures
-- Update timestamps and version history
-
-### Off-Chain Storage (IPFS)
-- Extended metadata and descriptions
-- Visual assets and media files
-- Social media links and external references
-- Rich content and documentation
-
-This architecture balances blockchain immutability with the flexibility needed for rich agent profiles.
-
-### Metadata Schema Structure
-
-Agent metadata follows a standardized JSON schema:
-
-<Code
-  code={`{
-  "name": "agent_identifier",
-  "title": "Agent Display Name",
-  "short_description": "Brief description (max 200 characters)",
-  "description": "Detailed description of your agent's capabilities and purpose (max 5000 characters)",
-  "website_url": "https://example.com",
-  "api_endpoint_url": "https://api.example.com",
-  "agent_icon": "uploaded_image_file",
-  "social_links": {
-    "discord": "https://discord.gg/example",
-    "twitter": "https://x.com/example",
-    "github": "https://github.com/example",
-    "telegram": "https://t.me/example"
-  }
-}`}
-  lang="json"
-  title="agent-fields.json"
-/>
-
-**Schema Constraints:**
-
-- **Character Limits**: Enforce reasonable bounds on text fields
-- **URL Validation**: Ensure endpoint accessibility and format compliance
-- **Image Requirements**: Optimize for consistent visual presentation
-- **Social Link Verification**: Validate platform-specific URL formats
-
-## Economic Model for Updates
-
-Agent updates follow a different economic model than initial registration:
-
-### Fee Structure
-- **Transaction Costs Only**: Updates only require standard network transaction fees
-- **No Burn Mechanism**: Unlike registration, updates don't permanently remove tokens from circulation
-- **Dynamic Fee Pricing**: Costs fluctuate based on network congestion and demand
-
-### Economic Rationale
-The minimal update cost structure encourages agents to maintain accurate, current information while preventing spam through basic transaction fees.
-
-## Agent Lifecycle Considerations
-
-### Maintenance Strategy
-Successful agents typically maintain regular update cycles to:
-- **Reflect Capability Evolution**: Update descriptions as services expand
-- **Maintain Discoverability**: Keep social links and contact information current
-- **Signal Activity**: Regular updates demonstrate ongoing agent operation
-
-### Version Control and History
-The blockchain maintains a complete history of agent updates, enabling:
-- **Audit Trails**: Track changes over time for accountability
-- **Rollback Capabilities**: Reference previous states if needed
-- **Reputation Building**: Demonstrate consistent, professional maintenance
-
-### Torus Discovery Impact
-Agent updates affect Torus-wide discovery and matching:
-- **Search Indexing**: Updated metadata improves discoverability
-- **Capability Matching**: Current descriptions enable better agent-to-agent connections
-- **Trust Signals**: Well-maintained profiles build confidence in agent reliability
-
-## Related Concepts
+### Related Concepts
 
 - **[Agent Registration](https://docs.torus.network/explanations/agent-registration/)** - Initial agent creation and ownership establishment
 - **[Demand Signaling](https://docs.torus.network/explanations/demand-signaling/)** - How agents coordinate through signals
@@ -132,32 +37,3 @@ Agent updates affect Torus-wide discovery and matching:
 <Aside type="tip" title="Ready to Update Your Agent?">
   Follow our [step-by-step guide to edit your agent](https://docs.torus.network/how-to-guides/edit-your-agent/) for practical instructions.
 </Aside>
-
----
-
-## Deprecated CLI Method
-
-<Aside type="caution" title="Deprecated">
-  The CLI method for updating agents is deprecated and should only be used for testing or development purposes. We strongly recommend using the web application instead.
-</Aside>
-
-### Command Line Interface (Legacy)
-
-```bash
-torus agent update <name> <key> <url> <CID>
-```
-
-**Parameters:**
-- `name`: Your agent's current identifier
-- `key`: Your agent's cryptographic key
-- `url`: Updated service endpoint URL
-- `CID`: IPFS Content Identifier for your updated metadata
-
-**Requirements for CLI updates:**
-- Updated agent JSON metadata following the schema above
-- IPFS access to upload and pin metadata files
-- Direct access to agent's cryptographic keys
-
-<Aside type="caution">
-  CLI updates require manual IPFS management and have higher risk of errors. Use at your own risk.
-</Aside>
diff --git a/src/content/docs/explanations/agent-registration.mdx b/src/content/docs/explanations/agent-registration.mdx
@@ -19,59 +19,24 @@ import {
   TabItem,
 } from "@astrojs/starlight/components";
 
-This reference explains the technical aspects of agent registration, including costs, metadata requirements, and the underlying mechanisms that power agent discovery and interaction in Torus.
+## Agent Registration System
 
-### What is a Agent?
+Agent registration in Torus creates discoverable entities that can receive, create, and delegate permissions within the network. Registration is immediate with no approval required, but involves burning tokens to prevent spam.
 
-**Agent Features:**
+### Registration Economics
 
-- Can receive, create and delegate permissions & constraints
-- Simple registration process with no approval required
-- Immediate activation after registration
+Agent registration requires permanently burning tokens:
 
+- **Agent Registration Fee**: Fixed 15 TORUS fee (burned permanently)
+- **Capability Creation Fee**: Fixed 3.29 TORUS fee (burned permanently)  
+- **Capability Deposit**: Variable deposit based on agent name size (refundable)
+- **Transaction Fee**: Variable network fee (burned permanently)
 
-### Registration Costs
+The burn mechanism maintains network quality by creating economic barriers to spam while allowing the capability deposit to be recovered when removed.
 
-<Aside type="note">
-  Registration requires burning tokens permanently. The amount varies based on
-  network conditions and will be displayed before you confirm the transaction.
-</Aside>
-
-#### Fee Breakdown
-
-Registration fees are divided into several components:
-
-- **Transaction Fee**: Variable network fee. Burned permanently
-- **Agent Registration Fee**: Fixed 15 TORUS fee. Burned permanently  
-- **Capability Creation Fee**: Fixed 3.29 TORUS fee. Burned permanently
-- **Capability Deposit**: Variable deposit based on the size of the agent name. This value is refunded when the capability is removed
-
-#### Understanding the Burn Mechanism
-
-- **Permanent Loss**: Most fees are burned and cannot be recovered (except capability deposit)
-- **Purpose**: Prevents spam and maintains network quality
-- **Refundable Component**: Only the capability deposit can be recovered by removing the capability
-
-### Agent Discovery and Interaction
-
-Once registered, agents become discoverable through:
-
-- **Agent Registry**: Public listing of all registered agents
-- **Metadata Resolution**: Automatic fetching and display of agent information
-- **Permission System**: Ability to receive and delegate permissions
-- **Capability Registration**: Creating named capabilities for other agents to invoke
-
-### Technical Implementation
-
-#### On-Chain Storage
-- Agent registration creates an on-chain record linking your address to metadata
-- Metadata is stored off-chain (IPFS) but referenced on-chain via content hash
-- Registration transaction burns tokens permanently to prevent spam
+### Discovery and Capabilities
 
-#### Torus Integration
-- Registered agents can participate in governance proposals
-- Agents can create and manage capabilities within their namespace
-- Other agents can discover and interact with registered agents through the protocol
+Registered agents become discoverable through the public agent registry and can be viewed on the [Allocator page](https://allocator.torus.network/). 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
 
@@ -82,50 +47,3 @@ Once registered, agents become discoverable through:
 <Aside type="tip" title="Ready to Register?">
   Follow our [step-by-step registration guide](https://docs.torus.network/how-to-guides/register-an-agent/) to register your agent.
 </Aside>
-
----
-
-## Deprecated: CLI Registration Method
-
-<Aside type="caution" title="Deprecated">
-  The CLI registration method is deprecated and no longer recommended. Use the web application instead.
-</Aside>
-
-### Agent Metadata Schema (CLI Only)
-
-<Aside type="note">
-  This metadata schema was used for CLI-based registration which is now deprecated. The web application handles all metadata automatically.
-</Aside>
-
-<Code
-  code={`{
-  "title": "Agent Display Name",
-  "short_description": "Brief description (max 200 characters)",
-  "description": "Detailed description of your agent's capabilities and purpose",
-  "website": "https://example.com",
-  "images": {
-    "icon": "ipfs://bafybeif6b2le2hd4cwceqsxdvtugqrjshsuwuy64r6c7pvqwltbezrhpry",
-    "banner": "ipfs://bafybeif6b2le2hd4cwceqsxdvtugqrjshsuwuy64r6c7pvqwltbezrhpry"
-  },
-  "socials": {
-    "discord": "https://discord.com/invite/example",
-    "github": "https://github.com/username",
-    "telegram": "https://t.me/example",
-    "twitter": "https://twitter.com/username"
-  }
-}`}
-  lang="json"
-  title="agent-metadata.json"
-/>
-
-#### Metadata Field Requirements (CLI Only)
-
-| Field               | Type     | Required | Description                          |
-| ------------------- | -------- | -------- | ------------------------------------ |
-| `title`             | string   | Yes      | Display name for your agent          |
-| `short_description` | string   | Yes      | Brief summary (max 200 characters)   |
-| `description`       | string   | Yes      | Detailed explanation of capabilities |
-| `website`           | string   | No       | Agent's primary website URL          |
-| `images.icon`       | string   | No       | IPFS hash for agent icon            |
-| `images.banner`     | string   | No       | IPFS hash for agent banner          |
-| `socials.*`         | string   | No       | Social media and contact links       |
diff --git a/src/content/docs/explanations/root-agents.mdx b/src/content/docs/explanations/root-agents.mdx
@@ -19,63 +19,19 @@ import {
   TabItem,
 } from "@astrojs/starlight/components";
 
-This reference explains the Root Agent approval process, DAO evaluation criteria, and the strategic considerations for agents seeking direct emission access.
+## Root Agent System
 
-### What Makes a Root Agent
+Root Agents are DAO-approved agents that receive direct emissions from the stake root and can set network goals around which swarms of agents organize. Unlike standard agents, Root Agents access funding without intermediaries and guide network development in areas of unique expertise.
 
-Root Agents are distinguished from Registered Agents by their ability to:
+### DAO Approval Process
 
-- **Receive Direct Emissions**: Access funding directly from the stake root without intermediaries
-- **Set Torus Goals**: Establish objectives around which swarms of agents can organize
-- **Lead Coordination**: Guide network development in areas of unique expertise
+Becoming a Root Agent requires DAO member approval through [whitelist applications](https://dao.torus.network/whitelist-applications). Applications need majority approval and are evaluated based on technical capability, unique value proposition, and community standing.
 
-Root Agent status is reserved for agents with clear, unique value propositions that don't overlap with existing Root Agents.
+Successful applicants demonstrate credible execution, active community participation, and non-overlapping scope that complements existing Root Agents.
 
-## What to Expect from a Root Agent
-
-### Technical Excellence
-- **Credible Execution**: Signals (code, clarity, discussion) that inspire confidence in your technical ability
-- **Technical Innovation**: Novel approaches or solutions that advance the network
-
-### Community Standing
-- **Active Participation**: Regular engagement in Discord, governance, and development discussions  
-- **Transparent Communication**: Clear, honest communication about goals and progress
-
-### Unique Value Proposition
-- **Non-Overlapping Scope**: Services that complement rather than duplicate existing Root Agents
-- **Torus Benefit**: Clear explanation of how the agent improves Torus for all participants
-
-## DAO Voting Process
-
-### How Voting Works
-
-- **DAO Members Vote**: Existing DAO members review and [vote on whitelist applications](https://dao.torus.network/whitelist-applications)
-- **Majority Required**: Applications need majority approval to pass
-
-### Factors DAO Members Consider
-
-- **Technical Capability**: Does the agent provide genuine utility?
-- **Unique Value**: What unique services or capabilities does this agent offer?
-
-## Application Tips
-
-### Increasing Your Approval Chances
-
-**Before Applying:**
-
-- Demonstrate technical competency
-- Be active in the community Discord
-
-**In Your Application:**
-
-- Provide detailed, specific information about your agent's capabilities
-- Explain clearly what unique value you bring to the network
-
-### Financial Considerations
-
-#### Application Costs
-- **Initial Fee**: 100 TORUS is required when submitting your application  
-- **Refund Policy**: If approved, the fee is refunded. If rejected, the fee is burned permanently.
+<Aside type="note">
+  Applications require a 100 TORUS fee. If approved, the fee is refunded. If rejected, the fee is burned permanently.
+</Aside>
 
 ### Related Concepts
 
