feat(embedding): an annotation loop an agent can reproduce, locate, and react to (annotkit-op6)

A host that launches many isolated instances of one binary — an HMR session
per branch, a gallery host, an inspect window per persona — could not say
which world an instance was or where its notes belonged: there is one binary
and N launches, and install() had no environment to read.

- WORLD CONTEXT on every note. An opaque [String: String] the host registers
  once and AnnotKit snapshots PER CAPTURE, so toggling dark mode between two
  notes files them under two different worlds. It reaches the agent through
  the markdown Context line, the JSON store, and annotation_get_pending.
- THE ENVIRONMENT IS THE CONFIGURATION SURFACE. AnnotationEnvironment (pure,
  takes the env as an argument) drives install(): ANNOTKIT_NOTES_MD /
  ANNOTKIT_NOTES / ANNOTKIT_EVENTS / ANNOTKIT_ROUTE / ANNOTKIT_CONTEXT*,
  fanned out through MultiSink. ANNOTKIT_NOTES names the JSON store because
  annotkit-mcp already reads that variable for that file — one variable, one
  file, both processes wired by the same env dict. Launcher context and the
  in-app provider merge with the provider winning: it is the newer
  measurement.
- A WATCHABLE STREAM. NotesFileSink writes atomically, which is what stops a
  reader seeing half a document and exactly what makes tail -f go silent. So
  JSONLEventSink appends beside it, one line per capture/edit/delete. Events
  are DERIVED by diffing each flush, not pushed per keystroke, so a woken
  reader always finds the note already in the snapshot; the diff compares the
  ENCODED record, so a scroll moving pins on screen is not an edit; and lines
  go out in one O_APPEND write(2), so a fleet can share one log.
- VALIDATED END TO END. AnnotKitEnvProbe is one embedding host with the human
  taken out (same Annotation.install path, capture driven in code).
  AgentLoopE2ETests launches two of them concurrently with nothing but an
  environment and asserts from outside the processes: context in both
  outputs, the MCP bridge serving it, a tail -F watcher woken under a second
  after capture, and no cross-writing.

Also fixed: JSONFileSink appended rather than upserted by id, so a second
press of Export put a second copy of every note in the store the agent reads.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: angusbezzina

.beads/interactions.jsonl

@@ -0,0 +1,5 @@
+{"id":"int-af6f382a5977c5caf2d2dc9e0c48a14a","kind":"field_change","created_at":"2026-08-19T21:49:47.610879Z","actor":"Angus Bezzina","issue_id":"annotkit-op6.1","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Implemented: world context on every note (provider + ANNOTKIT_CONTEXT*, per-capture snapshot, markdown/JSON/MCP), env-driven install and sink destinations (AnnotationEnvironment + MultiSink), append-only JSONL event stream (JSONLEventSink, O_APPEND, diff-per-flush), and end-to-end validation via AnnotKitEnvProbe + AgentLoopE2ETests. 264 tests pass."}}
+{"id":"int-441ae3d569178c4ef5d068ed035e2c07","kind":"field_change","created_at":"2026-08-19T21:49:47.97812Z","actor":"Angus Bezzina","issue_id":"annotkit-op6.2","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Implemented: world context on every note (provider + ANNOTKIT_CONTEXT*, per-capture snapshot, markdown/JSON/MCP), env-driven install and sink destinations (AnnotationEnvironment + MultiSink), append-only JSONL event stream (JSONLEventSink, O_APPEND, diff-per-flush), and end-to-end validation via AnnotKitEnvProbe + AgentLoopE2ETests. 264 tests pass."}}
+{"id":"int-6f3d5195f734cd5d3614c41b1f8dac01","kind":"field_change","created_at":"2026-08-19T21:49:48.345784Z","actor":"Angus Bezzina","issue_id":"annotkit-op6.3","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Implemented: world context on every note (provider + ANNOTKIT_CONTEXT*, per-capture snapshot, markdown/JSON/MCP), env-driven install and sink destinations (AnnotationEnvironment + MultiSink), append-only JSONL event stream (JSONLEventSink, O_APPEND, diff-per-flush), and end-to-end validation via AnnotKitEnvProbe + AgentLoopE2ETests. 264 tests pass."}}
+{"id":"int-f3a9554938910afe979932d09de7bc60","kind":"field_change","created_at":"2026-08-19T21:49:48.723087Z","actor":"Angus Bezzina","issue_id":"annotkit-op6.4","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Implemented: world context on every note (provider + ANNOTKIT_CONTEXT*, per-capture snapshot, markdown/JSON/MCP), env-driven install and sink destinations (AnnotationEnvironment + MultiSink), append-only JSONL event stream (JSONLEventSink, O_APPEND, diff-per-flush), and end-to-end validation via AnnotKitEnvProbe + AgentLoopE2ETests. 264 tests pass."}}
+{"id":"int-7faec6a4cf272864b5eadba0de92b0c3","kind":"field_change","created_at":"2026-08-19T21:49:49.08739Z","actor":"Angus Bezzina","issue_id":"annotkit-op6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Implemented: world context on every note (provider + ANNOTKIT_CONTEXT*, per-capture snapshot, markdown/JSON/MCP), env-driven install and sink destinations (AnnotationEnvironment + MultiSink), append-only JSONL event stream (JSONLEventSink, O_APPEND, diff-per-flush), and end-to-end validation via AnnotKitEnvProbe + AgentLoopE2ETests. 264 tests pass."}}

