From b47128f89690775284f69fe97b98ddaf1aff875b Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:48:59 +0330
Subject: [PATCH 01/17] docs: establish Codectx ambient HUD identity

---
 README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 75 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index c9df5ca..353a53d 100644
--- a/README.md
+++ b/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.

From b0d206b45194717fba7d2d370705db97578ca49b Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:49:56 +0330
Subject: [PATCH 02/17] docs: add canonical Codectx HUD direction

---
 docs/codectx-hud-v0/README.md | 313 ++++++++++++++++++++++++++++++++++
 1 file changed, 313 insertions(+)
 create mode 100644 docs/codectx-hud-v0/README.md

diff --git a/docs/codectx-hud-v0/README.md b/docs/codectx-hud-v0/README.md
new file mode 100644
index 0000000..2b66243
--- /dev/null
+++ b/docs/codectx-hud-v0/README.md
@@ -0,0 +1,313 @@
+# Codectx HUD Direction v0
+
+## Status
+
+```yaml
+status: canonical-direction
+stage: identity-without-behavior-change
+implementation_claim: false
+compatibility_migration: deferred
+```
+
+Codectx is an always-present contextual HUD for humans, virtual agents, and coding tools.
+
+Its purpose is to reduce context acquisition from an explicit interaction into perception. A worker should normally be able to glance at the current projection and continue acting without opening a separate application, navigating through state, or reconstructing why the current work matters.
+
+The current deterministic repository context compiler remains accepted. It becomes Codectx's first proven lens and explicit CLI surface rather than the complete definition of the product.
+
+## Canonical concepts
+
+### Codectx
+
+The complete ambient context and attention system.
+
+Codectx does not own all underlying truth. It observes, receives, derives, prioritizes, and presents bounded projections while preserving source authority, freshness, and epistemic status.
+
+### HUD
+
+The continuously available presentation layer through which a worker perceives relevant operational context.
+
+A HUD should normally collapse healthy state and expand only what requires attention. It is not a dashboard that occupies attention merely to celebrate the existence of telemetry.
+
+### Lens
+
+A bounded context provider.
+
+A lens observes or receives one class of source material and emits a typed projection contribution. Candidate lenses include:
+
+- repository and Git state;
+- focus and scope;
+- proof and evidence status;
+- Orb identity, contacts, capabilities, and commitments;
+- Ctudio domain authority;
+- deployment and runtime health;
+- communication and reviewer activity.
+
+A lens does not become authority for the source it observes.
+
+The current `ContextPacket v1` implementation is the compatibility contract of the repository lens.
+
+### Compositor
+
+The component that combines lens contributions into the current visible projection.
+
+The compositor is responsible for:
+
+- priority and attention ordering;
+- visibility and collapse rules;
+- conflict and contradiction presentation;
+- focus and pinning;
+- surface-independent projection state;
+- preserving source, freshness, and epistemic distinctions;
+- deciding what is visible now without inventing facts.
+
+The compositor does not authorize effects, resolve domain truth, or silently discard mandatory warnings.
+
+### Projection
+
+The current composed state presented to a worker or machine consumer.
+
+A projection may be rendered through an ambient HUD, terminal, structured API, reviewer view, handoff packet, Unreal surface, desktop overlay, or another bounded surface.
+
+### Attention item
+
+A projection contribution that deserves explicit awareness because it is relevant, changed, contradictory, risky, blocked, stale, or awaiting a decision.
+
+Healthy state should usually collapse. Attention is a scarce resource, a fact software has historically treated as an exciting challenge to defeat.
+
+### Move
+
+An explicit structured change to Codectx focus, visibility, or interpretation state.
+
+Candidate moves include:
+
+- focus;
+- pin;
+- dismiss;
+- acknowledge;
+- expand;
+- hide;
+- switch lens;
+- declare deviation;
+- change active context.
+
+A move is not merely cosmetic when it changes durable or shared context. The host runtime may retain it as an event when continuity requires that behavior.
+
+### Surface
+
+A renderer or interaction endpoint for a projection.
+
+The CLI is the current explicit surface. Future surfaces may be ambient, graphical, spatial, embedded, or machine-facing without becoming separate sources of truth.
+
+### Host runtime or device
+
+The environment that supplies lifecycle, subscriptions, event delivery, persistence, identity, and capability boundaries for Codectx.
+
+Orb is the primary intended durable host device. Codex or another agent runtime may host Codectx more locally when an Orb is absent or when the HUD must follow a bearer directly.
+
+### Codectx App
+
+The installable host integration component for Codectx.
+
+A Codectx App may be installed by Orb, Codex, or another accepted runtime. It manages the compositor inside that host environment and connects Codectx to runtime-owned services.
+
+Its responsibilities may include:
+
+- starting, suspending, resuming, and stopping the compositor;
+- registering and configuring lenses;
+- subscribing to host events and context sources;
+- translating host capabilities into bounded Codectx inputs;
+- delivering projections to available surfaces;
+- accepting explicit Codectx moves;
+- retaining or forwarding move and attention state when the host owns continuity;
+- exposing health and diagnostic state for the compositor.
+
+The Codectx App does not turn the compositor into Orb, Codex, or a general workflow runtime. It is an adapter and lifecycle owner inside the host.
+
+```text
+Orb or Codex runtime
+        |
+        | installs and supervises
+        v
+   Codectx App
+        |
+        | manages
+        v
+ Codectx compositor
+        |
+        | composes
+        v
+ lenses -> projection -> surfaces
+```
+
+A host-specific Codectx App may adapt to one runtime, while the compositor and lens contracts remain host-neutral.
+
+## Context origins
+
+Codectx must preserve the origin of state.
+
+### Derived
+
+Computed from observed sources.
+
+Examples:
+
+- Git change classification;
+- applicable repository commands;
+- attention derived from unexpected paths;
+- a collapsed healthy state.
+
+### Managed
+
+Supplied or required by a runtime, device, authority, or policy source.
+
+Examples:
+
+- capability expiry from Orb;
+- mandatory security warnings;
+- runtime health;
+- contact or commitment notifications;
+- Ctudio design authority.
+
+### Explicit
+
+Changed by a deliberate human or bearer move.
+
+Examples:
+
+- selected focus;
+- pinned item;
+- acknowledged warning;
+- declared deviation;
+- chosen lens or visibility state.
+
+Derived, managed, and explicit state may coexist, but must not be silently collapsed into one undifferentiated fact.
+
+## Current implementation mapping
+
+```text
+ContextPacket v1
+  repository-lens compatibility projection
+
+codectx
+  explicit CLI HUD surface
+
+codectx --json
+  machine projection surface
+
+codectx review
+  expanded reviewer surface
+
+codectx handoff
+  durable projection artifact
+
+codectx-legacy
+  preserved historical session and event runtime
+```
+
+The existing `AgentSurface` work in `codectx-core` is useful migration material for attention state and action affordances. Its historical stop-readiness and proof semantics must not be silently promoted into universal compositor authority.
+
+## Authority boundary
+
+Codectx owns:
+
+- projection contracts;
+- lens composition rules;
+- attention and visibility state;
+- source attribution and epistemic distinctions;
+- surface-independent presentation state;
+- explicit Codectx moves.
+
+Codectx does not own:
+
+- Git repository truth;
+- Orb identity, relationships, capabilities, or durable communication;
+- Runseal closure and evidence authority;
+- Ctudio domain authority;
+- deployment or runtime truth;
+- completion, approval, or effect authorization merely because it displays them.
+
+## Relationship with Orb
+
+```text
+Orb
+  durable personal device, identity, relationships, apps, capabilities,
+  communication, commitments, and history
+
+Codectx App for Orb
+  installed runtime integration and compositor lifecycle owner
+
+Codectx
+  ambient context and attention HUD
+
+Codex or another bearer
+  worker that sees and acts through the projection
+```
+
+Orb may retain app installation, durable moves, subscriptions, and continuity across bearer replacement. Codectx reconstructs the appropriate projection for the current bearer from bounded sources.
+
+## Compatibility rule
+
+Existing contracts remain authoritative for current consumers until explicit successors are introduced.
+
+In particular:
+
+- `ContextPacket v1` remains unchanged and continues to describe the repository lens;
+- the current CLI commands and JSON output remain unchanged;
+- focus-file semantics remain unchanged;
+- Runseal records remain external claims with unknown freshness;
+- legacy protocol and session commands remain compatibility surfaces;
+- `.orb/project.toml` remains a distribution and integration contract, not proof that Codectx is already an Orb-native app.
+
+The broader HUD direction must not be backported into v1 packets by silently changing their meaning.
+
+## Migration stages
+
+### Step 1: identity without behavior change
+
+- establish this canonical HUD definition;
+- reclassify the current compiler as the repository lens;
+- define the Codectx App and host-runtime boundary;
+- mark connected work as compatible but vocabulary-transitional;
+- preserve current CLI, packet, and interoperability contracts.
+
+### Step 2: additive compositor and lens seams
+
+- introduce host-neutral lens contribution and projection contracts;
+- introduce a compositor boundary above the repository lens;
+- preserve `ContextPacket v1` through an adapter;
+- define one in-process host adapter before Orb or Codex-specific lifecycle work.
+
+### Step 3: runtime-hosted ambient proof
+
+- install a Codectx App into Orb or another accepted runtime;
+- subscribe to at least two bounded lenses;
+- maintain a live projection as context changes;
+- accept one explicit move such as focus, pin, or acknowledge;
+- restore relevant projection state after bearer or compositor restart;
+- prove that healthy state collapses and urgent state becomes visible without manual navigation.
+
+## Design constraints
+
+1. Context is a projection, not domain authority.
+2. Codectx should reduce context acquisition from interaction into perception.
+3. Healthy state collapses; attention expands only when warranted.
+4. Lenses preserve source, freshness, and epistemic distinctions.
+5. The compositor does not manufacture authorization or completion.
+6. The Codectx App manages lifecycle and host integration, not domain truth.
+7. The compositor and lens contracts remain host-neutral.
+8. Orb, Codex, and other runtimes expose only explicit bounded capabilities.
+9. Explicit moves remain inspectable and event-shaped when they affect durable or shared context.
+10. Existing v1 contracts change only through versioned successors and migration proof.
+
+## Current non-goals
+
+- implementing the compositor in Step 1;
+- adding a daemon or database;
+- adding Orb or Codex runtime dependencies;
+- changing `ContextPacket v1`;
+- renaming current CLI commands;
+- converting historical `AgentSurface` semantics into universal HUD authority;
+- building a plugin marketplace;
+- treating semantic retrieval as accepted truth;
+- claiming that the Codectx App lifecycle already exists.

