insika 0.1.0 → 0.2.0

data/docs/REFINEMENT.md

@@ -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.
 
@@ -174,7 +174,7 @@ sets the defaults:
 
 ```ruby
 Insika.agent "bia" do
-  model "deepseek-chat"
+  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 '
@@ -66,5 +66,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

@@ -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:
 

data/docs/SECURITY.md

@@ -47,16 +47,26 @@ dispatch **any** registered authoring Command (`write_agent_file`, `write_data_t
 `upsert_llm_provider`, `update_settings`, `delete_agent`). Treat that token as
 operator-grade — it is not a read key, and a leak is agent takeover, not just usage.
 
-> **The auth decision (RFC-0018, decided for 0.1.0): one deployment, one token;
-> multi-tenancy belongs to the host.** There is exactly one credential per
-> surface — `OPENCLAW_GATEWAY_TOKEN` for `/v1`, `ADMIN_TOKEN` for the Studio —
-> and no per-caller scoping inside the engine. That is what the code has always
-> done; this paragraph is the decision written down so nothing built on top
-> inherits an assumption nobody stated. Serving two tenants from one mount means
-> putting the app behind your own authentication (see
-> [Embedding](EMBEDDING.md#embedding-is-not-multi-tenancy)), and scoped auth —
-> one mount, several tokens with different powers — is a real RFC the day an
-> adopter needs it, not a someday.
+### Multi-tenant mode (`INSIKA_TENANCY=multi_tenant`)
+
+A single operator-grade token cannot host N stores. With `INSIKA_TENANCY=multi_tenant`
+the Bearer is resolved to a **principal** before the routes:
+
+- **Per-tenant tokens** (`POST /v1/commands/issue_tenant_token`) scope a caller to
+  one tenant; **operator** tokens (and the legacy gateway token — an existing
+  deployment switching modes keeps its credential) have the run of the deployment.
+- Tokens are stored **only as SHA-256 hashes**; the plaintext is shown exactly once,
+  at issue time. Rotation (`rotate_tenant_token`) and revocation (`revoke_token`)
+  are operator commands — revoking one tenant's token never touches another's.
+- A tenant principal reaches only its **own runtime surfaces** (`/v1/sessions`,
+  `/v1/messages`, `/v1/responses`, workflow runs, and its own session/task/event
+  reads). Every authoring/provisioning/config surface answers `403` to a tenant.
+- Isolation is the key, not a convention: a tenant's sessions live under
+  `<tenant>:<session-id>`, its commands carry `meta.tenant` (memory scoping,
+  event tagging), and reading another tenant's session/task reads as `404`.
+
+`single_tenant` (the default) is exactly the classic behavior above — one
+operator credential, no principal, no stamping.
 
 ## The `/v1` contract is versioned by date
 
@@ -172,7 +182,10 @@ moderator off. See [`examples/guardrails/`](https://github.com/guizaols/insika/t
 - **Input** — deterministic detectors (prompt-injection, abuse) run *before* the
   model. A flagged input gets a **safe refusal without burning a model turn** — an
   injection or a flood never reaches the provider. An LLM moderator can be layered
-  on top.
+  on top. The moderator is **fail-open**: an error or an unparseable reply never
+  blocks a legitimate customer — but silence is not a negative. That third state
+  surfaces as a `:guardrail_flagged` event with category `moderator_unavailable`,
+  so a degraded tier is distinguishable from a healthy one in the audit stream.
 - **Output** — moderation plus PII/secret redaction on the streamed response, and
   a post-turn validator.
 

data/docs/SKILLS.md

@@ -22,6 +22,8 @@ See [`examples/skills/`](https://github.com/guizaols/insika/tree/main/examples/s
 ---
 name: refunds                       # must equal the directory name
 description: When and how to process a refund   # the Level-1 trigger text
+triggers: [refund, money back]      # optional: deterministic activation (below)
+companions: [refund-policy]         # optional: skills this one cannot work without
 ---
 
 <the full playbook body — loaded only on demand>
@@ -33,17 +35,121 @@ which the `name:` field must match.
 ## Progressive loading: two levels
 
 - **Level 1 — metadata only.** A context provider injects an `<available_skills>`
-  list (the name + one-line description of every allowed skill) into the system
-  prompt, telling the model to load a skill before acting on it. Cheap, and always
-  present for allowed skills.
+  list into the system prompt — the name, the one-line description and the
+  `triggers:` of every allowed skill — telling the model to load a skill before
+  acting on it. Cheap, and always present for allowed skills. **This is the routing
+  table, and it is generated:** it cannot disagree with the allowlist, so do not
+  hand-write one in a prompt file (see [Drift guards](#drift-guards)).
 - **Level 2 — the full body.** A built-in `load_skill` tool returns the skill body
   on demand. It enforces the agent's skill allowlist and is wired **automatically**
   whenever the agent has any allowed skills — you do not add it to `tools_allow`.
+- **Deterministic activation — `triggers:`.** When the user message contains one
+  of the skill's `triggers`, the body is injected for that turn — no model
+  decision, no `load_skill` call. Only matched skills, only that turn. Use it for
+  skills that MUST fire on known phrases; model loading stays as the fallback for
+  everything else. Matching is on **whole words**, case-insensitive and
+  accent-folded: `presente` fires on *um presente* and *presénte*, never inside
+  *apresente*.
 
 The Level-1 list is budgeted like any other context fragment
 (see [Context](CONTEXT.md)); the Level-2 body only costs tokens on the turns that
 open it.
 
+### Only trigger a skill that can finish the turn alone
+
+A `triggers:` match is not a hint — the body lands in the prompt with the
+authority of an instruction. So put triggers only on a skill that is
+**self-sufficient** for the turn it fires on.
+
+The failure mode is counter-intuitive: injecting a skill that is only *part* of
+the answer is **worse than injecting nothing**. Give the model a reference table
+whose procedure lives in a companion skill, and it now holds a plausible
+half-recipe — so it never calls `load_skill` for the other half, and improvises
+the missing part. A precise trigger on the wrong kind of skill still breaks the
+turn.
+
+Reference tables, vocabularies and lookup maps are the skills to leave on
+level 1. Whole procedures ("run this journey", "recover from this error") are the
+ones worth triggering.
+
+## Always-on skills: `skills_eager`
+
+A skill that every turn needs — output format, the marker vocabulary, how to
+recover from a failed tool — should not depend on the model choosing to load it.
+Name it on the **agent** and its body is in the prompt on every turn:
+
+```ruby
+Insika.agent("consultant") do
+  skills_eager "recommendation-formatting", "tool-error-recovery"
+  # skills_eager        # or: every allowed skill (a corpus that fits the budget)
+  # skills_eager false  # or: none — the default
+end
+```
+
+An eager skill also **leaves level 1**: it is absent from `<available_skills>` and
+`load_skill` refuses to serve it. There is no level 2 left to fetch, and a catalog
+pointing at a body already in the prompt only invites a call that pays for a
+duplicate.
+
+### Why the agent decides, and not the skill
+
+Eagerness used to be an `eager: true` key in the `SKILL.md` frontmatter. That put
+the decision on the wrong object: **skills are shared.** `escalation-to-human`,
+`recommendation-formatting` and `tool-error-recovery` each sit in several agents'
+allowlists, and one flag on the skill forced one decision onto every agent holding
+it — with no way to be always-on for the agent that needs it and discretionary for
+the one that does not.
+
+`skills_eager` is a per-agent list, so the same shared skill can be both. The
+frontmatter key is **ignored** — `insika doctor` flags any skill still carrying it,
+and names the agent setting that replaced it.
+
+A name that is not in the agent's `skills` allowlist is a no-op (eagerness is
+intersected with what the agent is allowed to see); `doctor` flags that too.
+
+### Keep the discretionary skills on the load path
+
+Making everything eager is a trap, and the reason is not the tokens: **it costs you
+the signal**. When every body is present on every turn, "which skills were active"
+is always "all of them", and you can no longer tell which one the model reached for.
+The `load_skill` call is the only record of that choice — it is a persisted tool
+message, so it shows up in the transcript on its own.
+
+So the split is: **eager for what the turn always needs, `load_skill` for what the
+turn might need.** The second group is where you want the model's choice on the
+record, because that is the group where a wrong choice is worth seeing.
+
+The token trade is real but smaller than it looks: eager bodies sit at a fixed
+position ahead of the history, so they belong to the **cacheable prefix**, and they
+are still evictable under budget pressure, unlike the pinned identity. Conditional
+injection is what breaks that prefix, on exactly the turns it fires.
+
+## Seeing which skills were active, and why
+
+The load path is legible for free: `load_skill` is a tool, so the call is a
+persisted message and shows up in the transcript on its own. The deterministic paths
+are not a call, so the engine reports them itself — **with a reason per skill**:
+
+| reason | what it means |
+|---|---|
+| `eager` | the agent's `skills_eager` names it, so every turn gets it |
+| `trigger:<phrase>` | this message matched that `triggers:` entry — the phrase as **authored**, so you can find the line to edit |
+| `pack` | a plugin's own context provider supplied the body |
+
+Where it shows up, per turn, in the Studio session screen:
+
+- an **activation card in the transcript thread**, placed at the top of its turn and
+  in the same visual language as a tool result, so a context-injected skill and a
+  model-loaded one read the same way;
+- the **Context card**, next to that category's token count, for the after-the-fact
+  audit;
+- the `skill_activated` **event** (`skills: [{name, reason}]`, `source: "context"`),
+  with full task/session correlation.
+
+All three are computed from what actually reached the prompt **after the budget
+cut**: a body the budget evicted is reported as an eviction, never as an activation.
+A turn that mixes both paths is labelled `mixed`, and each line keeps its own reason.
+
 ## Where skills live: the store, over a disk seed
 
 - Skills live as **rows in SQLite** — one row per skill, holding the entire
@@ -58,6 +164,68 @@ open it.
 > runtime operation (Studio / API / DSL), not a commit. See
 > [Context](CONTEXT.md#the-volume).
 
+## Pairs that must not break: `companions:`
+
+Injecting *part* of an answer is worse than injecting nothing. Give the model a line
+map whose query-construction rules live in another skill and it holds a plausible
+half-recipe — so it never calls `load_skill` for the other half, and improvises the
+missing part. Measured on a real pack: the map arrived by trigger, the rules did not,
+and the searches came out malformed. Twice.
+
+Declare the dependency and it travels with whatever brought it — a trigger match, the
+agent's eager set, or a `load_skill` call (which returns both bodies in the one call):
+
+```yaml
+companions: [query-construction]
+```
+
+Two deliberate limits:
+
+- **One level, no transitive walk.** A cycle would be a hang and a chain a budget
+  blowout, and "cannot work without" is a direct relationship.
+- **Never widens an allowlist.** A companion the agent is not allowed to load is
+  simply absent; `insika doctor` flags the declaration instead.
+
+## Specializing a shared skill for one agent
+
+Skills are shared on purpose: `escalation-to-human` belongs in several agents'
+allowlists. But sometimes one agent needs a different version of the same skill —
+its own return policy, its own store name — and forking it under a second name
+throws the sharing away and leaves two things to keep in step.
+
+So the store has a second scope, and resolution is a **precedence chain** with one
+more dimension:
+
+```
+for agent A, skill <name>:   (A, <name>) in the agent scope,
+                             then <name> in the shared scope
+```
+
+Three cases fall out of that one rule:
+
+| case | what exists in the store |
+|---|---|
+| **shared** | only the shared record — every agent gets the same body |
+| **override** | both — the agent's wins, for that agent only |
+| **agent-private** | only the agent record — invisible elsewhere, and the name may collide freely |
+
+The **name never changes.** An override keeps saying `name: escalation-to-human`
+inside, because it *is* that skill, specialized; the allowlist, the `<available_skills>`
+list, `load_skill` and the activation card all keep showing the bare name. What
+decides which record you get is its **position in the store**, never the frontmatter —
+otherwise an override would clobber the shared skill for everybody.
+
+Write one with `agent:`, and remove it the same way (which un-specializes, leaving
+the shared skill in place):
+
+```ruby
+dispatch(:write_skill,  { name: "escalation-to-human", agent: "store-cacau", content: md })
+dispatch(:delete_skill, { name: "escalation-to-human", agent: "store-cacau" })
+```
+
+In the Studio: **Skills → specialize for this agent**, which seeds the override from
+the shared body.
+
 ## Making a new skill "show up"
 
 For an agent to actually use a skill, **both** conditions must hold:
@@ -89,6 +257,24 @@ Two ways to satisfy both:
   `load_skill` errors → the store row is missing or misnamed (condition 1); the
   `name:` frontmatter must equal the directory name.
 
+## Drift guards
+
+A skill catalog drifts against the prose that routes to it, and every way it happened
+on the pilot was silent — found by reading a customer conversation days later. So the
+routing table is **generated** (above), and `insika doctor` reports the residue the
+generator cannot remove. Every check takes mechanical inputs only — names, allowlists,
+agent identities — because one false positive is enough for an operator to stop
+reading the doctor:
+
+| finding | what it means |
+|---|---|
+| a prompt file names a skill outside that agent's allowlist | leftover hand-written routing: the model is told to use something it cannot load |
+| a shared skill's body names one of its own holders | specialized text in shared clothing — the other holders are served that store's policy as their own. Specialize it instead |
+| a body references another catalog skill without declaring it a companion | the pair can still arrive apart |
+| a declared companion is outside an agent's allowlist | the pair cannot travel for that agent, and the engine will not widen the allowlist |
+| a skill still declares `eager:` in its frontmatter | the key is ignored; the decision moved to the agent |
+| an agent marks a skill eager that it does not allow | the name is a no-op |
+
 ## See also
 
 - [Context](CONTEXT.md) — how the skills list is budgeted into a turn.

data/docs/WHY.md

@@ -32,7 +32,7 @@ the same speed-to-first-agent story Python teams tell, without leaving Ruby:
 require "insika"
 
 agent = Insika.agent("assistant") do
-  model "deepseek-chat"
+  model "deepseek-v4-flash"
   provider :deepseek
   instructions "You are a concise, friendly assistant."
 end

data/docs/WORKFLOWS.md

@@ -40,8 +40,8 @@ agents by id and those agents must resolve in the same runtime:
 newsroom = Insika.system do
   provider :deepseek
 
-  agent("writer") { model "deepseek-chat"; instructions "Write ONE paragraph." }
-  agent("editor") { model "deepseek-chat"; instructions "Rewrite as ONE sentence." }
+  agent("writer") { model "deepseek-v4-flash"; instructions "Write ONE paragraph." }
+  agent("editor") { model "deepseek-v4-flash"; instructions "Rewrite as ONE sentence." }
 
   workflow "publish",
            description: "Draft a paragraph, then tighten it.",

data/docs/index.md

@@ -34,7 +34,7 @@ Ruby `>= 3.3` and a provider key (the demo uses DeepSeek). The whole program:
 require "insika"
 
 assistant = Insika.agent("assistant") do
-  model "deepseek-chat"
+  model "deepseek-v4-flash"
   provider :deepseek
   instructions "You are Bia, a concise and friendly assistant. Answer briefly."
 end

data/docs/onboarding/start.md

@@ -51,7 +51,7 @@ require "insika"
 
 assistant = Insika.agent("assistant") do
   provider :deepseek            # ← the provider slug from {{MODELS_URL}}
-  model "deepseek-chat"         # ← a model id from {{MODELS_URL}}
+  model "deepseek-v4-flash"         # ← a model id from {{MODELS_URL}}
   instructions "You are a concise, friendly assistant. Answer briefly."
 end