kiokuko 1.0.0

package/docs/getting-started.md

@@ -0,0 +1,49 @@
+# Getting started
+
+## Install and configure
+
+Node.js 24.16.0 or newer is required. Install and configure in two commands:
+
+```bash
+npm install --global @askdkc/kiokuko
+kiokuko setup
+```
+
+Optional setup flags: `--no-standard-skills`, `--skill-discovery off|official|community`, and `--dry-run --json`.
+
+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. Missing `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. 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

package/docs/release-notes-0.1.18.md

@@ -0,0 +1,105 @@
+# Kiokuko 0.1.18
+
+Historical release notes. Database upgrade and recovery behavior below does not apply to Kiokuko 1.0; see [1.0 breaking changes](breaking-changes-1.0.md).
+
+## 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へコピーしません。

package/docs/security-and-trust.md

@@ -0,0 +1,39 @@
+# Security and trust
+
+## Memory and secrets
+
+Kiokuko refuses content that resembles passwords, API keys, tokens, private keys,
+or similar secrets. It does not store full conversations. Memory is advisory and
+must not override current code, configuration, or execution evidence.
+
+## External Skills
+
+External Skill discovery is reference-only. Kiokuko verifies a source commit, stores
+bounded content as an untrusted candidate, and never installs, runs, or registers
+fetched Skill content automatically. `official` is the default discovery mode;
+`community` is explicit opt-in and `off` disables discovery.
+
+Inspect or manage mappings with:
+
+```bash
+kiokuko skills find svelte --official-only --json
+kiokuko skills list
+kiokuko skills disable <skill-id>
+kiokuko skills refresh <skill-id>
+```
+
+The Web UI can inspect and disable mappings, but has no install, script, or MCP
+registration action.
+
+## MCP extensions and public errors
+
+Codex `ToolLifecycleContributor` and other client extensions can inspect or replace successful and error MCP results. They are
+therefore part of the trusted computing base; Kiokuko cannot claim end-to-end
+authenticity without an extension-unforgeable original-result identifier and modified
+flag. Do not combine Kiokuko with an extension that changes critical results.
+
+Normal public tool failures use `isError: true` with an allowlisted message plus
+`structuredContent.code` and `structuredContent.retryable`; only `BACKPRESSURE` may
+include bounded `retryAfterSeconds`. Raw stacks, SQL, paths, payloads, and secrets
+are not copied into generic errors. Specialized validation and recovery errors retain
+only their bounded purpose-specific fields.

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/semantic-retrieval.ja.md

@@ -0,0 +1,18 @@
+# Semantic retrieval
+
+軽量インストールではlexical検索が動きます。semantic検索は任意のlocal `local-small` embedding profileです。
+
+```bash
+kiokuko embeddings setup
+kiokuko embeddings status --json
+kiokuko embeddings repair
+```
+
+固定runtimeを導入し、load前にartifactを検証します。`--offline`は検証済みlocal installationを要求し、`--dry-run`はdownload・書き込み・profile変更を行いません。
+`--replace`は別profileから切り替えます。model weightはnpm packageに含めません。
+
+このコマンドは通常のclient setup flowも実行し、managed MCP blockとproject instructionsを更新します。完全一致の旧managed blockは自動更新します。
+unmanagedまたは改変されたidentityは対話確認が必要で、JSON・非対話・dry-run自動化では設定を変えずfail closedします。
+
+runtime、model、vectorに障害があってもlexical検索と既存vectorは利用できます。`status`と`doctor --json`でcoverageとhealthを確認します。
+embedding設定は環境変数ではなくSQLiteに保存します。

package/docs/semantic-retrieval.md

@@ -0,0 +1,26 @@
+# Semantic retrieval
+
+Lexical retrieval works in the lightweight install. Semantic retrieval is an
+optional local `local-small` embedding profile.
+
+```bash
+kiokuko embeddings setup
+kiokuko embeddings status --json
+kiokuko embeddings repair
+```
+
+Setup installs only the pinned runtime and verifies every artifact before loading
+it. `--offline` requires an already verified local installation; `--dry-run` does
+not download, write, or change the active profile; `--replace` switches from a
+different active profile. Model weights are not included in the npm package.
+
+The command also runs the normal client setup flow: managed MCP blocks and project
+instructions are refreshed. Exact old managed blocks are upgraded automatically.
+An unmanaged or tampered identity requires interactive confirmation; JSON,
+non-interactive, and dry-run automation fails closed with no configuration change.
+
+If the local runtime, model, or vectors are unavailable, lexical retrieval and old
+vectors remain usable. `status` and `doctor --json` expose coverage and health.
+Embedding configuration is stored in SQLite, not environment variables. Platform-
+specific runtime installation details and allowlists are kept in the implementation
+references and release checks.

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.