@@ -0,0 +1,11 @@
+---
+'@object-ui/console': patch
+'@object-ui/i18n': patch
+---
+
+fix(console): a link inside an app's doc keeps the app shell, and the docs chrome reads the session language
+
+Clause-②: no
+Metadata-protocol: none
+
+A doc read inside an app (`/apps/APP/docs/BOOK/DOC`) rewrote its body cross-references to the portal's `/docs/NAME`, so following one left the app: no top bar, no app navigation. They now resolve under the app's own docs route, as the book sidebar already did, and the header's home link goes to the app's docs index. The header's "Documentation" label, the portal heading and the book sidebar's synthetic "Uncategorized" group title now read the new `help.documentation` and `help.uncategorized` keys, present in all ten locale packs; the group is titled by its key, and authored group labels keep the server's translation.
@@ -133,3 +133,66 @@ describe('a doc-to-doc link carries the router basename (objectui#12686)', () =>
     expect(screen.getByTestId('where').textContent).toBe('/docs/crm_manual/crm_lead_guide');
   });
 });
+
+/**
+ * objectstack#30554 — a doc read inside an app (`/apps/APP/docs/BOOK/DOC`,
+ * ADR-0048) resolves its body cross-references under that app's docs tree, so
+ * following one keeps the app shell. Before, the href was the portal's
+ * `/docs/NAME`, and a click left the app (no top bar, no app nav).
+ */
+const APP = 'app.example.crm';
+
+function renderAppDoc(basename: string) {
+  const prefix = basename === '/' ? '' : basename;
+  return render(
+    <MemoryRouter basename={basename} initialEntries={[`${prefix}/apps/${APP}/docs/crm_manual/crm_lead_guide`]}>
+      <Routes>
+        <Route path="/apps/:appName/docs/:slug/:name" element={<DocPage />} />
+        <Route path="/apps/:appName/docs/:slug" element={<div>landed in app</div>} />
+        <Route path="/docs/:name" element={<div>left the app</div>} />
+      </Routes>
+      <Link to={`/apps/${APP}/docs/crm_index`} data-testid="oracle">oracle</Link>
+      <Link to={`/docs/crm_index`} data-testid="portal">portal</Link>
+      <Where />
+    </MemoryRouter>,
+  );
+}
+
+describe("a doc-to-doc link in an app's doc stays in that app's docs route (objectstack#30554)", () => {
+  it("under `/_console`, the href is the app's docs route, basename included", async () => {
+    renderAppDoc('/_console');
+    const link = await screen.findByRole('link', { name: 'index' });
+    const oracle = screen.getByTestId('oracle').getAttribute('href');
+    expect(oracle).toBe(`/_console/apps/${APP}/docs/crm_index`);
+    expect(link.getAttribute('href')).toBe(oracle);
+    expect(link.getAttribute('href')).not.toBe(screen.getByTestId('portal').getAttribute('href'));
+    expect(screen.getByRole('link', { name: 'setup' }).getAttribute('href')).toBe(`${oracle}#setup`);
+  });
+
+  it('a plain left click navigates inside the app, never to the portal', async () => {
+    renderAppDoc('/_console');
+    const link = await screen.findByRole('link', { name: 'index' });
+    expect(fireEvent.click(link, { button: 0 })).toBe(false);
+    expect(await screen.findByText('landed in app')).toBeTruthy();
+    expect(screen.queryByText('left the app')).toBeNull();
+    expect(screen.getByTestId('where').textContent).toBe(`/apps/${APP}/docs/crm_index`);
+  });
+
+  it('on a root mount the href is `/apps/APP/docs/NAME`', async () => {
+    renderAppDoc('/');
+    const link = await screen.findByRole('link', { name: 'index' });
+    expect(link.getAttribute('href')).toBe(`/apps/${APP}/docs/crm_index`);
+  });
+
+  it("the header's home link is the app's docs index", async () => {
+    renderAppDoc('/_console');
+    await screen.findByRole('link', { name: 'index' });
+    expect(screen.getByRole('link', { name: 'Documentation' }).getAttribute('href')).toBe(`/_console/apps/${APP}/docs`);
+  });
+
+  it('CONTROL: outside an app the header home link is still the portal', async () => {
+    renderDoc('/_console');
+    await screen.findByRole('link', { name: 'index' });
+    expect(screen.getByRole('link', { name: 'Documentation' }).getAttribute('href')).toBe('/_console/docs');
+  });
+});
@@ -17,7 +17,7 @@ import { DocShell } from './DocShell';
 import { BookSidebar } from './BookSidebar';
 import { DocRefusal } from './BookPage';
 import { useBookData } from './use-book-data';
