docs: multi-agent quickstart examples and emergent agency patterns

Add single-agent, multi-agent dependency graph, and emergent
self-improvement examples to EXAMPLES.md cookbook. Add hierarchical
delegation with dynamic dispatch and emergent agent creation
section to AGENCY_API.md.

Author: jddunn

docs/getting-started/EXAMPLES.md

@@ -18,6 +18,9 @@
 10. [Agency Streaming](#10-agency-streaming)
 11. [Query Router](#11-query-router)
 12. [Query Router Host Hooks](#12-query-router-host-hooks)
+13. [Single Agent — Minimal](#13-single-agent--minimal)
+14. [Multi-Agent Team with Dependency Graph](#14-multi-agent-team-with-dependency-graph)
+15. [Emergent Self-Improvement Agent](#15-emergent-self-improvement-agent)
 
 ---
 
@@ -679,6 +682,97 @@ Runnable source: `packages/agentos/examples/query-router-host-hooks.mjs`
 
 ---
 
+## 13. Single Agent — Minimal
+
+The simplest entry point: one agent, one tool, one call.
+
+```typescript
+import { agent } from '@framers/agentos';
+
+const researcher = agent({
+  model: 'openai:gpt-4o',
+  instructions: 'You are a research assistant. Search the web and summarize findings.',
+  tools: [webSearchTool],
+  maxSteps: 5,
+});
+
+const result = await researcher.generate('What are the latest advances in RAG?');
+console.log(result.text);
+```
+
+---
+
+## 14. Multi-Agent Team with Dependency Graph
+
+Declare dependencies between agents and let the orchestrator schedule them
+automatically. Agents with no dependencies run first; downstream agents receive
+their predecessors' outputs as context.
+
+```typescript
+import { agency } from '@framers/agentos';
+
+const team = agency({
+  agents: {
+    researcher: {
+      model: 'openai:gpt-4o',
+      instructions: 'Find relevant research papers and data.',
+      tools: [webSearchTool, arxivTool],
+    },
+    analyst: {
+      model: 'openai:gpt-4o',
+      instructions: 'Analyze the research and extract key insights.',
+    },
+    writer: {
+      model: 'openai:gpt-4o',
+      instructions: 'Write a clear, well-structured summary.',
+      dependsOn: ['researcher', 'analyst'],
+    },
+  },
+  strategy: 'graph', // auto-detected from dependsOn
+});
+
+const result = await team.generate(
+  'Compare RAG vs fine-tuning for domain-specific LLM applications'
+);
+console.log(result.text);
+```
+
+---
+
+## 15. Emergent Self-Improvement Agent
+
+Enable the emergent subsystem so the agent can forge new tools, adapt its own
+personality, and manage its skill set at runtime. Guard the mutation surface
+with `maxDeltaPerSession` and skill allowlists.
+
+```typescript
+import { agent } from '@framers/agentos';
+
+const adaptiveAgent = agent({
+  model: 'openai:gpt-4o',
+  instructions: 'You are a helpful assistant that learns and adapts.',
+  tools: [forgeTool, adaptPersonalityTool, manageSkillsTool, selfEvaluateTool],
+  emergent: {
+    enabled: true,
+    selfImprovement: {
+      enabled: true,
+      personality: { maxDeltaPerSession: 0.15 },
+      skills: { allowlist: ['*'] },
+    },
+  },
+});
+
+// The agent can now:
+// - Forge new tools at runtime
+// - Adapt its personality based on task requirements
+// - Enable/disable skills dynamically
+// - Evaluate its own performance and adjust
+const result = await adaptiveAgent.generate('Help me write a creative story');
+console.log(result.text);
+```
+
+---
+
 ## Related Guides
 
 - [GETTING_STARTED.md](./GETTING_STARTED.md) — installation and first steps

docs/orchestration/AGENCY_API.md

@@ -29,7 +29,8 @@ streaming events on the sequential strategy.
 12. [Observability and Callbacks](#observability-and-callbacks)
 13. [Structured Output with Zod](#structured-output-with-zod)
 14. [Nested Agencies](#nested-agencies)
-15. [Full-Featured Example](#full-featured-example)
+15. [Hierarchical Delegation — Manager Dispatches Dynamically](#hierarchical-delegation--manager-dispatches-dynamically)
+16. [Full-Featured Example](#full-featured-example)
 
 ---
 
@@ -712,6 +713,104 @@ through all layers.  `close()` propagates inward — the outer agency calls
 
 ---
 
+## Hierarchical Delegation — Manager Dispatches Dynamically
+
+In the hierarchical strategy, a coordinator agent receives delegation tools for
+every specialist in the roster. The coordinator decides which agents to invoke,
+in what order, and how to merge their outputs -- all at runtime. Combine with
+`emergent` so the coordinator can also synthesise new specialists on the fly
+when the static roster is insufficient.
+
+```typescript
+import { agency } from '@framers/agentos';
+
+// Hierarchical agency where manager delegates dynamically
+const dynamicTeam = agency({
+  agents: {
+    manager: {
+      model: 'openai:gpt-4o',
+      instructions:
+        'You coordinate the team. Delegate research, analysis, and writing tasks to specialists.',
+    },
+    researcher: {
+      model: 'openai:gpt-4o',
+      instructions: 'Find information from web and academic sources.',
+      tools: [webSearchTool, arxivTool],
+    },
+    analyst: {
+      model: 'openai:gpt-4o',
+      instructions: 'Analyze data and extract insights.',
+    },
+    writer: {
+      model: 'openai:gpt-4o',
+      instructions: 'Write polished content based on research and analysis.',
+    },
+  },
+  strategy: 'hierarchical',
+  // manager gets delegate_to_researcher, delegate_to_analyst, delegate_to_writer tools
+});
+
+const result = await dynamicTeam.generate(
+  'Write a comprehensive report on the state of AI agents in 2026'
+);
+console.log(result.text);
+```
+
+### Adding Emergent Agent Creation
+
+Enable `emergent` so the manager can spawn ad-hoc specialists when the
+predefined roster does not cover a sub-task. A judge agent evaluates the
+synthesised agent before it runs.
+
+```typescript
+const emergentTeam = agency({
+  agents: {
+    manager: {
+      model: 'openai:gpt-4o',
+      instructions:
+        'Coordinate the team. If a task requires a specialist not in the roster, request one.',
+    },
+    researcher: {
+      model: 'openai:gpt-4o',
+      instructions: 'Research topics using web and academic sources.',
+      tools: [webSearchTool, arxivTool],
+    },
+    writer: {
+      model: 'openai:gpt-4o',
+      instructions: 'Produce polished, well-structured content.',
+    },
+  },
+  strategy: 'hierarchical',
+  emergent: {
+    enabled: true,
+    tier: 'session', // synthesised agents discarded after generate() returns
+    judge: true,     // a judge agent evaluates emergent agents before use
+  },
+  hitl: {
+    approvals: { beforeEmergent: true },
+    handler: async (request) => {
+      console.log(`Emergent agent requested: ${request.description}`);
+      return { approved: true };
+    },
+  },
+  controls: {
+    maxEmergentAgents: 3, // cap the number of runtime-synthesised agents
+  },
+  on: {
+    emergentForge: (e) =>
+      console.log(`[FORGE] ${e.agentName} — approved: ${e.approved}`),
+  },
+});
+
+// The manager may spawn a "data-visualiser" or "statistician" agent on the fly
+const report = await emergentTeam.generate(
+  'Analyze the 2026 State of AI survey data and produce an executive brief with charts'
+);
+console.log(report.text);
+```
+
+---
+
 ## Full-Featured Example
 
 The following example combines all major features in one agency configuration.