@@ -0,0 +1,18 @@
+---
+'@objectstack/cli': patch
+---
+
+fix(cli)!: `docs/nav-target` judges the apps a package body carries on a multi-package artifact
+
+Clause-②: yes (narrowing) — on a multi-package `composeStacks(…, { manifest: 'preserve' })` artifact, a `type: 'doc'` navigation item inside an app a package body carries, whose `doc` or `book` names nothing the artifact carries, built clean before and is now refused by `os build`, `os validate` and `os lint` (`docs/nav-target`).
+Metadata-protocol: none
+
+<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed, renamed or re-shaped, and no export or type of the package's public surface changes: the build-time docs lint now reaches the apps a package body carries, judging them by the rule it already applies to a stack's own apps. A refused nav item is fixed in the app's navigation; there is nothing for a migration to rewrite. -->
+
+**BREAKING** accept-set narrowing in the build-time docs lint (`os build`, `os validate`, `os lint`).
+
+- **Before.** The `docs/nav-target` check walked only the artifact's top-level `apps`. A multi-package `preserve` artifact keeps its apps inside the package bodies and has none at its top level, so a nav item in a package's app was never judged: a dead `doc` or `book` target built clean and degraded at runtime.
+- **Now.** The check walks the top level's apps when the stack carries the key, otherwise each package body's, the same rule `resolveStackCollection` applies. A package app's `doc` item resolves against every doc the artifact carries, and its `book` item against the declared books and package ids, as a single-package app's always did.
+- **Unchanged.** A stack with no `packages[]`, and any stack whose top level carries `apps`, is judged exactly as before.
+
+**The remedy.** For a refused item, name a doc in `src/docs/*.md` or a declared book (a package id is its own implicit book), or remove the item. The refusal message names the nearest match.
@@ -15,6 +15,7 @@ import { describe, it, expect, afterEach } from 'vitest';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { composeStacks, defineStack } from '@objectstack/spec';
 import { collectAndLintDocs, lintDocNavTargets } from './collect-docs.js';
 
 const app = (navigation: unknown[]) => ({ name: 'crm_app', label: 'CRM', navigation });
@@ -88,6 +89,21 @@ describe('docs/nav-target — a doc nav item must open something this package ha
     expect(issues.map((i) => i.path)).toEqual(['apps/setup/navigation/nav_crm_help']);
   });
 
