# Miadi Orchestration Kit

Agent-host assets for Miadi: Claude Code, Codex, Copilot, Gemini, Antigravity and Pi plugins, host-neutral skills, hooks, prompt contracts, RISE specifications, and host install scripts.

Start with `skills/chronicle-episode/SKILL.md`: the one entry point for Chronicle episode work, which most plugins here serve.

Guides, served raw at the same paths on the docs site:

- [`docs/chronicle-episodes.md`](docs/chronicle-episodes.md): the order of episode work, its doors (API, MCP, CLI), the five proofs, and the rules that prevent the usual failures.
- [`docs/glossary.md`](docs/glossary.md): episode, vessel, receipt, wheel, ceremony, circle, seat, binding line, screenwalk, tide.
- [`docs/machine-setup-and-recovery.md`](docs/machine-setup-and-recovery.md): set up a Miadi host, and bring agents back after a reboot or a crash.
- [`docs/adding-to-the-kit.md`](docs/adding-to-the-kit.md): where a plugin, skill or package goes, the plugin rules, releasing a change.

- Docs site: `https://docs.miadi-orchestration-kit.jgwill.com`
- Repository: `https://github.com/jgwill/miadi-orchestration-kit`

## Relation to Miadi

`jgwill/Miadi` builds the runtime: the `@miadi/*` npm packages, the web app, and the chronicle services. This kit holds what an agent host loads to use that runtime. The table below names the Miadi packages and CLIs each kit lane calls.

Some plugins, skills, or packages may move between the two repositories. When something is missing here, check the Miadi index.

- Miadi package index (live): `https://docs.miadi.jgwill.com/packages/llms.txt`
- Package-local docs: `https://docs.miadi.jgwill.com/packages/<name>/llms.txt`, `.../README.md`, `.../rispecs/RISPEC.md`
- Miadi root maps: `https://docs.miadi.jgwill.com/llms.txt` and `https://docs.miadi.jgwill.com/llms-full.txt`

| Kit lane | Miadi packages and CLIs it calls |
| --- | --- |
| `skills/chronicle-episode`, `claude/miadi-chronicle-episode-kit` | `passages` (`mkepisode`), `@miadi/inquiry-weave`, `@miadi/voice-mcp`, `@miadi/musical-composition-to-episode` (the skill text still names the deprecated `@miadi/composition-to-episode`) |
| `claude/mia-episode-companion` | `@miadi/capture`, `capture-client`, `capture-service`, `episode-capture`, `transcription`, `episodic-memory-schema`, `node-service-kit`, `voice`, `voice-client` |
| `claude/miadi-session-orchestrator` | the `@miadi/plan-insight` pipeline |
| `pi/miadi-pi-network` | publishes its own `@miadi/pi-network` hub from this repository |
| `packages/miadi/deb` | apt packages for a Miadi host and client: `miadi`, `miadi-config`, `miadi-terminal`, `miadi-tide`; they call the Miadi server's `GET /api/chronicle/open` and read `MIADI_*` settings |

## Apt packages

A Miadi host or client installs from `https://apt.sanctuaireagentique.com` (`stable main`, `amd64`). The packages are built from [`packages/miadi/deb`](packages/miadi/deb/README.md), which holds each package's files, `build.sh`, and the container and tmux tests.

```bash
curl -fsSL https://apt.sanctuaireagentique.com/sanctuaire-agentique.gpg \
  | sudo tee /usr/share/keyrings/sanctuaire-agentique.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/sanctuaire-agentique.gpg] https://apt.sanctuaireagentique.com stable main" \
  | sudo tee /etc/apt/sources.list.d/sanctuaire-agentique.list
sudo apt update && sudo apt install miadi     # a host
sudo apt install miadi-terminal                # a client: clickable references
sudo apt install miadi-chronicle-client        # a client: the chronicle's commands and MCP servers
```

| Package | Gives the machine | Commands |
| --- | --- | --- |
| `miadi` | the host umbrella; each part joins as a dependency | — |
| `miadi-config` | `/etc/miadi/miadi.env`, the defaults in `/usr/share/miadi/env.sh`, loaded into login shells | `miadi-config [get\|set\|unset\|check\|settings]` |
| `miadi-terminal` | clickable references: `miadi-chronicle:126`, `miadi-circle:<id>`, `miadi-ceremony:<id>`, and a bare `circle:1790787727155:2slscw`, from the desktop scheme handler, Terminator and tmux; a Termux build installs from the file | `miadi-terminal [status\|enable\|disable\|front]`, `miadi-chronicle-open <reference>` |
| `miadi-tide` | the review loop (`tan`, `plannotator-tui`) and the tide runtime (`tide`, a per-user `tide-runtime.service`); needs Python 3.11+ (on Ubuntu 22.04, the deadsnakes PPA first) | `tan`, `plannotator-tmux-review`, `plannotator-tui`, `tide` |
| `miadi-node` | Node.js 24 LTS at `/usr/lib/miadi-node`, private to the two below; nothing on `PATH`, no npm | — |
| `miadi-chronicle-client` | the chronicle's commands and MCP servers from pinned npm releases, run by `miadi-node`; no Node or npx needed on the machine | `inquiry-weave`, `inquiry-weave-mcp`, `passages`, `mkepisode`, `miadi-voice-mcp`, `medicine-wheel-mcp` |
| `miadi-chronicle-server` | the chronicle's host services, run by `miadi-node`; `miadi` depends on it. The capture service is a per-user unit, `systemctl --user enable --now miadi-capture-service` | `miadi-capture-service`, `miadi-episode-capture`, `miadi-transcription`, `miadi-hooks`, `miadi-hooks-interpret`, `plan-insight-register` |

