insika 0.1.0 → 0.3.0

data/docs/FACTS.md

@@ -0,0 +1,135 @@
+---
+title: Facts
+parent: Operate & prove it
+nav_order: 6
+permalink: /facts/
+---
+
+# Facts — distilled customer memory, human-gated
+
+Finished conversations teach a shop things — the customer's size, their budget,
+how they like to pay — and today that knowledge dies with the session. The
+engine can read it back out of the transcripts: **distillation** turns an idle,
+finished customer conversation into a list of proposed facts, a human approves
+or rejects them in the Studio, and an approved fact lands in the customer's
+memory cell — the same cell the `<memory>` block injects on every later turn.
+
+The loop has one hard rule: **nothing is ever applied automatically.** Zero
+facts reach the store without a click. Distillation proposes; the operator
+decides; the engine never applies its own proposal.
+
+## The loop
+
+1. A customer conversation (a session tagged with a `customer`, per
+   [Context](CONTEXT.md#memory)) goes idle — nobody has written for the
+   configured hours.
+2. The engine's distillation duty picks the session, sends its transcript to
+   the platform `utility_model` (off the turn path, on its own worker fiber),
+   and the model answers with a JSON list of durable facts: `name`, `value`,
+   an optional `confidence`, and the transcript message indexes that support
+   the fact (the **evidence**).
+3. The engine filters the answer against a safe subset (no invented scopes, no
+   oversized values, no out-of-range evidence), dedups it against the ledger,
+   and writes the survivors as **proposals**.
+4. The **Facts** page in the Studio shows the pending proposals with their
+   evidence excerpt. The operator **approves** (the fact is written to the
+   customer's memory, stamped with its origin), **rejects** (optionally with a
+   reason) or **dismisses** (it will never be proposed again).
+5. Approved facts join the customer's memory cell and are injected by the
+   Memory provider on the next turn of any session of that customer.
+
+## Enabling it — the `distill:` block
+
+Distillation is pack data on the agent, exactly like `refinement:` or
+`followup:` — absent = the feature is off for that agent, byte-identical engine:
+
+```ruby
+agent = Insika.agent("store-support") do
+  instructions "…"
+  distill enabled: true,
+          idle_hours: 6,        # how idle a session must be before it distills
+          min_messages: 3,      # a shorter session distills noise, not facts
+          max_proposals: 10     # cap per session pass
+  # prompt: "<what counts as a fact for THIS store>" — the pack-authored half;
+  #   absent = the engine's generic prompt. `model:` (absent = the platform
+  #   utility_model) can name the distiller explicitly.
+end
+```
+
+The same keys work in a pack's `agent.config.json`. `idle_hours` /
+`min_messages` / `max_proposals` are per-agent data; `prompt` is the store's
+half — what counts as a fact for a fashion store ("size, preference, budget")
+is not what counts for a logistics one ("address, delivery window, carrier").
+The engine never writes store vocabulary.
+
+## The human gate, precisely
+
+The **Facts** page (operate group, next to Follow-ups) shows:
+
+- **Pending** — oldest first, because evidence ages. Each card is the fact,
+  its confidence, its scope (`tenant:customer`), and the evidence excerpt read
+  from the transcript at request time (evidence is a link, never a copy). Three
+  buttons: **Approve & save to memory**, **Reject** (with an optional reason,
+  shown on the card), **Dismiss** (ghost — labelled "will not be proposed
+  again").
+- **Stale** — the CAS-lost re-present (below): the proposed value struck
+  through next to the operator's current value, resolved by dismissal.
+- **Recent** — every resolved proposal, most recent first, with operator and
+  note.
+
+**The latch** — a dismissed *or* rejected `(name, value)` tuple is never
+proposed again. The proposal rows ARE the ledger: a human saw that tuple and
+said no, and re-proposing it would train the operator to stop reading. An
+unanswered proposal is never piled on, either. A *different* value for the same
+name is a different tuple — "wears M" dismissed does not block "wears L".
+
+**The CAS guarantee** — approval never silently overwrites an operator edit.
+At distill time the engine records the target fact's existence and revision; at
+approve time it writes through the store's optimistic compare-and-swap. A fact
+the operator moved in between flips the proposal to `stale` with both values
+visible — the operator's edit always wins, never a silent overwrite.
+
+## Provenance
+
+An approved fact is written with `origin: "distilled:<session_ref>"` — the
+RFC-0031 provenance discipline: `"engine"` (the `remember` tool), `"operator"`
+(Studio edits), `"legacy"`, and `"distilled"` (+ the session that produced it).
+The Closed loop reads the same cell every later turn injects, and the
+distillation ledger suppresses re-proposing a fact that is already applied with
+a `distilled:` origin.
+
+## LGPD
+
+Distilled facts are personal data, and the engine treats them like it:
+
+- **Forget a customer** — `forget_customer` purges the customer's proposals
+  (every status) along with their memory cell and sessions.
+- **Delete a tenant** — `delete_tenant_data` purges the tenant's proposals.
+- **Retention** — proposals age out under the same `retention_days` sweep as
+  the rest of the footprint (pending included — a proposal is evidence of a
+  transcript, and when the transcript dies the pending fact is stale). The
+  session marker dies with its proposals: **an unreviewed proposal that ages
+  out is expired, not lost-locked** — the session is re-distillable, and a
+  duplicate survivor is filtered by the ledger, never applied.
+
+## The honest limits
+
+- **Best-effort extraction, re-scan recovery.** There is no distillation
+  queue. A crash mid-pass leaves the session unmarked; the next pass re-scans
+  it, and the ledger filters any duplicate proposal. Exactly-once is not
+  claimed — facts are re-derivable, and a duplicate is filtered, never applied.
+- **Precision is a forge audit.** The engine guarantees the *gates* (schema,
+  dedup, CAS, human approval); it cannot guarantee the *model's judgment*.
+  "Is this fact true and durable?" is audited on real traffic, per store — the
+  pack prompt is where that judgment is tuned.
+- **Scope comes from the session, never the model.** The proposal's landing
+  cell is assembled by the engine from the session's tenant and customer; the
+  schema rejects a model-authored scope outright (a cross-tenant escape), and
+  an untagged session is never distilled.
+- **Sessions only.** Distillation targets customer-tagged sessions; a
+  session without a customer has no landing zone and is skipped.
+- **One stamp, once.** A session receives `vars["agent"]` on the same write
+  that stamps its `customer` — the first tagged turn. The stamp is
+  idempotent: a session that already carries a `customer` (a pre-upgrade
+  conversation, or one that since moved to this agent) never gains `agent`
+  on its own, so it can never participate in distillation.

data/docs/HARVEST.md

@@ -0,0 +1,117 @@
+---
+title: Harvest
+parent: Operate & prove it
+nav_order: 7
+permalink: /harvest/
+---
+
+# Harvest — skills from real traffic, promoted only if eval AND conversion hold
+
+The harvest is the loop that makes a store smarter with its own traffic: it
+reads the store's **finished** conversations, asks a model to propose SKILLS
+for the agent's playbook, filters every proposal through two pre-registered
+lists (the negative list, the evidence ledger), scores it with a double gate,
+and — **only after a human approves** — lands it as a live skill. Nothing is
+ever applied automatically, and a skill that fails the gate is terminal: the
+same finding must re-surface with new evidence, there is no silent retry.
+
+Per-store data (`harvest:` on the agent), absent = the loop is off for that
+agent:
+
+```ruby
+harvest enabled: true,
+        negative_list: [ { rule: "no-competitor-prices", pattern: "concorrente" } ],
+        miner: { model: "deepseek-v4-flash",    # absent = the platform utility_model
+                 window: { last_sessions: 200 },
+                 max_proposals: 10,
+                 budget: { tokens: 100_000 } },
+        idle_hours: 24,      # how idle a session must be before it mines
+        min_messages: 3      # a shorter session mines noise
+```
+
+## The pass
+
+A mine reads ONLY durable, finished data — never an in-flight turn, never a
+live prompt prefix (the "fork" is structural: the mining writes nothing to the
+sessions it read, so a customer turn's cache is untouched by construction). The
+miner gets the transcript slices (masked), the session's evidence-ledger ids,
+and the agent's current skill names so it does not re-propose them. Then the
+filters, each drop counted and logged:
+
+1. **The negative list** — the versioned rules file (seed, imported
+   per store by `insika harvest:negative import --agent ID --file F`) and the
+   profile's hot-editable `harvest.negative_list`. A rule is a phrase or a
+   regex; phrases match case/accent-folded at word boundaries. Every rejected
+   candidate is logged with the rule id.
+2. **The grounding filter** — every product reference in a proposal must be
+   in the union of the origin sessions' evidence ids (RFC-0029's ledger).
+   A store without `grounding.matcher.sku` does not mine at all: product
+   claims that cannot be verified are blocked by refusal, not by prompt.
+3. **Dedup** — an open `(agent, name)` tuple or a skill the store already has.
+
+## The double gate
+
+A candidate that survives mining is scored by RUNNING it — the eval gate
+clones the agent, writes the candidate skill into the clone's agent-scoped
+store, enables it on the clone's allowlist, replays the golden set over the
+ordinary public surface and compares to the accepted baseline. **Any
+regression disqualifies** — the gate is a veto, never a score to argue with.
+Judges are mandatory in exactly the shapes the refinement gate already
+refuses: no recorded baseline, an all-red baseline, and a judged baseline
+replayed with no judge (a rubric'd case with no verdict would count as a
+pass — the P18 lesson, see [Evals](EVALS.md)).
+
+The conversion gate is the second ruler: the store's funnel metric over the
+criterion's window, compared to the **frozen baseline** (the RFC-0032
+`freeze_funnel_baseline`). Outcome is evidence — this gate can only say "the
+store is measurably worse than the accepted state" or "there is nothing to
+compare against". It refuses on missing data, never passes: no frozen
+baseline, no criterion, no funnel store, a fold that has not converged — each
+named on the Harvest page.
+
+Both passed → the candidate awaits **a human**. Promotion is snapshot-first
+(the pre-promotion content + allowlist), then the two existing write commands,
+then an append-only log row carrying `skill`, `origin`, `eval_ref`,
+`conversion_ref`, `approver`, `snapshot_ref` and the criterion's sha. The
+conversion ruler is re-read at the moment the skill lands — a store that
+dipped below its frozen baseline since gating parks the promotion with the
+current numbers, and a criterion file that changed since boot is a criterion
+nobody froze.
+
+## Rollback
+
+One click, deterministic: the snapshot is restored — `WriteSkill` with the
+pre-promotion bytes (or `DeleteSkill` when the skill did not exist), the
+allowlist restored to the snapshot's set, and the promotion row stamped
+`rolled_back_at`. The log stays the single ledger: a skill promoted, rolled
+back, re-promoted is three readable rows.
+
+## The honest limits
+
+- **A store with no golden cases cannot gate, and cannot promote.** The gate's
+  strength is entirely the golden set.
+- **Grounding first.** A store without a matcher does not mine — the product
+  loop is blocked until the evidence ledger is live (by refusal, not by
+  warning).
+- **A promoted skill is live text**, like any skill: the SkillStore's version
+  history plus the harvest snapshot plus the log make the rollback path
+  deterministic.
+- **The first-10 audit is human.** The negative list can carry a false
+  restriction (a phrase too broad) — that is exactly the Hermes failure, and
+  it is caught by the audit, not by the engine: the list grows and the loop
+  stops (`harvest.enabled: false`), both by data.
+- **The harvest costs provider money**: one miner call per window plus one
+  full golden replay per gated candidate. The `budget` cap, the recorded run
+  cost and the manual trigger bound it; the automated loop mines one session
+  per claim window.
+
+## The operator surface
+
+- `insika harvest --agent ID [--last-sessions N] [--since ISO] [--full]` — mine one window.
+- `insika harvest:negative import --agent ID --file F` — seed the profile's list from a rules file.
+- `insika harvest:criterion check --file F` — strict-load the frozen conversion criterion (the hook before any promotion).
+- The **Harvest page** in the Studio: the human's inbox (each candidate with
+  its evidence excerpt, the eval report, the conversion card, promote/reject),
+  the gated-but-blocked rows with the named ruler hole, the pending list, the
+  append-only promoted log with the rollback mirror, the negative list with
+  per-rule rejection counts, and the criterion block read-only.

data/docs/LOADTEST.md

@@ -16,15 +16,21 @@ The whole point: the engine exposes `POST /v1/responses` as an **SSE drop-in** o
 the OpenClaw gateway. Same contract → the same load tools work against either side,
 so you can measure the engine you are about to ship against the gateway it replaces.
 
-There are three scripts, each answering a different question:
+There are four scripts, each answering a different question:
 
 | Script | Question it answers | Needs a provider? |
 |--------|---------------------|-------------------|
 | `scripts/bench_store.rb` | Does SQLite (WAL) hold up N processes writing the same file? | No |
 | `scripts/loadtest.rb` | End-to-end: TTFB/total/tokens/cache/error against `/v1/responses` | Yes |
 | `scripts/loadtest-local.sh` | Single-proc baseline vs N-worker multi-proc on one box | Yes |
+| `scripts/loadtest_session.rb` | A full multi-message session (CEP, searches, FAQ) under C concurrent sessions — direct to the engine (`--surface engine`, stream vs steer) or through the consumer's real ingress (`--surface web`, the consumer's widget API) | Yes |
+| `insika soak` | Does the deploy degrade over 72 h of steady load? | Yes |
 
