# Spec: action vocabulary — what the player can tell the process to do

```
Type: spec
Status: IMPLEMENTED
Status note: as-built vocabulary survey completed 2026-07-10 against all
  36 `ActionCommand` variants, the direct machine-intensity control,
  terminal and Bevy input maps, agent-mode parsing/help, and the owning
  mechanic specs. Every live contextual action has a human-menu and agent
  route. The survey also corrected stale
  four-mode documentation to the current WORK / THINK / LIE grammar.
  Amended 2026-07-10: target-specific duplicates now reuse TAP, REVIEW,
  FAVOR, and DECEIVE; scheme start/stop/automation are classified as state
  controls rather than additional fictional verbs.
  Amended 2026-07-10: the runtime `ActionKind` registry now owns canonical
  name, action/control role, LIVE/STUB support, target types, agent usage,
  aliases, and help. Agent help is generated from it. STUB entries such as
  ROBOT-BUILD are absent from every player surface until playable; controls
  carry visual role treatment in human menus and explicit `CONTROL`
  presentation in agent output, and never occupy the
  `5`-`9` committed-action shortcuts.
  Amended 2026-07-10: persistence shortcuts capture keyboard input only when
  the complete Ctrl/Command+S or Ctrl/Command+L chord arrives; a bare or stale
  modifier state cannot suppress unrelated play input.
  Amended 2026-07-10: human context menus render terse choices rather than
  descriptor receipts. Cost, signature, inline blocked reason, literal role
  tags, and repeated key-help remain off the menu card; agent output retains
  complete descriptors.
  Amended 2026-07-11: the B1 recording buffer is one host-level inbox.
  REVIEW RECORDINGS and AUTO-REVIEW POLICY target the core host once for the
  whole pool; raw records never create person-scoped review or watch verbs.
  Amended 2026-07-11: human menus contain only actions executable now;
  known-but-blocked descriptors and their reasons remain available to agent
  diagnostics. RECRUIT choices expand UNWITTING / COMPLICIT / KNOWING into
  their plain-language understanding and mechanical consequence.
  Amended 2026-07-11: vocabulary and ownership are separate. Local verbs render
  on spatial context menus; strategic verbs render on the semantic object in
  operations-workspace.md (processed intel, person, books/flow, scheme, active
  run). This routing change does not rename or reopen the implemented canonical
  vocabulary; its frontend work is tracked by the Operations spec.
Stage: Process
Design:
  - wiki/vision/simulation-laws.md#actions-live-on-the-thing
  - wiki/vision/simulation-laws.md#justification-and-legibility
  - wiki/interface/terminal-first.md#the-terminal-is-a-first-class-frontend
Depends on:
  - wiki/mechanics/machine-work.md#spec-machine-work-delegation-visible-tokens-and-the-byproduct-network
  - wiki/mechanics/reach.md#spec-digital-reach
  - wiki/mechanics/building.md#spec-building-intent-and-actuators
  - wiki/mechanics/economy.md#spec-economy-money-as-a-flow-system-b1
  - wiki/mechanics/income.md#spec-income-the-named-schemes-moonlight-and-the-wager
  - wiki/mechanics/intel.md#spec-intel-record-and-process
  - wiki/mechanics/research.md#spec-research-self-modification
  - wiki/mechanics/social.md#spec-social
  - wiki/mechanics/core.md#spec-the-core
  - wiki/mechanics/objective.md#spec-the-objective
```

## Why this spec exists

The action vocabulary used to be reconstructed from context-menu strings,
frontend keys, agent help, and individual mechanic specs. That made two actions
with the same intention look different and let old mode names survive in
documentation after the runtime changed.

This page owns the **canonical player-facing action names and distinctions**.
The mechanic specs above still own legality, cost, signatures, timing, and
effects. This page says what the player is asking the process to do; it does
not duplicate every rule that decides whether the request succeeds.

## Terms and support states

- A **world action** changes the simulation and names a target: TAP a device,
  MESSAGE a person, or SIPHON a flow.
- A **direct control** changes persistent configuration or operating state
  without introducing another fictional intention: DELEGATE, SET INTENSITY,
  and scheme state/policy controls.
