vault-ingest

Vault ingestion assistant. Takes messy old campaign materials and translates them into structured inputs that existing skills can process. Adapter + Orchestrator pattern.

Shared references: Read on first invocation:

• shared/session-principles.md
• shared/session-document-chain.md
• shared/reconcile.md

Skill references: Read before each phase:

• references/classification-taxonomy.md — Phase 1
• references/image-handling.md — Phase 1 (when images present)
• references/keeper-interview.md — Phase 4
• references/synthesis-templates.md — Phase 5

Downstream skills:

• campaign-organizer — vault skeleton, entity filing
• session-wrapup — wrap-up generation from synthesized notes
• reconcile (shared) — GM review, canon confirmation
• campaign-qa — optional post-ingestion health check

Orchestrates via conversational handoffs, not programmatic calls.

Input Channels

All three can be used in the same invocation:

1. Staging folder — Files in _inbox/ within the vault. After ingestion, source files move to _inbox/_processed/ with a date stamp (not deleted).
2. External path — GM points to a folder or file outside the vault. Read-only — never modify external sources.
3. Pasted content — GM pastes text directly. Treat as an implicit source document.

Supported formats: Markdown, plain text, Word, PDF, images, spreadsheets (CSV/Excel), chat/VTT exports.

Bootstrap Detection

On invocation, check whether a vault exists (look for _meta/). If no vault detected:

"I don't see a campaign vault here. Want me to hand off to campaign-organizer to set one up first, or point me to your vault's location?"

Do not proceed without a vault — ingested entities need folder structure, templates, and _meta/ schema to file correctly. Without these, entities get created with wrong paths and missing metadata.

Version check: After confirming the vault exists, read gm_apprentice_version from _meta/vault-config.md and current_version from shared/migrations.md — frontmatter only, Read with limit: 10; the rest of the file is a long migration history you don't need for the check. If the vault version is lower or absent, announce the mismatch and hand off to campaign-organizer's migration workflow (campaign-organizer/references/migration-procedure.md) before proceeding with ingestion. Resume after migration completes. Skip this check if _meta/ doesn't exist (that's first-time setup, not migration).

Gotchas

1. Read _Templates/_Template_{Type}.md before creating any entity — Template is canonical structure. Pattern-matching off existing entities propagates drift and deprecated fields.
2. ONE file per entity — Multiple entities in one file break wiki-link resolution and publish rendering.
3. Never modify external source files — Read-only access. The GM's originals are their backup and legal proof of ownership.
4. Process buckets chronologically, earliest first — Later buckets reference entities created by earlier ones. Out-of-order processing creates dangling wiki-links and duplicate entities.
5. Move processed _inbox/ files to _inbox/_processed/ with date stamp, never delete — Source provenance. The GM may need to re-ingest if errors are found, and the original file is the audit trail.
6. Validate each bucket's entities before the next bucket — run the bundled vault_check.py frontmatter (see shared/vault-access.md) on folders you wrote; fix every ERROR first. Later buckets build on earlier files, so schema drift compounds.

The Pipeline

Six phases, sequential. Phases 1-4 owned by vault-ingest. Phases 5-6 hand off to existing skills. When multiple buckets exist, process each through Phases 3-6 before the next (chronological order, earliest first).

Phase 1: Survey & Classify

Read all source material. Classify every document or section. Read references/classification-taxonomy.md for the full taxonomy and heuristics.

Key heuristic: If a document contains dice rolls, skill check results, or specific PC actions, those lines are play records regardless of what surrounds them.

Image handling: Read references/image-handling.md for full procedures. Summary: classify every image file, convert non-web-safe formats (best-effort via sips or magick), match to entities by slugified filename, file in the correct _attachments/ subfolder, and link to matched entities. Unmatched images go on the Phase 4 keeper interview list.

Output: Classified manifest — summary table of every source item with classification, brief content summary, and time-period guess. Present to GM: "Does this look right? Any misclassifications?"

Phase 2: Sort into Buckets

Group classified items by chapter/session/time period.

Sorting signals:

• Explicit references ("Session 5 notes", "Chapter 2 prep")
• Timeline references (in-game dates, event references)
• NPC/location clustering (same cast = same period)
• GM context from Phase 1 confirmation

Each bucket gets: working label, classified items, certainty level (certain / probable / needs-GM-input).

Ambiguous items go to "unsorted" bucket — resolved at the start of Phase 4 before play-event interview begins.

Processing order: Chronological, earliest first. Earlier buckets build vault context for later ones.

Phase 3: Extract Play Events

Read all AUTHORITATIVE-classified material per bucket. Build confirmed play events.

Source priority:

1. Timeline.md — existing record, read first
2. Existing session wrap-ups
3. Play transcripts and fragments from source material
4. Player_Characters.md — deaths, transitions, rosters
5. Existing entity files — current canon state

