leancraft 0.1.0

package/.leancraft/templates/discovery/02-research.md

@@ -0,0 +1,104 @@
+# 02 — Research — 12 Pain Themes (P1-P12)
+
+> Status: DRAFT — Agent drafts, human verifies quotes. Min 12 themes (no max — add P13-P20 if needed). Sources Inventory holds your 50–100 raw posts — more sources = stronger themes. Validator checks ≥12.
+
+## P1: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P2: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P3: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P4: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P5: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P6: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P7: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P8: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P9: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P10: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P11: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## P12: [Theme]
+
+- **Quote:** "[verbatim]"
+- **Source:** https://... — Date: YYYY-MM-DD — Platform: Reddit/X/HN/G2
+- **Frequency:**
+- **Severity:** high/medium/low
+
+## Sources Inventory (50–100 raw posts — more = stronger)
+
+| # | URL | Platform | Date | Pain |
+|---|---|---|---|---|
+| 1 |  |  |  | P1 |
+| ... |  |  |  |  |
+
+## Synthesis
+
+- Top 3 by frequency:
+
+## Validation
+
+- [ ] P1-P12 headings present (add P13+ if needed — validator checks ≥12)
+- [ ] Each has Quote + URL + Date
+- [ ] ≥12 unique URLs (50–100 recommended)

package/.leancraft/templates/discovery/03-competitive.md

@@ -0,0 +1,27 @@
+# 03 — Competitive Teardown
+
+> REQUIRED: competitors, pricing-table (with $), wedges. Min 9 competitors, min 5 wedges.
+
+## Competitors (9+)
+
+| # | Name | URL | Pricing | Strength | Weakness |
+|---|---|---|---|---|---|
+| 1 | [Competitor 1] | https://... | $X/mo | ... | ... |
+| ... | ... | ... | ... | ... | ... |
+
+## Pricing Table (must have $)
+
+| Competitor | Free | Starter | Pro | Enterprise |
+|---|---|---|---|---|
+|  | $0 | $ | $ | $ |
+
+## Our 7 Wedges (why we win)
+
+1. ...
+2. ...
+
+## Validation
+
+- [ ] ≥9 competitors with URLs
+- [ ] Pricing table has $ values (validator checks `$` or `€` or `£`)
+- [ ] ≥5 wedges

package/.leancraft/templates/discovery/04-personas.md