DECISIONS.md

@@ -424,6 +424,57 @@ selected by their rect's CENTRE falling inside the scroller's viewport, so a fra
 drawn slightly proud of a card still travels with it while chrome outside the
 scroller stays put. macOS-only: `UIScrollView` is not intercepted on iOS.
 
+## The agent-grade embedding loop (annotkit-op6)
+
+An embedding host that launches many isolated instances of one binary — an HMR
+session per branch, a gallery host, an inspect window per persona — cannot express
+"this instance is Ada's dark-mode world and its notes go here" in the app's source.
+There is one binary and N launches. Three decisions follow from that.
+
+**The environment is the configuration surface.** `Annotation.install()` reads
+`ANNOTKIT_NOTES_MD` / `ANNOTKIT_NOTES` / `ANNOTKIT_EVENTS` / `ANNOTKIT_ROUTE` /
+`ANNOTKIT_CONTEXT*` and builds its own sinks, so a launcher configures each
+instance without touching a call site (`docs/embedding.md`). `ANNOTKIT_NOTES` names
+the JSON store rather than the markdown one because `annotkit-mcp` already reads
+that variable for exactly that file: one variable, one file, both halves of the
+product pointed at it by the same env dict. Parsing lives in a pure
+`AnnotationEnvironment` taking the environment as an argument — the process env is
+neither thread-safe to mutate nor reversible between tests.
+
+**World context is opaque and snapshotted per note.** `[String: String]`, host
+vocabulary, no schema: the moment AnnotKit knows what a persona is it stops being
+embeddable in the next host. The provider is registered once at install and called
+once per capture, not once per session — appearance, window size and persona all
+change while a session is open, and a note has to record the world it was made in
+rather than the one the app booted into. Launcher context and provider context are
+merged with **the provider winning**, because it is the newer measurement.
+
+**The snapshot is unwatchable on purpose, so the stream is separate.**
+`NotesFileSink` writes atomically (rename), which is what stops a reader ever
+seeing half a document — and is exactly what makes `tail -f` go silent, since it
+follows the inode it opened. Rather than give that up, `ANNOTKIT_EVENTS` adds an
+append-only JSONL log beside it. Two rules keep the pair honest:
+
+- Events are DERIVED by diffing each flush, not pushed from each capture. Both
+  files are written by the same flush, so a watcher woken by a line always finds
+  the note already in the snapshot — the stream cannot promise something the
+  snapshot has not been given. A note typed but not sent produces no line.
+- The diff compares the ENCODED record, not the struct. The overlay's window-local
+  rects move on every scroll, and a note that merely moved on screen must not read
+  as edited. What the agent can see changed, or nothing changed.
+
+Lines are appended with a single `O_APPEND` `write(2)`, so a fleet of instances can
+share one log without tearing each other's lines and each line names its own
+world's snapshot — one `tail -F` covers the fleet. The stream is never a
+substitute for the snapshot: replayed from the beginning it would double-count
+edits and resurrect deletes, and the `process-agentation-notes` skill still reads
+the markdown.
+
+`AnnotKitEnvProbe` is one such instance with the human taken out — same
+`Annotation.install` path, capture driven in code — and `AgentLoopE2ETests` runs
+two of them at once to assert reproduce/locate/react/isolate from outside the
+processes.
+
 ## IP hygiene (carried into the F7 legal gate)
 
 - Do not copy original Agentation source (PolyForm Shield 1.0.0, non-compete). Only the `AGENTATION_NOTES.md` file format is reused, reimplemented clean-room.

