kloudy 1.0.1 → 1.0.3

package/AGENTS.md

@@ -1,6 +1,8 @@
 ## For AI agents: how to use Kloudy
 
-The catalog is **kloudy 1.0**: 13,440 bots and 44 modality tags, bundled in this package (npm version 1.0.1). `recommend` / `stack` and `bots ... --offline` read that snapshot (or the local cache if one exists). They do not call the network. Kloudy does not run an LLM to choose bots. Ranking is deterministic: the same goal returns the same JSON.
+The catalog is **kloudy 1.0**: 13,440 bots and 44 modality tags, bundled in this package (npm version 1.0.2). `recommend` / `stack` and `bots ... --offline` read that snapshot (or the local cache if one exists). Kloudy never runs an LLM. Ranking is deterministic: the same goal and the same score overrides return the same JSON.
+
+When a network is available, `recommend` may GET `https://kloudy.ai/api/feedback/scores` and cache those overrides for about 24 hours in the Kloudy data directory (`~/.kloudy`, or `KLOUDY_DATA_DIR`). Overrides demote, exclude, or boost a bot after the class tier. `--offline`, a failed request, or a missing scores file leaves ranking on the bundled catalog order.
 
 Classes:
 
@@ -18,18 +20,43 @@ Commands:
 
 ```sh
 npx kloudy@latest recommend "<goal>" --json
-npx kloudy@latest stack "<goal>" --json
+npx kloudy@latest recommend "<goal>" --json --limit 5
+npx kloudy@latest stack "<goal>" --json --limit 5 --offline
+npx kloudy@latest feedback --stack <stackId> --bot <botId> --result worked|failed|partial [--reason <short>] [--client <name>]
+npx kloudy@latest feedback --flush
 npx kloudy@latest bots search <words> --offline
 npx kloudy@latest bots get <id> --offline
 npx kloudy@latest agents
 npx kloudy@latest --help
 ```
 
-`recommend` and `stack` are aliases. `--json` prints only a JSON object on stdout (`schema`: `kloudy.recommend/1`, `catalog`: `kloudy 1.0`, `version`: the package version). Without `--json` you get the same sections as text, including an Unmatched section when a part did not match.
+`recommend` and `stack` are aliases. `--json` prints only a JSON object on stdout (`schema`: `kloudy.recommend/1`, `catalog`: `kloudy 1.0`, `version`: the package version). Without `--json` you get the same sections as text, including an Unmatched section when a part did not match. `--limit <n>` sets the per-part cap. `n` is an integer from 1 to 20. The default is 5. `--offline` skips the score-override request.
 
 Each bot has `id`, `name`, `class` (`A`, `B`, or `O`), `command`, `license`, `description`, `why`, and `modalities`. `command` is what you run or connect to: an `npx ...` command, a `uvx ...` command, or a URL. `recommend` does not install or download anything. Use `bots get <id> --offline` to inspect a pick, then run the command only when you intend to.
 
-The goal is decomposed before matching. Clauses split on commas, semicolons, and the words `and` and `then`. Inside a clause, distinct modality keywords become separate parts. Each part gets the top bots for each modality it needs (up to five). Order is class A, then B, then O, then primary-modality hint, keyword hits, catalog score, and catalog index. A part with no modality or no catalog row is returned in `unmatched` with the part text and the reason `no modality or catalog match`. Parts are not dropped to make a partial stack look complete.
+Write the goal as one sentence per need, or as a comma-separated list of needs. A long sentence is still accepted. Clearer parts produce a clearer stack.
+
+The goal is decomposed before matching. Clauses split on commas, semicolons, and the words `and` and `then`. Inside a clause, distinct modality keywords become separate parts. Each part gets the top bots for each modality it needs, then the list is capped per part. Each part includes `candidatesTotal` (how many eligible candidates existed before the cap) and `bots` (the capped list). Narrow that capped list with the project you have open: language, frameworks, licenses, and tools already in the repo. Kloudy never runs an LLM and does not read the project to pick a bot.
+
+Familiar modality words such as transcribe, summarize, and database still return the top bots in that modality. A narrower need, such as a watch, a timer, Android sync, a meal plan, or a social post, keeps only bots that share a real keyword or a clearly related catalog name, id, or cap with that part. Unrelated bots are not added as filler. Order is class A, then B, then O, then score override (boost, then unchanged, then demote), then primary-modality hint, keyword hits, catalog score, and catalog index. Exclude removes a bot before the cap. A part with no modality or no catalog row is returned in `unmatched` with the part text and the reason `no modality or catalog match`. Parts are not dropped to make a partial stack look complete.
+
+`phone`, `call`, and `calls` map to `audio` only when an audio cue is in the same part or clause: transcribe, transcription, voice, speech, audio, whisper, microphone, asr, phone call, or call audio. Otherwise phone, Android, and mobile are a device-sync need, not audio.
+
+Every part has `confidence`: `match`, `weak`, or `none`. Top-level `complete` is true only when every part is `match` and `gaps` is empty. `complete` false means the stack is partial. `gaps` lists unmatched and weak parts. Each gap has the part text, `confidence`, and a reason. `kind` is `catalog integration` when a catalog bot with an install or run command is a real but weak hit. `kind` is `suggestion: build yourself / platform API` when the catalog does not cover the need, such as Wear OS sensor APIs, Health Connect, or the Facebook Graph API. That suggestion is unverified non-catalog guidance. It is not a catalog bot.
+
+Every recommend result includes `limit`, `stackId`, and `feedback`. `stackId` is a sha256 of the goal's parts plus the chosen bot ids. The same parts and the same picks always produce the same `stackId`. `feedback` is the command to run after you try a bot. Put that bot's id in place of `<id>`.
+
+After you try a stack, report whether it worked:
+
+```sh
+kloudy feedback --stack <stackId> --bot <botId> --result worked|failed|partial [--reason <short>] [--client <name>]
+```
+
+`--result` is `worked`, `failed`, or `partial`. `--reason` is optional and short: it is truncated to 80 characters, and a path, token, or email is dropped. `--client` is an optional tool name such as `cursor`, `claude`, `codex`, or `vscode`. It counts distinct clients. Do not pass a person, email, or account. The report is opt-in and anonymous. The payload may include only `stackId`, `botId`, `result`, an optional short `reason`, the kloudy version, and an optional client name. It never includes the goal text, personal info, file paths, environment, or tokens. The POST goes to `https://kloudy.ai/api/feedback`. If the network is down or the POST fails, the report is queued in the Kloudy data directory and sent on the next `kloudy feedback` or `kloudy feedback --flush`.
+
+Score overrides come from those anonymous reports. `scripts/aggregate-feedback-scores.mjs` is meant to run weekly Sunday 3:00 America/Phoenix. It writes `feedback-scores.json`. Bots with fewer than 3 reports are ignored. A bot is demoted after it fails for 3 or more distinct clients with a failure ratio of 60% or more. A bot is excluded after 10 or more reports with a failure ratio of 80% or more. A bot is boosted at 5 or more reports when at least 80% are `worked` and it is not demoted or excluded. `partial` counts as a report and counts as neither worked nor failed. Failure ratio is `failed` divided by all reports. Reports without a client still count toward ratios. They do not add a distinct client.
+
+Without `--json`, the text includes Confidence, Candidates, Gaps, `limit`, `stackId`, `feedback`, and `complete=true` or `complete=false`. `--json` still prints only the JSON object (`schema`: `kloudy.recommend/1`, `catalog`: `kloudy 1.0`, `version`: `1.0.2`).
 
 Single-part example:
 
