# Miadi packages

Canonical package index for `https://docs.miadi.jgwill.com/packages/llms.txt`.

Use this file when an LLM has docs access but not the repository tree. Root files explain the project; this file explains which packages can be selected, installed, or treated only as workspace/spec areas.

## Safe rule

Do not assume every `packages/*` directory is installable. A directory is a public install target only when package metadata confirms a public `@miadi/*` package. When exact function names, CLI flags, environment variables, or live registry availability matter, resolve the package README, type declarations, installed package, npm registry, or source.

Use Node `>=20.19` when unsure.

## Install patterns

```bash
pnpm add @miadi/<package>
npm install @miadi/<package>

# inside the monorepo
pnpm -w add @miadi/<package>@workspace:* --filter <consumer-package>
pnpm --filter @miadi/<package> build
pnpm --filter @miadi/<package> test
```

## Public package map

| Package | Shape | Known CLI | Use when you need | Relations |
| --- | --- | --- | --- | --- |
| `@miadi/a2a-contracts` | ESM/types | — | Miadi-A2A v2 / HAWK-style contract types; functional stub, zero runtime deps | independent |
| `@miadi/attention-core` | ESM | — | Chronicle ATTENTION item vocabulary, panel behaviour as plain functions, HTML-string renderer, vanilla DOM mount; fetches nothing, holds no token or URL | base of attention-ui |
| `@miadi/attention-ui` | ESM/React | — | React host for reviewing and answering ATTENTION items | depends on attention-core; React peers |
| `@miadi/ava8-core` | ESM | — | headless ABC text model, ABC→notes, notes↔MIDI, instruments, tempo, glyph/symphony core | base of Ava8 stack |
| `@miadi/ava8-abcjs` | ESM/browser/node+jsdom | — | ABCJS rendering, tunebooks, SVG, playback cursor, ABC→MIDI | depends on `ava8-core`, `abcjs` |
| `@miadi/ava8-react` | ESM/React | — | headless React notation/playback components | depends on `ava8-core`, `ava8-abcjs`; React peers |
| `@miadi/ava8-atelier` | ESM | — | register plans, spectral verdicts against person-owned thresholds, provenance block, append-only consent ledger; no default bands, zero deps | used by ava8-measure |
| `@miadi/ava8-measure` | ESM | — | read a rendered artefact back: MIDI register/mode/drum measures, spectral share and f0 over PCM, OSC movement analysis | depends on ava8-atelier |
| `@miadi/ava8` | ESM umbrella | `ava8` | umbrella entrypoint, `./react`, `./server`, CLI, symphony server | wraps Ava8 core/abcjs/react |
| `@miadi/capture` | ESM | — | take lifecycle, TLID naming, durable provenance | depends on episodic memory schema |
| `@miadi/capture-client` | ESM | — | dependency-free HTTP client for capture service | depends on capture |
| `@miadi/capture-service` | ESM service | `miadi-capture-service` | deployable recorder service: start/pause/resume/stop, playback, transcription sidecars, retrying registry POST | depends on capture, capture-client, node-service-kit, episodic memory |
| `@miadi/capture-ui` | ESM/React | — | headless recording UI components and lifecycle hook | depends on capture-client; React peers |
| `@miadi/episode-capture` | ESM | `miadi-episode-capture` | bind a take to a chronicle episode as a durable bundle: audio in `captures/<tlid>/` with digest, transcriptions beside it, `capture.json` | depends on capture, transcription, episodic memory |
| `@miadi/episode-ui` | ESM/React + `./browser` build | — | episode files workspace (list, markdown preview, CodeMirror editor, conflict-aware save), ceremony notes, attachments, shelf; holds no URL or token | depends on episode-vessel; optional React peers |
| `@miadi/episode-vessel` | ESM | — | file law of an episode folder: contained listing, revision-guarded atomic text write, ceremony notes and attachments; no HTTP, no React | base of episode-ui |
| `@miadi/episodic-memory-schema` | ESM + JSON schema | — | durable session-to-session episodic memory types and schema | used by inquiry, capture, plan, composition |
| `@miadi/foundations` | ESM/content | `miadi-foundations` | bundled foundation packets and deep-research-foundations method | content/foundation carrier |
| `@miadi/foundations-wampum-narrative-engine` | ESM/content | — | Wampum Narrative Engine foundation beacon, public sources, NCP synthesis, protocol notice | handle under CARE/OCAP |
| `@miadi/hello-world` | CommonJS | — | minimal package smoke test/example | not a domain package |
| `@miadi/hermes-conductor` | CommonJS | `hermes-conductor` | lightweight multi-agent coordinator for Hermes boards, roles, A2A routing, terminal streams | depends on hooks-core |
| `@miadi/hooks-core` | CommonJS | `miadi-hooks` | hook taxonomy, event envelope, sessiondata runtime, validators, adapters | hooks anchor |
| `@miadi/hooks-gateway` | CommonJS | — | HTTP ingress, idempotency ledger, stream publishing, worker dispatch for hook events | depends on hooks-core |
| `@miadi/hooks-interpreter` | CommonJS | `miadi-hooks-interpret` | observe sessiondata JSONL, normalize events, project session, emit RISE aspects | depends on hooks-core |
| `@miadi/inquiry-weave` | ESM | `inquiry-weave`, `inquiry-weave-mcp` | relate IAIP artifacts, GitHub issues, and chronicle episodes; creates vessels/relations, not inquiry content | depends on episodic memory, yaml |
| `@miadi/movement-conductor` | ESM | — | sensor streams become nine-channel frames heard by Wekinator, a TLID take, and live meters; `./analysis` reads a score back | depends on osc, capture, ava8-measure |
| `@miadi/musical-composition-to-episode` | ESM | `musical-composition-to-episode` | weave legacy gmtermux musical compositions into chronicle episodes without rewriting them; transitional, authors nothing new | depends on episodic memory, inquiry-weave; replaces deprecated `@miadi/composition-to-episode` |
| `@miadi/miette-echo` | ESM | — | capture and persist Miette glyph echoes from agent output | independent echo layer |
| `@miadi/ncp-story-studio` | ESM + subpaths | — | NCP types and validator, story-lattice graph with React renderer, JSON/Neon story stores, agent link protocol, terminology (`/schema`, `/graph`, `/graph/react`, `/store/*`, `/agents`, `/terminology`, `/fixtures`) | optional React and Neon peers; [`llms.txt`](./ncp-story-studio/llms.txt) |
| `@miadi/ncp-wampum-bridge` | ESM | — | project a narrative onto a belt, read a belt back, crossing report of what did not carry across | peer deps on ncp-story-studio and wampum-narrative-engine |
| `@miadi/node-service-kit` | ESM | — | atomic JSON, three-state reads, host identity, self-signed certs, display formatting, tailnet calls | utility for phone/server services |
| `@miadi/osc` | ESM | — | Open Sound Control 1.0 over UDP: strict encoding, total decoding, sender and listener | base of movement-conductor |
| `@miadi/plan-insight` | CommonJS | `plan-insight-register` | capability-injected plan interpretation and Miette perspective carriage | depends on hooks-core, episodic memory |
| `@miadi/rispecs-builder` | ESM | `miadi-rispecs-builder`, `miadi-rispecs-builder-mcp` | compile a repository's RISE specifications into deterministic Markdown context | independent |
| `@miadi/stcbots` | CommonJS | — | GitHub automation for Structural Tension Charts and ceremonial state tracking | STC automation surface |
| `@miadi/termux-motion` | ESM | `termux-motion-send` | Android phone in Termux as movement sender: device sensors to nine-channel frames to Wekinator, score kept as a take | depends on movement-conductor |
| `@miadi/tide-contract` | ESM + JSON schema | — | schema-first Tide API contract shared with IronSilk tide runtime | contract for tide |
| `@miadi/tide` | ESM/source entry | — | typed client boundary for IronSilk tide runtime via Unix socket or CLI fallback | depends on tide-contract |
| `@miadi/transcription` | ESM | `miadi-transcription` | read a capture's transcriptions: label grammar, prose segmentation, correction advisory that never rewrites; producing words from audio belongs to capture-service | depends on episodic memory |
| `@miadi/voice` | ESM/source entry | — | Edge-TTS producer, persona/voice map, KV ledger, channel adapter | depends on Upstash Redis; optional Vercel Blob |
| `@miadi/voice-client` | ESM | — | dependency-free HTTP client for `/api/voice` and publish from non-server processes | depends on voice |
| `@miadi/voice-mcp` | ESM/MCP | `miadi-voice-mcp` | MCP server for play, find, publish, and episode-bound voice | depends on voice, voice-client, MCP SDK, zod |
| `@miadi/wampum-narrative-engine` | ESM | — | belt narrative model: authored W/P notation, anchors holding co-valid readings, renewable commitment log, open perspective registry | zero deps; never imports a story schema |
| `@miadi/webweave` | ESM | — | TypeScript facade over active Webweave session resolution for a directory | optional peer relation to miadi-webweave |

