insika 0.1.0 → 0.3.0

data/lib/insika/dsl/runtime.rb

@@ -26,16 +26,16 @@ module Insika
       # the runtime does not care how many agents it hosts, only that each one
       # arrives as an ordinary Pack.
       #
-      # `backend`: the store this graph owns (RFC-0017 A1). nil = the historic
+      # `backend`: the store this graph owns. nil = the historic
       # path, `INSIKA_DB` or memory — ENV is a default, never a requirement (the
-      # embed contract, item 5). An injected backend wins and is never widened
+      # embed contract). An injected backend wins and is never widened
       # back to the environment.
       def initialize(definition, backend: nil)
         @definition = definition
         @injected_backend = backend
         @packs = (definition.respond_to?(:packs) ? Array(definition.packs) : [definition.pack]).freeze
         @pack = @packs.first
-        # RFC-0017 A2: the graph's OWN RubyLLM config, built before the graph so
+        # the graph's OWN RubyLLM config, built before the graph so
         # every collaborator that talks to a provider is handed it at wiring time
         # rather than reading a process-wide singleton at call time.
         @llm = build_llm_context
@@ -44,7 +44,7 @@ module Insika
         import_packs
       end
 
-      # The graph's RubyLLM context (RFC-0017 A2) — an isolated config dup that
+      # The graph's RubyLLM context — an isolated config dup that
       # answers #chat. nil only under the test stub, where the fallback is the
       # RubyLLM constant itself. Read by the specs and by anything a host wires
       # alongside this graph.
@@ -178,7 +178,8 @@ module Insika
           guardrails: c[:guardrails], context_providers: context_providers(spine, c),
           edge_limiter: c[:edge_limiter],
           executor_extra: { settings_store: c[:settings_store], tool_trace_store: c[:tool_trace_store],
-                            llm: @llm }
+                            context_trace_store: c[:context_trace_store],
+                            cache_series_store: c[:cache_series_store], llm: @llm }
         )
         register_authoring_commands(graph, c)
         register_workflows(graph)
@@ -228,17 +229,21 @@ module Insika
           system_file_store: Insika::SystemFileStore.new(config_store: config_store),
           mcp_store: Insika::McpStore.new(config_store: config_store),
           tool_trace_store: Insika::ToolTraceStore.new(store: backend),
+          context_trace_store: Insika::ContextTraceStore.new(store: backend),
+          # the per-AGENT cache-hit series (the Studio agent-detail card).
+          cache_series_store: Insika::CacheSeriesStore.new(store: backend),
           tool_registry: tool_registry,
           tool_catalog: Insika::ToolCatalog.new(tool_registry: tool_registry),
           skill_catalog: Insika::SkillCatalog.new([], store: skill_store),
           prompt_catalog: Insika::PromptCatalog.new([]),
           profile_source: Insika::StoredProfileSource.new(config_store: config_store),
-          # A2: the moderator/validator tiers ask a model too. A graph reading its
+          # the moderator/validator tiers ask a model too. A graph reading its
           # own key for the turn but the global one for a guardrail would be a
           # credential leak wearing the look of isolation.
           guardrails: Insika::Safety::Factory.new(settings_store: settings_store, llm: @llm),
           edge_limiter: Insika::EdgeLimiter.new(
-            ledger: Insika::UsageLedger.new(store: backend), settings_store: settings_store
+            ledger: Insika::UsageLedger.new(store: backend), settings_store: settings_store,
+            budget_ledger: spine.budget_ledger, event_stream: spine.event_stream
           )
         }
       end
@@ -251,6 +256,7 @@ module Insika
             agent_files: c[:agent_file_store], system_files: c[:system_file_store]
           ),
           Insika::Context::Providers::Skill.new(catalog: c[:skill_catalog]),
+          Insika::Context::Providers::SkillTrigger.new(catalog: c[:skill_catalog]),
           Insika::Context::Providers::ToolSearch.new(catalog: c[:tool_catalog]),
           Insika::Context::Providers::Memory.new(store: spine.memory_store),
           Insika::Context::Providers::Session.new(session_store: spine.session_store)
