ai-runtime-engine 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to `ai-runtime` are documented here. The format follows
 Versioning](https://semver.org/). Development history and rationale live in
 [docs/DECISIONS.md](docs/DECISIONS.md) and [docs/PROGRESS.md](docs/PROGRESS.md).
 
+## [1.2.0] — 2026-08-31
+
+Closes the known gaps between what the CLI/REPL exposed and what the Runtime supported. Additive and
+backward compatible, with three small behavior corrections noted under Changed.
+
+### Added
+
+- **Approve / deny from the terminal** — `resume-execution --approve` / `--deny`, and REPL `/approve <id>`
+  / `/deny <id>`. A plan that stops at `waiting_for_approval` can now be advanced or cancelled from the
+  CLI or interactive terminal (previously reachable only programmatically or via a host `ApprovalProvider`).
+- **Live progress in the interactive terminal** — the REPL now prints concise mode/routing/fallback lines
+  during a run by subscribing to lifecycle events (it always claimed to, but never did).
+
+### Changed
+
+- **`chat` mode now honors `--dry-run` / `dryRun`** — a chat dry run makes **no** model call and captures
+  **no** memory; it reports what it would send. (Orchestration modes already did; chat used to run live.)
+- **`ai-runtime config`** now resolves `.ai-runtime/config.yaml` through the runtime loader, matching
+  every other command. It previously used the legacy root-only loader and reported "no config file found"
+  even when the canonical file was in use.
+- **`ai-runtime init`** now scaffolds the canonical `.ai-runtime/config.yaml` (same location as `setup`)
+  instead of a root `ai-runtime.yaml`. A root `ai-runtime.yaml` still works as a fallback if present.
+- **`ai-runtime telemetry`** empty-state message now explains that telemetry is buffered in-process and
+  points to `telemetry: { sink: file }` for history that survives across CLI invocations.
+
+## [1.1.1] — 2026-08-31
+
+Documentation only — no code changes.
+
+- Rewrote the README as a short, scannable landing page (~400 → ~140 lines) and removed relative links to
+  bundled docs / `LICENSE` / `CHANGELOG`, which show "no page found" on the npm package page (the source
+  repo is private). The full docs still ship in the package's `docs/` folder.
+- Added npm version / Node / license badges and a top-of-page `npm install` line.
+
 ## [1.1.0] — 2026-08-29
 
 Closes out the two items 1.0 deferred. Additive and backward compatible.
@@ -73,6 +107,8 @@ Initial release: the provider-agnostic AI **router** — capability-based routin
 scoring, evidence validation, fallback, health tracking, learning-based scoring, multi-model verification,
 budgets, MCP tools, OpenAPI-based adapter generation, and the `AI` class + CLI.
 
+[1.2.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.2.0
+[1.1.1]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.1.1
 [1.1.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.1.0
 [1.0.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.0.0
 [0.1.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v0.1.0

package/README.md

@@ -1,127 +1,44 @@
-# ai-runtime
+# AI Runtime
 
-**A provider-agnostic AI runtime for building and running AI features — without locking yourself to one vendor.**
+[![npm version](https://img.shields.io/npm/v/ai-runtime-engine)](https://www.npmjs.com/package/ai-runtime-engine)
+[![node](https://img.shields.io/node/v/ai-runtime-engine)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/ai-runtime-engine)](https://www.npmjs.com/package/ai-runtime-engine)
 
-You point it at whatever AI providers you have (cloud APIs, a local model, or an internal endpoint). It
-routes each request to the best available model, and gives you a whole runtime on top of that: modes,
-an interactive terminal, memory, skills, tools, planning, orchestration, comparison, and learning.
-
-```ts
-import { Runtime } from 'ai-runtime-engine';
-
-const runtime = await Runtime.load();                 // reads your config + .env
-const result  = await runtime.run({ input: 'Fix the failing tests' });
-console.log(result.response?.text);
-```
-
-> **The idea:** providers are replaceable; capabilities are durable. You never have to know *which*
-> provider handled a request — you describe what you want, and the runtime picks the right model and runs it.
-
-> 📘 **New here?** Start with the **[hands-on Guide](docs/GUIDE.md)** — install to first run, with runnable
-> examples you can try offline (no API key needed).
-
----
-
-## Contents
-
-- [What it is](#what-it-is)
-- [Requirements](#requirements)
-- [Install](#install)
-- [Quick start](#quick-start)
-- [How it works](#how-it-works)
-- [How to use it](#how-to-use-it) — modes, terminal, memory, skills, orchestration, comparison, learning
-- [Configuration](#configuration)
-- [What you need to do](#what-you-need-to-do) — a getting-started checklist
-- [CLI commands](#cli-commands)
-- [Package & distribution](#package--distribution)
-- [Security & privacy](#security--privacy)
-- [Troubleshooting](#troubleshooting)
-- [Further reading](#further-reading)
-- [Development](#development)
-
----
-
-## What it is
-
-Hardcoding one AI provider means vendor lock-in, availability risk, and painful migrations — and different
-providers are better at different things (reasoning, speed, cost, privacy), while any of them can be
-rate-limited, out of quota, or down.
-
-`ai-runtime` separates **provider support** from **provider availability**. Configure whatever you have
-once; then, on every request, the runtime:
-
-1. figures out **what kind of work** it is (a quick answer, a plan, a multi-step task, a comparison…),
-2. **routes** it to the best model you have that can actually do it (by capability, health, privacy, cost),
-3. **executes** through one normalized interface and **validates** the result,
-4. **falls back** to the next-best model if something fails, and
-5. returns a clean result with a full trace of how it decided.
-
-Around that router sits the **Runtime**: an interactive terminal, conversation history, durable memory,
-context building, a skill/tool system with permissions, planning and orchestration, resumable long-running
-tasks, model comparison, and learning from outcomes. Everything runs over native `fetch` — **no provider
-SDKs**.
-
----
-
-## Requirements
-
-- **Node.js 22 or newer.**
-- Git is optional (used to detect your workspace).
-- At least one AI provider — a cloud API key, or a local model via [Ollama](https://ollama.com) (no key needed).
-
----
-
-## Install
-
-The npm package is **`ai-runtime-engine`**. Installing it gives you both a **library** and the
-**`ai-runtime`** command-line tool (the command name is `ai-runtime` — a package name need not match its
-command name).
+**A provider-agnostic AI runtime — point it at whatever AI providers you have, and it routes each request
+to the best available model.** On top of that it adds an interactive terminal, memory, skills, tools,
+planning, orchestration, comparison, and learning.
 
 ```bash
-# in your project (library + local CLI via `npx ai-runtime`)
 npm install ai-runtime-engine
-
-# or install globally to get the `ai-runtime` command on your PATH
-npm install -g ai-runtime-engine
 ```
 
-Requires Node 22+. Use it as a library:
-
-```ts
-import { Runtime, AI } from 'ai-runtime-engine';
-```
-
-> **Naming:** the **product** is *AI Runtime*, the **npm package** is `ai-runtime-engine`, and the **CLI
-> command** is `ai-runtime`. The main API is `Runtime`; the lower-level router is `AI`.
+> **Naming:** the product is **AI Runtime**, the npm package is **`ai-runtime-engine`**, and the CLI command
+> is **`ai-runtime`**. In code you use `Runtime` (the high-level API) and `AI` (the low-level router).
 
 ---
 
 ## Quick start
 
-### Option A — the terminal (fastest)
+**In the terminal** (install globally, or use `npx ai-runtime …`):
 
 ```bash
-npm install -g ai-runtime-engine   # (or use `npx ai-runtime …` from a project that installed it)
-
-ai-runtime setup     # detects your workspace, generates config + .env.example (asks before each write)
-# → add a provider key to .env, OR install Ollama for a local, no-key model
-ai-runtime doctor    # check that a provider is configured and reachable
-ai-runtime           # open the interactive terminal — just type what you want
+npm install -g ai-runtime-engine
+ai-runtime setup      # scaffolds config + .env.example (asks before each write)
+ai-runtime doctor     # checks a provider is configured and reachable
+ai-runtime            # opens the interactive terminal — just type what you want
 ```
 
-### Option B — in code
+**In code:**
 
 ```ts
 import { Runtime } from 'ai-runtime-engine';
 
-const runtime = await Runtime.load({ workspace: process.cwd() });
-const r = await runtime.run({ input: 'Summarize what this repo does' });
+const runtime = await Runtime.load();                 // reads your config + .env
+const r = await runtime.run({ input: 'Fix the failing tests' });
 console.log(r.response?.text);
 ```
 
-### Try it with no keys (offline)
-
-Use the built-in mock provider to see everything work without any credentials — great for tests and demos:
+**Try it offline (no API key):** the built-in mock provider runs the whole pipeline with no credentials.
 
 ```ts
 import { Runtime, MockProvider, makeModel } from 'ai-runtime-engine';
@@ -139,142 +56,31 @@ console.log(r.response?.text, r.routing?.selected);   // includes the full routi
 
 ## How it works
 
-A request goes through one vendor-agnostic path. You provide the capabilities (providers, tools, skills,
-a workspace); the runtime decides *how* to use them.
-
-```
-runtime.run({ input })
-   │
-   ▼  resolve MODE (auto-detected, or set by you): chat · plan · execute · orchestrate · agent · compare · debug
-   │
-   ▼  build the model context under a token budget (workspace summary, memory, your request)
-   │
-   ▼  route to the best model  ──►  the ONE router:  filter (capability/health/privacy/cost) → score → pick
-   │                                                 → execute → validate → fall back on failure
-   │
-   ▼  for multi-step work: plan → run tools/skills as a DAG (succeed a step only on evidence) → replan on failure
-   │
-   ▼  result  { ok, response, routing trace, + plan / execution / comparison / memory as relevant }
-```
-
-Two principles hold everywhere:
+You describe *what you want*; the runtime picks *which model* runs it. A few ideas carry the whole design:
 
+- **Providers are replaceable; capabilities are durable.** You route by what a task needs (reasoning, JSON,
+  a big context window…), never by a provider name.
 - **One router.** Every model call — chat, planning, comparison, a skill's own call — goes through the same
-  router. There's never a second, hidden selection engine.
-- **Evidence over claims.** A step "succeeds" only when there's proof (a tool returned ok, a validator
-  passed) — never because a model said "done."
-
-For the engine's internals (scoring dimensions, strategies, provider contracts, the `AI` API), see
-[docs/router.md](docs/router.md).
+  router: filter (capability · health · privacy · cost) → score → pick → execute → validate → fall back.
+- **Modes** decide *what kind of work* it is: `chat`, `plan`, `execute`, `orchestrate`, `agent`, `compare`,
+  `debug`. `auto` (the default) detects it from your request.
+- **`Runtime` vs `AI`.** `Runtime` is the high-level API you'll use; `AI` is the bare router underneath it.
+- **Evidence over claims.** A step succeeds only with proof (a tool returned ok, a validator passed) — never
+  because a model said "done."
 
 ---
 
-## How to use it
-
-Load the runtime once, then `run()` requests. It resolves a **mode** and dispatches.
-
-```ts
-const runtime = await Runtime.load({ workspace: process.cwd() });
-runtime.ai.registerProvider(myProvider);   // register providers the same way as the router
-const r = await runtime.run({ input: 'Explain this stack trace: …' });
-```
-
-### Modes
-
-Every run resolves to one of eight modes. **`auto`** (the default) detects intent; you can force any mode
-per run (`{ mode: 'plan' }`), in config (`runtime.defaultMode`), or via `AI_DEFAULT_MODE`. Precedence:
-per-run > config > env > detection — an explicit mode is never overridden.
-
-| Mode | What it does |
-|---|---|
-| `chat` | A single conversational answer (memory- and workspace-aware). |
-| `plan` | Produce a structured plan; execute nothing. |
-| `execute` | Run a planned sequence once. |
-| `orchestrate` | Plan → execute → observe → replan until done or a limit is hit. |
-| `agent` | A longer autonomous loop with hard stops (iterations, budget, permissions). |
-| `debug` | Evidence-first investigation (gather → hypotheses → validate → conclude). |
-| `compare` | Fan the same task across models and analyze the results. |
-
-Mode is *what kind of work*; **autonomy** is *how much independent action* — `chat`/`plan` need no approval,
-`execute`/`orchestrate` ask before acting, `agent` runs autonomously within limits.
-
-### Interactive terminal
-
-Bare `ai-runtime` opens a REPL: type natural language, or use slash commands to inspect and steer —
-`/mode`, `/status`, `/info`, `/providers`, `/models`, `/skills [discover]`, `/tools`, `/permissions`,
-`/memory`, `/conversations`, `/resume`, `/executions`, `/compare`, `/feedback`, `/learning`, `/doctor`,
-`/cleanup`, `/dry-run`. For CI, `ai-runtime run "<input>" [--mode m] [--dry-run]` is the one-shot equivalent.
-
-### Conversations & memory
+## What you can do
 
-Conversations are saved verbatim (recoverable, with secrets scrubbed). Memory is durable, scoped facts —
-say "remember that we use Postgres" and it's kept, retrieved when relevant, and superseded when it changes.
-Turn persistence off entirely with `Runtime.load({ persistence: 'disabled' })` (for CI/ephemeral use).
-
-### Skills & tools (and your own)
-
-**Tools** are concrete operations — `filesystem`, `shell`, and `git` are built in; add your own. They're
-**deny-by-default**: reads are allowed and jailed to your workspace, but writes, shell, git commit/push,
-and network are off until you grant them in config.
-
-**Skills** are reusable capabilities that compose tools. Beyond the built-ins, the runtime **loads your
-own local skills**:
-
-- Drop a manifest (`*.skill.yaml`) or a JS module (`*.skill.mjs`) into **`.ai-runtime/skills/`** — auto-loaded.
-- `ai-runtime skills --discover` scans the rest of your repo and **reports** other skill files without
-  loading them (you enable one deliberately).
-- Install a **skill pack** (any npm package that exports `skills`) and name it under `skills.packages`.
-
-```yaml
-# .ai-runtime/skills/read-changelog.skill.yaml — a declarative skill (composes tools, no code)
-id: read-changelog
-version: 1.0.0
-name: Read changelog
-description: read CHANGELOG.md
-steps:
-  - tool: filesystem
-    input: { op: read, path: CHANGELOG.md }
-```
-
-### Planning, orchestration & dry-run
-
-For multi-step work, the runtime plans (using only your registered skills/tools), runs the plan as a DAG,
-succeeds a step only on evidence, and replans on failure. **Dry-run** (`run --dry-run`, `/dry-run`) shows
-the plan and what it *would* touch — with zero changes made.
-
-### Persistent executions & resume
-
-Longer runs are saved before they start and can be resumed. Resume never blindly continues: it re-checks
-your workspace (git state, touched files, config) and replans if anything drifted. `/executions`,
-`/resume-execution <id>`, `/pause`, `/cancel`.
-
-### Comparison
-
-`compare` mode (or `runtime.compare(...)`) runs the same task across models and shows where they agree,
-differ, and contradict each other. If you supply a way to *check* each answer (e.g. run the tests), the one
-that passes wins — evidence beats opinion.
-
-### Steering which models get used
-
-- **Exclude = a hard filter.** An excluded provider/model is **never** selected (it still shows in the
-  routing trace as `⊘ excluded by user configuration`).
-- **Prefer = a soft preference.** A preferred model is nudged up, but a preferred-but-incapable/unhealthy
-  one still loses.
-- **Neither configured = normal routing** across all eligible models.
-
-Set them in config `routing:`, per run (`runtime.run({ input, routing: {…} })`), or via environment
-variables — they combine, so an exclusion set anywhere always holds:
-
-```bash
-AI_EXCLUDE_PROVIDERS=ollama
-AI_EXCLUDE_MODELS=gemini:model-a,groq:model-b     # provider:model, or a bare model id
-AI_PREFER_PROVIDERS=gemini
-AI_PREFER_MODELS=groq:model-c
-```
-
-**Learning** — the runtime learns which providers/skills work from real outcomes and your `/feedback`, and
-turns that into *soft* preferences only. **Learning can never override an exclusion** (nor a privacy rule,
-a pin, a required capability, or the budget) — a guarantee proven by a dedicated test.
+- **Chat, plan, or run multi-step tasks** — preview any run with `--dry-run` (or `dryRun: true`) to see the
+  plan and what it *would* touch, with zero changes.
+- **Compare models** — `compare` mode (or `runtime.compare(...)`) runs a task across several models and
+  reports agreement, differences, and contradictions; a validator you supply lets evidence pick the winner.
+- **Remember facts** — durable, scoped memory that's retrieved when relevant (or turn it off with
+  stateless mode).
+- **Add your own skills** — drop a manifest into `.ai-runtime/skills/`, or install a skill pack from npm.
+- **Steer routing** — hard-`exclude` or soft-`prefer` providers/models via config, per-run, or env vars.
+- Everything that acts is **permission-gated and workspace-jailed** (see [Safety](#safety)).
 
 ---
 
@@ -284,9 +90,9 @@ Three places, and only these:
 
 | Path | What | In git? |
 |---|---|---|
-| `.ai-runtime/config.yaml` | Project config — runtime settings + providers (env-var **names** only). Falls back to root `ai-runtime.yaml`. | ✅ commit it |
-| `.env` | The secret **values** for the env vars your config names. | ❌ gitignored |
-| `~/.ai-runtime/` | Local state — conversations, memory, executions, cache, learning. Override with `AI_RUNTIME_HOME`. | ❌ never in git |
+| `.ai-runtime/config.yaml` | Project config — settings + providers (env-var **names**). | ✅ commit it |
+| `.env` | The secret **values** for those env vars. | ❌ gitignored |
+| `~/.ai-runtime/` | Local state — conversations, memory, executions, cache. Override with `AI_RUNTIME_HOME`. | ❌ never in git |
 
 A minimal config:
 
@@ -297,193 +103,41 @@ runtime:
 providers:
   - id: gemini
     kind: gemini
-    apiKeyEnv: GEMINI_API_KEY   # the NAME of the env var — never the value
-  - id: ollama                  # local, no key required
+    apiKeyEnv: GEMINI_API_KEY     # the NAME of the env var — never the value
+  - id: ollama                    # local, no key required
     kind: ollama
 ```
 
-**Provider API keys** go in `.env` — the config names the variable, the value lives here. Each provider
-kind has a default variable name (override with `apiKeyEnv`): `GEMINI_API_KEY`, `GROQ_API_KEY`,
-`ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY` (Ollama needs none).
-
-**Optional runtime variables** — all optional; unset means the built-in default:
-
-| Variable | Effect |
-|---|---|
-| `AI_DEFAULT_MODE` | Default mode when a run doesn't set one (`auto` by default). |
-| `AI_DEFAULT_STRATEGY` | Default routing strategy. |
-| `AI_CONTEXT_MAX_TOKENS` | Token budget for the compiled model context. |
-| `AI_MAX_COST_USD` · `AI_MAX_CALLS` | Per-run spend / call guardrails. |
-| `AI_MEMORY_ENABLED` | Set `false` to disable memory. |
-| `AI_LEARNING_ENABLED` | Set `false` to disable outcome learning. |
-| `AI_EXCLUDE_PROVIDERS` · `AI_EXCLUDE_MODELS` | Hard-exclude providers / models (see [steering](#steering-which-models-get-used)). |
-| `AI_PREFER_PROVIDERS` · `AI_PREFER_MODELS` | Soft-prefer providers / models. |
-| `AI_CONVERSATION_RETENTION_DAYS` · `AI_EXECUTION_RETENTION_DAYS` · `AI_ARTIFACT_RETENTION_DAYS` | Retention for `cleanup` (unset = keep everything). |
-| `AI_RUNTIME_HOME` | Override the `~/.ai-runtime/` state directory. |
-| `AI_TELEMETRY_ENABLED` | *Reserved — not yet honored by the runtime.* Telemetry is metadata-only and set in config. |
-
-`ai-runtime setup` writes the config and `.env.example` for you (asking first), and `ai-runtime info` shows
-everything resolved. For the full router config (routing strategies, scoring weights, privacy posture,
-telemetry, self-declared providers), see [docs/router.md](docs/router.md).
-
-### Providers
-
-If no provider is configured, `ai-runtime setup` and `ai-runtime doctor` walk you through adding one.
-Recommended starters:
-
-| Provider | Type | Key | Where to get it |
-|---|---|---|---|
-| **Google Gemini** | Cloud API | `GEMINI_API_KEY` | https://aistudio.google.com/apikey |
-| **Groq** | Cloud API | `GROQ_API_KEY` | https://console.groq.com/keys |
-| **OpenRouter** | Cloud API (aggregator) | `OPENROUTER_API_KEY` | https://openrouter.ai/keys |
-| **Ollama** | Local (no key) | — | https://ollama.com |
-
-Cloud providers need an API key; **Ollama** runs models locally with no key. Availability, models, and any
-free/paid tiers are set by each provider — check their site for current terms.
+Optional env vars (all optional): `AI_DEFAULT_MODE`, `AI_CONTEXT_MAX_TOKENS`, `AI_MAX_COST_USD`,
+`AI_MAX_CALLS`, `AI_MEMORY_ENABLED`, `AI_LEARNING_ENABLED`, `AI_EXCLUDE_PROVIDERS` / `AI_EXCLUDE_MODELS` /
+`AI_PREFER_PROVIDERS` / `AI_PREFER_MODELS`, `AI_*_RETENTION_DAYS`, `AI_RUNTIME_HOME`. Run `ai-runtime setup`
+to scaffold everything and `ai-runtime info` to see it resolved.
 
----
-
-## What you need to do
-
-A getting-started checklist:
-
-1. **Install** — Node 22+, then `npm install -g ai-runtime-engine` (or add it to a project). Verify with
-   `ai-runtime --help`.
-2. **Scaffold** — run `ai-runtime setup`. It creates `.ai-runtime/config.yaml`, `.env.example`, and
-   `.gitignore` entries (asking before each write).
-3. **Add a provider** — either put a real key in `.env` (e.g. `GEMINI_API_KEY=…`), or install
-   [Ollama](https://ollama.com) for a local model with no key.
-4. **Check it** — `ai-runtime doctor` confirms a provider is configured and reachable.
-5. **Use it** — `ai-runtime` (terminal), `ai-runtime run "…"` (one-shot), or `Runtime.load().run(…)` (code).
-6. **Go further (optional)** — add skills to `.ai-runtime/skills/`, grant write/shell permissions under
-   `permissions:` when you want the runtime to act, and set `routing:` to steer model selection.
+Recommended providers: **Google Gemini** (`GEMINI_API_KEY`), **Groq** (`GROQ_API_KEY`), **OpenRouter**
+(`OPENROUTER_API_KEY`), and **Ollama** (local, no key). Cloud providers need a key; Ollama runs locally.
 
 ---
 
-## CLI commands
-
-The commands you'll use day to day:
-
-| Command | What it does |
-|---|---|
-| `ai-runtime` | Open the interactive terminal. |
-| `ai-runtime setup` | Detect the workspace and scaffold config (asks before writing). |
-| `ai-runtime run "<input>" [--mode m] [--dry-run] [--json]` | Run one request (one-shot, for scripts/CI). |
-| `ai-runtime info [--json]` | Read-only summary: workspace, providers, skills, tools, memory, storage. |
-| `ai-runtime doctor [--json]` | Diagnose config, `.env` (by name), providers, models, store, permissions, git. |
-| `ai-runtime skills [--discover]` | List available skills; `--discover` reports skill files elsewhere in the repo. |
-| `ai-runtime cleanup [--dry-run] [--yes]` | Enforce retention, drop the cache, validate the store. |
-| `ai-runtime executions` · `resume-execution <id>` | List and resume persisted executions. |
+## Safety
 
-The engine also ships lower-level commands (`route`, `providers`, `models`, `capabilities`, `probe`,
-`discover`, `benchmark`, `presets`, `telemetry`) — see [docs/router.md](docs/router.md). Run any command
-with `--help` for its flags.
-
-### Inside the interactive terminal
-
-Type a request in plain language, or use a slash command to inspect and steer. The commands that exist
-today:
-
-```
-/help                          show all commands
-/status  /info                 workspace, mode, provider count · full runtime summary
-/mode [name]                   show or set the mode (auto|chat|plan|…)
-/providers                     list providers + access state
-/providers/all models          list every provider's models
-/providers/<id> [models|capabilities|health]   inspect one provider
-/providers/setup               how to add a provider (keys / Ollama)
-/models                        list all known models
-/skills [discover]  /tools  /permissions
-/memory [list|search <q>|delete <id>|clear]
-/conversations  /resume <id>
-/executions  /resume-execution <id>  /pause <id>  /cancel <id>
-/compare <request>             compare across all providers
-/feedback <text>  /learning    record feedback · show what was learned
-/dry-run                       toggle dry-run (plan only, no changes)
-/doctor  /cleanup  /config     diagnostics · retention preview · resolved config
-/clear  /exit
-```
+Everything read through tools, files, the web, or MCP is treated as **data, never instructions**.
+Filesystem access is jailed to your workspace; shell is allowlist-first with a destructive denylist; writes
+and network are off by default. Secrets are named by env var only and redacted from all output — the npm
+package contains only the runtime code, never your keys, memory, or local state.
 
 ---
 
-## Package & distribution
-
-| | |
-|---|---|
-| **Product** | AI Runtime |
-| **npm package** | `ai-runtime-engine` |
-| **CLI command** | `ai-runtime` |
-| **Source repository** | private |
-| **Project config** | `.ai-runtime/config.yaml` (committed) |
-| **Secrets** | `.env` (gitignored) |
-| **Runtime state** | `~/.ai-runtime/` (never committed) |
-
-The public npm package contains the **distributed runtime code** (compiled `dist/`), this README, and the
-changelog. It **does not** contain any of your data — no API keys, `.env`, memory, conversations, execution
-state, local indexes, cache, or other runtime state; those live only on your machine under `~/.ai-runtime/`
-and `.env`, and are never part of the package.
+## Documentation
 
-The **source repository is private**; the npm package is public. Note that a public npm package still ships
-runnable code — publishing to npm distributes the compiled implementation to anyone who installs it. It
-does not hide the implementation from package consumers; keeping the *repository* private only keeps the
-source history and development materials private.
+This package bundles fuller docs in its `docs/` folder (open them after installing):
 
----
-
-## Security & privacy
-
-- Everything the runtime reads through tools, files, the web, or MCP is treated as **data, never
-  instructions** — it can't change permissions, obtain secrets, run commands, or bypass approvals.
-- Filesystem access is **jailed to your workspace** (tested against `..`, absolute paths, and symlinks).
-  Shell is allowlist-first with a destructive-command denylist; writes, commit/push, and network are
-  each gated and off by default.
-- **Secrets are named by env var only** in config; an inline key is rejected at load, and every value is
-  redacted at every egress — including the terminal and logs.
-- **Privacy:** high-sensitivity input is kept off cloud providers unless you explicitly allow it.
-
-Full details in [docs/security.md](docs/security.md).
-
----
+- **`docs/GUIDE.md`** — a hands-on, study-friendly guide: install → first run → how it works → worked
+  examples, runnable offline.
+- **`docs/router.md`** — the engine reference: config keys, the `run()` API and `AI` class, providers,
+  routing internals.
+- **`docs/architecture.md`** — how the router and Runtime layers fit together.
+- **`docs/security.md`** — the full security model.
 
-## Troubleshooting
-
-- **"No compatible AI provider is available"** — run `ai-runtime doctor`: it shows which provider keys are
-  set (by name), which providers authenticated, and how many models are usable. Add a key to `.env`, or a
-  provider to config; with none, `ai-runtime setup` lists free/local options (Ollama needs no key).
-- **A provider is never chosen** — check `doctor` for its health and `/providers` for its access state; a
-  provider you excluded shows as `⊘ excluded by user configuration` in the routing trace.
-- **Writes or shell are refused** — that's deny-by-default; grant them under `permissions:` in config
-  (destructive shell always asks). Use `--dry-run` to preview what a run would touch.
-- **A local skill isn't loading** — `ai-runtime skills --discover` shows what was found and any load errors;
-  module skills load only from `.ai-runtime/skills/` or a configured `skills.paths`.
-- **Nothing persists** — you may be in stateless mode (`persistence: 'disabled'`) or have `AI_*_ENABLED`
-  toggles off; `ai-runtime info` shows storage status.
-
----
-
-## Further reading
-
-- **[docs/GUIDE.md](docs/GUIDE.md)** — a hands-on, study-friendly guide: install → first run → how it works
-  → worked examples, runnable offline.
-- **[docs/architecture.md](docs/architecture.md)** — how the two layers fit together, the one-router
-  invariant, and the lifecycle of a request.
-- **[docs/router.md](docs/router.md)** — the router engine reference: config keys, strategies, scoring,
-  providers, the `AI` API, and advanced features.
-- **[docs/security.md](docs/security.md)** — the full security model.
-- **[CHANGELOG.md](CHANGELOG.md)** — version history.
-
----
-
-## Development
-
-TypeScript, ESM, Node ≥ 22. The test suite is fully offline and deterministic.
-
-```bash
-npm install
-npm run typecheck     # tsc --noEmit (strict)
-npm test              # node:test — offline, no keys, no network
-npm run build         # tsc → dist/ (ESM + .d.ts)
-npm run cli -- info   # run the CLI from source
-```
+## License
 
-CI (GitHub Actions) runs typecheck, tests, and build on Linux and Windows for every push and pull request.
+ISC.

package/dist/cli/cli.js

@@ -20,7 +20,7 @@ import { skillsCommand } from './commands/skills.js';
 import { startRepl } from './interactive/repl.js';
 import { printError } from './render.js';
 const program = new Command();
-program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('1.1.0');
+program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('1.2.0');
 const configOpt = ['-c, --config <path>', 'path to an ai-runtime config file'];
 // Bare `ai-runtime` (no subcommand) opens the interactive terminal. `allowExcessArguments(false)` keeps
 // a mistyped subcommand (e.g. `ai-runtime porviders`) failing fast instead of silently opening the REPL.
@@ -48,6 +48,8 @@ program
     .description('Resume a persisted execution (reconciles the workspace first)')
     .option(...configOpt)
     .option('--answer <text>', 'answer a pending clarification')
+    .option('--approve', 'approve a plan that is waiting for approval, then continue')
+    .option('--deny', 'deny a plan waiting for approval (cancels the execution)')
     .action((id, o) => resumeExecutionCommand(id, o));
 program.command('init').description('Scaffold ai-runtime.yaml, .env.example, and .gitignore entries').action(() => initCommand());
 program

package/dist/cli/commands/config.js

@@ -3,16 +3,18 @@
  * defaults). Shows weights, strategy, policy posture, and timeouts. No secrets are read or printed.
  */
 import { resolveConfig } from '../../config/defaults.js';
-import { loadConfig, findConfigFile } from '../../config/load.js';
+import { loadRuntimeConfig } from '../../runtime/config.js';
 import { print } from '../render.js';
 export function configCommand(options) {
-    const file = options.config ?? findConfigFile();
-    const resolved = resolveConfig(loadConfig(options.config));
+    // Use the runtime loader so `.ai-runtime/config.yaml` is honored (root `ai-runtime.yaml` still works
+    // as a fallback) — matching every other command, instead of the legacy root-only loader.
+    const loaded = loadRuntimeConfig({ workspaceRoot: process.cwd(), ...(options.config ? { explicitPath: options.config } : {}) });
+    const resolved = resolveConfig(loaded.config.router);
     if (options.json) {
         print(JSON.stringify(resolved, null, 2));
         return;
     }
-    print(file ? `Resolved config (${file}):` : 'Resolved defaults (no config file found):');
+    print(loaded.configFile ? `Resolved config (${loaded.configFile}):` : 'Resolved defaults (no config file found):');
     print(`  providers:      ${resolved.providers.length}`);
     print(`  strategy:       ${resolved.strategy}`);
     print(`  timeoutMs:      ${resolved.timeoutMs}`);

package/dist/cli/commands/executions.d.ts

@@ -6,4 +6,6 @@ export declare function executionsCommand(options: {
 export declare function resumeExecutionCommand(id: string, options: {
     config?: string;
     answer?: string;
+    approve?: boolean;
+    deny?: boolean;
 }): Promise<void>;

package/dist/cli/commands/executions.js

@@ -14,10 +14,17 @@ export async function executionsCommand(options) {
 }
 export async function resumeExecutionCommand(id, options) {
     const rt = await Runtime.load({ ...(options.config ? { config: options.config } : {}) });
-    const r = await rt.resumeExecution(id, { ...(options.answer ? { clarificationAnswer: options.answer } : {}) });
+    // --approve proceeds past a waiting-for-approval gate; --deny cancels it. Neither → leave the decision.
+    const approve = options.approve ? true : options.deny ? false : undefined;
+    const r = await rt.resumeExecution(id, {
+        ...(options.answer ? { clarificationAnswer: options.answer } : {}),
+        ...(approve !== undefined ? { approve } : {}),
+    });
     if (r.response?.text)
         print(r.response.text);
     print(`status: ${r.status}`);
+    if (r.status === 'waiting_for_approval')
+        print('(waiting for approval — re-run with --approve to proceed or --deny to cancel)');
     if (r.clarification)
         print(`? ${r.clarification.question}`);
     if (!r.ok)

package/dist/cli/commands/init.js

@@ -2,8 +2,8 @@
  * `ai-runtime init` — scaffold a config, an env template, and gitignore entries. Never writes secrets;
  * the config carries only env-var NAMES, and `.env` is added to .gitignore.
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { print } from '../render.js';
 const EXAMPLE_YAML = `# ai-runtime configuration. Secret VALUES live in .env (gitignored); this file names env vars only.
 strategy: best
@@ -48,6 +48,7 @@ function writeIfAbsent(file, contents) {
         print(`  • ${file} already exists — left unchanged`);
         return;
     }
+    mkdirSync(dirname(full), { recursive: true });
     writeFileSync(full, contents);
     print(`  ✓ wrote ${file}`);
 }
@@ -65,11 +66,13 @@ function ensureGitignore() {
 }
 export function initCommand() {
     print('Initializing ai-runtime...');
-    writeIfAbsent('ai-runtime.yaml', EXAMPLE_YAML);
+    // Write the canonical `.ai-runtime/config.yaml` (the location the runtime loader prefers) so `init`
+    // and `setup` scaffold the same file. A root `ai-runtime.yaml` still works as a fallback if present.
+    writeIfAbsent('.ai-runtime/config.yaml', EXAMPLE_YAML);
     writeIfAbsent('.env.example', EXAMPLE_ENV);
     ensureGitignore();
     print('\nNext steps:');
     print('  1. Copy .env.example to .env and fill in the keys you have');
     print('  2. Run `ai-runtime doctor` to verify configuration');
-    print('  3. Run `ai-runtime route <task>` to route a task');
+    print('  3. Run `ai-runtime` to open the interactive terminal (or `ai-runtime run "<task>"`)');
 }

package/dist/cli/commands/phase2.js

@@ -65,8 +65,12 @@ export function telemetryCommand(opts) {
     const events = ai.telemetryEvents();
     const limit = opts.limit ? Number(opts.limit) : 20;
     const recent = events.slice(-limit);
-    if (recent.length === 0)
-        return print('No telemetry recorded in this session.');
+    if (recent.length === 0) {
+        print('No telemetry recorded in this session.');
+        print('(Telemetry is buffered in-process, so a fresh CLI invocation starts empty. For telemetry that');
+        print(' persists across processes, set `telemetry: { sink: file }` in your config.)');
+        return;
+    }
     for (const e of recent)
         print(JSON.stringify(e));
 }

package/dist/cli/interactive/repl.js

@@ -15,10 +15,30 @@ function banner(rt) {
     print(`mode: auto  ·  ${rt.ai.providers().length} providers  ·  type /help or a request, /exit to quit`);
     print('');
 }
+/** A concise, redacted progress line for a lifecycle event — the REPL's live feedback during a run. */
+function progressLine(e) {
+    switch (e.type) {
+        case 'mode.selected':
+            return e.source === 'auto' ? `  · mode: ${e.selected} (auto, ${Math.round(e.confidence * 100)}%)` : `  · mode: ${e.selected}`;
+        case 'provider.selected':
+            return `  · routed → ${e.providerId}/${e.model}`;
+        case 'provider.failed':
+            return `  · ${e.providerId}/${e.model} failed${e.category ? ` (${e.category})` : ''} — falling back`;
+        default:
+            return undefined; // runtime.started / clarification.requested / run.completed are covered by the result block
+    }
+}
 /** Start the interactive session. Resolves when the user exits (or stdin closes). */
 export async function startRepl(configPath) {
     const rt = await Runtime.load({ ...(configPath ? { config: configPath } : {}) });
     const session = new ReplSession(rt);
+    // Live progress: print concise routing/mode lines as they happen during a run. The events are already
+    // redacted; a throwing observer can never break a run (the emitter swallows sink errors).
+    rt.on((e) => {
+        const line = progressLine(e);
+        if (line)
+            print(line);
+    });
     banner(rt);
     const rl = createInterface({ input: process.stdin, output: process.stdout, prompt: '> ' });
     rl.prompt();

package/dist/cli/interactive/session.js

@@ -36,6 +36,8 @@ const HELP = [
     '  /resume <id>                resume a conversation',
     '  /executions                 list persisted executions',
     '  /resume-execution <id>      resume an execution',
+    '  /approve <id>               approve an execution waiting for approval, then continue',
+    '  /deny <id>                  deny an execution waiting for approval (cancels it)',
     '  /pause <id>                 pause an execution',
     '  /cancel <id>                cancel an execution',
     '  /config                     show the resolved configuration',
@@ -141,6 +143,10 @@ export class ReplSession {
                 return this.executionsList();
             case 'resume-execution':
                 return this.resumeExecution(args[0]);
+            case 'approve':
+                return this.resumeExecution(args[0], true);
+            case 'deny':
+                return this.resumeExecution(args[0], false);
             case 'pause':
                 return args[0] ? { lines: [this.runtime.pauseExecution(args[0]) ? `paused ${args[0]}` : `cannot pause '${args[0]}'`] } : { lines: ['usage: /pause <execution-id>'] };
             case 'cancel':
@@ -165,8 +171,10 @@ export class ReplSession {
             lines.push(`[${result.error.category}] ${result.error.message}`);
         if (result.mode.executed !== result.mode.selected)
             lines.push(`(mode: ${result.mode.selected} → ${result.mode.executed})`);
-        if (result.status === 'waiting_for_approval')
-            lines.push('(approval required before execution — resume the execution to approve)');
+        if (result.status === 'waiting_for_approval') {
+            const execId = result.execution?.id;
+            lines.push(execId ? `(approval required — /approve ${execId} to proceed, or /deny ${execId})` : '(approval required — approve the execution via /executions then /approve <id>)');
+        }
         if (result.status === 'failed')
             lines.push('(did not complete)');
         if (result.clarification)
@@ -249,14 +257,16 @@ export class ReplSession {
             return { lines: ['no executions yet.'] };
         return { lines: ['Executions:', ...list.map((e) => `  ${e.id}  [${e.status}]  ${e.mode}: ${e.goal.slice(0, 50)}`)] };
     }
-    async resumeExecution(id) {
+    async resumeExecution(id, approve) {
         if (!id)
-            return { lines: ['usage: /resume-execution <execution-id>'] };
-        const r = await this.runtime.resumeExecution(id);
+            return { lines: [`usage: /${approve === undefined ? 'resume-execution' : approve ? 'approve' : 'deny'} <execution-id>`] };
+        const r = await this.runtime.resumeExecution(id, approve !== undefined ? { approve } : {});
         const lines = [];
         if (r.response?.text)
             lines.push(r.response.text);
         lines.push(`status: ${r.status}`);
+        if (r.status === 'waiting_for_approval')
+            lines.push('(waiting for approval — /approve ' + id + ' to proceed, /deny ' + id + ' to cancel)');
         if (r.clarification)
             lines.push(`? ${r.clarification.question}`);
         return { lines };

package/dist/runtime/runtime.d.ts

@@ -186,6 +186,10 @@ export declare class Runtime {
     private contextBlocks;
     /** Best-effort estimator calibration from provider-reported input usage (estimates never claim to be exact). */
     private calibrate;
-    /** Capture an explicit "remember …" fact and retrieve relevant facts for context. Off when disabled. */
+    /**
+     * Capture an explicit "remember …" fact and retrieve relevant facts for context. Off when disabled.
+     * `capture` is false on a dry run — retrieval is read-only, but writing a fact is a mutation the dry
+     * run must not perform.
+     */
     private applyMemory;
 }

package/dist/runtime/runtime.js

@@ -350,8 +350,9 @@ export class Runtime {
         const clarification = buildClarification(modeResult);
         if (clarification)
             this.emitter.emit({ type: 'clarification.requested', runId, question: clarification.question });
-        // Memory: capture an explicit "remember …" and retrieve relevant facts into context.
-        const memTrace = this.applyMemory(text);
+        // Memory: retrieve relevant facts into context, and (unless this is a dry run) capture an explicit
+        // "remember …". A dry run performs zero mutations, so it retrieves but never writes.
+        const memTrace = this.applyMemory(text, !policy.dryRun);
         // Compile the model context (workspace summary + memory facts + user system) under a token budget.
         const budget = resolveContextBudget({
             ...(req.context?.maxTokens !== undefined ? { perRun: req.context.maxTokens } : {}),
@@ -360,6 +361,19 @@ export class Runtime {
         });
         const compiled = compileContext(this.contextBlocks(req, context.workspace, memTrace?.retrieved), { budgetTokens: budget, estimator: this.estimator });
         const contextReport = { metrics: compiled.metrics, validation: compiled.validation };
+        // Dry-run: chat's only "action" is the model call itself, so a dry run makes NO call. It reports
+        // what it would send (mode, compiled-context size) and performs zero mutations.
+        if (policy.dryRun) {
+            const status = clarification ? 'waiting_for_clarification' : 'completed';
+            this.emitter.emit({ type: 'run.completed', runId, ok: true, status, confidence: 1 });
+            const preview = `[dry-run] chat — no model call made. Would compile ${compiled.metrics.compiledTokens} context token(s) (budget ${budget}) and send one request to the best-matching provider. Run without --dry-run to execute.`;
+            const result = { ok: true, runId, mode: resolution, status, response: { text: preview }, context: contextReport, artifacts: [] };
+            if (clarification)
+                result.clarification = clarification;
+            if (memTrace)
+                result.memory = memTrace;
+            return result;
+        }
         const runRequest = buildChatRequest(req, strategy, compiled.system || undefined, routing);
         const runResult = await this._ai.run(runRequest);
         this.calibrate(runRequest.system, text, runResult);
@@ -673,16 +687,22 @@ export class Runtime {
         if (tokens && tokens > 0)
             this.estimator.calibrate((system?.length ?? 0) + inputText.length, tokens);
     }
-    /** Capture an explicit "remember …" fact and retrieve relevant facts for context. Off when disabled. */
-    applyMemory(text) {
+    /**
+     * Capture an explicit "remember …" fact and retrieve relevant facts for context. Off when disabled.
+     * `capture` is false on a dry run — retrieval is read-only, but writing a fact is a mutation the dry
+     * run must not perform.
+     */
+    applyMemory(text, capture = true) {
         if (!this.memoryEnabled())
             return undefined;
         try {
             const trace = { retrieved: [] };
-            const candidate = classifyMemory(text);
-            if (candidate) {
-                const rec = this._memory.remember(candidate);
-                trace.captured = { id: rec.id, scope: rec.scope };
+            if (capture) {
+                const candidate = classifyMemory(text);
+                if (candidate) {
+                    const rec = this._memory.remember(candidate);
+                    trace.captured = { id: rec.id, scope: rec.scope };
+                }
             }
             trace.retrieved = this._memory.search(text, { limit: 3 }).map((h) => h.text);
             if (trace.retrieved.length === 0 && !trace.captured)

package/docs/GUIDE.md

@@ -66,8 +66,9 @@ You can run the whole pipeline with a **mock provider** — no credentials, no n
 ```js
 import { Runtime, MockProvider, makeModel } from 'ai-runtime-engine';
 
-// A fresh runtime with no persistence (nothing written to disk).
-const runtime = new Runtime();
+// A fresh runtime in stateless mode, so this demo writes nothing to disk.
+// (Persistence is ON by default; pass { persistence: 'disabled' } to turn it off.)
+const runtime = new Runtime(undefined, { persistence: 'disabled' });
 
 // Register one fake provider with one fake model that can "reason" and output "text".
 runtime.ai.registerProvider(new MockProvider({

package/docs/README.md

@@ -13,8 +13,15 @@ with the `ai-runtime-engine` package:
   permissions, credentials, and the learning safety rail.
 
 Additional development records — the append-only decision log (`DECISIONS.md`), the phase-by-phase build
-log (`PROGRESS.md`), and the release checklist (`NPM_PUBLISHING.md`) — live in the (private) source
-repository and are not part of the published package.
+log (`PROGRESS.md`), the release checklist (`NPM_PUBLISHING.md`), and the complete project **handbook**
+(`handbook/00-index.md` and its chapters) — live in the (private) source repository and are not part of
+the published package. The handbook is the deepest reference: architecture, a file-by-file source tour,
+the CLI/REPL, the npm story, testing, and maintenance.
+
+> Note: this index file (`docs/README.md`) itself *does* end up in the npm tarball, because npm always
+> includes any `README*` file regardless of the `files` allowlist. It only links to shipped docs, so that
+> is harmless — but keep anything private out of `README*`-named files. (The handbook index is named
+> `00-index.md`, not `README.md`, for exactly this reason.)
 
 Per-subsystem detail is documented at the source: each module under `src/**` opens with a doc comment
 describing its contract and invariants, and the README's [How to use it](../README.md#how-to-use-it)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-runtime-engine",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "AI Runtime — a provider-agnostic AI runtime and orchestration platform. Point it at whatever AI providers you have; it routes each task to the best available model. Ships the `ai-runtime` CLI and the `Runtime`/`AI` library API.",
   "type": "module",
   "license": "ISC",