monora-ai 2.0.0 → 2.1.3

package/README.md

@@ -1,40 +1,117 @@
-# Monora SDK for Node.js v1.9.3
+# Monora SDK for Node.js v2.1.3
 
 Lightweight governance and trace SDK for AI systems.
 
 ![Monora SDK screenshot](assets/sdk-screenshot.png)
 
-## Features
+---
 
-- **Immutable Event Logs**: SHA-256 hash chains for tamper-evident audit trails
-- **Policy Enforcement**: Model allowlist/denylist with classification-based rules
-- **Model Registry**: Centralized model and provider metadata
-- **Tracing**: Distributed tracing for AI system observability
-- **Event Processing**: Background event dispatcher with batching and buffering
-- **Multiple Sinks**: Output to stdout, file (JSON-lines), or HTTPS endpoints
-- **Durable HTTPS Delivery**: Retry queue + idempotency headers for HTTP sinks
-- **Event Enrichment**: Automatic metadata (timestamp, host, process, environment)
+## Streamlined Setup (Recommended)
+
+Use this local-first onboarding flow to get production-ready governance/reporting quickly:
+
+```bash
+# 1. Install and generate a base config
+npm install monora-ai
+npx monora-ai init --preset production
+
+# 2. Initialize onboarding contract + model spec + enrichment bundles
+npx monora-ai onboard init --config monora.yml
+
+# 3. Validate logs + schema mapping + role mapping
+npx monora-ai onboard validate --config monora.yml --pretty
+
+# 4. Complete onboarding and auto-generate baseline reports
+npx monora-ai onboard complete --config monora.yml --completed-by "platform-team" --pretty
 
-### New in v1.9.0
+# 5. Check onboarding status and generated artifacts
+npx monora-ai onboard status --config monora.yml --pretty
+```
+
+On completion, Monora writes baseline reports and summaries under `onboarding.artifacts.baseline_reports_dir` (default `./monora_reports/onboarding`):
+
+- `soc2_baseline_report.json`
+- `gdpr_baseline_report.json`
+- `iso27001_baseline_report.json`
+- `onboarding_validation.json`
+- `onboarding_summary.json`
+
+Each baseline report includes:
 
-- **🔄 Circuit Breaker**: Fault tolerance for HTTPS sinks with automatic recovery
-- **📊 Telemetry/Analytics**: Prometheus and StatsD metrics export for observability
-- **📄 PDF Reports**: Generate compliance and EU AI Act PDF reports
-- **🌐 Next.js Middleware**: W3C Trace Context propagation for Next.js applications
+- `claims[].severity`
+- `claims[].remediation`
+- `findings_summary` (totals, status breakdown, remediation recommendations)
 
-## Installation
+---
+
+## CLI Reference
 
 ```bash
-npm install monora-ai
+# Configuration
+npx monora-ai init                    # Interactive setup wizard
+npx monora-ai init --yes              # Quick setup with defaults
+npx monora-ai init --preset minimal   # Minimal preset
+npx monora-ai init --preset dev       # Dev preset (file + pretty stdout)
+npx monora-ai init --preset production # Production preset
+npx monora-ai validate                # Validate config file
+npx monora-ai validate --mode lenient # Lenient validation
+npx monora-ai doctor                  # Diagnose configuration issues
+npx monora-ai config fix              # Auto-fix common config issues
+
+# Onboarding lifecycle
+npx monora-ai onboard init --config monora.yml
+npx monora-ai onboard validate --config monora.yml --input ./monora_events.jsonl --pretty
+npx monora-ai onboard complete --config monora.yml --completed-by "platform-team" --pretty
+npx monora-ai onboard status --config monora.yml --pretty
+
+# Schema/model bootstrapping
+npx monora-ai schema infer \
+  --input ./monora_events.jsonl \
+  --output ./monora_spec.json \
+  --compliance-target gdpr \
+  --compliance-target soc2 \
+  --compliance-target iso42001 \
+  --report ./monora_inference_report.json \
+  --contract ./onboarding/schema_contract.json
+
+npx monora-ai model create \
+  --input ./monora_events.jsonl \
+  --output ./monora_model.json \
+  --model-name support-bot \
+  --risk-category high \
+  --compliance-target gdpr \
+  --compliance-target soc2 \
+  --compliance-target iso42001 \
+  --config-out ./monora_model_config.json \
+  --config-format json \
+  --contract-out ./onboarding/schema_contract.json
+
+# Reports
+npx monora-ai report --input events.jsonl --output report.json
+npx monora-ai report --input events.jsonl --output report.md --format markdown
+
+# Security & Verification
+npx monora-ai security-review --input events.jsonl --output security.json
+npx monora-ai verify --input events.jsonl --config monora.yml --pretty
+
+# Trust Packages
+npx monora-ai trust-package --input events.jsonl --trace-id trc_123 --output trust.json
+
+# HTTP Queue Management
+npx monora-ai retry-queue --config monora.yml
+npx monora-ai retry-queue --path ./monora_http_queue --clear
 ```
 