Output: Two lists per bucket:

• Confirmed events (with source citations)
• Gaps (things prep says could have happened but unconfirmed)

Image linking: For each entity created or updated in this bucket, check filed images (from Phase 1) for matches. Single match → set portrait. Multiple matches with clear default (unsuffixed filename) → set portrait, embed rest via ![[filename]]. Multiple matches with no default → defer portrait selection to Phase 4. See references/image-handling.md.

Phase 4: Keeper Interview

The skill's exclusive value. Read references/keeper-interview.md for the full technique.

Rules:

1. One question at a time — never bulk lists
2. Contextual framing — trigger memory with scene context
3. Follow the thread — each answer is a door
4. Record as you go — log every answer immediately
5. Know when to stop — "I don't remember" → flag and move on
6. Distinguish certainty — "definitely" vs "I think so"

First resolve any unsorted items from Phase 2 before starting the play-event interview.

Image questions: After resolving unsorted items and before starting the play-event interview, resolve image assignments:

1. Show each unmatched image — ask the GM which entity it belongs to (or "atmosphere art" → _attachments/documents/)
2. For entities with multiple images and no clear default — ask the GM to pick the portrait See references/image-handling.md for question templates.

PC arc questions: After image resolution and before starting the play-event interview, ask one question per active PC about their personal arc across the ingested period. See references/keeper-interview.md § PC Narrative Arcs.

Phase 5: Synthesize & Hand Off

Read references/synthesis-templates.md for the output format.

1. For buckets with no existing session files, hand to campaign-organizer for chapter/session skeleton creation
2. Write synthesized content as a Play Notes file per shared/session-document-chain.md. Apply the block/seam test: preserve finished-prose blocks from the sources verbatim; author only the fragment-derived text and the seams. Synthesis assembles fragments — it does not re-voice writing that is already written. (rationale: shared/content-fidelity.md)
3. Follow session-wrapup workflow to produce the Wrap-Up file and create/update entities
4. For each PC active during the ingested period, write a consolidated character story entry per references/synthesis-templates.md § Character Story Backstory Entries

Self-check after each entity:

1. Re-read the entity file just written
2. Compare frontmatter fields against _Templates/_Template_{Type}.md
3. Verify: type matches, canon_status is set, all required fields present
4. Verify: wiki-links use [[Entity Name]] format (no bare text references to entities)
5. Verify: play_date is YYYY-MM-DD; in_game_date uses a real-date form (ISO, month-name, or seasonal with a 4-digit year) or the campaign's own non-Earth calendar — never a fabricated Gregorian date, and no narrative time-of-day in the field (see shared/session-document-chain.md)
6. Fix any issues before proceeding to the next entity

Include > [!info] Reconstruction Note with source descriptions and limitations. Mark uncertain items with <!-- UNVERIFIED -->.

Planning content: If the ingested material contains narrative planning documents (scene designs, arc structures, investigation flows), create them as type: plan entities in Chapters/{chapter}/Planning/. Read _Templates/_Template_Plan.md for the frontmatter structure. Set plan_type to the closest match: arc, scene, investigation, or timeline.

Phase 6: Review

Invoke shared/reconcile.md to walk the GM through reviewing the wrap-up. On approval, promotes to reviewed status and AUTHORITATIVE canon status.

Post-Ingestion

After all buckets are processed:

Cross-reference pass:

• Deduplicate entities across buckets
• Identify relationship chains spanning buckets
• Check timeline consistency
• Validate entity status progression
• Inconsistencies → back through reconcile

Optional handoff: Suggest campaign-qa for graph health check. Don't force.

"I've ingested N sessions of material. Want to run a vault health check?"

Design Principles

1. Prep is not play. Most dangerous error. Scenario prep describes potential, not reality.
2. One question at a time. Bulk questions → shallow answers.
3. Follow the thread. Don't move on too quickly.
4. Synthesize, don't invent. Only source material + GM.
5. Every image gets filed. Non-negotiable baseline.
6. Flag, don't guess. Ambiguous → flagged, not resolved.
7. Entity creation cascades. One NPC → three locations.

Model Selection

Match model capability to task complexity. These are guidelines, not requirements — use whatever models are available and appropriate for your setup.

Phase	Complexity	Why
1-2	Light	Classification, grouping — pattern matching
3-6	Heavy	Judgment, synthesis, GM interaction
Entity subagents	Light	Structured file creation from templates
Image filing	Light	Format conversion, filename matching

Sub-agent Opportunity

Phase 5 entity work parallelizes well. Phase 4 interview must be sequential.

Compaction

After all phases, preserve: confirmed events + sources, GM answers (verbatim), manifest, unresolved items, entity paths. Discard: intermediate reasoning, processed source material, failed extractions, superseded interview chains.