diff --git a/README.md b/README.md
index aabef40..6e9ed38 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,26 @@
-
cu
-
-Evidence-bound Computer Use from the Windows command line.
-
-
-
-
-
-
-
-
-
- Getting Started
- ·
- Features
- ·
- CLI
- ·
- Safety
- ·
- Documentation
-
+
+
+
+
+---
`cu` captures validated Windows desktop regions, executes finite pointer and keyboard
plans against the latest observation, and records enough durable evidence to distinguish
@@ -37,34 +38,15 @@ operation, and closes its helper resources before returning. Stateless `displays
> is controlled-region observation and bounded input; unrestricted full-desktop
> observation remains blocked until isolated synthetic-desktop verification is complete.
-```powershell
-cu init --json
-cu displays --json
-cu observe work-a --region pixel:100,100,800,600 --json
-cu status work-a
-cu help action-file
-```
+## Core Idea
-The `observe` receipt supplies the `observationId` for the next action file. Coordinates
-inside an action file use the normalized `0..999` top-left coordinate space of that
-observation:
+Keep observation authority, input delivery, and application outcomes separate.
-```json
-{
- "kind": "cu.action/v1",
- "observationId": "obs_0123456789abcdef0123456789abcdef",
- "coordinateSpace": "normalized_999_top_left",
- "actions": [
- { "kind": "click", "at": { "x": 500, "y": 500 } }
- ]
-}
-```
-
-Replace the example observation ID with the value returned by `observe`, then run:
-
-```powershell
-cu act work-a --action-file action.json --json
-```
+| Question | Evidence to inspect |
+| --- | --- |
+| Are these coordinates still authorized? | The latest actionable observation and revalidated display topology |
+| Was native input emitted? | The effect journal and action receipt, including partial or indeterminate outcomes |
+| Did the application achieve the goal? | A fresh observation of application state; input emission alone is not proof |
## Key Features
@@ -87,7 +69,9 @@ cu act work-a --action-file action.json --json
- **Stable machine output**: versioned JSON receipts, sanitized error envelopes, and
fixed exit-code meanings for shell automation.
-## Requirements
+## Quick Start
+
+### Requirements
- Windows with an interactive default desktop
- Node.js `22.19.0` or newer
@@ -97,7 +81,7 @@ cu act work-a --action-file action.json --json
Locked, secure, unavailable, or elevation-bypass desktops fail closed. `cu` does not
attempt to work around those boundaries.
-## Installation
+### Installation
The current public build is a GitHub prerelease and is not published to the npm
registry. Download the exact release artifact and checksum with the GitHub CLI:
@@ -129,7 +113,7 @@ cu help
The prerelease supports controlled regional observation and bounded input. Unrestricted
full-desktop observation remains blocked pending isolated Windows Sandbox/VM acceptance.
-## Getting Started
+### Getting Started
Create a separate workspace so all state remains local to that directory:
@@ -172,6 +156,37 @@ When retained evidence is no longer needed:
cu clearall work-a --json
```
+### Observation-bound action file
+
+```powershell
+cu init --json
+cu displays --json
+cu observe work-a --region pixel:100,100,800,600 --json
+cu status work-a
+cu help action-file
+```
+
+The `observe` receipt supplies the `observationId` for the next action file. Coordinates
+inside an action file use the normalized `0..999` top-left coordinate space of that
+observation:
+
+```json
+{
+ "kind": "cu.action/v1",
+ "observationId": "obs_0123456789abcdef0123456789abcdef",
+ "coordinateSpace": "normalized_999_top_left",
+ "actions": [
+ { "kind": "click", "at": { "x": 500, "y": 500 } }
+ ]
+}
+```
+
+Replace the example observation ID with the value returned by `observe`, then run:
+
+```powershell
+cu act work-a --action-file action.json --json
+```
+
## Command Line
| Command | Purpose |
@@ -211,6 +226,21 @@ Receipts and durable diagnostics exclude raw typed text, private helper paths, r
process identifiers, window handles, and application-level success claims. Native input
emission never proves that an application completed a business operation.
+## Project Structure
+
+```text
+cu/
+├── src/ # CLI, observation, input, archive and effect state
+│ └── helper/ # Command-scoped Windows PowerShell helpers
+├── test/ # Unit, integration and controlled desktop tests
+├── scripts/ # Build assets and CI smoke checks
+├── skills/ # Agent-facing usage guidance
+├── docs/ # Design, contracts, verification and release notes
+└── assets/ # README title artwork
+```
+
+Runtime state belongs in a workspace-local `.cu/`, not in the source tree.
+
## Workspace State
Each working directory owns its own `.cu/` namespace. Runs are not inherited by parent
@@ -231,6 +261,18 @@ or child directories.
Some files are absent in steady state. Do not edit `.cu/` manually; use `status`,
`history`, `clear`, and `clearall` so witness and transaction checks remain intact.
+## Preview Limitations
+
+- Unrestricted full-desktop observation is not yet release-accepted.
+- Stale or ownerless run locks are preserved and block rather than being reclaimed.
+- Process-interruption recovery is fail-closed; power-loss durability is not claimed.
+- A capable Windows host is still required for the final file-symlink confinement gate.
+- Display IDs identify topology-bound geometric placements, not physical monitor devices;
+ exact Windows Task View virtual-desktop selection is not supported.
+- Repository-wide non-live L3 and all four installed-command E2E suites completed for
+ this prerelease; those results do not substitute for the blocked environment gates
+ above.
+
## Documentation
- [Documentation index](docs/README.md)
@@ -274,18 +316,14 @@ Report suspected vulnerabilities privately according to [SECURITY.md](SECURITY.m
Do not open a public issue containing captures, typed text, credentials, private `.cu/`
state, helper paths, process IDs, or window handles.
-## Preview Limitations
-
-- Unrestricted full-desktop observation is not yet release-accepted.
-- Stale or ownerless run locks are preserved and block rather than being reclaimed.
-- Process-interruption recovery is fail-closed; power-loss durability is not claimed.
-- A capable Windows host is still required for the final file-symlink confinement gate.
-- Display IDs identify topology-bound geometric placements, not physical monitor devices;
- exact Windows Task View virtual-desktop selection is not supported.
-- Repository-wide non-live L3 and all four installed-command E2E suites completed for
- this prerelease; those results do not substitute for the blocked environment gates
- above.
-
## License
Licensed under the [MIT License](LICENSE).
+
+---
+
+
+
+**Observe first. Act within evidence. Never replay uncertainty.**
+
+
diff --git a/assets/cu-title.png b/assets/cu-title.png
new file mode 100644
index 0000000..7f003e0
Binary files /dev/null and b/assets/cu-title.png differ