The Episodic documentation set, sorted by what it is for

• Users' guide describes supported user-facing behaviour and externally visible workflows.
• Roadmap tracks phased delivery work, dependencies, and acceptance criteria.
• Episodic podcast generation system design primary product and architecture design for the podcast generation system.
• Developers' guide gives maintainer-facing build, test, lint, extension, and contribution guidance.

Documentation lives in the Episodic repository and is linked rather than copied, so nothing here can fall behind the source. Where a document is itself a plan or a decision record, the category says so - a design that was accepted is not a description of running code.

If you want the supported user-facing path first, start with the users' guide and then branch out to the task-specific pages.

For this published companion's route map, read the df12 site users' guide.

Orientation

Guide For: Everyone 5 documents

Start here. What the project is, how it is laid out, and where delivery stands.

• Repository layout explains the repository tree, ownership boundaries, and path conventions.
• Documentation style guide defines the writing, formatting, and document-type conventions for project documentation.
• Users' guide describes supported user-facing behaviour and externally visible workflows.
• Developers' guide gives maintainer-facing build, test, lint, extension, and contribution guidance.
• Roadmap tracks phased delivery work, dependencies, and acceptance criteria.

Product and system design

Design For: Technical evaluator 5 documents

The platform model, its interface contracts, and its operational shape.

• Episodic podcast generation system design primary product and architecture design for the podcast generation system.
• Episodic TUI API design design notes for the terminal user interface and API interaction model.
• Infrastructure design Kubernetes, GitOps, observability, and operational infrastructure design.
• Reference binding resolution reference binding model and resolution behaviour.
• LangGraph and Celery in hexagonal architecture integration guidance for orchestration and worker boundaries.

User and integration guides

Guide For: Developer 7 documents

Working guidance for the dependencies and testing surfaces the platform integrates.

• Femtologging users' guide integration guidance for the femtologging dependency.
• TEI Rapporteur users' guide integration guidance for Text Encoding Initiative (TEI) payload handling.
• Async SQLAlchemy with PostgreSQL and Falcon reference for asynchronous persistence and HTTP service integration.
• Testing async Falcon endpoints practical guidance for endpoint tests.
• Testing SQLAlchemy with pytest and py-pglite persistence testing guidance.
• Local validation of GitHub Actions with act and pytest local continuous integration validation workflow.
• Scripting standards conventions for helper scripts and command execution.

Architecture and engineering references

Reference For: Maintainer 6 documents

Background material behind recurring engineering decisions.

• Agentic systems with LangGraph and Celery background reference for agentic workflow orchestration.
• Cost management in LangGraph agentic systems cost-control patterns for agentic workflows.
• Complexity antipatterns and refactoring strategies maintainability guidance for refactoring decisions.
• Reliable testing in Rust via dependency injection reference material for Rust dependency-injection testing.
• Rust doctest dry guide Rust documentation-test maintenance guidance.
• Rust testing with rstest fixtures Rust fixture-based testing guidance.

Decision records

Decision record For: Maintainer 16 documents

Accepted decisions, each with the context that forced it.

All 16 documents

• ADR 001: Pedante evaluator contract evaluator contract decision retained at the historical top-level ADR path.
• ADR 001: Reference binding resolution algorithm accepted reference binding resolution algorithm.
• ADR 002: HTTP service composition root HTTP service composition boundary.
• ADR 003: Celery worker scaffold worker process scaffold decision.
• ADR 004: Show notes TEI representation show notes representation in TEI.
• ADR 005: Structured planning and tool execution structured planning and tool execution model.
• ADR 006: Chrono spoken text semantics spoken-text runtime estimation semantics.
• ADR 007: Durable generation checkpoints durable checkpointing model for generation workflows.
• ADR 008: Chapter marker TEI representation chapter marker representation in TEI.
• ADR 009: Source-to-script REST vertical slice REST vertical slice scope for source-to-script work.
• ADR 010: Guest bios TEI representation guest biography representation in TEI.
• ADR 011: TTS capability negotiation text-to-speech capability negotiation model.
• ADR 012: Pronunciation repository pronunciation repository decision.
• ADR 013: Speech synthesis adapters speech synthesis adapter boundaries.
• ADR 014: Hexagonal architecture enforcement import-boundary enforcement model.
• ADR 015: Upload and idempotency ports source-intake upload storage and idempotency port decisions.

Execution plans

Execution plan For: Maintainer 36 documents

Implementation plans for individual roadmap tasks. Historical once the task lands.

All 36 documents

• Reference binding resolution implementation plan for roadmap task 1.4.3.
• Scaffold Falcon HTTP services on Granian implementation plan for roadmap task 1.5.1.
• Scaffold Celery workers with RabbitMQ integration implementation plan for roadmap task 1.5.2.
• Architectural enforcement for hexagonal boundaries implementation plan for roadmap task 1.5.4.
• Pedante factuality and accuracy evaluator evaluator implementation plan.
• Relational schema design storage schema implementation plan.
• Migration tooling with Alembic migration tooling plan.
• Repository and unit of work layers persistence boundary implementation plan.
• Multi-source ingestion service ingestion service implementation plan.
• Capture provenance metadata provenance implementation plan.
• Chrono runtime estimator runtime estimation implementation plan.
• Define reusable reference document model reference document model plan.
• Reusable reference document repository docs reference repository documentation plan.
• Series profile and episode template models profile and template model plan.
• REST endpoints for reference documents reference document API plan.
• Generate show notes from template expansions show notes generation plan.
• Generate chapter markers aligned to script segments chapter marker generation plan.
• Generate guest bios from reference document bindings guest biography generation plan.
• Structured output planning and tool-calling execution planning and tool execution implementation plan.
• Add LangGraph suspend and resume orchestration orchestration checkpoint plan.
• Configure Celery queue routing worker routing plan.
• LLM port adapter large language model adapter plan.
• Introduce v1 target API prefix REST API versioning plan.
• Finalize REST surfaces REST surface hardening plan.
• Adopt Hecate architecture enforcement adoption plan.
• Femtologging April 2026 migration femtologging migration plan.
• LangGraph design enhancements orchestration design enhancement plan.
• Roadmap normalization roadmap structure normalization plan.
• Update to TEI Rapporteur with type hints dependency update plan.
• Upgrade Python to 3.14: compression zstd Python 3.14 compression adoption plan.
• Upgrade Python to 3.14: concurrent interpreters Python 3.14 concurrent interpreter adoption plan.
• Upgrade Python to 3.14: custom task factory support Python 3.14 task-factory adoption plan.
• Upgrade Python to 3.14: lazy annotations Python 3.14 lazy annotation adoption plan.
• Upgrade Python to 3.14: template strings in prompts Python 3.14 template string adoption plan.
• Upgrade Python to 3.14: type guards in OpenAI client Python 3.14 type guard adoption plan.
• Upgrade Python to 3.14: UUID7 for storage IDs Python 3.14 UUID7 adoption plan.

• Guides describe supported behaviour. The users' guide is the closest thing to a statement of what works. It is explicit about being under construction.
• Designs describe intent. The system design is thorough and largely unimplemented. Read it for the model, not the feature list.
• Decision records and execution plans are historical. An accepted ADR records what was decided and why. An execution plan describes how one roadmap task was approached and stops being current the moment it lands.

Run the code · Read the API reference · Check delivery state