kiokuko-dsh 0.1.0

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,11 @@
+# Embedding database changes
+
+Migration 022 rebuilds the released semantic projection tables to allow both
+v1 OpenAI-compatible history and v2 local profiles. It adds singleton settings,
+model installation metadata, and durable setup runs. Migration SQL performs no
+network access, model loading, or vector generation.
+
+Old v1 profiles, vectors, jobs, and query cache rows remain available. An old
+active profile is represented as requiring setup while runtime mode remains
+off. The manual down migration requires a backup and refuses to silently
+convert a local v2 profile.

package/docs/dsh-plugin.md

@@ -0,0 +1,108 @@
+# DeepSeek Harness Plugin
+
+Kiokuko provides an out-of-tree DeepSeek Harness bundle at
+`kiokuko-dsh/dsh`. It mounts the same Kiokuko core contracts used by the
+MCP clients; it does not fork DeepSeek Harness or modify a repository's files.
+
+## Install
+
+The Git dependency runs `prepare` to build its exported `dist/` files. pnpm
+blocks that script until you explicitly allow this exact Git artifact. Run the
+install once, copy the exact commit key printed by pnpm into
+`~/.dsh/profiles/web/pnpm-workspace.yaml`, and set it to `true`:
+
+```yaml
+allowBuilds:
+  "kiokuko-dsh@https://codeload.github.com/askdkc/kiokuko-dsh/tar.gz/<commit>": true
+```
+
+Keep existing entries and replace `<commit>` with the value pnpm printed. Then,
+from a DeepSeek Harness source checkout, run:
+
+```bash
+pnpm dsh plugin --profile web add github:askdkc/kiokuko-dsh
+pnpm dsh --profile web --dump-config
+```
+
+With an installed dsh CLI, use the same commands without the `pnpm` launcher.
+
+The package exposes the `./dsh` entrypoint and declares
+`dsh/cordis.patch.yml` as its bundle patch. Use a profile when testing or when
+you need an isolated configuration:
+
+```bash
+dsh plugin --profile kiokuko-test add github:askdkc/kiokuko-dsh
+dsh --profile kiokuko-test --dump-config
+dsh plugin --profile kiokuko-test remove kiokuko-dsh
+```
+
+`kiokuko-dsh` is the single named bundle row. Removal is exact and does not
+rewrite unrelated plugins or settings. The plugin itself never runs `kiokuko
+setup`, changes MCP configuration, or edits `AGENTS.md`.
+
+## Runtime contract
+
+The SQLite database remains the semantic authority for Akinator, memory,
+Enno-Oduno, receipts, leases, and verifier evidence. DeepSeek `SessionEvent`
+is the current-session ordered transcript and tool-evidence boundary. Events
+are observed after the host commit, while session flush, model dispatch, tool
+execution, and turn stopping are awaited durability or policy boundaries.
+
+The dsh integration provides:
+
+- the exact bundled `kiokuko-soul` system-prompt section and six standard Skill
+  providers;
+- one current Akinator question at a time, with unresolved intake blocking the
+  model and tools;
+- all fourteen Kiokuko operations, with only the seven model-facing operations
+  exposed as model tools and host identity injected after argument validation;
+- revision, route, phase, lease, idempotency, confirmation, verifier, and
+  meditation gates through the Kiokuko core;
+- ordered, idempotent SessionEvent bridging with a final flush before terminal
+  ledger close; and
+- bounded turn continuation, exact run/session/workspace/route binding, and
+  in-memory plaintext continuation tokens.
+
+`runId` is required for dsh resume. The plugin never selects a repository-wide
+latest run. Ambiguous, stale, cancelled, aborted, lease-conflicting, or
+unavailable states stop without converting the failure into a normal success.
+
+## Verification
+
+From the Kiokuko checkout:
+
+```bash
+npm run test:e2e:dsh
+```
+
+This builds the package, runs the Cordis composition test with an in-memory
+host adapter, validates model/tool/question/ledger/turn-end boundaries, and
+then runs the pack/install/dump-config/remove flow when a `dsh` executable is
+available. Without that executable the CLI portion is reported as
+`unsupported`; it is not represented as a passing install result.
+
+The current compatibility measurement is:
+
+| Harness profile | Status |
+|---|---|
+| web | contract covered; DeepSeek CLI runtime not available in this checkout |
+| headless | contract covered; DeepSeek CLI runtime not available in this checkout |
+| sdk | unsupported until a real Loader/SDK host is supplied |
+| acp | unsupported until a real Loader/ACP host is supplied |
+| sdk-minimal | unsupported until a real Loader/SDK host is supplied |
+
+The `web` and `headless` labels describe the intended host profiles. They are
+not a claim that an external DeepSeek binary was executed in an environment
+where it is absent.
+
+## DSH acceptance boundary
+
+DSH acceptance is limited to the DSH surface and the directly relevant
+Kiokuko contracts listed by the DSH verifier set. The Core HTTP/Web/TCP suite
+is not silently folded into that acceptance boundary: if the host forbids
+loopback listeners (for example, with `listen EPERM`), that suite remains
+explicitly unverified and is not converted into a skip or a passing result.
+
+The DSH acceptance evidence is therefore reported separately from broader
+Core-suite evidence. An unavailable DeepSeek CLI is likewise reported as
+`unsupported`, never as a successful install or runtime execution.