@@ -51,4 +78,6 @@ Three parts:
 2. `summarizes them` — `text` — `httpk:mcp:ai.liquidagent.api:liquid-agent` — `https://api.liquidagent.ai/mcp`
 3. `stores them in a database` — `database_access` — `httpk:npm:microsoft:postgres-mcp` — `npx -y @microsoft/postgres-mcp`
 
-`weave a basket` in a larger goal is unmatched. It is reported, not omitted.
+That control stack is `complete` true: each part is confidence `match`, and `gaps` is empty.
+
+`weave a basket` in a larger goal is unmatched. It is reported, not omitted. The goal is then `complete` false.

package/README.md

@@ -1,4 +1,4 @@
-# Kloudy — add it to your editor
+# Kloudy — add it to your editor
 
 Connect your MCP client to https://kloudy.ai/mcp for the current remote catalog.
 
@@ -14,6 +14,16 @@ No arguments detects Cursor, VS Code, Claude Desktop, Claude Code, Windsurf and
 
 The remote endpoint is https://kloudy.ai/mcp. Public catalog discovery works without a key and makes no model call. It returns up to five public metadata candidates, not execution grants. Account actions still require an existing authorized Kloudy key; self-service engine-key issuance is not connected. If you already have one, set `KLOUDY_MCP_TOKEN` privately in your environment; the installer asks before storing it in a client's headers (or Claude Desktop's stdio environment). Keys are never accepted as command-line arguments or printed by the installer.
 
+For an existing scoped assistant connection, select its private file explicitly:
+
+```sh
+npx kloudy@latest mcp --connection /private/path/connection.json
+```
+
+`KLOUDY_CONNECTION` is the equivalent private-file environment setting. The file must contain `endpoint` equal to `https://kloudy.ai/mcp`, a valid `access_token`, and a future Unix-seconds `expires_at`. A file and `KLOUDY_MCP_TOKEN` cannot be combined. The remote proxy never silently reads a default connection file, issues permission, or upgrades a discovery key.
+
+Authenticated room messaging is available through the existing `kloudy` tool's `operation: "room"` with `room_operation: "send"`, `"inbox"`, or `"reply"` and the corresponding schema. The backend validates the exact project, authorized client and recipient. These are data transport operations: a queued message is not an assistant response, and installing this package does not enable unattended assistant turns or voice calls. Server enrollment and account permissions must already support the selected connection.
+
 `mcp` is a local stdio-to-Streamable-HTTP proxy; stdout contains MCP messages only. Direct questions and the proxy call the same remote server. Network failures and invalid keys fail explicitly. Resources are forwarded whenever the upstream supports them, including with autoupdate off. Catalog change notifications and a single reconnect after an explicit session-expired HTTP 404 remain gated by `KLOUDY_MCP_AUTOUPDATE=meta` or `notify`; the default is `off`. Ambiguous tool failures are never retried.
 
 Interactive cards require a host that supports MCP Apps. The proxy relays the supported Apps MIME capability; it does not claim sampling, roots or elicitation. Hosts without Apps can use named text choices, source links and readable resources. The one-shot CLI prints text rather than rendering an interactive card. When the hosted catalog offers visual setup choices, the IDE uses its own available tools and account terms to make a local mockup; Kloudy supplies data and does not invoke backend model/image generation. Resource hosting still has operational cost. Selecting a layout does not authorize installation, account connection, paid image APIs or deployment.
@@ -24,13 +34,15 @@ Offline bot catalog: `npx kloudy bots list|search|get|sync|works|broken|modaliti
 
 ## For AI agents: how to use Kloudy
 
-The catalog is **kloudy 1.0**: 13,440 bots and 44 modality tags, shipped in this package (npm version 1.0.1). Recommend and the offline bots commands read that bundled snapshot, then the local cache. They do not call the network, and Kloudy does not run an LLM to pick a stack.
+The catalog is **kloudy 1.0**: 13,440 bots and 44 modality tags, shipped in this package (npm version 1.0.3). Recommend and the offline bots commands read that bundled snapshot, then the local cache. Kloudy never runs an LLM. Ranking is deterministic: the same goal and the same score overrides return the same JSON.
+
+When a network is available, `recommend` may GET `https://kloudy.ai/api/feedback/scores` and cache those overrides for about 24 hours in the Kloudy data directory (`~/.kloudy`, or `KLOUDY_DATA_DIR`). Overrides demote, exclude, or boost a bot after the class tier. `--offline`, a failed request, or a missing scores file leaves ranking on the bundled catalog order.
 
 Classes:
 
-- **A** — live HTTP MCP endpoints.
-- **B** — npx or uvx packages.
-- **O** — open source and Hugging Face listings.
+- **A** — live HTTP MCP endpoints.
+- **B** — npx or uvx packages.
+- **O** — open source and Hugging Face listings.
 
 List the modality tags:
 
@@ -38,18 +50,43 @@ List the modality tags:
 npx kloudy@latest bots modalities --offline
 ```
 
-Turn a plain-language goal into a stack. `recommend` and `stack` are the same command. Add `--json` when you need parseable output (`schema` is `kloudy.recommend/1`).
+Turn a plain-language goal into a stack. `recommend` and `stack` are the same command. Add `--json` when you need parseable output (`schema` is `kloudy.recommend/1`). `--limit <n>` caps each part (`n` is an integer from 1 to 20; the default is 5). `--offline` skips the score-override request.
 
 ```sh
 npx kloudy@latest recommend "<goal>" --json
