docs: 1.0 release notes, versioning strategy, README for adopters

[MendixMau]

Direct lane

What changed and why (one paragraph):
The repo is going professional, so this adds three things. (1) docs/releases/v1.0.md is the first milestone's release notes, written for a Mendix developer or lead deciding whether to adopt. It covers the themes of 2026-09-30 to 2026-10-14, what each means for you, upgrading, known gaps and credits, and every claim links a CHANGELOG line or PR. (2) A versioning rule, added as docs/RELEASE-PROCESS.md §8 (the single source; the CHANGELOG header now defers to it). Milestones are named train releases; the vYYYY.MM.DD train and bin/cut-release.sh are unchanged, and tags start at 1.0. (3) A README rewrite for newcomers: what it is, how it works, ways to use it, quick start, Make it yours, testing and quality, We need your input, and releases. The old reference material is kept under "Reference", and both generated ROUTING blocks are untouched.

Field evidence: docs only, no instrument changed. Every path named in "Make it yours" was checked on master 31e90ae: templates/company-brain/, bin/init-company-brain.sh, bin/wire-company-brain.sh, init-project.sh --company, .claude/lint-rules-disabled.txt, bin/interview-mode.sh modes and persistence, bin/exec-approval.sh, bin/permission-profile.sh, the bin/wire-agents.sh tool list incl. --with-kiro, and sync touching only the marked blocks of CLAUDE.local.md.

• No client data anywhere in the diff. The whole-word forbidden-name grep over added lines finds 0 hits, and LEAKGUARD_ALLOW_NO_DENYLIST=1 bin/check-no-client-data.sh is clean.
• Size-cap exception (docs restructure). 4 files and about 672 counted lines (excluding CHANGELOG), mostly moved README text. It stays one PR, with the independent reviewer's agreement.
• Test tier: T0, plus scoped fixtures tests/wave2/test-guide-reopen.sh bin/init-project.sh (10/10) and tests/wave2/test-routing-tier.sh bin/render-routing.sh (12/12). Also clean: render-routing.sh --check (baseline 74,995 before and after; README is not counted in the baseline), check-scripts.sh, check-no-private-citations.sh, check-pr-discipline.sh origin/master and check-docs-numbering.sh (no hits in the touched files).
• CHANGELOG.md line under ## Unreleased, credited to MendixMau

Review

The independent review returned MERGE-AFTER-FIX. The fixes landed as a follow-up commit (f279645):

• HIGH, tags. The remote has no tags.
  • The notes now say 1.0 is the first train tag published to GitHub, cut with cut-release.sh at announcement, and that earlier dated CHANGELOG headings were never pushed.
  • README and the notes say sync prints Toolkit release: none tagged yet until tags exist.
  • RELEASE-PROCESS §8 says tags start at 1.0 and uses vYYYY.MM.DD placeholders instead of a concrete tag.
• MEDIUM, pinning. §8 now says the session ritual (pull --ff-only, the "not on master" note) warns while a clone is pinned to a tag, and that this is expected.
• MEDIUM, closed PR links. The notes now say that most linked PRs landed through integration 2026-10-14: nineteen independently reviewed PRs combined for one merge #329 and show as closed.
• LOW, cadence. §8 points to the CHANGELOG header for the train cadence instead of restating it.
• LOW, accuracy:
  • interview-mode.sh --set persists in .claude/.interview-mode; only $CLAUDE_INTERVIEW_MODE is per-session.
  • The lint line now reads "UX001/002 plus Batches 1–4".
  • app-restart.sh is credited to feat(exec): per-project exec lock, --commit-first, watch-compat verdict, scoped app restart, scratch mxcli test #304, and Guard against a leftover mxcli test injection (#244), app-restart pid check and test-scratch takeover (#304 review), lint-a-copy recipe (#240) #322 to the injection refusal it added.
• LOW, known gaps. Added the stale-lock takeover race after a holder is killed mid-takeover (rare; a designed fix and a regression test are owed).

Decisions for the maintainer to confirm

1. Version name "1.0". Proposal: the next bin/cut-release.sh cut becomes 1.0 and is the first tag pushed. The GitHub Release for that tag uses docs/releases/v1.0.md as its body, and a CHANGELOG pointer line is added in that cut's section.
2. Milestone rule (§8). A major is anything that breaks a project without action and needs a Migration section plus a sync path. A change that sync migrates by itself counts as minor. Exit-code or output-format changes are named in the notes even when minor. Deprecations are removed no earlier than the next major.
3. Removed from the README:
   • the "Decision flow" section (now a pointer to query-the-model.md);
   • "Stages 0–4: pure LLM" (duplicated the flow section);
   • "Stage 6: testing", including the stale screenshot-discipline paragraph;
   • the examples/ removal note;
   • the per-skill file tree (now directory level only);
   • "How to add a project-specific learning" (folded into "We need your input");
   • the long doctor --install explanation;
   • "Several other client integration and migration projects" under the renamed "Pipelines".
4. Corrected in the README:
   • the Windows note no longer claims a pgrep concurrency guard (feat(exec): per-project exec lock, --commit-first, watch-compat verdict, scoped app restart, scratch mxcli test #304 made it a per-project lock);
   • "How to add a new skill" now says to add a row to skill-routing.tsv and re-render, not to hand-edit tables.
5. Kept headings that other files cite by name: "Context cost", "Platform support", "When to use which skill", "Baseline routing", "Consuming this toolkit" and "How to add a new skill". Their heading levels went down one step under "Reference".
6. Interview-mode values. The README documents the canonical values (steering/assist/auto, with "alias: unattended" next to auto). The script-side alias fix is a separate PR (fix/interview-mode-aliases).

🤖 Generated with Claude Code

https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw