@probelabs/visor 0.1.106 → 0.1.107

package/dist/docs/proposals/snapshot-scope-execution.md

@@ -0,0 +1,236 @@
+# Snapshot + Scope Execution Model — Plan & Tracker
+
+Status: In progress
+Last updated: 2025-10-20
+
+This document captures an incremental plan to simplify Visor’s execution model using snapshot isolation (MVCC‑style) and scope‑aware output resolution, while preserving today’s routing semantics and recently added `on_finish` behavior (PR #146).
+
+It also lists a set of quick wins we can land immediately to polish PR #146 and align docs/engine behavior.
+
+---
+
+## Status Dashboard
+
+Priority scale: P0 = must‑have next; P1 = important; P2 = nice‑to‑have.
+
+Overall progress: ~85% complete (Phases 0–3 done; Phases 2 and 4 now complete; Phase 5 pending).
+
+| Phase | Priority | Status | % Complete | Notes |
+|---|---|---:|---:|---|
+| Phase 0 — Lay Hooks | P0 | ✅ Done | 100% | Journal + commits wired; unit coverage present. |
+| Phase 1 — Snapshot Visibility | P0 | ✅ Done | 100% | Engine builds dependencyResults from snapshot. |
+| Phase 2 — Outputs Surface | P1 | ✅ Done | 100% | outputs + outputs_history + outputs_raw shipped; docs updated with precedence matrix and examples. |
+| Phase 3 — Unified Scheduling | P0 | ✅ Done | 100% | runNamedCheck added; routing uses it; loop budget uniform. |
+| Phase 4 — Remove Per‑Item Map Cloning | P1 | ✅ Done | 100% | executeCheckInline and grouped forEach paths now use ScopePath + snapshot; minimal per-item overlay remains only within the same item’s inline descendant chain. |
+| Phase 5 — Fan‑Out/Reduce Control | P2 | ⏳ Not Started | 0% | Add reduce/fanout flag; keep default single‑run. |
+
+High‑priority backlog (outside phases)
+- [P0] Journal Event Scoping: tag entries with event; filter ContextView by current/goto_event.
+- [P1] Journal Performance Indexes: per‑(sessionId, checkId) indexes for readVisible.
+
+## Goals
+- Deterministic reads under concurrency: each step sees a point‑in‑time view of prior results in the current run/session.
+- Scope‑aware outputs for forEach: nearest item wins, with explicit raw/history accessors.
+- Unify inline/goto execution as scheduling in the same scope (no special contexts), with loop budgets enforced.
+- Keep provider interfaces, routing model (`on_success`, `on_fail`, `on_finish`, `goto_event`), and CI behavior.
+
+## Non‑Goals (for this iteration)
+- Dataflow auto‑scheduling when a template references a not‑yet‑executed step.
+- A new DSL for reduce/zip/cartesian across multiple forEach parents (we’ll add a minimal flag later if needed).
+
+---
+
+## Quick Wins For PR #146 (Low Risk)
+- [x] Fix built-in schema lookup for Action runs (load from dist/output via __dirname with cwd fallback).
+
+Checklist targets polish and parity; can be merged ahead of the snapshot work.
+
+- [x] Expose `outputs.history` (or `outputs_history`) in `on_finish.goto_js` sandbox to match docs and examples.
+- [x] Implement `on_finish.run_js` (docs mention it; engine currently ignores it).
+- [x] Count `on_finish` routing toward `routing.max_loops` (prevent cycles); add tests.
+- [x] Add `output_format` (command provider) to the config schema to remove warnings in examples.
+- [ ] Keep `defaults/.visor.yaml` and `dist/defaults/.visor.yaml` in sync or clearly document source of truth. (tracked separately)
+
+Acceptance checks
+- [x] Unit/E2E: `on_finish.run_js` executes and merges with static `run` (order defined and tested). See `tests/e2e/on-finish-run-js-e2e.test.ts`.
+- [x] E2E: `routing.max_loops` caps `on_finish` run/goto deterministically. See `tests/e2e/on-finish-loop-budget-e2e.test.ts`.
+- [x] E2E: fact‑validator example runs without schema warnings. Manual run verified.
+
+Target: by 2025-10-22
+
+---
+
+## Design At A Glance (Snapshot + Scope)
+
+Primitives
+```
+type ScopePath = Array<{ check: string; index: number }>; // e.g., [{check:"comments", index:3}]
+
+interface JournalEntry {
+  commitId: number;     // strictly increasing per session
+  sessionId: string;    // current run
+  scope: ScopePath;     // where this result belongs
+  checkId: string;      // producer
+  result: ReviewSummary & { output?: unknown; content?: string };
+}
+```
+
+ExecutionJournal
+- `beginSnapshot()` → returns the highest visible commitId now.
+- `commit(entry)` → stores a result with the next commitId.
+- `readVisible(sessionId, commitMax)` → entries ≤ commitMax.
+
+ContextView (what templates/routing read)
+- `get(checkId)` → nearest item in current scope; else ancestor; else latest.
+- `getRaw(checkId)` → aggregate output (e.g., full array for forEach parent).
+- `getHistory(checkId)` → all results up to snapshot.
+
+Resolution rules
+1) If current scope includes `{check:X,index:i}`, then `outputs['X']` → item `i`.
+2) Else prefer an ancestor scope entry for `X`.
+3) Else the latest committed result of `X` in the snapshot.
+4) `outputs_raw['X']` returns the aggregate parent output.
+5) `outputs_history['X']` returns prior committed outputs.
+
+---
+
+## Phased Plan (Incremental)
+
+Phase 0 — Lay Hooks (no behavior change)
+- [x] Add `ExecutionJournal` and `ContextView` (internal module).
+- [x] Commit every enriched result to the journal (in both normal and inline paths).
+- [x] No feature flags — default-ready rollout.
+
+Acceptance
+- [x] Unit: journal commits monotonicity (see tests/unit/snapshot-store.test.ts).
+
+Target: by 2025-10-24
+
+Phase 1 — Snapshot‑based Visibility (minimal surface)
+- [x] Build `dependencyResults` from a snapshot view instead of ad‑hoc `depends_on` maps in:
+  - [x] `executeWithRouting(...)`
+  - [x] `executeCheckInline(...)`
+- [x] Keep dependency graph for ordering; this change affects visibility only.
+
+Acceptance
+- [x] Unit: parallel checks read only entries ≤ their snapshot; later commits are not visible. (covered by snapshot-store tests)
+- [x] Integration: no‑deps visibility validated via snapshot with goto (see `tests/integration/snapshot-visibility-integration.test.ts`).
+
+Target: by 2025-10-28
+
+Phase 2 — Standardize Outputs Surface
+- [x] Expose `outputs`, `outputs_history` consistently in:
+  - [x] Liquid templates (providers: ai, command, log, memory)
+  - [x] Routing sandboxes (`on_success.run_js`, `on_success.goto_js`, `on_fail.run_js`, `on_fail.goto_js`, `on_finish.goto_js`)
+- [x] Expose `outputs_raw` for aggregate parent values (scope‑aware raw access)
+- [x] Document precedence and examples (short snippet + table)
+
+Acceptance
+- [x] Unit/Integration: routing sandboxes read outputs_history (see tests/integration/output-history-integration.test.ts).
+- [x] E2E: on_finish.goto_js can read outputs.history (see tests/e2e/on-finish-outputs-history-e2e.test.ts).
+- [x] outputs_raw surfaced across providers and routing (tests/integration/outputs-raw-integration.test.ts).
+
+Example: using outputs_raw
+
+```
+checks:
+  list:
+    type: command
+    exec: echo '["a","b","c"]'
+    forEach: true
+
+  use-raw-memory:
+    type: script
+    depends_on: [list]
+    content: |
+      const arr = outputs_raw["list"]; // → ["a","b","c"]
+      return { count: arr.length };
+
+  route-by-raw:
+    type: script
+    depends_on: [list]
+    content: |
+      return 'ok';
+    on_success:
+      goto_js: |
+        // Branch using the aggregate array
+        return (outputs_raw["list"] || []).length >= 3 ? 'after-route' : null;
+
+  after-route:
+    type: log
+    message: Reached after-route
+```
+
+Target: by 2025-10-31
+
+Phase 3 — Unified Scheduling Helper (same scope)
+- [x] Introduce `runNamedCheck(target, scope, opts)` used by inline/goto/on_finish.
+- [x] Ensure routing transitions count toward `routing.max_loops` uniformly.
+- [x] Preserve current single‑run semantics (no fan‑out yet).  
+  Note: Fan‑out control is deferred to Phase 5.
+
+Acceptance
+- [x] Integration: on_success/on_fail loop budgets enforced uniformly (tests/integration/routing-loop-budget-uniformity.test.ts).
+- [x] Integration: forEach item retry/remediation uses item context (tests/integration/routing-integration.test.ts).
+
+Target: by 2025-11-01
+
+Phase 4 — Remove Per‑Iteration Map Cloning
+- [ ] Delete special “override resultsMap per iteration” code; rely on `ContextView` unwrapping.
+
+Acceptance
+- [ ] Unit: forEach dependent checks still see the correct per‑item output.
+
+Target: by 2025-11-04
+
+Phase 5 — Optional Fan‑Out/Reduce Control
+- [ ] Add `fanout: map|reduce` (or `reduce: true`) on targets to control default behavior after forEach.
+- [ ] Default remains current (single run) for backward compatibility.
+
+Acceptance
+- [ ] Unit/E2E: with `fanout: map`, target runs once per item; with `reduce: true`, runs once at parent.
+
+Target: by 2025-11-06
+
+---
+
+## Engine Touchpoints (Where Changes Land)
+- `src/check-execution-engine.ts`
+  - Commit to journal after provider returns (both main and inline paths).
+  - Build snapshot‑based `dependencyResults` (Phase 1, default, no flags).
+  - Add `runNamedCheck(...)` and route `on_success`/`on_fail`/`on_finish` through it (Phase 3).
+  - Count `on_finish` routing toward loop budgets (Quick Win).
+- Routing sandbox init
+  - Inject `outputs`, `outputs_raw`, `outputs_history` (Phase 2).
+- Providers (AI/command/memory/log)
+  - Use standardized outputs surface for templates (Phase 2).
+
+---
+
+## Event Scoping & Safety
+- Journal entries should carry event context; default ContextView visibility is current event unless explicitly overridden by `goto_event`.
+- Loop budgets: every routing transition (success/fail/finish) consumes the same `routing.max_loops` counter.
+
+---
+
+## Performance Notes
+- Start with simple arrays; quickly add indexes by `(sessionId, checkId)`.
+- Snapshot build: avoid O(N) scans by caching latest per checkId per snapshot when feasible.
+
+---
+
+## Test Plan (Highlights)
+- Snapshot isolation under concurrency (parallel suites).
+- Event elevation with `goto_event` (issue → PR context) does not leak across events.
+- Fan‑out/Reduce behavior gated by explicit config.
+- Loop budget exhaustion errors are deterministic and logged.
+
+---
+
+## Rollout & Backout
+- Default rollout (no flags). Backout by reverting the engine changes if needed.
+
+---
+
+## Decision Log
+- 2025-10-20: Adopt snapshot+scope plan incrementally; keep dependency graph for ordering; visibility moves to snapshots.