-import { resolveBookTree, bookSlug, bookNamedBy, type ResolvedBook } from './book-nav';
+import { resolveBookTree, bookSlug, bookNamedBy, labelUncategorized, type ResolvedBook } from './book-nav';
 
 interface DocItem {
   name: string;
@@ -47,10 +47,16 @@ export default function DocPage() {
   // the parent route's package-id segment under `/apps/:appName/docs/:slug/:name`.
   const { slug, name, appName } = useParams<{ slug?: string; name: string; appName?: string }>();
   const navigate = useNavigate();
-  // The docs route's href, router basename included (objectui#12686): the
+  // The docs route this page is read under: the app's own docs tree inside an
+  // app (ADR-0048), else the portal. Body cross-references resolve under it, so
+  // a link followed from an app's doc keeps the app shell (top bar, app nav),
+  // the same answer the book sidebar gives; the flat `<base>/<name>` segment
+  // redirects to the doc's in-book URL under that same base (DocsSlug).
+  const base = appName ? `/apps/${appName}/docs` : '/docs';
+  // That route's href, router basename included (objectui#12686): the
   // rewritten cross-references carry it so a new tab or a copied link reaches
   // the doc. `navigate` takes the bare router path and applies the basename.
-  const docsHref = useHref('/docs');
+  const docsHref = useHref(base);
   const adapter = useAdapter();
   const { t } = useObjectTranslation();
   const [doc, setDoc] = useState<DocItem | null>(null);
@@ -128,13 +134,13 @@ export default function DocPage() {
       if (!href) return;
       if (href.startsWith(`${docsHref}/`)) {
         e.preventDefault();
-        navigate(`/docs${href.slice(docsHref.length)}`);
+        navigate(`${base}${href.slice(docsHref.length)}`);
       } else if (href.startsWith('#')) {
         e.preventDefault();
         scrollToHeading(decodeURIComponent(href.slice(1)));
       }
     },
-    [docsHref, navigate, scrollToHeading],
+    [base, docsHref, navigate, scrollToHeading],
   );
 
   // ToC entries are bare `#id` anchors; scroll in JS for the same <base> reason.
@@ -159,13 +165,16 @@ export default function DocPage() {
   // the portal book set; degrades to no sidebar if the slug is unknown (e.g.
   // the backend serves no books yet).
   const { books, authoredBooks, docs: allDocs } = useBookData();
-  const base = appName ? `/apps/${appName}/docs` : '/docs';
+  // The synthetic catch-all group is titled in the session language, by its key.
+  const uncategorizedLabel = t('help.uncategorized', { defaultValue: 'Uncategorized' });
   const resolvedBook = useMemo<ResolvedBook | null>(() => {
     const book = books.find((b) => bookSlug(b) === slug);
     // Every authored book judges the Uncategorized group, so a doc a sibling
     // book places is not listed there (objectstack#27091).
-    return book ? resolveBookTree(book, allDocs, undefined, authoredBooks) : null;
-  }, [books, authoredBooks, allDocs, slug]);
+    return book
+      ? labelUncategorized(resolveBookTree(book, allDocs, undefined, authoredBooks), uncategorizedLabel)
+      : null;
+  }, [books, authoredBooks, allDocs, slug, uncategorizedLabel]);
   const docHref = useCallback((docName: string) => `${base}/${slug}/${docName}`, [base, slug]);
   // A `:slug` segment that is a book's NAME rather than its slug — what a
   // `{ type: 'doc', book, doc }` navigation entry links to (objectui#11197) — is
 
@@ -7,8 +7,9 @@
  */
 
 import type { ReactNode } from 'react';
-import { Link } from 'react-router-dom';
+import { Link, useParams } from 'react-router-dom';
 import { BookOpen } from 'lucide-react';