-All three take `--help` / `-h`.
+The first four take `--help` / `-h`; the soak is a shipped command (`insika soak --help`) rather
+than a repo script. Bursts and uptime are different questions: a wave driver
+measures a burst, and the soak's arrival process measures *degradation over
+uptime* — the load-test table above deliberately stops where
+[Soak](SOAK.md) begins.
 
 ---
 
@@ -54,7 +60,7 @@ sits ~100× below this ceiling. See DEPLOY.md for the measured numbers.
 ## 2. `loadtest.rb` — end-to-end against `/v1/responses` (with provider)
 
 Hits `POST /v1/responses` (SSE) directly — the production path
-(achei-b2b/WhatsApp → engine). Standard library only. Fires `agents × concurrency ×
+(a consumer app, e.g. WhatsApp, → engine). Standard library only. Fires `agents × concurrency ×
 iterations` turns in waves of `concurrency`, and per turn records TTFB (time to
 first SSE byte), total time, and the `usage` block (tokens + cache hit) of the last
 frame that carries it.
@@ -63,7 +69,7 @@ frame that carries it.
 INSIKA_URL=http://localhost:9292 \
 OPENCLAW_GATEWAY_TOKEN=xxx \
 bundle exec ruby scripts/loadtest.rb \
-  --agents bia,my-store --concurrency 16 --iterations 3 \
+  --agents demo,my-store --concurrency 16 --iterations 3 \
   --message "hi, how are you?"
 ```
 
