@dinyangetoh/codeplug-cli 0.1.4 → 0.1.5

package/README.md

@@ -1,63 +1,50 @@
 # CodePlug
 
-## Executive Summary
-
-This document provides comprehensive technical documentation for CodePlug, a local-first CLI tool designed to detect, enforce, and document coding conventions across TypeScript/JavaScript codebases. The guide covers installation, configuration, usage commands, project architecture, and development workflows for teams seeking automated codebase governance with AI agent integration capabilities.
-
----
+> The source of truth for codebase understanding & governance.
 
 ## Overview
 
-**The source of truth for codebase understanding and governance.**
-
-CodePlug is a local-first CLI tool that detects your codebase's coding conventions, enforces them with drift detection and compliance scoring, generates living documentation, and exports convention context for AI coding agents.
-
-The tool operates entirely on-device using ML models for pattern detection, ensuring your codebase data never leaves your machine unless you explicitly configure cloud LLM providers for enhanced documentation generation.
+This document is the primary technical reference for **CodePlug** (`@dinyangetoh/codeplug-cli`), a professional-grade, local-first CLI tool designed to detect, enforce, and document coding conventions across TypeScript and JavaScript codebases. It covers installation, configuration, usage, and the underlying architecture to help developers integrate CodePlug into their workflows. CodePlug combines AST analysis with on-device ML inference to provide automated convention governance, living documentation generation, and structured AI agent context export — ensuring both human developers and AI assistants adhere to the same project standards.
 
 ---
 
-## Key Features
-
-### Convention Detection
-
-AST analysis with on-device ML identifies naming patterns, folder structure, component styles, test organization, error handling, and import conventions across your TypeScript/JavaScript codebase.
+## Key Descriptions
 
-### Drift & Compliance
+CodePlug acts as the **source of truth for codebase understanding**. It uses AST visitors and on-device ML models (via `@huggingface/transformers`, with no Python dependency) to identify patterns across naming, structure, components, and error handling. It generates "living documentation" and structured rule files for AI agents (Claude, Cursor, Copilot), and provides a compliance scoring engine to prevent architectural drift over time.
 
-Classifies git diffs against stored conventions, scores compliance with severity-weighted metrics, tracks trends over time, and auto-fixes what it can.
-
-### Living Documentation
+---
 
-Generates and maintains README, ARCHITECTURE, CONVENTIONS, CONTRIBUTING, and ONBOARDING docs using ML summarization and optional LLM enhancement.
+## Key Features
 
-### AI Agent Export
+### Convention Detection & Governance
+- **Multi-Dimensional AST Analysis:** Six to seven specialized visitors identify naming patterns, component styles, test organization, error handling, and import conventions.
+- **Drift & Compliance Scoring:** Classifies git diffs against stored conventions, scores compliance with severity-weighted metrics, and tracks trends via an internal `sql.js` time-series database.
+- **Auto-Fix:** Supports automated renaming and provides guided remediation for complex violations.
 
-Exports your conventions as `CLAUDE.md`, `.cursor/rules`, `.github/copilot-instructions.md`, structured JSON, and SARIF-format CI reports.
+### Documentation & AI Integration
+- **Living Documentation:** Automatically maintains `ARCHITECTURE.md`, `CONVENTIONS.md`, and `ONBOARDING.md` using ML summarization pipelines (BART, BERT).
+- **AI Agent Export:** Generates context files including `CLAUDE.md`, `.cursor/rules`, and `.github/copilot-instructions.md`.
+- **CI/CD Ready:** Exports SARIF-format reports for integration with GitHub Actions and other CI pipelines.
 
-### All Features
+### Feature Matrix
 
