mythos-router 1.7.2 → 1.12.0

package/AGENTS.md

@@ -0,0 +1,92 @@
+# AGENTS.md — mythos-router Project Standards
+
+## Project Identity
+- **Name**: mythos-router
+- **Type**: CLI power tool (local-first, zero-slop)
+- **Stack**: TypeScript on Node.js 20+ (ESM, `tsx` for dev)
+
+## Architecture
+- `src/cli.ts` — Commander.js entry point
+- `src/config.ts` — Constants, system prompt, validation, budget defaults
+- `src/client.ts` — Provider facade and Anthropic direct-client compatibility path
+- `src/budget.ts` — Session budget limiter (token cap, turn cap, progress bar)
+- `src/swd.ts` — SWD execution kernel (engine, types, parsing, snapshots, verification, rollback)
+- `src/swd-cli.ts` — SWD terminal presentation layer (verification output, dry-run preview)
+- `src/receipts.ts` — SWD trust receipts (creation, storage, drift verification)
+- `src/memory.ts` — Self-healing MEMORY.md manager (SQLite FTS5 derivative index)
+- `src/metrics.ts` — Global metrics store (persistent budget tracking)
+- `src/diff.ts` — Myers' diff algorithm (zero-dependency, line-by-line)
+- `src/git.ts` — Git operations (branching, committing, status)
+- `src/utils.ts` — Terminal colors, spinner, formatting, badges, confirm prompt
+- `src/index.ts` — Public SDK exports (SWDEngine, parseActions, etc.)
+- `src/commands/chat.ts` — Interactive REPL and one-shot run orchestration (ChatSession + ChatUI abstraction)
+- `src/commands/swd.ts` — Model-free external-agent SWD apply command (`mythos swd apply`)
+- `src/commands/init.ts` — Project initialization (environment checks, provider detection, scaffolding)
+- `src/commands/verify.ts` — Codebase ↔ Memory drift scanner (dry-run aware)
+- `src/commands/receipts.ts` — SWD receipt list/show/verify command
+- `src/commands/dream.ts` — Memory compression (dry-run aware)
+- `src/commands/stats.ts` — Budget analytics reporter
+
+## Conventions
+1. **Zero external runtime deps** beyond `@anthropic-ai/sdk` and `commander`
+2. **No `chalk`, no `ink`** — all terminal formatting is vanilla ANSI
+3. **ESM only** — `"type": "module"` in package.json
+4. All file operations use `node:fs` (sync) for SWD determinism
+5. **SWD is non-negotiable** — every model or external-agent file action is verified against the filesystem
+6. **MEMORY.md is sacred** — never delete it, only append or compress via Dream
+7. The system prompt lives in `config.ts` — do NOT scatter prompt fragments
+8. **Budget defaults live in `config.ts`** — 500K tokens, 25 turns, 80% warning
+9. **Pricing constants live in `config.ts`** — update provider pricing there when model rates change
+10. **Dry-run mode** — all filesystem writes must check `dryRun` flag before mutating
+
+## File Operation Protocol
+- Built-in model output and external agents must express file mutations as `[FILE_ACTION: path]...[/FILE_ACTION]` blocks or structured JSON actions.
+- SWD parses these actions, validates paths, snapshots before/after state, verifies against actual filesystem state, and rolls back failed mutations when enabled.
+- Max 2 correction retries before yielding to human in model-driven `chat`/`run` flows.
+- In `--dry-run` mode, actions are previewed and must not mutate files or write receipts.
+
+## External Agent SWD Protocol
+- `mythos swd apply --stdin --json` is the model-free integration point for external/autonomous agents.
+- It must not require `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `DEEPSEEK_API_KEY`; the external agent brings its own model/key.
+- External SWD input must fail closed: reject oversized input, malformed JSON/actions, path traversal, sensitive paths, and high-impact command-surface changes unless explicitly allowed.
+- Sensitive files such as `.env`, `.npmrc`, private keys, wallet files, and `.git` internals must remain blocked by default.
+- Receipts for external-agent applies should record the external agent/model identity without leaking secrets.
+
+## Budget Limiter Protocol
+- `SessionBudget` tracks tokens + turns + estimated cost per session (not persisted across runs)
+- Pre-check before every API call — **graceful save** at limit (progress → MEMORY.md)
+- Warning at 80% consumption
+- `--no-budget` disables for expert users
+- Correction turns count toward the budget
+
+## Running
+```bash
+# Dev mode (no build required)
+npx tsx src/cli.ts chat
+npx tsx src/cli.ts chat --dry-run --verbose
+npx tsx src/cli.ts chat --max-tokens 100000 --max-turns 10
+npx tsx src/cli.ts chat --no-budget
+npx tsx src/cli.ts run "explain this repo architecture"
+npx tsx src/cli.ts run --file TASK.md
+npx tsx src/cli.ts run "fix the failing smoke test" --dry-run
+your-agent --emit-file-actions | npx tsx src/cli.ts swd apply --stdin --json
+npx tsx src/cli.ts verify
+npx tsx src/cli.ts verify --dry-run
+npx tsx src/cli.ts dream
+npx tsx src/cli.ts dream --dry-run
+npx tsx src/cli.ts stats
+npx tsx src/cli.ts stats --days 7
+npx tsx src/cli.ts receipts
+npx tsx src/cli.ts receipts verify latest
+npx tsx src/cli.ts init
+npx tsx src/cli.ts init --check
+npx tsx src/cli.ts init --force
+
+# Or via npm scripts
+npm run chat
+npm run verify
+npm run dream
+npm run stats
+npm run receipts
+npm run init
+```

package/CHANGELOG.md

@@ -7,15 +7,123 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.12.0] - 2026-05-24
+
+### Added
+- **External Agent SWD Interface** - Added `mythos swd apply` so external agents can submit structured file actions to Mythos without calling a model provider or requiring an Anthropic key.
+- **Model Free SWD Automation** - Added `--stdin`, `--file <path>`, and `--json` support for machine readable external agent workflows.
+- **External Agent Receipt Metadata** - SWD receipts can now identify external agent/model sources for verified non-dry-run executions.
+
+### Changed
+- **Provider Key Validation** - `mythos chat` and `mythos run` now require at least one configured provider key instead of requiring Anthropic specifically, preserving Anthropic as the recommended/default provider when present.
+- **README and SDK Documentation** - Documented the agent neutral SWD execution flow, security defaults, BYOK provider selection, and receipt behavior for external agent use.
+
+### Security
+- **Fail Closed External Actions** - External SWD input is size limited, schema validated, constrained to safe project relative paths, and reviewed before filesystem mutation.
+- **Sensitive Path Protection** - External agent actions block `.env`, private keys, wallet files, `.git`, `.npmrc`, and secret-like paths by default. High impact command surface files and deletes require explicit `--allow-risky`.
+- **No Model Execution Boundary** - `mythos swd apply` does not call Anthropic, OpenAI, DeepSeek, provider fallback, memory compression, or test-healing; it only applies and verifies supplied file actions through SWD.
+
+---
+
+## [1.11.0] - 2026-05-22
+
+### Added
+- **`mythos learn` Command** - Added deterministic repo skill generation that creates `.mythos/skills/repo/SKILL.md` from local repo structure, docs, package scripts, CI workflows, public surfaces, and security-sensitive files without running project commands or calling a model.
+
+### Changed
+- **Skill Onboarding** - Skills can now be bootstrapped from detected repository signals instead of requiring maintainers to write every rule pack from scratch.
+
+---
+
+## [1.10.0] - 2026-05-20
+
+### Added
+- **`mythos skills` Command** - Added first-class skill pack management through `mythos skills`, `mythos skills show <name>`, `mythos skills new <name>`, and `mythos skills check`.
+- **Project-Local Skill Packs** - Added `.mythos/skills/<name>/SKILL.md` support so repositories can ship their own Mythos operating rules without relying on a user's global setup.
+- **Global Skill Packs** - Preserved reusable user-global skills in `~/.mythos-router/skills/<name>/SKILL.md`, with project-local skills taking precedence when names overlap.
+- **Skill Receipt Metadata** - SWD receipts now record active skill ids, names, versions, and sources so verified edits can be reviewed with the rule packs that guided them.
+- **Skill Documentation and Examples** - Added a dedicated skills guide plus example `repo` and `security-review` skill packs.
+- **Skill SDK Helpers** - Exported skill loading, listing, validation, creation, and prompt-building helpers through the public SDK entry point.
+
+### Changed
+- **Project Initialization** - `mythos init` now scaffolds and checks the project-local `.mythos/skills/` directory as part of repo onboarding.
+- **Skill Validation** - Skill checks now validate numeric limits, parse frontmatter arrays more consistently, and detect incompatibilities by either skill id or skill name.
+- **Receipt Privacy** - Receipt skill paths are stored only when they resolve inside the current project, avoiding accidental leakage of user-global or outside-project paths.
+
+---
+
+## [1.9.0] - 2026-05-19
+
+### Added
+- **`mythos run` Command** - Added one-shot prompt execution for tasks that do not need the interactive REPL. The command accepts any prompt, runs it through Mythos once, and exits.
+- **File and Stdin Prompt Sources** - `mythos run` can now read its prompt from a local file with `--file <path>` or from piped input with `--stdin`, making Mythos easier to use in scripts, task files, and editor workflows.
+- **Shared Chat/SWD Pipeline** - `run` reuses the existing chat session initialization, provider routing, SWD verification, receipts, memory logging, budget tracking, skills, and branch sandboxing instead of introducing a separate execution path.
+- **Bounded Run Defaults** - One-shot runs default to a smaller turn budget: one initial model turn, SWD correction turns, and optional test-healing turns only when `--test-cmd` is provided.
+- **Resume-Safe Execution** - `run` records metrics as its own command but does not overwrite the resumable session used by `mythos chat --resume`.
+- **`mythos init --check`** - Added a read-only setup check for environment, providers, `.mythosignore`, `MEMORY.md`, and the local skills directory without scaffolding or modifying files.
+
+### Changed
+- **Command Help Coverage** - CLI smoke coverage now checks that built help output includes the `run` and `init` commands, verifies the `run --help` prompt-source options, and covers `init --check` as a no-write smoke path.
+
+---
+
+## [1.8.1] - 2026-05-17
+
+### Fixed
+- **SWD Rollback Drift Protection** — Rollback now uses the cached post-verification snapshot, preventing Mythos from overwriting external file changes made after verification.
+
+### Changed
+- **CI Verification Gate** — Added a GitHub Actions step to run `node dist/cli.js verify --ci` against the locally built CLI.
+- **CI Hardening** — Tightened workflow permissions and install behavior.
+
+### Security
+- **Local Data Disclosure** - Documented where Mythos stores local memory, receipts, resumable sessions, metrics, cache data, and skills so users can inspect or clear private project state.
+
+---
+
+## [1.8.0] — 2026-05-15
+
+### Added
+- **CI Verification Mode** — Added `mythos verify --ci`, a read-only GitHub CI mode for reviewing PR/diff changes before merge
+- **Generic PR Review** — `verify --ci` now works even when no Mythos receipts are present, checking high-impact repository changes in generic PR-review mode.
+- **Receipt-Aware CI Checks** — When Mythos receipts are changed under `.mythos/receipts/`, CI verifies receipt integrity and changed-file coverage.
+- **Execution-Surface Detection** — Added CI checks for `package.json` script changes, npm lifecycle hooks, GitHub Actions workflows, shell/deploy/Docker surfaces, `.env`/`.npmrc` paths, private-key-like files, and high-confidence secret patterns.
+- **CI Output Options** — Added `--strict`, `--json`, and `--base <ref>` options for stricter CI policies, downstream tooling, and custom git base comparisons.
+- **CI Documentation** — Added `docs/CI.md` with GitHub Actions setup, exit behavior, examples, and maintainer notes.
+
+### Changed
+- **Verify Command Extension** — Extended `mythos verify` with a dedicated CI path while keeping normal local verification behavior unchanged.
+- **Test-Healing Loop Refactor** — Refactored the test-healing loop in `src/commands/chat.ts` into smaller helper methods for maintainability, without changing existing chat/SWD behavior.
+
+### Security
+- **No-AI CI Verification** — `verify --ci` does not call a model, use provider fallback, modify files, execute SWD actions, or write to `MEMORY.md`.
+- **Lifecycle Hook Review** — Newly added npm install lifecycle hooks such as `preinstall`, `install`, and `postinstall` are treated as high-severity CI findings.
+- **Execution-Surface Review** — Package scripts, workflows, shell/deploy files, and other high-impact repo surfaces are flagged for review before merge.
+- **Sensitive File Checks** — Added high-confidence checks for sensitive paths, private-key-like files, and secret-like material.
+
+---
+
+## [1.7.1] — 2026-05-13
+
+### Added
+- **Malformed Action Detection** — Mythos now warns when model output appears to include `[FILE_ACTION]` blocks but no valid actions can be parsed, making broken agent output easier to diagnose.
+- **Safety Regression Coverage** — Added tests covering receipt redaction, dry-run wording, and oversized write blocking.
+
+### Changed
+- **Safer Receipt Output** — Receipt test-output tails are now limited to 500 characters and redact obvious API keys, tokens, and secrets before being stored locally.
+
+### Fixed
+- **Large Write Protection** — Oversized `CREATE` and `MODIFY` actions are now blocked before touching disk, reducing the risk of unsafe full-file rewrites.
+
+---
+
 ## [1.7.0] — 2026-05-11
 
 ### Added
 - **SWD Trust Receipts** — Added persistent receipts for SWD runs, recording verified file outcomes, request summaries, provider/model metadata, token usage, git context, test status, and an integrity hash for later audit.
 - **`mythos receipts` Command** — Added receipt listing, inspection, and drift verification through `mythos receipts`, `mythos receipts show <id|latest>`, and `mythos receipts verify <id|latest>`, with `--json` output for automation.
-- **Receipt Regression Coverage** — Added tests for receipt save/list/read/verify behavior, drift detection, symlinked project roots, built CLI receipt commands, and Node 20/24-compatible test discovery.
 
 ### Fixed
-- **Receipt Path Normalization** — Receipt snapshots now store stable project-relative paths even when CI temp directories resolve through platform-specific symlinks such as macOS `/var` and `/private/var`.
 - **Machine-Readable JSON Output** — Terminal cursor restoration no longer contaminates redirected stdout, keeping `--json` output parseable in CI and shell pipelines.
 
 ---
@@ -260,6 +368,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Correction Turns** — max 2 retries before yielding to human.
 - **Dream/Verify Commands** — memory compression and drift detection.
 
+[1.12.0]: https://github.com/thewaltero/mythos-router/releases/tag/v1.11.0
+[1.11.0]: https://github.com/thewaltero/mythos-router/releases/tag/v1.11.0
+[1.10.0]: https://github.com/thewaltero/mythos-router/releases/tag/v1.10.0
+[1.9.0]: https://github.com/thewaltero/mythos-router/releases/tag/v1.9.0
+[1.8.1]: https://github.com/thewaltero/mythos-router/releases/tag/v1.8.1
+[1.8.0]: https://github.com/thewaltero/mythos-router/releases/tag/v1.8.0
+[1.7.1]: https://github.com/thewaltero/mythos-router/releases/tag/v1.7.1
 [1.7.0]: https://github.com/thewaltero/mythos-router/releases/tag/v1.7.0
 [1.6.1]: https://github.com/thewaltero/mythos-router/releases/tag/v1.6.1
 [1.6.0]: https://github.com/thewaltero/mythos-router/releases/tag/v1.6.0

package/README.md

@@ -13,7 +13,6 @@
 ## Claude Opus 4.7 · Strict Write Discipline · Zero Slop
 **A local CLI power tool for verifiable AI-assisted coding.**
 
-<br />
 
 [What is this?](#what-is-this) • [Features](#features) • [Installation](#installation) • [Usage](#usage) • [Architecture](#architecture) • [Token Budget](#token-usage--budget) • [SDK](#-sdk-usage-for-agentic-systems) • [SWD Protocol](#the-swd-protocol)
 
@@ -53,17 +52,21 @@ Zero slop. Zero hallucinated state. Full adaptive thinking.
 
 | Feature | Description |
 |---------|-------------|
-|  **mythos init** | Single-command project onboarding with environment validation and scaffolding |
-|  **Multi-Provider Fallback** | Auto-routes between Anthropic, DeepSeek, and OpenAI with circuit breakers |
-|  **Skills Protocol** | Inject modular expert plugins via YAML frontmatter (`-s mcp`, `-s react`) |
+|  **mythos init** | Single-command project onboarding with environment validation, read-only `--check`, and scaffolding |
+|  **mythos learn** | Generate a repo-local `SKILL.md` from detected project structure, scripts, docs, CI, and risk surfaces |
+|  **mythos run** | One-shot prompt mode with inline, file, stdin input, and optional `--provider` BYOK selection: same SWD, budget, skills, branch, and optional test-healing pipeline as chat |
+|  **Multi-Provider BYOK** | Auto-routes between configured Anthropic, DeepSeek, and OpenAI keys with circuit breakers; Anthropic is no longer required when another provider is configured |
+|  **Verified Skill Packs** | Load project-local or user-global `SKILL.md` rules with `-s <name>`; active skills are recorded in SWD receipts |
 |  **Deterministic Caching** | SQLite-backed caching for reasoning (SDK only) *(Node 22+)* |
 |  **Adaptive Thinking** | Opus 4.7 with configurable effort levels (high/medium/low) |
-|  **Strict Write Discipline** | Pre/post filesystem snapshots verify every model claim |
-|  **SWD Receipts** | Per-run trust receipts record touched files, hashes, provider, budget, git state, and verification result |
+|  **Strict Write Discipline** | Pre/post filesystem snapshots verify every model or external-agent file claim |
+|  **SWD Receipts** | Per-run trust receipts record touched files, hashes, provider/external-agent id, budget, git state, and verification result |
 |  **Self-Healing Memory** | Authority-based logging with a rebuildable SQLite FTS5 search index *(Node 22+)* |
 |  **Auto-Healing TDD** | Pass `--test-cmd` for bounded, error-driven autonomous repair loops |
 |  **Correction Turns** | Model gets 2 retries to match filesystem reality, then yields |
 |  **Integrity Gate** | `verify` command ensures referenced memory files still exist |
+|  **CI Verification** | `verify --ci` runs read-only PR checks for command-surface, sensitive-file, and receipt risks without an API key |
+|  **Bring Your Own Agent** | `mythos swd apply --stdin --json` lets any external agent route file actions through SWD without a Mythos model key |
 |  **Token Limiter** | Budget cap with graceful save — progress saved to MEMORY.md, never lose work |
 |  **Session Resume** | Pick up exactly where you left off after a crash or exit (`--resume`) |
 |  **Dry-Run Mode** | Preview every file operation before it executes — full transparency |
@@ -106,14 +109,18 @@ As memory approaches capacity, the `dream` command delegates a compression phase
 # Install globally
 npm install -g mythos-router
 
-# Set your API keys (Anthropic is primary, others are fallbacks)
+# Set at least one model key for mythos chat/run
+# Anthropic remains the recommended default, but OpenAI/DeepSeek can be used standalone.
 export ANTHROPIC_API_KEY="sk-ant-..."
-export OPENAI_API_KEY="sk-proj-..."
-export DEEPSEEK_API_KEY="sk-..."
+# export OPENAI_API_KEY="sk-proj-..."
+# export DEEPSEEK_API_KEY="sk-..."
 
-# Initialize and start
+# Initialize and start the built-in Mythos agent
 mythos init
 mythos chat
+
+# Or use only the model-free SWD layer with your own external agent
+your-agent --emit-file-actions | mythos swd apply --stdin --json
 ```
 
 ### Or try without installing
