docs(readme): revamp — audience-first structure#61
Merged
Conversation
…tation tree Lead with "Who Bonsai is for" (solo devs + small teams) and show mechanism over personality — hook events, protocol file paths, checklist locations. Add station/ tree snippet as the "what you actually get" visual. Merge the old "Why Bonsai" layer stack and "What's Inside" into a single "How it works" section. Reserve a logo slot via HTML comment. Drop the standalone Documentation and Contributing sections — both roll into the footer nav. Plan: station/Playbook/Plans/Active/25-readme-revamp.md
5 tasks
LastStep
added a commit
that referenced
this pull request
Apr 22, 2026
* docs(audit): pre-release P0+P1 fixes for v0.2.0 cut
P0 — block-launch fixes:
- website + README: sensor count 12 → 13 (compact-recovery row already present in
sensors.mdx but headers stale; ran website/scripts/generate-catalog.mjs to sync
catalog.json + overview.mdx + sensors.mdx description; manual README:158 fix)
- tagline mechanical replace ("structured language" → "workspace") in
index.mdx (description+tagline+body), astro.config.mjs (description),
why-bonsai.mdx (body) — matches README PR #61 audience pivot
- strip invalid agent types from meta.yaml: review-checklist drops `reviewer`,
test-strategy drops `qa` (neither agent type exists; backlog Group D notes
these as unbuilt — leaks reduce to real types only)
P1 — should-fix:
- LICENSE: copyright 2025 → 2025-2026
- README + CONTRIBUTING: Go 1.24+ → 1.25+ (matches go.mod 1.25.0 / toolchain 1.25.8)
- station/CLAUDE.md.bak deleted (gitignored, no diff — Plan 01 marker migration leftover)
- Plans/Archive/23-uiux-phase2-add.md frontmatter: Status: Draft → Complete
Verification:
- make build clean
- go test -count=1 ./internal/catalog/ ./internal/generate/ pass
- npm run build (Starlight): 45 pages, all internal links valid
Plan 26 candidates filed (deferred from this PR per Q3=C scope):
- full website concept-page rewrite (heavier framing pivot beyond mechanical tagline)
- skills frontmatter convention decision (13 of 17 skills lack it; loader treats as
cosmetic, but worth canonical decision before mass apply)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* docs(code-index): refresh post Plan 22+23 — line drift + flow stages
Update station/code-index.md against current source after the
init/add cinematic redesigns landed and add_redesign.go was deleted:
- Drop entries for cmd/add_redesign.go (deleted Plan 23 Phase 3).
- Repoint init runner to cmd/init_flow.go (renamed from init_redesign.go).
- Refresh line numbers across catalog, generate, styles, prompts,
config/lockfile, cmd/{root,add,remove}.go.
- Add new sub-tables for the harness, initflow, and addflow packages
so the index covers the cinematic flow surface area at the same
granularity as the rest of the index.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* docs(readme): clarify why docs/ exists alongside website/
Pre-launch audit flagged that a contributor browsing the repo could
not tell why docs/ and website/ both exist. Rewrite docs/README.md
to spell out the relationship: docs/ is the embedded terminal-friendly
subset served by `bonsai guide`; website/ is the Starlight expanded
reference. Note the two must move together when a concept changes.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* docs(changelog): cut v0.2.0 entry covering Plans 19-25
Curated entries grouped per keep-a-changelog: Added (cinematic
init/add flows, statusline, compact-recovery sensor, trigger
metadata, Starlight site, multi-topic guide, RenderFileTree),
Changed (BubbleTea harness foundation, README rewrite, palette
refresh, CI widened to push: main, Go 1.25.8, golangci-lint v2),
Removed (BONSAI_REDESIGN + BONSAI_ADD_REDESIGN env gates, three
orphan guide topics), Fixed (Plan 19 OSS-blocker sweep, Planted
path, chmod-on-unchanged, .bak silent-discard), Security (CodeQL
+ govulncheck + Dependabot + Astro CVE).
Also fix v0.1.0-0.1.3 dates from 2026-04-15 to 2026-04-16 to match
git tag creator dates, switch the new v0.2.0 separator from em-dash
to hyphen per keep-a-changelog convention, and rewire the
[Unreleased] / [0.2.0] link references at the bottom.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Audience-first README rewrite. Leads with "Who Bonsai is for", swaps abstract framing ("structured language") for a concrete outcome tagline, and adds the
station/tree snippet that answers the "what do I actually get?" objection up front.Plan:
station/Playbook/Plans/Active/25-readme-revamp.mdChanges
README.md— full rewrite per Plan 25:<div>, no broken GitHub gap).A structured language for working with AI agents.→A workspace for your coding agent.status-early-stageshield badge.## How it works.## Why Bonsai— layer-stack diagram moves to## How it works.## Who Bonsai is for— audience hook, problem framing, 5 mechanism bullets (bold lead word + concrete file reference), "Not just CLAUDE.md with extra steps" rebuttal,station/tree snippet.## What's Inside(agent types, catalog, extensible) into## How it works.## Documentationand## Contributingas standalone sections — roll into the footer nav row.station/Playbook/Plans/Active/25-readme-revamp.md— new Tier 1 plan.Plan
See
station/Playbook/Plans/Active/25-readme-revamp.mdfor full step list and verification checklist.Verification
station/tree matchesbonsai initdirs (Playbook/,Logs/,Reports/,agent/Core/,agent/Protocols/,agent/Skills/,agent/Workflows/,agent/Sensors/,agent/Routines/).## Why Bonsai,## Documentation,## Contributingno longer standalone.assets/demos/init.gif,docs/assets/graph-view.png).No code touched — CI lint/test should stay green.
Process note
Proposed structure was reviewed by an independent research agent (general-purpose) before drafting. All high-impact findings adopted: mechanism-over-personality bullet rewrite,
station/tree snippet inclusion, "CLAUDE.md with extra steps" rebuttal, footer consolidation, tagline replacement, boilerplate phrase excisions.