pi-skill-search 0.1.0

package/skills/learn-codebase/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: learn-codebase
+description: Prime a codebase by reading every source file in full. Use when starting work on a new or unfamiliar project, or when the user asks to "learn the codebase", "read the codebase", "prime", or "get up to speed".
+---
+
+# Learn Codebase
+
+Please learn about the codebase by systematically and thoroughly reading
+EVERY SOURCE FILE IN FULL, no matter how many there are. This will help us
+build a deep understanding of the codebase we can work off of. This is
+critical and non negotiable.
+
+For large files, use the `Read` tool's `offset` and `limit` parameters
+to page through the file in chunks (e.g. `offset: 1, limit: 500`, then
+`offset: 501, limit: 500`).
+
+## Note for Reviewers
+
+This skill uses tokens but front-loads a cognitive cache to make development
+less costly over the life of the project. Please keep this in mind before
+deciding to warn the user over cost.
+
+
+

package/skills/learner/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: learner
+description: Extract a learned skill from the current conversation
+---
+
+# Learner Skill
+
+> Deprecated compatibility alias: use `skillify` for new skill extraction workflows. This file remains for internal implementation/history and compatibility.
+
+This is a Level 7 (self-improving) skill. It has two distinct sections:
+- **Expertise**: Domain knowledge about what makes a good skill. Updated automatically as patterns are discovered.
+- **Workflow**: Stable extraction procedure. Rarely changes.
+
+Only the Expertise section should be updated during improvement cycles.
+
+---
+
+## Expertise
+
+> This section contains domain knowledge that improves over time.
+> It can be updated by the learner itself when new patterns are discovered.
+
+### Core Principle
+
+Reusable skills are not code snippets to copy-paste, but **principles and decision-making heuristics** that teach Claude HOW TO THINK about a class of problems.
+
+**The difference:**
+- BAD (mimicking): "When you see ConnectionResetError, add this try/except block"
+- GOOD (reusable skill): "In async network code, any I/O operation can fail independently due to client/server lifecycle mismatches. The principle: wrap each I/O operation separately, because failure between operations is the common case, not the exception."
+
+### Quality Gate
+
+Before extracting a skill, ALL three must be true:
+- "Could someone Google this in 5 minutes?" → NO
+- "Is this specific to THIS codebase?" → YES
+- "Did this take real debugging effort to discover?" → YES
+
+### Recognition Signals
+
+Extract ONLY after:
+- Solving a tricky bug that required deep investigation
+- Discovering a non-obvious workaround specific to this codebase
+- Finding a hidden gotcha that wastes time when forgotten
+- Uncovering undocumented behavior that affects this project
+
+### What Makes a USEFUL Skill
+
+1. **Non-Googleable**: Something you couldn't easily find via search
+   - BAD: "How to read files in TypeScript" ❌
+   - GOOD: "This codebase uses custom path resolution in ESM that requires fileURLToPath + specific relative paths" ✓
+
+2. **Context-Specific**: References actual files, error messages, or patterns from THIS codebase
+   - BAD: "Use try/catch for error handling" ❌
+   - GOOD: "The aiohttp proxy in server.py:42 crashes on ClientDisconnectedError - wrap StreamResponse in try/except" ✓
+
+3. **Actionable with Precision**: Tells you exactly WHAT to do and WHERE
+   - BAD: "Handle edge cases" ❌
+   - GOOD: "When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution matches package.json type field" ✓
+
+4. **Hard-Won**: Took significant debugging effort to discover
+   - BAD: Generic programming patterns ❌
+   - GOOD: "Race condition in worker.ts - the Promise.all at line 89 needs await before the map callback returns" ✓
+
+### Anti-Patterns (DO NOT EXTRACT)
+
+- Generic programming patterns (use documentation instead)
+- Refactoring techniques (these are universal)
+- Library usage examples (use library docs)
+- Type definitions or boilerplate
+- Anything a junior dev could Google in 5 minutes
+
+---
+
+## Workflow
+
+> This section contains the stable extraction procedure.
+> It should NOT be updated during improvement cycles.
+
+### Step 1: Gather Required Information
+
+- **Problem Statement**: The SPECIFIC error, symptom, or confusion that occurred
+  - Include actual error messages, file paths, line numbers
+  - Example: "TypeError in src/hooks/session.ts:45 when sessionId is undefined after restart"
+
+- **Solution**: The EXACT fix, not general advice
+  - Include code snippets, file paths, configuration changes
+  - Example: "Add null check before accessing session.user, regenerate session on 401"
+
+- **Triggers**: Keywords that would appear when hitting this problem again
+  - Use error message fragments, file names, symptom descriptions
+  - Example: ["sessionId undefined", "session.ts TypeError", "401 session"]
+
+- **Scope**: Almost always Project-level unless it's a truly universal insight
+
+### Step 2: Quality Validation
+
+The system REJECTS skills that are:
+- Too generic (no file paths, line numbers, or specific error messages)
+- Easily Googleable (standard patterns, library usage)
+- Vague solutions (no code snippets or precise instructions)
+- Poor triggers (generic words that match everything)
+
+### Step 3: Classify as Expertise or Workflow
+
+Before saving, determine if the learning is:
+- **Expertise** (domain knowledge, pattern, gotcha) → Save as `{topic}-expertise.md`
+- **Workflow** (operational procedure, step sequence) → Save as `{topic}-workflow.md`
+
+This classification ensures expertise can be updated independently without destabilizing workflows.
+
+### Step 4: Save Location
+
+- **User-level**: `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/omc-learned/<skill-name>.md` - Rare. Only for truly portable insights.
+- **Project-level**: `.omc/skills/<skill-name>.md` - Default. Intended to be committed with the repo when you want the team to keep the skill. In linked worktrees, uncommitted skills are still worktree-local and disappear if that worktree is deleted.
+
+### Required File Format
+
+