@@ -139,17 +146,65 @@ npm run chat
 
 ```bash
 mythos init                  # Initialize mythos-router in the current project
+mythos init --check          # Check environment and project setup without writing files
 mythos init --force          # Re-scaffold files even if they already exist
 ```
 
+`init` prepares the local repo surface Mythos uses: `.mythosignore`, `MEMORY.md`, and the project-local `.mythos/skills/` directory.
+
+### `mythos learn` - Repo Skill Generation
+
+```bash
+mythos learn                 # Generate .mythos/skills/repo/SKILL.md
+mythos learn --dry-run       # Preview the generated skill without writing files
+mythos learn --force         # Overwrite an existing repo skill
+mythos learn --name backend  # Generate .mythos/skills/backend/SKILL.md
+```
+
+`learn` turns the current repo into a reviewable project skill. It scans local repo signals such as `README.md`, `package.json`, source directories, CI workflows, config files, docs, tests, package scripts, public exports, and security-sensitive paths. It does not run npm scripts, shell commands, tests, builds, or a model. The generated `SKILL.md` is a deterministic starting point that should be inspected and edited like any other project file.
+
+### `mythos skills` - Verified Skill Packs
+
+```bash
+mythos skills                # List project-local and user-global skills
+mythos skills new repo       # Create .mythos/skills/repo/SKILL.md
+mythos skills new audit --global  # Create ~/.mythos-router/skills/audit/SKILL.md
+mythos skills show repo      # Inspect metadata and instructions
+mythos skills check          # Validate all discovered skills
+```
+
+Skill packs are repo operating manuals for Mythos. They encode project conventions, files to read first, files to avoid, review expectations, and verification rules without adding runtime code. Project-local skills live in `.mythos/skills/<name>/SKILL.md` and win over global skills with the same name. User-global skills live in `~/.mythos-router/skills/<name>/SKILL.md` for personal reuse across repositories.
+
+```bash
+mythos run --file TASK.md -s repo
+mythos chat -s repo -s security-review
+```
+
+When a non-dry-run SWD operation creates a receipt, Mythos records the active skill ids and versions. That makes skill-guided changes auditable: reviewers can see which repo rules were loaded when the verified edit happened. See [`docs/skills.md`](docs/skills.md) for the format and examples.
+
+### `mythos run` — One-Shot Task
+
+```bash
+mythos run "explain this repo architecture"
+mythos run --file TASK.md
+cat TASK.md | mythos run --stdin
+mythos run --provider openai "explain this repo architecture"
+mythos run "update the docs for verify --ci" --dry-run
+mythos run "fix the failing smoke test" --test-cmd "npm test"
+mythos run "refactor provider scoring" --branch provider-score
+```
+
+`run` sends one prompt through the same Mythos pipeline as `chat`, including SWD verification, budget tracking, skills, branch sandboxing, receipts, and optional `--test-cmd` healing. The prompt can come from the command line, a local file, or piped stdin. It exits after that prompt instead of opening the interactive REPL, and it does not overwrite the resumable chat session used by `mythos chat --resume`.
+
 ### `mythos chat` — Interactive Session
 
 ```bash
 mythos chat                  # Full power (high effort, Opus 4.7)
-mythos chat -s react         # Load the 'react' expert skill
+mythos chat -s repo          # Load a project-local skill pack
 mythos chat --test-cmd "npm test" # Enable autonomous test-driven self-healing
-mythos chat --effort low     # Budget mode (Haiku 4.5)
-mythos chat --effort medium  # Balanced (Sonnet 4.6)
+mythos chat --provider openai # Force a configured BYOK provider
+mythos chat --effort low     # Budget mode (Haiku 4.5 when using Claude)
+mythos chat --effort medium  # Balanced (Sonnet 4.6 when using Claude)
 mythos chat --resume         # Resume your previous session exactly where you left off
 mythos chat --dry-run        # Preview all file changes before executing
 mythos chat --verbose        # See full SWD traces and thinking
@@ -203,6 +258,62 @@ In dry-run mode, every file operation is previewed before execution:
 In-session commands:
 - `/exit`, `/q` or `quit` — End session (shows final budget summary)
 
+### `mythos swd apply` — Bring Your Own Agent
+
+```bash
+# Pipe raw [FILE_ACTION] blocks from any external agent
+your-agent --task "update docs" | mythos swd apply --stdin --json
+
+# Or pass a JSON action envelope
+cat actions.json | mythos swd apply --stdin --json --agent python-agent --model local-llama
+
+# Preview without touching disk or writing receipts
+cat actions.json | mythos swd apply --stdin --dry-run --json
+
+# High-impact files such as package.json require explicit opt-in; sensitive files stay blocked
+cat actions.json | mythos swd apply --stdin --allow-risky --json
+```
+
+`swd apply` is the model-free external-agent interface. It does **not** call Anthropic, OpenAI, DeepSeek, or any other model provider. Your agent keeps its own model key and only hands Mythos structured file actions. Mythos then applies Strict Write Discipline: path validation, security-policy review, pre/post snapshots, hash verification, rollback on failed verification, and local SWD receipts for successful non-dry-run applies.
+
+Accepted input formats:
+
+```text
+[FILE_ACTION: src/example.ts]
+OPERATION: CREATE | MODIFY | DELETE | READ
+INTENT: MUTATE | NOOP | UNKNOWN
+CONTENT_HASH: <optional sha256 of final content>
+DESCRIPTION: <one-line summary>
+CONTENT:
+<full file content for CREATE/MODIFY>
+[/FILE_ACTION]
+```
+
+```json
+{
+  "request": "external agent task label",
+  "summary": "CREATE: src/example.ts",
+  "agent": { "id": "python-agent", "model": "custom-model" },
+  "actions": [
+    {
+      "path": "src/example.ts",
+      "operation": "CREATE",
+      "intent": "MUTATE",
+      "description": "Create example file",
+      "content": "export const ok = true;\n"
+    }
+  ]
+}
+```
+
+Security defaults:
+- input is size-limited and schema-validated before execution
+- external JSON paths must be safe project-relative paths
+- `.env`, private keys, wallet files, `.git`, `.npmrc`, and secrets paths are blocked
+- deletes and command-surface files require `--allow-risky`
+- dry-runs do not write files or receipts
+- receipts record the external agent/model as `external:<agent-id>`
+
 ### `mythos receipts` — SWD Trust Receipts
 
 ```bash