-| Category | Feature | Command / Config | Notes |
-|----------|---------|------------------|-------|
-| CLI | Interactive wizard | `codeplug start` | Config, Convention, Docs, Export menus; see [COMMAND.md](COMMAND.md) |
-| Convention | Detection (6 dimensions) | `convention init` | Naming, Component, Test, ErrorHandling, Import, Schema visitors |
-| Convention | Structure (7th dimension) | `convention audit` | StructureVisitor in ViolationDetector |
-| Convention | Drift | `convention drift` | Rule-based diff classification |
-| Convention | Compliance | `convention audit`, `score` | Severity-weighted, sql.js time-series |
-| Convention | Auto-fix | `convention fix` | Rename + manual guidance |
-| Convention | Semantic coherence | `convention.enableSemanticCoherence` | Opt-in; zero-shot + sentenceSimilarity |
-| Convention | Custom rules | `.codeplug/rules.json` | Regex rules (filename, path, content) |
-| Docs | Generate / Status / Update | `docs generate/status/update` | 5 docs, ML pipeline + optional LLM; template fallback |
-| Export | Claude / Cursor / Copilot | `export --target` | CLAUDE.md, .cursor/rules, .github/copilot-instructions |
-| Export | JSON / CI (SARIF) | `export --target json/ci` | .codeplug/exports/, .codeplug/ci-report.json |
-| Config | Model tier, LLM provider | `config set` | default / lite; 8 providers |
+| Category | Feature | Command | Notes |
+|---|---|---|---|
+| **CLI** | Interactive Wizard | `codeplug start` | Single entry point for all menus |
+| **Audit** | Compliance Score | `codeplug convention score` | Severity-weighted, time-series tracking |
+| **Docs** | ML Generation | `codeplug docs generate` | 5 core docs; optional LLM enhancement |
+| **Export** | AI Context | `codeplug export --all` | Supports Claude, Cursor, Copilot, JSON |
+| **Config** | Model Tiers | `codeplug config set` | Choose between `default` or `lite` models |
 
 ---
 
 ## Prerequisites
 
-- **Node.js 20+** (required) — CodePlug is built with TypeScript and requires Node.js 20 or higher for native fetch and modern ESM support.
-- **Git** (required for drift detection and history analysis) — CodePlug integrates with Git for diff analysis, commit history inspection, and pre-commit hook management.
-- **Ollama** (optional) — For LLM-enhanced documentation. Any OpenAI-compatible provider works as an alternative.
+| Requirement | Version | Notes |
+|---|---|---|
+| **Node.js** | `>=20.0.0` | Required for native fetch and modern ESM support |
+| **Git** | Any modern version | Required for drift detection and history analysis |
+| **Ollama** | Optional | For local LLM-enhanced documentation; any OpenAI-compatible provider is also supported |
 
 ---
 
@@ -72,7 +59,7 @@ npm install -g @dinyangetoh/codeplug-cli
 ### Local Development
 
 ```bash
-git clone <repo-url>
+git clone <repository-url>
 cd codeplug
 npm install
 npm run build
@@ -84,24 +71,15 @@ node dist/cli/index.js --help
 ## Quick Start
 
 ```bash
-# Install globally
-npm install -g @dinyangetoh/codeplug-cli
-
-# Navigate to your project
+# Initialize and detect conventions in your project
 cd your-project
-
-# Interactive wizard — single entry point for new users
-codeplug start
-```
-
-Or run commands directly:
-
-```bash
-# Detect and confirm conventions
 codeplug convention init
 
-# Check compliance
+# Run a compliance audit
 codeplug convention audit
+
+# Launch the interactive wizard
+codeplug start
 ```
 
 ---
@@ -110,419 +88,162 @@ codeplug convention audit
 
 ### Interactive Wizard
 
-```bash
-codeplug start
-```
-
-Launches an interactive menu with four core areas:
-
-| Menu     | Options                                                                 |
-| -------- | ----------------------------------------------------------------------- |
-| Config   | View full config, Set provider/model/API key/tier, Back                  |
-| Convention | Initialize, Run audit, Check drift, Show score, Auto-fix, Back        |
-| Docs     | Generate docs, Check status, Update stale, Back                          |
-| Export   | Export all targets, Check freshness, Back                                |
-
-Use arrow keys to navigate and Enter to select. Each sub-menu has a Back option to return.
-
-### Convention Detection
-
-```bash
-# Detect and interactively confirm conventions
-codeplug convention init
+The `codeplug start` command provides a guided interface organized into four areas:
 
