@dailephd/my-frontend-observer 0.9.1 → 0.10.1

package/docs/PROJECT_OVERVIEW.md

@@ -1,191 +1,200 @@
-# Project Overview
-
-The repository contains the complete v0.9.1 release, published as
-`@dailephd/my-frontend-observer@0.9.1` under the MIT license. It hardens
-independent PWA security acceptance while preserving the structured visual
-annotation added 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
-and what a browser actually renders and supports three durable jobs: human-to-LLM
-design communication, safer LLM-assisted frontend changes, and runtime evidence
-for coordinated ecosystem work. Human-to-LLM design communication can begin
-from the currently rendered frontend or from an approved external visual
-reference that describes the desired design.
-
-The responsibility split is stable:
-
-- `my-dev-kit` produces static repository/source evidence.
-- `my-frontend-observer` produces rendered browser/runtime evidence and owns the
-  structured external-reference evidence used to compare approved desired-design
-  intent with an actual browser-rendered candidate.
-- `my-dev-kit-orchestrator` coordinates workflows and bounded evidence use.
-- `my-dev-kit-lab` owns compatibility, fixtures, experiments, and evaluation.
-
-## Current repository state
-
-v0.1, Runtime Observation Foundation; v0.2, Stable Semantic Targets and
-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; 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.1` 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`,
-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
-bounded page/target evidence through CSS shorthand, structured semantic targets,
-or a bounded scroll scenario, and persists one portable local artifact; a real
-`compare` command reads two persisted observations and derives before/after
-relationship and difference evidence; `approve-baseline`,
-`save-change-contract`, and `evaluate-contract` provide canonical executable
-change-scope evaluation; and the v0.7 reference commands import, approve, and
-evaluate approved external visual references. See `docs/CURRENT_STATE.md` for
-the complete implemented state and release evidence.
-
-v0.6 adds a programmatic bounded runtime projection plus an explicit
-runtime/static correlation boundary (`correlated`/`ambiguous`/
-`unavailable`), exported from `src/index.ts` with no new CLI command.
-
-v0.7 (End-to-End Coding-Agent Frontend Change Review) adds the complete
-external-reference architecture: the external-reference artifact foundation
-and explicit approval lifecycle (`import-reference`/`approve-reference`),
-explicit reference regions and reusable geometry relationships, selected
-design requirements/tolerances/reference-evidence adequacy, reference
-applicability and candidate-state compatibility, explicit
-reference-region-to-runtime-target binding, structured
-reference-vs-candidate fidelity evaluation (`evaluate-reference-fidelity`),
-its integration into the existing v0.6 bounded-agent-context, and a
-controlled, programmatic end-to-end correction workflow
-(`prepareReferenceCorrection`/`reviewReferenceCorrectionAttempt`) proven
-against real Chromium (success, protected-regression, and multi-attempt
-correction-iteration cases). See `docs/CURRENT_STATE.md` for the full
-implementation record and
-`docs/reports/v0.7-implementation-completeness-documentation-reconciliation.md`
-for the completeness audit that preceded release.
-
-v0.8 (Interactive Local Observation Viewer) is released as package version
-`0.8.0` - `my-frontend-observer view` starts a loopback-only Node server
-serving a React + TypeScript + Vite viewer (normal browser or installed PWA)
-that inspects observations, comparisons, contract results, external
-references/candidates with explicit binding cross-selection and on-demand
-fidelity evaluation, and, when supplied, a bounded agent context's
-adequacy/omissions/truncations/correlation - all through the same canonical
-engines used by the CLI, never a second implementation of them. See
-`docs/CURRENT_STATE.md`,
-`docs/reports/v0.8-implementation-completeness-documentation-reconciliation.md`,
-and `docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`
-for the implementation and release evidence.
-
-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
-the existing canonical engines. The purpose is to stop making humans and coding
-agents repeatedly manage output paths, evidence roots, and long canonical
-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`.
-
-The latest published release is v0.9.1. v0.9 added 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.
-
-The v0.9.1 maintenance release hardens the
-PWA server-down hard acceptance test so the gate is reproducible from a fresh
-browser profile and fresh test-owned state. PWA hard/security acceptance no
-longer depends on prior test order or persistent browser state, and
-`npm run test:security` now also runs the gate by itself through
-`npm run test:pwa-hard-gate`. This was a test-isolation correction, not a
-production PWA defect. No production behavior changed. The frozen concrete plan
-is `docs/plans/v0.9.1-implementation-plan.md`.
-
-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:
-
-```text
-runtime observation and stable identity
-→ bounded behavior, relationships, comparison, and safe-change contracts
-→ bounded agent context plus native ecosystem integration (released as 0.6.0)
-→ text/config-driven coding-agent change review
-  + external visual-reference evidence foundation
-  + 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 (released as 0.8.1)
-→ structured visual annotation on runtime screenshots and external references
-  (released as 0.9.0)
-→ full visual human-LLM workflow with actual-frontend-driven and
-  reference-driven entry modes (planned v0.10)
-```
-
-The implemented reference model is not a second observer or a
-screenshot-cloning system. An external reference is desired-design evidence,
-not an earlier runtime observation, and reference design vs candidate remains
-distinct from before vs after comparison and contract vs candidate evaluation.
-Structured geometry, relationships, explicit design intent, applicability
-state, provenance, and bounded tolerances remain primary; image similarity may
-only supplement them where reliable. Reference-derived executable intent must
-reuse the existing requested/expected-dependent/protected/preserved contract
-semantics rather than create a second PASS/FAIL taxonomy.
-
-Viewer and annotation enhance the proven coding-agent workflow; they are not
-prerequisites for proving it. The viewer must consume the reference model and
-fidelity evidence established before it rather than inventing a UI-only
-comparison engine. The implemented v0.8.1 workflow layer likewise resolves project
-configuration and human aliases to existing canonical artifacts and services;
-it does not replace artifact identity or evaluation semantics.
-
-Repository-local authorities and navigation:
-
-- [PROJECT_DESCRIPTION.md](PROJECT_DESCRIPTION.md) contains complete durable
-  product intent and responsibility boundaries.
-- [PROJECT_MILESTONES.md](PROJECT_MILESTONES.md) contains the complete ordered
-  capability plan and cross-milestone rules.
-- [ROADMAP.md](ROADMAP.md) owns version-level direction without prewritten
-  implementation batches.
-- [CURRENT_STATE.md](CURRENT_STATE.md) records current implementation and
-  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.
-- [plans/v0.9.1-implementation-plan.md](plans/v0.9.1-implementation-plan.md)
-  freezes the bounded maintenance plan for independent PWA hard-gate
-  reproduction, fresh browser-profile ownership, explicit service-worker/cache
-  precondition proof, and isolated-gate validation. It does not authorize a
-  production PWA change unless the corrected experiment demonstrates a real
-  product defect.
-- [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.
+# Project Overview
+
+The repository contains the v0.10.1 release of
+`@dailephd/my-frontend-observer` under the MIT license. It completes the Visual
+Change workflow on the project workflow (`init`, `capture`, `check`, Viewer).
+
+`my-frontend-observer` is the rendered browser/runtime evidence producer in
+the my-dev-kit ecosystem. It addresses the gap between source-level evidence
+and what a browser actually renders and supports three durable jobs: human-to-LLM
+design communication, safer LLM-assisted frontend changes, and runtime evidence
+for coordinated ecosystem work. Human-to-LLM design communication can begin
+from the currently rendered frontend or from an approved external visual
+reference that describes the desired design.
+
+The responsibility split is stable:
+
+- `my-dev-kit` produces static repository/source evidence.
+- `my-frontend-observer` produces rendered browser/runtime evidence and owns the
+  structured external-reference evidence used to compare approved desired-design
+  intent with an actual browser-rendered candidate.
+- `my-dev-kit-orchestrator` coordinates workflows and bounded evidence use.
+- `my-dev-kit-lab` owns compatibility, fixtures, experiments, and evaluation.
+
+## Current repository state
+
+v0.1, Runtime Observation Foundation; v0.2, Stable Semantic Targets and
+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; v0.8, Interactive
+Local Observation Viewer; v0.8.1, Project Workflow CLI and Human-Readable
+Evidence Aliases; v0.9, Human Visual Annotation and Design-Intent Capture; and
+v0.10.0, Full Visual Human–LLM Frontend Change Workflow, and v0.10.1, Project
+Check Baseline Context Replay, are released and published to npm. The current
+package version is `0.10.1` 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`,
+visual annotation schema `1.0.0`, visual-change workflow schema `1.0.0`,
+handoff `1.0.0`; Viewer protocol `1.3.0`). Exact-candidate readiness passed
+on Windows, Linux, and macOS.
+
+In v0.10.1, project-aware `check` replays a validated baseline's optional
+scroll and caller-declared state context while project configuration continues
+to own URL, viewport, and targets. See `CURRENT_STATE.md` for release state.
+
+The released low-level command surface remains artifact-oriented: a real
+`observe` command launches Chromium, enforces loopback-only safety, captures
+bounded page/target evidence through CSS shorthand, structured semantic targets,
+or a bounded scroll scenario, and persists one portable local artifact; a real
+`compare` command reads two persisted observations and derives before/after
+relationship and difference evidence; `approve-baseline`,
+`save-change-contract`, and `evaluate-contract` provide canonical executable
+change-scope evaluation; and the v0.7 reference commands import, approve, and
+evaluate approved external visual references. See `docs/CURRENT_STATE.md` for
+the complete implemented state and release evidence.
+
+v0.6 adds a programmatic bounded runtime projection plus an explicit
+runtime/static correlation boundary (`correlated`/`ambiguous`/
+`unavailable`), exported from `src/index.ts` with no new CLI command.
+
+v0.7 (End-to-End Coding-Agent Frontend Change Review) adds the complete
+external-reference architecture: the external-reference artifact foundation
+and explicit approval lifecycle (`import-reference`/`approve-reference`),
+explicit reference regions and reusable geometry relationships, selected
+design requirements/tolerances/reference-evidence adequacy, reference
+applicability and candidate-state compatibility, explicit
+reference-region-to-runtime-target binding, structured
+reference-vs-candidate fidelity evaluation (`evaluate-reference-fidelity`),
+its integration into the existing v0.6 bounded-agent-context, and a
+controlled, programmatic end-to-end correction workflow
+(`prepareReferenceCorrection`/`reviewReferenceCorrectionAttempt`) proven
+against real Chromium (success, protected-regression, and multi-attempt
+correction-iteration cases). See `docs/CURRENT_STATE.md` for the full
+implementation record and
+`docs/reports/v0.7-implementation-completeness-documentation-reconciliation.md`
+for the completeness audit that preceded release.
+
+v0.8 (Interactive Local Observation Viewer) is released as package version
+`0.8.0` - `my-frontend-observer view` starts a loopback-only Node server
+serving a React + TypeScript + Vite viewer (normal browser or installed PWA)
+that inspects observations, comparisons, contract results, external
+references/candidates with explicit binding cross-selection and on-demand
+fidelity evaluation, and, when supplied, a bounded agent context's
+adequacy/omissions/truncations/correlation - all through the same canonical
+engines used by the CLI, never a second implementation of them. See
+`docs/CURRENT_STATE.md`,
+`docs/reports/v0.8-implementation-completeness-documentation-reconciliation.md`,
+and `docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`
+for the implementation and release evidence.
+
+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
+the existing canonical engines. The purpose is to stop making humans and coding
+agents repeatedly manage output paths, evidence roots, and long canonical
+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 added 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.
+
+The v0.9.1 maintenance release hardened the
+PWA server-down hard acceptance test so the gate is reproducible from a fresh
+browser profile and fresh test-owned state. PWA hard/security acceptance no
+longer depends on prior test order or persistent browser state, and
+`npm run test:security` now also runs the gate by itself through
+`npm run test:pwa-hard-gate`. This was a test-isolation correction, not a
+production PWA defect. No production behavior changed. The frozen concrete plan
+is `docs/plans/v0.9.1-implementation-plan.md`.
+
+v0.10.0 completes the Visual Change workflow on top of the v0.9 annotation
+model and v0.8.1 high-level acceptance surface. It supports actual-frontend
+and approved-reference entry, explicit activation, bounded coding-agent
+handoff, immutable correction history, PASS-only human acceptance, and
+separate governance. Installed-package and Viewer support are included.
+
+The revised dependency path reaches practical coding-agent use before graphical
+interaction and keeps later visual work on the same canonical evidence system:
+
+```text
+runtime observation and stable identity
+→ bounded behavior, relationships, comparison, and safe-change contracts
+→ bounded agent context plus native ecosystem integration (released as 0.6.0)
+→ text/config-driven coding-agent change review
+  + external visual-reference evidence foundation
+  + 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 (released as 0.8.1)
+→ structured visual annotation on runtime screenshots and external references
+  (released as 0.9.0)
+→ full visual human-LLM workflow with actual-frontend-driven and
+  reference-driven entry modes (released as v0.10.0)
+```
+
+The implemented reference model is not a second observer or a
+screenshot-cloning system. An external reference is desired-design evidence,
+not an earlier runtime observation, and reference design vs candidate remains
+distinct from before vs after comparison and contract vs candidate evaluation.
+Structured geometry, relationships, explicit design intent, applicability
+state, provenance, and bounded tolerances remain primary; image similarity may
+only supplement them where reliable. Reference-derived executable intent must
+reuse the existing requested/expected-dependent/protected/preserved contract
+semantics rather than create a second PASS/FAIL taxonomy.
+
+Viewer and annotation enhance the proven coding-agent workflow; they are not
+prerequisites for proving it. The viewer must consume the reference model and
+fidelity evidence established before it rather than inventing a UI-only
+comparison engine. The implemented v0.8.1 workflow layer likewise resolves project
+configuration and human aliases to existing canonical artifacts and services;
+it does not replace artifact identity or evaluation semantics.
+
+Repository-local authorities and navigation:
+
+- [PROJECT_DESCRIPTION.md](PROJECT_DESCRIPTION.md) contains complete durable
+  product intent and responsibility boundaries.
+- [PROJECT_MILESTONES.md](PROJECT_MILESTONES.md) contains the complete ordered
+  capability plan and cross-milestone rules.
+- [ROADMAP.md](ROADMAP.md) owns version-level direction without prewritten
+  implementation batches.
+- [CURRENT_STATE.md](CURRENT_STATE.md) records current implementation and
+  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.
+- [plans/v0.9.1-implementation-plan.md](plans/v0.9.1-implementation-plan.md)
+  freezes the bounded maintenance plan for independent PWA hard-gate
+  reproduction, fresh browser-profile ownership, explicit service-worker/cache
+  precondition proof, and isolated-gate validation. It does not authorize a
+  production PWA change unless the corrected experiment demonstrates a real
+  product defect.
+- [plans/v0.10-implementation-plan.md](plans/v0.10-implementation-plan.md)
+  is the frozen planning authority for the completed v0.10 implementation;
+  current evidence and reconciliation are recorded in the v0.10 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,96 +1,100 @@
-# 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 --json
-node dist/cli.js view
-```
-
-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. The package identity is:
-
-```powershell
-npm install --save-dev @dailephd/my-frontend-observer
-npx playwright install chromium
-```
-
-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
-npx playwright install chromium
-npm run build
-```
-
-The advanced observation workflow remains supported:
-
-```powershell
-node dist/cli.js observe `
-  --url http://localhost:3000/ `
-  --viewport 1280x720 `
-  --target header=header `
-  --target main-content=main `
-  --output observations
-```
-
-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
-npm run lint
-npm test
-npm run test:browser
-npm run build
-npm run check:docs
-```
+# 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 --json
+node dist/cli.js view
+```
+
+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. The package identity is:
+
+```powershell
+npm install --save-dev @dailephd/my-frontend-observer
+npx playwright install chromium
+```
+
+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
+npx playwright install chromium
+npm run build
+```
+
+The advanced observation workflow remains supported:
+
+```powershell
+node dist/cli.js observe `
+  --url http://localhost:3000/ `
+  --viewport 1280x720 `
+  --target header=header `
+  --target main-content=main `
+  --output observations
+```
+
+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. The v0.10.0 project-aware Viewer also owns the explicit
+Visual Change workflow: visual entry, activation, handoff, check,
+review/correction, acceptance, and separate
+governance-result recording. Use `view --root observations --no-open` for
+standalone roots; that mode remains inspect-only. The `--bindings-file` and
+`--context-file` inputs do not create a second evaluator or automatic
+source-owner mapping. The installed package includes the Visual Change surface.
+
+To validate this repository itself, rather than the target application:
+
+```powershell
+npm run typecheck
+npm run lint
+npm test
+npm run test:browser
+npm run build
+npm run check:docs
+```