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

README goes thin #10

New issue
Closed
opened 2026-10-06 10:13:23 +00:00 by pit · 2 comments
pit commented 2026-10-06 10:13:23 +00:00
Owner
Copy link

Part of #7

What to build

Rewrite the README so it does one job: say what this is and how to run it. The conventions list and the detail that moved into the docs are gone; what remains is a front door. The forge's repository description is brought in line with the new tagline (it is still in another language).

Acceptance criteria

  • The README opens with a tagline and a short paragraph covering what this provisions, the problem it solves and who it is for.
  • It carries Requirements, Environment variables, Running (the three layers as copy-pasteable commands), a one-line repository overview, a before-you-touch-anything pointer, Contributing and License.
  • The conventions list is gone, no rule is referenced by number, the state-backup instruction appears once (in the runbook), and there are no badges, screenshot or table of contents.
  • The README does not link into the docs yet.
  • Stale statements are gone: repository visibility is stated accurately, the PRE Guest is described as destroyed and parked on its branch, and the "phase 1, no CI" framing is dropped.
  • The License section points at the LICENSE added with the docs tree.
  • The forge repository description is updated to the new tagline, in English, and read back.
  • Lands as its own PR.

Blocked by

Part of #7 ## What to build Rewrite the README so it does one job: say what this is and how to run it. The conventions list and the detail that moved into the docs are gone; what remains is a front door. The forge's repository description is brought in line with the new tagline (it is still in another language). ## Acceptance criteria - [ ] The README opens with a tagline and a short paragraph covering what this provisions, the problem it solves and who it is for. - [ ] It carries Requirements, Environment variables, Running (the three layers as copy-pasteable commands), a one-line repository overview, a before-you-touch-anything pointer, Contributing and License. - [ ] The conventions list is gone, no rule is referenced by number, the state-backup instruction appears once (in the runbook), and there are no badges, screenshot or table of contents. - [ ] The README does not link into the docs yet. - [ ] Stale statements are gone: repository visibility is stated accurately, the PRE Guest is described as destroyed and parked on its branch, and the "phase 1, no CI" framing is dropped. - [ ] The License section points at the LICENSE added with the docs tree. - [ ] The forge repository description is updated to the new tagline, in English, and read back. - [ ] Lands as its own PR. ## Blocked by - #8
pit commented 2026-10-06 11:23:47 +00:00
Author
Owner
Copy link

PR: pit/infra-forge#16 (base main, head hermes/10-readme-goes-thin, 1 file: README.md, +44/−86).

What landed, checked against the acceptance criteria on the branch:

  • Tagline + short paragraph: what it provisions, the problem, who it is for.
  • Sections: Requirements, Environment variables, Running (Guest → Edge → service as copy-pasteable commands), a one-line repository overview, before-you-touch-anything pointer, Contributing, License.
  • Conventions list gone; no rule referenced by number; state-backup instruction only in the runbook; no badges, screenshot or TOC.
  • No links into docs/ yet; the overview names docs/ without linking it.
  • Stale statements gone: no private-repo claim, no running PRE, no "phase 1, no CI".
  • License points at LICENSE.

Out-of-diff, run now and read back: the forge repository description is
OpenTofu + Ansible that provision and maintain a self-hosted Forgejo on the Pit homelab.

Review note (for the maintainer, outside this issue's scope): docs/adr/0001-forgejo-actions-runner-on-guest.md still cites "convention 4" / "convention 7" and points at the README. With the numbered list gone those references dangle; they belong to the self-contained-comments work in #9, along with the convention 4 note in ansible/roles/forgejo/defaults/main.yml and the README pointer in ansible/ansible.cfg.

PR: https://forgejo.thepit.space/pit/infra-forge/pulls/16 (base `main`, head `hermes/10-readme-goes-thin`, 1 file: `README.md`, +44/−86). What landed, checked against the acceptance criteria on the branch: - Tagline + short paragraph: what it provisions, the problem, who it is for. - Sections: Requirements, Environment variables, Running (Guest → Edge → service as copy-pasteable commands), a one-line repository overview, before-you-touch-anything pointer, Contributing, License. - Conventions list gone; no rule referenced by number; state-backup instruction only in the runbook; no badges, screenshot or TOC. - No links into `docs/` yet; the overview names `docs/` without linking it. - Stale statements gone: no private-repo claim, no running PRE, no "phase 1, no CI". - License points at `LICENSE`. Out-of-diff, run now and read back: the forge repository description is `OpenTofu + Ansible that provision and maintain a self-hosted Forgejo on the Pit homelab.` Review note (for the maintainer, outside this issue's scope): `docs/adr/0001-forgejo-actions-runner-on-guest.md` still cites "convention 4" / "convention 7" and points at the README. With the numbered list gone those references dangle; they belong to the self-contained-comments work in #9, along with the `convention 4` note in `ansible/roles/forgejo/defaults/main.yml` and the README pointer in `ansible/ansible.cfg`.
pit referenced this issue from a commit 2026-10-06 11:54:06 +00:00
README goes thin (#10) (#16)
pit commented 2026-10-06 11:54:49 +00:00
Author
Owner
Copy link

Merged in #16 (95b4659). Every acceptance criterion checked against main, not just the branch:

  • Opens with a tagline and a short paragraph (what it provisions, the problem, who it is for).
  • Requirements, Environment variables, Running (the three layers as copy-pasteable commands), a one-line repository overview, the agent pointer, Contributing and License all present.
  • Conventions list gone; no rule referenced by number; no badges, screenshot or TOC; the state-backup instruction appears once, in the runbook.
  • No link into docs/ (named only).
  • Stale statements gone: no private-repo claim, PRE described as destroyed and parked on its branch (runbook), "phase 1, no CI" dropped.
  • License points at LICENSE.
  • Forge repository description updated to the tagline, in English, and read back — matches.
  • Landed as its own PR (#16).

Note: #9/#15 landed the Secrets and Privacy rules in AGENTS.md first, so the ## For agents pointer now points at a file that genuinely carries the working context.

Merged in #16 (`95b4659`). Every acceptance criterion checked against `main`, not just the branch: - [x] Opens with a tagline and a short paragraph (what it provisions, the problem, who it is for). - [x] Requirements, Environment variables, Running (the three layers as copy-pasteable commands), a one-line repository overview, the agent pointer, Contributing and License all present. - [x] Conventions list gone; no rule referenced by number; no badges, screenshot or TOC; the state-backup instruction appears once, in the runbook. - [x] No link into `docs/` (named only). - [x] Stale statements gone: no private-repo claim, PRE described as destroyed and parked on its branch (runbook), "phase 1, no CI" dropped. - [x] License points at `LICENSE`. - [x] Forge repository description updated to the tagline, in English, and read back — matches. - [x] Landed as its own PR (#16). Note: #9/#15 landed the *Secrets* and *Privacy* rules in `AGENTS.md` first, so the `## For agents` pointer now points at a file that genuinely carries the working context.
pit closed this issue 2026-10-06 11:54:49 +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#10
No description provided.