-# Re-run detection, overwrite existing conventions
-codeplug convention init --force
-```
+| Area | Description |
+|---|---|
+| **Config** | Manage LLM providers, API keys, and model tiers |
+| **Convention** | Initialize detection, run audits, and apply auto-fixes |
+| **Docs** | Generate and update stale documentation |
+| **Export** | Refresh AI agent rule files |
 
-### Compliance Audit
+### Common Commands
 
 ```bash
-# Full compliance report
-codeplug convention audit
-
-# Audit only changes from the last 7 days
+# Audit changes from the last 7 days
 codeplug convention audit --since 7d
 
-# CI mode -- exits non-zero if score drops below threshold
+# CI mode — exits non-zero if score is below threshold
 codeplug convention audit --ci
-```
-
-### Drift Detection
-
-```bash
-# Check recent commits for convention drift
-codeplug convention drift
-```
-
-### Compliance Score
-
-```bash
-# Show current score
-codeplug convention score
-
-# Show score history and trend chart
-codeplug convention score --trend
-```
-
-### Auto-Fix
 
-```bash
-# Apply all safe auto-fixes
-codeplug convention fix --auto
-
-# Fix a specific finding by ID
-codeplug convention fix --id naming-pascal-components
-```
-
-### Documentation Generation
-
-```bash
-# Generate all 5 documents
-codeplug docs generate
-
-# Generate a specific document
-codeplug docs generate --doc ARCHITECTURE
-
-# Tune for audience and style
+# Generate docs for a junior audience in concise style
 codeplug docs generate --audience junior --style concise
 
-# Check which docs are stale
-codeplug docs status
-
-# Regenerate only stale sections
-codeplug docs update
-```
-
-### Export for AI Agents
-
-```bash
-# Export for a specific target
-codeplug export --target claude
+# Export rules for Cursor
 codeplug export --target cursor
-codeplug export --target copilot
 
-# Export all targets at once
+# Export all AI agent context files
 codeplug export --all
-
-# Check if exports are up to date
-codeplug export --check
-```
-
-### Configuration
-
-```bash
-# View all settings
-codeplug config list
-
-# Get a specific value
-codeplug config get llm.provider
-
-# Set values
-codeplug config set llm.provider openai
-codeplug config set llm.model gpt-4o
-codeplug config set llm.apiKey sk-...
 ```
 
-### Planned / Partial Features
-
-- **`convention show <commit>`**: Listed in help; returns "Not yet implemented. Coming in Phase 2."
-- **Pre-commit hook**: PreCommitHook class exists; `codeplug hook install/uninstall` commands are not yet exposed (programmatic API; coming soon).
-- **Export `--target ci`**: Produces SARIF 2.1.0 at `.codeplug/ci-report.json` for CI integration.
-
 ---
 
 ## Configuration
 
-CodePlug stores project-level configuration in `.codeplug/config.json`. The `config` command manages this file.
-
-### LLM Provider
+CodePlug stores project-level settings in `.codeplug/config.json`.
 
-The default provider is Ollama (local). Setting a provider auto-fills its base URL and default model:
+### LLM Providers
 
-```bash
-codeplug config set llm.provider ollama    # local, no API key needed
-codeplug config set llm.provider openai    # sets baseUrl + model automatically
-codeplug config set llm.provider anthropic
-```
+Convention detection runs entirely on-device. Documentation prose generation can optionally be enhanced via a local or cloud LLM provider:
 
-You can also set individual fields for custom endpoints:
+- **Local:** Ollama (default)
+- **Cloud:** OpenAI, Anthropic, Gemini, OpenRouter, Groq, DeepSeek, Grok
 
 ```bash