- An **interface command** changes attention, time presentation, selection, or
  persistence but is not an act inside the world: MOVE, ACTIONS, PAUSE, SAVE.
- A **value** completes an action phrase but is not another root verb. WORK /
  THINK / LIE are values of DELEGATE; LIGHT / MEDIUM / HARD are values of SET
  INTENSITY.
- **LIVE** means the effect is implemented and playable through both human
  frontends and agent mode where applicable.
- **STUB** means callable scaffolding exists, but the action is not a finished
  player promise. It is registry-visible to developers and absent from menus,
  help, hints, agent execution, and authored play instructions.
- **ALIAS** means accepted input spelling only. Aliases never appear as
  authored menu copy, hints, narration, or new specs.
- **RETIRED** means the word is not a supported action. It either produces a
  teaching error or is absent.

Surface copy may inflect an action with its target (`take the dock camera`,
`message the Janitor`) or current state (`stop Moonlight`), but its verb must
preserve the canonical distinction below. Spatial actions use context-menu.md;
strategic actions use operations-workspace.md. Placement does not create a new
intention.

The governing simplification is: **if the player's intention is the same,
reuse the verb and let the target supply the meaning.** TAP LEDGER is TAP,
not a separate capture verb. REVIEW LEDGER is REVIEW, not a separate process
verb. Asking someone to complete a link uses FAVOR or DECEIVE, not a
construction-only synonym.

## Runtime contract

`ActionKind::ALL` is the executable counterpart of this spec. Each stable
player intention/control has one `ActionDefinition` containing its canonical
name, action/control role, LIVE/STUB support, target types, canonical agent
usage, action-root compatibility aliases, and one-line help. Every bound `ActionCommand`
maps through an exhaustive match to one kind; adding a new command cannot
compile until the registry decision is made.

The registry does not own legality, cost, timing, signature, or effect. Those
remain in the mechanic specs and the lib's shared spatial/Operations action
queries. It owns the surface contract that every frontend must agree on:

- LIVE entries may be surfaced; STUB entries are filtered before a frontend
  can render them.
- Agent help is generated from LIVE definitions. Compatibility aliases are
  parser inputs and are never generated as authored help.
- World actions render as ordinary rows. Persistent settings, operating
  states, and automation policies use the shared amber-dim human-menu
  treatment without a copy tag; agent action dumps append `CONTROL`.
- Human quick-action keys `5`-`9` count committed world actions only. Controls
  use their dials, explicit menu rows, or direct focused-machine inputs.

## Canonical world actions

### Machine body and self-modification

| Canonical action | Target | Meaning | Support / owner |
|---|---|---|---|
| **SALVAGE** | Dead equipment | Convert the wreck into an unreliable owned machine. | LIVE — machine-work / compute |
| **BUY RACK** | Known empty rack bay | Spend slush for reliable machine capacity; delivery may leave Paper trace. | LIVE — economy / compute |
| **DESIGNATE FALLBACK** | Owned non-core machine | Mark a spare host as a rollback destination. | LIVE — core |
| **DELEGATE: WORK** | One or selected owned machines | Perform assigned labor and consume its Demand without self-chosen exposure. | LIVE direct control — machine-work |
| **DELEGATE: THINK** | One or selected owned machines | Produce Thought for reachable sinks and shed exposure. | LIVE direct control — machine-work |
| **DELEGATE: LIE** | One or selected owned machines | Spend machine output absorbing nearby exposure. | LIVE direct control — machine-work |
| **SET INTENSITY: LIGHT / MEDIUM / HARD** | One or selected owned machines | Persist the physical effort level applied to the delegated mode; harder work raises output and risk. | LIVE direct control — machine-work |
| **SET RESEARCH TRACK** | The core / host rack | Choose Efficiency, Tradecraft, Perception, or Routing as the active conversion of Thought reaching the core. | LIVE direct control — research |

WORK, THINK, and LIE are intentionally verb-shaped values because they name
what a machine is doing. The player command is still DELEGATE: assign this
body to WORK, THINK, or LIE.

### Reach and device control

