# Harness contract

The seam everything third-party builds against. spt-core contains zero
harness-specific logic; a harness (or a driven surface) interfaces through
exactly two things:

1. **The [runtime manifest](manifest.md)** — a declarative TOML file stating
   what varies for this harness: how to spawn sessions, which hook events
   fire which commands, how history is read, how the adapter updates.
   Command templates are opaque strings; spt-core fills `{key}` placeholders
   and runs them.
2. **The [`spt api` surface](api.md)** — the imperative entry points the
   harness's hooks fire to keep spt-core's state honest: session started,
   went idle, hit a context boundary, ended.

That's the whole integration surface. An adapter is a manifest plus the
harness's own native extension points — there is no SDK to link, no daemon to
embed, no protocol to speak beyond running `spt`.

```text
  your harness                         spt-core
 ┌────────────────────┐             ┌──────────────────────────┐
 │ hooks ─────────────┼── api … ───►│ perches · spools ·       │
 │ (SessionStart,     │             │ lifecycle · registry     │
 │  Idle, End, …)     │             │                          │
 │                    │◄────────────┼─ spawns [session.*]      │
 │ sessions           │  templates  │  templates, keys filled  │
 └────────────────────┘             └──────────────────────────┘
          ▲                                      ▲
          └────────── manifest.toml declares both seams
```

## Where to go

- **Start:** [the adapter quickstart](../quickstart/adapter.md) — take the
  reference mock adapter apart and drive the contract in minutes.
- **Build it all:** the [integration checklist](integration-checklist.md) —
  every surface by necessity, mapped to the interaction lifecycle.
- **Reference:** [manifest](manifest.md) · [`spt api`](api.md) ·
  [`manifest.schema.json`](https://sabermage.github.io/spt-releases/manifest.schema.json).
- **Ship it:** [install-on-demand bootstrap](install-on-demand.md) — how an
  adapter brings spt-core with it.
- **Driven surfaces:** [Shells](../shells/overview.md) — the `kind = "shell"`
  flavor of the same contract.

Building adapters, shells, or integrations against this contract is
**unrestricted and royalty-free** — see the
[license split](https://github.com/SaberMage/spt-releases#license).