### Setup Development Environment

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/contributors/package-quality-standards.md

Install all necessary dependencies and configure the development environment for the project.

```bash
mix setup
```

--------------------------------

### Install Package via Igniter

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/contributors/package-quality-standards.md

Example of how to install a package using the `mix igniter.install` command. This is typically documented in the package's README.

```bash
mix igniter.install my_package
```

--------------------------------

### Minimal Runnable Starter Example

Source: https://github.com/agentjido/jido_run/blob/main/priv/prompts/content_gen/templates/docs-concept.md

Provides the fastest runnable path to first success with minimal setup.

```elixir
# Minimal runnable starter example
```

--------------------------------

### Clone and Setup Jido Workbench

Source: https://github.com/agentjido/jido_run/blob/main/README.md

Steps to clone the repository, set up the environment, and start the development server.

```bash
git clone git@github.com:agentjido/agentjido_xyz.git
cd agentjido_xyz
cp .env.example .env
mix setup
mix phx.server
```

--------------------------------

### Setup and Create Agent Tutorials

Source: https://github.com/agentjido/jido_run/blob/main/specs/competitors/02-llamaindex/topics.md

General guidance and reference material for framework tutorials, with an emphasis on setup and agent creation.

```APIDOC
## Setup and Create Agent Tutorials

### Description
Covers general guidance and reference material for framework tutorials, emphasizing setup and agent creation.

### Reference
- [1 setup](https://developers.llamaindex.ai/typescript/framework/tutorials/agents/1_setup/)
- [2 create agent](https://developers.llamaindex.ai/typescript/framework/tutorials/agents/2_create_agent/)
```

--------------------------------

### Markdown Guide Structure: Getting Started

Source: https://github.com/agentjido/jido_run/blob/main/specs/docs-manifesto.md

Structure guides using the 'slippery slide' principle, where each section naturally leads to the next. Start with a compelling introduction, followed by minimal prerequisites, and then step-by-step instructions.

```markdown
# Getting Started with MyLib

You've got a GenServer that's becoming a bottleneck. Requests queue up,
response times spike, and you're not sure where the problem is.

This guide shows you how to surface that bottleneck in under 5 minutes.

## Prerequisites

[Minimal list—don't pad this]

## Step 1: Add the dependency

[Code, then one sentence of context if needed]

## Step 2: ...
```

--------------------------------

### Livebook Setup Cell with Dependencies and Logger Configuration

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/contributors/livebook-authoring-standards.md

This setup cell installs necessary dependencies using Mix.install, configures the logger level to warning, and disables compiler documentation generation temporarily. It's crucial for ensuring a clean and controlled execution environment for Livebooks.

```elixir
Mix.install([
  {{mix_dep:jido}},
  {{mix_dep:jido_ai}},
  {{mix_dep:req_llm}}
])

Logger.configure(level: :warning)

# Livebook imports can execute generated docs as doctests.
# Disable compiler docs until the current Jido Hex release drops the invalid signal_types/0 example.
Code.put_compiler_option(:docs, false)
```

--------------------------------

### Start AgentServer Process

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/concepts/agent-runtime.md

Use `Jido.AgentServer.start/1` to start an agent under `Jido.AgentSupervisor`. Use `Jido.AgentServer.start_link/1` to start an agent linked to the calling process, optionally providing an ID and initial state.

```elixir
 {:ok, pid} = Jido.AgentServer.start(agent: MyAgent)

 {:ok, pid} = Jido.AgentServer.start_link(
  agent: MyAgent,
  id: "order-42",
  initial_state: %{total: 0}
 )
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/agentjido/jido_run/blob/main/specs/templates/ecosystem-package.md

After updating `mix.exs`, run this command to fetch and install all project dependencies.

```bash
mix deps.get
```

--------------------------------

### Project Setup and Management Commands

Source: https://github.com/agentjido/jido_run/blob/main/AGENTS.md

Use these commands for initial project setup, running the development server, executing tests, and maintaining code quality.

```bash
mix setup
```

```bash
mix phx.server
```

```bash
iex -S mix phx.server
```

```bash
mix test
```

```bash
mix test test/path/to/test_file.exs:LINE
```

```bash
mix format
```

```bash
mix credo
```

--------------------------------

### Configure Jido Browser Install Alias

Source: https://github.com/agentjido/jido_run/blob/main/priv/examples/jido-ai-browser-web-workflow.md

Set up a setup alias to automatically fetch dependencies and install the jido_browser package if it's missing. This ensures the browser backend is ready when needed.

```elixir
defp aliases do
  [
    setup: ["deps.get", "jido_browser.install --if-missing"]
  ]
