feat(console): book-driven documentation portal (ADR-0046 §6)

The `/docs` portal already rendered docs, but its navigation was a
namespace heuristic (group by the doc-name prefix). ADR-0046 §6 makes
`book` the authored navigation spine — ordered groups whose membership
over docs is derived from each group's include rule (glob/tag) with an
optional explicit `pages` override. This wires the portal to that spine.

- book-nav.ts: a faithful local port of the framework's `resolveBookTree`
  (glob/tag/order/explicit-pages resolution) plus portal helpers
  (sortBooks, buildBookCards, findBookContainingDoc, scopeDocsToBook). The
  synthetic Uncategorized catch-all is flagged so it's excluded from
  authored-membership questions (it appears in every book's resolution).
  No dependency on a published @objectstack/spec version or a /tree
  endpoint — resolves client-side from the ordinary metadata API.
- use-book-data.ts: fetch book + doc via meta.getItems; book is optional
  (a backend not yet serving it degrades to books: []).
- BookSidebar.tsx: the resolved spine as a persistent grouped left nav.
- BookPage.tsx (/docs/book/:book): a book landing — sidebar + grouped TOC.
- DocsIndex: lead with Books when present; keep the package-grouped flat
  list below as a complete index and the no-book fallback.
- DocPage: when the current doc belongs to a book, show that book's
  sidebar so a reader can move within the book.
- Routes: /docs/book/:book (top-level + app-scoped), before /docs/:name.

Tests: book-nav (12) + BookSidebar (5); existing doc tests unchanged.
console type-check + eslint clean.

Note: book/doc must be served by the backend for real data; all states
degrade gracefully (current published spec 9.5.1 serves neither yet).
Making /docs anonymously readable (ADR-0046 §6.7 public audience) is left
as a separate change — these routes stay behind ProtectedRoute as before.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

apps/console/src/App.tsx

@@ -44,6 +44,7 @@ import { MetadataHmrReloader } from './components/MetadataHmrReloader';
 import SharedRecordPage from './pages/SharedRecordPage';
 import DocPage from './pages/DocPage';
 import DocsIndex from './pages/DocsIndex';
+import BookPage from './pages/BookPage';
 import { LoginPage } from './pages/auth/LoginPage';
 import { RegisterPage } from './pages/auth/RegisterPage';
 import { ForgotPasswordPage } from './pages/auth/ForgotPasswordPage';
@@ -189,6 +190,12 @@ export function App() {
                 <DocsIndex />
               </ProtectedRoute>
             } />
+            {/* Book landing (ADR-0046 §6): the authored navigation spine. */}
+            <Route path="/docs/book/:book" element={
+              <ProtectedRoute>
+                <BookPage />
+              </ProtectedRoute>
+            } />
             <Route path="/docs/:name" element={
               <ProtectedRoute>
                 <DocPage />

apps/console/src/AppContent.tsx

@@ -35,6 +35,7 @@ const IntegrationsPage = lazy(() => import('./pages/developer/IntegrationsPage')
 // app-scoped index at /apps/:packageId/docs (AppDocsIndex).
 const DocPage = lazy(() => import('./pages/DocPage'));
 const AppDocsIndex = lazy(() => import('./pages/AppDocsIndex'));
+const BookPage = lazy(() => import('./pages/BookPage'));
 
 // Note: marketplace routes (`system/marketplace`, `system/marketplace/:packageId`)
 // are registered by DefaultAppContent in @object-ui/app-shell so they're
@@ -92,6 +93,8 @@ const systemRoutes = (
     {/* ADR-0048 — package docs under the package container: app-scoped index
         (/apps/:packageId/docs) + single-doc viewer (/apps/:packageId/docs/:name) */}
     <Route path="docs" element={<Suspense fallback={<LoadingScreen />}><AppDocsIndex /></Suspense>} />
+    {/* Book landing (ADR-0046 §6) — before docs/:name so 'book' isn't read as a doc name. */}
+    <Route path="docs/book/:book" element={<Suspense fallback={<LoadingScreen />}><BookPage /></Suspense>} />
     <Route path="docs/:name" element={<Suspense fallback={<LoadingScreen />}><DocPage /></Suspense>} />
     {/* Legacy URL redirects → metadata-admin engine (zero-cost compatibility). */}
     <Route path="system/objects" element={<ObjectRedirect />} />

apps/console/src/pages/BookPage.tsx

@@ -0,0 +1,128 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { useMemo } from 'react';
+import { Link, useParams } from 'react-router-dom';
+import { FileText, FileQuestion, Loader2 } from 'lucide-react';
+import { DocShell } from './DocShell';
+import { BookSidebar } from './BookSidebar';
+import { useBookData } from './use-book-data';
+import { resolveBookTree, scopeDocsToBook } from './book-nav';
+
+/**
+ * `/docs/book/:book` — a book landing page (ADR-0046 §6). Resolves the book's
+ * spine against the current docs and shows the grouped table of contents: the
+ * persistent nav sidebar plus an overview that lists every section's docs.
+ * Each doc links to the single-doc reader, which keeps this sidebar in view.
+ */
+export default function BookPage() {
+  const { book: bookName, appName } = useParams<{ book: string; appName?: string }>();
+  const { books, docs, state, error } = useBookData();
+
+  const found = useMemo(() => books.find((b) => b.name === bookName), [books, bookName]);
+  const resolved = useMemo(
+    () => (found ? resolveBookTree(found, scopeDocsToBook(found, docs)) : null),
+    [found, docs],
+  );
+
+  const docHref = (name: string) =>
+    appName ? `/apps/${appName}/docs/${name}` : `/docs/${name}`;
+
+  if (state === 'loading') {
+    return (
+      <div className="flex h-full items-center justify-center p-10 text-muted-foreground">
+        <Loader2 className="h-5 w-5 animate-spin" aria-label="Loading documentation" />
+      </div>
+    );
+  }
+
+  if (state === 'error' || !found || !resolved) {
+    return (
+      <DocShell breadcrumb={bookName}>
+        <div className="mx-auto flex max-w-3xl flex-col items-center gap-3 p-10 text-center">
+          <FileQuestion className="h-10 w-10 text-muted-foreground" />
+          <h1 className="text-lg font-semibold">
+            {state === 'error' ? 'Failed to load documentation' : 'Book not found'}
+          </h1>
+          <p className="text-sm text-muted-foreground">
+            {error ?? (
+              <>
+                No book named <code className="rounded bg-muted px-1 py-0.5">{bookName}</code> is installed.
+              </>
+            )}
+          </p>
+        </div>
+      </DocShell>
+    );
+  }
+
+  return (
+    <DocShell breadcrumb={resolved.label ?? bookName}>
+      <div className="mx-auto flex max-w-5xl gap-8 p-4 sm:p-6">
+        <aside className="hidden w-60 shrink-0 lg:block">
+          <div className="sticky top-20 max-h-[calc(100vh-6rem)] overflow-auto pr-1">
+            <BookSidebar book={resolved} docHref={docHref} />
+          </div>
+        </aside>
+
+        <div className="min-w-0 max-w-3xl flex-1">
+          <h1 className="text-2xl font-bold">{resolved.label ?? bookName}</h1>
+          {resolved.description ? (
+            <p className="mt-2 text-sm text-muted-foreground">{resolved.description}</p>
+          ) : null}
+
+          <div className="mt-6 space-y-8">
+            {resolved.groups.map((group) => (
+              <section key={group.key}>
+                <h2 className="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                  {group.label}
+                </h2>
+                <ul className="divide-y divide-border rounded-md border border-border">
+                  {group.entries
+                    .filter((e) => !e.separator)
+                    .map((entry, i) =>
+                      entry.href ? (
+                        <li key={`ext-${i}`}>
+                          <a
+                            href={entry.href}
+                            target="_blank"
+                            rel="noreferrer"
+                            className="flex items-start gap-3 px-3 py-3 hover:bg-muted/50"
+                          >
+                            <FileText className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" />
+                            <span className="text-sm font-medium">{entry.label ?? entry.href}</span>
+                          </a>
+                        </li>
+                      ) : entry.doc ? (
+                        <li key={entry.doc}>
+                          <Link
+                            to={docHref(entry.doc)}
+                            className="flex items-start gap-3 px-3 py-3 hover:bg-muted/50"
+                          >
+                            <FileText className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" />
+                            <div className="min-w-0">
+                              <div className="text-sm font-medium">{entry.label ?? entry.doc}</div>
+                              {entry.description ? (
+                                <div className="mt-0.5 line-clamp-2 text-xs text-muted-foreground">
+                                  {entry.description}
+                                </div>
+                              ) : null}
+                            </div>
+                          </Link>
+                        </li>
+                      ) : null,
+                    )}
+                </ul>
+              </section>
+            ))}
+          </div>
+        </div>
+      </div>
+    </DocShell>
+  );
+}

apps/console/src/pages/BookSidebar.test.tsx

@@ -0,0 +1,75 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, cleanup, within } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import { BookSidebar } from './BookSidebar';
+import type { ResolvedBook } from './book-nav';
+
+afterEach(cleanup);
+
+const book: ResolvedBook = {
+  name: 'crm_manual',
+  label: 'CRM Manual',
+  groups: [
+    {
+      key: 'start',
+      label: 'Getting started',
+      entries: [
+        { doc: 'crm_intro', label: 'Intro' },
+        { separator: true },
+        { href: 'https://example.com', label: 'External' },
+      ],
+    },
+    { key: 'extra', label: 'Extra', synthetic: true, entries: [{ doc: 'misc_note', label: 'Note' }] },
+  ],
+};
+
+function renderSidebar(activeDoc?: string) {
+  return render(
+    <MemoryRouter>
+      <BookSidebar book={book} activeDoc={activeDoc} docHref={(n) => `/docs/${n}`} />
+    </MemoryRouter>,
+  );
+}
+
+describe('BookSidebar', () => {
+  it('renders the book label and group headings', () => {
+    renderSidebar();
+    expect(screen.getByText('CRM Manual')).toBeInTheDocument();
+    expect(screen.getByText('Getting started')).toBeInTheDocument();
+    expect(screen.getByText('Extra')).toBeInTheDocument();
+  });
+
+  it('renders doc links to the resolved href', () => {
+    renderSidebar();
+    const link = screen.getByRole('link', { name: 'Intro' });
+    expect(link).toHaveAttribute('href', '/docs/crm_intro');
+  });
+
+  it('marks the active doc with aria-current', () => {
+    renderSidebar('crm_intro');
+    expect(screen.getByRole('link', { name: 'Intro' })).toHaveAttribute('aria-current', 'page');
+    expect(screen.getByRole('link', { name: 'Note' })).not.toHaveAttribute('aria-current');
+  });
+
+  it('renders external links with target=_blank', () => {
+    renderSidebar();
+    const ext = screen.getByRole('link', { name: /External/ });
+    expect(ext).toHaveAttribute('href', 'https://example.com');
+    expect(ext).toHaveAttribute('target', '_blank');
+  });
+
+  it('renders a separator as a non-interactive divider', () => {
+    renderSidebar();
+    // The "Getting started" group has 2 links (Intro + External) and 1 separator.
+    const startNav = screen.getByLabelText('CRM Manual');
+    expect(within(startNav).getAllByRole('link').length).toBe(3); // Intro, External, Note
+  });
+});

apps/console/src/pages/BookSidebar.tsx

@@ -0,0 +1,87 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { Link } from 'react-router-dom';
+import { ExternalLink } from 'lucide-react';
+import type { ResolvedBook } from './book-nav';
+
+/**
+ * The persistent left navigation for a book (ADR-0046 §6) — the resolved
+ * spine rendered as grouped links. Used by the book landing page and shown
+ * alongside the single-doc reader so a reader can move within the book
+ * without losing their place.
+ *
+ * Routing is delegated: the parent supplies `docHref` so the same sidebar
+ * works under the top-level `/docs/:name` route and the package-scoped
+ * `/apps/:appName/docs/:name` route.
+ */
+export function BookSidebar({
+  book,
+  activeDoc,
+  docHref,
+}: {
+  book: ResolvedBook;
+  activeDoc?: string;
+  docHref: (docName: string) => string;
+}) {
+  return (
+    <nav aria-label={book.label ?? book.name} className="text-sm">
+      {book.label ? (
+        <div className="mb-3 px-2 text-sm font-semibold text-foreground">{book.label}</div>
+      ) : null}
+      <div className="space-y-5">
+        {book.groups.map((group) => (
+          <div key={group.key}>
+            <div className="mb-1 px-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+              {group.label}
+            </div>
+            <ul className="space-y-0.5">
+              {group.entries.map((entry, i) => {
+                if (entry.separator) {
+                  return <li key={`sep-${i}`} className="my-1.5 border-t border-border/60" aria-hidden />;
+                }
+                if (entry.href) {
+                  return (
+                    <li key={`ext-${i}`}>
+                      <a
+                        href={entry.href}
+                        target="_blank"
+                        rel="noreferrer"
+                        className="flex items-center gap-1.5 rounded px-2 py-1 text-muted-foreground hover:bg-muted/50 hover:text-foreground"
+                      >
+                        <span className="truncate">{entry.label ?? entry.href}</span>
+                        <ExternalLink className="h-3 w-3 shrink-0 opacity-60" />
+                      </a>
+                    </li>
+                  );
+                }
+                if (!entry.doc) return null;
+                const active = entry.doc === activeDoc;
+                return (
+                  <li key={entry.doc}>
+                    <Link
+                      to={docHref(entry.doc)}
+                      aria-current={active ? 'page' : undefined}
+                      className={`block truncate rounded px-2 py-1 transition ${
+                        active
+                          ? 'bg-primary/10 font-medium text-foreground'
+                          : 'text-muted-foreground hover:bg-muted/50 hover:text-foreground'
+                      }`}
+                    >
+                      {entry.label ?? entry.doc}
+                    </Link>
+                  </li>
+                );
+              })}
+            </ul>
+          </div>
+        ))}
+      </div>
+    </nav>
+  );
+}

apps/console/src/pages/DocPage.tsx

@@ -14,6 +14,9 @@ import { MarkdownRenderer, extractToc } from '@object-ui/plugin-markdown';
 import { useObjectTranslation } from '@object-ui/i18n';
 import { rewriteDocLinks } from './doc-links';
 import { DocShell } from './DocShell';
+import { BookSidebar } from './BookSidebar';
+import { useBookData } from './use-book-data';
+import { findBookContainingDoc } from './book-nav';
 
 interface DocItem {
   name: string;
@@ -104,6 +107,20 @@ export default function DocPage() {
   const toc = useMemo(() => extractToc(doc?.content ?? ''), [doc?.content]);
   const tocLabel = t('help.onThisPage', { defaultValue: 'On this page' });
 
+  // Book context (ADR-0046 §6): if this doc belongs to an authored book, show
+  // that book's spine as a persistent left nav so the reader can move within
+  // the book. Independent of the single-doc fetch above — degrades to no
+  // sidebar when no book owns the doc (or the backend serves no books yet).
+  const { books, docs: allDocs } = useBookData();
+  const bookCtx = useMemo(
+    () => (name ? findBookContainingDoc(books, allDocs, name) : null),
+    [books, allDocs, name],
+  );
+  const docHref = useCallback(
+    (docName: string) => (appName ? `/apps/${appName}/docs/${docName}` : `/docs/${docName}`),
+    [appName],
+  );
+
   if (state === 'loading') {
     return (
       <div className="flex h-full items-center justify-center p-10 text-muted-foreground">
@@ -141,7 +158,14 @@ export default function DocPage() {
 
   return (
     <DocShell breadcrumb={doc?.label ?? name}>
-      <div className="mx-auto flex max-w-5xl gap-8 p-4 sm:p-6">
+      <div className={`mx-auto flex gap-8 p-4 sm:p-6 ${bookCtx ? 'max-w-6xl' : 'max-w-5xl'}`}>
+        {bookCtx ? (
+          <aside className="hidden w-56 shrink-0 lg:block">
+            <nav className="sticky top-20 max-h-[calc(100vh-6rem)] overflow-auto pr-1">
+              <BookSidebar book={bookCtx.resolved} activeDoc={name} docHref={docHref} />
+            </nav>
+          </aside>
+        ) : null}
         <article
           className="min-w-0 max-w-3xl flex-1 [&_h1]:scroll-mt-24 [&_h2]:scroll-mt-24 [&_h3]:scroll-mt-24"
           onClick={onContentClick}