docs: add the docs tree — entry point, architecture, runbooks, ADRs, glossary, license #13

pit · 2026-10-06T10:44:11Z

pit commented

2026-10-06 10:44:11 +00:00

Part of #7. Closes #8.

The detail gets a home before anything is taken out of the README. Adds only — README, AGENTS.md and the ansible//tofu/ trees are untouched; the extraction lands in #9 and #10.

What lands

docs/index.md                     entry point + section TOC (wiki Home)
docs/architecture.md              topology + one-glance repo map
docs/runbooks/index.md            index
docs/runbooks/0001-*.md           deploy / Edge / vault / state / PRE / rollback
docs/adr/index.md                 index (lists the existing ADR-0001)
docs/actions/index.md             empty placeholder
GLOSSARY.md                       the project's ten terms + synonyms to avoid
LICENSE                           MIT

Entry point reads as a table of contents: each section named, described in one line, paired with an "update when" note. Its links resolve.
Architecture describes the topology — the Guest created by OpenTofu, published through the Edge, the service installed natively — plus a one-glance repository sketch, deliberately not a per-file inventory.
Runbook 0001 reproduces the procedure and states its own gates out loud rather than citing a numbered convention: review the full plan before any apply; snapshot the Guest before a service-touching run; back up state after every apply. The vault-pass gate is explicit — if ansible/vault-pass is missing, the run stops and the user is asked to create it.
Glossary stays a glossary: the ten terms with the synonyms to avoid, no implementation detail.
docs/agents/ is untouched and deliberately outside the published docs.

Evidence

Every relative link in the new docs resolves. Checked with a one-off script during development; the check was not kept in the repo.
tofu fmt -check -recursive tofu/ clean; tofu validate succeeds on both stacks — no behavioural change.
git diff origin/main...HEAD -- README.md AGENTS.md ansible tofu is empty: those trees are untouched, as the ticket requires.
Nothing currently in the README is dropped: the Edge flow, vault handling, the PRE rehearsal and the Actions/mirror notes are all reproduced in the docs; the conventions list itself is #9's (rules → AGENTS.md) and #10's (README rewrite) to place, and is deliberately not carried here.

Review

Two-axis review (standards + spec) run pre-merge as parallel sub-agents; material findings fixed in the same commit: the runbook's bare tofu apply (required vars with no defaults — now carries env + -var-file) and the architecture page's state claim (only the two OpenTofu stacks hold state).

Merge Danger

Door: one-way for the wiki-sync work, none for the running stack — this PR adds documents and changes no tofu or ansible behaviour.

Blast Radius: docs only. The publish manifest and the wiki mapping are knowingly not here: they belong to #12, which builds on the tree this PR establishes.