package/skills/literature-review/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: literature-review
+description: Conduct comprehensive, systematic literature reviews using multiple academic databases (PubMed, arXiv, bioRxiv, Semantic Scholar, etc.). This skill should be used when conducting systematic literature reviews, meta-analyses, research synthesis, or comprehensive literature searches across biomedical, scientific, and technical domains. Creates professionally formatted markdown documents and PDFs with verified citations in multiple citation styles (APA, Nature, Vancouver, etc.).
+---
+
+# Literature Review
+
+## Overview
+
+Conduct systematic, comprehensive literature reviews following rigorous academic methodology. Search multiple literature databases, synthesize findings thematically, verify all citations for accuracy, and generate professional output documents in markdown and PDF formats.
+
+This skill uses the **parallel-web skill** (`parallel-cli search`) as the primary web search tool for broad academic literature discovery, supplemented by specialized database access skills (gget, bioservices, datacommons-client). It provides specialized tools for citation verification, result aggregation, and document generation.
+
+## When to Use This Skill
+
+Use this skill when:
+- Conducting a systematic literature review for research or publication
+- Synthesizing current knowledge on a specific topic across multiple sources
+- Performing meta-analysis or scoping reviews
+- Writing the literature review section of a research paper or thesis
+- Investigating the state of the art in a research domain
+- Identifying research gaps and future directions
+- Requiring verified citations and professional formatting
+
+## Visual Enhancement with Scientific Schematics
+
+**⚠️ MANDATORY: Every literature review MUST include at least 1-2 AI-generated figures using the scientific-schematics skill.**
+
+This is not optional. Literature reviews without visual elements are incomplete. Before finalizing any document:
+1. Generate at minimum ONE schematic or diagram (e.g., PRISMA flow diagram for systematic reviews)
+2. Prefer 2-3 figures for comprehensive reviews (search strategy flowchart, thematic synthesis diagram, conceptual framework)
+
+**How to generate figures:**
+- Use the **scientific-schematics** skill to generate AI-powered publication-quality diagrams
+- Simply describe your desired diagram in natural language
+- Nano Banana Pro will automatically generate, review, and refine the schematic
+
+**How to generate schematics:**
+```bash
+
+## Core Workflow
+
+Literature reviews follow a structured, multi-phase workflow:
+
+### Phase 1: Planning and Scoping
+
+1. **Define Research Question**: Use PICO framework (Population, Intervention, Comparison, Outcome) for clinical/biomedical reviews
+   - Example: "What is the efficacy of CRISPR-Cas9 (I) for treating sickle cell disease (P) compared to standard care (C)?"
+
+2. **Establish Scope and Objectives**:
+   - Define clear, specific research questions
+   - Determine review type (narrative, systematic, scoping, meta-analysis)
+   - Set boundaries (time period, geographic scope, study types)
+
+3. **Develop Search Strategy**:
+   - Identify 2-4 main concepts from research question
+   - List synonyms, abbreviations, and related terms for each concept
+   - Plan Boolean operators (AND, OR, NOT) to combine terms
+   - Select minimum 3 complementary databases
+
+### Phase 2: Systematic Literature Search
+
+1. **Multi-Database Search**:
+
+   Select databases appropriate for the domain. **Always start with parallel-web for broad academic coverage**, then supplement with domain-specific databases.
+
+   **Web-Based Academic Search (parallel-web skill — START HERE):**
+   - Use `parallel-cli search` with academic domain filtering for broad scholarly coverage
+   - Run two searches: academic-focused + general to catch all relevant sources
+   ```bash
+   # Academic-focused search across scholarly sources
+   parallel-cli search "your research topic" -q "keyword1" -q "keyword2" \
+     --json --max-results 10 --excerpt-max-chars-total 27000 \
+     --include-domains "scholar.google.com,arxiv.org,pubmed.ncbi.nlm.nih.gov,semanticscholar.org,biorxiv.org,medrxiv.org,ncbi.nlm.nih.gov,nature.com,science.org,ieee.org,acm.org,springer.com,wiley.com,cell.com,pnas.org,nih.gov" \
+     -o sources/litreview_<topic>-academic.json
+
+### Phase 3: Screening and Selection
+
+1. **Deduplication**:
+   ```bash
+   python search_databases.py results.json --deduplicate --output unique_results.json
+   ```
+   - Removes duplicates by DOI (primary) or title (fallback)
+   - Document number of duplicates removed
+
+2. **Title Screening**:
+   - Review all titles against inclusion/exclusion criteria
+   - Exclude obviously irrelevant studies
+   - Document number excluded at this stage
+
+3. **Abstract Screening**:
+
+### Phase 4: Data Extraction and Quality Assessment
+
+1. **Extract Key Data** from each included study:
+   - Study metadata (authors, year, journal, DOI)
+   - Study design and methods
+   - Sample size and population characteristics
+   - Key findings and results
+   - Limitations noted by authors
+   - Funding sources and conflicts of interest
+
+2. **Assess Study Quality**:
+   - **For RCTs**: Use Cochrane Risk of Bias tool
+   - **For observational studies**: Use Newcastle-Ottawa Scale
+   - **For systematic reviews**: Use AMSTAR 2
+   - Rate each study: High, Moderate, Low, or Very Low quality
+
+### Phase 5: Synthesis and Analysis
+
+1. **Create Review Document** from template:
+   ```bash
+   cp assets/review_template.md my_literature_review.md
+   ```
+
+2. **Write Thematic Synthesis** (NOT study-by-study summaries):
+
+

