diff --git a/docs/explanation/ownership-and-templates.md b/docs/explanation/ownership-and-templates.md index fd2559d..ee38f10 100644 --- a/docs/explanation/ownership-and-templates.md +++ b/docs/explanation/ownership-and-templates.md @@ -179,6 +179,17 @@ sha256 per shipped file in `.wikitool-release.json`. `wikitool dist upgrade` com candidate path against the digest recorded when it was installed, overwrites only what still matches, and refuses rather than overwrite what does not. +A generated verbatim file adds one more way to touch it without meaning to. The reference pages +under `docs/reference/` are verbatim, and `wikitool docs reference --apply` rewrites their +generated regions in whatever tree it runs in. Most of them render the command records in +`tools/`, which an instance leaves alone, so they come out the same everywhere. The skill +catalogue and the page types would render material an instance does own: its adopted type-specs +and any instructions it added. Regenerated there, they would turn a shipped page into a locally +changed one, and the next upgrade would refuse to replace it. So those two pages describe the +stack's shipped defaults. They are generated and checked only in the origin repo, the one tree +without a release stamp, and an instance leaves them alone and asks `wikitool types describe` or +`wikitool instructions list` for its own state. + So the practical rule is narrower than "overwrite the verbatim files, leave the rest alone": overwrite the verbatim files *this instance has not touched*, never write the other two categories, and make a locally changed file a decision someone takes deliberately instead of