end
```

--------------------------------

### Example Usage of Package

Source: https://github.com/agentjido/jido_run/blob/main/priv/prompts/content_gen/templates/ecosystem-package.md

This is a runnable code example demonstrating a key capability of the package. It shows how to use the package's features in a practical scenario. Ensure this example compiles against the current package version.

```elixir
# [WHAT THIS EXAMPLE SHOWS]

[RUNNABLE CODE EXAMPLE]
```

--------------------------------

### Start Runtime and LLM Agent

Source: https://context7.com/agentjido/jido_run/llms.txt

Demonstrates starting the Jido runtime and then launching an LLM-backed agent like `MyApp.WeatherAgent`. Requires `Jido.start()` and `Jido.start_agent/4`.

```elixir
{:ok, _}    = Jido.start()
runtime     = Jido.default_instance()
{:ok, pid}  = Jido.start_agent(runtime, MyApp.WeatherAgent, id: "weather-1")

```

--------------------------------

### Example: Creating an Agent

Source: https://github.com/agentjido/jido_run/blob/main/priv/prompts/content_gen/templates/docs-reference.md

This example demonstrates the basic process of creating a new agent. Ensure the agent's behavior and dependencies are correctly defined.

```elixir
[RUNNABLE CODE]
```

--------------------------------

### Minimal Example

Source: https://github.com/agentjido/jido_run/blob/main/priv/prompts/content_gen/templates/docs-concept.md

A basic example demonstrating the core functionality of the concept.

```elixir
# Minimal example
```

--------------------------------

### Realistic Example

Source: https://github.com/agentjido/jido_run/blob/main/priv/prompts/content_gen/templates/docs-concept.md

A more comprehensive example suitable for production environments, including relevant caveats.

```elixir
# Realistic example
```

--------------------------------

### Verify Jido Applications Started

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/getting-started/installation.md

Start an IEx session and confirm that both the :jido and :jido_ai applications have started successfully.

```shell
iex -S mix
```

```elixir
iex> Application.ensure_all_started(:jido)
#=> {:ok, _}
iex> Application.ensure_all_started(:jido_ai)
#=> {:ok, _}
```

--------------------------------

### Jido Runtime Start with Default Instance

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/contributors/livebook-authoring-standards.md

This snippet demonstrates the canonical Livebook pattern for starting the Jido runtime and a default agent. It ensures rerunnability and avoids confusion with custom runtime names, making it suitable for beginner notebooks.

```elixir
{:ok, _} = Jido.start()

runtime = Jido.default_instance()
tag_id = "chat-demo-" <> System.unique_integer([:positive])

{:ok, pid} = Jido.start_agent(
  runtime,
  MyApp.ChatAgent,
  id: agent_id
)
```

--------------------------------

### Start AgentServer with Pre-built Struct

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/concepts/agent-runtime.md

Start an AgentServer using a pre-built agent struct. Specify `agent_module` if it differs from the struct's module.

```elixir
agent = MyAgent.new(id: "prebuilt", state: %{value: 99})
{:ok, pid} = Jido.AgentServer.start_link(
 agent: agent,
 agent_module: MyAgent
)
```

--------------------------------

### Elixir Example: Demonstrating a Specific Capability

Source: https://github.com/agentjido/jido_run/blob/main/priv/prompts/content_gen/templates/feature-page.md

A concise, runnable Elixir code example demonstrating a core capability of the feature. Ensure it is under 30 lines and uses realistic module/function names. The expected output should also be provided.

```elixir
# [BRIEF DESCRIPTION OF WHAT THIS EXAMPLE DEMONSTRATES]

