From 2172bef613b560ee827d5ddada278cff61473e62 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 1 Oct 2026 01:22:06 +0000 Subject: [PATCH 1/2] docs(cli): state the package-docs search as the any-depth rule it is The ADR-0130 paragraph in deployment/cli.mdx described per-package docs collection as one level under src/. The collector now finds each package's directory from the packages the artifact registers, at any depth: restate the depth rule, where the search stops, the no-packages case, and the three cases that end in the uncollected-directory warning (none, more than one, and one package answering to more than one docs directory). Claude-Session: https://claude.ai/code/session_01JAhu8u8QfBvRjVZDox7CP9 Co-authored-by: Claude --- content/docs/deployment/cli.mdx | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/content/docs/deployment/cli.mdx b/content/docs/deployment/cli.mdx index cfe5065e059..765fd2108e3 100644 --- a/content/docs/deployment/cli.mdx +++ b/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//docs/` directory whose `` names one of the +collected too: a `/docs/` directory whose `` 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 `` directory is found from the packages the artifact registers, at +**any depth** under `src/`: `src//docs/` and `src/packages//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 one. That directory is the package's root +and everything under it is the package's own source, so only its own `docs/` +is read — a deeper `src//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//docs/` one level down is +reported, not read. `` 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 From 32d0a0178cc8836da7dabaa25a3194a7d8d37bc4 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 1 Oct 2026 01:24:59 +0000 Subject: [PATCH 2/2] docs(cli): an ambiguous directory also stops the package-docs search "stops at the first directory that names one" read as one package only; a directory naming two declared packages stops the search as well, so say "any of them". Reflow the paragraph. Claude-Session: https://claude.ai/code/session_01JAhu8u8QfBvRjVZDox7CP9 Co-authored-by: Claude --- content/docs/deployment/cli.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/docs/deployment/cli.mdx b/content/docs/deployment/cli.mdx index 765fd2108e3..a38ff94d32b 100644 --- a/content/docs/deployment/cli.mdx +++ b/content/docs/deployment/cli.mdx @@ -635,12 +635,12 @@ The `` directory is found from the packages the artifact registers, at **any depth** under `src/`: `src//docs/` and `src/packages//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 one. That directory is the package's root -and everything under it is the package's own source, so only its own `docs/` -is read — a deeper `src//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//docs/` one level down is -reported, not read. +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//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//docs/` one level down +is reported, not read. `` 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