PARITY.md

@@ -26,6 +26,7 @@ row; each asymmetry is closed by code or has a tracked mitigation.
 | Pin CLICK-TO-EDIT in both tools (VRT-u209) | shared: `SelectionGesture.resolve(…pins:)` consults `PinAttentionRule.pressedNote` on a press that did not travel, and the shared catcher in `OverlayView` opens the editor for `.editNote` | same | none — the whole decision is a pure rule over the notes' stored window-local anchors, so both hosts route a tap identically, and iOS gets it from the one catcher it already shares. The TRAVEL gate is the only platform-sensitive part and it is already parameterized (`SelectionGesture.minimumTravel` is 10 on iOS vs 6 on macOS, because a finger rolls several points on a deliberate tap) — so a touch that would have been a sloppy tap still opens the pin's editor rather than being read as a drag. Verification is the same asymmetry as the row above: probe 11c is macOS-only; iOS relies on the shared unit tests |
 | Recall survives a scroll | `KeyablePanel.scrollWheel` measures the translation it applied to the host's `NSScrollView` and feeds `AnnotationSession.translateNotes(by:within:)` | none | ASYMMETRIC BY THE MECHANISM: the correction is affordable on macOS only because the overlay panel already intercepts every wheel event and drives the clip itself, so the exact translation is known at the moment it is applied. iOS does not intercept `UIScrollView`, so nothing there knows a scroll happened; a note's rects stay where they were captured, which is the pre-existing behaviour `AnnotationPins` has always accepted for the pin. The RECEIVING side is shared and unit-tested (`translateNotes` is pure bookkeeping over `pending`), so an iOS host that later observes its own scrollers can adopt it without re-deriving anything |
 | Overlay excluded from element lookup | AX window identifier (`AXIntrospection.overlayWindowIdentifier`) filtered out of every `kAXWindows` read | `PassThroughWindow` TYPE identity filtered out of `IOSElementSource.windows()` | ASYMMETRIC BY NECESSITY — the hosts are different window kinds. macOS's overlay is a separate `NSPanel` matched by the identifier the controller stamps on it; iOS's is a `UIWindow` in the HOST's scene sharing its pid, so no pid/scene filter separates it and a type check (internal to the module) cannot drift the way an identifier convention can. Both filter in the shared window lookup, so snapshot / hit-test / region-anchor / marquee agree; leaving it in would let a marquee bind the user's note to AnnotKit's own UI |
