Skip to content

docs: delete scope-doc text with no live producer - #3728

Merged
dr-bonez merged 2 commits into
masterfrom
docs/cruft-audit-monorepo-scope
Aug 19, 2026
Merged

docs: delete scope-doc text with no live producer#3728
dr-bonez merged 2 commits into
masterfrom
docs/cruft-audit-monorepo-scope

Conversation

@MattDHill

Copy link
Copy Markdown
Member

Phase 2 of the docs cruft audit: all 65 AGENTS.md / ARCHITECTURE.md / CONTRIBUTING.md files, at every scope, read end to end.

Same rule as the guide pass — a sentence citing what not to do, what not to include, or a mistake once made only earns its place if you can name the live producer. No producer, delete. 53 deletions across 29 files; 200 prohibitions and incident narrations examined and kept, each with a named producer.

Things that were simply wrong

These are the ones worth reading the diff for.

Doc Claim Reality
projects/start-registry/CONTRIBUTING.md Cargo version "tracks the OS release line — don't bump it independently" start-registry is 1.0.2, StartOS is 0.4.0.2. The crate's own AGENTS.md, one directory over, says the opposite. This is the retired rule stated as current.
projects/start-registry/AGENTS.md "(currently 1.0.0)" Already 1.0.2.
shared-libs/crates/rpc-toolkit/CONTRIBUTING.md "This crate ships a rustfmt.toml" It does not; only the repo root has one.
projects/start-sdk/AGENTS.md build table documents make dist Not a target in that Makefile. (start-core's make dist, referenced further down the same file, is real and stays.)
ARCHITECTURE.md apt/ under projects/start-os/ apt/ is at the repo root.
shared-libs/CONTRIBUTING.md ts-modules' "current contents are Angular libraries" It also holds the non-Angular start-core.
projects/start-registry/ARCHITECTURE.md "All five product binaries" Root AGENTS.md counts six.
projects/start-sdk/ARCHITECTURE.md AGENTS.md listed twice in Further reading.

Migration narration whose migration is over

Four separate stale-path notes mapped the pre-monorepo root layout (core/, web/, sdk/, patch-db/, container-runtime/). The root AGENTS.md keeps onecore/src/ is still referenced live in projects/start-os/DEV_TODO.md, so the mapping is still reachable, and one line is the maximum the still-encounterable rule allows. The copies in start-cli, container-runtime and shared-libs go, along with "Internally unchanged from the old core/ crate", the start-fs migration note, the retired submodule's workspace Cargo.toml, and the base/lib/... import shape.

Same treatment for the in-flight CONTRIBUTING.mdAGENTS.md migration: the rule for how to migrate stays in all three places it appears; the three tallies of which scopes have migrated go. A reader can determine that by looking, and the next scope to migrate silently falsifies a written count.

Counts and in-progress markers

~430 tests (twice), 11 modules (twice), ~28 utility modules, ~117-line, ~2200 lines, 3 small build-infra patches, the SDK/OS version pair, (currently by start-core), (currently just bitcoin-guides), (currently the Angular libs shared and marketplace) (twice), being replaced, being phased out, two notes recording which warnings a crate happened to emit, and a commented-out list of ten aspirational locales.

Plus "the standalone Start9Labs/patch-db repo is being retired" — worse than stale: gh api shows the repo unarchived and pushed to after that line was written, so a reader who checks cannot tell whether the doc is wrong or the retirement stalled.

Kept against the extraction pass's recommendation

Each of these was flagged for deletion and I disagreed; producer named.

  • projects/start-wrt/web/CONTRIBUTING.md — the taiga-ui-mcp entry. Flagged as a beta tool. It is one of the three sanctioned ways to verify a Taiga API in the frontend workflow; deleting it would contradict live guidance.
  • projects/brochure-marketplace/AGENTS.md — "Don't add a parallel state store." The pass found no copyable neighbour, which is true, but the producer here is the obvious-but-wrong fix: an agent adding a feature that needs registry state stands up its own service instead of extending MarketplaceService. The preceding sentences say where state lives; they do not forbid adding a second one.
  • shared-libs/crates/jsonpath/AGENTS.md — "Do not add new FFI here." src/ffi/mod.rs is a working exported C ABI and lua/jsonpath.lua dlopens it in-tree. That is a neighbouring example, literally.
  • projects/start-registry/AGENTS.md — "no longer tied to the StartOS release line." The shared # VERSION_BUMP marker sits on this crate exactly as on the OS-coupled ones, and VERSION_BUMP.md is titled the StartOS version bump guide, so the wrong inference is one glance away.
  • Root AGENTS.md — the stale-path watch, and root CONTRIBUTING.md — the next/* mapping line. Both are the single surviving pointer for a dead thing still reachable in a live artifact. Two agents independently proposed deleting each half of a pair; taking both would have removed the pointer entirely.

Wants a decision — not resolved here

  1. projects/start-wrt/CONTRIBUTING.md:61 — "The OpenWrt image build needs a consistent environment — Docker is recommended; native builds on some distros fail silently." The Docker half is dead: build.mk runs make -C on the host with no container, and CI builds the image natively on ubuntu-latest. But the second half warns about the only path the repo offers, and I cannot tell from the tree whether that environment sensitivity is real. If it is, the sentence needs rewriting rather than deleting; if it is not, the whole thing goes.
  2. projects/start-wrt/AGENTS.md:13 and :16 — the "start-wrt was migrated from its own repo" lead-in and "the old embedded start-os submodule is gone". Both are completed-migration history, but the first introduces a heading and a five-bullet list of durable facts, and the second is mid-sentence in a clause explaining a genuinely non-obvious live fact (a dependency named startos that is really the start-core package). Cleaning these is a structural re-cut, not a deletion, so I left them.

Separate finding, not a docs issue

13 remote branches still carry - next/* workflow trigger lines, several with open PRs (#3617, #3622, #3623, #3607, #3573, #3137). The triggers were removed from master in 7695ab1ff; those branches predate it and will restore them on merge. Worth a sweep independently of this PR — it is also why the mapping line in the root CONTRIBUTING.md is kept.

MattDHill and others added 2 commits August 16, 2026 21:49
"Two more characters' worth of advice, both from descriptions already in
the registries" — the provenance half is a claim about what the fleet's
short descriptions look like right now, with nothing keeping it true. It
is already only partly accurate: 4 of the 107 packages with an en_US
short open with the service name, which is the pattern the first bullet
tells you to avoid.

The two bullets it introduces both have live producers and stay exactly
as written.

Split out from the rest of the packaging-guide cruft audit because this
paragraph exists only on master — the published guide does not carry it,
so it cannot be fixed on live-docs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Audited all 65 AGENTS.md / ARCHITECTURE.md / CONTRIBUTING.md files across
every scope against one test: a sentence citing what not to do, what not
to include, or a mistake once made must name a live producer — a scaffold
that emits it, a neighbour someone would copy, a tool that does it unless
you intervene, or an obvious-but-wrong fix someone would reach for. No
producer, delete.

Facts that are simply wrong:

- start-registry's CONTRIBUTING said its Cargo version "tracks the OS
  release line — don't bump it independently", while its own AGENTS.md
  one directory over says the opposite. The crate is 1.0.2 and StartOS is
  0.4.0.2, so the CONTRIBUTING rule is the retired one. Its "(currently
  1.0.0)" had drifted too.
- rpc-toolkit's CONTRIBUTING described a `rustfmt.toml` the crate does not
  ship; only the repo root has one.
- start-sdk's build table documented `make dist`, which is not a target in
  that Makefile (start-core's `make dist`, referenced further down the
  same file, is real and stays).
- The root ARCHITECTURE tree put `apt/` under projects/start-os/; it is at
  the repo root.
- shared-libs' CONTRIBUTING said ts-modules' contents are Angular
  libraries; it also holds the non-Angular start-core.
- start-registry's ARCHITECTURE counted "all five product binaries"; the
  root AGENTS.md counts six.
- start-sdk's ARCHITECTURE listed AGENTS.md twice in Further reading.

Migration narration whose migration is over:

Four separate stale-path notes mapped the pre-monorepo root layout
(`core/`, `web/`, `sdk/`, `patch-db/`, `container-runtime/`). The root
AGENTS.md keeps one — `core/src/` is still referenced live in
projects/start-os/DEV_TODO.md, so the mapping is still reachable — and the
copies in start-cli, container-runtime and shared-libs go, along with
"Internally unchanged from the old `core/` crate", the start-fs migration
note, the retired start-os submodule's workspace Cargo.toml, and the
`base/lib/...` import shape.

The retired `next/patch` | `next/minor` | `next/major` prohibition goes
from AGENTS.md; the mapping line in the root CONTRIBUTING.md stays, which
is the one line the still-reachable-artifact rule allows.

Counts and in-progress markers:

`~430 tests` (twice), `11 modules` (twice), `~28 utility modules`,
`~117-line`, `~2200 lines`, `all five product binaries`, `currently 1.0.0`,
`3 small build-infra patches`, `(currently by start-core)`, `(currently
just bitcoin-guides)`, `(currently the Angular libs shared and
marketplace)` (twice), the SDK/OS version pair, `being replaced`, `being
phased out`, the per-scope CONTRIBUTING migration tally (three copies), the
patch-db repo "is being retired" (the repo is still live and was pushed to
after the claim was written), and two notes recording which warnings a
crate happened to emit.

Also drops a commented-out list of ten aspirational locales, a prohibition
against putting files directly in shared-libs/ (nothing but doc files ever
has, across the directory's whole history), and a prohibition against
nesting tab groups more than one level, which restates the positive rule
in the sentence before it.

Includes the fleet-provenance clause in the packaging guide's manifest.md,
which can only be fixed here — the rest of that audit is on live-docs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@dr-bonez
dr-bonez merged commit 81f7af3 into master Aug 19, 2026
6 checks passed
@dr-bonez
dr-bonez deleted the docs/cruft-audit-monorepo-scope branch August 19, 2026 16:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants