Use this page to select the shortest path through the Jidoka documentation. You do not have to read the guides in sidebar order.
Start Here
| Goal | Read first | Read next |
|---|---|---|
| Build your first agent | Getting Started | Agent DSL |
| Understand the data and execution model | Core Concepts | Public Facade |
| Use the stable application API | Public Facade | Sessions And Stores |
| Prepare a production deployment | Configuration | Idempotency And Safety |
| Diagnose a failure | Troubleshooting | Inspection And Preflight |
| Contribute to Jidoka | Contributor Testing | Runic Spine Internals |
Application Developer Path
Use this path when you build an application with Jidoka:
- Getting Started - install Jidoka and run one agent.
- Agent DSL - define the model, instructions, tools, and controls.
- Tools And Operations - expose work to the model.
- Testing And Evals - use deterministic capabilities in tests.
Add these guides when the product needs the related feature:
- Controls and Human In The Loop for policy and human review.
- Structured Results for validated application output.
- Sessions And Stores for durable multi-turn state.
- Memory for prompt recall and durable writes.
- Streaming and Agent View for interactive user interfaces.
- Workflows, Agent Orchestration, and Handoffs for composed work.
- Import (JSON/YAML) for portable agent definitions.
Production Operator Path
Use this path when you deploy or operate Jidoka:
- Configuration - configure defaults, credentials, and runtime services.
- Sessions And Stores - select durable store implementations.
- Snapshots And Resume - persist and resume paused turns.
- Idempotency And Safety - control replay and side effects.
- Tracing And Events - collect safe operational evidence.
- Troubleshooting - diagnose common failures.
The in-memory stores are suitable for tests, examples, and one-node development. Use application-owned durable stores when session state, memory, trace data, or handoff ownership must survive process or node loss.
Integration Path
Read only the integration guides that apply to your system:
- Live LLM Tool Loop - verify a real provider and the complete model-operation loop.
- Jido Process Integration - run agents in the Jido process tree.
- AshJido Resources - expose selected Ash resource actions.
- Browser Tools - expose browser-backed actions.
- MCP Tools - load and call remote MCP tools.
- Skill, Workflow, And Subagent Tools - expose composed operations.
- Kino Notebooks - use Jidoka in Livebook.
Contract Reference
Use the contract guides when you serialize data, implement an adapter, or write compatibility tests:
- Agent Spec Contract
- Turn And Effect Contracts
- Operation Source Contracts
- Memory Contracts
- Import And Snapshot Contracts
- Errors And Config Reference
The module pages are the source for function signatures and types. The guides explain how the contracts work together.
Maintainer Path
The internals guides describe implementation boundaries. They are not a second public API.
- Runic Spine Internals - pure turn planning.
- Turn Runner And Effect Interpreter - the effect shell and replay boundary.
- Runtime Capabilities Internals - injected runtime functions and adapters.
- Projection Internals - stable debug and UI data.
- Contributor Testing - local quality and test commands.
Preserve the main architecture rule: pure transitions belong in the workflow steps, external work belongs in effect intents, and adapter calls belong in the effect interpreter.
Public API And Internals
Prefer the Jidoka facade and the documented DSL in application code. Public
data contracts, behaviours, and adapter boundaries are also documented in the
module reference.
Implementation-only Runtime, Adapter, Execution, Projection, Harness, and Schema module pages are filtered from the normal module index. Maintainers can use the internals guides and source. The Advanced Extension Support group contains the small set of current runtime and adapter seams that application guides still require.
Verify The Documentation
Run these commands before a release:
mix format --check-formatted
mix compile --warnings-as-errors
mix test
mix docs
mix doctor --raise
mix docs must complete without warnings. mix doctor --raise enforces the
documentation and type-specification thresholds in .doctor.exs.
Help
- Glossary defines the common runtime terms.
- Troubleshooting maps symptoms to likely causes and checks.
- Inspection And Preflight shows how to inspect an agent without calling a provider.