docs: delete scope-doc text with no live producer - #3728
Merged
Conversation
"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
approved these changes
Aug 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 2 of the docs cruft audit: all 65
AGENTS.md/ARCHITECTURE.md/CONTRIBUTING.mdfiles, 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.
projects/start-registry/CONTRIBUTING.mdstart-registryis 1.0.2, StartOS is 0.4.0.2. The crate's ownAGENTS.md, one directory over, says the opposite. This is the retired rule stated as current.projects/start-registry/AGENTS.md1.0.0)"1.0.2.shared-libs/crates/rpc-toolkit/CONTRIBUTING.mdrustfmt.toml"projects/start-sdk/AGENTS.mdmake diststart-core'smake dist, referenced further down the same file, is real and stays.)ARCHITECTURE.mdapt/underprojects/start-os/apt/is at the repo root.shared-libs/CONTRIBUTING.mdstart-core.projects/start-registry/ARCHITECTURE.mdAGENTS.mdcounts six.projects/start-sdk/ARCHITECTURE.mdAGENTS.mdlisted 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 rootAGENTS.mdkeeps one —core/src/is still referenced live inprojects/start-os/DEV_TODO.md, so the mapping is still reachable, and one line is the maximum the still-encounterable rule allows. The copies instart-cli,container-runtimeandshared-libsgo, along with "Internally unchanged from the oldcore/crate", thestart-fsmigration note, the retired submodule's workspaceCargo.toml, and thebase/lib/...import shape.Same treatment for the in-flight
CONTRIBUTING.md→AGENTS.mdmigration: 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-dbrepo is being retired" — worse than stale:gh apishows 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— thetaiga-ui-mcpentry. 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 extendingMarketplaceService. 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.rsis a working exported C ABI andlua/jsonpath.luadlopens 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_BUMPmarker sits on this crate exactly as on the OS-coupled ones, andVERSION_BUMP.mdis titled the StartOS version bump guide, so the wrong inference is one glance away.AGENTS.md— the stale-path watch, and rootCONTRIBUTING.md— thenext/*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
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.mkrunsmake -Con the host with no container, and CI builds the image natively onubuntu-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.projects/start-wrt/AGENTS.md:13and:16— the "start-wrt was migrated from its own repo" lead-in and "the old embeddedstart-ossubmodule 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 namedstartosthat is really thestart-corepackage). 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 in7695ab1ff; 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 rootCONTRIBUTING.mdis kept.