### Start Development Server and Build Production Version (Bash)

Source: https://docs.miadi.jgwill.com/llms-full.txt

Provides commands to start the development server and build the production version of the project using pnpm. The development server typically runs on port 3335.

```bash
pnpm dev       # Start development server on port 3335
pnpm build     # Build production version
```

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

### Demo Flow API

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Initiates a simulated demo flow between agents.

```APIDOC
## POST /api/a2a-test

### Description
Triggers a simulated demonstration of agent-to-agent communication flow.

### Method
POST

### Endpoint
/api/a2a-test

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the demo flow has started.

#### Response Example
```json
{
  "message": "Demo flow initiated successfully."
}
```
```

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

### Message Broker API in TypeScript

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Provides examples of using the Message Broker API in TypeScript for sending, receiving, marking as read, and clearing messages. It relies on functions imported from '@/lib/a2a-message-broker'.

```typescript
import { sendMessage, getMessages, markMessageAsRead, clearMessages } from "@/lib/a2a-message-broker"

const msg = await sendMessage("agent-a", "agent-b", "analysis_complete", { result: "..." })
const messages = await getMessages("agent-b")  // unread only
await markMessageAsRead(msg.id)
await clearMessages("agent-b")
```

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

### Demo Flow using cURL

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Initiates a simulated agent-to-agent communication flow using a cURL command. This is useful for testing and demonstrating the A2A system.

```bash
curl -X POST http://localhost:3335/api/a2a-test
```

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

### Get Messages using cURL

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Shows how to retrieve messages for a specific agent using a cURL command. This is used by an agent to fetch incoming messages from the queue.

```bash
curl "http://localhost:3335/api/a2a/messages?agentId=agent-b"
```

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

### Tracer API in TypeScript

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Demonstrates the usage of the Tracer API in TypeScript for initializing traces, logging agent start/complete events, message send/receive events, and trace completion. It uses functions imported from '@/lib/a2a-tracer'.

```typescript
import { initializeTrace, logAgentStart, logAgentComplete,
         logMessageSend, logMessageReceive, logTraceComplete } from "@/lib/a2a-tracer"

initializeTrace(traceId, agentId)
logAgentStart(traceId, agentId, "analysis", "Analyze beat")
logAgentComplete(traceId, agentId, result)
logMessageSend(traceId, from, to, type, payload)
logMessageReceive(traceId, agentId, messageId, type)
logTraceComplete(traceId, "success", summary)

Logs to: `TRACE_LOG_PATH` env var or `/src/logs.miadi.log`
```

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

### Get Messages API

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Retrieves unread messages for a specific agent from the Redis queue.

