@dzhechkov/p-replicator 1.5.3 → 1.5.5

package/README.md

@@ -1,57 +1,94 @@
-# @dzhechkov/p-replicator
+<div align="center">
 
-> **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.
+# 🚀 @dzhechkov/p-replicator
 
-[![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)
+### **Claude Code toolkit for AI-assisted product development**
+##### *Transform a product idea — or existing project — into fully documented, validated, toolkit-equipped code*
 
-**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)
+<br>
 
-## Documentation in your language
+[![npm version](https://img.shields.io/npm/v/@dzhechkov/p-replicator?color=cb3837&label=npm&style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@dzhechkov/p-replicator)
+[![License](https://img.shields.io/badge/License-MIT-22c55e.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/node-%E2%89%A516-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)
 
-- 🇷🇺 [Документация на русском](./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
+[![Tests](https://img.shields.io/badge/tests-105%2F105-22c55e?style=flat-square)](#test-infrastructure)
+[![Skills](https://img.shields.io/badge/skills-10-8b5cf6?style=flat-square)](#skills-reference)
+[![Commands](https://img.shields.io/badge/slash%20commands-11-f59e0b?style=flat-square)](#commands-reference)
+[![Hooks](https://img.shields.io/badge/hooks-6-3b82f6?style=flat-square)](#hooks-system)
+[![SPARC Pipeline](https://img.shields.io/badge/SPARC-5%20phases-ec4899?style=flat-square)](#pipeline-overview--replicate-phases)
 
-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.
+<br>
+
+**[📦 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)**
+
+</div>
 
 ---
 
-## 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)
+## 📚 Documentation in your language
+
+| Language | Format | Description |
+|---|---|---|
+| 🇷🇺 Русский | [Markdown (8 sections)](./README/ru/README.md) | ~3000 строк deep-dive докуменации |
+| 🇬🇧 English | [Markdown (8 sections)](./README/eng/README.md) | ~3000 lines deep-dive documentation |
+| 🌐 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.
 
 ---
 
-## What is p-replicator?
+## 📑 Table of Contents
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**🌟 Getting Started**
+- [📖 What is p-replicator?](#-what-is-p-replicator)
+- [🚀 Quick Start](#-quick-start)
+- [📑 Already have technical docs?](#-already-have-technical-documentation)
+- [🔧 Adding features (Mode 2)](#-adding-features-to-an-existing-project-mode-2)
+- [📦 Installation](#-installation)
+- [📋 What Gets Installed](#-what-gets-installed)
+- [✅ Verify the install](#-verify-the-install)
+
+**🛠️ Reference**
+- [🎯 Pipeline overview](#-pipeline-overview--replicate-phases)
+- [🧠 Skills Reference](#-skills-reference)
+- [⚡ Commands Reference](#-commands-reference)
+- [💻 CLI Commands](#-cli-commands)
+- [🎚️ Validation Cycle](#-validation-cycle-details)
+- [🔄 Feature Lifecycle](#-feature-lifecycle--feature-command)
+
+</td>
+<td width="50%" valign="top">
+
+**⚙️ Operations**
+- [📊 Statusline Dashboard](#-statusline-dashboard)
+- [🪝 Hooks System](#-hooks-system)
+- [🗺️ Roadmap & Insights](#%EF%B8%8F-roadmap--insights)
+- [🏛️ Architecture Highlights](#%EF%B8%8F-architecture-highlights)
+- [⚙️ Configuration](#%EF%B8%8F-configuration)
+- [🔄 Update workflow](#-update-workflow)
+
+**🆘 Help & Meta**
+- [🆘 Troubleshooting](#-troubleshooting)
+- [📈 Migration](#-migration)
+- [🧪 Test Infrastructure](#-test-infrastructure)
+- [⚠️ Known Limitations](#%EF%B8%8F-known-limitations)
+- [📜 Changelog Highlights](#-changelog-highlights)
+- [🤝 Contributing](#-contributing)
+- [📃 License](#-license)
+
+</td>
+</tr>
+</table>
+
+> 💡 **Quick navigation tip:** TOC items use emoji visual anchors instead of plain text — easier to scan than 26 dark-blue links.
+
+<div align="center">━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</div>
+
+## 📖 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.
 
@@ -83,7 +120,7 @@ Plus **`/feature`** for adding new features to a project with the same SPARC-min
 
 ---
 
-## Quick Start
+## 🚀 Quick Start
 
 ```bash
 # 1. Install in any project
@@ -108,7 +145,7 @@ After `/replicate` completes:
 
 ---
 
-## Already have technical documentation?
+## 📑 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:
 
@@ -137,7 +174,7 @@ Full recipe: see [User Guide](./README/eng/02_user_guide.md#starting-from-existi
 
 ---
 
-## Adding features to an existing project (Mode 2)
+## 🔧 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):
 
@@ -183,17 +220,17 @@ cat > .claude/feature-roadmap.json << 'EOF'
 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)
+> ⚠️ **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
+## 📦 Installation
 
 ### Prerequisites
 
@@ -219,7 +256,7 @@ This creates:
 - `.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.
+> 📌 **Idempotency:** `init` will NOT overwrite existing files without `--force`. Your `CLAUDE.md`, custom commands, and modified settings are preserved.
 
 ### Common install scenarios
 
@@ -234,7 +271,7 @@ This creates:
 
 ---
 
-## What Gets Installed
+## 📋 What Gets Installed
 
 | Component | Count | Description |
 |-----------|-------|-------------|
@@ -258,7 +295,7 @@ After running `/replicate`, the toolkit also generates **project-specific** arti
 
 ---
 
-## Verify the install
+## ✅ Verify the install
 
 After `/replicate`, run:
 
@@ -285,7 +322,7 @@ npx @dzhechkov/p-replicator doctor
 
 ---
 
-## Pipeline overview — `/replicate` phases
+## 🎯 Pipeline overview — `/replicate` phases
 
 ### Phase 0 — Product Discovery (optional)
 
@@ -353,7 +390,7 @@ Skill: `cc-toolkit-generator-enhanced` (9 modules with quality gates).
 
 ---
 
-## Skills Reference
+## 🧠 Skills Reference
 
 | Skill | Purpose |
 |-------|---------|
@@ -405,7 +442,7 @@ Claude Code resolves these references dynamically — when executing a skill, th
 
 ---
 
-## Commands Reference
+## ⚡ Commands Reference
 
 | Command | Purpose | When to use |
 |---|---|---|
@@ -473,7 +510,7 @@ Extract reusable patterns from a completed project into a knowledge base. Skill:
 
 ---
 
-## CLI Commands
+## 💻 CLI Commands
 
 ### Subcommands
 
@@ -508,7 +545,7 @@ Extract reusable patterns from a completed project into a knowledge base. Skill:
 
 ---
 
-## Validation Cycle Details
+## 🎚️ Validation Cycle Details
 
 The same validation pipeline runs in **`/replicate` Phase 2** and **`/feature` Phase 2**. Skill: `requirements-validator`.
 
@@ -552,7 +589,7 @@ Output: `docs/features/<id>/review-report.md`.
 
 ---
 
-## Feature Lifecycle — `/feature` command
+## 🔄 Feature Lifecycle — `/feature` command
 
 `/feature <id>` runs a 4-phase lifecycle: **PLAN → VALIDATE → IMPLEMENT → REVIEW**. Project-context-aware (reads `docs/`), checkpoint-driven, parallel where independent.
 
@@ -607,7 +644,7 @@ Severity-classified findings. Critical (`blocker` | `high`) MUST be fixed.
 
 ---
 
-## Statusline Dashboard
+## 📊 Statusline Dashboard
 
 **6-line ANSI dashboard** above Claude Code's prompt with real-time pipeline + roadmap + toolkit + status metrics.
 
@@ -650,7 +687,7 @@ For internals, see [admin guide](./README/eng/03_admin_guide.md#statusline--dash
 
 ---
 
-## Hooks System
+## 🪝 Hooks System
 
 `p-replicator` ships **6 cross-platform Node scripts** in `.claude/hooks/`:
 
@@ -705,7 +742,7 @@ Pipeline commands optionally call this script (via Bash tool) so statusline show
 
 ---
 
-## Roadmap & Insights
+## 🗺️ Roadmap & Insights
 
 ### Feature roadmap (`.claude/feature-roadmap.json`)
 
@@ -773,7 +810,7 @@ What fixed it (1-5 sentences with code if relevant).
 
 ---
 
-## Architecture Highlights
+## 🏛️ Architecture Highlights
 
 ### Two-tier model: Pre-shipped vs Project-generated
 
@@ -782,7 +819,7 @@ What fixed it (1-5 sentences with code if relevant).
 | **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.
+> 💡 **Key insight:** 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`
 
@@ -820,7 +857,7 @@ For complete internals, see [`README/eng/05_architecture.md`](./README/eng/05_ar
 
 ---
 
-## Configuration
+## ⚙️ Configuration
 
 ### `.claude/settings.json`
 
@@ -828,7 +865,7 @@ Default structure after `init`:
 
 ```json
 {
-  "$schema": "https://www.schemastore.org/claude-code-settings.json",
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "_comment": "Default hooks + statusline shipped by @dzhechkov/p-replicator init.",
   "statusLine": {
     "type": "command",
@@ -893,7 +930,7 @@ If `.keysarium.json` (from sibling `@dzhechkov/keysarium` package) is detected:
 
 ---
 
-## Update workflow
+## 🔄 Update workflow
 
 ```bash
 # Safe upgrade with preserved customizations:
@@ -923,7 +960,14 @@ npx @dzhechkov/p-replicator verify
 
 ---
 
-## Troubleshooting
+## 🆘 Troubleshooting
+
+> 💡 **Tip:** This section covers the 12 most common issues. For a comprehensive 15+ case troubleshooting reference with detailed diagnostics, see [`README/eng/06_troubleshooting.md`](./README/eng/06_troubleshooting.md).
+
+<details>
+<summary><b>👉 Click to expand 12 common issues + fixes</b></summary>
+
+<br>
 
 ### `init` refuses: "P-Replicator is already installed"
 
@@ -1071,9 +1115,16 @@ Workaround: temporarily disable statusline by removing the `statusLine` field in
 
 For full troubleshooting (15+ issues with detailed diagnostics), see [`README/eng/06_troubleshooting.md`](./README/eng/06_troubleshooting.md).
 
+</details>
+
 ---
 
-## Migration
+## 📈 Migration
+
+<details>
+<summary><b>👉 Click to expand per-version migration matrix</b></summary>
+
+<br>
 
 | From → To | What you get | Migration cost |
 |---|---|---|
@@ -1085,7 +1136,7 @@ For full troubleshooting (15+ issues with detailed diagnostics), see [`README/en
 | 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.
+> ✅ **No breaking changes** between any versions. All upgrades are backward-compatible.
 
 After any upgrade — `verify` to confirm contract:
 
@@ -1093,9 +1144,16 @@ After any upgrade — `verify` to confirm contract:
 npx @dzhechkov/p-replicator verify
 ```
 
+</details>
+
 ---
 
-## Test Infrastructure
+## 🧪 Test Infrastructure
+
+<details>
+<summary><b>👉 Click to expand test layer breakdown + meta-tests</b></summary>
+
+<br>
 
 **Suite:** 105 tests, 36 suites, ~25 sec runtime.
 
@@ -1118,9 +1176,11 @@ npm run test:e2e                            # e2e only
 npm run test:snapshot                       # snapshot only
 ```
 
+</details>
+
 ---
 
-## Known Limitations
+## ⚠️ Known Limitations
 
 For currently-open improvement items — see [`KNOWN_LIMITATIONS.md`](./KNOWN_LIMITATIONS.md) (8 entries: 3 medium, 5 low priority).
 
@@ -1135,7 +1195,19 @@ For multiplatform support roadmap (Codex, OpenCode, KiloCode) — see [`MULTIPLA
 
 ---
 
-## Changelog Highlights
+## 📜 Changelog Highlights
+
+> 📌 For full version history with migration notes — see [`CHANGELOG.md`](./CHANGELOG.md) (authoritative source).
+
+<details>
+<summary><b>👉 Click to expand 9 versions: v1.3.0 → v1.5.3</b></summary>
+
+<br>
+
+### v1.5.3 — 2026-05-07 (Comprehensive README + visual polish)
+
+- 📚 **Expanded `README.md`** from ~14.6 kB to ~50 kB (consolidating 8 eng/ files for npm registry visibility)
+- 🎨 Visual polish: hero banner, 8 badges, emoji TOC, collapsible sections, callout blocks, `<kbd>` for CLI commands
 
 ### v1.5.2 — 2026-05-07 (Mode 2 documentation)
 
@@ -1190,11 +1262,11 @@ Formalized **"Starting from existing technical documentation"** workflow for `/r
 
 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).
+</details>
 
 ---
 
-## Contributing
+## 🤝 Contributing
 
 This package is part of the [`pu-unicorn-replicate`](https://github.com/dzhechko/pu-unicorn-replicate) monorepo.
 
@@ -1239,7 +1311,7 @@ Each significant improvement is persisted as a cross-session pattern (16+ entrie
 
 ---
 
-## License
+## 📃 License
 
 MIT — see [LICENSE](./LICENSE).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/p-replicator",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "P-Replicator — Claude Code toolkit for AI-assisted product development (Vibe Coding). Full /replicate pipeline, 10 modular skills (194K+ chars), /harvest knowledge extraction, swarm agents, quality gates, security patterns, cross-project learning.",
   "main": "src/cli.js",
   "bin": {
@@ -17,8 +17,7 @@
     "test:e2e": "node --test tests/e2e/lifecycle.test.js",
     "test:snapshot": "node --test tests/snapshot/templates.test.js",
     "test:doctor": "node bin/cli.js doctor",
-    "snapshot:baseline": "node tests/snapshot/update-baseline.js",
-    "prepublishOnly": "node scripts/sync-templates.js"
+    "snapshot:baseline": "node tests/snapshot/update-baseline.js"
   },
   "keywords": [
     "claude",
@@ -55,18 +54,22 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/dzhechko/pu-unicorn-replicate"
+    "url": "https://github.com/djd1m/dz-harness-hub.git",
+    "directory": "packages/@dzhechkov/p-replicator"
   },
-  "homepage": "https://github.com/dzhechko/pu-unicorn-replicate#readme",
+  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/p-replicator#readme",
   "bugs": {
-    "url": "https://github.com/dzhechko/pu-unicorn-replicate/issues"
+    "url": "https://github.com/djd1m/dz-harness-hub/issues"
   },
   "peerDependencies": {
-    "@dzhechkov/keysarium-core": "^1.0.0"
+    "@dzhechkov/keysarium-core": "^1.1.0"
   },
   "peerDependenciesMeta": {
     "@dzhechkov/keysarium-core": {
       "optional": true
     }
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/templates/.claude/settings.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://www.schemastore.org/claude-code-settings.json",
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "_comment": "Default hooks + statusline shipped by @dzhechkov/p-replicator init. Cross-platform Node scripts (no bash dependencies). Auto-commits roadmap/insights/plans on Stop, injects relevant insights on SessionStart. Statusline displays pipeline+roadmap+toolkit dashboard above the prompt. Project-specific hooks (DDD, fitness functions, etc.) are merged in by /replicate Phase 3.",
   "statusLine": {
     "type": "command",