docs(cli): state the package-docs search as the any-depth rule it is (#21013)

Fixes #19525
Clause-②: no

## What changed

Docs only: `content/docs/deployment/cli.mdx`, the ADR-0130 paragraph
under `os compile` (one paragraph; no code, no
`content/docs/releases/**`, no governed surface).

The paragraph described per-package docs collection as `src/PKG/docs/`,
one level under `src/`. Since PR #19492 (`0e671d20`) the collector finds
each package's directory from the packages the artifact registers, at
any depth. No sentence on the page was false; it was narrower than the
rule. The rewrite:

- keeps verbatim the two sentences that still hold: the `id` /
last-dot-segment matching, and the display `name` not being a directory
key;
- states the depth rule (`src/PKG/docs/` and `src/packages/PKG/docs/`
are one case);
- states where the search stops: it descends through directories that
name no declared package (never into `node_modules`) and stops at the
first one that names any of them. Everything under that root is the
package's own source, so a deeper `src/PKG/components/docs/` is neither
read nor reported;
- states the no-`packages[]` case: nothing to search for, so docs are
read from `src/docs/` alone and a one-level `src/DIR/docs/` is reported,
not read;
- restates what the warning now means, as three cases: a directory
naming none of the packages (an intermediate one such as `src/packages/`
included), a directory naming more than one, and the new refusal of one
package that answers to more than one docs directory (neither is read;
each warning names the others).

## Each behaviour against the source, not the card

Read at `origin/main` `a5bce40888`
(`packages/cli/src/utils/collect-docs.ts`), then measured.

| Page sentence | Source | Measured by |
|---|---|---|
| any depth; two-level layout collected | `packageDirectoryCandidates`
docblock: "derived from the packages the artifact REGISTERS rather than
from a fixed depth under `src/`"; `walk` recurses only into a directory
with no owners, and only when the artifact declares packages | test
"collects the ADR-0130 D4 two-level layout…"; probe P2
(`src/a/b/orders/docs` collected) |
| never into `node_modules` | `entry.name !== 'node_modules'` on the
descent condition | probe P3 (`src/node_modules/orders/docs`: nothing
collected, no issue) |
| stops at the first directory naming any package; deeper `docs/`
neither read nor reported | descent requires `owners.length === 0` |
test "stops at the package root…" (`issues` is `[]`); probe P4 (an
ambiguous directory stops the search too) |
| no `packages[]` ⇒ one level, reported not read | no refs ⇒ no
recursion; the `refs.length === 0` branch emits `uncollectedDocsMessage`
| test "a stack with no packages[] gets the original sentence"; test
"single-package regression…"; probe P6 |
| `id` and its last dot segment, not `name` | `docsPackageRefs` | tests
"resolves a directory named by the id TAIL…", "the package `name` is not
a resolution spelling" |
| none ⇒ warning listing the declared packages, intermediate directories
included | `owners.length === 0` message: "Declared packages: …" | test
"a directory naming NO package keeps its own answer at the new depth";
probe P1 (`src/packages/docs` reported while `src/packages/orders/docs`
is collected) |
| more than one ⇒ warning naming those packages | message for a
directory with two or more owners | test "an AMBIGUOUS directory name
keeps its own answer at the new depth" |
| one package, more than one docs directory ⇒ neither read, each names
the others | `locationsOf` refusal in `sweepPackageDocsDirectories` |
test "ONE package answering to TWO docs directories is refused…"; probe
P5 (three directories, each warning lists the other two); control P7 (a
package directory without Markdown is not a second location) |

The probe was a one-off `tsx` script over `collectDocsFromSrc` against
temp trees, run from the built dependency closure. It is not committed.

## Verification, at head `32d0a0178c`

- `pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2
src/utils/collect-docs.package-docs.test.ts`: `Tests 40 passed (40)`
(code unchanged; this confirms the behaviours the page now states are
the ones the landed tests pin).
- `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
--commands` (no paths) derived 41 commands from the 1-path change set.
All 41 were run, and `--ran` answered `41 derived famil(ies) accounted
for — 41 run, 0 NOT-MEASURED`. They include `pnpm check:doc-authoring`
(exit 0), `pnpm check:docs-transcript-drift` (exit 0: "4 declared
transcript value(s) across 408 page(s)… equal what the registry derives
today"), `pnpm check:nul-bytes` (exit 0) and `pnpm --filter
@objectstack/spec run check:docs` (exit 0).
- `check:skill-examples` first exited 3 (PREREQUISITE NOT MET: no
`client-react` declarations). After building
`@objectstack/client-react...` and `@objectstack/client...` under the
verify lock it exited 0 ("259 prose examples type-check across 3
surface(s)").
- MDX compile of the page with `@mdx-js/mdx` 3.1.1: compiles at HEAD and
at base.
- NOT MEASURED locally: CI's `Build Docs` job (`ci.yml`), which this
path schedules. It is left to CI.

Changeset: none. `content/docs/**` ships in no package's `files[]`
(`apps/docs` is private), so the PR takes the `skip-changeset` label.

## Acceptance notes

- **Two rows of the card's table, corrected by measurement.** Row 3 says
"the warning is what happens when the search finds nothing". In fact
every directory the search passes through is a candidate in its own
right: `src/packages/docs/*.md` is reported even while
`src/packages/orders/docs/` is collected beneath it (probe P1). Row 4
merges two cases. A directory name matching more than one package (named
in the warning by package) is a different case from the new refusal of
one package answering to more than one directory (named in the warning
by directory). The page states both separately.
- **Silent by design, now stated on the page.** Markdown under a
resolved package's subtree, under `node_modules`, or under an ambiguous
directory's subtree is neither collected nor reported. With no
`packages[]`, a `docs/` two levels down is not reported either. This is
the ruled design (`packageDirectoryCandidates` property 1) and is pinned
by tests. The module header's "Absence" bullet ("Markdown under a
`DIR/docs/` that no registered package claims is … REPORTED") reads
wider than that; the function docblocks are exact. Comment precision
only, not filed. Carrier: none.
- `doc-pages.mdx`, `skills/objectstack-ui/rules/pages.md` and ADR-0046
are untouched: the card records them as a separate, older gap.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01JAhu8u8QfBvRjVZDox7CP9)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

content/docs/deployment/cli.mdx

@@ -627,17 +627,36 @@ The docs step reports what it collected, not what it attempted — a project who
 successful collection prints.
 
 Under an **ADR-0130 multi-package layout**, docs that moved into a package are
-collected too: a `src/<pkg>/docs/` directory whose `<pkg>` names one of the
+collected too: a `<pkg>/docs/` directory whose `<pkg>` names one of the
 artifact's declared `packages[]` entries is read into **that package's own
 body**, and the step line says so:
 `12 collected (4 from 2 package directories)`.
+The `<pkg>` directory is found from the packages the artifact registers, at
+**any depth** under `src/`: `src/<pkg>/docs/` and `src/packages/<pkg>/docs/`
+are one case, not two. The search descends through every directory whose name
+names none of the declared packages (never into `node_modules`) and **stops**
+at the first directory that names any of them. That directory is a package
+root and everything under it is that package's own source, so only its own
+`docs/` is read — a deeper `src/<pkg>/components/docs/` is neither read nor
+reported. A stack that declares no `packages[]` has nothing to search for: its
+docs are read from `src/docs/` alone, and a `src/<dir>/docs/` one level down
+is reported, not read.
 `<pkg>` is matched against two spellings of the package: its
 `id`, and the last dot-separated segment of that `id`. The display `name` is
 ⛔ not a directory key — it is free to be re-worded, and a docs binding a
-re-wording can break is worse than one that never existed. A directory
-that matches **none** of the declared packages, or **more than one**, is still
-not read — that case keeps the warning that names the files it skipped and the
-spellings it tried, so it is never a silent `0 collected`.
+re-wording can break is worse than one that never existed.
+Docs the search finds but cannot attribute unambiguously are still not read:
+each such `docs/` directory is reported in a warning that names the files it
+skipped, so it is never a silent `0 collected`. Three cases lead there:
+
+- a directory the search passes through, `src/packages/` itself included,
+  whose name matches **none** of the declared packages — the warning lists the
+  declared packages;
+- a directory whose name matches **more than one** declared package — the
+  warning names those packages;
+- one package that answers to **more than one** directory with Markdown in its
+  `docs/`, such as `src/core/docs/` beside `src/packages/core/docs/` — ⛔
+  neither is read and nothing is merged, and each warning names the others.
 
 The resulting `dist/objectstack.json` is a **portable, self-describing deployment unit** —
 you can hand it to `os start` (locally or on a server), publish it to a CDN, or fetch it