update the welcome file to be easier to digest the documentation

astro.config.mjs

@@ -25,12 +25,9 @@ export default defineConfig({
         {
           label: "Getting Started",
           items: [
-            { label: "Introduction", slug: "index" },
-            { label: "Tokenomics", slug: "concepts/tokenomics" },
-            {
-              label: "Concepts & Terminology",
-              slug: "getting-started/concepts",
-            },
+            { label: "Welcome", slug: "index" },
+            { label: "Tokenomics", slug: "getting-started/tokenomics" },
+            { label: "Understanding Torus", slug: "getting-started/concepts" },
           ],
         },
         {
@@ -40,29 +37,29 @@ export default defineConfig({
             {
               label: "v0.5",
               items: [
-                { label: "Control Space", slug: "v05/control-space" },
-                { label: "Permission System", slug: "v05/permissions" },
+                { label: "Control Space", slug: "explanations/v05/control-space" },
+                { label: "Permission System", slug: "explanations/v05/permissions" },
                 {
                   label: "Capability Permissions",
-                  slug: "v05/capability-permissions",
+                  slug: "explanations/v05/capability-permissions",
                 },
-                { label: "Emission Permissions", slug: "v05/emission-permissions" },
-                { label: "Governance & DAO", slug: "concepts/governance-dao" },
+                { label: "Emission Permissions", slug: "explanations/v05/emission-permissions" },
+                { label: "Governance & DAO", slug: "explanations/v05/governance-dao" },
               ],
             },
             {
               label: "Builders",
               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" },
               ],
             },
             {
-              label: "Leaders",
+              label: "Goal Leaders",
               collapsed: false,
               items: [
                 { label: "Root Agents", slug: "explanations/root-agents/root-agents" },
@@ -78,19 +75,21 @@ 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: "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,33 +103,40 @@ export default defineConfig({
             },
           ],
         },
-        {
-          label: "CLI & Tools",
-          items: [
-            { label: "Key Management", slug: "cli/key-management" },
-            { label: "Balance Operations", slug: "cli/balance-operations" },
-          ],
-        },
         {
           label: "Development",
           items: [
+            { label: "Start Here", slug: "development/start-here" },
             {
-              label: "Web Apps Overview and Setup",
-              slug: "development/web-apps-overview-and-setup",
+              label: "Web Apps",
+              collapsed: false,
+              items: [
+                {
+                  label: "Overview and Setup",
+                  slug: "development/web/overview-and-setup",
+                },
+                {
+                  label: "Querying Data",
+                  slug: "development/web/querying-data",
+                },
+              ],
             },
             {
-              label: "Querying Data",
-              slug: "development/querying-data",
+              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" },
+              ],
             },
-          ],
-        },
-        {
-          label: "Network Operations",
-          items: [
-            { label: "Global Parameters", slug: "network/global-parameters" },
             {
-              label: "Running a Node",
-              slug: "network/running-node",
+              label: "Network Operations",
+              collapsed: false,
+              items: [
+                { label: "Global Parameters", slug: "development/network/global-parameters" },
+                { label: "Running a Node", slug: "development/network/running-node" },
+              ],
             },
           ],
         },

src/components/RedText.astro

@@ -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>

src/content/docs/cli/balance-operations.mdx → src/content/docs/development/cli/balance-operations.mdx

@@ -43,4 +43,4 @@ The unstaking command is defined as follows:
 torus balance unstake <key-name> <amount> <allocator-ss58address>
 ```
 
-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 name of the key, if it's located on your disk. Same as in transferring or staking.

src/content/docs/cli/key-management.mdx → src/content/docs/development/cli/key-management.mdx

@@ -45,7 +45,7 @@ This command displays both public and private key details, ensuring you have acc
 To list all keys stored on your system, execute:
 
 ```sh
-# Lists the names and addresses of keys stored on disk.
+# Lists the names and addresses of keys stored on disk.
 torus key list
 ```
 
@@ -69,4 +69,4 @@ You can also sort the balance by **all, free, staked** (default all summed balan
 torus key balances --sort-balance free
 ```
 
-Will return the keys sorted by their free balance.
+Will return the keys sorted by their free balance.

src/content/docs/how-to-guides/builders/setup-cli.mdx → src/content/docs/development/cli/setup-cli.mdx

@@ -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/cli/key-management/) for secure operations
-- **Check balances**: Use [balance operations](https://docs.torus.network/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/content/docs/network/global-parameters.mdx → src/content/docs/development/network/global-parameters.mdx

@@ -86,4 +86,4 @@ You can query all of these global parameters using CLI:
 
 ```bash
 torus network params
-```
+```

src/content/docs/network/running-node.mdx → src/content/docs/development/network/running-node.mdx

@@ -85,4 +85,4 @@ cargo xtask run local --alice
 
 ## Additional Information
 
-- You can customize your node's configuration by modifying the appropriate files in the project.
+- You can customize your node's configuration by modifying the appropriate files in the project.

src/content/docs/development/start-here.mdx

@@ -0,0 +1,60 @@
+---
+title: Start Here
+description: Technical documentation and tools for developing with and on Torus.
+---
+import {
+  Steps,
+  Aside,
+  CardGrid,
+  Card,
+  Tabs,
+  TabItem
+} from "@astrojs/starlight/components";
+
+Welcome to the **Development** section of the Torus documentation.
+
+This section provides comprehensive technical resources for developers building with Torus — from setting up development environments to running nodes and managing keys.   
+Whether you're integrating with existing web apps, querying data, or running your own infrastructure, you'll find the technical details here.
+
+## Web Application Development
+
+Building and integrating with the Torus ecosystem:
+
+- [Overview and Setup](https://docs.torus.network/development/web/overview-and-setup/) — Setting up the development environment and understanding the monorepo structure
+- [Querying Data](https://docs.torus.network/development/web/querying-data/) — API operations for retrieving stake allocation and network data
+
+---
+
+## CLI & Tools
+
+Command-line operations for key and balance management:
+
+- [Key Management](https://docs.torus.network/development/cli/key-management/) — Creating, importing, and managing cryptographic keys
+- [Balance Operations](https://docs.torus.network/development/cli/balance-operations/) — Transferring and staking operations via CLI
+
+---
+
+## Network Infrastructure
+
+Running and configuring Torus network infrastructure:
+
+- [Global Parameters](https://docs.torus.network/development/network/global-parameters/) — Understanding and configuring blockchain parameters
+- [Running a Node](https://docs.torus.network/development/network/running-node/) — Setting up and operating a Torus Substrate node
+
+---
+
+## Questions Not Covered Here?
+
+Need help with development tasks? The community is here to help:
+
+- **[Discord](https://discord.gg/torus)** — Technical discussions, support, and announcements
+- **[Telegram](https://t.me/torusnetwork)** — General chat and announcements
+- **[Twitter](https://x.com/torus_network)** — Updates and ecosystem news
+
+### Core Projects
+
+Explore the open source code to understand implementation details:
+
+- **[torus-substrate](https://github.com/renlabs-dev/torus-substrate)** — Core blockchain runtime built on Substrate
+- **[torus-ts](https://github.com/renlabs-dev/torus-ts)** — TypeScript SDK for building on Torus and WebApps
+- **[torus-docs](https://github.com/renlabs-dev/torus-docs)** — This documentation