From a5366b72a912d68eae94ff4ca608538b25c25d37 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:50:20 +0330
Subject: [PATCH 03/17] docs: preserve ContextPacket as repository lens
 contract

---
 docs/context-packet-v1.md | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/docs/context-packet-v1.md b/docs/context-packet-v1.md
index 2a1fcb4..8eb36f9 100644
--- a/docs/context-packet-v1.md
+++ b/docs/context-packet-v1.md
@@ -1,10 +1,22 @@
 # Context Packet v1
 
+> **Codectx HUD direction marker**
+>
+> ```yaml
+> status: implemented-compatibility-contract
+> vocabulary_generation: repository-context-v1
+> target_position: repository-lens-projection
+> contract_changes: deferred
+> canonical_direction: docs/codectx-hud-v0/README.md
+> ```
+>
+> This contract remains authoritative for the current repository lens. The broader Codectx HUD direction does not redefine this packet as a universal compositor or runtime schema.
+
 Status: implemented MVP contract.
 
 The context packet is Codectx's deterministic intermediate representation between repository observation and human or agent-facing rendering.
 
-It is a projection. It is not a closure, issue, task database, proof ledger, or authorization decision.
+It is a projection. It is not a closure, issue, task database, proof ledger, authorization decision, universal HUD model, or host-runtime protocol.
 
 ## Shape
 