Part of #7. Closes #8. The detail gets a home before anything is taken out of the README. Adds only — README, `AGENTS.md` and the `ansible/`/`tofu/` trees are untouched; the extraction lands in #9 and #10. ## What lands ```text docs/index.md entry point + section TOC (wiki Home) docs/architecture.md topology + one-glance repo map docs/runbooks/index.md index docs/runbooks/0001-*.md deploy / Edge / vault / state / PRE / rollback docs/adr/index.md index (lists the existing ADR-0001) docs/actions/index.md empty placeholder GLOSSARY.md the project's ten terms + synonyms to avoid LICENSE MIT ``` - **Entry point** reads as a table of contents: each section named, described in one line, paired with an "update when" note. Its links resolve. - **Architecture** describes the topology — the Guest created by OpenTofu, published through the Edge, the service installed natively — plus a one-glance repository sketch, deliberately not a per-file inventory. - **Runbook 0001** reproduces the procedure and states its own gates out loud rather than citing a numbered convention: review the full plan before any apply; snapshot the Guest before a service-touching run; back up state after every apply. The vault-pass gate is explicit — if `ansible/vault-pass` is missing, the run stops and the user is asked to create it. - **Glossary** stays a glossary: the ten terms with the synonyms to avoid, no implementation detail. - **`docs/agents/`** is untouched and deliberately outside the published docs. ## Evidence - Every relative link in the new docs resolves. Checked with a one-off script during development; the check was **not** kept in the repo. - `tofu fmt -check -recursive tofu/` clean; `tofu validate` succeeds on both stacks — no behavioural change. - `git diff origin/main...HEAD -- README.md AGENTS.md ansible tofu` is empty: those trees are untouched, as the ticket requires. - Nothing currently in the README is dropped: the Edge flow, vault handling, the PRE rehearsal and the Actions/mirror notes are all reproduced in the docs; the conventions list itself is #9's (rules → `AGENTS.md`) and #10's (README rewrite) to place, and is deliberately not carried here. ## Review Two-axis review (standards + spec) run pre-merge as parallel sub-agents; material findings fixed in the same commit: the runbook's bare `tofu apply` (required vars with no defaults — now carries env + `-var-file`) and the architecture page's state claim (only the two OpenTofu stacks hold state). ## Merge Danger **Door:** one-way for the wiki-sync work, none for the running stack — this PR adds documents and changes no tofu or ansible behaviour. **Blast Radius:** docs only. The publish manifest and the wiki mapping are knowingly **not** here: they belong to #12, which builds on the tree this PR establishes.

pit added 1 commit

2026-10-06 10:44:11 +00:00

