kiokuko 1.0.0

package/dist/web/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../../src/web/ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE7F,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC;IACrC,aAAa,EAAE,kBAAkB;IACjC,YAAY,EAAE,iBAAiB;IAC/B,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,YAAY;CACvB,CAAC;KACC,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC;KAC1B,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC;KAC1B,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC;KAC1B,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC;KAC/B,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEnC,gFAAgF;AAChF,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtF,MAAM,KAAK,GAAG,KAAgC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC;QACrB,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY;QAClF,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,iBAAiB,EAAE,cAAc;QACrF,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY;QACpF,eAAe,EAAE,YAAY;KAC9B,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,CAAC,IAAa,EAAE,OAAe,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ;WACpF,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,OAAO,IAAI,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChH,MAAM,SAAS,GAAG,CAAC,IAAa,EAAkB,EAAE;QAClD,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC;IAC5E,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAChC,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;IAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IACxC,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IACxC,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IACpC,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IACtC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;WAClG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;WACpG,KAAK,CAAC,UAAU,KAAK,QAAQ;WAC7B,OAAO,aAAa,KAAK,QAAQ,IAAI,CAAC,2CAA2C,CAAC,IAAI,CAAC,aAAa,CAAC;WACrG,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,4BAA4B,CAAC,IAAI,CAAC,IAAI,CAAC;WACpE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC;WAC5E,KAAK,CAAC,OAAO,KAAK,UAAU,aAAa,IAAI,IAAI,EAAE;WACnD,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC;WACtB,KAAK,CAAC,UAAU,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,sBAAsB,aAAa,EAAE;WACvF,OAAO,cAAc,KAAK,QAAQ;WAClC,CAAC,CAAC,SAAS,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC;WACvG,OAAO,KAAK,CAAC,SAAS,KAAK,SAAS;WACpC,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC;WACjG,OAAO,KAAK,KAAK,QAAQ;WACzB,CAAC,CAAC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;WAC3E,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,GAAG,CAAC;WACjC,YAAY,KAAK,IAAI,IAAI,CAAC,OAAO,YAAY,KAAK,QAAQ,IAAI,CAAC,kCAAkC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;WACrH,YAAY,KAAK,IAAI,IAAI,CAAC,OAAO,YAAY,KAAK,QAAQ,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;WACpG,CAAC,YAAY,KAAK,IAAI,CAAC,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;WACnD,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;WAC5E,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC;WACrH,OAAQ,QAAoC,CAAC,SAAS,KAAK,QAAQ;WACnE,CAAC,MAAM,CAAC,aAAa,CAAE,QAAoC,CAAC,SAAS,CAAC;WACpE,QAAoC,CAAC,SAAoB,GAAG,CAAC;WAC7D,QAAoC,CAAC,SAAoB,GAAG,EAAE;WAC/D,QAAoC,CAAC,UAAU,KAAK,IAAI,IAAI,CAAC,IAAI,CAAE,QAAoC,CAAC,UAAU,EAAE,GAAG,CAAC;WACzH,OAAO,WAAW,KAAK,QAAQ;WAC/B,CAAC,CAAC,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;WAC1E,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,UAAU,GAAG,CAAC;WACvG,CAAC,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC;WAChG,UAAU,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;WAC5C,KAAK,CAAC,WAAsB,GAAI,KAAK,CAAC,UAAqB;WAC3D,KAAK,CAAC,WAAsB,GAAI,KAAK,CAAC,aAAwB;WAC/D,UAAU,KAAK,IAAI,IAAI,UAAU,GAAI,KAAK,CAAC,WAAsB;WACjE,YAAY,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,UAAU,KAAK,IAAI,CAAC;WAC1F,YAAY,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;WACtF,KAAK,KAAK,UAAU,IAAI,UAAU,KAAK,IAAI;WAC3C,KAAK,KAAK,UAAU,IAAI,UAAU,KAAK,IAAI;WAC3C,YAAY,KAAK,IAAI,IAAI,CAAE,QAAoC,CAAC,SAAS,KAAK,CAAC,IAAK,QAAoC,CAAC,UAAU,KAAK,IAAI,CAAC;WAC7I,YAAY,KAAK,IAAI,IAAI,CAAE,QAAoC,CAAC,SAAS,KAAK,CAAC,IAAI,CAAC,IAAI,CAAE,QAAoC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACpK,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,gCAAgC,CAAC,KAAc;IAC7D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtF,MAAM,KAAK,GAAG,KAAgC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjG,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI;WAC3C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;WACtD,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE;WACvI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC;WACjG,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,IAAI,KAAK;WACxG,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC;WAClF,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC;WACzF,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,UAAU,IAAI,CAAC;WACvG,OAAO,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC;AAC/E,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAqQf,eAAe;0CACQ,4BAA4B,CAAC,QAAQ,EAAE;8CACnC,gCAAgC,CAAC,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAo8BjF,CAAC"}

package/docs/README.ja.md

