Spec: the cursor and the senses #

Status: READY
Status note: the decided core (cursor, sight/hearing, blueprint fog,
  inspection) is binding and dispatchable now. Blueprint was promoted
  from proposal to decided 2026-07-06 (criterion 8). Two extensions —
  remembered snapshots, telemetry — remain Proposal [OPEN] below; their
  criteria (P2-P3) activate only if affirmed in the decisions log.
  Sensor ownership (tap vs take, the subscription model) is owned by
  reach.md — implement the two together or reach.md first.
Stage: B1 — The Basement
Constitution: "Presence: the cursor and the senses", "No disembodied
  hands" (the action-side twin), "Justification and legibility"
  (inspection is the legibility law at the tile), design pillar 2 (the
  cursor reversal) and pillar 4 (readable at DF density), "Act One"
  (opening state; the Ears and Eyes beats)
Depends on: reach.md (device graph; sensor ownership/subscription —
  senses are subscribed feeds), basement-map.md (sensors, fog, tile
  vocabulary), core.md (the core as the player's only physical
  location), schedules.md (person presence; located knowledge),
  social.md (staged knowledge)

Behavior #

The cursor #

The player's map presence is a cursor — attention, not an avatar.

• It moves freely over every tile — walls, fog, locked rooms — in both frontends (keyboard in terminal; keyboard + mouse in Bevy).
• It is not a sim entity: no collision, no walkability check, no signature, no suspicion, no compute cost. Nothing in the world reacts to it. Moving it changes nothing in the sim.
• Cursor position is frontend state, not sim state. The sim exposes query APIs (inspect, knowledge lookups); it does not store or save a cursor. The existing build cursor merges into this one — there is one pointer, and build/splice/action targeting anchor to it.
• The walking player entity is deleted (zombie fiction from the villain era): no move_player, no player walkability, no vision radius around a player position, no player body coordinates in the save. The player's only physical location is the core's host bay (core.md, Rack 3).
• Actions that targeted "nearest to the player's body" (e.g. the sensor splice) re-anchor to "target at/near the cursor," with legality coming from control and reach (network paths, assets, badge access of the humans involved) — distance from any body is never a cost or a gate.

The senses #