package/dist/docs/recipes.md

@@ -0,0 +1,21 @@
+## 📚 Examples & Recipes
+
+- Minimal `.visor.yaml` starter
+```yaml
+version: "1.0"
+steps:
+  security:
+    type: ai
+    schema: code-review
+    prompt: "Identify security vulnerabilities in changed files"
+```
+
+- Fast local pre-commit hook (Husky)
+```bash
+npx husky add .husky/pre-commit "npx -y @probelabs/visor@latest --tags local,fast --output table || exit 1"
+```
+
+- More examples
+  - docs/NPM_USAGE.md – CLI usage and flags
+  - GITHUB_CHECKS.md – Checks, outputs, and workflow integration
+  - examples/ – MCP, Jira, and advanced configs

package/dist/docs/roadmap/criticality-implementation-tasks.md

@@ -0,0 +1,92 @@
+# Criticality & Contracts — Implementation Tasks (Do‑It‑Right)
+
+This file lists the remaining engineering tasks to fully implement the criticality model, contracts, and transitions as documented. Items are grouped and check‑listable. “(optional)” items can be phased in later.
+
+## 1) Schema & Types
+- [ ] Add `criticality` field to `CheckConfig` (`external | internal | policy | info`).
+- [ ] (optional) Add `assume_mode: 'skip' | 'fail'` to control unmet preconditions handling.
+- [ ] (optional) Add `retry_on: ['transient'] | ['transient','logical']` to narrow retry classes.
+- [ ] Update JSON schema generator and `src/generated/config-schema.ts`.
+- [ ] Update TypeScript types (`src/types/config.ts`, SDK exports).
+
+## 2) Config Validation & Linting
+- [ ] Validator: warn when `criticality` omitted on mutating providers (external inference) or forEach parents (control‑plane inference).
+- [ ] Validator: warn when critical steps lack `assume`/`guarantee`.
+- [ ] Validator: warn when `assume` references this step’s own `output`.
+- [ ] Validator: warn when `guarantee` contains policy thresholds better modeled as `fail_if`.
+- [ ] Validator: ensure `transitions[].to` targets exist (or null) and expressions compile.
+
+## 3) Engine Policy Mapping
+- [ ] Derive defaults from `criticality` at load time (but allow per‑check overrides):
+      - external/control‑plane/policy: `continue_on_failure=false`, retries transient‑only (max 2–3), loop budgets tighter (e.g., 8), contracts required.
+      - non‑critical: contracts optional, `continue_on_failure` may be true, default loop budget 10, retries standard.
+- [ ] Enforce “no auto‑retry for logical failures” in critical modes (fail_if/guarantee violations).
+- [ ] (optional) Per‑criticality loop budget override (e.g., control‑plane default 8).
+
+## 4) Runtime Semantics (clarity & safety)
+- [ ] Ensure `assume` is evaluated pre‑exec (no access to this step’s `output`), with clear error messaging.
+- [ ] Ensure `guarantee` is evaluated post‑exec, with issues emitted as `contract/guarantee_failed`.
+- [ ] Keep expressions sandboxed, pure, and short‑timed; log evaluation errors as fail‑secure decisions.
+- [ ] Transitions precedence over `goto_js` when both present; loop budget enforcement per scope.
+- [ ] (optional) forEach per‑item concurrency with default 1; cap via config.
+
+## 5) Side‑Effect Classification
+- [ ] Provider capability flags: identify mutating actions (GitHub ops except read‑only; HTTP methods ≠ GET/HEAD; file writes).
+- [ ] For critical external steps: provide idempotency and/or compensation hooks (sagas) (optional roadmap).
+- [ ] Suppress downstream mutating steps when contracts/fail_if fail in critical branches (via dependency gating).
+
+## 6) CLI & Safety Switches
+- [ ] `--safe-mode` flag to disable mutating providers (dry‑run all externals) for verification.
+- [ ] (optional) `--safety-profile strict|standard` to adjust loop budgets and retry caps globally.
+
+## 7) Telemetry & Observability
+- [ ] Emit structured fault events: `fault.detected`, `fault.isolated`, `fault.recovery.{attempted,failed,succeeded}`.
+- [ ] Metrics: retries attempted, logical vs transient failure counts, loop budget hits, contract violations by check.
+- [ ] Journal: ensure all contract/transition decisions and expressions are captured with scope/timestamps.
+
+## 8) Persistence
+- [ ] Keep JSON snapshot export (done) and add (optional) debug‑resume path gated by a debug flag.
+
+## 9) Defaults & Examples
+- [ ] Update `defaults/visor.yaml` (and any bundled defaults) to declare `criticality` for relevant checks and prefer `transitions` over `goto_js` where applicable.
+- [ ] Update `defaults/task-refinement.yaml` and `defaults/agent-builder.yaml` to use `criticality` and transitions where appropriate; ensure no `assume` refers to own output.
+- [ ] Convert inline YAML arrays in defaults to block‑style lists for consistency.
+- [ ] Add an annotated example block with all primitives (if, assume, guarantee, fail_if, transitions) and modes (reference the guides) in the defaults or examples folder.
+- [ ] Verify defaults run green via dist CLI:
+      - `npm run build:cli`
+      - `node dist/index.js test defaults/visor.tests.yaml --progress compact`
+      - Any other default suites (`task-refinement`, `agent-builder`) if present.
+
+## 10) Tests
+- [ ] Unit (engine/native):
+      - `assume` skip vs guard‑step hard‑fail (no provider call on skip).
+      - `guarantee` violation adds `contract/guarantee_failed` and does not double‑execute provider.
+      - Transitions precedence over `goto_js`; undefined transition falls back to `goto`.
+      - Loop budget enforcement per scope (error surfaced; routing halts in that scope).
+      - Criticality policy mapping (external/control‑plane/policy/non‑critical) sets defaults (gating, retries, budgets).
+- [ ] Integration:
+      - Critical external step blocks downstream mutating side‑effects on contract/fail_if failure (dependents gated).
+      - Control‑plane forEach parent respects tighter loop budget; no oscillation beyond cap.
+      - Retry classifier: transient provider errors retried; logical (fail_if/guarantee) not auto‑retried in critical modes.
+      - Non‑critical step with `continue_on_failure: true` does not block pipeline.
+- [ ] YAML e2e / Defaults:
+      - `defaults/visor.yaml` flow passes using transitions.
+      - `defaults/task-refinement.yaml` and `defaults/agent-builder.yaml` pass with `criticality` declared.
+      - Add a strict safety profile scenario (e.g., `safety: strict`) and ensure it passes.
+- [ ] CI Gates:
+      - Add a job to build CLI and run default YAML suites with `--progress compact`.
+      - Run unit/integration on PR; block merges on regressions.
+
+## 11) Docs (remaining polish)
+- [ ] README or landing page: link to Criticality Modes and Fault Management guides.
+- [ ] Ensure quick‑starts show `criticality` in at least one example (SDK & CLI done).
+- [ ] Sweep older docs for inline arrays (`[a, b]`) and convert to block lists.
+- [ ] Add “assume vs guarantee — do’s and don’ts” callout in any doc that introduces contracts (done for two guides).
+
+## Acceptance Criteria
+- [ ] All tests pass (unit/integration/YAML) with representative critical/non‑critical mixes.
+- [ ] Config validator warns on unsafe/missing contracts and mis‑declared criticality.
+- [ ] Engine enforces defaults per `criticality` while allowing explicit overrides.
+- [ ] Logs have timestamps; debug gated; decisions visible in journal and metrics.
+- [ ] No dist/ artifacts in commits.
+- [ ] Updated defaults (`defaults/visor.yaml`, `defaults/task-refinement.yaml`, `defaults/agent-builder.yaml`) run green via dist CLI in CI.

