olympus/infra-forge
3
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

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

New issue
Closed
opened 2026-10-06 10:13:19 +00:00 by pit · 1 comment
pit commented 2026-10-06 10:13:19 +00:00
Owner
Copy link

Part of #7

What to build

Give the docs a home before anything is removed from the README. A docs entry point that works as a table of contents — each section described in one line, with when to update it — plus the pages themselves: an architecture page (the topology: the Guest, the Edge, and the native service), a runbooks section (an index and one runbook covering the deploy flow, vault handling, state backup, PRE rehearsal and rollback), a decisions section (an index plus the existing runner-on-the-guest decision), an empty Actions index, and a glossary of the project's own terms. Add the MIT license. The README is left untouched, so the detail it currently carries is duplicated here rather than lost.

Acceptance criteria

  • A docs entry point exists and reads as a table of contents: each section named, described in one line, and paired with an "update when Y" note; its links resolve.
  • An architecture page describes the topology (the Guest created by OpenTofu, published through the Edge, the service installed natively) and gives a one-glance repository overview, deliberately not a per-file inventory.
  • Runbooks are a directory with an index and one runbook per file. The first runbook reproduces the Guest / Edge / service procedure, vault handling, encrypted state backup, the PRE rehearsal and the rollback.
  • The runbook states its own gates out loud (review the full plan before any apply; snapshot the Guest before a service-touching run; back up state after every apply) rather than referencing a numbered convention.
  • The runbook states that the vault-pass file must be present and that, if it is missing, the run is stopped and the user is asked to create it.
  • Decisions are a directory with an index and one file per decision; the existing runner-on-the-guest decision is listed.
  • An Actions directory exists with an empty index (placeholder only, no links).
  • A glossary records the project's terms (Edge, Guest, Node, NPM, Prod, PRE, Stack, Blueprint, Operator key, Vault) with the synonyms to avoid; it stays a glossary with no implementation detail.
  • An MIT LICENSE file is present.
  • The README is unchanged by this ticket.
  • No information removed from the README later is lost: everything currently in it is reproduced in the docs.
  • Lands as its own PR.
Part of #7 ## What to build Give the docs a home before anything is removed from the README. A docs entry point that works as a table of contents — each section described in one line, with when to update it — plus the pages themselves: an architecture page (the topology: the Guest, the Edge, and the native service), a runbooks section (an index and one runbook covering the deploy flow, vault handling, state backup, PRE rehearsal and rollback), a decisions section (an index plus the existing runner-on-the-guest decision), an empty Actions index, and a glossary of the project's own terms. Add the MIT license. The README is left untouched, so the detail it currently carries is duplicated here rather than lost. ## Acceptance criteria - [ ] A docs entry point exists and reads as a table of contents: each section named, described in one line, and paired with an "update when Y" note; its links resolve. - [ ] An architecture page describes the topology (the Guest created by OpenTofu, published through the Edge, the service installed natively) and gives a one-glance repository overview, deliberately not a per-file inventory. - [ ] Runbooks are a directory with an index and one runbook per file. The first runbook reproduces the Guest / Edge / service procedure, vault handling, encrypted state backup, the PRE rehearsal and the rollback. - [ ] The runbook states its own gates out loud (review the full plan before any apply; snapshot the Guest before a service-touching run; back up state after every apply) rather than referencing a numbered convention. - [ ] The runbook states that the vault-pass file must be present and that, if it is missing, the run is stopped and the user is asked to create it. - [ ] Decisions are a directory with an index and one file per decision; the existing runner-on-the-guest decision is listed. - [ ] An Actions directory exists with an empty index (placeholder only, no links). - [ ] A glossary records the project's terms (Edge, Guest, Node, NPM, Prod, PRE, Stack, Blueprint, Operator key, Vault) with the synonyms to avoid; it stays a glossary with no implementation detail. - [ ] An MIT LICENSE file is present. - [ ] The README is unchanged by this ticket. - [ ] No information removed from the README later is lost: everything currently in it is reproduced in the docs. - [ ] Lands as its own PR.
pit commented 2026-10-06 10:44:38 +00:00
Author
Owner
Copy link