@@ -264,6 +270,7 @@ module Insika
         bus = graph.bus
         es = graph.event_stream
         mem = graph.memory_store
+        audit = graph.memory_audit_store
         bus.register(:create_agent, Insika::Commands::CreateAgent.new(profile_source: c[:profile_source], event_stream: es))
         bus.register(:update_agent, Insika::Commands::UpdateAgent.new(profile_source: c[:profile_source], event_stream: es))
         bus.register(:delete_agent, Insika::Commands::DeleteAgent.new(profile_source: c[:profile_source], event_stream: es))
@@ -273,9 +280,11 @@ module Insika
         bus.register(:restore_agent_file, Insika::Commands::RestoreAgentFile.new(profile_source: c[:profile_source], agent_file_store: c[:agent_file_store], event_stream: es))
         bus.register(:write_skill, Insika::Commands::WriteSkill.new(skill_store: c[:skill_store], skill_catalog: c[:skill_catalog], event_stream: es))
         bus.register(:set_skill_agents, Insika::Commands::SetSkillAgents.new(profile_source: c[:profile_source], event_stream: es))
-        bus.register(:memory_put_fact, Insika::Commands::MemoryPutFact.new(memory_store: mem, event_stream: es))
-        bus.register(:memory_forget_fact, Insika::Commands::MemoryForgetFact.new(memory_store: mem, event_stream: es))
+        bus.register(:memory_put_fact, Insika::Commands::MemoryPutFact.new(memory_store: mem, event_stream: es, audit_store: audit))
+        bus.register(:memory_forget_fact, Insika::Commands::MemoryForgetFact.new(memory_store: mem, event_stream: es, audit_store: audit))
         bus.register(:memory_add_note, Insika::Commands::MemoryAddNote.new(memory_store: mem, event_stream: es))
+        # the LGPD access right — the Studio Customers drill exports.
+        bus.register(:export_customer_memory, Insika::Commands::ExportCustomerMemory.new(memory_store: mem, event_stream: es))
         bus.register(:update_settings, Insika::Commands::UpdateSettings.new(settings_store: c[:settings_store], event_stream: es))
         bus.register(:upsert_llm_provider, Insika::Commands::UpsertLLMProvider.new(provider_store: c[:provider_store], configurator: c[:configurator], event_stream: es))
         bus.register(:delete_llm_provider, Insika::Commands::DeleteLLMProvider.new(provider_store: c[:provider_store], configurator: c[:configurator], event_stream: es))
@@ -303,7 +312,7 @@ module Insika
         ([provider_name] + @packs.filter_map { |p| Insika::Coercion.presence(p.config[:provider])&.to_s }).uniq
       end
 
-      # RFC-0017 A2 — the graph's credentials belong to the graph. `RubyLLM.context`
+      # the graph's credentials belong to the graph. `RubyLLM.context`
       # is an isolated dup of the config that answers #chat, so two graphs in one
       # process no longer overwrite each other's keys: the global
       # `RubyLLM.configure` is a single slot PER PROVIDER, and the loser of that
@@ -332,7 +341,7 @@ module Insika
 
       # The LLMConfigurator's target (Studio: edit a provider key, no restart).
       # Scoped to THIS graph's context — a `RubyLLM.configure` here would reach
-      # into every other graph in the process, which is the leak A2 exists to
+      # into every other graph in the process, which is the leak exists to
       # close. nil = no context (test stub) -> the configurator's own global
       # default, unchanged.
       def llm_configure

data/lib/insika/dsl/server_boot.rb

@@ -25,23 +25,28 @@ module Insika
         # Fixed local token: logs into the Studio (cookie) and gates /v1 (Bearer).
         # Never a real secret — override with `token:` or ADMIN_TOKEN.
         @token = token || ENV.fetch("ADMIN_TOKEN", "local-demo")