-npx kloudy@latest stack "<goal>" --json
+npx kloudy@latest recommend "<goal>" --json --limit 5
+npx kloudy@latest stack "<goal>" --json --limit 5 --offline
+npx kloudy@latest feedback --stack <stackId> --bot <botId> --result worked|failed|partial [--reason <short>] [--client <name>]
+npx kloudy@latest feedback --flush
 npx kloudy@latest bots search <words> --offline
 npx kloudy@latest bots get <id> --offline
 ```
 
 Each recommended bot includes `id`, `class` (A, B, or O), `command`, `license`, a one-line `description`, and `why`. `command` is an `npx` or `uvx` invocation, or a URL for a live endpoint or source repo. Run or open that command when you want to install or connect. `recommend` itself does not install anything. Inspect a pick with `bots get` before running it.
 
-`recommend` splits the goal on commas, semicolons, and the words `and` and `then`, and it also splits a clause when keywords hit different modalities. You get one section per part, with the top bots in each needed modality (class A, then B, then O, then the same primary-modality, score, and index ordering as catalog search). A part with no modality or no catalog row stays in `unmatched` with the part text and a reason. It is not dropped.
+Write the goal as one sentence per need, or as a comma-separated list of needs. A long sentence is still accepted. Clearer parts produce a clearer stack.
+
+`recommend` splits the goal on commas, semicolons, and the words `and` and `then`, and it also splits a clause when keywords hit different modalities. You get one section per part. Each part includes `candidatesTotal` (how many eligible candidates existed before the cap) and `bots` (the capped list). Narrow that capped list with the project you have open: language, frameworks, licenses, and tools already in the repo. Kloudy never runs an LLM and does not read the project to pick a bot.
+
+Order is class A, then B, then O, then score override (boost, then unchanged, then demote), then the same primary-modality, keyword, score, and index ordering as catalog search. Exclude removes a bot before the cap. Familiar modality words such as transcribe, summarize, and database still return the top bots in that modality. A narrower need, such as a watch, a timer, Android sync, a meal plan, or a social post, keeps only bots that share a real keyword or a clearly related catalog name, id, or cap with that part. Unrelated bots are not filler. A part with no modality or no catalog row stays in `unmatched` with the part text and a reason. It is not dropped.
+
+`phone`, `call`, and `calls` are `audio` only when an audio cue is in the same part or clause (transcribe, transcription, voice, speech, audio, whisper, microphone, asr, phone call, or call audio). Otherwise phone, Android, and mobile are device sync, not audio.
+
+Each part includes `confidence` (`match`, `weak`, or `none`). Top-level `complete` is true only when every part is `match` and `gaps` is empty. `complete` false means the stack is partial. `gaps` lists unmatched and weak parts with the part text, confidence, and a reason. `kind` `catalog integration` means a catalog bot with an install or run command is a real but weak hit. `kind` `suggestion: build yourself / platform API` means the catalog does not cover the need (Wear OS sensor APIs, Health Connect, or the Facebook Graph API, for example). That suggestion is unverified non-catalog guidance, not a catalog bot.
+
+Every recommend result includes `limit`, `stackId`, and `feedback`. `stackId` is a sha256 of the goal's parts plus the chosen bot ids. The same parts and the same picks always produce the same `stackId`. `feedback` is the command to run after you try a bot. Put that bot's id in place of `<id>`.
+
+After you try a stack, report whether it worked:
+
+```sh
+kloudy feedback --stack <stackId> --bot <botId> --result worked|failed|partial [--reason <short>] [--client <name>]
+```
+
+`--result` is `worked`, `failed`, or `partial`. `--reason` is optional and short: it is truncated to 80 characters, and a path, token, or email is dropped. `--client` is an optional tool name such as `cursor`, `claude`, `codex`, or `vscode`. It counts distinct clients. Do not pass a person, email, or account. The report is opt-in and anonymous. The payload may include only `stackId`, `botId`, `result`, an optional short `reason`, the kloudy version, and an optional client name. It never includes the goal text, personal info, file paths, environment, or tokens. The POST goes to `https://kloudy.ai/api/feedback`. If the network is down or the POST fails, the report is queued in the Kloudy data directory and sent on the next `kloudy feedback` or `kloudy feedback --flush`.
+
+Score overrides come from those anonymous reports. `scripts/aggregate-feedback-scores.mjs` is meant to run weekly Sunday 3:00 America/Phoenix. It writes `feedback-scores.json`. Bots with fewer than 3 reports are ignored. A bot is demoted after it fails for 3 or more distinct clients with a failure ratio of 60% or more. A bot is excluded after 10 or more reports with a failure ratio of 80% or more. A bot is boosted at 5 or more reports when at least 80% are `worked` and it is not demoted or excluded. `partial` counts as a report and counts as neither worked nor failed. Failure ratio is `failed` divided by all reports. Reports without a client still count toward ratios. They do not add a distinct client.
+
+Text output includes Confidence, Candidates, Gaps, `limit`, `stackId`, `feedback`, and `complete=true` or `complete=false`. `--json` still prints only the JSON object.
 
 Single-part example:
 
@@ -57,7 +94,7 @@ Single-part example:
 npx kloudy@latest recommend "voice assistant that transcribes phone calls" --json
 ```
 
-That goal is one audio part. The first of the five bots is `httpk:npm:mendelio-voice-mcp` (class B, MIT, `npx -y mendelio-voice-mcp`).
+That goal is one audio part. The first bot in the capped list is `httpk:npm:mendelio-voice-mcp` (class B, MIT, `npx -y mendelio-voice-mcp`).
 
 Multi-part example:
 
@@ -67,11 +104,13 @@ npx kloudy@latest recommend "voice assistant that transcribes calls, summarizes
 
 That becomes three parts, not one blended search:
 
-1. `voice assistant that transcribes calls` — `audio` — `httpk:npm:mendelio-voice-mcp` — `npx -y mendelio-voice-mcp`
-2. `summarizes them` — `text` — `httpk:mcp:ai.liquidagent.api:liquid-agent` — `https://api.liquidagent.ai/mcp`
-3. `stores them in a database` — `database_access` — `httpk:npm:microsoft:postgres-mcp` — `npx -y @microsoft/postgres-mcp`
+1. `voice assistant that transcribes calls` — `audio` — `httpk:npm:mendelio-voice-mcp` — `npx -y mendelio-voice-mcp`
+2. `summarizes them` — `text` — `httpk:mcp:ai.liquidagent.api:liquid-agent` — `https://api.liquidagent.ai/mcp`
+3. `stores them in a database` — `database_access` — `httpk:npm:microsoft:postgres-mcp` — `npx -y @microsoft/postgres-mcp`
+
+That control stack is complete (`complete` true). Each part is confidence `match`.
 
-A leftover clause such as `weave a basket` is listed under Unmatched (`no modality or catalog match`) instead of disappearing.
+A leftover clause such as `weave a basket` is listed under Unmatched (`no modality or catalog match`) and under Gaps. The goal is then `complete` false.
 
 On first contact, read the agent guide and the command list:
 
@@ -98,7 +137,7 @@ npm start
 npm run card -- /world
 ```
 
-`init` creates a new folder and refuses to overwrite an existing one. `kloudy read https://example.com` and `kloudy card /world` also work directly. These are real public reads, with no model or account call; shared rate limits and website restrictions apply. The public Node exports are `readPublicPage` and `readCard` from `kloudy/public`. Source HTML stays data, never executable UI. The starter’s separate toolbox example requires an existing private connection and selects definitions without executing them.
+`init` creates a new folder and refuses to overwrite an existing one. `kloudy read https://example.com` and `kloudy card /world` also work directly. These are real public reads, with no model or account call; shared rate limits and website restrictions apply. The public Node exports are `readPublicPage` and `readCard` from `kloudy/public`. Source HTML stays data, never executable UI. The starter’s separate toolbox example requires an existing private connection and selects definitions without executing them.
 
 Developer guide and availability: https://kloudy.ai/build. Customer self-registration is separate from these working public examples.
 