[RUNNABLE CODE EXAMPLE — UNDER 30 LINES]
```

--------------------------------

### Agent Configuration Example

Source: https://github.com/agentjido/jido_run/blob/main/specs/learn-content-briefs.md

Example of frontmatter configuration for a documentation page, including title, description, category, order, tags, draft status, and prerequisites.

```elixir
%{
  title: "Reasoning strategies compared",
  description: "Solve the same problem with Chain-of-Thought, Tree-of-Thoughts, and Adaptive strategies.",
  category: :docs,
  order: 31,
  tags: [:docs, :learn, :ai, :strategies, :cot, :tot, :adaptive, :livebook],
  draft: true,
  prerequisites: ["/docs/learn/ai-agent-with-tools"]
}
```

--------------------------------

### Full Agent Lifecycle: Start, Route, Assert State

Source: https://context7.com/agentjido/jido_run/llms.txt

Demonstrates starting the Jido runtime, launching an agent, sending a signal, and asserting the resulting state change. Requires `Jido.start()` and `Jido.start_agent/4`.

```elixir
{:ok, _} = Jido.start()
{:ok, pid} = Jido.start_agent(Jido.default_instance(), MyApp.OrderAgent, id: "order-1")

signal = Jido.Signal.new!("order.placed", %{order_id: "ord_42", total: 99.99}, source: "/checkout")
{:ok, agent} = Jido.AgentServer.call(pid, signal)
agent.state.processed  #=> 1
```

--------------------------------

### Define and Start a Jido Agent

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/features/how-agents-work.md

Define a new agent with its name, description, tools, and system prompt. Then, start it supervised and send it a message.

```elixir
defmodule MyApp.SupportAgent do
  use Jido.AI.Agent,
    name: "support_agent",
    description: "Customer support agent",
    tools: [MyApp.Tools.KnowledgeBase, MyApp.Tools.TicketSystem],
    system_prompt: "You help customers resolve product issues."
end

# Start supervised
{:ok, pid} = Jido.AgentServer.start(agent: MyApp.SupportAgent)

# Ask it a question
MyApp.SupportAgent.ask(pid, "My order hasn't arrived")
```

--------------------------------

### Start Supervised Orchestrator Server

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/features/executive-brief.md

Starts a supervised orchestrator server for a Jido agent. This demonstrates the runtime model used for larger adoption phases. It also retrieves and checks the state of the agent.

```elixir
{:ok, _pid} =
  Jido.AgentServer.start_link(
    id: AgentJido.ContentOps.OrchestratorServer,
    agent: AgentJido.ContentOps.OrchestratorAgent,
    jido: AgentJido.Jido,
    name: AgentJido.ContentOps.OrchestratorServer
  )

{:ok, server_state} = Jido.AgentServer.state(AgentJido.ContentOps.OrchestratorServer)
is_map(server_state.agent.state)
```

```text
true
```

--------------------------------

### Start and Call Jido AgentServer

Source: https://context7.com/agentjido/jido_run/llms.txt

Start Jido agents as supervised OTP processes using `Jido.AgentServer.start` or `start_link`. Agents handle signal routing, directive execution, and process supervision. Signals can be sent synchronously via `call/3` or asynchronously via `cast/2`.

```elixir
# Start under Jido.AgentSupervisor
{:ok, pid} = Jido.AgentServer.start(agent: MyApp.CounterAgent)

# Start linked to calling process with options
{:ok, pid} = Jido.AgentServer.start_link(
  agent:         MyApp.CounterAgent,
  id:            "counter-42",
  initial_state: %{count: 0},
  max_queue_size: 5_000,
  debug:         true
)

# Send a signal synchronously — returns updated agent
signal = Jido.Signal.new!("counter.increment", %{by: 5}, source: "/api")
{:ok, agent} = Jido.AgentServer.call(pid, signal)
agent.state.count  #=> 5
```

--------------------------------

### Start and Query a Jido AI Agent

Source: https://github.com/agentjido/jido_run/blob/main/priv/blog/2026/03-04-jido-2-0-is-here.md

Start the agent server and then ask a question synchronously. The `ask_sync` function handles the agent's reasoning loop and tool execution.

```elixir
# Start the agent and ask a question
{:ok, pid} = Jido.AgentServer.start_link(agent: MyApp.SupportAgent)