package/docs/enno-oduno.ja.md

@@ -0,0 +1,22 @@
+# 役小角(enno-oduno)
+
+![役小角(enno-oduno)](../skills/kiokuko-enno-oduno/enno-oduno.png)
+
+build、debug、review、devopsでは、Enno-Odunoがrun-bound loopを管理します。
+
+```text
+intake → ideal → plan → 確認 → WorkUnit実行 → 最終検証 → meditation
+```
+
+clientを特定し、Akinatorのintakeを解決し、理想の結果を保存してから、revision-bound planをZenkiへ渡します。
+Zenkiは変更を責務と理由が1つのWorkUnitへ分割し、Gokiは承認済みunitだけを実行します。unitにはcode/ui/test/docs/operationsのローカルrouteがあります。
+
+確認画面にはscope、除外、完了条件、Skill、expertise、command、timeoutを利用者の言語で表示します。内部IDやraw JSONは表示しません。
+
+plan環境が欠落・変更した場合、discovery、plan保存、実装の前に停止し、continue/review/restart/cancelを選びます。継続は短命のroute-epoch-bound resume tokenと
+単一ownerのexecution leaseを使い、期限切れleaseだけ安全に回収できます。曖昧なrunはrerouteしません。
+
+Final Reviewはshell無効・repository相対pathでverifierを実行し、contract/mutation revision、verifier仕様、repository stateにevidenceを束縛します。
+完全なpass evidenceだけを`enno_finish`が受理します。失敗時はGokiへ直接戻らず、Zenkiが新revisionで再計画します。受理後はread-only meditationで削除候補を記録するだけです。
+
+ideal、planning、final-reviewでは、親hostが最大3つの隔離read-only Advisory Round slotを使えます。Kiokuko自身はadvisorを起動せず、隔離を確認できないslotはunavailableになります。

package/docs/enno-oduno.md

@@ -0,0 +1,35 @@
+# 役小角(enno-oduno)
+
+![役小角(enno-oduno)](../skills/kiokuko-enno-oduno/enno-oduno.png)
+
+For build, debug, review, and devops work, Enno-Oduno keeps a run-bound loop:
+
+```text
+intake → ideal → plan → confirmation → WorkUnit execution → final verification → meditation
+```
+
+The loop identifies the current client, resolves Akinator intake, derives and
+persists an ideal outcome, and hands a revision-bound plan to Zenki. Zenki divides
+changes into cohesive WorkUnits; Goki may execute only approved units. A WorkUnit
+has one responsibility, one reason to change, focused checks, and local code/ui/test/
+docs/operations routes.
+
+Confirmation displays scope, exclusions, completion criteria, skills, expertise,
+commands, and timeouts in user language. It never exposes internal IDs or raw JSON.
+
+If the plan environment is missing or changed, recovery pauses before discovery,
+plan persistence, or implementation. The user chooses continue, review, restart, or
+cancel. Continuation uses a short-lived route-epoch-bound resume token and one-owner
+execution lease; expired leases can be reclaimed safely. Ambiguous active runs are
+not rerouted.
+
+Final Review first runs approved verifiers with shell disabled and repository-relative
+paths. Evidence is bound to the contract revision, mutation revision, verifier
+specification, and repository state. `enno_finish` accepts only complete passing
+evidence. A failed review returns to Zenki for a new revision; it never resumes Goki
+directly. An accepted review enters read-only Oduno meditation, which records
+evidence-backed obsolete test/function candidates without deleting them.
+
+At ideal, planning, and final-review phases, the parent host may use three isolated
+read-only Advisory Round slots. Kiokuko does not launch advisors; unverifiable slots
+are reported unavailable and only the parent submits bounded, identity-free results.

package/docs/execution-ledger.md

@@ -0,0 +1,89 @@
+# 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
+
+Migration `004_agent_gateway.sql` 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.
+
+Migration `010_nudge_deliveries.sql` adds:
+
+- `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.
+
+Migration `011_nudge_integrity.sql` adds database guards for the supported nudge policy, code/priority pairs, and bounded JSON snapshots.
+
+Enno client routing writes `enno.client_bound` for the first session route and
+`enno.client_rebound` for later route changes. The payload records the previous
+and current client kind, session ID, and version projection; a rebound clears
+the old version. These events audit routing changes and do not confer ownership
+or advance the Enno contract state.
+
+The Enno execution ledger also uses database-backed ownership rows rather than
+process memory. Resume tokens are stored only as hashes and bind a route epoch;
+rerouting invalidates old epochs. A WorkUnit execution lease prevents two local
+clients from reporting the same unit and blocks rerouting while current.
+Operation receipts and verifier runs have `started`, `completed`, `failed`, and
+`abandoned` states with bounded leases and owner nonces. Recovery atomically
+abandons an expired owner before one new owner claims the exact operation; a
+losing or stale nonce cannot complete it.
+
+Final evidence binds contract revision, mutation revision, verifier
+specification digest, and complete repository-state digests captured before and
+after verifier execution. A verifier-caused repository mutation marks the run
+unacceptable, and any later HEAD/index/worktree/untracked/symlink change makes
+the evidence stale before `enno_finish` can commit.
+
+## 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,88 @@
+# 導入ガイド
+
+## インストールと設定
+
+Node.js 24.16.0以上が必要です。`kiokuko-dsh`をnpmに公開するまでは、local checkoutから実行します。
+
+```bash
+cd /path/to/kiokuko-dsh
+pnpm install --frozen-lockfile
+pnpm run build
+node dist/bin/kiokuko.js setup
+```
+
+npm公開後はglobal installも使えます。
+
+```bash
+npm install --global kiokuko-dsh
+kiokuko setup
+```
+
+`--clients codex,opencode,claude,hermes`で対象を明示できます。省略時はインストール済みclientを検出します。
+`--dry-run --json`は書き込みなしで計画を出力します。`--no-standard-skills`、`--skill-discovery off|official|community`、
+`--enno-oduno on|off`も指定できます。
+
+Codexでは次のmanaged blockを所有します。
+
+```toml
+[mcp_servers.kiokuko]
+command = "kiokuko"
+args = ["mcp"]
+enabled = true
+required = true
+```
+
+`required`を含まない完全一致の旧managed blockだけを再実行時に更新します。値、順序、重複key、余分なfieldの変更や
+`required = false`はuser-managed conflictとして無断上書きしません。対話実行では置換確認を行い、JSON・非対話・dry-runでは
+`CONFLICT`を返して変更しません。他の対応clientも同じ規則です。
+
+起動中のclientは設定後に再起動してください。Codex Stop hookを作成・更新した場合は`/hooks`で明示的にtrustします。
+`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
+
+`kiokuko web`を実行し、`http://127.0.0.1:4173`を開きます。UIはローカル限定の管理画面で、model向けMCP呼び出しの代替ではありません。
+Enno-Oduno有効時、Codex・OpenCode・Claude Codeには継続adapterがあり、Hermesはnative stdio MCPを使います。
+
+## DeepSeek Harness Plugin
+
+このパッケージはnpmに未公開です。Git dependencyは`prepare`で`dist/`を生成するため、pnpmの明示的な許可が必要です。
+
+一度導入を実行し、pnpmが表示したcommit付きのexact keyを
+`~/.dsh/profiles/web/pnpm-workspace.yaml`へ追加して`true`にします:
+
+```yaml
+allowBuilds:
+  "kiokuko-dsh@https://codeload.github.com/askdkc/kiokuko-dsh/tar.gz/<commit>": true
+```
+
+その後、次を実行します。
+
+```bash
+dsh plugin add github:askdkc/kiokuko-dsh
+```
+
+profileを分ける場合は次のようにします。
+
+```bash
+dsh plugin --profile kiokuko-test add github:askdkc/kiokuko-dsh
+dsh --profile kiokuko-test --dump-config
+dsh plugin --profile kiokuko-test remove kiokuko-dsh
+```
+
+install/remove、resume安全性、互換性、検証状況は
+[DeepSeek Harness Plugin](dsh-plugin.md)を参照してください。

package/docs/getting-started.md

@@ -0,0 +1,99 @@
+# Getting started
+
+## Install and configure
+
+Node.js 24.16.0 or newer is required. Until `kiokuko-dsh` is published to npm,
+run the CLI from a local checkout:
+
+```bash
+cd /path/to/kiokuko-dsh
+pnpm install --frozen-lockfile
+pnpm run build
+node dist/bin/kiokuko.js setup
+```
+
+After npm publication, the equivalent global install is:
+
+```bash
+npm install --global kiokuko-dsh
+kiokuko setup
+```
+
+Use `--clients codex,opencode,claude,hermes` to select clients explicitly. Without
+it, setup detects installed clients. `--dry-run --json` validates and reports planned
+changes without writing. `--no-standard-skills`, `--skill-discovery off|official|community`,
+and `--enno-oduno on|off` control optional setup behavior.
+
+For Codex, setup owns one exact managed block:
+
+```toml
+[mcp_servers.kiokuko]
+command = "kiokuko"
+args = ["mcp"]
+enabled = true
+required = true
+```
+
+The discovery environment line is managed with that block. Rerunning setup upgrades
+only the exact previous managed block that omitted `required`. Changed values,
+ordering, duplicate keys, extra fields, or an explicit `required = false` are
+user-managed conflicts and are never silently overwritten. Interactive setup asks
+whether to replace a conflicting identity; JSON, non-interactive, and dry-run calls
+return `CONFLICT` without mutation. The same rule applies to other supported clients.
+
+Restart a running client after setup. If a Codex Stop hook is created or updated,
+open `/hooks` and explicitly trust it. Use `kiokuko doctor --json` to inspect runtime,
+database, and Codex MCP health; doctor is read-only.
+
+## Embeddings setup
+
+`kiokuko embeddings setup` installs the pinned local semantic runtime and runs the
+same client configuration flow as `kiokuko setup`, including conflict confirmation,
+managed MCP replacement, and registered-project instruction refresh.
+
+```bash
+kiokuko embeddings setup --clients codex
+kiokuko embeddings setup --preset local-small --offline
+kiokuko embeddings status --json
+```
+
+`--replace` switches from another active embedding profile. `--dry-run` performs no
+download or mutation; `--json` is suitable for automation and fails closed on an
+unmanaged MCP identity.
+
+## Web UI and clients
+
+Run `kiokuko web` and open `http://127.0.0.1:4173`. The UI is local-only and is a
+human/operator management surface, not a substitute for model task-entry MCP calls.
+Codex, OpenCode, and Claude Code have bounded continuation adapters when Enno-Oduno
+is enabled; Hermes uses native stdio MCP and bundled Skills without an adapter.
+
+## DeepSeek Harness plugin
+
+The package is not published to npm. The Git dependency builds its `dist/`
+files through `prepare`, so pnpm requires an explicit build approval.
+
+Run the install once, copy the exact commit key printed by pnpm into
+`~/.dsh/profiles/web/pnpm-workspace.yaml`, and set it to `true`:
+
+```yaml
+allowBuilds:
+  "kiokuko-dsh@https://codeload.github.com/askdkc/kiokuko-dsh/tar.gz/<commit>": true
+```
+
+Then run:
+
+```bash
+dsh plugin add github:askdkc/kiokuko-dsh
+```
+
+Use a profile for an isolated test:
+
+```bash
+dsh plugin --profile kiokuko-test add github:askdkc/kiokuko-dsh
+dsh --profile kiokuko-test --dump-config
+dsh plugin --profile kiokuko-test remove kiokuko-dsh
+```
+
+See [DeepSeek Harness Plugin](dsh-plugin.md) for the lifecycle contract,
+resume safety, compatibility status, and verification command.

package/docs/release-notes-0.1.18.md

@@ -0,0 +1,103 @@
+# Kiokuko 0.1.18
+
+## External Skills
+
+- Added bounded provider search, commit-pinned source validation, chunk limits, snapshot idempotency, and shared discovery single-flight.
+- Added `kiokuko skills find|import|list|show|refresh|disable|enable|prune-cache`.
+- Manual Skill import is now create-only and accepts only an exact locally
+  reviewed catalog identity. Re-importing an existing identity is a conflict;
+  use `skills refresh` for an existing managed Skill.
+- Akinator discovery and `kiokuko skills find` now use one shared provider-backed search operation; the temporary capability-fallback response was removed.
+- Akinator task preparation now defaults to reference-only `official` discovery; `off` remains available and `community` remains explicit opt-in.
+- Interactive setup now asks before enabling audited community discovery and persists the selected mode in each managed MCP client configuration; batch setup uses `--skill-discovery`.
+- Added authenticated local Web UI/API visibility for imported external skills.
+- Disabled, stale, blocked, and unmanaged external references are excluded from retrieval and Curator globalization.
+- Community-mode candidates fail closed without a successful provider audit.
+- Unknown capability catalogs now force official-only discovery; imported Skill
+  reuse requires explicit applicability and mode-compatible provenance.
+- Multiple relevant Skills can be imported from one repository, and lifecycle
+  CLI commands resolve both internal IDs and `owner/repository/skill` paths.
+- Task preparation replay identity now includes the effective discovery mode
+  and a bounded normalized capability-catalog hash, so changed discovery input
+  cannot reuse an older context delivery.
+- `task_prepare` now requires a bounded client-generated `requestId`. The same
+  ID and bound input replay one run; a changed bound request under that ID
+  conflicts, while a new ID opens a distinct run even for identical task text.
+  The raw ID is not stored and `client.sessionId` is not used as a turn ID. The
+  normalized context budget is bound and must match on `task_answer`.
+- Generated agent/setup/MCP contracts now require an available local
+  `memory-reasoning` Skill to be read before code modification and recalled
+  claims to be converted into verified premises, invariants, counterexamples,
+  and regression tests; availability alone is not compliance.
+- A v1 provider response with exact HTTP 401 authentication failure falls back
+  once per query to the Compatibility Provider, with provider-separated
+  negative and result caches. Other authentication and protocol failures stop.
+- Removed legacy fixed-source sync and guessed-source fallback. Bounded exact
+  verification of reviewed catalog-pinned sources remains. The ungated
+  `guide context` compatibility command was removed; task-aware ContextBroker
+  output is capability-gated.
+
+External skills remain untrusted candidate references. Kiokuko does not install,
+execute, verify, globalize, or register fetched skill content automatically.
+
+## Fail-closed storage and setup
+
+- Fixed Windows OpenCode setup writing MCP configuration, global instructions,
+  and bundled skills under `%APPDATA%\opencode`; setup now follows OpenCode's
+  XDG global directory resolution.
+- Setup now rejects duplicate or semantically colliding JSON/TOML configuration,
+  malformed UTF-8, symlink escapes, and concurrent target changes before it can
+  silently merge or overwrite them. Exact concurrent `use` results converge once;
+  incompatible state remains an explicit conflict.
+- Migration and repository transactions now surface rollback failures, and
+  verified pre-migration backups complete before any schema mutation.
+- Node.js 24.16 is now the minimum runtime. Manual and pre-migration SQLite
+  backups serialize the exact already-open connection and install a verified,
+  create-only artifact; the retired pathname-reopening backup subprocess and
+  overwrite behavior were removed. `kiokuko backup` no longer initializes or
+  migrates its source.
+- Project binding rejects the reserved global identity. Forced rebinding now
+  requires a distinct repository/workspace pair and performs an exact database
+  location compare-and-swap or fails; it never mutates a repository workspace
+  in place or silently retains the old identity. Moving `agentFile` removes
+  only the old marked block, preserves human bytes and mode, and conditionally
+  restores all owned file mutations if a later step fails. Skipping an agent
+  write rejects any stale managed block at the prospective target.
+- Repository binding/template versions are downgrade-protected across files and
+  SQLite metadata. Missing, malformed, corrupt, or future version metadata fails
+  explicitly. An indeterminate SQLite commit is surfaced as such and retains
+  the matching installed files instead of risking split-brain compensation.
+- Stored revision chains, hashes, structured scope, projections, and context
+  replay state are validated from their exact persisted identities. Corruption
+  fails explicitly instead of being skipped or normalized into a new identity.
+- Migration 012 validates the persisted structural identity of released
+  `context-ranking-v2` and `context-ranking-v3` scoped deliveries during setup.
+  Original delivery IDs, policy versions, character metadata, delivery items,
+  and all historical references are preserved. Legacy preview text was not
+  persisted and is not reconstructed during upgrade. Legacy deliveries remain
+  available for audit and feedback references but are never replayed as current
+  `context-ranking-v4` context; invalid persisted legacy structure aborts the
+  migration transaction. New scoped deliveries continue to use
+  `context-ranking-v4`.
+- Migration 009 transactionally rewrites the one exact released locale-ordered
+  revision preimage to the canonical hash and scope. Forged preimages and
+  canonical collisions abort the upgrade; runtime compatibility hashing was
+  removed completely.
+- Workspace archive v2 is intentionally limited to revision-1 current state.
+  Import/export use one strict canonical format, bounded input, complete secret
+  scanning, snapshot-consistent reads, and create-only output. Use a full SQLite
+  backup when immutable revision history must be preserved.
+
+## Model task boundary
+
+- Removed the direct model-facing `memory_recall` and
+  `claude_prompt_context` MCP tools. Task memory now enters through
+  `task_prepare` / `task_answer`; checkpoint and Curator tools remain lifecycle
+  operations.
+- Removed generic JSON `call` operations that returned memory through `read`,
+  `search`, or scoped/unscoped `recall`. Direct CLI/Web inspection remains a
+  human/operator management surface.
+- Setup no longer installs Claude prompt hooks or the OpenCode loop guard and
+  no longer accepts their CLI options. During upgrade it removes only the exact
+  retired managed hook/guard; modified or ambiguous legacy identities fail
+  explicitly and unrelated settings are preserved.

