scaffold.sh leaves every new project with a broken link and a red doc-claims #15

New Issue

Closed

opened 2026-08-17 23:32:49 -05:00 by null · 0 comments

null commented

2026-08-17 23:32:49 -05:00

Owner

docs/data/README.md says, of the asset spec:

Dimensions, weights and how to generate them are in img/README.md, beside the files they describe.

scaffold.sh never copies that file. DOCS does not list it, and DIRS=(docs/data/img) creates the directory empty. So a project scaffolded from this template gets:

a broken link in a required document, pointing at a file that does not exist
a doc-claims.sh failure on its first run, because a markdown link target is a claim the file exists
and no copy of the spec the link promises, which is the one place recording that the marks are webp checked by magic bytes, and at what dimensions

Reproduced by scaffolding into a scratch directory: docs/data/ contains README.md and an empty img/.

The exclusion is almost certainly a misreading of the script's own rule. Its header says "It does not copy branding" and "The template's own docs/data/img is not a source" — both are about the three .webp marks, which genuinely must not be copied because a placeholder that looks deliberate outlives the issue that would have replaced it. img/README.md is documentation about those files, not one of them, and every other document in the tree is copied.

This is the fourth instance in this repository of one shape: a document naming a path that is not there. The others were docs/planning/FUTURE.md in the batch ledger, an Exempt: line inside a code fence, and docs/data/logo.webp as an example of where not to put an asset. The first three were wrong in the template itself; this one is correct in the template and wrong in every copy of it, which is why nothing here caught it.

Verify: scaffold.sh --dry-run names docs/data/img/README.md, a real scaffold creates it, and doc-claims.sh run inside a freshly scaffolded project reports no missing paths.

`docs/data/README.md` says, of the asset spec: > **Dimensions, weights and how to generate them are in [`img/README.md`](img/README.md)**, beside the files they describe. `scaffold.sh` never copies that file. `DOCS` does not list it, and `DIRS=(docs/data/img)` creates the directory empty. So a project scaffolded from this template gets: - a **broken link** in a required document, pointing at a file that does not exist - a **`doc-claims.sh` failure on its first run**, because a markdown link target is a claim the file exists - and no copy of the spec the link promises, which is the one place recording that the marks are webp checked by magic bytes, and at what dimensions Reproduced by scaffolding into a scratch directory: `docs/data/` contains `README.md` and an empty `img/`. The exclusion is almost certainly a misreading of the script's own rule. Its header says *"It does not copy branding"* and *"The template's own docs/data/img is not a source"* — both are about the three `.webp` marks, which genuinely must not be copied because a placeholder that looks deliberate outlives the issue that would have replaced it. `img/README.md` is documentation about those files, not one of them, and every other document in the tree is copied. This is the fourth instance in this repository of one shape: a document naming a path that is not there. The others were `docs/planning/FUTURE.md` in the batch ledger, an `Exempt:` line inside a code fence, and `docs/data/logo.webp` as an example of where *not* to put an asset. The first three were wrong in the template itself; this one is correct in the template and wrong in every copy of it, which is why nothing here caught it. Verify: `scaffold.sh --dry-run` names `docs/data/img/README.md`, a real scaffold creates it, and `doc-claims.sh` run inside a freshly scaffolded project reports no missing paths.