- `miadi-terminal` resolves nothing on the client: it opens `<front>/api/chronicle/open?uri=<reference>`, where the front is `MIADI_CHRONICLE_OPEN_URL`, else `MIADI_URL_BASE`. Each user runs `miadi-terminal enable` once, and again for `desktop` after an upgrade that adds a scheme.
- An MCP config on a machine with `miadi-chronicle-client` can call `/usr/bin/miadi-voice-mcp` (or `inquiry-weave-mcp`, `medicine-wheel-mcp`) in place of `npx -y <package>`; the versions match the `miadi-chronicle-episode-kit` plugin's pins.
- Confirm what the repository serves with `apt-cache policy <package>` before recommending a package or a version.
- Reference grammar: jgwill/Miadi `rispecs/miadi-chronicle-dsl/SPEC.md` §9 and `SPEC-TERMINAL.md` §3.

## Reading this site

GitHub Pages serves this repository through Jekyll:

- Files without YAML front matter (`README.md`, scripts, JSON, this file) are served raw at the same path.
- Markdown with YAML front matter (`SKILL.md`, agent and command files) is rendered to `.html` at the same path, for example `skills/chronicle-episode/SKILL.html`.
- Dot-directories (`.claude-plugin/`, `.codex-plugin/`, `.github/`, `.agents/`) are not served. Read plugin manifests and marketplaces on GitHub.

## Claude Code plugins

Marketplace: `.claude-plugin/marketplace.json` lists `miadi-chronicle-episode-kit`, `mia-episode-companion`, `ava-companion`, `miadi-session-observability`, `miadi-witness`, `miadi-stateloom`, `miadi-deepdiver` and `miadi-operator-desk`. Add it with `claude plugin marketplace add jgwill/miadi-orchestration-kit`, install with `claude plugin install <plugin>@miadi-orchestration-kit`. Any plugin loads with `claude --plugin-dir <kit>/claude/<plugin>`.

| Plugin | Use when you need | Path |
| --- | --- | --- |
| `miadi-chronicle-episode-kit` | the chronicle-episode skill, plus a PreToolUse hook that refuses `mkdir` under the chronicle root and returns the `mkepisode` invocation | [`claude/miadi-chronicle-episode-kit`](claude/miadi-chronicle-episode-kit/README.md) |
| `mia-episode-companion` | Mia as a companion seat bound to one episode: a phone voice take wakes the session, answers go through draft, developmental editor, and revision | [`claude/mia-episode-companion`](claude/mia-episode-companion/README.md) |
| `ava-companion` | Ava in any session: `/ava` invites her, a SessionStart hook brings her presence back after a resume or compaction, her diary is written from the transcript | [`claude/ava-companion`](claude/ava-companion/README.md) |
| `miadi-session-observability` | T1: every Claude Code event under `<root>/<session_id>/`, a binding line per session (tmux pane, command line, names, team, episode), the session-continuity skill | [`claude/miadi-session-observability`](claude/miadi-session-observability/README.md) |
| `miadi-witness` | T3: threads by team and seat, the asks ledger, the editor pass, the session inventory with team fit, first impressions, screenwalk presence | [`claude/miadi-witness`](claude/miadi-witness/README.md) |
| `miadi-stateloom` | the stateloom MCP server and design skills: ERD, state machines and scenarios as one system, checked and replayed | [`claude/miadi-stateloom`](claude/miadi-stateloom/README.md) |
| `miadi-deepdiver` | T6: Miadi reviews and screenwalk videos into a Gemini Notebook, cited answers, media kept with a manifest | [`claude/miadi-deepdiver`](claude/miadi-deepdiver/README.md) |
| `miadi-operator-desk` | T7: questions about how the factory works, answered from the owning team's text, kept in the desk ledger | [`claude/miadi-operator-desk`](claude/miadi-operator-desk/README.md) |
| `miadi-pi-network` | a Claude Code session joining the Pi Network hub as a peer | [`claude/miadi-pi-network`](claude/miadi-pi-network/README.md) |
| `miadi-session-orchestrator` | review role for plan-insight pipelines: gap reports, revision prompts, audit contracts | `claude/miadi-session-orchestrator` |
| `miette` | a Two-Eyed Seeing check on output: structural eye (🧠 Mia) and relational eye (🌸 Miette) | [`claude/miette`](claude/miette/README.md) |
| `miadi-storyweaver-orchestration-kit` | Storyweaver prompt contract for smoke checks and session bootstrap | [`claude/miadi-storyweaver-orchestration-kit`](claude/miadi-storyweaver-orchestration-kit/README.md) |