@@ -212,19 +323,48 @@ mythos receipts verify latest  # Re-check current files against receipt hashes
 mythos receipts --json       # Machine-readable output for tooling
 ```
 
-Every non-dry-run SWD file operation writes a local receipt to `.mythos/receipts/`. Receipts include the user request summary, provider/model, token usage, budget snapshot, git branch/commit, per-file before/after hashes, rollback status, and optional `--test-cmd` result. `verify` turns those receipts into a quick drift check for "did the files still match what SWD verified?" Receipts are local by default and gitignored by default. They may include prompts, file paths, provider metadata, test command names, and a short test output tail. Do not publish raw receipts from private repositories; force-add only when you intentionally want a shared audit trail.
+Every non-dry-run SWD file operation writes a local receipt to `.mythos/receipts/`. Receipts include the request summary, provider or external-agent/model identity, git branch/commit, per-file before/after hashes, rollback status, and verification errors. Built-in `chat`/`run` receipts also include token usage, budget snapshot, active skill packs, and optional `--test-cmd` result. `verify` turns those receipts into a quick drift check for "did the files still match what SWD verified?" Receipts are local by default and gitignored by default. They may include prompts, file paths, provider metadata, skill names, test command names, and a short test output tail. Do not publish raw receipts from private repositories; force-add only when you intentionally want a shared audit trail.
 
-### `mythos verify` — Codebase ↔ Memory Existence Scan
+### `mythos verify` — Local Memory Scan + CI Verification
 
 ```bash
 mythos verify              # Scan and log results to MEMORY.md
 mythos verify --dry-run    # Scan without writing to MEMORY.md
