# Work OS V2 - Product Design Guide

Date: August 9, 2026
Status: binding design guide for prototype-to-product work

## Product sentence

Work OS is one fixed operating room that shows what matters, why it matters,
what the machine is doing, where Nathan's word is required, and what actually
happened.

The unit is a causal object, not a task card, chat message, notification, or
dashboard widget.

## The causal grammar

Every consequential object follows one order:

`consequence -> proof -> your word -> machine work -> outcome -> receipt`

### Consequence

State what is blocked, exposed, delayed, or enabled. Include why the object
entered the field now.

### Proof

Show exact source identity, observed time, freshness, role, and pointer. A
machine judgment remains labeled as a maybe.

### Your word

Ask only for judgment or authority the machine cannot supply. Show what was
tried first. Offer consequence-bearing options plus `say it`.

### Machine work

Show factual stage, current action, and completed units. Do not use invented
percentages or theatrical progress.

### Outcome

Describe the visible state change. Prepared work is not sent work. A draft is
not an email.

### Receipt

Separate intent, parse, request, actual provider state, and deliberate
non-actions. A toast is never the receipt.

## Fixed furniture

The room has seven pieces. Production work may deepen them but may not add
product navigation.

1. **Line** - command input, parse, consequence, and non-effect before action.
2. **Watch** - standing topics, people court state, and learned state only.
   Work, capability gaps, weekly close, and help stay beside the room state they
   govern instead of becoming a second navigation system.
3. **Field** - dense, stable bands of consequential objects.
4. **Selected line** - the complete six-station chain expanded in place.
5. **Tape** - append-only did, saw, and thinks events with traces.
6. **Drawer** - one shared depth container over the still-visible room.
7. **Mobile machine strip** - persistent selected state and entry into depth.

Do not add:

- a chat-first home;
- permanent side navigation;
- tabs for sources, activity, result, or history;
- a second details page;
- a parallel effort or receipt model.

## Room hierarchy

The field is always dominant. The order of attention is:

1. top consequence;
2. open word;
3. active or failed machine work;
4. exact safe move;
5. latest receipt;
6. standing context.

At 1440px, show at least eight monitored states and one full causal line. At
390px, the first viewport must preserve the line, top consequence, word state,
current machine state, and latest receipt or named failure.

## Row contract

Every collapsed row exposes:

- immutable object ID;
- consequence state and age;
- plain title;
- why now;
- proof state and source;
- Nathan's word or `Not needed`;
- machine state and current unit;
- one local hero verb.

One row may carry one saturated claim. Additional metadata stays quiet.

The row remains at a stable address. Selection expands it without reordering the
field.

## State encoding

Color always carries a specific fact and is never the only distinction.

| State | Color | Non-color treatment |
| --- | --- | --- |
| Consequence or failure | alert red | stop edge or named failure |
| Nathan's word or maybe | gate purple | dashed edge |
| Exact proof or verified result | proof green | solid edge |
| Waiting or undone promise | amber | interruption edge |
| Receipt or machine register | ink | mono label and bounded trace |

Facts use a solid proof edge. Maybes use a dashed edge. A judgment on a maybe
does not convert it into a fact.

## Visual system

### Light mode

| Token | Value | Role |
| --- | --- | --- |
| Ground | `#E6E9E4` | room field |
| Surface | `#F8F9F6` | rows and drawers |
| Surface 2 | `#EEF1ED` | controls and bounded wells |
| Ink | `#17201B` | primary text |
| Ink soft | `#59645D` | secondary text |
| Rule | `#BFC7C1` | structure |
| Machine | `#1B231E` | tape and raw receipts |
| Alert | `#C0442B` | consequence and failure |
| Gate | `#7457BA` | word and judgment |
| Proof | `#247355` | exact evidence and verified result |
| Wait | `#93660F` | waiting and undone |

### Dark mode

Dark mode uses tuned green-black grounds, not an inversion:

| Token | Value |
| --- | --- |
| Ground | `#121713` |
| Surface | `#1B211D` |
| Surface 2 | `#222A24` |
| Ink | `#E6ECE7` |
| Ink soft | `#AEB9B1` |
| Rule | `#48534B` |
| Alert | `#EF775D` |
| Gate | `#B6A0ED` |
| Proof | `#66C198` |
| Wait | `#E0B457` |

Every text and control state must reach 4.5:1 contrast on its actual ground.

## Type

Use Avenir Next or the existing system sans for world state and Nathan's words.
Use system mono for IDs, timestamps, counts, keys, receipts, and machine
registers.

The closed size schedule is:

- 8px: machine micro-label only;
- 9px: timestamps, IDs, receipt metadata;
- 10.5px: secondary dense-row text;
- 11.5px: primary dense-row text;
- 13px: body;
- 15px: selected-line heading;
- 18px: drawer heading.

Do not use serif type, negative letter spacing, viewport-scaled text, or display
type inside compact operational surfaces.

## Geometry