+---
+
 ## Quick Start
 
+After setup, initialize Monora in your app:
+
 ```typescript
 import { init, llmCall, trace } from 'monora-ai';
 
-// Initialize SDK
-init({ configPath: './monora.yml' });
+await init({ configPath: './monora.yml' });
 
 const ask = llmCall({ purpose: 'support' })(function ask(
   question: string,
@@ -50,6 +127,180 @@ trace('my-ai-task', (span) => {
 });
 ```
 
+Production gate behavior:
+
+- If `defaults.environment=production`
+- And `onboarding.enabled=true`
+- And `onboarding.required_in_production=true`
+- And `onboarding.status!=completed`
+
+`init()` fails fast with an onboarding-required error.
+
+---
+
+## Presets
+
+Use presets to generate opinionated configs:
+
+- minimal: file sink only, relaxed validation, minimal setup
+- dev: file + pretty stdout, relaxed validation for local development
+- production: file sink with daily rotation + symlink, strict validation
+
+Example:
+
+```bash
+npx monora-ai init --preset dev
+```
+
+---
+
+## Configuration
+
+`monora.yml` is the default config path (`monora.json` is also supported). For onboarding-driven production setup:
+
+```yaml
+defaults:
+  data_classification: internal
+  environment: production
+
+onboarding:
+  enabled: true
+  required_in_production: true
+  status: draft # draft | validated | completed
+  standards: [SOC2, GDPR, ISO27001]
+  artifacts:
+    production_logs_path: ./monora_events.jsonl
+    schema_contract_path: ./onboarding/schema_contract.json
+    dataset_sample_path: ./onboarding/dataset_sample.jsonl # optional
+    baseline_reports_dir: ./monora_reports/onboarding
+  validation:
+    min_log_records: 100
+    required_field_presence_threshold: 0.95
+    type_conformance_threshold: 0.90
+
+model_spec:
+  name: monora_default
+  version: v1
+  event_ts_field: timestamp
+  schema_ref: ./onboarding/schema_contract.json
+  roles:
+    inputs: [body.prompt]
+    outputs: [body.response]
+    metadata: [event_type, service_name, timestamp]
+    identifiers: [event_id, trace_id, span_id]
+
+enrichments:
+  profile: recommended
+  bundles: [core_observability, soc2_access, gdpr_privacy, iso27001_security]
+  toggles:
+    identity_tracking: true
+    risk_tracking: true
+    bias_tracking: false
+    oversight_tracking: true
+    data_governance_tracking: true
+    lifecycle_tracking: true
+```
+
+Notes:
+
+- `onboard validate` returns `coverage.profiling` and `coverage.inference` (field profiles, role suggestions, timestamp suggestion, schema mapping gaps).
+- `onboard complete` generates one report per selected standard and records outputs in `artifacts.baseline_reports`.
+- Enrichment bundles map to existing Monora observability, access, privacy, and security controls.
+
+### Programmatic Onboarding API
+
+```typescript
+import {
+  buildModelSpec,
+  validateOnboarding,
+  completeOnboarding,
+} from 'monora-ai';
+
+const modelSpec = buildModelSpec({
+  schemaRef: './onboarding/schema_contract.json',
+  roles: {
+    inputs: ['body.prompt'],
+    outputs: ['body.response'],
+    metadata: ['event_type', 'service_name', 'timestamp'],
+    identifiers: ['event_id', 'trace_id', 'span_id'],
+  },
+});
+
+const validation = validateOnboarding({ configPath: './monora.yml' });
+if (validation.status === 'validated') {
+  const completion = completeOnboarding({
+    configPath: './monora.yml',
+    completedBy: 'platform-team',
+  });
+  console.log(completion.status);
+}
+```
+
+Allowlist/denylist patterns use glob syntax (minimatch), for example `gpt-*` matches `gpt-4o-mini`.
+
+### HTTP Retry Queue + Idempotency
+
+```yaml
+sinks:
+  - type: https
+    endpoint: https://api.example.com/events # replace with your endpoint
+    retry_queue:
+      enabled: true
+      path: ./monora_http_queue
+      max_items: 10000
+      flush_interval_sec: 5.0
+    idempotency:
+      enabled: true
+      header_name: Idempotency-Key
+```
+
+Idempotency keys are computed per batch as a SHA-256 digest of the canonical event JSON in order.
+
+```bash
+npx monora-ai retry-queue --config monora.yml
+npx monora-ai retry-queue --path ./monora_http_queue --clear
+```
+
+---
+
+### File Sink Rotation
+
+```yaml
+sinks:
+  - type: file
+    path: ./monora_events.jsonl
+    rotation: daily   # none | daily | size
+    symlink: true     # keeps monora_events.jsonl and monora_events.latest.jsonl pointing to the newest file
+```
+
+When rotation is enabled, use `./monora_events.latest.jsonl` in scripts to always read the current file.
+
+---
+
+## Features
+
+- **Immutable Event Logs**: SHA-256 hash chains for tamper-evident audit trails
+- **Policy Enforcement**: Model allowlist/denylist with classification-based rules
+- **Model Registry**: Centralized model and provider metadata
+- **Tracing**: Distributed tracing for AI system observability
+- **Event Processing**: Background event dispatcher with batching and buffering
+- **Multiple Sinks**: Output to stdout, file (JSON-lines), or HTTPS endpoints
+- **Durable HTTPS Delivery**: Retry queue + idempotency headers for HTTP sinks
+- **Event Enrichment**: Automatic metadata (timestamp, host, process, environment)
+- **Attribution + Usage Telemetry**: Optional project registration and anonymous usage stats (opt-in)
+- **Compliance Assessment Hooks**: Built-in checks and usage profiles for audits
+
+### New in v2.1.3
+
+- **Circuit Breaker**: Fault tolerance for HTTPS sinks with automatic recovery
+- **Telemetry/Analytics**: Prometheus and StatsD metrics export for observability
+- **PDF Reports**: Generate compliance and EU AI Act PDF reports
+- **Next.js Middleware**: W3C Trace Context propagation for Next.js applications
+
+---
+
+## Usage Examples
+
 ### Decorator Helpers (TypeScript)
 
 ```typescript
@@ -85,32 +336,32 @@ Enable decorators in your `tsconfig.json`:
 }
 ```
 