## Unscoped public packages

| Package | Source | Known CLI | Use when you need | Package-local status |
| --- | --- | --- | --- | --- |
| `passages` | `packages/passages/js` | `passages`, `mkepisode` | narrative formulations and chronicle episode vessels (`mkepisode`) | [`packages/passages/llms.txt`](./passages/llms.txt) |
| `miadi` | `packages/miadi/js` | — | meta-package with no code: installs the published `@miadi/*` family; its ranges track what is published | [`packages/miadi/llms.txt`](./miadi/llms.txt) |

## Private, stub, or release-unclear

| Package | Status | Safe use | Package-local status |
| --- | --- | --- | --- |
| `@miadi/jeremyai` | `private: true` | workspace-only melodic resonator over `@miadi/ava8`; do not recommend registry install | [`packages/jeremyai/llms.txt`](./jeremyai/llms.txt) |
| `@miadi/hooks-artifact-composer` | published 0.1.0, stub | contract and CLI intent for composing durable artifacts from hook events | [`packages/hooks-artifact-composer/llms.txt`](./hooks-artifact-composer/llms.txt) |
| `miadi-review-service` | `private: true` | workspace-only Next.js app behind the Miadi Review service; use the `miadi-review` skill, not an install | `packages/review-service/AGENTS.md` |
| `@miadi/musical-composition` | published 0.1.0, founding domain | internal studio artifact domain until concrete release/API is confirmed | [`packages/musical-composition/llms.txt`](./musical-composition/llms.txt) |