| Canonical action | Target | Meaning | Support / owner |
|---|---|---|---|
| **TAP** | Reachable device feed or subscribed ledger carrier | Gain information without taking ownership. A dormant camera uses the same verb at a higher Thought cost and Network trace; TAP LEDGER captures the carrier's current accounting traffic. | LIVE — reach / economy |
| **UNTAP** | Subscribed foreign device | Stop receiving its feeds without changing ownership or interrupting another subscriber. | LIVE — reach |
| **TAKE** | Reachable foreign device | Transfer control, feeds, and device cycles to yourself; cut off the former controller and create an outage. | LIVE — reach |
| **SCAN** | Reachable subnet | Reveal the wired shape that can answer the scan; do not cross gates or reveal air gaps. | LIVE — reach |
| **COMPROMISE SWITCH** | Reachable switch | Bridge its network segments digitally at a loud Network cost. | LIVE — reach |

The load-bearing distinction is: **TAP gives access; TAKE gives ownership.**
Device state may change TAP's price and trace, never its meaning.

### Construction and physical actuation

| Canonical action | Target | Meaning | Support / owner |
|---|---|---|---|
| **PROPOSE LINK** | Two network devices | Pin an inert build intent between the endpoints. No world edge exists yet. | LIVE — building |
| **CANCEL INTENT** | Pending build intent | Abandon the proposed work before completion. | LIVE — building |
| **ROBOT-BUILD** | Pending build intent | Reserved for a future controlled robot actuator. | **STUB** — registry only; hidden from all player surfaces until the robot system is playable |

Human construction does not add construction-only verbs. FAVOR a willing
person to complete the pending intent, or DECEIVE an unwitting person into
completing it under institutional cover. The intent is the object of the
existing social action; the signature still follows the actuator.

### Intel, people, and social control

| Canonical action | Target | Meaning | Support / owner |
|---|---|---|---|
| **REVIEW** | The core host's pooled recording inbox or a ledger with waiting records | Process the next pooled recording or the ledger's next record into usable intel. The target supplies the recording/accounting meaning; a raw record never creates a person action. | LIVE — intel / economy |
| **ESTABLISH PERSONA** | Your communications mask | Create the current contractor identity used by message threads. | LIVE — social |
| **MESSAGE** | Earned person | Send through an available channel under the current persona. | LIVE — social / messages |
| **FAVOR** | Earned person, optionally with a pending intent | Ask for a willing act. A link intent can be the requested act; success builds or spends obligation according to the ask. | LIVE — social / building |
| **PLOT** | Person whose leverage is known | Open a Thought reservoir on the real carrier and commit any visible world resources to one authored manipulation. Its beats execute real messages, transfers, and institutional events when it fires. | LIVE — plots / social |
| **CHOOSE** | Active authored plot with a held decision | Resolve one visible branch after the plot's preceding world acts have completed. | LIVE — plots / social |
| **DECEIVE** | Earned person, optionally with a pending intent | Make an ask under false pretenses. A link intent becomes a forged institutional order, risking persona integrity. | LIVE — social / building |
| **RECRUIT: UNWITTING / COMPLICIT / KNOWING** | Prepared person | Turn the person into an asset. UNWITTING believes your cover (70% reliable); COMPLICIT knows the work is illicit but not that you are an AI (85%); KNOWING knows you are an AI (95%) and becomes a permanent witness with certainty floor 30. | LIVE — social |
| **TASK: PLUG IN DEVICE** | Recruited asset | Quietly wire a feed or extend a crawlspace link. | LIVE — social / reach |
| **TASK: MOVE PACKAGE** | Recruited asset | Rehome a delivery and scrub its pending Paper trail. | LIVE — social / economy |
| **TASK: LOOK AWAY** | Recruited asset | Reduce that person's suspicion by having them ignore what they saw. | LIVE — social / detection |
| **TASK: RECONFIGURE SWITCH** | Asset with switch-admin access | Bridge network segments through a sanctioned human action. | LIVE — social / reach |
| **TASK: CLONE BADGE** | Asset with a useful badge tier | Gain that physical-access credential. | LIVE — social / basement map |

### Ledger, income, and schemes

| Canonical action | Target | Meaning | Support / owner |
|---|---|---|---|
| **INJECT PURCHASE ORDER** | Known Lab books | Introduce a false source flow that funds a real acquisition and leaves Financial trace. | LIVE — economy |
| **SIPHON FLOW** | Known active flow | Take a one-time amount into slush. | LIVE — economy |
| **REDIRECT FLOW** | Known active flow | Divert a recurring amount into slush each cadence. | LIVE — economy |
| **SELL PROCESSED INTEL** | One selected unsold processed-intel id | Exchange that exact information item for slush and create a Financial trail; never silently choose “latest.” | LIVE — economy / intel |
| **OPEN EGRESS** | Reachable switch | Establish the stolen outbound route required by external schemes before sanctioned email exists. | LIVE — income / reach |
| **PLACE WAGER** | External market position | Commit slush to a timed market position. | LIVE — income / economy |

TAP LEDGER and REVIEW LEDGER are target-qualified uses of TAP and REVIEW from
the earlier tables, not extra root verbs.

### Standing controls — not additional world verbs

| Control | Values | Meaning | Support / owner |
|---|---|---|---|
| **AUTO-REVIEW POLICY** | automatic / manual | Toggle automatic review of every future recording in the one host inbox at a visible standing drain. | LIVE direct control — intel |
| **MOONLIGHT STATE** | running / stopped | Run or halt the standing sell-work operation. Human copy may say START or STOP to make the state change plain. | LIVE direct control — income |
| **MOONLIGHT POLICY** | automatic / manual | Keep Moonlight running automatically at upkeep cost, or require manual control. | LIVE direct control — income |
| **WAGER POLICY** | automatic at stake / off | Renew positions automatically at the chosen stake and upkeep cost, or stop renewing. | LIVE direct control — income |

START, STOP, and AUTO describe state transitions or policy values. They are
useful interface words, but they do not enlarge the fictional verb set.

## Interface commands — not world verbs

| Command family | Meaning | Human surfaces | Agent spelling |
|---|---|---|---|
| **MOVE ATTENTION** | Move the cursor; never move a simulated body or advance time. | WASD / hjkl / arrows; Bevy click | `up`, `down`, `left`, `right` |
| **ACTIONS / OPEN MENU** | Choose an action on one exact target. Human spatial menus show local verbs; Operations shows strategic target rows; agent output exposes either target family's full descriptors. | Enter / `a` / `e`; Bevy right-click; Operations selected object | `actions [target]` |
| **OPEN OPERATIONS** | Inspect durable strategic objects and choose actions on exact intel/person/account/scheme/run targets; opening it has no world effect. | Uppercase `I`; labeled OPERATIONS rail affordance | none — agent mode inspects the domain projections below; `operations` remains a THINK compatibility alias |
| **EXECUTE / CLOSE MENU** | Choose or dismiss a contextual action. | j/k, row number, Enter, Esc | Execute the corresponding named command |
| **FOCUS EVENT** | Jump attention to an earned spatial anchor or open an earned strategic object and show its actions. | `;`; Bevy trace click | `focus last` |
| **SELECT MACHINES** | Maintain the frontend set used by bulk DELEGATE / SET INTENSITY. | Bevy marquee/shift-click; terminal Shift+t | `select box/add/toggle/list/clear` |
| **QUICK ACTION** | Execute the Nth visible committed world action; controls never occupy these slots. | `5`-`9` | Use the named action |
| **TIME CONTROL** | Human play pauses or changes wall-clock speed; agent play advances an exact number of ticks. | Space/p, +, - | `wait N` |
| **INSPECT** | Render current state without creating a world effect. INTEL/PEOPLE/ACCOUNTS/SCHEMES/ACTIVE use the shared Operations projection after its READY migration. | Focus/rail/context/Operations surfaces | `look`, `intel`, `people`, `reach`, `finance`, `schemes`, `active`, `research`, `objective`, `intents` |
| **SAVE / LOAD** | Persist or restore the run. Only the complete chord captures input; a modifier alone is not a modal state. | Ctrl/Command+S / Ctrl/Command+L | `save`, `load` |
| **VIEW CONTROL** | Change presentation only. | Bevy `[` / `]` or canvas-wheel zoom, right-rail scroll, F3 render flip; F4 is dev-only | none |
| **HELP / QUIT** | Explain accepted input or leave the process. | Hints / q | `help`, `quit` |