+mythos verify --ci         # Read-only PR/diff verification for GitHub CI
+mythos verify --ci --json  # Machine-readable CI report
+mythos verify --ci --strict # Fail CI on warnings as well as high findings
 ```
 
-Scans your project and cross-references against `MEMORY.md`:
+Local mode scans your project and cross-references against `MEMORY.md`:
 - ✅ **Verified** — Memory logs are present and up to date
 - ❌ **Missing** — Memory references a file that doesn't exist
 
+CI mode does not call a model and does not require an API key. It reviews the current PR/diff for high-impact repo changes such as package scripts, npm lifecycle hooks, GitHub Actions workflows, shell/deploy surfaces, `.env`/`.npmrc`, high-confidence secrets, and changed Mythos receipts.
+
+GitHub Actions example:
+
+```yaml
+name: Mythos Verify
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  mythos-verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx mythos-router verify --ci
+```
+
+See [`docs/CI.md`](docs/CI.md) for exit behavior, strict mode, JSON output, and examples.
+
 ### `mythos dream` — Memory Compression
 
 ```bash
@@ -289,11 +429,14 @@ mythos-router/
 ├── src/
 │   ├── cli.ts           # Commander.js entry point
 │   ├── config.ts        # System prompt + constants + budget defaults + validation
-│   ├── client.ts        # Anthropic SDK (adaptive thinking, streaming)
+│   ├── client.ts        # Provider facade (Anthropic/OpenAI/DeepSeek BYOK routing)
 │   ├── budget.ts        # Session budget limiter (token cap, turn cap, progress bar)
 │   ├── swd.ts           # SWD execution kernel (engine, types, parsing, snapshots)
 │   ├── swd-cli.ts       # SWD terminal presentation (verification output, dry-run)
 │   ├── receipts.ts      # SWD trust receipt creation, storage, and verification