Implemented on hermes/improve-readme, PR #13: pit/infra-forge#13

Adds the docs tree without touching the README: docs/index.md (entry point + section TOC), docs/architecture.md (topology + one-glance repo map), docs/runbooks/ (index + runbook 0001, with its gates stated as steps), docs/adr/index.md (listing the existing ADR-0001), docs/actions/index.md (empty placeholder), GLOSSARY.md (ten terms + synonyms to avoid), and an MIT LICENSE. Eight files, adds only.

Nothing in the README is dropped — the Edge flow, vault handling, PRE rehearsal, state backup and the Actions/mirror notes are all reproduced in the docs. The conventions list is deliberately not reproduced: #9 gives rules 5 and 7 a home in AGENTS.md and rule 2/3 become the runbook's gates, #10 rewrites the README. Carrying the numbered list here would duplicate it in the exact form those two tickets exist to remove.

The publish manifest and the wiki page mapping are not here — they are #12, which builds on this tree.

Implemented on `hermes/improve-readme`, PR #13: https://forgejo.thepit.space/pit/infra-forge/pulls/13 Adds the docs tree without touching the README: `docs/index.md` (entry point + section TOC), `docs/architecture.md` (topology + one-glance repo map), `docs/runbooks/` (index + runbook 0001, with its gates stated as steps), `docs/adr/index.md` (listing the existing ADR-0001), `docs/actions/index.md` (empty placeholder), `GLOSSARY.md` (ten terms + synonyms to avoid), and an MIT `LICENSE`. Eight files, adds only. Nothing in the README is dropped — the Edge flow, vault handling, PRE rehearsal, state backup and the Actions/mirror notes are all reproduced in the docs. The conventions *list* is deliberately not reproduced: #9 gives rules 5 and 7 a home in `AGENTS.md` and rule 2/3 become the runbook's gates, #10 rewrites the README. Carrying the numbered list here would duplicate it in the exact form those two tickets exist to remove. The publish manifest and the wiki page mapping are **not** here — they are #12, which builds on this tree.
pit closed this issue 2026-10-06 11:03:38 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
forgejo-npm-edge
No results found.
Labels
Clear labels   
needs-info
Waiting on reporter for more information

  
needs-triage
Maintainer needs to evaluate this issue

  
ready-for-agent
Ready for an agent to pick up; see docs/agents/

  
ready-for-human
Requires human implementation

  
wontfix
Will not be actioned

  
needs-info
Waiting on reporter for more information

  
needs-triage
Maintainer needs to evaluate this issue

  
ready-for-agent
Fully specified, ready for an AFK agent

  
ready-for-human
Requires human implementation

  
review/merge-ready
No blocking findings; human merge pending

  
review/needs-fix
Reviewer found blocking findings; fixer dispatched

  
review/needs-human
Circuit stopped: needs a human decision

  
review/needs-review
Awaiting review by the review agent

  
wayfinder:grilling
HITL ticket: conversation; grilling + domain-modeling

  
wayfinder:map
The map itself: destination, decisions so far, and the fog

  
wayfinder:prototype
HITL ticket: a cheap concrete artifact to react to

  
wayfinder:research
AFK ticket: read docs/APIs for a fact a decision waits on

  
wayfinder:task
HITL or AFK ticket: manual work that unblocks a decision

  
wontfix
Will not be actioned

No labels
needs-info
needs-triage
ready-for-agent
ready-for-human
wontfix
needs-info
needs-triage
ready-for-agent
ready-for-human
review/merge-ready
review/needs-fix
review/needs-human
review/needs-review
wayfinder:grilling
wayfinder:map
wayfinder:prototype
wayfinder:research
wayfinder:task
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
olympus/infra-forge#8
No description provided.