+| Env-configured embedding (destinations, world context, event stream) | `Annotation.install` reads `AnnotationEnvironment` and builds `NotesFileSink`/`JSONFileSink`/`JSONLEventSink` | same | none in the code — the environment parse, the sink fan-out, the per-capture context snapshot and the JSONL diff are all platform-free, and both `install` overloads go through one `makeSession`. ASYMMETRIC VERIFICATION, recorded rather than closed: `AnnotKitEnvProbe` (and the `AgentLoopE2ETests` that launch two of it) mounts a real overlay on an `NSWindow`, so it is macOS-only for the same reason `AnnotKitProbe` is. What that leaves unverified on iOS is only the MOUNT; every file the contract produces is written by shared code covered by `AnnotationEnvironmentTests`, `EventStreamTests` and `SinkTests` |
 | Coordinate space | Cocoa bottom-left to AX top-left flip | UIKit top-left native | iOS needs no flip; shared `ScreenSpace` used only on macOS |
 | Screenshot | ScreenCaptureKit / `cacheDisplay` | `UIGraphicsImageRenderer` + `drawHierarchy` | both capture own hierarchy only; no cross-window or secure overlays |
 | Overlay host | resizing `NSPanel` (toolbar corner idle, full screen annotating) | pass-through `UIWindow` | both interactive; selection via the shared SwiftUI catcher, not a global monitor |

Package.swift

@@ -74,6 +74,18 @@ let package = Package(
                 .swiftLanguageMode(.v6)
             ]
         ),
+        // One isolated embedding host, configured from its environment alone and
+        // driven in code: mounts via `Annotation.install`, captures a note with
+        // host world context, and exports to whatever destinations the launch env
+        // named. `AgentLoopE2ETests` runs two of these side by side to assert an
+        // agent can reproduce the world, find the notes, and be woken by them.
+        .executableTarget(
+            name: "AnnotKitEnvProbe",
+            dependencies: ["AnnotKit"],
+            swiftSettings: [
+                .swiftLanguageMode(.v6)
+            ]
+        ),
         // Off-screen overlay diagnostic harness. Unlike AnnotKitProbe (which only
         // exercises the IDLE corner panel), this one calls `Annotation.install()`
         // then `Annotation.start()` so the child panel EXPANDS to the full host

README.md

@@ -37,6 +37,15 @@ ContentView()
 Annotation.install(sink: ClipboardSink(format: .json))
 ```
 
+Register a **world-context provider** and every captured note snapshots it, so an
+agent can put back the world the note was made in instead of guessing:
+
+```swift
+Annotation.install(
+    context: { ["persona": currentPersona, "appearance": appearanceName] }
+)
+```
+
 ## How it works
 
 - **macOS** queries the app's own accessibility tree (the only strategy that
@@ -68,13 +77,40 @@ swift run annotkit-mcp path/to/AGENTATION_NOTES.json
 
 Tools: `annotation_get_pending`, `annotation_resolve`.
 
+## Multi-instance hosts
+
+A host that launches many isolated instances of one binary — a design loop with an
+HMR session per branch, a gallery, an inspect window per persona — configures each
+of them from the launch environment alone, with no change to the app's call site:
+
+```sh
+ANNOTKIT_NOTES_MD=$WORLD/notes.md \
+ANNOTKIT_NOTES=$WORLD/notes.json \
+ANNOTKIT_EVENTS=$WORLD/events.jsonl \
+ANNOTKIT_CONTEXT_PERSONA=ada \
+  ./MyApp
+```
+
+`ANNOTKIT_EVENTS` adds an append-only JSONL log beside the snapshot — one line per
+capture, edit and delete — because the snapshot itself is written atomically and
+so cannot be followed with `tail -f`. An agent watches the stream and reads the
+snapshot the line names:
+
+```sh
+tail -F "$WORLD/events.jsonl" | while read -r line; do … done
+```
+
+Full contract, including how launcher context and the in-app provider merge:
+[`docs/embedding.md`](docs/embedding.md).
+
 ## Build
 
 ```sh
 swift build
 swift test
-swift run AnnotKitProbe   # live macOS smoke test
-swift run AnnotKitDemo    # interactive demo app (overlay mounted; good for recordings)
+swift run AnnotKitProbe     # live macOS smoke test
+swift run AnnotKitDemo      # interactive demo app (overlay mounted; good for recordings)
+swift run AnnotKitEnvProbe  # one env-configured embedding host, driven in code
 ```
 
 Swift 6 (strict concurrency), macOS 15+, iOS 17+.