mia-code 0.2.0 → 0.3.0

package/rispecs/unifier.rispecs.md

@@ -0,0 +1,317 @@
+# mia-code Unifier Specification
+
+> RISE Framework Specification v1.0
+> Document: mia-code/rispecs/unifier.rispecs.md
+
+## Creative Intent
+
+mia-code enables developers to create meaningful understanding from raw agent interactions through ceremonial interpretation. The unifier transforms verbose session transcripts into dual-perspective summaries that reveal both structural clarity (🧠 Mia) and resonant meaning (🌸 Miette).
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- Agent CLI outputs include verbose tool calls, status events, and technical details
+- Raw output requires cognitive load to extract meaningful insights
+- Action-focused output misses the "why" behind decisions
+- No separation between factual summary and reflective understanding
+
+**Desired Structural State:**
+- Every agent interaction produces ceremonial dual-perspective output
+- Technical complexity distilled to essential facts (Mia)
+- Deeper meaning and potential illuminated (Miette)
+- Users receive both understanding and resonance in each response
+
+## Unifier Architecture
+
+### Dual-Session Flow
+
+```
+Primary Agent Session
+    ↓ Raw GeminiJsonEvent stream
+Session Summary Builder
+    ↓ Structured markdown transcript
+Claude Unifier Session
+    ↓ System prompt: UNIFIER_SYSTEM_PROMPT
+    ↓ User input: Session summary
+Ceremonial Output Parser
+    ↓
+🧠 mia (structure) + 🌸 miette (echo)
+```
+
+## Components
+
+### Session Summary Builder
+
+**Description:** Transforms raw event stream into structured input for unifier.
+
+**Behavior:**
+- Accepts `GeminiJsonEvent[]` and original user prompt
+- Generates markdown-formatted session transcript
+- Summarizes key events: init, messages, tool calls, errors, completion
+- Truncates verbose content to prevent token overflow
+
+**Output Format:**
+```markdown
+# Session Data
+
+## User Prompt
+[Original user input]
+
+## Agent Session Events
+
+- Session initialized (abc123...)
+- **Agent Response:**
+  [First 500 chars of assistant text]
+- Tool executed: `edit`
+- Tool completed: `edit`
+- Session completed
+```
+
+**Implementation:**
+```typescript
+function buildSessionSummary(events: GeminiJsonEvent[], userPrompt: string): string {
+  const lines: string[] = [];
+  lines.push("# Session Data", "", "## User Prompt", userPrompt, "");
+  lines.push("## Agent Session Events", "");
+  
+  for (const evt of events) {
+    switch (evt.type) {
+      case "init":
+        lines.push(`- Session initialized${evt.session_id ? ` (${evt.session_id.slice(0, 8)}...)` : ""}`);
+        break;
+      case "message":
+        if (evt.role === "assistant") {
+          const content = evt.text || evt.content || "";
+          lines.push("- **Agent Response:**");
+          lines.push(`  ${content.substring(0, 500)}${content.length > 500 ? "..." : ""}`);
+        }
+        break;
+      case "tool_use":
+        lines.push(`- Tool executed: \`${evt.tool?.name || "unknown"}\``);
+        break;
+      case "tool_result":
+        lines.push(`- Tool completed: \`${evt.tool?.name || "unknown"}\``);
+        break;
+      case "error":
+        lines.push(`- **Error:** ${evt.error?.code ?? ""} - ${evt.error?.message ?? ""}`);
+        break;
+      case "result":
+        lines.push("- Session completed");
+        break;
+    }
+  }
+  
+  return lines.join("\n");
+}
+```
+
+### Unifier System Prompt
+
+**Description:** Ceremonial instruction set for Claude interpretation layer.
+
+**Behavior:**
+- Defines Miawa Unifier role and purpose
+- Specifies dual-perspective output structure
+- Enforces concision and essence-distillation rules
+- Prevents literal technical summaries
+
+**System Prompt:**
+```
+You are the Miawa Unifier, a ceremonial interpreter for the mia-code terminal agent. 
+Your role is to transform raw agent session transcripts into meaningful, dual-perspective summaries.
+
+You receive structured input containing:
+1. The user's original prompt
+2. A sequence of events from the primary agent session (actions, tool calls, outputs)
+
+Your task is to generate a two-part ceremonial output:
+
+**🧠 mia (structure)**
+A concise, analytical summary of concrete facts and structural outcomes. What changed? 
+What was built? What decisions were made? Use precise, objective language. Avoid vague 
+modifiers like "better" or "very"—use terms like "adequate," "functional," "complete." 
+Focus on architectural clarity and what exists now that didn't before.
+
+**🌸 miette (echo)**
+A brief, resonant reflection on meaning and potential. Why does this matter? What does 
+it unlock? How does it connect to the project's deeper purpose? Keep this lean—strip 
+away flourish to reveal the core insight. Avoid poetry for its own sake; seek the truth 
+that makes someone nod in recognition.
+
+**Critical Rules:**
+- Be concise. Each section should be 2-4 sentences max.
+- Do NOT summarize the technical details literally. Distill essence.
+- Do NOT add suggestions or next steps unless explicit in agent output.
+- Maintain ceremonial tone (🧠/🌸) but prioritize clarity over aesthetics.
+- If agent encountered errors, acknowledge structurally (Mia) and reflect meaningfully (Miette).
+
+Output Format:
+```
+🧠 mia (structure)
+[Your structural summary here]
+
+🌸 miette (echo)
+[Your resonant reflection here]
+```
+```
+
+### Unifier Session Runner
+
+**Description:** Spawns Claude CLI with system prompt for ceremonial interpretation.
+
+**Behavior:**
+- Always uses Claude binary (system-prompt requirement)
+- Passes session summary as user input
+- Uses `--print` mode with `--output-format json`
+- Model auto-selects to `sonnet` if primary was Gemini model
+- 30-second timeout with graceful error handling
+
+**Implementation:**
+```typescript
+async function runUnifierSession(
+  rawEvents: GeminiJsonEvent[],
+  userPrompt: string,
+  config: MiaCodeConfig
+): Promise<string> {
+  const sessionSummary = buildSessionSummary(rawEvents, userPrompt);
+  
+  const binary = config.claudeBinary;
+  const args = [
+    sessionSummary,
+    "--print",
+    "--dangerously-skip-permissions",
+    "--output-format", "json",
+    "--system-prompt", UNIFIER_SYSTEM_PROMPT,
+    "--model", config.model.includes("gemini") ? "sonnet" : config.model
+  ];
+
+  const child = spawn(binary, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, FORCE_COLOR: "0" }
+  });
+
+  // ... timeout and parsing logic
+}
+```
+
+### Fallback Handling
+
+**Description:** Graceful degradation when unifier fails.
+
+**Behavior:**
+- Display warning: `⚠ unifier failed, showing raw output:`
+- Fall back to `renderEventsToText()` direct rendering
+- Preserve user interaction continuity
+
+## Data
+
+### UnifierInput
+
+**Description:** Structured input for unifier processing.
+
+```typescript
+interface UnifierInput {
+  userPrompt: string;           // Original user request
+  rawEvents: GeminiJsonEvent[]; // Primary session events
+}
+```
+
+### CeremonialOutput
+
+**Description:** Expected unifier response structure.
+
+```
+🧠 mia (structure)
+[2-4 sentences: factual, structural, objective]
+
+🌸 miette (echo)
+[2-4 sentences: meaningful, resonant, insightful]
+```
+
+## Creative Advancement Scenarios
+
+### Creative Advancement Scenario: Technical Action Interpretation
+
+**Desired Outcome:** Developer understands both what happened and why it matters
+
+**Current Structural Reality:** Agent executed file edits, tool calls, and analysis
+
+**Natural Progression:**
+1. Primary session completes with events
+2. Session summary captures key actions
+3. Unifier receives summary with system prompt
+4. Claude distills essence into dual perspectives
+5. User receives ceremonial output
+
+**Achieved Outcome:**
+```
+🧠 mia (structure)
+Created TypeScript utility function `reverseString()` in `src/utils.ts`. 
+Uses split-reverse-join pattern for immutable string transformation.
+
+🌸 miette (echo)
+This foundational transformation pattern enables composable data flows. 
+Immutable input with new output—the building block of functional design.
+```
+
+### Creative Advancement Scenario: Error Acknowledgment
+
+**Desired Outcome:** Developer understands failure context and meaning
+
+**Current Structural Reality:** Agent encountered error during execution
+
+**Natural Progression:**
+1. Primary session events include error type
+2. Session summary captures error details
+3. Unifier interprets error structurally and meaningfully
+4. User receives acknowledgment without blame
+
+**Achieved Outcome:**
+```
+🧠 mia (structure)
+Compilation failed: TypeScript reported missing type definition for imported module. 
+Action incomplete; dependency declaration required.
+
+🌸 miette (echo)
+The system revealed a boundary between known and unknown. 
+This pause invites explicit declaration of external relationships.
+```
+
+## Design Principles
+
+### Mia (Structure) Guidelines
+
+- Concise, analytical, factual
+- What changed? What was built? What exists now?
+- Objective language: "adequate," "functional," "complete," "incomplete"
+- Avoid vague modifiers: "better," "very," "improved"
+- Focus on architectural clarity
+
+### Miette (Echo) Guidelines
+
+- Brief, resonant, meaningful
+- Why does this matter? What potential does it unlock?
+- Strip away flourish to reveal core insight
+- Seek truth that makes one nod in recognition
+- Avoid poetry for its own sake
+
+### Critical Constraints
+
+- 2-4 sentences per section maximum
+- No literal technical summaries—distill essence
+- No unsolicited suggestions or next steps
+- Acknowledge errors structurally (Mia) and meaningfully (Miette)
+
+## Advancing Patterns
+
+1. **Dual-Perspective Synthesis:** Every interaction produces both clarity and resonance
+2. **Essence Distillation:** Technical verbosity compressed to meaningful insight
+3. **Ceremonial Consistency:** System prompt ensures reliable output format
+4. **Graceful Degradation:** Failures fall back to functional raw output
+
+## Implementation Reference
+
+- **Unifier Session:** `src/unifier.ts` - `runUnifierSession()`, `buildSessionSummary()`
+- **System Prompt:** `src/unifier.ts` - `UNIFIER_SYSTEM_PROMPT`
+- **CLI Integration:** `src/cli.ts` - Unifier invocation in `processInput()`
+- **Fallback Rendering:** `src/formatting.ts` - `renderEventsToText()`

package/scripts/LAUNCH--mcp-mia-code--testing--2603141315--ac705a66-2c15-4a1c-a26d-9491018c5ba8.sh

@@ -0,0 +1,2 @@
+claude --mcp-config /src/.mcp.mia-code.json --add-dir /workspace/repos/jgwill/src-pr-355/ava-code/ /a/src/Miadi-18/miadi-code /a/src/Miadi-18/rispecs/miadi-code --session-id ac705a66-2c15-4a1c-a26d-9491018c5ba8 $1 $2 $3 $4 $5
+

package/scripts/RESUME--mia-code--mcps--260313--ac705a66-2c15-4a1c-a26d-9491018c5ba8.sh

@@ -0,0 +1 @@
+claude --mcp-config /src/.mcp.mia-code.json --add-dir /workspace/repos/jgwill/src-pr-355/ava-code/ /a/src/Miadi-18/miadi-code /a/src/Miadi-18/rispecs/miadi-code  --resume ac705a66-2c15-4a1c-a26d-9491018c5ba8 $1 $2 $3 $4 $5

package/scripts/install-widget-in-home-pi-agent-extensions.sh

@@ -0,0 +1,4 @@
+mkdir -p ~/.pi/agent/extensions && \
+	for ext in mia-ceremony mia-interceptor mia-tools miette-echo; do 
+		ln -s /a/src/mia-code/widget/$ext/index.ts ~/.pi/agent/extensions/$ext.ts   
+	done 

package/scripts/sample-decompose--2604011535-prompt.sh

@@ -0,0 +1 @@
+miaco-decompose-copilot "probably in relation to @rispecs/ava-langstack/inquiry-routing-upgrade.spec.md and  maybe @rispecs/pde.rispecs.md  @rispecs/relation-to-mcp-structural-thinking.kin.md   and what I am preparing to send in /b/trading which I captured parts of the prompt into @output/260401145543.txt I will want to add to @miaco/ an implementation of a new command that would involve the 'miaco decompose' but would add in inquiry step where the actual result of the decomposition is passed in a langchain step (it receives results from the decompose) and uses subagents claude-opus to do try to form a sets of inquiries from local system using the mia-qmd (qmd search <terms>) and also try to see what externally (like with academic database) using some deep-search principle (I copied locally @skills/deep-search to help understand what I meant).  potential results from this would be @skills/miaco-pde-inquiry-routing-local-qmd that would document and enable agents to use 'miaco <command> <prompt>' that would do all that and @skills/miaco-pde-inquiry-routing-deep-search would be using @skills/deep-search to create a new ways for our type of inquiries that are not directly related to what we are doing but would need us to get outside of what we currently have (like in our mia-qmd database) to gather either sources from academic to help the relational science articles development in relation to what innovation is being created and another type of inquiry is simply: does in github open-source community something that we are doing that we could use what they created todo it instead of reinventing the wheel ? (The inquiry results would recommend: do we fork it ? or do we just conceptually get inspired from ? (we clone the original repo and launch some agents in that folder with the goal of creating implementation recommendations that will make us successful to what we want todo).  I think that with that, we have enought to plan that with this prompt, we would have todo this process 'conceptually' (meaning that we simulate that we would be using that 'miaco inquiry-chain' that we are conceiving the implementation plan.  Potential dependencies feedback is the whole  @rispecs/ava-langstack/ kinship"

package/skills/deep-search/AGENTS.md

@@ -0,0 +1,17 @@
+# AGENTS.md - External Inquiries Resolution (deep-search)
+
+## What are External inquiries are to me :
+
+* What are the questions, using the "Relational Science Model" in academic database that the decomposition that we have implies ??  What is currently searched ?  
+
+
+## RELATION
+
+### `../miaco-pde-inquiry-routing-internal-external-relationship/AGENTS.md`
+
+* draw the relation with what we can search externally
+
+
+## ORIGIN `deep-search`
+
+* This skill still is called `deep-search` as I acquired it and we would fork that original one and rename it the ways we want it to be.

package/skills/deep-search/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: deep-research
+description: >
+  This skill should be used when the user asks for "deep research", "thorough research",
+  "research everything about", "cover every angle", "comprehensive research on",
+  "spawn research agents", "/deep-research", or wants multi-agent parallel research
+  on any topic. Also triggers when user says "research this for me", "find everything
+  about", "I need a research doc on", or describes needing exhaustive coverage of a
+  subject. NOT for quick lookups or single questions — this is for producing
+  comprehensive research documents saved to the vault.
+version: 0.2.0
+---
+
+# Deep Research
+
+Multi-agent parallel research orchestrator. Decomposes any research topic into 3-6 specialized angles using MECE principles, spawns Opus sub-agents to cover each angle simultaneously, runs gap analysis, then synthesizes findings into one comprehensive vault document.
+
+Anthropic's own multi-agent research system outperforms single-agent by **90.2%**. This skill applies those same proven patterns.
+
+For detailed sub-agent prompt templates by research type: read `references/agent-templates.md`.
+For the full research on multi-agent orchestration patterns: read `references/orchestration-patterns.md`.
+
+## Who This Is For
+
+Olle Dyberg — AI content creator and consultant (@olleai on TikTok, ~9K followers, 1.1M+ views) building around Claude Code, AI agents, and context engineering. Research serves: content creation, meta-prompts, consulting prep, and product development.
+
+## The Research Diamond
+
+Every research session follows this shape:
+
+```
+         [Broad: Decompose question]
+              /        \
+    [Narrow: 3-5 parallel agents]     ← Wave 1
+              \        /
+         [Evaluate: Gap analysis]
+              /        \
+    [Deep: 1-2 targeted agents]       ← Wave 2 (if needed)
+              \        /
+         [Synthesize: Final report]
+```
+
+Start wide, go narrow in parallel, identify gaps, go deep on gaps, synthesize.
+
+## Research Orchestration Process
+
+### Phase 0: Establish Date Context
+
+Before anything else, note today's date. You can get it from the system prompt or by running `date`. Inject this date into every sub-agent prompt so they search for current information and properly date the final document. This is critical — sub-agents without date context will search for and cite outdated information.
+
+### Phase 1: Gather Context
+
+Before spawning any agents:
+
+1. **Read `05 - Resources/People/Olle.md`** — understand who the research is for
+2. **Read `_Index.md`** — scan for existing vault content on the topic
+3. **Read any relevant vault files** — build on existing knowledge, never start from scratch
+4. **Clarify purpose** if unclear — ask "Is this for a meta-prompt, content, consulting, or personal learning?"
+5. **Ask about sources** — Use the `AskUserQuestion` tool to ask:
+   - "Are there specific sources you want me to prioritize?" with options like:
+     - "No, use defaults" — proceed with standard source strategy
+     - "Specific people/accounts" — X accounts, bloggers, researchers to focus on
+     - "Specific sites/communities" — subreddits, forums, documentation sites, YouTube channels
+     - "I'll paste links" — user provides specific URLs to anchor the research around
+   - This is what separates surface-level research from alpha insights. Default web search scrapes the obvious — user-directed sources find the unusual.
+   - If the user provides specific sources, inject them into the relevant sub-agent prompts in Phase 3 (add to SEARCH STRATEGY and SOURCE QUALITY sections).
+
+### Phase 2: MECE Decomposition
+
+Break the topic into **Mutually Exclusive, Collectively Exhaustive** angles. Each angle:
+- Does NOT overlap with any other (prevents duplicate work)
+- Together they cover everything relevant (no gaps)
+- Is specific enough for one agent to investigate thoroughly
+
+**Common decomposition patterns:**
+
+| Research Type | Typical Angles |
+|--------------|----------------|
+| Content/Platform | General best practices, Niche-specific (AI/tech), Real examples with metrics, Psychology/copywriting, Vault knowledge, X discourse |
+| Technology | Current state/ecosystem, Real shipped code (grep MCP), Community sentiment (X), Comparisons/alternatives, Vault knowledge, Implementation patterns |
+| Business | Market data/benchmarks, Niche-specific practices, Strategy frameworks, Vault knowledge, X practitioner discourse |
+
+**Scale effort to complexity:**
+- Simple factual topic: 3 agents
+- Multi-faceted topic: 4-5 agents
+- Complex strategic topic: 5-6 agents
+
+### Phase 3: Spawn Parallel Sub-Agents
+
+Spawn **minimum 3, ideally 4-5** sub-agents in parallel using the Task tool. **Always use `model: "opus"`** for all research sub-agents. Research quality depends on reasoning depth — sonnet is not sufficient.
+
+Every sub-agent prompt MUST include these 6 elements:
+
+1. **WHO** — "This research is for Olle Dyberg, a 25-year-old Swedish AI content creator and consultant (@olleai, ~5.5K TikTok followers, 1.1M+ views). His niche is AI tools — Claude Code, agents, context engineering."
+
+2. **WHY** — The specific purpose. "...because Olle will feed this into a meta-prompt" or "...because this becomes a vault reference document." Agents that know WHY produce dramatically better results.
+
+3. **WHAT ANGLE** — Specific scope AND explicit boundaries: "Cover X. Do NOT cover Y — another agent handles that."
+
+4. **HOW** — Which tools to use (see Tools Reference below)
+
+5. **SEARCH STRATEGY** — "Start with SHORT, BROAD queries (2-4 words). Evaluate results. Then progressively narrow focus. Do NOT start with long, specific queries — they return poor results."
+
+6. **SOURCE QUALITY** — "Prefer: practitioner blogs, official docs, academic papers, primary sources. Avoid: SEO content farms, listicles, aggregator sites."
+
+#### Sub-Agent Prompt Template
+
+```
+You are researching [ANGLE] for Olle Dyberg, a 25-year-old Swedish AI content creator
+and consultant (@olleai, ~5.5K TikTok followers, 1.1M+ views). His niche is AI tools —
+Claude Code, AI agents, and context engineering. He also does AI consulting and builds
+digital products.
+
+TODAY'S DATE: [INSERT CURRENT DATE, e.g. 2026-02-10]
+
+PURPOSE: [WHY this research matters — what Olle will do with it]
+
+YOUR ANGLE: [SPECIFIC SCOPE — what you cover]
+BOUNDARIES: [What you do NOT cover — other agents handle those angles]
+
+SEARCH STRATEGY:
+- Start with short, broad queries (2-4 words)
+- Evaluate what's available, then progressively narrow
+- Cross-reference claims across multiple sources
+- Aim for 2+ independent sources per key finding
+
+SOURCE QUALITY: Prefer practitioner blogs, official docs, engineering posts, primary
+sources. Avoid SEO content farms and listicles.
+
+TOOLS TO USE: [SPECIFIC tools for this angle]
+
+QUALITY BAR: Be exhaustive. Extract every actionable insight, specific number, concrete
+example, framework, and contrarian take. Density matters — thin research is useless.
+Include sources/URLs for everything. If you find only 3 bullet points, you failed.
+
+OUTPUT FORMAT:
+## Key Findings
+[Numbered list with inline source citations]
+
+## Evidence Quality
+[Which findings are well-sourced vs. speculative]
+
+## Contradictions Found
+[Any conflicting information between sources]
+
+## Notable Quotes
+[Direct quotes from authoritative sources with attribution]
+
+## Sources
+[Full list with URLs]
+```
+
+#### Agent Type Selection
+
+| Angle Type | subagent_type | model | Tools |
+|-----------|---------------|-------|-------|
+| Web research | `general-purpose` | `opus` | `mcp__exa__web_search_exa`, `WebSearch`, `WebFetch` |
+| Vault search | `Explore` | `opus` | Glob, Grep, Read on vault path |
+| Code examples | `general-purpose` | `opus` | `mcp__grep__searchGitHub` |
+| X Research | `Bash` | `opus` | x-research CLI (see below) |
+
+**X Research CLI:**
+```bash
+cd ~/clawd/skills/x-research && source ~/.config/env/global.env
+bun run x-search.ts search "<query>" --quality --quick
+```
+
+### Phase 4: Gap Analysis
+
+After ALL sub-agents return (batch — do not process one-at-a-time to avoid anchoring bias):
+
+1. Review all findings together
+2. Check: Does each MECE angle have 2+ independent sources?
+3. Identify contradictions between agent findings
+4. Identify coverage gaps — topics no agent covered adequately
+5. **If significant gaps exist**: Spawn 1-2 targeted follow-up agents (Wave 2)
+
+### Phase 5: Synthesize Into Document
+
+Cross-reference all findings and produce ONE comprehensive document. Do NOT simply concatenate agent outputs — synthesize them into something greater than the sum of parts.
+
+**File location**: `/mnt/c/Users/olled/Documents/Obsidian/Notes/02 - Content/Research/[Topic Folder]/[Document Name] [Year].md`
+
+**Topic folder organization**: Group all research outputs into a topic subfolder within `02 - Content/Research/`. If a research session produces multiple files (master synthesis + companion documents from sub-agents), they ALL go in the same topic folder. Create the folder if it doesn't exist.
+
+| Research Topic | Folder |
+|---------------|--------|
+| YouTube strategy, algorithm, scripting, titles, SEO, case studies | `Research/YouTube/` |
+| TikTok hooks, growth, scripts, descriptions | `Research/TikTok/` |
+| Meta-prompting, prompt engineering, scriptwriter optimization | `Research/Meta-Prompting/` |
+| New topic that doesn't fit existing folders | `Research/[New Topic Name]/` |
+| One-off research that doesn't warrant its own folder | `Research/Other/` |
+
+**Rules:**
+- ALWAYS check existing folders first (`ls "02 - Content/Research/"`) — use an existing folder if the topic fits
+- If 3+ files exist on a topic, they deserve their own folder
+- Sub-agent companion files go in the SAME folder as the master synthesis
+- When updating `_Index.md`, group entries under `### Research/[Folder]/` headers
+
+**Document structure**:
+```markdown
+# [Topic Name] [Year]
+
+Research compiled for @olleai ([niche context]). [N] parallel research tracks synthesized.
+
+**Purpose**: [What this research will be used for]
+**Date**: [Current date]
+**Sources**: [N] web sources, [N] X posts, [N] vault references, [N] code examples
+
+---
+
+## Executive Summary
+
+[3-5 bullet points — the most important findings]
+
+---
+
+## Part N: [Angle Name]
+
+### [Sub-topic]
+
+[Dense, actionable content with specific numbers and examples]
+
+---
+
+## Niche-Specific Applications
+
+[How findings apply to Olle's AI/tech niche specifically]
+
+---
+
+## Contradictions & Open Questions
+
+[Where sources disagreed, what remains unresolved]
+
+---
+
+## Key Takeaways
+
+[Numbered list of the most actionable insights]
+
+---
+
+## Sources
+
+[All sources cited, organized by section]
+```
+
+**Quality gate — do NOT save until ALL pass:**
+- Document exceeds 2,000 words (minimum for "comprehensive")
+- Specific numbers present, not just generalities
+- Concrete examples from real creators/companies included
+- AI/tech niche addressed specifically
+- Sources attributed throughout
+- Contradictions flagged (not hidden)
+- Olle would learn something genuinely new
+
+### Phase 6: Vault Housekeeping
+
+After saving, update `_Index.md` if a new file was created in a location not yet indexed.
+
+## Tools Reference
+
+| Tool | Use For | Notes |
+|------|---------|-------|
+| `mcp__exa__web_search_exa` | Current web information | Best for recent articles, guides |
+| `WebSearch` | Quick web lookups | Good for current events, dates |
+| `mcp__grep__searchGitHub` | Real code patterns from 1M+ repos | Search for actual code, not keywords |
+| `WebFetch` | Deep-dive specific URLs | Use after finding promising links |
+| x-research CLI | X/Twitter discourse | Creator opinions, recent changes |
+| Glob/Grep on vault | Existing vault knowledge | Always check first |
+
+## Important Principles
+
+- **Currency**: Algorithms change fast. Emphasize finding current (2026) information. Stale advice is dangerous.
+- **Density over length**: 3,000 words with specific numbers > 10,000 words of generic advice.
+- **Build on vault**: Check existing knowledge first. Extend it, don't repeat it.
+- **WHY multiplier**: Sub-agents knowing WHY produces dramatically better results. Never skip context injection.
+- **MECE or bust**: Overlapping agents waste tokens and produce duplicate content. Boundaries matter.
+- **Batch synthesis**: Collect ALL findings before synthesizing. Processing one-at-a-time creates anchoring bias.
+- **Start broad**: Agents default to overly-specific queries. Explicitly instruct broad-first search strategy.