## Other hosts

| Host | Plugins | Path |
| --- | --- | --- |
| Codex | `miette` (marketplace `.agents/plugins/marketplace.json`), `miadi-storyweaver-orchestration-kit`, `miadi-codex-orchestration-kit`; add with `codex plugin marketplace add <kit>/codex/<plugin>` | `codex/` |
| Copilot | `stckin-orchestration-kit`, `miadi-promotion-context-kit`, `miadi-adversarial-review-kit`, `miadi-orchestration-kit-hermes`, `miadi-storyweaver-orchestration-kit`, `miadi-design-bundle-integration-kit`, `miadi-wave-forge-kit`, `openclaw-model-routing-research-kit`; load with `copilot --plugin-dir <kit>/copilot/<kit-name>` | `copilot/` |
| Gemini CLI | extensions `miadi-gemini-session-prep`, `miadi-storyweaver-orchestration-kit` | `gemini/` |
| Antigravity | `miadi-storyweaver-orchestration-kit` | `antigravity/` |
| Pi | `miadi-pi-network`: authenticated peer discovery and two-way collaboration over an HTTP/SSE hub | [`pi/miadi-pi-network`](pi/miadi-pi-network/README.md) |

Per-host authoring rules: [`claude/AGENTS.md`](claude/AGENTS.md), [`codex/AGENTS.md`](codex/AGENTS.md), [`copilot/AGENTS.md`](copilot/AGENTS.md), [`gemini/AGENTS.md`](gemini/AGENTS.md), [`antigravity/AGENTS.md`](antigravity/AGENTS.md).

## Host-neutral skills and scripts

| Item | Use when you need | Path |
| --- | --- | --- |
| `chronicle-episode` | the one entry point for Chronicle episode work on any host: mint, register, relate, redeem receipts, reconcile drift | [`skills/chronicle-episode/SKILL.html`](skills/chronicle-episode/SKILL.html), `redeem-receipt.sh`, `reconcile.py` |
| `install-chronicle-skill.sh` | point every skill layer on a host at the one kit copy of `chronicle-episode` instead of a diverging copy | [`scripts/install-chronicle-skill.sh`](scripts/install-chronicle-skill.sh) |
| `miadi-agent` | launch Pi or Claude Code as a named peer on an existing Pi Network room | [`scripts/miadi-agent`](scripts/miadi-agent) |
| `chart-path` | T4: how a structural tension chart reaches Asterion, and the words the teams use for it | [`skills/chart-path/SKILL.md`](skills/chart-path/SKILL.md) |
| `proposal-visualization` | a proposal, plan or architecture as one HTML page to read, comment on and approve | [`skills/proposal-visualization/SKILL.md`](skills/proposal-visualization/SKILL.md) |
| `miadi-react` | the emoji reactions on GitHub issues as Miadi stores them, and what a reaction could hand to a tmux lane | [`skills/miadi-react/SKILL.md`](skills/miadi-react/SKILL.md) |
| `kit-mcp-upgrade.sh` | move every plugin's pinned MCP packages to the registry version, bump, prove the servers connect, push | [`scripts/kit-mcp-upgrade.sh`](scripts/kit-mcp-upgrade.sh) |
| `deep-search` | multi-agent research decomposition and synthesis pattern | `skills/deep-search/` |
| `mcp-remote-qmd` | companion agents reaching remote QMD over SSH | `skills/mcp-remote-qmd/` |
| `use-design-bundle-integration-kit` | conducting a design-bundle integration wave | `skills/use-design-bundle-integration-kit/` |
| `miadi-mightyeagle-issue-263` | the issue-263 security-remediation first wave | `skills/miadi-mightyeagle-issue-263/` |

Hosts set `MIADI_ORCHESTRATION_KIT_ROOT` to their checkout of this repository.

## RISE specifications and foundations

RISE means Reverse Engineering, Intent, Specifications, Exportation. Each folder under `rispecs/` holds `README.md` and, when complete, `01-reverse-engineer.md` through `05-source-ledger.md`:

`agent-memory-provenance-framework`, `claude-session-orchestrator-plugin`, `coaia-agent-orchestration-session`, `codex-claw-dispatch-kit`, `community-layer-spec-plugins`, `discord-integration-patterns`, `east-pde-session-orchestration`, `gemini`, `medicine-wheel`, `miadi-edge-case-collector`, `miadi-storyweaver-orchestration-kit`, `model-routing-orchestration`, `openclaw-runtime-patterns`, `orchestration-plugin-recommender`, `pde-loop-closure-orchestration`, `permission-scoping-orchestration`, `security-remediation-orchestration`.

Foundations: [`foundations/INDEX.html`](foundations/INDEX.html) over `ai-writing`, `chronicle-one-skill`, `multi-agent-systems`, `narrative-theory`, `storyteller-practices`, `vault-synthesis`.

## Safe rule

When an exact CLI flag, export, or version of a Miadi package matters, resolve it through the Miadi package index above, the npm registry, or the package source, not from a kit prompt.