package/dist/docs/schema-next-pr.md

@@ -0,0 +1,10 @@
+# Schema Coverage – Next Phase
+
+This PR tracks follow-up work to expand the generated JSON Schema to cover all provider-specific keys and options without relying on runtime generation.
+
+Planned tasks:
+- Validate and document provider-specific fields (ai, log, command, http, http_input, http_client, claude-code).
+- Ensure additionalProperties is set appropriately per object; allow `x-` extensions.
+- Keep human-friendly error messages while surfacing unknown keys via Ajv warnings.
+
+This doc will be updated as changes land.

package/dist/docs/schema-templates.md

@@ -0,0 +1,68 @@
+## 📋 Schema-Template System
+
+Visor pairs JSON Schemas (data shape) with Liquid templates (rendering) so outputs are predictable, auditable, and GitHub‑native.
+
+### Overview
+- Schema validates check output at runtime (via AJV)
+- Template renders tables/markdown and GitHub Checks annotations
+- Group controls which GitHub comment a check posts to
+
+### Quick Example
+
+```yaml
+steps:
+  security:
+    type: ai
+    group: code-review
+    schema: code-review
+    prompt: "Review for security issues and return JSON"
+
+  overview:
+    type: ai
+    group: summary
+    schema: text
+    prompt: "Summarize PR in markdown"
+```
+
+### Built-in Schemas
+- code-review: structured findings with severity, file, line → native annotations
+- text: free‑form markdown content (no annotations)
+
+### Grouping
+
+```yaml
+steps:
+  security:   { group: code-review }
+  performance:{ group: code-review }
+  overview:   { group: summary }
+  assistant:  { group: dynamic } # always creates a new comment
+```
+
+### Custom Schemas
+
+```yaml
+schemas:
+  custom-metrics:
+    file: ./schemas/metrics.json
+
+steps:
+  metrics:
+    schema: custom-metrics
+    group: metrics
+```
+
+### GitHub Checks API Compatibility
+
+For status checks and annotations, use structured output with `issues[]` having:
+- severity: critical | error | warning | info
+- file, line, message
+
+Unstructured (none/plain) → posted as-is, no status checks.
+
+### Enhanced Prompts
+- Smart auto‑detection, Liquid templating, file‑based prompts
+- Template context: `pr`, `files`, `event`, `outputs`, `utils`
+- See [Liquid Templates Guide](./liquid-templates.md) for available variables and filters
+
+See full examples in `defaults/.visor.yaml`.
+

