docs: split README into a leaner top page + topic docs#13
Merged
Conversation
The README had grown to 677 lines, with three sections taking up two-thirds of it. A first-time visitor scrolling for "what is this" or "how do I run it" had to load almost half of a long-form walkthrough they didn't ask for. Three sections move into the existing docs/ directory: - Recipes (335 lines) → docs/recipes.md. The eleven-step product-feed walkthrough plus the quick-reference index. The walkthrough's `[Fields & bindings](#fields--bindings)` link rewrites to `../README.md#fields--bindings` so it still resolves on GitHub. Fixture paths gain `../` prefixes. - Adding a new BareDOM component (75 lines) → docs/adding- components.md. Recipe + what-it-touches + optional polish + how- it-works as a contributor onboarding doc. No relative links needed adjustment. - Project layout (36 lines) → folded into the existing docs/architecture.md before its "Where to read next" outro, alongside the doc references it already lists. The README gains a new `## Docs` section between Features and Authoring shortcuts (the user-chosen TOC strategy), with bulleted links to all four docs/. The Features section's existing pointer into the walkthrough re-targets `docs/recipes.md`. README is now 246 lines (was 677, down 64%). No code changes; gates green for muscle-memory: - cljfmt check — all source files formatted correctly. - npx shadow-cljs compile test — 571 tests, 0 failures. - npx shadow-cljs release app — 0 warnings. - clj-kondo — 0 errors, 0 warnings. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The rule lived as a sub-paragraph inside `PR readiness gate`, which is easy to skim past — and was missed in this very session when the README-split PR went straight from plan-approval to `gh pr create`. Pulling it out into its own top-level section between `PR readiness gate` and `After a PR is merged`, and adding the clauses that close the loopholes I'd been tripping on: - **Plan approval is not PR approval.** Approving a plan via ExitPlanMode authorises writing the code, not opening the PR. - **All-gates-green is not approval.** Cljfmt + tests + release + lint passing means the branch is ready for review, not that the reviewer wants the review request fired right now. - **A previous PR's approval is not blanket approval.** Each PR needs its own go-ahead. - **Auto mode does not override this.** Auto mode is for minimising interruptions on local, reversible work; PR creation is shared-state and explicitly excluded. Plus a clear what-to-do-instead checklist (push the branch first — that's fine — summarise gate results, ask, wait for yes, then run `gh pr create`). Co-Authored-By: Claude Opus 4.7 (1M context) <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
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
The README had grown to 677 lines, with three sections (Recipes,
Adding-a-new-BareDOM-component, Project-layout) taking up two-thirds
of the file. First-time visitors landing on the README for "what
is this" or "how do I run it" had to scroll past almost half of a
long-form walkthrough they didn't ask for.
This PR pulls the deep-dive content into the existing `docs/`
directory (which already houses `architecture.md` and
`plugins.md`) and gives the README a new `## Docs` section
between Features and Authoring shortcuts with one-line pointers to
the four docs.
What moved
What stayed
Marketing hook sections — Why Bareforge?, Features, Authoring
shortcuts (the v0.2.0 highlight), Fields & bindings, Templates,
Status, Quick start, Philosophy, Contributing — plus the new
`## Docs` section. README is now 246 lines (down 64%) while
keeping every user-facing top-of-funnel feature mention.
Link integrity
rewrites to `../README.md#fields--bindings` so it still
resolves on GitHub.
`test/fixtures/export/demo-store-with-bindings.json`) gain a
`../` prefix.
anchor now points at `docs/recipes.md`.
resolve.
Test plan
This is a documentation refactor — no code changes. Standard gates
re-run as muscle memory:
Render-side checks worth doing post-merge:
bullets resolve, all section anchors work.
paths resolve, the back-link to `../README.md#fields--bindings`
jumps to the right anchor.
section sits before "Where to read next".
🤖 Generated with Claude Code