@documentation-robotics/cli 0.1.0 → 0.1.7

package/README.md

@@ -1,926 +1,699 @@
 # Documentation Robotics CLI
 
-TypeScript-based CLI for managing federated architecture data models across 12 interconnected layers.
-
-## Overview
-
-This is the Documentation Robotics CLI - a production-ready command-line tool for creating, managing, and exporting comprehensive architecture models that span business requirements through technical implementation.
-
-## Foundation
-
-- ✅ Project structure initialized
-- ✅ TypeScript configuration (strict mode)
-- ✅ Core domain models (Element, Layer, Model, Manifest)
-- ✅ Reference and Relationship registries for tracking dependencies
-- ✅ File I/O utilities with atomic writes
-- ✅ JSON schemas bundled (all 12 layers)
-- ✅ Comprehensive unit tests
-- ✅ Code formatted and configured for linting
-
-## Directory Structure
-
-```
-cli/
-├── src/
-│   ├── cli.ts                          # Entry point
-│   ├── core/                           # Domain models
-│   │   ├── element.ts                  # Individual architecture items
-│   │   ├── layer.ts                    # Layer containers
-│   │   ├── model.ts                    # Complete model orchestration
-│   │   ├── manifest.ts                 # Model metadata (JSON)
-│   │   ├── reference-registry.ts       # Cross-layer reference tracking
-│   │   └── relationship-registry.ts    # Intra-layer relationship management
-│   ├── types/
-│   │   └── index.ts                    # TypeScript type definitions
-│   ├── utils/
-│   │   └── file-io.ts                  # File operations (atomic writes)
-│   └── schemas/
-│       └── bundled/                    # All JSON schemas from spec/
-│           ├── 01-motivation-layer.schema.json
-│           ├── 02-business-layer.schema.json
-│           ├── ... (all 12 layer schemas)
-│           ├── relationship-catalog.json
-│           ├── link-registry.json
-│           └── common/
-│               ├── relationships.schema.json
-│               ├── predicates.schema.json
-│               └── ...
-├── tests/
-│   └── unit/
-│       ├── core/
-│       │   ├── element.test.ts
-│       │   ├── layer.test.ts
-│       │   ├── manifest.test.ts
-│       │   ├── model.test.ts
-│       │   ├── reference-registry.test.ts
-│       │   ├── relationship-registry.test.ts
-│       │   └── element.integration.test.js
-│       └── utils/
-│           └── file-io.test.ts
-├── dist/                               # Compiled JavaScript
-├── package.json
-├── tsconfig.json
-├── biome.json
-└── README.md
-```
-
-## Installation & Setup
-
-### Prerequisites
-
-- **Node.js 18+** (npm included)
-- **Bun 1.3+** (optional, recommended for best performance)
-- A Documentation Robotics model directory (`.dr/`)
-
-### Quick Start
+A command-line tool for managing comprehensive architecture models that span from business requirements through technical implementation.
 
-```bash
-# Install the CLI globally
-npm install -g @documentation-robotics/cli
+[![npm version](https://img.shields.io/npm/v/@documentation-robotics/cli.svg)](https://www.npmjs.com/package/@documentation-robotics/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-# Or install locally in your project
-npm install @documentation-robotics/cli
-
-# Run CLI
-dr --version
-dr --help
-```
+## What is Documentation Robotics?
 
-### Development Setup
+Documentation Robotics helps you build and maintain a **federated architecture model** across 12 interconnected layers:
 
-For contributing to the CLI:
+1. **Motivation** - Goals, requirements, stakeholders
+2. **Business** - Business processes and services
+3. **Security** - Authentication, authorization, threats
+4. **Application** - Application services and components
+5. **Technology** - Infrastructure and platforms
+6. **API** - REST APIs and operations
+7. **Data Model** - Entities and relationships
+8. **Data Store** - Database schemas
+9. **UX** - User interface components
+10. **Navigation** - Application routing
+11. **APM** - Observability and monitoring
+12. **Testing** - Test strategies and cases
 
-```bash
-# Clone the repository
-git clone https://github.com/tinkermonkey/documentation_robotics.git
-cd documentation_robotics/cli
+**Key Benefits:**
 
-# Install dependencies
-npm install
+- Trace dependencies from business goals to implementation
+- Export to industry standards (ArchiMate, OpenAPI, JSON Schema)
+- Visualize your architecture in an interactive web interface
+- Chat with AI (Claude Code or GitHub Copilot) about your architecture model
+- Validate model integrity automatically
 
-# Build TypeScript
-npm run build
+## Installation
 
-# Run tests with Bun (preferred)
-bun test
+### Global Installation (Recommended)
 
-# Or run tests with Node.js
-npm test
-
-# Format code
-npm run format
-
-# Run CLI locally during development
-node dist/cli.js --help
+```bash
+npm install -g @documentation-robotics/cli
 ```
 
-### Installation Methods
-
-#### Option 1: Global Installation (Recommended)
+### Local Installation (Project-Specific)
 
 ```bash
-# Using npm
-npm install -g @documentation-robotics/cli
+npm install @documentation-robotics/cli
+```
 
-# Using bun
-bun add -g @documentation-robotics/cli
+### Verify Installation
 
-# Verify installation
+```bash
 dr --version
+dr --help
 ```
 
-#### Option 2: Project-Local Installation
-
-```bash
-# Install as a dev dependency
-npm install --save-dev @documentation-robotics/cli
+### System Requirements
 
-# Or add to package.json and run npm install
-{
-  "devDependencies": {
-    "@documentation-robotics/cli": "^0.1.0"
-  }
-}
+| Feature       | Requirement                       | Notes                               |
+| ------------- | --------------------------------- | ----------------------------------- |
+| Basic CLI     | Node.js 18+                       | All commands work                   |
+| Visualization | Node.js 18+                       | Interactive web interface           |
+| Chat          | Claude Code CLI or GitHub Copilot | AI-powered architecture discussions |
 