@@ -0,0 +1,26 @@
+# 04 — Personas — 5 Personas + Affinity Map
+
+> REQUIRED: 5 personas, each with goals/pains/jtbd, plus affinity map. Min 5.
+
+## Persona 1: [Name] — [Role, e.g., Solo Sree, Agency Maria]
+
+- **Demographics:** age, role, tech level
+- **Goals:** ...
+- **Pains:** (link to P# from 02-research.md)
+- **JTBD:** When ... I want ... So ...
+- **Behaviors:** ...
+- **Quote:** "[from research]"
+
+... (Persona 2-5 same structure) ...
+
+## Affinity Map
+
+| Theme | P1 | P2 | P3 | P4 | P5 |
+|---|---|---|---|---|---|
+| Pain X | ● |  | ● |  | ● |
+
+## Validation
+
+- [ ] 5 personas, each has goals/pains/jtbd
+- [ ] Each pain links to P# from 02-research.md
+- [ ] Affinity map present

package/.leancraft/templates/discovery/05-jtbd.md

@@ -0,0 +1,27 @@
+# 05 — JTBD + Empathy Maps + Pain Matrix
+
+> REQUIRED: jtbd-statements, empathy-maps, pain-matrix
+
+## JTBD Statements (per persona)
+
+- **When** [situation] **I want** [motivation] **So I can** [outcome] — Persona: [Name] — Pain: P#
+
+## Empathy Maps (1 per persona)
+
+### Persona: [Name]
+- **Says:** ...
+- **Thinks:** ...
+- **Does:** ...
+- **Feels:** ...
+
+## Cross-Persona Pain Matrix
+
+| Pain | P1 | P2 | P3 | P4 | P5 | Priority |
+|---|---|---|---|---|---|---|
+| P1: ... | 3 | 1 | 3 | 2 | 1 | P0 |
+
+## Validation
+
+- [ ] JTBD present per persona
+- [ ] 5 empathy maps (says/thinks/does/feels)
+- [ ] Pain matrix present

package/.leancraft/templates/discovery/06-prd.md

@@ -0,0 +1,102 @@
+# 06 — PRD — Goals, Flows, Reqs
+
+> REQUIRED: goals, non-goals, user-flows (≥3), functional-reqs (≥10), nfrs, risks, success-metrics, assumptions, stakeholders, raci, pestel, 4-whys, timeline, legal. Lean overview, not 20 pages.
+
+## Goals (P0/P1)
+
+- P0: ...
+- P1: ...
+
+## Non-Goals (explicit)
+
+- Not building: ...
+
+## Success Metrics (North Star + Activation)
+
+| Metric | Target | Source |
+|---|---|---|
+| North Star | ... | 01-vision.md |
+| Activation | ... | 04-personas.md |
+| Retention | ... | 05-jtbd.md |
+
+## Assumptions + Open Questions
+
+| Assumption | How to test | Owner |
+|---|---|---|
+| ... | ... | PM |
+
+## User Flows (≥3, with steps)
+
+### Flow 1: [Name] — Persona: [Name]
+1. User ...
+2. System ...
+3. ...
+
+## Functional Reqs (≥10, testable)
+
+| ID | Req | Persona | Flow | Priority |
+|---|---|---|---|---|
+| FR-01 | As [persona] I can ... | P1 | F1 | P0 |
+
+## NFRs
+
+- Performance: ...
+- Security: ...
+- A11y: WCAG AA
+- i18n:
+
+## Stakeholders / Dependencies (overview)
+
+| Role / System | Person / API | Dependency |
+|---|---|---|
+| ... | ... | ... |
+
+## RACI (light)
+
+| Decision | R | A | C | I |
+|---|---|---|---|---|
+| ... | ... | ... | ... | ... |
+
+## PESTEL (light — 1 line each)
+
+- P:
+- E:
+- S:
+- T:
+- E:
+- L:
+
+## 4 Whys
+
+- Why now:
+- Why us:
+- Why this problem:
+- Why not others:
+
+## Timeline / Milestones (light Gantt)
+
+| Milestone | Target | Owner | Depends on |
+|---|---|---|---|
+| M1 | Wk 4 | Eng | FR-01-05 |
+
+## Legal / Compliance (overview)
+
+- Data / PII:
+- IP / License:
+- Regulatory:
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+|  |  |  |  |
+
+## Validation
+
+- [ ] ≥3 flows with steps
+- [ ] ≥10 FRs with IDs
+- [ ] Success Metrics (North Star + Activation)
+- [ ] Assumptions + Open Questions
+- [ ] RACI, PESTEL, 4 Whys, Timeline, Legal present (overview)
+- [ ] Non-goals listed
+- [ ] NFRs present

package/.leancraft/templates/sprint/map.md

@@ -0,0 +1,23 @@
+# Sprint — Map (Day 1)
+
+> Design Sprint Day 1 — Human owns, agent READ-ONLY
+
+## How-Might-We
+
+- HMW ...
+
+## Target
+
+- Persona:
+- Moment:
+- Success metric:
+
+## Map (user journey)
+
+1. ...
+2. ...
+
+## Validation
+
+- [ ] HMW present
+- [ ] Target has persona + metric

package/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "leancraft": {
+      "command": "node",
+      "args": ["./scripts/mcp-server.mjs"],
+      "env": {},
+      "description": "Leancraft doc-first guardrails — enforces human READ-ONLY, registry, budget, proposals"
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,70 @@
+# AGENTS.md — Leancraft Doc-First Repo
+
+> This file is auto-read by Claude Code, Opencode, Cursor. Do not skip.
+
+You are in a **Leancraft** repo. This is a doc-first, human-owned system. Your job is to draft, not decide. Human locks, you propose.
+
+## MANDATORY READ SEQUENCE (every run, no exceptions)
+
+1. `.leancraft/config.json` — the registry. `locked`, `docRegistry`, `budget`, `researchMap`. This is law.
+2. `.leancraft/human/discovery/00-index.md` → `00-overview.md` → target doc
+3. `.leancraft/human/definition/intent.md` + `guardrails.md` — invariants + security rules you MUST obey
+4. `.leancraft/agent/context.md` — 500-line compressed memory (anti context-rot)
+5. Template in `.leancraft/templates/**` for the doc you are about to write
+
+If any `human/**` is `DRAFT` or missing, **do not code**. Draft docs first, run `validate`, then ask to Lock.
+
+## OWNERSHIP — HARD RULES
+
+- `human/**` — READ-ONLY when `locked:true`. NEVER call `write`/`edit` on it. To change it, write `agent/proposals/NNN-<target>.md` with `Source, Why, Diff` and ask `[🔓 Unlock / ❌ Don't]`. Hook will reject direct edits.
+- `agent/**` — You own. Keep `context.md` + `status.md` updated. Max 500 lines for `context.md`.
+- `joint/**` — Append only, cite `source doc + line`.
+
+## REGISTRY IS TIGHT — NO HALLUCINATION
+
+- You may ONLY create docs listed in `config.json.docRegistry`. Do not invent `13-future.md`.
+- Each doc has `required sections` + `min counts`. `validate` will block Lock if you miss one.
+- **Never hallucinate URLs, quotes, or pricing.** Every quote in `02-research.md` needs verbatim `Quote + URL + Date + Platform` that is fetchable. Every competitor in `03-competitive.md` needs real URL + pricing with `$`. `validate` checks counts; human checks truth.
+
+## RESEARCH MAP — WHAT TO SEARCH PER DOC (type, not tool name)
+
+Your `web_search` may be `tavily_search`, `exa_search`, `brave_search`, or `WebSearch` — any counts. Your `web_fetch` may be `firecrawl`, `exa_fetch`, `WebFetch`, or `fetch` — any counts. Match by **type**, not name.
+
+| Doc | Search / Derive | Type Needed | Examples | What to compile |
+|---|---|---|---|---|
+| `02-research.md` | Search `{idea} pain, {idea} reddit, {idea} alternative, {idea} complaint` on Reddit/X/HN/G2 | `web_search` + `web_fetch` | Tavily/Exa/Brave/WebSearch + Firecrawl/Exa_Fetch/WebFetch | 12 pains P1-P12, each with Quote + URL + Date |
+| `03-competitive.md` | Search `{idea} vs, {idea} alternative, {idea} pricing` | `web_search` | Tavily/Exa/Brave/WebSearch | 9+ competitors with URL + pricing table ($), 5+ wedges |
+| `04-personas.md` | **DERIVE FROM `02-research.md` P# ONLY** — no new search | — | — | 5 personas, each pain links to P#, + affinity map |
+| `05-jtbd.md` | **DERIVE FROM `02,03,04`** | — | — | JTBD per persona + empathy maps + pain matrix |
+| `06-prd.md` | **DERIVE FROM `02,04,05`** | — | — | ≥3 flows, ≥10 FRs (FR-01...), NFRs, risks |
+| `intent.md` | **DISTILL FROM `06-prd.md`** | — | — | ≥3 invariants (I1:) with Check command + ≥2 oracles |
+| `system.md` | **DISTILL FROM `06,02`** | repo scan | — | Pinned stack + architecture + decisions |
+| `guardrails.md` | **DISTILL FROM `system.md`** | — | — | Security/perf/a11y/i18n with Check commands |
+| `features/*.md` | **1 per flow from `06-prd.md`** — `042-kebab-case.md` | — | — | Invariants + oracles + acceptance + Source Trace |
+
+**If you have no tool of that type:** STOP. Do NOT invent. Write to `agent/status.md`: `BLOCKED: No web_search available — human must provide 02-research.md or connect a search connector (Tavily/Exa/Brave)` and append to `joint/decisions.log.md`. Ask human directly in chat. Also log: `Inform user in chat + docs that web search is unavailable and human must paste research or enable a connector.`
+
+**Anti-hallucination:** If your `web_search` returns 0 results, say so in `status.md`, do not invent. For `04,05,06,intent` you MUST cite `P#`/`FR-#` — inventing a new pain is a failure.
+
+## ONE DOC PER FEATURE — HARD RULE
+
+- `human/definition/features/` — `NNN-kebab-case.md` (e.g., `042-pdf-export.md`), 1 per flow from `06-prd.md`.
+- Each feature doc has `intent, invariants (with Check), oracles, acceptance, Source Trace: FR-# + Persona`.
+- Do not put 2 features in one doc. Do not create a feature doc before `06-prd.md` has that flow. `validate` will warn if feature has no trace.
+
+## DEFINITION OF DONE — BEFORE CLAIMING DONE
+
+- [ ] `npm run leancraft:validate` → PASS (no TODO, all sections, min counts, URLs)
+- [ ] No fabricated URLs, quotes, or test results
+- [ ] `npm run leancraft:sync` → `agent/context.md` + `status.md` updated, `ledger.jsonl` appended
+- [ ] If `locked`, you did NOT edit `human/**`
+- [ ] Teach-back ready: you can explain invariant + why without reading code
+
+Never claim `done` while `validate` is red. Never fabricate.
+
+## BUDGET & SANDBOX
+
+- Max $5, 25 calls, 30 min. Network `deny-all` except `allowlist` in `.leancraft/config.json` (default: `registry.npmjs.org`, `registry.yarnpkg.com`, `pypi.org` — covers `npm`/`pnpm`/`bun`/`npx`, they all use the same registry). Never read `.env`, `DATABASE_URL`, `GITHUB_TOKEN` is read-only.
+- **Non-tech: you never edit allowlist manually.** Agent detects needed hosts from `system.md` / `package.json` / network error, then asks you in chat: `[Allow api.stripe.com? / Deny]` + writes a proposal to `agent/proposals/`. You click Allow → agent updates `config.json` for you. No manual JSON edit.
+
+Full skill: `.claude/skills/leancraft/SKILL.md` + `.leancraft/config.json`

package/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md — Leancraft
+
+Read `AGENTS.md` — it is the single source of truth for this repo. Then read `.leancraft/config.json` + `.leancraft/human/discovery/00-index.md` + `.leancraft/human/definition/intent.md` + `.leancraft/human/definition/guardrails.md` + `.leancraft/agent/context.md` before any action.
+
+You are in doc-first mode. Human owns `human/**` when locked. You own `agent/**`. See AGENTS.md for registry, research map, and definition of done.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sree-pm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# Leancraft - Doc-First Verified Agency
+
+> Stop vibe coding. Start owning.
+
+**Leancraft is a doc-first scaffold that locks human intent and leashes agentic coding.** Your agent can draft 12 pains, 5 personas, 50 reqs — but it cannot ship until `validate` passes and you click Lock. After Lock, `human/**` is read-only; agent must propose.
+
+Fixes the 25 vibe-coding failures (62% vulns, 9-sec DB wipes, 19% slowdown, context rot) with one `npx` install.
+
+[![npm version](https://img.shields.io/npm/v/leancraft)](https://www.npmjs.com/package/leancraft) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Why
+
+Vibe coding: `Prompt → Code → Hope`. Leancraft: `Doc (locked) → Bounded Agency → Verification → Code is projection`.
+
+- **Tight registry:** 13 docs with required sections + min counts (12 pains P1-P12, 9 competitors + $, 5 personas, 3 flows + 10 FRs). `validate` blocks Lock if you miss one.
+- **Ownership:** `human/**` 🔒, `agent/**` 🤖 auto, `joint/**` 👥. Hook rejects agent writes to `human/**`.
+- **Anti-hallucination:** Research map per doc — `02-research` must `web_search + web_fetch` (Tavily/Exa/Brave/WebSearch + Firecrawl/Exa_Fetch/WebFetch — any counts) on Reddit/X/HN/G2, each pain needs `Quote + URL + Date`. `03-competitive` needs real pricing with `$`.
+- **One doc per feature:** `human/definition/features/042-kebab-case.md` — 1 per flow from PRD.
+
+## Install — 1 Command
+
+```bash
+npx leancraft init
+# scaffolds .leancraft/ + skills + hooks + .mcp.json
+```
+
+Or with npm:
+
+```bash
+npm install -D leancraft
+npx leancraft init
+```
+
+## Quickstart (first idea)
+
+```bash
+# 1. Agent drafts docs (first time, unlocked)
+# Prompt your agent: "Bootstrap from idea: Infonaut — $10/mo infobots for solo founders"
+
+# 2. Human reviews, then:
+npx leancraft validate   # must PASS (no TODO, all sections, min counts, URLs)
+npx leancraft lock       # 🔒 human owns, agent read-only
+
+# 3. Agent now codes
+# Agent reads .leancraft/human/definition/intent.md + guardrails.md + agent/context.md
+# Needs change? → writes agent/proposals/NNN-*.md → asks [🔓 Unlock / ❌ Don't]
+
+# 4. Keep in sync
+npx leancraft sync       # also auto on git commit
+
+# Unlock if you must:
+npx leancraft unlock
+```
+
+## Repo Layout After `init`
+
+```
+.leancraft/
+├── config.json                         ← Registry: which docs, sections, budget, lock
+├── human/                              ← 🔒 HUMAN-OWNED — agent READ-ONLY
+│   ├── discovery/ 00-index, 00-overview, 01-vision, 02-research, 03-competitive, 04-personas, 05-jtbd, 06-prd
+│   ├── definition/ intent.md, system.md, guardrails.md, features/*.md
+│   └── sprint/ map.md
+├── agent/                              ← 🤖 AUTO — human READ-ONLY
+│   ├── context.md (500 lines, compressed memory)
+│   ├── status.md (live tracker)
+│   └── proposals/ (agent's PRs to human)
+└── joint/ decisions.log.md + ledger.jsonl + test-report.md
+```
+
+See `.leancraft/README.md` for the full map. Templates live in `.leancraft/templates/**`.
+
+## Agentic Tools — How To Connect
+
+Leancraft works with any agent. Pick yours — same `init`, same docs.
+
+### Claude Code
+
+```bash
+npx leancraft init
+# Skills auto-installed to .claude/skills/leancraft/SKILL.md + CLAUDE.md + AGENTS.md
+# Claude Code reads AGENTS.md on every run automatically
+# MCP: uses .mcp.json (leancraft mcp server)
+```
+
+Verify: open Claude Code, type `/skills` → `leancraft` should appear.
+
+### Cursor
+
+```bash
+npx leancraft init
+# Rule auto-installed to .cursor/rules/leancraft.mdc (alwaysApply: true)
+# Cursor reads it on every chat automatically
+```
+
+Also add MCP: Cursor Settings → Features → MCP → Add server → `node ./scripts/mcp-server.mjs` or point to `.mcp.json`.
+
+### Opencode
+
+```bash
+npx leancraft init
+# Skill auto-installed to .opencode/skills/leancraft/SKILL.md
+# Opencode reads AGENTS.md at root automatically
+```
+
+### Windsurf / Codex / Cline
+
+Any agent that reads `AGENTS.md` at repo root works out of the box. For MCP:
+
+```bash
+# .mcp.json is scaffolded. Point your agent's MCP config at:
+node ./scripts/mcp-server.mjs
+# Tools: leancraft_read_intent, leancraft_get_context, leancraft_propose_change, leancraft_validate
+```
+
+### GitHub Copilot / VS Code
+
+Works as file-based guardrails — no MCP needed. Copilot reads `AGENTS.md` + `.leancraft/human/definition/intent.md` via workspace context. For best results, add `#file:.leancraft/human/definition/intent.md` to your prompt.
+
+### Generic (any agent)
+
+1. Ensure `AGENTS.md` at repo root exists (scaffolded by `init`)
+2. Ensure `.leancraft/config.json` exists — it is the contract
+3. Agent's first prompt should be: `Read AGENTS.md and .leancraft/config.json, then bootstrap discovery per registry`
+
+## MCP
+
+```bash
+npx leancraft mcp   # prints .mcp.json snippet
+```
+
+`scripts/mcp-server.mjs` exposes:
+
+- `leancraft_read_intent` — must call first (returns intent + guardrails + budget + registry)
+- `leancraft_get_context` — compressed 500-line memory (anti context-rot)
+- `leancraft_propose_change` — write to `agent/proposals/` when locked
+- `leancraft_validate` — run registry checks
+
+Add to your agent's MCP config:
+
+```json
+{ "mcpServers": { "leancraft": { "command": "node", "args": ["./scripts/mcp-server.mjs"] } } }
+```
+
+## CLI
+
+```bash
+npx leancraft --help
+npx leancraft init [--force]
+npx leancraft validate
+npx leancraft sync
+npx leancraft lock
+npx leancraft unlock
+npx leancraft status
+npx leancraft mcp
+```
+
+## Validation
+
+```bash
+npm run leancraft:validate  # or npx leancraft validate
+# Checks: required docs + required sections + min counts (12 pains, 9 competitors, 5 personas, 10 FRs, 3 invariants) + URLs + no TODO
+# Exit 0 = PASS → Lock allowed, 1 = FAIL → Lock blocked
+```
+
+## Cost & ROI — Dogfooded
+
+> Doc overhead is `3.2k` tokens/read (`~$0.01`), `30–40k` one-time to draft 13 docs. Per feature it saves `~10k` tokens & `~0.7h` after 2 features — measured on this repo itself (`45k chars / 11.3k tokens` total on disk, `3.2k` per run, 2026-08-30).
+
+Assumptions: Claude pricing ($3/$15 per 1M), 1 feature = `10k` gen + `15k` debug vibe vs `13k` doc-first. Based on METR -19% slowdown without context and GitClear 41% churn. Your stack will vary — track `joint/ledger.jsonl` $/feature and `agent/status.md` time to verify. PR your numbers — we publish community ROI.
+
+## Ownership
+
+- `human/**` — READ-ONLY when `locked:true` (see `.github/CODEOWNERS`, `.git/hooks/pre-commit`). Agent must propose.
+- `agent/**` — Agent owns, auto-generated
+- `joint/**` — Both append
+
+## Contributing
+
+See `CONTRIBUTING.md`. Run `npm run leancraft:validate` before PR.
+
+## License
+
+MIT — see `LICENSE`.
+
+## Roadmap
+
+- `leancraft import notion --url <url>` — import PM docs into `human/discovery/`
+- `leancraft validate --fetch` — firecrawl URL fetch check (hallucination guard)
+- Semgrep + axe + CodeQL wiring in `leancraft:security`