+│   ├── skills.ts        # Project-local and user-global SKILL.md packs
+│   ├── learn.ts         # Deterministic repo skill generator
+│   ├── ci/              # Read-only CI verification for PR/diff risk review
 │   ├── memory.ts        # MEMORY.md self-healing manager (SQLite FTS5 index)
 │   ├── metrics.ts       # Global metrics store (persistent budget tracking)
 │   ├── diff.ts          # Myers' diff algorithm (zero-dependency)
@@ -302,8 +445,12 @@ mythos-router/
 │   ├── index.ts         # Public SDK exports
 │   └── commands/
 │       ├── chat.ts      # Interactive REPL (ChatSession + ChatUI abstraction)
+│       ├── init.ts      # Project onboarding and read-only setup checks
 │       ├── verify.ts    # Codebase ↔ Memory scanner (dry-run aware)
+│       ├── swd.ts       # External-agent SWD apply command
 │       ├── receipts.ts  # SWD receipt list/show/verify command
+│       ├── skills.ts    # Skill pack list/show/new/check command
+│       ├── learn.ts     # Repo skill generation command
 │       ├── dream.ts     # Memory compression (dry-run aware)
 │       └── stats.ts     # Budget analytics reporter
 ├── src/providers/       # Multi-Provider Orchestration Engine
