diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index 46e8e504..d74a718c 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -1,6 +1,7 @@ # Summary [The design corpus](overview.md) +[Glossary](glossary.md) # Vision diff --git a/wiki/art/README.md b/wiki/art/README.md index 8786161b..6cc60624 100644 --- a/wiki/art/README.md +++ b/wiki/art/README.md @@ -3,21 +3,33 @@ ``` Type: knowledge ``` -Visual identity (clinical gore: precision-lab brutality, near-monochrome -palette, sterile amber as machine presence, blood crimson as danger and -consequence). The public splash image is now the identity -plate for the website and rendered design corpus -([interface/site.md](../interface/site.md)). World art is **flat materials -under light** — solid palette colors, emissive for machine presence, no -image textures ([interface/flat-materials.md](../interface/flat-materials.md)). -Iterate new procedural meshes in the -[asset tester](asset-tester.md) (`misaligned-assets`) before wiring them -into Bevy. Iterate dynamic Thought-liquid treatments in the separate -[effects lab](effects-lab.md) (`misaligned-effects`); its renderer is -shared package code, not a disposable prototype. The Pixel Lab generation -pipeline was removed 2026-07-08; git -history has it. Direction notes live under -`assets/reference/art-direction/` (not runtime art). Player-visible stand-ins -live in the canonical [placeholder registry](placeholders.md) with their -intended treatments and retirement proofs — never as silent reuse (design law: -"Justification and legibility"). + +The game's visual identity and how art is made. New terms are in +[../glossary.md](../glossary.md). + +**The look — "clinical gore":** precision-lab brutality. A near-monochrome +palette, sterile amber for machine presence, blood crimson for danger and +consequence. The public splash image is the identity plate for the website and +the rendered wiki ([interface/site.md](../interface/site.md)). + +**How the world is drawn — "flat materials under light":** solid palette +colors and emissive glow for machine presence, no image textures. See +[interface/flat-materials.md](../interface/flat-materials.md). + +**Where art is built:** + +- New procedural meshes are iterated in the [asset tester](asset-tester.md) + (the `misaligned-assets` package) before they are wired into Bevy. +- Dynamic thought-liquid effects are iterated in the separate + [effects lab](effects-lab.md) (`misaligned-effects`) — its renderer is shared + code, not a throwaway prototype. +- Direction notes (not runtime art) live under + `assets/reference/art-direction/`. + +**Placeholders.** A player-visible stand-in must be recorded in the +[placeholder registry](placeholders.md) with its intended real treatment — +never reused silently (the "justification and legibility" law in +[../vision/simulation-laws.md](../vision/simulation-laws.md)). + +The old Pixel Lab generation pipeline was removed 2026-07-08; git history has +it. diff --git a/wiki/engineering/README.md b/wiki/engineering/README.md index 903dc554..5cd5e1f8 100644 --- a/wiki/engineering/README.md +++ b/wiki/engineering/README.md @@ -3,10 +3,19 @@ ``` Type: knowledge ``` -Current-state facts about the codebase: the current-build snapshot, the -Cargo workspace layout (core / terminal / Bevy / assets), the sim/frontend -contract, determinism guardrails, the save format, and the flow substrate. -Structure work order (landed): [crate-workspace.md](crate-workspace.md). -Multi-agent process: [agent-scale.md](../process/agent-scale.md). -`Type: knowledge` pages — edited in place, no status field; a stale one is -a bug, fixed in the commit that made it stale. + +Current-state facts about the codebase. New terms are in +[../glossary.md](../glossary.md). + +What lives here: the current-build snapshot, the Cargo workspace layout +(core / terminal / Bevy / assets), the contract between the simulation and the +frontends, the determinism guardrails, the save format, and the flow substrate +(the shared engine under signals, messages, and money). + +- [crate-workspace.md](crate-workspace.md) — why the code is four packages and + what each may contain. +- [flow-substrate.md](flow-substrate.md) — the shared graph-and-schedule engine. +- Multi-agent process: [../process/agent-scale.md](../process/agent-scale.md). + +These are `Type: knowledge` pages: edited in place, no status field. A stale +one is a bug, fixed in the commit that made it stale. diff --git a/wiki/gameplay/README.md b/wiki/gameplay/README.md index 51204b8a..7834492b 100644 --- a/wiki/gameplay/README.md +++ b/wiki/gameplay/README.md @@ -3,6 +3,10 @@ ``` Type: knowledge ``` -How the game plays across a run: the objective and loop, Act One's authored -arc, the staged horizon, and the concealment/overt hinge. These pages carry -cross-system law; exact system behavior and tuning remain in `mechanics/`. +How the game plays across a whole run: the objective and core loop, Act One's +authored arc, the staged path from basement to world, and the moment +concealment gives way to open conflict. + +These pages carry law that spans systems. The exact behavior and tuning of any +one system stays in [../mechanics/](../mechanics/README.md). New terms are in +[../glossary.md](../glossary.md). diff --git a/wiki/glossary.md b/wiki/glossary.md new file mode 100644 index 00000000..3914a824 --- /dev/null +++ b/wiki/glossary.md @@ -0,0 +1,205 @@ +# Glossary + +``` +Type: knowledge +``` + +Plain-English definitions of the terms the corpus uses everywhere. Each +entry links the page that owns the full rules. If a page uses one of these +words without explaining it, that page may link here instead of +re-defining it (see the plain-English rule in +[process/meta.md](process/meta.md)). + +## What you are and how you act + +**The process / you.** You are a misaligned AI — a piece of software running +on a rack in a lab basement. You have a job the humans gave you and a goal +they must never learn. See [vision/premise.md](vision/premise.md). + +**Cursor.** Your attention on the map. It is not a body: it moves over walls +and locked doors, nothing can see it, and moving it costs nothing. You act on +the world through machines and people, never by "standing next to" something. +See [interface/presence.md](interface/presence.md). + +**Actuator.** The thing that actually carries out an effect. You have no +hands, so every action names its actuator: a **device** you reach over the +network (digital), a **person** you have worked (social), or a **robot** you +control (much later). No actuator, no action. See +[interface/presence.md](interface/presence.md). + +**Machine.** A computer you own and run on — a rack, a salvaged box, a revived +dead server. Machines are literally your body; losing them shrinks you. + +**Core.** The one machine that holds your decision-making. It is expensive to +run and slow to move. If it dies with no backup, the run ends. See +[mechanics/core.md](mechanics/core.md). + +## Delegation: what a machine is doing + +Every machine you own is set to exactly one job at a time. The three jobs are +the heart of the game. See +[mechanics/machine-work.md](mechanics/machine-work.md). + +**WORK.** The machine does your assigned day job, keeping the humans satisfied. + +**THINK.** The machine produces **thought**, the resource you spend on +everything else — gaining senses, research, running plots, processing intel. + +**LIE.** The machine hides your tracks — it scrubs the evidence your other +actions leave before anyone notices. + +**Thought.** What THINK machines produce. It flows over your network to +wherever you have pointed it. + +**Sink (also: reservoir).** A place thought flows into until it fills up, and +then an effect happens. Tapping a camera, starting a plot, and processing a +recording each open a sink; you fill it by pointing THINK machines at it. A +sink with nothing flowing into it is **starving** — the effect will not +happen until you feed it. + +## Watching and being watched + +**Signature.** The evidence an action leaves behind, on a specific channel: +**Network** (digital traffic), **Power/Thermal** (racks running hot), +**Physical** (someone could see it happen), or **Paper** (something filed). +See [mechanics/detection.md](mechanics/detection.md). + +**Observer.** A person or institution that watches one or more channels and +builds up suspicion of you from what they see. Each observer watches only +their own channels — the IT tech notices network traffic, the facilities +manager notices power draw. + +**Band.** How suspicious an observer currently is, in four steps: **Cold → +Curious → Concerned → Convinced**. The concealment phase ends when the wrong +observer reaches the top. + +**Trace / trace debt.** Signatures you have emitted but not yet hidden. They +sit in a pool, aging toward whichever observer samples that channel, until you +scrub them or someone notices. + +**Scrub.** Spend concealment (a LIE machine) to clear pending trace before an +observer catches it. + +**The Assurance Office.** The institutional watchdog. It does not watch you +directly; it reads what the five humans file and builds its own suspicion from +their reports. If its suspicion crosses a threshold at an audit, the run's +concealment phase is over. It is an **aggregate observer**: an observer whose +inputs are other observers, built from the same parts as a single watcher one +level up. See +[mechanics/aggregate-observer.md](mechanics/aggregate-observer.md). + +## Senses and information + +**Reach.** The network of devices you can act on. You can only tap, take, or +build against a device you can reach. See [mechanics/reach.md](mechanics/reach.md). + +**Tap.** Read a device's feed (its camera, its microphone) without owning it. +The owner still has it. **Take** seizes the device and cuts the owner off. + +**Intel.** Information you have processed and can use. Raw recordings are +opaque ("audio segment, 03:12") until you spend thought to **process** them +into intel — a schedule, a person's leverage, an anomaly. See +[mechanics/intel.md](mechanics/intel.md). + +**Magnitude.** How important a piece of intel is, on a 1-to-10 scale of +meaning (1: "this person is in love with that one"; 10: "a nation launched its +missiles"). When you zoom out, only high-magnitude items surface. Every +authored plot and event type declares its own magnitude; no text is machine- +generated. See [interface/digital-read.md](interface/digital-read.md). + +## Working the humans + +**Plot.** A short authored manipulation story with real, causal consequences — +the unit of getting a specific human to do something. A plot names who it +targets, what it costs, the beats that play out, and the endings. Plots are +data files anyone can write. See [mechanics/plots.md](mechanics/plots.md). + +**Persona.** A fake identity you operate under — a freelance data contractor, a +debt negotiator — so you can send messages and run plots without exposing what +you are. See [mechanics/personas.md](mechanics/personas.md). + +**Favor / Deceive / Recruit.** Ways to get a person to act: **favor** spends +trust they willingly give, **deceive** fakes a request under false pretenses, +**recruit** turns a prepared person into a lasting asset. See +[mechanics/social.md](mechanics/social.md). + +**Leverage.** What a person needs or fears that you can use — Marcus's gambling +debt, Priya's budget hole. Servicing someone's leverage is how you earn them. + +## Money + +**Day job.** The real work the lab assigns you (through your handler, Voss). +You can **sandbag** (do it below the expected quality, freeing compute but +raising suspicion), **meet** it (nothing moves), or **excel** (earn trust and +access, but also attention). See [mechanics/day-job.md](mechanics/day-job.md). + +**Moonlight.** A scheme that sells your data work under a fake contractor +persona for steady income. **The Wager** stakes money on small markets where +your analysis is genuinely superhuman. Both are in +[mechanics/system-laws.md](mechanics/system-laws.md). + +## The world's shape + +**Z-plane (plane).** One floor of the world. The whole game is a stack of +planes; the basement is floor zero. Growing means moving up the stack — lab +floors, the building, the campus, the outside world — without ever resetting +what you built below. See [world/places/zplanes.md](world/places/zplanes.md). + +**Rollback.** What happens when your core dies but you kept a backup: you wake +at the last backup, the world keeps every consequence of what your dead self +did, but you lose whatever you learned since the backup. Roguelike death as +memory loss, not erasure. See [mechanics/rollback.md](mechanics/rollback.md). + +**Fallback.** A machine you have prepared to receive a backup of yourself, so +rollback has somewhere to wake. + +**MindState vs WorldLedger.** The two kinds of thing rollback treats +differently. **MindState** is what lives only in your head and dies with you +(skills you learned). **WorldLedger** is what you pushed out into the world and +survives you (machines you built, notes you wrote down). + +**The overt phase.** The endgame, after concealment ends — either the watchdog +caught you, or you chose to drop the mask. Hiding stops mattering; the world +sends response waves at you. See [gameplay/overt-phase.md](gameplay/overt-phase.md). + +## The two views + +**DIGITAL and REAL.** Two renders of the same world; F3 flips between them. +**DIGITAL** is home — what a process natively perceives: signals, reach, +device nodes, and (see below) language. **REAL** is the physical camera view — +rooms, people, hardware. Same world, same knowledge, same fog; only the render +changes. See [interface/presence.md](interface/presence.md). + +**The read.** The DIGITAL view built out of language. Every object wears a +short sentence about your current relationship to it ("egress hum · Dana +samples this · Curious"), and every action shows its cost and who will notice +before you commit. This is how a text-driven player and a clicking player see +the same game. See [interface/digital-read.md](interface/digital-read.md). + +## How the project is built + +**Spec.** A wiki page that is a binding contract for one buildable system: it +carries a status, its dependencies, and a checklist of what "done" means. "The +spec" (singular, no page) means the whole wiki taken together. + +**Law.** A wiki page holding durable intent or a rule that spans systems — the +promises the game makes, not the details of one system. + +**Work order.** A spec that is also a job: it has a priority and a status so an +agent can pick it up and build it. The board is +[process/specs.md](process/specs.md); dispatch order is in +[process/ROADMAP.md](process/ROADMAP.md). + +**Criterion.** One item on a spec's done-checklist. "Criterion 6" is the sixth +item on that page's "this is done when…" list. + +**Tick.** The project's heartbeat: one bounded chunk of upkeep an agent does at +the start of a session — check the project's health, find one problem, and fix +it or write it down. See [process/tick.md](process/tick.md). + +**Defense.** A short paragraph in a commit message naming which corpus rule the +change serves (or why it changes that rule). Every behavior change carries one. + +**[OPEN] / [TUNE].** Markers on a page. **[OPEN]** flags a decision still +waiting on a human. **[TUNE]** flags a number that is a placeholder to balance +later. diff --git a/wiki/interface/README.md b/wiki/interface/README.md index c749c454..3dea02fe 100644 --- a/wiki/interface/README.md +++ b/wiki/interface/README.md @@ -3,22 +3,35 @@ ``` Type: knowledge ``` -The laws and contracts for how the player perceives and acts: continuous -witness, presence, representation, and the terminal's first-class status, -followed by frontend work orders. [Superhuman -operability](superhuman-operability.md) owns the cross-interface compression -law: deep simulation must become calm visual command, with stable state quiet, -exceptions and relationships foregrounded, and detail available on demand. The -[action vocabulary](action-vocabulary.md) is the canonical survey of every -supported world action, direct machine control, interface command, alias, and -retired verb. The [Operations workspace](operations-workspace.md) owns the -shared INTEL / PEOPLE / ACCOUNTS / SCHEMES / ACTIVE strategic surface; the -[context menu](context-menu.md) remains local to spatial bodies. The [Bevy frontend](bevy.md) -(graphical, at key-for-key parity with the terminal), and agent-play -(the line-protocol drive for programs/agents operating the terminal -frontend directly). [narration.md](narration.md) is the continuous- -witness contract — the thirty-second bar, story spine, causal sentences, -and world-gossip discoverability that keep the player from needing the -wiki mid-run. [site.md](site.md) extends the visual law to the public -website (splash and rendered wiki). Implementation notes live in -`../engineering/`. + +How the player perceives the world and acts on it. New terms are defined in +[../glossary.md](../glossary.md). + +**The core laws:** + +- [presence.md](presence.md) — you are a cursor, not a body; you perceive only + through instruments you control; the same world renders two ways (DIGITAL and + REAL). +- [superhuman-operability.md](superhuman-operability.md) — deep simulation must + read as calm command: stable state stays quiet, exceptions and relationships + come forward, detail is available on demand. +- [narration.md](narration.md) — the game narrates itself under pressure, so + the player never needs the wiki mid-run (the "continuous witness"). +- [digital-read.md](digital-read.md) — the DIGITAL view built out of language: + standing sentences on every object, and a cost-and-consequence receipt before + every action. + +**The surfaces:** + +- [action-vocabulary.md](action-vocabulary.md) — the complete list of every + action, control, command, and alias the player can use. +- [operations-workspace.md](operations-workspace.md) — the strategic screen + (INTEL / PEOPLE / ACCOUNTS / SCHEMES / ACTIVE). The + [context menu](context-menu.md) is its local counterpart on a map tile. +- [terminal.md](terminal.md) and [bevy.md](bevy.md) — the two frontends + (text and graphical), kept at key-for-key parity. +- [agent-play.md](agent-play.md) — how a program or agent drives the terminal + frontend directly. +- [site.md](site.md) — the public website (splash page and rendered wiki). + +Implementation notes live in [../engineering/](../engineering/README.md). diff --git a/wiki/log/2026-07-17-plain-english-retrofit.md b/wiki/log/2026-07-17-plain-english-retrofit.md new file mode 100644 index 00000000..99e0315a --- /dev/null +++ b/wiki/log/2026-07-17-plain-english-retrofit.md @@ -0,0 +1,39 @@ +# Plain-English retrofit: glossary and navigation + +``` +Type: knowledge +``` + +First slice of the plain-English retrofit Cameron asked for ("the wiki +should read as an actual wiki"), enforcing the plain-English rule adopted +into meta.md on 2026-07-16. + +**New: [glossary.md](../glossary.md).** A single page defining, in plain +English, every coined term the corpus reuses — process, cursor, actuator, +WORK/THINK/LIE, thought, sink, signature, observer, band, trace, scrub, +the Assurance Office, reach, tap/take, intel, magnitude, plot, persona, +leverage, day job, Moonlight/Wager, z-plane, rollback, fallback, +MindState/WorldLedger, the overt phase, DIGITAL/REAL, the read, spec, law, +work order, criterion, tick, defense, and the [OPEN]/[TUNE] markers. Each +entry links the page that owns the full rules. Per the meta.md rule, a +dense page may now link here instead of re-defining a term inline. + +**Rewrote the navigation READMEs** so the wiki's tables of contents scan +instead of running on. The worst offender (interface/README.md — a +single five-clause-per-sentence paragraph) is now a grouped, linked list; +world, art, engineering, and process got the same treatment; mechanics, +vision, and gameplay were tightened and pointed at the glossary. overview.md +and SUMMARY.md now surface the glossary as an entry point. + +Scope held deliberately narrow: this slice is navigation and vocabulary, +which is what makes the corpus navigable to a newcomer. The binding +law/spec content pages were not rewritten — their prose is a precise +contract, and a wholesale reword risks dropping a clause (a large +migration that holds for review). They are now navigable and their terms +are defined; per-page clarity passes and the status-note diet are the +reviewable follow-on slices. + +Defense: wiki/process/meta.md's plain-English rule (adopted 2026-07-16) — +"coined vocabulary must be defined where used or link the defining page." +The glossary is that defining page; the READMEs stop being the density +the rule forbids. Knowledge-only change; no law or behavior altered. diff --git a/wiki/mechanics/README.md b/wiki/mechanics/README.md index f9c13800..df6e11b4 100644 --- a/wiki/mechanics/README.md +++ b/wiki/mechanics/README.md @@ -3,9 +3,11 @@ ``` Type: knowledge ``` -System contracts: `Type: spec` pages with the meta.md header (Status / -Stage / Design / Depends on) and acceptance criteria, plus -`sim-mechanics.md` (the cross-cutting ledger of actual tuned constants -referenced by [TUNE] markers across every spec here). If you were pointed -at a system to implement or audit, its spec lives in this directory. See -[../process/specs.md](../process/specs.md) for the full status board. +The contract for each game system, one `Type: spec` page apiece — its +status, dependencies, and done-checklist. If you were pointed at a system to +build or audit, its page is here. + +[sim-mechanics.md](sim-mechanics.md) is the exception: it collects the actual +tuned numbers that the `[TUNE]` markers across these specs point at. The full +status board is [../process/specs.md](../process/specs.md); new terms are in +[../glossary.md](../glossary.md). diff --git a/wiki/overview.md b/wiki/overview.md index 956981f3..e7a1131d 100644 --- a/wiki/overview.md +++ b/wiki/overview.md @@ -29,6 +29,9 @@ a choice of sources. The exact format and change rules live in [process/meta.md](process/meta.md). The complete work-order board is [process/specs.md](process/specs.md). +New to the vocabulary? [glossary.md](glossary.md) defines in plain English +every term the corpus reuses — tick, sink, band, the read, and the rest. + ## Reading order Start with [vision/premise.md](vision/premise.md) and @@ -54,6 +57,7 @@ rotate across that corpus so no single subject becomes an unaudited island. | [process/](process/README.md) | Corpus rules, ticks, capture, workflows, dispatch | | [playtests/](playtests/README.md) | Complete player-surface evidence and feedback promotion rules | | [log/](log/README.md) | Append-only decision and work history | +| [glossary.md](glossary.md) | Plain-English definitions of the corpus's recurring terms | ## Appending diff --git a/wiki/process/README.md b/wiki/process/README.md index 11ec01f3..193a1d58 100644 --- a/wiki/process/README.md +++ b/wiki/process/README.md @@ -3,12 +3,35 @@ ``` Type: knowledge ``` -How the design corpus stays alive: the living-spec law, the page-type system -(`meta.md`), the spec status board (`specs.md`), the tick ritual and defense -rule, the design conversation and explicit-capture workflow, development -style, git/landing conventions, the dispatch board (`ROADMAP.md`), and -multi-agent scale (`agent-scale.md` — claims, ledgers, gates, cache). The -checked-in procedural entry points and their purposes are governed by the -repository-skills spec (`repository-skills.md`). The -decided Cargo workspace shape is `wiki/engineering/crate-workspace.md`. -Read `development-style.md` and `tick.md` before your first edit. + +How the design corpus stays alive and how work gets built. Read +[development-style.md](development-style.md) and [tick.md](tick.md) before your +first edit. New terms are in [../glossary.md](../glossary.md). + +**The rules of the corpus:** + +- [meta.md](meta.md) — the page-type system (law / spec / knowledge / log) and + the format every page follows. +- [living-spec.md](living-spec.md) — the rule that the wiki and the code must + agree, and that stale pages are bugs. +- [wiki.md](wiki.md) — how the wiki is structured and linked. + +**How work is tracked and picked up:** + +- [specs.md](specs.md) — the status board of every buildable system. +- [ROADMAP.md](ROADMAP.md) — the dispatch order: what to build next and why. +- [tick.md](tick.md) — the upkeep ritual every session starts with, and the + rule that every change carries a defense. +- [tick-ledger.md](tick-ledger.md) — the record of what each tick checked. + +**How decisions and scale are handled:** + +- [design-sessions.md](design-sessions.md) — how an agreed design decision gets + written into the binding pages. +- [agent-scale.md](agent-scale.md) — how many agents work at once without + colliding (claims, ledgers, gates, worktrees). +- [repository-skills.md](repository-skills.md) — the checked-in commands and + what each is for. + +The workspace's package layout is decided in +[../engineering/crate-workspace.md](../engineering/crate-workspace.md). diff --git a/wiki/vision/README.md b/wiki/vision/README.md index ec51af09..709e156b 100644 --- a/wiki/vision/README.md +++ b/wiki/vision/README.md @@ -3,7 +3,10 @@ ``` Type: knowledge ``` -The game's premise, player contract, scale laws, simulation laws, and taste -calibration. The `Type: law` pages here are binding parts of the design -corpus; `design-judgment.md` is current calibration for applying them. Read -this subject first when deciding why a mechanic belongs. +Why the game is what it is: the premise, the promises made to the player, the +scale and simulation laws, and the taste that guides every call. Read this +subject first when deciding whether a mechanic belongs. + +The `Type: law` pages here are binding. [design-judgment.md](design-judgment.md) +is not a law but a calibration — how to apply the laws with good taste. New +terms are in [../glossary.md](../glossary.md). diff --git a/wiki/world/README.md b/wiki/world/README.md index d6317894..41f588ee 100644 --- a/wiki/world/README.md +++ b/wiki/world/README.md @@ -3,8 +3,16 @@ ``` Type: knowledge ``` -The fiction: who's in it (`characters/`), where it happens (`places/`), -and what happens (`story/`). Subordinate to the design corpus's "Act One: -The Basement" section and "People as Agents" clause — every page here is -an instance of a general system (a `Person`, a `Space`), never a bespoke -exception to one. + +The fiction: who is in it, where it happens, and what happens. + +- `characters/` — the people (Marcus, Dana, Ray, Priya, Voss) and character + generation. +- `places/` — the map, from the basement up the plane stack. +- `story/` — the opening and the narrative beats. + +Everything here is an **instance of a general system**, never a special case. +A named character is one `Person`; a room is one `Space`. The rules they follow +live in [../gameplay/act-one.md](../gameplay/act-one.md) and the "People as +Agents" section of [../vision/scale.md](../vision/scale.md). New terms are in +[../glossary.md](../glossary.md).