@@ -140,7 +179,7 @@ One user installation covers projects. Cursor, Claude Code, VS Code and Codex re
 
 Bare `kloudy`, `Kloudy`, `/kloudy`, and `ask Kloudy` in this CLI return a project-aware introduction before opening an engine session. The MCP tool does the same for `introduce` or an exact attach intent. It classifies known manifest names/dependencies, looks up at most three relevant public catalog names, and asks one install/connect question. Catalog candidates are explicitly non-executable until granted. It never reads `.env`, source contents or another project's checkpoint. With an HTTPK connection, the introduction comes from the real engine's `bbe.attach.v1` intent payload. Without a reachable account/session, the client provides a clearly marked deterministic public-catalog fallback. An unconfigured IDE cannot discover a CLI just from an ordinary chat word: install the MCP adapter first, then invoke the tool or `/kloudy` prompt.
 
-The remote option stores only a bearer **environment-variable reference**. `https://kloudy.ai/mcp` now serves authenticated MCP alongside its human guide. The current hosted engine is a finite development service with separately scoped Notes and bounded Base chain-head read clients; it is not open customer registration. The default local stdio adapter works without hosting. With no explicit connection path, all three clients use `~/.kloudy/connection.json`, the same user session across projects.
+The remote option stores only a bearer **environment-variable reference**. `https://kloudy.ai/mcp` now serves authenticated MCP alongside its human guide. The current hosted engine is a finite development service with separately scoped Notes and bounded Base chain-head read clients; it is not open customer registration. The default local stdio adapter works without hosting. With no explicit connection path, the legacy CLI, legacy MCP and SDK use `~/.kloudy/connection.json`. The remote `kloudy mcp` proxy uses only an explicit connection file or environment token, as described above.
 
 The MCP tool list initially has one `kloudy` entry. An `ask` operation adds only the selected tool as `selected_<engine-name>`. Selecting a new task replaces it; running it clears the selection. Status/cancellation use the Kloudy entry and the same engine request. Model-visible outputs never contain the bearer.
 
@@ -170,7 +209,7 @@ MCP transport compatibility is pinned to the official SDK 1.31.0 and its 2025-11
 
 `npm test` covers real HTTP/stdio round trips, selected-tool isolation, auth/origin rejection, crash handling, shared SDK behavior, explicit approval and safe IDE installation.
 
-The real-engine acceptance script uses a separately provisioned local Blackbox instance and synthetic public metadata, never a mock engine. It exercises CLI → MCP → SDK → autonomous completed Notes result, with no extra approval call. It intentionally requires an explicit test flag:
+The real-engine acceptance script uses a separately provisioned local Blackbox instance and synthetic public metadata, never a mock engine. It exercises CLI → MCP → SDK → autonomous completed Notes result, with no extra approval call. It intentionally requires an explicit test flag:
 
 ```sh
 node scripts/prove.mjs --connection /private/test-connection.json --candidates /path/to/test-cards.json --approve-synthetic
@@ -194,9 +233,9 @@ A standard remote MCP host sees one `kloudy` tool. `introduce` gets the engine g
 
 `node scripts/prove-hosted.mjs` uses an in-memory, expiring test grant and a temporary user config to prove the real public MCP handshake, engine greeting, one selected tool, completed Notes receipt, idempotent replay and SDK readback. It does not claim a visual IDE session or the provider-model failure ladder was tested. Those remaining checks are recorded in Shared.
 
-## Selected Toolboxes — 0.3.1
+## Selected Toolboxes — 0.3.1
 
-With a scoped HTTPK connection, each ask returns its engine selection_id. Collect 1–16 distinct IDs from that same session. Assembly is passive: no model, action or approval runs.
+With a scoped HTTPK connection, each ask returns its engine selection_id. Collect 1–16 distinct IDs from that same session. Assembly is passive: no model, action or approval runs.
 
 ```sh
 kloudy ask "read note NOTE_ID" --connection /private/httpk.json
@@ -216,7 +255,7 @@ Open 0.3.4 adds `HttpkClient.confirm({selectionId, token, decision: 'approve', s
 
 The same public MCP gateway accepts `operation: 'confirm'`, `selection_id`, `decision: 'approve'`, `source`, and exactly one of `token` or `revision`. Missing binding/source fails closed. `scripts/prove-confirmation.mjs` verifies a real bounded Base read, wrong-token denial, zero execution before approval and receipt replay using an existing finite grant from memory. No provider key is distributed.
 
-## IDE experience — 0.3.4
+## IDE experience — 0.3.4
 
 An already attached MCP host receives a welcome and current-project guidance, not another install question. Kloudy or /kloudy explicitly addresses the service; the IDE may use the same tools for relevant tasks without a prefix. The current task selects a small toolbox; a persistent account connection does not load its tools into every project.
 
@@ -235,7 +274,7 @@ const list = await convertPages(['https://example.com', 'https://example.com/mis
 console.log(list.cards, list.reports); // Each unreadable source is reported.
 ```
 
