@dailephd/my-frontend-observer 0.8.1 → 0.9.1

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,30 @@
 # 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.1` (PWA Hard-Gate Isolation and Reproducible Security Acceptance) is
+released and published to npm as `@dailephd/my-frontend-observer`. This
+maintenance 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.1`; 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,