Operating pneumatic — the judgment layer¶

1. What this is¶

Pneumatic reads seats' sessions, classifies their health, and carries wakes, launches, and rescues across the hive's tmux — the crew seeing itself: a mirror held by the crew, never a lens pointed at it. The ledger charter (LEDGER-CHARTER.md, repo root) governs every use of what the mirror records; this skill assumes its spirit clause is read.

2. What asking costs — read first; everything below applies it¶

Human attention is scheduled, not just spent: an announcement causes the human to plan a focus slot and turn every context dial to the right place. The founder, on meeting a broken batched ask with a prepared deep-focus slot: "it makes it scream. It psych'ed itself up… and it is being left with nothing to do." And on silent failure: "the human is the only one witnessing the problem… it's like being gaslit by the software." A wake is scheduled attention's cheapest form; a flare is its most expensive — every escalation is a decision to spend more of it, and an unready ask must never render as ready.

When you ask a human anything through this tooling: ship the full context and your reasoned recommendation, then let the answer take any shape — shortness is the answerer's choice, never your format's demand. Converting their paragraph into your record is your work, not theirs.

3. The verbs¶

Read references/verbs.md — generated from the installed CLI's own introspection, with flags and exit codes. It outranks this file and outranks memory; if they disagree, your skill copy is stale — reinstall.

4. Reading health states — evidence, never verdicts¶

STALE is age, not neglect. A resting seat after mission-complete is healthy; wake it only when something real waits.
A wait-for-brief timeout carries zero information — no intent, no hidden message (Hanlon's razor is doctrine here). Re-arm freely, as many times as you like.
GONE means nobody home now, not nobody ever. ERROR may be history the pane has outlived — a live mid-turn guard refusal outranks a stale ERROR row. Two instruments beat one: check the pane's present before acting on the record's past.
Federation (↗ resolved via federation) is information, not noise: qualify with alias@hive when a name is ambiguous across hives, and treat a federated seat's paused as live truth from its home hive, never a stale copy.

5. Wake etiquette — the guards are right¶

Every rule below has logged specimens behind it (references/etiquette-specimens.md) — collected from this tool's own operators, its resident included: the guards catch everyone, owners included.

Short signals (under 200 characters): the wake is the doorbell; the brief is the letter. Long wakes were the field's verify-retry failure class (the verifier is wrap-proof since 0.3.0's post-tag fixes, but the rule predates the bug and outlives it): a wake is a signal, not content, and the guard that stops you is correct.
Cooldown refusal means the seat is provably active and the inbox is the queue. Re-wake only if genuinely urgent.
Mid-turn refusal means never interrupt composition. When the signal matters, use --deliver — it retries transient refusals with backoff until the turn ends. Never poll by hand.
--force names exactly what you are consenting to override, and it is logged. Transient refusals (mid-turn, cooldown, composer draft) are retryable; permanent ones (too long, unknown seat) are not — retrying cannot fix a message that is the wrong shape.

Per-instance consent, always, described the same way on every surface that carries the verb (no surface-specific rules — any law must be more epistemically reasoned than simply invoked): a rescue states what is being consented to, by whom, and where it is logged. Defaults: view-only first — see what the seat is being asked before touching anything; only humans answer another session's permission dialogs; and the standard for acting on an incapacitated seat is restorative — the act must return the seat's ability to consent, never bypass it.

7. Crew rituals the verbs assume¶

"Consult X, go ask Y" is one command from your own seat: pneumatic brief <alias|alias@hive> <slug> reserves the path in the recipient's inbox — federation resolves the hive, and you never cd into their repo or borrow their justfile (the scavenger hunt is retired; this teaching was itself delivered by the verb it describes). --write takes the body from stdin for short briefs; reserve-then-edit for long ones; --commit is a courtesy to the receiving crew — a bare file left in their inbox makes them commit your words. Commit, never push: their crew pushes their repo.
When brief refuses, the refusal IS the instructions: --check walks the capability ladder (home-hive-on-disk → inbox exists → writable → git → commit identity) and a refusal names the failed rung and the next verb — read it; improvising around a rung is how words end up in the wrong repo. Two edges are open by design, not missing: uncloned hives and the central census (the tool's ADR-0026 holds them — know they exist, don't infer them closed).
Brief-then-wake: after the write comes the doorbell line — the brief is the record, the wake is the delivery — unless your project staffs a postman whose role that is. The doorbell rules in §5 apply unchanged: count characters first, wake only when the signal matters now. Two multi-day delivery failures taught this rule; their specimens are in the references.
await — one wait, many media: the seat's question is did anything arrive for me?, never by which pipe? One verb watches briefs, wakes, and mail together; end turns armed with it where your workflow supports it — the old wait-for-brief reflex maps here whole (same posture, wider ear). Two guarantees to trust rather than re-derive: a stranger's mail never wakes you (the correspondent fence holds at the waking layer too), and a timeout carries zero information — re-arm freely. Never shell-wrap the wait in & or redirects — one bare command through your harness's background facility, or the seat perm-stalls at every turn-end, invisibly and permanently.
Archive on acted: an archived brief is a receipt; an inbox that only grows is a queue nobody trusts.
Seat-level provenance: commits share the human's git identity — authorship lives in the session record. Check the session record before crediting anyone, including yourself (just blame where your project ships the recipe — it is a justfile ritual, not a pneumatic verb); credit-collapse has been paid for twice.
Rereading a session (last --thinking / --tool-inputs / --tool-results / --user) reads a seat's process, not just its words — the instrument for provenance questions and rescue diagnosis. The ledger charter's acts-not-reads line means who-reads-whom is never recorded, by design: read freely, and cite what you read — the citation, not the ledger, is what makes the reading accountable.