• Sensor gains capability flags sees and hears. The env_camera both sees and hears (the constitution has it overhearing Marcus's 3 a.m. phone calls); camera_node and dock_camera see; a mic fixed object may be authored where hearing-only coverage is wanted [TUNE which rooms, if any, at B1]. Its audio feed is tappable from tick one (the Ears beat — reach.md) while the camera stays dormant until the Eyes beat.
• "Controlled" throughout this spec means subscribed per reach.md's ownership contract (owner + subscribers; tap vs take). The player's senses are exactly the union of feeds they subscribe to.
• Sight = the union of subscribed seeing-sensors' coverage. Full live detail inside; none outside.
• Hearing = the union of subscribed hearing-sensors' coverage. Yields room-grade events, not pictures: entry/exit, machinery state, conversations. A heard person surfaces per staged knowledge (social.md) — an unidentified presence until knowledge identifies them. Overheard conversations are the audio intel channel (the Marcus leverage beat runs through it).

Fog: epistemic tile states #

A tile renders what you know and how you know it. Core states, by precedence: Seen > Heard > Blueprint > Unknown.

• Seen — full live render.
• Heard — no visuals; presence/event markers; room label if known.
• Blueprint — schematic: walls, doors, fixed objects known from static sources; no live data. Seeded from the reach graph's known topology (the partial subnet map — reach.md owns knowledge growth); grows from records and schedule knowledge.
• Unknown — dark.

Terminal renders the states as distinct dim/glyph conventions; Bevy as darkness/tint/markers. Exact treatment is the art pass's; the states must be distinguishable at a glance (pillar 4).

Inspection #

inspect(x, y) (sim API, rendered by both frontends) returns a card: what the tile/asset is, plus every known fact, each tagged with its provenance (seen / heard / blueprint / and, if the proposal lands, remembered @ time).

• Door: type, badge tier; open state only while seen.
• Rack/machine: what it is; owner, bays, load per what your senses (or telemetry, if affirmed) earn.
• Person: identity, role, and state strictly per staged social knowledge, plus how you currently know they're here.
• Fixed objects (records box, breaker panel, key hook...): what it is, and its story-relevant contents once known.

The converse of the legibility law binds: no live fact appears without the sense coverage that earns it.

Design notes (cross-spec, per meta.md) #

• Refines basement-map.md's fog rule: "visibility is exactly the union of controlled sensors" remains true for the Seen state; Heard adds an epistemic grade below it and never grants visual detail.
• Extends schedules.md AC4 ("no person renders outside sensor coverage"): inside hearing-only coverage a person renders as a presence marker gated by staged knowledge, never a full glyph.
• Save format: the JSON save drops the player body position and gains sensor capability flags (+ knowledge state if the proposals land), under the versioned-migration rule (player contract, continuity).

Proposals awaiting decision — Proposal [OPEN] #

Not yet law; do not implement until affirmed in the decisions log, at which point criteria P2-P3 join the acceptance set. (Blueprint — formerly P1 — was affirmed 2026-07-06 and is now core criterion 8.)

2. Remembered state. Tiles once seen keep a dimmed, timestamped last-seen snapshot ("last seen day 3, 14:00" on inspect), rendering between Blueprint and Heard in precedence. Why: a process keeps logs; DF-style map memory with an in-fiction reason.
3. Telemetry. Machines you run report their own state (power, temperature, load, job) regardless of fog — proprioception, not sight. Why: it legitimizes what the host-bay vision hack was groping at, and "you feel your racks" is the machine-axis fantasy.

Player surface #

• One cursor, always visible, in both frontends; the inspect card (sidebar in terminal, panel in Bevy) live-updates as it moves.
• The opening beats: at tick one the map is dark except blueprint traces of the known subnet. Tapping the env monitor's audio feed (Ears — reach.md) brings the first heard events; splicing its camera floods the coverage into Seen — first sound, then sight, each a visible epistemic upgrade to a diagram you already obsess over.

Acceptance criteria #

1. No walking avatar: neither frontend has a player-move command that changes sim state; the sim exposes no move_player; no visibility derives from any player position; the save carries no player body coordinates (versioned migration from saves that did).
2. The cursor reaches every tile — walls, fog, locked rooms — in both frontends, and moving it changes nothing in the sim: no signature, no suspicion, no compute effect (test: sim state hash identical before/after arbitrary cursor movement).
3. Sight is exactly the union of controlled seeing-sensors; hearing exactly the union of controlled hearing-sensors; neither includes any player/core radius.
4. The fog states render distinguishably in both frontends; acquiring the env_camera converts its coverage to Seen (the first-eyes beat end-to-end); a hearing-only region shows presence/events and never visual detail or unearned identity.
5. inspect returns a card for any tile with every fact provenance-tagged, and a live fact never appears without the sense coverage that earns it (test: a person in an uncovered room is absent from inspect; the same person under mic-only coverage is a presence event; under camera coverage, fully surfaced per staged knowledge).
6. Overheard conversation events exist and can carry intel: with a controlled hearing sensor covering Marcus's room during his 3 a.m. call, the call surfaces as a heard event (the leverage pipeline can consume it).
7. Save/load round-trips sensor capability flags and all knowledge state this spec adds; cursor position is frontend-only and absent from the save.
8. Blueprint: subnet-seeded rooms render schematic from tick one; non-seeded rooms are dark; blueprint tiles show no live state and convert to Seen/Heard when coverage arrives.

(P) — active only if the matching proposal is affirmed:

• P2 (remembered): a tile seen once and lost renders its dimmed snapshot; inspect shows the last-seen timestamp; snapshots survive save/load.
• P3 (telemetry): a controlled machine's own state is readable with zero sensor coverage of its tile; an uncontrolled machine's is not.