{:ok, answer} = MyApp.SupportAgent.ask_sync(
  pid,
  "Order #4521 hasn't arrived. Can you check on it and open a ticket?",
  timeout: 60_000
)
```

--------------------------------

### Elixir Package Aliases for Git Hooks

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/contributors/package-quality-standards.md

Defines Elixir aliases for package setup and Git hook installation. The `install_hooks` alias is used to explicitly install custom hook scripts.

```elixir
defp aliases do
  [
    setup: ["deps.get"],
    install_hooks: ["git_hooks.install"]
  ]
end

```

--------------------------------

### Asynchronous Action Execution

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/concepts/execution.md

Starts an action asynchronously and returns a reference immediately. Use `await/2` to get the result or `cancel/1` to terminate the task. The process that starts the async action is the only one that can await or cancel it.

```elixir
ref = Jido.Exec.run_async(MyApp.GenerateReport, %{quarter: "Q4"})

result = Jido.Exec.await(ref, 60_000)

:ok = Jido.Exec.cancel(ref)
```

--------------------------------

### Jido Workbench Development Setup

Source: https://context7.com/agentjido/jido_run/llms.txt

Provides commands for cloning the Jido repository, setting up the environment, running the development server, and performing quality checks.

```bash
git clone git@github.com:agentjido/agentjido_xyz.git
cd agentjido_xyz
cp .env.example .env
# edit .env with OPENAI_API_KEY and DATABASE_URL

mix setup          # deps, assets, DB migrations, seeds
mix phx.server     # http://localhost:4000

# Bootstrap a local admin account
ADMIN_EMAIL=you@example.com ADMIN_PASSWORD='at-least-12-chars' mix run priv/repo/seeds.exs

# Quality checks
mix test
mix format
mix credo --strict
mix quality          # format + compile warnings-as-errors + credo + dialyzer

# Link audit
mix site.link_audit --include-heex
mix site.link_audit --include-heex --check-external
```

--------------------------------

### Example Agent Invocation

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/concepts/agents.md

Demonstrates how to create a new agent, execute a command using `cmd/2` with an action and parameters, and inspect the updated agent state and directives.

```elixir
# Example invocation:
# agent = MyApp.CounterAgent.new()
# {updated_agent, directives} = MyApp.CounterAgent.cmd(agent, {MyApp.Increment, %{by: 2}})
# updated_agent.state.count
# # => 2
# directives
# # => []
```

--------------------------------

### Callout Block Examples

Source: https://github.com/agentjido/jido_run/blob/main/specs/docs-style-guide.md

Examples of using blockquotes with bold labels for notes, warnings, and tips in documentation.

```markdown
> **Note:** Agents are immutable structs, not processes. See [Agent Runtime](/docs/concepts/agent-runtime) for the process layer.
```

```markdown
> **Warning:** Never store API keys in `config/config.exs`. Use `config/runtime.exs` for all secrets.
```

```markdown
> **Tip:** Run `cmd/2` in IEx to inspect state transitions interactively.
```

--------------------------------

### IEx Session Example

Source: https://github.com/agentjido/jido_run/blob/main/specs/docs-style-guide.md

Demonstrates creating a new agent and accessing its state within an IEx session.

```elixir
iex> agent = MyApp.CounterAgent.new()
iex> agent.state.count
#=> 0
```

--------------------------------

### Create Your First Agent

Source: https://github.com/agentjido/jido_run/blob/main/specs/templates/training-module.md

This exercise guides you through creating your initial Jido agent. It demonstrates the basic structure and signal handling.

```elixir
defmodule MyFirstAgent do
  use Jido.Agent, 
    signals: [:hello]

  @impl true
  def handle_signal(:hello, _from, state) do
    {:reply, "World", state}
  end
