monora-ai 2.1.0 → 2.1.4

package/README.md

@@ -1,42 +1,118 @@
-# Monora SDK for Node.js v1.9.3
+# Monora SDK for Node.js v2.1.4
 
 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)
-- **Attribution + Usage Telemetry**: Optional project registration and anonymous usage stats (opt-in)
-- **Compliance Assessment Hooks**: Built-in checks and usage profiles for audits
+## Streamlined Setup (Recommended)
 
-### New in v1.9.0
+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
 
-- **🔄 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
+# 2. Initialize onboarding contract + model spec + enrichment bundles
+npx monora-ai onboard init --config monora.yml
 
-## Installation
+# 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
+
+# 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`
+- `iso42001_baseline_report.json`
+- `onboarding_validation.json`
+- `onboarding_summary.json`
+
+Each baseline report includes:
+
+- `claims[].severity`
+- `claims[].remediation`
+- `findings_summary` (totals, status breakdown, remediation recommendations)
+
+---
+
+## 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 --control-standard SOC2
+
+# 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,
@@ -52,6 +128,179 @@ 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, ISO42001]
+  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.4
+
+- **SOC2/GDPR Workflow Parity**: First-class SOC2/GDPR control catalogs and standard-aware workflow gap prioritization
+- **ISO42001 Onboarding Defaults**: Onboarding standards defaults now include `SOC2`, `GDPR`, `ISO27001`, and `ISO42001`
+- **Trust Package Selector**: `trust-package --control-standard ISO42001|SOC2|GDPR` selects bundled catalogs without custom paths
+
+---
+
+## Usage Examples
+
 ### Decorator Helpers (TypeScript)
 
 ```typescript
@@ -87,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';
 
@@ -125,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,
@@ -146,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
 
@@ -226,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
 });
@@ -295,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';
 
@@ -327,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';
 
@@ -351,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';
 
@@ -374,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 }),
 ];
 
@@ -390,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'
@@ -404,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' },
@@ -417,7 +578,9 @@ const httpsSink = new HttpSink(
 );
 ```
 
-## v1.9.0 Features
+---
+
+## Advanced Features
 
 ### Circuit Breaker
 
@@ -442,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,
@@ -474,8 +635,7 @@ init({
 
 ### 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.
+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';
@@ -498,7 +658,7 @@ init({
       telemetry: {
         enabled: true,
         send_data: true,
-        data_residency: 'eu'
+        data_residency: 'us'
       }
     }
   }
@@ -524,8 +684,7 @@ Additional presets: `default_secure`, `experimental`, `audit_first`, `low_latenc
 
 ### 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:
+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 {
@@ -591,15 +750,14 @@ const result = await runComplianceCheck({
 const profile = reportUsageProfile();
 ```
 
-Compliance scores are weighted by framework and control category (integrity,
-auditability, privacy, and governance) instead of a flat pass rate.
+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 \
@@ -610,37 +768,39 @@ 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`
+- ISO 42001: `templates/standards/iso42001_claims.json`
+
+Packaged control catalogs for trust-package/control-coverage workflows:
 
-If your report is JSON and already contains a `claims` list, you can pass it via
-`--report` without `--claims`.
+- SOC 2: `templates/controls/soc2_control_catalog.json`
+- GDPR: `templates/controls/gdpr_control_catalog.json`
+- ISO 42001: supported via default control catalog resolution
 
-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 \
@@ -651,7 +811,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
@@ -660,7 +820,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 \
@@ -771,6 +931,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