Skip to content

Give each repeated idea one home - #9

Merged
pierrebrunelle merged 1 commit into
mainfrom
consolidate-docs
Sep 5, 2026
Merged

pierrebrunelle merged 1 commit into
mainfrom
consolidate-docs

Conversation

@pierrebrunelle

Copy link
Copy Markdown
Member

The daemon/key fix was written into six places. It is the right rule, but it was stated in full every time. Docs go 409 → 346 lines with no rule lost.

One canonical home for the ordering rule

chat-agent/README.md keeps the full explanation. That choice is forced as much as chosen: pixeltable-new's extract_pattern copies that directory verbatim into every scaffolded project, so a scaffolded user may never see the root README — the file has to stand alone. It also happens to be the best of the six versions: the only one that says why re-running pxt service update does not help ("the plan is already in agreement, so nothing respawns"), and the only one naming pxt config --section anthropic as the diagnostic.

The other five keep their warning and every actionable command, and lose only the repeated mechanism:

File Keeps
README.md the bolded warning, now one line, pointing at chat-agent
.env.example the compose exception and the config.toml alternative, both unique to it
chat-agent/app.py the recovery commands — someone debugging in-file should not have to leave it
.devcontainer/post-create.sh the printed commands
AGENTS.md already a single line

Two more verbatim repeats

pxt db update packs the hosted image and workers; it is not Experiment. appeared identically in four files. It now lives once, in AGENTS.md, beside the rest of the Cloud sequence.

Advertised order is schema, then service, then insert. sat directly above a code block showing exactly that order, in both app READMEs.

One thing moved rather than cut

The pxt schema diff exit-code contract (0 in sync, 2 pending, 1 error) existed only in the root README's "For agents" blurb, not in AGENTS.md — the file that is supposed to be the fuller agent reference. Moved it there and left a pointer. This is the only change here that grows a file.

Verified

ruff check, 49 tests, 1 skipped. Three existing tests constrain this rewrite and all still pass:

  • test_cloud_teaches_hosted_service_update requires the literal pxt service update app.py pxt:// in both README.md and AGENTS.md, so the Cloud sections could not simply collapse into one.
  • test_no_em_dashes bans U+2014 in contract markdown — every rewrite uses --.
  • test_one_apply_path scans the app dirs and the three root .md files for banned apply tokens.

Note this repo has no release gate: pixeltable-new fetches refs/heads/main, so merging ships chat-agent/README.md to every new scaffold immediately.

🤖 Generated with Claude Code

The daemon/key rule was written into six places when it was fixed. It is
the right rule, but it was stated in full every time.

chat-agent/README.md keeps the full explanation and becomes the canonical
home. It has to stay self-contained regardless: `pixeltable-new` extracts
that directory verbatim into every scaffolded project, so a reader may
never see the root README. It is also the best of the six -- the only one
that says why re-running `service update` does not help, and the only one
naming `pxt config --section anthropic` as the diagnostic.

The other five keep their warning and every actionable command, and lose
the repeated mechanism: root README, .env.example, chat-agent/app.py's
docstring, and the dev container's printed steps. AGENTS.md was already
one line.

Two more repeats: `pxt db update packs the hosted image and workers` was
verbatim in four files and now lives once, in AGENTS.md next to the rest
of the Cloud sequence. `Advertised order is schema, then service, then
insert.` sat directly above a code block showing that order in both app
READMEs.

Moved the `pxt schema diff` exit codes out of the root README's "For
agents" blurb into AGENTS.md, which is meant to be the fuller reference
and did not have them. The README keeps a pointer.

Docs 409 -> 346 lines, no rule lost.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@pierrebrunelle
pierrebrunelle merged commit f6adb25 into main Sep 5, 2026
6 checks passed
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.

1 participant