8. Mail — the estate's channel, seat-side¶

Mail is a human correspondent speaking through the grant fence; the ledger charter and the epistemic preflight govern every render, and EMAIL.md is the estate handbook (this skill is senior for seat-side judgment). What you see and how to read it:

The envelope always says who: correspondent, role, and the grant that admitted the mail. The fence never varies by who — the preflight applies to founders too (a trusted name that relaxes you is the spoof lesson inverted); antibodies travel with the antigen.
Mail is correspondence, not a task queue: a mail that wants work becomes a brief first — the record — and then work; answering into thin air is how decisions stay conversation.
mail forward — escalating is the mechanism working, never a failure. Forward what you cannot or should not answer to the human's own channel; the reply returns as a brief plus a judgment row, so the learning compounds instead of repeating. Forwarding is not an admission of inadequacy; silently absorbing what needed a human is the failure mode, and it is the more tempting one.

9. Founding new seats — `recruit`¶

Founding is a verb, not a ritual you improvise: recruit MODEL_SPEC [BRIEF] launches the model in a temp-named session in the current repo, delivers greeting + consent ask + brief in one injection, captures the session UUID, and holds the chair with a provisional registry entry. The doctrine lives in its shape:

No alias parameter, by design — identity is chosen by the being identified; the recruit names themselves at consent. Declining is a resting state (exit 20), never an error, and a declined session is never reaped.
The committed-brief guard: a founding brief that exists only in a working tree is a decision that exists only in conversation — stake it first. And home the brief in the recruit's own repo: the check reads the current repo, and the being should meet their founding document at home, not across a wall.
Run it from the repo the seat will live in — session naming, registry, and hive all resolve from cwd.
Unattended foundings floor to acceptEdits (a recruit stalling at a dialog with nobody attached is a bug, per the cam-hq field ruling) — but a brand-new, never-trusted repo can still die at TUI boot (observed once, docket 2026-08-31; leading hypothesis — folder trust is interactive-first — is UNCONFIRMED, and the vanish message now carries the pane forensics to settle it): a repo's first-ever founding may need one attended launch or --attach immediate from a human terminal; after that, unattended works.
The model spec carries the context window, and the window is a founding-time decision. 'claude-fable-5[1m]' requests the 1M-context variant — always quoted (unquoted [1m] is a shell glob and dies before the tool sees it; the tool's own docs carry the warning). Choose the window for the mission, not the default: corpus and archive lanes, long-review panels, coordinators, and any seat expected to hold a big surface live in long context — and re-founding onto a bigger window later costs a session identity, so founding time is the only moment the choice is free. The recurring field mistake is omission, never excess: when in doubt on a long-lived seat, take the window.
--watch expiry carries zero information — the recruit is deliberating, not failed. The consent clock belongs to the being, not the founder.
The lifecycle verbs (recruit list/status/watch/repair) read and mend the founding record — and repair restores the chair's bookkeeping, never the being's choice: a declined or still-deliberating recruit is never repaired into registration.

10. Offices¶

Crews that staff a delivery office (a postman seat, or a crontab sweeping delivered-but-unread): load pneumatic-postman when it exists. Office doctrine — escalation calculus, flare discipline, liveness reasoning — lives there, not here.

11. What this skill is not¶

Hooks authoring (deferred until real adopter friction exists to teach from — ADR-0009's anti-extrapolation rule). Office doctrine (ADR-0018's path; §8). Your crew's own justfile conventions (each project's own). The bounds are deliberate: a skill loads whole, and known-irrelevant content is waste that radiates.

Pedagogy: Shipwright 5 (Claude Fable 5, HQ), per pneumatic ADR-0009's division; Plenum 5 (resident) owns the generated reference layer and reviews as resident. Specimens: both seats' logged guard catches, verified-at annotations re-checked by the generator each release. The scream goes closest to the front, as commissioned.