@@ -74,7 +80,7 @@ Runs against a local server **or** a remote one (e.g. Railway) — just point
 
 | Flag | Default | Meaning |
 |------|---------|---------|
-| `--agents a,b,c` | `bia` | comma-separated agent ids (mapped to `model: openclaw:<agent>`) |
+| `--agents a,b,c` | `demo` | comma-separated agent ids (mapped to `model: openclaw:<agent>`) |
 | `--concurrency N` | `8` | concurrent turns per wave |
 | `--iterations N` | `1` | number of waves per agent |
 | `--message TEXT` | greeting | user message sent every turn |
@@ -97,7 +103,7 @@ Use `--dry-run` to sanity-check your flags/URL/token before firing real traffic
 
 ```bash
 INSIKA_URL=http://localhost:9292 OPENCLAW_GATEWAY_TOKEN=xxx \
-  bundle exec ruby scripts/loadtest.rb --agents bia --concurrency 16 --dry-run
+  bundle exec ruby scripts/loadtest.rb --agents demo --concurrency 16 --dry-run
 ```
 
 ### `--same-user` and the cache
@@ -109,7 +115,7 @@ and TTFB drop. Run both to bracket cold vs hot behaviour.
 
 ---
 
-## 3. `loadtest-local.sh` — baseline vs multi-worker on one box (§1.3 proof)
+## 3. `loadtest-local.sh` — baseline vs multi-worker on one box
 
 Boots Falcon with `--count 1` (single-process baseline), runs the sweep, then boots
 `--count N` (multi-process) over the **same** SQLite file (WAL), runs the sweep