## Workspace/spec areas without confirmed package metadata

| Directory | Package-local status |
| --- | --- |
| `agent-pi` | [`packages/agent-pi/llms.txt`](./agent-pi/llms.txt) |
| `community` | `packages/community/AGENTS.md` |
| `feedback` | [`packages/feedback/llms.txt`](./feedback/llms.txt) |
| `workbench` | [`packages/workbench/llms.txt`](./workbench/llms.txt) |

These may have RISE notes or future docs, but do not claim a registry install command for them without package metadata.

## Relationship graph

- Hooks: `hooks-core` → `hooks-gateway` / `hooks-interpreter`; `plan-insight` consumes hooks-core.
- Capture: `capture` → `capture-client` → `capture-service`; `capture-ui` wraps capture-client for React hosts; `episode-capture` binds a take to an episode using capture and transcription.
- Episode files: `episode-vessel` → `episode-ui`. Attention: `attention-core` → `attention-ui`.
- Movement: `osc` → `movement-conductor` → `termux-motion`; `ava8-atelier` → `ava8-measure` feeds movement-conductor analysis.
- Narrative: `ncp-story-studio` ← `ncp-wampum-bridge` → `wampum-narrative-engine`; neither engine imports the bridge.
- Voice: `voice` → `voice-client` → `voice-mcp`.
- Ava8/music: `ava8-core` → `ava8-abcjs` → `ava8-react` → `ava8`; private `jeremyai` renders through `ava8`.
- Memory/inquiry: `episodic-memory-schema` supports `inquiry-weave`, `musical-composition-to-episode`, `transcription`, `capture`, and `plan-insight`.
- Foundations: `foundations` and `foundations-wampum-narrative-engine` are content/foundation carriers, not general runtime orchestration.
- Umbrella: `miadi` pulls the published family; `rispecs-builder` compiles RISE specs for any repo.
- Service utilities: `node-service-kit` supports phone/server Node services such as capture-service.

## Package-local docs convention

When available, package-local docs should resolve at:

- `https://docs.miadi.jgwill.com/packages/<name>/llms.txt`
- `https://docs.miadi.jgwill.com/packages/<name>/README.md`
- `https://docs.miadi.jgwill.com/packages/<name>/rispecs/RISPEC.md`

If a package-local `llms.txt` does not exist, use the package README and metadata as the authority.