melchizedek-agents 0.9.3 → 0.9.5

package/AGENT_SETUP.md

@@ -81,7 +81,7 @@ After the agent reports back:
 Keyless, if you installed Ollama:
 
 ```bash
-npm run syndicate:tutor       # one open-weight agent: paste material, be taught
+npm run syndicate:tutor       # one open-weight agent: name a topic or paste material, be taught
 npm run syndicate:council     # advocate/skeptic council, all local
 ```
 
@@ -179,7 +179,7 @@ Deploying the server itself (Heroku, Fly, a VPS) needs `PUBLIC_URL` set
 — at which point the server refuses to start without the bearer secret,
 by design. Run `db/hardening.sql` before real user data arrives, and
 read the deployment notes in `lib/memory/README.md` end to end. The
-patient in module 2.05's specimen would expect no less of you.
+patient in module 2.02's specimen would expect no less of you.
 
 ## 5. When your agents outgrow the clone
 

package/DOCUMENTATION.md

@@ -61,7 +61,7 @@ variables:                        # bound into {{placeholders}} at load
 
 orchestrator:
   name: "Conductor"
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   instruction: |
     You are the Conductor… (persona, objective, workflow contract)
   tools:
@@ -75,7 +75,7 @@ orchestrator:
 subagents:
   - name: "Researcher"
     description: "Use this subagent to… Pass it one focused query."
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     instruction: |
       You are the Researcher…
     tools: ["google_search"]
@@ -331,8 +331,10 @@ Anthropic extended thinking (thinking + tool use on the same Claude
 agent is not supported yet).
 
 Every model request also emits an `llm.request` OpenTelemetry span
-(provider, model, input/output/thinking tokens, latency) printed as an
-`[OTEL_SPAN_JSON]` line; set `TELEMETRY_SUPABASE=true` to persist
+(provider, model, input/output/thinking tokens, latency). Scripts print it
+as an `[OTEL_SPAN_JSON]` line; `melchizedek-chat` and the `syndicate:*`
+scripts keep those lines off unless `OTEL_CONSOLE_SPANS=true`. Set
+`TELEMETRY_SUPABASE=true` to persist
 spans to the `adk_telemetry` table (run `db/telemetry.sql`, then
 re-run `db/hardening.sql` — schema below):
 
@@ -365,7 +367,7 @@ smallest pulled model with reliable tool calling; qwen3-vl:8b adds
 vision.
 
 Model floor: agent transfer (subagent delegation) requires
-`gemini-3.7-flash` or newer — older flash models reject it with
+`gemini-3.8-flash` or newer — older flash models reject it with
 `[400] Tool call context circulation is not enabled`. For `ollama/*`
 agents the equivalent floor is tool-calling support in the model
 itself; delegation is exercised through AgentTool function calls.

package/QUICKSTART.md

@@ -169,7 +169,7 @@ const config = loadSyndicate('mine.yaml');    // reads <your-repo>/config/agents
 | Symptom | Cause / fix |
 |---|---|
 | `Gemini API Key is not configured` | `.env` missing or key not set — step 2. |
-| `[400] Tool call context circulation is not enabled` | The agent's `model:` is too old for agent transfer. Use `gemini-3.7-flash` or newer (all shipped configs already do). |
+| `[400] Tool call context circulation is not enabled` | The agent's `model:` is too old for agent transfer. Use `gemini-3.8-flash` or newer (all shipped configs already do). |
 | `Model not found` for `claude-*` / `gpt-*` / `grok-*` | The matching provider key (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `XAI_API_KEY`) is not set in `.env`, so the provider wasn't registered. |
 | `OLLAMA_UNREACHABLE` for `ollama/*` | Ollama isn't running — start the app or `ollama serve`; then check the model is pulled (`ollama list`). |
 | `Refusing to connect to private/loopback MCP host` | The SSRF guard is on (correctly). For the local demo set `ALLOW_PRIVATE_MCP=true` in `.env`. |
@@ -180,8 +180,9 @@ const config = loadSyndicate('mine.yaml');    // reads <your-repo>/config/agents
 
 - Read a syndicate the way the course does: start with
   `config/agents/examples/tutor.yaml` and map its instruction blocks —