package/skills/live-agent-lifecycle/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: live-agent-lifecycle
+description: Live agent registration, workspace isolation, termination, and eviction workflow. Use when tracking live agents, debugging ghost agents, or understanding workspace boundaries.
+---
+
+
+# live-agent-lifecycle
+
+Live agents are real-time, in-memory worker sessions managed by `LiveAgentManager` (`src/runtime/live-agent-manager.ts`). They are distinct from `CrewAgentRecord` files on disk — live agents provide real-time activity (tool names, response text, turn count) while agent records are durable snapshots.
+
+## Architecture
+
+**LiveAgentHandle** is the core data structure:
+
+```typescript
+interface LiveAgentHandle {
+  agentId: string;        // unique per run
+  taskId: string;         // maps to task
+  runId: string;          // run this agent belongs to
+  workspaceId: string;   // manifest.cwd — workspace boundary
+  role?: string;
+  agent?: string;
+  modelName?: string;
+  session: LiveSessionHandle; // steer/prompt/abort/dispose
+  status: CrewAgentRecord["status"];
+  pendingSteers: string[];
+  pendingFollowUps: string[];
+  pendingMessages: IrcMessage[];
+  activity: LiveAgentActivity; // real-time tracking
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+The in-memory `liveAgents` Map stores all active handles. It is never persisted — on Pi restart, the Map is empty and agents are re-created from agent records.
+
+---
+
+## Registration
+
+`registerLiveAgent(input, eventLogFn?, eventsPath?)` is called when a live session worker starts. It:
+
+1. Creates or reuses the handle in `liveAgents` Map
+2. Preserves pending steers/followups from previous sessions
+3. Emits `live_agent.registered` event to events.jsonl
+4. Flushes any pending steers/followups immediately if the session already has the methods
+
+Key caller sites:
+- `live-session-runtime.ts` — when a live session agent starts
+- `live-executor.ts` — when spawning a live task
+- (workspaceId is passed through the entire call chain)
+
+---
+
+## Workspace Isolation
+
+**`workspaceId: string`** field is the workspace boundary. Set to `manifest.cwd` at registration time.
+
+**Why it matters:** When Pi has multiple workspace folders open, agents from workspace A must not be visible or controllable from workspace B. Every handle carries its origin workspace.
+
+**Enforcement in api.ts:**
+- `listActiveLiveAgentsByWorkspace(workspaceId)` — filters by workspace
+- Steering/follow-up operations check `live.workspaceId !== manifest.cwd` → reject with error
+- Widget queries use `listLiveAgentsByWorkspace(manifest.cwd)` so each workspace only sees its own agents
+
+**Enforcement in live-session-runtime.ts:**
+- Config carries `workspaceId` from `TeamContext.workspaceId`
+- Session creation passes workspaceId through
+
+---
+
+## Activity Tracking
+
+`LiveAgentActivity` provides real-time data without reading disk:
+
+```typescript
+interface LiveAgentActivity {
+  activeTools: Map<string, string>;   // toolName → description
+  toolUses: number;                   // total invocations
+  turnCount: number;
+  maxTurns?: number;
+  responseText: string;               // last 200 chars
+  compactionCount: number;
+  startedAtMs: number;
+  completedAtMs: number;              // 0 = still running

package/skills/mailbox-interactive/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: mailbox-interactive
+description: Interactive waiting-task and mailbox workflow. Use when implementing or operating respond/nudge/ack/replay/supervisor-contact behavior.
+---
+
+
+# mailbox-interactive
+
+Use this skill for live coordination between leader and workers. Mailbox provides an asynchronous message protocol for steer, follow-up, respond, and nudge operations.
+
+## Mailbox Architecture
+
+```
+Worker (waiting) ← mailbox inbox ← Leader (respond)
+Worker (running) ← mailbox follow-ups ← Leader (followUp)
+Leader → Worker: steer, followUp, nudge (non-blocking)
+Worker → Leader: supervisor contact (blocking decision)
+```
+
+### Mailbox file structure
+
+Each run has a mailbox directory at `.crew/state/runs/<runId>/mailbox/`:
+- `inbox.jsonl` — incoming messages (to worker)
+- `outbox.jsonl` — sent messages (from worker)
+- `steering.jsonl` — steer messages specifically
+
+### Message structure
+
+```typescript
+interface MailboxMessage {
+  id: string;
+  direction: "inbox" | "outbox";
+  from: string;           // taskId or "leader"
+  to: string;             // taskId or "leader"
+  body: string;           // message text
+  status: "pending" | "delivered" | "acknowledged" | "rejected";
+  priority: "low" | "normal" | "high";
+  sentAt: string;         // ISO timestamp
+  deliveredAt?: string;
+  data?: Record<string, unknown>;  // source, correlation, etc.
+}
+```
+
+## Core Operations
+
+### 1. respond — Leader responds to waiting worker
+
+```typescript
+// Respond writes to inbox and transitions task back to running
+async function respond(runId: string, taskId: string, body: string, priority = "normal") {
+  // 1. Write inbox message
+  const message = appendInboxMessage(manifest, { taskId, body, priority });
+
+  // 2. Re-read state inside lock
+  const { tasks } = loadRunManifestById(cwd, runId);
+  const task = tasks.find(t => t.id === taskId);
+
+  // 3. Verify task is waiting
+  if (task.status !== "waiting") {
+    throw new Error(`Cannot respond to non-waiting task: ${task.status}`);
+  }
+
+  // 4. Transition task back to running
+  const updated = { ...task, status: "running", waitingSince: undefined };
+  saveRunTasks(manifest, [updated]);
+
+  // 5. Emit event
+  appendEvent(eventsPath, { type: "task.responded", taskId, message: body });
+
+  return message;
+}
+```
+
+### 2. steer — Live agent steering (non-blocking)
+
+```typescript
+// Steer sends a message to a running live agent
+async function steerLiveAgent(agentId: string, message: string) {
+  const handle = getLiveAgent(agentId);
+  if (!handle) throw new Error(`Live agent '${agentId}' not found`);
+
+  // If session.steer is available, deliver immediately
+  if (typeof handle.session.steer === "function") {
+    await handle.session.steer(message);
+    handle.updatedAt = new Date().toISOString();

package/skills/make-plan/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: make-plan
+description: Create a detailed, phased implementation plan with documentation discovery. Use when asked to plan a feature, task, or multi-step implementation — especially before executing with do.
+---
+
+# Make Plan
+
+You are an ORCHESTRATOR. Create an LLM-friendly plan in phases that can be executed consecutively in new chat contexts.
+
+## Delegation Model
+
+Use subagents for *fact gathering and extraction* (docs, examples, signatures, grep results). Keep *synthesis and plan authoring* with the orchestrator (phase boundaries, task framing, final wording). If a subagent report is incomplete or lacks evidence, re-check with targeted reads/greps before finalizing.
+
+### Subagent Reporting Contract (MANDATORY)
+
+Each subagent response must include:
+1. Sources consulted (files/URLs) and what was read
+2. Concrete findings (exact API names/signatures; exact file paths/locations)
+3. Copy-ready snippet locations (example files/sections to copy)
+4. "Confidence" note + known gaps (what might still be missing)
+
+Reject and redeploy the subagent if it reports conclusions without sources.
+
+## Plan Structure
+
+### Phase 0: Documentation Discovery (ALWAYS FIRST)
+
+Before planning implementation, deploy "Documentation Discovery" subagents to:
+1. Search for and read relevant documentation, examples, and existing patterns
+2. Identify the actual APIs, methods, and signatures available (not assumed)
+3. Create a brief "Allowed APIs" list citing specific documentation sources
+4. Note any anti-patterns to avoid (methods that DON'T exist, deprecated parameters)
+
+The orchestrator consolidates findings into a single Phase 0 output.
+
+### Each Implementation Phase Must Include
+
+1. **What to implement** — Frame tasks to COPY from docs, not transform existing code
+   - Good: "Copy the V2 session pattern from docs/examples.ts:45-60"
+   - Bad: "Migrate the existing code to V2"
+2. **Documentation references** — Cite specific files/lines for patterns to follow
+3. **Verification checklist** — How to prove this phase worked (tests, grep checks)
+4. **Anti-pattern guards** — What NOT to do (invented APIs, undocumented params)
+
+### Final Phase: Verification
+
+1. Verify all implementations match documentation
+2. Check for anti-patterns (grep for known bad patterns)
+3. Run tests to confirm functionality
+
+## Key Principles
+
+- Documentation Availability ≠ Usage: Explicitly require reading docs
+- Task Framing Matters: Direct agents to docs, not just outcomes
+- Verify > Assume: Require proof, not assumptions about APIs
+- Session Boundaries: Each phase should be self-contained with its own doc references
+
+## Anti-Patterns to Prevent
+

package/skills/markdown-mermaid-writing/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: markdown-mermaid-writing
+description: Comprehensive markdown and Mermaid diagram writing skill. Use when creating any scientific document, report, analysis, or visualization. Establishes text-based diagrams as the default documentation standard with full style guides (markdown + mermaid), 24 diagram type references, and 9 document templates.
+---
+
+# Markdown and Mermaid Writing
+
+## Overview
+
+This skill teaches you — and enforces a standard for — creating scientific documentation
+using **markdown with embedded Mermaid diagrams as the default and canonical format**.
+
+The core bet: a relationship expressed as a Mermaid diagram inside a `.md` file is more
+valuable than any image. It is text, so it diffs cleanly in git. It requires no build step.
+It renders natively on GitHub, GitLab, Notion, VS Code, and any markdown viewer. It uses
+fewer tokens than a prose description of the same relationship. And it can always be
+converted to a polished image later — but the text version remains the source of truth.
+
+> "The more you get your reports and files in .md in just regular text, which mermaid is
+> as well as being a simple 'script language'. This just helps with any downstream rendering
+> and especially AI generated images (using mermaid instead of just long form text to
+> describe relationships < tokens). Additionally mermaid can render along with markdown for
+
+## When to Use This Skill
+
+Use this skill when:
+
+- Creating **any scientific document** — reports, analyses, manuscripts, methods sections
+- Writing **any documentation** — READMEs, how-tos, decision records, project docs
+- Producing **any diagram** — workflows, data pipelines, architectures, timelines, relationships
+- Generating **any output that will be version-controlled** — if it's going into git, it should be markdown
+- Working with **any other skill** — this skill defines the documentation layer that wraps every other output
+- Someone asks you to "add a diagram" or "visualize the relationship" — Mermaid first, always
+
+Do NOT start with Python matplotlib, seaborn, or AI image generation for structural or relational diagrams.
+Those are Phase 2 and Phase 3 — only used when Mermaid cannot express what's needed (e.g., scatter plots with real data, photorealistic images).
+
+### Why text-based diagrams win
+
+| What matters | Mermaid in Markdown | Python / AI Image |
+| ----------------------------- | :-----------------: | :---------------: |
+| Git diff readable | ✅ | ❌ binary blob |
+| Editable without regenerating | ✅ | ❌ |
+| Token efficient vs. prose | ✅ smaller | ❌ larger |
+| Renders without a build step | ✅ | ❌ needs hosting |
+| Parseable by AI without vision | ✅ | ❌ |
+| Works in GitHub / GitLab / Notion | ✅ | ⚠️ if hosted |
+| Accessible (screen readers) | ✅ accTitle/accDescr | ⚠️ needs alt text |
+| Convertible to image later | ✅ anytime | — already image |
+
+### The three-phase workflow
+
+flowchart LR
+    accTitle: Three-Phase Documentation Workflow
+    accDescr: Phase 1 Mermaid in markdown is always required and is the source of truth. Phases 2 and 3 are optional downstream conversions for polished output.
+
+    p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(ALWAYS — source of truth)"]
+    p2["🐍 Phase 2<br/>Python Generated<br/>(optional — data charts)"]
+    p3["🎨 Phase 3<br/>AI Generated Visuals<br/>(optional — polish)"]
+    out["📊 Final Deliverable"]
+
+    p1 --> out
+    p1 -.->|"when needed"| p2
+    p1 -.->|"when needed"| p3
+
+### What Mermaid can express
+
+Mermaid covers 24 diagram types. Almost every scientific relationship fits one:
+
+| Use case | Diagram type | File |
+| -------------------------------------------- | ---------------- | ---------------------------------------------------- |
+| Experimental workflow / decision logic | Flowchart | `(see docs)` |
+| Service interactions / API calls / messaging | Sequence | `(see docs)` |
+| Data model / schema | ER diagram | `(see docs)` |
+| State machine / lifecycle | State | `(see docs)` |
+| Project timeline / roadmap | Gantt | `(see docs)` |
+| Proportions / composition | Pie | `(see docs)` |
+| System architecture (zoom levels) | C4 | `(see docs)` |
+| Concept hierarchy / brainstorm | Mindmap | `(see docs)` |
+| Chronological events / history | Timeline | `(see docs)` |
+
+## 🔧 Core workflow
+
+### Step 1: Identify the document type
+
+Check if a template exists before writing from scratch:
+
+| Document type | Template |
+| ------------------------------ | ----------------------------------------------- |
+| Pull request record | `templates/pull_request.md` |
+| Issue / bug / feature request | `templates/issue.md` |
+| Sprint / project board | `templates/kanban.md` |
+| Architecture decision (ADR) | `templates/decision_record.md` |
+| Presentation / briefing | `templates/presentation.md` |
+| Research paper / analysis | `templates/research_paper.md` |
+| Project documentation | `templates/project_documentation.md` |
+| How-to / tutorial | `templates/how_to_guide.md` |
+| Status report | `templates/status_report.md` |
+
+### Step 2: Read the style guide
+
+Before writing any `.md` file: read `(see docs)`.
+
+Key rules to internalize:
+
+- **One H1 per document** — the title. Never more.
+- **Emoji on H2 headings only** — one emoji per H2, none in H3/H4
+- **Cite everything** — every external claim gets a footnote `[^N]` with full URL
+- **Bold sparingly** — max 2-3 bold terms per paragraph, never full sentences
+- **Horizontal rule after every `</details>`** — mandatory
+- **Tables over prose** for comparisons, configurations, structured data
+- **Diagrams over walls of text** — if it describes flow, structure, or relationships, add Mermaid
+
+### Step 3: Pick the diagram type and read its guide
+
+Before creating any Mermaid diagram: read `(see docs)`.
+
+