@damenor/agent-docs 0.1.1 → 0.4.0

package/README.md

@@ -64,19 +64,21 @@ npx @damenor/agent-docs
 
 ### What comes out:
 
+Every file is generated programmatically by 22 TypeScript generators — no static templates copied. Each generator produces content tailored to your stack and language.
+
 ```
 my-project/
 ├── AGENTS.md              🤖 AI agent protocol (they finally behave)
 ├── docs/
 │   ├── CONTEXT.md         📝 Domain glossary (everyone speaks the same language)
 │   ├── README.md          📑 Docs index (navigable from day one)
+│   ├── DESIGN.md          🎨 Design system tokens (colors, typography, spacing)
 │   ├── tutorials/         🎓 Step-by-step learning (onboarding in 15 min, not 2 hours)
 │   ├── guides/            📖 How-to guides (deployment, troubleshooting, runbooks)
 │   ├── reference/         📋 Technical reference (API, config, infra, code-style)
 │   ├── explanation/       🏗️ Architecture decisions (ADRs, not lost Slack messages)
 │   ├── product/           📊 Overview & roadmap (what are we building again?)
 │   ├── operations/        🔧 Monitoring & incidents (when prod goes brrr)
-│   ├── DESIGN.md          🎨 Design system tokens (colors, typography, spacing)
 │   └── adr/               📐 Architecture Decision Records (decisions that last)
 ├── .agents/               🤖 5 skills + 5 agents (your AI team is ready)
 ├── .github/workflows/     ⚙️ CI/CD for docs (never ship broken docs again)
@@ -90,33 +92,57 @@ my-project/
 
 Every project is different. Mix and match:
 
-| 🎯 Module | 📄 What you get | 💡 Why you care |
-|-----------|----------------|----------------|
-| 🎓 Tutorials | quick-start, setup, first-task | New dev productive in 15 min |
-| 📖 Guides | deployment, troubleshooting, runbooks | No more "it works on my machine" |
-| 📋 Reference | API, config, infra, code-style | Stop answering the same questions |
-| 🏗️ Explanation | architecture.md | Everyone understands the big picture |
-| 📊 Product | overview, roadmap | Stakeholders know what's happening |
-| 🔧 Operations | monitoring, incidents, SLAs | Prod issues resolved faster |
-| 🎨 Design System | DESIGN.md with tokens | Consistent UI, no guesswork |
-| 🤖 AI Agent Skills | 5 skills + 5 agents | AI agents that actually help |
-| ⚙️ CI/CD | GitHub Actions workflow | Docs checked on every PR |
+| 🎯 Module          | 📄 What you get                       | 💡 Why you care                      |
+| ------------------ | ------------------------------------- | ------------------------------------ |
+| 🎓 Tutorials       | quick-start, setup, first-task        | New dev productive in 15 min         |
+| 📖 Guides          | deployment, troubleshooting, runbooks | No more "it works on my machine"     |
+| 📋 Reference       | API, config, infra, code-style        | Stop answering the same questions    |
+| 🏗️ Explanation     | architecture.md                       | Everyone understands the big picture |
+| 📊 Product         | overview, roadmap                     | Stakeholders know what's happening   |
+| 🔧 Operations      | monitoring, incidents, SLAs           | Prod issues resolved faster          |
+| 🎨 Design System   | DESIGN.md with tokens                 | Consistent UI, no guesswork          |
+| 🤖 AI Agent Skills | 5 skills + 5 agents                   | AI agents that actually help         |
+| ⚙️ CI/CD           | GitHub Actions workflow               | Docs checked on every PR             |
 
 **Plus** the base layer is always included: `AGENTS.md`, `CONTEXT.md`, `README.md`, ADR template, and shared configs.
 
 ---
 
+## 🛡️ Conflict detection — non-destructive by default
+
+Running the CLI in a project that already has docs? It detects existing files and **skips them by default** — never overwriting your work.
+
+| Flag              | What it does                                             |
+| ----------------- | -------------------------------------------------------- |
+| `--force`         | Overwrite all existing files                             |
+| `--skip-existing` | Skip all conflicts silently (no prompts)                 |
+| `--merge`         | Merge `AGENTS.md` heading-by-heading instead of skipping |
+| `--dry-run`       | Preview what would be generated without writing anything |
+
+```bash
+# Safe re-run: merge AGENTS.md, skip everything else
+npx @damenor/agent-docs --merge
+
+# Preview mode: see what would change
+npx @damenor/agent-docs --dry-run
+
+# CI mode: non-interactive, skip all conflicts
+npx @damenor/agent-docs --skip-existing
+```
+
+---
+
 ## 🔍 Auto-detects your stack
 
 No manual configuration. The CLI reads your project and figures it out:
 
-| 📁 Found | 🛠️ Detected | ✨ Auto-injected |
-|----------|-------------|-----------------|
-| `package.json` | Node.js + framework + pkg manager | `npm run dev`, `npm test`, etc. |
-| `pyproject.toml` | Python + Django/FastAPI/Flask | `python manage.py runserver`, etc. |
-| `go.mod` | Go | `go run .`, `go test ./...` |
-| `Cargo.toml` | Rust | `cargo run`, `cargo test` |
-| `pom.xml` / `build.gradle` | Java/Kotlin + Spring | `mvn spring-boot:run`, etc. |
+| 📁 Found                   | 🛠️ Detected                       | ✨ Auto-injected                   |
+| -------------------------- | --------------------------------- | ---------------------------------- |
+| `package.json`             | Node.js + framework + pkg manager | `npm run dev`, `npm test`, etc.    |
+| `pyproject.toml`           | Python + Django/FastAPI/Flask     | `python manage.py runserver`, etc. |
+| `go.mod`                   | Go                                | `go run .`, `go test ./...`        |
+| `Cargo.toml`               | Rust                              | `cargo run`, `cargo test`          |
+| `pom.xml` / `build.gradle` | Java/Kotlin + Spring              | `mvn spring-boot:run`, etc.        |
 
 Supports **Next.js, Nuxt, Astro, SvelteKit, React, Vue, Express, NestJS, Fastify, Hono, Django, FastAPI, Flask**, and more.
 
@@ -140,6 +166,7 @@ npx @damenor/agent-docs --agents-guide
 ```
 
 Outputs a structured guide that tells AI agents **exactly** what to do after generation:
+
 - ✅ What files to fill and in what order
 - ✅ What to delete if it doesn't apply
 - ✅ Which placeholders to verify
@@ -151,20 +178,29 @@ No guessing. No "I'll add docs later". Your AI agent runs this and knows the dri
 
 ## 📊 Before vs After
 
-| 😩 Before | 🤩 After |
-|-----------|----------|
-| "Where are the docs?" → "What docs?" | Professional docs index, navigable from day one |
-| New dev onboarding: 2 hours | New dev onboarding: 15 minutes |
-| AI agent: "I don't know the context" | AI agent: "I read AGENTS.md, I know the rules" |
-| "How do we deploy?" → Slack thread with 47 messages | `docs/guides/deployment.md` — one click |
-| Every project documents differently | Consistent Diátaxis structure across all projects |
-| Architecture decisions lost in Slack/Notion | ADRs that persist and are searchable |
+| 😩 Before                                           | 🤩 After                                          |
+| --------------------------------------------------- | ------------------------------------------------- |
+| "Where are the docs?" → "What docs?"                | Professional docs index, navigable from day one   |
+| New dev onboarding: 2 hours                         | New dev onboarding: 15 minutes                    |
+| AI agent: "I don't know the context"                | AI agent: "I read AGENTS.md, I know the rules"    |
+| "How do we deploy?" → Slack thread with 47 messages | `docs/guides/deployment.md` — one click           |
+| Every project documents differently                 | Consistent Diátaxis structure across all projects |
+| Architecture decisions lost in Slack/Notion         | ADRs that persist and are searchable              |
+
+---
+
+## 🧪 Battle-tested
+
+- **129 tests** across 19 test files
+- **98.66% statement coverage** — every generator, resolver, and utility is tested
+- **Vitest** for unit and integration testing
+- Tests run on every PR via GitHub Actions
 
 ---
 
-## 🌐 Web docs — coming soon
+## 🌐 Web docs
 
-A beautiful documentation site powered by Astro + Starlight. Publish your docs as a searchable website with zero config.
+A beautiful documentation site powered by Astro + Starlight lives in `packages/web/`. Publish your docs as a searchable website with zero config.
 
 ---