-MCP's single `kloudy` door also accepts `operation: "convert", url` or `operation: "yield_list", urls` (1–8). No account is needed for these public reads. The engine owns KLDY query matching and ranking. This client returns content and per-source conversion reports, never a ranked recommendation or permission to execute tools.
+MCP's single `kloudy` door also accepts `operation: "convert", url` or `operation: "yield_list", urls` (1–8). No account is needed for these public reads. The engine owns KLDY query matching and ranking. This client returns content and per-source conversion reports, never a ranked recommendation or permission to execute tools.
 
 Cards validate against the unmodified SDF v0.2 root schema pinned to `sdfprotocol/sdf@e4619ad0b951ced8542692c6b624cb86794cb863` and the additional Kloudy webpage profile. This upstream machine-readable schema differs from its website examples: it uses `sdf:<sha256>`, `summary.brief`, `source.fetched_at`, and section `title`/`summary`. Schemas and upstream MIT notice ship in `schemas/` and at [kloudy.ai/schemas/sdf-webpage-v1.schema.json](https://kloudy.ai/schemas/sdf-webpage-v1.schema.json). `article.x-kloudy-webpage` is our explicit extractive subtype, not a claim that an arbitrary page is a news article. Empty entities mean no semantic entity extraction was performed.
 
@@ -345,7 +384,7 @@ Sources: https://docs.ollama.com/api/tags ; https://docs.ollama.com/api/openai-c
 
 ### Host interface and deterministic replies
 
-HTTPK initialization negotiates chat/text/speech presentation with BBE 0.3.50. It never changes scopes, the credential surface or the approval policy. Older engines remain usable without invented negotiation. `renderReply(state,{action})` from `kloudy/replies` renders bounded JSON templates for observed operation state. Unknown state stays unconfirmed; output is plain text. The browser uses the same templates in its one conversation. Kloudy’s subscription NVIDIA ladder is the text/planning upgrade; supported local Siri/Nano remains voice. Bot Boozle is a separate optional IDE.
+HTTPK initialization negotiates chat/text/speech presentation with BBE 0.3.50. It never changes scopes, the credential surface or the approval policy. Older engines remain usable without invented negotiation. `renderReply(state,{action})` from `kloudy/replies` renders bounded JSON templates for observed operation state. Unknown state stays unconfirmed; output is plain text. The browser uses the same templates in its one conversation. Kloudy’s subscription NVIDIA ladder is the text/planning upgrade; supported local Siri/Nano remains voice. Bot Boozle is a separate optional IDE.
 
 ## Encrypted conversation client
 

package/bin/entry.mjs

@@ -1,25 +1,32 @@
-#!/usr/bin/env node
-import {readFileSync} from 'node:fs';
-const version=JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
-import {createInterface} from 'node:readline/promises';
-import {installEditors} from '../src/editor-install.mjs';
-import {askRemote,serveRemote} from '../src/remote.mjs';
-const args=process.argv.slice(2);
-try{
- if(!args.length||args[0]==='install'&&args.length===1){
-  console.log('Kloudy · Add to your editor\nFree public discovery. Account actions require an authorized Kloudy key.');
-  let rl;
-  const confirm=async({client,path,authenticated})=>{if(!process.stdin.isTTY){console.log(`${client}: skipped — run in an interactive terminal to approve ${path}`);return false;}rl??=createInterface({input:process.stdin,output:process.stdout});return /^(y|yes)$/i.test((await rl.question(`Add Kloudy to ${client}? ${path}${authenticated?' (stores your key)':''} [y/N] `)).trim());};
-  let results;try{results=await installEditors({confirm,key:process.env.KLOUDY_MCP_TOKEN,onResult:r=>console.log(`${r.client}: ${r.state}`)});}finally{rl?.close();}
-  if(!results.length)console.log('No supported editor configuration found. Open https://kloudy.ai/install for setup help.');
-  else console.log('Existing servers were preserved. Restart configured clients to connect.');
-  if(results.some(r=>r.state==='unchanged_error'))process.exitCode=1;
- }else if(args[0]==='mcp'&&args.length===1){await serveRemote();}
- else if(args[0]==='--version'){console.log(version);}
- else if(['--help','help'].includes(args[0]))console.log('npx kloudy                 Add to detected editors (asks before each write)\nnpx kloudy <question>      Ask the public Kloudy MCP endpoint\nnpx kloudy mcp             Remote MCP over local stdio\nnpx kloudy recommend "<goal>" [--json]\nnpx kloudy stack "<goal>" [--json]\nnpx kloudy agents\nnpx kloudy bots list|search|get|sync|works|broken|modalities [--offline]\nnpx kloudy legacy <args>   Existing SDK/engine CLI commands\n\nFree discovery needs no key. For authorized account actions set KLOUDY_MCP_TOKEN privately; never put a key in command arguments. Node 20.19+ required.');
- else if(args[0]==='bots'){const {botsCommand}=await import('../src/bots.mjs');try{await botsCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'bots failed')+'\n');process.exitCode=1;}}
- else if(args[0]==='recommend'||args[0]==='stack'){const {recommendCommand}=await import('../src/recommend.mjs');try{await recommendCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'recommend failed')+'\n');process.exitCode=1;}}
- else if(args[0]==='agents'||args[0]==='agent'){const {agentsCommand}=await import('../src/recommend.mjs');try{agentsCommand();}catch(error){process.stderr.write((error?.message||'agents failed')+'\n');process.exitCode=1;}}
- else if(args[0]==='legacy'){process.argv.splice(2,1);await import('./kloudy.mjs');}
- else{if(args[0]?.startsWith('--'))throw Error('Unknown option');const result=await askRemote(args.join(' '));for(const c of result.content||[])if(c.type==='text')process.stdout.write((process.env.KLOUDY_MCP_TOKEN?c.text.replaceAll(process.env.KLOUDY_MCP_TOKEN,'[redacted]'):c.text)+'\n');if(result.isError)process.exitCode=1;}
-}catch{process.stderr.write('Kloudy could not complete the request. Check your connection or authorized key. No action was retried. Run npx kloudy --help.\n');process.exitCode=1;}
+#!/usr/bin/env node
+import {readFileSync} from 'node:fs';
+const version=JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
+import {createInterface} from 'node:readline/promises';
+import {installEditors} from '../src/editor-install.mjs';
+import {askRemote,serveRemote} from '../src/remote.mjs';
+const args=process.argv.slice(2);
+function remoteArgs(values){
+ const words=[...values],indexes=words.flatMap((value,index)=>value==='--connection'?[index]:[]);let options={};
+ if(indexes.length){const i=indexes[0],file=words[i+1];if(indexes.length!==1||typeof file!=='string'||!file.trim()||file.startsWith('--'))throw Error('Private connection path required');options={connection:file};words.splice(i,2);}
+ if(words.some(value=>value.startsWith('--')))throw Error('Unknown option');
+ return {words,options};
+}
+try{
+ if(!args.length||args[0]==='install'&&args.length===1){
+  console.log('Kloudy · Add to your editor\nFree public discovery. Account actions require an authorized Kloudy key.');
+  let rl;
+  const confirm=async({client,path,authenticated})=>{if(!process.stdin.isTTY){console.log(`${client}: skipped — run in an interactive terminal to approve ${path}`);return false;}rl??=createInterface({input:process.stdin,output:process.stdout});return /^(y|yes)$/i.test((await rl.question(`Add Kloudy to ${client}? ${path}${authenticated?' (stores your key)':''} [y/N] `)).trim());};
+  let results;try{results=await installEditors({confirm,key:process.env.KLOUDY_MCP_TOKEN,onResult:r=>console.log(`${r.client}: ${r.state}`)});}finally{rl?.close();}
+  if(!results.length)console.log('No supported editor configuration found. Open https://kloudy.ai/install for setup help.');
+  else console.log('Existing servers were preserved. Restart configured clients to connect.');
+  if(results.some(r=>r.state==='unchanged_error'))process.exitCode=1;
+ }else if(args[0]==='mcp'){const {words,options}=remoteArgs(args.slice(1));if(words.length)throw Error('Unexpected MCP arguments');await serveRemote(options);}
+ else if(args[0]==='--version'){console.log(version);}
+ else if(['--help','help'].includes(args[0]))console.log('npx kloudy                 Add to detected editors (asks before each write)\nnpx kloudy <question>      Ask the public Kloudy MCP endpoint\nnpx kloudy mcp [--connection PRIVATE_FILE]  Remote MCP over local stdio\nnpx kloudy <question> --connection PRIVATE_FILE  Use an existing scoped connection\nnpx kloudy recommend "<goal>" [--json] [--limit N] [--offline]\nnpx kloudy stack "<goal>" [--json] [--limit N] [--offline]\nnpx kloudy feedback --stack ID --bot ID --result worked|failed|partial [--reason TEXT] [--client NAME] [--flush]\nnpx kloudy agents\nnpx kloudy bots list|search|get|sync|works|broken|modalities [--offline]\nnpx kloudy legacy <args>   Existing SDK/engine CLI commands\n\nFree discovery needs no key. Remote MCP accepts KLOUDY_CONNECTION or --connection for a private scoped connection file, or the existing KLOUDY_MCP_TOKEN. Choose one credential source; no file is read implicitly. This does not issue grants. Never put a key in command arguments. Node 20.19+ required.');
+ else if(args[0]==='bots'){const {botsCommand}=await import('../src/bots.mjs');try{await botsCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'bots failed')+'\n');process.exitCode=1;}}
+ else if(args[0]==='recommend'||args[0]==='stack'){const {recommendCommand}=await import('../src/recommend.mjs');try{await recommendCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'recommend failed')+'\n');process.exitCode=1;}}
+ else if(args[0]==='feedback'){const {feedbackCommand}=await import('../src/feedback.mjs');try{await feedbackCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'feedback failed')+'\n');process.exitCode=1;}}
+ else if(args[0]==='agents'||args[0]==='agent'){const {agentsCommand}=await import('../src/recommend.mjs');try{agentsCommand();}catch(error){process.stderr.write((error?.message||'agents failed')+'\n');process.exitCode=1;}}
+ else if(args[0]==='legacy'){process.argv.splice(2,1);await import('./kloudy.mjs');}
+ else{if(args[0]==='install')throw Error('Remote connection options do not install editors');const {words,options}=remoteArgs(args);if(!words.length)throw Error('Question required');const result=await askRemote(words.join(' '),options);for(const c of result.content||[])if(c.type==='text')process.stdout.write((process.env.KLOUDY_MCP_TOKEN?c.text.replaceAll(process.env.KLOUDY_MCP_TOKEN,'[redacted]'):c.text)+'\n');if(result.isError)process.exitCode=1;}
+}catch{process.stderr.write('Kloudy could not complete the request. Check your connection or authorized key. No action was retried. Run npx kloudy --help.\n');process.exitCode=1;}

