@dzhechkov/p-replicator 1.3.0 → 1.5.3

package/README.md

@@ -1,34 +1,357 @@
 # @dzhechkov/p-replicator
 
-**P-Replicator** — Claude Code toolkit for AI-assisted product development (Vibe Coding).
+> **Claude Code toolkit for AI-assisted product development (Vibe Coding).**
+> Transform a product idea — or an existing project — into fully documented,
+> validated, toolkit-equipped code with a 5-phase SPARC pipeline.
+
+[![npm version](https://img.shields.io/npm/v/@dzhechkov/p-replicator.svg)](https://www.npmjs.com/package/@dzhechkov/p-replicator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg)](https://nodejs.org)
+
+**Quick links:** [npm](https://www.npmjs.com/package/@dzhechkov/p-replicator) · [GitHub](https://github.com/dzhechko/pu-unicorn-replicate) · [Issues](https://github.com/dzhechko/pu-unicorn-replicate/issues) · [Telegram](https://t.me/llm_notes)
+
+## Documentation in your language
+
+- 🇷🇺 [Документация на русском](./README/ru/README.md) — 8 разделов (~3000 строк)
+- 🇬🇧 [English documentation](./README/eng/README.md) — 8 sections (~3000 lines)
+- 🌐 [Interactive HTML guide (RU)](./README/ru/html/index.html) — single-page with search, theming, syntax highlighting
+
+This README is **comprehensive and self-contained** — covers ~95% of what most users need. For deep dives (architecture internals, full troubleshooting, formal API schemas) see the eng/ folder.
+
+---
+
+## Table of Contents
+
+- [What is p-replicator?](#what-is-p-replicator)
+- [Quick Start](#quick-start)
+- [Already have technical documentation?](#already-have-technical-documentation)
+- [Adding features to an existing project (Mode 2)](#adding-features-to-an-existing-project-mode-2)
+- [Installation](#installation)
+- [What Gets Installed](#what-gets-installed)
+- [Verify the install](#verify-the-install)
+- [Pipeline overview — `/replicate` phases](#pipeline-overview--replicate-phases)
+- [Skills Reference](#skills-reference)
+- [Commands Reference](#commands-reference)
+- [CLI Commands](#cli-commands)
+- [Validation Cycle Details](#validation-cycle-details)
+- [Feature Lifecycle — `/feature` command](#feature-lifecycle--feature-command)
+- [Statusline Dashboard](#statusline-dashboard)
+- [Hooks System](#hooks-system)
+- [Roadmap & Insights](#roadmap--insights)
+- [Architecture Highlights](#architecture-highlights)
+- [Configuration](#configuration)
+- [Update workflow](#update-workflow)
+- [Troubleshooting](#troubleshooting)
+- [Migration](#migration)
+- [Test Infrastructure](#test-infrastructure)
+- [Known Limitations](#known-limitations)
+- [Changelog Highlights](#changelog-highlights)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## What is p-replicator?
+
+`@dzhechkov/p-replicator` installs a ready-made `.claude/` toolkit into any project: **11 slash commands**, **10 skills**, **4 agents**, **5 rules**, **6 hook scripts**, and a `settings.json` with pre-configured hooks and a multi-line statusline dashboard.
+
+The flagship `/replicate` command takes a project through a **5-phase pipeline**:
 
-Transform a product idea into a fully documented, validated, toolkit-equipped project ready for development.
+```
+Phase 0 (optional)    Product Discovery     reverse-engineering of similar companies
+Phase 1               Planning              11 SPARC documents (PRD, Architecture, Pseudocode, ...)
+Phase 2               Validation            5-agent swarm validates against INVEST + SMART
+Phase 3               Toolkit Generation    project-specific agents, rules, skills
+Phase 4               Finalize              docker-compose.yml, Dockerfile, .gitignore + git commit
+```
+
+Plus **`/feature`** for adding new features to a project with the same SPARC-mini validation cycle, **`/run --feature-branches`** for autonomous batch builds with per-feature git branches, **`/harvest`** for extracting reusable patterns into a knowledge base, and 8 more commands (`/start`, `/plan`, `/go`, `/next`, `/myinsights`, `/docs`, `/deploy`, `/feature-ent`).
+
+**Two main use cases:**
+
+| Use case | Entry command | Time | Result |
+|---|---|---|---|
+| **Bootstrap a new project** from idea or company name | `/replicate` | 45–90 min | Fully-documented project + scaffold + Docker |
+| **Add features** to an existing project | `/feature` (Mode 2) | 10–30 min per feature | Validated SPARC docs + implementation + review |
+
+**Target architecture for generated projects:**
+- **Pattern:** Distributed Monolith (Monorepo)
+- **Containers:** Docker + Docker Compose
+- **Infrastructure:** VPS (e.g., AdminVPS, HOSTKEY)
+- **Deploy:** Docker Compose direct deploy
+- **AI Integration:** MCP servers
+
+---
 
 ## Quick Start
 
 ```bash
-# Install into any project
+# 1. Install in any project
+cd your-project
 npx @dzhechkov/p-replicator init
 
-# Open Claude Code
+# 2. Open Claude Code
 claude
 
-# Run the pipeline
+# 3. Run the pipeline
 /replicate "Online marketplace for handmade crafts with AI-powered recommendations"
 ```
 
-The system walks you through 4-5 phases with interactive checkpoints. At each checkpoint you review the output and confirm before proceeding. Estimated time: 45-90 minutes for the full pipeline.
+The system walks you through 4–5 phases with interactive checkpoints. At each checkpoint you review the output and confirm before proceeding.
+
+**Estimated time:** 45–90 minutes for the full pipeline (Phase 0 optional).
+
+After `/replicate` completes:
+- `/start` — bootstrap the scaffold from `Architecture.md`
+- `/run mvp` — autonomous feature build from roadmap
+- `/feature <id>` — single-feature lifecycle
+
+---
+
+## Already have technical documentation?
+
+If you already have tech specs, architecture notes, or API docs for the project, you can skip Phase 0 (Product Discovery) and feed your existing docs into Phase 1 as input:
+
+```bash
+mkdir -p docs/existing
+cp your-tech-doc-*.md docs/existing/   # place your existing docs here
+
+claude
+/replicate "Use my existing docs in docs/existing/, skip Phase 0"
+```
+
+**Three sub-paths:**
+
+| Path | When | Result |
+|---|---|---|
+| **A. Full pipeline** | Have tech docs, want full pipeline + toolkit + scaffold | All 11 SPARC docs + validation + toolkit + scaffold |
+| **B. SPARC docs only** | Want only the 11 SPARC docs | Invoke `sparc-prd-mini` skill in AUTO mode |
+| **C. Validation-only** | Existing docs already SPARC-shaped | Rename to `PRD.md`, `Architecture.md`, ... + invoke `requirements-validator` |
+
+**Modified flow when triggered:**
+- **Phase 0** — SKIPPED entirely
+- **Phase 1** — `sparc-prd-mini` runs in **AUTO mode**, reads your docs, generates the 11 SPARC slots; missing parts marked `[GAP: ...]`
+- **Phase 2-4** — unchanged
+
+Full recipe: see [User Guide](./README/eng/02_user_guide.md#starting-from-existing-tech-docs) ([RU](./README/ru/02_user_guide.md#альтернативный-вход-у-вас-уже-есть-техдокументация)).
+
+---
+
+## Adding features to an existing project (Mode 2)
+
+If you already have a working project (stack, PRD, CLAUDE.md, Specification defined) and want to **add new features** with the same SPARC-mini validation cycle that `/replicate` provides — use `/feature` (Mode 2):
+
+```bash
+cd existing-project
+npx @dzhechkov/p-replicator init      # idempotent — preserves CLAUDE.md
+claude
+/feature add-stripe-payments          # 4-phase: PLAN → VALIDATE → IMPLEMENT → REVIEW
+```
+
+`/feature` runs the same validation pipeline as `/replicate` Phase 2, scoped to a single feature. Same verdicts: 🟢 READY (≥70) / 🟡 CAVEATS (50–69) / 🔴 NEEDS WORK (<50). Same retry logic. Same `brutal-honesty-review` post-implementation.
+
+**Two officially supported entry modes for `/feature`:**
+
+| Mode | When | Pre-conditions |
+|---|---|---|
+| **Mode 1: Post-/replicate** | Project bootstrapped via `/replicate` | CLAUDE.md, docs/, scaffold all generated by /replicate |
+| **Mode 2: Existing project** | Working project, adding features with verification | `init` ran on top of existing project; CLAUDE.md already exists |
+
+**Three sub-paths for Mode 2:**
+
+| Path | When | Skills invoked |
+|---|---|---|
+| **A. /feature directly** | Single feature ≥4 files, new capability | sparc-prd-mini → requirements-validator → parallel implement → brutal-honesty-review |
+| **B. /go auto-router** | Mixed complexity | Routes between /plan (≤3 files) and /feature (≥4 files) |
+| **C. Direct skill invocation** | Only validation cycle | requirements-validator + brutal-honesty-review skills directly |
+
+**Mode 2 setup (one-time):**
+
+```bash
+# 1. Install (idempotent — does NOT touch CLAUDE.md or existing .claude/ files)
+npx @dzhechkov/p-replicator init
+npx @dzhechkov/p-replicator verify
+
+# 2. Normalize SPARC paths (one-time)
+mv docs/your-prd.md   docs/PRD.md
+mv docs/your-spec.md  docs/Specification.md
+mv docs/your-arch.md  docs/Architecture.md
+
+# 3. (Optional) feature-roadmap for batch mode via /run
+cat > .claude/feature-roadmap.json << 'EOF'
+{"features": [{"id": "stripe-payments", "title": "Stripe", "priority": "mvp", "status": "planned"}]}
+EOF
+```
+
+**Mode 2 caveats:**
+- DO NOT run `/start` — it expects a fresh scaffold
+- `/feature-ent` unavailable in Mode 2 without DDD/ADR/C4 docs
+- Auto-commit hooks may conflict with custom git workflows — edit `settings.json` after `init`
+- No `--prd-path` flag for non-standard paths — one-time rename/symlink required (see [KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md) M3)
+
+Full recipe: see [User Guide](./README/eng/02_user_guide.md#feature-workflow-in-an-existing-project-mode-2) ([RU](./README/ru/02_user_guide.md#feature-workflow-в-существующем-проекте-mode-2)).
+
+---
+
+## Installation
+
+### Prerequisites
+
+- **Node.js** ≥ 16.0.0
+- **Claude Code** installed (CLI or web)
+- **Git** initialized in the project (`git init` if not already)
+- **Docker + Docker Compose** (needed for `/start` Phase 3, optional for `/feature`)
+
+### Install command
+
+```bash
+cd your-project
+npx @dzhechkov/p-replicator init
+```
+
+This creates:
+
+- `.claude/skills/` — 10 pre-shipped skills
+- `.claude/commands/` — 11 slash commands (`/replicate`, `/run`, `/feature`, ...)
+- `.claude/agents/` — 4 pipeline agents
+- `.claude/rules/` — 5 governance rules
+- `.claude/hooks/` — 6 cross-platform Node scripts
+- `.claude/settings.json` — hooks + statusline configuration
+- `.p-replicator.json` — install manifest
+
+**Idempotency:** `init` will NOT overwrite existing files without `--force`. Your `CLAUDE.md`, custom commands, and modified settings are preserved.
+
+### Common install scenarios
+
+| Scenario | Command |
+|---|---|
+| Fresh project | `npx @dzhechkov/p-replicator init` |
+| Existing project (preserve all custom files) | `npx @dzhechkov/p-replicator init` (idempotent — same as fresh) |
+| Upgrade (preserve user customizations) | `npx @dzhechkov/p-replicator@latest update` |
+| Repair broken install | `npx @dzhechkov/p-replicator init --force` |
+| Full reset (loses custom hooks) | `npx @dzhechkov/p-replicator init --force --reset-settings` |
+| Preview without writing | `npx @dzhechkov/p-replicator init --dry-run` |
+
+---
 
 ## What Gets Installed
 
 | Component | Count | Description |
 |-----------|-------|-------------|
 | **Skills** | 10 | 90+ files (~200K chars). Modular architecture: foundation → composite → master orchestrator |
-| **Commands** | 2 | `/replicate` (full pipeline), `/harvest` (knowledge extraction) |
-| **Agents** | 4 | replicate-coordinator, product-discoverer, doc-validator, harvest-coordinator |
-| **Rules** | 2 | replicate-pipeline (phase constraints), skill-interface-protocol (composition standard) |
+| **Commands** | 11 | `/replicate`, `/harvest`, `/start`, `/plan`, `/feature`, `/go`, `/run`, `/next`, `/myinsights`, `/docs`, `/deploy` |
+| **Agents** | 4 | `replicate-coordinator`, `product-discoverer`, `doc-validator`, `harvest-coordinator` |
+| **Rules** | 5 | `replicate-pipeline`, `skill-interface-protocol`, `git-workflow`, `insights-capture`, `feature-lifecycle` |
+| **Hooks** | 6 | `session-insights`, `autocommit-{roadmap,insights,plans}`, `statusline`, `state-update` (cross-platform Node) |
+| **Settings** | 1 | `settings.json` with statusLine + SessionStart + Stop hooks pre-configured |
+
+After running `/replicate`, the toolkit also generates **project-specific** artifacts:
+
+- `.claude/agents/planner.md`, `code-reviewer.md`, `architect.md` (project-aware)
+- `.claude/rules/security.md`, `coding-style.md`, `testing.md`, optionally `secrets-management.md`
+- `.claude/skills/project-context/`, `coding-standards/`, optionally `security-patterns/`
+- `.claude/feature-roadmap.json` (from PRD MVP scope)
+- `CLAUDE.md` enhanced with project-specific content
+- `DEVELOPMENT_GUIDE.md`, project `README.md`
+- `docker-compose.yml`, `Dockerfile`, `.gitignore` (Phase 4 scaffolds)
+- `docs/*` — all SPARC documentation (11 files)
+
+---
+
+## Verify the install
+
+After `/replicate`, run:
+
+```bash
+npx @dzhechkov/p-replicator verify
+```
+
+The command checks:
+
+- **Pre-shipped contract** (must-have): 10 skills + 11 commands + 4 agents + 5 rules + settings.json + 6 hooks
+- **Post-/replicate hints** (advisory): CLAUDE.md, project-specific agents, feature-roadmap.json, security rules, etc.
+
+**Exit codes:**
+- `0` — pre-shipped contract intact (warnings about project-specific are normal pre-/replicate)
+- `1` — pre-shipped contract violated → run `init --force` to repair
+
+**Alternative — health check:**
+
+```bash
+npx @dzhechkov/p-replicator doctor
+```
+
+`doctor` verifies pre-shipped contract + Prerequisites (`git on PATH`). Stricter than `verify` for must-have components.
+
+---
+
+## Pipeline overview — `/replicate` phases
 
-After running `/replicate`, the toolkit generates additional commands, agents, rules, and skills specific to your project (see [Post-Pipeline Commands](#post-pipeline-commands)).
+### Phase 0 — Product Discovery (optional)
+
+**Activated for:** new SaaS, startups, products to research. **Skipped for:** internal tools, experiments, projects with existing tech docs.
+
+- Skill: `reverse-engineering-unicorn` (JTBD analysis + competitors + Blue Ocean canvas)
+- Output: `docs/00_product_discovery.md`
+
+### Phase 1 — Planning (SPARC docs)
+
+Generates 11 standardized documents in `docs/`:
+
+| Document | Content |
+|---|---|
+| `PRD.md` | Vision, personas, user stories |
+| `Solution_Strategy.md` | Solution approach |
+| `Specification.md` | Acceptance criteria, NFRs |
+| `Pseudocode.md` | Algorithms, data flow |
+| `Architecture.md` | C4 diagrams, tech stack |
+| `Refinement.md` | Edge cases, testing strategy |
+| `Completion.md` | Deploy, CI/CD, monitoring |
+| `Research_Findings.md` | Market and tech research |
+| `Final_Summary.md` | Executive summary |
+| `C4_Diagrams.md` | Context / container / component |
+| `ADR.md` | Architecture Decision Records |
+
+Skill: `sparc-prd-mini` (internally chains explore + research + solve sub-phases).
+
+### Phase 2 — Validation (5-agent swarm)
+
+| Agent | Validates |
+|---|---|
+| `validator-stories` | INVEST criteria for user stories |
+| `validator-acceptance` | SMART criteria for acceptance criteria |
+| `validator-architecture` | Architecture consistency vs target constraints |
+| `validator-pseudocode` | Algorithm cohesion |
+| `validator-coherence` | Cross-document consistency |
+
+**Verdicts:**
+- 🟢 **READY** (score ≥70) → Phase 3
+- 🟡 **CAVEATS** (50–69) → Phase 3 with notes (auto-retry once on 🟡 in AUTO mode)
+- 🔴 **NEEDS WORK** (<50 or blockers) → return to Phase 1, max 3 retries → halt
+
+Output: `docs/validation-report.md`, `docs/test-scenarios.md` (BDD).
+
+### Phase 3 — Toolkit Generation (project-specific only)
+
+**Does NOT generate pre-shipped commands** (those are installed via `init`). Generates only project-specific artifacts:
+
+- `.claude/agents/{planner,code-reviewer,architect}.md` — project-aware
+- `.claude/rules/{security,coding-style,testing}.md` — derived from Specification + Refinement
+- `.claude/skills/{project-context,coding-standards}/` — domain knowledge
+- `CLAUDE.md` enhanced with project content
+- `.claude/feature-roadmap.json` — from PRD MVP scope
+- `DEVELOPMENT_GUIDE.md`, `README.md`
+- Conditional: `.mcp.json` (if external integrations detected), `.claude/commands/feature-ent.md` (if DDD docs detected)
+
+Skill: `cc-toolkit-generator-enhanced` (9 modules with quality gates).
+
+### Phase 4 — Finalize
+
+- `docker-compose.yml`, `Dockerfile`, `.gitignore` (scaffold files)
+- Git commit `chore: initial project setup from SPARC documentation`
+- Final summary
+
+---
 
 ## Skills Reference
 
@@ -39,13 +362,13 @@ After running `/replicate`, the toolkit generates additional commands, agents, r
 | `goap-research-ed25519` | Verified research with Ed25519 anti-hallucination |
 | `problem-solver-enhanced` | First principles + TRIZ (9 modules) |
 | `requirements-validator` | INVEST/SMART validation + BDD scenarios |
-| `brutal-honesty-review` | Unvarnished technical criticism |
+| `brutal-honesty-review` | Unvarnished technical criticism by severity |
 | `cc-toolkit-generator-enhanced` | Modular toolkit generator (9 modules, ~165K chars) + cross-project learning |
 | `reverse-engineering-unicorn` | Company reverse engineering + playbook |
-| `pipeline-forge` | Meta-skill: build AI pipelines from patterns |
+| `pipeline-forge` | Meta-skill: build AI pipelines from extracted patterns |
 | `knowledge-extractor` | Extract reusable knowledge from projects |
 
-## Skill Architecture
+### Skill Architecture
 
 Skills use a **composable module system** with three tiers:
 
@@ -67,270 +390,884 @@ The `cc-toolkit-generator-enhanced` skill is the largest component (~165K chars)
 | 08-skill-composition | Dependency graph + path rewriting |
 | 09-cross-project-learning | Pattern reuse via maturity model |
 
-## CLI Commands
+### `view()` cross-skill loading
+
+Skills use `view()` for cross-skill loading at runtime:
+
+```markdown
+view() .claude/skills/explore/SKILL.md
+view() .claude/skills/explore/references/questioning-techniques.md
+```
+
+Claude Code resolves these references dynamically — when executing a skill, the LLM reads referenced files at the moment of use. This lets skill A delegate to skill B without duplicating content.
+
+**Limitation:** only Claude Code supports this runtime mechanism. For other platforms (Codex, OpenCode), skill content must be **inlined** at install time. See [`MULTIPLATFORM_ROADMAP.md`](./MULTIPLATFORM_ROADMAP.md).
+
+---
+
+## Commands Reference
+
+| Command | Purpose | When to use |
+|---|---|---|
+| `/replicate` | Full pipeline: idea → SPARC docs → toolkit | Start of a new project |
+| `/start` | Bootstrap scaffold from SPARC docs | After `/replicate`, before feature work |
+| `/run` | Autonomous feature build loop from roadmap | Regular development |
+| `/go` | Router: picks `/plan`, `/feature`, or `/feature-ent` | One specific feature |
+| `/next` | Show next feature from roadmap | Sprint navigation |
+| `/plan` | Lightweight plan in `docs/plans/<id>.md` | Small task (≤3 files) |
+| `/feature` | Full SPARC-mini cycle (PLAN → VALIDATE → IMPLEMENT → REVIEW) | Large feature (4+ files) |
+| `/myinsights` | Capture or recall insights | After every non-trivial debug |
+| `/docs` | Bilingual docs generator (RU + EN) | End of project or feature |
+| `/harvest` | Extract reusable patterns | After completed project |
+| `/deploy` | Deployment workflow (dev/staging/prod) | Deployment |
+
+### `/run` — autonomous feature build
 
 ```bash
-npx @dzhechkov/p-replicator init       # Install (default)
-npx @dzhechkov/p-replicator update     # Update to latest version
-npx @dzhechkov/p-replicator remove     # Remove from project
-npx @dzhechkov/p-replicator list       # List installed components
-npx @dzhechkov/p-replicator doctor     # Health check
+/run mvp                                          # only priority=mvp features
+/run all                                          # everything in roadmap
+/run mvp --feature-branches                       # each feature in its own branch
+/run mvp --feature-branches --auto-merge          # also merge into main
 ```
 
-### Options
+**One iteration loop:**
 
 ```
---force      Overwrite existing files without prompting
---dry-run    Show what would be done without making changes
---help       Show help message
---version    Show version number
+while features in scope:
+    feature_id = /next                       # pick highest-priority
+    if no feature: break
+    /go feature_id                           # complexity router
+    verify (tests green, code committed)
+    mark roadmap entry: status=done
+    git commit + git push
 ```
 
-## The /replicate Pipeline
+**`--feature-branches` flag** (v1.5.0):
+- Creates `feature/{NNN}-{id}` branch per feature (zero-padded 3-digit)
+- Auto-stashes uncommitted changes with message `auto-stash before /run feature-branches`
+- Optional `--auto-merge` merges branch into main on success
+- Updates `feature-roadmap.json` with `number` + `branch` fields
 
-After installation, run `/replicate "idea"` in Claude Code to execute:
+### `/go` — intelligent router
 
-```
-Phase 0 (optional) → Phase 1 → Phase 2 → Phase 3 → Phase 4
-Product Discovery     Planning   Validation  Toolkit    Finalize
+`/go <id>` decides between:
+- `/plan` — for small tasks (≤3 files, no new architecture)
+- `/feature` — for large features (4+ files)
+- `/feature-ent` — for cross-bounded-context features with new ADRs (only available if Phase 3 generated `feature-ent.md` from DDD docs)
+
+### `/myinsights` — knowledge capture
+
+Build a project-local knowledge base of "rakes" (development insights) that auto-inject into every session via the SessionStart hook.
+
+```bash
+/myinsights                                                  # interactive prompt
+/myinsights "Prisma migrate dev fails silently if shadow DB unreachable. Workaround: set DATABASE_URL_SHADOW explicitly."
+/myinsights recall prisma                                    # search by keyword
 ```
 
-### Phase 0: Product Discovery (Optional)
+Storage: `.claude/insights/index.md` — markdown log auto-committed by Stop hook.
 
-Activates automatically for SaaS, startups, and new products. Skipped for internal tools and utilities.
+### `/harvest` — knowledge extraction
 
-- Reverse engineers similar companies and products
-- Identifies target customer segments (Jobs-To-Be-Done)
-- Analyzes competitive landscape (Blue Ocean Canvas)
-- Maps unit economics and monetization
-- Produces a Product Discovery Brief used by Phase 1
+Extract reusable patterns from a completed project into a knowledge base. Skill: `knowledge-extractor` (4 modules: agent review → classify → decontextualize → integrate).
 
-### Phase 1: Planning
+---
 
-Generates 11 SPARC documents in `docs/`:
+## CLI Commands
 
-| Document | Content |
-|----------|---------|
-| `PRD.md` | Product Requirements — vision, personas, user stories |
-| `Solution_Strategy.md` | Problem analysis and solution approach |
-| `Specification.md` | Detailed requirements with acceptance criteria |
-| `Pseudocode.md` | Algorithms and data flow |
-| `Architecture.md` | System design and component diagrams |
-| `Refinement.md` | Edge cases, testing strategy |
-| `Completion.md` | Deployment, CI/CD, monitoring |
-| `Research_Findings.md` | Market and technology research |
-| `Final_Summary.md` | Executive summary |
-| `C4_Diagrams.md` | System context, container, and component diagrams |
-| `ADR.md` | Architecture Decision Records |
+### Subcommands
 
-### Phase 2: Validation
+| Subcommand | Purpose | Exit code |
+|---|---|---|
+| `init` (default) | Install package in project | `0` ok, `1` if already installed without `--force` |
+| `update` | Upgrade files to new version (preserves customizations) | `0` ok, `1` if not installed |
+| `remove` | Delete package-tracked files | `0` ok, `1` if not installed |
+| `list` | List installed components with metadata | `0` |
+| `doctor` | Health check of pre-shipped contract + git PATH | `0` ok, `1` if anything broken |
+| `verify` | Pre-shipped + post-/replicate verification | `0` ok, `1` if pre-shipped contract violated |
 
-Validates documentation quality using 5 parallel agents (swarm):
+### Global flags
 
-| Agent | Validates |
-|-------|----------|
-| Stories Validator | User stories against INVEST criteria |
-| AC Validator | Acceptance criteria against SMART criteria |
-| Architecture Validator | Architecture consistency and completeness |
-| Pseudocode Validator | Algorithm correctness and edge cases |
-| Coherence Validator | Cross-document consistency |
+| Flag | Where it works | Description |
+|---|---|---|
+| `--force` | `init` | Overwrite existing files (with merge logic for settings.json) |
+| `--dry-run` | `init`, `update`, `remove` | Preview without writing to disk |
+| `--reset-settings` | `init --force`, `update` | Full overwrite of settings.json (disables merge) |
+| `--help`, `-h` | any | Show help |
+| `--version`, `-v` | any | Show package version |
+
+### Slash command flags (inside Claude Code)
+
+| Flag | Where | Description |
+|---|---|---|
+| `--feature-branches` | `/run`, `/go` | Each feature on its own branch `feature/{NNN}-{id}` |
+| `--auto-merge` | `/run`, `/go` (with `--feature-branches`) | Auto-merge feature branch into main on success |
+| `--skip-tests` | `/start` | Skip test generation |
+| `--skip-seed` | `/start` | Skip DB seeding |
+| `--dry-run` | `/start`, `/replicate` | Preview without writing |
+
+---
+
+## Validation Cycle Details
+
+The same validation pipeline runs in **`/replicate` Phase 2** and **`/feature` Phase 2**. Skill: `requirements-validator`.
+
+### Validators (5-agent swarm)
+
+| Agent | Criteria | Scoring |
+|---|---|---|
+| `validator-stories` | INVEST: Independent, Negotiable, Valuable, Estimable, Small, Testable | 0–100 per story, average |
+| `validator-acceptance` | SMART: Specific, Measurable, Achievable, Relevant, Time-bound | 0–100 per AC, average |
+| `validator-architecture` | Consistency vs target constraints (Distributed Monolith / Docker / VPS / MCP) | Pass/fail + score |
+| `validator-pseudocode` | Algorithm cohesion + data-flow coherence | 0–100 |
+| `validator-coherence` | Cross-document consistency (PRD↔Spec, Spec↔Pseudocode, etc.) | 0–100 |
+
+### Verdicts
+
+| Verdict | Threshold | Next |
+|---|---|---|
+| 🟢 **READY** | average ≥ 70, no blockers | Phase 3 (or IMPLEMENT in /feature) |
+| 🟡 **CAVEATS** | 50–69, no blockers | Phase 3 with notes (AUTO mode auto-retries once on 🟡) |
+| 🔴 **NEEDS WORK** | < 50 OR any blocker | Return to Phase 1 / PLAN, max 3 retries → halt |
+
+After 3 retries with 🔴, the pipeline halts and surfaces to the user. The user can adjust the input or override.
+
+### Output
+
+- `docs/validation-report.md` (or `docs/features/<id>/validation-report.md` for /feature)
+- `docs/test-scenarios.md` — BDD scenarios derived from acceptance criteria
+
+### Post-implementation review (`brutal-honesty-review`)
+
+After `IMPLEMENT` phase (Phase 3 of /feature), `brutal-honesty-review` skill classifies findings by severity:
 
-**Scoring:** Score >= 70 passes (READY), 50-69 passes with caveats, <50 requires fixes (auto-retries up to 3 times).
+| Severity | Action |
+|---|---|
+| `blocker` | MUST fix before merge |
+| `high` | Fix in this feature unless explicit deferral |
+| `medium` | Optional fix; create follow-up issue |
+| `low` | Logged, no action required |
 
-**Output:** `docs/validation-report.md` and `docs/test-scenarios.md` (BDD/Gherkin).
+Output: `docs/features/<id>/review-report.md`.
 
-### Phase 3: Toolkit Generation
+---
 
-Creates Claude Code instruments for your project:
+## Feature Lifecycle — `/feature` command
 
-| Category | Generated |
-|----------|-----------|
-| **Commands** | `/start`, `/feature`, `/plan`, `/next`, `/deploy`, `/myinsights`, `/go`, `/run`, `/docs` |
-| **Agents** | `planner`, `code-reviewer`, `architect` |
-| **Rules** | `git-workflow`, `feature-lifecycle`, `security`, `coding-style`, `insights-capture` |
-| **Skills** | `project-context`, `coding-standards`, `testing-patterns`, `feature-navigator` |
-| **Hooks** | `SessionStart` (feature context), `Stop` (auto-commit) |
-| **Project files** | `CLAUDE.md`, `DEVELOPMENT_GUIDE.md`, `README.md` |
+`/feature <id>` runs a 4-phase lifecycle: **PLAN → VALIDATE → IMPLEMENT → REVIEW**. Project-context-aware (reads `docs/`), checkpoint-driven, parallel where independent.
 
-Conditional generation (automatically detected):
-- DDD patterns found → `/feature-ent`, enterprise lifecycle
-- External APIs detected → security rules, secrets management
-- Fitness functions defined → fitness validation rules
+### Two entry modes
 
-### Phase 4: Finalization
+| Mode | When | Pre-conditions |
+|---|---|---|
+| **Mode 1: Post-/replicate** | Project bootstrapped via `/replicate` | CLAUDE.md, docs/, scaffold all generated |
+| **Mode 2: Existing project** | Working project, adding features with verification | `init` ran on top of existing project |
 
-Creates infrastructure scaffolding (`docker-compose.yml`, `Dockerfile`, `.gitignore`) and commits everything with structured git history.
+The 4-phase pipeline is **identical in both modes**. Same validation thresholds, same retry logic, same brutal-honesty review.
 
-### Checkpoint Interaction
+### Phase 1 — PLAN (sparc-prd-mini)
 
-After each phase, you see a checkpoint prompt and can respond:
+Generates 5 SPARC docs in `docs/features/<feature>/`:
+- `01_specification.md` — requirements + acceptance criteria
+- `02_pseudocode.md` — algorithms + data flow
+- `03_architecture.md` — component placement + dependencies
+- `04_refinement.md` — edge cases + error paths
+- `05_completion.md` — testing + deployment notes
 
-| Command | Action |
-|---------|--------|
-| `ok` | Proceed to next phase |
-| `add [detail]` | Add information to current phase output |
-| `fix [issue]` | Fix something in current output |
-| `redo` | Redo the current phase |
-| `skip` | Skip the current phase (not recommended for Phase 2) |
+### Phase 2 — VALIDATE (requirements-validator)
 
-## Post-Pipeline Commands
+Same swarm-of-5 as `/replicate` Phase 2. Verdict 🟢/🟡/🔴 with same retry logic.
 
-After `/replicate` completes, the following commands become available:
+### Phase 3 — IMPLEMENT (parallel agents)
 
-### /start — Bootstrap the Project
+1. Identify independent work units from Phase 1 Architecture
+2. Spawn parallel `Task` tool calls, one per unit
+3. Each Task: implement + write tests + commit
+4. Coordinator merges/integrates
+5. Run full test suite
 
-Reads SPARC documentation and creates the initial project structure: source code directories, database schemas, API stubs, and configuration files.
+**Quality gate:** tests pass, lint clean, build succeeds.
 
-### /feature — Full Feature Lifecycle
+### Phase 4 — REVIEW (brutal-honesty-review)
+
+Severity-classified findings. Critical (`blocker` | `high`) MUST be fixed.
+
+### AUTO mode (called from /go or /run)
+
+- Phase 1: proceed if all docs exist
+- Phase 2: proceed if 🟢 or 🟡; auto-retry once on 🔴
+- Phase 3: proceed if tests + lint + build green
+- Phase 4: auto-fix `high` if straightforward; halt on `blocker`
+
+### Final steps
+
+1. Update `.claude/feature-roadmap.json`: status `in_progress` → `done`
+2. Commit: `feat(<feature>): complete lifecycle [phases 1-4]`
+3. Push (if `--feature-branches` mode: also create branch + optional auto-merge)
+
+---
+
+## Statusline Dashboard
+
+**6-line ANSI dashboard** above Claude Code's prompt with real-time pipeline + roadmap + toolkit + status metrics.
 
 ```
-/feature user-authentication
+P-Replicator V1.5.x ● user │ Sonnet 4.7
+🚀 Pipeline   /<cmd> ▓▓▓░░░░ 50%  │ Phase: VALIDATE (2/4)  │ Last: /replicate
+🎯 Roadmap    [●●●○○○○○] mvp 3/8   │ Done 5/12  │ ▶ auth-jwt  │ Domain: banking
+📊 SPARC      ●11/11  │ 🟢 78/100  │ Plans ●3  │ ADRs ●2  │ Harvest 2026-05-05
+🛠️ Toolkit    Skills ●10/10 │ Cmds ●11/11 │ Agents ●4+3 │ Rules ●5+2 │ Hooks ●6/6
+💡 Insights   ●12 (2026-05-06) │ Tests 85/85 ✓ │ MCP ●1/1 │ Settings ✓ │ 🧬 Keysarium ✓
 ```
 
-4-phase lifecycle: **PLAN** (SPARC docs) → **VALIDATE** (swarm, score >= 70) → **IMPLEMENT** (parallel agents) → **REVIEW** (code review swarm).
+### Sources (heuristic + state-file)
+
+| Metric | Source |
+|---|---|
+| Pipeline command + phase + progress | `.claude/.p-replicator-state.json` |
+| Roadmap progress | `.claude/feature-roadmap.json` |
+| SPARC count | `docs/{PRD,Architecture,...}.md` |
+| Validation score | regex extract from `docs/validation-report.md` |
+| Plans count | `docs/plans/*.md` |
+| ADRs count | `docs/ADR.md` H2/H3 headings, or `docs/adr/*.md`, or `docs/ddd/adr/*.md` |
+| Insights count + last date | `## YYYY-MM-DD` in `.claude/insights/index.md` |
+| Toolkit counts | filesystem walks of `.claude/{skills,commands,agents,rules,hooks}/` |
+| Settings status | deep-equals current vs `manifest.shippedDefaults` |
+| MCP servers | `.mcp.json` |
+| Domain | keyword grep in `CLAUDE.md` |
+| Last harvest | `TOOLKIT_HARVEST.md` mtime |
+| Last test | optional `.claude/.last-test.json` cache |
+
+### Defensive design
+
+Every section wrapped in `safeRun()` with fallback — one parse error doesn't break the whole status bar.
+
+**Stale state:** state file older than 30 minutes is ignored (Pipeline section shows `idle`).
+
+**Disable statusline:** remove the `statusLine` field from `.claude/settings.json`. The deletion is preserved on next `update` thanks to merge logic.
+
+For internals, see [admin guide](./README/eng/03_admin_guide.md#statusline--dashboard) and [`documentation/07-dashboard-howto.md`](../../documentation/07-dashboard-howto.md) (in source repo).
+
+---
+
+## Hooks System
+
+`p-replicator` ships **6 cross-platform Node scripts** in `.claude/hooks/`:
+
+| Hook | Event | Purpose |
+|---|---|---|
+| `session-insights.cjs` | SessionStart | Inject 3 recent insights from `.claude/insights/index.md` to stdout (Claude Code captures into context) |
+| `autocommit-roadmap.cjs` | Stop | Auto-commit `.claude/feature-roadmap.json` if changed |
+| `autocommit-insights.cjs` | Stop | Auto-commit `.claude/insights/` if changed |
+| `autocommit-plans.cjs` | Stop | Auto-commit `docs/plans/` if changed |
+| `statusline.cjs` | (statusLine config) | Multi-line dashboard above the prompt |
+| `state-update.cjs` | (utility) | Argv-driven helper for writing `.claude/.p-replicator-state.json` |
 
-### /plan — Lightweight Planning
+### Cross-platform discipline
 
+All 4 autocommit scripts use `execFileSync('git', [...])` (no shell pipes, no `2>/dev/null`/`|| true`). Works identically on Windows-cmd, bash, PowerShell.
+
+**Each script is defensive:** wrapped in try/catch, always exits 0 (best-effort, never blocks the session).
+
+### State file for live progress
+
+`.claude/.p-replicator-state.json` — ephemeral state, updated by commands during pipeline execution:
+
+```json
+{
+  "currentCommand": "/feature",
+  "currentPhase": { "name": "VALIDATE", "index": 2, "total": 4, "progress": 0.5 },
+  "lastCommand": "/replicate",
+  "lastFeature": "auth-jwt",
+  "updatedAt": "2026-05-07T..."
+}
 ```
-/plan add-payment-gateway
+
+Updated via `state-update.cjs`:
+
+```bash
+node .claude/hooks/state-update.cjs \
+  --command /feature \
+  --phase VALIDATE \
+  --index 2 \
+  --total 4 \
+  --progress 0.5
 ```
 
-Creates a single plan file in `docs/plans/`. Good for smaller tasks (2-5 min vs. 15-30 min for `/feature`).
+Pipeline commands optionally call this script (via Bash tool) so statusline shows real progress.
+
+**⚠️ Recommendation:** add to `.gitignore`:
 
-### /go — Smart Pipeline Selector
+```
+.claude/.p-replicator-state.json
+.claude/.last-test.json
+```
 
+---
+
+## Roadmap & Insights
+
+### Feature roadmap (`.claude/feature-roadmap.json`)
+
+**File:** generated in `/replicate` Phase 3 from PRD MVP scope, or by hand for Mode 2.
+
+**Schema (post v1.5.0):**
+
+```json
+{
+  "version": "1.0",
+  "features": [
+    {
+      "id": "auth-jwt",
+      "number": 1,
+      "branch": "feature/001-auth-jwt",
+      "name": "JWT-based authentication",
+      "priority": "mvp",
+      "status": "next",
+      "complexity": "medium",
+      "estimated_hours": "2-4",
+      "blockers": [],
+      "expected_files": ["packages/backend/src/auth/jwt.ts"],
+      "depends_on": []
+    }
+  ]
+}
 ```
-/go user-authentication
+
+**Lifecycle states:** `planned` → `next` → `in_progress` → `done` (or `blocked`).
+
+**`number` and `branch`** are populated by `--feature-branches` flag. Auto-commit via `autocommit-roadmap.cjs` (Stop hook).
+
+### Insights system
+
+**Storage:** `.claude/insights/index.md` (markdown log).
+
+**Entry format:**
+
+```markdown
+## YYYY-MM-DD — short title
+
+**Tags:** tag1, tag2, tag3
+
+**Problem:**
+What happened (1-3 sentences).
+
+**Solution:**
+What fixed it (1-5 sentences with code if relevant).
+
+**References:** file:line or commit hash or external link
+
+---
 ```
 
-Automatically analyzes task complexity and selects `/plan`, `/feature`, or `/feature-ent`.
+**Lifecycle:**
+- ≤ 50 entries → single `index.md`
+- > 50 → split into archive `<YYYY-MM>.md` with `index.md` as TOC
+- Never delete — only supersede via `**Status:** superseded by <link>`
+
+**Tag conventions:**
+- ✅ `prisma-migration`, `postgres-timezone`, `docker-compose-network`
+- ❌ `bug`, `fix`, `important` (too generic — recall fails)
+
+**Auto-injection:** `SessionStart` hook (`session-insights.cjs`) reads top 3 recent entries to stdout, Claude Code injects into initial session context.
+
+---
+
+## Architecture Highlights
+
+### Two-tier model: Pre-shipped vs Project-generated
+
+| Tier | Created by | Lives in | Updated |
+|---|---|---|---|
+| **Pre-shipped** | `npx p-replicator init` | `.claude/{skills,commands,agents,rules,hooks}/` + `settings.json` | On each package upgrade |
+| **Project-generated** | `/replicate` Phase 3 (LLM execution) | `CLAUDE.md`, `.claude/agents/planner.md`, `docs/`, etc. | Only on regeneration |
+
+This is **the main fix of v1.4.0** — previously `/replicate` Phase 3 tried to generate ALL artifacts (including generic commands like `/run`, `/feature`), which led to flaky outputs (LLM compression, missed templates). Post-v1.4.0, generic commands are pre-shipped, Phase 3 generates ONLY project-specific artifacts.
+
+### SSOT: `utils.COMPONENTS`
 
-### /run — Autonomous Build Loop
+Single source of truth for what's shipped and what's generated, in `src/utils.js`. **Any future edit to items automatically updates 5 surfaces** (init, update, doctor, verify, list, cli help) — eliminating drift issues that existed pre-v1.3.1.
 
+### Settings.json merge logic (v1.4.2 + v1.4.3)
+
+`init --force` and `update` use `mergeSettingsJson(existing, template)` to preserve user customizations:
+
+- **User-added hook** (absent from template) → preserved
+- **User-modified default** (changed command) → treated as user-added → preserved
+- **Identical command** in template and user → de-duped
+- **New hook in template** → added to user's settings
+- **Removed default** (was in old template, gone from new) → orphan-detected and removed
+
+**Identity model:** hooks compared by `command` string. **Override:** `--reset-settings` flag disables merge — full overwrite.
+
+### Manifest schema (`.p-replicator.json`)
+
+```json
+{
+  "version": "1.5.x",
+  "installedAt": "2026-05-07T12:00:00.000Z",
+  "components": ["agents", "commands", "hooks", "rules", "settings", "skills"],
+  "files": ["...sorted list of all installed files..."],
+  "shippedDefaults": {
+    "settings.json": { "hooks": {...}, "statusLine": {...} }
+  }
+}
 ```
-/run          # Build next features (MVP scope)
-/run all      # Build all planned features
+
+`shippedDefaults` is the baseline for orphan detection on upgrade (v1.4.3+). Backward-compatible: pre-v1.4.3 manifests load without error, orphan detection skipped on first upgrade.
+
+For complete internals, see [`README/eng/05_architecture.md`](./README/eng/05_architecture.md) — covers cross-platform hooks, sync-templates merge mode, settings merge algorithm, statusline architecture.
+
+---
+
+## Configuration
+
+### `.claude/settings.json`
+
+Default structure after `init`:
+
+```json
+{
+  "$schema": "https://www.schemastore.org/claude-code-settings.json",
+  "_comment": "Default hooks + statusline shipped by @dzhechkov/p-replicator init.",
+  "statusLine": {
+    "type": "command",
+    "command": "node .claude/hooks/statusline.cjs"
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/session-insights.cjs", "timeout": 5 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/autocommit-roadmap.cjs", "timeout": 10 },
+          { "type": "command", "command": "node .claude/hooks/autocommit-insights.cjs", "timeout": 10 },
+          { "type": "command", "command": "node .claude/hooks/autocommit-plans.cjs", "timeout": 10 }
+        ]
+      }
+    ]
+  }
+}
 ```
 
-Continuously implements features from the roadmap until complete.
+**Customization:** add new hooks or event types — preserved on `init --force` or `update` thanks to merge logic.
 
-### /next — What to Do Next
+**Disable individual default hooks:** delete from `settings.json` after `init`. The deletion is preserved on next `update` (orphan detection only removes hooks **previously shipped** but absent in **new** template — your manual deletion is a user customization).
 
-Shows current sprint progress, features in progress, suggested next tasks, blockers and dependencies.
+### MCP servers (`.mcp.json`)
 
-### /deploy — Deployment
+Project-local MCP server config:
 
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "..." }
+    }
+  }
+}
 ```
-/deploy staging
-/deploy production
+
+Statusline shows MCP server count. `/replicate` Phase 3 auto-generates `.mcp.json` when external integrations are detected.
+
+### Keysarium integration
+
+If `.keysarium.json` (from sibling `@dzhechkov/keysarium` package) is detected:
+
+- `init` shows an integration banner
+- Statusline shows `🧬 Keysarium ✓`
+- `/replicate` Phase 3 doesn't duplicate skills already provided by Keysarium
+
+---
+
+## Update workflow
+
+```bash
+# Safe upgrade with preserved customizations:
+npx @dzhechkov/p-replicator@latest update
+
+# Or via init --force (also preserves customizations):
+npx @dzhechkov/p-replicator@latest init --force
+
+# Full reset of settings.json to defaults (loses custom hooks):
+npx @dzhechkov/p-replicator@latest init --force --reset-settings
 ```
 
-Guides the deployment process to the specified environment.
+### What the merge logic does
+
+1. Reads `manifest.shippedDefaults['settings.json']` (what we shipped previously)
+2. Reads current `templates/.claude/settings.json` (new template)
+3. Reads `.claude/settings.json` (user's current)
+4. **Orphan detection:** removes hooks present in old template but missing in new
+5. **Merge:** adds hooks from new template that aren't already in user's current
+6. User-added hooks (never in old template) are **preserved**
 
-### /myinsights — Development Insights
+After upgrade, run `verify` to confirm:
 
-Captures errors, workarounds, and discoveries into the knowledge base. Error-first lookup: when you hit an error, the system checks if a solution already exists.
+```bash
+npx @dzhechkov/p-replicator verify
+```
 
-### /docs — Generate Documentation
+---
 
+## Troubleshooting
+
+### `init` refuses: "P-Replicator is already installed"
+
+```bash
+npx @dzhechkov/p-replicator update                            # safe upgrade
+npx @dzhechkov/p-replicator init --force                      # forced re-install
+npx @dzhechkov/p-replicator init --force --reset-settings     # full reset
 ```
-/docs         # Both Russian and English
-/docs eng     # English only
-/docs update  # Update existing docs
+
+### Missing files after `init`
+
+```bash
+npx @dzhechkov/p-replicator doctor       # see what's missing
+npx @dzhechkov/p-replicator init --force # repair
 ```
 
-Generates bilingual documentation in `README/` directory.
+### Install went to `~/node_modules` instead of project
 
-## Feature Development Workflows
+Cause: no `package.json` in your project, npm walks up and finds one in home directory.
 
-### Simple Task
+```bash
+npm init -y
+npx @dzhechkov/p-replicator init
+```
 
+### Statusline doesn't appear
+
+Checks:
+1. Claude Code version supports `statusLine` config? Update Claude Code.
+2. `statusLine` field present in `.claude/settings.json`?
+3. Script runs directly:
+
+```bash
+node .claude/hooks/statusline.cjs
 ```
-/plan task-name       → Creates plan in docs/plans/
-implement manually    → Write code following the plan
-/myinsights           → Capture any learnings
+
+Should print 6 lines of ANSI output. If it errors:
+
+```bash
+node .claude/hooks/statusline.cjs 2>&1
 ```
 
-### Standard Feature
+Likely cause: corrupt JSON or missing `.p-replicator.json`.
+
+### Hooks aren't auto-committing
 
+```bash
+npx @dzhechkov/p-replicator doctor
 ```
-/feature feature-name → Runs 4-phase lifecycle
-/next                 → Check what's next
+
+Look for `✓ git on PATH` in Prerequisites section. Also verify `.git` exists:
+
+```bash
+git rev-parse --git-dir
 ```
 
-### Smart Mode
+Debug a specific hook:
 
+```bash
+node .claude/hooks/autocommit-roadmap.cjs
+echo "Exit: $?"
+git log -1 --format="%s"
 ```
-/go feature-name      → Auto-selects /plan or /feature or /feature-ent
+
+### Statusline shows "Settings ⚠️ merged" but I didn't change anything
+
+Cause: some process modified `settings.json` (formatting, whitespace, ordering). Statusline compares via deep-equals on sorted keys.
+
+```bash
+npx @dzhechkov/p-replicator init --force --reset-settings
 ```
 
-### Autonomous Build
+### Settings.json lost my custom hooks after update
+
+This was a bug pre-v1.4.2. In v1.4.2+, `update` and `init --force` use `mergeSettingsJson` which preserves user customizations.
+
+If you're on v1.4.1 or earlier:
 
+```bash
+npx @dzhechkov/p-replicator@latest update
 ```
-/run                  → Builds all "next" features from roadmap
+
+Restore lost hooks from git history:
+
+```bash
+git log -p --follow -- .claude/settings.json
 ```
 
-### Feature Roadmap
+### `/run --feature-branches` immediately fails "not on main"
+
+Cause: you're on a feature branch. Switch to main:
 
-The system maintains `.claude/feature-roadmap.json` with statuses: `done`, `in_progress`, `next`, `planned`, `blocked`. Use `/next` to navigate.
+```bash
+git checkout main
+/run mvp --feature-branches
+```
 
-## The /harvest Pipeline
+### `--feature-branches` lost my unsaved changes
 
-Extract reusable knowledge from completed projects:
+They're stashed:
 
+```bash
+git stash list
+git stash show stash@{0}
+git stash pop
 ```
-/harvest quick    # Fast extraction, no checkpoints (~15 min)
-/harvest full     # Comprehensive 4-phase pipeline with checkpoints (~45 min)
-/harvest marker   # Mark artifact for later extraction (~30 sec)
+
+`p-replicator` auto-stashes with message `auto-stash before /run feature-branches`.
+
+### `/replicate` didn't generate expected commands (`/run`, `/feature`, ...)
+
+This is solved in v1.4.0+. All 11 generic commands are now pre-shipped via `init`. If you're on an old version:
+
+```bash
+npx @dzhechkov/p-replicator@latest init --force
+npx @dzhechkov/p-replicator verify
 ```
 
-### How /harvest full Works
+### Insights aren't auto-injected into new sessions
+
+Checks:
+1. `.claude/insights/index.md` exists with entries?
+2. Hook works:
+   ```bash
+   node .claude/hooks/session-insights.cjs    # should print recent insights
+   ```
+3. SessionStart hook configured in `settings.json`?
+
+If all 3 OK but still nothing — Claude Code may cache. Restart `claude`.
 
+### Statusline lags on every command
+
+```bash
+time node .claude/hooks/statusline.cjs    # how many seconds?
 ```
-Phase 1: AGENT REVIEW   → 5 parallel scanners
-Phase 2: CLASSIFY        → Categorize into skills/commands/rules/etc.
-Phase 3: DECONTEXTUALIZE → Remove project-specific names, generalize
-Phase 4: INTEGRATE       → Write to toolkit, update index
+
+Should be < 100ms. If > 1s, check `docs/` size:
+
+```bash
+du -sh docs/
+find docs/ -type f -name "*.md" | wc -l
 ```
 
-### Harvest Audit
+Workaround: temporarily disable statusline by removing the `statusLine` field in `.claude/settings.json`. See [KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md) item L6 for future enhancement (`STATUSLINE_PROFILE=1` env var).
+
+For full troubleshooting (15+ issues with detailed diagnostics), see [`README/eng/06_troubleshooting.md`](./README/eng/06_troubleshooting.md).
+
+---
+
+## Migration
+
+| From → To | What you get | Migration cost |
+|---|---|---|
+| 1.3.x → 1.5.x | All pre-shipped commands + statusline + feature-branches + merge logic + Mode 2 | `init --force` (preserves customizations) |
+| 1.4.0 → 1.4.1 | Cross-platform hooks + sync merge mode | `init --force` |
+| 1.4.1 → 1.4.2 | Settings merge (preserve customizations) | `init --force` is safe (preserves) |
+| 1.4.2 → 1.4.3 | Orphan detection | First upgrade lacks baseline — re-run `init --force` to populate |
+| 1.4.3 → 1.5.0 | Statusline + `--feature-branches` | `update` or `init --force` |
+| 1.5.0 → 1.5.1 | "Existing tech docs" workflow formalized | docs only — no migration |
+| 1.5.1 → 1.5.2 | Mode 2 (existing project + /feature) formalized | docs only — no migration |
 
+**No breaking changes** between any versions. All upgrades are backward-compatible.
+
+After any upgrade — `verify` to confirm contract:
+
+```bash
+npx @dzhechkov/p-replicator verify
 ```
-/harvest audit
+
+---
+
+## Test Infrastructure
+
+**Suite:** 105 tests, 36 suites, ~25 sec runtime.
+
+| Layer | File | Coverage |
+|---|---|---|
+| **Unit** | `tests/unit/utils.test.js` (54 tests) | Pure functions: createManifest, mergeSettingsJson, removeOrphanHooks, getItemRelativePath, parseToolkit logic |
+| **E2E** | `tests/e2e/lifecycle.test.js` (48 tests) | Full CLI lifecycle, hooks installation, settings merge edge cases, statusline output, --feature-branches docs |
+| **Snapshot** | `tests/snapshot/templates.test.js` (3 tests) | SHA-256 baseline of all 115 files in `templates/` |
+
+**Meta-tests** verify consistency between documents:
+- `replicate-pipeline.md` mentions every pre-shipped command (no orphan in rule)
+- `replicate.md` Phase 3 doesn't claim "Generate `<pre-shipped>.md`" (no spec drift)
+
+**Snapshot baseline** regenerated via `npm run snapshot:baseline` after intentional template changes.
+
+```bash
+npm test                                    # full suite
+npm run test:unit                           # unit only
+npm run test:e2e                            # e2e only
+npm run test:snapshot                       # snapshot only
 ```
 
-Reviews toolkit maturity distribution, recommendations for promotion, and gaps in coverage.
+---
+
+## Known Limitations
+
+For currently-open improvement items — see [`KNOWN_LIMITATIONS.md`](./KNOWN_LIMITATIONS.md) (8 entries: 3 medium, 5 low priority).
 
-## Tips & Best Practices
+**Highlights:**
+- **M1** — `--feature-branches` behavior tested only via documentation-presence (not e2e git workflow)
+- **M2** — No formal `--from-docs` CLI flag (workflow works via natural-language only)
+- **M3** — `/feature` requires standard SPARC doc paths (no `--prd-path` flag)
+- **L5** — `.p-replicator-state.json` not auto-gitignored
+- **L6** — Statusline could profile per-section if slow
 
-1. **Write descriptive product ideas** — the more detail you provide to `/replicate`, the better the documentation quality.
+For multiplatform support roadmap (Codex, OpenCode, KiloCode) — see [`MULTIPLATFORM_ROADMAP.md`](./MULTIPLATFORM_ROADMAP.md).
 
-2. **Use checkpoints actively** — review output at each phase, don't just skip through. Check that user stories match your vision and architecture aligns with constraints.
+---
 
-3. **Start with /plan for small tasks** — not every task needs `/feature`. For tasks touching <= 3 files, `/plan` is faster and sufficient.
+## Changelog Highlights
 
-4. **Use /go for automatic selection** — let the system decide between `/plan`, `/feature`, and `/feature-ent` based on complexity.
+### v1.5.2 — 2026-05-07 (Mode 2 documentation)
 
-5. **Harvest knowledge regularly** — use `/harvest marker` during development, run `/harvest quick` at the end of each sprint.
+Formalized **"Feature workflow in existing project (Mode 2)"** across all documentation surfaces. Pure docs/spec patch — no code changes.
 
-6. **Use /next for focus** — start each session with `/next` to understand current state, blockers, and priorities.
+### v1.5.1 — 2026-05-07 (Existing-docs workflow)
 
-7. **Check insights before debugging** — the `SessionStart` hook automatically injects relevant insights from previous sessions.
+Formalized **"Starting from existing technical documentation"** workflow for `/replicate`. New build.js link-rewriter for HTML guide.
 
-8. **Review generated CLAUDE.md** — it's Claude Code's primary context. Ensure architecture, commands, and coding standards are accurate.
+### v1.5.0 — 2026-05-07 (Statusline + feature-branches)
 
-9. **Iterate on validation** — if Phase 2 returns CAVEATS, fix documentation before proceeding. Toolkit quality depends on documentation quality.
+- ✨ **Statusline dashboard** (RuFlo-style 6-line bar) via `templates/.claude/hooks/statusline.cjs`
+- ✨ **`--feature-branches` flag** for `/run` and `/go` (each feature on its own branch `feature/{NNN}-{id}`)
+- 🆕 `state-update.cjs` — argv-driven helper
+- 🆕 `--auto-merge` companion flag
 
-## Integration with @dzhechkov/keysarium
+### v1.4.3 — 2026-05-07 (Orphan hook detection)
 
-Works alongside Keysarium. If `@dzhechkov/keysarium` is detected during `init`, PU skills integrate with the existing Keysarium setup, sharing `.claude/commands`, `.claude/rules`, and `.claude/agents` directories.
+- 🐛 `mergeSettingsJson` now cleans hooks shipped previously but removed in newer template
+- 🆕 `manifest.shippedDefaults['settings.json']` baseline
+- 🐛 `update.js` now also uses merge logic
+
+### v1.4.2 — 2026-05-06 (Merge + meta-tests)
+
+- 🐛 `init --force` MERGES settings.json (preserves user customizations)
+- 🆕 `--reset-settings` flag for explicit nuclear-overwrite
+- 🐛 Stronger meta-test for `replicate.md` drift (multi-axis)
+- 🆕 `doctor` checks `git on PATH`
+
+### v1.4.1 — 2026-05-06 (Cross-platform + critical fix)
+
+- 🐛 Cross-platform hooks: replaced bash chains with 4 Node scripts
+- 🐛 `verify.js` SSOT: `kind: 'pre-shipped' | 'project-generated'` field
+- 🐛 Meta-tests for `replicate.md` ↔ `replicate-pipeline.md` consistency
+- 🐛 **Critical regression fixed:** `sync-templates.js` cleanDir silently deleted pre-shipped files
+
+### v1.4.0 — 2026-05-06 (Major: 9 pre-shipped commands)
+
+- ✨ **9 new pre-shipped commands:** `/start`, `/plan`, `/feature`, `/go`, `/run`, `/next`, `/myinsights`, `/docs`, `/deploy`
+- ✨ **3 new pre-shipped rules:** `git-workflow`, `insights-capture`, `feature-lifecycle`
+- ✨ Settings.json shipped with hooks
+- ✨ `verify` command — replaces user's manual verification prompt
+- 🐛 5 sources of truth divergence unified via `utils.COMPONENTS.items`
+
+### v1.3.1 — 2026-05-06 (SSOT bugfix)
+
+- 🐛 `cli.js` --help showed "1 rule" while `EXPECTED_RULES` had 2 entries → SSOT fix
+- 🐛 `update.js` corrupted manifest → `getRelativePaths(templateClaude)` fix
+- 🐛 `update` now removes orphan template files
+
+### v1.3.0 (baseline)
+
+Initial published version. 10 skills, 2 commands (`/replicate`, `/harvest`), 4 agents, 2 rules.
+
+For full version history with migration notes — see [`CHANGELOG.md`](./CHANGELOG.md) (authoritative source).
+
+---
+
+## Contributing
+
+This package is part of the [`pu-unicorn-replicate`](https://github.com/dzhechko/pu-unicorn-replicate) monorepo.
+
+### Development setup
+
+```bash
+git clone https://github.com/dzhechko/pu-unicorn-replicate.git
+cd pu-unicorn-replicate/packages/p-replicator
+npm install
+npm test
+```
+
+### Pre-publish checklist
 
 ```bash
-npx @dzhechkov/keysarium init        # Install Keysarium
-npx @dzhechkov/p-replicator init      # Add PU Unicorn skills
-# Both work together seamlessly
+npm run snapshot:baseline    # regenerate baseline if templates/ changed
+npm test                     # all 105 tests must pass
+npm pack --dry-run           # verify tarball contents
+npm publish                  # prepublishOnly hook syncs source → templates/
 ```
 
+### Filing issues
+
+https://github.com/dzhechko/pu-unicorn-replicate/issues
+
+Include:
+- `npx @dzhechkov/p-replicator --version` output
+- `npx @dzhechkov/p-replicator verify` output
+- Repro steps + expected vs actual
+
+### Patterns persisted in AQE memory
+
+Each significant improvement is persisted as a cross-session pattern (16+ entries from v1.3.1 → v1.5.2). Categories:
+
+- `cli-package-ssot-component-lists`, `cli-package-manifest-preservation` (v1.3.1)
+- `cli-package-pre-ship-vs-generate-boundary`, `cli-package-verify-replaces-manual-prompts` (v1.4.0)
+- `cli-package-cross-platform-hooks-via-node-scripts`, `cli-package-kind-discrimination-for-ssot` (v1.4.1)
+- `cli-package-settings-json-merge-vs-overwrite`, `meta-test-multi-axis-drift-detection` (v1.4.2)
+- `cli-shipped-defaults-baseline-for-orphan-detection`, `cli-update-must-mirror-init-merge-logic` (v1.4.3)
+- `cli-statusline-multi-line-dashboard`, `cli-feature-branches-flag-for-teaching-workflows` (v1.5.0)
+- `doc-rollout-pattern` (v1.5.1, v1.5.2 — 14-surface symmetric rollout)
+
+---
+
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE).
+
+---
+
+## Links
+
+- **npm:** https://www.npmjs.com/package/@dzhechkov/p-replicator
+- **GitHub:** https://github.com/dzhechko/pu-unicorn-replicate
+- **Issues:** https://github.com/dzhechko/pu-unicorn-replicate/issues
+- **Telegram:** https://t.me/llm_notes
+- **Author:** dzhechko
+
+### Companion documentation
+
+- [`CHANGELOG.md`](./CHANGELOG.md) — version history (authoritative)
+- [`KNOWN_LIMITATIONS.md`](./KNOWN_LIMITATIONS.md) — 8 open improvement items
+- [`MULTIPLATFORM_ROADMAP.md`](./MULTIPLATFORM_ROADMAP.md) — Codex/OpenCode/KiloCode support roadmap
+- [`README/ru/`](./README/ru/) — Russian documentation (8 sections)
+- [`README/eng/`](./README/eng/) — English documentation (8 sections, deeper than this README)
+- [`README/ru/html/index.html`](./README/ru/html/index.html) — interactive single-page HTML guide
+
+---
+
+**🚀 Ready to start?**
+
+```bash
+npx @dzhechkov/p-replicator init && claude
+```
+
+Then in Claude Code: `/replicate "your idea"` (new project) or `/feature add-something` (existing project).