package/dist/docs/script.md

@@ -0,0 +1,34 @@
+## Script step (type: `script`)
+
+The `script` provider executes JavaScript in a secure sandbox with access to
+PR context, dependency outputs, and the Visor memory store.
+
+- Use `type: script` with a `content` block containing your code.
+- The sandbox exposes these objects:
+  - `pr`: basic PR metadata and file list.
+  - `outputs`: map of dependency outputs (plus `outputs.history`).
+  - `outputs_raw`: aggregated values from `-raw` dependencies.
+  - `outputs_history_stage`: per-stage output history slice for tests.
+  - `memory`: synchronous helpers `get`, `set`, `append`, `increment`, `delete`, `clear`.
+- The value you `return` becomes this step’s `output` (for `depends_on`).
+
+Example:
+
+```yaml
+steps:
+  extract-facts:
+    type: command
+    exec: node ./scripts/extract-facts.js
+
+  aggregate:
+    type: script
+    depends_on: [extract-facts]
+    content: |
+      const facts = outputs['extract-facts'] || [];
+      memory.set('total_facts', Array.isArray(facts) ? facts.length : 0, 'fact-validation');
+      const allValid = Array.isArray(facts) && facts.every(f => f.valid === true);
+      memory.set('all_valid', allValid, 'fact-validation');
+      return { total: memory.get('total_facts', 'fact-validation'), allValid };
+```
+
+The script context and memory helpers mirror other providers’ contexts.