-### Guided Setup (Wizard)
-
-```bash
-npx monora-ai init
-# or
-./node_modules/.bin/monora init
-```
+### High-level Runtime Helpers
 
-This generates a `monora.yml` you can load with `loadConfig({ configPath: './monora.yml' })`.
+```typescript
+import { init, logEvent, toolCall, agentStep, setViolationHandler } from 'monora-ai';
 
-### Reports & Security Review
+init({ configPath: './monora.yml' });
 
-The runtime automatically generates compliance reports at trace completion (default: `./monora_reports/<trace_id>/compliance.json`) and emits a `trust_summary` event. Configure behavior with the `reporting` section in `monora.yml`.
+setViolationHandler((violation) => {
+  console.error('Violation:', violation.message);
+});
 
-```bash
-npx monora-ai report --input events.jsonl --output report.json
-npx monora-ai report --input events.jsonl --output report.md --format markdown
+const fetchTool = toolCall({ toolName: 'fetch', purpose: 'integration' })(async (url: string) => {
+  return { ok: true, url };
+});
 
-npx monora-ai security-review --input events.jsonl --output security.json
-npx monora-ai security-review --input events.jsonl --output security.json --sign gpg --gpg-key "you@example.com"
+const plan = agentStep({ agentName: 'planner', stepType: 'planning', purpose: 'analysis' })(
+  (goal: string) => [`step for ${goal}`]
+);
 