end
```

--------------------------------

### Start Jido Application

Source: https://context7.com/agentjido/jido_run/llms.txt

Ensure the Jido application is started within your Elixir shell using `Application.ensure_all_started(:jido)`.

```shell
iex -S mix
iex> Application.ensure_all_started(:jido)
#=> {:ok, _}
```

--------------------------------

### Install Git Hooks

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/contributors/package-quality-standards.md

Explicitly install git hooks from the primary checkout. This ensures that pre-commit and other hooks are active.

```bash
mix install_hooks
```

--------------------------------

### Run Studio Step Demo

Source: https://github.com/agentjido/jido_run/blob/main/priv/examples/runic-ai-research-studio-step-mode.md

Execute the step-mode demo script for the Runic AI Research Studio using Mix.

```bash
mix run lib/examples/studio_step_demo.exs
```

--------------------------------

### Example Agent Invocation and State Check

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/concepts/agents.md

Demonstrates how to create a new agent, invoke a command to process a registration, and inspect the resulting agent state and directives. The state is updated, and an emit directive is generated.

```elixir
# Example invocation:
# agent = MyApp.RegistrationAgent.new()
# {agent, directives} =
#   MyApp.RegistrationAgent.cmd(agent, {MyApp.ProcessRegistration, %{user_id: "usr_123"}})
# agent.state
# # => %{processed: 1, last_user_id: "usr_123"}
# directives
# # => [%Jido.Agent.Directive.Emit{...}]
```

--------------------------------

### Running Commands on Counter Agent

Source: https://github.com/agentjido/jido_run/blob/main/priv/content_plan/docs/learn/counter-agent.md

Demonstrates how to start the Counter agent and send commands to it sequentially, observing the state changes. This shows the agent's deterministic behavior.

```elixir
iex> {:ok, agent} = Counter.start_link()
{:ok, #PID<0.123.0>}

iex> Counter.cmd(agent, {:increment, 5})
:ok

iex> Counter.cmd(agent, {:increment, 2})
:ok

iex> Counter.cmd(agent, {:decrement, 3})
:ok

iex> Counter.cmd(agent, :reset)
:ok

iex> Counter.state(agent)
%Counter.State{count: 0}
```

--------------------------------

### Get Data Source API

Source: https://github.com/agentjido/jido_run/blob/main/specs/competitors/02-llamaindex/topics.md

Retrieves information about a specific data source. This API is used to get details of configured data origins.

```APIDOC
## GET /v1/data-sources/{data_source_id}

### Description
Returns details for a specified data source.

### Method
GET

### Endpoint
/v1/data-sources/{data_source_id}

### Parameters
#### Path Parameters
- **data_source_id** (string) - Required - The ID of the data source.
```

--------------------------------

### Run Runic Research Studio Demo

Source: https://github.com/agentjido/jido_run/blob/main/priv/examples/runic-ai-research-studio.md

Execute the Runic research studio example using the mix run command. This demonstrates the full pipeline execution.

```bash
mix run lib/examples/studio_demo.exs
```

--------------------------------

### Get Data Sink API

Source: https://github.com/agentjido/jido_run/blob/main/specs/competitors/02-llamaindex/topics.md

Retrieves information about a specific data sink. This API is used to get details of configured data destinations.

```APIDOC
## GET /v1/data-sinks/{data_sink_id}

### Description
Returns details for a specified data sink.

### Method
GET

### Endpoint
/v1/data-sinks/{data_sink_id}

### Parameters
#### Path Parameters
- **data_sink_id** (string) - Required - The ID of the data sink.
```

--------------------------------

### Elixir Library Configuration Example

Source: https://github.com/agentjido/jido_run/blob/main/specs/docs-manifesto.md

Demonstrates a common pattern for configuring a library, contrasting a less effective API-surface-focused approach with a more practical, transformation-oriented one.

```elixir
# BAD: Shows API surface
MyLib.configure(option: :value)
MyLib.do_thing()
```

```elixir
# GOOD: Shows complete, working transformation
# Before: Manual, error-prone approach
defmodule MyApp.Worker do
  def process(data) do
    case validate(data) do
      {:ok, valid} ->
        case transform(valid) do
          {:ok, result} -> {:ok, save(result)}
          {:error, reason} -> {:error, reason}
        end
      {:error, reason} -> {:error, reason}
    end
  end
end
```

```elixir
# After: With MyLib
defmodule MyApp.Worker do
  use MyLib.Pipeline

  def process(data) do
    data
    |> validate()
    |> transform()
    |> save()
  end
end
```

--------------------------------

### Configure LLM Provider in runtime.exs

Source: https://github.com/agentjido/jido_run/blob/main/priv/content_plan/docs/learn/first-llm-agent.md

Set up your LLM provider and API key in `config/runtime.exs`. This example shows configuration for Anthropic, but OpenAI or others can be used similarly.

```elixir
import Config

config :jido_ai, :providers,
  anthropic: [api_key: System.fetch_env!("ANTHROPIC_API_KEY")]

config :jido_ai, :default_provider, :anthropic
```

--------------------------------

### Minimal Content Brief Example

Source: https://github.com/agentjido/jido_run/blob/main/specs/topic-briefs-todo.md

This example demonstrates the basic structure of a content brief, including essential frontmatter fields and the 'prompt_overrides' map, followed by the Content Brief section.

```markdown
%{
priority: :high,
status: :draft,
title: "Signals",
destination_route: "/docs/concepts/signals",
destination_collection: :pages,
order: 40,
purpose: "Document typed message envelopes and routing patterns",
audience: :intermediate,
content_type: :guide,
learning_outcomes: ["Create stable signal contracts", "Route signals safely"],
prerequisites: ["docs/concepts/key-concepts"],
related: ["docs/concepts/actions", "docs/concepts/agent-runtime"],
repos: ["jido_signal", "jido"],
ecosystem_packages: ["jido_signal", "jido"],
tags: [:docs, :core, :signals],
source_modules: ["Jido.Signal"],
prompt_overrides: %{
document_intent: "Write the authoritative guide to Jido Signals.",
required_sections: ["Signal Structure", "Routing Patterns"],
must_include: ["Signal fields aligned with source", "Idempotency considerations"],
must_avoid: ["Duplicating tutorial content from Learn section"],
required_links: ["/docs/concepts/agents", "/docs/learn/signals-routing"],
min_words: 600,
max_words: 1_200,
minimum_code_blocks: 2,
diagram_policy: "optional",
section_density: "light_technical",
max_paragraph_sentences: 3
}
}

---

## Content Brief

Signal structure, metadata, routing, and practical coordination guidance.

```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/contributors/package-quality-standards.md

Examples of conventional commit messages in bash. These demonstrate how to structure commit messages for different types of changes, including features, fixes, and breaking changes.

```bash
git commit -m "feat(schema): add validation for email fields"
git commit -m "fix: resolve timeout in async operations"
git commit -m "feat!: breaking change to API"

```

--------------------------------

### Next Steps Section Example

Source: https://github.com/agentjido/jido_run/blob/main/specs/docs-style-guide.md

A standard 'Next Steps' section with a brief introduction and a bulleted list of related documentation links.

```markdown
## Next Steps

Now that you've defined your first agent, continue building.

- [Build Your First LLM Agent](/docs/learn/first-llm-agent) - add AI capabilities
- [Actions and Validation](/docs/learn/actions-validation) - deeper dive into action schemas
- [Agents concept](/docs/concepts/agents) - understand the data-first model
```

--------------------------------

### Disable Git Hooks Auto-Install Configuration

Source: https://github.com/agentjido/jido_run/blob/main/priv/pages/docs/contributors/package-quality-standards.md

Elixir configuration to disable the automatic installation of Git hooks. This is typically set in `config/dev.exs` and `config/test.exs` to ensure hooks are installed explicitly.

```elixir
# config/dev.exs and config/test.exs
import Config

config :git_hooks, auto_install: false

```

--------------------------------

### Launch MCP Docs Server

Source: https://github.com/agentjido/jido_run/blob/main/README.md

Command to start the read-only MCP documentation server. Ensure the project is compiled first.

```bash
mix mcp.docs
```