@try-works/dsh-righthand 0.1.9 → 0.1.11

package/README.md

@@ -6,7 +6,7 @@ tool guard. Every tool is built on the harness's own services
 (`storageDomain`, `credentials`, `settings`, `subprocess`, `jobs`, `tools`),
 not hand-rolled primitives.
 
-The plugin also ships **blueprint guidance** — ten named recipes for the agent-built tools this plugin exists to compose (see [Blueprints](#blueprints) below) — plus a packaged skill, a settings namespace, and an optional tool guard.
+The plugin also ships **blueprint guidance** — fifteen named recipes for the agent-built tools this plugin exists to compose, six of them committed kits (see [Blueprints](#blueprints) below) — plus a packaged skill, a settings namespace, and an optional tool guard.
 
 ## Install
 
@@ -75,7 +75,10 @@ Namespace "righthand" (registered by the secrets family):
 | `defaultNotifyTopic` | "" | default ntfy topic for `rh_notify_send` |
 
 `rh_settings_get` returns the resolved values; `rh_settings_set` merges a
-partial patch (persisted by the harness settings provider).
+partial patch (persisted by the harness settings provider). Schema wall:
+updates with keys the schema does not define are accepted but never come
+back from `rh_settings_get` — register new keys in the plugin schema, or
+keep ad-hoc knobs in `rh_store`.
 
 ## Blueprints
 
@@ -89,7 +92,11 @@ canonical example of the current DSH-native form (tool-to-tool via
 | Blueprint | What it builds |
 |---|---|
 | `blueprint/daily-digest` | Collect sources, summarize, send on a schedule — extractive locally, LLM synthesis as escalation |
-| `blueprint/data-adapter` | Wrap one keyless public API as a tool family: guarded fetch, normalize, one tool per query. Worked example ships in the plugin: `rh_weather_*` |
+| `blueprint/data-adapter` | Wrap one keyless public API as a tool family: guarded fetch, normalize, one tool per query. Worked examples ship in the plugin: `rh_weather_*`, `rh_places_*` |
+| `blueprint/reminder-flow` | The agent as its own scheduler: `rh_events_*` checked each turn, `rh_notify_send` delivery, one store receipt per event — exactly-once via the state flip |
+| `blueprint/geo-context` | A place query becomes agent context: geocode, then elevation + weather + air + nearby at those coordinates, TTL-cached in `rh_store` |
+| `blueprint/governed-exec` | Every high-impact command as a governed, receipted step: guard gates the prefix, `rh_run` collects, the store keeps the before/after undo trail |
+| `blueprint/file-vault` | R2 as the agent's file system with the store as the index: `rh_files_*` blobs + metadata records + time-boxed presigned shares |
 | (phase 5) `rh_files_*` on R2 | The first family on an actual Cloudflare primitive: S3-compatible API, SigV4 signing pinned to the AWS test vector, credentials from the credential provider |
 | `blueprint/research-radar` | Multi-source research over a rolling window (Reddit, X, YouTube, HN, Polymarket, web): score, dedupe, synthesize with citations |
 | `blueprint/web-scraper` | Fetch a page, extract title/headings/links/text, make it searchable — static HTML first, render/vision as escalation |
@@ -108,6 +115,12 @@ families worth adding, from the tools catalogue + permission commit) and
 from the whole repo — single-source specs, golden permissions, layering,
 held-state gates, SSRF guarding).
 
+[`docs/scenario-patterns.md`](docs/scenario-patterns.md) is the guidance
+built by actually running the tools: key-prefix conventions, the receipt
+pattern, undo trails, the settings schema wall, credential auth gates, and
+exec collect-vs-background — each pattern live-verified against the real
+harness services.
+
 ## Packaged skill
 
 The plugin ships the `dsh-righthand` skill

package/docs/agent-tool-catalog.md

@@ -0,0 +1,188 @@
+# Agent tool catalog — analysis of micro.mu/tools + the permission commit
+
+Source material:
+- https://micro.mu/tools — the Mu tool catalogue (~30 services, ~130 methods,
+  every method an agent-callable tool).
+- https://github.com/micro/mu/commit/4933862770d706f6c56e0ab2af287070811fc52d —
+  "five permission flags become two": the permission-model commit.
+
+## What the commit teaches (apply to guard-tools)
+
+The commit collapses five declared flags into two derived facts:
+
+| Mu model | Meaning |
+|---|---|
+| `Requires: Open` | anybody, including nobody at all |
+| `Requires: Caller` | somebody — a funded wallet counts; enough for anything scoped to "theirs" (own notes, own files) |
+| `Requires: Account` | a real account, not just a wallet — requests made *on somebody's behalf* (fetch any URL you name) or spending a shared reputation (mail.Send); "rationing needs somebody to ration" |
+| `Destructive` | an irreversible effect nobody asked for; the flag exists because tool *descriptions* are attacker-controlled text, so a tool that holds one is a prompt-injection surface |
+
+Lessons for righthand's guard:
+1. Mu's identity tiers (Open/Caller/Account) and its `limit` per-day counts
+   are **not applicable** here: righthand is a single user — the tools are
+   built by that user's own agent and run locally or on the user's own
+   Cloudflare account. There are no accounts to tier and nothing to ration.
+   What *does* carry over is the **destructive marker**: an irreversible
+   effect the agent's own tool descriptions could talk it into (a deploy, a
+   delete, a DNS change) is the prompt-injection surface the guard exists
+   for, and prefix-based allow/deny/ask already covers it — the marker just
+   makes the reasoning explicit.
+2. **Golden-file the derived permissions** (`test/permissions.golden`):
+   baseline every tool's permission from the derived policy and let the test
+   fail when one changes. The commit's own debugging is the guidance: the
+   golden first recorded *nothing* (registering a service is not deriving its
+   tools), then recorded only the derived policy (and missed the exact
+   distinction being collapsed), then recorded prices (failed on test order).
+   It now records permissions alone, sees the change, and is stable.
+   Righthand equivalent: a `tests/permissions.golden` over every `rh_*` tool.
+
+## Tool families Mu ships, mapped onto righthand primitives
+
+Legend: **have** = the harness/righthand already provides this;
+**add** = a new righthand family worth building; **data** = a keyless-API
+adapter (blueprint material); **skip** = instance-local social or
+third-party-keyed, out of scope for the core plugin.
+
+### Already provided (no work — document as guidance, don't rebuild)
+
+| Mu | Righthand/harness equivalent |
+|---|---|
+| shell_run / shell_write | `rh_run` / `rh_run_bg` + `ctx.fs` write tools |
+| web_fetch / web_search / browser_read / browser_shot | harness `web_search` + browser tools + `blueprint/web-scraper` |
+| notes_add/get/list/delete | `rh_store_*` (the notes pattern, scenario 2) |
+| tasks_create/list/update/next | `rh_store_*` task board (documented use case) — candidate for a typed `rh_task_*` family |
+| recall_list/search/conversation | harness session services (`session-query-sqlite`, `session` projection) |
+| docs_write/read/list | `ctx.fs` read/write/edit tools (store keyed index is the delta) |
+
+### New righthand families worth adding (core plugin)
+
+| Family | Mu analogue | Backing | Effort |
+|---|---|---|---|
+| `rh_task_*` | tasks_* | `rh_store` domain `tasks` (state machine: open → done, `tasks_next`) | small — the store family already proves the pattern |
+| `rh_text_*` | text_classify / text_extract / text_summarise / text_translate | `ctx.llm` (same route as digest summaries) | small — JSON-constrained prompts, one tool per verb |
+| `rh_files_*` | files_put/get/list/share | Cloudflare R2 (put → object URL; share → public/private toggle) | medium — first real "Cloudflare primitive" family |
+| `rh_notify_*` | notify_send/devices | ntfy.sh topic (keyless — the topic name is the only secret, no token) or web-push (self-generated VAPID); store device/topic registry in `rh_store` | small |
+| `rh_events_*` | events_create/list/free | `rh_store` + Cloudflare cron trigger (or OS scheduler locally) | medium — scheduling is the hard half |
+
+### Keyless data adapters (blueprint material — one pattern, many tools)
+
+> Constraint (2026-08-30): third-party services are allowed **only when they
+> need no API token or credentials** — keyless public endpoints. Anything
+> that needs a key (Twilio, Resend, paid tiers) is out. All of these are
+> keyless.
+
+These are all the same shape as `blueprint/daily-digest` + `research-radar`
+adapters: a keyless HTTP API, a probe + fixture test, normalize, cache in
+`rh_store`, optional LLM summarization. One `blueprint/data-adapter` recipe
+would generate the whole set.
+
+| Mu | Keyless source |
+|---|---|
+| weather_air / weather_forecast / weather_history / weather_marine | Open-Meteo (no key) |
+| places_geocode / places_address / places_elevation / places_nearby / places_search | Nominatim (OSM), no key — **shipped 0.1.9** as `rh_places_geocode` / `rh_places_address` / `rh_places_elevation` / `rh_places_nearby` (search is covered by geocode) |
+| flights_airport / flights_overhead / flights_track | OpenSky Network (anonymous tier) |
+| hazards_quakes / hazards_alerts / hazards_floods | USGS / GDACS / UK EA flood API |
+| food_product / food_search | Open Food Facts (no key) |
+| markets_convert / markets_list | CoinGecko / exchangerate APIs (free tier) |
+| routes_directions / routes_eta / routes_nearest | OSRM public server |
+| maps_tile / maps_area | static tile URLs (OSM) |
+| news_list / news_read / news_search | RSS + index (the daily-digest fetcher generalised) |
+
+### Out of scope for the core plugin (note in guidance, don't build)
+
+| Mu | Why skip |
+|---|---|
+| prayer_* (times, qibla, verse, hadith, reflection, search) | Muslim/Islamic tools are out of scope by explicit instruction |
+| mail_send / mail_inbox | needs a mail provider key (Resend/MailChannels) — violates the keyless rule; account-scoped reputation |
+| sms_send / sms_history | Twilio-style key — violates the keyless rule |
+| images_generate | Workers AI image gen is the natural fit — the user's own Cloudflare account, optional paid plugin |
+| wallet_* (USDC on Base) | custodial payments, regulatory surface |
+| chat/social/stream/blog/users | instance-local social graph — nothing to attach to in a personal harness |
+| apps_create/build/fork | a whole hosting surface; closest righthand form is Cloudflare Workers deployment (`blueprint/vision-worker` shape), a phase-2 plugin |
+| transit_* (TfL) | UK-only, keyed in parts; a data adapter if a user asks |
+
+## Suggested build order
+
+> Constraint (2026-08-30): TypeScript only, no Go. Single user — no accounts,
+> no rationing, no identity tiers. Every tool is built by the user's own
+> agent and runs locally or on the user's own Cloudflare account. The
+> `requires`/`limit` axes from Mu are dropped; the `destructive` marker and
+> the golden-file discipline stay.
+
+1. **Guard upgrade**: `destructive: true` marker on guard rules + a
+   `tests/permissions.golden` over all `rh_*` tools recording destructive
+   flags and guard modes. Prefix-based allow/deny/ask stays — the marker
+   documents *why* a prefix is guarded, and the golden catches drift.
+2. **`rh_task_*` + `rh_text_*`** — both tiny over existing services, and
+   together they cover Mu's most-used families (tasks, notes, text).
+3. **One data-adapter blueprint** (weather or places as the demo) + the
+   recipe that generates the rest, all running locally or as the user's own
+   Workers.
+4. **`rh_files_*` on R2** — the first family that is *actually on a
+   Cloudflare primitive* (the user's own R2), the plugin's stated purpose.
+5. `rh_events_*`, `rh_notify_*`, then the out-of-scope list as optional
+   plugins.
+
+## Incorporation decisions (from mu-repo-analysis.md)
+
+> Constraints (2026-08-30): **TypeScript only — no Go.** Single user —
+> **no accounts, no rationing**: nothing to tier, nothing to meter per-day.
+> Every tool is built by the user's own agent and runs locally or on the
+> user's own Cloudflare account. Mu lessons that presuppose a multi-user
+> server (identity tiers, limits, quotas, wallets, address spaces) are out;
+> the engineering discipline carries over.
+
+The architecture read produced eleven lessons; these are the ones worth
+incorporating now, each mapped to a concrete righthand change, in order.
+Deliberately NOT incorporated below the fold.
+
+### Incorporate now
+
+1. **Permissions golden first** (Mu lesson 2). Record the answer before
+   changing the model: `tests/permissions.golden`, one line per `rh_*` tool
+   recording its **destructive flag** and guard mode. Any guard refactor
+   that leaves the file unchanged is behaviour-preserving; any diff is the
+   list of doors that moved.
+2. **Guard rules gain a `destructive` marker** (lessons 2). Prefix-based
+   allow/deny/ask stays; `destructive: true` documents *why* a prefix is
+   guarded — irreversible effects (deploy, delete, DNS change) are the
+   prompt-injection surface. The marker is declarative only: the enforcement
+   is still the rule's mode. No identity tiers, no limits — there is one
+   user and nothing to ration.
+3. **Scope = catalogue** (lesson 10). The visible catalogue and the
+   enforceable scope must be one mechanism: the SKILL.md and README tool
+   tables must state what a guard rule gates, and the golden must derive
+   from the same declaration — no second hand-kept list.
+4. **`rh_task_*` family** (lesson 4). Tasks domain over the store:
+   create/list/next/update/delete with a state machine; descriptions carry
+   the "always say something" rule — a failed run is delivered like an
+   answer.
+5. **`rh_text_*` family** (lesson 7). summarise/extract/classify/translate
+   over `ctx.llm`, reusing the digest summarizer's prompt discipline: roles
+   stay roles, caps are deliberate, per-call failure contained.
+6. **Settings hygiene** (lesson 11). Every settings key must have a
+   consumer or go. The namespace holds the user's own Cloudflare account
+   facts (`accountId`, `defaultZone`, `defaultScriptPrefix`) — no pricing,
+   no limits.
+7. **Data-adapter blueprint with the SSRF checklist** (lesson 6). The
+   fetcher blueprint guidance must carry: block non-public destinations,
+   revalidate every redirect hop, cap size and time. Adapters may call any
+   **keyless** public endpoint — an API token requirement is the line that
+   puts a service out of scope.
+
+### Deliberately not incorporated
+
+| Mu feature | Reason |
+|---|---|
+| Go services / handlers | righthand is TypeScript on the DSH harness |
+| `requires` identity tiers (Open/Caller/Account) | single user — no accounts to tier |
+| `limit` per-day counts / quota.json pricing | single user — nothing to ration, nothing to meter |
+| Spec.Card renderers | the web GUI owns turn summaries; righthand outputs carry `fetchedAt` instead |
+| held-state judge (agent/gate) | guard `ask` is the local judge; a full inbound queue needs a product surface |
+| agents-as-accounts / inbox address space | a product, not a plugin — the DSH harness already is the agent host |
+| wallet_* (USDC, x402) | payments/regulatory surface, absent by design |
+| memory-as-history fix | already how the DSH agent loop works — only prompt-building tools inherit the rule |
+| internal/ layering test | Cordis + the harness enforce the equivalent; the tool-to-tool rule goes in guidance instead |
+| keyed third parties (Twilio, Resend, paid APIs) | the keyless rule: any service that requires an API token or credentials is out |
+| prayer_* / Muslim or Islam-related tools | out of scope by explicit instruction |
+

package/docs/mu-repo-analysis.md

@@ -0,0 +1,194 @@
+# Mu repository analysis — architecture lessons for righthand
+
+Source: https://github.com/micro/mu (Go, ~1200 go files). This is the
+*architecture* read of the repo, not the tool list — that is in
+[agent-tool-catalog.md](agent-tool-catalog.md). Each section names the Mu
+mechanism, the failure it fixed, and the righthand/DSH equivalent to adopt
+or adapt.
+
+## 1. One declaration, every surface derives (internal/service/spec.go)
+
+Every service declares itself once — name, description, page, icon,
+endpoints with model-facing docs, cost, permissions, and a Card renderer —
+and every surface *derives* from that Spec: MCP tool list, REST reference,
+nav, guest allowlists, agent labels, the destructive list, the account-
+scoped list, pricing ops, and two documentation tables. Before the Spec
+there were **fourteen hand-written lists**, each correct alone and none
+aware of the others — the same capability was called search, search_web,
+index and web_search at once, and Stream and Chat shared an icon for months
+because nothing could notice the repeat.
+
+**Righthand equivalent:** the `rh_*` tool family. Today each tool declares
+its description/params/output inline in `defineTool`. The Mu lesson is to
+declare the *spec* once and derive the catalogue — in DSH the tool registry
+already derives the model-facing list; what righthand should add is the
+derived **permissions golden** (§2) and a derived **docs table** (README,
+skill, catalog) rather than hand-kept lists.
+
+## 2. Golden-file the derived permissions (test/permissions.golden)
+
+`permissions.golden` records one line per tool — needsAccount, destructive,
+bound/open, accountOnly, optionalAuth — and the test fails when any derived
+permission moves. The file's own debugging is the guidance: the first
+version recorded **nothing** (registering a service is not deriving its
+tools — an empty golden that passed, worse than none because it looks like
+cover); the second recorded only the derived policy and missed the exact
+distinction being collapsed; the third recorded prices and failed on test
+order. It now records permissions alone, sees the change, and is stable.
+
+**Righthand equivalent:** `tests/permissions.golden` over every `rh_*` tool
+(and, once they exist, the rt_* test tools): one line per tool with the
+guard-relevant facts. Refactors that are behaviour-preserving leave the file
+untouched; any diff is the list of doors that moved.
+
+## 3. Layer discipline, asserted by test (test/layering_test.go)
+
+Product packages (home, agent, service, admin, account) may import
+internal/; internal/ may never import the product, with two exceptions —
+the assembly programs. The rule is enforced by a regex test, and the bill
+for every past violation is legible: internal/server/hooks.go, seven hundred
+lines of function variables whose only job was to hand one package a pointer
+to another because they could not import each other. Also: a service may
+not import the wallet — asking what something costs is internal/quota, which
+knows prices and not balances.
+
+**Righthand equivalent:** the tool modules are already thin consumers over
+harness services. The rule to write down: a tool module answers a question
+about state; an *agent* (or a digest-type helper) decides which question to
+ask — services announce events, agents subscribe (Mu's agent/gate,
+agent/work, agent/digest all work this way). In DSH terms that is
+`ctx.on(...)` + the session-watcher blueprint, never a tool that imports
+another tool's internals — call it by name through `ctx.tools.execute`.
+
+## 4. Agents are accounts; work is assigned, not invoked
+
+An agent is a user in the same address space — it holds an address
+(mail/XMPP) and can be written to. Tasks assign work (`service/tasks` holds
+it, `agent/work` runs it); a standing instruction falling due and a task
+assigned are the same fact. Results always say something: a run that could
+not happen is delivered like an answer, because "a standing instruction
+that goes quiet looks like the instruction was forgotten."
+
+**Righthand equivalent:** `rh_task_*` (already the top build item in the
+catalog doc) + `blueprint/session-watcher` for standing instructions. The
+"always say something" rule belongs in the tool descriptions: a failed
+scheduled job must produce a visible record, not silence.
+
+## 5. The held state — fail visible, release when in doubt (agent/gate, internal/thread)
+
+A conversation is in the record or it is not; the binary is what made
+unsolicited inbound impossible to handle (dropping is undetectable, filing
+wakes a paid agent). So: **held** — in the record, visible, searchable, and
+nothing acts on it until a judge (one model call per arrival) releases it.
+The judge is *reluctant on purpose*: the costly mistake is holding a real
+message (the plumber texting he is outside), so the prompt releases when in
+doubt. Fail-safe direction: if the model is down, arrivals sit held and
+visible — never silently dropped.
+
+**Righthand equivalent:** guard `ask` mode is the local judge; the posture
+to copy is: deny loudly and visibly, never silently drop, and when in doubt
+let it through. Also relevant to `blueprint/inbound-webhook-pipeline`'s
+idempotency dedupe.
+
+## 6. Defensive web: safefetch (SSRF guard) + safety (generation policy)
+
+`internal/safefetch`: an SSRF-guarded HTTP client for fetching untrusted
+URLs — refuses loopback, private ranges, link-local (including the
+169.254.169.254 metadata address), and multicast; validates **every
+redirect hop**, not just the first; caps response size (2 MiB) and time
+(10 s). `internal/safety`: what the instance will not *generate* — one
+category refused always and not configurable, one category refused by
+default and an operator's decision; a door, not a classifier ("it stops
+casual misuse and raises the cost of the rest").
+
+**Righthand equivalent:** the harness's web tools already own SSRF
+protection; the blueprint guidance for any righthand fetcher should carry
+the checklist (block non-public destinations, revalidate redirects, cap
+size/time) and the generation-policy split belongs in the guard/skill
+guidance, not per-tool ad hoc.
+
+## 7. Memory is real message history (agent/memory.go)
+
+The conversation went to the model as prose inside one user message, with
+assistant turns truncated to 300 chars and the whole blob sent twice. The
+model never saw its own turns as its own; truncation made "what was the
+third thing you listed?" unanswerable by construction. The fix: turns in
+their real roles, nothing truncated, nothing duplicated.
+
+**Righthand equivalent:** already the harness model (the DSH agent loop
+does exactly this). For tools that *build prompts* — the digest summarizer,
+any rh_text_* tool — the rule is the same: assistant content stays assistant
+content, and input caps must be deliberate, not string-worries.
+
+## 8. Cards: a view, not a widget — and time is the missing field (Spec.Card)
+
+Each service can render a Card; the field that mattered was `At` — a
+headline from four minutes ago and a forecast are different kinds of thing,
+so a card that knows when belongs in a chronology (stream) and one that
+does not is a standing view. The Viewer is a struct ("who is looking" is
+domain data, not context values), and the zero value is the shared render,
+safe to cache; personal renders must never be cached. A card is a view — it
+renders and links, holds no state and takes no input.
+
+**Righthand equivalent:** the digest MDX already records `fetchedAt`; the
+same discipline generalises — any rh_* summary output should say *when what
+it shows happened* so a stream can order it honestly.
+
+## 9. Pricing: price vs limit, and an operator file (quota.json)
+
+An operation is charged when it costs the instance something (a model call
+or third-party request); storage and talking-to-your-agent are 0 because
+they have no marginal cost — charging taxed exactly the behaviour the
+product wants more of. `limit` is a hard per-day count, checked *before*
+price, for the operations that reach a stranger — a price stops somebody
+who has to pay and does nothing about a loop. quota.json is an operator's
+file, not code.
+
+**Righthand equivalent:** the settings namespace is the quota.json slot;
+the split belongs in guard rules (a rate/limit axis beside allow/deny/ask).
+
+## 10. Tool scoping: the list follows the token (internal/api/listscope)
+
+Scoping was enforced at dispatch and ignored by tools/list, so a confined
+agent was handed every tool definition and found out by trial and error
+that almost all were refused — the context cost of the whole catalogue and
+none of its use. Fixed: the listing follows the token's scope; an explicit
+`?tools=` list can only narrow further.
+
+**Righthand equivalent:** guard rules are the scope; the lesson is that the
+*visible* catalogue and the *enforceable* scope must be one mechanism, or
+the agent pays context for tools it cannot use.
+
+## 11. Delete the dead switch (one model tier; five flags → two)
+
+Two recurring refactors: the Fast/Best model tier outlived its only control
+(nothing sent the field) and was deleted — "a premium tier needs a control,
+a price somebody has decided on, and something on the page saying what the
+difference buys... not a switch to leave lying around"; and the permission
+flags collapsed from five to two because three of them were three ways of
+saying the same thing and one was dead code nobody had ever set.
+
+**Righthand equivalent:** every config key in the righthand settings
+namespace must have a consumer or go; every guard rule field must have a
+meaning a test can see (the golden file is what makes the difference
+visible).
+
+## What this means for the righthand build order
+
+> Constraints (2026-08-30): TypeScript only — no Go. Single user — no
+> accounts, no rationing: Mu's identity tiers (`requires`) and per-day
+> `limit` counts are out; the `destructive` marker and the golden-file
+> discipline stay. Tools are built by the user's own agent and run locally
+> or on the user's own Cloudflare account.
+
+1. **Spec + golden first**: a permissions.golden over the existing `rh_*`
+   tools, then the `destructive` marker it records. This is Mu's own
+   ordering — record the answer before changing the model.
+2. **`rh_task_*` + `rh_text_*`** (catalog doc §build order) — tasks
+   implements §4 (assigned work, always say something), text implements
+   §7's prompt discipline.
+3. **Data adapters with the safefetch checklist** in the blueprint guidance
+   — §6.
+4. **Scope = catalogue**: when guard scoping lands, the skill/catalog text
+   must reflect the same rule — §10.
+

package/docs/scenario-patterns.md

@@ -0,0 +1,107 @@
+# Scenario patterns - righthand recipes, tested by building
+
+> Every recipe here ran live on 2026-08-31 against the real harness
+> services (store, settings, credentials, subprocess, jobs) through the
+> agent-facing `rh_*` tools, then the state was cleaned back up. Evidence
+> of each run is inline; re-run them any time - they are safe.
+
+## The key conventions (one store, many collections)
+
+`rh_store_*` is one key space. The prefix IS the collection;
+`rh_store_list` + a prefix filter is the query language. Conventions:
+
+| Prefix | Collection | Example value shape |
+|---|---|---|
+| `task:` | task board | `{ state: 'open', result? }` |
+| `digest:` | daily digests | `{ top: [...], fetchedAt }` |
+| `run:` / `uptime:` / `expense:` | dated logs | one record per date, aggregate by scan |
+| `deploy:` / `dns:` / `tidy:` / `smoke:` | receipts and undo trails | `{ before, after, exitCode, at }` |
+| anything else | ad-hoc | JSON-serializable only |
+
+Absence is `{ found: false }`, not an error - that is the exists() check.
+Every `rh_store_put` returns a global `writes` counter; the increment
+sequence is the audit trail.
+
+## The receipt pattern (scenario 4, live-verified)
+
+Build with `rh_run`, keep the result as one receipt key:
+
+```
+rh_run { argv: ['node', 'scripts/fetch-digest.mjs', 'tests/fixtures/day2.json', '5'], cwd: 'D:/righthand-test' }
+// -> exit 0, stdout = the fetcher's JSON (parse it in the caller)
+rh_store_put { key: 'digest:scenario-test:2026-08-31',
+               value: { source: 'day2.json', count: 2, fresh: ['4'],
+                        top: [{ id: '4', title: '...' }], fetchedAt: '<iso>' } }
+rh_store_get { key: 'digest:scenario-test:2026-08-31' }  // found: true, full value back
+rh_store_delete { key: 'digest:scenario-test:2026-08-31' } // clean up when done
+```
+
+The diff step that makes a digest a digest: fetch today and yesterday,
+compare id sets in the caller, store only `fresh` in the receipt.
+
+## Undo trails (scenario 7 pattern)
+
+Any mutating build writes what it is about to change BEFORE doing it,
+then the after-state:
+
+```
+rh_store_put { key: 'tidy:<ts>', value: { moved: [{ from, to }], at: '<iso>' } }
+// ... do the moves with rh_run ...
+// revert = read tidy:<ts> and move each { to -> from } in reverse
+```
+
+## Settings: the schema wall (live finding)
+
+`rh_settings_set` accepts any patch - including keys the schema does not
+define: `{ weeklyBudget: 200 }` returned `applied: true`. But
+`rh_settings_get` only ever returns schema-known keys, so the custom key
+never comes back. A scenario that needs its own config knob has exactly
+two honest options:
+
+1. register the key in the righthand settings schema (a plugin change), or
+2. keep the knob in `rh_store` under its own prefix.
+
+Never depend on an unregistered settings key - it looks written and
+silently disappears.
+
+## Credentials: the auth gate (scenario 1/2, live-verified)
+
+`rh_credential_describe` is the first step of any Cloudflare scenario and
+it answers yes/no without leaking the value:
+
+```
+rh_credential_describe { ref: 'CLOUDFLARE_API_TOKEN' }
+// { configured: false, writable: true }  -> stop, tell the user what to set
+```
+
+`set` stores, `unset` removes, and no output ever contains the secret
+(live-verified with a throwaway ref: set -> describe configured:true ->
+unset -> configured:false; the value never appeared).
+
+## Exec: collect vs background (live finding)
+
+| | `rh_run` | `rh_run_bg` |
+|---|---|---|
+| Returns | exit code + bounded stdout/stderr | a job id |
+| Use when | you need the output in this turn | the command is long and this turn must go on |
+| Polling | - | the job registry reports status/exit (`job_list` / `job_output`) |
+| Output capture | yes (bounded) | NOT captured by the local registry - status and exit only |
+
+Live-verified: `rh_run` curl returned HTTP headers + exit 0, and a failing
+`node -e` returned exit 3 with stderr. `rh_run_bg` settled completed with
+exit 0 and an empty output tail - background is for fire-and-forget and
+status polling, collect mode is for answers.
+
+## Cleanup discipline
+
+Scenarios write, verify, then delete their keys - the live runs above
+left the store exactly as found (baseline keys only). If a run is a
+deliverable rather than a test, the receipt key stays and IS the record.
+
+## Scenario matrix
+
+`D:/righthand-test/SCENARIOS.md` holds the full tool-per-step matrix for
+nine scenarios (deploy, DNS, grocery, digest, uptime, workout, downloads
+tidy, budget, smoke test). The ones exercised live here: grocery (3),
+digest (4), uptime (5), workout (6), plus the credential/settings/exec
+cross-cuts shared by the rest.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-righthand",
   "description": "DeepSeek Harness plugin: DSH-native righthand tools — durable KV store, credential/settings management, governed exec, and a tool guard",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -74,6 +74,7 @@
     "lib",
     "src",
     "skills",
+    "docs",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"

package/skills/dsh-righthand/SKILL.md

@@ -29,6 +29,8 @@ The righthand toolkit: DSH-native tools over the harness's own services. Use thi
 - One domain `righthand_store`: a `rows` table (string key → JSON value + timestamp) and a global write counter.
 - `rh_store_get` returns `{ found, key, value?, updatedAt? }` — `found: false` means the key is absent, not an error.
 - Writes are durable (backend flush before commit) and serialized on one write chain; values must be JSON-serializable.
+- The key prefix IS the collection (`task:`, `digest:`, `run:`, `uptime:`, `deploy:`); `rh_store_list` + a prefix filter is the query language. See `docs/scenario-patterns.md` for the conventions, the receipt pattern and undo trails.
+- Build, then keep one receipt key per run (`{ ...result, fetchedAt }`) — the store is the agent's durable trail; delete scenario keys when a run is only a test.
 
 ## Events semantics
 
@@ -92,6 +94,8 @@ The righthand toolkit: DSH-native tools over the harness's own services. Use thi
 | `defaultR2Bucket` | `""` | default R2 bucket for `rh_files_*` |
 | `defaultNotifyTopic` | `""` | default ntfy topic for `rh_notify_send` |
 
+Schema wall: `rh_settings_set` accepts keys the schema does not define, but `rh_settings_get` never returns them — an unregistered key looks written and silently disappears. Register new keys in the schema (a plugin change) or keep ad-hoc knobs in `rh_store`.
+
 ## Guard policy
 
 Rules come from the plugin config (`rules: [{ toolPrefix, mode, ask?, destructive? }]`). `deny` throws before dispatch; `ask` defers to the policy function (return true to allow); `allow` passes through. Tools matching no rule are unaffected. Prefixes match by prefix — `rh_run` also covers `rh_run_bg`.
@@ -102,3 +106,7 @@ Rules come from the plugin config (`rules: [{ toolPrefix, mode, ask?, destructiv
 
 - **web profile**: all thirty-seven tools register (`storageDomain` is provided by the web app rows).
 - **other profiles** (e.g. headless): the store, task and events families stay dormant (no `storageDomain`); the other twenty-three tools (secrets, settings, exec, text, weather, places, files, notify) still register. The plugin never fails the boot.
+
+## Composition blueprints
+
+Repo guidance kits under `experiments/` (each a `blueprint.json` spec + recipe + learnings) for composing the tools into routines. Committed kits: `blueprint/daily-digest` (collect → summarize → send), `blueprint/data-adapter` (wrap a keyless API; worked examples `rh_weather_*` / `rh_places_*`), `blueprint/reminder-flow` (events + notify + receipts), `blueprint/geo-context` (places + weather + store cache), `blueprint/governed-exec` (guard + receipts + undo trails), `blueprint/file-vault` (R2 + store index + presigned shares). The README catalogues nine more for future builds; `docs/scenario-patterns.md` holds the live-tested recipes.