| name | meatywiki |
| description | Drive the MeatyWiki CLI end-to-end — knowledge-compilation loop (ingest → classify → extract → compile → file-back → lint) over a file-first Obsidian-compatible markdown vault. Use when running any MeatyWiki CLI task, compiling inbox sources, querying/searching the wiki (including semantic/vector search), checking lens scores, managing workflow runs, evaluating decisions, OR bootstrapping MeatyWiki into a fresh project (vault init + AGENTS.md sidecar + wiki-spec stub). Triggers: "meatywiki", "compile loop", "ingest into wiki", "vault", "knowledge compilation", "semantic search", "lens score", "fidelity", "freshness", "workflow run", "decision table", "bootstrap meatywiki", "set up meatywiki", "wire meatywiki into this project". Do NOT use for: non-MeatyWiki knowledge systems, Portal UI, SAM/CCDash (those are separate skills/projects). |
MeatyWiki Skill
1. Compile Loop Overview
MeatyWiki implements Karpathy's knowledge-compilation loop over a markdown vault. Sources enter via ingest (raw/), flow through classify → extract → compile into structured wiki/ artifacts, and are validated by lint. Files are canonical; SQLite + FTS5 (_meta/meatywiki.db) is a derived, rebuildable index. Seven engine layers (CLI → Vault → Schema → Index → LLM → Workflows → Hooks) execute as linear pipelines — no DAGs, no retry framework.
1.5 Bootstrap Mode (one-shot project setup)
When the user says "bootstrap meatywiki here" / "set up meatywiki for this project" / "wire meatywiki into this repo", or when MeatyWiki should be added to a project that has no vault yet, load bootstrap/README.md and follow it. Bootstrap is a one-shot orchestration that:
- Runs
meatywiki init for the project's vault
- Writes a
.Codex/context/meatywiki.md sidecar in the project root
- Proposes a diff-confirmed managed block in root
AGENTS.md referencing the sidecar
- Generates a
<vault>/wiki-spec.md stub capturing project intent
All steps are idempotent and diff-confirmed. Bootstrap is separate from day-to-day CLI usage documented below; once it completes, agents drive meatywiki commands normally per the rest of this file.
Entry point: bootstrap/README.md. Contract: SPEC.md §13. Do NOT inline bootstrap steps here — they are a progressive-disclosure surface.
2. Decision Tree
TASK COMMAND
─────────────────────────────────────────────────────────────────
First-time vault setup → init
Add a source (URL/PDF/note/transcript) → ingest
Process inbox (raw/ → wiki/) → compile --pending
Recompile specific domain → compile --scope <domain>
Preview compile without writing → compile --dry-run
Force full recompile of all sources → compile --full
Look up information in the wiki → query
Write query answer back to vault → query --file-back
Scope a query to a domain → query --scope <domain>
Cross-source synthesis / summary → synthesize
Fix frontmatter / schema drift → lint --fix
Generate a lint report → lint --report
Run specific lint checks → lint --checks <names>
Full-text keyword search → search
Filter search by artifact type → search --type <type>
Filter search by freshness → search --freshness <age>
Vector similarity search → search --mode semantic
Hybrid FTS5 + vector search → search --mode hybrid
Traverse artifact relationships → graph
Set relationship traversal depth → graph --depth <n>
Export graph in specific format → graph --format <fmt>
Rebuild the derived SQLite index → index --reset
Index embeddings for semantic search → index --reindex --embeddings
Count artifacts / freshness stats → stats
Report classification friction metrics → stats --friction
Review low-confidence pending artifacts → review --low-confidence
Override artifact classification → reclassify <artifact-id> --type <type>
Health check: vault + index + config → doctor
Auto-ingest on file drop → watch
Auto-compile on file drop → watch --auto-compile
Lifecycle promotion (draft→compiled…) → promote
Force promotion past rules → promote --force
Start FastAPI thin wrapper → serve
List computed lens scores → lens list
Get lens scores for an artifact → lens get <artifact-id>
List Portal workflow runs → workflow list
Show a workflow run → workflow show <run-id>
Cancel a workflow run → workflow cancel <run-id>
Retry a failed workflow run → workflow retry <run-id>
Bulk-action workflow runs → workflow bulk-action
List decision tables → decision list
Show a decision table → decision show <table-id>
Create a decision table (YAML spec) → decision create <spec.yaml>
Update a decision table → decision update <table-id> <spec.yaml>
Delete a decision table → decision rm <table-id>
Evaluate artifact against rubric → decision apply <table-id> <artifact-id>
(Register artifact with SAM → [deferred: F1])
3. Command Map
| Command | Purpose | Key flags | Reference |
|---|
init | Initialize a new vault at the target path | — | references/command-reference.md#init |
ingest | Ingest a source into raw/ and classify | — | references/command-reference.md#ingest |
compile | Process raw/ artifacts through extract → compile → write wiki/ | --pending, --scope, --dry-run, --full | references/command-reference.md#compile |
query | FTS5-backed natural-language query over the wiki | --file-back, --scope | references/command-reference.md#query |
synthesize | Cross-source synthesis into a new wiki/ artifact | — | references/command-reference.md#synthesize |
lint | Deterministic + semantic checks on vault artifacts | --fix, --report, --checks | references/command-reference.md#lint |
search | Full-text and semantic/hybrid search | --type, --freshness, --mode, --semantic | references/command-reference.md#search |
graph | Traverse and render artifact relationships | --depth, --format | references/command-reference.md#graph |
index | Manage the derived SQLite + FTS5 + embeddings index | --reset, --reindex, --embeddings | references/command-reference.md#index |
stats | Vault counts by type, lifecycle, freshness | --friction | references/command-reference.md#stats |
review | Review low-confidence or flagged artifacts pending classification | --low-confidence | references/command-reference.md#review |
reclassify | Override artifact classification and record the override | --type | references/command-reference.md#reclassify |
doctor | Health check: structure, index freshness, config, drift | — | references/command-reference.md#doctor |
watch | Auto-ingest on file drop in raw/ | --auto-compile | references/command-reference.md#watch |
promote | Lifecycle promotion with default rules | --force | references/command-reference.md#promote |
serve | Start the FastAPI thin CLI-parity wrapper | — | references/command-reference.md#serve |
lens | Query computed lens scores (fidelity, freshness, clarity) | --format, --freshness | references/command-reference.md#lens |
workflow | Observe and control Portal workflow runs | — | references/command-reference.md#workflow |
decision | Manage decision tables and evaluate artifacts against rubrics | — | references/command-reference.md#decision |
4. Top 7 Workflow Recipes
Recipe 1 — Ingest a URL and auto-classify into the wiki
meatywiki ingest https://example.com/article
meatywiki compile --pending
meatywiki stats
Recipe 2 — Ingest a PDF with manual classification override
meatywiki ingest ~/downloads/paper.pdf
meatywiki compile --pending
Recipe 3 — Full compile loop end-to-end
meatywiki ingest <source>
meatywiki compile --pending
meatywiki lint --fix
meatywiki stats
Recipe 4 — Query the wiki and write the answer back to a vault file
meatywiki query "What are the key patterns in distributed tracing?" --file-back
Recipe 5 — Rebuild the derived index after manual vault edits
meatywiki index --reset
meatywiki stats
meatywiki doctor
Recipe 6 — Semantic search workflow
meatywiki index --reindex --embeddings
meatywiki search "attention mechanisms in transformers" --mode semantic
meatywiki search "distributed tracing patterns" --mode hybrid --type concept
Recipe 7 — Decision table triage workflow
meatywiki lens list --freshness 30d --format table
meatywiki decision create triage-rubric.yaml
meatywiki decision apply <table-id> <artifact-id>
5. Guardrails
- (a) All writes go through the engine. Agents MUST invoke
meatywiki commands rather than editing wiki/, raw/, or _meta/ files directly; all writes pass through vault/writer.py which indexes in the same transaction. Direct file edits will cause vault/index drift.
- (b)
_meta/ is engine-owned. Never edit _meta/meatywiki.db, _meta/compile_state.json, or _meta/config.yaml programmatically except via CLI commands or meatywiki config operations. _meta/ is gitignored.
- (c) Semantic search requires embeddings index.
search --mode semantic and --mode hybrid require meatywiki index --reindex --embeddings to have been run and PORTAL_DATABASE_URL set. Each query calls the embedding provider once. Fall back to plain search (FTS5 only) when embeddings are not indexed.
- (d) All V1 frontmatter must include
schema_version: "1.0.0". Artifacts without this field will fail lint and will not round-trip through the index.
- (e)
lens, workflow, and decision commands require PORTAL_DATABASE_URL. Read-only workflow list|show work without the arq worker running. Mutation commands (workflow cancel|retry|bulk-action) need the arq worker running.
6. Deferred Features (do NOT invoke)
| Feature | Track | What the skill says |
|---|
SAM register + live hook | F1 | no-op stub only |
| CCDash live hook | F2 | no-op stub only |
| Dev-artifact connectors (SkillMeat/GitHub/Codex config) | F4 | knowledge-domain connectors only |
| Portal / web UI | F6 | not in engine V1 |
| Image OCR | — | images as opaque blobs + captions |
agent_visibility enforcement | — | advisory metadata only |
| Prompt-template auto-recompile | — | manual compile --full --scope only |
| DAG workflows / retry | — | linear pipelines only |
Promoted (no longer deferred): F3 (semantic/hybrid search via search --mode) and F5 (lens scoring via lens get|list) shipped in v1.2.
7. References Pointer Table
| File | Load when | Max lines |
|---|
references/command-reference.md | Need full flag/exit-code/example detail for a command | 900 |
references/workflow-patterns.md | Need expanded recipe with setup/output/troubleshooting | 800 |
references/vault-layout.md | Need to understand directory ownership or Obsidian compat | 800 |
references/artifact-taxonomy.md | Need to construct or validate a specific artifact subtype | 800 |
references/hook-policy.md | Working near SAM/CCDash stubs or F1/F2 boundary | 800 |
references/troubleshooting.md | Compile failure, vault drift, index corruption, LLM timeout | 800 |
bootstrap/README.md | Bootstrap mode entry: when to trigger, what it does, exit conditions | 200 |
bootstrap/plan.md | Bootstrap orchestration: state detection → B1–B5 with exact commands | 300 |
bootstrap/sidecar-template.md | Canonical content for .Codex/context/meatywiki.md sidecar (B3) | 200 |
bootstrap/wiki-spec-template.md | Canonical content for <vault>/wiki-spec.md intent stub (B5) | 200 |
bootstrap/troubleshooting.md | Sidecar drift, partial-state recovery, re-bootstrap across skill versions | 300 |
8. Contract Pointer
See SPEC.md for the coverage matrix, CLI version compatibility, and update protocol.
