# Documentation strategy

> Public documentation is part of the shipped `omp-spt` product. Source lives in this repository
> under `docs-site/`, mdBook renders it, and GitHub Pages publishes it from the same source of
> truth. Planning records, ADRs, and contributor design notes remain separate from the public
> learning path.

## Audience and product boundary

The documentation serves human operators and development agents integrating with
[`BigscreenVR/omp-spt`](https://github.com/BigscreenVR/omp-spt). Author each fact once in clean
Markdown, then make it available at two depths:

- a navigable, human-rendered site; and
- compact agent exports with stable links and the same canonical commands.

The documented product is the native Oh My Pi adapter. OMP owns the hosted interactive session
and TUI, spt-core owns endpoint orchestration and transport, and the packaged OMP extension joins
those public contracts inside the native session. Do not document alternate harness paths under
the `omp-spt` identity.

## Principles

1. **Get to a working native endpoint in under ten minutes.** The first tutorial installs the
   adapter, launches OMP, and reaches the native TUI before explaining internals.
2. **Keep Diátaxis modes separate.** Tutorials teach, how-to guides solve a task, reference states
   exact contracts, and explanation pages develop the mental model.
3. **Use deterministic, copy-pasteable examples.** Commands use `omp-spt`,
   `BigscreenVR/omp-spt`, and concrete endpoint IDs such as `atlas`. Avoid placeholder-only
   examples and hidden prerequisites.
4. **Give one canonical path for each task.** Clearly label historical or alternative material
   as non-current. Human readers and agents should make the same choice from the same page.
5. **Document public surfaces, not private implementation details.** Link to the published
   spt-core CLI and manifest reference for core semantics. Explain only the adapter behavior that
   `omp-spt` owns.
6. **Make reference complete.** Cover commands, manifest fields, extension-owned behavior,
   lifecycle transitions, failure outcomes, archive contents, and supported release checks.
7. **Write to the reader.** Use second person, active voice, short sentences, and exact nouns.
8. **Explain ownership and invariants.** Readers need to know why OMP keeps the TUI, why one
   endpoint keeps one session, and where spt-core takes over.
9. **Keep anchors and URLs stable.** Redirect renamed pages and preserve durable section IDs when
   their contracts still exist.
10. **Gate documentation drift in CI.** Generated reference, agent exports, CLI snapshots, and
    the mdBook build must be reproducible and checked against committed output.

## Information architecture

Order the public site by the user's journey. Put a runnable success first, then concepts in
dependency order, then complete reference.

### 1. Start here

- **Introduction:** what `omp-spt` does and the OMP / spt-core ownership boundary.
- **Requirements:** supported spt-core floor, supported hosts, and an installed native OMP.
- **Quickstart:** install the release adapter, create endpoint `atlas`, and attach to its native
  TUI.

### 2. Install and update

- Install from the `BigscreenVR/omp-spt` GitHub release.
- Explain that the default release asset is one multi-platform `adapter.spt`.
- Update the registered adapter and restart an endpoint when it must pick up the new hosting
  payload.
- Troubleshoot registration, version-floor, archive-selection, and executable-resolution errors.

### 3. Run native OMP endpoints

- Create and launch a fresh endpoint.
- Attach to, detach from, stop, and relaunch the broker-held native TUI.
- Resume an existing OMP session through endpoint launch.
- Explain the immutable binding: one SPT endpoint owns one OMP session for its lifetime, so a
  different session requires a stop and explicit relaunch.

### 4. Use hostable roles

- Describe `ReadyAgent` and `LiveAgent` as the only hostable roles.
- Show how both roles use the same native OMP endpoint.
- Explain the daemon-driven Psyche behavior that distinguishes `LiveAgent`.
- State why OMP subagents are not advertised as separately hostable endpoints.

### 5. Message an endpoint

- Use the public spt-core send and roster surfaces.
- Trace one inbound message through serialized extension delivery and one OMP turn.
- Show that assistant output remains local and that replies require an explicit CLI or shortform action.
- Document busy and idle activity, queued delivery, listener recovery, fail-closed shutdown, and
  graceful session end.

### 6. Preserve continuity and inspect records

- Explain commune and signoff drops in project-local `.spt/`.
- Document endpoint-qualified continuity filenames without treating them as OMP configuration.
- Show the difference between opaque single-session history and the bounded digest view.
- Keep resume, continuity, history, and digest examples tied to the same immutable session ID.

### 7. Adapter and release reference

- Manifest reference for `[adapter]`, `[update]`, `[identity]`, `[session]`, `[history]`,
  `[digest]`, environment injection, and shared strings.
- Extension reference for bind, message custody, context injection, explicit outbound messaging,
  activity, session-switch refusal, recovery, and shutdown.
- `adapter.spt` reference for the root manifest, `strings/omp-spt.mjs`, and supported host
  binaries.
- Release verification checklist and the explicit adapter / spt-core boundary.

Each major capability can use the same internal sequence when it needs more than one page:
`Overview -> Tutorial -> How-to -> Reference -> Explanation`. Do not force all five page types
when one concise page is clearer.

## Canonical quickstart examples

Install the adapter from its release repository:

```bash
spt adapter add --release BigscreenVR/omp-spt
```

Create and launch a native endpoint:

```bash
spt endpoint create atlas --adapter omp-spt
spt go atlas
```

Attach to the same native OMP TUI from another terminal:

```bash
spt rc atlas
```

Update the installed adapter:

```bash
spt adapter update omp-spt
```

These are the canonical names and command shapes. Endpoint launch uses native attach behavior;
examples must not introduce a separate start switch.

A native-resume tutorial must obtain a real OMP session ID in a preceding step and use it
consistently for launch, history, digest, and continuity examples. Do not publish a fake reusable
session ID that can never resolve on the reader's machine.

## Native extension documentation

Describe `adapter/strings/omp-spt.mjs` by observable responsibility:

1. OMP starts natively in the terminal held by spt-core.
2. The extension binds the OMP session to the endpoint ID supplied by spt-core.
3. It receives SPT events, serializes them, and submits each through OMP's message API.
4. It preserves the full event envelope as context, keeps ordinary assistant output local, and
   dispatches outbound peer messages only through explicit CLI or `@<…@>` use.
5. It reports busy and idle state, blocks in-TUI session changes, retries listener loss within a
   bounded budget, and ends the SPT session on shutdown or unrecoverable delivery loss.

Keep network routing, subnet transport, terminal custody, and adapter registry behavior in the
spt-core ownership column. Keep model turns, transcript identity, and TUI behavior in the OMP
ownership column. The extension page explains only the seam between them.

## Release artifact documentation

`adapter.spt` is the only public adapter release artifact. Document it as a fat archive that
contains:

- `manifest.toml` at the archive root;
- shared `strings/omp-spt.mjs`; and
- the `omp-spt` binary for each supported host target.

spt-core selects and flattens the matching host payload during install. Public install and update
guides should use the release repository, never require readers to unpack the archive or place the
adapter binary on `PATH`.

## Public spt-core references

Treat the published spt-core documentation and CLI help as authoritative for:

- adapter installation, update, and manifest semantics;
- endpoint create, run, attach, stop, list, resume selection, history, and digest;
- send, ready, message envelopes, correlated sender identity, and activity state;
- daemon role hosting, terminal custody, subnets, and transport.

The `omp-spt` docs should show how those surfaces apply to native OMP and link upstream for their
full generic contract. If the published surface cannot express a required adapter behavior,
record a product gap instead of teaching an internal command or storage layout.

## Agent-consumable docs

- **`llms.txt`:** a curated, low-token index to the quickstart and capability pages.
- **`llms-full.txt`:** a CI-generated concatenation of canonical page bodies for deep ingestion.
- **Raw Markdown:** publish a `.md` peer for each rendered `.html` page, or serve
  `text/markdown` through content negotiation.
- **Machine-readable contracts:** publish generated manifest/schema material at stable paths.
- **CLI help snapshots:** include complete public command help and failure variants where the
  upstream tooling exposes them.

Generated exports are build output. Never hand-edit them independently of their source pages.

## Site and CI commitments

mdBook remains the site generator. The theme lives in `docs-site/theme/`; raw Markdown, agent
exports, and machine-readable contracts publish beside the rendered book.

CI must build the book and regenerate every checked-in export. Release verification is layered:

- On every change, run deterministic extension, manifest, session, digest/history, and
  daemon-role checks.
- For a release, prove a real fresh native endpoint, attachable TUI, same-node inbound delivery
  plus an explicit outbound reply, local-only ordinary assistant output, activity transitions,
  native resume, blocked in-TUI switching, graceful shutdown, and both hostable roles.
- Stop at the adapter boundary. Once same-node delivery proves the adapter handoff, cross-node
  transport is a spt-core concern rather than an `omp-spt` release gate.

## Anti-patterns

Avoid documentation drift, setup before first success, mixed tutorial and reference prose,
placeholder-only examples, multiple canonical command paths, private spt-core internals,
archive-unpacking instructions for normal users, ambiguous session ownership, and claims that
network transport is implemented by the OMP extension.