-codeplug config set llm.baseUrl https://my-proxy.example.com/v1
-codeplug config set llm.model my-custom-model
-codeplug config set llm.apiKey my-key
+codeplug config set llm.provider openai
+codeplug config set llm.apiKey sk-...
 ```
 
-### Model Tier
-
-```bash
-# Full-size models (default) -- best quality, ~1.1GB disk, 8GB+ RAM recommended
-codeplug config set models.tier default
+### Model Tiers
 
-# Lightweight models -- reduced quality, ~420MB disk, 4GB RAM minimum
-codeplug config set models.tier lite
-```
+| Tier | RAM | Disk | Use Case |
+|---|---|---|---|
+| **Default** | 8 GB+ | ~1.2 GB | Production quality, CI pipelines |
+| **Lite** | 4 GB+ | ~450 MB | Constrained local hardware |
 
-Switching to `lite` prints a warning about potential quality degradation.
-
-### Configurable Sections
-
-CodePlug supports optional sections in `.codeplug/config.json`. Each section merges with built-in defaults (shallow merge). Omit a section to keep defaults.
-
-```mermaid
-flowchart TB
-  subgraph sources [Config Sources]
-    Defaults[DEFAULT_CONFIG]
-    User[config.json]
-  end
-  Defaults --> Merge[ConfigManager.load]
-  User --> Merge
-  Merge --> Config[CodePlugConfig]
-  Config --> Structure[structure]
-  Config --> Analysis[analysis]
-  Config --> Scoring[scoring]
-  Config --> Convention[convention]
-  Config --> Drift[drift]
-  Config --> Docs[docs]
-  Config --> Naming[naming]
+```bash
+codeplug config set model.tier lite
 ```
 
-| Section | Purpose |
-|---------|---------|
-| `structure` | Architecture patterns (feature-based, MVC, layered) and directory placement rules (e.g. *Helper in helpers/) |
-| `analysis` | Glob `include` and `ignore` for file discovery |
-| `scoring` | Severity weights, compliance threshold, trend window |
-| `convention` | Confidence threshold and dimension → severity map |
-| `drift` | Confidence threshold and naming pattern regexes |
-| `docs` | Tracked doc names, export targets, dev scripts |
-| `naming` | Stem stopwords for file-responsibility extraction |
-
 ### Custom Rules
 
-Add regex-based rules via `.codeplug/rules.json`. Schema: `id`, `pattern`, `scope` (filename | path | content), `message`, `severity` (optional).
+Define regex-based rules in `.codeplug/rules.json` to extend or override detected conventions:
 
 ```json
-[{ "id": "no-index-export", "pattern": "export \\* from", "scope": "content", "message": "Prefer named exports", "severity": "low" }]
+[{
+  "id": "no-index-export",
+  "pattern": "export \\* from",
+  "scope": "content",
+  "message": "Prefer named exports",
+  "severity": "low"
+}]
 ```
 
-### Data Files
-
-| File | Purpose |
-|------|---------|
-| `.codeplug/config.json` | Project config (LLM, models, analysis, etc.) |
-| `.codeplug/conventions.json` | Stored conventions from `convention init` |
-| `.codeplug/rules.json` | Custom regex rules for audit |
-| `.codeplug/scores.json` | Compliance score history (sql.js) |
-| `.codeplug/violations.json` | Recent violation records |
-
 ---
 
