@arka-labs/nemesis 1.2.0

package/README.md

@@ -0,0 +1,668 @@
+<p align="center">
+  <pre align="center">
+   █████╗ ██████╗ ██╗  ██╗ █████╗ ██╗      █████╗ ██████╗ ███████╗
+  ██╔══██╗██╔══██╗██║ ██╔╝██╔══██╗██║     ██╔══██╗██╔══██╗██╔════╝
+  ███████║██████╔╝█████╔╝ ███████║██║     ███████║██████╔╝███████╗
+  ██╔══██║██╔══██╗██╔═██╗ ██╔══██║██║     ██╔══██║██╔══██╗╚════██║
+  ██║  ██║██║  ██║██║  ██╗██║  ██║███████╗██║  ██║██████╔╝███████║
+  ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚══════╝
+  </pre>
+</p>
+
+<h1 align="center">Nemesis CLI</h1>
+<p align="center"><strong>PM cockpit for orchestrating AI agent teams</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@arka-labs/nemesis"><img src="https://img.shields.io/npm/v/@arka-labs/nemesis.svg" alt="npm version"></a>
+  <img src="https://img.shields.io/node/v/@arka-labs/nemesis.svg" alt="node version">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="license"></a>
+  <img src="https://img.shields.io/badge/dependencies-1_(xstate)-blue.svg" alt="dependencies">
+  <img src="https://img.shields.io/badge/tests-862%20passing-brightgreen.svg" alt="tests">
+</p>
+
+---
+
+## Why Nemesis?
+
+When you orchestrate a team of AI agents (Claude Code, Copilot, etc.), you need structure: who does what, what's been assigned, what's been delivered, what's broken. Nemesis gives you a **file-first CLI cockpit** to manage all of that without a server, a database, or any runtime dependency. JSON files in your repo are the single source of truth. A remote HCM (Human Capital Management) graph keeps everything in sync.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @arka-labs/nemesis
+
+# Initialize a project in your repo
+nemesis init
+
+# Add an AI agent to your team
+nemesis team add
+
+# Check project status
+nemesis status
+```
+
+Requires **Node.js >= 20**. Single runtime dependency (xstate for workflow state machine).
+
+## Interactive Mode
+
+Run `nemesis` without arguments to launch the interactive menu:
+
+```
+   █████╗ ██████╗ ██╗  ██╗ █████╗ ██╗      █████╗ ██████╗ ███████╗
+  ...
+
+  ARKA Labs CLI v1.2.0  nemesis
+
+  ── Projet ──────────────────────────
+  ❯ status      — Etat du projet + alertes
+    init        — Scaffold structure projet
+    doctor      — Diagnostic complet
+
+  ── Equipe ──────────────────────────
+    team:list   — Organigramme hierarchique
+    team:panneau— Panneau agent
+    team:add    — Ajouter un agent
+    kars        — Profils Kairos disponibles
+
+  ── Travail ─────────────────────────
+    orch        — Dashboard orchestration
+    inbox       — Documents → Mission Contract
+    mission     — Mission Contracts
+    odm         — Ordres de Mission
+    audit       — Audits techniques
+
+  ── Memoire ─────────────────────────
+    notes       — Notes et CRs agents
+    notewriter  — Gestion contexte agent
+
+  ── Infra ───────────────────────────
+    services    — Connexions LLM
+    hcm         — Synchronisation HCM
+    auth        — Login HCM
+    kairos      — Hooks & contexte agent
+
+  Fleches ↑↓ pour naviguer, Enter pour selectionner, q pour quitter
+```
+
+Navigate with arrow keys (or `j`/`k`), press Enter to select, `q` or Escape to quit.
+
+## Commands
+
+### `nemesis init`
+
+Scaffold a new project structure in the current repository.
+
+```bash
+nemesis init
+nemesis init --bare --id MY-PROJECT --name "My Project" --desc "Description"
+```
+
+Creates:
+- `.nemesis/HCM/` — 10 subdirectories for project artifacts (contracts, odm, cr, decisions, etc.)
+- `.nemesis/template/` — 8 JSON templates for structured documents
+- `CONTEXT_PROJECT_*.json` — project context file
+- `REGISTRY-*.json` — team registry (PM only at start)
+- `PROCESS.md` — workflow documentation
+
+### `nemesis team`
+
+The core command. Manages your AI agent team.
+
+#### `nemesis team add`
+
+Onboard a new agent through an interactive 9-step process:
+
+1. Detect project
+2. Select Kairos profile from HCM (or manual entry)
+3. Configure agent (name, role, hierarchy)
+4. Create `memory.md` for the agent
+5. Create contributor card in `.nemesis/HCM/contributors/`
+6. Update team registry
+7. Update `~/.claude/CLAUDE.md` (agent table + workflow tree)
+8. Generate onboarding prompt
+9. Return launch command
+
+```bash
+# Interactive (recommended)
+nemesis team add
+
+# Non-interactive
+nemesis team add --name Agent_Dev --role Implementeur --reports-to PM --no-prompt
+```
+
+Output:
+```
+  ✓ Projet detecte           → MY-PROJECT
+  ✓ Agent configure           → Agent_Dev — Implementeur
+  ✓ memory.md cree            → .nemesis/claude/Agent_Dev/memory.md
+  ✓ Contributor card creee    → .nemesis/HCM/contributors/CONTRIB-Dev.json
+  ✓ Registre mis a jour       → Lane ajoutee : Agent_Dev
+  ✓ CLAUDE.md mis a jour      → Tableau + Workflow
+  ✓ Prompt d'onboarding genere → .nemesis/onboarding/prompt-Dev.md
+  ✓ Commande de lancement      → claude --prompt .nemesis/onboarding/prompt-Dev.md
+
+  Pour demarrer l'agent :
+    claude --prompt .nemesis/onboarding/prompt-Dev.md
+```
+
+#### `nemesis team list`
+
+Display the organizational tree.
+
+```bash
+nemesis team list
+```
+
+```
+  Jeremy Grimonpont (PM)
+  ├── Agent_Nemesis-CLI (Architecte / QA)
+  │   └── Agent_Bot-CLI (Implementeur)
+  └── Agent_ARCH-CLI (Archiviste documentaire)
+```
+
+#### `nemesis team inspect [agent]`
+
+Detailed view of a specific agent: memory stats, assigned OdMs, recent CRs.
+
+```bash
+nemesis team inspect Agent_Bot-CLI
+nemesis team inspect Agent_Bot-CLI --format json
+```
+
+```
+  Agent     : Agent_Bot-CLI
+  Kind      : agent
+  Role      : Implementeur
+  Reporte a : Agent_Nemesis-CLI
+  MCP       : (aucun)
+  Memory    : .nemesis/claude/Agent_Bot-CLI/memory.md (2.1 KB, maj 2026-03-10)
+
+  OdMs assignes :
+  ┌──────────────────┬──────────┬─────────────────────────────┐
+  │ OdM              │ Status   │ Titre                       │
+  ├──────────────────┼──────────┼─────────────────────────────┤
+  │ ODM-NEMESIS-004  │ VALIDE   │ Infrastructure + Team       │
+  └──────────────────┴──────────┴─────────────────────────────┘
+```
+
+#### `nemesis team remove [agent]`
+
+Archive an agent. Files are preserved for traceability (memory.md renamed to .archived).
+
+```bash
+nemesis team remove Agent_Dev
+```
+
+### `nemesis project`
+
+```bash
+nemesis project status    # Synthetic project view: team size, OdMs, decisions, CRs
+nemesis project init      # Alias for "nemesis init"
+```
+
+### `nemesis mission`
+
+Manage Mission Contracts (high-level work packages with gates and task registries).
+
+```bash
+nemesis mission init              # Create a new Mission Contract (auto-generates ID)
+nemesis mission init MCT-001      # Create with explicit ID
+nemesis mission list              # List all contracts
+nemesis mission inspect MCT-001   # Full contract content: cadrage, workflow, tasks
+```
+
+### `nemesis odm`
+
+Manage Ordres de Mission (specific, assignable work items derived from Mission Contracts).
+
+```bash
+nemesis odm init              # Create a new OdM (auto-generates ID)
+nemesis odm init ODM-004      # Create with explicit ID
+nemesis odm list              # List all OdMs with status/assignee/priority
+nemesis odm inspect ODM-004   # Full OdM content + associated CRs
+```
+
+### `nemesis status`
+
+Quick project status with smart alerts.
+
+```bash
+nemesis status
+```
+
+```
+  MY-PROJECT — 2 agent(s), 3 OdM, 1 en cours
+
+  ⚠ Equipe vide — ajoutez un agent : nemesis team add
+  ⚠ ODM-003 en DRAFT mais non assigne
+  ⚠ Agent_Bot n'a pas mis a jour sa memoire depuis 4 jours
+```
+
+Alerts include: empty team, missing Mission Contracts, OdMs without CRs, stale agent memory, unassigned drafts.
+
+### `nemesis hcm`
+
+Synchronize local JSON files with the remote HCM knowledge graph.
+
+```bash
+nemesis hcm status    # Connection diagnostic (ping, auth, graph stats)
+nemesis hcm sync      # Scan .nemesis/HCM/, diff hashes, push modified files
+nemesis hcm search "query"  # Full-text search in HCM documents
+```
+
+The sync engine:
+1. Scans `.nemesis/HCM/` recursively for JSON files
+2. Computes SHA-256 hashes and compares with last sync state
+3. Pushes only modified files to the HCM API
+4. Ignores `template_*` and `legacy_*` files
+
+### `nemesis doctor`
+
+Full system diagnostic.
+
+```bash
+nemesis doctor
+```
+
+```
+  Structure .nemesis/HCM/ :
+    ✓ contracts/
+    ✓ odm/
+    ✓ cr/
+    ...
+
+  Templates .nemesis/template/ :
+    ✓ 8 templates presents
+
+  Config :
+    ✓ Projet detecte : MY-PROJECT
+
+  HCM :
+    ✓ Connexion : 142ms
+    ✓ Auth : API key valide
+    ✓ Graphe : 847 noeuds, 1203 edges
+
+  Registre :
+    ✓ REGISTRY (3 membres)
+    ✓ CLAUDE.md sync (2 agents)
+
+  Agents :
+    ✓ Agent_Nemesis-CLI : memory.md present (3.2 KB)
+    ✓ Agent_Bot-CLI : memory.md present (1.8 KB)
+
+  Tout est OK.
+```
+
+Checks: directory structure (10 dirs), templates (8 files), config file, HCM connection (ping, auth, graph), registry vs CLAUDE.md sync, agent memory files.
+
+### `nemesis orch`
+
+Orchestration dashboard — monitor dispatches, escalations, and deliveries in real-time.
+
+```bash
+nemesis orch              # Auto-refresh every 2s, quit with 'q'
+nemesis orch --once       # Display once and exit
+nemesis orch --format json
+```
+
+The daemon polls for OdMs with status `READY_TO_DISPATCH`, auto-dispatches via headless agents, and routes results through the configured routing chain.
+
+### `nemesis services`
+
+Manage LLM provider connections and hook lifecycle.
+
+```bash
+# Connexions
+nemesis services connexions add       # Add provider (Anthropic, OpenAI, Gemini, Ollama, etc.)
+nemesis services connexions list      # List all connections with status
+nemesis services connexions test      # Health check (auth/endpoint)
+nemesis services connexions live      # Full validation (real LLM call + file I/O)
+
+# Service assignment
+nemesis services config               # Assign connections to services (notes, odm, mc)
+nemesis services status               # Overview of all assignments + fallback chains
+
+# Hooks
+nemesis services hooks status         # Hook state (active/inactive count)
+nemesis services hooks setup          # Enable all hooks
+nemesis services hooks reset          # Disable all hooks
+```
+
+### `nemesis notes`
+
+Browse agent notes and CRs with filtering and timeline views.
+
+```bash
+nemesis notes                         # Interactive menu
+nemesis notes agent Agent_Dev         # View by agent
+nemesis notes timeline                # Project timeline (all agents)
+nemesis notes inspect NOTE-Dev-042    # Display note or CR by ID
+nemesis notes agent Agent_Dev --cr    # Filter CRs only
+nemesis notes agent Agent_Dev --level L3  # Filter by level
+```
+
+### `nemesis notewriter`
+
+Manage agent context: notes, CRs, and session replay.
+
+```bash
+nemesis notewriter status Agent_Dev   # NoteWriter state
+nemesis notewriter cr Agent_Dev       # Generate manual CR (calls LLM)
+nemesis notewriter list Agent_Dev     # List notes and CRs
+nemesis notewriter inspect Agent_Dev NOTE-Dev-042
+nemesis notewriter replay Agent_Dev   # Replay session from JSONL log
+```
+
+### `nemesis kairos`
+
+Install and manage Claude Code hooks for agent context injection.
+
+```bash
+nemesis kairos hooks setup            # Install 4 hooks into .claude/settings.json
+nemesis kairos hooks status           # Verify hook installation
+nemesis kairos hooks remove           # Uninstall hooks
+nemesis kairos push --to Agent_Dev --type CR_DEPOSITED  # Send event
+nemesis kairos events                 # List pending events
+nemesis kairos clear --agent Agent_Dev  # Purge event queue
+```
+
+Four hooks are installed: `SessionStart` (context injection), `UserPromptSubmit` (situation detection + turn logging), `Stop` (note generation + CR check), `PreCompact` (context re-injection).
+
+### `nemesis auth`
+
+Configure HCM authentication.
+
+```bash
+nemesis auth login    # Configure URL + API key (test → save → sync shell RC)
+nemesis auth status   # Show active connection + live ping
+nemesis auth logout   # Remove credentials
+```
+
+### `nemesis kars`
+
+Browse available Kairos profiles by sector.
+
+```bash
+nemesis kars                   # Interactive sector picker
+nemesis kars search --sector cybersecurity
+nemesis kars search --format json
+```
+
+### `nemesis audit`
+
+Run template-based technical audits.
+
+```bash
+nemesis audit list             # Available audit templates
+nemesis audit run              # Launch an audit (template → target → prompt generation)
+nemesis audit reports          # View generated reports
+```
+
+### `nemesis inbox`
+
+Human document pipeline: intake → Leader dispatch → Mission Contract draft.
+
+```bash
+nemesis inbox list             # Pending documents
+nemesis inbox add spec.pdf     # Add document to inbox
+nemesis inbox process          # Dispatch to Leader for MC drafting
+nemesis inbox history          # Completed documents
+```
+
+### `nemesis run`
+
+Resume an agent session.
+
+```bash
+nemesis run agent:Agent_Dev                  # Interactive session (claude --resume)
+nemesis run agent:Agent_Dev --p "fix the bug"  # Direct prompt (headless)
+```
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--format json\|text\|yaml` | Output format (default: `text`) |
+| `--no-color` | Disable ANSI colors |
+| `--verbose` | Detailed error output |
+| `-h, --help` | Help (global and per-command) |
+| `-V, --version` | Print version |
+
+## Architecture
+
+```
+nemesis-cli/
+├── src/
+│   ├── index.js              # Entry point (#!/usr/bin/env node)
+│   ├── cli.js                # Command dispatcher + interactive menu (18 commands)
+│   ├── config.js             # Config loader + project auto-detection
+│   └── commands/             # One handler per command
+│       ├── init.js           # nemesis init
+│       ├── team.js           # nemesis team (add/list/inspect/remove)
+│       ├── project.js        # nemesis project (status/init)
+│       ├── mission.js        # nemesis mission (init/list/inspect)
+│       ├── odm.js            # nemesis odm (init/list/inspect)
+│       ├── status.js         # nemesis status
+│       ├── hcm.js            # nemesis hcm (sync/status/search)
+│       ├── doctor.js         # nemesis doctor
+│       ├── orch.js           # nemesis orch (orchestration dashboard)
+│       ├── services.js       # nemesis services (LLM connections + hooks)
+│       ├── notes.js          # nemesis notes (browse notes/CRs)
+│       ├── notewriter.js     # nemesis notewriter (agent memory management)
+│       ├── kairos.js         # nemesis kairos (hooks + event bus)
+│       ├── auth.js           # nemesis auth (HCM credentials)
+│       ├── kars.js           # nemesis kars (profile search)
+│       ├── audit.js          # nemesis audit (technical audits)
+│       ├── inbox.js          # nemesis inbox (document pipeline)
+│       ├── run.js            # nemesis run (resume agent session)
+│       └── _helpers.js       # Shared utilities (ensureProject, pickFromList)
+├── lib/
+│   ├── core/                 # Business logic (pure functions, no UI)
+│   │   ├── project.js        # initProject, detectProject, getProjectStatus
+│   │   ├── team.js           # teamAdd, teamList, teamInspect, teamRemove
+│   │   ├── registry.js       # Registry CRUD (addLane, removeLane, getLanes)
+│   │   ├── odm.js            # initOdm, listOdm, inspectOdm, setOdmStatus
+│   │   ├── mission.js        # initMission, listMissions, inspectMission
+│   │   ├── templates.js      # Template loading (priority: .nemesis > .owner > embedded)
+│   │   ├── generators.js     # Generate memory.md, onboarding prompts, CLAUDE.md updates
+│   │   ├── logger.js         # Minimal stderr logger (warn, error, debug)
+│   │   ├── secrets.js        # AES-256-GCM encryption with PBKDF2 key derivation
+│   │   ├── audit.js          # Audit template management + prompt generation
+│   │   ├── inbox.js          # Document pipeline (pending → processing → done)
+│   │   ├── connexions.js     # LLM provider connection registry
+│   │   ├── services.js       # Service configuration (assignments, fallback chains)
+│   │   ├── agent-launcher.js # Spawn Claude CLI with streaming JSON parsing
+│   │   ├── profile-picker.js # Kairos profile selection from HCM
+│   │   ├── notewriter/       # Agent memory system
+│   │   │   ├── config.js     # NoteWriter configuration (enable, timers, levels)
+│   │   │   ├── log.js        # Session turn logging (JSONL, open/close)
+│   │   │   ├── notes.js      # Note generation via LLM (L1-L5 depth)
+│   │   │   ├── cr.js         # CR generation (combine notes, LLM summary)
+│   │   │   ├── reader.js     # Timeline + filtering across notes/CRs
+│   │   │   ├── paths.js      # Path resolution (month-bucketed directories)
+│   │   │   └── registry.js   # Notes/CRs index with sequential IDs
+│   │   └── flowmap/          # Workflow state machine (XState v5)
+│   │       ├── machine.js    # 18-state workflow (F00→FIN)
+│   │       ├── api.js        # Actor management + event dispatch
+│   │       ├── persistence.js # XState snapshot I/O
+│   │       └── cli-helpers.js # Display helpers for flowmap status
+│   ├── kairos/               # Agent orchestration hooks
+│   │   ├── hook-handlers.js  # 4 hook entry points (pre/dynamic/post/compact)
+│   │   ├── hook-installer.js # Claude Code hooks installation
+│   │   ├── context-injector.js # Unified context injection via stdout
+│   │   ├── context-writer.js # Situation persistence
+│   │   ├── context-loader.js # Agent context resolution
+│   │   ├── situation-detector.js # Keyword-based situation detection
+│   │   ├── agent-runner.js   # Headless agent dispatch + result polling
+│   │   ├── dispatcher.js     # LLM response classification (LEADER/HUMAN/NOISE)
+│   │   ├── dispatcher-router.js # File-based routing for dispatch results
+│   │   ├── event-bus.js      # Async event queue (TTL, priority, per-agent)
+│   │   ├── event-router.js   # Event routing to agents
+│   │   ├── flowmap-bridge.js # Signal detection → flowmap events
+│   │   ├── pid-checker.js    # Agent PID registration + liveness
+│   │   ├── leader-rules.js   # Leader-specific dispatch/validation rules
+│   │   ├── hook-prompts.js   # Prompt templates for hooks
+│   │   └── claude-invoker.js # Claude CLI invocation wrapper
+│   ├── sync/                 # HCM + LLM communication
+│   │   ├── hcm-client.js     # HCM HTTP client (vanilla fetch, Node 20+)
+│   │   ├── sync-engine.js    # Hash-based scan/diff/sync engine
+│   │   ├── health.js         # HCM connection diagnostic
+│   │   ├── nemesis-client.js # Nemesis API client
+│   │   ├── llm-client.js     # Multi-provider LLM client
+│   │   ├── service-session.js # LLM API caller with fallback
+│   │   └── fallback-engine.js # Silent cascade across connections
+│   └── ui/                   # Terminal display
+│       ├── brand.js          # ARKA LABS ASCII logo + branded headers
+│       ├── colors.js         # ANSI color system (NO_COLOR / FORCE_COLOR aware)
+│       ├── box.js            # Unicode box drawing (emoji-aware width)
+│       ├── table.js          # ASCII table renderer
+│       ├── tree.js           # Hierarchical tree renderer
+│       ├── menu.js           # Interactive keyboard menu (arrows, j/k, scrolling)
+│       ├── prompt.js         # Interactive prompts (text, choice, confirm)
+│       ├── spinner.js        # Braille-pattern loading spinner
+│       ├── format.js         # Output formatter (JSON / YAML / text)
+│       ├── dashboard.js      # Orchestration dashboard (real-time monitoring)
+│       ├── streambox.js      # Streaming JSON output renderer
+│       ├── note-card.js      # Note/CR card components
+│       ├── note-colors.js    # Level-based color system (L1-L5)
+│       ├── note-detail.js    # Note/CR detail views
+│       ├── note-filters.js   # Filter panel UI
+│       ├── note-views.js     # Agent/timeline views
+│       └── error-hints.js    # User-friendly error suggestions
+├── templates/                # 9 embedded JSON templates
+└── test/                     # 862 tests across 88 files
+    ├── unit/                 # Pure function tests (68 files)
+    ├── integration/          # Multi-module tests with temp directories (12 files)
+    └── e2e/                  # Full workflow test
+```
+
+### How It Fits Together
+
+```
+                          ┌──────────────────┐
+                          │    HCM Graph      │
+                          │  (remote API)     │
+                          └────────▲──────────┘
+                                   │ sync (hash-based)
+┌──────────────┐          ┌────────┴──────────┐
+│  PM (human)  │◄────────►│   nemesis CLI     │
+│  via terminal│          │                   │
+└──────────────┘          │  reads/writes     │
+                          │  .nemesis/HCM/    │
+                          └────────▲──────────┘
+                                   │ JSON files
+                          ┌────────┴──────────┐
+                          │  AI Agents        │
+                          │  (Claude Code)    │
+                          │                   │
+                          │  write OdM, CR,   │
+                          │  decisions, etc.  │
+                          └───────────────────┘
+```
+
+**Data flow:** Agents produce structured JSON artifacts (OdMs, CRs, decisions) in `.nemesis/HCM/`. Kairos hooks inject context at session start, detect situations dynamically, generate notes/CRs on each turn, and route dispatch results through the configured routing chain. The orchestrator daemon (`nemesis orch`) auto-dispatches OdMs and monitors the entire lifecycle. The PM uses Nemesis CLI to observe progress, manage the team, and orchestrate work.
+
+### Design Principles
+
+1. **File-first** — All data lives in `.nemesis/HCM/` as JSON files. No local database.
+2. **Read-heavy, write-light** — The CLI reads a lot (status, inspect, list) and writes little (init, team add). Agents do the writing.
+3. **Daemon-light** — `nemesis orch` provides real-time orchestration via filesystem polling (no background service required).
+4. **Minimal dependencies** — Only xstate (workflow state machine) at runtime. All UI, crypto, and I/O use Node.js built-ins.
+5. **Portable** — Works on any repo. Auto-detects project from `.nemesis/HCM/project/CONTEXT_PROJECT_*.json`.
+
+## Configuration
+
+### Config File
+
+Optional global configuration at `~/.nemesis/config.json`:
+
+```json
+{
+  "defaults": {
+    "hcm_url": "https://hcm.arkalabs.app",
+    "hcm_api_key_env": "HCM_API_KEY"
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HCM_URL` | HCM API base URL | `https://hcm.arkalabs.app` |
+| `HCM_API_KEY` | API key for HCM authentication | (none) |
+| `NO_COLOR` | Disable all ANSI colors ([no-color.org](https://no-color.org)) | — |
+| `FORCE_COLOR` | Force colors even without TTY | — |
+| `NEMESIS_COLOR` | Override color detection (`0` = off, `1` = on) | — |
+| `NEMESIS_VERBOSE` | Enable debug logging to stderr (`1` = on) | — |
+
+### Project Auto-Detection
+
+The CLI auto-detects the current project by looking for:
+
+1. `.nemesis/HCM/project/CONTEXT_PROJECT_*.json` (primary)
+2. `.owner/HCM/project/CONTEXT_PROJECT_*.json` (legacy fallback)
+
+No project detected? Run `nemesis init` or the CLI will offer to initialize one interactively.
+
+### Template Priority
+
+When loading templates for new documents (OdM, CR, Mission Contract, etc.):
+
+1. `.nemesis/template/` (project-specific overrides)
+2. `.owner/template/` (legacy path)
+3. `templates/` (embedded defaults shipped with the package)
+
+## Embedded Templates
+
+Nemesis ships with 9 JSON templates for structured documents:
+
+| Template | Purpose |
+|----------|---------|
+| `template_ODM-NAME-000.json` | Ordre de Mission |
+| `template_CR-ODM-NAME-000.exemple.json` | Compte-Rendu (delivery report) |
+| `template_MISSION_CONTRACT.json` | Mission Contract (work package) |
+| `template_REGISTRY-PROJECT.json` | Team registry |
+| `template_DEC-NAME-000.json` | Decision record |
+| `template_INTV-NAME-000.json` | Intervention log |
+| `template_CONTRIB-NAME.json` | Contributor card |
+| `template_TXN-NAME-000.json` | Transaction record |
+| `project-context.json` | Project context |
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/arka-squad/arkalabs-nemesis-cli.git
+cd arkalabs-nemesis-cli
+
+# Install dependencies
+npm install
+
+# Link for local development
+npm link
+
+# Run tests
+npm test              # 862 tests across 88 files
+npm run test:watch    # Watch mode
+npm run test:coverage # With coverage report (v8, thresholds: 50% lines / 60% functions)
+npm run lint          # ESLint check
+npm run lint:fix      # ESLint auto-fix
+```
+
+### Test Structure
+
+862 tests across 88 files, organized in three categories:
+
+- **Unit** (`test/unit/`, 68 files) — pure function tests covering core logic, UI components, kairos hooks, notewriter, flowmap, dispatcher, event bus, secrets, logger, and more
+- **Integration** (`test/integration/`, 12 files) — multi-module tests with temp directories (init, team, mission, odm, doctor, hcm-sync, services, event-bus, orch-dashboard, nemesis-mcp)
+- **E2E** (`test/e2e/`, 1 file) — full workflow: init → team → mission → odm → sync → remove
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute.
+
+## License
+
+[Apache License 2.0](LICENSE) — ARKA LABS