-# Run via npx
-npx dr --help
-```
+## Quick Start
 
-#### Option 3: Build from Source
+### 1. Create Your First Model
 
 ```bash
-# Clone and build
-git clone https://github.com/tinkermonkey/documentation_robotics.git
-cd documentation_robotics/cli
-npm install
-npm run build
+# Initialize a new model
+dr init --name "My Architecture" --author "Your Name"
 
-# Install globally from built dist
-npm install -g .
+# Add some elements (format: dr add <layer> <type> <name>)
+dr add motivation goal customer-satisfaction \
+  --name "Ensure customer satisfaction"
 
-# Or run directly
-node dist/cli.js --help
+dr add business service order-management \
+  --name "Order Management Service"
+
+dr add api endpoint create-order \
+  --name "Create Order" \
+  --properties '{"method":"POST","path":"/api/orders"}'
 ```
 
-### Configuration
+### 2. View Your Model
 
-#### Claude Code CLI Setup (for Chat Features)
+```bash
+# Show model summary
+dr info
 
-Chat functionality requires **Claude Code CLI** to be installed and authenticated with your Anthropic account.
+# List elements in a layer
+dr list api
 
-**Install Claude Code:**
+# Search for elements
+dr search order
 
-1. Visit https://claude.ai/download
-2. Follow installation instructions for your platform
-3. Authenticate with your Anthropic account when prompted
+# Show element details
+dr show api-endpoint-create-order
+```
 
-Verify installation:
+### 3. Visualize Your Architecture
 
 ```bash
-# Check Claude Code CLI is available
-which claude
+# Launch interactive visualization
+dr visualize
 
-# Run without a model directory to test
-claude --version
+# Opens in your browser at http://localhost:8080
+# - Explore layers and relationships
+# - Search and filter elements
+# - Chat with Claude about your model
 ```
 
-#### Visualization Server
+### 4. Export Your Model
 
 ```bash
-# Run visualization server with custom port
-dr visualize --port 3000
+# Export to ArchiMate (enterprise architecture standard)
+dr export archimate --output model.xml
 
-# Run without auto-opening browser
-dr visualize --no-browser
+# Export API layer to OpenAPI spec
+dr export openapi --layers api --output api-spec.yaml
+
+# Export to Markdown documentation
+dr export markdown --output docs/architecture.md
 ```
 
-#### Telemetry & Observability (Optional)
+## Common Commands
 
-The CLI supports comprehensive OpenTelemetry instrumentation for tracing, logging, and observability during development and testing. Telemetry is completely optional and incurs **zero overhead in production builds** due to compile-time constant elimination.
+### Model Management
 
-##### Features
+```bash
+dr init                     # Initialize new model
+dr info                     # Show model information
+dr validate                 # Validate model integrity
+dr upgrade                  # Check for spec upgrades
+```
 
-- **Command Tracing**: All CLI commands create root spans with command name, arguments, and working directory
-- **Validator Instrumentation**: Schema, naming, reference, and semantic validation stages produce nested spans
-- **Console Logging**: Console output (`console.log`, `console.error`, etc.) is automatically captured and correlated with traces
-- **Test Instrumentation**: Tests can emit spans with test file names, test case names, pass/fail status, and error details
-- **Project Context**: All telemetry includes your project name from the manifest for easy filtering
-- **Circuit-Breaker Protection**: Graceful degradation if the telemetry collector is unavailable—no user-facing errors or blocking
-- **Compile-Time Configuration**: Telemetry code is completely eliminated from production builds via dead-code elimination
+### Working with Elements
 
-##### Setup
+```bash
+dr add <layer> <type> <id>       # Add element
+dr update <element-id>           # Update element
+dr delete <element-id>           # Delete element
+dr show <element-id>             # Show element details
+dr list <layer>                  # List layer elements
+dr search <query>                # Search elements
+```
 
-###### Prerequisites
+**Element ID Format**: `{layer}.{ElementType}.{kebab-case-name}`
 
-- Node.js 18+
-- An OpenTelemetry collector (optional, for viewing traces/logs)
+Examples:
 
-###### Start an OTEL Collector (Optional)
+- `motivation.goal.customer-satisfaction`
+- `business.service.order-management`
+- `api.endpoint.create-order`
+- `data-model.entity.user-profile`
 
-**Option 1: Use Your Own Collector**
+**Important**: In CLI commands, element types use **lowercase** (e.g., `goal`, `service`, `endpoint`), while element names use **kebab-case** (e.g., `customer-satisfaction`). In generated element IDs, the type segment matches the CLI format (e.g., `motivation.goal.customer-satisfaction`).
 
-The CLI works with any OTLP-compatible collector (Jaeger, Zipkin, Grafana Tempo, Honeycomb, etc.).
+See [Element Type Reference](../docs/ELEMENT_TYPE_REFERENCE.md) for comprehensive documentation of all element types by layer.
 
-**Option 2: Use the Example SigNoz Stack**
+### Source File Tracking
 
-An example SigNoz configuration is provided in `docs/otel_example/`:
+Link architecture elements to their implementation source code:
 
 ```bash
-# From the repository root
-./docs/otel_example/signoz-stack.sh start
+# Add element with source reference
+dr add api endpoint create-user \
+  --name "Create User Endpoint" \
+  --source-file "src/api/endpoints/users.ts" \
+  --source-symbol "createUser" \
+  --source-provenance "extracted"
 
