diff --git a/site/content/docs/_index.md b/site/content/docs/_index.md
index 022a819..61f7741 100644
--- a/site/content/docs/_index.md
+++ b/site/content/docs/_index.md
@@ -8,4 +8,4 @@ tags: ["reference", "documentation"]
 
 ASW is a single-file CSS framework for agent-generated web content. Semantic HTML is the only API. No classes, no build step, no JavaScript required.
 
-Browse the sections in the sidebar, or start with [Introduction](/docs/introduction/).
+Browse the sections in the sidebar, or start with [Introduction](/docs/getting-started/introduction/).
diff --git a/site/content/docs/components/components.md b/site/content/docs/components/components.md
index 11f3175..b96c0cf 100644
--- a/site/content/docs/components/components.md
+++ b/site/content/docs/components/components.md
@@ -168,8 +168,8 @@ Three-column sidebar scaffold. Source order matters: left aside → article →
     <nav aria-label="Documentation" data-nav="sidebar">
       <small>Section</small>
       <ul>
-        <li><a href="/docs/introduction/" aria-current="page">Introduction</a></li>
-        <li><a href="/docs/tokens/">Token System</a></li>
+        <li><a href="/docs/getting-started/introduction/" aria-current="page">Introduction</a></li>
+        <li><a href="/docs/core/tokens/">Token System</a></li>
       </ul>
     </nav>
   </aside>
@@ -205,7 +205,7 @@ Three-column sidebar scaffold. Source order matters: left aside → article →
 ## CTA links
 
 ```html
-<a href="/docs/introduction/" data-role="primary">Get started →</a>
+<a href="/docs/getting-started/introduction/" data-role="primary">Get started →</a>
 <a href="/docs/" data-role="secondary">Documentation</a>
 ```
 
diff --git a/site/content/docs/components/layouts.md b/site/content/docs/components/layouts.md
index 3f20157..0eeb3f0 100644
--- a/site/content/docs/components/layouts.md
+++ b/site/content/docs/components/layouts.md
@@ -25,8 +25,8 @@ Three-column scaffold: sidebar, content, TOC. Source order: left `<aside>` → c
     <nav data-nav="sidebar" aria-label="Docs">
       <small>Getting started</small>
       <ul>
-        <li><a href="/docs/introduction/" aria-current="page">Introduction</a></li>
-        <li><a href="/docs/tokens/">Token System</a></li>
+        <li><a href="/docs/getting-started/introduction/" aria-current="page">Introduction</a></li>
+        <li><a href="/docs/core/tokens/">Token System</a></li>
       </ul>
     </nav>
   </aside>
@@ -75,7 +75,7 @@ CTA button row, centered, wraps on small screens.
 
 ```html
 <nav data-layout="actions">
-  <a href="/docs/introduction/" data-role="primary">Get started →</a>
+  <a href="/docs/getting-started/introduction/" data-role="primary">Get started →</a>
   <a href="https://github.com/..." data-role="secondary">GitHub</a>
 </nav>
 ```
@@ -243,5 +243,5 @@ Renders a `<dl>` as a two-column grid: terms on the left, definitions on the rig
 
 ## Related
 
-- [Data Attributes](/docs/data-attributes/) — full `data-*` vocabulary reference
-- [Token System](/docs/tokens/) — the custom property values that layout tokens reference
+- [Data Attributes](/docs/core/data-attributes/) — full `data-*` vocabulary reference
+- [Token System](/docs/core/tokens/) — the custom property values that layout tokens reference
diff --git a/site/content/docs/components/navigation.md b/site/content/docs/components/navigation.md
index 2dda71f..9919b71 100644
--- a/site/content/docs/components/navigation.md
+++ b/site/content/docs/components/navigation.md
@@ -100,6 +100,6 @@ Add `data-layout="vertical"` for a top-down flow — useful in sidebars or narro
 
 ## Related
 
-- [Data Attributes](/docs/data-attributes/) — `data-role`, `data-status`, and the full attribute vocabulary
-- [Layouts](/docs/layouts/) — `data-layout` values including `vertical`
+- [Data Attributes](/docs/core/data-attributes/) — `data-role`, `data-status`, and the full attribute vocabulary
+- [Layouts](/docs/components/layouts/) — `data-layout` values including `vertical`
 - [Components](/docs/components/) — callouts, tasks, and other component patterns
diff --git a/site/content/docs/core/data-attributes.md b/site/content/docs/core/data-attributes.md
index ba257a2..cab4248 100644
--- a/site/content/docs/core/data-attributes.md
+++ b/site/content/docs/core/data-attributes.md
@@ -137,7 +137,7 @@ Text modifier. Supports multiple space-separated values.
 
 ## data-layout
 
