@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/CURRENT_STATE.md

@@ -1,15 +1,26 @@
 # Current State
 
-v0.8.1 is released and published as `@dailephd/my-frontend-observer@0.8.1`.
-Project aliases, `init`, `capture`, project-aware `view`, and `check`
-orchestration are implemented and MIT licensed.
-
-The project is published at package version `0.8.1` (roadmap v0.8.1,
-Interactive Local Observation Viewer; observation schema `1.2.0`; comparison
-schema `1.0.0`; frontend contract schema `1.0.0`; evaluation artifact schema
-`1.0.0`; bounded-agent-context schema `1.0.0`; external-reference schema
-`1.0.0` - no schema version changed for v0.8) - see "v0.8 status" below for
-the final, complete v0.8 state.
+v0.9.0 is released and published as `@dailephd/my-frontend-observer@0.9.0`.
+v0.9 (Human Visual Annotation and Design-Intent Capture) adds structured visual
+annotation to the project-aware viewer. It passed integrated real-Chromium
+acceptance and final exact-candidate pre-release readiness on Windows, Linux
+and macOS, including all four tutorials. The viewer protocol is `1.3.0` and the
+visual annotation schema is `1.0.0`. Project aliases, `init`, `capture`,
+project-aware `view`, and `check` orchestration from v0.8.1 remain implemented,
+and the package is MIT licensed. The
+repository also holds a deterministic demo and four tutorial scenarios for
+v0.9, recorded by the external `@dailephd/my-dev-kit-lab@0.4.9` tool. See
+"v0.9 status" below.
+
+The project is published at package version `0.9.0` (roadmap v0.9, Human
+Visual Annotation and Design-Intent Capture; observation schema `1.2.0`;
+comparison schema `1.0.0`; frontend contract schema `1.0.0`; evaluation
+artifact schema `1.0.0`; bounded-agent-context schema `1.0.0`;
+external-reference schema `1.0.0`; visual annotation schema `1.0.0`). v0.9.0
+added the visual annotation schema and did not change any other canonical
+evidence schema version. v0.8.1 did not change any canonical evidence schema
+version either; see "v0.8 status" below for the final, complete v0.8 viewer
+state.
 
 v0.8 (Interactive Local Observation Viewer) is fully implemented, tested,
 formally cross-platform/security validated, and released. All eight v0.8
@@ -38,13 +49,14 @@ The retained repository contains:
   and standardized documentation.
 
 The package bin (`src/cli.ts`) now exposes the real current public CLI
-surface described below - the five commands released through `0.6.0`
+surface described below: the five low-level commands released through `0.6.0`
 (`observe`, `compare`, `approve-baseline`, `save-change-contract`,
-`evaluate-contract`) plus three additional commands released as part of
-`0.7.0` (`import-reference`, `approve-reference`,
-`evaluate-reference-fidelity` - see "v0.7 Prompt 1/6 status" below) - while
-remaining a thin parsing/dispatch/presentation boundary; it is no longer the
-not-implemented placeholder.
+`evaluate-contract`); three reference commands released in `0.7.0`
+(`import-reference`, `approve-reference`, `evaluate-reference-fidelity`);
+`view`, released in `0.8.0`; and the v0.8.1 high-level `init`, `capture`, and
+`check` commands. v0.8.1 also makes `view` project-aware while preserving its
+standalone `--root` form. `src/cli.ts` remains a thin parsing/dispatch/
+presentation boundary; it is no longer the not-implemented placeholder.
 
 ## v0.1 progress (Batch 1–6; implemented and released as 0.1.0)
 
@@ -546,13 +558,11 @@ binding, or fidelity evaluation yet.
   extends outside the owning image's bounds.
 - **Domain** (`src/domain/externalReferenceRegionRelationships.ts`): reuses
   the exact pure geometry predicates `deriveLayoutRelationships` uses for