-# Wait for services to initialize (~30 seconds)
-# Access SigNoz UI at http://localhost:3301
-# OTEL Collector is available at http://localhost:4318
-```
+# Update element to add source reference
+dr update api-endpoint-create-user \
+  --source-file "src/api/endpoints/users.ts" \
+  --source-symbol "createUser" \
+  --source-provenance "extracted" \
+  --source-repo-remote "https://github.com/example/repo.git" \
+  --source-repo-commit "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b"
 
-**⚠️ Note:** This is an example configuration only. See [`docs/otel_example/README.md`](../docs/otel_example/README.md) for details.
+# Show element with source reference details
+dr show api-endpoint-create-user
 
-###### Build and Run CLI with Telemetry
+# Search elements by source file
+dr search --source-file "src/api/endpoints/users.ts"
 
-```bash
-# Build CLI with telemetry enabled
-npm run build:debug
+# Clear source reference from element
+dr update api-endpoint-create-user --clear-source-reference
+```
 
-# Set telemetry endpoint (optional - defaults to localhost:4318)
-export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+**Source Reference Options:**
 
-# Run CLI commands - traces and logs will be sent to SigNoz
-node dist/cli.js validate
-node dist/cli.js list motivation
-node dist/cli.js add business service my-service --name "My Service"
+| Option                 | Required                        | Description                                                               | Example                               |
+| ---------------------- | ------------------------------- | ------------------------------------------------------------------------- | ------------------------------------- |
+| `--source-file`        | When using source options       | Path to source file (relative to repo root)                               | `src/api/routes.ts`                   |
+| `--source-symbol`      | Optional                        | Symbol name (function, class, variable)                                   | `createUser`                          |
+| `--source-provenance`  | When using source options       | How reference was created: `extracted`, `manual`, `inferred`, `generated` | `extracted`                           |
+| `--source-repo-remote` | Requires `--source-repo-commit` | Git remote URL                                                            | `https://github.com/example/repo.git` |
+| `--source-repo-commit` | Requires `--source-repo-remote` | Full 40-character commit SHA                                              | `a1b2c3d4...`                         |
 
-# View traces and logs in SigNoz UI
-# http://localhost:3301
-```
+**Examples:**
 
-###### Verify Tracing
+```bash
+# Source reference with minimal information
+dr add security policy auth-validate \
+  --name "Auth Validation" \
+  --source-file "src/security/auth.ts" \
+  --source-provenance "manual"
 
