Skip to content

First ingest

This walkthrough takes a YouTube URL from raw source to approved entity facts.

1. Ingest the source

auto-lorebook ingest https://youtube.com/watch?v=abc123

The tool fetches the transcript via yt-dlp, stores it under sources/yt-abc123/, and prints what it captured:

✓ Manual subtitles available (English)
Source stored as yt-abc123.
  Title: Aether Chronicles S3E14
  Duration: 2:20:32
  Captions: manual (English)

If only auto-generated captions are available, the tool warns that proper-noun mishearings are likely and suggests adding name corrections during reading review.

2. Fill in context

The tool prompts interactively. Every field is skippable; defaults come from flags, then .wiki-context.yaml, then your last ingest.

Session date (YYYY-MM-DD): 2026-01-15
Perspective (e.g. "Cor playing Kiki"): Cor playing Kiki in Aether Chronicles
Source nature [actual-play/dm-lore/worldbuilding-video/interview/notes/other]: actual-play
Setting [Aether Chronicles]:
Any notes? (one line, or Enter to skip): Picks up mid-session after a long rest.

Context saved to sources/yt-abc123/info.yaml.

Generate reading now? [Y/n]: y

Context fields are optional — blank is allowed. Unfilled fields reduce LLM quality but don't block the pipeline. See context pipeline for schema details.

3. Review the reading

After Stage 1a (structure) and Stage 1b (summarize) run, you get a draft: sidecar at pending/yt-abc123/reading/reading.yaml and one segments/seg-NNN.md per segment. Open the interactive review:

auto-lorebook approve-reading yt-abc123

The session prints the draft and prompts:

  • a — approve (flips status, copies to wiki).
  • e — preview assembled draft in $EDITOR (read-only; edits are discarded). Edit segment files directly for now.
  • r — queue the draft for deletion.
  • u — restore the draft to its session-start contents and clear any queued reject.
  • q — quit; commits a queued reject (after a y/N confirm) or exits cleanly.

Pass --yes to skip the loop and auto-approve (required for scripted/CI runs). See reading stage for deeper treatment.

4. Plan and extract

After approving the reading, run Stage 2 (planner) and Stage 3 (extractor) explicitly:

auto-lorebook plan yt-abc123
auto-lorebook extract yt-abc123

plan routes claim bullets to entities and writes pending/yt-abc123/plan.yaml; it refuses if the wiki-side reading.md is missing. extract locates verbatim transcript spans for each planned claim and writes proposal YAMLs under pending/yt-abc123/proposals/; it refuses if plan.yaml is missing.

5. Review facts

To walk through proposed facts:

auto-lorebook review ingest-2026-04-20-a

Each proposal shows the claim text, the raw transcript span it came from, corrections applied, source locator, and routing rationale. Decide per proposal: approve, edit, reject, or play (opens the source at the right timestamp to verify). There is no skip — every proposal gets a decision.

First approval of a claim targeting a new entity creates the entity stub atomically. If review reveals systematic routing errors, bail out with auto-lorebook replan <ingest_id> instead of fighting proposal by proposal. See fact review.

6. View the wiki

Approved facts land in <category>/<slug>.yaml; the summarizer regenerates <category>/<slug>.md with citation-backed prose. Browse either directly, or via the web UI once implemented:

auto-lorebook wiki show Aldara
auto-lorebook wiki list --category locations

See summarizer stage for how YAML facts become readable prose.