@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/dist/cli.js

@@ -25,11 +25,11 @@ const defaultIO = {
         process.stderr.write(text);
     },
 };
-const TOP_LEVEL_HELP = `my-frontend-observer - local-first browser runtime evidence producer
-
-Usage:
-  my-frontend-observer <command> [options]
-
+const TOP_LEVEL_HELP = `my-frontend-observer - local-first browser runtime evidence producer
+
+Usage:
+  my-frontend-observer <command> [options]
+
 Common workflow:
   init                  Initialize project-local Observer configuration and state.
   capture <alias>       Capture one project-configured observation under a human alias.
@@ -38,36 +38,36 @@ Common workflow:
 
 Advanced:
   observe               Capture one bounded browser observation and persist
-                        it as a portable artifact.
-  compare               Compare two persisted observations and write a
-                        structured comparison artifact.
-  approve-baseline      Explicitly approve and persist one already-authored
-                        persistent baseline contract against the observation
-                        it claims to approve.
-  save-change-contract  Validate and persist one already-authored per-change
-                        contract so it can later be evaluated.
-  evaluate-contract     Evaluate a candidate change against an approved
-                        baseline, a per-change contract, and existing
-                        before/after/comparison evidence, and persist the
-                        result.
-  import-reference      Validate and persist one local external design-
-                        reference image as a new, unapproved
-                        external-reference artifact.
-  approve-reference     Explicitly approve one already-imported
-                        external-reference artifact, persisting a new
-                        approved artifact instance.
-  evaluate-reference-fidelity  Evaluate whether a candidate observation
-                        satisfies an external reference's selected design
-                        requirements, gated by reference adequacy,
-                        reference/candidate compatibility, and explicit
-                        region-to-target bindings. Prints a structured
-                        result; persists nothing.
-
-Options:
-  --help     Show this help.
-  --version  Print the package version.
-
-Run "my-frontend-observer <command> --help" for command-specific options.
+                        it as a portable artifact.
+  compare               Compare two persisted observations and write a
+                        structured comparison artifact.
+  approve-baseline      Explicitly approve and persist one already-authored
+                        persistent baseline contract against the observation
+                        it claims to approve.
+  save-change-contract  Validate and persist one already-authored per-change
+                        contract so it can later be evaluated.
+  evaluate-contract     Evaluate a candidate change against an approved
+                        baseline, a per-change contract, and existing
+                        before/after/comparison evidence, and persist the
+                        result.
+  import-reference      Validate and persist one local external design-
+                        reference image as a new, unapproved
+                        external-reference artifact.
+  approve-reference     Explicitly approve one already-imported
+                        external-reference artifact, persisting a new
+                        approved artifact instance.
+  evaluate-reference-fidelity  Evaluate whether a candidate observation
+                        satisfies an external reference's selected design
+                        requirements, gated by reference adequacy,
+                        reference/candidate compatibility, and explicit
+                        region-to-target bindings. Prints a structured
+                        result; persists nothing.
+
+Options:
+  --help     Show this help.
+  --version  Print the package version.
+
+Run "my-frontend-observer <command> --help" for command-specific options.
 `;
 const VIEW_HELP = `Usage:
   my-frontend-observer view [--root <evidence-root>] [--bindings-file <json-file>] [--context-file <json-file>] [options]
@@ -78,71 +78,77 @@ Project or standalone input:
                   used and no initialized project or alias catalog is required.
                   Without --root, view requires an initialized project and
                   discovers its managed evidence root and alias metadata.
