Table of Contents for Docs, signals section

.gitignore

@@ -31,6 +31,6 @@ jido-*.tar
 # expublish
 RELEASE.md
 
-# Local Nodes
+# Local Notes
 NOTES.md
 PLAN.md

guides/about/alternatives.md

@@ -0,0 +1,13 @@
+# Alternative Solutions
+
+_Part of the "About Jido" section in the documentation._
+
+This guide compares Jido with alternative agent frameworks and solutions, helping developers understand where Jido fits in the ecosystem. It provides an honest assessment of when to use Jido versus other options, including both open-source and commercial alternatives.
+
+This is a living document, and is not comprehensive. We are not _vouching_ for any of these packages, but rather listing them here for your convenience to investigate on your own.
+
+Want to add or edit this list? Open a [pull request](https://github.com/agentjido/jido/edit/main/guides/about/alternatives.md) Want a more comprehensive list? Check out the [Awesome Elixir](https://github.com/h4cc/awesome-elixir).
+
+## Agents
+
+- [Agent](https://hexdocs.pm/elixir/Agent.html) - For simple agent systems, using the built-in Agent module may be sufficient.

guides/about/design-principles.md

@@ -0,0 +1,5 @@
+# Design Principles
+
+_Part of the "About Jido" section in the documentation._
+
+This guide outlines the core design principles and architectural decisions that shape Jido. It explains the key philosophies behind the framework's design, including its emphasis on distributed systems, functional programming, and agent autonomy.

guides/about/do-you-need-an-agent.md

@@ -0,0 +1,27 @@
+# Do You Need an Agent?
+
+_Part of the "About Jido" section in the documentation._
+
+This guide helps developers evaluate whether their use case is appropriate for an agent-based solution using Jido. It covers common scenarios where agents excel, potential alternatives, and factors to consider when making architectural decisions.
+
+Agents are a hot topic right now, but they aren't a silver bullet. In particular, Large Language Models (LLMs) are powerful yet slow and costly—if your application doesn't require dynamic decision-making or complex planning, consider whether you really need an Agent at all.
+
+- **LLMs aren't required for all tasks** — Avoid building them into your core logic unless necessary
+- **Agents as Dynamic ETL** — Agents dynamically direct data ingestion, transformation, and output based on:
+  - LLMs (e.g., GPT)
+  - Classical planning algorithms (A\*, Behavior Trees, etc.)
+- **Simplicity often wins** — If you don't need these dynamic behaviors, you probably don't need an Agent. This library is likely overkill compared to straightforward code.
+
+### Our Definition of an Agent
+
+An Agent is a system where LLMs _or_ classical planning algorithms dynamically direct their own processes. Some great definitions from the community:
+
+- "Agents are Dynamic ETL processes directed by LLMs" — [YouTube](https://youtu.be/KY8n96Erp5Q?si=5Itt7QR11jgfWDTY&t=22)
+- "Agents are systems where LLMs dynamically direct their own processes" — [Anthropic Research](https://www.anthropic.com/research/building-effective-agents)
+- "AI Agents are programs where LLM outputs control the workflow" — [Hugging Face Blog](https://huggingface.co/blog/smolagents)
+
+If your application doesn't involve dynamic workflows or data pipelines that change based on AI or planning algorithms, you can likely do more with less.
+
+> 💡 **NOTE**: This library intends to support both LLM planning and Classical AI planning (ie. [Behavior Trees](https://github.com/jschomay/elixir-behavior-tree) as a design principle via Actions. See [`jido_ai`](https://github.com/agentjido/jido_ai) for example LLM actions.
+
+_This space is evolving rapidly. Last updated 2025-01-01_?

guides/about/what-is-jido.md

@@ -0,0 +1,5 @@
+# What is Jido?
+
+_Part of the "About Jido" section in the documentation._
+
+This guide provides a high-level overview of what Jido is, its core purpose, and where it fits in the landscape of agent-based systems. It serves as the primary introduction to the framework and explains the fundamental concepts that make Jido unique.

guides/about/where-is-the-AI.md

@@ -0,0 +1,5 @@
+# Where is the AI?
+
+_Part of the "About Jido" section in the documentation._
+
+This guide explains Jido's approach to AI integration, clarifying that Jido is an agent framework that can work with both AI and classical planning approaches. It discusses how AI components can be integrated through the Actions system and points to companion libraries for AI-specific functionality.

guides/actions/actions-as-tools.md

@@ -0,0 +1,5 @@
+# Actions as Tools
+
+_Part of the "Actions" section in the documentation._
+
+This guide explains how actions can be exposed as tools for AI agents, particularly in the context of LLM-based systems. It covers tool definition, documentation standards, and integration patterns with AI planning systems.

guides/actions/chaining.md

@@ -0,0 +1,5 @@
+# Action Chaining
+
+_Part of the "Actions" section in the documentation._
+
+This guide covers advanced patterns for chaining actions together, including data flow between actions, conditional execution, and error handling strategies. It provides patterns and best practices for building complex action chains.

guides/actions/directives.md

@@ -0,0 +1,5 @@
+# Action Directives
+
+_Part of the "Actions" section in the documentation._
+
+This guide explains the directive system that allows actions to influence agent behavior and state. It covers built-in directives, their usage patterns, and how to implement custom directives for specialized needs.

guides/actions/instructions.md

@@ -1,4 +1,8 @@
-# Instructions Guide
+# Action Instructions
+
+_Part of the "Actions" section in the documentation._
+
+This guide covers the instruction system used to define action behavior. It explains how to write clear, maintainable instructions that can be interpreted by both AI and classical planning systems.
 
 ## Overview
 
@@ -22,6 +26,7 @@ A full instruction struct contains:
 Jido supports several shorthand formats for convenience, all of which are normalized to the full instruction struct during processing. Here are the supported formats:
 
 ### 1. Action Module Only
+
 ```elixir
 # Shorthand
 MyApp.Actions.ProcessFile
@@ -35,6 +40,7 @@ MyApp.Actions.ProcessFile
 ```
 
 ### 2. Action With Parameters (Tuple Form)
+
 ```elixir
 # Shorthand
 {MyApp.Actions.ProcessFile, %{path: "/tmp/data.csv"}}
@@ -48,6 +54,7 @@ MyApp.Actions.ProcessFile
 ```
 
 ### 3. Full Instruction Struct
+
 ```elixir
 # Explicit struct
 %Instruction{
@@ -58,6 +65,7 @@ MyApp.Actions.ProcessFile
 ```
 
 ### 4. Lists of Mixed Formats
+
 ```elixir
 # Mixed shorthand list
 [
@@ -72,11 +80,13 @@ MyApp.Actions.ProcessFile
 ## Normalization Process
 
 All instruction formats are normalized when:
+
 1. Planning actions on an Agent
 2. Directly executing through a Runner
 3. Creating instruction queues
 
 The normalization ensures:
+
 - Consistent structure for execution
 - Parameter validation
 - Context preservation
@@ -88,6 +98,7 @@ The normalization ensures:
 ### When to Use Shorthand
 
 Use shorthand formats when:
+
 - Planning simple action sequences
 - Writing tests
 - Demonstrating examples
@@ -105,6 +116,7 @@ Use shorthand formats when:
 ### When to Use Full Structs
 
 Use full instruction structs when:
+
 - Implementing custom runners
 - Building complex workflows
 - Needing explicit context control
@@ -126,6 +138,7 @@ instruction = %Instruction{
 ### Context Management
 
 The context map is preserved during normalization and is available to:
+
 - Action implementations
 - Runners
 - Error handlers
@@ -156,11 +169,11 @@ end
 # Transform instructions
 def add_context(instructions, context) do
   Enum.map(instructions, fn
-    %Instruction{} = inst -> 
+    %Instruction{} = inst ->
       %{inst | context: Map.merge(inst.context, context)}
-    {action, params} -> 
+    {action, params} ->
       %Instruction{action: action, params: params, context: context}
-    action when is_atom(action) -> 
+    action when is_atom(action) ->
       %Instruction{action: action, context: context}
   end)
 end
@@ -172,7 +185,7 @@ Instructions provide rich error context:
 
 ```elixir
 case MyAgent.plan(agent, invalid_instruction) do
-  {:ok, agent} -> 
+  {:ok, agent} ->
     # Success case
   {:error, %Error{type: :validation_error, context: context}} ->
     # Handle validation failure with full context
@@ -186,14 +199,14 @@ Test both shorthand and normalized forms:
 ```elixir
 test "supports shorthand planning" do
   {:ok, agent} = MyAgent.plan(agent, SimpleAction)
-  assert [%Instruction{action: SimpleAction}] = 
+  assert [%Instruction{action: SimpleAction}] =
     :queue.to_list(agent.pending_instructions)
 end
 
 test "preserves context in normalization" do
   context = %{request_id: "123"}
   {:ok, agent} = MyAgent.plan(agent, SimpleAction, context)
-  
+
   [instruction] = :queue.to_list(agent.pending_instructions)
   assert instruction.context.request_id == "123"
 end
@@ -208,4 +221,4 @@ end
 - Test both shorthand and normalized forms
 - Handle errors with full context
 
-Remember: Instructions are always normalized before execution, so choose the format that makes your code most readable and maintainable in each specific situation.
+Remember: Instructions are always normalized before execution, so choose the format that makes your code most readable and maintainable in each specific situation.