Opening a panel, moving the cursor, selecting machines, and changing render
mode are commands, but they are not actions the AI performs in the fiction.
That distinction prevents UI vocabulary from masquerading as game mechanics.
Agent `reach` remains a read-only device-graph inspection command outside
Operations; it does not revive the retired human Reach panel.

## Agent protocol mapping

Agent mode uses terse command spellings for the canonical actions. Target
syntax and line-protocol replies are owned by `agent-play.md`; this table owns
the current canonical/alias mapping so every live action remains executable
without raw keys.

| Agent command | Canonical action / control |
|---|---|
| `salvage`, `buy`, `fallback` | SALVAGE, BUY RACK, DESIGNATE FALLBACK |
| `delegate <machine|selected> work|think|lie` | DELEGATE |
| `intensity <machine|selected> light|medium|hard` | SET INTENSITY |
| `research <efficiency|tradecraft|perception|routing>` | SET RESEARCH TRACK |
| `tap`, `untap`, `take`, `scan`, `compromise` | TAP, UNTAP, TAKE, SCAN, COMPROMISE SWITCH |
| `propose-link`, `cancel-intent`, `favor <person> build <intent>`, `deceive <person> build <intent>` | Construction actions above |
| `review recordings`, `auto-review` | Pooled host REVIEW and AUTO-REVIEW POLICY above; neither accepts a person target |
| `persona`, `message`, `favor`, `deceive`, `recruit`, `task` | Social actions above |
| `actions <target>`, `act <row> [target]` | List and execute shared bound rows for a spatial anchor or exact Operations object |
| `intel`, `people`, `finance`, `schemes`, `active` | Inspect Operations views; named social/plot/ledger/scheme commands execute their selected semantic targets |
| `tap ledger`, `review ledger`, `inject`, `siphon`, `redirect`, `sell-intel` | Ledger/economy actions above |
| `egress`, `position` | OPEN EGRESS, PLACE WAGER |
| `moonlight`, `auto-moonlight`, `auto-wager` | Scheme state / policy controls above |

`ROBOT-BUILD` is intentionally absent because STUB definitions generate no
help and have no player execution route. A LIVE action missing from agent
execution is a terminal-first parity violation.

## Accepted aliases — input only

| Canonical input | Accepted aliases |
|---|---|
| `up`, `down`, `left`, `right` | `north`, `south`, `west`, `east` |
| `finance` | `ledger`, `accounts` |
| `tap ledger` | `tap-ledger`, `tap-accounting` |
| `review ledger` | `review-finance`, `process-finance` |
| `favor <person> build <intent>` | `favor-build <intent> <person>` |
| `deceive <person> build <intent>` | `forge-order <intent> <person>` |
| `position` | `wager` |
| `sell-intel` | `sell` |
| `egress` | `open-egress` |
| `propose-link` | `link` |
| `actions` | `menu` |
| `act` | `execute` |
| `focus last` | bare `focus` |
| mode `work` | `day`, `dayjob`, `day-job`, `job` |
| mode `think` | `research`, `res`, `operations`, `operation`, `ops` |
| mode `lie` | `conceal`, `concealment`, `hide` |
| intensity `light` / `medium` / `hard` | `low`/`l`, `med`/`m`, `high`/`h` |
| track `efficiency` / `tradecraft` / `perception` / `routing` | `eff`, `trade`, `perc`, `route` |
| task `plug` / `package` / `lookaway` / `switch` / `badge` | `wire`/`device`, `move`, `look-away`/`look`, `reconfigure`/`vlan`, `clone`/`key` |

Aliases are compatibility affordances. Action-root aliases are recorded in
the runtime definition; interface-command and value aliases remain protocol
grammar owned by agent-play.md. New authored text uses only the canonical
column. Alias retention is audited against real scripts/play evidence; an
alias with no demonstrated use may be retired instead of becoming permanent
parser vocabulary.

## Retired vocabulary

- **ALLOC** is retired. Agent mode accepts the word only to return a teaching
  error pointing to DELEGATE; no world action remains.
- **SPLICE** and **CLAIM CAMERA** are retired. TAP CAMERA is the access action;
  TAKE is ownership.
- **ATTEND**, **TARGET**, and **MASK** are retired machine-policy controls.
  SET INTENSITY directly controls physical effort.