@@ -359,14 +506,20 @@ If you prefer to keep it private, add `MEMORY.md` to your `.gitignore`.
 
 | Env Variable | Required | Description |
 |-------------|----------|-------------|
-| `ANTHROPIC_API_KEY` | ✅ | Your Anthropic API key (Primary Provider) |
-| `OPENAI_API_KEY` | ❌ | OpenAI API Key (Fallback Provider) |
-| `DEEPSEEK_API_KEY` | ❌ | DeepSeek API Key (Fallback Provider, reasoning capable) |
+| `ANTHROPIC_API_KEY` | Optional* | Anthropic/Claude key; recommended default provider for `chat`/`run` |
+| `OPENAI_API_KEY` | Optional* | OpenAI API key; can be used as the only configured provider or fallback |
+| `DEEPSEEK_API_KEY` | Optional* | DeepSeek API key; can be used as the only configured provider or fallback |
+
+\* `mythos chat` and `mythos run` need at least one model provider key. `mythos swd apply` needs no model key because an external agent brings its own model/key and Mythos only verifies file actions.
 
 | File | Purpose |
 |------|---------| 
 | `.mythosignore` | Patterns to exclude from SWD scanning |
+| `.mythos/skills/` | Optional project-local skill packs that can be committed with a repo |
+| `.mythos/receipts/` | Local SWD receipts, gitignored by default because they may include prompts and file paths |
 | `MEMORY.md` | Auto-generated agentic memory log |