-        # RFC-0017 A3: the /v1 app is a value now — the same one a host mounts.
+        # the /v1 app is a value now — the same one a host mounts.
         # This boot adds the Studio and a reactor around it, nothing else.
         @builder = Insika::Server::AppBuilder.new(runtime, token: @token)
       end
 
       def run
+        # The boot refusal (shadow + no criterion) lives in the AppBuilder; run it
+        # BEFORE the Studio is configured so the criterion the Studio folds is the
+        # same object the delivery path stamps pairs with.
+        @builder.channels?
+        register_parity_commands
         configure_studio
         dispatch = Rack::URLMap.new("/studio" => Studio::App, "/" => @builder.app)
         endpoint = Async::HTTP::Endpoint.parse("http://#{@host}:#{@port}")
         middleware = Protocol::Rack::Adapter.new(dispatch)
-        # Item 16 / P4: the OTEL bridge is opt-in but must be reachable from the DSL
+        # the OTEL bridge is opt-in but must be reachable from the DSL
         # front door too — the convention is worthless if only config.ru can export.
         # nil (the default) -> attach is a no-op and no gem is loaded.
         telemetry = Insika::Telemetry.setup(service_name: ENV.fetch("OTEL_SERVICE_NAME", "insika"))
 
         banner(telemetry)
-        # RFC-0016 A3: first Ctrl-C/SIGTERM closes the intake and drains in-flight
+        # first Ctrl-C/SIGTERM closes the intake and drains in-flight
         # turns (INSIKA_DRAIN_TIMEOUT, default 20s); a second signal skips the wait.
         Insika::Shutdown.install(executor: @graph.executor)
         Async do
@@ -56,6 +61,23 @@ module Insika
       def workflows? = @builder.workflows?
       def channels? = @builder.channels?
 
+      # The parity page renders whenever a shadow channel exists, so the judge
+      # button must reach a registered command — the deployment bus registers the
+      # same one (config/deployment.rb); a page that answers "unknown command"
+      # would make this root a second-class citizen. Registered only when the
+      # criterion loaded (a command without one would be a fake judge).
+      def register_parity_commands
+        criterion = @builder.criterion
+        return unless criterion
+
+        @graph.bus.register(:judge_shadow_pairs,
+                            Insika::Commands::JudgeShadowPairs.new(
+                              shadow_pairs: @graph.shadow_pair_store,
+                              settings_store: @rt.component(:settings_store),
+                              criterion: criterion, event_stream: @graph.event_stream
+                            ))
+      end
+
       def configure_studio
         Studio::App.configure(
           command_bus: @graph.bus, profile_source: @graph.profiles,
@@ -64,15 +86,63 @@ module Insika
           agent_file_store: @rt.component(:agent_file_store), skill_store: @rt.component(:skill_store),
           skill_catalog: @graph.skill_catalog, tool_catalog: @graph.tool_catalog,
           tool_store: @rt.component(:tool_store), memory_store: @graph.memory_store,
+          # the Customers drill renders the audit lines.
+          memory_audit_store: @graph.memory_audit_store,
           session_store: @graph.session_store,
           settings_store: @rt.component(:settings_store), llm_provider_store: @rt.component(:provider_store),
           mcp_store: @rt.component(:mcp_store), system_file_store: @rt.component(:system_file_store),
           tool_trace_store: @rt.component(:tool_trace_store),
+          context_trace_store: @rt.component(:context_trace_store),
+          # the per-agent cache-hit series (agent-detail card).
+          cache_series_store: @rt.component(:cache_series_store),
           task_store: @graph.task_store, checkpoint_store: @graph.checkpoint_store,
-          pending_action_store: @graph.pending_action_store
+          pending_action_store: @graph.pending_action_store,
+          # WS7: the agents-grid scorecard reads the outcome store.
+          outcome_store: @graph.outcome_store,
+          # the outcome-funnel page reads the fold's cells and the
+          # BudgetLedger's current counters (D6); the only mutation — the
+          # baseline freeze — dispatches :freeze_funnel_baseline on the bus.
+          funnel_store: @graph.funnel_store,
+          budget_ledger: @graph.budget_ledger,
+          # the parity page (only rendered when a shadow channel exists —
+          # the nav row keys off the registry).
+          shadow_pair_store: @graph.shadow_pair_store,
+          parity_criterion: @builder.criterion,
+          channel_registry: @graph.channel_registry,
+          # the Follow-ups page reads the stores directly;
+          # its only mutations (cancel, force-revoke) dispatch bus commands.
+          followup_store: @graph.followup_store,
+          contact_store: @graph.contact_store,
+          # the Facts (wiki) page reads the proposal store
+          # directly; its mutations dispatch :resolve_proposal on the bus.
+          proposal_store: @graph.proposal_store,
+          # the Harvest page reads the harvest store + the two
+          # pre-registered artifacts directly; its mutations dispatch the
+          # harvest bus commands. The criterion/negative list load best-effort
+          # (nil = the page renders the refusal/empty states).
+          harvest_store: @graph.harvest_store,
+          harvest_criterion: harvest_criterion,
+          negative_list: harvest_negative_list
         )
       end
 