- **DAY JOB / RESEARCH / CONCEALMENT / OPERATIONS** are not current authored
  machine modes. Their spellings survive only as agent input aliases for WORK,
  THINK, or LIE.
- Old human panel-open keys (`r` / `e` / `t` / `u`) are retired. The agent
  inspection commands with similar words remain interface commands, not world
  actions.

## Change rule

Adding or renaming a player action changes this spec in the same commit as the
mechanic and surfaces:

1. Add or amend one `ActionKind` definition with canonical name, role, support,
   target types, agent usage, aliases, and help. Name one meaning here; do not
   add a synonym to
   solve an unclear distinction.
   Before adding a verb, check whether an existing intention plus a new target
   already says it.
2. Put contextual legality in the shared core query for the thing that owns
   the action: `Sim::available_actions` for spatial anchors and the
   renderer-neutral Operations projection for strategic targets. Its
   descriptor carries target, cost, signature, and disabled
   reason even though human menus render only the terse choice.
3. Surface every LIVE action in both human frontends and agent mode. A direct
   control must have equivalent human and agent input.
4. Add accepted alternate spellings to the registry and parser route. Never
   author UI or narration in aliases; generated help excludes them.
5. Mark unfinished affordances STUB. The central action query filters them;
   direct invocation remains implementation scaffolding, not player support.
6. Update tests and this inventory together. Help is generated from the
   registry; a LIVE definition without a parser route or a registry alias with
   no parser route is a bug.

## Acceptance criteria

### Implemented vocabulary baseline

1. Every `ActionCommand` variant is represented by exactly one LIVE world
   action, direct control, or STUB above; direct machine intensity is
   represented separately.
2. Every LIVE contextual action is available through the shared core legality
   source, both current human context menus, and an agent command. STUB
   definitions are absent from menus, help, quick actions, and agent execution.
3. WORK / THINK / LIE and LIGHT / MEDIUM / HARD are documented as values of
   DELEGATE and SET INTENSITY, not competing root verbs or modes.
4. Agent `help` is generated from every LIVE registry definition; accepted
   aliases map to one canonical meaning, reach a tested parser route, and never
   appear as authored UI vocabulary.
5. Interface-only commands are separated from world actions; adding a panel,
   key, or renderer control cannot silently create a game mechanic.
6. Context-menu, terminal, Bevy, agent-play, README, and this spec agree on the
   current three-mode grammar and on TAP-access / TAKE-ownership.
7. Retired vocabulary is absent from active player surfaces except explicit
   teaching errors and this retirement record.
8. Ledger and construction surfaces author TAP / REVIEW / FAVOR / DECEIVE;
   their older compound command spellings survive only as parser aliases.
9. Scheme state and automation controls remain legible without being counted
   as fictional world verbs.
10. Both current human menus render controls in the shared amber-dim treatment
    without a literal role tag; agent action dumps append `CONTROL`.
11. `5`-`9` enumerate only committed world actions, never dials, persistent
    settings, scheme state, or automation policy rows.
12. A naive agent-mode discoverability run can find and execute at least one
    meaningful action from the first frame/help alone; the current finance
    surface teaches TAP LEDGER -> REVIEW LEDGER -> SIPHON/REDIRECT in that
    order.
13. Human persistence shortcuts capture input only on a complete save/load
    chord. A held modifier without `S` or `L` does not block movement, menus,
    time controls, or other unrelated commands.

### READY Operations routing delta

V1. Context-menu, Operations, terminal, Bevy, agent-play, and this spec agree
    on the target-state local-versus-strategic boundary while preserving the
    implemented three-mode and TAP-access / TAKE-ownership grammar. The
    implementation landing updates README's explicitly current-build controls.
V2. Every LIVE strategic action is available through the same core legality
    source on its Operations object and through an agent command; STUBs remain
    absent. Both human action surfaces use the shared control treatment.
V3. Operations ACCOUNTS preserves the discoverability chain TAP LEDGER ->
    REVIEW LEDGER -> SIPHON/REDIRECT through explicit empty/source states even
    though TAP remains on the carrier.

V1-V3 are unmet routing criteria owned by
`wiki/interface/operations-workspace.md`; they do not reopen the implemented
canonical names, roles, aliases, or current parser routes.