-
-Options:
-  --port <n>      TCP port to bind, in [0, 65535]. Defaults to ${DEFAULT_VIEWER_PORT}.
-                  An explicit alternate port is a different web origin than
-                  the default - an installed PWA is not portable across
-                  origins. If the requested port is already in use, this
-                  command fails with an actionable error; it never silently
-                  falls back to a different port.
-  --bindings-file <json-file>  Local JSON file of the form
-                  { "bindings": [ { "referenceRegion": "...", "runtimeTarget": "..." } ] }
-                  (the exact same operational wrapper format as
-                  \`evaluate-reference-fidelity --bindings-file\`, sharing its
-                  parser). Explicit, session-only viewer input: read once at
-                  startup, never persisted, never written into any Observer
-                  artifact, and never exposed as a path to the browser. Its
-                  declarations become available for on-demand binding/
-                  fidelity evaluation once a reference and candidate are
-                  explicitly selected in the viewer. Reference-specific
-                  validity (region existence, etc.) is checked when a
-                  reference is actually selected, not at startup - only the
-                  file's own readability/JSON/wrapper shape is validated at
-                  startup. Omit to run with no binding declarations (the
-                  viewer remains fully usable; cross-selection stays
-                  disabled).
-  --context-file <json-file>  Local JSON file containing exactly one
-                  BoundedAgentContextArtifact value directly (no wrapper
-                  object) - e.g. { "artifactKind":
-                  "my-frontend-observer/bounded-agent-context",
-                  "schemaVersion": "1.0.0", ... }. Explicit, session-only
-                  viewer input: read once at startup, validated through the
-                  existing canonical isValidBoundedAgentContextArtifact,
-                  held only in server memory, never persisted, never written
-                  into any Observer artifact, and never exposed as a path to
-                  the browser. Bounded agent context remains programmatic-
-                  only as an Observer-produced contract - this command does
-                  not add a way to generate, save, or write one; the viewer
-                  never rebuilds it (no projectBoundedAgentContext call) and
-                  never derives runtime/static correlation (no
-                  deriveRuntimeStaticCorrelations/attachRuntimeStaticCorrelations
-                  call) - it only displays the exact context it was given.
-                  A recognized artifactKind with a schemaVersion other than
-                  the currently supported one starts the viewer showing an
-                  honest "unsupported version" context state rather than
-                  failing. An unreadable file, invalid JSON, wrong
-                  artifactKind, or a structurally invalid current-schema
-                  artifact fails startup clearly. Omit to run with no
-                  bounded context supplied (the viewer remains fully usable;
-                  the context panel says none was supplied). May be combined
-                  with --bindings-file.
-  --no-open       Do not attempt to open the system default browser after
-                  the server starts. Browser auto-open is a best-effort
-                  convenience only: its failure is never fatal and never
-                  affects server startup success.
-  --help          Show this help.
-
-Starts one Node HTTP server bound only to 127.0.0.1, serving the built
-React + TypeScript + Vite viewer application (and its PWA manifest/service
-worker) plus one minimal read-only status endpoint. The server never writes
-to the supplied evidence root, never exposes it as a generic static
-directory, and never launches a browser observation. The process keeps
-running (serving the viewer) until interrupted. On success, prints the
-viewer URL and exits only when the server stops. On invalid syntax, a
-missing/non-directory --root, an invalid --port, or a port already in use,
-prints structured diagnostics to stderr and exits nonzero without starting
-a server.
+
+Options:
+  --port <n>      TCP port to bind, in [0, 65535]. Defaults to ${DEFAULT_VIEWER_PORT}.
+                  An explicit alternate port is a different web origin than
+                  the default - an installed PWA is not portable across
+                  origins. If the requested port is already in use, this
+                  command fails with an actionable error; it never silently
+                  falls back to a different port.
+  --bindings-file <json-file>  Local JSON file of the form
+                  { "bindings": [ { "referenceRegion": "...", "runtimeTarget": "..." } ] }
+                  (the exact same operational wrapper format as
+                  \`evaluate-reference-fidelity --bindings-file\`, sharing its
+                  parser). Explicit, session-only viewer input: read once at
+                  startup, never persisted, never written into any Observer
+                  artifact, and never exposed as a path to the browser. Its
+                  declarations become available for on-demand binding/
+                  fidelity evaluation once a reference and candidate are
+                  explicitly selected in the viewer. Reference-specific
+                  validity (region existence, etc.) is checked when a
+                  reference is actually selected, not at startup - only the
+                  file's own readability/JSON/wrapper shape is validated at
+                  startup. Omit to run with no binding declarations (the
+                  viewer remains fully usable; cross-selection stays
+                  disabled).
+  --context-file <json-file>  Local JSON file containing exactly one
+                  BoundedAgentContextArtifact value directly (no wrapper
+                  object) - e.g. { "artifactKind":
+                  "my-frontend-observer/bounded-agent-context",
+                  "schemaVersion": "1.0.0", ... }. Explicit, session-only
+                  viewer input: read once at startup, validated through the
+                  existing canonical isValidBoundedAgentContextArtifact,
+                  held only in server memory, never persisted, never written
+                  into any Observer artifact, and never exposed as a path to
+                  the browser. Bounded agent context remains programmatic-
+                  only as an Observer-produced contract - this command does
+                  not add a way to generate, save, or write one; the viewer
+                  never rebuilds it (no projectBoundedAgentContext call) and
+                  never derives runtime/static correlation (no
+                  deriveRuntimeStaticCorrelations/attachRuntimeStaticCorrelations
+                  call) - it only displays the exact context it was given.
+                  A recognized artifactKind with a schemaVersion other than
+                  the currently supported one starts the viewer showing an
+                  honest "unsupported version" context state rather than
+                  failing. An unreadable file, invalid JSON, wrong
+                  artifactKind, or a structurally invalid current-schema
+                  artifact fails startup clearly. Omit to run with no
+                  bounded context supplied (the viewer remains fully usable;
+                  the context panel says none was supplied). May be combined
+                  with --bindings-file.
+  --no-open       Do not attempt to open the system default browser after
+                  the server starts. Browser auto-open is a best-effort
+                  convenience only: its failure is never fatal and never
+                  affects server startup success.
+  --help          Show this help.
+
+Starts one Node HTTP server bound only to 127.0.0.1, serving the built
+React + TypeScript + Vite viewer application (and its PWA manifest/service
+worker) plus its local evidence API. With --root the session is read-only
+and never writes to the supplied evidence root. Without --root the
+project-aware session also enables local visual-annotation authoring: the
+viewer page may save immutable annotations, promote selected confirmed
+runtime intent into a change contract, and materialize selected confirmed
+reference intent into a new imported reference revision, all inside the
+project's managed evidence root. The server never edits target source,
+never approves baselines or references, never exposes the evidence root as
+a generic static directory, and never launches a browser observation. The
+process keeps running (serving the viewer) until interrupted. On success,
+prints the viewer URL and exits only when the server stops. On invalid
+syntax, a missing/non-directory --root, an invalid --port, or a port
+already in use, prints structured diagnostics to stderr and exits nonzero
+without starting a server.
 `;
 const INIT_HELP = `Usage:
   my-frontend-observer init --url <loopback-url> [options]
@@ -178,367 +184,367 @@ Options:
 
 Exit codes: PASS 0; FAIL 1; REVIEW_REQUIRED 2; BLOCKED 3.
 `;
-const OBSERVE_HELP = `Usage:
-  my-frontend-observer observe --url <loopback-url> [options]
-
-Required:
-  --url <url>              Loopback target URL (http/https, localhost/127.x.x.x/::1 only).
-
-Options:
-  --viewport <WIDTHxHEIGHT> Viewport size, e.g. 1280x720.
-  --target <id=selector>    An explicit CSS-shorthand observation target.
-                            Repeatable. Parsed on the first "=" only, so
-                            selectors containing "=" (e.g.
-                            button[data-state="active"]) are preserved
-                            intact. Cannot be combined with --targets-file.
-  --targets-file <json-file> Loads structured semantic observation targets
-                            from a local JSON file: { "targets": [ { "name":
-                            "...", "locators": [ { "kind": "role"|"id"|
-                            "data-attribute"|"semantic-element"|"css"|"text",
-                            ... } ] } ] }. Locator order within a target is
-                            the fallback order. Relative paths resolve from
-                            the current working directory; the file path
-                            itself is never persisted into the artifact or
-                            included in the observation's request identity.
-                            Cannot be combined with --target.
-  --scroll-scenario-file <json-file>
-                            Loads one bounded runtime scroll scenario from a
-                            local JSON file: { "action": { "kind":
-                            "window-scroll-by"|"target-scroll-by", ...,
-                            "deltaX": <int>, "deltaY": <int> } }.
-                            "target-scroll-by" additionally requires a
-                            "target" naming a configured stable target.
-                            Exactly zero or one scenario per observation.
-                            Relative paths resolve from the current working
-                            directory; the file path itself is never
-                            persisted into the artifact or included in the
-                            observation's request identity. May be combined
-                            with either --target or --targets-file.
-  --state-file <json-file>  Loads explicit, caller-declared frontend state
-                            identity from a local JSON file: { "theme":
-                            "...", "applicationState": "...",
-                            "authenticatedState": "authenticated"|
-                            "unauthenticated" } (each field independently
-                            optional; at least one required). Never inferred
-                            by the observer from screenshot pixels, CSS, DOM,
-                            or URLs - this is caller-declared metadata only,
-                            used solely for later comparability/compatibility
-                            evaluation. Relative paths resolve from the
-                            current working directory; the file path itself
-                            is never persisted into the artifact or included
-                            in the observation's request identity.
-  --output <directory>      Portable, relative output location for the
-                            observation artifact.
-  --timeout <ms>            Overall request timeout in milliseconds.
-  --help                    Show this help.
-
-On success, prints a concise result and exits 0. On invalid syntax, invalid
-request, unsafe/failed navigation, or a failed artifact write, prints
-structured diagnostics to stderr and exits nonzero. No progress output is
-printed during a normal capture.
+const OBSERVE_HELP = `Usage:
+  my-frontend-observer observe --url <loopback-url> [options]
+
+Required:
+  --url <url>              Loopback target URL (http/https, localhost/127.x.x.x/::1 only).
+
+Options:
+  --viewport <WIDTHxHEIGHT> Viewport size, e.g. 1280x720.
+  --target <id=selector>    An explicit CSS-shorthand observation target.
+                            Repeatable. Parsed on the first "=" only, so
+                            selectors containing "=" (e.g.
+                            button[data-state="active"]) are preserved
+                            intact. Cannot be combined with --targets-file.
+  --targets-file <json-file> Loads structured semantic observation targets
+                            from a local JSON file: { "targets": [ { "name":
+                            "...", "locators": [ { "kind": "role"|"id"|
+                            "data-attribute"|"semantic-element"|"css"|"text",
+                            ... } ] } ] }. Locator order within a target is
+                            the fallback order. Relative paths resolve from
+                            the current working directory; the file path
+                            itself is never persisted into the artifact or
+                            included in the observation's request identity.
+                            Cannot be combined with --target.
+  --scroll-scenario-file <json-file>
+                            Loads one bounded runtime scroll scenario from a
+                            local JSON file: { "action": { "kind":
+                            "window-scroll-by"|"target-scroll-by", ...,
+                            "deltaX": <int>, "deltaY": <int> } }.
+                            "target-scroll-by" additionally requires a
+                            "target" naming a configured stable target.
+                            Exactly zero or one scenario per observation.
+                            Relative paths resolve from the current working
+                            directory; the file path itself is never
+                            persisted into the artifact or included in the
+                            observation's request identity. May be combined
+                            with either --target or --targets-file.
+  --state-file <json-file>  Loads explicit, caller-declared frontend state
+                            identity from a local JSON file: { "theme":
+                            "...", "applicationState": "...",
+                            "authenticatedState": "authenticated"|
+                            "unauthenticated" } (each field independently
+                            optional; at least one required). Never inferred
+                            by the observer from screenshot pixels, CSS, DOM,
+                            or URLs - this is caller-declared metadata only,
+                            used solely for later comparability/compatibility
+                            evaluation. Relative paths resolve from the
+                            current working directory; the file path itself
+                            is never persisted into the artifact or included
+                            in the observation's request identity.
+  --output <directory>      Portable, relative output location for the
+                            observation artifact.
+  --timeout <ms>            Overall request timeout in milliseconds.
+  --help                    Show this help.
+
+On success, prints a concise result and exits 0. On invalid syntax, invalid
+request, unsafe/failed navigation, or a failed artifact write, prints
+structured diagnostics to stderr and exits nonzero. No progress output is
+printed during a normal capture.
 `;
-const COMPARE_HELP = `Usage:
-  my-frontend-observer compare --before <observation-artifact-root> --after <observation-artifact-root> --output <directory> [options]
-
-Required:
-  --before <path>           Root directory of the "before" persisted
-                             observation artifact (the directory containing
-                             its manifest.json).
-  --after <path>             Root directory of the "after" persisted
-                             observation artifact.
-  --output <directory>      Portable, relative output location for the
-                            comparison artifact.
-
-Options:
-  --config-file <json-file> Loads a comparison configuration from a local
-                            JSON file: { "geometryTolerancePx": <0-10>,
-                            "expectedDependencies": [ { "cause": { "target":
-                            "...", "property": "x"|"y"|"width"|"height",
-                            "direction": "increase"|"decrease"|"change"|
-                            "unchanged" }, "effect": { ... same shape ... },
-                            "source": "explicit-config" } ] }. Relative
-                            paths resolve from the current working
-                            directory; the file path itself is never
-                            persisted into the artifact or included in the
-                            comparison request identity. Without
-                            --config-file, geometryTolerancePx defaults to
-                            0.5 with no declared dependencies.
-  --help                    Show this help.
-
-Comparison reads two already-persisted observation artifacts and derives
-evidence purely from their existing content - it never launches a browser
-and never re-observes either target. On success, prints a concise result
-and exits 0, including when the two observations are found to be
-"incomparable" (that is itself a successful comparison outcome, not a
-failure). On invalid syntax, an unreadable or structurally invalid source
-artifact, invalid configuration, or a failed artifact write, prints
-structured diagnostics to stderr and exits nonzero. No progress output is
-printed during a normal comparison.
+const COMPARE_HELP = `Usage:
+  my-frontend-observer compare --before <observation-artifact-root> --after <observation-artifact-root> --output <directory> [options]
+
+Required:
+  --before <path>           Root directory of the "before" persisted
+                             observation artifact (the directory containing
+                             its manifest.json).
+  --after <path>             Root directory of the "after" persisted
+                             observation artifact.
+  --output <directory>      Portable, relative output location for the
+                            comparison artifact.
+
+Options:
+  --config-file <json-file> Loads a comparison configuration from a local
+                            JSON file: { "geometryTolerancePx": <0-10>,
+                            "expectedDependencies": [ { "cause": { "target":
+                            "...", "property": "x"|"y"|"width"|"height",
+                            "direction": "increase"|"decrease"|"change"|
+                            "unchanged" }, "effect": { ... same shape ... },
+                            "source": "explicit-config" } ] }. Relative
+                            paths resolve from the current working
+                            directory; the file path itself is never
+                            persisted into the artifact or included in the
+                            comparison request identity. Without
+                            --config-file, geometryTolerancePx defaults to
+                            0.5 with no declared dependencies.
+  --help                    Show this help.
+
+Comparison reads two already-persisted observation artifacts and derives
+evidence purely from their existing content - it never launches a browser
+and never re-observes either target. On success, prints a concise result
+and exits 0, including when the two observations are found to be
+"incomparable" (that is itself a successful comparison outcome, not a
+failure). On invalid syntax, an unreadable or structurally invalid source
+artifact, invalid configuration, or a failed artifact write, prints
+structured diagnostics to stderr and exits nonzero. No progress output is
+printed during a normal comparison.
 `;
-const APPROVE_BASELINE_HELP = `Usage:
-  my-frontend-observer approve-baseline --observation <observation-artifact-root> --contract-file <json-file> --output <directory>
-
-Required:
-  --observation <path>      Root directory of the persisted observation
-                             artifact (the directory containing its
-                             manifest.json) that this baseline claims to
-                             approve.
-  --contract-file <json-file> Local JSON file containing one already-authored
-                             persistent baseline contract (the raw contract
-                             value, no wrapper field). Relative paths resolve
-                             from the current working directory; the file
-                             path itself is never persisted or included in
-                             any identity.
-  --output <directory>      Portable, relative output location for the
-                             baseline artifact.
-
-Options:
-  --help                     Show this help.
-
-This command is the only explicit baseline-approval act in the observer -
-approval is never inferred from a successful comparison or evaluation. The
-supplied contract's source-observation reference must match the supplied
-observation artifact's stable identity; a mismatched or unrelated observation
-is rejected. Any \`supersedesBaselineId\` already authored in the contract is
-preserved exactly - this command never discovers, infers, or deletes a prior
-baseline. Remains local and non-mutating: it never launches a browser and
-never modifies the source observation or any existing baseline artifact. On
-success, prints a concise result and exits 0. On invalid syntax, an
-unreadable/malformed contract file, a non-baseline contract, a
-structurally invalid contract, a source-observation mismatch, an existing
-artifact collision, or a persistence failure, prints structured diagnostics
-to stderr and exits nonzero.
+const APPROVE_BASELINE_HELP = `Usage:
+  my-frontend-observer approve-baseline --observation <observation-artifact-root> --contract-file <json-file> --output <directory>
+
+Required:
+  --observation <path>      Root directory of the persisted observation
+                             artifact (the directory containing its
+                             manifest.json) that this baseline claims to
+                             approve.
+  --contract-file <json-file> Local JSON file containing one already-authored
+                             persistent baseline contract (the raw contract
+                             value, no wrapper field). Relative paths resolve
+                             from the current working directory; the file
+                             path itself is never persisted or included in
+                             any identity.
+  --output <directory>      Portable, relative output location for the
+                             baseline artifact.
+
+Options:
+  --help                     Show this help.
+
+This command is the only explicit baseline-approval act in the observer -
+approval is never inferred from a successful comparison or evaluation. The
+supplied contract's source-observation reference must match the supplied
+observation artifact's stable identity; a mismatched or unrelated observation
+is rejected. Any \`supersedesBaselineId\` already authored in the contract is
+preserved exactly - this command never discovers, infers, or deletes a prior
+baseline. Remains local and non-mutating: it never launches a browser and
+never modifies the source observation or any existing baseline artifact. On
+success, prints a concise result and exits 0. On invalid syntax, an
+unreadable/malformed contract file, a non-baseline contract, a
+structurally invalid contract, a source-observation mismatch, an existing
+artifact collision, or a persistence failure, prints structured diagnostics
+to stderr and exits nonzero.
 `;
-const SAVE_CHANGE_CONTRACT_HELP = `Usage:
-  my-frontend-observer save-change-contract --contract-file <json-file> --output <directory>
-
-Required:
-  --contract-file <json-file> Local JSON file containing one already-authored
-                             per-change contract (the raw contract value, no
-                             wrapper field). Relative paths resolve from the
-                             current working directory; the file path itself
-                             is never persisted or included in any identity.
-  --output <directory>      Portable, relative output location for the
-                             change-contract artifact.
-
-Options:
-  --help                     Show this help.
-
-This command validates and persists a per-change contract only - it does not
-approve anything. Any \`supersedesBaselineClauseIds\` already authored on a
-clause is preserved exactly; resolving those references against a particular
-baseline remains \`evaluate-contract\`'s responsibility, not this command's.
-Remains local and non-mutating. On success, prints a concise result and
-exits 0. On invalid syntax, an unreadable/malformed contract file, a
-non-change contract (e.g. a persistent baseline contract), a structurally
-invalid contract (including an authored \`unexpected\` category, which is
-never a valid authored scope), an existing artifact collision, or a
-persistence failure, prints structured diagnostics to stderr and exits
-nonzero.
+const SAVE_CHANGE_CONTRACT_HELP = `Usage:
+  my-frontend-observer save-change-contract --contract-file <json-file> --output <directory>
+
+Required:
+  --contract-file <json-file> Local JSON file containing one already-authored
+                             per-change contract (the raw contract value, no
+                             wrapper field). Relative paths resolve from the
+                             current working directory; the file path itself
+                             is never persisted or included in any identity.
+  --output <directory>      Portable, relative output location for the
+                             change-contract artifact.
+
+Options:
+  --help                     Show this help.
+
+This command validates and persists a per-change contract only - it does not
+approve anything. Any \`supersedesBaselineClauseIds\` already authored on a
+clause is preserved exactly; resolving those references against a particular
+baseline remains \`evaluate-contract\`'s responsibility, not this command's.
+Remains local and non-mutating. On success, prints a concise result and
+exits 0. On invalid syntax, an unreadable/malformed contract file, a
+non-change contract (e.g. a persistent baseline contract), a structurally
+invalid contract (including an authored \`unexpected\` category, which is
+never a valid authored scope), an existing artifact collision, or a
+persistence failure, prints structured diagnostics to stderr and exits
+nonzero.
 `;
-const EVALUATE_CONTRACT_HELP = `Usage:
-  my-frontend-observer evaluate-contract --before <observation-artifact-root> --after <observation-artifact-root> --comparison <comparison-artifact-root> --baseline <baseline-contract-artifact-root> --change <per-change-contract-artifact-root> --output <directory> [--enforce]
-
-Required:
-  --before <path>      Root directory of the "before" persisted observation
-                        artifact.
-  --after <path>        Root directory of the "after" persisted observation
-                        artifact.
-  --comparison <path>   Root directory of the already-persisted comparison
-                        artifact for that before/after pair.
-  --baseline <path>     Root directory of the already-approved persistent
-                        baseline contract artifact.
-  --change <path>       Root directory of the already-persisted per-change
-                        contract artifact.
-  --output <directory>  Portable, relative output location for the
-                        evaluation artifact.
-
-Options:
-  --enforce  Make a FAIL verdict produce a nonzero process exit status. A
-             FAIL evaluation is always persisted and printed identically
-             with or without this flag - it changes only the process exit
-             code, never evaluation identity, contents, or persistence.
-  --help     Show this help.
-
-This command never launches a browser, never re-resolves targets, and never
-recomputes comparison or relationship evidence - it reads the already-
-persisted before/after observations and comparison exactly as given and
-evaluates the supplied baseline/change contracts against them exactly once.
-A FAIL verdict (a found regression or unsatisfied contract clause) is a
-successful, persisted evaluation outcome, not an execution error; without
---enforce it exits 0 like PASS. On success (evaluation constructed and
-persisted, verdict PASS, or verdict FAIL without --enforce), prints a
-concise result and exits 0. With --enforce and verdict FAIL, prints the same
-result and exits nonzero. On invalid syntax, an unreadable/malformed/
-incoherent source artifact, or a persistence failure (evaluation could not
-even be constructed), prints structured diagnostics to stderr, persists
-nothing, and exits nonzero.
+const EVALUATE_CONTRACT_HELP = `Usage:
+  my-frontend-observer evaluate-contract --before <observation-artifact-root> --after <observation-artifact-root> --comparison <comparison-artifact-root> --baseline <baseline-contract-artifact-root> --change <per-change-contract-artifact-root> --output <directory> [--enforce]
+
+Required:
+  --before <path>      Root directory of the "before" persisted observation
+                        artifact.
+  --after <path>        Root directory of the "after" persisted observation
+                        artifact.
+  --comparison <path>   Root directory of the already-persisted comparison
+                        artifact for that before/after pair.
+  --baseline <path>     Root directory of the already-approved persistent
+                        baseline contract artifact.
+  --change <path>       Root directory of the already-persisted per-change
+                        contract artifact.
+  --output <directory>  Portable, relative output location for the
+                        evaluation artifact.
+
+Options:
+  --enforce  Make a FAIL verdict produce a nonzero process exit status. A
+             FAIL evaluation is always persisted and printed identically
+             with or without this flag - it changes only the process exit
+             code, never evaluation identity, contents, or persistence.
+  --help     Show this help.
+
+This command never launches a browser, never re-resolves targets, and never
+recomputes comparison or relationship evidence - it reads the already-
+persisted before/after observations and comparison exactly as given and
+evaluates the supplied baseline/change contracts against them exactly once.
+A FAIL verdict (a found regression or unsatisfied contract clause) is a
+successful, persisted evaluation outcome, not an execution error; without
+--enforce it exits 0 like PASS. On success (evaluation constructed and
+persisted, verdict PASS, or verdict FAIL without --enforce), prints a
+concise result and exits 0. With --enforce and verdict FAIL, prints the same
+result and exits nonzero. On invalid syntax, an unreadable/malformed/
+incoherent source artifact, or a persistence failure (evaluation could not
+even be constructed), prints structured diagnostics to stderr, persists
+nothing, and exits nonzero.
 `;
-const IMPORT_REFERENCE_HELP = `Usage:
-  my-frontend-observer import-reference <image-file> --output <directory> [options]
-
-Required:
-  <image-file>           Local path to a PNG, JPEG, or WebP external design-
-                          reference image.
-  --output <directory>   Portable, relative output location for the
-                          external-reference artifact.
-
-Options:
-  --label <text>         Optional human-readable label, stored as pure
-                          provenance - never part of the reference's logical
-                          identity.
-  --supersedes <path>    Root directory of a prior external-reference
-                          artifact (imported or approved) that this import
-                          explicitly supersedes. The prior artifact is never
-                          modified.
-  --regions-file <json-file>  Local JSON file of the form { "regions": [...] }
-                          declaring explicit, meaningful reference-image
-                          regions (id + a {x, y, width, height} rectangle in
-                          reference-image pixels, origin at the image's
-                          top-left corner). Optional - a reference imported
-                          without this flag behaves exactly as in v0.7 Prompt
-                          1. Region content participates in the reference's
-                          logical identity; the file path itself never does.
-  --requirements-file <json-file>  Local JSON file of the form
-                          { "requirements": [...] } declaring explicit,
-                          user-selected design requirements over the regions
-                          above - what actually matters for later candidate
-                          evaluation, never inferred merely because a region
-                          property/relationship exists. Each requirement has
-                          a "category" (requested | expected-dependent |
-                          protected | preserved - "unexpected" is never
-                          authorable), a "subject" (a region property, a
-                          region-to-region relationship, or a derived
-                          two-region measurement), and - for property/
-                          measurement subjects - a "tolerance" (exact |
-                          absolute-reference-px | percent; relationship
-                          subjects must omit tolerance). Requires --regions-
-                          file (or an already-present region set) supplying
-                          every region a requirement refers to. Optional -
-                          a reference imported without this flag behaves
-                          exactly as in v0.7 Prompt 1/2. Requirement content
-                          participates in the reference's logical identity.
-  --applicability-file <json-file>  Local JSON file declaring the runtime
-                          frontend state this reference is intended to
-                          represent: { "viewport": { "width", "height" },
-                          "theme": "...", "applicationState": "...",
-                          "authenticatedState": "authenticated"|
-                          "unauthenticated" } (each field independently
-                          optional; at least one required). "viewport" here
-                          is the CSS-pixel runtime viewport the design
-                          represents - distinct from the reference image's
-                          own pixel dimensions, which are never assumed
-                          equal. Never inferred from the image - caller-
-                          declared metadata only, used for later reference/
-                          candidate compatibility evaluation (see
-                          docs/CONTRACTS.md "v0.7 Prompt 4"). Optional - a
-                          reference imported without this flag behaves
-                          exactly as in v0.7 Prompt 1/2/3. Applicability
-                          content participates in the reference's logical
-                          identity.
-  --help                 Show this help.
-
-Detects the image format from its header bytes only (never from the file
-extension), reads its pixel dimensions from the same bounded header bytes
-(never decoding pixel data), and persists a new external-reference artifact
-in the "imported" lifecycle state - importing never approves it. On success,
-prints a concise result (including the accepted region/requirement counts,
-the resulting reference-side requirement adequacy: adequate, partial, or
-inadequate, and whether applicability was declared) and exits 0. On an
-unreadable file, an unsupported or undetectable format, invalid/out-of-bound
-dimensions, an over-limit file size, an unresolvable --supersedes target, an
-invalid region (missing/duplicate/malformed id, non-finite/negative/zero
-geometry, a region extending outside the image, or more than the bounded
-maximum region count), an invalid requirement (unsupported category/
-property/measurement/relationship, a tolerance that is missing/inapplicable/
-out of bounds, a reference to an unknown region id, a duplicate requirement
-subject, or more than the bounded maximum requirement count), or invalid
-applicability (an out-of-bound viewport, an invalid state label, an
-unsupported authenticatedState value, or an empty applicability object),
-prints structured diagnostics to stderr and exits nonzero.
+const IMPORT_REFERENCE_HELP = `Usage:
+  my-frontend-observer import-reference <image-file> --output <directory> [options]
+
+Required:
+  <image-file>           Local path to a PNG, JPEG, or WebP external design-
+                          reference image.
+  --output <directory>   Portable, relative output location for the
+                          external-reference artifact.
+
+Options:
+  --label <text>         Optional human-readable label, stored as pure
+                          provenance - never part of the reference's logical
+                          identity.
+  --supersedes <path>    Root directory of a prior external-reference
+                          artifact (imported or approved) that this import
+                          explicitly supersedes. The prior artifact is never
+                          modified.
+  --regions-file <json-file>  Local JSON file of the form { "regions": [...] }
+                          declaring explicit, meaningful reference-image
+                          regions (id + a {x, y, width, height} rectangle in
+                          reference-image pixels, origin at the image's
+                          top-left corner). Optional - a reference imported
+                          without this flag behaves exactly as in v0.7 Prompt
+                          1. Region content participates in the reference's
+                          logical identity; the file path itself never does.
+  --requirements-file <json-file>  Local JSON file of the form
+                          { "requirements": [...] } declaring explicit,
+                          user-selected design requirements over the regions
+                          above - what actually matters for later candidate
+                          evaluation, never inferred merely because a region
+                          property/relationship exists. Each requirement has
+                          a "category" (requested | expected-dependent |
+                          protected | preserved - "unexpected" is never
+                          authorable), a "subject" (a region property, a
+                          region-to-region relationship, or a derived
+                          two-region measurement), and - for property/
+                          measurement subjects - a "tolerance" (exact |
+                          absolute-reference-px | percent; relationship
+                          subjects must omit tolerance). Requires --regions-
+                          file (or an already-present region set) supplying
+                          every region a requirement refers to. Optional -
+                          a reference imported without this flag behaves
+                          exactly as in v0.7 Prompt 1/2. Requirement content
+                          participates in the reference's logical identity.
+  --applicability-file <json-file>  Local JSON file declaring the runtime
+                          frontend state this reference is intended to
+                          represent: { "viewport": { "width", "height" },
+                          "theme": "...", "applicationState": "...",
+                          "authenticatedState": "authenticated"|
+                          "unauthenticated" } (each field independently
+                          optional; at least one required). "viewport" here
+                          is the CSS-pixel runtime viewport the design
+                          represents - distinct from the reference image's
+                          own pixel dimensions, which are never assumed
+                          equal. Never inferred from the image - caller-
+                          declared metadata only, used for later reference/
+                          candidate compatibility evaluation (see
+                          docs/CONTRACTS.md "v0.7 Prompt 4"). Optional - a
+                          reference imported without this flag behaves
+                          exactly as in v0.7 Prompt 1/2/3. Applicability
+                          content participates in the reference's logical
+                          identity.
+  --help                 Show this help.
+
+Detects the image format from its header bytes only (never from the file
+extension), reads its pixel dimensions from the same bounded header bytes
+(never decoding pixel data), and persists a new external-reference artifact
+in the "imported" lifecycle state - importing never approves it. On success,
+prints a concise result (including the accepted region/requirement counts,
+the resulting reference-side requirement adequacy: adequate, partial, or
+inadequate, and whether applicability was declared) and exits 0. On an
+unreadable file, an unsupported or undetectable format, invalid/out-of-bound
+dimensions, an over-limit file size, an unresolvable --supersedes target, an
+invalid region (missing/duplicate/malformed id, non-finite/negative/zero
+geometry, a region extending outside the image, or more than the bounded
+maximum region count), an invalid requirement (unsupported category/
+property/measurement/relationship, a tolerance that is missing/inapplicable/
+out of bounds, a reference to an unknown region id, a duplicate requirement
+subject, or more than the bounded maximum requirement count), or invalid
+applicability (an out-of-bound viewport, an invalid state label, an
+unsupported authenticatedState value, or an empty applicability object),
+prints structured diagnostics to stderr and exits nonzero.
 `;
-const APPROVE_REFERENCE_HELP = `Usage:
-  my-frontend-observer approve-reference --reference <external-reference-artifact-root> --output <directory> [options]
-
-Required:
-  --reference <path>     Root directory of the already-imported
-                          external-reference artifact (the directory
-                          containing its manifest.json) to approve.
-  --output <directory>   Portable, relative output location for the newly
-                          persisted approved artifact.
-
-Options:
-  --supersedes <path>    Root directory of a prior external-reference
-                          artifact (imported or approved) that this approval
-                          explicitly supersedes. The prior artifact is never
-                          modified.
-  --help                 Show this help.
-
-This is the only explicit reference-approval act in the observer - approval
-is never inferred from a successful import or from any later fidelity
-evaluation. Approving persists a brand-new artifact instance (a fresh
-referenceId sharing the imported artifact's referenceRequestId) that carries
-a reference back to the imported artifact's image rather than a second copy
-of its bytes; the imported artifact's own manifest is never modified. Any
-regions, requirements, and applicability already declared on the imported
-artifact are carried forward unchanged (not re-validated against new input,
-not re-derived) - approval never adds, removes, or edits regions,
-requirements, or applicability. Only a reference currently in the "imported"
-lifecycle state can be approved. On success, prints a concise result
-(including the carried-forward region/requirement counts, reference-side
-requirement adequacy, and whether applicability was declared) and exits 0.
-On an unreadable/malformed --reference target, a target that is not in the
-"imported" state, an unresolvable --supersedes target, or a persistence
-failure, prints structured diagnostics to stderr and exits nonzero.
+const APPROVE_REFERENCE_HELP = `Usage:
+  my-frontend-observer approve-reference --reference <external-reference-artifact-root> --output <directory> [options]
+
+Required:
+  --reference <path>     Root directory of the already-imported
+                          external-reference artifact (the directory
+                          containing its manifest.json) to approve.
+  --output <directory>   Portable, relative output location for the newly
+                          persisted approved artifact.
+
+Options:
+  --supersedes <path>    Root directory of a prior external-reference
+                          artifact (imported or approved) that this approval
+                          explicitly supersedes. The prior artifact is never
+                          modified.
+  --help                 Show this help.
+
+This is the only explicit reference-approval act in the observer - approval
+is never inferred from a successful import or from any later fidelity
+evaluation. Approving persists a brand-new artifact instance (a fresh
+referenceId sharing the imported artifact's referenceRequestId) that carries
+a reference back to the imported artifact's image rather than a second copy
+of its bytes; the imported artifact's own manifest is never modified. Any
+regions, requirements, and applicability already declared on the imported
+artifact are carried forward unchanged (not re-validated against new input,
+not re-derived) - approval never adds, removes, or edits regions,
+requirements, or applicability. Only a reference currently in the "imported"
+lifecycle state can be approved. On success, prints a concise result
+(including the carried-forward region/requirement counts, reference-side
+requirement adequacy, and whether applicability was declared) and exits 0.
+On an unreadable/malformed --reference target, a target that is not in the
+"imported" state, an unresolvable --supersedes target, or a persistence
+failure, prints structured diagnostics to stderr and exits nonzero.
 `;
-const EVALUATE_REFERENCE_FIDELITY_HELP = `Usage:
-  my-frontend-observer evaluate-reference-fidelity --reference <external-reference-artifact-root> --candidate <observation-artifact-root> [options]
-
-Required:
-  --reference <path>   Root directory of an already-imported or already-
-                        approved external-reference artifact (the directory
-                        containing its manifest.json).
-  --candidate <path>   Root directory of the already-persisted candidate
-                        observation artifact to evaluate against it.
-
-Options:
-  --bindings-file <json-file>  Local JSON file of the form
-                        { "bindings": [ { "referenceRegion": "...",
-                        "runtimeTarget": "..." } ] } declaring which stable
-                        observer runtime target (a configured target name -
-                        see "observe" --target/--targets-file) explicitly
-                        corresponds to each reference region a selected
-                        requirement depends on. Never inferred from
-                        geometry, matching names, or source code - a
-                        binding exists only because this file declares it.
-                        Optional - omitting it (or supplying an empty
-                        "bindings" array) evaluates with no bindings at
-                        all, so every requirement whose subject depends on
-                        a reference region becomes "unavailable".
-  --enforce  Make a FAIL fidelity result produce a nonzero process exit
-             status. A FAIL result is always printed identically with or
-             without this flag - it changes only the process exit code,
-             never the evaluation's content. Has no effect on a
-             "not-evaluated" result (a reference-adequacy or compatibility
-             blocker is never treated as a design mismatch).
-  --help     Show this help.
-
-This command never launches a browser, never re-resolves targets, and
-never recomputes reference regions/requirements/adequacy, compatibility, or
-bindings - it reads the already-persisted reference and candidate exactly
-as given, evaluates the supplied binding declarations, and evaluates every
-one of the reference's selected requirements exactly once. It persists
-nothing: the result exists only for this invocation. On success, prints a
-concise result (reference-side adequacy, compatibility state, the overall
-fidelity state - "not-evaluated"/"pass"/"fail" - and a pass/fail/unavailable
-requirement breakdown) and exits 0, unless --enforce is given and the
-fidelity state is "fail", in which case it exits nonzero. A "not-evaluated"
-result (reference adequacy inadequate, or reference/candidate
-incompatible) is a successful, structured evaluation outcome, never an
-execution error - it always exits 0. On invalid syntax, an unreadable/
-malformed --reference or --candidate target, a malformed --bindings-file,
-or an invalid/out-of-bound binding declaration, prints structured
-diagnostics to stderr and exits nonzero.
+const EVALUATE_REFERENCE_FIDELITY_HELP = `Usage:
+  my-frontend-observer evaluate-reference-fidelity --reference <external-reference-artifact-root> --candidate <observation-artifact-root> [options]
+
+Required:
+  --reference <path>   Root directory of an already-imported or already-
+                        approved external-reference artifact (the directory
+                        containing its manifest.json).
+  --candidate <path>   Root directory of the already-persisted candidate
+                        observation artifact to evaluate against it.
+
+Options:
+  --bindings-file <json-file>  Local JSON file of the form
+                        { "bindings": [ { "referenceRegion": "...",
+                        "runtimeTarget": "..." } ] } declaring which stable
+                        observer runtime target (a configured target name -
+                        see "observe" --target/--targets-file) explicitly
+                        corresponds to each reference region a selected
+                        requirement depends on. Never inferred from
+                        geometry, matching names, or source code - a
+                        binding exists only because this file declares it.
+                        Optional - omitting it (or supplying an empty
+                        "bindings" array) evaluates with no bindings at
+                        all, so every requirement whose subject depends on
+                        a reference region becomes "unavailable".
+  --enforce  Make a FAIL fidelity result produce a nonzero process exit
+             status. A FAIL result is always printed identically with or
+             without this flag - it changes only the process exit code,
+             never the evaluation's content. Has no effect on a
+             "not-evaluated" result (a reference-adequacy or compatibility
+             blocker is never treated as a design mismatch).
+  --help     Show this help.
+
+This command never launches a browser, never re-resolves targets, and
+never recomputes reference regions/requirements/adequacy, compatibility, or
+bindings - it reads the already-persisted reference and candidate exactly
+as given, evaluates the supplied binding declarations, and evaluates every
+one of the reference's selected requirements exactly once. It persists
+nothing: the result exists only for this invocation. On success, prints a
+concise result (reference-side adequacy, compatibility state, the overall
+fidelity state - "not-evaluated"/"pass"/"fail" - and a pass/fail/unavailable
+requirement breakdown) and exits 0, unless --enforce is given and the
+fidelity state is "fail", in which case it exits nonzero. A "not-evaluated"
+result (reference adequacy inadequate, or reference/candidate
+incompatible) is a successful, structured evaluation outcome, never an
+execution error - it always exits 0. On invalid syntax, an unreadable/
+malformed --reference or --candidate target, a malformed --bindings-file,
+or an invalid/out-of-bound binding declaration, prints structured
+diagnostics to stderr and exits nonzero.
 `;
 function parseViewport(raw) {
     const match = /^(\d+)x(\d+)$/.exec(raw);
@@ -2290,6 +2296,8 @@ async function runViewCommand(argv, io) {
     }
     let root;
     let aliasMetadata;
+    // v0.9 Batch 2: only the normal project-aware form enables annotation authoring; explicit --root stays read-only.
+    let authoringProjectRoot;
     if (parsedArgs.root !== undefined) {
         root = parsedArgs.root;
     }
@@ -2306,6 +2314,7 @@ async function runViewCommand(argv, io) {
         }
         root = projectState.root;
         aliasMetadata = { observationAliasesByRelativeDir: projectState.aliases };
+        authoringProjectRoot = projectState.projectRoot;
     }
     const result = await startViewer({
         root,
@@ -2313,6 +2322,7 @@ async function runViewCommand(argv, io) {
         bindingDeclarations,
         context: contextState,
         ...(aliasMetadata === undefined ? {} : { aliasMetadata }),
+        ...(authoringProjectRoot === undefined ? {} : { authoringProjectRoot }),
     });
     if (!result.ok) {
         for (const diagnostic of result.diagnostics)