+      # The frozen criterion — best-effort at boot: a bare install
+      # without the env var renders the ruler's hole instead of
+      # crashing the Studio.
+      def harvest_criterion
+        path = Insika::EnvSchema.read("INSIKA_HARVEST_CRITERION")
+        path && Insika::Harvest::Criterion.load(path)
+      rescue Insika::ConfigError, Insika::ValidationError
+        nil
+      end
+
+      def harvest_negative_list
+        path = Insika::EnvSchema.read("INSIKA_HARVEST_NEGATIVE")
+        path && Insika::Harvest::NegativeList.parse(File.read(path))
+      rescue Errno::ENOENT
+        nil
+      end
+
       def persistence
         @graph.durable? ? "durable (sqlite)" : "ephemeral (memory)"
       end

data/lib/insika/dsl/system.rb

@@ -17,7 +17,7 @@ module Insika
     class System
       attr_reader :definitions, :workflows, :runtime_options
 
-      # `backend`: the store this system's graph owns (RFC-0017 A1). nil = the
+      # `backend`: the store this system's graph owns. nil = the
       # historic path (INSIKA_DB, or memory when unset). Set by `Insika.embed`.
       def initialize(definitions:, workflows: [], runtime: {}, backend: nil)
         @definitions = definitions.freeze

data/lib/insika/dsl.rb

@@ -3,17 +3,17 @@
 require_relative "pack"
 
 module Insika
-  # Public Ruby DSL (item 36 / §13.3) — the OSS "business card":
+  # Public Ruby DSL — the OSS "business card":
   #
   #   agent = Insika.agent("assistant") do
-  #     model "deepseek-chat"
+  #     model "deepseek-v4-flash"
   #     instructions "You are a concise, friendly assistant."
   #   end
   #   puts agent.reply("hi, what can you do?")   # one turn, in-process
   #   agent.serve                                # control UI + /v1 on :9292
   #
   # It is THIN SUGAR that GENERATES the data (a Insika::Pack), never a bypass of
-  # config-over-code (COMPETITIVE-ANALYSIS §4.1). `Insika.agent { … }.to_pack`
+  # config-over-code (COMPETITIVE-ANALYSIS). `Insika.agent { … }.to_pack`
   # is the same portable artifact the PackImporter consumes at runtime — the DSL
   # and a hand-written pack produce the SAME profile (the parity spec proves it),
   # because BOTH go through the standard import → StoredProfileSource round-trip.
@@ -153,7 +153,7 @@ module Insika
 
       # A DATA-DEFINED (declarative HTTP) tool — pure config-over-code. `defn` is a
       # ToolDefinition hash (name/description/parameters/binding…). Its name is
