@oscharko-dev/keiko 0.1.0-beta.0 → 0.1.0-beta.2

package/README.md

@@ -1,621 +1,149 @@
 # Keiko
 
-Keiko is an enterprise, model-agnostic developer-assist coding agent for regulated engineering teams.
+Keiko is a local enterprise coding assistant for regulated engineering teams. It helps inspect a repository, chat with configured language models, generate reviewable unit tests, investigate bugs, run verification, and keep redacted evidence for human review.
 
-It runs bounded, reviewable coding workflows against a configurable gateway of language models, across three surfaces: a command-line tool (`keiko`), a programmatic SDK, and a local web UI. Dry-run workflows are the default, and the manifest-producing surfaces emit redacted evidence for audit. Keiko assists a developer; it does not merge code on its own.
-
-This README is the package's primary shipped guide. It contains the package-facing essentials and links to the repository [`docs/`](https://github.com/oscharko-dev/Keiko/tree/dev/docs) for deeper operational guidance.
-
----
-
-## Table of contents
-
-- [What Keiko is](#what-keiko-is)
-- [Wave 1 scope](#wave-1-scope)
-- [Requirements](#requirements)
-- [Install](#install)
-- [Quick start](#quick-start)
-- [Build and test](#build-and-test)
-- [Configuration and secrets](#configuration-and-secrets)
-- [CLI usage](#cli-usage)
-- [SDK usage](#sdk-usage)
-- [Evidence output](#evidence-output)
-- [Local UI](#local-ui)
-- [Security and audit boundaries](#security-and-audit-boundaries)
-- [Evaluation and Go/No-Go](#evaluation-and-gono-go)
-- [Packaging](#packaging)
-- [Future architecture path](#future-architecture-path)
-- [Documentation index](#documentation-index)
-- [Development](#development)
-- [License and attribution](#license-and-attribution)
-
----
-
-## What Keiko is
-
-Keiko is a coding agent for teams who must show their work. It targets regulated engineering — banking, insurance, and similar — where every automated change needs a human reviewer and an audit trail.
-
-Three properties define it:
-
-- **Model-agnostic.** Route each task to a model that fits the work and the budget, from one config file. The gateway exposes each model's declared capabilities; the caller chooses.
-- **Bounded and reviewable.** Workflows run as deterministic pipelines, not open-ended autonomy. Changes are dry-run by default and returned as a diff for human review. No change reaches a branch without a person.
-- **Auditable.** Manifest-producing surfaces emit structured, redacted evidence. Credentials never enter logs, events, or evidence.
-
-Keiko provides bounded developer assistance with measurable output and regulated reviewability. It is not a replacement for engineering judgment, and it does not claim parity with general-purpose autonomous agents.
-
----
-
-## Wave 1 scope
-
-Wave 1 is feature-complete for its defined scope. The shipped capabilities are:
-
-- **Bounded repository context** — a redacted, byte-budgeted view of a workspace.
-- **Unit-test generation** — generate a reviewable test patch for an existing source file.
-- **Bug investigation** — propose a fix and a regression test for a reported symptom.
-- **Safe tool and command execution** — an allowlisted, bounded command runner.
-- **Verification** — run the project's gates (lint, typecheck, test, build) under resource limits.
-- **Audit evidence** — redacted, durable evidence manifests with retention.
-- **Local UI** — a single-user, local-only web surface for the workflows and evidence.
-- **Evaluation harness** — an offline (default) or live scorecard for pilot decisions.
-
-Surface coverage is intentionally not identical. The CLI exposes the full command set; the SDK exposes programmatic workflows, workspace, verification, gateway, evaluation, and evidence APIs; the local UI exposes workflow launch/review/apply, live run observation, evidence browsing, config/model inspection, and workspace summary.
-
-Two model kinds in the portfolio are registered but not yet callable: OCR-vision (`callOcr`) and embedding (`callEmbedding`) methods are Wave 2. See the [model capability guide](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pilot/model-capability-guide.md).
-
----
+Keiko is developer-controlled by design. It does not commit, push, open pull requests, merge code, or apply changes without an explicit local action. The manifest-producing surfaces emit redacted evidence for audit.
 
 ## Requirements
 
-- Node.js >= 22 (ESM-only package)
-- npm >= 10
+- Node.js 22 or newer.
+- npm 10 or newer.
+- A model gateway with an OpenAI-compatible chat-completions API and an API token for model-backed work.
 
----
+## Install and Start
 
-## Install
+Install Keiko in the project where you want to use it:
 
 ```bash
 npm install @oscharko-dev/keiko
+npx keiko init
+npm run keiko:start
 ```
 
-Keiko ships ESM only with a minimal runtime dependency set. Use `import`, not `require`.
-
----
-
-## Quick start
+Open the local UI:
 
-A dry-run pass that writes nothing: inspect context, generate a test patch, review the diff.
-
-```bash
-# 1. List the models your gateway knows about (no credentials needed)
-keiko models list
-
-# 2. Print a redacted summary of what the workspace layer would read
-keiko context --dir .
-
-# 3. Generate a unit-test patch for a source file (dry-run by default)
-keiko gen-tests --file src/foo.ts
+```text
+http://127.0.0.1:1983
 ```
 
-Step 3 prints the proposed diff and writes nothing. Review it, then re-run with `--apply` to write the test file, which triggers verification.
-
----
-
-## Build and test
-
-From a clone of the repository:
+Stop Keiko when you are done:
 
 ```bash
-npm install
-npm run build       # compile TypeScript to dist/
-npm test            # run the test suite (vitest)
-npm run lint        # eslint
-npm run typecheck   # tsc --noEmit
-npm run format      # prettier --write
-npm --prefix ui ci --ignore-scripts  # install UI build tooling when packaging or testing the UI
-```
-
----
-
-## Configuration and secrets
-
-Keiko reads model credentials from **environment variables** or a **JSON config file** — never from CLI flags. This keeps credentials out of shell history and process listings.
-
-### Precedence
-
-The first match wins:
-
-1. Per-model environment variables: `KEIKO_MODEL_<UPPER_MODEL_ID>_API_KEY` / `_BASE_URL`
-2. Config-file value for that model's `apiKey` / `baseUrl`
-3. Global environment variables: `KEIKO_DEFAULT_API_KEY` / `_BASE_URL`
-
-Live model CLI surfaces (`keiko models validate`, `keiko gen-tests`, `keiko investigate`, and `keiko evaluate --live`) read a config only from `--config PATH` or `KEIKO_CONFIG_FILE`. `keiko ui` requires `--config PATH` for model-backed runs. Keiko does not implicitly trust `./keiko.config.json` from the target repository.
-
-Provider `baseUrl` values must use `https:` unless they target `localhost` or loopback for local development.
-
-### Per-model variables
-
-Derive the variable name from the model id: uppercase it, then replace every non-alphanumeric character with `_`. Suffix with `_API_KEY` or `_BASE_URL`.
-
-```
-gpt-oss-120b  →  KEIKO_MODEL_GPT_OSS_120B_API_KEY
-                 KEIKO_MODEL_GPT_OSS_120B_BASE_URL
+npm run keiko:stop
 ```
 
-### Global fallback
+`npx keiko init` adds these local scripts to `package.json`:
 
-Used when neither a per-model environment variable nor a config-file value supplies the secret:
+| Script                | Purpose                                        |
+| --------------------- | ---------------------------------------------- |
+| `npm run keiko:start` | Starts the local Keiko UI on the default port. |
+| `npm run keiko:stop`  | Stops the local Keiko UI process.              |
 
-```
-KEIKO_DEFAULT_API_KEY
-KEIKO_DEFAULT_BASE_URL
-```
+## First-Run Setup
 
-Credentials are held in memory for the duration of a call and are never logged or serialized. See [`.env.example`](https://github.com/oscharko-dev/Keiko/blob/dev/.env.example) for a template and [ADR-0003](https://github.com/oscharko-dev/Keiko/blob/dev/docs/adr/README.md#adr-0003) for the rationale.
+If no model gateway is configured, the UI asks for:
 
----
+- Base URL, for example `https://llm-gateway.example.com/v1`
+- API token
 
-## CLI usage
+Keiko calls the gateway model list endpoint, tests discovered chat models with a small chat-completions request, and stores only callable chat models in the local runtime configuration. Credentials stay on the local machine and are not returned to the browser.
 
-The CLI provides nine subcommands (`models`, `run`, `context`, `verify`, `gen-tests`, `investigate`, `evidence`, `evaluate`, `ui`); `models` and `evidence` each take a sub-action. Top-level `keiko --help` and `keiko --version` print usage; `keiko evaluate --help` prints its own usage. Global options:
+The UI runs on loopback only. The `--host` option can validate a loopback host value; the server always binds `127.0.0.1`.
 
-| Option            | Effect               |
-| ----------------- | -------------------- |
-| `-h`, `--help`    | Show help text       |
-| `-v`, `--version` | Show the CLI version |
+## Daily Use
 
-Exit codes are consistent across commands unless noted:
+1. Add a local project path.
+2. Select one of the configured chat models.
+3. Use chat or a workflow: Generate Tests, Investigate Bug, Explain Plan, or Verify.
+4. Review proposed diffs and evidence before applying any change.
+5. Keep generated evidence with the project review material when required by your delivery process.
 
-| Code | Meaning       |
-| ---- | ------------- |
-| `0`  | success       |
-| `1`  | runtime error |
-| `2`  | usage error   |
+Surface coverage is intentionally not identical. The UI is the primary surface for day-to-day use; the CLI remains available for focused inspection, verification, and automation.
 
-### `keiko models list`
+## CLI Essentials
 
-List all registered model capabilities as a table. No credentials required.
-
-```bash
-keiko models list
-```
-
-Takes no options. Prints one row per model: id, kind, cost class, latency class, tool-calling, structured-output, and use cases.
-
-### `keiko models validate`
-
-Validate the gateway configuration from `--config` or `KEIKO_CONFIG_FILE`. Reports structural errors without printing any configured value. Exit `0` when valid, `1` when invalid or no source is given, `2` when `--config` has no path.
-
-```bash
-keiko models validate --config ./keiko.config.json
-```
-
-| Option          | Description                                  |
-| --------------- | -------------------------------------------- |
-| `--config PATH` | Gateway config file (or `KEIKO_CONFIG_FILE`) |
-
-### `keiko run`
-
-Run a bounded, dry-run task through the agent harness against deterministic fixtures (no provider call). The task type selects the harness pipeline. A redacted evidence manifest is written by default.
-
-```bash
-keiko run explain-plan --file src/auth.ts --question "what does this do?"
-keiko run generate-unit-tests --file src/add.ts --function add
-keiko run investigate-bug --description "login 500 on empty password"
-```
-
-| Option                | Description                                                               |
-| --------------------- | ------------------------------------------------------------------------- |
-| `<task-type>`         | `explain-plan`, `generate-unit-tests`, or `investigate-bug`               |
-| `--file PATH`         | Target file (required for the first two task types)                       |
-| `--question TEXT`     | Question for `explain-plan`                                               |
-| `--function NAME`     | Focus function for `generate-unit-tests`                                  |
-| `--description TEXT`  | Bug description (required for `investigate-bug`)                          |
-| `--no-evidence`       | Do not write an evidence manifest                                         |
-| `--evidence-dir PATH` | Evidence directory (or `KEIKO_EVIDENCE_DIR`; default `./.keiko/evidence`) |
-| `--include-reasoning` | Include redacted reasoning entries in the manifest                        |
-| `--include-diff`      | Include the redacted proposed diff in the manifest                        |
-
-For real model-backed generation and investigation, use `keiko gen-tests` and `keiko investigate`.
-
-### `keiko context`
-
-Print a redacted workspace context summary. Dry-run by construction: no model is called and nothing is written.
-
-```bash
-keiko context --dir .
-keiko context --dir . --task "add tests" --budget 65536
-```
-
-| Option           | Description                                 |
-| ---------------- | ------------------------------------------- |
-| `--dir PATH`     | Workspace root (default: cwd)               |
-| `--task TEXT`    | Build a context pack scoped to this task    |
-| `--budget BYTES` | Context-pack byte budget (positive integer) |
-| `--json`         | Emit the summary as JSON                    |
-
-### `keiko verify`
-
-Run the project's gates through the safe tool layer under per-command resource limits, and print a redacted summary. Exit `0` when every gate passes, `1` when a gate fails or a workspace error occurs.
-
-```bash
-keiko verify --dir .
-keiko verify --only typecheck,lint --changed src/a.ts
-```
-
-| Option                  | Description                                                                 |
-| ----------------------- | --------------------------------------------------------------------------- |
-| `--dir PATH`            | Workspace root (default: cwd)                                               |
-| `--only KIND[,KIND]`    | Run only these gates: `test`, `targeted-test`, `typecheck`, `lint`, `build` |
-| `--changed FILE[,FILE]` | Restrict targeted tests to these changed files                              |
-| `--json`                | Emit the verification report as JSON                                        |
-
-### `keiko gen-tests`
-
-Generate a reviewable unit-test patch. Dry-run by default; `--apply` writes the tests and runs verification. The patch may only create or modify test files (a production-code guard rejects anything else). The model provider comes from config, never a flag. Exit `0` on a successful dry-run or apply, `1` on a rejected/cancelled/failed run or workspace error, `2` on a usage error.
-
-```bash
-keiko gen-tests --file src/add.ts --config ~/keiko/config.json
-keiko gen-tests --file src/add.ts --function add --apply
-keiko gen-tests --dir src/math --changed src/math/sum.ts
-```
-
-| Option                  | Description                                                                 |
-| ----------------------- | --------------------------------------------------------------------------- |
-| `--file PATH`           | Source file to test (exactly one of `--file` / `--dir`)                     |
-| `--dir PATH`            | Module directory to test (exactly one of `--file` / `--dir`)                |
-| `--function NAME`       | Focus on one function (with `--file`)                                       |
-| `--changed FILE[,FILE]` | Authoritative changed-file target set                                       |
-| `--apply`               | Write the patch and run verification (default: dry-run)                     |
-| `--model ID`            | Registered configured model id (default: cheapest capable configured model) |
-| `--config PATH`         | Gateway config file (or `KEIKO_CONFIG_FILE`)                                |
-| `--json`                | Emit the workflow report as JSON                                            |
-| `--dir-root PATH`       | Workspace root (default: cwd)                                               |
-
-### `keiko investigate`
-
-Investigate a bounded bug report, then propose a minimal fix and a regression test, separating verified facts from the model's unverified hypothesis. Dry-run by default; `--apply` writes the fix and runs verification. A scope guard rejects edits to sensitive paths (version-control internals, CI config, git hooks, lockfiles). At least one evidence source is required. Exit `0` on `fix-applied`/`fix-proposed`/`investigation-only`, `1` on a rejected/cancelled/failed run or read error, `2` on a usage error.
-
-```bash
-keiko investigate --description "login returns 500 on empty password" --config ~/keiko/config.json
-keiko investigate --output-file ./fail.txt --file src/auth.ts --apply
-```
+| Command                       | Purpose                                                          |
+| ----------------------------- | ---------------------------------------------------------------- |
+| `keiko init`                  | Adds local start and stop scripts.                               |
+| `keiko start`                 | Starts the local UI in the background.                           |
+| `keiko stop`                  | Stops the local UI.                                              |
+| `keiko status`                | Prints the local UI status.                                      |
+| `keiko ui`                    | Runs the UI in the foreground. Port to bind (default: 1983).     |
+| `keiko models validate`       | Validates gateway configuration.                                 |
+| `keiko context`               | Prints a redacted workspace context summary.                     |
+| `keiko gen-tests`             | Generates a reviewable unit-test patch.                          |
+| `keiko investigate`           | Investigates a bug and proposes a fix plus regression test.      |
+| `keiko verify`                | Runs configured verification gates and writes redacted evidence. |
+| `keiko evidence list`         | Lists local evidence manifests.                                  |
+| `keiko evidence show <runId>` | Shows one redacted evidence manifest.                            |
 
-| Option               | Description                                                                 |
-| -------------------- | --------------------------------------------------------------------------- |
-| `--description TEXT` | Free-text bug description                                                   |
-| `--output TEXT`      | Failing command/test output (inline)                                        |
-| `--output-file PATH` | Failing output read from a file                                             |
-| `--stack TEXT`       | Stack trace (inline)                                                        |
-| `--stack-file PATH`  | Stack trace read from a file                                                |
-| `--file PATH[,PATH]` | Suspected target file(s)                                                    |
-| `--apply`            | Apply the fix and run verification (default: dry-run)                       |
-| `--model ID`         | Registered configured model id (default: cheapest capable configured model) |
-| `--config PATH`      | Gateway config file (or `KEIKO_CONFIG_FILE`)                                |
-| `--json`             | Emit the investigation report as JSON                                       |
-| `--dir-root PATH`    | Workspace root (default: cwd)                                               |
+`keiko gen-tests` and `keiko investigate` print a reviewable report but do not persist an evidence manifest. Use `keiko run`, `keiko verify`, or the UI evidence view when a stored manifest is required.
 
-### `keiko evidence`
+## Configuration
 
-Inspect redacted evidence manifests written by `keiko run`, the local UI, and `keiko evaluate`. Reads only the evidence base directory. Exit `0` on success, `1` on a run id not found in the store or a read error, `2` on a usage error (including `show` with no run id).
+The UI can create a local runtime config during first-run setup. For scripted use, provide a JSON config file through `KEIKO_CONFIG_FILE` or `--config`:
 
-```bash
-keiko evidence list
-keiko evidence show <runId>
-```
-
-| Option                | Description                                                               |
-| --------------------- | ------------------------------------------------------------------------- |
-| `list`                | List stored manifests                                                     |
-| `show <runId>`        | Show one manifest by run id                                               |
-| `--evidence-dir PATH` | Evidence directory (or `KEIKO_EVIDENCE_DIR`; default `./.keiko/evidence`) |
-| `--json`              | Emit as JSON                                                              |
-
-### `keiko evaluate`
-
-Run the evaluation harness against the built-in fixtures. Offline (deterministic, no network) by default; `--live` evaluates against a configured model and fails closed when no credentials resolve. Exit `0` when every applicable dimension and surface-parity pass, `1` on a failure or runtime error, `2` on a usage error.
-
-```bash
-keiko evaluate
-keiko evaluate --suite unit-tests --json
-keiko evaluate --live --model gpt-oss-120b --config ~/keiko/config.json
-```
-
-| Option           | Description                                                 |
-| ---------------- | ----------------------------------------------------------- |
-| `--suite NAME`   | `unit-tests`, `bug-investigation`, or `all` (default `all`) |
-| `--fixture NAME` | Run one fixture by name (mutually exclusive with `--suite`) |
-| `--live`         | Evaluate against a configured model (default: offline)      |
-| `--model ID`     | Override the model id for all fixtures (live mode)          |
-| `--config PATH`  | Gateway config file (or `KEIKO_CONFIG_FILE`)                |
-| `--json`         | Emit the scorecard as JSON                                  |
-| `--output PATH`  | Write the scorecard JSON to a file                          |
-
-The offline suite checks workflow plumbing deterministically. It does not measure model quality. See [Evaluation and Go/No-Go](#evaluation-and-gono-go).
-
-### `keiko ui`
-
-Launch the local UI. The server binds to `127.0.0.1` (loopback only), prints its URL, and runs until interrupted (Ctrl+C). It serves prebuilt UI assets. The published npm package ships these assets, so `keiko ui` works immediately after install; from a source checkout, run `npm run build && npm run ui:ci && npm run build:ui` first.
-
-```bash
-keiko ui
-keiko ui --port 4319
-```
-
-| Option                | Description                                                         |
-| --------------------- | ------------------------------------------------------------------- |
-| `--port PORT`         | Port to bind (default: 4319)                                        |
-| `--host HOST`         | Validate a loopback host value; the server always binds `127.0.0.1` |
-| `--evidence-dir PATH` | Evidence directory for UI-run evidence                              |
-| `--config PATH`       | Gateway config file required for model-backed UI runs               |
-
-See [Local UI](#local-ui) and the [local UI runbook](https://github.com/oscharko-dev/Keiko/blob/dev/docs/ui-runbook.md).
-
----
-
-## SDK usage
-
-Keiko ships ESM-only with full type definitions. The package entry point re-exports the public surface; import named values from `keiko`.
-
-`detectWorkspace` and `loadConfigFromFile` are synchronous and take a path string. The workflow functions take a `workspaceRoot` path (not a workspace object) plus a `deps` object carrying the model port.
-
-### Workspace summary
-
-```typescript
-import { detectWorkspace, buildWorkspaceSummary } from "@oscharko-dev/keiko";
-
-const workspace = detectWorkspace(process.cwd());
-const summary = buildWorkspaceSummary(workspace);
-console.log(summary.name, summary.counts);
-```
-
-### Generate unit tests
-
-```typescript
-import {
-  generateUnitTests,
-  renderUnitTestReport,
-  Gateway,
-  GatewayModelPort,
-  loadConfigFromFile,
-} from "@oscharko-dev/keiko";
-
-const config = loadConfigFromFile("./keiko.config.json", process.env);
-const model = new GatewayModelPort(new Gateway(config));
-
-const report = await generateUnitTests(
-  {
-    workspaceRoot: ".",
-    target: { kind: "file", filePath: "src/add.ts" },
-    modelId: config.providers[0].modelId,
-    // apply defaults to false: a reviewable diff, no files written
-  },
-  { model },
-);
-
-console.log(report.status, report.proposedDiff);
-console.log(renderUnitTestReport(report));
-```
-
-### Investigate a bug
-
-```typescript
-import {
-  investigateBug,
-  renderBugInvestigationReport,
-  Gateway,
-  GatewayModelPort,
-  loadConfigFromFile,
-} from "@oscharko-dev/keiko";
-
-const config = loadConfigFromFile("./keiko.config.json", process.env);
-const model = new GatewayModelPort(new Gateway(config));
-
-const report = await investigateBug(
-  {
-    workspaceRoot: ".",
-    report: { description: "login returns 500 on empty password" },
-    modelId: config.providers[0].modelId,
-    // apply defaults to false (dry-run)
-  },
-  { model },
-);
-
-// The report separates established facts from the model's unverified hypothesis.
-console.log(report.verified, report.hypothesis);
-console.log(renderBugInvestigationReport(report));
-```
-
-### Run verification
-
-`runVerification` takes a plan. Build it from the detected workspace and its script catalog.
-
-```typescript
-import {
-  detectWorkspace,
-  detectScripts,
-  buildVerificationPlan,
-  runVerification,
-  buildVerificationSummary,
-} from "@oscharko-dev/keiko";
-
-const workspace = detectWorkspace(process.cwd());
-const catalog = detectScripts(workspace);
-const plan = buildVerificationPlan(workspace, catalog, {});
-
-const report = await runVerification(plan, { workspace });
-console.log(buildVerificationSummary(report));
-console.log(report.overallStatus); // "passed" when every gate passed
-```
-
-### Inspect evidence
-
-`listEvidence` and `loadEvidence` are synchronous. The loaded data is redacted by construction.
-
-```typescript
-import { createNodeEvidenceStore, listEvidence, loadEvidence } from "@oscharko-dev/keiko";
-
-const store = createNodeEvidenceStore("./.keiko/evidence");
-
-for (const entry of listEvidence(store)) {
-  console.log(entry.runId, entry.taskType, entry.outcome, entry.finishedAt);
+```json
+{
+  "providers": [
+    {
+      "modelId": "example-chat-model",
+      "baseUrl": "https://llm-gateway.example.com/v1",
+      "apiKey": "replace-me"
+    }
+  ]
 }
-
-const manifest = loadEvidence(store, "the-run-id");
-if (manifest !== undefined) {
-  console.log(manifest.evidenceSchemaVersion);
-}
-```
-
-### Drive a workflow with a scripted model
-
-`createScriptedModelPort` builds a `ModelPort` that replays a fixed transcript, so you can exercise a workflow deterministically with no live model or credentials. It satisfies the same `deps.model` seam the workflows use.
-
-```typescript
-import {
-  createScriptedModelPort,
-  generateUnitTests,
-  type NormalizedResponse,
-} from "@oscharko-dev/keiko";
-
-const response: NormalizedResponse = {
-  modelId: "scripted",
-  content: "--- a/src/add.test.ts\n+++ b/src/add.test.ts\n+// generated test\n",
-  finishReason: "stop",
-  toolCalls: [],
-  structuredOutput: null,
-  usage: {
-    requestId: "scripted",
-    promptTokens: 0,
-    completionTokens: 0,
-    latencyMs: 1,
-    costClass: "low",
-  },
-};
-
-const model = createScriptedModelPort([response]);
-
-const report = await generateUnitTests(
-  { workspaceRoot: ".", target: { kind: "file", filePath: "src/add.ts" }, modelId: "scripted" },
-  { model },
-);
-console.log(report.status);
-```
-
-For the full offline scorecard, run `keiko evaluate` (see [Evaluation and Go/No-Go](#evaluation-and-gono-go)).
-
-`SDK_VERSION` is exported for diagnostics. `--version` on the CLI reports the same value.
-
----
-
-## Evidence output
-
-`keiko run`, workflow runs launched from the local UI, and `keiko evaluate` (offline and live) persist an `EvidenceManifest`. `keiko gen-tests` and `keiko investigate` print a reviewable report but do not persist an evidence manifest; `keiko verify` and `keiko context` are read-only summaries that persist nothing. Manifests are **redacted at construction** — secret-shaped strings, environment values, and known literal credentials are removed before anything is written. There is no code path that writes an unredacted manifest.
-
-Manifests are written with an exclusive-create (`O_EXCL`) open into a directory whose real path is verified to be inside the evidence root. The default location is `$KEIKO_EVIDENCE_DIR` or `.keiko/evidence` under the workspace.
-
-Retention keeps the newest runs up to a maximum (`DEFAULT_RETENTION`, 50 runs). Every manifest carries a stable `EVIDENCE_SCHEMA_VERSION`; readers reject unknown versions rather than guessing.
-
-Inspect manifests with `keiko evidence list` and `keiko evidence show <runId>`. See [ADR-0010](https://github.com/oscharko-dev/Keiko/blob/dev/docs/adr/README.md#adr-0010).
-
----
-
-## Local UI
-
-`keiko ui` serves a single-user web surface for the workflows and evidence. It binds to `127.0.0.1` by default, checks `Host` and `Origin` headers to block DNS-rebinding, serves a strict Content-Security-Policy, and renders only redacted views. The apply action uses the same gated, dry-run-default path as the CLI.
-
-The server runs until you interrupt it (Ctrl+C). For setup, surfaces, and troubleshooting, see the [local UI runbook](https://github.com/oscharko-dev/Keiko/blob/dev/docs/ui-runbook.md).
-
-Multi-user access, authentication, and remote hosting are out of scope for Wave 1.
-
----
-
-## Security and audit boundaries
-
-Keiko's boundaries are explicit, and so are their limits. In summary:
-
-- **Workspace access** is confined to the workspace root by a lexical and real-path check; secret-shaped files are always denied.
-- **Command execution** runs an allowlist with no shell interpretation, an ephemeral HOME, and resource ceilings.
-- **Patches** are dry-run by default and guarded by path scope; applying requires an explicit opt-in and is followed by verification.
-- **The UI** is local-only with DNS-rebinding defense and a strict CSP.
-- **No unattended merge.** A human reviews every change. This is a hard invariant of the pilot.
-
-Wave 1 is **not** OS-level isolation. Allowlisted project scripts (for example `npm test`) can run repository-authored code; the boundary protects the host outside the workspace, not the workspace from itself. For the full picture and the explicit limitations, read [Security and audit boundaries](https://github.com/oscharko-dev/Keiko/blob/dev/docs/security-and-audit-boundaries.md).
-
----
-
-## Evaluation and Go/No-Go
-
-`keiko evaluate` produces a scorecard, not a verdict. The Wave 1 pilot decision is made by people, using the scorecard plus run evidence.
-
-- Offline (`keiko evaluate`) checks workflow plumbing deterministically against scripted responses. It does not measure model quality.
-- Live (`keiko evaluate --live`) runs the same suite against a configured model endpoint.
-
-See [Go/No-Go criteria](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pilot/go-no-go.md) and the [model capability guide](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pilot/model-capability-guide.md).
-
----
-
-## Packaging
-
-The published tarball ships `dist/`, `README.md`, `LICENSE`, `NOTICE`, and `TRADEMARKS.md`. A surface check enforces that package boundary and rejects source, docs, source maps, and secret files. Runtime dependencies are intentionally minimal; the root package currently uses `ws` for the browser CDP transport. Supply-chain review is covered by CI dependency review, CodeQL, audit steps, and SBOM builds. Inspect the surface with:
-
-```bash
-npm pack --dry-run
 ```
 
-Publishing the package is out of scope for Wave 1. See [npm packaging](https://github.com/oscharko-dev/Keiko/blob/dev/docs/npm-packaging.md) for the exact prepack chain and surface check.
-
----
-
-## Future architecture path
+Environment variables can override file values:
 
-Wave 1 is npm-first and TypeScript-first: a CLI, an SDK, and a local UI that run on a developer machine or a CI runner with no managed control plane. This keeps the pilot's footprint small and its trust boundary local.
+| Variable                    | Purpose                        |
+| --------------------------- | ------------------------------ |
+| `KEIKO_CONFIG_FILE`         | Path to a gateway config file. |
+| `KEIKO_DEFAULT_BASE_URL`    | Fallback gateway base URL.     |
+| `KEIKO_DEFAULT_API_KEY`     | Fallback gateway API token.    |
+| `KEIKO_MODEL_<ID>_BASE_URL` | Per-model base URL override.   |
+| `KEIKO_MODEL_<ID>_API_KEY`  | Per-model API token override.  |
+| `KEIKO_UI_PORT`             | Local UI port override.        |
 
-A later phase may add a cloud-native backend for teams that want shared evaluation, central evidence, or larger workloads. If it does, the CLI and UI stay lightweight local clients; the local-first path remains supported. Multi-user access, authentication, and a hosted UI are explicitly out of scope for Wave 1.
+Do not commit gateway config files, API tokens, `.keiko/`, or evidence that contains project-specific review material unless your process explicitly requires it.
 
----
+## Security Boundaries
 
-## Documentation index
+Keiko is a local tool, not a remote service.
 
-Repository documentation (not shipped in the package):
+- The UI binds to `127.0.0.1`.
+- API keys are accepted from local config, local environment, or the first-run UI flow.
+- Credentials are redacted from logs, evidence, and browser responses.
+- Workspace reads are bounded by the selected local project path.
+- Commands are allowlisted and run without a shell.
+- Generated patches are dry-run by default and must be reviewed before application.
+- Evidence is redacted before it is written.
 
-| Document                                                                                                              | Audience                            |
-| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| [Customer pilot runbook](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pilot/runbook.md)                        | Pilot teams, evaluators, reviewers  |
-| [Go/No-Go criteria](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pilot/go-no-go.md)                            | Pilot sponsors, leads, review board |
-| [Model capability guide](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pilot/model-capability-guide.md)         | Pilot evaluators, operators         |
-| [Security and audit boundaries](https://github.com/oscharko-dev/Keiko/blob/dev/docs/security-and-audit-boundaries.md) | Security and regulated reviewers    |
-| [Local UI runbook](https://github.com/oscharko-dev/Keiko/blob/dev/docs/ui-runbook.md)                                 | UI operators and reviewers          |
-| [npm packaging](https://github.com/oscharko-dev/Keiko/blob/dev/docs/npm-packaging.md)                                 | Release engineers                   |
+Known limits:
 
-Architecture Decision Records live in [`docs/adr/`](https://github.com/oscharko-dev/Keiko/tree/dev/docs/adr).
-
----
-
-## Development
-
-```bash
-npm install
-npm run build
-npm test
-npm run lint
-npm run typecheck
-npm run format
-```
+- Keiko is not a sandbox or OS-level isolation layer.
+- Evidence files are ordinary local files, not encrypted or tamper-evident records.
+- Local project scripts can execute repository code when you run verification.
+- Do not run Keiko against untrusted repositories.
 
-Contributions follow the delivery standard in [`CONTRIBUTING.md`](CONTRIBUTING.md): strict TypeScript, tested behavior, conventional commits with an issue number, and reviewable, evidence-backed changes.
+## Troubleshooting
 
----
+| Symptom               | Check                                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------------------- |
+| UI does not open      | Run `npm run keiko:status`, then inspect `.keiko/ui.log`.                                               |
+| Port is busy          | Start with `KEIKO_UI_PORT=1984 npm run keiko:start` or stop the process using the port.                 |
+| No model appears      | Reopen Settings, verify the base URL and token, then run the credential test again.                     |
+| Credential test fails | Confirm the gateway accepts OpenAI-compatible chat-completions requests at the configured base URL.     |
+| Stale process state   | Run `npm run keiko:stop`, delete `.keiko/ui.pid` if the process is no longer running, then start again. |
 
-## License and attribution
+## Further Reading
 
-Keiko is licensed under Apache-2.0. See [`LICENSE`](LICENSE).
+- [Local UI guide](https://github.com/oscharko-dev/Keiko/blob/dev/docs/ui-runbook.md)
+- [Security boundaries](https://github.com/oscharko-dev/Keiko/blob/dev/docs/security-and-audit-boundaries.md)
+- [Pilot guide](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pilot/runbook.md)
+- [Pilot evaluation](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pilot/go-no-go.md)
 
-The `NOTICE` file carries the package attribution for Keiko and oscharko-dev and
-ships with the npm package. Redistributors must preserve applicable copyright,
-license, and NOTICE attribution as required by Apache-2.0.
+## License
 
-The Keiko name, logo, visual identity, and oscharko-dev origin identifiers are
-covered by the repository's trademark and brand policy. Truthful attribution and
-compatibility references are permitted, but forks and derivative distributions
-must not imply that they are the official Keiko project or endorsed by
-oscharko-dev. See [`TRADEMARKS.md`](TRADEMARKS.md).
+Apache-2.0. See `LICENSE`, `NOTICE`, and `TRADEMARKS.md`.