+  it('judges an app a package body carries on a multi-package `preserve` artifact', () => {
+    // The real composer: a `preserve` artifact keeps `apps` in the package body, not at its top level.
+    const composed = (doc: string) => JSON.parse(JSON.stringify(composeStacks([
+      defineStack({ manifest: { id: 'com.example.svc', name: 'svc', namespace: 'svc', version: '1.0.0', type: 'app' } } as never, { strict: false }),
+      defineStack({
+        manifest: { id: 'com.example.crm', name: 'crm', namespace: 'crm', version: '1.0.0', type: 'app' },
+        apps: [app([{ id: 'nav_page', type: 'doc', label: 'Guide', doc }])],
+      } as never, { strict: false }),
+    ], { manifest: 'preserve' }))) as Record<string, unknown>;
+    expect(composed('crm_lead_guide').apps).toBeUndefined();
+    expect(lintDocNavTargets(composed('crm_lead_guide'), DOCS)).toEqual([]);
+    const issues = lintDocNavTargets(composed('crm_lead_gide'), DOCS);
+    expect(issues.map((i) => [i.rule, i.path])).toEqual([['docs/nav-target', 'apps/crm_app/navigation/nav_page']]);
+  });
+
   it('resolves a book declared on a package body, and that package id as its implicit book', () => {
     expect(lintDocNavTargets({
       packages: [{ manifest: { id: 'com.example.help', books: [{ name: 'help_centre', groups: [] }] } }],
 
@@ -1109,7 +1109,8 @@ export function lintMetadataEmbeds(
  * judged here so one nav item is judged in one place.
  *
  * Walked: every app's `navigation` and `areas[].navigation` (children
- * included), and the items of `manifest.navigationContributions`.
+ * included) — the top level's apps, or each package body's when the top level
+ * carries none — and the items of `manifest.navigationContributions`.
  *
  * ## What resolves
  *
@@ -1175,7 +1176,13 @@ export function lintDocNavTargets(stack: Record<string, unknown>, docNames: Read
     }
   };
 
-  const apps = Array.isArray(stack.apps) ? (stack.apps as AnyRec[]) : [];
+  // A multi-package `preserve` artifact carries its apps in the package bodies
+  // and none at its top level. The top level's apps when it carries the key,
+  // otherwise each body's: `resolveStackCollection`'s rule, over the same
+  // `artifactPackages` walk as the books above, which refuses no entry shape.
+  const apps = (Array.isArray(stack.apps)
+    ? stack.apps
+    : artifactPackages(stack).flatMap(({ body }) => (Array.isArray(body.apps) ? body.apps : []))) as AnyRec[];
   for (const app of apps) {
     if (!app || typeof app !== 'object') continue;
     const appName = typeof app.name === 'string' ? app.name : '(unnamed)';
 
@@ -50,10 +50,10 @@
  * By file and by the chain of callees directly wrapping the identifier, never
  * by line or by count: `computeI18nCoverage(authoringRuleUnionStack(normalized`
  * names both the analysis and the fold it reads through. A grouping paren is
- * named by the member read off it: `(normalized).i18n`. Comments and string
- * bodies are blanked first, so prose and messages do not count; the bound that
- * buys is that a site inside a template literal's `${…}` is blanked too, and none
- * exists today. Test files are not scanned.
+ * named by the member read off it: `(normalized).i18n`. Comments, string
+ * bodies, template text and regex bodies are blanked first, so prose and
+ * messages do not count; a template literal's `${…}` is code and is scanned, at
+ * any depth. Test files are not scanned.
  */
 
 import { describe, expect, it } from 'vitest';
@@ -152,12 +152,46 @@ const KEYWORDS: ReadonlySet<string> = new Set([
   'new', 'do', 'else', 'yield', 'void', 'delete', 'in', 'of', 'as', 'async',
 ]);
 
-/** The source with comment bodies and string/template bodies blanked to spaces. */
+/** Words a `/` can follow and still open a regex literal rather than divide. */
+const REGEX_AFTER_WORD: ReadonlySet<string> = new Set([
+  'return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'throw', 'case', 'do', 'else', 'yield', 'await',
+]);
+
+/** Does the `/` at `at` open a regex literal? Judged by the last code character before it. */
+function regexMayStart(code: readonly string[], at: number): boolean {
+  let k = at - 1;
+  while (k >= 0 && /\s/.test(code[k])) k -= 1;
+  if (k < 0 || '(,=:[!&|?{};+-*%<>~^}'.includes(code[k])) return true;
+  const word = /[A-Za-z_$][\w$]*$/.exec(code.slice(Math.max(0, k - 16), k + 1).join(''));
+  return word !== null && REGEX_AFTER_WORD.has(word[0]);
+}
+
+/**
+ * The source with comment bodies, string bodies, template TEXT and regex
+ * literal bodies blanked to spaces; offsets, quotes and newlines kept.
+ *
+ * A template literal's `${…}` is code at any depth: `holes` holds one count per
+ * open `${` of the `{` opened inside it, so its own `}` hands back to the text,
+ * and a template, string or object literal inside it is masked as code would
+ * be. A `/` after an operator, an opening bracket or a keyword opens a regex
+ * literal (its character class may hold a `/`); anywhere else it divides.
+ */
 function codeOnly(src: string): string {
   const out = src.split('');
   const blank = (from: number, to: number) => {
     for (let k = from; k < to && k < src.length; k++) if (out[k] !== '\n') out[k] = ' ';
   };
+  const holes: number[] = [];
+  /** Blanks template text from `from`; the index past its closing backtick or its `${`. */
+  const templateText = (from: number): number => {
+    let j = from;
+    while (j < src.length && src[j] !== '`' && !(src[j] === '$' && src[j + 1] === '{')) j += src[j] === '\\' ? 2 : 1;
+    blank(from, j);
+    if (j >= src.length) return src.length;
+    if (src[j] === '`') return j + 1;
+    holes.push(0);
+    return j + 2;
+  };
   let i = 0;
   while (i < src.length) {
     const c = src[i];
@@ -172,11 +206,39 @@ function codeOnly(src: string): string {
       const end = j === -1 ? src.length : j + 2;
       blank(i, end);
       i = end;
-    } else if (c === "'" || c === '"' || c === '`') {
+    } else if (c === "'" || c === '"') {
       let j = i + 1;
       while (j < src.length && src[j] !== c) j += src[j] === '\\' ? 2 : 1;
       blank(i + 1, j);
       i = j + 1;
+    } else if (c === '`') {
+      i = templateText(i + 1);
+    } else if (c === '/' && regexMayStart(out, i)) {
+      let j = i + 1;
+      let inClass = false;
+      while (j < src.length && src[j] !== '\n' && (inClass || src[j] !== '/')) {
+        if (src[j] === '[') inClass = true;
+        else if (src[j] === ']') inClass = false;
+        j += src[j] === '\\' ? 2 : 1;
+      }
+      // No closing `/` on the line: not a regex after all, so read on as code.
+      if (src[j] === '/') {
+        blank(i + 1, j);
+        i = j + 1;
+      } else {
+        i += 1;
+      }
+    } else if (c === '{' && holes.length > 0) {
+      holes[holes.length - 1] += 1;
+      i += 1;
+    } else if (c === '}' && holes.length > 0) {
+      if (holes[holes.length - 1] === 0) {
+        holes.pop();
+        i = templateText(i + 1);
+      } else {
+        holes[holes.length - 1] -= 1;
+        i += 1;
+      }
     } else {
       i += 1;
     }
@@ -317,7 +379,8 @@ describe('the site scanner', () => {
 // A receiver holds a stack by its NAME: `config`, `stack`, `normalized`,
 // `bundle`, `cfg`, or any name ending in `Config`, `Stack` or `Bundle`. The
 // read forms are `R.key`, `R?.key`, `R!.key`, `(R as T).key` (a `T` without
-// parentheses) and `R['key']`. Comments and string bodies are blanked first.
+// parentheses) and `R['key']`. Comments, string bodies, template text and
+// regex bodies are blanked first; a template's `${…}` is code and is read.
 // An assignment target (`R.key = …`) is a write and is not a read.
 //
 // ⛔ Bounds, stated so they are not mistaken for coverage: a stack held under
@@ -424,7 +487,11 @@ const READS: Readonly<Record<string, ReadRow>> = {
   },
   'utils/collect-docs.ts :: stack.books': {
     reads: 'top-level',
-    why: '`lintDocNavTargets` resolves a nav item\'s `book` against the artifact\'s own top-level `books` AND each package body\'s (`addBooks(body.books)` over `artifactPackages(stack)`), so the top-level read is one half of the union on purpose (#27090 measured it: the read was there before, hidden from this census by `codeOnly` losing its place in a nested template literal).',
+    why: '`lintDocNavTargets` resolves a nav item\'s `book` against the artifact\'s own top-level `books` AND each package body\'s (`addBooks(body.books)` over `artifactPackages(stack)`), so the top-level read is one half of the union on purpose (#27090 measured it: the read was there before, hidden from this census by `codeOnly` losing its place; #27210 measured the cause there as a regex literal holding a quote).',
+  },
+  'utils/collect-docs.ts :: stack.apps': {
+    reads: 'top-level',
+    why: '`lintDocNavTargets` walks the top level\'s apps when it carries the key, otherwise each package body\'s (`artifactPackages(stack)`): `resolveStackCollection`\'s rule, over a walk that refuses no entry shape. Measured on a two-package `preserve` app in `collect-docs.nav-target.test.ts` (#27210: before, a body\'s app was never judged, and a nested template literal hid this read from the census).',
   },
   'utils/format.ts :: stack': {
     reads: 'resolved',
@@ -597,6 +664,27 @@ describe('the package-owned read scanner', () => {
     expect(packageOwnedReadsOf('// (config as any).requires\nconst s = \'config.requires\';\n', keys)).toEqual([]);
   });
 
+  it('keeps its place past a nested template literal and a regex literal (#27210)', () => {
+    // The did-you-mean shape `collect-docs.ts` carries: a template nested in another's `${…}`.
+    const nested = 'err(`unknown "${t}"${s ? ` — did you mean \\`${s}\\`?` : ` (expected ${x})`}.`);\n';
+    expect(packageOwnedReadsOf(`${nested}const o = stack.objects;\n`, keys)).toEqual(['stack.objects']);
+    // A `${…}` is code at any depth, braces and strings inside it included.
+    expect(packageOwnedReadsOf('const m = `${stack.flows.length} of ${ {a: \'}\'}.a } ${ `${config.requires}` }`;\n', keys))
+      .toEqual(['stack.flows', 'config.requires']);
+    // A quote or backtick inside a regex literal opens nothing; a division is not a regex.
+    expect(packageOwnedReadsOf('const v = l.replace(/^[\'"`]|[\'"]$/g, \'\'); const o = stack.objects;\n', keys))
+      .toEqual(['stack.objects']);
+    expect(packageOwnedReadsOf('const h = w / 2; const o = stack.objects; const q = h / 3;\n', keys))
+      .toEqual(['stack.objects']);
+    // A `${` in a quoted string opens no interpolation.
+    expect(packageOwnedReadsOf('const s = \'${\'; const o = stack.objects;\n', keys)).toEqual(['stack.objects']);
+  });
+
+  it('masks a nested template exactly: its text blanked, its interpolations kept', () => {
+    expect(codeOnly('`a ${ `b ${c}` } d`;')).toBe('`  ${ `  ${c}` }  `;');
+    expect(codeOnly('`${ {k: "}"} }x`; /[/`]/.test(y) / 2;')).toBe('`${ {k: " "} } `; /    /.test(y) / 2;');
+  });
+
   it('sees the reads where they are (positive control on the real tree)', () => {
     expect(scanPackageOwnedReads(packageOwnedCollectionKeys())).toEqual(expect.arrayContaining([
       'utils/format.ts :: stack.objects',
Original file line number	Diff line number	Diff line change
`@@ -1109,7 +1109,8 @@ export function lintMetadataEmbeds(`
`1109`	`1109`	`* judged here so one nav item is judged in one place.`
`1110`	`1110`	`*`
`1111`	`1111`	* Walked: every app's `navigation` and `areas[].navigation` (children
`1112`		- * included), and the items of `manifest.navigationContributions`.
	`1112`	`+ * included) — the top level's apps, or each package body's when the top level`
	`1113`	+ * carries none — and the items of `manifest.navigationContributions`.
`1113`	`1114`	`*`
`1114`	`1115`	`* ## What resolves`
`1115`	`1116`	`*`
`@@ -1175,7 +1176,13 @@ export function lintDocNavTargets(stack: Record<string, unknown>, docNames: Read`
`1175`	`1176`	`}`
`1176`	`1177`	`};`
`1177`	`1178`
`1178`		`- const apps = Array.isArray(stack.apps) ? (stack.apps as AnyRec[]) : [];`
	`1179`	+ // A multi-package `preserve` artifact carries its apps in the package bodies
	`1180`	`+ // and none at its top level. The top level's apps when it carries the key,`
	`1181`	+ // otherwise each body's: `resolveStackCollection`'s rule, over the same
	`1182`	+ // `artifactPackages` walk as the books above, which refuses no entry shape.
	`1183`	`+ const apps = (Array.isArray(stack.apps)`
	`1184`	`+ ? stack.apps`
	`1185`	`+ : artifactPackages(stack).flatMap(({ body }) => (Array.isArray(body.apps) ? body.apps : []))) as AnyRec[];`
`1179`	`1186`	`for (const app of apps) {`
`1180`	`1187`	`if (!app \|\| typeof app !== 'object') continue;`
`1181`	`1188`	`const appName = typeof app.name === 'string' ? app.name : '(unnamed)';`