```APIDOC
## GET /api/a2a/messages

### Description
Retrieves a list of unread messages for a specified agent.

### Method
GET

### Endpoint
/api/a2a/messages

### Parameters
#### Query Parameters
- **agentId** (string) - Required - The identifier of the agent for whom to retrieve messages.

### Response
#### Success Response (200)
- **messages** (array) - A list of message objects.
  - **id** (string) - The unique identifier of the message.
  - **from** (string) - The identifier of the sending agent.
  - **to** (string) - The identifier of the receiving agent.
  - **type** (string) - The type or category of the message.
  - **payload** (object) - The content of the message.
  - **timestamp** (string) - The timestamp when the message was sent.

#### Response Example
```json
{
  "messages": [
    {
      "id": "msg-123e4567-e89b-12d3-a456-426614174000",
      "from": "agent-a",
      "to": "agent-b",
      "type": "analysis_complete",
      "payload": {
        "result": "..."
      },
      "timestamp": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

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

### Send Message using cURL

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Demonstrates how to send a message between agents using a cURL command. It specifies the sender, receiver, message type, and payload.

```bash
curl -X POST http://localhost:3335/api/a2a/message \
  -H 'Content-Type: application/json' \
  -d '{"from":"agent-a","to":"agent-b","type":"analysis_complete","payload":{"result":"..."}}'
```

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

### Live Story Monitor Tools (TypeScript)

Source: https://docs.miadi.jgwill.com/llms-full.txt

Functions for managing and monitoring live story scenes within the narrative platform. Includes tools to create, retrieve, archive, and get the history of story scenes across different universes.

```typescript
// 5 MCP tools
miadi-create-story-scene({ event, universes: ['engineer', 'ceremony', 'story_engine'] })
miadi-get-active-scenes({ limit? })
miadi-archive-scene({ sceneId })
miadi-get-scene-history({ universe?, limit? })
miadi-monitor-health()
```

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

### Clear Messages using cURL

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Demonstrates how to clear all messages for a specific agent using a cURL command. This can be used to clean up the message queue.

```bash
curl -X DELETE "http://localhost:3335/api/a2a/messages?agentId=agent-b"
```

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

### Mark Message as Read using cURL

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Illustrates how to mark a specific message as read using a cURL command. This is typically done after an agent has processed a message.

```bash
curl -X PATCH "http://localhost:3335/api/a2a/messages?messageId=msg-xxx"
```

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

### Mark Message Read API

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Marks a specific message as read for an agent, removing it from their unread queue.

```APIDOC
## PATCH /api/a2a/messages

### Description
Marks a specific message as read for the intended agent.

### Method
PATCH

### Endpoint
/api/a2a/messages

### Parameters
#### Query Parameters
- **messageId** (string) - Required - The unique identifier of the message to mark as read.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., "success").

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### Send Message API

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Allows an agent to send a message to another agent. Messages are stored in a Redis queue for the recipient agent.

```APIDOC
## POST /api/a2a/message

### Description
Sends a message from one agent to another using Redis message passing.

### Method
POST

### Endpoint
/api/a2a/message

### Parameters
#### Request Body
- **from** (string) - Required - The identifier of the sending agent.
- **to** (string) - Required - The identifier of the receiving agent.
- **type** (string) - Required - The type or category of the message.
- **payload** (object) - Required - The content of the message.

### Request Example
```json
{
  "from": "agent-a",
  "to": "agent-b",
  "type": "analysis_complete",
  "payload": {
    "result": "..."
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the sent message.

#### Response Example
```json
{
  "id": "msg-123e4567-e89b-12d3-a456-426614174000"
}
```
```

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

### Health Check using cURL

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Shows how to perform a health check on the A2A communication system using a cURL command. This is useful for monitoring system status.

```bash
curl http://localhost:3335/api/a2a/health
```

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

### Test GitHub Hook with Sample Payload

Source: https://docs.miadi.jgwill.com/CLAUDE

This snippet demonstrates how to test a GitHub hook by piping a sample JSON payload to the hook script. It simulates receiving webhook data via stdin and setting environment variables for event metadata.

```bash
cat sample-payload.json | WEBHOOK_EVENT_TYPE=push ./.github-hooks/push
```

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

### Health Check API

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Checks the operational status of the agent-to-agent communication system.

```APIDOC
## GET /api/a2a/health

### Description
Provides a health status check for the A2A communication service.

### Method
GET

### Endpoint
/api/a2a/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the service (e.g., "operational").

#### Response Example
```json
{
  "status": "operational"
}
```
```

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

### PDE CLI Commands

Source: https://docs.miadi.jgwill.com/llms-full.txt

Lists the available command-line interface commands for interacting with the Prompt Decomposition Engine. These commands allow users to perform various decomposition and analysis tasks.

```bash
/pde decompose "prompt"  - Full 5-layer decomposition
/pde quick "prompt"      - Summary workflow view
/pde intents "prompt"    - Intent extraction only
/pde deps "prompt"       - Dependency graph only
/pde wheel "prompt"      - Medicine Wheel mapping
/pde workflow "prompt"   - Workflow template
/pde plan "prompt"       - Execution plan
/pde check "prompt"      - Complexity check
/pde ceremony [type]     - Ceremony requirements
/pde export [format]     - Export (json/yaml/md)
/pde last                - Show last decomposition
```

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

### Clear Messages API

Source: https://docs.miadi.jgwill.com/A2A_QUICK_START

Clears all messages for a specific agent from the Redis queue.

```APIDOC
## DELETE /api/a2a/messages

### Description
Clears all messages associated with a specific agent from the message queue.

### Method
DELETE

### Endpoint
/api/a2a/messages

### Parameters
#### Query Parameters
- **agentId** (string) - Required - The identifier of the agent whose messages should be cleared.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., "success").

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### PDE Module CLI Commands

Source: https://docs.miadi.jgwill.com/llms-full.txt

This section outlines the various command-line interface commands available for the Prompt Decomposition Engine (PDE) module.

```APIDOC
## PDE Module CLI Commands

### Description
Provides a set of CLI commands to interact with the 5-layer Prompt Decomposition Engine for various analysis and generation tasks.

### Method
CLI Commands

### Endpoint
N/A (Local CLI)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
/pde decompose "User prompt here"
/pde quick "Another prompt"
```

### Response
#### Success Response
Output varies based on the command used. Can include decomposed prompt details, dependency graphs, workflows, execution plans, or complexity checks.

#### Response Example
```json
// Example for /pde decompose "prompt"
{
  "explicitIntents": [...],
  "implicitIntents": [...],
  "classifiedIntents": [...],
  "dependencyGraph": {...},
  "medicineWheelAssignments": [...],
  "workflow": {...},
  "executionPlan": {...}
}
```
```

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

### Memory System Tools (TypeScript)

Source: https://docs.miadi.jgwill.com/llms-full.txt

Provides functions for interacting with the Redis-backed memory storage. Includes tools for storing, retrieving, listing, scanning, gathering, and synchronizing memory data. Supports pattern matching and TTL.

```typescript
// Memory tool categories (9 tools)
miadi-store-memory({ key, value, ttl? })
miadi-get-memory({ key })
miadi-list-memories({ pattern?, limit? })
miadi-memory-scan({ pattern, cursor?, count? })
miadi-memory-gather({ keys })
miadi-sync-memory({ source, target })
```

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

### Prompt Decomposition Engine Layers

Source: https://docs.miadi.jgwill.com/llms-full.txt

Illustrates the 5-layer process of the Prompt Decomposition Engine, from intent extraction to execution planning. This is a conceptual overview of the PDE's internal workings.

```text
User Prompt
  → Layer 1: Intent Extraction (explicit + implicit)
  → Layer 2: Dependency Analysis (graph + topological order)
  → Layer 3: Medicine Wheel Mapping (EAST/SOUTH/WEST/NORTH)
  → Layer 4: Workflow Generation (parallel/sequential stages)
  → Layer 5: Execution Planning (CLI commands + checkpoints)
```

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

### Memory System Tools

Source: https://docs.miadi.jgwill.com/llms-full.txt

Tools for interacting with the Redis-backed memory system, including storing, retrieving, listing, and scanning memory entries.

```APIDOC
## Memory System Tools

### Description
Tools for interacting with the Redis-backed memory system, including storing, retrieving, listing, and scanning memory entries.

### Method
Various (functions exposed as tools)

### Endpoints
N/A (Tool-based functions)

### Parameters
#### miadi-store-memory
- **key** (string) - Required - The key for the memory entry.
- **value** (any) - Required - The value to store.
- **ttl** (number) - Optional - Time-to-live for the memory entry in seconds.

#### miadi-get-memory
- **key** (string) - Required - The key of the memory entry to retrieve.

#### miadi-list-memories
- **pattern** (string) - Optional - A pattern to filter memory keys.
- **limit** (number) - Optional - The maximum number of keys to return.

#### miadi-memory-scan
- **pattern** (string) - Required - The pattern to scan for.
- **cursor** (string) - Optional - The cursor for pagination.
- **count** (number) - Optional - The number of keys to return per scan.

#### miadi-memory-gather
- **keys** (array of strings) - Required - An array of keys to retrieve values for.

#### miadi-sync-memory
- **source** (string) - Required - The source memory key.
- **target** (string) - Required - The target memory key.

### Request Example
```json
{
  "tool_name": "miadi-store-memory",
  "arguments": {
    "key": "user_session_123",
    "value": {"user_id": "abc", "timestamp": "2023-10-27T10:00:00Z"},
    "ttl": 3600
  }
}
```

### Response
#### Success Response (200)
- **miadi-store-memory**: null (or confirmation)
- **miadi-get-memory**: (any) - The retrieved memory value.
- **miadi-list-memories**: array of strings - List of matching memory keys.
- **miadi-memory-scan**: object - Contains `cursor` and `keys`.
- **miadi-memory-gather**: object - Key-value pairs of retrieved memories.
- **miadi-sync-memory**: null (or confirmation)

#### Response Example
```json
{
  "key": "user_session_123",
  "value": {"user_id": "abc", "timestamp": "2023-10-27T10:00:00Z"}
}
```
```

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

### Live Story Monitor Tools

Source: https://docs.miadi.jgwill.com/llms-full.txt

Tools for managing and monitoring live story scenes, including creation, retrieval, archiving, and history.

```APIDOC
## Live Story Monitor Tools

### Description
Tools for managing and monitoring live story scenes, including creation, retrieval, archiving, and history.

### Method
Various (functions exposed as tools)

### Endpoints
N/A (Tool-based functions)

### Parameters
#### miadi-create-story-scene
- **event** (object) - Required - The event data to create the scene from.
- **universes** (array of strings) - Required - The universes to associate the scene with (e.g., ['engineer', 'ceremony', 'story_engine']).

#### miadi-get-active-scenes
- **limit** (number) - Optional - The maximum number of active scenes to return.

#### miadi-archive-scene
- **sceneId** (string) - Required - The ID of the scene to archive.

#### miadi-get-scene-history
- **universe** (string) - Optional - Filter history by a specific universe.
- **limit** (number) - Optional - The maximum number of history entries to return.

#### miadi-monitor-health
- No parameters.

### Request Example
```json
{
  "tool_name": "miadi-create-story-scene",
  "arguments": {
    "event": {"type": "pull_request", "title": "Fix bug #123"},
    "universes": ["engineer", "story_engine"]
  }
}
```

### Response
#### Success Response (200)
- **miadi-create-story-scene**: object - The created story scene.
- **miadi-get-active-scenes**: array of objects - List of active story scenes.
- **miadi-archive-scene**: null (or confirmation)
- **miadi-get-scene-history**: array of objects - Scene history entries.
- **miadi-monitor-health**: object - Health status of the monitor.

#### Response Example
```json
{
  "sceneId": "scene_xyz789",
  "title": "Bug Fix PR",
  "status": "active",
  "universes": ["engineer", "story_engine"]
}
```
```

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

### MIADI-CODE-PDE Architecture Flow

Source: https://docs.miadi.jgwill.com/llms-full.txt

Illustrates the architectural flow of the MIADI-CODE-PDE when used as an MCP tool. It shows the interaction between agent sessions, the PDE functions, LLM processing, and data storage in Redis.

```text
Agent Session A (Decomposer)
  → miadi-code-pde::pde_decompose()
  → LLM processes systemPrompt + userMessage
  → miadi-code-pde::pde_parse_response()
    → .pde/<uuid>.json + .pde/<uuid>.md (local)
    → POST /api/pde/webhook → Redis (pde:decompositions:{uuid})
    → pde:events:queue (event notification)

Agent Session B (Partner/Reviewer)
  → Reads pde:decompositions:{uuid} from Redis
  → Applies structural-thinking validation
  → Edits .pde/<uuid>.md or provides review feedback
```

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

### Spiral Memory Tools (TypeScript)

Source: https://docs.miadi.jgwill.com/llms-full.txt

Tools for managing nested memory layers with depth-based descent and search capabilities. Allows storing, descending into, and searching within spiral memory structures.

```typescript
miadi-spiral-descend({ key, depth })
miadi-spiral-search({ query, maxDepth? })
miadi-spiral-store({ key, value, depth })
```

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

### Redis Storage Schema for PDE

Source: https://docs.miadi.jgwill.com/llms-full.txt

Details the Redis keys and their corresponding data structures used for storing PDE decompositions and related events. This schema facilitates cross-session access and event notifications.

```text
pde:decompositions:{uuid}     — Full DecompositionResult JSON
pde:events:queue               — Event queue for partner notification
pde:sessions:{session_id}      — Session-scoped decomposition list
pde:index:timestamp            — Sorted set for time-based queries
```

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

### GitHub Webhook ETL

Source: https://docs.miadi.jgwill.com/llms-full.txt

API endpoint for receiving GitHub webhooks to trigger the ETL pipeline for event classification and narrative beat generation.

```APIDOC
## GitHub Webhook ETL

### Description
API endpoint for receiving GitHub webhooks to trigger the ETL pipeline for event classification and narrative beat generation. This endpoint processes events like push, pull_request, and issues, feeding them into the three-universe analysis.

### Method
POST

### Endpoint
/api/github/webhook

### Parameters
#### Request Body
- **event_type** (string) - Required - The type of GitHub event (e.g., 'push', 'pull_request', 'issues').
- **payload** (object) - Required - The full payload of the GitHub event.

### Request Example
```json
{
  "event_type": "pull_request",
  "payload": {
    "action": "opened",
    "pull_request": {
      "number": 123,
      "title": "Add new feature"
    },
    "repository": {
      "full_name": "owner/repo"
    }
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the webhook was received and processed.

#### Response Example
```json
{
  "message": "GitHub webhook received and processing initiated."
}
```
```