docs: correct file references and the dev reachability claim #156

Merged

admin_emi merged 1 commit from fix/doc-accuracy into dev

2026-08-01 18:51:09 +00:00

emig commented

2026-08-01 18:49:51 +00:00

Owner

Audited the five CLAUDE.md files and all twenty-one README.md files against the tree: 334 in-repo path claims machine-checked, plus live verification against vps1/vps2 wherever a claim was testable.

The one that matters is in the root file. dev was documented as reachable on the mesh at 10.10.0.2:8137. It is not — infra/docker-compose.yml binds the port to 127.0.0.1, and the address answers from neither vps2 nor vps1 itself. Only loopback responds. Anyone following it gets a connection refused with nothing to explain it.

The rest are stale paths, several dating to the reunification:

File	Was	Is
`infra/deploy/twa/README.md` ×2	`frontend/.well-known/assetlinks.json`	`frontend/static/.well-known/assetlinks.json`
`infra/deploy/twa/README.md`	`backend/push.py`, `backend/notify.py`	`backend/notifications/…`
`observability/README.md`	`INFRA.md`	never existed in any branch
`infra/deploy/forgejo/README.md`	`deploy/stack/README`	never existed in any branch
`infra/terraform/README.md`	`deploy/Caddyfile`	`deploy/stack/lb/Caddyfile`

The assetlinks one is the sharpest: the file moved under static/ in the subtree merge, so following the README would put it where nothing serves it and Android app-link verification would fail silently.

Plus three bare relative paths that resolve for a reader but not from the directory the file sits in — units.js is the frontend's, deploy.sh is infra's, entrypoint.sh is the backend's.

One addition. infra/deploy/forgejo/README.md explains pinning git.thermograph.org on mesh clients but not that the registry's bearer-token realm follows ROOT_URL — so pinning the image host alone still sends the token request out the public route, where the /v2/* matcher returns 403 and docker falls back to anonymous. That surfaces as unauthorized: reqPackageAccess, indistinguishable from a bad credential. It cost an outage today.

Verified true and left alone: the four-domain layout, both .claude/ runbooks, the absence of any domain-level .forgejo/ directory, the pinned compose project name, the SERVICE=…/BACKEND_IMAGE_TAG=sha-<12hex> contract, prod's eight stack services, beta's five prefixed ones with no db of its own, dev's five, PAYLOAD_VER across five source files, and every documented make target.

No behaviour changes — documentation only.

Audited the five `CLAUDE.md` files and all twenty-one `README.md` files against the tree: 334 in-repo path claims machine-checked, plus live verification against vps1/vps2 wherever a claim was testable. **The one that matters** is in the root file. `dev` was documented as reachable on the mesh at `10.10.0.2:8137`. It is not — `infra/docker-compose.yml` binds the port to `127.0.0.1`, and the address answers from neither vps2 nor vps1 itself. Only loopback responds. Anyone following it gets a connection refused with nothing to explain it. The rest are stale paths, several dating to the reunification: | File | Was | Is | |---|---|---| | `infra/deploy/twa/README.md` ×2 | `frontend/.well-known/assetlinks.json` | `frontend/static/.well-known/assetlinks.json` | | `infra/deploy/twa/README.md` | `backend/push.py`, `backend/notify.py` | `backend/notifications/…` | | `observability/README.md` | `INFRA.md` | never existed in any branch | | `infra/deploy/forgejo/README.md` | `deploy/stack/README` | never existed in any branch | | `infra/terraform/README.md` | `deploy/Caddyfile` | `deploy/stack/lb/Caddyfile` | The assetlinks one is the sharpest: the file moved under `static/` in the subtree merge, so following the README would put it where nothing serves it and Android app-link verification would fail silently. Plus three bare relative paths that resolve for a reader but not from the directory the file sits in — `units.js` is the frontend's, `deploy.sh` is infra's, `entrypoint.sh` is the backend's. **One addition.** `infra/deploy/forgejo/README.md` explains pinning `git.thermograph.org` on mesh clients but not that the registry's bearer-token realm follows `ROOT_URL` — so pinning the image host alone still sends the token request out the public route, where the `/v2/*` matcher returns 403 and docker falls back to anonymous. That surfaces as `unauthorized: reqPackageAccess`, indistinguishable from a bad credential. It cost an outage today. **Verified true and left alone:** the four-domain layout, both `.claude/` runbooks, the absence of any domain-level `.forgejo/` directory, the pinned compose project name, the `SERVICE=…/BACKEND_IMAGE_TAG=sha-<12hex>` contract, prod's eight stack services, beta's five prefixed ones with no `db` of its own, dev's five, `PAYLOAD_VER` across five source files, and every documented `make` target. No behaviour changes — documentation only.

emig added 1 commit 2026-08-01 18:49:52 +00:00

docs: correct file references and the dev reachability claim

secrets-guard / encrypted (pull_request) Successful in 5s

Details

shell-lint / shellcheck (pull_request) Successful in 10s

Details

PR build (required check) / changes (pull_request) Successful in 16s

Details

PR build (required check) / build-frontend (pull_request) Has been skipped

Details

PR build (required check) / validate-observability (pull_request) Successful in 20s

Details

PR build (required check) / build-backend (pull_request) Successful in 45s

Details

PR build (required check) / gate (pull_request) Successful in 5s

Details

af21d8e477

Audited the five CLAUDE.md files and all twenty-one README.md files against the
tree, machine-checking every in-repo path they name and verifying the testable
claims against the live hosts.

The one that matters is in the root file: dev was documented as reachable on
the mesh at 10.10.0.2:8137. It is not, and never was from anywhere but vps1 —
infra/docker-compose.yml binds the port to 127.0.0.1, and the address answers
from neither vps2 nor vps1 itself. Anyone following it gets a connection
refused with nothing to explain it.

The rest are stale paths, several from the reunification:

  * assetlinks.json moved under frontend/static/ in the subtree merge; the TWA
    README kept the pre-merge path in both places it names it. Following it
    would put the file where nothing serves it and Android app-link
    verification would fail silently.
  * push.py and notify.py now live in backend/notifications/.
  * INFRA.md and deploy/stack/README have never existed in this repo, in any
    branch.
  * the Caddyfile is at deploy/stack/lb/Caddyfile.
  * three bare relative paths that resolve for a reader but not from the
    directory the file sits in: units.js is the frontend's, deploy.sh is
    infra's, entrypoint.sh is the backend's.

Also records why mesh clients must pin the ROOT_URL host and not only the image
host: the registry's bearer-token realm follows ROOT_URL, so pinning
git.thermograph.org alone still sends the token request out the public route,
where the /v2/* matcher returns 403 and docker falls back to anonymous. That
surfaces as `unauthorized: reqPackageAccess`, indistinguishable from a bad
credential.

Verified true and left alone: the four-domain layout, both .claude runbooks,
the absence of any domain-level .forgejo directory, the pinned compose project
name, the deploy contract, prod's eight stack services, beta's five prefixed
ones with no db of its own, dev's five, and every documented make target.