-In SigNoz UI (http://localhost:3301):
+# Source reference with symbol and repository context
+dr add data-model entity user-entity \
+  --name "User Entity" \
+  --source-file "src/models/user.ts" \
+  --source-symbol "User" \
+  --source-provenance "extracted" \
+  --source-repo-remote "https://github.com/myorg/myapp.git" \
+  --source-repo-commit "5a7b3c9d1e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b"
 
-1. **View Command Traces**:
-   - Navigate to "Traces" section
-   - Look for spans named `cli.execute`
-   - Expand to see nested validator spans (`validation.stage.schema`, `validation.stage.naming`, etc.)
-   - Each span shows command name, arguments, working directory, and project name
+# Search for all elements in a source file
+dr search --source-file "src/services/auth.ts"
 
-2. **View Correlated Logs**:
-   - Click on a command span to view details
-   - Switch to "Logs" tab to see console output captured during command execution
-   - Logs include severity level (INFO, WARN, ERROR) and trace context (traceId, spanId)
+# Search by file with additional filters
+dr search --source-file "src/api/endpoints.ts" --layer "06-api" --type "endpoint"
+```
 
-3. **Filter by Project**:
-   - Use the filter `dr.project.name = "YourProjectName"` to isolate telemetry for a specific project
-   - Useful when multiple projects share the same collector
+**Provenance Types:**
 
-###### Test Instrumentation
+- **`extracted`**: Automatically detected from source code via parsing/analysis tools
+- **`manual`**: Manually linked by a person reviewing source code
+- **`inferred`**: Determined through pattern matching and heuristics
+- **`generated`**: Created automatically from code generation or model transformation
 
-Tests can emit telemetry to verify logging behavior. Use the test instrumentation utilities:
+### Relationships & Dependencies
 
-```typescript
-import { describe, test, beforeAll, afterAll } from 'bun:test';
-import {
-  startTestFileSpan,
-  endTestFileSpan,
-  instrumentTest,
-} from '../../src/telemetry/test-instrumentation.js';
+```bash
+# Add relationships between elements
+dr relationship add motivation.goal.customer-satisfaction \
+                        business.service.customer-support \
+                        --predicate "supports"
 
-beforeAll(() => {
-  startTestFileSpan('tests/unit/my-feature.test.ts');
-});
+# List relationships for an element
+dr relationship list business.service.order-management
 
-afterAll(() => {
-  endTestFileSpan();
-});
+# Trace dependencies (see which elements depend on this one)
+dr trace api.endpoint.create-order
 
-describe('MyFeature', () => {
-  test(
-    'should validate input',
-    instrumentTest(
-      'should validate input',
-      async () => {
-        // Test logic here
-        expect(result).toBe(expected);
-      },
-      'MyFeature' // Suite name for organization
-    )
-  );
-});
+# Project dependencies to another layer
+dr project api.endpoint.create-order business
 ```
 
-Run tests with telemetry:
+### Visualization & Export
 
 ```bash
-npm run build:debug
-npm run test
-
-# View test spans in SigNoz UI with attributes:
-# - test.file: Path to test file
-# - test.name: Test case name
-# - test.suite: Describe block name
-# - test.status: 'pass', 'fail', or 'skip'
-# - test.error.message and test.error.stack (for failed tests)
+dr visualize                             # Interactive web UI
+dr export <format>                       # Export model
+  # Formats: archimate, openapi, jsonschema, plantuml, markdown, graphml
 ```
 
-###### Stop the Example Stack (if using)
+### AI-Powered Features
 
 ```bash
-./docs/otel_example/signoz-stack.sh stop
-
-# To remove all data and start fresh:
-./docs/otel_example/signoz-stack.sh clean
+dr chat                                  # Auto-detect or use saved preference
+dr chat claude-code                      # Use Claude Code, save as preference
+dr chat github-copilot                   # Use GitHub Copilot, save as preference
 ```
 
-##### Configuration
+**Note**: Chat requires either [Claude Code CLI](https://claude.ai/download) or [GitHub Copilot CLI](https://github.com/github/gh-copilot) to be installed and authenticated. The CLI will auto-detect available clients and prompt you to choose if both are installed. You can also explicitly specify which client to use.
 
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | OTLP collector endpoint (applies to both traces and logs) |
-| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Derived from OTLP_ENDPOINT | Override for logs endpoint specifically |
-| `DR_TELEMETRY` | Determined by build | Build-time flag (set via `npm run build:debug`) |
+## Configuration
 
-##### Architecture
+### Model Structure
 
-The telemetry system consists of:
+Model data and changesets are stored in the `documentation-robotics/` directory:
 
-1. **Resilient OTLP Exporter** - Exports traces with circuit-breaker pattern (30s backoff on failure)
-2. **Resilient Log Exporter** - Exports logs with same circuit-breaker protection
-3. **Console Interceptor** - Captures console output without modifying application code
-4. **Test Instrumentation** - Provides utilities for creating test spans with standard attributes
-5. **Resource Attributes** - Every trace and log includes:
-   - `service.name`: `dr-cli`
-   - `service.version`: CLI version from package.json
-   - `dr.project.name`: Project name from manifest (if available, else `unknown`)
+```
+your-project/
+├── documentation-robotics/
+│   ├── model/
+│   │   ├── manifest.yaml                    # Model metadata
+│   │   ├── 01_motivation/
+│   │   │   ├── goals.yaml
+│   │   │   └── ...
+│   │   ├── 02_business/
+│   │   │   ├── services.yaml
+│   │   │   └── ...
+│   │   └── ...
+│   └── changesets/
+│       ├── feature-x/
+│       │   ├── metadata.yaml   # Changeset metadata
+│       │   └── changes.yaml    # Staged changes
+│       └── ...
+```
 
-##### Troubleshooting
+**Legacy models**: Old projects using `.dr/` directory will auto-migrate changesets to `documentation-robotics/changesets/` on first use.
 
-###### Traces not appearing in SigNoz
+### Specification Reference
 
-1. **Verify SigNoz is running:**
-   ```bash
-   curl http://localhost:13133  # OTEL Collector health check
-   curl http://localhost:3301   # SigNoz UI
-   ```
+When you run `dr init`, the CLI installs a complete copy of the Documentation Robotics specification to `.dr/spec/`:
 
-2. **Check telemetry build:**
-   ```bash
-   # Verify build was done with DR_TELEMETRY=true
-   npm run build:debug
-   ```
+```
+your-project/
+├── .dr/
+│   ├── spec/
+│   │   ├── layers/              # 12 layer definitions
+│   │   └── schemas/
+│   │       ├── base/            # 8 base schemas
+│   │       ├── nodes/           # 354 node type schemas
+│   │       └── relationships/   # 252 relationship schemas
+│   ├── manifest.json            # Spec version info
+│   └── README.md
+```
 
-3. **Verify endpoint connectivity:**
-   ```bash
-   node dist/cli.js validate
-   # If SigNoz is unavailable, circuit-breaker activates silently after 500ms timeout
-   ```
+**What this enables:**
 
-4. **Check resource attributes:**
-   - In SigNoz, search for traces with filter `service.name = "dr-cli"`
-   - Verify `dr.project.name` appears in span attributes
+- `dr schema layers` - List all architecture layers
+- `dr schema types <layer>` - Show valid element types for a layer
+- `dr schema node <spec_node_id>` - View detailed node type schema
+- `dr schema relationship <type>` - Show valid relationships for a type
+- `dr conformance` - Validate model against layer specifications
 
-###### "Circuit-breaker activated" messages
+**Important:**
 
-These are internal debug messages and do not affect CLI execution. They appear when:
-- The OTLP collector is unreachable
-- Export timeout (500ms) is exceeded
+- The `.dr/` directory is ephemeral and should be git-ignored
+- It will be recreated automatically by the CLI when needed
+- Run `dr upgrade` to update the spec reference after CLI updates
 
-The CLI continues normally—no errors are shown to users.
+### AI Chat Setup (for Chat Features)
 
-##### Production Deployment
+The chat functionality supports two AI CLI tools. You need at least one installed:
 
-- **Development builds** (`npm run build:debug`): Includes full telemetry code (~50KB overhead)
-- **Production builds** (`npm run build`): Zero telemetry overhead via dead-code elimination
-- Telemetry code is completely removed from production bundles at compile time
+#### Option 1: Claude Code CLI
 
-##### Notes
+1. Visit https://claude.ai/download
+2. Follow installation instructions for your platform
+3. Authenticate with your Anthropic account
+4. Verify: `claude --version`
 
-- Telemetry is **entirely optional** and disabled in production builds
-- The CLI gracefully handles missing SigNoz (no blocking, no user-visible errors)
-- Traces and logs are sent asynchronously without blocking CLI commands
-- Default OTLP collection endpoint: `http://localhost:4318` (standard OpenTelemetry receiver)
-- Supported log severity levels: DEBUG, INFO, WARN, ERROR
-- Automatic trace-log correlation via traceId and spanId
+#### Option 2: GitHub Copilot CLI
 
-### System Requirements
+1. Install GitHub CLI: https://cli.github.com/
+2. Install Copilot extension: `gh extension install github/gh-copilot`
+3. Authenticate: `gh auth login`
+4. Verify: `gh copilot --version`
 
-| Feature       | Requirement       | Notes                              |
-| ------------- | ----------------- | ---------------------------------- |
-| Basic CLI     | Node.js 18+       | All commands work                  |
-| Visualization | Node.js 18+       | WebSocket support required         |
-| Chat          | Claude Code CLI   | OAuth authentication via Claude Code |
-| Telemetry     | Docker Compose    | Optional, for local SigNoz/OTLP tracing |
-| Performance   | Bun 1.3+          | Optional but recommended           |
+**Client Selection**:
 
-### Troubleshooting
+- **Auto-detection**: The first time you use `dr chat`, if both clients are available, you'll be prompted to choose one.
+- **Explicit selection**: You can specify a client directly (e.g., `dr chat github-copilot` or `dr chat claude-code`).
+- **Preference storage**: Your client choice is saved in the model manifest for future sessions. You can change it anytime by explicitly specifying a different client.
 
-#### Command Not Found
+### Visualization Server
 
 ```bash
-# If "dr" is not found after global installation
-npm install -g @documentation-robotics/cli
-
-# Check npm global location
-npm config get prefix
-
-# Add to PATH if needed (macOS/Linux)
-export PATH="$(npm config get prefix)/bin:$PATH"
+# Launch with default embedded viewer
+dr visualize
 
-# Add to PATH permanently (.bashrc or .zshrc)
-echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
-source ~/.bashrc
-```
+# Custom port
+dr visualize --port 3000
 
-#### Module Not Found Errors
+# Don't auto-open browser
+dr visualize --no-browser
 
-```bash
-# Clear and reinstall
-rm -rf node_modules package-lock.json
-npm install
+# Load custom viewer build (useful for development or custom distributions)
+dr visualize --viewer-path ./dist/embedded/dr-viewer-bundle
 
-# Rebuild
-npm run build
+# Combined example: custom viewer on custom port without browser
+dr visualize --viewer-path ./my-viewer --port 3000 --no-browser
 ```
 
-#### Test Failures
+**Custom Viewer Path**:
 
-```bash
-# Check that all dependencies are installed
-npm list
+The `--viewer-path` option allows you to serve a custom web UI instead of the default embedded viewer:
 
-# Reinstall with clean cache
-npm cache clean --force
-npm install
+- Point to a directory containing `index.html` and supporting files (CSS, JS, assets)
+- Useful for developing custom viewers or using bundled distributions
+- The server will serve static files from the specified path with proper MIME types
+- Path traversal protection is enforced for security
+
+**Example custom viewer structure**:
 
-# Run tests with verbose output
-DEBUG=* npm test
+```
+my-viewer/
+├── index.html          # Entry point
+├── assets/
+│   ├── style.css      # Stylesheets
+│   ├── script.js      # JavaScript
+│   └── logo.png       # Images
+└── ...                 # Other static files
 ```
 
-## Command Reference
+## Generating Layer Reports
 
-All commands include detailed help. View help for any command:
+To generate comprehensive markdown reports for all 12 architecture layers:
 
 ```bash
-dr --help                              # Show all commands
-dr <command> --help                    # Show command-specific help
-dr element add --help                  # Show element add help
-```
-
-### Quick Command Summary
-
-| Category          | Command               | Purpose                                              |
-| ----------------- | --------------------- | ---------------------------------------------------- |
-| **Model**         | `init`                | Initialize a new architecture model                  |
-|                   | `info`                | Show model information and statistics                |
-|                   | `validate`            | Validate the complete model                          |
-| **Elements**      | `add`                 | Add an element to a layer                            |
-|                   | `update`              | Update an element                                    |
-|                   | `delete`              | Delete an element                                    |
-|                   | `show`                | Display element details                              |
-|                   | `list`                | List elements in a layer                             |
-|                   | `search`              | Search for elements by name/ID                       |
-| **Relationships** | `relationship add`    | Add intra-layer relationship                         |
-|                   | `relationship delete` | Delete a relationship                                |
-|                   | `relationship list`   | List relationships for an element                    |
-| **Dependencies**  | `trace`               | Trace element dependencies                           |
-|                   | `project`             | Project dependencies to a target layer               |
-| **Export**        | `export`              | Export to various formats (ArchiMate, OpenAPI, etc.) |
-| **Visualization** | `visualize`           | Launch interactive visualization server              |
-| **AI**            | `chat`                | Interactive Claude AI chat about model               |
-| **Advanced**      | `migrate`             | Migrate model to new spec version                    |
-|                   | `upgrade`             | Check for version upgrades                           |
-|                   | `conformance`         | Check spec conformance                               |
-|                   | `changeset`           | Manage model change tracking                         |
-
-### Common Workflows
-
-#### Create a New Model
+npm run generate:layer-reports
+```
 
-```bash
-# Initialize model
-dr init --name "My Architecture" --author "Team A"
+This command:
 
-# Add some elements
-dr add motivation goal customer-satisfaction --name "Ensure customer satisfaction"
-dr add business service-category order-mgmt --name "Order Management"
-dr add api endpoint create-order --properties '{"method":"POST","path":"/orders"}'
+- Loads 354 node schemas, 252 relationship schemas, 12 layer definitions, and 47 predicates
+- Computes per-layer statistics and relationship classifications
+- Generates 12 markdown reports in `spec/browser/` with Mermaid diagrams
+- Generates `spec/browser/README.md` with overview and dependency matrix
 
-# View the model
-dr info
-dr list api
-```
+**Output Location**: `spec/browser/{NN}-{layer-name}-layer-report.md`
 
-#### Search and Update Elements
+**When to Regenerate**:
 
-```bash
-# Search for elements
-dr search customer
+- After modifying layer definitions in `spec/layers/*.layer.json`
+- After adding/modifying node schemas in `spec/schemas/nodes/`
+- After adding/modifying relationship schemas in `spec/schemas/relationships/`
+- Before creating a new spec version release
 
-# Show details
-dr show api-endpoint-create-order
+**Git Integration**: The generated reports in `spec/browser/` are committed to git for easy browsing on GitHub. Regenerate them before spec releases to keep documentation in sync with specification changes.
 
-# Update an element
-dr update api-endpoint-create-order --name "Create Order API (v2)"
+## Example Workflows
 
-# Delete an element
-dr delete api-endpoint-old-endpoint --force
-```
-
-#### Analyze Dependencies
+### Analyzing Dependencies
 
 ```bash
-# Trace dependencies for an element
+# Find all dependencies for an API endpoint
 dr trace api-endpoint-create-order
 
-# Show dependencies in a specific direction
+# Show only dependencies from higher layers
 dr trace api-endpoint-create-order --direction up
 
-# Show element metrics
+# Show dependency metrics
 dr trace api-endpoint-create-order --metrics
 
-# Project to another layer
+# Project dependencies to business layer
 dr project api-endpoint-create-order business
 ```
 
-#### Manage Relationships
+### Managing Relationships
 
 ```bash
-# Add a relationship
-dr relationship add business-process-1 business-process-2 --predicate depends-on
-
-# List relationships
-dr relationship list business-process-1
+# Add a relationship between business processes
+dr relationship add business-process-order business-process-payment \
+  --predicate triggers
 
-# Show only outgoing relationships
-dr relationship list business-process-1 --direction outgoing
+# List all relationships for an element
+dr relationship list business-process-order
 
 # Delete a relationship
-dr relationship delete business-process-1 business-process-2 --force
+dr relationship delete business-process-order business-process-payment
 ```
 
-#### Export and Visualize
+### Staging Workflow
+
+The staging feature allows you to safely prepare and review changes before committing them to the base model:
 
 ```bash
-# Export to multiple formats
-dr export archimate --output model.xml
-dr export openapi --layers api --output api-spec.yaml
-dr export markdown --output docs/architecture.md
+# Create a changeset for your changes
+dr changeset create user-mgmt-v2 \
+  --name "User Management v2" \
+  --description "Redesign user management system"
 
-# Launch visualization server
-dr visualize
-dr visualize --port 3000 --no-browser
-```
+# Activate the changeset to track changes
+dr changeset activate user-mgmt-v2
 
-#### Chat
+# Now make your changes - they will be tracked automatically
+dr add api endpoint create-user \
+  --properties '{"method":"POST","path":"/users"}'
 
-Interactive conversation with Claude about your architecture model.
+dr add data-model entity user \
+  --name "User Entity"
 
-**Requirements**: Claude Code CLI must be installed and authenticated. The chat functionality uses your Claude Code OAuth token, not an API key.
+# Preview how staged changes will merge with the base model
+dr changeset preview
 
-**Install Claude Code**:
-1. Visit https://claude.ai/download
-2. Follow installation instructions for your platform
-3. Authenticate with your Anthropic account
+# View changeset details
+dr changeset show
 
-**CLI Usage**:
+# Commit when satisfied (checks for drift and validates changes)
+dr changeset commit
 
-```bash
-dr chat
+# Or discard if you change your mind
+dr changeset discard
 ```
 
-The chat command:
-- Launches an interactive conversation loop
-- Uses Claude Code CLI with restricted tools (Bash, Read)
-- Provides context about your model (manifest, layer statistics)
-- Streams responses in real-time
-- Exit with "exit", "quit", or "q"
+**Key Features:**
 
-**Example**:
+- **Activate for tracking**: Activate a changeset to automatically track all changes
+- **Virtual preview**: See merged view before committing
+- **Drift detection**: Alerts if base model changed since changeset creation
+- **Export/Import**: Share changesets across team or save for backup
 
-```bash
-$ dr chat
-┌  Documentation Robotics Chat
-└  Powered by Claude Code - Ask about your architecture model
-
-You: What are the dependencies for the create-order endpoint?
-Claude: Let me check the model for you...
-[Using tool: Bash]
-[Tool result: Found dependencies...]
-
-You: Show me the critical path in the business layer
-Claude: I'll analyze the business layer relationships...
-
-You: exit
-└  Goodbye!
-```
-
-**WebSocket Chat** (via `dr visualize`):
-
-The visualization server provides WebSocket-based chat using JSON-RPC 2.0:
-
-**Request** (send message):
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "chat.send",
-  "params": {
-    "message": "What layers are in this model?"
-  },
-  "id": 1
-}
-```
-
-**Notifications** (streaming response):
-
-Text content chunk:
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "chat.response.chunk",
-  "params": {
-    "conversation_id": "conv-1-12345",
-    "content": "This model has 12 layers...",
-    "is_final": false,
-    "timestamp": "2025-01-02T12:00:00.000Z"
-  }
-}
-```
-
-Tool invocation notification:
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "chat.tool.invoke",
-  "params": {
-    "conversation_id": "conv-1-12345",
-    "tool_name": "Bash",
-    "tool_input": { "command": "dr list api" },
-    "timestamp": "2025-01-02T12:00:00.000Z"
-  }
-}
-```
-
-Tool result notification:
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "chat.tool.result",
-  "params": {
-    "conversation_id": "conv-1-12345",
-    "result": "output from tool execution",
-    "timestamp": "2025-01-02T12:00:00.000Z"
-  }
-}
-```
-
-**Completion response**:
-```json
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "conversation_id": "conv-1-12345",
-    "status": "complete",
-    "exit_code": 0,
-    "full_response": "Complete response text...",
-    "timestamp": "2025-01-02T12:00:00.000Z"
-  },
-  "id": 1
-}
-```
-
-**Error response**:
-```json
-{
-  "jsonrpc": "2.0",
-  "error": {
-    "code": -32001,
-    "message": "Claude Code CLI not available"
-  },
-  "id": 1
-}
-```
-
-**Error Codes**:
-- `-32001`: Claude Code CLI not available (install Claude Code)
-- `-32002`: Invalid parameters
-- `-32603`: Internal error (process failure, timeout)
-
-#### Manage Changesets
+**Changeset Status:**
+
+- `staged`: Changes are prepared but not applied (default)
+- `committed`: Changes have been applied to base model
+- `discarded`: Changes were abandoned
+
+For comprehensive guide, see [STAGING_GUIDE.md](../../docs/STAGING_GUIDE.md).
+
+### Tracking Changes
+
+> ⚠️ **IMPORTANT**: Changesets must be **ACTIVATED** to track changes.
+>
+> After creating a changeset:
+>
+> 1. `dr changeset create "my-changes"`
+> 2. `dr changeset activate "my-changes"` ← **DON'T FORGET THIS**
+> 3. Make your changes (add/update/delete)
 
 ```bash
 # Create a changeset
-dr changeset create "v1.1 migration" --description "Migrate to new API structure"
+dr changeset create "v2.0 API migration" \
+  --description "Update to new API structure"
+
+# Activate the changeset to track changes
+dr changeset activate "v2.0 API migration"
+
+# Now make your changes - they will be tracked
+dr update api-endpoint-users --name "Users API v2"
+dr add api endpoint users-list
 
 # List changesets
 dr changeset list
 
+# Review changes
+dr changeset show "v2.0 API migration"
+
 # Apply a changeset
-dr changeset apply "v1.1 migration"
+dr changeset apply "v2.0 API migration"
 
-# Revert a changeset
-dr changeset revert "v1.1 migration"
+# Revert if needed
+dr changeset revert "v2.0 API migration"
+
+# Deactivate when done
+dr changeset deactivate
 ```
 
-## Core Classes
+## Getting Help
+
+### Command-Line Help
 
-### Element
+Every command includes detailed help:
 
-Individual architecture items in the model. Supports:
+```bash
+dr --help                    # Show all commands
+dr <command> --help          # Command-specific help
+dr add --help                # Show element add help
+dr relationship --help       # Relationship commands
+```
 
-- Properties with type-safe getters/setters
-- Array properties with add/get operations
-- References to other elements (cross-layer)
-- Relationships with other elements (intra-layer)
+### Documentation
 
-```typescript
-const element = new Element({
-  id: "motivation-goal-test",
-  type: "Goal",
-  name: "Test Goal",
-  description: "A test goal",
-  properties: { priority: "high" },
-});
+- 📚 [Full Specification](https://github.com/tinkermonkey/documentation_robotics/tree/main/spec) - The 12-layer model in detail
+- 🛠️ [Contributing Guide](./CONTRIBUTING.md) - For developers working on the CLI
+- 📦 [npm Package](https://www.npmjs.com/package/@documentation-robotics/cli)
 
-element.setProperty("owner", "team-a");
-element.addToArrayProperty("tags", "important");
-```
+### Community
 
-### Layer
+- 🐛 [Report Issues](https://github.com/tinkermonkey/documentation_robotics/issues)
+- 💬 [Discussions](https://github.com/tinkermonkey/documentation_robotics/discussions)
+- 🌟 [GitHub Repository](https://github.com/tinkermonkey/documentation_robotics)
 
-Container for elements within a single layer. Supports:
+## Utilities
 
-- Add/get/delete/list operations
-- Dirty tracking (unsaved changes)
-- JSON serialization/deserialization
+### Export Python Annotations
 
-```typescript
-const layer = new Layer("motivation");
-layer.addElement(element);
+For migrating Python CLI annotation metadata, a utility script is available:
 
-if (layer.isDirty()) {
-  await model.saveLayer("motivation");
-  layer.markClean();
-}
+```bash
+bun run src/utils/export-python-annotations.ts
 ```
 
-### Manifest
+This utility exports Python CLI annotations to a processable format, used during migrations between CLI versions.
 
-Model metadata (JSON-based). Supports:
+## Relationship Audit
 
-- Automatic timestamp management
-- JSON serialization/deserialization
-- Version tracking
+The relationship audit system provides comprehensive analysis of intra-layer relationships:
 
-```typescript
-const manifest = new Manifest({
-  name: "Test Model",
-  version: "1.0.0",
-  description: "A test model",
-  specVersion: "0.6.0",
-});
+- **Coverage Analysis**: Measures isolation, density, and predicate utilization
+- **Duplicate Detection**: Identifies semantic overlaps using predicate semantics
+- **Gap Analysis**: Detects missing relationships based on layer standards
+- **Balance Assessment**: Evaluates relationship density against node type targets
+- **AI Assistance**: Optional Claude Code CLI integration for recommendations
 
-const json = JSON.stringify(manifest.toJSON());
-const deserialized = Manifest.fromJSON(json);
-```
+See CLAUDE.md for detailed usage instructions.
 
-### Model
+## Validation
 
-Central orchestrator for the complete architecture model. Supports:
+### Local Validation
 
-- Lazy layer loading
-- Manifest management
-- Atomic persistence to `.dr/` directory structure
+Since pre-commit hooks for validation were removed in favor of CI-based validation, developers who want local feedback before committing can use the following commands to validate their changes:
 
-```typescript
-// Initialize a new model
-const model = await Model.init(".", {
-  name: "My Model",
-  version: "1.0.0",
-});
+#### Validate Model Conformance
 
-// Load an existing model
-const loaded = await Model.load(".");
+Validate your architecture model against the layer specifications:
 
-// Save changes
-await model.saveManifest();
-await model.saveDirtyLayers();
-```
+```bash
+# Validate entire model
+dr conformance
 
-### ReferenceRegistry
+# Validate specific layers
+dr conformance --layers motivation,business,api
 
-Tracks cross-layer references between architecture elements. Provides:
+# Check model statistics and summary
+dr info
+```
 
-- Add/query references by source, target, or type
-- Reference validation and integrity checking
-- Impact analysis (find all references to/from an element)
-- Statistics on reference usage
+#### Validate Specifications (During Development)
 
-```typescript
-const refRegistry = new ReferenceRegistry();
+If you're developing locally and modifying the specification files:
 
-refRegistry.addReference({
-  source: "01-motivation-goal-create-customer",
-  target: "02-business-process-create-order",
-  type: "realizes",
-});
+```bash
+# Validate spec schemas are correct
+dr validate --schemas
 
-const refsFrom = refRegistry.getReferencesFrom("01-motivation-goal-create-customer");
-const refsTo = refRegistry.getReferencesTo("02-business-process-create-order");
+# List schema information for debugging
+dr schema layers           # List all layers
+dr schema types <layer>    # List valid types for a layer
+dr schema node <id>        # Show node schema details
 ```
 
-### RelationshipRegistry
+#### Schema Synchronization
 
-Manages intra-layer relationships and their semantic metadata. Provides:
+After modifying specification files in `spec/`, ensure the CLI has the latest schemas:
 
-- Register relationship types with predicates and metadata
-- Query relationships by source, layer, or predicate
-- Validate relationship predicates
-- Layer-specific relationship rules
-
-```typescript
-const relRegistry = new RelationshipRegistry();
-
-relRegistry.registerType({
-  id: "depends-on",
-  predicate: "depends-on",
-  category: "dependency",
-});
+```bash
+# Sync spec schemas to CLI bundled schemas
+npm run sync-schemas
 
-relRegistry.addRelationship({
-  source: "02-process-create-order",
-  target: "02-process-validate-order",
-  predicate: "depends-on",
-});
+# Build CLI with updated schemas
+npm run build
 ```
 
-## File I/O Utilities
+These commands provide immediate feedback during development, allowing you to catch validation errors locally before pushing to CI.
 
-Atomic file operations for safe persistence:
+## Troubleshooting
 
-```typescript
-import { ensureDir, writeFile, readFile, writeJSON, readJSON, atomicWrite } from "@/utils/file-io";
+### "dr: command not found"
 
-// Ensure directory exists
-await ensureDir(".dr/layers");
+```bash
+# Check if npm global bin is in PATH
+npm config get prefix
 
-// Atomic write (safe for crash recovery)
-await atomicWrite(".dr/manifest.json", content);
+# Add to PATH (macOS/Linux)
+export PATH="$(npm config get prefix)/bin:$PATH"
 
-// JSON operations
-await writeJSON(".dr/layers/motivation.json", data, true);
-const loaded = await readJSON(".dr/layers/motivation.json");
+# Make permanent (add to ~/.bashrc or ~/.zshrc)
+echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
 ```
 
-## Type Definitions
+### Module or Build Errors
 
-Core types defined in `src/types/index.ts`:
+```bash
+# Clear and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
 
-- `Element` - Architecture item representation
-- `LayerData` - Layer serialization format
-- `ManifestData` - Manifest metadata
-- `Reference` - Cross-layer references
-- `Relationship` - Intra-layer relationships
-- `ModelOptions` - Model configuration
+### Chat Not Working
 
-## Testing
+Ensure at least one AI CLI tool is installed and authenticated:
 
-Comprehensive test coverage for core classes:
+#### For Claude Code
 
 ```bash
-# Run Bun tests (requires Bun runtime)
-bun test
-
-# Run specific test file
-bun test tests/unit/core/element.test.ts
-
-# With coverage
-bun test --coverage
+# Check installation
+which claude
 
-# Node.js integration test
-node tests/unit/core/element.integration.test.js
+# Verify authentication
+claude --version
 ```
 
-## Bundled Schemas
+If not installed, visit https://claude.ai/download
 
-All JSON schemas from `spec/schemas/` are bundled:
+#### For GitHub Copilot
 
-- **Layer Schemas**: 01-motivation through 12-testing
-- **Catalogs**: relationship-catalog.json, link-registry.json
-- **Common Schemas**: predicates, relationships, source-references, layer-extensions
+```bash
+# Check installation
+gh copilot --version
 
-These schemas are loaded at build time and do not require filesystem access at runtime.
+# Or check for standalone copilot
+which copilot
 
-## Code Quality
+# Authenticate GitHub CLI
+gh auth login
+```
 
-- **TypeScript**: Strict mode with comprehensive type coverage
-- **Linting**: Biome configured for code quality checks
-- **Formatting**: Code formatted to project standards
+If not installed, see instructions above in the "AI Chat Setup" section.
 
-## Related Resources
+## What's Next?
 
-- Specification: `/workspace/spec/`
-- Design Discussion: [GitHub Discussion #68](https://github.com/tinkermonkey/documentation_robotics/discussions/68)
-- Migration Guide: [Migrating from Python CLI](../docs/migration-from-python-cli.md)
+- ⭐ **Star the project** on [GitHub](https://github.com/tinkermonkey/documentation_robotics)
+- 📖 **Read the spec** to understand the 12-layer model
+- 🎨 **Try visualization** with `dr visualize`
+- 🤖 **Chat with AI** about your architecture (Claude Code or GitHub Copilot)
+- 🚀 **Export to standards** (ArchiMate, OpenAPI)
 
 ## License
 
-MIT
+MIT © Documentation Robotics Contributors
+
+---
+
+**Made with ❤️ by the Documentation Robotics community**