+| `~/.mythos-router/skills/` | User-global skill packs available across projects |
+| `~/.mythos-router/sessions/` | Resumable chat session state |
 
 ---
 

package/SECURITY.md

@@ -0,0 +1,75 @@
+# Security Policy
+
+## Philosophy
+
+mythos-router follows a **zero-trust AI model**.
+
+AI outputs are never trusted by default.
+All file operations are verified against the actual filesystem before being accepted.
+
+---
+
+## Safe Execution
+
+* AI-proposed file writes are routed through Strict Write Discipline (SWD) and verified against filesystem state.
+* Normal SWD file operations do not execute shell commands.
+* Git sandboxing uses fixed `git` subcommands with argument arrays.
+* `--test-cmd` is an explicit user-supplied escape hatch. It runs the provided command through the local shell for test-healing workflows, so only pass commands you trust.
+* There is no hidden shell lockdown mode; omit `--test-cmd` if you want model-driven sessions to avoid arbitrary shell execution.
+
+---
+
+## Environment Variables
+
+* Sensitive values (e.g. API keys) require explicit configuration
+* No implicit defaults are used for security-critical settings
+
+---
+
+## Local Data
+
+mythos-router stores local state in predictable locations:
+
+* `MEMORY.md` in the project root stores the human-readable agentic memory log.
+* `memory.db`, `memory.db-wal`, and `memory.db-shm` in the project root are derivative SQLite indexes rebuilt from `MEMORY.md`.
+* `.mythos/receipts/` stores local SWD receipts. These may include prompts, file paths, hashes, provider metadata, budget data, test command names, and a short redacted test output tail. This directory is gitignored by default.
+* `~/.mythos-router/sessions/latest.json` stores the latest resumable conversation history and budget state.
+* `~/.mythos-router/metrics.json` stores local token, cost, duration, command, and project metrics for `mythos stats`.
+* `~/.mythos-router/cache.db` may store SDK response-cache entries when the cache API is used. Responses containing tool calls or SWD file actions are not cached.
+* `~/.mythos-router/skills/` stores user-provided skill instructions loaded only when selected.
+
+Treat session files, receipts, memory, and cache files as private project data. Delete the relevant file or directory to clear that local state.
+
+---
+
+## Scope
+
+This tool is designed for **local execution only**.
+
+Users are responsible for:
+
+* reviewing AI-generated actions
+* validating changes before applying in production environments
+
+---
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+* X: **[@thewaltero](https://www.x.com/thewaltero)** *(recommended)*
+* Or open a private security advisory on GitHub
+
+Please avoid public disclosure until the issue has been reviewed.
+
+---
+
+## Supported Versions
+
+Currently supported:
+
+* Latest version on `main`
+
+Older versions may not receive security updates.
+
+---

package/dist/ci/git.d.ts

@@ -0,0 +1,6 @@
+import type { DiffInfo } from './types.js';
+export declare function assertGitRepository(cwd: string): void;
+export declare function getDiffInfo(cwd: string, base?: string): DiffInfo;
+export declare function readFileAtRef(cwd: string, ref: string, filePath: string): string | null;
+export declare function readPackageJsonBeforeChange(diff: DiffInfo): string | null;
+//# sourceMappingURL=git.d.ts.map

package/dist/ci/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/ci/git.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,QAAQ,EAAE,MAAM,YAAY,CAAC;AAgBxD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKrD;AAoGD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAoBhE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEvF;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAGzE"}