feat(ADR-0046): package documentation portal + nav entry (#1686)

The /docs/:name viewer (DocPage) already existed but had no entry point — no
index and no nav link — so a doc was reachable only by typing its exact URL.
That is why docs were invisible in the console.

- DocsIndex (/docs): platform-level portal listing every installed `doc`
  grouped by package namespace, each linking to the existing viewer. Fetches
  via meta.getItems('doc'); empty/error/loading states mirror DocPage.
- groupDocsByPackage: pure, unit-tested grouping helper (6 tests).
- UnifiedSidebar: "Documentation" entry in the base home/system nav — visible
  to ALL users, not gated behind workspace-admin (it lives in the always-shown
  items array, not the admin cluster).
- App.tsx: register the top-level /docs route alongside /docs/:name; both are
  app-independent (reachable with no active app), keeping the doc URL
  single-coordinate as ADR-0046 specifies.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

.changeset/adr-0046-docs-portal.md

@@ -0,0 +1,17 @@
+---
+"@object-ui/console": minor
+"@object-ui/app-shell": minor
+---
+
+Package documentation portal + nav entry (ADR-0046).
+
+The `/docs/:name` viewer already existed but had no way in: no index and no
+navigation entry, so a doc was reachable only by typing its exact URL. Adds a
+platform-level docs portal at `/docs` (`DocsIndex`) that lists every installed
+`doc` metadata item grouped by package namespace, each linking to the existing
+viewer. A "Documentation" entry now appears in the home/system navigation
+(`UnifiedSidebar`), visible to all users (not gated behind workspace-admin), so
+docs are discoverable. The viewer route stays app-independent and
+single-coordinate (`/docs/<name>`); per-app deep-links remain opt-in `url` nav
+items pointing at that same global URL. Doc grouping is a pure, unit-tested
+helper (`groupDocsByPackage`).

apps/console/src/App.tsx

@@ -43,6 +43,7 @@ import { FormPage } from './components/FormPage';
 import { MetadataHmrReloader } from './components/MetadataHmrReloader';
 import SharedRecordPage from './pages/SharedRecordPage';
 import DocPage from './pages/DocPage';
+import DocsIndex from './pages/DocsIndex';
 import { LoginPage } from './pages/auth/LoginPage';
 import { RegisterPage } from './pages/auth/RegisterPage';
 import { ForgotPasswordPage } from './pages/auth/ForgotPasswordPage';
@@ -179,9 +180,15 @@ export function App() {
                 <FormPage mode="internal" />
               </ProtectedRoute>
             } />
-            {/* Package documentation (ADR-0046): one route renders any
-              * installed `doc` metadata item; cross-references between docs
-              * resolve to this same route. */}
+            {/* Package documentation (ADR-0046): a platform-level portal
+              * lists every installed `doc` (grouped by package), and one
+              * viewer route renders any item; cross-references between docs
+              * resolve to that same viewer route. Both are app-independent. */}
+            <Route path="/docs" element={
+              <ProtectedRoute>
+                <DocsIndex />
+              </ProtectedRoute>
+            } />
             <Route path="/docs/:name" element={
               <ProtectedRoute>
                 <DocPage />

apps/console/src/pages/DocsIndex.tsx

@@ -0,0 +1,131 @@
+/**
+ * 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 { useEffect, useState } from 'react';
+import { Link } from 'react-router-dom';
+import { AlertCircle, BookOpen, Loader2 } from 'lucide-react';
+import { useAdapter } from '@object-ui/app-shell';
+import { type DocGroup, groupDocsByPackage } from './doc-groups';
+
+/**
+ * `/docs` — the platform-level documentation portal (ADR-0046).
+ *
+ * Lists every installed `doc` metadata item, grouped by package
+ * namespace, each linking to the single-doc viewer at `/docs/<name>`.
+ * The viewer route is app-independent, so this portal is the canonical
+ * place to discover docs regardless of which app (if any) is active.
+ * An app may additionally surface a contextual link into a specific
+ * `/docs/<name>`, but discovery lives here.
+ */
+export default function DocsIndex() {
+  const adapter = useAdapter();
+  const [groups, setGroups] = useState<DocGroup[]>([]);
+  const [state, setState] = useState<'loading' | 'ready' | 'error'>('loading');
+  const [errorMessage, setErrorMessage] = useState<string>('');
+
+  useEffect(() => {
+    let cancelled = false;
+    async function load() {
+      if (!adapter) return;
+      const client: any = adapter.getClient();
+      if (!client?.meta?.getItems) {
+        setErrorMessage('meta.getItems is not available on this client');
+        setState('error');
+        return;
+      }
+      setState('loading');
+      try {
+        const result: any = await client.meta.getItems('doc');
+        const items: any[] = Array.isArray(result)
+          ? result
+          : Array.isArray(result?.items)
+            ? result.items
+            : Array.isArray(result?.value)
+              ? result.value
+              : [];
+        if (cancelled) return;
+        setGroups(
+          groupDocsByPackage(
+            items.map((it) => ({ name: it?.name, label: it?.label })),
+          ),
+        );
+        setState('ready');
+      } catch (err: any) {
+        if (cancelled) return;
+        setErrorMessage(err?.message ?? 'Failed to load documentation');
+        setState('error');
+      }
+    }
+    void load();
+    return () => {
+      cancelled = true;
+    };
+  }, [adapter]);
+
+  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') {
+    return (
+      <div className="mx-auto flex max-w-3xl flex-col items-center gap-3 p-10 text-center">
+        <AlertCircle className="h-10 w-10 text-destructive" />
+        <h1 className="text-lg font-semibold">Failed to load documentation</h1>
+        <p className="text-sm text-muted-foreground">{errorMessage}</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto max-w-3xl p-4 sm:p-6">
+      <div className="mb-6 flex items-center gap-2">
+        <BookOpen className="h-6 w-6 text-muted-foreground" />
+        <h1 className="text-2xl font-semibold">Documentation</h1>
+      </div>
+
+      {groups.length === 0 ? (
+        <div className="flex flex-col items-center gap-3 py-16 text-center text-muted-foreground">
+          <BookOpen className="h-10 w-10" />
+          <p className="text-sm">
+            No documentation is installed. Packages ship docs as flat
+            <code className="mx-1 rounded bg-muted px-1 py-0.5">src/docs/*.md</code>
+            files (ADR-0046).
+          </p>
+        </div>
+      ) : (
+        <div className="space-y-8">
+          {groups.map((group) => (
+            <section key={group.pkg}>
+              <h2 className="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                {group.pkg}
+              </h2>
+              <ul className="divide-y divide-border rounded-md border border-border">
+                {group.docs.map((doc) => (
+                  <li key={doc.name}>
+                    <Link
+                      to={`/docs/${doc.name}`}
+                      className="flex items-center gap-2 px-3 py-2 text-sm hover:bg-muted/50"
+                    >
+                      <BookOpen className="h-4 w-4 shrink-0 text-muted-foreground" />
+                      <span className="font-medium">{doc.label ?? doc.name}</span>
+                      <code className="ml-auto text-xs text-muted-foreground">{doc.name}</code>
+                    </Link>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

apps/console/src/pages/doc-groups.test.ts

@@ -0,0 +1,61 @@
+/**
+ * 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, expect, it } from 'vitest';
+import { groupDocsByPackage } from './doc-groups';
+
+describe('groupDocsByPackage (ADR-0046)', () => {
+  it('groups docs by namespace prefix', () => {
+    const groups = groupDocsByPackage([
+      { name: 'crm_user_guide' },
+      { name: 'crm_index' },
+      { name: 'hr_onboarding' },
+    ]);
+    expect(groups.map((g) => g.pkg)).toEqual(['crm', 'hr']);
+    expect(groups[0].docs.map((d) => d.name)).toEqual(['crm_index', 'crm_user_guide']);
+    expect(groups[1].docs.map((d) => d.name)).toEqual(['hr_onboarding']);
+  });
+
+  it('sorts groups alphabetically and docs by label then name', () => {
+    const groups = groupDocsByPackage([
+      { name: 'zoo_b', label: 'Zebra' },
+      { name: 'zoo_a', label: 'Antelope' },
+      { name: 'apex_x' },
+    ]);
+    expect(groups.map((g) => g.pkg)).toEqual(['apex', 'zoo']);
+    // Sorted by label: Antelope before Zebra.
+    expect(groups[1].docs.map((d) => d.name)).toEqual(['zoo_a', 'zoo_b']);
+  });
+
+  it('groups a bare (unprefixed) name under itself', () => {
+    const groups = groupDocsByPackage([{ name: 'readme' }]);
+    expect(groups).toEqual([{ pkg: 'readme', docs: [{ name: 'readme' }] }]);
+  });
+
+  it('ignores a leading underscore (no empty-string package)', () => {
+    // indexOf('_') === 0 → not a real prefix; group under the whole name.
+    const groups = groupDocsByPackage([{ name: '_hidden' }]);
+    expect(groups[0].pkg).toBe('_hidden');
+  });
+
+  it('drops malformed items without a name', () => {
+    const groups = groupDocsByPackage([
+      { name: 'crm_a' },
+      { name: '' },
+      // @ts-expect-error — exercising the runtime guard
+      { label: 'no name' },
+      // @ts-expect-error — exercising the runtime guard
+      null,
+    ]);
+    expect(groups).toEqual([{ pkg: 'crm', docs: [{ name: 'crm_a' }] }]);
+  });
+
+  it('returns an empty array for no docs', () => {
+    expect(groupDocsByPackage([])).toEqual([]);
+  });
+});

apps/console/src/pages/doc-groups.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+
+export interface DocListItem {
+  name: string;
+  label?: string;
+}
+
+export interface DocGroup {
+  /** Namespace prefix (the package), derived from the doc name. */
+  pkg: string;
+  docs: DocListItem[];
+}
+
+/**
+ * Group docs by their namespace prefix (everything before the first `_`).
+ *
+ * Doc names are namespace-prefixed by build-time convention (ADR-0046) —
+ * `crm_user_guide` belongs to package `crm`. The spec carries no explicit
+ * `namespace` field, so the package is derived from the name; a bare name
+ * with no underscore groups under itself. Groups and the docs within each
+ * are returned in stable alphabetical order. Malformed items (missing
+ * name) are dropped.
+ */
+export function groupDocsByPackage(items: DocListItem[]): DocGroup[] {
+  const byPkg = new Map<string, DocListItem[]>();
+  for (const item of items) {
+    if (!item || typeof item.name !== 'string' || !item.name) continue;
+    const underscore = item.name.indexOf('_');
+    const pkg = underscore > 0 ? item.name.slice(0, underscore) : item.name;
+    const bucket = byPkg.get(pkg);
+    if (bucket) bucket.push(item);
+    else byPkg.set(pkg, [item]);
+  }
+  return Array.from(byPkg.keys())
+    .sort((a, b) => a.localeCompare(b))
+    .map((pkg) => ({
+      pkg,
+      docs: byPkg
+        .get(pkg)!
+        .slice()
+        .sort((a, b) => (a.label ?? a.name).localeCompare(b.label ?? b.name)),
+    }));
+}

packages/app-shell/src/layout/UnifiedSidebar.tsx

@@ -225,6 +225,10 @@ export function UnifiedSidebar({ activeAppName }: UnifiedSidebarProps) {
   const homeNavigation: NavigationItem[] = React.useMemo(() => {
     const items: NavigationItem[] = [
       { id: 'home-dashboard', label: t('home.nav', { defaultValue: 'Home' }), type: 'url' as const, url: '/home', icon: 'home' },
+      // Package documentation portal (ADR-0046) — visible to all users, not
+      // just workspace admins, so it lives in the base items rather than the
+      // admin cluster below.
+      { id: 'docs', label: t('layout.systemNav.documentation', { defaultValue: 'Documentation' }), type: 'url' as const, url: '/docs', icon: 'book-open' },
     ];
     if (isWorkspaceAdmin) {
       const adminItems: NavigationItem[] = [