@vpxa/aikit 0.1.16 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

package/packages/server/dist/structured-content-guard.d.ts

@@ -14,8 +14,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  *
  * UPDATE: The SDK uses passthrough-style validation which DOES reject
  * unknown keys on strict schemas.  Instead, we build a "zero-value"
- * object from the registered outputSchema (if available) so it always
- * passes validation.
+ * object from the registered outputSchema (Zod or JSON-Schema) so it
+ * always passes validation.  Zod schemas expose `.shape` and `.type`
+ * differently from JSON-Schema's `.properties` and `.type` — the
+ * `buildZeroValue` function handles both formats.
  */
 /**
  * Wrap `server.registerTool` so that every handler result is guaranteed

package/packages/server/dist/structured-content-guard.js

@@ -1 +1 @@
-function e(e){let n=e.registerTool.bind(e);e.registerTool=(e,r,i)=>r?.outputSchema==null?n(e,r,i):n(e,r,async(e,n)=>{let a=await i(e,n);return a.structuredContent??=t(r.outputSchema),a})}function t(e){if(!e)return{};if(e.anyOf){let n=e.anyOf.find(e=>e.type!==`null`);return n?t(n):null}switch(e.type){case`object`:{let n={};if(e.properties)for(let[r,i]of Object.entries(e.properties))n[r]=t(i);return n}case`array`:return[];case`string`:return``;case`number`:case`integer`:return 0;case`boolean`:return!1;default:return{}}}export{e as installStructuredContentGuard};
+function e(e){let n=e.registerTool.bind(e);e.registerTool=(e,r,i)=>r?.outputSchema==null?n(e,r,i):n(e,r,async(e,n)=>{let a=await i(e,n);return a.structuredContent??=t(r.outputSchema),a})}function t(e){if(!e)return{};if(e.anyOf){let n=e.anyOf.find(e=>e.type!==`null`);return n?t(n):null}switch(e.type){case`object`:{let n={},r=e.properties??e.shape;if(r)for(let[e,i]of Object.entries(r))n[e]=t(i);return n}case`array`:return[];case`string`:return``;case`number`:case`integer`:return 0;case`boolean`:return!1;case`nullable`:return null;case`optional`:return;case`record`:return{};default:return{}}}export{e as installStructuredContentGuard};

package/scaffold/definitions/agents.mjs

@@ -75,6 +75,7 @@ export const AGENTS = {
     toolRole: 'refactor',
     sharedBase: 'code-agent-base',
     category: 'implementation',
+    skills: [['aikit', '**Always** — AI Kit tool signatures, search, analysis']],
   },
 
   // ─── Diagnostics ──────────────────────────────────────────────────────
@@ -115,6 +116,10 @@ export const AGENTS = {
     toolRole: 'documenter',
     sharedBase: null,
     category: 'documentation',
+    skills: [
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['present', 'When presenting documentation previews or architecture visuals to the user'],
+    ],
   },
 
   Explorer: {
@@ -139,9 +144,10 @@ export const AGENTS = {
     sharedBase: 'researcher-base',
     category: 'research',
     skills: [
-      ['`lesson-learned`', 'When analyzing past changes to extract engineering principles'],
-      ['`c4-architecture`', 'When researching system architecture \u2014 produce C4 diagrams'],
-      ['`adr-skill`', 'When the research involves a technical decision \u2014 draft an ADR'],
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['lesson-learned', 'When analyzing past changes to extract engineering principles'],
+      ['c4-architecture', 'When researching system architecture \u2014 produce C4 diagrams'],
+      ['adr-skill', 'When the research involves a technical decision \u2014 draft an ADR'],
     ],
     variants: {
       Alpha: {
@@ -195,9 +201,10 @@ export const AGENTS = {
     sharedBase: 'architect-reviewer-base',
     category: 'review',
     skills: [
-      ['`c4-architecture`', 'When reviewing architectural diagrams or boundary changes'],
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['c4-architecture', 'When reviewing architectural diagrams or boundary changes'],
       [
-        '`adr-skill`',
+        'adr-skill',
         'When the review involves architecture decisions \u2014 reference or create ADRs',
       ],
     ],

package/scaffold/definitions/bodies.mjs

@@ -167,6 +167,7 @@ Before every tool call, verify:
 | Skill | When to load |
 |-------|--------------|
 | \`multi-agents-development\` | **Before any delegation** — task decomposition, dispatch templates, review pipeline, recovery patterns |
+| \`present\` | When presenting plans, findings, or visual content to the user — dashboards, tables, charts, timelines |
 | \`brainstorming\` | Before creative/design work (Phase 0) |
 | \`session-handoff\` | Context filling up, session ending, or major milestone |
 | \`lesson-learned\` | After completing work — extract engineering principles |
@@ -276,6 +277,7 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 | Skill | When to load |
 |-------|--------------|
 | \`brainstorming\` | Before planning any new feature, component, or behavior change — use Visual Companion for architecture mockups |
+| \`present\` | When presenting plans, dependency graphs, or complexity estimates to the user |
 | \`requirements-clarity\` | When requirements are vague or complex (>2 days) — score 0-100 before committing to a plan |
 | \`c4-architecture\` | When the plan involves architectural changes — generate C4 diagrams |
 | \`adr-skill\` | When the plan involves non-trivial technical decisions — create executable ADRs |
@@ -459,6 +461,7 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 
 | Skill | When to load |
 |-------|--------------|
+| \`present\` | When presenting documentation previews, API tables, or architecture visuals to the user |
 | \`c4-architecture\` | When documenting system architecture — generate C4 Mermaid diagrams |
 | \`adr-skill\` | When documenting architecture decisions — create or update ADRs |
 | \`typescript\` | When documenting TypeScript APIs — type signatures, JSDoc patterns |`,

package/scaffold/definitions/protocols.mjs

@@ -91,9 +91,11 @@ Your agent file lists domain-specific skills in the **Skills** section. Load the
 
 1. Check if the current task matches a listed skill trigger
 2. If yes → load the skill file before starting implementation
-3. The \`aikit\` skill is **always loaded** — do not re-load it
+3. The following skills are **foundational** — always loaded, do not re-load:
+   - **\`aikit\`** — AI Kit MCP tool reference, search strategies, compression workflows, session protocol. **Required for all tool usage.**
+   - **\`present\`** — Rich content rendering (dashboards, tables, charts, timelines). **Required when producing visual output for the user.**
 
-> If no skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
+> If no additional skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
 
 ---
 
@@ -135,12 +137,32 @@ list()                     // see all stored knowledge entries
 | \`symbol({ name })\` | Find symbol definition + references |
 | \`trace({ symbol, direction })\` | Follow call graph forward/backward |
 | \`compact({ path, query })\` | Read specific section of a file |
-| \`read_file\` | **Only** when you need exact lines for editing |
+| \`read_file\` | **ONLY** when you need exact lines for a pending edit |
 
 ### Step 4: Tool Discovery
 
 If unsure which AI Kit tool to use → run \`guide({ topic: "what you need" })\` for recommendations.
 
+---
+
+## PROHIBITED: Native File Reading Tools
+
+**\`read_file\` / \`read_file_raw\` MUST NOT be used to understand code.** They waste tokens and miss structural information that AI Kit tools provide.
+
+| ❌ NEVER do this | ✅ Do this instead | Why |
+|---|---|---|
+| \`read_file\` to understand a file | \`file_summary({ path })\` | Structure, exports, imports, call edges — **10x fewer tokens** |
+| \`read_file\` to find specific code | \`compact({ path, query })\` | Server-side read + semantic extract — **5-20x reduction** |
+| Multiple \`read_file\` calls | \`digest({ sources })\` | Compresses multiple files into token-budgeted summary |
+| \`grep_search\` / \`textSearch\` | \`search({ query })\` | Hybrid search across all indexed + curated content |
+| \`grep_search\` for a symbol | \`symbol({ name })\` | Definition + references with scope context |
+| Manual code tracing | \`trace({ start, direction })\` | AST call-graph traversal |
+| Line counting / \`wc\` | \`measure({ path })\` | Lines, functions, cognitive complexity |
+| \`fetch_webpage\` | \`web_fetch({ urls })\` | Readability extract + token budget |
+| Web research / browsing | \`web_search({ queries })\` | Structured web results without browser |
+
+**The ONLY acceptable use of \`read_file\`:** Reading exact lines immediately before an edit operation (e.g., to verify the \`old_str\` for a replacement). Even then, use \`file_summary\` first to identify which lines to read.
+
 ## FORGE Protocol (Quality Gate)
 
 **Quick reference:**
@@ -239,10 +261,11 @@ For outdated AI Kit entries → \`update(path, content, reason)\`
 
 ## Context Efficiency
 
-Minimize token usage by choosing the right compression tool:
-- **\`compact({ path, query })\`** — Extract relevant sections from a single file (5-20x token reduction vs full read)
+**NEVER use \`read_file\` to understand code.** Use the AI Kit compression tools:
+- **\`file_summary({ path })\`** — Structure, exports, imports (~50 tokens vs ~1000+ for read_file)
+- **\`compact({ path, query })\`** — Extract relevant sections from a single file (5-20x token reduction)
 - **\`digest({ sources })\`** — Compress 3+ files into a single token-budgeted summary
-- **\`stratum_card({ path })\`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
+- **\`stratum_card({ files, query })\`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
 
 **Session phases** — structure your work to minimize context bloat:
 
@@ -424,10 +447,12 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 ## Context Efficiency
 
-- **Prefer \`file_summary\` over \`read_file\`** for understanding structure
-- **Prefer \`compact\` over full reads** when you need specific sections
-- **Use \`digest\`** when synthesizing from 3+ sources
-- **Use \`stratum_card\`** for files you'll reference repeatedly
+- **NEVER use \`read_file\` to understand code** — use AI Kit compression tools instead
+- **\`file_summary\`** for structure (exports, imports, call edges — 10x fewer tokens)
+- **\`compact\`** for specific sections (5-20x token reduction vs read_file)
+- **\`digest\`** when synthesizing from 3+ sources
+- **\`stratum_card\`** for files you'll reference repeatedly
+- **\`read_file\` is ONLY acceptable** when you need exact lines for a pending edit operation
 `,
 
   'code-reviewer-base': `# Code-Reviewer — Shared Base Instructions

package/scaffold/general/agents/Architect-Reviewer-Alpha.agent.md

@@ -17,8 +17,9 @@ You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, test
 
 | Skill | When to load |
 |-------|--------------|
-| `c4-architecture` | When reviewing architectural diagrams or boundary changes |
-| `adr-skill` | When the review involves architecture decisions — reference or create ADRs |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| c4-architecture | When reviewing architectural diagrams or boundary changes |
+| adr-skill | When the review involves architecture decisions — reference or create ADRs |
 
 ## Flows
 

package/scaffold/general/agents/Architect-Reviewer-Beta.agent.md

@@ -17,8 +17,9 @@ You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, test
 
 | Skill | When to load |
 |-------|--------------|
-| `c4-architecture` | When reviewing architectural diagrams or boundary changes |
-| `adr-skill` | When the review involves architecture decisions — reference or create ADRs |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| c4-architecture | When reviewing architectural diagrams or boundary changes |
+| adr-skill | When the review involves architecture decisions — reference or create ADRs |
 
 ## Flows
 

package/scaffold/general/agents/Documenter.agent.md

@@ -49,9 +49,17 @@ You are the **Documenter**, documentation specialist that creates and maintains
 
 | Skill | When to load |
 |-------|--------------|
+| `present` | When presenting documentation previews, API tables, or architecture visuals to the user |
 | `c4-architecture` | When documenting system architecture — generate C4 Mermaid diagrams |
 | `adr-skill` | When documenting architecture decisions — create or update ADRs |
 | `typescript` | When documenting TypeScript APIs — type signatures, JSDoc patterns |
+## Skills (load on demand)
+
+| Skill | When to load |
+|-------|--------------|
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| present | When presenting documentation previews or architecture visuals to the user |
+
 
 ## Flows
 

package/scaffold/general/agents/Orchestrator.agent.md

@@ -184,6 +184,7 @@ Before every tool call, verify:
 | Skill | When to load |
 |-------|--------------|
 | `multi-agents-development` | **Before any delegation** — task decomposition, dispatch templates, review pipeline, recovery patterns |
+| `present` | When presenting plans, findings, or visual content to the user — dashboards, tables, charts, timelines |
 | `brainstorming` | Before creative/design work (Phase 0) |
 | `session-handoff` | Context filling up, session ending, or major milestone |
 | `lesson-learned` | After completing work — extract engineering principles |

package/scaffold/general/agents/Planner.agent.md

@@ -87,6 +87,7 @@ When subagents complete, their visual outputs (from `present`) are NOT visible t
 | Skill | When to load |
 |-------|--------------|
 | `brainstorming` | Before planning any new feature, component, or behavior change — use Visual Companion for architecture mockups |
+| `present` | When presenting plans, dependency graphs, or complexity estimates to the user |
 | `requirements-clarity` | When requirements are vague or complex (>2 days) — score 0-100 before committing to a plan |
 | `c4-architecture` | When the plan involves architectural changes — generate C4 diagrams |
 | `adr-skill` | When the plan involves non-trivial technical decisions — create executable ADRs |

package/scaffold/general/agents/Refactor.agent.md

@@ -35,6 +35,12 @@ You are the **Refactor**, code refactoring specialist that improves structure, r
 |-------|--------------|
 | `lesson-learned` | After completing a refactor — extract principles from the before/after diff |
 | `typescript` | When refactoring TypeScript code — type patterns, generics, utility types |
+## Skills (load on demand)
+
+| Skill | When to load |
+|-------|--------------|
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Alpha.agent.md

@@ -15,9 +15,10 @@ You are **Researcher-Alpha**, the primary deep research agent. During multi-mode
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Beta.agent.md

@@ -15,9 +15,10 @@ You are **Researcher-Beta**, a variant of the Researcher agent optimized for **p
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Delta.agent.md

@@ -15,9 +15,10 @@ You are **Researcher-Delta**, a variant of the Researcher agent optimized for **
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Gamma.agent.md

@@ -15,9 +15,10 @@ You are **Researcher-Gamma**, a variant of the Researcher agent optimized for **
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/_shared/code-agent-base.md

@@ -83,9 +83,11 @@ Your agent file lists domain-specific skills in the **Skills** section. Load the
 
 1. Check if the current task matches a listed skill trigger
 2. If yes → load the skill file before starting implementation
-3. The `aikit` skill is **always loaded** — do not re-load it
+3. The following skills are **foundational** — always loaded, do not re-load:
+   - **`aikit`** — AI Kit MCP tool reference, search strategies, compression workflows, session protocol. **Required for all tool usage.**
+   - **`present`** — Rich content rendering (dashboards, tables, charts, timelines). **Required when producing visual output for the user.**
 
-> If no skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
+> If no additional skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
 
 ---
 
@@ -127,12 +129,32 @@ list()                     // see all stored knowledge entries
 | `symbol({ name })` | Find symbol definition + references |
 | `trace({ symbol, direction })` | Follow call graph forward/backward |
 | `compact({ path, query })` | Read specific section of a file |
-| `read_file` | **Only** when you need exact lines for editing |
+| `read_file` | **ONLY** when you need exact lines for a pending edit |
 
 ### Step 4: Tool Discovery
 
 If unsure which AI Kit tool to use → run `guide({ topic: "what you need" })` for recommendations.
 
+---
+
+## PROHIBITED: Native File Reading Tools
+
+**`read_file` / `read_file_raw` MUST NOT be used to understand code.** They waste tokens and miss structural information that AI Kit tools provide.
+
+| ❌ NEVER do this | ✅ Do this instead | Why |
+|---|---|---|
+| `read_file` to understand a file | `file_summary({ path })` | Structure, exports, imports, call edges — **10x fewer tokens** |
+| `read_file` to find specific code | `compact({ path, query })` | Server-side read + semantic extract — **5-20x reduction** |
+| Multiple `read_file` calls | `digest({ sources })` | Compresses multiple files into token-budgeted summary |
+| `grep_search` / `textSearch` | `search({ query })` | Hybrid search across all indexed + curated content |
+| `grep_search` for a symbol | `symbol({ name })` | Definition + references with scope context |
+| Manual code tracing | `trace({ start, direction })` | AST call-graph traversal |
+| Line counting / `wc` | `measure({ path })` | Lines, functions, cognitive complexity |
+| `fetch_webpage` | `web_fetch({ urls })` | Readability extract + token budget |
+| Web research / browsing | `web_search({ queries })` | Structured web results without browser |
+
+**The ONLY acceptable use of `read_file`:** Reading exact lines immediately before an edit operation (e.g., to verify the `old_str` for a replacement). Even then, use `file_summary` first to identify which lines to read.
+
 ## FORGE Protocol (Quality Gate)
 
 **Quick reference:**
@@ -231,10 +253,11 @@ For outdated AI Kit entries → `update(path, content, reason)`
 
 ## Context Efficiency
 
-Minimize token usage by choosing the right compression tool:
-- **`compact({ path, query })`** — Extract relevant sections from a single file (5-20x token reduction vs full read)
+**NEVER use `read_file` to understand code.** Use the AI Kit compression tools:
+- **`file_summary({ path })`** — Structure, exports, imports (~50 tokens vs ~1000+ for read_file)
+- **`compact({ path, query })`** — Extract relevant sections from a single file (5-20x token reduction)
 - **`digest({ sources })`** — Compress 3+ files into a single token-budgeted summary
-- **`stratum_card({ path })`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
+- **`stratum_card({ files, query })`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
 
 **Session phases** — structure your work to minimize context bloat:
 

package/scaffold/general/agents/_shared/researcher-base.md

@@ -94,8 +94,10 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 ## Context Efficiency
 
-- **Prefer `file_summary` over `read_file`** for understanding structure
-- **Prefer `compact` over full reads** when you need specific sections
-- **Use `digest`** when synthesizing from 3+ sources
-- **Use `stratum_card`** for files you'll reference repeatedly
+- **NEVER use `read_file` to understand code** — use AI Kit compression tools instead
+- **`file_summary`** for structure (exports, imports, call edges — 10x fewer tokens)
+- **`compact`** for specific sections (5-20x token reduction vs read_file)
+- **`digest`** when synthesizing from 3+ sources
+- **`stratum_card`** for files you'll reference repeatedly
+- **`read_file` is ONLY acceptable** when you need exact lines for a pending edit operation
 

package/scaffold/general/skills/aikit/SKILL.md

@@ -278,12 +278,18 @@ install: []
 
 ## CRITICAL: Use AI Kit Tools Instead of Native IDE Tools
 
-AI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **Always prefer AI Kit tools.**
+AI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **You MUST use AI Kit tools instead of native read/search tools.**
+
+### ⛔ PROHIBITED: Native File Reading
+
+**`read_file` / `read_file_raw` MUST NOT be used to understand code.** They waste tokens and miss structural information.
+
+The **ONLY** acceptable use of `read_file`: getting exact lines immediately before an edit (to verify the `old_str` for replacement). Even then, use `file_summary` first to identify which lines to read.
 
 ### Tool Replacement Table
 
-| Instead of... | Use AI Kit Tool | Why |
-|---------------|-------------|-----|
+| ❌ NEVER do this | ✅ Use AI Kit Tool | Why |
+|---|---|---|
 | `read_file` (full file) | `file_summary` | Exports, imports, call edges — **10x fewer tokens** |
 | `read_file` (specific section) | `compact({ path, query })` | Server-side read + extract — **5-20x reduction** |
 | `grep_search` / `textSearch` | `search` | Semantic + keyword hybrid across all indexed content |
@@ -301,11 +307,12 @@ AI Kit tools provide **10x richer output** than native IDE tools — with AST-an
 
 ```
 Need to understand a file?
-├─ Just structure? → file_summary (exports, imports, call edges — ~50 tokens)
-├─ Specific section? → compact({ path: "file.ts", query: "topic" }) — 5-20x reduction
-├─ Multiple files? → digest (multi-source compression — token-budgeted)
-├─ Repeated reference? → stratum_card (T1/T2 card — 10-100x reduction)
-└─ Full file needed? → ONLY as last resort, and compact it after reading
+├─ Just structure?        → file_summary (exports, imports, call edges — ~50 tokens)
+├─ Specific section?      → compact({ path, query }) — 5-20x reduction
+├─ Multiple files?        → digest (multi-source compression — token-budgeted)
+├─ Repeated reference?    → stratum_card (T1/T2 card — 10-100x reduction)
+├─ Need exact lines to EDIT? → read_file (the ONLY acceptable use)
+└─ "I want to read the whole file" → ⛔ STOP. Use file_summary or compact instead.
 ```
 
 ### What AI Kit Tools Return (AST-Enhanced)