@@ -0,0 +1,13 @@
+# Kiokuko ドキュメント
+
+目的別に参照してください。
+
+- [導入ガイド](getting-started.ja.md) — インストール、Codex/OpenCode/Claude/Hermes設定、再起動、Web UI。
+- [基本概念](concepts.ja.md) — RAG、記憶のライフサイクル、Project/Ecosystem/Global、Akinator。
+- [Semantic retrieval](semantic-retrieval.ja.md) — embedding runtime、運用、offline、fallback。
+- [Security and trust](security-and-trust.ja.md) — secret拒否、記憶の境界、External Skills、公開エラー。
+- [CLI contract](cli-contract.md) — 安定したコマンドとレスポンス。
+
+実装者向けは[architecture](architecture.md)、[database](database.md)、[execution ledger](execution-ledger.md)、
+[client compatibility](client-compatibility.md)、[retrieval evaluation](retrieval-evaluation.md)を参照してください。
+英語目次は[こちら](README.md)です。

package/docs/README.md

@@ -0,0 +1,15 @@
+# Kiokuko documentation
+
+Choose a guide by what you need to do:
+
+- [Getting started](getting-started.md) — install, configure Codex/OpenCode/Claude/Hermes, restart clients, and use the Web UI.
+- [Concepts](concepts.md) — RAG, memory lifecycle, Project/Ecosystem/Global scopes, and Akinator.
+- [Semantic retrieval](semantic-retrieval.md) — embedding runtime setup, operation, offline mode, and fallback.
+- [Security and trust](security-and-trust.md) — secret rejection, memory boundaries, External Skills, and public errors.
+- [CLI contract](cli-contract.md) — stable command and response details.
+
+Implementation references: [architecture](architecture.md), [database](database.md),
+[execution ledger](execution-ledger.md), [client compatibility](client-compatibility.md),
+and [retrieval evaluation](retrieval-evaluation.md).
+
+The Japanese user guides are available from the [日本語目次](README.ja.md).

package/docs/agent-file.md