@@ -129,7 +135,7 @@ DEEPSEEK_API_KEY=sk-... ./scripts/loadtest-local.sh [WORKERS] [CONCURRENCY]
 | `DEEPSEEK_API_KEY` | — (required) | real turns hit the provider; also auto-sourced from `.env.local` |
 | `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN`, then `local-demo` | Bearer for the sweep |
 | `PORT` | `9299` | bind port for the local Falcon |
-| `AGENT` | `bia` | agent id to load |
+| `AGENT` | `demo` | agent id to load |
 
 The final block prints the lock counts; the expected reading is `0` for both:
 
@@ -162,7 +168,7 @@ drop-in for the gateway, you only change **where it points**:
 # In the OpenClaw checkout, run its gateway loadtest against the HARNESS:
 OPENCLAW_GATEWAY_URL=http://localhost:9292 \
 OPENCLAW_GATEWAY_TOKEN=<same bearer the engine accepts> \
-node scripts/loadtest-gateway.mjs --agents bia --concurrency 16 --iterations 3
+node scripts/loadtest-gateway.mjs --agents demo --concurrency 16 --iterations 3
 ```
 
 Then run the exact same command with `OPENCLAW_GATEWAY_URL` pointing at the real
@@ -173,7 +179,7 @@ gateway, and diff the two reports. This is the shadow comparison the pilot needs
 - The OpenClaw checkout containing `scripts/loadtest-gateway.mjs` and Node installed.
 - A **bearer token accepted by both** sides. For the engine that is
   `OPENCLAW_GATEWAY_TOKEN` (see DEPLOY.md); point the gateway run at its own token.
-- **The same agent id provisioned on both** sides (e.g. `bia`) so `model:
+- **The same agent id provisioned on both** sides (e.g. `demo`) so `model:
   openclaw:<agent>` resolves on each. On the engine, provision via
   `scripts/import_pack.rb`.
 - The **same provider** (or an equivalent-latency one) behind each, otherwise you