-  runtime targets (now exported additively from `relationships.ts`, formulas
-  unchanged) to derive the six geometry-only relationship families
-  (horizontal order, vertical order, area overlap, relative width, geometric
-  fit, vertical sequencing) between reference regions. Not persisted -
-  `deriveReferenceRegionRelationships()` is a pure function callers invoke
-  on demand against an artifact's own `regions`, bounded at
-  `MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS`.
+  runtime targets (now exported additively) from `relationships.ts` rather
+  than reimplemented, so reference-region geometry and runtime-target
+  geometry can never diverge on the same underlying formula; only the
+  geometry-only relationship families apply, since a static image exposes
+  no DOM, scroll, or viewport evidence.
 - **Schema**: `ExternalReferenceArtifact` gained one additive, optional
   `regions?: ReferenceRegion[]` field. No schema version bump
   (`EXTERNAL_REFERENCE_SCHEMA_VERSION` remains `'1.0.0'`) - every Prompt 1
@@ -980,7 +990,9 @@ most one designated server-side call site, and several (`compareObservations`,
 never called by the viewer at all. The viewer never runs
 `@dailephd/my-dev-kit`, never mutates target source or any Observer
 artifact, never persists a new viewer-owned evidence family, and every route
-rejects non-`GET`/`HEAD` methods.
+rejects non-`GET`/`HEAD` methods. (That was the complete v0.8 surface. v0.9
+later adds exactly three project-aware authoring `POST` routes. See "v0.9
+status" below.)
 
 **Validated on the canonical worktree**: `npm run typecheck`, `npm run
 lint`, `npm test`, `npm run build`, `npm run check:docs`, `npm run
@@ -998,25 +1010,132 @@ viewer surface both passed - see the readiness report above, including the
 one security finding it found and fixed (a symlinked-media evidence-root
 escape in the viewer's media route).
 
+## v0.9 status (Human Visual Annotation and Design-Intent Capture) - released as 0.9.0
+
+v0.9 is implemented against the frozen plan
+`docs/plans/v0.9-implementation-plan.md` and released as
+`@dailephd/my-frontend-observer@0.9.0`.
+
+- **Prompt 1** (`docs/reports/v0.9-batch1-visual-annotation-foundation.md`)
+  added the `VisualAnnotationArtifact` domain (schema `1.0.0`), structured
+  point/rectangle/line/arrow/note marks, runtime and reference coordinate
+  spaces, explicit associations, candidate/confirmed interpretation,
+  deterministic identity, the atomic writer, the canonical reader, the
+  persistence service, and the derived overlay SVG.
+- **Prompt 2**
+  (`docs/reports/v0.9-batch2-viewer-annotation-authoring-boundary.md`) added
+  viewer discovery of annotations, the source-resolving annotation view
+  route, the verified overlay media role, and the project-aware authoring
+  boundary with `POST /api/annotations`. `view --root` stays read-only.
+- **Prompt 3**
+  (`docs/reports/v0.9-batch3-runtime-screenshot-annotation-authoring.md`)
+  added runtime screenshot annotation in runtime CSS pixels with zoom, pan,
+  keyboard selection, save, reload, revisions, and stale-parent conflicts.
+- **Prompt 4**
+  (`docs/reports/v0.9-batch4-external-reference-annotation-authoring.md`)
+  added external-reference annotation in reference-image pixels, candidate
+  region create and refine proposals, candidate reference requirements, and
+  informational and asset-sensitive intent.
+- **Prompt 5**
+  (`docs/reports/v0.9-batch5-runtime-intent-contract-promotion.md`) added
+  runtime intent, explicit confirmation, promotion of selected confirmed
+  `move`/`resize`/`preserve` intent into a canonical per-change contract
+  (`POST /api/annotations/:handle/promote-contract`), optional explicit
+  project contract activation, and `.tmp-*` discovery exclusion. Confirmed
+  `remove` intent is honestly non-promotable.
+- **Prompt 6** (`docs/reports/v0.9-batch6-reference-materialization.md`)
+  added materialization of selected confirmed reference regions and
+  requirements into a new imported external-reference revision
+  (`POST /api/annotations/:handle/materialize-reference`). The source is never
+  changed and nothing is approved automatically.
+- **Prompt 7** (`docs/reports/v0.9-batch7-integrated-acceptance.md`) added the
+  integrated real-Chromium acceptance suite
+  (`tests/browser/v09IntegratedAcceptance.test.ts`), the packed installed
+  annotation smoke (`scripts/ci/runPackedV09AnnotationSmoke.mjs`), its step in
+  the pre-release readiness matrix, and this documentation reconciliation.
+
+Current versions: package `0.9.0`, viewer protocol `1.3.0`, visual annotation
+schema `1.0.0`, frontend contract schema `1.0.0`, external-reference schema
+`1.0.0`. No other schema changed.
+
+Invariants: annotations are evidence, not contracts. Only selected confirmed
+supported intent is promoted or materialized, always through the existing
+canonical contract and external-reference services. The existing contract,
+reference relationship, adequacy, and fidelity evaluators remain the only
+source of verdicts. Observer never edits target source, never approves a
+baseline or reference automatically, and never updates project reference
+acceptance.
+
+Validation state: the full local validation suite, the integrated acceptance
+suite, and all three packed installed-candidate smokes passed locally on
+Windows. See the Prompt 7 report for exact results. A cross-platform
+pre-release readiness run passed on Windows, Linux, and macOS for the Prompt 7
+commit `a78a058` (`docs/reports/v0.9-pre-release-readiness.md`). That run is
+historical evidence only. It did not contain the demo and tutorial commits
+described below, so it is not readiness evidence for the final candidate.
+
+### v0.9 demo and tutorials (release support, not product behavior)
+
+- **Demo foundation** (commit `59ae009`,
+  `docs/reports/v0.9-demo-foundation.md`): a deterministic demo application
+  in `examples/v09-demo/` with ten stable region names, nine frozen states, a
+  loopback-only demo server, a disposable-target materializer, and a fixed
+  1440x900 reference PNG.
+- **Tutorial integration** (commit `6895b30`,
+  `docs/reports/v0.9-tutorial-integration.md`): four `TutorialScenarioV1`
+  scenarios in `examples/v09-demo/tutorials/`, a per-run target-contract
+  generator, and a prepare command that builds each disposable target through
+  the canonical `init`, `capture`, contract, and reference commands. The only
+  product change was two optional `data-testid` attributes on the viewer
+  drawing surfaces.
+- **End-to-end acceptance**
+  (`docs/reports/v0.9-tutorial-end-to-end-acceptance.md`): all four tutorials
+  regenerated from clean targets with `@dailephd/my-dev-kit-lab@0.4.9`,
+  structural and content acceptance, canonical evidence checks, and a full
+  local regression. Scenario narration, reading pauses, and screenshot
+  requests were corrected in this stage. Human visual review of the videos
+  was completed and approved before release.
+- **Final pre-release readiness**
+  (`docs/reports/v0.9-final-pre-release-readiness.md`, with corrections in
+  `docs/reports/v0.9-final-readiness-corrections.md`): one exact candidate
+  package passed the packed observation, viewer and v0.9 annotation smokes and
+  all four tutorials on Windows, Linux and macOS, using
+  `@dailephd/my-dev-kit-lab@0.4.9` semantic `select-option` for native
+  selects.
+
+The four scenarios are annotation basics, runtime intent to an active change
+contract, reference authoring, and reference materialization. After each run
+the canonical evidence is read directly from the disposable target. The checks
+prove, for example, that only the two selected clauses were promoted, that
+`remove` and `inspect` never became clauses, and that a materialized reference
+revision is `imported`, supersedes its approved source, and reuses the source
+image bytes unchanged.
+
+`my-dev-kit-lab` is an external tool invoked through `npx`. It is not an
+Observer dependency, and Observer has no tutorial command, recorder, subtitle
+writer, or tutorial manifest schema. `examples/v09-demo/` is excluded from the
+npm package.
+
 ## Not implemented
 
 - v0.5 baseline-selection/discovery policy (the caller must supply which
   baseline to approve/evaluate against; there is no "find the current
-  baseline" command), source ownership, orchestrator/lab product
-  integration, and annotation all remain unimplemented in this repository.
+  baseline" command), source ownership, and orchestrator/lab product
+  integration all remain unimplemented in this repository.
   (v0.6's bounded runtime projection and runtime/static correlation, the
   complete v0.7 external-reference correction workflow described above, and
   the v0.8 interactive viewer described in "v0.8 status" above, *are* now
   implemented.) A CLI surface for Prompt 8's correction workflow specifically
   remains unimplemented by design (programmatic-only, library-level use is
   the current supported entry point) - see "v0.7 Prompt 8 status" above.
-  Structured visual annotation (v0.9) and the full graphical human-LLM
-  workflow (v0.10) remain future and unimplemented.
+  The full graphical human-LLM workflow (v0.10) remains future and
+  unimplemented. Structured visual annotation (v0.9) is implemented and
+  released as `0.9.0` - see "v0.9 status" above.
 
 ## Next target
 
-v0.1-v0.8 are implemented, validated, and released (`0.1.0`, `0.2.0`,
-`0.3.0`, `0.4.0`, `0.5.0`, `0.6.0`, `0.7.0`, `0.8.0`). v0.7 (End-to-End
+v0.1-v0.9 are implemented, validated, and released (`0.1.0`, `0.2.0`,
+`0.3.0`, `0.4.0`, `0.5.0`, `0.6.0`, `0.7.0`, `0.8.0`, `0.8.1`, `0.9.0`). v0.7 (End-to-End
 Coding-Agent Frontend Change Review) is fully implemented and released: the
 external-reference artifact foundation, explicit reference
 regions/relationships, selected design requirements/tolerance
@@ -1035,8 +1154,8 @@ for the completeness audit, and
 readiness validation that preceded this release.
 
 v0.8 (Interactive Local Observation Viewer) is fully implemented, tested,
-and released - see "v0.8 status" above. v0.8.1 is the current package
-release: `@dailephd/my-frontend-observer@0.8.1`. All
+and released - see "v0.8 status" above. v0.8.1 was released as
+`@dailephd/my-frontend-observer@0.8.1`. All
 eight implementation batches, the hardened documentation/implementation-
 completeness audit, and formal pre-release readiness (cross-platform and
 security validation) have passed - see `docs/ROADMAP.md` for v0.8's full
@@ -1044,6 +1163,9 @@ scope,
 `docs/reports/v0.8-implementation-completeness-documentation-reconciliation.md`
 for the completeness audit, and
 `docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`
-for the cross-platform readiness validation that preceded this release. v0.9
-(structured visual annotation) and v0.10 (full graphical human-LLM workflow)
-remain future - see `docs/ROADMAP.md`.
+for the cross-platform readiness validation that preceded this release.
+
+v0.9 (structured visual annotation) is released as
+`@dailephd/my-frontend-observer@0.9.0` - see "v0.9 status" above. The next
+target is v0.10 (full graphical human-LLM workflow), which remains future and
+unimplemented - see `docs/ROADMAP.md`.

package/docs/DEVELOPMENT.md

@@ -1,7 +1,8 @@
 # Development
 
-The released v0.8.1 workflow is published as
-`@dailephd/my-frontend-observer@0.8.1` (CLI `my-frontend-observer`).
+The released v0.9.0 package is published as
+`@dailephd/my-frontend-observer@0.9.0` (CLI `my-frontend-observer`). It keeps
+the v0.8.1 project workflow and adds structured visual annotation.
 
 The v0.8.1 workflow is exercised through unit and real-Chromium tests. Project fixtures use `init`, `capture baseline`, and `check`; coding-agent consumers use bounded `check --json`. `tests/browser/projectCheckWorkflow.test.ts` covers REVIEW_REQUIRED, contract FAIL-to-PASS, reference FAIL/PASS/BLOCKED, incomparable BLOCKED, current history, and contained acceptance paths. `scripts/ci/runPackedViewerSmoke.mjs` is the single installed-package viewer/project-workflow smoke owner: it repeats REVIEW_REQUIRED and unchanged-contract FAIL-to-PASS before alias-aware viewer proof. Run the full unit, browser, security, build, documentation, and packed-consumer validations before release readiness.
 
@@ -187,7 +188,11 @@ This starts a real, loopback-only server serving the actual built PWA. As of
 v0.8 (all eight implementation batches), it reads `--root` only for bounded,
 read-only evidence discovery through the existing canonical
 readers/classifiers - it never writes to `--root` or modifies any artifact
-under it.
+under it. The v0.9 annotation authoring surface (implemented, not yet
+released) is available only from the project-aware `node dist/cli.js view`
+inside an initialized project, never from `--root`. Its end-to-end browser
+proof is `tests/browser/v09IntegratedAcceptance.test.ts`, and its packed
+installed proof is `scripts/ci/runPackedV09AnnotationSmoke.mjs`.
 
 Unlike `scripts/ci/runPackedObservationSmoke.mjs`, none of these five dev
 smokes is wired into any CI workflow or is a release gate - they are

package/docs/PROJECT_DESCRIPTION.md

@@ -1357,7 +1357,10 @@ The viewer must consume the reusable observation, reference, comparison, contrac
 
 It must not contain a second browser-observation implementation, a second reference model, a second binding engine, a second reference-evaluation implementation, a second contract engine, or a second bounded-context builder.
 
-## Future capability — Human visual annotation
+## Implemented capability (v0.9) — Human visual annotation
+
+Status: implemented and released as `0.9.0`. The intent below is unchanged and
+remains the capability authority.
 
 A later phase should allow the user to communicate visual intent directly on top of either an observed frontend or an approved external reference.
 

package/docs/PROJECT_MILESTONES.md

@@ -1715,6 +1715,10 @@ Milestone 8 is complete when:
 
 ## Milestone 9 — Human Visual Annotation and Design-Intent Capture
 
+Implementation status: implemented and released as `0.9.0`. The milestone
+design below is unchanged and remains the capability authority. Milestone 10
+remains future.
+
 ### Objective
 
 Add visual human intent to the already working Milestone 7 coding-agent/reference workflow through the Milestone 8 viewer.

package/docs/PROJECT_OVERVIEW.md

@@ -1,8 +1,9 @@
 # Project Overview
 
-The repository contains the complete v0.8.1 source workflow (`init`, `capture`,
-`check`, project-aware `view`), released as
-`@dailephd/my-frontend-observer@0.8.1` under the MIT license.
+The repository contains the complete v0.9.0 release, published as
+`@dailephd/my-frontend-observer@0.9.0` under the MIT license. It adds
+structured visual annotation to the v0.8.1 project workflow (`init`,
+`capture`, `check`, project-aware `view`).
 
 `my-frontend-observer` is the rendered browser/runtime evidence producer in
 the my-dev-kit ecosystem. It addresses the gap between source-level evidence
@@ -28,13 +29,16 @@ Region Identity; v0.3, Runtime Scrolling, Overflow, and Visibility Behavior;
 v0.4, Layout Relationships, Dependency Evidence, and Before/After
 Comparison; v0.5, Executable Frontend Contracts and Explicit Change Scope;
 v0.6, Bounded Agent Context and Native my-dev-kit Ecosystem Integration;
-v0.7, End-to-End Coding-Agent Frontend Change Review; and v0.8, Interactive
-Local Observation Viewer, are released and published to npm. The current
-package version is `0.8.1` as `@dailephd/my-frontend-observer` (observation schema `1.2.0`, comparison schema
+v0.7, End-to-End Coding-Agent Frontend Change Review; v0.8, Interactive
+Local Observation Viewer; v0.8.1, Project Workflow CLI and Human-Readable
+Evidence Aliases; and v0.9, Human Visual Annotation and Design-Intent Capture,
+are released and published to npm. The current package version is `0.9.0` as
+`@dailephd/my-frontend-observer` (observation schema `1.2.0`, comparison schema
 `1.0.0`, frontend contract schema `1.0.0`, evaluation artifact schema `1.0.0`,
-bounded-agent-context schema `1.0.0`, external-reference schema `1.0.0`). The
-released package was validated as a packed npm tarball in a clean consumer
-environment across Windows, Linux, and macOS.
+bounded-agent-context schema `1.0.0`, external-reference schema `1.0.0`,
+visual annotation schema `1.0.0`). The released package was validated as a
+packed npm tarball in a clean consumer environment across Windows, Linux, and
+macOS.
 
 The released low-level command surface remains artifact-oriented: a real
 `observe` command launches Chromium, enforces loopback-only safety, captures
@@ -81,8 +85,8 @@ engines used by the CLI, never a second implementation of them. See
 and `docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`
 for the implementation and release evidence.
 
-The repository implementation now includes released v0.8.1, a project-workflow
-CLI usability patch published as `@dailephd/my-frontend-observer@0.8.1`. It does
+v0.8.1 was a project-workflow CLI usability patch published as
+`@dailephd/my-frontend-observer@0.8.1`. It does
 not introduce a new evidence model. It adds project configuration,
 human-readable aliases, managed project-local Observer state, and a small
 high-level `init` / `capture` / `check` / project-aware `view` workflow above
@@ -92,10 +96,23 @@ artifact identifiers during ordinary use. Existing low-level commands remain
 supported. The frozen plan is
 `docs/plans/v0.8.1-cli-usability-patch-plan.md`.
 
-v0.9 and v0.10 remain future and unimplemented. v0.9 adds structured visual
-annotation through the existing viewer. v0.10 completes the visual human-LLM
-workflow and should consume the v0.8.1 high-level acceptance surface rather than
-introduce another Observer command architecture.
+The latest published release is v0.9.0. v0.9 adds structured
+visual annotation to the project-aware viewer for both runtime observations and
+external references. People draw marks, explicitly associate them, and confirm
+structured intent. Selected confirmed runtime intent can become a normal
+per-change contract, and selected confirmed reference intent can become a new
+imported external-reference revision. The existing contract and reference
+evaluators stay authoritative. It followed the frozen plan in
+`docs/plans/v0.9-implementation-plan.md`, grounded by
+`docs/reports/v0.9-architecture-retrieval.md`.
+The repository-owned deterministic demo and its four tutorial scenarios
+(`examples/v09-demo/`, recorded by the external
+`@dailephd/my-dev-kit-lab@0.4.9` tool) passed final cross-platform readiness
+with the release. They are release support and documentation, not product
+behavior, and they are not shipped in the npm package.
+v0.10 remains future and unimplemented and completes the visual human-LLM
+workflow on top of the v0.9 annotation model and v0.8.1 high-level acceptance
+surface.
 
 The revised dependency path reaches practical coding-agent use before graphical
 interaction and keeps later visual work on the same canonical evidence system:
@@ -109,9 +126,9 @@ runtime observation and stable identity
   + reference-vs-candidate structured fidelity evaluation
   + controlled end-to-end correction workflow (released as 0.7.0)
 → interactive viewer with reference/candidate inspection (released as 0.8.0)
-→ project workflow CLI + human-readable evidence aliases (implemented in source; not published)
+→ project workflow CLI + human-readable evidence aliases (released as 0.8.1)
 → structured visual annotation on runtime screenshots and external references
-  (planned v0.9)
+  (released as 0.9.0)
 → full visual human-LLM workflow with actual-frontend-driven and
   reference-driven entry modes (planned v0.10)
 ```
@@ -145,6 +162,13 @@ Repository-local authorities and navigation:
   release state.
 - [plans/v0.8.1-cli-usability-patch-plan.md](plans/v0.8.1-cli-usability-patch-plan.md)
   freezes the concrete implementation plan for the v0.8.1 patch.
+- [plans/v0.9-implementation-plan.md](plans/v0.9-implementation-plan.md)
+  freezes the concrete implementation architecture, seven ordered batches,
+  gates, and validation expectations for v0.9. It is planning authority only;
+  the v0.9 implementation state is recorded in CURRENT_STATE.md and the
+  `reports/v0.9-*.md` reports.
+- [reports/v0.9-architecture-retrieval.md](reports/v0.9-architecture-retrieval.md)
+  preserves the bounded current-source retrieval that grounded the v0.9 plan.
 
 Historical greenfield artifacts and reports are retained as evidence that an
 earlier run overreached into v0.1; they are not current-state authority.

package/docs/QUICKSTART.md

@@ -1,28 +1,46 @@
 # Quickstart
 
+For complete coding-agent features, runtime-to-source repair, shared-component
+protection, and ecosystem failure feedback, use the single
+[ecosystem workflow guide in my-dev-kit](https://github.com/dailephd/my-dev-kit/blob/main/docs/ECOSYSTEM_DEVELOPMENT_WORKFLOWS.md).
+Observer owns the browser evidence and its canonical evaluations. Project tests
+own application actions and backend/frontend integration. Orchestrator owns
+native lifecycle when selected. Lab supplies applicable assurance separately.
+This repository does not maintain another ecosystem-guide copy.
+
 The common source workflow is:
 
 ```powershell
 node dist/cli.js init --url http://127.0.0.1:3000 --target app=#app
 node dist/cli.js capture baseline
 # make a frontend change
-node dist/cli.js check baseline
+node dist/cli.js check baseline --json
 node dist/cli.js view
 ```
 
-Use `check baseline --json` for a coding agent: on `FAIL`, use the returned
-bounded runtime evidence, correct source externally, and rerun until `PASS`.
-Observer never edits source. Canonical IDs remain available in details and
-provenance but are not required as ordinary command input.
+Use `check baseline --json` for a coding agent. It captures a new immutable
+candidate, compares it canonically, and evaluates configured acceptance. The
+result and exit status are `PASS`/0, `FAIL`/1, `REVIEW_REQUIRED`/2, or `BLOCKED`/3.
+Comparison alone returns `REVIEW_REQUIRED`, even when no differences are found.
+Configure the applicable contract and/or approved reference through the current
+project schema before expecting an acceptance PASS. See
+[COMMANDS.md](COMMANDS.md#v081-common-workflow) for the exact fields.
+
+On a failure, preserve the bounded evidence, correct source externally, and
+recheck against the same baseline. Do not replace the baseline, relax protected
+requirements, or treat REVIEW_REQUIRED/BLOCKED as success. Observer never edits
+source. Canonical IDs remain available in details and provenance but are not
+required as ordinary project-command input.
 
-Prerequisites are Node.js 24 or later and npm. For the published package:
+Prerequisites are Node.js 24 or later and npm. The package identity is:
 
 ```powershell
 npm install --save-dev @dailephd/my-frontend-observer
 npx playwright install chromium
 ```
 
-The installed CLI is still named `my-frontend-observer`.
+The installed CLI remains `my-frontend-observer`. Use the resolved local binary
+or `npx @dailephd/my-frontend-observer` and record its version. For source setup:
 
 ```powershell
 npm install
@@ -30,7 +48,7 @@ npx playwright install chromium
 npm run build
 ```
 
-Run a real observation against your own local frontend:
+The advanced observation workflow remains supported:
 
 ```powershell
 node dist/cli.js observe `
@@ -41,37 +59,32 @@ node dist/cli.js observe `
   --output observations
 ```
 
-This launches Chromium, captures a screenshot plus bounded page/target
-evidence, and writes one portable artifact under `observations/<observation-id>/`.
-See [COMMANDS.md](COMMANDS.md) for the full flag reference, including the
-`--targets-file` structured semantic-target input and the
-`--scroll-scenario-file` bounded runtime scroll scenario input.
-
-Once you have two such artifacts, `node dist/cli.js compare --before
-<root> --after <root> --output comparisons` derives before/after evidence
-between them without launching a browser again - see
-[COMMANDS.md](COMMANDS.md#compare) for details.
-
-You can then approve a baseline, save a per-change contract, and evaluate a
-candidate change against them plus the observation/comparison evidence
-above - see [COMMANDS.md](COMMANDS.md#approve-baseline) for the exact flags
-and [WORKFLOWS.md](WORKFLOWS.md) for the full flow.
-
-If you also have an external design-reference image, `import-reference`/
-`approve-reference`/`evaluate-reference-fidelity` let you compare a
-candidate observation against it (implemented in the current development
-state; see [COMMANDS.md](COMMANDS.md) and [CONTRACTS.md](CONTRACTS.md) for
-the exact flags and contract).
-
-To inspect a project visually instead of opening raw artifact files,
-`my-frontend-observer view --no-open` starts a local,
-loopback-only viewer server (usable in a normal browser or as an installed
-PWA) over managed project evidence. For existing standalone evidence roots,
-use `my-frontend-observer view --root observations --no-open`. See
-[COMMANDS.md](COMMANDS.md#view) for the full
-flag reference, including `--bindings-file` and `--context-file`.
-
-To validate the repository itself instead:
+It launches Chromium, captures a screenshot plus bounded page/target evidence,
+and writes a portable artifact under `observations/<observation-id>/`.
+[COMMANDS.md](COMMANDS.md) documents structured `--targets-file` input, bounded
+`--scroll-scenario-file` actions, and declared `--state-file` identity. Declaring
+state does not log in, seed data, or execute a user journey. Establish required
+application state with the project's actual setup/browser test commands.
+
+With two observations, `compare --before <root> --after <root> --output
+comparisons` derives before/after evidence without launching another browser.
+It can report incomparable evidence successfully, so inspect the semantic
+result rather than treat advanced-command exit 0 as acceptance.
+
+`approve-baseline`, `save-change-contract`, and `evaluate-contract` expose the
+advanced frontend contract flow. A selected external image additionally uses
+`import-reference`, `approve-reference`, and `evaluate-reference-fidelity`.
+Reference requirements, applicability, explicit bindings, and protected behavior
+remain independent acceptance responsibilities. A raw image import does not
+approve a reference or prove every aesthetic requirement. See
+[CONTRACTS.md](CONTRACTS.md) and [WORKFLOWS.md](WORKFLOWS.md).
+
+`my-frontend-observer view --no-open` starts the loopback-only viewer over managed
+project evidence. Use `view --root observations --no-open` for standalone roots.
+The viewer is inspect-only. Its `--bindings-file` and `--context-file` inputs do
+not create a second evaluator or automatic source-owner mapping.
+
+To validate this repository itself, rather than the target application:
 
 ```powershell
 npm run typecheck

package/docs/RELEASE.md

@@ -1,24 +1,29 @@
 # Release
 
-`v0.8.1` (Project Workflow CLI and Human-Readable Evidence Aliases) is
-released and published to npm as `@dailephd/my-frontend-observer`. The
-release includes the managed project workflow, bounded check interface,
-alias-aware viewer, cross-platform validation, and MIT license.
+`v0.9.0` (Human Visual Annotation and Design-Intent Capture) is released and
+published to npm as `@dailephd/my-frontend-observer`. The release adds
+structured visual annotation of runtime observations and external references
+to the project-aware viewer, selected promotion of confirmed runtime intent
+into canonical change contracts, and selected materialization of confirmed
+reference intent into new imported reference revisions, with final
+Windows/Linux/macOS readiness and the MIT license.
 
 The CLI remains `my-frontend-observer`; package identity and product identity
 are intentionally distinct. Canonical artifact schemas remain versioned
 independently from the npm package version.
 
 Observation, comparison, frontend contract, evaluation artifact,
-bounded-agent-context, external-reference, and package version all remain
-separate: package version is `0.7.0`; observation schema is `1.2.0`,
-comparison schema is `1.0.0`, frontend contract schema is `1.0.0`,
+bounded-agent-context, external-reference, visual annotation, and package
+version all remain separate: package version is `0.9.0`; observation schema is
+`1.2.0`, comparison schema is `1.0.0`, frontend contract schema is `1.0.0`,
 evaluation artifact schema is `1.0.0`, bounded-agent-context schema is
-`1.0.0`, and external-reference schema is `1.0.0` - none of which changes
-automatically with the package version, and none of which was bumped by
-the v0.7 work.
+`1.0.0`, external-reference schema is `1.0.0`, and visual annotation schema is
+`1.0.0` - none of which changes automatically with the package version. v0.9
+introduced the visual annotation schema and bumped no existing schema.
 
-Prior releases: `v0.6.0` (Bounded Agent Context and Native my-dev-kit
+Prior releases: `v0.8.1` (Project Workflow CLI and Human-Readable Evidence
+Aliases), `v0.8.0` (Interactive Local Observation Viewer), `v0.7.0` (End-to-End
+Coding-Agent Frontend Change Review), `v0.6.0` (Bounded Agent Context and Native my-dev-kit
 Ecosystem Integration), `v0.5.0` (Executable Frontend Contracts and
 Explicit Change Scope), `v0.4.0` (Layout Relationships, Dependency
 Evidence, and Before/After Comparison), `v0.3.0` (Runtime Scrolling,