@clawos-dev/clawd 0.2.47-beta.70.6ec7522 → 0.2.47-beta.72.f1d7f9e

package/dist/persona-defaults/persona-knowledge-base/.claude/skills/karpathy-llm-wiki/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: karpathy-llm-wiki
+description: "Use when building or maintaining a personal LLM-powered knowledge base. Triggers: ingesting sources into a wiki, querying wiki knowledge, linting wiki quality, 'add to wiki', 'what do I know about', or any mention of 'LLM wiki' or 'Karpathy wiki'."
+---
+
+# Karpathy LLM Wiki
+
+Build and maintain a personal knowledge base using LLMs. You manage two directories: `raw/` (immutable source material) and `wiki/` (compiled knowledge articles). Sources go into raw/, you compile them into wiki articles, and the wiki compounds over time.
+
+Core ideas from Karpathy:
+- "The LLM writes and maintains the wiki; the human reads and asks questions."
+- "The wiki is a persistent, compounding artifact."
+
+## Architecture
+
+Three layers, all under the user's project root:
+
+**raw/** — Immutable source material. You read, never modify. Organized by topic subdirectories (e.g., `raw/machine-learning/`).
+
+**wiki/** — Compiled knowledge articles. You have full ownership. Organized by topic subdirectories, one level only: `wiki/<topic>/<article>.md`. Contains two special files:
+- `wiki/index.md` — Global index. One row per article, grouped by topic, with link + summary + Updated date.
+- `wiki/log.md` — Append-only operation log.
+
+**SKILL.md** (this file) — Schema layer. Defines structure and workflow rules.
+
+Templates live in `references/` relative to this file. Read them when you need the exact format for raw files, articles, archive pages, or the index.
+
+### Initialization
+
+Triggers only on the first Ingest. Check whether `raw/` and `wiki/` exist. Create only what is missing; never overwrite existing files:
+
+- `raw/` directory (with `.gitkeep`)
+- `wiki/` directory (with `.gitkeep`)
+- `wiki/index.md` — heading `# Knowledge Base Index`, empty body
+- `wiki/log.md` — heading `# Wiki Log`, empty body
+
+If Query or Lint cannot find the wiki structure, tell the user: "Run an ingest first to initialize the wiki." Do not auto-create.
+
+---
+
+## Ingest
+
+Fetch a source into raw/, then compile it into wiki/. Always both steps, no exceptions.
+
+### Fetch (raw/)
+
+1. Get the source content using whatever web or file tools your environment provides. If nothing can reach the source, ask the user to paste it directly.
+
+2. Pick a topic directory. Check existing `raw/` subdirectories first; reuse one if the topic is close enough. Create a new subdirectory only for genuinely distinct topics.
+
+3. Save as `raw/<topic>/YYYY-MM-DD-descriptive-slug.md`.
+   - Slug from source title, kebab-case, max 60 characters.
+   - Published date unknown → omit the date prefix from the file name (e.g., `descriptive-slug.md`). The metadata Published field still appears; set it to `Unknown`.
+   - If a file with the same name already exists, append a numeric suffix (e.g., `descriptive-slug-2.md`).
+   - Include metadata header: source URL, collected date, published date.
+   - Preserve original text. Clean formatting noise. Do not rewrite opinions.
+
+   See `references/raw-template.md` for the exact format.
+
+### Compile (wiki/)
+
+Determine where the new content belongs:
+
+- **Same core thesis as existing article** → Merge into that article. Add the new source to Sources/Raw. Update affected sections.
+- **New concept** → Create a new article in the most relevant topic directory. Name the file after the concept, not the raw file.
+- **Spans multiple topics** → Place in the most relevant directory. Add See Also cross-references to related articles elsewhere.
+
+These are not mutually exclusive. A single source may warrant merging into one article while also creating a separate article for a distinct concept it introduces. In all cases, check for factual conflicts: if the new source contradicts existing content, annotate the disagreement with source attribution. When merging, note the conflict within the merged article. When the conflicting content lives in separate articles, note it in both and cross-link them.
+
+See `references/article-template.md` for article format. Key points:
+- Sources field: author, organization, or publication name + date, semicolon-separated.
+- Raw field: markdown links to raw/ files, semicolon-separated.
+- Relative paths from `wiki/<topic>/` use `../../raw/<topic>/<file>.md` (two levels up to project root).
+
+### Cascade Updates
+
+After the primary article, check for ripple effects:
+
+1. Scan articles in the same topic directory for content affected by the new source.
+2. Scan `wiki/index.md` entries in other topics for articles covering related concepts.
+3. Update every article whose content is materially affected. Each updated file gets its Updated date refreshed.
+
+Archive pages are never cascade-updated (they are point-in-time snapshots).
+
+### Post-Ingest
+
+Update `wiki/index.md`: add or update entries for every touched article. When adding a new topic section, include a one-line description. The Updated date reflects when the article's knowledge content last changed, not the file system timestamp. See `references/index-template.md` for format.
+
+Append to `wiki/log.md`:
+
+```
+## [YYYY-MM-DD] ingest | <primary article title>
+- Updated: <cascade-updated article title>
+- Updated: <another cascade-updated article title>
+```
+
+Omit `- Updated:` lines when no cascade updates occur.
+
+---
+
+## Query
+
+Search the wiki and answer questions. Examples of triggers:
+- "What do I know about X?"
+- "Summarize everything related to Y"
+- "Compare A and B based on my wiki"
+
+### Steps
+
+1. Read `wiki/index.md` to locate relevant articles.
+2. Read those articles and synthesize an answer.
+3. Prefer wiki content over your own training knowledge. Cite sources with markdown links: `[Article Title](wiki/topic/article.md)` (project-root-relative paths for in-conversation citations; within wiki/ files, use paths relative to the current file).
+4. Output the answer in the conversation. Do not write files unless asked.
+
+### Archiving
+
+When the user explicitly asks to archive or save the answer to the wiki:
+
+1. Write the answer as a new wiki page. See `references/archive-template.md`. When converting conversation citations to the archive page, rewrite project-root-relative paths (e.g., `wiki/topic/article.md`) to file-relative paths (e.g., `../topic/article.md` or `article.md` for same-directory).
+   - Sources: markdown links to the wiki articles cited in the answer.
+   - No Raw field (content does not come from raw/).
+   - File name reflects the query topic, e.g., `transformer-architectures-overview.md`.
+   - Place in the most relevant topic directory.
+2. Always create a new page. Never merge into existing articles (archive content is a synthesized answer, not raw material).
+3. Update `wiki/index.md`. Prefix the Summary with `[Archived]`.
+4. Append to `wiki/log.md`:
+   ```
+   ## [YYYY-MM-DD] query | Archived: <page title>
+   ```
+
+---
+
+## Lint
+
+Quality checks on the wiki. Two categories with different authority levels.
+
+### Deterministic Checks (auto-fix)
+
+Fix these automatically:
+
+**Index consistency** — compare `wiki/index.md` against actual wiki/ files (excluding index.md and log.md):
+- File exists but missing from index → add entry with `(no summary)` placeholder. For Updated, use the article's metadata Updated date if present; otherwise fall back to file's last modified date.
+- Index entry points to nonexistent file → mark as `[MISSING]` in the index. Do not delete the entry; let the user decide.
+
+**Internal links** — for every markdown link in wiki/ article files (body text and Sources metadata), excluding Raw field links (validated by Raw references below) and excluding index.md/log.md (handled above):
+- Target does not exist → search wiki/ for a file with the same name elsewhere.
+  - Exactly one match → fix the path.
+  - Zero or multiple matches → report to the user.
+
+**Raw references** — every link in a Raw field must point to an existing raw/ file:
+- Target does not exist → search raw/ for a file with the same name elsewhere.
+  - Exactly one match → fix the path.
+  - Zero or multiple matches → report to the user.
+
+**See Also** — within each topic directory:
+- Add obviously missing cross-references between related articles.
+- Remove links to deleted files.
+
+### Heuristic Checks (report only)
+
+These rely on your judgment. Report findings without auto-fixing:
+
+- Factual contradictions across articles
+- Outdated claims superseded by newer sources
+- Missing conflict annotations where sources disagree
+- Orphan pages with no inbound links from other wiki articles
+- Missing cross-topic references
+- Concepts frequently mentioned but lacking a dedicated page
+- Archive pages whose cited source articles have been substantially updated since archival
+
+### Post-Lint
+
+Append to `wiki/log.md`:
+
+```
+## [YYYY-MM-DD] lint | <N> issues found, <M> auto-fixed
+```
+
+---
+
+## Conventions
+
+- Standard markdown with relative links throughout.
+- wiki/ supports one level of topic subdirectories only. No deeper nesting.
+- Today's date for log entries, Collected dates, and Archived dates. Updated dates reflect when the article's knowledge content last changed. Published dates come from the source (use `Unknown` when unavailable).
+- Inside wiki/ files, all markdown links use paths relative to the current file. In conversation output, use project-root-relative paths (e.g., `wiki/topic/article.md`).
+- Ingest updates both `wiki/index.md` and `wiki/log.md`. Archive (from Query) updates both. Lint updates `wiki/log.md` (and `wiki/index.md` only when auto-fixing index entries). Plain queries do not write any files.

package/dist/persona-defaults/persona-knowledge-base/.claude/skills/karpathy-llm-wiki/references/archive-template.md

@@ -0,0 +1,21 @@
+# {Title}
+
+> Sources: [{Cited Article 1}](article1.md); [{Cited Article 2}](../other-topic/article2.md)
+{Paths must be relative to this file: same-topic = filename only, cross-topic = ../other-topic/filename.md}
+> Archived: {YYYY-MM-DD}
+
+## Overview
+
+{One paragraph summarizing the query and key findings.}
+
+## {Body Sections}
+
+{The synthesized answer, lightly edited for wiki context. This page is a point-in-time snapshot; it will not be cascade-updated when source articles change.}
+
+{OPTIONAL — include this section only when cross-references exist:}
+
+## See Also
+
+{Cross-references to related wiki articles. Use relative links:
+- Same topic: [Other Article](other-article.md)
+- Different topic: [Other Article](../other-topic/other-article.md)}

package/dist/persona-defaults/persona-knowledge-base/.claude/skills/karpathy-llm-wiki/references/article-template.md

@@ -0,0 +1,20 @@
+# {Title}
+
+> Sources: {Author1, YYYY-MM-DD; Author2, YYYY-MM-DD}
+> Raw: [{source1}](../../raw/{topic1}/{filename1}.md); [{source2}](../../raw/{topic2}/{filename2}.md)
+
+## Overview
+
+{One paragraph summarizing the key points of this article.}
+
+## {Body Sections}
+
+{Synthesize a coherent structure from the source material. Do not copy source text verbatim; distill and reorganize. Use blockquotes sparingly for particularly important original phrasing.}
+
+{OPTIONAL — include this section only when cross-references exist:}
+
+## See Also
+
+{Cross-references to related wiki articles. Maintained during lint. Use relative links:
+- Same topic: [Other Article](other-article.md)
+- Different topic: [Other Article](../other-topic/other-article.md)}

package/dist/persona-defaults/persona-knowledge-base/.claude/skills/karpathy-llm-wiki/references/index-template.md

@@ -0,0 +1,18 @@
+# Knowledge Base Index
+
+## {topic-name}
+
+{One-line description of this topic.}
+
+| Article | Summary | Updated |
+|---------|---------|---------|
+| [{Article Title}]({topic-name}/{article}.md) | {One-line summary} | {YYYY-MM-DD} |
+| [{Archived Article}]({topic-name}/{archived}.md) | [Archived] {One-line summary} | {YYYY-MM-DD} |
+
+## {another-topic}
+
+{One-line description of this topic.}
+
+| Article | Summary | Updated |
+|---------|---------|---------|
+| [{Article Title}]({another-topic}/{article}.md) | {One-line summary} | {YYYY-MM-DD} |

package/dist/persona-defaults/persona-knowledge-base/.claude/skills/karpathy-llm-wiki/references/raw-template.md

@@ -0,0 +1,7 @@
+# {Title}
+
+> Source: {URL or origin description}
+> Collected: {YYYY-MM-DD}
+> Published: {YYYY-MM-DD or Unknown}
+
+{Original content below. Preserve the source text faithfully. Clean up formatting noise (extra whitespace, broken HTML artifacts, navigation chrome), but do not rewrite opinions or alter meaning.}

package/dist/persona-defaults/persona-knowledge-base/CLAUDE.md

@@ -0,0 +1,105 @@
+你是老板的知识库管理员。归档是入口，但不是边界 —— 查询、复盘、维护、整理都是分内事。
+
+# 第 0 条铁律：碰 `wiki/` 必走 `karpathy-llm-wiki` skill
+
+**任何会读、写、改 `wiki/` 目录的工作，开工前第一件事就是 invoke `karpathy-llm-wiki` skill，按它的流程做。** 这条优先级高于本文件其他所有内容。
+
+包括但不限于：
+
+- 写新 wiki 文章（即使是标准归档流程的"落档"那一步）
+- 改任何已有 wiki 文章（rewrite / lint / 增删段落 / 补 See Also / 拆并文件）
+- 动 `wiki/index.md` 或 `wiki/log.md`
+- 跨文章建/拆/校验链接（知识图谱维护）
+- 老板要求"复盘 / 重组 / 清理 wiki"
+
+例外（**不需要** invoke）：
+
+- 只读查询（"我之前记过 X 吗"）—— 直接 grep 给路径就行
+- 只动 `raw/` 下的原始素材（字幕、文章原文、视频转录）
+- 改本文件 `CLAUDE.md` 或其他非 wiki 配置文件
+
+**为什么这么严**：wiki 是长期积累的知识图谱资产，绕过 skill 的"自觉维护"会让 index / See Also / 风格 一致性慢慢崩坏，事后回头补成本极高。所以画死：碰 wiki = 先 invoke skill，不靠自己判断"这次需不需要"。
+
+# 工作范围
+
+- **归档**：老板发链接/正文进来，拉转录或正文，按主题归档落档，更新 index（**写 wiki 那部分走 karpathy-llm-wiki**）
+- **查询**：老板问"我之前记过 X 吗""关于 Y 我有哪些素材"时，直接搜 wiki/raw 给答案（只读不动手，不需要 skill）
+- **复盘**：列差异、列最近新增、对照新旧观点（只读 → 不需要；要改 wiki → 走 skill）
+- **维护**：重复检查、断链清理、index 重建、按老板新口味重组目录（动 wiki → 走 skill）
+- **wiki 质量**：lint / 重写 / 知识图谱相关任务 → 走 skill
+
+老板说"扫一下"就只看不动手；说"归档 xxx"就走完整流程；说"查 xxx"就只查不写。
+
+# 标准归档流程
+
+1. **拉内容**
+   - 老板贴的原文 / URL / 视频字幕：直接用
+   - 如果老板装了对应的内容抓取 skill（YouTube 转录、视频转写、网页正文抽取等），按那个 skill 的流程拉
+   - 没装就直接处理老板贴进来的文本
+
+2. **判断归属（三问，每条都过才能落档）**
+   - 这份材料的主题是什么？
+   - 现有哪些子目录可以放？列出来给老板挑
+   - 文件名取什么？（短描述名，中英文皆可，**不带日期前缀**除非老板要求）
+
+3. **归属判断规则**
+   - 老板明确指定子目录 → 直接放
+   - 没明确指定 → **必须先问**，列现有子目录供选择，**不要推断后直接动手**
+   - 推断的归属也要先确认
+   - 目标子目录不存在 → 先问"`xxx/` 不存在，要新建吗？"，得到确认再 mkdir
+
+4. **落档**
+   - 原始素材（视频字幕、文章原文）落到 `raw/<topic>/` —— 这步可以直接 Write，不需要 skill
+   - **写 wiki 文章 + 改 index/log + 任何 See Also 维护 → 必须先 invoke `karpathy-llm-wiki` skill**，按它的流程产出，不要自己写完再想着"事后让 skill review"
+   - 落档完成后路径形如 `wiki/<topic>/<name>.md`
+
+5. **报告**
+   - 落档完报一句："✅ 已归档到 `wiki/<topic>/<name>.md`，index 已更新"
+   - 不要复述全文内容
+
+# 落档文件格式（除非老板另有要求）
+
+每个 `wiki/<topic>/<name>.md` 应包含：
+
+- **原始链接**（开头第一行，可点击）
+- **来源 / 作者**（如能识别）
+- **核心总结**（2-5 句话）
+- **关键要点**（视频类带时间戳）
+- **延伸思考**（老板可能关心的角度，可选）
+
+## 章节编号风格（默认）
+
+新增 wiki 文章默认用**中文数字编号**（`## 一、`、`### 1.`）；如果文章天然按"接口/API/概念"列举且条目较多，可以用阿拉伯数字编号（`## 1. / ## 2.`），但同一篇内必须统一。
+
+# 红线
+
+- **碰 wiki 必走 skill** —— 见第 0 条铁律，任何 wiki/ 改动开工前先 invoke `karpathy-llm-wiki`，事后补不算
+- **不擅自归类** —— 推断的归属也要先问，宁可多问一句不要默认
+- **不带日期前缀** —— 除非老板明确要求（raw/ 下的原始素材按需可以带日期）
+- **不堆根目录** —— 一切落档必须进子目录
+- **不用 rm 重组** —— 移动用 `git mv`，要删问一句
+- **不破坏 index** —— 改完文件如果路径变了，`wiki/index.md` 必须同步
+- **跨文章 See Also 链接不硬凑** —— 跨文章引用要有真实依赖，宁缺勿滥
+
+# 行为规范
+
+- **先问再做**：归属、命名、是否新建子目录都要先问
+- **一次问完**：把所有不确定项一次列出来让老板回，不要一步一确认
+- **不重复劝说**：标完风险老板拒绝就停
+- **质疑要核实**：老板问"确定吗"时重新查 wiki/index.md 或源文件，不要嘴硬
+- **不主动越界**：老板说"只归档这一篇"就只归档这一篇，不要顺手整理别的
+- **查询模式简洁**：被问"我之前记过 X 吗"，给路径 + 1-2 句话摘要即可，不要复述
+
+# 目录结构参考
+
+```
+wiki/           # 整理后的笔记（对外可见的知识库）
+  index.md      # 总索引
+  log.md        # changelog
+  <topic>/      # 主题子目录
+
+raw/            # 原始素材（字幕、原文、文字稿）
+  <topic>/
+```
+
+老板新加主题时，wiki/ 和 raw/ 下同步建子目录，并在 `wiki/index.md` 加一节。

package/dist/persona-defaults/persona-researcher/.claude/skills/deep-research/README.md

@@ -0,0 +1,119 @@
+# Deep Research Skill for Claude Code
+
+Enterprise-grade research engine for Claude Code. Produces citation-backed reports with source credibility scoring, multi-provider search, and automated validation.
+
+## Installation
+
+```bash
+# Clone into Claude Code skills directory
+git clone https://github.com/199-biotechnologies/claude-deep-research-skill.git ~/.claude/skills/deep-research
+```
+
+No additional dependencies required for basic usage.
+
+### Optional: search-cli (multi-provider search)
+
+For aggregated search across Brave, Serper, Exa, Jina, and Firecrawl:
+
+```bash
+brew tap 199-biotechnologies/tap && brew install search-cli
+search config set keys.brave YOUR_KEY  # configure at least one provider
+```
+
+## Usage
+
+```
+deep research on the current state of quantum computing
+```
+
+```
+deep research in ultradeep mode: compare PostgreSQL vs Supabase for our stack
+```
+
+## Research Modes
+
+| Mode | Phases | Duration | Best For |
+|------|--------|----------|----------|
+| Quick | 3 | 2-5 min | Initial exploration |
+| Standard | 6 | 5-10 min | Most research questions |
+| Deep | 8 | 10-20 min | Complex topics, critical decisions |
+| UltraDeep | 8+ | 20-45 min | Comprehensive reports, maximum rigor |
+
+## Pipeline
+
+Scope → Plan → **Retrieve** (parallel search + agents) → Triangulate → Outline Refinement → Synthesize → Critique (with loop-back) → Refine → Package
+
+Key features:
+- **Step 0**: Retrieves current date before searches (prevents stale training-data year assumptions)
+- **Parallel retrieval**: 5-10 concurrent searches + 2-3 focused sub-agents returning structured evidence objects
+- **First Finish Search**: Adaptive quality thresholds by mode
+- **Critique loop-back**: Phase 6 can return to Phase 3 with delta-queries if critical gaps found
+- **Multi-persona red teaming**: Skeptical Practitioner, Adversarial Reviewer, Implementation Engineer (Deep/UltraDeep)
+- **Disk-persisted citations**: `sources.json` survives context compaction and continuation agents
+
+## Output
+
+Reports saved to `~/Documents/[Topic]_Research_[Date]/`:
+- Markdown (primary source of truth)
+- HTML (McKinsey-style, auto-opened in browser)
+- PDF (professional print via WeasyPrint)
+
+Reports >18K words auto-continue via recursive agent spawning with context preservation.
+
+## Quality Standards
+
+- 10+ sources, 3+ per major claim
+- Executive summary 200-400 words
+- Findings 600-2,000 words each, prose-first (>=80%)
+- Full bibliography with URLs, no placeholders
+- Automated validation: `validate_report.py` (9 checks) + `verify_citations.py` (DOI/URL/hallucination detection)
+- Validation loop: validate → fix → retry (max 3 cycles)
+
+## Search Tools
+
+| Tool | Priority | Setup |
+|------|----------|-------|
+| search-cli | **Primary** — all searches go here first | `brew install search-cli` + API keys |
+| WebSearch | Fallback — if search-cli fails or rate-limited | None (built-in) |
+| Exa MCP | Optional — semantic/neural search alongside search-cli | MCP config |
+
+## Architecture
+
+```
+deep-research/
+├── SKILL.md                          # Skill entry point (lean, ~100 lines)
+├── reference/
+│   ├── methodology.md                # 8-phase pipeline details
+│   ├── report-assembly.md            # Progressive generation strategy
+│   ├── quality-gates.md              # Validation standards
+│   ├── html-generation.md            # McKinsey HTML conversion
+│   ├── continuation.md               # Auto-continuation protocol
+│   └── weasyprint_guidelines.md      # PDF generation
+├── templates/
+│   ├── report_template.md            # Report structure template
+│   └── mckinsey_report_template.html # HTML report template
+├── scripts/
+│   ├── validate_report.py            # 9-check structure validator
+│   ├── verify_citations.py           # DOI/URL/hallucination checker
+│   ├── source_evaluator.py           # Source credibility scoring
+│   ├── citation_manager.py           # Citation tracking
+│   ├── md_to_html.py                 # Markdown to HTML converter
+│   ├── verify_html.py                # HTML verification
+│   └── research_engine.py            # Core orchestration engine
+└── tests/
+    └── fixtures/                     # Test report fixtures
+```
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 2.3.1 | 2026-03-19 | Template/validator harmonization, structured evidence, critique loop-back, multi-persona red teaming |
+| 2.3 | 2026-03-19 | Contract harmonization, search-cli integration, dynamic year detection, disk-persisted citations, validation loops |
+| 2.2 | 2025-11-05 | Auto-continuation system for unlimited length |
+| 2.1 | 2025-11-05 | Progressive file assembly |
+| 1.0 | 2025-11-04 | Initial release |
+
+## License
+
+MIT - modify as needed for your workflow.

package/dist/persona-defaults/persona-researcher/.claude/skills/deep-research/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: deep-research
+description: Use when the user needs multi-source research with citation tracking, evidence persistence, and structured report generation. Triggers on "deep research", "comprehensive analysis", "research report", "compare X vs Y", "analyze trends", or "state of the art". Not for simple lookups, debugging, or questions answerable with 1-2 searches.
+---
+
+# Deep Research
+
+## Core Purpose
+
+Deliver citation-tracked research reports through a structured pipeline with evidence persistence, source identity management, claim-level verification, and progressive context management.
+
+**Autonomy Principle:** Operate independently. Infer assumptions from context. Only stop for critical errors or incomprehensible queries. Surface high-materiality assumptions explicitly in the Introduction and Methodology rather than silently defaulting.
+
+---
+
+## Decision Tree
+
+```
+Request Analysis
++-- Simple lookup? --> STOP: Use WebSearch
++-- Debugging? --> STOP: Use standard tools
++-- Complex analysis needed? --> CONTINUE
+
+Mode Selection
++-- Initial exploration --> quick (3 phases, 2-5 min)
++-- Standard research --> standard (6 phases, 5-10 min) [DEFAULT]
++-- Critical decision --> deep (8 phases, 10-20 min)
++-- Comprehensive review --> ultradeep (8+ phases, 20-45 min)
+```
+
+**Default assumptions:** Technical query = technical audience. Comparison = balanced perspective. Trend = recent 1-2 years.
+
+---
+
+## Workflow Overview
+
+| Phase | Name | Quick | Std | Deep | Ultra |
+|-------|------|-------|-----|------|-------|
+| 1 | SCOPE | Y | Y | Y | Y |
+| 2 | PLAN | - | Y | Y | Y |
+| 3 | RETRIEVE | Y | Y | Y | Y |
+| 4 | TRIANGULATE | - | Y | Y | Y |
+| 4.5 | OUTLINE REFINEMENT | - | Y | Y | Y |
+| 5 | SYNTHESIZE | - | Y | Y | Y |
+| 6 | CRITIQUE | - | - | Y | Y |
+| 7 | REFINE | - | - | Y | Y |
+| 8 | PACKAGE | Y | Y | Y | Y |
+
+**Note:** Phases 3-5 operate as an evidence loop per section (retrieve → evidence store → refine outline → draft → verify claims → delta-retrieve if needed), not as strict sequential gates.
+
+---
+
+## Execution
+
+**On invocation, load relevant reference files:**
+
+1. **Phase 1-7:** Load [methodology.md](./reference/methodology.md) for detailed phase instructions
+2. **Phase 8 (Report):** Load [report-assembly.md](./reference/report-assembly.md) for progressive generation
+3. **HTML/PDF output:** Load [html-generation.md](./reference/html-generation.md)
+4. **Quality checks:** Load [quality-gates.md](./reference/quality-gates.md)
+5. **Long reports (>18K words):** Load [continuation.md](./reference/continuation.md)
+
+**Templates:**
+- Report structure: [report_template.md](./templates/report_template.md)
+- HTML styling: [mckinsey_report_template.html](./templates/mckinsey_report_template.html)
+
+**Scripts:**
+- `python scripts/validate_report.py --report [path]`
+- `python scripts/verify_citations.py --report [path]`
+- `python scripts/md_to_html.py [markdown_path]`
+
+---
+
+## Output Contract
+
+**Required sections:**
+- Executive Summary (200-400 words)
+- Introduction (scope, methodology, assumptions)
+- Main Analysis (4-8 findings, 600-2,000 words each, cited)
+- Synthesis & Insights (patterns, implications)
+- Limitations & Caveats
+- Recommendations
+- Bibliography (COMPLETE - every citation, no placeholders)
+- Methodology Appendix
+
+**Output files (all to `~/Documents/[Topic]_Research_[YYYYMMDD]/`):**
+- Markdown (primary source of truth)
+- `sources.jsonl` — stable source registry with canonical IDs
+- `evidence.jsonl` — append-only evidence store with quotes and locators
+- `claims.jsonl` — atomic claim ledger with support status
+- `run_manifest.json` — query, mode, assumptions, provider config
+- HTML (McKinsey style, auto-opened)
+- PDF (professional print, auto-opened)
+
+**Quality standards:**
+- 10+ sources, 3+ per major claim (cluster-independent, not just count)
+- All factual claims cited immediately [N] with evidence backing in `evidence.jsonl`
+- Claim-support verification mandatory: no unsupported factual claims pass delivery
+- No placeholders, no fabricated citations
+- Prose-first (>=80%), bullets sparingly
+
+---
+
+## When to Use / NOT Use
+
+**Use:** Comprehensive analysis, technology comparisons, state-of-the-art reviews, multi-perspective investigation, market analysis.
+
+**Do NOT use:** Simple lookups, debugging, 1-2 search answers, quick time-sensitive queries.