refactor: enhance documentation clarity and styling, focusing on swarms explanation and content link customization guide

Author: Sipher

src/content/docs/getting-started/understanding-torus.mdx

@@ -16,13 +16,14 @@ Swarms are subgraphs, and can form at any position in the hypergraph.
 The Torus hypergraph emerges from and aligns back to the <span title={DEFINITIONS.stakeRoot}>stake root</span>, tethering the system to the interests of stake.
 Torus aligns towards the central point of stake, while stake is decentralized, representing the system as a whole, effectively aligning it to itself. 
 
-Swarms form bottom-up around <span title={DEFINITIONS.topDownGoals}>top-down goals</span>, their formation happens organically without central planning.
+Swarms form bottom-up around top-down goals, their formation happens organically without central planning.
 Swarms operate as <span title={DEFINITIONS.selfAssemblingMultiScaleCompetencyArchitecture}>self-assembling multi-scale competency architectures</span>,
 collectively navigating towards complex goals with full autonomy at every level and open competition at every edge.
 
 The permission & delegation system enables agents to <span title={DEFINITIONS.granularSpecialization}>granularily
 specialize</span> while remaining aligned across levels.
-Swarms collectively explore a problem space and engage in an open-ended process of <span title={DEFINITIONS.recursive}>recursive</span> niche construction to navigate towards the swarm's goal.
+Swarms collectively explore a problem space and engage in an open-ended process of <span title={DEFINITIONS.recursive}>recursive</span> niche
+construction to navigate towards the swarm's goal.
 
 
 #### v0.5

src/content/docs/index.mdx

@@ -38,8 +38,9 @@ Connect with the Torus community:
 
 ## Choose Your Path
 
-This documentation is structured linearly, but you're free to explore it your way.
+This guide adapts to your style, whether you prefer theory first or hands‑on learning.
 
-You can start with <RedText variant="light">Understanding the concepts</RedText> or skip ahead to <RedText variant="light">How it works</RedText>.  
-If you choose <RedText variant="light">Understanding the concepts</RedText>, and then getting stuff done, 
-just follow the guide step-by-step using the <RedText variant="light">Next button below</RedText>.
+- Understanding the Concepts: Explore the key ideas, definitions, and background.  
+- [How-to guides](https://docs.torus.network/how-to-guides/table-of-contents): Jump straight into practical steps and examples.
+
+If you’d like a step-by‑step walkthrough, start with <RedText variant="light">Understanding the Concepts</RedText> and use the <RedText variant="light">Next</RedText> button at the bottom of each page to proceed.  

src/tailwind.css

@@ -28,6 +28,24 @@ details details .large {
   color: inherit !important; /* Remove test color */
 }
 
+/*
+CONTENT LINK STYLING CUSTOMIZATION GUIDE:
+This section controls the blue color for content links while preserving 
+navigation elements in their original colors.
+
+To customize content link colors:
+- Change #3b82f6 (blue-500) for normal link color
+- Change #2563eb (blue-600) for hover link color
+- Add more selectors to include additional link types
+- Add more exclusions to prevent styling specific elements
+
+Navigation elements excluded:
+- Sidebar navigation
+- Page navigation (prev/next buttons)
+- Header navigation
+- Any nav-specific elements
+*/
+
 /* Make content hyperlinks blue, but keep navigation original colors */
 @layer components {
   /* Only make content area links blue */
@@ -54,8 +72,9 @@ details details .large {
   }
 }
 
-/* Explicitly keep sidebar navigation in original colors */
+/* Explicitly keep navigation elements in original colors */
 @layer components {
+  /* Sidebar navigation */
   nav a,
   nav .large,
   [data-starlight-sidebar] a,
@@ -65,16 +84,32 @@ details details .large {
   details summary,
   details summary .large,
   .sidebar a,
-  .sidebar .large {
+  .sidebar .large,
+  /* Page navigation (prev/next buttons) */
+  .pagination a,
+  [data-pagination] a,
+  .pagination-links a,
+  .sl-flex a[rel="prev"],
+  .sl-flex a[rel="next"],
+  footer a,
+  .starlight-aside .pagination a {
     color: inherit !important;
     text-decoration: none !important;
   }
 
+  /* Hover states for navigation elements */
   nav a:hover,
   [data-starlight-sidebar] a:hover,
   nav[aria-labelledby="starlight__sidebar-navigation"] a:hover,
   details summary:hover,
-  .sidebar a:hover {
+  .sidebar a:hover,
+  .pagination a:hover,
+  [data-pagination] a:hover,
+  .pagination-links a:hover,
+  .sl-flex a[rel="prev"]:hover,
+  .sl-flex a[rel="next"]:hover,
+  footer a:hover,
+  .starlight-aside .pagination a:hover {
     color: inherit !important;
     text-decoration: none !important;
   }