-## Supported LLM Providers
-
-All providers work through a single unified client via the OpenAI SDK.
-
-| Provider | Setup |
-|----------|-------|
-| Ollama | `codeplug config set llm.provider ollama` (default, no API key) |
-| OpenAI | `codeplug config set llm.provider openai` then set `llm.apiKey` |
-| Anthropic | `codeplug config set llm.provider anthropic` then set `llm.apiKey` |
-| Gemini | `codeplug config set llm.provider gemini` then set `llm.apiKey` |
-| OpenRouter | `codeplug config set llm.provider openrouter` then set `llm.apiKey` |
-| Groq | `codeplug config set llm.provider groq` then set `llm.apiKey` |
-| DeepSeek | `codeplug config set llm.provider deepseek` then set `llm.apiKey` |
-| Grok | `codeplug config set llm.provider grok` then set `llm.apiKey` |
-
----
-
-## Model Tiers
-
-| | Default | Lite |
-|---|---------|------|
-| Target machine | 8GB+ RAM | 4GB+ RAM |
-| Disk usage | ~1.2GB | ~450MB |
-| Classification | CodeBERT-base (125M params) | CodeBERTa-small (84M params) |
-| Summarization | BART-large-CNN (406M params) | DistilBART (230M params) |
-| NER | BERT-base-NER (110M params) | DistilBERT-NER (66M params) |
-| Zero-shot | DistilBERT-MNLI (68MB) | DistilBERT-MNLI (68MB) |
-| Sentence similarity | all-MiniLM-L6-v2 (23MB) | all-MiniLM-L6-v2 (23MB) |
-| When to use | Production quality, CI pipelines | Local development on constrained hardware |
-
-**Model usage (all 6 roles used):**
-
-| Role | Default | Lite | Used By |
-|------|---------|------|---------|
-| classifier | CodeBERT-base | CodeBERTa-small | ConventionMlResolver (convention init) |
-| zeroShot | DistilBERT-MNLI | same | SemanticCoherenceService (opt-in) |
-| sentenceSimilarity | all-MiniLM-L6-v2 | same | SemanticCoherenceService (fallback) |
-| summarizer | BART-large-CNN | DistilBART | DocGenerator (docs generate) |
-| extractor | DistilBERT-SQuAD | same | DocGenerator |
-| ner | BERT-base-NER | DistilBERT-NER | DocGenerator |
-
-Convention detection: AST visitors + CodeBERT (ConventionMlResolver) + zero-shot/sentenceSimilarity when semantic coherence enabled. Doc generation: summarizer, extractor, ner via PipelineOrchestrator (default); falls back to template-only on model load failure.
+## Project Structure & Architecture
 
-Models are downloaded on first use and cached in `~/.codeplug/models/`.
+### Folder Structure
 
-### Tradeoffs
-
-- **Default vs Lite**: Quality vs resource usage (8GB vs 4GB RAM; ~1.2GB vs ~450MB disk).
-- **Semantic coherence**: Enable for stricter "export fits context" checks; adds ~68MB model load and inference time per audit.
-- **LLM for docs**: Optional; template-only fallback when LLM unavailable.
-- **Performance targets**: CLI startup <1s; init ~500 files <15s; drift <3s; audit <30s; docs (all 5) <2min.
-
-### Hugging Face Transformers
-
-Convention detection, drift, and compliance use **on-device ML only** via `@huggingface/transformers`. No API keys or network calls for convention features.
-
-**Why Transformers / Local-First ML**
-
-```mermaid
-flowchart LR
-    subgraph design [Design Rationale]
-        A[Privacy: no data leaves machine]
-        B[Zero cost for convention features]
-        C[Python-free Node.js inference]
-        D[Deterministic logic first ML fallback]
-    end
-```
-
-- **Privacy**: Convention detection, drift, compliance run entirely on-device — no API keys, no network calls.
-- **Cost**: Zero runtime cost; models cached in `~/.codeplug/models/`.
-- **Portability**: `@huggingface/transformers` runs in Node.js — no Python, no separate ML server.
-- **Explainability**: Rule-based detection first; ML used for ambiguous cases (e.g., semantic coherence) to keep outputs explainable.
-
-**Feature → Model usage:**
-
-```mermaid
-flowchart TB
-    subgraph convention [Convention Features]
-        Init[convention init]
-        Audit[convention audit]
-    end
-    subgraph conventionML [Convention ML]
-        CodeBERT[classifier: CodeBERT]
-        ZeroShot[zeroShot: DistilBERT-MNLI]
-        SentSim[sentenceSimilarity: all-MiniLM]
-    end
-    subgraph docsML [Docs ML]
-        BART[summarizer]
-        Extractor[extractor]
-        NER[ner]
-    end
-    Init --> CodeBERT
-    Init --> ZeroShot
-    Init --> SentSim
-    Audit --> conventionML
-    DocsGenerate[docs generate] --> BART
-    DocsGenerate --> Extractor
-    DocsGenerate --> NER
-```
-
-**Pipelines by feature:**
-
-| Feature | Pipeline | Use |
-|---------|----------|-----|
-| Convention discovery | Feature extraction (CodeBERT embedding via ConventionMlResolver) | Pattern similarity during init |
-| Convention (opt-in) | Zero-shot, sentence similarity (all-MiniLM) | Semantic coherence: "export fits file context" |
-| Doc generation | Summarization (BART), Q&A (DistilBERT-SQuAD), NER (BERT-NER) | Living documentation; template fallback on load failure |
-
-**LLM scope:** The LLM is **optional** and used only for prose generation in docs. Convention detection, drift, and compliance do not use an LLM.
-
-**Cost:** Zero runtime cost for convention features; models are cached locally.
-
----
-
-## Project Structure
-
-```
-src/
+```text
+src/                          # 66 source files
 ├── cli/