package/docs/retrieval-evaluation.md

@@ -0,0 +1,10 @@
+# Retrieval evaluation
+
+The existing evaluation keeps lexical and exact-signal lanes as baselines and
+preserves weighted reciprocal-rank fusion. Local semantic evaluation covers
+Japanese, English, Simplified Chinese, Korean, technical identifiers, stale
+vectors, scope boundaries, and query-cache privacy.
+
+Run the deterministic suite with `npm run test:evaluation`. Run the installed
+model probe with `node scripts/run-local-embedding-smoke.mjs --offline` when a
+verified local model directory is available.

package/docs/security-and-trust.ja.md

@@ -0,0 +1,29 @@
+# Security and trust
+
+## 記憶とsecret
+
+パスワード、API key、token、秘密鍵などに似た内容は拒否し、会話全文は保存しません。記憶は参考情報であり、現在のコード、設定、実行結果を上書きしません。
+
+## External Skills
+
+外部Skill discoveryは参照専用です。source commitを検証し、boundedな内容をuntrusted candidateとして保存しますが、取得したSkillを自動install・実行・登録しません。
+既定は`official`、`community`は明示opt-in、`off`で無効化します。
+
+Skillの確認・管理:
+
+```bash
+kiokuko skills find svelte --official-only --json
+kiokuko skills list
+kiokuko skills disable <skill-id>
+kiokuko skills refresh <skill-id>
+```
+
+Web UIではmappingの確認・無効化だけを行い、install、script、MCP登録は行いません。
+
+## MCP extensionと公開エラー
+
+client extensionは成功・エラーMCP resultを検査・置換できるため、trusted computing baseの一部です。extensionが偽造できないoriginal-result identifierとmodified flagなしには、
+end-to-end authenticityを主張できません。重要なresultを変更するextensionと併用しないでください。
+
+通常の公開tool errorは`isError: true`、allowlist済みmessage、`structuredContent.code`、`structuredContent.retryable`だけを返します。`BACKPRESSURE`だけがboundedな`retryAfterSeconds`を追加できます。
+stack、SQL、path、payload、secretはgeneric errorへコピーしません。