-Layout pattern. See [Layouts](/docs/layouts/) for the full reference.
+Layout pattern. See [Layouts](/docs/components/layouts/) for the full reference.
 
 Common values: `docs`, `hero`, `install`, `actions`, `grid-2`, `grid-3`, `card-grid`, `stats`, `prose`, `fluid`, `timeline`, `report`.
 
@@ -155,8 +155,8 @@ Navigation variant. Applied to `<nav>` elements.
 ```html
 <nav data-nav="sidebar" aria-label="Documentation">
   <ul>
-    <li><a href="/docs/introduction/" aria-current="page">Introduction</a></li>
-    <li><a href="/docs/tokens/">Token System</a></li>
+    <li><a href="/docs/getting-started/introduction/" aria-current="page">Introduction</a></li>
+    <li><a href="/docs/core/tokens/">Token System</a></li>
   </ul>
 </nav>
 ```
@@ -357,6 +357,6 @@ Document metadata patterns for structured article content.
 
 ## Related
 
-- [Layouts](/docs/layouts/) — `data-layout` values in full
-- [Semantic HTML](/docs/semantic-html/) — how plain elements are styled without attributes
+- [Layouts](/docs/components/layouts/) — `data-layout` values in full
+- [Semantic HTML](/docs/core/semantic-html/) — how plain elements are styled without attributes
 - [Components](/docs/components/) — callouts, tasks, and session blocks in detail
diff --git a/site/content/docs/core/reset.md b/site/content/docs/core/reset.md
index 4265b59..4e46d24 100644
--- a/site/content/docs/core/reset.md
+++ b/site/content/docs/core/reset.md
@@ -124,5 +124,5 @@ body { padding-inline: var(--space-4); }
 
 ## Related
 
-- [Semantic HTML](/docs/semantic-html/) — element styles built on top of this reset
-- [Token System](/docs/tokens/) — the custom properties (`--surface`, `--text`, `--font-ui`) referenced in this layer
+- [Semantic HTML](/docs/core/semantic-html/) — element styles built on top of this reset
+- [Token System](/docs/core/tokens/) — the custom properties (`--surface`, `--text`, `--font-ui`) referenced in this layer
diff --git a/site/content/docs/core/semantic-html.md b/site/content/docs/core/semantic-html.md
index e947e73..8ad7c20 100644
--- a/site/content/docs/core/semantic-html.md
+++ b/site/content/docs/core/semantic-html.md
@@ -267,6 +267,6 @@ Opt out with `data-layout="fluid"` on `<main>`.
 
 ## Related
 
-- [Reset](/docs/reset/) — the normalization layer underneath these element styles
-- [Data Attributes](/docs/data-attributes/) — extend element styles with `data-*` attributes
-- [Token System](/docs/tokens/) — the custom properties driving all colours, sizes, and fonts here
+- [Reset](/docs/core/reset/) — the normalization layer underneath these element styles
+- [Data Attributes](/docs/core/data-attributes/) — extend element styles with `data-*` attributes
+- [Token System](/docs/core/tokens/) — the custom properties driving all colours, sizes, and fonts here
diff --git a/site/content/docs/reference/charts.md b/site/content/docs/reference/charts.md
index 74ded2b..95dee9c 100644
--- a/site/content/docs/reference/charts.md
+++ b/site/content/docs/reference/charts.md
@@ -213,5 +213,5 @@ Override chart size tokens on the `[data-chart]` element:
 
 ## Related
 
-- [Token System](/docs/tokens/) — colour tokens used by the chart colour cycle (`--accent`, `--accent-blue`, etc.)
-- [Data Attributes](/docs/data-attributes/) — the broader `data-*` vocabulary of which `data-chart` is a part
+- [Token System](/docs/core/tokens/) — colour tokens used by the chart colour cycle (`--accent`, `--accent-blue`, etc.)
+- [Data Attributes](/docs/core/data-attributes/) — the broader `data-*` vocabulary of which `data-chart` is a part
diff --git a/site/content/docs/reference/chroma.md b/site/content/docs/reference/chroma.md
index 82b91f4..c6ac743 100644
--- a/site/content/docs/reference/chroma.md
+++ b/site/content/docs/reference/chroma.md
@@ -151,5 +151,5 @@ Use Chroma for Hugo sites. Use Prism for everything else.
 
 ## Related
 
-- [Token System](/docs/tokens/) — the Open Props colour tokens that the highlight palette maps to
-- [Semantic HTML](/docs/semantic-html/) — how `<pre>` and `<code>` are styled at the element level
+- [Token System](/docs/core/tokens/) — the Open Props colour tokens that the highlight palette maps to
+- [Semantic HTML](/docs/core/semantic-html/) — how `<pre>` and `<code>` are styled at the element level