Docs: Enable documentation section of website (#95)

* Enable documentation section of website

Signed-off-by: Ed Snible <snible@us.ibm.com>

Author: esnible

README.md

@@ -51,8 +51,7 @@ SRC_REPO=/path/to/rossoctl npm run sync-docs
 npm start            # http://localhost:3000/.github/  (Ctrl+C to stop)
 ```
 
-To verify a production build the way CI does — this is the check that matters
-before pushing, since `npm start` is more lenient than a real build:
+We do not use `npm start` to run the dev server with hot reload, because we make heavy use of the `draft` feature, which is not suppressed by `start`.
 
 ```sh
 npm run build        # production build into build/  (fails on broken links, type errors)
@@ -84,3 +83,4 @@ set `baseUrl: '/'` in `docusaurus.config.ts` and add `static/CNAME`.
 Commits require **DCO sign-off** (`git commit -s`). See [`CLAUDE.md`](./CLAUDE.md)
 for the sign-off and attribution policy, and enable the hook with
 `git config core.hooksPath scripts/hooks`.
+

docusaurus.config.ts

@@ -57,8 +57,8 @@ const config: Config = {
         // and sitemap — not merely hidden from the navbar. Doc authoring
         // continues upstream in rossoctl/rossoctl:docs/.
         // TO RESTORE: delete `docs: false` and uncomment the block below.
-        docs: false,
-        /* docs: {
+        // docs: false,
+        docs: {
           // Read docs from a local docs/ folder that mirrors the source of
           // truth 1:1. This folder is NOT committed — scripts/sync-docs.sh syncs
           // it from rossoctl/rossoctl:docs/ at build time. routeBasePath keeps
@@ -73,12 +73,15 @@ 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.
+          exclude: [
+            
+          ],
           versions: {
             current: {
               label: 'dev',
             },
           },
-        }, */
+        },
         // Blog is an EXTERNAL Medium link (see navbar) — no local blog.
         blog: false,
         theme: {
@@ -146,14 +149,12 @@ const config: Config = {
         // clicking the logo/title goes to '/', the landing page
       },
       items: [
-        // === TEMPORARY: "Documentation" nav item hidden until docs go public. ===
-        // TO RESTORE: uncomment this item (requires re-enabling `docs` in the preset above).
-        /* {
+        {
           type: 'docSidebar',
           sidebarId: 'docsSidebar',
           position: 'left',
           label: 'Documentation',
-        }, */
+        },
         {
           // Single "Contributing" page rendered from the contributing docs
           // instance (docs layout + breadcrumbs). Content mirrors rossoctl's

ecosystem/welcome.mdx

@@ -25,42 +25,42 @@ export const cortexFunctions = [
   },
   {
     number: '03',
-    status: 'In progress',
+    status: 'beta in 0.7',
     title: 'Intent-based access',
     description:
       "Access is tied to what the user actually asked for, so an agent that drifts off task can't quietly reuse its access for something else.",
   },
   {
     number: '04',
-    status: 'In progress',
+    status: 'beta in 0.7',
     title: 'Tool semantic validation',
     description:
       "Tool calls are checked for correctness and meaning before they run, catching calls that are malformed or don't match the task.",
   },
   {
     number: '05',
-    status: 'Next',
+    status: 'alpha in 0.7',
     title: 'Context compaction',
     description:
       "The platform assembles and trims what goes into the model's context, keeping it relevant and lowering token cost.",
   },
   {
     number: '06',
-    status: 'Next',
+    status: 'alpha in 0.7',
     title: 'Data-flow analysis',
     description:
       'The platform tracks where the data behind a decision came from, so its provenance can gate what the agent does next.',
   },
   {
     number: '07',
-    status: 'In progress',
+    status: 'beta in 0.7',
     title: 'Failure recovery',
     description:
       'The platform detects when an agent stalls or fails and returns it to a known state instead of leaving work half-finished.',
   },
   {
     number: '08',
-    status: 'In progress',
+    status: 'beta in 0.7',
     title: 'User interaction',
     description:
       'For high-stakes steps, a person stays in the loop and approves before the agent acts.',
@@ -112,8 +112,7 @@ rossoctl is a set of platform primitives for agent security, resilience, and eff
 
 <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="https://github.com/rossoctl/rossoctl">Get started</Link>
-  <Link className="button button--lg cta-secondary" href="https://github.com/rossoctl/cortex">Try RossoCortex</Link>
+  <Link className="button button--lg cta-primary margin-right--sm" href="/docs/overview/quickstart">Get started</Link>
 </div>
 
 <ArchitectureDiagram />

scripts/sync-docs.sh

@@ -45,7 +45,20 @@ if [[ -d "$UP" ]]; then
   mkdir -p "$DEST"
   rsync -a --delete --exclude '.DS_Store' "$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"
+  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.)
   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

@@ -11,7 +11,26 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
  * The key here ("docsSidebar") must match `sidebarId` in docusaurus.config.ts.
  */
 const sidebars: SidebarsConfig = {
-  docsSidebar: [{type: 'autogenerated', dirName: '.'}],
+  // 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: '.'}],
+    },
+  ],
 };
 
 export default sidebars;

src/components/Accordion/index.tsx

@@ -16,9 +16,9 @@ export type AccordionItem = {
 
 // Map a status label to its pill style.
 const STATUS_CLASS: Record<string, string> = {
-  Ready: styles.pillReady,
-  'In progress': styles.pillProgress,
-  Next: styles.pillNext,
+  'Ready': styles.pillReady,
+  'beta in 0.7': styles.pillProgress,
+  'alpha in 0.7': styles.pillNext,
 };
 
 function Chevron({open}: {open: boolean}): ReactNode {