-│   └── commands/           # Command handlers (convention, docs, export, config)
-├── config/                 # ConfigManager, Zod schemas, types, provider presets
+│   └── commands/             # Command handlers (convention, docs, export)
+├── config/                   # Zod schemas and provider presets
 ├── core/
-│   ├── analyzer/           # AST analysis: 6 visitors (init), 7 for audit (adds StructureVisitor), PatternAggregator
-│   ├── classifier/         # Drift classification + confidence gating
-│   ├── scorer/             # Compliance scoring, violation detection, auto-fix, trends
-│   ├── generator/          # Doc generation, ML pipelines, LLM client, staleness tracking
-│   ├── exporter/           # Export engine + 5 formatters (Claude, Cursor, Copilot, JSON, CI)
-│   └── git/                # Git integration + pre-commit hook management
-├── models/                 # ML model manager + tier-aware registry
-├── storage/                # ConventionStore, ScoreStore (sql.js), ViolationStore, CustomRuleStore
-├── templates/              # Export templates (Claude, Cursor, Copilot)
-└── tests/                  # Unit tests, integration tests, fixture repos
-```
-
-### Directory Details
-
-| Directory | Purpose |
-|-----------|---------|
-| `cli/commands/` | Command handlers for the CLI interface |
-| `config/` | Configuration management with Zod validation |
-| `core/analyzer/` | AST-based code analysis with pattern aggregation |
-| `core/classifier/` | Drift detection and severity classification |
-| `core/scorer/` | Compliance scoring engine with trend analysis |
-| `core/generator/` | Doc generation; PipelineOrchestrator (summarizer, extractor, ner) + LLM; template fallback on failure |
-| `core/exporter/` | Multi-format export for AI coding agents |
-| `core/git/` | Git integration, diff analysis, PreCommitHook (CLI not yet exposed) |
-| `models/` | ML model lifecycle management |
-| `storage/` | ConventionStore, ScoreStore (sql.js), ViolationStore, CustomRuleStore (rules.json) |
+│   ├── analyzer/             # AST analysis — 6–7 specialized visitors
+│   ├── classifier/           # Drift classification & confidence gating
+│   ├── scorer/               # Compliance engine & violation detection
+│   ├── generator/            # ML pipelines (BART, BERT) & LLM client
+│   ├── exporter/             # Formatters (Claude, Cursor, SARIF)
+│   └── git/                  # Diff analysis & hook management
+├── models/                   # Tier-aware ML model registry
+├── storage/                  # sql.js (scores) and JSON stores
+└── templates/                # Export templates for AI agents
+
+tests/                        # 18 test files
+├── unit/
+│   ├── analyzer/
+│   ├── config/
+│   ├── exporter/
+│   ├── generator/
+│   ├── models/
+│   └── scorer/
+└── fixtures/
+    └── sample-react-app/
+```
+
+### Technical Stack
+
+| Layer | Technology |
+|---|---|
+| **ML Inference** | `@huggingface/transformers` — Python-free, Node.js native |
+| **Summarization** | BART (documentation prose) |
+| **Embeddings** | BERT (pattern classification) |
+| **Database** | `sql.js` (compliance time-series) |
+| **Schema Validation** | Zod |
+| **Test Runner** | Vitest |
 
 ---
 
 ## Conventions
 
