| name | notebook-ingest |
| description | Compile a raw source in the notebook vault (raw/papers, raw/repos, raw/clippings) into wiki/sources + wiki/entities + wiki/concepts, update indexes, append INGEST line to _log.md, and record hash in raw/.manifest.json. Use when running /notebook-ingest or after /notebook-capture has dropped new raw cards. |
notebook-ingest
Compile a raw source in the personal notebook vault into interlinked wiki pages. Scoped to notebook/ — writes only inside the vault.
Scope Gate (mandatory)
Before doing anything, confirm the cwd is a notebook vault. The marker is raw/.manifest.json — it is notebook-unique. Don't substitute wiki/_hot.md; it is a weaker signal and can exist in other vaults.
[ -f raw/.manifest.json ] || { echo "Not a notebook vault — cd into the vault root first"; exit 1; }
Boundaries
| Writes to | Never touches |
|---|
raw/.manifest.json (hash/manifest updates only, never card content) | raw/* source cards (immutable) |
wiki/sources/, wiki/entities/, wiki/concepts/, wiki/_index.md, wiki/_hot.md, wiki/_log.md | wiki/journal/ (owned by /notebook-capture) |
Entity Discipline
Entity pages in wiki/entities/ represent people, orgs, and projects worth tracking across sources. For multi-author surveys (e.g., 35-author position papers), create entities only for the lead + senior PIs — cap at roughly 5 per source. Summaries use + N others on the authors line. Full author lists belong in the raw card metadata, not the entity layer. Inflating entities with every co-author turns the graph into noise.
Concept Discipline
Concepts in wiki/concepts/ capture named primitives, patterns, or anti-patterns. Prefer one umbrella concept per source over one concept per construct: Bandara's nine best practices become a single production-agentic-workflows concept, not nine. Spawn a new concept only when the construct is structurally distinct from what the graph already holds.
When a new source reinforces an existing concept, update the concept's "Sources I've Read" section in place rather than creating a redundant concept. This grows the cross-link graph without concept inflation.
Vocabulary import. When a source names a primitive precisely ("conceptual retrofitting", "model consortium", "instruction fade-out"), adopt the term verbatim. Named primitives compound across the wiki; unnamed ones stay trapped in the source summary.
For sibling-concepts-across-surfaces and sub-primitive promotion thresholds, see reference.md — Concept Discipline (Extended).
Hot Cache as Synthesis Staging
wiki/_hot.md Notes section is a live synthesis substrate, not just a recent-activity log. As each source is ingested, append thread gaps, resolutions, and new vocabulary. Thread coherence typically emerges at 4-5 sources — by that point the Notes section has become the synthesis outline for the eventual synthesis page. Use source count + gap articulation as the ripeness signal, not calendar time.
Raw Card Hygiene
- Abstract-only by default. Arxiv abstract + metadata + "why this card exists" is usually enough for a
wiki/sources/ summary. Pull full PDFs only on user request for deeper distillation.
- Link-rot-proof clippings. Substack and similar rot-prone sources get a
## Content section in the raw card with the full body extracted via defuddle parse <url> --md. Strip tracking params (?r=, utm_*) before archiving.
- Verify suspicious URLs. When an arxiv ID looks forward-dated or structurally unusual, WebFetch or curl the metadata before writing the card. Title/author values invented from URL patterns produce silent misinformation that propagates into the entity graph and source summaries before anyone reads the actual paper.
Workflow
See reference.md for the full 8-step ingest workflow, batch/force modes, context discipline, and the Session-1 preservation contract.