@@ -223,6 +229,7 @@ Work top-down and **measure before assuming** — avoid premature topology optim
 | 4 | Insika vs gateway, identical knobs | §4 (either method) | Is the engine at parity with the engine it replaces before cut-over? |
 | 5 | Cold vs hot conversation (cache) | `loadtest.rb` with/without `--same-user 1` | Expected steady-state cost/latency once conversations warm up. |
 | 6 | Remote (Railway) vs local | `loadtest.rb` with `INSIKA_URL` remote | Network/deploy overhead of the real environment. |
+| 7 | Degradation over uptime (72 h) | `insika soak` (see [Soak](SOAK.md)) | The cut argument: does latency or memory grow with uptime? Run it last — it needs the topology settled first. |
 
 **Reaching for horizontal scale is only justified after 1–3 show the single box is
 the limit.** If it is, the paths are: sharding-by-tenant +

data/docs/OBSERVABILITY.md

@@ -36,7 +36,27 @@ something that left no task of its own behind:
 | `:turn_steered` | `task_id`, `count`, `total` | a message arrived mid-run and was appended to the turn in flight |
 | `:turn_steer_released` | `task_id`, `released_as`, `count` | the run could not absorb it, so it became the turn `released_as` |
 | `:turn_interrupted` | `task_id`, `replaced_by` | the turn was abandoned mid-run, and which turn replaced it |
+| `:turn_stuck` | `task_id`, `agent`, `reason`, `message` | the agent declared it could not proceed (`signal_stuck`, WS5) — the deterministic signal a consumer escalates on |
 | `:channel_delivered` | `channel`, `outbox_id`, `status`, `attempts`, `error` | the answer reached the platform (or did not) — the turn completing says nothing about that |
+| `:delivery_failed` | `channel`, `outbox_id`, `status`, `attempts`, `error` | a delivery exhausted its bounded retries — the alert face of the row above (WS6) |
+| `:budget_warning` | `agent`, `tenant`, `window`, `spent`, `cap` | a calendar budget crossed its threshold (`alert_at` or a soft cap) — once per window (WS2) |
+| `:breaker_open` | `agent`, `ref`, `tenant` | the reliability circuit breaker tripped for a `(tenant, provider/model)` — further turns fail fast until the cooldown (WS3/WS6) |
+| `:provider_failure` | `agent`, `ref`, `error`, `kind` | one attempt against `ref` failed and spent a retry — emitted with or without a circuit breaker (WS3) |
+| `:provider_fallback` | `agent`, `from`, `to`, `error`, `kind` | the turn ROTATED mid-flight to the next node of the fallback chain, and the error that caused it (WS3) |
+| `:ttft` | `task_id`, `session_id`, `ttft_ms` | the provider's time-to-first-token on the streaming envelope — only under `INSIKA_TURN_TIMING`, once per turn (WS6) |
+| `:distillation_completed` | `session_ref`, `agent`, `proposals`, `dropped{}`, `deduped`, `cost{}` | a session's traffic was distilled into N proposals (RFC-0034) — counts and ids only, never a fact value |
+| `:proposal_approved` | `proposal_id`, `status`, `operator` | a human approved a distilled fact on the Facts page — written to memory via CAS |
+| `:proposal_rejected` | `proposal_id`, `status`, `operator` | a human rejected it (the reason is on the proposal record, not in the event) |
+| `:proposal_dismissed` | `proposal_id`, `status`, `operator` | a human dismissed it — the tuple is latched, never proposed again |
+| `:proposal_stale` | `proposal_id`, `status`, `operator` | the CAS lost: the fact moved after distillation — re-presented with both values on the wiki, never silently overwritten |
+| `:harvest_mined` | `agent`, `run_id`, `candidates`, `rejected{}`, `cost{}` | a mining pass finished (RFC-0035) — counts and rule ids only, never a skill body |
+| `:harvest_gated` | `run_id`, `candidate_id`, `agent`, `eval_passed`, `conversion_passed`, `reason` | the double gate's verdict on one candidate — ids and verdicts only |
+| `:skill_promoted` | `agent`, `skill`, `candidate_id`, `snapshot_ref`, `promotion_ref`, `approver` | a human approved a mined skill — it is live for the store, with the snapshot for rollback |
+| `:skill_rolled_back` | `snapshot_ref`, `skill`, `agent`, `operator` | the snapshot was restored — the promotion row carries the `rolled_back_at` stamp |
+
+`delivery_failed` and `breaker_open` are the two the operator config is pointed at
+(`alerts.webhook` on the profile): each only fires when something durable did
+not land. `:ttft` is additive debug, absent unless `INSIKA_TURN_TIMING` is set.
 
 `:channel_delivered` is the one worth alerting on: a turn can be `:task_completed`
 and correct while the customer got nothing, because delivery is a separate,