@@ -31,6 +43,7 @@ ContextPacket {
 - Change relevance is a projection, not permission.
 - Runseal status remains an external claim.
 - Suggested actions are presentation affordances, not completion decisions.
+- A host runtime may transport or render this packet without acquiring authority over its observed sources.
 
 ## Focus
 
@@ -89,6 +102,10 @@ codectx handoff  durable JSON packet
 
 Renderers may omit detail for brevity. They may not invent facts absent from the packet.
 
+In the broader direction, these are explicit surfaces for the repository lens. A future compositor may adapt this packet into a larger projection, but must preserve source and epistemic boundaries.
+
 ## Evolution
 
-A v2 schema is justified only when a real consumer cannot perform a useful bounded workflow with v1. Decorative metadata does not qualify, despite its thriving industry lobby.
+A v2 schema is justified only when a real repository-lens consumer cannot perform a useful bounded workflow with v1.
+
+A host-neutral lens contribution, compositor projection, or Codectx App protocol should be introduced as a distinct contract unless evidence proves it is truly the next version of this repository packet. Decorative metadata still does not qualify, despite its thriving industry lobby.

From 1bf35486208630ef5f764c5383b2f018c96fa918 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:50:58 +0330
Subject: [PATCH 04/17] docs: map implementation to HUD direction

---
 docs/implementation-status.md | 71 ++++++++++++++++++++++++++++++++++-
 1 file changed, 70 insertions(+), 1 deletion(-)

diff --git a/docs/implementation-status.md b/docs/implementation-status.md
index 1eb431f..c87045d 100644
--- a/docs/implementation-status.md
+++ b/docs/implementation-status.md
@@ -1,5 +1,18 @@
 # Implementation Status
 
+## Direction status
+
+```yaml
+canonical_direction: docs/codectx-hud-v0/README.md
+current_stage: identity-without-behavior-change
+current_product_slice: repository-lens
+ambient_compositor: not-implemented
+codectx-app: not-implemented
+host-runtime-integration: not-implemented
+```
+
+The current public implementation remains valid as Codectx's first repository lens and explicit CLI surface. The ambient HUD direction does not imply that a compositor, Codectx App, Orb integration, or continuously hosted runtime already exists.
+
 ## Current public MVP
 
 Implemented:
@@ -15,6 +28,16 @@ Implemented:
 - preserved legacy session binary and compatibility forwarding;
 - Rust contract tests, CLI integration tests, CI, and a committed fixture-backed demo.
 
+These capabilities form the current repository lens:
+
+```text
+repository sources
+      ↓
+ContextPacket v1
+      ↓
+CLI HUD / JSON / review / handoff
+```
+
 ## Presentation witness
 
 `fixtures/context-demo/repository` is the public communication fixture. `scripts/demo.sh` commits its baseline, applies expected, supporting, and unexpected changes, and verifies:
@@ -54,18 +77,64 @@ The original public session prototype remains available through `codectx-legacy`
 
 Legacy proof recording is an attestation mechanism. It is not state-bound evidence.
 
+The historical `AgentSurface` model is useful migration material for attention state and action affordances. Its completion and proof semantics are not accepted as universal compositor authority.
+
+## Directional mapping
+
+```text
+Current repository observer
+  -> repository lens
+
+ContextPacket v1
+  -> repository-lens compatibility projection
+
+codectx CLI
+  -> explicit HUD shell
+
+future Codectx App
+  -> installable host integration and compositor lifecycle manager
+
+future compositor
+  -> host-neutral lens composition and attention engine
+
+Orb or Codex
+  -> possible host runtime or device
+```
+
+This mapping does not authorize code motion or contract changes in Step 1.
+
 ## Not implemented
 
+- ambient compositor runtime;
+- host-neutral lens registration or contribution contracts;
+- Codectx App installation or lifecycle;
+- Orb or Codex runtime integration;
+- continuous event subscriptions;
+- projection restoration across bearer or compositor restart;
 - closure identity, evaluation, or resolution;
 - state-bound evidence execution;
 - evidence invalidation from source changes;
 - generic risk assessment;
 - autonomous coding or workflow orchestration;
 - repository indexing or RAG;
-- daemon, database, or plugin framework.
+- daemon, database, or plugin marketplace.
 
 Closure and evidence authority belong to Runseal.
 
+## Step 1 compatibility boundary
+
+The following remain unchanged:
+
+- `ContextPacket v1` shape and semantics;
+- CLI commands and output contracts;
+- focus-file behavior;
+- handoff path and JSON determinism;
+- Runseal external-claim treatment;
+- legacy command forwarding;
+- `.orb/project.toml` product and distribution facts.
+
+Future compositor, lens, move, and Codectx App contracts must be introduced additively and must not silently reinterpret these surfaces.
+
 ## Proof
 
 ```bash

From e1eaaa0295b1e6fd40025deabf4aede75b8216d6 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:51:27 +0330
Subject: [PATCH 05/17] docs: define Codectx App host boundary

---
 docs/codectx-app-v0.md | 45 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 docs/codectx-app-v0.md

diff --git a/docs/codectx-app-v0.md b/docs/codectx-app-v0.md
new file mode 100644
index 0000000..c7ddb00
--- /dev/null
+++ b/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.

From c47410fb08c4b21f90be3a6d281327d88399dc75 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:51:35 +0330
Subject: [PATCH 06/17] docs: record Codectx Step 1 scope

---
 docs/step-1-scope.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 docs/step-1-scope.md

diff --git a/docs/step-1-scope.md b/docs/step-1-scope.md
new file mode 100644
index 0000000..a26f578
--- /dev/null
+++ b/docs/step-1-scope.md
@@ -0,0 +1,15 @@
+# Codectx Step 1 Scope
+
+This document records the boundary of the ambient-HUD direction change.
+
+Step 1 changes product identity and documentation only. It does not change Rust code, crate layout, CLI behavior, JSON output, `ContextPacket v1`, focus semantics, legacy forwarding, Runseal authority, or the Orb project manifest.
+
+Changed direction documents:
+
+- `README.md`;
+- `docs/codectx-hud-v0/README.md`;
+- `docs/codectx-app-v0.md`;
+- `docs/context-packet-v1.md`;
+- `docs/implementation-status.md`.
+
+The next implementation stage may introduce additive compositor and lens seams, but only after this identity package is reviewed.

From 150dd915432088f680fb0e6749efcdb0e0f54f9f Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:51:44 +0330
Subject: [PATCH 07/17] docs: index Codectx direction documents

---
 docs/README.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 docs/README.md

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..8186ba5
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,7 @@
+# Codectx Documentation
+
+- [`codectx-hud-v0/README.md`](codectx-hud-v0/README.md): canonical ambient HUD direction.
+- [`codectx-app-v0.md`](codectx-app-v0.md): installable host integration and compositor lifecycle boundary.
+- [`context-packet-v1.md`](context-packet-v1.md): current repository-lens compatibility contract.
+- [`implementation-status.md`](implementation-status.md): implemented and deferred capabilities.
+- [`step-1-scope.md`](step-1-scope.md): documentation-only migration boundary.

From 5fb480689c255dceb6c409202e0bee59d5bbe929 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:51:50 +0330
Subject: [PATCH 08/17] docs: mark canonical Codectx direction

---
 docs/.direction-marker | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 docs/.direction-marker

diff --git a/docs/.direction-marker b/docs/.direction-marker
new file mode 100644
index 0000000..1c4f429
--- /dev/null
+++ b/docs/.direction-marker
@@ -0,0 +1 @@
+codectx-hud-v0

From b551629dae192a8523281905da42787675dcd324 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:52:04 +0330
Subject: [PATCH 09/17] docs: remove redundant Step 1 bookkeeping

---
 docs/step-1-scope.md | 15 ---------------
 1 file changed, 15 deletions(-)
 delete mode 100644 docs/step-1-scope.md

diff --git a/docs/step-1-scope.md b/docs/step-1-scope.md
deleted file mode 100644
index a26f578..0000000
--- a/docs/step-1-scope.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# Codectx Step 1 Scope
-
-This document records the boundary of the ambient-HUD direction change.
-
-Step 1 changes product identity and documentation only. It does not change Rust code, crate layout, CLI behavior, JSON output, `ContextPacket v1`, focus semantics, legacy forwarding, Runseal authority, or the Orb project manifest.
-
-Changed direction documents:
-
-- `README.md`;
-- `docs/codectx-hud-v0/README.md`;
-- `docs/codectx-app-v0.md`;
-- `docs/context-packet-v1.md`;
-- `docs/implementation-status.md`.
-
-The next implementation stage may introduce additive compositor and lens seams, but only after this identity package is reviewed.

From a91a44f870b173973cfb1c00aeafbd54cce017e5 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:52:09 +0330
Subject: [PATCH 10/17] docs: remove redundant direction index

---
 docs/README.md | 7 -------
 1 file changed, 7 deletions(-)
 delete mode 100644 docs/README.md

diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index 8186ba5..0000000
--- a/docs/README.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Codectx Documentation
-
-- [`codectx-hud-v0/README.md`](codectx-hud-v0/README.md): canonical ambient HUD direction.
-- [`codectx-app-v0.md`](codectx-app-v0.md): installable host integration and compositor lifecycle boundary.
-- [`context-packet-v1.md`](context-packet-v1.md): current repository-lens compatibility contract.
-- [`implementation-status.md`](implementation-status.md): implemented and deferred capabilities.
-- [`step-1-scope.md`](step-1-scope.md): documentation-only migration boundary.

From e8640105a5d2ac05289b03d2d81898f5902223c6 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:52:15 +0330
Subject: [PATCH 11/17] docs: remove redundant direction marker

---
 docs/.direction-marker | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 docs/.direction-marker

diff --git a/docs/.direction-marker b/docs/.direction-marker
deleted file mode 100644
index 1c4f429..0000000
--- a/docs/.direction-marker
+++ /dev/null
@@ -1 +0,0 @@
-codectx-hud-v0

From 4f02c644ab3ce13667f5927dc11d9917c743dcbd Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:52:24 +0330
Subject: [PATCH 12/17] chore: preserve docs directory

---
 docs/.keep | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 docs/.keep

diff --git a/docs/.keep b/docs/.keep
new file mode 100644
index 0000000..e69de29

From 29bfce8d03d4281c828a86b8848328ceeda31d62 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:52:33 +0330
Subject: [PATCH 13/17] chore: remove empty placeholder

---
 docs/.keep | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 delete mode 100644 docs/.keep

diff --git a/docs/.keep b/docs/.keep
deleted file mode 100644
index e69de29..0000000

From db5425a217361e8a95433dd991f5f77a337153b7 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:52:41 +0330
Subject: [PATCH 14/17] chore: stage PR metadata

---
 docs/pr-body.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 docs/pr-body.md

diff --git a/docs/pr-body.md b/docs/pr-body.md
new file mode 100644
index 0000000..ca4a8f8
--- /dev/null
+++ b/docs/pr-body.md
@@ -0,0 +1 @@
+temporary
\ No newline at end of file

From 355f938c98af2c4e4bd42e785ba1fcb88d993070 Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:52:55 +0330
Subject: [PATCH 15/17] chore: remove accidental scratch file

---
 docs/pr-body.md | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 docs/pr-body.md

diff --git a/docs/pr-body.md b/docs/pr-body.md
deleted file mode 100644
index ca4a8f8..0000000
--- a/docs/pr-body.md
+++ /dev/null
@@ -1 +0,0 @@
-temporary
\ No newline at end of file

From 38cb1ca5cd1ac3f725b3755812ab581951bad70a Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:53:10 +0330
Subject: [PATCH 16/17] ignore

---
 docs/ignored.tmp | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 docs/ignored.tmp

diff --git a/docs/ignored.tmp b/docs/ignored.tmp
new file mode 100644
index 0000000..8485e98
--- /dev/null
+++ b/docs/ignored.tmp
@@ -0,0 +1 @@
+ignore
\ No newline at end of file

From 0700380edc47a9e7b837a0088b02fa8b6396d83f Mon Sep 17 00:00:00 2001
From: Goudarz Firoozi <63324407+greygoody@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:53:20 +0330
Subject: [PATCH 17/17] chore: remove accidental connector scratch file

---
 docs/ignored.tmp | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 docs/ignored.tmp

diff --git a/docs/ignored.tmp b/docs/ignored.tmp
deleted file mode 100644
index 8485e98..0000000
--- a/docs/ignored.tmp
+++ /dev/null
@@ -1 +0,0 @@
-ignore
\ No newline at end of file