# Miadi full LLM operating guide

This is the expanded source-free guide for Miadi. It assumes an LLM may have docs access but not the repository tree.

For exact package status, module shape, CLI bins, and dependency direction, read [`packages/llms.txt`](./packages/llms.txt). This file explains how to use that package map safely.

## What an LLM can know from docs alone

With `README.md`, `llms.txt`, `llms-full.txt`, and `packages/llms.txt`, an LLM should be able to:

- understand Miadi as a relational package lattice,
- identify the main package families,
- pick a plausible smallest package for a task,
- distinguish public packages from private/stub/workspace areas,
- know known CLI binary names,
- know module shape at a high level,
- avoid inventing install commands for directories that are not packages.

It should **not** claim exact function names, exact CLI flags, required environment variables, or live registry publication status unless a package README, package-local docs, installed package, npm registry, type declaration, test, or source file confirms it.

## Documentation resolution model

The docs site should expose this shape:

```text
/README.md or /
/llms.txt
/llms-full.txt
/packages/llms.txt
/packages/<name>/README.md
/packages/<name>/rispecs/RISPEC.md
/packages/<name>/rispecs/README.rise.md
```

Package-local `llms.txt` files may be added when a package needs a dedicated machine-first entrypoint. Until then, the package README and package metadata remain enough for exact API lookup.

## Safe install baseline

Use Node `>=20.19` when unsure.

External consumer, after registry confirmation:

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

Monorepo/workspace consumer:

```bash
pnpm install
pnpm -w add @miadi/<package>@workspace:* --filter <consumer-package>
pnpm --filter @miadi/<package> build
pnpm --filter @miadi/<package> test
```

Do not assume npm can consume internal `workspace:*` dependency declarations from an unpublished package. Published packages should have registry-resolved dependencies.

## Host and client install (apt)

A Miadi host (the server, its settings, its runtime) and a Miadi client (a machine that reads chronicle references) install from the apt repository `https://apt.sanctuaireagentique.com`, suite `stable`, component `main`, architecture `amd64`. The packages are authored in `jgwill/miadi-orchestration-kit` under `packages/miadi/deb`, which holds their README, build script and tests. They are not npm packages and do not appear in `packages/llms.txt`.

```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: the MIADI_* settings (miadi-config) and what joins as a dependency
sudo apt install miadi-terminal   # a client: clickable chronicle, ceremony and circle references
```

| package | gives the machine |
|---|---|
| `miadi` | the umbrella for a host; each part joins as a dependency |
| `miadi-config` | `/etc/miadi/miadi.env` (plain `KEY=VALUE`, kept on upgrade), `/usr/share/miadi/env.sh` (defaults), `/etc/profile.d/miadi.sh` (loads them into login shells), and `miadi-config` |
| `miadi-terminal` | clickable references on a client: desktop scheme handler, Terminator plugin, tmux binding; a Termux build installs from the file |
| `miadi-tide` | the review loop (`tan`, `plannotator-tui`) and the tide runtime (`tide`, and `tide-runtime.service`, a per-user systemd unit each user enables); needs Python 3.11+ with `venv`, so on Ubuntu 22.04 add the deadsnakes PPA before `apt install miadi` |

Confirm what the repository serves with `apt-cache policy <package>` before recommending a package or a version.

### miadi-config

A value in the environment wins over `/etc/miadi/miadi.env`, which wins over the defaults in `env.sh`. The file holds no secrets.

```bash
miadi-config                          # every setting, its value and its source
miadi-config get MIADI_URL_BASE       # one resolved value, for scripts
sudo miadi-config set MIADI_SRC /a/src/Miadi
miadi-config check                    # what this host is missing
miadi-config settings                 # what each setting does
```

### miadi-terminal

The client resolves nothing. `/usr/bin/miadi-chronicle-open` turns a reference into `<front>/api/chronicle/open?uri=<reference>` and the Miadi server redirects to the page. The front is `MIADI_CHRONICLE_OPEN_URL`, else `MIADI_URL_BASE`, read through `miadi-config`.

```bash
sudo apt install miadi-terminal
miadi-terminal front https://<your Miadi>   # only when MIADI_URL_BASE is not already it
miadi-terminal enable                       # once per user: desktop, terminator, tmux
miadi-terminal status                       # what a click does here, per integration
miadi-chronicle-open circle:1790787727155:2slscw   # print the URL a click would open
```

- `desktop`: `miadi-chronicle:`, `miadi-ceremony:` and `miadi-circle:` open from any application (an OSC 8 link, a link in a page, `xdg-open`). A user enabled before 0.1.4 runs `miadi-terminal enable desktop` again for the two newer schemes.
- `terminator`: Ctrl+click a bare reference. Restart Terminator after an upgrade.
- `tmux`: click, or tap on Termux, a bare reference in a pane. Needs `set -g mouse on`. Reload a running server with `tmux source-file` after an upgrade.
- `enable` writes only that user's configs and keeps a `.bak-miadi-terminal` of each.

## Chronicle, ceremony, circle and foundation references

Contract: `rispecs/miadi-chronicle-dsl/SPEC.md` (§9 for ceremonies and circles, §10 for foundations) and `SPEC-TERMINAL.md` (the terminal click).

```text
miadi-chronicle:126                         an episode
miadi-chronicle:311/services-inventory      an artifact of an episode
miadi-circle:circle:1790787727155:2slscw    a circle (the id is the wheel's, verbatim)
miadi-ceremony:<uuid>                        a ceremony
miadi-foundation:<slug>[/<file>]             a foundation packet from @miadi/foundations, page /foundations/<slug>
miadi-chronicle:550/foundations[/<topic>]   the packets episode 550 holds, or one it wrote under foundations/<topic>/
circle:1790787727155:2slscw                 a bare circle id; a terminal click gives it its scheme
ceremony:ep<N>:<slug>:<n>                   a bare ceremony id
```