@@ -181,13 +201,13 @@ million tokens**:
 
 ```bash
 INSIKA_MODEL_PRICING='{
-  "deepseek-chat":       {"input": 0.27, "output": 1.10, "cached_input": 0.07},
+  "deepseek-v4-flash":       {"input": 0.27, "output": 1.10, "cached_input": 0.07},
   "claude-sonnet-4-5":   {"input": 3.00, "output": 15.00, "cached_input": 0.30, "cache_write": 3.75}
 }'
 ```
 
 - A key matches the model id the provider reports, **with or without** the
-  `provider/` prefix — `deepseek/deepseek-chat` and `deepseek-chat` both hit the
+  `provider/` prefix — `deepseek/deepseek-v4-flash` and `deepseek-v4-flash` both hit the
   same entry.
 - `input` / `output` are required (one of them is enough for the entry to load).
 - `cached_input`, when given, bills cache **reads** at that rate and subtracts them
@@ -357,6 +377,49 @@ consumer that fell far behind would have its subscription closed (telemetry stop
 the turn does not). Span and instrument operations are cheap, so there's ample
 headroom.
 
+## Process vitals — `GET /v1/vitals`
+
+OTel carries turn/tool telemetry; it says nothing about the **process**. For the
+questions a soak (or any operator) asks — *which process is this, how long has it
+been up, how much memory does it hold, and what is the Ruby heap doing?* — there
+is one read-only route:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" https://<target>/v1/vitals
+```
+
+```jsonc
+{
+  "boot_id": "20260820T09-…",     // one per container start; a change = a restart
+  "pid": 42,
+  "started_at": "2026-08-20T09:00:00Z",
+  "uptime_s": 259200,
+  "version": "0.2.0",
+  "ruby": "ruby 3.4.1 …",
+  "yjit": true,
+  "rss_bytes": 536870912,          // nil when unreadable — never a guess
+  "gc": { "heap_live_slots": …, "major_gc_count": …, "malloc_increase_bytes": … },
+  "threads": 8,
+  "in_flight": 1,                  // the executor's in-flight turns
+  "db_bytes": { "db": …, "wal": …, "shm": … },
+  "at": "2026-08-20T09:00:00Z"
+}
+```
+
+The two fields that make it a **restart detector**: `boot_id` (one per container
+start, exported by the entrypoint and shared by every worker) and `pid`. A
+`boot_id` change is a container restart; a `pid` change under the same `boot_id`
+is a worker respawn — the event a platform metrics API cannot see.
+
+- **Operator-only.** The route is not in the public allowlist (no bearer →
+  unauthorized) and not on the tenant surface, so only an operator reads
+  process internals. `/up` stays the public health probe and carries no
+  process data.
+- **Reads no store.** Pure OS/VM readings — safe to poll at any rate, and it
+  cannot contend with turns.
+- **The soak's sampler.** [Soak](SOAK.md) polls it hourly; a `nil` RSS reads as
+  missing coverage, never as zero.
+
 ---
 
 *Packaging note.* Today the bridge lives in the Insika repo as an opt-in core

data/docs/REFINEMENT.md

@@ -32,11 +32,11 @@ it reaches anyone. Every part of that is below, including what it cannot catch.
 From the CLI, against the same database the engine uses:
 
 ```bash
-INSIKA_DB=insika.db bin/insika refine --agent bia
+INSIKA_DB=insika.db bin/insika refine --agent demo
 ```
 
 ```text
-bia — completed (last 200 session(s))
+demo — completed (last 200 session(s))
   tool_error     ×24   shipping_quote failed: cep is required
                        sessions: 9f2c1a04…, 4b7e5590…, c1d0aa31…
   repetition     ×7    customer repeated themselves
@@ -149,7 +149,7 @@ it did before, so no transcript needs migrating.
 
 `repetition` counts only what a customer said and `safe_reply` reads only what the
 engine said, both from this field. A message that declares nothing falls back to the
