docs: tabbed sidebar nav + de-emphasize objectql/ui/os protocol branding (#1917)

os-zhuang · claude · web-flow · commit f8bfcd60ad6a · 2026-06-15T20:39:49.000+05:00
Splits the single long docs sidebar into six icon-labelled tabs via fumadocs
folder roots (Getting Started, Concepts, Guides, Reference, Protocol, Releases),
so readers see one section at a time instead of all 366 pages competing in one
rail.

- root + icon on each top-level section meta.json; root meta.json reordered so
  Protocol (the early-emphasis ObjectQL/ObjectUI/ObjectOS layer) sits last and
  the generated Reference gets its own tab instead of crowding the hand-written
  docs.
- references/meta.json is generated, so the Reference tab's title/icon/root is
  emitted from packages/spec/scripts/build-docs.ts (title "Protocol Reference"
  → "Reference").
- Guides regrouped: added a "Foundations" label, moved Service Contracts into
  Integration, surfaced Cheatsheets under their own label instead of buried
  after a bare divider.
- Renamed colliding "Protocol" labels: "Protocol Overview" → "Protocol",
  "Contracts Protocol" → "Service Contracts".
- Fixed the top-nav GitHub link target: objectstack-ai/spec → framework.

Nav-only: no files moved, no doc URLs changed. `next build` compiles all 1113
pages clean; lucide icons resolve with no warnings.

Co-authored-by: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/docs-nav-restructure.md b/.changeset/docs-nav-restructure.md
@@ -0,0 +1,4 @@
+---
+---
+
+docs: restructure the docs site left navigation — split the single long sidebar into six icon-labelled tabs (Getting Started, Concepts, Guides, Reference, Protocol, Releases), de-emphasise the ObjectQL/ObjectUI/ObjectOS protocol branding (Protocol moved to the last tab), isolate the 238 generated reference pages into their own tab, group the Guides section (Foundations/Building/Integration/Operations/Cheatsheets), and fix the top-nav GitHub link (objectstack-ai/spec → framework). Nav-only; no doc URLs change.
diff --git a/apps/docs/lib/layout.shared.tsx b/apps/docs/lib/layout.shared.tsx
@@ -3,7 +3,7 @@ import Image from 'next/image';
 
 export const gitConfig = {
   user: 'objectstack-ai',
-  repo: 'spec',
+  repo: 'framework',
   branch: 'main',
 };
 
diff --git a/content/docs/concepts/meta.json b/content/docs/concepts/meta.json
@@ -1,4 +1,6 @@
 {
   "title": "Concepts",
+  "icon": "Lightbulb",
+  "root": true,
   "pages": ["index", "north-star", "metadata-driven", "metadata-lifecycle", "design-principles", "architecture", "cluster-semantics", "webhook-delivery", "skills", "core", "packages", "setup-app", "cloud-artifact-api", "terminology", "implementation-status"]
 }
diff --git a/content/docs/getting-started/meta.json b/content/docs/getting-started/meta.json
@@ -1,4 +1,6 @@
 {
   "title": "Getting Started",
+  "icon": "Rocket",
+  "root": true,
   "pages": ["index", "quick-start", "core-concepts", "architecture", "examples", "cli", "glossary"]
 }
diff --git a/content/docs/guides/contracts/meta.json b/content/docs/guides/contracts/meta.json
@@ -1,4 +1,4 @@
 {
-  "title": "Contracts Protocol",
+  "title": "Service Contracts",
   "pages": ["index", "metadata-service", "auth-service", "storage-service", "data-engine", "cache-service"]
-}
+}
diff --git a/content/docs/guides/meta.json b/content/docs/guides/meta.json
@@ -1,7 +1,10 @@
 {
   "title": "Guides",
+  "icon": "BookOpen",
+  "root": true,
   "pages": [
     "index",
+    "---Foundations---",
     "packages",
     "metadata",
     "adding-a-metadata-type",
@@ -26,6 +29,7 @@
     "---Integration---",
     "api-reference",
     "client-sdk",
+    "contracts",
     "project-scoping",
     "driver-configuration",
     "kernel-services",
@@ -43,8 +47,7 @@
     "error-handling-server",
     "standards",
     "troubleshooting",
-    "---",
-    "contracts",
+    "---Cheatsheets---",
     "cheatsheets"
   ]
 }
diff --git a/content/docs/meta.json b/content/docs/meta.json
@@ -4,11 +4,8 @@
     "getting-started",
     "concepts",
     "guides",