- Rootless is canonical. `//` after the scheme is accepted on input and never emitted.
- In articles and episode scripts and chapters, a link, an autolink `<miadi-circle:…>` or a directive `{{ circle:1790787727155:2slscw | show=card }}` renders what the reader's seat allows.
- `GET /api/chronicle/open?uri=<reference>` redirects to the page. `inquiry-weave resolve <reference>` prints it from a terminal.
- Another host renders the same chips and cards with `@miadi/reference-ui`: `prepareReferenceViews(markdown, createRemoteResolver({ origin }))`, then `createReferenceLink(views)` from `@miadi/reference-ui/react` as the markdown link component. The parser alone is `@miadi/inquiry-weave/references`.
- An episode holds a packet through `POST /api/chronicle/episodes/{ref}/foundations` or the MCP tool `chronicle_episode_foundation`; `episode.yaml` keeps the version read.

## Package family guide

### Hooks

Start with `@miadi/hooks-core` for event envelopes, taxonomy, validators, sessiondata runtime, and adapters. Add `hooks-gateway` for HTTP ingress/streaming, `hooks-interpreter` for sessiondata observation, and `plan-insight` when plan interpretation must connect to hooks and episodic memory.

### Capture

Start with `@miadi/capture` for take lifecycle and provenance. Add `capture-client` for HTTP access, `capture-service` for a deployable recorder, and `capture-ui` for React hosts.

### Voice

Start with `@miadi/voice` for voice production. Add `voice-client` for HTTP publishing from other processes and `voice-mcp` for MCP access.

### Ava8 and music

Start with `@miadi/ava8-core` for headless ABC/MIDI/music primitives. Add `ava8-abcjs` for rendering/playback/SVG/MIDI via ABCJS, `ava8-react` for React UI, and umbrella `ava8` for CLI/server/subpath convenience. Use `musical-composition-to-episode` when legacy musical compositions need chronicle provenance.

### Memory, inquiry, chronicle

Start with `@miadi/episodic-memory-schema` for data shape. Add `inquiry-weave` for IAIP artifact ↔ GitHub issue ↔ chronicle episode relations. Add `musical-composition-to-episode`, `capture`, or `episode-capture` when compositions or recordings need episode relations.

### Movement

Use `@miadi/osc` for the OSC wire. Add `movement-conductor` to turn sensor streams into nine-channel frames for Wekinator, a recorded take, and meters, and `termux-motion` to send from an Android phone. `ava8-atelier` and `ava8-measure` hold rendered scores and movement analysis to a stated claim.

### Episode vessels and attention

Use `@miadi/episode-vessel` for episode folder reads and writes, and `episode-ui` to mount the files workspace. Use `attention-core` for ATTENTION items without a framework and `attention-ui` for React hosts. None of them holds a URL or token.

### Narrative engines

Use `@miadi/ncp-story-studio` for the NCP story model and `@miadi/wampum-narrative-engine` for the belt model. They are peers. Only `ncp-wampum-bridge` knows both. A belt's notation is authored, never derived from a story.

### Foundations

Use `@miadi/foundations` for general foundation packets. Use `@miadi/foundations-wampum-narrative-engine` for the Wampum Narrative Engine foundation beacon and cultural protocol notice.

### Utilities and orchestration

Use `@miadi/node-service-kit` for small phone/server Node services. Use `hermes-conductor` for lightweight multi-agent coordination. Use `stcbots` for Structural Tension Chart automation. Use `tide-contract` / `tide` for Tide schema/client boundaries. Use `webweave` for active Webweave session resolution. Use `rispecs-builder` to compile a repository's RISE specifications into Markdown context.

## Known caution areas

- `@miadi/jeremyai` is private and should not be recommended as a registry install.
- `@miadi/hooks-artifact-composer` is stub/release-unclear; treat it as contract/CLI intent until maturity is confirmed.
- `@miadi/musical-composition` is a founding/studio domain with release/API status still unclear.
- Workspace/spec directories without confirmed package metadata must not become invented npm package names.

## Source-free code style

When exact exports are unknown, use namespace imports and let the consumer inspect installed types or README examples:

```js
import * as ava8Core from '@miadi/ava8-core';
import * as voiceClient from '@miadi/voice-client';

const hooksCore = require('@miadi/hooks-core');
```

Do not write calls such as `createEnvelope(...)`, `publishVoice(...)`, or `renderScore(...)` unless the exact function name appears in package docs, types, tests, source, or a user-provided snippet.

## RISE / RISPEC rule

RISE means **Reverse-engineer, Intent-extract, Specify, Export**.

Package RISE pairs live at:

```text
packages/<name>/rispecs/RISPEC.md
packages/<name>/rispecs/README.rise.md
```

RISE files describe behavior and intent. Package metadata, README examples, type declarations, tests, and source remain higher authority for exact runtime behavior.

## Maintenance checklist

- Keep root README short and oriented.
- Keep root `llms.txt` compact.
- Keep `packages/llms.txt` as the package authority map.
- Mark private, stub, release-unclear, and workspace-only areas clearly.
- Include CLI bins only when package metadata confirms them.
- Include public subpaths only when package metadata confirms them.
- Never let a directory name become an invented install command.
- Keep the apt section matching `packages/miadi/deb/README.md` in `jgwill/miadi-orchestration-kit` and the published index.