@askdkc/kiokuko 0.2.7 → 0.2.9

package/docs/client-compatibility.md

@@ -0,0 +1,298 @@
+# Client compatibility policy
+
+Status: global MCP integration for Codex, OpenCode, Claude Code, and profile-scoped Hermes Agent. Enno-Oduno continuation adapters are bounded and available for Codex, OpenCode, and Claude Code; Hermes has no Enno continuation adapter.
+
+| 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-enno-oduno,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | bounded Stop hook when Enno-Oduno is enabled |
+| 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-enno-oduno,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | bounded `session.idle` plugin when Enno-Oduno is enabled |
+| 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-enno-oduno,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | bounded Stop hook when Enno-Oduno is enabled |
+| Hermes Agent | managed `mcp_servers.kiokuko` in the effective profile `config.yaml` | none | effective profile `skills/{memory-reasoning,kiokuko-soul,kiokuko-enno-oduno,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-enno-oduno`,
+`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.
+
+The Enno-Oduno standard skill is the role-level controller contract. Every
+Enno-Oduno directive and WorkUnit retains `kiokuko-soul` first. Enno-Oduno
+directives then require `kiokuko-enno-oduno` during intake, Oduno ideal
+derivation, confirmation, final review, and Oduno meditation. A ready intake
+enters `oduno_ideal`: `enno_ideal_submit` derives the optimal target from the
+structured `task_prepare` handoff plus exactly one contribution per
+Akinator-discovered Skill before Zenki can plan. After accepted final
+verification, `oduno_meditation` inspects changed and approved paths for
+evidence-backed obsolete test or function candidates without deleting them;
+`enno_meditation_submit` persists that reflection and completes the run. The
+controller skill itself is not inserted into Zenki's WorkUnit
+Skill snapshot; Zenki continues to require the single-purpose-functions skill
+for every code-changing plan. Every code-changing WorkUnit persists one to
+three registered `expertRefs`; UI WorkUnits include at least one `code.*` and
+one `ui.*` expert. Unknown, duplicate, missing, or oversized expert mixtures
+are rejected before Skill discovery or repository mutation.
+
+A `needs_confirmation` response carries
+`ennoOduno.directive.userFacingConfirmation`, a deterministic display
+projection of the decided contract. It presents scope paths, exclusions,
+completion criteria, work items with display-number dependencies, skills with
+their reference-only status, expertise with selection reasons, focused and
+final checks (executable, arguments, directory, and timeout kept separate, never
+joined into a shell command), and the attempt limit, each labeled with its
+provenance basis (`user`, `repository`, or `proposal` for inferred fields). The
+directive also carries a fixed confirmation report schema and objective, so the
+client model presents every item in the user's language, translating headings
+only, without raw directive JSON, internal field names, WorkUnit IDs, expert
+IDs, or verifier IDs, and then waits for an explicit approve, revise, or cancel
+through `enno_answer` at the confirmed contract revision. Projection content
+that resembles a secret or exceeds the 64 KiB display bound rejects the plan
+submit instead of being redacted or truncated. `needs_confirmation` stays
+outside the Codex Stop hook, Claude Code Stop hook, and OpenCode
+`session.idle` continuation candidates, so no client auto-continues through a
+user confirmation.
+
+Final Review is two-phase. `enno_verify_prepare` runs the approved final
+verifiers outside database transactions with shell disabled and a
+repository-relative cwd, stores evidence bound to contract/mutation revision,
+verifier specification, and complete repository state, and only then permits
+the final-review advisory fanout. `enno_finish` rechecks that state, decides
+accept/replan/block from the complete stored context, never spawns a subprocess,
+and rejects unready evidence as a conflict. Passing tests alone do not accept a
+run; Enno-Oduno must accept the current contract.
+
+All supported clients consume the same bounded `ENNO_INPUT_INVALID` validation
+envelope and the same WorkUnit-local route contract. New verifier cwd values are
+repository-relative. Continuation adapters transport opaque resume tokens and
+route epochs; Goki transports the returned execution lease. Old tokens become
+invalid after rerouting, and an active lease prevents another client from
+rerouting or reporting the same WorkUnit.
+
+If the environment information needed to start a plan is absent or no longer
+matches the task-preparation binding, the MCP result instead contains a
+non-mutating `userFacingRecovery` projection. Clients translate and present
+only its what-happened, work-state, resolution, and choices. Every choice is
+shown as its translated label and recommendation, followed by its translated
+`whenToChoose` intent and exact `whatHappens` result. The machine `action`,
+internal tool and field names, catalog, hashes, run identity, revisions,
+presentation version, reason codes, and raw JSON remain hidden. The client must
+not retry, cancel, or create a replacement automatically.
+
+For missing information, continuing attaches the complete catalog retained by
+the host and reuses the same attempt; reviewing asks the user for changes and
+starts no implementation before the answer; cancelling ends the current attempt
+without a replacement. For changed environment information, restarting first
+cancels the active planning attempt and then opens a new task with the current
+environment and agreed plan. Review-before-restart asks for changes first, then
+cancels and replaces the active attempt only after the answer. If a legacy
+attempt already ended because the catalog was provably lost during plan
+submission, both restart choices leave that terminal attempt unchanged and open
+a replacement only after the user chooses and, for review, answers. Cancelling
+an already-ended attempt creates nothing.
+
+For new Codex, OpenCode, and Claude Code setup, Enno-Oduno continuation is
+enabled by default; existing managed installations remain unchanged until
+`--enno-oduno on` is selected. Setup installs only the bounded native adapter
+for each of those clients: a Codex or Claude Code Stop hook, or an OpenCode
+`session.idle` plugin. Hermes receives no Enno continuation adapter. During an
+adapter continuation, `client_session_id` is routing metadata rather than
+authorization ownership. A valid short-lived resume token wins; otherwise the current
+local Codex, Claude Code, or OpenCode session may atomically reroute the single
+unambiguous active run in the canonical repository, including across client
+kinds. Rerouting increments the route epoch and invalidates old tokens; an
+active WorkUnit execution lease blocks it. Multiple active candidates remain
+unchanged. A per-session continuation limit stops only that session and leaves
+the run and ledger active for another local project client. Hermes has no
+automatic hook but may continue the same run through MCP with its exact run
+identity. The public `clientBinding` field reports this current route; its
+`bound` state does not grant ownership.
+upgrade, `--enno-oduno off` removes only the exact Enno-owned adapter, while
+setup also removes only the byte-exact retired OpenCode guard and the one exact
+retired Claude prompt handler. A modified, duplicate, relocated, or partial
+legacy identity is `CONFLICT` and requires manual review; unrelated client
+settings are preserved.
+
+`task_prepare` can accept an ephemeral catalog of skill and MCP-tool names from
+the calling client. Kiokuko matches Akinator policy recommendations and task
+terms against that catalog, but cannot enumerate another MCP server or a
+client's private skill registry by itself. A result therefore distinguishes
+`available`, `missing`, and `unknown`; it never treats a fetched `SKILL.md` as
+installed or executable. External skill discovery is controlled independently
+by `KIOKUKO_SKILL_DISCOVERY=off|official|community` and defaults to `official`.
+When enabled, Kiokuko compares the project fingerprint with relevant client
+skills rather than checking whether the catalog is globally empty. An omitted
+catalog is treated as unknown availability; official reference-only discovery
+may still proceed, but fetched skills are never treated as installed or
+executable. Akinator discovery and `kiokuko skills find` share the same
+provider-backed `findSkills` operation. There is no legacy fixed-source sync or
+guessed-source fallback; bounded exact verification of a reviewed,
+catalog-pinned source remains.
+
+`task_prepare` also requires a bounded opaque `requestId`. Clients create a new
+ID for every logical user request, including a later request with identical task
+text, and reuse an ID only for an exact transport retry. Reusing an ID with
+changed bound intake input is `CONFLICT`; `client.sessionId` is not a turn or
+request identity. The raw request ID is not stored.
+The normalized context budget is part of the bound request and every
+`task_answer` must repeat it; a changed budget conflicts before intake mutation.
+
+The legacy ungated `guide context` path was removed. Task-aware context must use
+`task_prepare` / `task_answer` or the generic Agent bridge so the same
+`kiokuko-soul` hard gate applies. External Skill discovery belongs to
+`task_prepare` or the explicit `skills find` / `skills import` commands.
+
+Every `task_answer` request must include the exact `run.runId`, capability
+catalog, and context budget supplied to `task_prepare`; clients must not fall
+back to session-only run lookup or replace those bindings between answers. Inspect
+`nextAction` and `memoryPolicy` after every `task_prepare` and `task_answer` response. Every task
+requires the exact local `kiokuko-soul`; missing or unknown availability returns
+`required_capability_unavailable`, even while intake needs an answer. For a ready
+build/debug task with actionable ordinary memory, missing or unknown
+`memory-reasoning` alone sets `memoryPolicy.contextWithheld=true`, reports
+`memory_reasoning_missing` or `memory_reasoning_unknown` in
+`memoryPolicy.withheldReason`, withholds that memory, and leaves `nextAction=proceed` so
+the client can continue from repository evidence. When it is available, the
+client must read the 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. Catalog availability
+alone does not satisfy this execution contract.
+`context: null` with `memoryPolicy.contextWithheld=true` is the explicit
+withholding state and persists no delivery. A non-null empty context with a null
+delivery ID means there was no actionable candidate; clients must not collapse
+these states.
+If the client cannot obtain the Kiokuko policy for a non-trivial build/debug
+request, it must also stop and report that boundary. Repository-only
+continuation for such a request is allowed only after the policy establishes
+that no Kiokuko memory was delivered or used.
+
+The latest returned `intake.question` is authoritative for every answer. If
+`question.options` is non-null, submit exactly one returned option as `value`.
+If `options` is null, submit grounded non-empty free text. Repeat the loop until
+`intake.status` is `ready` or `exhausted`; `target` and `expected` require
+grounded text and are not one-word enums.
+
+Run-bound `memory_checkpoint` has the same intake precondition across MCP,
+scoped memory, and the Agent Gateway: only `active` runs may be closed by a
+successful checkpoint. If `task_prepare` or `task_answer` returns
+`needs_answer` with `nextAction=answer_from_evidence_or_ask_user`, the client
+must finish every required `task_answer` question before retrying. The MCP
+tool returns `isError=true` with fixed text and structured fields
+`code=CHECKPOINT_RUN_NOT_ACTIVE`, `reason`, `runStatus`, `nextAction`, and
+`retryableAfterStateChange`; arbitrary internal messages and details are never
+forwarded. A terminal run returns `reason=run_terminal` and `nextAction=stop`.
+
+The MCP checkpoint payload is closed and has two forms. A standalone
+checkpoint contains at least one memory and omits `runId`, `outcome`,
+`deliveryId`, `feedback`, and `evidence`. A run-bound checkpoint requires an
+active exact `runId`, an explicit terminal `outcome`, and at least one
+non-empty `memories`, `feedback`, or `evidence` lane. Outcome-only, empty
+evidence, empty feedback, and invented evidence fields such as `checks` are
+invalid. Evidence fields are limited to `changedPaths`, `errorSignatures`,
+`commands`, `tests`, and `verification`; feedback items are limited to
+`entryId`, `entryRevision`, `verdict`, and `comment`.
+
+## Scope boundary
+
+The stdio MCP server calls Kiokuko's memory services only through
+`task_prepare`, `task_answer`, and lifecycle tools. It never exposes the SQLite
+file or a direct recall tool. Human/operator CLI and Web inspection remains
+management-only. Task context is limited to the resolved current repository
+and/or the reserved global workspace; it never searches unrelated project
+workspaces. Writes are candidate-only, untrusted, bounded, content-hash
+idempotent, audited, and passed through secret detection.
+
+The generic Agent Gateway remains available for explicit execution-ledger
+workflows and applies the same task capability gate.

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/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/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.md

@@ -0,0 +1,11 @@
+# Embedding security
+
+The local-small preset fixes the repository, full revision, required files,
+sizes, and SHA-256 values. Arbitrary repositories, URLs, paths, extensions,
+and remote code are not accepted. Files are verified before model loading;
+staging is private and final installation is atomic.
+
+Status, doctor, progress, and errors do not include memory text, query text,
+credentials, redirect URLs, or absolute model paths. Legacy embedding
+environment variables are detected by name only and are not used as runtime
+configuration.

package/docs/sqlite-driver-adr.md

@@ -0,0 +1,8 @@
+# SQLite driver ADR
+
+Kiokuko keeps JavaScript exact-cosine search as the portable fallback and uses
+the package-owned sqlite-vec extension only when the configured backend is
+`auto` or `sqlite-vec` and the extension loads successfully. The setup model
+and embedding profile are independent of that backend choice. Extension
+loading is disabled immediately after a successful load, and user-provided
+native extension paths are not accepted.