-CodePlug follows these conventions throughout the codebase:
+These are the conventions CodePlug enforces and itself follows internally.
 
-### Naming Conventions
+### Naming
 
-- **Utility files** — Use camelCase (e.g., `formatDate.ts`, `parseConfig.ts`)
-- **Class/service files** — Use PascalCase (e.g., `ConfigManager.ts`, `ConventionStore.ts`)
-- **React components** — Use PascalCase file names (e.g., `Button.tsx`, `UserProfile.tsx`)
-- **Hooks** — Use "use" prefix with camelCase (e.g., `useAuth.ts`, `useTheme.ts`)
+| Target | Convention | Example |
+|---|---|---|
+| Class / service files | `PascalCase` | `ConfigManager.ts` |
+| Utility files | `camelCase` | `formatDate.ts` |
+| Class names | `PascalCase` | `class ConventionScorer` |
+| Interface names | `PascalCase` | `interface RuleConfig` |
+| Type aliases | `PascalCase` | `type SeverityLevel` |
+| Factory functions | `camelCase` | `createAnalyzer()` |
 
-### Testing Conventions
+> **Note:** Kebab-case filenames are not used anywhere in this project.
 
-- **Separate tests/** directory — Integration and e2e tests live outside `src/`
-- **Test file naming** — Use `.test.ts` or `.spec.ts` suffix
-- **Co-located tests** — Use `__tests__/` directories for unit tests near source files
+### API & Async Patterns
 
-### Project Structure Conventions
+- All I/O operations use `async/await`; callbacks and raw Promise chains are avoided.
 
-- **Source root** — All source code resides in `src/`
-- **Entry points** — CLI entry at `src/cli/index.ts`
-- **Core modules** — Domain logic in `src/core/` subdirectories by responsibility
+### Testing
+
+- Integration tests live in the root `tests/` directory.
+- Unit tests are co-located in `__tests__/` subdirectories alongside source files.
+- Test files follow the `.test.{ext}` naming convention.
 
 ---
 
 ## Development
 
 ```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Type check without emitting
-npm run typecheck
-
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run with coverage
-npm run coverage
-
-# Lint
-npm run lint
-
-# Lint with auto-fix
-npm run lint:fix
-
-# Watch build during development
-npm run dev
+npm run build        # Compile TypeScript
+npm run dev          # Watch mode for active development
+npm run test         # Run the full Vitest suite
+npm run coverage     # Generate test coverage report
+npm run lint         # Check code style
+npm run typecheck    # Verify TypeScript types
 ```
 
 ---

package/dist/cli/commands/docs.d.ts

@@ -1,7 +1,5 @@
 import type { DocsGenerateOptions } from '../../config/types.js';
-export declare function handleDocsGenerate(options: DocsGenerateOptions & {
-    ml?: boolean;
-}): Promise<void>;
+export declare function handleDocsGenerate(options: DocsGenerateOptions): Promise<void>;
 export declare function handleDocsStatus(): Promise<void>;
 export declare function handleDocsUpdate(): Promise<void>;
 //# sourceMappingURL=docs.d.ts.map

package/dist/cli/commands/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG;IAAE,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBvG;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CA0BtD;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CActD"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBpF;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CA0BtD;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CActD"}