diff --git a/‎.changeset/11245-book-sidebar-explicit-group.md‎
Lines changed: 18 additions & 0 deletions b/‎.changeset/11245-book-sidebar-explicit-group.md‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎apps/console/src/pages/book-nav.explicitGroup-11245.test.ts‎
Lines changed: 121 additions & 0 deletions b/‎apps/console/src/pages/book-nav.explicitGroup-11245.test.ts‎
Lines changed: 121 additions & 0 deletions
diff --git a/‎apps/console/src/pages/book-nav.ts‎
Lines changed: 10 additions & 1 deletion b/‎apps/console/src/pages/book-nav.ts‎
Lines changed: 10 additions & 1 deletion
diff --git a/‎apps/console/src/pages/docs-portal.explicitGroup-11245.test.tsx‎
Lines changed: 142 additions & 0 deletions b/‎apps/console/src/pages/docs-portal.explicitGroup-11245.test.tsx‎
Lines changed: 142 additions & 0 deletions
@@ -0,0 +1,18 @@
+---
+'@object-ui/console': patch
+---
+
+fix(console): the docs portal's book sidebar keeps a doc placed by its own `group` key from outside the book's package (objectui#11245)
+
+A doc names the book group it belongs to through its own `group` key. The framework's
+`resolveBookTree` places such a doc in that group with no package scope (only a group's
+`include` is scoped), and `GET /meta/book/:name/tree` answers that resolver. The portal
+dropped every doc outside the book's package BEFORE resolving, so a doc an admin placed
+from the doc editor was listed by the tree endpoint and missing from the book sidebar:
+its group rendered empty, the book card did not count it, and a book with nothing else
+to open showed "This book has no documents yet".
+
+`scopeDocsToBook` now keeps a doc whose `group` names one of the book's group keys,
+whatever its package. The package filter still narrows what `include` and the synthetic
+Uncategorized group can collect, so another package's ungrouped docs stay out of the
+book, and a group-level `package` override still scopes that group's `include`.
@@ -0,0 +1,121 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#11245 — a doc placed by its own `group` key keeps its place in the
+ * book sidebar even when it lives outside the book's package.
+ *
+ * The framework's `resolveBookTree` places a doc in a group when the doc's own
+ * `group` names that group's `key`, with no package scope; only `include` is
+ * scoped (to `group.package`, else the book's package). `GET
+ * /meta/book/:name/tree` answers that resolver over every doc. The portal's
+ * `scopeDocsToBook` dropped every doc outside the book's packages BEFORE
+ * resolving, so a doc the admin placed from the doc editor (objectui#11241)
+ * was listed by the endpoint and missing from the sidebar.
+ *
+ * The package filter still narrows what the synthetic Uncategorized group can
+ * collect — the controls below hold that — and `include` stays scoped by the
+ * resolver itself.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { resolveBookTree as specResolveBookTree } from '@objectstack/spec/system';
+import {
+  resolveBookTree,
+  scopeDocsToBook,
+  countBookDocs,
+  type Book,
+  type ResolvedBook,
+  type ResolverDoc,
+} from './book-nav';
+
+const BOOK_PKG = 'com.example.docprobe';
+const OTHER_PKG = 'com.example.other';
+
+/** The shape of the card's probe: a book with an `include` group and a `reference` group. */
+const book: Book = {
+  name: 'docprobe_manual',
+  label: 'Probe Manual',
+  packageId: BOOK_PKG,
+  groups: [
+    { key: 'start', label: 'Getting started', order: 1, include: 'docprobe_gs_*' },
+    { key: 'reference', label: 'Reference', order: 2, include: 'docprobe_ref_*' },
+  ],
+};
+
+const docs: ResolverDoc[] = [
+  { name: 'docprobe_gs_welcome', label: 'Welcome', packageId: BOOK_PKG },
+  // Outside the book's package, placed by its own `group` — one read back with no
+  // stamped package, one stamped with a package that is not the book's.
+  { name: 'live_guide', label: 'Live Guide', group: 'reference' },
+  { name: 'probe_curl', label: 'Probe Curl', group: 'reference', packageId: 'sys_metadata' },
+  // Controls: another package's ungrouped doc, and one naming a key this book lacks.
+  { name: 'other_note', label: 'Other Note', packageId: OTHER_PKG },
+  { name: 'other_stray', label: 'Other Stray', group: 'appendix', packageId: OTHER_PKG },
+];
+
+/** What the portal renders for a book: the same two calls `DocPage` / `BookPage` make. */
+const portalTree = (b: Book, all: ResolverDoc[]): ResolvedBook => resolveBookTree(b, scopeDocsToBook(b, all));
+
+/** What `GET /meta/book/:name/tree` answers: the spec resolver over every doc, scoped by the book's package. */
+const endpointTree = (b: Book, all: ResolverDoc[]) =>
+  specResolveBookTree({ name: b.name, label: b.label, groups: b.groups ?? [] }, all, b.packageId);
+
+/** The authored groups only, as `key → [doc…]`. */
+const authored = (groups: { key: string; entries: { doc?: string }[] }[]) =>
+  groups.filter((g) => g.key !== 'uncategorized').map((g) => ({ key: g.key, docs: g.entries.map((e) => e.doc) }));
+
+const members = (r: ResolvedBook, key: string) => r.groups.find((g) => g.key === key)?.entries.map((e) => e.doc);
+
+describe('objectui#11245 — explicit `group` placement survives the book package scope', () => {
+  it('a doc outside the book\'s package that names one of its groups is listed in that group', () => {
+    expect(members(portalTree(book, docs), 'reference')).toEqual(['live_guide', 'probe_curl']);
+  });
+
+  it('the authored groups equal the tree endpoint\'s answer for the same docs', () => {
+    expect(authored(portalTree(book, docs).groups)).toEqual(authored(endpointTree(book, docs).groups));
+  });
+
+  it('countBookDocs counts the explicit members', () => {
+    expect(countBookDocs(book, docs)).toBe(3); // docprobe_gs_welcome + live_guide + probe_curl
+  });
+
+  it('control: another package\'s ungrouped doc, and one naming a key the book lacks, stay out of Uncategorized', () => {
+    const tree = portalTree(book, docs);
+    const everywhere = tree.groups.flatMap((g) => g.entries.map((e) => e.doc));
+    expect(everywhere).not.toContain('other_note');
+    expect(everywhere).not.toContain('other_stray');
+    expect(tree.groups.some((g) => g.synthetic)).toBe(false);
+  });
+
+  it('a group-level `package` override scopes that group\'s `include`, and the explicit member still joins it', () => {
+    const scoped: Book = {
+      name: 'a_manual',
+      label: 'A Manual',
+      packageId: 'a',
+      groups: [
+        { key: 'own', label: 'Own', order: 1, include: '*' },
+        { key: 'ext', label: 'Ext', order: 2, include: '*', package: 'b' },
+      ],
+    };
+    const mixed: ResolverDoc[] = [
+      { name: 'a_1', packageId: 'a' },
+      { name: 'b_1', packageId: 'b' },
+      { name: 'c_1', packageId: 'c', group: 'ext' },
+      { name: 'c_2', packageId: 'c' },
+    ];
+    const tree = portalTree(scoped, mixed);
+    // The override REPLACES the book's scope for `ext`: `own` takes only package a,
+    // `ext` only package b by `include`, and c_1 by its own `group`.
+    expect(members(tree, 'own')).toEqual(['a_1']);
+    expect(members(tree, 'ext')).toEqual(['b_1', 'c_1']);
+    expect(authored(tree.groups)).toEqual(authored(endpointTree(scoped, mixed).groups));
+    // c_2 (package c, no `group`) stays out, as other packages' ungrouped docs do.
+    expect(tree.groups.flatMap((g) => g.entries.map((e) => e.doc))).not.toContain('c_2');
+  });
+});
@@ -313,11 +313,20 @@ function bookPackages(book: Book): Set<string> {
  * up every other package's docs. When a book declares no package (its own or a
  * group override) we can't scope safely, so all docs are kept and membership
  * falls to each group's `include` glob.
+ *
+ * A doc whose own `group` names one of this book's group keys is kept whatever
+ * its package (objectui#11245): the framework's `resolveBookTree` places a doc
+ * by its explicit `group` with no package scope, and the book tree endpoint
+ * answers that resolver, so the sidebar lists the doc where the endpoint does.
+ * The package filter narrows only what `include` and the synthetic
+ * Uncategorized group can collect; `include` stays scoped by the resolver
+ * itself (`group.package`, else the book's package).
  */
 export function scopeDocsToBook(book: Book, docs: ResolverDoc[]): ResolverDoc[] {
   const pkgs = bookPackages(book);
   if (pkgs.size === 0) return docs;
-  return docs.filter((d) => pkgs.has(pkgOf(d)));
+  const groupKeys = new Set((book.groups ?? []).map((g) => g.key));
+  return docs.filter((d) => pkgs.has(pkgOf(d)) || (d.group != null && groupKeys.has(d.group)));
 }
 
 /** Sort books for the index: by `order`, then label, then name (stable). */
 
@@ -0,0 +1,142 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#11245 — the rendered book sidebar, through the REAL route table
+ * (DocsLayout → DocsSlug / DocPage → BookSidebar), lists a doc that names one of
+ * the book's groups through its own `group` key from outside the book's package.
+ *
+ * The world is the card's probe: book `docprobe_manual` (package
+ * `com.example.docprobe`) with a "Getting started" and a "Reference" group, and a
+ * doc `live_guide` saved from the doc editor with `group: 'reference'` into it —
+ * a runtime row, not the book's package. `GET /meta/book/docprobe_manual/tree`
+ * lists it under Reference; the sidebar now does too. The book landing opens a
+ * book whose only member is placed that way. Another package's ungrouped doc
+ * stays out of the sidebar (the control).
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, screen, cleanup, within } from '@testing-library/react';
+import { MemoryRouter, Routes, Route, useLocation } from 'react-router-dom';
+
+const { ADAPTER } = vi.hoisted(() => {
+  const PKG = 'com.example.docprobe';
+  const DOCS = [
+    { name: 'docprobe_gs_welcome', label: 'Welcome', _packageId: PKG },
+    { name: 'live_guide', label: 'Live Guide', group: 'reference', _packageId: 'sys_metadata' },
+    { name: 'other_note', label: 'Other Note', _packageId: 'com.example.other' },
+    { name: 'live_note', label: 'Live Note', group: 'notes', _packageId: 'sys_metadata' },
+  ];
+  const BOOKS = [
+    { name: 'docprobe_manual', label: 'Probe Manual', _packageId: PKG,
+      groups: [
+        { key: 'start', label: 'Getting started', order: 1, include: 'docprobe_gs_*' },
+        { key: 'reference', label: 'Reference', order: 2 },
+      ] },
+    // A book whose ONLY member is placed by its own `group` from another package.
+    { name: 'notes_manual', label: 'Notes', _packageId: 'com.example.notes',
+      groups: [{ key: 'notes', label: 'Notes' }] },
+  ];
+  const CONTENT: Record<string, string> = {
+    docprobe_gs_welcome: 'WELCOME BODY',
+    live_guide: 'LIVE BODY',
+    other_note: 'OTHER BODY',
+    live_note: 'NOTE BODY',
+  };
+  const ADAPTER = {
+    getClient: () => ({
+      meta: {
+        getItems: async (type: string) => (type === 'doc' ? DOCS : type === 'book' ? BOOKS : []),
+        getItem: async (_type: string, name: string) => ({ item: { name, content: CONTENT[name] } }),
+      },
+    }),
+  };
+  return { ADAPTER };
+});
+
+vi.mock('@object-ui/app-shell', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useAdapter: () => ADAPTER,
+}));
+
+vi.mock('@object-ui/plugin-markdown', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  MarkdownRenderer: ({ schema }: { schema: { content?: string } }) => (
+    <div data-testid="doc-content">{schema.content}</div>
+  ),
+  extractToc: () => [],
+}));
+
+vi.mock('@object-ui/i18n', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useObjectTranslation: () => ({ t: (_k: string, o?: { defaultValue?: string }) => o?.defaultValue ?? _k }),
+}));
+
+// Imported AFTER the mocks so the pages pick up the mocked modules.
+import DocsLayout from './DocsLayout';
+import DocsSlug from './DocsSlug';
+import DocPage from './DocPage';
+
+function Where() {
+  return <div data-testid="where">{useLocation().pathname}</div>;
+}
+
+function Portal({ entry }: { entry: string }) {
+  return (
+    <MemoryRouter initialEntries={[entry]}>
+      <Where />
+      <Routes>
+        <Route path="/docs" element={<DocsLayout />}>
+          <Route path=":slug" element={<DocsSlug />} />
+          <Route path=":slug/:name" element={<DocPage />} />
+        </Route>
+      </Routes>
+    </MemoryRouter>
+  );
+}
+
+/** Each rendered copy of a sidebar group (wide nav + narrow disclosure), by its label. */
+const sidebarGroups = async (label: string) =>
+  (await screen.findAllByText(label)).map((el) => el.parentElement as HTMLElement);
+
+afterEach(cleanup);
+
+describe('objectui#11245 — the book sidebar lists a doc placed by its own `group` from another package', () => {
+  it('reading another page of the book, the Reference group links the placed doc', async () => {
+    render(<Portal entry="/docs/docprobe_manual/docprobe_gs_welcome" />);
+    expect(await screen.findByTestId('doc-content')).toHaveTextContent('WELCOME BODY');
+    const groups = await sidebarGroups('Reference');
+    expect(groups.length).toBeGreaterThanOrEqual(1);
+    for (const group of groups) {
+      const link = within(group).getByRole('link', { name: 'Live Guide' });
+      expect(link).toHaveAttribute('href', '/docs/docprobe_manual/live_guide');
+    }
+  });
+
+  it('reading the placed doc, the sidebar marks it current inside its group', async () => {
+    render(<Portal entry="/docs/docprobe_manual/live_guide" />);
+    expect(await screen.findByTestId('doc-content')).toHaveTextContent('LIVE BODY');
+    for (const group of await sidebarGroups('Reference')) {
+      expect(within(group).getByRole('link', { name: 'Live Guide' })).toHaveAttribute('aria-current', 'page');
+    }
+  });
+
+  it('a book whose only member is placed that way opens to it, not to "no documents yet"', async () => {
+    render(<Portal entry="/docs/notes_manual" />);
+    expect(await screen.findByTestId('doc-content')).toHaveTextContent('NOTE BODY');
+    expect(screen.getByTestId('where').textContent).toBe('/docs/notes_manual/live_note');
+  });
+
+  it('control: another package\'s ungrouped doc stays out of the sidebar (no Uncategorized)', async () => {
+    render(<Portal entry="/docs/docprobe_manual/docprobe_gs_welcome" />);
+    expect(await screen.findByTestId('doc-content')).toHaveTextContent('WELCOME BODY');
+    await sidebarGroups('Getting started'); // the sidebar has rendered
+    expect(screen.queryAllByRole('link', { name: 'Other Note' })).toEqual([]);
+    expect(screen.queryAllByText('Uncategorized')).toEqual([]);
+  });
+});