-    "---",
-    "protocol",
-    "---",
     "references",
-    "---",
+    "protocol",
     "releases"
   ]
 }
diff --git a/content/docs/protocol/meta.json b/content/docs/protocol/meta.json
@@ -1,4 +1,6 @@
 {
-  "title": "Protocol Overview",
+  "title": "Protocol",
+  "icon": "Network",
+  "root": true,
   "pages": ["index", "objectql", "objectui", "objectos", "knowledge"]
 }
diff --git a/content/docs/references/meta.json b/content/docs/references/meta.json
@@ -1,5 +1,7 @@
 {
-  "title": "Protocol Reference",
+  "title": "Reference",
+  "icon": "FileCode",
+  "root": true,
   "pages": [
     "ai",
     "api",
diff --git a/content/docs/releases/meta.json b/content/docs/releases/meta.json
@@ -1,4 +1,6 @@
 {
   "title": "Releases",
+  "icon": "Tag",
+  "root": true,
   "pages": ["index", "v9"]
 }
diff --git a/packages/spec/scripts/build-docs.ts b/packages/spec/scripts/build-docs.ts
@@ -442,7 +442,11 @@ const pages = [
 ];
 
 const meta = {
-  title: "Protocol Reference",
+  title: "Reference",
+  icon: "FileCode",
+  // Render the (large, generated) reference as its own sidebar tab so it does not
+  // crowd the hand-written docs. Keep in sync with the other root sections' meta.json.
+  root: true,
   pages: pages
 };
 fs.writeFileSync(path.join(DOCS_ROOT, 'meta.json'), JSON.stringify(meta, null, 2));

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +---
 +---
++
 +docs: restructure the docs site left navigation — split the single long sidebar into six icon-labelled tabs (Getting Started, Concepts, Guides, Reference, Protocol, Releases), de-emphasise the ObjectQL/ObjectUI/ObjectOS protocol branding (Protocol moved to the last tab), isolate the 238 generated reference pages into their own tab, group the Guides section (Foundations/Building/Integration/Operations/Cheatsheets), and fix the top-nav GitHub link (objectstack-ai/spec → framework). Nav-only; no doc URLs change.
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"title": "Concepts",`
	`3`	`+ "icon": "Lightbulb",`
	`4`	`+ "root": true,`
`3`	`5`	`"pages": ["index", "north-star", "metadata-driven", "metadata-lifecycle", "design-principles", "architecture", "cluster-semantics", "webhook-delivery", "skills", "core", "packages", "setup-app", "cloud-artifact-api", "terminology", "implementation-status"]`
`4`	`6`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"title": "Getting Started",`
	`3`	`+ "icon": "Rocket",`
	`4`	`+ "root": true,`
`3`	`5`	`"pages": ["index", "quick-start", "core-concepts", "architecture", "examples", "cli", "glossary"]`
`4`	`6`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`	`1`	`{`
`2`		`- "title": "Contracts Protocol",`
	`2`	`+ "title": "Service Contracts",`
`3`	`3`	`"pages": ["index", "metadata-service", "auth-service", "storage-service", "data-engine", "cache-service"]`
`4`		`-}`
	`4`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -4,11 +4,8 @@`
`4`	`4`	`"getting-started",`
`5`	`5`	`"concepts",`
`6`	`6`	`"guides",`
`7`		`- "---",`
`8`		`- "protocol",`
`9`		`- "---",`
`10`	`7`	`"references",`
`11`		`- "---",`
	`8`	`+ "protocol",`
`12`	`9`	`"releases"`
`13`	`10`	`]`
`14`	`11`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,6 @@`
`1`	`1`	`{`
`2`		`- "title": "Protocol Overview",`
	`2`	`+ "title": "Protocol",`
	`3`	`+ "icon": "Network",`
	`4`	`+ "root": true,`
`3`	`5`	`"pages": ["index", "objectql", "objectui", "objectos", "knowledge"]`
`4`	`6`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,7 @@`
`1`	`1`	`{`
`2`		`- "title": "Protocol Reference",`
	`2`	`+ "title": "Reference",`
	`3`	`+ "icon": "FileCode",`
	`4`	`+ "root": true,`
`3`	`5`	`"pages": [`
`4`	`6`	`"ai",`
`5`	`7`	`"api",`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"title": "Releases",`
	`3`	`+ "icon": "Tag",`
	`4`	`+ "root": true,`
`3`	`5`	`"pages": ["index", "v9"]`
`4`	`6`	`}`