x

README.md

@@ -1,12 +1,32 @@
 # Codectx
 
-**A deterministic repository context compiler for humans and coding tools.**
+**An always-present contextual HUD for humans, virtual agents, and coding tools.**
 
-Codectx observes a Git repository, combines explicit task focus with project commands and imported external signals, and emits a focused context packet for implementation, review, or handoff.
+Codectx projects the minimum operational information a worker needs to perceive its current environment, focus, constraints, risks, and available moves without stopping work to reconstruct context through a separate interface.
 
-Git remains repository authority. Codectx does not resolve external obligations, run autonomous coding loops, or silently modify implementation files.
+The current repository implements Codectx's first proven lens: deterministic repository context. It observes a Git repository, combines explicit focus with project commands and imported external signals, and emits one bounded projection for human HUD, machine consumption, review, and handoff.
 
-## Implemented MVP
+Git remains repository authority. Codectx is a projection and attention system, not a task database, proof authority, workflow orchestrator, or source of domain truth.
+
+The canonical HUD direction and migration boundaries are defined in [`docs/codectx-hud-v0/README.md`](docs/codectx-hud-v0/README.md).
+
+## Product direction
+
+```text
+World, runtime, repository, Orb, and domain sources
+                         ↓
+                  Codectx lenses
+                         ↓
+               composed projection
+                         ↓
+       ambient HUD / machine view / review / handoff
+```
+
+Codectx should eventually remain continuously available through a host runtime or device such as Orb. The worker should normally acquire context by perception rather than by opening another application and navigating to the relevant state.
+
+The current CLI remains valid. It is the first explicit shell and proof surface for the projection model, not obsolete scaffolding awaiting ceremonial deletion.
+
+## Implemented repository lens
 
 - human-readable HUD through plain `codectx`;
 - deterministic machine packet through `codectx --json`;
@@ -19,7 +39,7 @@ Git remains repository authority. Codectx does not resolve external obligations,
 - Runseal records imported as external claims with unknown freshness;
 - the earlier session runtime preserved as `codectx-legacy`.
 
-Codectx does not implement closure resolution, state-bound evidence execution, generic risk assessment, orchestration, repository indexing, a daemon, or a database.
+Codectx does not currently implement an ambient compositor runtime, continuous subscriptions, lens registration, Orb integration, closure resolution, state-bound evidence execution, generic risk assessment, orchestration, repository indexing, a daemon, or a database.
 
 ## Quickstart
 
@@ -166,7 +186,7 @@ Available commands
 }
 ```
 
-## Runseal boundary
+## Projection authority
 
 Runseal owns persistent obligations, typed conditions, evidence semantics, resolution, and regression.
 
@@ -180,11 +200,30 @@ Imported records remain external claims with unknown freshness. Codectx observes
 ```text
 Git / focus / justfile / external record
                    ↓
-             ContextPacket
+             ContextPacket v1
                    ↓
         HUD / JSON / review / handoff
 ```
 
+In the broader direction, `ContextPacket v1` becomes the compatibility contract for the repository lens. It is not silently redefined into a universal HUD schema.
+
+## Context state classes
+
+Future Codectx projections should preserve three origins:
+
+```text
+derived
+  computed from observed sources
+
+managed
+  supplied or required by a runtime, device, authority, or policy source
+
+explicit
+  changed by a deliberate user or bearer move
+```
+
+Current focus files and CLI options are explicit input. Git observations and change relevance are derived. Imported external records remain managed external claims only when their source and authority are preserved.
+
 ## v0.2 interface decisions
 
 ### Legacy commands
@@ -207,16 +246,32 @@ The primary managed destination is `.codectx/handoffs/latest.json`, and the walk
 
 ```text
 crates/codectx-core
-  Git observation, command discovery, packet construction, renderers
+  repository observation, command discovery, packet construction, renderers
 
 crates/codectx-cli
-  context-first CLI and legacy compatibility binary
+  explicit HUD shell, machine packet, review, handoff, compatibility binary
 
 crates/codectx-protocol
   historical session/event protocol used by compatibility code
 ```
 
-See [`docs/context-packet-v1.md`](docs/context-packet-v1.md) and [`docs/implementation-status.md`](docs/implementation-status.md).
+Target direction, not implemented in Step 1:
+
+```text
+Codectx lenses
+  bounded context providers
+
+Codectx compositor
+  attention, priority, visibility, and projection composition
+
+Codectx surfaces
+  ambient HUD, CLI, machine API, review, and handoff renderers
+
+Host runtime or device
+  subscriptions, lifecycle, delivery, persistence, and authority integration
+```
+
+See [`docs/context-packet-v1.md`](docs/context-packet-v1.md), [`docs/implementation-status.md`](docs/implementation-status.md), and [`docs/codectx-hud-v0/README.md`](docs/codectx-hud-v0/README.md).
 
 ## Proof
 
@@ -237,10 +292,13 @@ bash scripts/demo.sh
 ## Design rules
 
 1. Context is a projection, not domain authority.
-2. Observed, derived, external claim, and unknown remain distinct.
-3. Git stays visible and authoritative for repository state.
-4. Missing data is not fabricated.
-5. Human and machine views derive from one deterministic packet.
-6. Codectx suggests actions but does not award completion.
-7. External systems retain ownership of their semantics.
-8. Writes remain within explicit Codectx artifact boundaries.
+2. Codectx reduces context acquisition from an interaction into perception.
+3. Observed, derived, managed, explicit, external claim, and unknown remain distinguishable.
+4. Git stays visible and authoritative for repository state.
+5. Missing data is not fabricated.
+6. Human and machine views derive from bounded deterministic projections.
+7. Attention is prioritized; healthy state should collapse rather than occupy the entire field of view.
+8. Codectx suggests or exposes moves but does not award completion or manufacture authorization.
+9. External systems retain ownership of their semantics.
+10. Writes remain within explicit Codectx artifact or move boundaries.
+11. The current repository lens and ContextPacket v1 remain compatibility surfaces until versioned successors are proven.

docs/codectx-app-v0.md

@@ -0,0 +1,45 @@
+# Codectx App v0 Boundary
+
+Status: direction only; not implemented.
+
+A Codectx App is the installable integration component used by Orb, Codex, or another accepted host runtime to manage Codectx inside that environment.
+
+It owns host integration and compositor lifecycle:
+
+- install and uninstall integration state;
+- start, suspend, resume, restart, and stop the compositor;
+- register and configure lenses;
+- subscribe to host events and bounded context sources;
+- translate host capabilities into typed Codectx inputs;
+- deliver projections to available surfaces;
+- accept explicit Codectx moves;
+- retain or forward move and attention state when the host owns continuity;
+- expose compositor health and diagnostics.
+
+It does not own:
+
+- Orb identity, contacts, capabilities, communication, or history;
+- Codex execution semantics;
+- source-system domain truth;
+- approval, completion, or effect authorization;
+- the host-neutral compositor and lens contracts themselves.
+
+```text
+host runtime
+    |
+    | installs and supervises
+    v
+Codectx App
+    |
+    | manages and adapts
+    v
+Codectx compositor
+    |
+    | composes
+    v
+lenses -> projection -> surfaces
+```
+
+The first implementation should use one in-process host adapter. Orb-native and Codex-native integrations should follow only after the host-neutral compositor seam exists.
+
+This boundary supplements [`docs/codectx-hud-v0/README.md`](codectx-hud-v0/README.md) and must not change `ContextPacket v1`, current CLI behavior, or the `.orb/project.toml` contract in Step 1.