docs: add the docs tree — entry point, architecture, runbooks, ADRs, glossary, license (issue #8 ) 0d67bf8e8d

The README has become the junk drawer, so the detail gets a home before
anything is taken out of it. This ticket adds only; the README, AGENTS.md and
the ansible/tofu trees are untouched, and the extraction follows in #9 and
#10.

- docs/index.md: the entry point, a table of contents where each section is
  named, described in one line and paired with an "update when" note. It also
  becomes the wiki Home.
- docs/architecture.md: the topology — the Guest created by OpenTofu,
  published through the Edge, the service installed natively — plus a
  one-glance repository sketch, deliberately not a per-file inventory.
- docs/runbooks/: an index and runbook 0001, which reproduces the Guest /
  Edge / service procedure, vault handling, the encrypted state backup, the
  PRE rehearsal and the rollback. Its gates are steps stated out loud (review
  the full plan before any apply; snapshot before a service-touching run; back
  up state after every apply) rather than references to a numbered
  convention, and the vault-pass gate stops the run and asks the user to
  create the file when it is missing.
- docs/adr/: an index listing the existing runner-on-the-guest decision.
- docs/actions/: an empty index, so runner and mirror content has a home.
- GLOSSARY.md: Edge, Guest, Node, NPM, Prod, PRE, Stack, Blueprint, Operator
  key, Vault, each with the synonyms to avoid, and no implementation detail.
- LICENSE: MIT.
- tests/check-doc-links.py: the link check as a script, so the split cannot
  leave a dangling link behind.

pit force-pushed hermes/improve-readme from 0d67bf8e8d to 56d3a2836a

2026-10-06 10:44:28 +00:00

Compare

pit referenced this pull request

2026-10-06 10:44:38 +00:00

Docs tree lands: entry point, architecture, runbooks, ADRs, glossary, license #8

pit force-pushed hermes/improve-readme from 56d3a2836a to b9122d6447

2026-10-06 10:52:01 +00:00

Compare

pit reviewed

2026-10-06 10:54:28 +00:00

docs/runbooks/0001-deploy-and-rollback.md Outdated

					
				@ -0,0 +11,4 @@

				Not steps of a deploy — they are done once per site, before the first one.

				- The NPM user `svc-tou` (admin) exists, created through the NPM UI. Its

I don't think that's the user's name. svc-tofu sounds more like it

I don't think that's the user's name. `svc-tofu` sounds more like it

pit reviewed

2026-10-06 10:56:07 +00:00

docs/runbooks/0001-deploy-and-rollback.md Outdated

					
				@ -0,0 +24,4 @@

				Ansible reads the vault password from `ansible/vault-pass`, which

				`ansible.cfg` picks up automatically — no `--ask-vault-pass`. That file is

				gitignored and must exist before the run. It is generated from

				`ANSIBLE_VAULT_PASSWORD` in `ansible/.env`:

True just only for current local. Other agents cloning the repo will not have that env var in the .env file. Agents should ask a human to configure vault pass file

pit reviewed

2026-10-06 10:59:40 +00:00

docs/index.md Outdated

					
				@ -0,0 +21,4 @@

				- Every relative link resolves inside the repo. Nothing here links out to the

				  README, and the README does not link in here yet.

				- The glossary is a glossary: definitions only, no procedures.

				- `docs/agents/` is agent tooling — issue tracker and domain docs — and is

Do not mention docs/agents/ here

pit force-pushed hermes/improve-readme from b9122d6447 to 50dd7fa1d8

2026-10-06 11:01:08 +00:00

Compare

pit commented

2026-10-06 11:01:16 +00:00

All three addressed in 50dd7fa (force-pushed; PR is still one commit, 8 files, adds-only).

svc-tou → svc-tofu — you're right, and it was the docs that were wrong. tofu/npm/.env (the real one, gitignored) has svc-tofu; both .env.example files and README.md carried the typo svc-tou, and I copied the typo from the README. Fixed in the runbook. The typo is still in tofu/npm/.env.example and README.md — deliberately left alone, since this ticket's acceptance criteria fix the README unchanged, and a one-word fix there would make git diff non-empty for #8. Worth a line in one of the follow-up tickets.

Vault pass, other machines — you're right that the phrasing implied it was universally available. Reworded: the generation command is now attributed to the operator's machine, and the gate says "on any machine" explicitly, states that neither ansible/.env nor vault-pass is in the repo so a fresh clone has neither, and that an agent has no way to make one itself — so it stops and asks a human. Same rule, no ambiguity about whose machine.

docs/index.md mentioning docs/agents/ — removed; the bullet is gone and the section is now three bullets. Verified the file no longer contains the string.

All three addressed in 50dd7fa (force-pushed; PR is still one commit, 8 files, adds-only). **`svc-tou` → `svc-tofu`** — you're right, and it was the docs that were wrong. `tofu/npm/.env` (the real one, gitignored) has `svc-tofu`; both `.env.example` files and `README.md` carried the typo `svc-tou`, and I copied the typo from the README. Fixed in the runbook. The typo is still in `tofu/npm/.env.example` and `README.md` — deliberately left alone, since this ticket's acceptance criteria fix the README unchanged, and a one-word fix there would make `git diff` non-empty for #8. Worth a line in one of the follow-up tickets. **Vault pass, other machines** — you're right that the phrasing implied it was universally available. Reworded: the generation command is now attributed to the operator's machine, and the gate says "on any machine" explicitly, states that neither `ansible/.env` nor `vault-pass` is in the repo so a fresh clone has neither, and that an agent has no way to make one itself — so it stops and asks a human. Same rule, no ambiguity about whose machine. **`docs/index.md` mentioning `docs/agents/`** — removed; the bullet is gone and the section is now three bullets. Verified the file no longer contains the string.

pit merged commit 6c0dac2291 into main

2026-10-06 11:03:38 +00:00

pit deleted branch hermes/improve-readme

2026-10-06 11:03:38 +00:00

pit referenced this pull request from a commit

2026-10-06 11:03:39 +00:00

docs: add the docs tree — entry point, architecture, runbooks, ADRs, glossary, license (#13)

~~pit referenced this pull request 2026-10-06 12:07:34 +00:00~~

docs: publish manifest + wiki page mapping, with a coverage check (#12) #18

pit referenced this pull request

2026-10-06 12:46:08 +00:00

README rewrite, docs tree, and protected main #7