fix(console): authored books lead the index; humanize implicit book labels

Browser-verified against the framework showcase backend. Two polish fixes
found there:

- buildPortalBooks now returns authored books (in their `order`) ahead of
  the synthetic per-package books, and buildBookCards preserves that order
  instead of re-sorting — so a book with an explicit `order: 0` (e.g. the
  showcase manual) is no longer pushed below a fallback implicit book.
- Implicit per-package books label themselves with the humanized package id
  ("com.objectstack.setup" → "Setup") rather than the raw id; the slug/name
  stay the full id so they remain unique and reversible.

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

Author: os-zhuang

apps/console/src/pages/book-nav.test.ts

@@ -138,6 +138,11 @@ describe('buildPortalBooks (ADR-0046 §6.4 — no flat/book fork)', () => {
     expect(portal.map((b) => b.name)).toContain('misc'); // implicit book keyed by packageId
     // no duplicate implicit 'crm' book, since crm_manual already owns 'crm'
     expect(portal.filter((b) => b.name === 'crm').length).toBe(0);
+    // authored books lead, implicit ones follow
+    expect(portal[0].name).toBe('crm_manual');
+    expect(portal[portal.length - 1].name).toBe('misc');
+    // implicit label is humanized, not the raw package id
+    expect(portal.find((b) => b.name === 'misc')?.label).toBe('Misc');
   });
 
   it('with no authored books, every package becomes its own implicit book', () => {

apps/console/src/pages/book-nav.ts

@@ -323,9 +323,14 @@ export function countBookDocs(book: Book, docs: ResolverDoc[]): number {
   return seen.size;
 }
 
-/** Build the index cards for the portal landing, in display order. */
+/**
+ * Build the index cards for the portal landing. Input order is preserved —
+ * callers pass {@link buildPortalBooks} output, which already orders authored
+ * books (by `order`) ahead of the synthetic per-package ones; re-sorting here
+ * would undo that.
+ */
 export function buildBookCards(books: Book[], docs: ResolverDoc[]): BookCard[] {
-  return sortBooks(books).map((b) => ({
+  return books.map((b) => ({
     name: b.name,
     slug: bookSlug(b),
     label: b.label ?? b.name,
@@ -348,8 +353,20 @@ export function buildPortalBooks(authored: Book[], docs: ResolverDoc[]): Book[]
   const docPkgs = new Set(docs.map(pkgOf));
   const implicit: Book[] = [...docPkgs]
     .filter((p) => !ownPkgs.has(p))
-    .map((p) => ({ ...deriveImplicitPackageBook(p), packageId: p }));
-  return sortBooks([...authored, ...implicit]);
+    // Humanize the package id for the visible label (the slug/name stays the
+    // full id so it remains unique and reversible); keep the group as the
+    // generic "Documentation".
+    .map((p) => ({ ...deriveImplicitPackageBook(p), label: humanizePackageId(p), packageId: p }));
+  // Authored books lead (curated, primary) in their own order; the synthetic
+  // per-package books follow, alphabetically — so an authored book with an
+  // explicit `order` is never pushed below a fallback.
+  return [...sortBooks(authored), ...sortBooks(implicit)];
+}
+
+/** "com.objectstack.setup" → "Setup" — a readable label for an implicit book. */
+function humanizePackageId(pkg: string): string {
+  const seg = pkg.split('.').pop() || pkg;
+  return seg.charAt(0).toUpperCase() + seg.slice(1);
 }
 
 /**

apps/console/src/pages/docs-portal.test.tsx

@@ -126,9 +126,9 @@ describe('book-driven docs portal (integration)', () => {
   it('clicking a book card navigates to its landing (real router flow)', async () => {
     render(<Harness entry="/docs" />);
     fireEvent.click(await screen.findByRole('link', { name: /ops/i }));
-    // Now on /docs/ops — the ops book landing renders, headed by the book, with
-    // its doc reachable (in both the sidebar and the overview list).
-    expect(await screen.findByRole('heading', { name: 'ops' })).toBeInTheDocument();
+    // Now on /docs/ops — the ops book landing renders, headed by the book
+    // (its label is the humanized package id, "Ops"), with its doc reachable.
+    expect(await screen.findByRole('heading', { name: /ops/i })).toBeInTheDocument();
     const setupLinks = screen.getAllByRole('link', { name: 'Setup' });
     expect(setupLinks.some((a) => a.getAttribute('href') === '/docs/ops/ops_setup')).toBe(true);
   });