+import { useObjectTranslation } from '@object-ui/i18n';
 
 /**
  * Lightweight chrome for the package-documentation routes (ADR-0046).
@@ -18,18 +19,26 @@ import { BookOpen } from 'lucide-react';
  * "Documentation" home link (→ `/docs`) plus an optional breadcrumb — so a
  * reader always knows where they are and has a way back, without pulling in
  * the full app shell (which ADR-0046 deliberately keeps out of v1).
+ *
+ * Under an app (`/apps/:appName/docs/...`, ADR-0048) the home link is that
+ * app's docs index, so it keeps the reader inside the app shell, the same
+ * answer the sidebar and the body cross-references give. The label reads the
+ * session language (`help.documentation`).
  */
 export function DocShell({ breadcrumb, children }: { breadcrumb?: string; children: ReactNode }) {
+  const { appName } = useParams<{ appName?: string }>();
+  const { t } = useObjectTranslation();
+  const home = appName ? `/apps/${appName}/docs` : '/docs';
   return (
     <div className="min-h-full">
       <header className="sticky top-0 z-10 border-b border-border bg-background/80 backdrop-blur supports-[backdrop-filter]:bg-background/60">
         <div className="mx-auto flex max-w-3xl items-center gap-2 px-4 py-3 sm:px-6">
           <Link
-            to="/docs"
+            to={home}
             className="flex items-center gap-2 text-sm font-semibold hover:opacity-80"
           >
             <BookOpen className="h-4 w-4 text-muted-foreground" />
-            <span>Documentation</span>
+            <span>{t('help.documentation', { defaultValue: 'Documentation' })}</span>
           </Link>
           {breadcrumb ? (
             <>
 
@@ -52,7 +52,7 @@ export default function DocsIndex() {
     <DocShell>
       <div className="mx-auto max-w-4xl p-4 sm:p-6">
         <header className="mb-6">
-          <h1 className="text-2xl font-bold tracking-tight">Documentation</h1>
+          <h1 className="text-2xl font-bold tracking-tight">{t('help.documentation', { defaultValue: 'Documentation' })}</h1>
           <p className="mt-1 text-sm text-muted-foreground">
             Books and guides from your installed packages.
           </p>
 
@@ -109,8 +109,29 @@ export interface ResolvedBook {
   groups: ResolvedGroup[];
 }
 
+/**
+ * The key of the synthetic Uncategorized group. Its `label` is the framework's
+ * English default (the spec's `resolveBookTree` answers the same); a reader
+ * names the group in the session language by this key, never by the label
+ * (see {@link labelUncategorized}).
+ */
 const UNCATEGORIZED_KEY = 'uncategorized';
 
+/**
+ * The resolved book with its synthetic Uncategorized group titled `label` —
+ * the reader's own word for it. Authored groups keep their served labels,
+ * which the server already answers in the request locale; an authored group
+ * that happens to use the key `uncategorized` is not synthetic and is left
+ * as authored.
+ */
+export function labelUncategorized(book: ResolvedBook, label: string): ResolvedBook {
+  if (!book.groups.some((g) => g.synthetic && g.key === UNCATEGORIZED_KEY)) return book;
+  return {
+    ...book,
+    groups: book.groups.map((g) => (g.synthetic && g.key === UNCATEGORIZED_KEY ? { ...g, label } : g)),
+  };
+}
+
 /** The namespace prefix of a metadata name (everything before the first `_`). */
 export function namePrefix(name: string): string {
   const i = name.indexOf('_');
 
@@ -18,11 +18,18 @@
  * the authored book run through the spec's own translator with a translation
  * bundle, for the locale the "request" carries. So the chain pinned here is
  * bundle → served book → sidebar, with nothing hand-translated in between.
+ *
+ * objectstack#30554 adds the console's own words in that chrome: the header's
+ * "Documentation" home link and the synthetic Uncategorized group (which no
+ * bundle carries; the console titles it by its key). Those pins mount a real
+ * `I18nProvider` and read their expectations from the locale packs.
  */
 
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import { render, screen, cleanup, within } from '@testing-library/react';
 import { MemoryRouter, Routes, Route } from 'react-router-dom';
+import { I18nProvider } from '@object-ui/i18n';
+import { builtInLocales } from '@object-ui/i18n/locales';
 // Paid at collection, not inside the adapter's clocked `getItems` call.
 import '@objectstack/spec/system';
 import type { TranslationBundle } from '@objectstack/spec/system';
@@ -32,6 +39,8 @@ const { ADAPTER, REQUEST } = vi.hoisted(() => {
   const DOCS = [
     { name: 'crm_start_login', label: 'Signing in', _packageId: 'com.example.crm', order: 1 },
     { name: 'crm_pipe_stages', label: 'Stages', _packageId: 'com.example.crm', order: 2 },
+    // Claimed by no group: the book's Uncategorized catch-all lists it.
+    { name: 'crm_loose_note', label: 'Loose note', _packageId: 'com.example.crm', order: 3 },
   ];
   const BOOK = {
     name: 'crm_manual',
@@ -79,18 +88,13 @@ vi.mock('@object-ui/plugin-markdown', async (importOriginal) => ({
   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 Portal({ entry }: { entry: string }) {
-  return (
+function Portal({ entry, language }: { entry: string; language?: string }) {
+  const routed = (
     <MemoryRouter initialEntries={[entry]}>
       <Routes>
         <Route path="/apps/:appName/docs" element={<DocsLayout />}>
@@ -100,6 +104,13 @@ function Portal({ entry }: { entry: string }) {
       </Routes>
     </MemoryRouter>
   );
+  return language ? (
+    <I18nProvider config={{ defaultLanguage: language, detectBrowserLanguage: false }} persistLanguage={false}>
+      {routed}
+    </I18nProvider>
+  ) : (
+    routed
+  );
 }
 
 /**
@@ -140,3 +151,33 @@ describe('objectstack#26690 — the docs sidebar serves the request locale', ()
     }
   });
 });
+
+describe("objectstack#30554 — the docs chrome's own words follow the session language", () => {
+  const ENTRY = '/apps/com.example.crm/docs/manual/crm_start_login';
+
+  for (const language of ['zh', 'ja', 'es'] as const) {
+    it(`a ${language} reader sees the home link and the Uncategorized title in ${language}`, async () => {
+      const pack = builtInLocales[language].help;
+      // Guard: the expectations are real translations, not the English words.
+      expect(pack.documentation).not.toBe('Documentation');
+      expect(pack.uncategorized).not.toBe('Uncategorized');
+      render(<Portal entry={ENTRY} language={language} />);
+      const navs = await sidebars('User Manual');
+      for (const nav of navs) {
+        expect(within(nav).getByText(pack.uncategorized)).toBeInTheDocument();
+        expect(within(nav).queryByText('Uncategorized')).toBeNull();
+        expect(within(nav).getByText('Loose note')).toBeInTheDocument();
+      }
+      const home = screen.getByRole('link', { name: pack.documentation });
+      expect(home.getAttribute('href')).toBe('/apps/com.example.crm/docs');
+      expect(screen.queryByText('Documentation')).toBeNull();
+    });
+  }
+
+  it('CONTROL: with no provider the chrome reads its English', async () => {
+    render(<Portal entry={ENTRY} />);
+    const navs = await sidebars('User Manual');
+    for (const nav of navs) expect(within(nav).getByText('Uncategorized')).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'Documentation' }).getAttribute('href')).toBe('/apps/com.example.crm/docs');
+  });
+});
@@ -3355,6 +3355,8 @@ const ar = {
     allDocs: 'كل الوثائق',
     onlineDocs: 'الوثائق عبر الإنترنت',
     loadingDocumentation: 'جارٍ تحميل الوثائق',
+    documentation: 'الوثائق',
+    uncategorized: 'غير مصنف',
     about: 'حول',
     aboutTitle: 'حول وحدة التحكم هذه',
     aboutDescription: 'الإصدار الذي بُنيت منه وحدة التحكم هذه.',
 
@@ -3101,6 +3101,8 @@ const de = {
     allDocs: 'Gesamte Dokumentation',
     onlineDocs: 'Online-Dokumentation',
     loadingDocumentation: 'Dokumentation wird geladen',
+    documentation: 'Dokumentation',
+    uncategorized: 'Nicht kategorisiert',
     about: 'Über',
     aboutTitle: 'Über diese Konsole',
     aboutDescription: 'Der Build, aus dem diese Konsole kompiliert wurde.',
 
@@ -3701,6 +3701,8 @@ const en = {
     keyboardShortcuts: 'Keyboard shortcuts',
     onlineDocs: 'Online documentation',
     loadingDocumentation: 'Loading documentation',
+    documentation: 'Documentation',
+    uncategorized: 'Uncategorized',
     about: 'About',
     aboutTitle: 'About this console',
     aboutDescription: 'The build this console was compiled from.',