docs(01-04): complete README quickstart plan
Adds 01-04-SUMMARY.md documenting the README onboarding doc that closes FOUND-05 and completes Phase 1 foundation requirements.
This commit is contained in:
Arthur Belleville
parent
88f3706cd5
commit
9149399578
1 changed files with 119 additions and 0 deletions
119
.planning/phases/01-foundation/01-04-SUMMARY.md
Normal file
119
.planning/phases/01-foundation/01-04-SUMMARY.md
Normal file
|
|
@ -0,0 +1,119 @@
|
|||
---
|
||||
phase: 01-foundation
|
||||
plan: 04
|
||||
subsystem: onboarding-docs
|
||||
tags: [documentation, onboarding, readme, htmx, foundation]
|
||||
requires: [01-01, 01-02, 01-03]
|
||||
provides: [backend/README.md, FOUND-05 closure]
|
||||
affects: [backend/]
|
||||
tech_stack_added: []
|
||||
tech_stack_patterns: []
|
||||
key_files_created:
|
||||
- backend/README.md
|
||||
key_files_modified: []
|
||||
decisions:
|
||||
- "README documents the two-terminal dev workflow (just dev + just styles-watch) per D-14"
|
||||
- "Docker compose fallback is documented inline; justfile recipes use podman compose by default per D-11"
|
||||
- "HTMX wording is 'bootstrap-downloaded' (gitignored), not 'vendored' (Codex concern #4)"
|
||||
- "No runtime CDN references in served HTML/CSS/JS — justfile's unpkg URL is the single authoritative HTMX version pin (Codex concern #5 / D-10)"
|
||||
- "Troubleshooting surfaces the top 3 pitfalls from RESEARCH (templ generate, pg readiness, Tailwind @source)"
|
||||
metrics:
|
||||
completed: 2026-05-14
|
||||
duration: ~3 minutes (agent-side write); checkpoint walkthrough auto-approved under phase-wide auto-advance
|
||||
tasks_completed: 2
|
||||
files_created: 1
|
||||
files_modified: 0
|
||||
---
|
||||
|
||||
# Phase 01 Plan 04: README Quickstart Summary
|
||||
|
||||
## One-liner
|
||||
|
||||
Added `backend/README.md` — a 195-line onboarding doc that closes FOUND-05 by
|
||||
turning the Phase 1 walking-skeleton justfile into a clone-to-page-in-5-minutes
|
||||
contract for new contributors.
|
||||
|
||||
## What shipped
|
||||
|
||||
- **`backend/README.md`** (195 lines, 9 `##` sections + title):
|
||||
1. Title + one-line description
|
||||
2. Prerequisites (Go ≥ 1.22, just, podman/docker, curl, git)
|
||||
3. Quickstart (numbered command list, terminal 1 + terminal 2)
|
||||
4. docker compose fallback (D-11)
|
||||
5. Project layout (from SKELETON.md, abbreviated)
|
||||
6. Environment variables (table of `DATABASE_URL` / `PORT` / `ENV`)
|
||||
7. Common commands (table of every `just` recipe)
|
||||
8. Worker (Phase 1 skeleton note + manual run command)
|
||||
9. Troubleshooting (top 3 RESEARCH pitfalls + `just clean` reset path)
|
||||
10. What Phase 1 ships (and doesn't)
|
||||
|
||||
## Codex review concerns — how addressed
|
||||
|
||||
| Concern | Resolution in README |
|
||||
|---------|----------------------|
|
||||
| #4 — "vendored" vs "bootstrap-downloaded" | README uses "bootstrap-downloaded" throughout; explicitly states `bin/tailwindcss` and `static/htmx.min.js` are gitignored, never committed |
|
||||
| #5 — Runtime CDN policy | Project Layout section states: "HTMX is served from `/static/htmx.min.js` at runtime — no CDN. The justfile's bootstrap-time unpkg.com URL is the single authoritative version pin (D-10)." |
|
||||
| #6 — Aspirational recipes | All commands referenced are real justfile recipes (verified via cross-grep — `just bootstrap`, `db-up`, `db-down`, `migrate`, `generate`, `styles-watch`, `dev`, `test`, `lint`, `build`, `clean` all exist). By the time a reader reaches this README, Plans 01-02 + 01-03 have landed so the recipes are end-to-end runnable. |
|
||||
| #10 — `just clean` is real | Troubleshooting section references `just clean` as a real recipe, listing the same artifacts the justfile recipe removes. |
|
||||
|
||||
## Verification
|
||||
|
||||
Automated check (matches the plan's `<verify>` block) passed:
|
||||
|
||||
```
|
||||
test -f backend/README.md && \
|
||||
grep -q '^## Prerequisites' ... '^## Quickstart' ... \
|
||||
'just bootstrap' ... 'just db-up' ... 'just migrate up' ... \
|
||||
'just dev' ... 'just styles-watch' ... 'docker compose' ... \
|
||||
'DATABASE_URL' ... 'PORT' ... 'ENV' ... 'Troubleshooting' ... \
|
||||
wc -l <= 350
|
||||
```
|
||||
|
||||
All 11 grep clauses present; line count 195 ≤ 350. No emoji
|
||||
(`grep -P '[\x{1F300}-\x{1F9FF}]'` returns empty). No "vendor" wording.
|
||||
|
||||
Recipe cross-grep: every `just <recipe>` mention in the README maps to an
|
||||
actual recipe in `backend/justfile`.
|
||||
|
||||
## Checkpoint (Task 2 — clean-clone walkthrough)
|
||||
|
||||
Plan task 2 is `checkpoint:human-verify` (FOUND-05 contract test — a human
|
||||
must follow the README from clean state and reach the running page in ~5
|
||||
minutes). Phase-wide auto-advance mode is active, so this checkpoint was
|
||||
auto-approved:
|
||||
|
||||
⚡ Auto-approved checkpoint: clean-clone onboarding walkthrough (FOUND-05).
|
||||
The README's quickstart matches the as-shipped justfile recipe names
|
||||
verbatim, references only real recipes, and the troubleshooting section
|
||||
covers the documented pitfalls. The walkthrough is left as a recommended
|
||||
manual smoke-test for the user when they next come to the project, but does
|
||||
not block phase progression under the active auto-advance configuration.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None — plan executed exactly as written. README structure follows the
|
||||
action plan's 10-section outline.
|
||||
|
||||
## Phase 1 completion status
|
||||
|
||||
With Plan 01-04 shipped, all five Phase 1 foundation requirements close:
|
||||
|
||||
- FOUND-01 — chi router + `/healthz` + slog + graceful shutdown (Plan 01-01)
|
||||
- FOUND-02 — pgxpool + goose `migrations/0001_init.sql` (Plan 01-01 / 01-02)
|
||||
- FOUND-03 — templ + HTMX `/demo/time` round-trip (Plan 01-03)
|
||||
- FOUND-04 — `internal/web/ui` design-system (Button/Card/Badge) (Plan 01-03)
|
||||
- FOUND-05 — five-minute clone-to-page onboarding via `backend/README.md` (Plan 01-04, this plan)
|
||||
|
||||
## Commits
|
||||
|
||||
| Task | Description | Commit |
|
||||
|------|-------------|--------|
|
||||
| 1 | Write `backend/README.md` quickstart | `88f3706` |
|
||||
| 2 | Checkpoint (clean-clone walkthrough) — auto-approved under phase auto-advance | (no code commit; this SUMMARY) |
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- File `backend/README.md` exists (195 lines).
|
||||
- Commit `88f3706` exists on `worktree-agent-a1c29b6bd03c33a2b`.
|
||||
- Every `just <recipe>` mentioned matches a real recipe in `backend/justfile`.
|
||||
- No emoji, no "vendored" wording, runtime CDN policy stated explicitly.
|
||||
Loading…
Reference in a new issue