-npx monora-ai trust-package --input events.jsonl --trace-id trc_123 --output trust.json --config monora.yml
-npx monora-ai verify --input events.jsonl --config monora.yml --pretty
-npx monora-ai retry-queue --config monora.yml
+logEvent('custom', { message: 'hello' }, { purpose: 'manual' });
 ```
 
+### Reports & Trust Packages
+
+The runtime automatically generates compliance reports at trace completion (default: `./monora_reports/<trace_id>/compliance.json`) and emits a `trust_summary` event.
+
 ```typescript
 import { exportTrustPackage } from 'monora-ai';
 
@@ -123,7 +374,7 @@ const trustPackage = exportTrustPackage('trc_123', {
 ### Data Handling + Alerts
 
 ```typescript
-import { DataHandlingEngine, buildDataViolation, ViolationWebhookDispatcher } from 'monora-ai';
+import { DataHandlingEngine, ViolationWebhookDispatcher } from 'monora-ai';
 
 const dataHandling = new DataHandlingEngine({
   enabled: true,
@@ -144,77 +395,7 @@ dispatcher.start();
 dispatcher.send({ event_type: 'policy_violation', message: 'Example violation' });
 ```
 
-### High-level Runtime Helpers
-
-```typescript
-import { init, logEvent, toolCall, agentStep, setViolationHandler } from 'monora-ai';
-
-init({ configPath: './monora.yml' });
-
-setViolationHandler((violation) => {
-  console.error('Violation:', violation.message);
-});
-
-const fetchTool = toolCall({ toolName: 'fetch', purpose: 'integration' })(async (url: string) => {
-  return { ok: true, url };
-});
-
-const plan = agentStep({ agentName: 'planner', stepType: 'planning', purpose: 'analysis' })(
-  (goal: string) => [`step for ${goal}`]
-);
-
-logEvent('custom', { message: 'hello' }, { purpose: 'manual' });
-```
-
-## Configuration
-
-Create a `monora.json` or `monora.yaml` file:
-
-```json
-{
-  "defaults": {
-    "data_classification": "internal",
-    "environment": "production"
-  },
-  "policies": {
-    "model_allowlist": ["gpt-4*", "claude-3-*"],
-    "model_denylist": ["deepseek:*"],
-    "enforce": true
-  },
-  "immutability": {
-    "enabled": true,
-    "scope": "per_trace",
-    "hash_algorithm": "sha256"
-  }
-}
-```
-
-### HTTP Retry Queue + Idempotency
-
-```yaml
-sinks:
-  - type: https
-    endpoint: https://api.example.com/events
-    retry_queue:
-      enabled: true
-      path: ./monora_http_queue
-      max_items: 10000
-      flush_interval_sec: 5.0
-    idempotency:
-      enabled: true
-      header_name: Idempotency-Key
-```
-
-Idempotency keys are computed per batch as a SHA-256 digest of the canonical
-event JSON in order. Reordering events or changing batch boundaries changes the
-idempotency key.
-
-Inspect or clear the local retry queue:
-
-```bash
-npx monora-ai retry-queue --config monora.yml
-npx monora-ai retry-queue --path ./monora_http_queue --clear
-```
+---
 
 ## API Documentation
 
@@ -224,7 +405,7 @@ npx monora-ai retry-queue --path ./monora_http_queue --clear
 import { PolicyEngine } from 'monora-ai';
 
 const engine = new PolicyEngine({
-  model_allowlist: ['gpt-4*'],
+  model_allowlist: ['gpt-*', 'claude-*', 'o1-*', 'gemini-*'],
   model_denylist: ['deepseek:*'],
   enforce: true
 });
@@ -293,23 +474,10 @@ const gaps = detectSequenceGaps(events);
 console.log('Sequence gaps:', gaps);
 ```
 
-### Security Reports
-
-Generate JSON security review reports locally with CLI:
-
-Auth: none (local CLI). Errors: invalid JSONL/config or GPG signing failures.
-
-```bash
-npx monora-ai security-review --input events.jsonl --output security.json
-npx monora-ai security-review --input events.jsonl --output security.json --config monora.yml
-```
-
 ### Data Handling
 
 Use the data handling engine for redaction or blocking decisions (modes: `redact`, `block`, `allow`):
 
-Auth: none. Errors: `DataHandlingViolation` in block mode or invalid regex patterns.
-
 ```typescript
 import { DataHandlingEngine } from 'monora-ai';
 
@@ -325,8 +493,6 @@ const { value, applied } = engine.sanitizePayload('request', payload, 'confident
 
 Send policy violation payloads to a webhook:
 
-Auth: set headers such as `Authorization`. Errors: network failures, non-2xx responses, or queue overflow.
-
 ```typescript
 import { ViolationWebhookDispatcher } from 'monora-ai';
 
@@ -349,8 +515,6 @@ dispatcher.send({ event_type: 'policy_violation', message: 'Blocked model' });
 
 ### Event Building and Dispatching
 
-Event builder and dispatcher classes are available in the current Node SDK.
-
 ```typescript
 import { EventBuilder, EventDispatcher, StdoutSink, FileSink } from 'monora-ai';
 
@@ -372,7 +536,7 @@ const event = builder.build('llm_call', {
 
 // Setup event dispatcher with sinks
 const sinks = [
-  new StdoutSink('json'),
+  new StdoutSink('pretty'),
   new FileSink('./events.jsonl', { batchSize: 100 }),
 ];
 
@@ -388,8 +552,6 @@ dispatcher.close();
 
 ### Sink Options
 
-These sink implementations are exported and ready for use.
-
 ```typescript
 // Stdout Sink
 const stdoutSink = new StdoutSink('pretty'); // or 'json'
@@ -402,7 +564,8 @@ const fileSink = new FileSink('./logs/events.jsonl', {
   maxSizeMb: 100,
 });
 
-// HTTPS Sink with retry
+// HTTPS sinks are optional; the wizard will not enable them unless you provide an endpoint.
+// HTTPS Sink with retry (example only)
 const httpsSink = new HttpSink(
   'https://api.example.com/events',
   { 'Authorization': 'Bearer token' },
@@ -415,7 +578,9 @@ const httpsSink = new HttpSink(
 );
 ```
 
-## v1.9.0 Features
+---
+
+## Advanced Features
 
 ### Circuit Breaker
 
@@ -440,21 +605,19 @@ const httpsSink = new HttpSink(
 
 ### Telemetry/Analytics
 
-Telemetry is enabled by default with a minimal in-memory backend (queue depth,
-sink errors, retry queue size). Opt out with `telemetry.enabled: false`.
+Telemetry is enabled by default with a minimal in-memory backend (queue depth, sink errors, retry queue size). Set `telemetry.backend` to `minimal`, `memory`, `prometheus`, `statsd`, or `none`. Opt out with `telemetry.backend: none` (or `telemetry.enabled: false`).
 
 Export metrics to Prometheus or StatsD:
 
 ```typescript
-import { init, initMetrics, recordEvent, recordViolation } from 'monora-ai';
+import { init } from 'monora-ai';
 
-// Configure telemetry
 init({
   configPath: './monora.yml',
   config: {
     telemetry: {
       enabled: true,
-      backend: 'prometheus', // or 'statsd'
+      backend: 'prometheus', // or 'statsd' | 'memory' | 'minimal' | 'none'
       prometheus: {
         port: 9090,
         start_server: true,
@@ -470,6 +633,79 @@ init({
 // - monora_tokens_total
 ```
 
+### Attribution & Usage Telemetry (Opt-In)
+
+Collect optional attribution details and anonymous usage stats with explicit opt-in. No data leaves your environment unless `send_data` is enabled.
+
+```typescript
+import { init } from 'monora-ai';
+
+init({
+  configPath: './monora.yml',
+  config: {
+    attribution: {
+      enabled: true,
+      project: {
+        company: 'Acme Corp',
+        role: 'ML Engineer',
+        email: 'dev@acme.com',
+        source: 'npm',
+        use_case: 'Customer Support AI',
+        team_size: 'small',
+        business_owner: 'Jane Smith',
+        data_categories: ['PII']
+      },
+      telemetry: {
+        enabled: true,
+        send_data: true,
+        data_residency: 'us'
+      }
+    }
+  }
+});
+```
+
+You can also call `registerProject(...)` and `reportUsage(...)` directly.
+
+### Environment-Aware Presets
+
+Monora can auto-select presets based on environment, or you can pick explicitly:
+
+```typescript
+import { init } from 'monora-ai';
+
+await init();                  // auto-detect env (dev/poc/production)
+await init({ preset: 'poc' }); // low-friction POC mode
+await init({ preset: 'production' });
+await init({ preset: 'strict_enterprise' });
+```
+
+Additional presets: `default_secure`, `experimental`, `audit_first`, `low_latency`.
+
+### Migration Guidance (POC -> Production)
+
+When you promote a POC to production, Monora will warn if you use a POC/dev preset in a production environment. You can also run the readiness checks directly:
+
+```typescript
+import {
+  validateProductionReadiness,
+  checkPresetEnvironmentMismatch,
+  logProductionWarnings,
+  loadConfig,
+} from 'monora-ai';
+
+const config = loadConfig({ configPath: './monora.yml' });
+let warnings = validateProductionReadiness(config);
+const mismatch = checkPresetEnvironmentMismatch(
+  'poc',
+  config.defaults?.environment || 'development'
+);
+if (mismatch) {
+  warnings = [mismatch, ...warnings];
+}
+logProductionWarnings(warnings);
+```
+
 ### Production Profiles
 
 Ship-ready templates with clear tradeoffs:
@@ -477,12 +713,51 @@ Ship-ready templates with clear tradeoffs:
 - Audit-first: `templates/monora_audit_first.yml` (strongest auditability, higher I/O and shutdown checks).
 - Low-latency: `templates/monora_low_latency.yml` (lowest overhead, weaker audit trail and reports).
 
+### Audit Hooks (onEvent)
+
+Capture every emitted event for external audit systems or SIEM pipelines:
+
+```typescript
+import { onEvent } from 'monora-ai';
+
+const unsubscribe = onEvent((event) => {
+  console.log('Audit:', event.event_type, event.event_id);
+  // Forward to your audit sink
+});
+
+// Later: unsubscribe();
+```
+
+### Compliance Assessment & Audit Metadata
+
+Capture audit metadata and run compliance checks for certification workflows:
+
+```typescript
+import { setAuditMetadata, runComplianceCheck, reportUsageProfile } from 'monora-ai';
+
+setAuditMetadata({
+  useCaseName: 'Customer Support AI',
+  businessOwner: 'Jane Smith',
+  dataCategories: ['PII', 'customer_data'],
+  riskLevel: 'medium',
+  complianceFrameworks: ['SOC2', 'ISO42001'],
+});
+
+const result = await runComplianceCheck({
+  eventsPath: './monora_events.jsonl',
+  configPath: './monora.yml',
+});
+const profile = reportUsageProfile();
+```
+
+Compliance scores are weighted by framework and control category (integrity, auditability, privacy, and governance) instead of a flat pass rate.
+
 ### Standards Mapping (SOC 2 / GDPR / ISO)
 
 Evaluate external claims against Monora evidence (event IDs, causal paths, guardrails):
 
 ```bash
-monora standards-check \
+npx monora-ai standards-check \
   --input ./monora_events.jsonl \
   --report ./SOC2_Report.pdf \
   --claims ./claims.json \
@@ -493,37 +768,32 @@ monora standards-check \
 Generate a claims manifest interactively (with optional coverage preview):
 
 ```bash
-monora standards-wizard \
+npx monora-ai standards-wizard \
   --standard SOC2 \
   --output ./claims.json \
   --input ./monora_events.jsonl \
   --config ./monora.yml
 ```
 
-Start with `templates/standards_claims_template.json` and customize the claims to
-match the sections you care about. Packaged standards templates are also available:
+Start with `templates/standards_claims_template.json` and customize the claims. Packaged standards templates:
 
 - SOC 2: `templates/standards/soc2_claims.json`
 - GDPR: `templates/standards/gdpr_claims.json`
 - ISO 27001: `templates/standards/iso27001_claims.json`
 
-If your report is JSON and already contains a `claims` list, you can pass it via
-`--report` without `--claims`.
-
-Supported checks: `policy_violations_max`, `unknown_models_max`, `forbidden_models_max`,
-`hash_chain_status`, `signatures_status`, `sequence_gaps_max`, `errors_max`, `config_required`.
+Supported checks: `policy_violations_max`, `unknown_models_max`, `forbidden_models_max`, `hash_chain_status`, `signatures_status`, `sequence_gaps_max`, `errors_max`, `config_required`.
 
 ### Report Ingestion + Excerpts (SOC 2 / GDPR / ISO)
 
 Ingest a report, extract text, and attach verified excerpts to your claims manifest:
 
 ```bash
-monora standards-ingest \
+npx monora-ai standards-ingest \
   --report ./SOC2_Report.pdf \
   --output ./report_ingest.json \
   --text-out ./SOC2_Report.txt
 
-monora standards-excerpt \
+npx monora-ai standards-excerpt \
   --ingest ./report_ingest.json \
   --claims ./claims.json \
   --excerpts ./excerpts.json \
@@ -534,7 +804,7 @@ monora standards-excerpt \
 Auto-suggest and approve excerpts interactively:
 
 ```bash
-monora standards-review \
+npx monora-ai standards-review \
   --ingest ./report_ingest.json \
   --claims ./claims.json \
   --output ./claims_with_excerpts.json
@@ -543,7 +813,7 @@ monora standards-review \
 Or produce suggestions as JSON:
 
 ```bash
-monora standards-suggest \
+npx monora-ai standards-suggest \
   --ingest ./report_ingest.json \
   --claims ./claims.json \
   --output ./suggestions.json \
@@ -654,6 +924,27 @@ export const createUser = withMonoraAction(
 );
 ```
 
+---
+
+## Troubleshooting
+
+- Validation fails due to null values: run `npx monora-ai config fix --config monora.yml` or validate with `npx monora-ai validate --mode lenient`.
+- Telemetry backend errors: set `telemetry.backend` to `minimal`, `memory`, `prometheus`, `statsd`, or `none`.
+- Daily rotation changed filenames: use `./monora_events.latest.jsonl` or set `rotation: none`.
+- CLI command not found: use `npx monora-ai <command>` (or `npm exec -- monora <command>`).
+- Console flooded with JSON: remove the stdout sink, set `format: pretty`, or export `MONORA_QUIET=1`.
+- HTTPS sink errors: only enable HTTPS sinks when you have a real endpoint; the wizard leaves them off by default.
+
+---
+
+## Migration Guide (Verbose/Null-Heavy Configs)
+
+1. Run `npx monora-ai config fix --config monora.yml` (creates a `.bak` backup).
+2. Optionally regenerate a minimal baseline with `npx monora-ai init --preset minimal` and copy over only the sections you use.
+3. Validate with `npx monora-ai validate --mode lenient`, then switch to `--mode strict` for production.
+
+---
+
 ## License
 
 MIT