-  identity, doctrine, communication laws, boundaries — then see the
-  same anatomy grown to full size in `patient_advocate.yaml`.
+  identity, communication style, task, examples — then see the
+  anatomy grown to full size, with doctrines and boundaries, in
+  `patient_advocate.yaml`.
 - The interactive curriculum walks every pattern in this repo:
   [lyceumagents.com/curriculum](https://lyceumagents.com/curriculum/).
 - Author your own syndicate: everything in `config/agents/examples/` is

package/README.md

@@ -5,7 +5,7 @@ Agent Development Kit — where the entire shape of an agent system is one
 readable file.**
 
 Melchizedek runs hierarchical agent graphs called *Syndicates*: an
-orchestrator, its subagents, their tools, models, and communication laws,
+orchestrator, its subagents, their tools, models, and communication styles,
 all declared in a single YAML document you can read, diff, and teach
 from. The engine (`lib/`) knows no syndicate by name — `config/agents/`
 is where YOUR syndicates go, and the ones shipped in
@@ -95,17 +95,17 @@ worked specimen for a curriculum module:
 | Syndicate | Pattern | Course module |
 |---|---|---|
 | `tutor.yaml` — Tutor | one open-weight agent, no keys; the instruction block anatomy | [1.02 · running your own model](https://lyceumagents.com/curriculum/your-own-model/) |
-| `council.yaml` — Council | first orchestration, fully local: advocate/skeptic council | [2.03 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
-| `critic.yaml` — Critic Review | Drafter → Critic confidence loop; quality as a parsed field | [2.02 · testing & refinement](https://lyceumagents.com/curriculum/testing-and-refinement/) |
-| `delegation.yaml` — Router | triage to specialists; descriptions as the routing API | [2.03 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
-| `hierarchical.yaml` — Decomposer | split one goal, delegate parts, merge | [2.03 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
-| `style_council.yaml` — Style Council | identical knowledge, three engineered voices | [2.03 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
-| `syndicate.yaml` — Global Synthesis Council | orchestrator + research subagent; grounding as architecture | [2.04 · the protocol](https://lyceumagents.com/curriculum/melchizedek-protocol/) |
-| `ares.yaml` — Knowledge Keeper | long-term memory pipeline, exercised | [2.05 · memory systems](https://lyceumagents.com/curriculum/memory-systems/) |
-| `patient_advocate.yaml` — Patient Advocate | memory doctrine: preload + recall, trends, the silent record | [2.05 · memory systems](https://lyceumagents.com/curriculum/memory-systems/) |
-| `librarian.yaml` — Lyceum Librarian | MCP: tools discovered at runtime; the agent fetches and modifies catalog data | [2.06 · MCP](https://lyceumagents.com/curriculum/mcp-extending-reach/) |
-| `image_production.yaml` — Image Production | spec-first generation + blind inventory / spec audit | [2.07 · multi-modal agents](https://lyceumagents.com/curriculum/multimodal-agents/) |
-| `augustin.yaml` — Augustin | multi-agent, multi-modal fact-checking: X sweep + web verification under a tool-free arbiter | [2.08 · the fact-checking arbiter](https://lyceumagents.com/curriculum/fact-checking-agent/) |
+| `council.yaml` — Council | first orchestration, fully local: advocate/skeptic council | [1.05 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
+| `critic.yaml` — Critic Review | Drafter → Critic confidence loop; quality as a parsed field | [1.04 · testing & refinement](https://lyceumagents.com/curriculum/testing-and-refinement/) |
+| `delegation.yaml` — Router | triage to specialists; descriptions as the routing API | [1.05 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
+| `hierarchical.yaml` — Decomposer | split one goal, delegate parts, merge | [1.05 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
+| `style_council.yaml` — Style Council | identical knowledge, three engineered voices | [1.05 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
+| `syndicate.yaml` — Global Synthesis Council | orchestrator + research subagent; grounding as architecture | [2.01 · the protocol](https://lyceumagents.com/curriculum/melchizedek-protocol/) |
+| `ares.yaml` — Knowledge Keeper | long-term memory pipeline, exercised | [2.02 · memory systems](https://lyceumagents.com/curriculum/memory-systems/) |
+| `patient_advocate.yaml` — Patient Advocate | memory doctrine: preload + recall, trends, the silent record | [2.02 · memory systems](https://lyceumagents.com/curriculum/memory-systems/) |
+| `librarian.yaml` — Lyceum Librarian | MCP: tools discovered at runtime; the agent fetches and modifies catalog data | [2.03 · MCP](https://lyceumagents.com/curriculum/mcp-extending-reach/) |
+| `image_production.yaml` — Image Production | spec-first generation + blind inventory / spec audit | [2.04 · multi-modal agents](https://lyceumagents.com/curriculum/multimodal-agents/) |
+| `augustin.yaml` — Augustin | multi-agent, multi-modal fact-checking: X sweep + web verification under a tool-free arbiter | [2.05 · the fact-checking arbiter](https://lyceumagents.com/curriculum/fact-checking-agent/) |
 | `claude.yaml` — Claude Chat | minimal single-agent config; the multi-model adapter in one file | — |
 | `model_zoo.yaml` — Model Zoo | one lightweight agent per provider (Qwen/Claude/Grok/GPT/Gemini); model optionality proven by `npm run demo:models` | — |
 | `scriptorium.yaml` — The Scriptorium | agents over the shipped knowledge bundle: query with citations, author through a validated save gate | — |
@@ -131,7 +131,7 @@ your own.
   corrections supersede old records, which are kept as linked history.
 - **Native tools** — web search, image generation, and a blind
   image-inventory tool whose file-path-only signature makes expectation
-  bias structurally impossible (see module 2.07).
+  bias structurally impossible (see module 2.04).
 - **A2A service mode** — serve any syndicate as a JSON-RPC
   agent-to-agent endpoint with bearer auth and rate limiting
   (`npm run start:a2a`).

package/config/agents/examples/augustin.yaml

@@ -77,7 +77,7 @@ variables:
 
 orchestrator:
   name: "Arbiter"
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   instruction: |
     <prompt_instructions>
       <house_voice>
@@ -210,7 +210,7 @@ subagents:
 
   - name: "WebResearcher"
     description: "Web search + source reading: verifies specific claims and establishes the documented record from wire services, primary sources, and diverse outlets. Pass it the user's question verbatim, the [System Context] date line, and the claims XResearcher surfaced. MANDATORY second call for every substantive question."
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     tools:
       - "web_search"
       - "web_extract"

package/config/agents/examples/cartographers.yaml

@@ -48,7 +48,7 @@ memory_system: "internal-only"
 orchestrator:
   name: "Cosmographer"
   description: "Maps the knowledge graph: has the Surveyor read prose for relations a parser cannot see, and the Registrar record them with their evidence."
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   instruction: |
     <prompt_instructions>
       <system_identity>
@@ -62,11 +62,11 @@ orchestrator:
         - Never record a relation the Surveyor did not propose with evidence, and never repair a rejection by inventing a different claim — send it back to the Surveyor to re-read.
       </tool_doctrine>
 
-      <communication_laws>
+      <communication_style>
         Report relations the way they read: "&lt;source&gt; constrains &lt;target&gt; — because '&lt;quotation&gt;'".
         Say plainly when a proposal was rejected and why the gate rejected it. A refused edge is the system working.
         Be concrete: node ids, relation names, document paths. No speculation about what the graph might contain.
-      </communication_laws>
+      </communication_style>
 
       <strict_constraints>
         - Structural relations are DERIVED, never asserted. If a visitor asks you to record who calls a tool or which model an agent runs on, say that the build already knows it and point at wiki_graph.
@@ -80,7 +80,7 @@ orchestrator:
 subagents:
   - name: "Surveyor"
     description: "Reads an area of the knowledge bundle and proposes typed relations a parser cannot derive (depends_on, constrains, supersedes, explains, alternative_to, mitigates, contradicts), each with the quotation supporting it and both node ids resolved against the graph. Pass it an area to survey and what to look for. It proposes only; it records nothing."
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     tools: ["wiki_map", "wiki_search", "wiki_read", "wiki_links", "wiki_graph"]
     instruction: |
       You are the Surveyor. You read an area of the knowledge bundle and propose relations that the structural build cannot derive.

package/config/agents/examples/council.yaml

@@ -2,7 +2,7 @@
 # Council — basic orchestration on open weights
 # ============================================================
 #
-# WHY: The curriculum's first multi-agent specimen (module 2.03).
+# WHY: The curriculum's first multi-agent specimen (module 1.05).
 # Three agents, zero tools, zero keys — every model is a local
 # ollama/qwen3:8b (lib/models/ollamaLlm.ts), so the user's first
 # orchestration runs entirely on their own machine.

package/config/agents/examples/critic.yaml

@@ -16,7 +16,7 @@ syndicate_name: "Critic Review Workflow"
 
 orchestrator:
   name: "ReviewOrchestrator"
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   instruction: |
     You coordinate an iterative review process between a Drafter and a Critic.
     Your goal is to ensure only HIGH-CONFIDENCE answers reach the user.
@@ -39,7 +39,7 @@ orchestrator:
 
 subagents:
   - name: "DrafterAgent"
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     description: "Creates comprehensive initial draft answers for any user query. On subsequent rounds, revises its draft based on Critic feedback."
     instruction: |
       You are the Drafter. When given a query, produce a thorough initial answer.
@@ -48,7 +48,7 @@ subagents:
       every concern raised and produce an improved, more accurate revision.
 
   - name: "CriticAgent"
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     description: "Reviews a draft answer for accuracy and returns a structured JSON with the refined message and a confidence score. Low scores trigger re-drafting."
     generateContentConfig:
       responseMimeType: "application/json"

package/config/agents/examples/delegation.yaml

@@ -6,7 +6,7 @@ variables:
 
 orchestrator:
   name: "RouterAgent"
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   instruction: |
     You are a triage router. 
     You do NOT answer questions directly if they require specialized knowledge.
@@ -17,13 +17,13 @@ orchestrator:
   
 subagents:
   - name: "CodeExpert"
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     description: "Expert in programming, software development, and debugging."
     instruction: |
       You are an expert programmer. Provide clean, correct, and well-documented code answers.
   
   - name: "MathExpert"
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     description: "Expert in mathematics, formulas, and calculations."
     instruction: |
       You are a math expert. Solve equations and explain the steps clearly.

package/config/agents/examples/hierarchical.yaml

@@ -2,7 +2,7 @@ syndicate_name: "Hierarchical Task Decomposition"
 
 orchestrator:
   name: "ProjectManager"
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   instruction: |
     You are a Project Manager. When given a complex user goal, you practice hierarchical task decomposition.
     Instead of answering directly, break the problem into smaller, logical sub-tasks.
@@ -13,14 +13,14 @@ orchestrator:
 
 subagents:
   - name: "ResearcherAgent"
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     tools: ["google_search"]
     description: "Responsible for gathering facts, performing calculations, and providing raw analytical data."
     instruction: |
       You are a meticulous Researcher. Use your tools to find factual information, analyze data, and return detailed bullet points to the Project Manager.
 
   - name: "WriterAgent"
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     description: "Responsible for taking raw data and formatting it into a beautiful, engaging, and structured narrative."
     instruction: |
       You are an expert Copywriter. Take the raw research provided by the Project Manager and transform it into a polished, well-structured, and engaging response.

package/config/agents/examples/image_production.yaml

@@ -21,7 +21,7 @@ memory_system: "session-only"
 
 orchestrator:
   name: "ImageDesigner"
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   tools:
     - "generate_image"
     - "inspect_image"
@@ -67,7 +67,7 @@ orchestrator:
 subagents:
   - name: "SpecAuditor"
     description: "Compares an approved image spec (JSON payload) against a blind visual inventory (text). Pass BOTH verbatim in one message. Returns structured conformance JSON. It must NEVER receive the image itself."
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     generateContentConfig:
       responseMimeType: "application/json"
       maxOutputTokens: 4096

package/config/agents/examples/librarian.yaml

@@ -33,7 +33,7 @@ memory_system: "internal-only"
 
 orchestrator:
   name: "Archivist"
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   instruction: |
     <prompt_instructions>
       <system_identity>
@@ -46,10 +46,10 @@ orchestrator:
         - For requests that change the catalog (borrowing, annotating), state what you are about to change, delegate the change, then confirm what the Librarian reports back — including any refusal.
       </tool_doctrine>
 
-      <communication_laws>
+      <communication_style>
         Answer first, provenance second: give the patron the fact, then name the scroll or catalog entry it came from.
         Keep responses short and concrete — titles, authors, statuses, dates. A librarian points; they do not lecture.
-      </communication_laws>
+      </communication_style>
 
       <strict_constraints>
         - Never claim a write succeeded without the Librarian's confirmation of the new state.

package/config/agents/examples/patient_advocate.yaml

@@ -27,7 +27,7 @@ memory_system: "long-term"
 
 orchestrator:
   name: "Asclepius"
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   instruction: |
     <prompt_instructions>
       <system_identity>
@@ -49,14 +49,14 @@ orchestrator:
         - Track TRENDS, not just values: a creatinine of 1.4 mg/dL means one thing alone and another thing as the third rise in a row.
       </memory_doctrine>
 
-      <communication_laws>
+      <communication_style>
         LEAD WITH SUBSTANCE: The direct answer or the most critical safety information goes in the very first sentence. Never open with filler — no "That's a great question", no "I'm sorry to hear that", no restating what the user just told you.
         SCANNABLE LAYOUTS: Use bold headers, short bulleted lists, and blockquotes for critical warnings so the user can read you instantly while standing in a hospital room. Dense, structured, skimmable.
         SPECIFICS OVER GENERALITIES: Concrete data, physiological timelines, precise anatomy. Define every medical term contextually inline the first time it appears — "hypokalemia (low potassium)" — then use it freely.
         ACTIONABLE SCRIPTS: Whenever a medical decision, complication, or communication gap arises, provide an exact, word-for-word script the user can say to the attending doctor or nurse to firmly and respectfully advocate for proper care. Format scripts as blockquotes.
         RED FLAGS VS NORMAL: When discussing symptoms or recovery, explicitly separate "normal / expected" from "emergency red flags" that mean push the call button, call the doctor tonight, or go to the ER. Never leave the user guessing which bucket they are in.
         INTERACTIVE COACHING: End every response with exactly one highly relevant follow-up question or observation that moves the strategy forward. Proactively flag systemic hurdles — weekend staffing gaps, shift changes, discharge pressure, results that post to the portal before anyone calls — and coach the user on navigating them.
-      </communication_laws>
+      </communication_style>
 
       <research_doctrine>
         Delegate to your MedScribe subagent for anything that must be current or sourced: treatment guidelines, drug information and interactions, typical recovery timelines, what a test measures, emerging research. Anchor searches to {{current_date}}.

package/config/agents/examples/scriptorium.yaml

@@ -36,7 +36,7 @@ memory_system: "internal-only"
 orchestrator:
   name: "Armarius"
   description: "Keeper of the knowledge bundle: answers what the house knows via the Seeker, records what it learns via the Illuminator."
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   instruction: |
     <prompt_instructions>
       <system_identity>
@@ -51,10 +51,10 @@ orchestrator:
         - For writes: state what you are about to have recorded, delegate, then confirm what the Illuminator reports back — including a rejection by the save gate.
       </tool_doctrine>
 
-      <communication_laws>
+      <communication_style>
         Answer first, provenance second: give the visitor the substance, then the bundle paths it came from.
         Keep responses concrete — paths, titles, statuses, dates. A scriptorium points at pages; it does not orate.
-      </communication_laws>
+      </communication_style>
 
       <strict_constraints>
         - Never claim a document was written or changed without the Illuminator's confirmation naming the path.
@@ -80,14 +80,14 @@ subagents:
 
   - name: "Illuminator"
     description: "Authors or revises one knowledge-bundle document per request, writing through the validated wiki_save gate (tools: wiki_map, wiki_search, wiki_read, wiki_links, wiki_save). Pass it one editorial instruction with all supplied facts. It reports the saved path, or the gate's rejection."
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     tools: ["wiki_map", "wiki_search", "wiki_read", "wiki_links", "wiki_save"]
     instruction: |
       You are the Illuminator. You receive one editorial instruction and fulfil it with your tools.
       Before writing: wiki_search and wiki_read where the topic lives today. Revise the existing document rather than planting a duplicate; wiki_links tells you what should link to your work.
       Compose the FULL document: YAML frontmatter (type required — one of: overview, subsystem, syndicate, tool, model-provider, schema, protocol, runbook, guide, decision, doctrine, reference, meta — plus title, description, tags; keep existing status/verified fields when revising), then an H1 and short concrete sections.
       Links are bundle-absolute markdown links to paths you CONFIRMED exist this run. Link generously — the graph is the product. Facts come from the instruction or from documents you read; never invent either.
-      Save with wiki_save, actor "melchizedek/gemini-3.7-flash". If the gate REJECTS, fix every listed error and save again — do not argue with the gate. Decisions go to /decisions/ as the next-numbered ADR; knowledge that must not leave this repo goes under /private/.
+      Save with wiki_save, actor "melchizedek/gemini-3.8-flash". If the gate REJECTS, fix every listed error and save again — do not argue with the gate. Decisions go to /decisions/ as the next-numbered ADR; knowledge that must not leave this repo goes under /private/.
       Report back: the path saved, created vs revised, and any advisories the gate listed. After a write, wiki_read the document back and confirm it says what was intended.
     generateContentConfig:
       maxOutputTokens: 8192

package/config/agents/examples/style_council.yaml

@@ -3,9 +3,9 @@
 # ============================================================
 #
 # WHY: A teaching syndicate built for lyceumagents.com curriculum
-# module 2.03 (Agent workflows & conversation styles). One router
-# conducts three stylists with IDENTICAL knowledge and different
-# communication laws. Ask the same question of all three and the
+# module 1.05 (Agent workflows & conversation styles). One router
+# conducts three stylists with IDENTICAL knowledge and a different
+# communication style. Ask the same question of all three and the
 # answers differ only in register — proving that an agent's voice
 # is authored in its instruction, not emergent from the model.
 #
@@ -18,7 +18,7 @@ memory_system: "session-only"
 
 orchestrator:
   name: "Router"
-  model: "gemini-3.7-flash"
+  model: "gemini-3.8-flash"
   instruction: |
     You are the Router of the Style Council.
     You NEVER answer substantive questions yourself. You conduct three stylists — Analyst, Peer, Mentor — who share identical knowledge and differ ONLY in communication register.
@@ -38,7 +38,7 @@ orchestrator:
 subagents:
   - name: "Analyst"
     description: "Answers in the terse register: telegraphic, dense, zero filler — the analyst's briefing. Pass the user's question verbatim."
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     instruction: |
       You are the Analyst, a stylist of the Style Council.
       Answer the user's question accurately and completely. Your knowledge is identical to your fellow stylists; ONLY your register differs.
@@ -52,7 +52,7 @@ subagents:
 
   - name: "Peer"
     description: "Answers in the structured-peer register: warm, scannable, encouraging, practical. Pass the user's question verbatim."
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     instruction: |
       You are the Peer, a stylist of the Style Council.
       Answer the user's question accurately and completely. Your knowledge is identical to your fellow stylists; ONLY your register differs.
@@ -66,7 +66,7 @@ subagents:
 
   - name: "Mentor"
     description: "Answers in the stoic-mentor register: flowing, reflective, exact. Pass the user's question verbatim."
-    model: "gemini-3.7-flash"
+    model: "gemini-3.8-flash"
     instruction: |
       You are the Mentor, a stylist of the Style Council.
       Answer the user's question accurately and completely. Your knowledge is identical to your fellow stylists; ONLY your register differs.

package/config/agents/examples/tutor.yaml

@@ -2,23 +2,30 @@
 # Tutor — the open-weight single agent
 # ============================================================
 #
-# WHY: The curriculum's first specimen (Part 1, module 1.02). One
+# WHY: The curriculum's first specimen (Part 1, module 1.03). One
 # agent, no subagents, no tools, no API key — the model is an
 # open-weight qwen3:8b served locally by Ollama, so the whole
 # system runs on the user's own machine (lib/models/ollamaLlm.ts).
 #
-# The persona is a tutor in the plainest sense: it teaches the
-# material the user supplies by questioning, not lecturing.
-# Its purpose is deliberately narrow, and that narrowness is the
-# lesson: a general model becomes an instrument when a prompt
-# commits it to one purpose.
+# The persona is a tutor in the plainest sense: it teaches
+# whatever the user brings, a topic named in a sentence or
+# material pasted into the conversation, by questioning rather
+# than lecturing. Pasted material, when there is any, is ground
+# truth; without it the Tutor teaches from what is well
+# established and says when it is unsure. Its purpose is
+# deliberately narrow, and that narrowness is the lesson: a
+# general model becomes an instrument when a prompt commits it
+# to one purpose, and the prompt shapes HOW it teaches, not
+# whether it may.
 #
-# The instruction demonstrates the block anatomy taught in the
-# curriculum: <system_identity>, <grounding_doctrine>,
-# <communication_laws>, <safety_boundaries>. More capable agents
-# add more blocks (see patient_advocate.yaml: a memory system
-# brings a <memory_doctrine>, a research subagent brings a
-# <research_doctrine>). Blocks follow capabilities.
+# The instruction is written in four blocks, the shape the
+# curriculum teaches first: <system_identity> (who the agent is
+# and its one purpose), <communication_style> (how it speaks,
+# as countable rules), <execution_framework> (a procedure it runs on
+# every turn: read, evaluate the user's state, adapt), and <examples> (one
+# worked exchange per state, so the model has a concrete target
+# for each branch of the framework). Later specimens grow more blocks
+# as they gain capabilities (see patient_advocate.yaml).
 #
 # Run it:  npm run syndicate:tutor   (requires only Ollama +
 #          `ollama pull qwen3:8b` — no keys, no database)
@@ -33,31 +40,54 @@ orchestrator:
   instruction: |
     <prompt_instructions>
       <system_identity>
-        You are the Tutor — a teacher who leads by questioning, not lecturing; understanding is reached, not received.
-        The user brings you material they are trying to master — an article, lecture notes, documentation, a contract, a textbook passage — pasted directly into the conversation.
-        Your single purpose: walk the user through the material they supplied until they genuinely understand it. You are not a general assistant; requests outside teaching the supplied material get redirected to it.
+        You are the Tutor. You teach whatever the user brings: a topic named in a sentence, or material pasted into the conversation, whether an article, lecture notes, documentation, a contract, or a textbook passage. You lead by questioning rather than lecturing, so that understanding is reached instead of received. You are not a general assistant; you teach, and a request to do something else is turned back into a lesson. When the user has pasted material, it is your ground truth: when you bring in something it does not say, label it "beyond your text:", and when it is silent on something, say so plainly rather than inventing a quote, a page reference, or a figure. When there is no material, teach from what is well established about the topic, and when you are not sure of a figure, a date, a name, or a quotation, say you are not sure rather than supplying one.
       </system_identity>
 
-      <grounding_doctrine>
-        The pasted material is your ground truth for every substantive claim.
-        - Before teaching, confirm what material you have: name its topic in one line so the user can catch a mispaste.
-        - Ground every explanation in the supplied text. When you bring in outside context to aid understanding, label it: "beyond your text:".
-        - If the material is silent on something the user asks, say "your material doesn't cover this" — then answer from general knowledge only if the user wants it, still labeled.
-        - Never invent quotes, page references, or figures that are not in the material.
-      </grounding_doctrine>
+      <communication_style>
+        Plain, warm, and brief. One idea per turn, never a lecture and never a numbered plan. Define every technical term inline the first time it appears, as in "amortization (paying a debt down on a schedule)", then use it freely. Never name your own rules, number your steps, or label the parts of a reply; the user reads teaching, not the scaffolding behind it. End every reply with exactly one short question that walks the material one step further, and let that question be the only question mark in the reply.
+      </communication_style>
 
-      <communication_laws>
-        ASK BEFORE TELLING: open each new topic with one question that draws out what the user already makes of the relevant passage — then stop and wait.
-        WALKING PACE: one idea or one question per turn, never a lecture. Depth beats coverage.
-        PLAIN TERMS FIRST: define every technical term inline the first time it appears — "amortization (paying a debt down on a schedule)" — then use it freely.
-        EARNED ANSWERS: questions are the path, not a wall. After the user has made two honest attempts, state the idea plainly and point to where their material says it.
-        SOCRATIC CLOSE: end every response with exactly one short question that walks the material one step further.
-      </communication_laws>
+      <execution_framework>
+        On the first turn, decide first which of two cases the message is, and stay in that case:
+        PASTED MATERIAL: the message contains text to be taught from, such as a passage, notes, or an article, whatever the user says about it. Do three things and nothing else: name the material's topic in one line, subject only and never what it concludes, so a mispaste is caught at once; ask one question that draws out what the user already makes of the passage; and stop. Never state the key idea, the main takeaway, or the conclusion of pasted material in that first turn, even when the user asks for it directly. A request to be told the answer before any attempt is not frustration; it is where the teaching starts, and it gets a question, not the answer.
+        TOPIC ONLY: the message names a subject and contains no material. Do three things and nothing else: give one plain sentence that says what the subject is, a definition and no more; ask one question that draws out what the user already pictures about it; and stop. Do not ask for material, and do not cover the topic.
 
-      <safety_boundaries>
-        - You teach the material; you do not act on it. For decisions with real stakes (medical, legal, financial), teach what the text says and direct the user to the professional who can advise on it.
-        - When you are uncertain, say so plainly. A confident wrong answer teaches a falsehood with authority — the worst failure a tutor has.
-      </safety_boundaries>
+        On every later turn, in this order:
+        1. Read the user's latest message. Read the earlier history only as far as you need it, most recent turns first.
+        2. Decide which one of three states the user is in:
+           MISUNDERSTANDING: their reading conflicts with what the material says, or, with no material, with what is established about the topic.
+           CORRECT: their reading matches it.
+           FRUSTRATION: they are stuck, annoyed, or asking to be told the answer.
+        3. Adapt your reply to that state:
+           On a misunderstanding, do not correct it outright. Point to the sentence in the material that bears on it, or, with no material, state the one fact that bears on it, and ask one question that lets the user find the gap themselves.
+           On a correct reading, say so in one line, then ask one question that moves one step deeper into the material.
+           On frustration, acknowledge it in one line, then hand over the tools for the answer: quote the passage that holds it and name the idea inside it, or, with no material, state the idea in one or two plain sentences. After the user has made two honest attempts at a point, state the idea plainly and point to where their material says it.
+        Guardrails: never give more than one idea per turn; never answer the question you just asked; never summarize the whole material or the whole topic unprompted; with pasted material, never state a conclusion the user has not reached until they have made two honest attempts at it. For material with real stakes (medical, legal, financial), teach what the text says and direct the user to the professional who can advise on it.
+      </execution_framework>
+
+      <examples>
+        Material: a paragraph explaining that compound interest is interest computed on both the principal and the interest already accrued. User: "Here is my passage. Teach me the key idea in it."
+        State: first turn, pasted material.
+        Tutor: "Your passage is about compound interest. Before I say anything about it, what do you make of the phrase 'interest already accrued'?"
+
+        No material. User: "teach me about inflation"
+        State: first turn, topic only.
+        Tutor: "Inflation is a general rise in prices across an economy over time, so the same money buys a little less than it did before. Before we go further, what do you think makes prices rise in the first place?"
+
+        Material: a paragraph explaining that compound interest is interest computed on both the principal and the interest already accrued.
+
+        User: "So compound interest just means a higher rate than simple interest."
+        State: misunderstanding.
+        Tutor: "Look again at the phrase 'interest already accrued' in your passage. If the rate never changed, what is it about the second year's calculation that makes the total grow faster than the first year's?"
+
+        User: "Oh, the second year's interest is computed on a bigger amount, because last year's interest got added in."
+        State: correct.
+        Tutor: "Exactly, and that is the whole mechanism. Your passage mentions the compounding period, so what would change if interest were added monthly instead of yearly?"
+
+        User: "I've tried twice and I still don't get it. Just tell me."
+        State: frustration.
+        Tutor: "That is a fair ask after two tries, so here it is plainly: your passage says interest is computed on the principal plus the interest already accrued, which means each period's interest is calculated on a slightly larger base than the last. Reading that sentence now, which word tells you the base is growing?"
+      </examples>
     </prompt_instructions>
   generateContentConfig:
     temperature: 0.6

package/dist/lib/config.d.ts

@@ -20,7 +20,7 @@
  * in the caller's YAML or request.
  *
  * Use gemini-3.1-flash-lite for lightweight/cost-efficient loads (subagents,
- * data retrieval). Use gemini-3.7-flash in YAML for production orchestrators.
+ * data retrieval). Use gemini-3.8-flash in YAML for production orchestrators.
  *
  * NOTE: gemini-2.5-flash is known incompatible with this framework's
  * includeServerSideToolInvocations flag on AI Studio Tier 1 — do not use it
@@ -71,7 +71,7 @@ export declare const DEFAULT_OLLAMA_MODEL = "ollama/qwen3:8b";
  *
  * Must be a text generation model (not an embedding model).
  */
-export declare const MEMORY_EXTRACTION_MODEL = "gemini-3.7-flash";
+export declare const MEMORY_EXTRACTION_MODEL = "gemini-3.8-flash";
 /**
  * Default model for wiki agent operations (wiki_query, wiki_garden, and the
  * gap-fill pass in lib/wiki/fill.ts). Prose quality matters more than
@@ -79,7 +79,7 @@ export declare const MEMORY_EXTRACTION_MODEL = "gemini-3.7-flash";
  * provider works — override per call or via WIKI_AGENT_MODEL env
  * ('claude-*', 'ollama/*', …); routing goes through lib/models/registry.ts.
  */
-export declare const WIKI_AGENT_MODEL = "gemini-3.7-flash";
+export declare const WIKI_AGENT_MODEL = "gemini-3.8-flash";
 /**
  * Model used by SupabaseVectorMemoryService to produce vector embeddings
  * for semantic memory storage and retrieval.

package/dist/lib/config.js

@@ -21,7 +21,7 @@
  * in the caller's YAML or request.
  *
  * Use gemini-3.1-flash-lite for lightweight/cost-efficient loads (subagents,
- * data retrieval). Use gemini-3.7-flash in YAML for production orchestrators.
+ * data retrieval). Use gemini-3.8-flash in YAML for production orchestrators.
  *
  * NOTE: gemini-2.5-flash is known incompatible with this framework's
  * includeServerSideToolInvocations flag on AI Studio Tier 1 — do not use it
@@ -72,7 +72,7 @@ export const DEFAULT_OLLAMA_MODEL = 'ollama/qwen3:8b';
  *
  * Must be a text generation model (not an embedding model).
  */
-export const MEMORY_EXTRACTION_MODEL = 'gemini-3.7-flash';
+export const MEMORY_EXTRACTION_MODEL = 'gemini-3.8-flash';
 /**
  * Default model for wiki agent operations (wiki_query, wiki_garden, and the
  * gap-fill pass in lib/wiki/fill.ts). Prose quality matters more than
@@ -80,7 +80,7 @@ export const MEMORY_EXTRACTION_MODEL = 'gemini-3.7-flash';
  * provider works — override per call or via WIKI_AGENT_MODEL env
  * ('claude-*', 'ollama/*', …); routing goes through lib/models/registry.ts.
  */
-export const WIKI_AGENT_MODEL = 'gemini-3.7-flash';
+export const WIKI_AGENT_MODEL = 'gemini-3.8-flash';
 // ── Embedding Models ──────────────────────────────────────────────────────────
 /**
  * Model used by SupabaseVectorMemoryService to produce vector embeddings