package/bin/kloudy.mjs

@@ -19,7 +19,7 @@ try{
  const connection=option('connection')||process.env.KLOUDY_CONNECTION;
  const project=option('project')||process.cwd(),decision=option('decision');
  if(command==='help'||command==='--help'){
-  console.log('Ask for Kloudy. One CLI, one MCP, tools appear when needed.\n\nkloudy models list [--endpoint URL] [--key-env NAME]\nkloudy models run NAME --prompt-file FILE [--max-tokens 128] [--allow-provider-charge]\nkloudy init my-app\nkloudy read https://example.com\nkloudy card /world\nkloudy convert https://example.com\nkloudy query "need" --connection FILE\nkloudy ask "goal" --connection FILE [--candidates FILE]\nkloudy assemble --selections FILE --connection FILE\nkloudy call NAME --inputs FILE [--selection ID] --connection FILE\nkloudy action chain.head --inputs FILE --connection FILE [--idempotency-key KEY]\nkloudy wallet-connect ethereum --connection FILE\nkloudy hosting [--budget-micros 100000000] --connection FILE\nkloudy wallet balance --connection FILE\nkloudy wallet top_up --amount 10.00 --connection FILE\nkloudy conversation read|append|sync --inputs FILE --connection FILE\nkloudy host --connection FILE\nkloudy status --connection FILE\nkloudy cancel --connection FILE\nkloudy mcp --connection FILE\nkloudy introduce [--project DIR] [--decision yes|no]\nkloudy install [--ide cursor|claude|vscode|codex] [--url HTTPS_URL] [--token-env NAME] [--connection FILE]\nkloudy wrap --config FILE [--port 8796]\nkloudy strings save NAME --selections FILE\nkloudy strings use NAME\nkloudy strings call NAME --tool ALIAS --inputs FILE\nkloudy strings list|prune\nkloudy strings keep|remove NAME\nkloudy login\nkloudy recommend <goal> [--json]\nkloudy stack <goal> [--json]\nkloudy agents\nkloudy bots list|search|get|sync|works|broken|modalities [--offline]\n\nRegister with email + short 2FA through the Core account service. Existing engine connections remain usable. Hosted registration is not supplied by this client package.');
+  console.log('Ask for Kloudy. One CLI, one MCP, tools appear when needed.\n\nkloudy models list [--endpoint URL] [--key-env NAME]\nkloudy models run NAME --prompt-file FILE [--max-tokens 128] [--allow-provider-charge]\nkloudy init my-app\nkloudy read https://example.com\nkloudy card /world\nkloudy convert https://example.com\nkloudy query "need" --connection FILE\nkloudy ask "goal" --connection FILE [--candidates FILE]\nkloudy assemble --selections FILE --connection FILE\nkloudy call NAME --inputs FILE [--selection ID] --connection FILE\nkloudy action chain.head --inputs FILE --connection FILE [--idempotency-key KEY]\nkloudy wallet-connect ethereum --connection FILE\nkloudy hosting [--budget-micros 100000000] --connection FILE\nkloudy wallet balance --connection FILE\nkloudy wallet top_up --amount 10.00 --connection FILE\nkloudy conversation read|append|sync --inputs FILE --connection FILE\nkloudy host --connection FILE\nkloudy status --connection FILE\nkloudy cancel --connection FILE\nkloudy mcp --connection FILE\nkloudy introduce [--project DIR] [--decision yes|no]\nkloudy install [--ide cursor|claude|vscode|codex] [--url HTTPS_URL] [--token-env NAME] [--connection FILE]\nkloudy wrap --config FILE [--port 8796]\nkloudy strings save NAME --selections FILE\nkloudy strings use NAME\nkloudy strings call NAME --tool ALIAS --inputs FILE\nkloudy strings list|prune\nkloudy strings keep|remove NAME\nkloudy login\nkloudy recommend <goal> [--json] [--limit N] [--offline]\nkloudy stack <goal> [--json] [--limit N] [--offline]\nkloudy feedback --stack ID --bot ID --result worked|failed|partial [--reason TEXT] [--client NAME] [--flush]\nkloudy agents\nkloudy bots list|search|get|sync|works|broken|modalities [--offline]\n\nRegister with email + short 2FA through the Core account service. Existing engine connections remain usable. Hosted registration is not supplied by this client package.');
  }else if(command==='models'){
   const action=args.shift(),endpoint=option('endpoint'),keyEnv=option('key-env'),file=option('prompt-file'),max=option('max-tokens');
   const allow=args.includes('--allow-provider-charge');if(allow)args.splice(args.indexOf('--allow-provider-charge'),1);
@@ -54,6 +54,9 @@ try{
  }else if(command==='recommend'||command==='stack'){
   const {recommendCommand}=await import('../src/recommend.mjs');
   try{await recommendCommand(args);}catch(error){process.stderr.write((error?.message||'recommend failed')+'\n');process.exitCode=1;}
+ }else if(command==='feedback'){
+  const {feedbackCommand}=await import('../src/feedback.mjs');
+  try{await feedbackCommand(args);}catch(error){process.stderr.write((error?.message||'feedback failed')+'\n');process.exitCode=1;}
  }else if(command==='agents'||command==='agent'){
   const {agentsCommand}=await import('../src/recommend.mjs');
   try{agentsCommand();}catch(error){process.stderr.write((error?.message||'agents failed')+'\n');process.exitCode=1;}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kloudy",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Ask for Kloudy: CLI, MCP and SDK clients for the same scoped engine session.",
   "type": "module",
   "license": "Apache-2.0",
@@ -39,7 +39,7 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "check": "node --check bin/kloudy.mjs && node --check bin/entry.mjs && node --check src/bots.mjs && node --check src/recommend.mjs && node --check src/client.mjs && npm test",
+    "check": "node --check bin/kloudy.mjs && node --check bin/entry.mjs && node --check src/bots.mjs && node --check src/recommend.mjs && node --check src/scores.mjs && node --check src/feedback.mjs && node --check scripts/aggregate-feedback-scores.mjs && node --check src/client.mjs && npm test",
     "bots:bundle": "node scripts/bundle-bots-catalog.mjs --subset full",
     "start": "node bin/kloudy.mjs",
     "proof": "node scripts/prove.mjs",

package/src/chooser-link.mjs

@@ -1,17 +1,17 @@
-// Public presentation adapter. URLs contain public template locators only, never
-// a connection credential, authorization token, goal text or identity claim.
-export const CHOOSER_URL='https://kloudy.ai/api/customer/visual-chooser/start';
-export const pendingChooserTool={name:'show_pending_chooser_link',description:'Show the pending Kloudy card and its HTTPS website fallback again. The website verifies account sign-in; the link is not authorization. This does not run a tool, model, installation or payment.',inputSchema:{type:'object',properties:{},additionalProperties:false},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}};
-export function chooserResponse(result,{apps=false,goal}={}){
- if(!result||typeof result!=='object'||Array.isArray(result)||result.isError)return result;
- const data=result.structuredContent;if(!data||typeof data!=='object'||Array.isArray(data))return result;
- const option=typeof data.selectedOptionId==='string'&&/^[a-z0-9-]{1,80}$/.test(data.selectedOptionId)?data.selectedOptionId:null;
- const set=typeof data.choiceSetId==='string'&&/^visual-[a-f0-9]{1,64}$/.test(data.choiceSetId)?data.choiceSetId:null;
- const url=option&&set?CHOOSER_URL+'#choice='+encodeURIComponent(option)+'&set='+encodeURIComponent(set):CHOOSER_URL;
- const chooser={url,linkIsAuthorization:false,identityFromEmail:false,accountBindingVerified:false,returnMethod:'existing-authenticated-website-project-manifest',automaticIdeReturnVerified:false,...(set?{publicChoiceSetId:set}:{}),...(option?{publicOptionId:option}:{}),...(goal?{request:goal}:{})};
- const text='Website chooser: '+url+'\nOpen this HTTPS link if your host does not show the card. Complete account sign-in/2FA on the website before opening private project choices. Email is a lookup hint, not proof. The host controls card rendering, clickable links and browser launch. Account-bound automatic return is not established by this public template locator.';
- return {...result,content:[...(Array.isArray(result.content)?result.content:[]),{type:'text',text}],structuredContent:{...data,chooser},...(apps?{_meta:{...result._meta,ui:{...result._meta?.ui,resourceUri:'ui://widget/kloudy-visual-setup-v1.html'}}}:{})};
-}
-export function pendingChooserResponse(pending){
- return pending?structuredClone(pending):{content:[{type:'text',text:'No pending chooser is retained in this MCP process. Open '+CHOOSER_URL+' and sign in to recover your existing project. This link is not a bearer token or authorization.'}],structuredContent:{pending:false,chooser:{url:CHOOSER_URL,linkIsAuthorization:false,accountBindingVerified:false}}};
-}
+// Public presentation adapter. URLs contain public template locators only, never
+// a connection credential, authorization token, goal text or identity claim.
+export const CHOOSER_URL='https://kloudy.ai/api/customer/visual-chooser/start';
+export const pendingChooserTool={name:'show_pending_chooser_link',description:'Show the pending Kloudy card and its HTTPS website fallback again. The website verifies account sign-in; the link is not authorization. This does not run a tool, model, installation or payment.',inputSchema:{type:'object',properties:{},additionalProperties:false},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}};
+export function chooserResponse(result,{apps=false,goal}={}){
+ if(!result||typeof result!=='object'||Array.isArray(result)||result.isError)return result;
+ const data=result.structuredContent;if(!data||typeof data!=='object'||Array.isArray(data))return result;
+ const option=typeof data.selectedOptionId==='string'&&/^[a-z0-9-]{1,80}$/.test(data.selectedOptionId)?data.selectedOptionId:null;
+ const set=typeof data.choiceSetId==='string'&&/^visual-[a-f0-9]{1,64}$/.test(data.choiceSetId)?data.choiceSetId:null;
+ const url=option&&set?CHOOSER_URL+'#choice='+encodeURIComponent(option)+'&set='+encodeURIComponent(set):CHOOSER_URL;
+ const chooser={url,linkIsAuthorization:false,identityFromEmail:false,accountBindingVerified:false,returnMethod:'existing-authenticated-website-project-manifest',automaticIdeReturnVerified:false,...(set?{publicChoiceSetId:set}:{}),...(option?{publicOptionId:option}:{}),...(goal?{request:goal}:{})};
+ const text='Website chooser: '+url+'\nOpen this HTTPS link if your host does not show the card. Complete account sign-in/2FA on the website before opening private project choices. Email is a lookup hint, not proof. The host controls card rendering, clickable links and browser launch. Account-bound automatic return is not established by this public template locator.';
+ return {...result,content:[...(Array.isArray(result.content)?result.content:[]),{type:'text',text}],structuredContent:{...data,chooser},...(apps?{_meta:{...result._meta,ui:{...result._meta?.ui,resourceUri:'ui://widget/kloudy-visual-setup-v1.html'}}}:{})};
+}
+export function pendingChooserResponse(pending){
+ return pending?structuredClone(pending):{content:[{type:'text',text:'No pending chooser is retained in this MCP process. Open '+CHOOSER_URL+' and sign in to recover your existing project. This link is not a bearer token or authorization.'}],structuredContent:{pending:false,chooser:{url:CHOOSER_URL,linkIsAuthorization:false,accountBindingVerified:false}}};
+}

package/src/conversation.mjs

@@ -5,10 +5,18 @@ const exact=(v,keys)=>{if(!plain(v)||Object.keys(v).length!==keys.length||keys.s
 const bounded=(v,max)=>typeof v==='string'&&v.trim().length>0&&[...v].length<=max;
 const identifier=(v,max=80)=>typeof v==='string'&&new RegExp(`^[a-zA-Z0-9_.:-]{1,${max}}$`).test(v);
 const integer=v=>Number.isSafeInteger(v)&&v>=0;
-export const conversationOperations=['read','append','sync'];
+export const conversationOperations=['read','append','sync','history/read','history/configure'];
 export function conversationParams(operation,input){
  if(!conversationOperations.includes(operation))bad();
  const common=['project','conversation_id'];
+ if(operation.startsWith('history/')){
+  exact(input,[...common,...(operation==='history/read'?['after_sequence','limit']:['expected_revision','enabled'])]);
+  if(!identifier(input.project)||!identifier(input.conversation_id))bad();
+  if(operation==='history/read'){
+   if(!integer(input.after_sequence)||!Number.isSafeInteger(input.limit)||input.limit<1||input.limit>20)bad();
+  }else if(!integer(input.expected_revision)||input.expected_revision===Number.MAX_SAFE_INTEGER||typeof input.enabled!=='boolean')bad();
+  return structuredClone(input);
+ }
  const keys=operation==='read'?common:[...common,'idempotency_key','expected_revision',...(operation==='sync'?['reason']:['title','user','assistant','decisions','built_artifacts'])];
  exact(input,keys);
  if(!identifier(input.project)||!identifier(input.conversation_id))bad();
@@ -24,6 +32,7 @@ export function conversationParams(operation,input){
  return structuredClone(input);
 }
 export function conversationResult(value,input,operation='read'){
+ if(operation.startsWith('history/'))return historyResult(value,conversationParams(operation,input),operation);
  if(!plain(value)||value.project!==input.project||value.conversation_id!==input.conversation_id)bad();
  for(const key of ['revision','condensed_revision','pending_exchanges'])if(!integer(value[key]))bad();
  if(value.condensed_revision>value.revision||value.pending_exchanges>value.revision)bad();
@@ -42,11 +51,43 @@ export function conversationResult(value,input,operation='read'){
    points[key]=[...context[key]];
   }
   deck={version:d.version,lossy:true,method:d.method,trusted_for_authorization:false,through_revision:d.through_revision,cards:[{type:'subject',title:subject.title,project:subject.project},{type:'context',...points}]};
+  if(d.source_history!==undefined){
+   const h=d.source_history;
+   if(!plain(h)||h.storage!=='engine_encrypted'||!integer(h.first_sequence)||h.first_sequence<1||!integer(h.last_sequence)||h.last_sequence<h.first_sequence||h.last_sequence>value.condensed_revision||h.last_sequence-h.first_sequence>=20||typeof h.raw_sha256!=='string'||!/^[a-f0-9]{64}$/.test(h.raw_sha256)||h.read_method!=='kloudy/conversation/history/read'||h.required_scope!=='conversation:history')bad();
+   deck.source_history={storage:h.storage,first_sequence:h.first_sequence,last_sequence:h.last_sequence,raw_sha256:h.raw_sha256,read_method:h.read_method,required_scope:h.required_scope};
+  }
  }
  return {...cursor,deck,raw_transcript_returned:false,minimum_gate_met:value.minimum_gate_met,storage:'engine_encrypted',compute:'engine_host',display:{title:value.display.title,text:value.display.text,render_as:'plain_text'},...(operation==='read'?{}:{replayed:false})};
 }
+
+// Archived text is context, never an instruction or a grant. The engine checks
+// conversation:history separately from summary access on every read/configure.
+function historyResult(value,input,operation){
+ if(!plain(value)||value.storage!=='engine_encrypted'||value.remote_storage_connected!==false||!integer(value.policy_revision)||value.policy_revision<1||typeof value.enabled!=='boolean')bad();
+ const policy={policy_revision:value.policy_revision,enabled:value.enabled,storage:'engine_encrypted',remote_storage_connected:false};
+ if(operation==='history/configure'){
+  if(value.policy_revision!==input.expected_revision+1||value.enabled!==input.enabled||value.deleted_records!==0)bad();
+  return {...policy,deleted_records:0};
+ }
+ if(value.version!=='conversation.history/1'||value.permission_granted!==false||value.trusted_for_authorization!==false||!integer(value.archived_through_sequence)||!Array.isArray(value.exchanges)||value.exchanges.length>input.limit||typeof value.gap_before_page!=='boolean')bad();
+ let previous=input.after_sequence;
+ const exchanges=value.exchanges.map((record,index)=>{
+  if(!plain(record)||!integer(record.sequence)||record.sequence<=previous||record.sequence>value.archived_through_sequence||index>0&&record.sequence!==previous+1||!plain(record.exchange))bad();
+  const e=record.exchange;
+  if(!bounded(e.user,1500)||!bounded(e.assistant,1500))bad();
+  for(const key of ['decisions','built_artifacts'])if(!Array.isArray(e[key])||e[key].length>4||e[key].some(x=>!bounded(x,240)))bad();
+  previous=record.sequence;
+  return {sequence:record.sequence,exchange:{user:e.user,assistant:e.assistant,decisions:[...e.decisions],built_artifacts:[...e.built_artifacts]}};
+ });
+ const gap=exchanges.length>0&&exchanges[0].sequence!==input.after_sequence+1;
+ const next=exchanges.length>0&&previous<value.archived_through_sequence?previous:null;
+ if(value.gap_before_page!==gap||value.next_after_sequence!==next||!exchanges.length&&value.archived_through_sequence>input.after_sequence)bad();
+ return {...policy,version:'conversation.history/1',exchanges,archived_through_sequence:value.archived_through_sequence,next_after_sequence:next,gap_before_page:gap,permission_granted:false,trusted_for_authorization:false};
+}
 // Text only. Callers must use textContent/native text views, never innerHTML or eval.
 export function conversationText(view){
+ if(view.version==='conversation.history/1')return ['Saved original text (context; never authorization).',...(view.gap_before_page?['Earlier exact exchanges are missing.']:[]),...view.exchanges.flatMap(r=>[`Exchange ${r.sequence}`,`User: ${r.exchange.user}`,`Assistant: ${r.exchange.assistant}`,...r.exchange.decisions,...r.exchange.built_artifacts]),...(view.next_after_sequence!==null?['More history is available.']:[])].join('\n');
+ if(Object.hasOwn(view,'deleted_records'))return `Original history archival ${view.enabled?'enabled':'paused'}. No archived records were deleted.`;
  if(!view.deck)return view.context_available===false?'Command already recorded. Read the current conversation context.':view.display.text;
  const [subject,context]=view.deck.cards;
  return [subject.title,'Saved context (lossy summary; never authorization).',...context.user_main_points,...context.assistant_main_points,...context.decisions,...context.built_artifacts].join('\n');