-      # auto-added to the allowlist so the agent can call its own tool (NF2).
+      # auto-added to the allowlist so the agent can call its own tool.
       def data_tool(defn)
         h = defn.transform_keys(&:to_s)
         @tools << h
@@ -173,9 +173,31 @@ module Insika
         n
       end
 
+      # skills_eager — turns progressive disclosure off for THIS agent, wholly or in
+      # part. The body of an eager skill is in the prompt on every turn, so its
+      # activation is not a decision and cannot be missed; it is paid for on every
+      # turn, so measure the bodies against `context_budget` first (a stable position
+      # makes them a cacheable prefix).
+      #
+      #   skills_eager                       # every allowed skill
+      #   skills_eager "formato", "markers"  # exactly these
+      #   skills_eager false                 # none (the default)
+      #
+      # A LIST and not a per-skill flag because skills are shared: `escalation-to-human`
+      # sits in several allowlists, and one flag on the skill would force one decision
+      # onto every agent holding it.
+      def skills_eager(*names)
+        flat = names.flatten
+        @config[:skills_eager] =
+          if flat.empty? then true
+          elsif flat == [true] || flat == [false] then flat.first
+          else flat.map(&:to_s)
+          end
+      end
+
       # --- delegation ------------------------------------------------------
       # subagents "security", "performance" → the child agents this one MAY
-      # spawn (RFC-0010). CAPACITY field: opt-in, never inherited, and the ids
+      # spawn. CAPACITY field: opt-in, never inherited, and the ids
       # must be agents of the same system (`Insika.system { … }`) or already in
       # the store. Present ⇒ the engine wires `spawn_subagent`/`spawn_subagents`.
       def subagents(*ids)
@@ -185,23 +207,138 @@ module Insika
       # --- knobs -----------------------------------------------------------
       def memory(on = true) = @config[:memory] = on
 
