docs: note programmatic context injection in architecture and handoff

Author: execsumo

ARCHITECTURE.md

@@ -258,10 +258,12 @@ v1 supports **Claude Code only** (B2) — the one harness that provides the full
 
 ---
 
-## 9. Assets & generated context
+## 9. Assets & Programmatic Context Injection
 
 The Distillation Guide, the Dossier Protocol skill, and the `library.md` template are **embedded** via `go:embed` (`assets/`). `init` writes both the guide and the `skill.md` file to `~/.dossier/context/`; `context refresh` regenerates `~/.dossier/context/library.md` from the template + a live frontmatter scan. This keeps the single-binary promise — no external asset files to ship.
 
+**Programmatic Injection (Zero-Tax Architecture):** Instead of injecting the 1500-token `guide.md` into global prompts (`skill.md`) or passive lifecycle hooks where it wastes tokens on generic coding tasks, Dossier uses **active interception**. When an LLM invokes the `dossier_session` MCP tool to bind a topic, the MCP server dynamically wraps the `Service.Switch` or `Service.Active` state response in a payload that explicitly includes the full string contents of the Distillation Guide. This guarantees the LLM receives strict schema instructions *exactly* when it enters a dossier context, while maintaining zero overhead during non-dossier operations. Future iterations will apply this deterministic pattern to other operational instructions currently housed in `skill.md` to further compress global bloat.
+
 ---
 
 ## 10. Testing strategy (how the acceptance criteria get met)

HANDOFF.md

@@ -30,6 +30,7 @@ Precedence when docs disagree: `BUILD-DECISIONS.md` > `SPEC.md` (mechanics) > `P
 
 > - **Cleanup & hardening (2026-06-24):** Code-review follow-ups. (1) **Unified write path** — removed `Service.SetStatus`/`SetLead`; CLI, MCP, and TUI now route all metadata edits (status, lead, …) through `Save`, eliminating an adapter fork that violated the "thin adapters over one core.Service" rule. `Save`'s audit entry now records a field-level `field "old"→"new"` summary, and still emits a `status_changed` event (not a generic `save`) when the lifecycle status changes, preserving the agent-facing provenance the dedicated commands had and satisfying SPEC §300. (2) **Quality gate wired up** — added `.github/workflows/ci.yml` (gofmt + `go vet` + `go test` + the long-documented `internal/core` dependency-direction guard); removed a stray `test_glamour.go` scratch file and a gofmt-dirty commit that the gate now catches. (3) **TUI polish** — markdown renderer cached (rebuilt only on width change); hot-refresh now watches every dossier directory so the dashboard live-updates, not just the detail view; `store.Lock` simplified to a single blocking `flock.Lock`. (4) Renaming via `dossier_update` keeps the slug stable (documented in SPEC §8.1).
 > - **Simplification of Priority and Dashboard (2026-06-25):** Dropped the cumulative points-based priority scoring in favor of a clean 2x2 Eisenhower matrix (1-4: Do, Plan, Delegate, Delete) strictly mapping importance (high/low) and urgency (high/low). In the TUI dashboard, replaced the Staleness column with a 'Due' column formatted as MM/DD, and expanded the Priority column width to 12 characters to display the full Eisenhower matrix labels.
+> - **Programmatic Context Injection (2026-06-25):** Migrated from passive injection (`guide.md` printed in `session-start` or requiring an explicit file read) to active interception via the `dossier_session` MCP tool payload. When an LLM calls `dossier_session` to bind or retrieve a dossier, the MCP handler intercepts the `Service.Switch`/`Active` response and wraps it in a struct containing the state AND the full string contents of `guide.md`. This zero-tax, seamless programmatic pattern guarantees strict distillation adherence without polluting global Claude Code prompts (`skill.md`) with a 1500-token overhead on generic tasks. **Next Step:** Apply this seamless, deterministic interception pattern to other instructions (e.g., the 'Resume' section of `skill.md` itself) by dynamically injecting them in the `dossier_session` response payload to further compress global skill context bloat.
 
 All features (CLI, MCP, and Rich TUI) are fully operational, tested, and integrated.
 

README.md

@@ -48,7 +48,7 @@ Once `init` has run, Dossier works on its own:
 - **During the session**, the agent recalls, saves, searches, promotes, and switches Dossiers through MCP tools — nothing for you to remember. Switching binds *this* session (the MCP server resolves your Claude Code session automatically), so concurrent sessions can each follow a different Dossier without stepping on each other.
 - **At session end and before compaction**, hooks save the active Dossier so context isn't lost.
 
-A shipped **Distillation Guide** tells the agent *what* to keep; the hooks decide *when* to save. A **Resumption Protocol Skill** injected into Claude Code ensures the agent polls **Active Monitors** (live external links like Slack threads) upon resuming a session. There's no confirmation gate — trust comes from the fact that nothing is ever deleted (superseded content moves to the Archive and audit log) and every claim carries a source link.
+A shipped **Distillation Guide** tells the agent *what* to keep; the hooks decide *when* to save. To save tokens on your generic coding tasks, the guide isn't injected globally. Instead, Dossier uses **programmatic context injection**: the moment the agent binds a dossier via the MCP server, the server dynamically wraps its response payload with the full guide. A **Resumption Protocol Skill** injected into Claude Code ensures the agent polls **Active Monitors** (live external links like Slack threads) upon resuming a session. There's no confirmation gate — trust comes from the fact that nothing is ever deleted (superseded content moves to the Archive and audit log) and every claim carries a source link.
 
 ### From the command line