- collapsed desktop row: 54-62px;
- band heading: 27-30px;
- control hit target: at least 24px;
- control radius: 4px;
- bounded surface radius: 7px maximum;
- structure: one-pixel rules;
- drawer: right side on desktop, full width on mobile.

Do not nest cards. A section is not a floating card. Wide screens gain useful
columns, not decorative margins.

## Core interactions

### Select and follow

Selecting a row:

- keeps furniture fixed;
- expands the six stations;
- teaches the command line the selected address;
- scopes the tape to related events;
- pins the compact state on mobile.

### Command line

Known commands print their parse, consequence, and non-effect before Enter.
Unknown work becomes an editable effort proposal. It never starts immediately.

Required command examples:

- `open t-21`;
- `snooze t-15 until monday`;
- `close week`;
- `review draft t-17`;
- an unconstrained sentence that creates a proposal.

### Your word

Options describe recognizable outcomes. No option is preselected. `say it`
records Nathan's exact words and renders the machine interpretation separately.
Reopening appends a correction event; it does not erase the prior answer.

### Delegation

An effort proposal names:

- goal;
- needs;
- plan;
- current work;
- decisions needed from Nathan;
- expected deliverable;
- effect boundary.

The approved effort exposes factual progress, map, actor, run rail, rejection,
result, stop, and resume.

### The Dig

A topic drawer reconstructs:

- present-state causal objects;
- current delta;
- sourced history;
- promises kept;
- amber promised-and-undone lines;
- honest source coverage and exclusions.

The Dig is history as behavior, not a document search result.

### People

The people table is ordered by age and makes court state the load-bearing
column. Each person opens in the shared drawer with:

- last interaction;
- open state;
- promises;
- append-only changeset;
- resurface rule;
- related causal object;
- one local draft verb that never contacts a provider.

### Draft custody

The only mail actions are read and place drafts through the bridge contract.
Work OS never sends.

The flow is:

`review -> exact effect -> explicit arm -> explicit confirm -> provider receipt`

The receipt names recipient, requested action, actual provider state, `sent:
false`, and every excluded mailbox effect.

### Weekly close

The close assembles an append-only ledger and requires an explicit stamp.
Reopening adds a new event and preserves the original close receipt.

### Capability growth

A failed capability exposes:

- named failure;
- safe current state;
- researched narrower path;
- requirements and scope;
- demonstrated rehearsal;
- one-shot authority;
- immediate expiry receipt.

Standing authority is never smuggled through a one-time approval.

## Drawer contract

All depth uses the same shell:

- the room remains visible behind it;
- the title names the object, not a product section;
- the close control is always in the same place;
- `Esc` closes one layer and restores focus;
- state changes remain visible after close;
- raw receipt and deliberate non-actions are available.

Drawers may contain proof, topic history, people state, effort maps, learned
patterns, capability proposals, draft custody, weekly close, and traces.

## Keyboard

- `Command-K`: focus the line;
- `j` and `k`: move selection without opening;
- `Enter` or `e`: invoke the selected safe move;
- `o`: open selected proof;
- `t`: open selected trace;
- `u`: undo the active five-second recovery action;
- `?`: open the key map;
- `Esc`: close one layer and restore focus.

Pointer labels and keyboard labels come from one action registry in production.

## Copy

Write from Nathan's side of the screen:

- `what it is doing`, not `orchestration status`;
- `everything gathered`, not `canonical dossier`;
- `maybe`, not `inference`;
- `pulled in because`, not `relation derivation`;
- `nothing was sent`, not `effect suppressed`.

Controls use direct outcome verbs. An unavailable control explains why and what
would make it available.

On compact rows, preserve the first operative verb (`Choose`, `Open`, `Review`,
`Research`) rather than collapsing every action to a generic label such as
`Do`. The full outcome verb remains the accessible name.

## Motion

Only four motions are permitted:

1. drawer entry, 150ms;
2. changed-row flash, 300ms;
3. commit-button state change, 180ms;
4. weekly-close ceremony, 800ms.

Reduced motion collapses timing to an immediate state change. Data never
animates between coordinates.

Reversible local actions such as snooze expose a five-second undo. Undo appends a
new event and never erases the original receipt.

## Truth and safety

- missing, stale, denied, or conflicting evidence fails closed;
- words and machine interpretation are separate records;
- judgments and corrections append;
- model-composed options never act by themselves;
- every claimed action reaches a trace and receipt;
- no server credential can enable mail sending;
- no UI control implies an integration that is not present;
- no flow asks Nathan to file, tag, sort, or maintain the system.

## Review checklist

A design is ready to build only when all answers are yes:

1. Can Nathan identify the top consequence in five seconds?
2. Is fact versus maybe visible without color?
3. Is the next safe move local to the object?
4. Does the action state what will and will not happen?
5. Are Nathan's exact words preserved?
6. Is machine work expressed with factual stage and units?
7. Can the result reach a raw receipt?
8. Can failure recover without hiding the prior state?
9. Does depth stay inside the room?
10. Does the same flow work at 390px and by keyboard?
11. Does this remove software management rather than create it?