package/dist/docs/sdk.md

@@ -0,0 +1,222 @@
+# Visor SDK (Programmatic Usage)
+
+Run Visor from Node.js without shelling out. The SDK is a thin façade over the existing engine: it just wires inputs/outputs and reuses all core behavior (routing, providers, templates, etc.).
+
+## Install
+
+```bash
+npm i -D @probelabs/visor
+```
+
+## Quick Start
+
+### JavaScript (ESM)
+```ts
+import { loadConfig, runChecks } from '@probelabs/visor/sdk';
+
+// Load config from object (not file!) - validation and defaults applied
+const config = await loadConfig({
+  version: '1.0',
+  checks: {
+    'security': { type: 'command', exec: 'npm audit' },
+    'lint': { type: 'command', exec: 'npm run lint' },
+  }
+});
+
+const result = await runChecks({
+  config,
+  checks: Object.keys(config.checks),
+  output: { format: 'json' },
+});
+console.log('Total issues:', result.reviewSummary.issues?.length ?? 0);
+```
+
+### TypeScript
+```typescript
+import { loadConfig, runChecks, type VisorConfig, type RunOptions } from '@probelabs/visor/sdk';
+
+// Type-safe config construction
+const rawConfig: Partial<VisorConfig> = {
+  version: '1.0',
+  checks: {
+    'security': { type: 'command', exec: 'npm audit' },
+    'lint': { type: 'command', exec: 'npm run lint' },
+  }
+};
+
+const config = await loadConfig(rawConfig);
+const result = await runChecks({
+  config,
+  checks: Object.keys(config.checks),
+  output: { format: 'json' },
+});
+
+// Type-safe result access with full type inference
+console.log('Total issues:', result.reviewSummary.issues?.length ?? 0);
+console.log('Checks executed:', result.checksExecuted);
+console.log('Execution time:', result.executionTime);
+```
+
+CommonJS
+```js
+const { loadConfig, runChecks } = require('@probelabs/visor/sdk');
+(async () => {
+  const config = await loadConfig({
+    version: '1.0',
+    checks: { test: { type: 'command', exec: 'echo test' } }
+  });
+  const result = await runChecks({ config, checks: Object.keys(config.checks), output: { format: 'json' } });
+  console.log('Total issues:', result.reviewSummary.issues?.length ?? 0);
+})();
+```
+
+### Loading from Files
+
+You can also load config from files:
+
+```ts
+import { loadConfig, runChecks } from '@probelabs/visor/sdk';
+
+// Load from specific file path
+const config = await loadConfig('./my-config.yaml');
+
+// Or discover default (.visor.yaml/.visor.yml)
+const config2 = await loadConfig();
+
+const result = await runChecks({
+  config,
+  checks: Object.keys(config.checks),
+  output: { format: 'json' },
+});
+```
+
+**Note:** The `output` parameter in `runChecks()` options controls the CLI output format (table/json/markdown/sarif). The config's `output` field is for GitHub PR comments and is optional for programmatic use.
+
+### Strict Validation Mode
+
+By default, unknown config keys generate warnings but don't fail. Enable strict mode to catch config errors early:
+
+```ts
+import { runChecks } from '@probelabs/visor/sdk';
+
+const config = {
+  version: '1.0',
+  checks: { test: { type: 'command', exec: 'echo test' } },
+  typo_field: 'oops'  // This would normally just warn
+};
+
+try {
+  await runChecks({
+    config,
+    checks: ['test'],
+    strictValidation: true  // Now throws error for unknown keys
+  });
+} catch (error) {
+  console.error('Config error:', error.message);
+  // Error: Unknown top-level key 'typo_field' will be ignored.
+}
+```
+
+## API
+
+- `loadConfig(configOrPath?: string | Partial<VisorConfig>, options?: { strict?: boolean }): Promise<VisorConfig>`
+  - Loads and validates a config from an object, file path, or discovers defaults
+  - Accepts config objects (validates and applies defaults) or file paths
+  - Returns fully validated config with all defaults applied
+  - Set `options.strict` to treat warnings as errors
+- `resolveChecks(checkIds: string[], config: VisorConfig | undefined): string[]`
+  - Expands check IDs to include dependencies in the correct order.
+- `runChecks(options: RunOptions): Promise<AnalysisResult>`
+  - Runs checks programmatically. Thin wrapper around the engine's `executeChecks`.
+
+### Types
+
+- `RunOptions`
+  - `config?: VisorConfig` | `configPath?: string`
+  - `checks?: string[]`
+  - `cwd?: string`
+  - `timeoutMs?: number`
+  - `output?: { format?: 'table'|'json'|'markdown'|'sarif' }`
+  - `debug?: boolean`
+  - `maxParallelism?: number`
+  - `failFast?: boolean`
+  - `tagFilter?: { include?: string[]; exclude?: string[] }`
+  - `strictValidation?: boolean` - Treat config warnings (unknown keys) as errors (default: false)
+
+- `AnalysisResult`
+  - `reviewSummary.issues: Issue[]`
+  - `executionTime: number`, `timestamp: string`, `checksExecuted: string[]`
+
+Refer to `src/types/config.ts` for `VisorConfig`, `Issue`, and related types.
+
+## Safety & Criticality (Quick Note)
+
+When building configs programmatically, model safety explicitly:
+
+- Declare criticality on steps with `criticality: external|internal|policy|info`.
+- Add contracts to critical steps:
+  - `assume:` preconditions checked before execution
+  - `guarantee:` postconditions checked after execution
+- Use declarative `transitions` for routing rather than `goto_js`.
+
+Example config (JS object):
+```ts
+const cfg = await loadConfig({
+  version: '1.0',
+  checks: {
+    'post-comment': {
+      type: 'github',
+      criticality: 'external',
+      on: ['pr_opened'],
+      op: 'comment.create',
+      assume: ["isMember()"],
+      guarantee: ["output && typeof output.id === 'number'"],
+      continue_on_failure: false,
+    },
+    // Structured outputs with unified `schema` (object) for validation
+    'summarize-json': {
+      type: 'ai',
+      schema: {
+        type: 'object',
+        properties: { ok: { type: 'boolean' }, items: { type: 'array', items: { type: 'string' } } },
+        required: ['ok', 'items']
+      },
+      prompt: 'Return JSON with ok and items...'
+    },
+    // Command/script can also use JSON Schema via `schema`
+    'aggregate': {
+      type: 'script',
+      content: 'return { all_valid: true };',
+      schema: { type: 'object', properties: { all_valid: { type: 'boolean' } }, required: ['all_valid'], additionalProperties: false }
+    }
+  },
+});
+```
+
+## Notes
+
+- SDK adds no new sandboxing or providers; all safety lives in the core engine.
+- For offline demos, unset provider env vars if you rely on mock providers.
+- You can still use all CLI features alongside the SDK in the same project.
+
+## Examples (in repo)
+
+- `examples/sdk-basic.mjs` (ESM) – Minimal example with raw config object
+- `examples/sdk-cjs.cjs` (CJS) – CommonJS usage
+- `examples/sdk-manual-config.mjs` (ESM) – Manual config construction with validation
+- `examples/sdk-typescript.ts` (TypeScript) – **Type-safe example** showing:
+  - Full TypeScript type safety with SDK type definitions
+  - Importing types from `@probelabs/visor/sdk`
+  - Type inference for configs and results
+  - Compile-time type checking
+  - Using exported types (`VisorConfig`, `RunOptions`)
+  - To run: `npx tsc examples/sdk-typescript.ts --module esnext --target es2022 --moduleResolution bundler --esModuleInterop --skipLibCheck && node examples/sdk-typescript.js`
+- `examples/sdk-comprehensive.mjs` (ESM) – **Complex example** showing:
+  - Multi-level check dependencies (`depends_on`)
+  - Tag filtering
+  - Parallel execution control
+  - Dependency resolution with `resolveChecks()`
+  - Strict validation mode
+  - Complete pipeline execution
+
+These are also exercised by CI smoke tests.