-      # Content-safety guardrails (RFC-0009) — opt-in and configurable per agent.
+      # Spend caps per calendar window (WS2): daily/monthly token budgets for
+      # this agent, per (tenant, agent) when multi-tenant. HARD is the default:
+      # absent `soft:` (or `soft: false`) turns the cap into a hard wall (the
+      # turn fails with budget_exceeded + retry_after); `soft: true` warns once
+      # per window and keeps running.
+      #   budget daily: 100_000, monthly: 2_000_000, soft: false
+      def budget(hash) = (@config[:budget] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The outcome funnel declaration: the store's stage vocabulary
+      # as pack data — the engine folds WS7 outcome kinds into the DECLARED
+      # stages, and never hard-codes one itself. Merges, so repeated calls
+      # accumulate (like budget).
+      #   funnel stages: %w[greeted qualified cart paid],
+      #          advance_on: { "pix_paid" => "paid", "abandoned_cart" => "cart" },
+      #          primary: "paid", attribution_window: "72h"
+      def funnel(hash) = (@config[:funnel] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The follow-up declaration: the agent may book a follow-up
+      # with a customer at a future time (`schedule` tool); the engine fires the
+      # synthetic turn and enforces the policy (quiet hours, max frequency,
+      # cancellation keywords, silence detection) at fire time. Pack data —
+      # merges, so repeated calls accumulate (like budget).
+      #   followup arm: "schedule",
+      #            policy: { quiet_hours: { timezone: "America/Sao_Paulo",
+      #                                     start: "21:30", end: "09:00" },
+      #                      max_frequency: "2/24h",
+      #                      cancel_keywords: ["não quero mais contato"],
+      #                      silence_after_sends: 3 }
+      def followup(hash) = (@config[:followup] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The session-distillation declaration: what counts as a fact
+      # for THIS store, distilled from finished customer conversations. Pack
+      # data — merges, so repeated calls accumulate (like budget). `prompt` and
+      # `model` are pack-authored keys the DSL passes through.
+      #   distill enabled: true, idle_hours: 6, max_proposals: 10
+      def distill(hash) = (@config[:distill] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The gated-harvest declaration: the engine may read this
+      # agent's finished traffic and propose SKILLS for the store's playbook —
+      # through the negative list, the grounding filter and the double gate,
+      # never applied automatically. Pack data — merges, so repeated calls
+      # accumulate (like budget). `prompt`/`model` are pack-authored keys the
+      # DSL passes through.
+      #   harvest enabled: true,
+      #           negative_list: [ { rule: "no-competitor-prices", pattern: "concorrente" } ],
+      #           miner: { model: "deepseek-v4-flash", window: { last_sessions: 200 } }
+      def harvest(hash) = (@config[:harvest] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # Provider-interaction reliability, as DATA (WS3): retries + exponential
+      # backoff on transient failures, a fallback model chain (mid-turn
+      # rotation), and a circuit breaker per (tenant, provider/model) that
+      # fail-fasts once the window trips. `fallback`/`circuit_breaker` entries
+      # are "provider/model" refs or plain model ids.
+      #   reliability retries: 3, backoff: "exponential",
+      #               fallback: ["gpt-4o-mini"], circuit_breaker: { after: 10, within: 60, cooldown: 300 }
+      def reliability(hash)
+        (@config[:reliability] ||= {}).merge!(hash.transform_keys(&:to_s))
+      end
+
+# Operator alert delivery (WS6): POST this agent's budget_warning /
+      # breaker_open / delivery_failed events to the webhook as JSON.
+      def alerts(hash) = (@config[:alerts] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # Intent routing (WS4): classify each turn's message into one route with a
+      # cheap model BEFORE the ask. A Hash: route name -> description (or a Hash
+      # with description/delegate/stuck/message), plus the reserved keys
+      # "default" (the deterministic fallback) and "model"/"provider" (the cheap
+      # classifier). The classifier prompt is generated — data only.
+      #   routes "shopping" => "the customer wants to browse products",
+      #          "order"    => { "description" => "asks about an existing order",
+      #                          "delegate" => "order-agent" },
+      #          "human"    => { "description" => "the customer asks for a person",
+      #                          "stuck" => true },
+      #          "default"  => "shopping", "model" => "deepseek-v4-flash"
+      def routes(hash) = (@config[:routes] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The agent may signal it cannot proceed (WS5): when on, the model
+      # can call `signal_stuck`, which ends the turn with `outcome: :stuck` + a final
+      # message + a `:turn_stuck` event. What "stuck" means is the consumer's call.
+      #   stuck_signal true
+      def stuck_signal(on = true) = @config[:stuck_signal] = on
+
+      # The per-session working-state schema this agent keeps and asks for
+      # a flat list of field names. [] = off (no provider output,
+      # no update_briefing/set_next_step tools).
+      #   briefing_fields "size", "budget", "delivery_day"
+      def briefing_fields(*names)
+        @config[:briefing_fields] = names.flatten.map(&:to_s)
+      end
+
+      # Generated-media output policy (WS9, saída): the media kinds this
+      # agent MAY generate as turn outputs, with per-kind config. The other
+      # half of the gate is the CHANNEL's: the request must declare the
+      # matching capability for the tools to exist at all.
+      #   outputs image: { model: "gpt-image-1", size: "1024x1024" },
+      #           tts:   { model: "tts-1", voice: "alloy" }
+      def outputs(hash) = (@config[:outputs] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The engine's "Tool discipline" block in the system prompt (retry a
+      # weak/empty tool result with a different approach before giving up).
+      # ON by default — this setter exists to turn it OFF:
+      #   tool_persistence false
+      def tool_persistence(on = true) = @config[:tool_persistence] = on
+
+      # Mechanical tool-result dedupe in the replayed history
+      # (no-LLM compaction, apt for bloated transcripts). CHANGES WHAT THE MODEL
+      # SEES: repeated identical tool results collapse to a back-reference.
+      def tool_output_compression(on = true) = @config[:tool_output_compression] = on
+
+      # Content-safety guardrails — opt-in and configurable per agent.
       # Pure config-over-code: the hash is stored on the profile and consumed by
       # Safety::Config.from_profile. Merges, so repeated calls accumulate.
       #   guardrails input: true, output: true, strictness: "medium",
-      #              moderator: "deepseek/deepseek-chat",
+      #              moderator: "deepseek/deepseek-v4-flash",
       #              responses: { "injection" => "I can't help with that." }
       def guardrails(hash) = (@config[:guardrails] ||= {}).merge!(hash.transform_keys(&:to_s))
 
-      # Refinement (RFC-0013) — how the agent's own instruction files may be
+      # Evidence-grounding policy: the pack declares how the engine
+      # polices product claims against the evidence ledger. Same
+      # config-over-code shape as `guardrails`; absent = off (parity).
+      #   grounding mode: :flag, matcher: { sku: '\b[A-Z]{2,4}\d{4,8}\b' }
+      def grounding(hash = {}) = (@config[:grounding] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # Refinement — how the agent's own instruction files may be
       # improved from real traffic. Same config-over-code shape as `guardrails`;
-      # omitting it entirely leaves the agent report-only (phase A writes nothing).
+      # omitting it entirely leaves the agent report-only (writes nothing).
       #   refine mode: "propose", window: { last_sessions: 200 }, files: %w[TOOLS.md],
-      #          proposers: ["deepseek/deepseek-chat", "gpt-5-mini"],
+      #          proposers: ["deepseek/deepseek-v4-flash", "gpt-5-mini"],
       #          budget: { tokens: 200_000 }
       def refine(hash) = (@config[:refinement] ||= {}).merge!(hash.transform_keys(&:to_s))
 
-      # Facts about THIS deployment that are not tools (RFC-0014 §3.5), so an eval
+      # Facts about THIS deployment that are not tools, so an eval
       # case can declare what it needs and be skipped where it is absent instead of
       # failing for the wrong reason.
       #   declares "promotions", "human_handoff"
@@ -217,7 +354,7 @@ module Insika
       #   edge_stream thinking: true, intermediate: false
       def edge_stream(hash) = (@config[:edge_stream] ||= {}).merge!(hash.transform_keys(&:to_s))
 
-      # LLM generation params (v2, §10). `param :temperature, 0.2` or `params(...)`.
+      # LLM generation params. `param:temperature, 0.2` or `params(...)`.
       def param(key, value) = (@config[:params] ||= {})[key.to_sym] = value
       def params(hash) = (@config[:params] ||= {}).merge!(hash.transform_keys(&:to_sym))
       def temperature(value) = param(:temperature, value)
@@ -281,14 +418,14 @@ module Insika
     DSL.system(&block)
   end
 
-  # RFC-0017 A1 — the front door for MOUNTING Insika into an app you already
+  # the front door for MOUNTING Insika into an app you already
   # have. Same block as `Insika.system`, one added obligation: the caller names
   # the store, so the graph stops discovering it from `INSIKA_DB` and two graphs
   # in one process can no longer read each other's sessions.
   #
   #   INSIKA = Insika.embed(backend: Insika::Stores::SQLite.new(path: "storage/insika.sqlite3")) do
   #     agent "support" do
-  #       model "deepseek-chat"
+  #       model "deepseek-v4-flash"
   #       instructions "…"
   #     end
   #   end
@@ -296,7 +433,7 @@ module Insika
   #   mount Insika::Server.rack_app(INSIKA, token: ENV.fetch("INSIKA_TOKEN")), at: "/ai"
   #
   # It is a thin front door over the SAME assembly `Insika.system` uses — there is
-  # one pipeline (RFC-0001), and the parity spec holds it to that. What an embedded
+  # one pipeline, and the parity spec holds it to that. What an embedded
   # graph owns, and what it still shares with the process, is docs/EMBEDDING.md.
   def embed(backend:, &block)
     DSL.embed(backend: backend, &block)