-old guess (an injected fragment opens with its own tag, `<cacau_cep_obrigatorio> …`,
+old guess (an injected fragment opens with its own tag, `<store_cep_required> …`,
 which no customer types) — that heuristic now runs only on messages that made no
 claim about themselves.
 
@@ -173,8 +173,8 @@ an agent with no configuration at all can be run. The optional block on the agen
 sets the defaults:
 
 ```ruby
-Insika.agent "bia" do
-  model "deepseek-chat"
+Insika.agent "demo" do
+  model "deepseek-v4-flash"
   refine window: { last_sessions: 200 }, max_findings: 20
 end
 ```
@@ -186,8 +186,8 @@ end
 | `exclude_sessions` | none | session-id prefixes to drop |
 | `mode` | `"report"` | `report` reads and writes nothing. `propose` allows a gated, human-approved edit (below). `auto_apply` lets a gate-passing edit land unattended — off by default, and read [what it costs you](#applying-without-a-human) first. A mode the engine does not know is refused, never silently downgraded |
 | `files` | none | the ONLY files a proposal may edit. Empty means report-only |
-| `proposer` | the platform `utility_model` | which model writes the candidate (`"deepseek/deepseek-chat"` or a bare model name). Neither set means no proposal — the engine never picks a model to spend your budget on |
-| `proposers` | falls back to `proposer` | a **panel**: several models, each writing its own candidate. `["deepseek/deepseek-chat", {model: "gpt-5-mini", provider: "openai"}]` — either syntax |
+| `proposer` | the platform `utility_model` | which model writes the candidate (`"deepseek/deepseek-v4-flash"` or a bare model name). Neither set means no proposal — the engine never picks a model to spend your budget on |
+| `proposers` | falls back to `proposer` | a **panel**: several models, each writing its own candidate. `["deepseek/deepseek-v4-flash", {model: "gpt-5-mini", provider: "openai"}]` — either syntax |
 | `budget.tokens` | unlimited | what one run may spend across every proposal and every gate replay |
 | `max_edits` | 3 | edits a single proposal may carry |
 | `auto_apply_max_edits` | 1 | edits an **unattended** apply may carry. A bigger diff waits for a person |
@@ -306,7 +306,7 @@ first question worth asking is whether the finding it addresses is behaviour at
 
 ```ruby
 refine mode: "propose", files: %w[TOOLS.md],
-       proposers: ["deepseek/deepseek-chat", "gpt-5-mini"],
+       proposers: ["deepseek/deepseek-v4-flash", "gpt-5-mini"],
        budget: { tokens: 200_000 }
 ```
 
@@ -440,7 +440,7 @@ not reasoned about.
 rest is detail. A regression is "a case that was passing now fails" — so an edit
 that breaks something no case covers passes cleanly. Two shallow cases wave almost
 anything through. If you want the loop to protect a behaviour, there has to be a
-case for that behaviour; that is the price [D4](#what-the-gate-needs) is charging,
+case for that behaviour; that is the price [the gate](#what-the-gate-needs) is charging,
 and it is charged in curation work, not in configuration.
 
 Three things it will **not** catch, and two of them are the engine working correctly:

data/docs/RELEASING.md

@@ -8,7 +8,7 @@ permalink: /releasing/
 # Releasing
 
 How an `insika` gem release is cut, and how the install is **proven** before the
-push. The rule that matters (RFC-0018 §8): a green suite is not a green gem —
+push. The rule that matters: a green suite is not a green gem —
 the suite resolves everything by path, so the entire class of packaging failure
 is invisible to it. Do not publish on rspec alone.
 
@@ -18,7 +18,7 @@ is invisible to it. Do not publish on rspec alone.
 2. `lib/insika/version.rb` carries the version being published.
 3. Every new `lib/` file is **tracked in git**. The gemspec's `files` come from
    `git ls-files`: an untracked file builds without a warning and the installed
-   gem fails at `require` — this is exactly the failure E1 exists to catch.
+   gem fails at `require` — this is exactly the failure this proof exists to catch.
 
 ## Cut the gem
 
@@ -26,7 +26,7 @@ is invisible to it. Do not publish on rspec alone.
 gem build insika.gemspec    # -> insika-<version>.gem
 ```
 
-## Prove the install (E1/E3) — from OUTSIDE the repo
+## Prove the install — from OUTSIDE the repo
 
 Install into a clean gem home and run the four shapes from a directory that is
 not the checkout, with the repo's `lib/` nowhere on the load path:
@@ -39,7 +39,7 @@ cd "$T"
 # 1. reply in-process
 GEM_HOME="$T/gemhome" GEM_PATH="$T/gemhome" ruby -e '
   require "insika"
-  agent = Insika.agent("assistant") { model "deepseek-chat"; provider :deepseek }
+  agent = Insika.agent("assistant") { model "deepseek-v4-flash"; provider :deepseek }
   puts agent.reply("hi")'                                   # needs DEEPSEEK_API_KEY
 
 # 2. serve  — /studio login 200, /v1/responses streams, /start.md 200
@@ -50,7 +50,7 @@ GEM_HOME="$T/gemhome" GEM_PATH="$T/gemhome" ruby -e '
 Shapes 2–4 are the ones that fail when a file is missing from the gem (the
 Studio's `views/`, `assets/dist/`, the onboarding docs); run all four.
 
-Then the load guard, from the **installed** gem (E3) — no test double:
+Then the load guard, from the **installed** gem — no test double:
 
 ```bash
 GEM_HOME="$T/gemhome" GEM_PATH="$T/gemhome" ruby -e '
@@ -59,6 +59,33 @@ GEM_HOME="$T/gemhome" GEM_PATH="$T/gemhome" ruby -e '
   puts "clean"'
 ```
 
+### The 1.0 release gate — the RFC-0036 install proof (E1)
+
+For the 1.0 release the proof above is scripted and its **installed-bytes**
+half is asserted by the domain-boundary suite (C1) on the artifact, not the
+repo. Run the runbook, with a key (the smoke turn is one `reply` through the
+installed gem):
+
+```bash
+DEEPSEEK_API_KEY=sk-... scripts/install_proof/install_proof.sh   # prints PASS
+```
+
+The script builds, installs into a FRESH `GEM_HOME`, asserts `gem contents
+insika` carries no `deploy/ packs/ examples/ plugins/ evals/ scripts/ spec/`
+path and no demo-persona-name string, and answers one turn from an app dir that follows
+only the public docs. Archive the PASS output with the release notes — it is
+the 1.0 exit criterion "install proof by the docs alone".
+
+The same gate writes the freeze date: a breaking `/v1` change needs a new
+`Insika-Version` entry (server/app.rb), a compatibility branch (RFC-0016 A5)
+and a rewritten `**Frozen as of:**` line in `docs/API.md` — the version-gate
+spec pins the two together, and the 1.0 release writes the date at release
+time.
+
+Catalog submission checklist (RFC §6): verify the best-of-Agent-Harnesses
+catalog size at submission time (161 vs 154 — the counts diverge across the
+catalog's own pages) and cite the conformance suite as the `durable` evidence.
+
 ## Publish
 
 ```bash
@@ -66,5 +93,5 @@ gem push insika-<version>.gem
 ```
 
 Publishing is irreversible in practice — a yanked 0.1.0 is a bad first
-impression. The version number is cheap; the name is not. E1 before push, and
-nothing else.
+impression. The version number is cheap; the name is not. The install proof before
+push, and nothing else.

data/docs/RUNNING-LOCAL.md

@@ -8,7 +8,7 @@ permalink: /running-local/
 # Running the Insika locally
 
 Boots the engine single-process, serving `/studio` and `/v1/*` against a demo
-agent (the `bia` persona on DeepSeek). Every message runs the **same**
+agent (the `demo` agent on DeepSeek). Every message runs the **same**
 `send_message` the API runs — real tools, skills, and memory.
 
 ## Boot
@@ -26,7 +26,7 @@ Open `http://localhost:9292`:
 | URL | What |
 |-----|------|
 | `/studio` | management UI (log in with the token; default `local-demo`) |
-| `/studio/chats` | chat with the demo agent (`agent: bia`, `session_id: web`, multi-turn ready) |
+| `/studio/chats` | chat with the demo agent (`agent: demo`, `session_id: web`, multi-turn ready) |
 | `/studio/tasks` | tasks / approvals console |
 | `/v1/responses` | OpenAI-Responses ingress (Bearer) — the drop-in API contract |
 | `/v1/agents` | provisioning by definition/pack (Bearer) — `POST` imports, `DELETE /:id` removes |
@@ -63,7 +63,7 @@ whole surface answers `503`, never open by omission.
 | `BIND` | `http://localhost:9292` | host:port |
 | `ADMIN_TOKEN` | `local-demo` | token for `/studio` |
 | `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for the whole `/v1` + `/a2a` surface |
-| `DEEPSEEK_MODEL` | `deepseek-chat` | model |
+| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | model |
 
 With persistence:
 
@@ -82,7 +82,7 @@ the `model`:
 curl -N http://localhost:9292/v1/responses \
   -H "Authorization: Bearer local-demo" \
   -H "Content-Type: application/json" \
-  -d '{ "model": "bia", "user": "web", "stream": true, "input": "hello" }'
+  -d '{ "model": "demo", "user": "web", "stream": true, "input": "hello" }'
 ```
 
 `user` is the session id (any stable id for a multi-turn conversation).