--- n: 3 title: Doc scope after 1.44.0: what is invisible, what was silently reassigned, and what to do abstract: Scope is a front-matter field on a project-wide doc, never a folder. Three gaps: the catalogue does not show scope, --all is undocumented, and 1.44.0's migration silently scoped every doc that carried provenance in track:. archived: old archived_at: 2026-09-16T00:06:43+00:00 status: final track: * source: the agent at: 2026-09-10T13:24:36+00:00 --- # Doc scope after 1.44.0 ## How it works today, established by reading the code **Scope is a field, not a folder.** Every doc lives in one project-wide directory — `docs_dir`, default `.journal/docs/` — whatever environment it belongs to. The scope is the `track:` line in its front matter, holding either an environment name or `*` (`docs.GLOBAL`). **That is deliberate and should not change.** `docs.py` states the reason: a rule binds every environment and may cite a doc, so a citation that stopped resolving outside one environment would make `--doc=N` a trap. Scope decides what is LISTED; it never decides what can be read. Putting a scoped doc inside `environments//` would make the location the scope, and then removing an environment — which now DELETES, since 1.46.0 — would take its docs with it. The refusal message already promises the opposite: "a doc scoped here becomes the project's, because an environment ending does not unmake what it settled." **Writing and moving both exist and both work.** journal docs add "" --abstract="<one line>" --brief scoped to the current environment journal docs add "<title>" --abstract="<one line>" --global --brief the project's journal docs move <n> "<environment>" give it to that one journal docs move <n> --global give it to the project ## Gap 1 — the catalogue never says which is which `journal docs` prints number, title, status, parts, files, age, abstract. It does not print scope. So the one command whose job is to show you the docs cannot answer "is this one the project's or this environment's?", and the only way to find out is `journal docs show <n>`, one doc at a time. `docs show` does print it, as "environment reminders" — but there is no evidence a GLOBAL doc prints anything at all there, which is the other half of the same gap: a reader cannot tell "global" from "the renderer said nothing". ## Gap 2 — `--all` is real and undocumented `catalogue()` takes `all_of_them` and `journal docs --all` reaches it, but `journal docs help` lists neither. Every other capped listing in this package advertises how to see the rest. A reader on `flags` who cannot see a doc has no way to learn that it exists on `leaks`. ## Gap 3 — 1.44.0 silently reassigned every doc that carried provenance THIS IS THE ONE THAT MATTERS. Before 1.44.0, `track:` recorded which line of work a doc came out of — provenance — and nothing filtered on it. 1.44.0 turned the same field into SCOPE and concluded the migration was nothing, because "a doc with no track at all is treated as global, which is what every doc written before this release has." That is false for any doc written by a version that filled the field in. Both docs in this project carry `track: reminders`, written 2026-09-09, and are therefore invisible on `flags`, `leaks` and `listings`. In `workflows` the same thing: 88 docs exist and `default`'s catalogue counts 85. Nothing was lost — every doc is still readable by number, which is exactly the property that makes this recoverable rather than a disaster. But a project's whole doc catalogue quietly narrowing to one environment is not what anyone asked for, and no check can see it, because the field is populated and valid either way. ## What to do Four rows follow, in the order they should be taken. Gap 3 first: it is the only one that has already changed what people can see.