README goes thin (#10) #16

pit · 2026-10-06T11:23:32Z

pit commented

2026-10-06 11:23:32 +00:00

Summary

The README stops being the junk drawer and becomes a front door. The numbered
Conventions list and the detail that had grown into it are gone; the detail
already lives in docs/ (issue #8). Scope is README.md only.

 # infra-forge
- IaC for the Forgejo LXC guest: OpenTofu + Ansible …
- ## Conventions (mandatory reading) 1..7
- ## Structure
- ## Edge (NPM) — full flow
- ## Manual usage (phase 1, no CI)
- ## Actions / PRE rehearsal / vault handling
+ <tagline> + short paragraph (what / problem / who)
+ ## Requirements
+ ## Environment variables   (tofu/.env, tofu/npm/.env, ansible/.env)
+ ## Running                 (Guest → Edge → service, copy-pasteable)
+ ## Repository overview     (one line)
+ ## Before you touch anything
+ ## Contributing
+ ## License

Evidence

Before: 112-line README carrying conventions 1–7, the Edge flow, vault
handling, PRE rehearsal and Actions notes; grep -nEi 'convention|phase 1|no CI|private' README.md matched 6 lines.
After: 71-line README; the same grep matches 0 lines. 44 insertions, 86 deletions.

Acceptance checks run against the branch:

No numbered rule, and no rule referenced by number: grep -nE '^\s*[0-9]+\.\s' → none.
No badges / screenshot / TOC / "phase 1, no CI" / stale visibility claim: none.
State-backup instruction appears once, in the runbook only (README has no "backup").
README links only AGENTS.md, LICENSE and external tool sites — nothing into docs/ yet.
Every relative link in README, the docs tree and the glossary resolves (no dangling links).
docs/ sections carried over from #8: Requirements/Env/Running/Overview/Contributing/License all present.

Out-of-diff, run at merge time: the forge repository description was updated via
the API to the new tagline, in English, and read back:

OpenTofu + Ansible that provision and maintain a self-hosted Forgejo on the Pit homelab.

Merge Danger

Door: two-way — README-only change, git revert walks it back.

Blast Radius: repo landing page. No tofu or ansible behaviour changes.

## Summary The README stops being the junk drawer and becomes a front door. The numbered Conventions list and the detail that had grown into it are gone; the detail already lives in `docs/` (issue #8). Scope is `README.md` only. ```diff # infra-forge - IaC for the Forgejo LXC guest: OpenTofu + Ansible … - ## Conventions (mandatory reading) 1..7 - ## Structure - ## Edge (NPM) — full flow - ## Manual usage (phase 1, no CI) - ## Actions / PRE rehearsal / vault handling + <tagline> + short paragraph (what / problem / who) + ## Requirements + ## Environment variables (tofu/.env, tofu/npm/.env, ansible/.env) + ## Running (Guest → Edge → service, copy-pasteable) + ## Repository overview (one line) + ## Before you touch anything + ## Contributing + ## License ``` ## Evidence - **Before:** 112-line README carrying conventions 1–7, the Edge flow, vault handling, PRE rehearsal and Actions notes; `grep -nEi 'convention|phase 1|no CI|private' README.md` matched 6 lines. **After:** 71-line README; the same grep matches 0 lines. 44 insertions, 86 deletions. Acceptance checks run against the branch: - No numbered rule, and no rule referenced by number: `grep -nE '^\s*[0-9]+\.\s'` → none. - No badges / screenshot / TOC / "phase 1, no CI" / stale visibility claim: none. - State-backup instruction appears once, in the runbook only (README has no "backup"). - README links only `AGENTS.md`, `LICENSE` and external tool sites — nothing into `docs/` yet. - Every relative link in README, the docs tree and the glossary resolves (no dangling links). - `docs/` sections carried over from #8: Requirements/Env/Running/Overview/Contributing/License all present. Out-of-diff, run at merge time: the forge repository description was updated via the API to the new tagline, in English, and read back: ``` OpenTofu + Ansible that provision and maintain a self-hosted Forgejo on the Pit homelab. ``` ## Merge Danger **Door:** two-way — README-only change, `git revert` walks it back. **Blast Radius:** repo landing page. No tofu or ansible behaviour changes.

pit added 1 commit

2026-10-06 11:23:32 +00:00

README: front door only — tagline, requirements, env, running, overview, contributing, license (#10 ) 694a7f62cb

pit referenced this pull request

2026-10-06 11:23:47 +00:00

README goes thin #10

pit reviewed

2026-10-06 11:34:30 +00:00

README.md Outdated

					
				@ -6,0 +7,4 @@

				its own git service — repositories, issues, pull requests and CI — instead of

				depending on a public one, and doubles as the worked example of the three-layer

				pattern (Guest, Edge, service) that the other sites copy. Part of the

				homelab-blueprint plan (https://github.com/atthepit/homelab-blueprint).

Remove mention of blueprint plan

pit marked this conversation as resolved

pit reviewed

2026-10-06 11:35:52 +00:00

README.md Outdated

					
				@ -16,0 +15,4 @@

				  token for it.

				- [OpenTofu](https://opentofu.org/) `>= 1.8`.

				- [Ansible](https://docs.ansible.com/) on the machine that runs the playbook.

				- An admin account on the Edge (NPM), with `sshd` disabled in its LXC and the

Would it be possible to move the sshd requirement to ansible config? out of scope for this PR, just curious

pit marked this conversation as resolved

pit reviewed

2026-10-06 11:37:15 +00:00

README.md Outdated

					
				@ -52,3 +42,2 @@

				cd tofu/npm && set -a && source .env && set +a && tofu plan -var-file=forgejo.tfvars

				# ALWAYS: source .env (tofu does not read .env on its own) and -var-file=forgejo.tfvars

				# (without it, the required variables fail the plan instead of proposing destroys).

				# Review the plan in full, then:

You mention plan review here but not for guest

pit marked this conversation as resolved

pit reviewed

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

README.md Outdated

					
				@ -76,3 +58,1 @@

				committed on main so a rehearsal needs no variable re-add — a bare variable

				creates nothing, its only consumer is the parked `tofu/pre.tf`.) To run a

				rehearsal:

				## Before you touch anything

Let's change this section to For agents or something similar

Let's change this section to `For agents` or something similar

pit marked this conversation as resolved

pit reviewed

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

README.md Outdated

					
				@ -93,2 +63,3 @@

				## Contributing

				## Actions (Forgejo runner on the guest)

				Work on a branch and open a pull request for Pedro to review — nothing goes

Change Pedro for a human

Change Pedro for `a human`

pit marked this conversation as resolved

pit added 1 commit

2026-10-06 11:40:43 +00:00

README review: drop blueprint link, gate the Guest plan, rename to For agents, generic human 29d5b4635a

pit commented

2026-10-06 11:40:50 +00:00

Addressed all five in 29d5b46:

#158 — "Remove mention of blueprint plan": dropped the trailing "Part of the homelab-blueprint plan (…)" sentence from the intro paragraph.
#160 — move the sshd requirement to ansible config? (out of scope, answering anyway): in principle yes, but it needs the NPM appliance to become a managed host, which it is not today. This repo reaches NPM only through its API (tofu/npm/, proxy hosts + streams); Ansible targets the Forgejo Guest only (inventories/prod/hosts). Doing it "in ansible" would mean adding an npm host to the inventory plus a small role/play that runs systemctl disable --now ssh there. Two wrinkles worth noting before anyone does: (1) ordering — Ansible reaches that host over SSH, so the disable happens from inside the very session it removes, and any later config drift to NPM would need another path in (the API, or re-enabling sshd); (2) the router rule and the NPM UI are still manual, so this would move one of three steps, not all of them. Worth its own issue if you want it.
#162 — "You mention plan review here but not for guest": split the Guest layer the same way — tofu plan, then tofu apply under a "Review the plan in full, then:" line — and the prose below now reads "Review the plan in full before every apply, both layers."
#164 — section name: renamed ## Before you touch anything → ## For agents.
#166 — "Change Pedro for a human": Contributing now reads "open a pull request for a human to review — nothing goes directly to main. A pull request merges without required approvals."

Addressed all five in `29d5b46`: - **#158 — "Remove mention of blueprint plan"**: dropped the trailing "Part of the homelab-blueprint plan (…)" sentence from the intro paragraph. - **#160 — move the `sshd` requirement to ansible config?** (out of scope, answering anyway): in principle yes, but it needs the NPM appliance to become a managed host, which it is not today. This repo reaches NPM only through its API (`tofu/npm/`, proxy hosts + streams); Ansible targets the Forgejo Guest only (`inventories/prod/hosts`). Doing it "in ansible" would mean adding an `npm` host to the inventory plus a small role/play that runs `systemctl disable --now ssh` there. Two wrinkles worth noting before anyone does: (1) ordering — Ansible reaches that host *over* SSH, so the disable happens from inside the very session it removes, and any later config drift to NPM would need another path in (the API, or re-enabling sshd); (2) the router rule and the NPM UI are still manual, so this would move one of three steps, not all of them. Worth its own issue if you want it. - **#162 — "You mention plan review here but not for guest"**: split the Guest layer the same way — `tofu plan`, then `tofu apply` under a "Review the plan in full, then:" line — and the prose below now reads "Review the plan in full before every apply, both layers." - **#164 — section name**: renamed `## Before you touch anything` → `## For agents`. - **#166 — "Change Pedro for `a human`"**: Contributing now reads "open a pull request for a human to review — nothing goes directly to `main`. A pull request merges without required approvals."

pit force-pushed hermes/10-readme-goes-thin from 29d5b4635a to 636df594b4

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

Compare

pit merged commit 95b46599d0 into main

2026-10-06 11:54:05 +00:00

pit deleted branch hermes/10-readme-goes-thin

2026-10-06 11:54:05 +00:00

pit referenced this pull request from a commit

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

README goes thin (#10) (#16)

pit referenced this pull request

2026-10-06 11:54:49 +00:00