site: support the restructured docs IA, and tune documentation typography

docusaurus.config.ts

@@ -92,8 +92,21 @@ const config: Config = {
           // versions exist yet. When the first is cut
           // (`npm run docusaurus docs:version 0.7`), it becomes the default
           // "latest" and "dev" stays as the work-in-progress version.
+          // IMPORTANT: providing `exclude` REPLACES Docusaurus's defaults rather
+          // than adding to them, so the defaults are repeated here verbatim. The
+          // '**/_*/**' entry is what keeps docs/_internal/** — the team's plans,
+          // research, retrospectives and QA notes — out of the build. Dropping it
+          // publishes those notes and fails the build on their repo-relative
+          // image links.
           exclude: [
-            // Internal working notes — not part of the published site.
+            // --- Docusaurus defaults. Do not remove. ---
+            '**/_*.{js,jsx,ts,tsx,md,mdx}',
+            '**/_*/**',
+            '**/*.test.{js,jsx,ts,tsx}',
+            '**/__tests__/**',
+            // --- Legacy locations, pre-restructure. Harmless once upstream has
+            // moved this content under docs/_internal/; kept so this config is
+            // correct whichever order the two PRs land in. ---
             'superpowers/**',
             'authbridge/**',
             'automation-health.md',
@@ -110,6 +123,10 @@ const config: Config = {
                       v,
                       {
                         label: v === LATEST_VERSION ? `v${v} (latest)` : `v${v}`,
+                        // Docusaurus already routes the lastVersion at the bare
+                        // /docs and the rest under /docs/<version>. Stating it
+                        // here is deliberate: it documents the URL shape at the
+                        // point a reader looks for it. Keep it.
                         path: v === LATEST_VERSION ? '' : v,
                         badge: true,
                       },

ecosystem/welcome.mdx

@@ -116,7 +116,7 @@ and built on open standards, supporting A2A and MCP.
 
 <div className="margin-top--md margin-bottom--lg">
   {/* Primary CTAs point at the project repos (docs hidden pre-launch). */}
-  <Link className="button button--lg cta-primary margin-right--sm" href="/docs/overview/quickstart">Get started</Link>
+  <Link className="button button--lg cta-primary margin-right--sm" href="/docs/">Get started</Link>
 </div>
 
 <ArchitectureDiagram />

package.json

@@ -20,6 +20,7 @@
     "@docusaurus/core": "3.10.1",
     "@docusaurus/preset-classic": "3.10.1",
     "@docusaurus/theme-mermaid": "3.10.1",
+    "@fontsource/ibm-plex-mono": "^5.3.0",
     "@fontsource/ibm-plex-sans": "^5.2.8",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",

scripts/sync-docs.sh

@@ -43,22 +43,30 @@ fi
 UP="$SRC/$SUBDIR"
 if [[ -d "$UP" ]]; then
   mkdir -p "$DEST"
-  rsync -a --delete --exclude '.DS_Store' "$UP"/ "$DEST"/
+  # _internal/ holds the team's engineering notes (plans, research, retrospectives,
+  # QA matrices, developer setup). Docusaurus would ignore them anyway via its
+  # default '**/_*/**' exclude, but keeping them out of the site tree entirely
+  # matters for versioning: `docusaurus docs:version` snapshots whatever is in
+  # docs/ into a COMMITTED versioned_docs/ folder, so without this every release
+  # would freeze a copy of those notes into this repo.
+  # '/_internal' is anchored to the top of the transfer, so it excludes exactly
+  # docs/_internal/ and not a directory of that name at any other depth.
+  rsync -a --delete --exclude '.DS_Store' --exclude '/_internal' "$UP"/ "$DEST"/
 
-  # The /docs/ root is a GENERATED INDEX (see sidebars.ts), not a markdown file.
-  # By default Docusaurus maps docs/README.md to the /docs/ route, which would
-  # collide with that generated index. Give README a slug so it ships as an
-  # ordinary page (/docs/readme) and frees the root route. Prepend frontmatter
-  # (upstream README has none). Skip if it somehow already has frontmatter.
-  README="$DEST/README.md"
-  if [[ -f "$README" ]] && ! head -1 "$README" | grep -q '^---$'; then
-    printf -- '---\nslug: /readme\nsidebar_label: Overview\n---\n\n%s' "$(cat "$README")" > "$README.tmp"
-    mv "$README.tmp" "$README"
+  # MIGRATION WINDOW: the restructured docs tree provides docs/index.md with
+  # `slug: /` as the /docs/ landing page (see sidebars.ts, which no longer wraps
+  # everything in a generated-index category). Until that lands upstream,
+  # synthesise a minimal one so the /docs/ route — and the navbar's
+  # "Documentation" link — still resolves. This becomes a no-op the moment
+  # upstream ships its own index.md, and can then be deleted.
+  if [[ ! -f "$DEST/index.md" ]]; then
+    printf -- '---\ntitle: Rossoctl documentation\nslug: /\n---\n\nChoose a section from the sidebar.\n' \
+      > "$DEST/index.md"
+    echo "==> synthesised docs/index.md (upstream does not provide one yet)."
   fi
 
-  # Rewrite links to README.md -> index.md (Docusaurus folder-index convention).
-  # (README is no longer the folder index, but existing ./README.md links across
-  # the docs still resolve to the same page; keep this so cross-links don't break.)
+  # Rewrite any remaining links to README.md -> index.md (Docusaurus folder-index
+  # convention), so a cross-link written against a folder README still resolves.
   find "$DEST" -name '*.md' -type f -print0 | while IFS= read -r -d '' f; do
     sed -i.bak -E 's#\]\(([^)]*)README\.md#](\1index.md#g' "$f" && rm -f "$f.bak"
   done

sidebars.ts

@@ -3,34 +3,20 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
 /**
  * The docs sidebar is fully AUTOGENERATED from the docs/ folder tree, so the
  * left nav mirrors the folder structure 1:1. Content authors control ordering
- * and labels with:
+ * and labels upstream in rossoctl/rossoctl:docs/ with:
  *   - _category_.json   (per folder: label, position, link, collapsed)
  *   - frontmatter       (per file: sidebar_position, sidebar_label, title)
  *
- * There is nothing to edit in this file when adding/removing/reordering docs.
- * The key here ("docsSidebar") must match `sidebarId` in docusaurus.config.ts.
+ * There is nothing to edit in this file when adding, removing, or reordering
+ * docs. The key here ("docsSidebar") must match `sidebarId` in
+ * docusaurus.config.ts.
+ *
+ * The /docs/ route is served by docs/index.md, which carries `slug: /`. There is
+ * deliberately no wrapping category: one would add a redundant "Documentation"
+ * level above the nine real sections.
  */
 const sidebars: SidebarsConfig = {
-  // The docs root (/docs/) is a GENERATED INDEX — an auto-built list of the
-  // sections below — rather than a single markdown file. This is durable: the
-  // docs/ folder is regenerated from upstream on every build (scripts/sync-docs.sh),
-  // so we don't rely on any specific file (like README.md) landing at the root.
-  // README.md still ships as a normal page; sync-docs.sh gives it a slug so it
-  // no longer claims the /docs/ route.
-  docsSidebar: [
-    {
-      type: 'category',
-      label: 'Documentation',
-      link: {
-        type: 'generated-index',
-        title: 'Rossoctl Documentation',
-        description:
-          'Guides, concepts, and references for deploying and operating Rossoctl.',
-        slug: '/',
-      },
-      items: [{type: 'autogenerated', dirName: '.'}],
-    },
-  ],
+  docsSidebar: [{type: 'autogenerated', dirName: '.'}],
 };
 
 export default sidebars;