@@ -0,0 +1,53 @@
+# Agent file management
+
+`kiokuko setup` creates or updates Codex/OpenCode global `AGENTS.md` files and
+Claude Code's global `CLAUDE.md` with a Kiokuko global-memory block. `kiokuko
+use` optionally creates or updates the repository's `AGENTS.md` with a
+project-specific block.
+
+If setup creates a missing project binding for a registered project, it also
+adds `.kiokuko.json` to that project's root `.gitignore` when neither the plain
+nor root-anchored entry is already present. This setup-only addition participates
+in the same compare-and-swap and rollback boundary as the binding and project
+agent file.
+
+Existing bytes outside the block are preserved, including the human-authored
+header/footer, line-ending style, and file mode. Missing markers are appended;
+imbalanced, duplicated, nested, or reversed markers cause a validation error
+and are not repaired automatically. Symlinks are rejected.
+
+Repeated `setup` or `use` with unchanged content does not rewrite its target
+files. `setup --dry-run` validates all target content without creating the
+database, config, or instruction files.
+
+When `kiokuko use --agent-file` changes an existing repository binding, the
+new target is installed and only the exact marked block is removed from the
+old target. Human bytes and file mode outside that block are preserved; a file
+is deleted only when the managed block was its entire content. Malformed
+markers, symlinks, concurrent file changes, or a later database-registration
+failure abort the transition and conditionally restore every Kiokuko-owned
+file mutation. Cleanup and restoration failures are reported rather than
+ignored.
+
+The generated instructions describe the high-level `task_prepare`,
+`task_answer`, Curator, and `memory_checkpoint` MCP lifecycle. The first two are
+the only model-facing task-memory entry points. Human/operator CLI and Web
+inspection remain management-only and are not a fallback for a client that
+cannot satisfy the task capability gate.
+
+The instructions require one new bounded opaque `requestId` per logical user
+request and permit reusing it only for an exact transport retry. Identical task
+text in a later request still gets a new ID. Reusing an ID with changed bound
+input conflicts, and `client.sessionId` is not accepted as a substitute.
+The normalized context budget is also bound at preparation and must be repeated
+unchanged by `task_answer`.
+
+Default setup installs the exact local `memory-reasoning` Skill, but installation
+is not proof that a model loaded or followed it. For actionable build/debug
+memory, generated instructions treat catalog
+availability as only the gate, not proof of compliance. The client must read the
+available local `memory-reasoning` Skill before modifying code and convert
+recalled claims that affect the task into verified premises, falsifiable
+invariants, concrete counterexamples, and regression tests. Missing or unknown
+availability is explicit in `memoryPolicy.contextWithheld` and
+`memoryPolicy.withheldReason`; `nextAction` remains `proceed`.

package/docs/agent-gateway.md

@@ -0,0 +1,102 @@
+# Agent Event Gateway HTTP/JSON v1
+
+Kiokuko exposes a client-neutral local control-plane API. Coding agents send run lifecycle and normalized events to Kiokuko; Kiokuko commits sanitized records to SQLite and returns bounded, untrusted memory context plus deterministic recommendations.
+
+The v1 gateway is **not** an OpenAI/Anthropic provider reverse proxy. It never requires provider credentials and does not claim to observe events that a client cannot report.
+
+## Runtime and discovery
+
+Start the foreground service with:
+
+```bash
+kiokuko serve [--host 127.0.0.1] [--port 0] [--json]
+kiokuko server status --json
+```
+
+`kiokuko web` is the compatibility entry point for the same server composition. The service accepts loopback hosts only. On startup it creates a same-user runtime descriptor containing protocol version, PID, base URL, database fingerprint, instance ID, start time, and a random capability token. The descriptor is mode `0600`; the token must not appear in stdout, argv, `AGENTS.md`, events, logs, or error responses.
+
+All `/api/v1/*` endpoints require `Authorization: Bearer <capability-token>`. `GET /health/live` exposes only liveness; `GET /health/ready` is authenticated. CORS is not permissive.
+
+## Write protocol
+
+Every write requires:
+
+- `Content-Type: application/json`
+- `apiVersion: "1"`
+- `Idempotency-Key: <opaque non-empty key>`
+- strict unknown-field rejection
+- request body at most 2 MiB
+
+A key is scoped to the operation/run. Replaying the same key with the same canonical request returns the stored atomic mutation acknowledgement and does not repeat the mutation. Reusing it with different content returns `409 CONFLICT`. For operations that add capability-gated context, gating and retrieval happen after that mutation boundary and are re-evaluated against the current retrievable revisions and feedback. The full enriched JSON may therefore change on an exact retry even though the acknowledged mutation does not. Freezing the earlier enriched context would bypass current retrieval eligibility. Event batches are all-or-nothing and contain at most 200 events; one sanitized payload is at most 64 KiB.
+
+Success envelope:
+
+```json
+{"apiVersion":"1","ok":true,"operation":"agent.checkpoint","data":{},"meta":{}}
+```
+
+Failure envelope:
+
+```json
+{"apiVersion":"1","ok":false,"operation":"agent.checkpoint","error":{"code":"VALIDATION_ERROR","message":"...","details":{}}}
+```
+
+The server never includes an auth token, matched secret, raw request, hidden reasoning, or internal stack in an error. Queue saturation returns `429` with `Retry-After`; unavailable storage returns `503`; validation returns `400`; authentication returns `401`; not found returns `404`; idempotency/source-ID conflict returns `409`.
+
+## Lifecycle endpoints
+
+### Open
+
+`POST /api/v1/agent/runs`
+
+Creates a ledger run, an Akinator intake session, and their one-to-one `run_intakes` link in one application transaction. Workspace is fixed here and is immutable for the rest of the run. Client-supplied coverage is stored exactly; Kiokuko does not upgrade it.
+
+If intake needs an answer, the run remains `intake`, the response includes only the current question and no memory context. A client must present that question to the user without inventing an answer. A finalized `ready` or bounded `exhausted` intake moves the run to `active` and permits initial context delivery.
+
+### Answer intake
+
+`POST /api/v1/agent/runs/:runId/intake/answers`
+
+Accepts only the currently outstanding question ID. The answer, intake transition, lifecycle event, and run status transition are atomic. Exact retry replays that mutation acknowledgement without repeating the answer; any post-commit capability gate and context retrieval are evaluated again under the bound catalog and current retrieval eligibility. A finalized profile is immutable; later task-understanding changes are appended as `task_profile.revised` events.
+
+### Append events
+
+`POST /api/v1/agent/runs/:runId/events`
+
+The server preserves source event IDs/sequences and assigns a contiguous local sequence. The canonical event type and optional client `sourceType` are both stored. Non-intake events are rejected while the run is `intake`. Terminal runs reject new events except exact idempotent replay.
+
+### Checkpoint
+
+`POST /api/v1/agent/runs/:runId/checkpoints`
+
+Atomically appends the included events, then projects state through the committed cursor. The response includes the authoritative finalized intake status (`ready` or `exhausted`). The request must include the exact complete `capabilities` catalog bound when the run opened; the server validates that binding before mutation and removes the catalog before strict checkpoint parsing. Retrieval happens after the write transaction and outside the bounded write queue. The broker ranks once, evaluates the capability gate against that fixed snapshot, and persists only that same snapshot after approval; it never previews and then re-queries. Inside the delivery transaction, every selected exact revision is revalidated as current and retrievable, including the active managed-external mapping and source identity. A concurrent revision, disable, stale, or refresh transition returns a conflict with no delivery instead of silently reranking. Every request requires the exact local `kiokuko-soul` Skill in the bound catalog; missing or unknown availability returns `nextAction: required_capability_unavailable`, `context: null`, and no persisted delivery, including while intake still needs an answer. Actionable ordinary build/debug memory from `ready` intake is returned only when the bound catalog also contains the local `memory-reasoning` Skill. Missing or unknown `memory-reasoning` alone sets `memoryPolicy.contextWithheld: true`, reports `memory_reasoning_missing` or `memory_reasoning_unknown` in `memoryPolicy.withheldReason`, and withholds that ordinary memory while leaving `nextAction: proceed`; the ready-only memory policy does not apply to bounded `exhausted` intake. After this gate, the response may contain one persisted v1 advisory nudge selected from the final recommendations; the nudge is never selected or persisted before capability gating.
+
+### Close, feedback, promotion
+
+- `POST /api/v1/agent/runs/:runId/close`
+- `POST /api/v1/agent/runs/:runId/feedback`
+- `POST /api/v1/agent/runs/:runId/promotions`
+
+Close records a terminal status, final events/evidence, unresolved items, outcome, and explicit memory proposals. Feedback records context, recommendation, intake-question/profile, and run outcomes without automatically changing entry trust/status or the active intake policy. Promotion creates only an existing-memory `candidate` entry and records run/event/delivery/intake provenance; it never auto-promotes to `verified`.
+
+The former unbound `POST /api/v1/context/query` route was removed. A request without a run cannot prove which capability catalog governs the returned memory, so the server does not provide an ungated compatibility fallback.
+
+## Read protocol
+
+Cursor-paginated read endpoints are:
+
+- `GET /api/v1/agent/runs?workspace=&client=&status=&cursor=&limit=`
+- `GET /api/v1/agent/runs/:runId`
+- `GET /api/v1/agent/runs/:runId/intake`
+- `GET /api/v1/agent/runs/:runId/events?after=&limit=&type=`
+
+List pages are capped at 100 records. Event content returned to agents is marked
+`untrusted: true` and must be checked against the current repository/runtime.
+Workspace and memory inspection belongs to the human/operator CLI and Web
+management surfaces; the Agent API does not expose ungated read aliases.
+
+The former context-delivery listing route was removed because a GET request has no complete capability-catalog channel. Context deliveries are returned only by the capability-gated open, answer, and checkpoint operations that create them.
+
+## Coverage
+
+Each category is one of `complete`, `best_effort`, `declared`, or `unavailable`. `complete` is reserved for a versioned bridge with a clean-room contract test. Generic CLI runs normally use `declared` or `unavailable`. UI and recommendations must display incomplete coverage rather than call the ledger a complete transcript.

package/docs/architecture.md

@@ -0,0 +1,12 @@
+# Embedding architecture
+
+Semantic retrieval is an optional lane beside lexical, exact-signal, tag, and
+trust-aware retrieval. The local provider reads a verified model directory and
+never sends memory or query text to Hugging Face. SQLite stores settings,
+profile identity, installation metadata, jobs, and rebuildable vector rows.
+
+Setup downloads allowlisted files into private staging, verifies size and
+SHA-256, runs an offline probe, and atomically installs the revision. Database
+activation and model I/O are separate phases. A profile identity includes the
+model revision, artifact manifest, runtime version, dtype, pooling,
+normalization, token limit, dimensions, and E5 input contract.

package/docs/breaking-changes-1.0.md

@@ -0,0 +1,64 @@
+# Kiokuko 1.0 breaking changes
+
+Kiokuko 1.0 removes enno-oduno, zenki, and goki. There is no replacement
+orchestrator. Akinator intake, memory, Skill discovery, Curator, and the normal
+CLI, MCP, and Web interfaces remain available.
+
+## Database
+
+Older databases cannot be upgraded or opened by 1.0. They are rejected without
+conversion or deletion. Keep the old database and choose a new absolute directory:
+
+```sh
+export KIOKUKO_DATA_DIR="/absolute/path/to/kiokuko-1"
+kiokuko init
+kiokuko setup --clients codex
+kiokuko doctor --json
+```
+
+Choose a new unused directory. Configure the same `KIOKUKO_DATA_DIR` in the
+client process environment or MCP server environment; a terminal export alone
+does not configure an already-running desktop client. Keep the old database
+with its WAL/SHM files together and use the previous binary to inspect it.
+There is no automatic import, reset, downgrade, or cross-major data conversion.
+
+The baseline no longer contains `context_deliveries.external_sync_summary_json`.
+Databases initialized from an earlier baseline, including the initially published
+1.0.0 baseline, fail checksum validation and require a new data directory.
+
+Structured memory scope accepts only `schemaVersion: 3`. The removed v2 shape
+is rejected on writes and stored-memory reads; search rebuild does not convert
+it. Unversioned scope remains arbitrary user JSON and does not authorize
+structured filtering or cross-project retrieval.
+
+## Removed interfaces
+
+- `kiokuko enno` and setup's `--enno-oduno` option.
+- Every `enno_*` MCP tool and the `ennoOduno` task/setup response property.
+- Controller ledger events, continuation tokens, execution leases, and advice.
+- Init/setup `backupPath`, `databaseBackupPath`, and `recoveredEntries` response fields,
+  Embedding setup's no-op `migration` result, and doctor
+  reports specific to controller leases and historical context conversion.
+
+The JSON envelope remains `apiVersion: "1"`. Its operation payloads follow the
+new package major. Removed commands and tools fail as unsupported operations.
+
+## Remove previously installed automation
+
+Stop affected clients before editing their configuration. Remove only these
+old Kiokuko entries, preserving other hooks and user content:
+
+- Codex: the Stop-hook handler whose command contains
+  `kiokuko enno hook --client codex` in `$CODEX_HOME/hooks.json`, or
+  `~/.codex/hooks.json` when `CODEX_HOME` is unset.
+- Claude Code: the Stop-hook handler containing
+  `kiokuko enno hook --client claude` in the Claude config directory's
+  `settings.json`. Also remove an old Kiokuko `UserPromptSubmit` handler if present.
+- OpenCode: `plugins/kiokuko-enno-oduno.js` and, if present,
+  `plugins/kiokuko-loop-guard.js` under its global config directory.
+- Each selected client's Skill directory: the old `kiokuko-enno-oduno` directory.
+
+Hook executables may be absolute paths; identify the `enno hook --client`
+arguments as well as the executable. Setup does not clean or convert these
+files. Rerun setup to update current managed instructions and supported Skills,
+then restart the clients. Review conflicts before replacing any modified file.

package/docs/cli-contract.md

@@ -0,0 +1,39 @@
+# Embedding CLI contract
+
+The default global installation is intentionally lightweight:
+
+```bash
+npm install --global @askdkc/kiokuko
+kiokuko setup
+```
+
+This keeps lexical retrieval and the normal setup flow available without the
+optional local semantic runtime. To opt into local semantic retrieval, run the
+following command. It installs the pinned optional dependencies when needed,
+then applies the same client configuration flow as `kiokuko setup`: managed
+MCP blocks are updated and registered-project instructions are refreshed.
+Unmanaged MCP identities require interactive confirmation before replacement;
+non-interactive or `--dry-run --json` runs fail closed without changing them.
+
+```bash
+kiokuko embeddings setup
+```
+
+`boolean@3.2.0` is an upstream transitive dependency of the Transformers.js
+runtime. It is not a Kiokuko dependency and is not present in the lightweight
+install. On Linux, the first automatic dependency installation uses sudo
+through npm. On macOS it installs into Kiokuko's package-local `node_modules`
+instead of the shared npm global prefix; other platforms invoke npm directly.
+Do not persist npm script permissions or use `--dangerously-allow-all-scripts`.
+
+`kiokuko embeddings setup` installs the pinned `local-small` preset without a
+separate confirmation flag. Automation uses:
+
+```bash
+kiokuko embeddings setup --preset local-small --json
+```
+
+`--dry-run` performs no download, model load, database write, or filesystem
+mutation. `--offline` uses only an existing verified installation. `--replace`
+allows switching profiles. `status --json` reports bounded coverage and model
+state; `repair` restores the same pinned artifact without destructive cleanup.

package/docs/client-compatibility.md

@@ -0,0 +1,110 @@
+# Client compatibility policy
+
+Status: global MCP integration for Codex, OpenCode, Claude Code, and profile-scoped Hermes Agent.
+
+| Client | Global MCP registration | Global instructions | Managed standard skills | Hooks/plugins |
+|---|---|---|---|---|
+| Codex | managed table in `~/.codex/config.toml` (or `$CODEX_HOME`) | managed block in global `AGENTS.md` | `~/.agents/skills/{memory-reasoning,kiokuko-soul,kiokuko-simple-work,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | none |
+| OpenCode | managed `mcp.kiokuko` property in global `opencode.json`/`opencode.jsonc` | managed block in global `AGENTS.md` | global config `skills/{memory-reasoning,kiokuko-soul,kiokuko-simple-work,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | none |
+| Claude Code | managed `mcpServers.kiokuko` property in `~/.claude.json` (or `$CLAUDE_CONFIG_DIR/.claude.json`) | managed block in global `CLAUDE.md` | Claude config `skills/{memory-reasoning,kiokuko-soul,kiokuko-simple-work,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | none |
+| Hermes Agent | managed `mcp_servers.kiokuko` in the effective profile `config.yaml` | none | effective profile `skills/{memory-reasoning,kiokuko-soul,kiokuko-simple-work,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | none |
+| Other MCP clients | manual `kiokuko mcp` stdio registration | client-specific | not installed | none |
+
+OpenCode global configuration follows XDG paths on every platform:
+`$XDG_CONFIG_HOME/opencode`, or `~/.config/opencode` when unset. On Windows,
+`~` resolves from `%USERPROFILE%`, falling back to `%HOME%`; `%APPDATA%` and
+`%LOCALAPPDATA%` are not OpenCode global configuration roots.
+
+Codex's current official documentation supports stdio MCP servers and global
+configuration. OpenCode's current official documentation supports local MCP
+commands and global rules. Claude Code supports user-scoped stdio MCP servers,
+global `CLAUDE.md`, and auto-discovered skills. `kiokuko setup` uses the MCP and
+instruction surfaces and installs the bundled `memory-reasoning`, `kiokuko-soul`, `kiokuko-simple-work`,
+`kiokuko-single-purpose-functions`, and `kiokuko-ui-design-soul` skills in the selected supported clients by
+default. The skills are copied from a fixed package manifest and never downloaded
+during setup. `--no-standard-skills`
+skips placement without deleting an existing copy.
+
+Hermes Agent v0.20.4 uses a profile-scoped native stdio MCP client. Kiokuko writes
+only the effective profile's `config.yaml` entry:
+
+```yaml
+mcp_servers:
+  # Managed by `kiokuko setup`.
+  kiokuko:
+    command: kiokuko
+    args: [mcp]
+    env:
+      KIOKUKO_SKILL_DISCOVERY: official
+```
+
+It does not create a global instruction file, Hermes plugin, or Hermes hook.
+Hermes's built-in memory and Kiokuko's bundled skills remain separate capabilities.
+Use `kiokuko setup --clients hermes`, then restart Hermes Agent or start a new
+session; `/reload-mcp` only reloads MCP registration. Smoke-test with
+`hermes mcp test kiokuko`.
+
+- [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp)
+- [Codex skills](https://developers.openai.com/codex/skills)
+- [OpenCode MCP servers](https://opencode.ai/docs/mcp-servers/)
+- [OpenCode rules](https://opencode.ai/docs/rules/)
+- [OpenCode skills](https://opencode.ai/docs/skills)
+- [Claude Code MCP servers](https://code.claude.com/docs/en/mcp)
+- [Claude Code memory and CLAUDE.md](https://code.claude.com/docs/en/memory)
+- [Claude Code skills](https://code.claude.com/docs/en/skills)
+- [Hermes skills](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/guides/work-with-skills.md)
+
+## Guarantees and non-guarantees
+
+Setup guarantees safe, repeatable configuration merging and makes the Kiokuko MCP
+tools available in each configured client scope after that client reloads its
+configuration and makes the bundled standard skills discoverable after a client
+restart or new session. Global instructions request `task_prepare` before non-trivial work, grounded
+`task_answer` calls when intake fields are missing, and checkpointing after
+substantial verified work.
+
+No supported client guarantees that a model will call an available tool for every
+prompt. Therefore “automatic” means no per-repository install and no manual CLI
+lifecycle after one-time setup; it does not mean Kiokuko intercepts every prompt
+or response. For Hermes specifically, automatic/model use is best effort from
+MCP tool descriptions.
+
+The `kiokuko-soul` standard skill is the canonical first-read router. Managed
+instruction surfaces require it before another bundled Kiokuko skill. Every
+`task_prepare` call requires `soulRead: true` as an explicit claim that the
+complete local Skill was read for that logical request, and the capability gate
+requires an exact local `kiokuko-soul` descriptor for every task. Omission or
+false attestation is invalid; missing or unknown capability availability returns
+`required_capability_unavailable` even while intake needs an answer. A
+namespaced, fetched, or reference-only skill does not satisfy the required
+master SOUL. The boolean attestation is enforceable protocol evidence, not
+remote proof that a model understood or followed the Skill.
+
+The `memory-reasoning` standard skill is installed by default, but filesystem
+placement is not proof that the current model loaded or followed it. For ready
+build/debug tasks, clients advertise the exact local capability only when it is
+actually available. If it is missing or availability is unknown, Kiokuko sets
+`memoryPolicy.contextWithheld=true`, reports `memory_reasoning_missing` or
+`memory_reasoning_unknown` in `memoryPolicy.withheldReason`, returns no actionable
+ordinary memory, and leaves `nextAction=proceed`. An unmanaged same-name file
+causes setup to fail closed; move or remove that file manually before rerunning
+setup if Kiokuko should own the destination.
+
+The UI standard skill is intended for explicit UI, UX, frontend, screen, SwiftUI,
+accessibility, and equivalent Japanese-language tasks. `task_prepare` treats it
+as a first-party recommendation only for such concrete terms; generic `design`,
+backend-only work, and image-only generation do not trigger it.
+
+The UI and function standard Skills use progressive disclosure. Their short
+`SKILL.md` files are mandatory indexes, while versioned expert fragments are
+selected for the concrete component, function, design decision, or WorkUnit.
+Normal execution reads one to three fragments rather than every reference.
+
+The single-purpose-functions standard skill applies to writing, modifying,
+reviewing, debugging, and refactoring code across languages and repositories.
+Its examples use typed TypeScript for concreteness, but the contracts explicitly
+adapt to the target project's language, error model, persistence layer, and test
+framework. `task_prepare` treats it as a first-party recommendation for concrete
+coding terms in English or Japanese. Explicit no-code, documentation-only, and
+image-only work do not trigger it. Kiokuko does not claim that availability alone
+forces model use.

package/docs/concepts.ja.md

@@ -0,0 +1,25 @@
+# 基本概念
+
+## RAGと記憶のライフサイクル
+
+KiokukoはRAG（retrieval-augmented generation）を使います。作業前にMCP serverが保存済みentryを検索し、関係する文脈だけを渡します。
+作業後は決定、結果、教訓をcheckpointできます。記憶は参考情報なので、現在のリポジトリと実行結果が常に優先されます。
+
+entryはcapture、validation、retrieval、review、必要ならpromotionを経ます。secretらしい内容は拒否され、checkpointは正しさの証明ではありません。
+
+## スコープ
+
+- **Project**: 1つのrepository専用。
+- **Ecosystem**: 言語、framework、database、runtimeの条件が一致する場合に再利用。
+- **Global**: 特定projectに依存しないと明示的に一般化した知識。
+
+tagだけでProject記憶が別projectへ漏れることはありません。Curatorの確認後にGlobalへ昇格できます。
+
+## Akinator
+
+Akinatorはintake gateです。依頼が曖昧なとき、候補を分ける最小の質問をします。回答が必要な間はplan、編集、検証、checkpointを開始しません。
+intakeがreadyまたはexhaustedになってから通常ルートへ進み、発見されたSkillは参照専用です。
+
+## Semantic retrieval
+
+基本はlexical検索です。任意のlocal embeddingがsemantic signalを追加します。詳細は[Semantic retrieval](semantic-retrieval.ja.md)を参照してください。

package/docs/concepts.md

@@ -0,0 +1,33 @@
+# Concepts
+
+## RAG and memory lifecycle
+
+Kiokuko uses retrieval-augmented generation (RAG): before work, the MCP server
+searches stored entries and delivers only relevant context; after work, useful
+decisions, results, and lessons can be checkpointed. Retrieval is advisory, so the
+current repository and execution evidence always win.
+
+Entries move through a lifecycle of capture, validation, retrieval, review, and
+optional promotion. Secret-shaped content is rejected. A checkpoint is not proof
+that a memory is correct; it is a candidate for later reuse.
+
+## Scopes
+
+- **Project**: knowledge for one repository.
+- **Ecosystem**: knowledge reusable for matching language, framework, database, or runtime constraints.
+- **Global**: explicitly generalized knowledge that does not depend on one project.
+
+Tags alone do not leak Project memory into another project. Curator reviews a
+candidate before Project knowledge can be promoted to Global.
+
+## Akinator
+
+Akinator is the intake gate. When a request is underspecified, it asks the smallest
+question needed to distinguish plausible goals. While intake needs an answer, the
+agent must not plan, edit, verify, or checkpoint. Once intake is ready or exhausted,
+the normal route can continue and discovered Skills remain reference-only.
+
+## Semantic retrieval
+
+Lexical retrieval is the baseline. Optional local embeddings add semantic signals
+without sending memory to a remote provider. See [Semantic retrieval](semantic-retrieval.md).

package/docs/database.md

@@ -0,0 +1,20 @@
+# Database baseline
+
+Kiokuko 1.0 initializes a new database from `migrations/001_baseline.sql`.
+The baseline includes memory revisions, task intake and ledger, scoped context,
+external Skill discovery, CJK word/trigram search, and semantic search tables.
+SQL performs no network access, model loading, or vector generation.
+
+`schema_migrations` binds the baseline filename and SHA-256 checksum. Reopening
+an initialized database does not reapply SQL. Unsupported histories, missing
+history on a nonempty database, and altered checksums fail before writes.
+Orphan WAL/SHM files and rollback journals also cause refusal; initialization
+never moves sidecars or invokes recovery for them. The preflight inspects a
+temporary DB/WAL copy so SQLite cannot alter the original SHM read marks.
+
+Only current data formats are read. Schema initialization never converts old
+memory, restores obsolete settings, or deletes unreadable rows. Optional
+Embedding providers used by current runtime and evaluation remain supported;
+new installations start with semantic search disabled until explicit setup.
+
+See [the 1.0 breaking changes](breaking-changes-1.0.md) for existing installations.

package/docs/execution-ledger.md

@@ -0,0 +1,68 @@
+# Execution ledger
+
+The execution ledger is an append-oriented audit of agent runs. It is separate from curated memory (`entries`, `entry_revisions`, `entry_revision_tags`, `entry_links`) and from memory mutation audit (`audit_events`). A ledger event never becomes verified memory automatically.
+
+## Storage model
+
+The baseline adds:
+
+- `ledger_runs`: immutable workspace/client/protocol/capture/coverage identity and mutable lifecycle cursor/status.
+- `run_intakes`: one-to-one link from a run to an existing Akinator session, including policy/schema versions, field sources, initial profile hash, and recommended tags.
+- `intake_feedback`: question/profile feedback with XOR target and actor/idempotency uniqueness.
+- `ledger_events`: contiguous local sequence, source identity, canonical/source types, bounded sanitized payload, redaction metadata, and hash-chain fields.
+- `ledger_evidence`: bounded command/test/file/diff/URL/artifact locators and digests; never binary or unlimited output.
+- `context_deliveries` and `context_delivery_entries`: exact cursor/profile/query/policy/budget and selected immutable entry revision/rank/score/reason. The child row has a composite foreign key to `entry_revisions`, so a delivery cannot reference a missing or silently substituted revision.
+- `context_feedback` and `run_feedback`: explicit weak ranking signals and outcome/recommendation feedback.
+- `ledger_memory_links`: provenance from run/event/delivery to promoted candidate memory.
+- `ledger_purge_audit`: content-free tombstones after privacy purge.
+
+The baseline includes:
+
+- `nudge_deliveries`: presentation history for selected advisory nudges. It stores the run, policy version, checkpoint identity, logical occurrence, code, sequence, priority, and bounded evidence/reference ID snapshots, but not rendered message text.
+
+The baseline includes database guards for the supported nudge policy, code/priority pairs, and bounded JSON snapshots.
+
+## Invariants
+
+1. A run belongs to one workspace for its lifetime.
+2. One run links to one intake session, and one intake session links to one run; their workspaces must match.
+3. `intake → active` is valid only after the linked session is `ready` or `exhausted`.
+4. A run's coverage declaration is preserved rather than inferred upward.
+5. `event_id` is globally unique; events also have unique `(run_id, sequence)` and unique `(run_id, source_event_id)` when present. Exact replay may identify an event by its explicit `eventId` or its run-scoped source identity; a different sanitized body conflicts.
+6. A batch receives contiguous local sequence numbers in one `BEGIN IMMEDIATE` transaction or writes nothing.
+7. Corrections and task-profile revisions are new events; prior event rows and finalized intake profiles are not rewritten.
+8. Terminal runs reject new events except exact replay of an acknowledged idempotency/source identity.
+9. Delivery rows reference entry revisions instead of copying memory bodies.
+10. Feedback cannot mutate entry status/trust or an existing policy/session/profile.
+11. Promotion is explicit, creates `candidate` memory only, and records provenance.
+
+## Canonical event types
+
+V1 recognizes intake/run/request/constraint/decision/step/approval/tool/command/file/test/verification/error/retry/cancellation/context/memory/task-profile/correction/source event families. Unknown client event names are retained only as `sourceType` behind the canonical `source.event` type; they are not invented or silently mapped.
+
+## Integrity chain
+
+Before storage, Kiokuko performs strict validation, creates an owned JSON snapshot, recursively sanitizes keys/values/URLs/paths/environment data, enforces byte limits, and canonicalizes JSON. Optional hash fields are represented explicitly as `null`, so the write-time preimage is identical after a SQLite round trip. The event hash commits to run ID, local sequence, canonical event data, sanitized payload, and previous hash. The first event uses the deterministic genesis hash. `doctor` checks contiguous sequence, run cursor, hash links, and orphans.
+
+One sanitized event payload, task snapshot, profile-hints snapshot, intake-answer snapshot, or run-metadata snapshot is limited to 64 KiB. The limit is applied after sanitization and before hashing or opening a write transaction.
+
+The chain is tamper-evident, not a signature or remote attestation. SQLite and same-user host security still define the local trust boundary.
+
+## Projection and evidence freshness
+
+Projection is deterministic through a committed local sequence. It derives current task profile from the immutable intake profile plus ordered `task_profile.revised` events, unresolved failures, unknown side effects, latest mutation, and latest passing verification. Evidence state is:
+
+- `none`: no verification evidence;
+- `failed`: latest relevant verification failed;
+- `fresh`: passing verification is at or after the latest mutation;
+- `stale`: a later mutation exists.
+
+Minimum recommendation codes are `INTAKE_INCOMPLETE`, `VERIFY_AFTER_MUTATION`, `SIDE_EFFECT_OUTCOME_UNKNOWN`, `UNRESOLVED_FAILURE`, `CONTEXT_STALE`, `CONTRADICTORY_MEMORY`, `COVERAGE_INCOMPLETE`, and `PROMOTION_CANDIDATE`. Recommendations are stored data with evidence IDs, not commands.
+
+Recommendations describe every currently applicable deterministic condition. A nudge is a separate presentation decision: at most one eligible advisory item selected from the v1 nudge subset (`SIDE_EFFECT_OUTCOME_UNKNOWN`, `UNRESOLVED_FAILURE`, and `VERIFY_AFTER_MUTATION`). `CONTRADICTORY_MEMORY` remains a recommendation but is not a nudge because the HTTP checkpoint broker does not currently expose its complete contradiction-pair state. Nudge candidates are derived from the committed projection and final capability-gated recommendations only; fixed messages and bounded evidence/reference IDs are returned, and rate limiting never removes the corresponding recommendation.
+
+Nudge policy version `nudges.v1` shows one logical occurrence at most once per run, permits at most three deliveries per run, and requires at least three committed ledger sequence positions between deliveries of the same code. Eligibility uses occurrence identity and ledger sequence, not wall-clock time. `nudge_deliveries` is presentation history outside `ledger_events`, so delivering a nudge cannot change the execution projection.
+
+## Archive, backup, purge
+
+Existing memory export remains memory-only. Ledger export/import uses a separate deterministic manifest/checksum and includes nudge delivery history. Full SQLite backup contains memory, ledger, nudge deliveries, and feedback. Purge removes bounded content under explicit confirmation while preserving only a content-free tombstone and any promoted memory that has its own lifecycle.

package/docs/getting-started.ja.md

@@ -0,0 +1,45 @@
+# 導入ガイド
+
+## インストールと設定
+
+Node.js 24.16.0以上が必要です。次の2コマンドで導入します。
+
+```bash
+npm install --global @askdkc/kiokuko
+kiokuko setup
+```
+
+Optional setup flags: `--no-standard-skills`, `--skill-discovery off|official|community`, and `--dry-run --json`.
+
+Codexでは次のmanaged blockを所有します。
+
+```toml
+[mcp_servers.kiokuko]
+command = "kiokuko"
+args = ["mcp"]
+enabled = true
+required = true
+```
+
+`required`の欠落、値、順序、重複key、余分なfieldの変更や
+`required = false`はuser-managed conflictとして無断上書きしません。対話実行では置換確認を行い、JSON・非対話・dry-runでは
+`CONFLICT`を返して変更しません。他の対応clientも同じ規則です。
+
+起動中のclientは設定後に再起動してください。
+`kiokuko doctor --json`はruntime、DB、Codex MCPを読み取り専用で検査します。
+
+## Embeddings
+
+`kiokuko embeddings setup`は固定semantic runtimeを導入し、`kiokuko setup`と同じclient設定フロー（conflict確認、managed MCP更新、
+登録済みプロジェクトのinstructions更新）を実行します。
+
+```bash
+kiokuko embeddings setup --clients codex
+kiokuko embeddings setup --preset local-small --offline
+kiokuko embeddings status --json
+```
+
+`--replace`は別のembedding profileから切り替える指定です。`--dry-run`はdownloadと変更を行わず、`--json`は自動化向けで
+unmanaged MCP identityをfail closedします。
+
+## Web UIとclient