Skip to content

File formats

Index of every YAML and markdown artifact the tool reads or writes. Each entry names where it lives, which stage owns it, and links to the spec for full field details.

Every YAML file carries schema_version as its first key — see schema versioning.

Wiki repo

.wiki-context.yaml

  • Location — wiki root.
  • Owner — hand-maintained by the user.
  • Purpose — setting name, description, naming conventions, interpretation defaults, recurring speakers.
  • Details — context pipeline.

.transcription-corrections.yaml

  • Location — wiki root.
  • Owner — tool-maintained via promote-correction; hand-editable.
  • Purpose — global phonetic / mishearing fixes applied to all sources.
  • Details — entity model.

sources/<source_id>/transcript.en.srt

  • Owner — tool-fetched or user-supplied; never rewritten.
  • Purpose — raw transcript evidence for every downstream fact.

sources/<source_id>/info.yaml

  • Owner — tool, with interactive context step filling in user-supplied fields.
  • Purpose — URL, title, duration, caption type, session date, per-source context.
  • Details — context pipeline.

sources/<source_id>/reading.md

  • Owner — tool (written to wiki when the reading-review engine commits with every segment decided).
  • Purpose — segmented, attributed, bulleted reading of the transcript. Frontmatter carries name_corrections, default_speaker, session_date, source_*. File presence is the approval gate.
  • Details — Stage 1: reading.

<category>/<slug>.yaml

  • Location — one of characters/, locations/, factions/, events/, items/, concepts/.
  • Owner — tool (created atomically on first approved fact); hand-editable as the designated post-approval edit surface.
  • Purpose — canonical name, aliases, and facts for a single entity. The source of truth for entity state.
  • Details — entity model.

<category>/<slug>.md

  • Owner — tool, regenerated by the summarizer.
  • Purpose — readable prose view of an entity, with citations back to sources.
  • Details — Stage 4: summarizer.

index.md

  • Owner — tool.
  • Purpose — auto-generated table of contents.

Tool state directory

~/.auto-lorebook/config.yaml

  • Owner — user.
  • Purpose — model selection, wiki repo path, API key env var name.
  • Details — installation.

~/.auto-lorebook/pending/<ingest_id>/reading/structure.yaml

  • Stage — Stage 1a output.
  • Purpose — segments, speaker attribution, sub-segment overrides, uncertainty flags. Intermediate artifact; retained as audit through ingest lifetime.
  • Details — Stage 1a.

~/.auto-lorebook/pending/<ingest_id>/reading/reading.yaml

  • Stage — Stage 1b output; sidecar.
  • Purpose — session metadata: default_speaker, name_corrections, session_date. Preserved across regenerations.
  • Details — Stage 1b.

~/.auto-lorebook/pending/<ingest_id>/reading/segments/<segment_id>.md

  • Stage — Stage 1b output; per-segment.
  • Purpose — YAML frontmatter (segment metadata, segment_status) plus pre-rendered bullet body. Assembled into the wiki-side reading.md at approval time.
  • Details — reading assembly.

~/.auto-lorebook/pending/<ingest_id>/plan.yaml

  • Stage — Stage 2 output.
  • Purpose — entity resolutions, new-entity proposals, routed claims. No filesystem side effects.
  • Details — Stage 2: planner.

~/.auto-lorebook/pending/<ingest_id>/proposals/<proposal_id>.yaml

  • Stage — Stage 3 output.
  • Purpose — one proposed fact per file, with verbatim span, corrections applied, locator, and routing metadata.
  • Details — Stage 3: extractor.

Staleness hashes

Every tool-generated YAML or markdown carries an inputs block with SHA-256 hashes of the inputs that produced it. See staleness.

Hand-edit surfaces

Only these files are intended as hand-edit surfaces:

  • pending/<id>/reading/reading.yaml — before approval. Edit name_corrections and session_date.
  • pending/<id>/reading/segments/seg-NNN.md — before approval. Edit bullet body text and timestamps. (Per-segment interactive editing lands in a future slice; currently the assembled preview is read-only.)
  • <category>/<slug>.yaml — after approval. Edit facts, aliases, sections, superseded_by.

Hand-edits to intermediate artifacts (structure.yaml, plan.yaml, proposal YAMLs) are not detected as staleness signals; they are not supported edit surfaces.