reflection-check 0.0.2 → 0.0.4

package/docs/browser-contract.md

@@ -30,12 +30,22 @@ browser: {
     reuseExisting: true,
     timeoutMs: 60_000
   },
+  setup: {
+    localStorage: {
+      'reflection:test-mode': 'enabled'
+    }
+  },
   maskSelectors: ['[data-reflection-mask]'],
   routes: [
     {
       id: 'login',
       path: '/login',
       viewports: ['desktop', 'mobile'],
+      setup: {
+        sessionStorage: {
+          'reflection:login-state': 'ready'
+        }
+      },
       expects: [
         { role: 'heading', name: 'Login' },
         { label: 'Email' },
@@ -51,6 +61,27 @@ browser: {
 }
 ```
 
+## Route setup for authenticated fixtures
+
+Use `setup.localStorage` and `setup.sessionStorage` to seed non-secret test state before Reflection navigates to a route:
+
+```ts
+routes: [
+  {
+    id: 'authenticated-home',
+    path: '/',
+    setup: {
+      localStorage: {
+        'reflection:test-user': 'fixture-user'
+      }
+    },
+    expects: [{ text: 'Welcome fixture-user' }]
+  }
+]
+```
+
+Browser-level setup applies to every route, and route-level setup extends or overrides it. Reflection records only setup key names in metadata so reports show that setup ran without logging values. Keep real credentials and production session values out of committed config; prefer test-mode auth or mock fixture tokens.
+
 ## Expectations
 
 | Expectation | Use for |

package/docs/ci.md

@@ -4,8 +4,18 @@ Reflection is designed to be safe in CI: runs create evidence artifacts, but the
 
 ## Recommended command
 
+Install Reflection in the consuming repository:
+
+```bash
+pnpm add -D reflection-check
+```
+
+Then run the CI evidence loop:
+
 ```bash
+reflection doctor --config reflection.config.ts
 reflection run --ci --config reflection.config.ts --mode smoke
+reflection review --report-dir artifacts/reflection --json
 ```
 
 When `--ci` is enabled and `--report-dir` is not provided, Reflection writes artifacts to:
@@ -41,4 +51,4 @@ artifacts/reflection/runs/latest
 
 ## GitHub Actions example
 
-See `.github/workflows/reflection.yml` for a repo-owned example that installs dependencies, builds Reflection, runs `reflection run --ci`, and uploads `artifacts/reflection` for review.
+See `.github/workflows/reflection.yml` for a repo-owned example that installs dependencies, builds Reflection, runs `reflection run --ci`, reviews `artifacts/reflection`, and uploads the report root for inspection.

package/docs/configuration.md

@@ -59,6 +59,11 @@ browser: {
     reuseExisting: true,
     timeoutMs: 60_000
   },
+  setup: {
+    localStorage: {
+      'reflection:test-mode': 'enabled'
+    }
+  },
   maskSelectors: ['[data-reflection-mask]'],
   routes: [
     {
@@ -66,6 +71,11 @@ browser: {
       name: 'Home route',
       path: '/',
       viewports: ['desktop', 'mobile'],
+      setup: {
+        sessionStorage: {
+          'reflection:route-state': 'ready'
+        }
+      },
       expects: [
         { role: 'heading', name: 'Home' },
         { noHorizontalOverflow: true },
@@ -96,10 +106,26 @@ Browser fields:
 | `blocking` | Defaults to `true`; route assertion failures are blocking unless configured otherwise by current runner behavior. |
 | `baseUrl` | Absolute URL used to visit route paths. |
 | `server` | Optional managed server. If omitted, Reflection assumes `baseUrl` is already reachable. |
+| `setup` | Optional browser-level storage setup applied before route navigation. Values are not written to report metadata. |
 | `maskSelectors` | Selectors masked in browser screenshots. |
 | `routes` | Route assertions executed in `smoke` and `full` modes. |
 | `visualSmoke` | Route screenshot baseline comparisons driven from successful browser screenshots. |
 
+Route setup fields:
+
+```ts
+setup: {
+  localStorage: {
+    'reflection:test-user': 'fixture-user'
+  },
+  sessionStorage: {
+    'reflection:test-session': 'fixture-session'
+  }
+}
+```
+
+Browser-level setup applies to every route. Route-level setup extends or overrides browser-level keys for that route. Reflection records only storage key names in metadata, never storage values. Use this for non-secret test-mode state, mock auth, or local fixture tokens. Do not commit real credentials or production session values in config.
+
 Supported browser expectations:
 
 ```ts
@@ -175,6 +201,12 @@ component: {
       id: 'primary-button',
       storyId: 'atoms-button--primary',
       viewport: 'component',
+      viewportSize: { width: 390, height: 220 },
+      framing: {
+        background: '#ffffff',
+        align: 'center',
+        padding: 0
+      },
       baselineRoot: 'tests/fixtures/baselines',
       baseline: 'components/button/primary.chromium-linux.light.png',
       threshold: { maxDiffPixelRatio: 0.005 },
@@ -197,6 +229,21 @@ component: {
 
 Component visual cases resolve Storybook `/index.json`, open the story iframe, capture an actual screenshot, and compare it against the configured baseline.
 
+`viewport` accepts the built-in presets (`desktop`, `tablet`, `mobile`, `component`) and any custom string label. When `viewportSize` is provided, Reflection captures the Storybook iframe at that exact `{ width, height }` instead of resolving the string preset. Use this for exported Figma baselines: the PNG dimensions must match `viewportSize` exactly or the check fails with `visual-dimension-mismatch`.
+
+`framing` lets a component visual case normalize the Storybook canvas before the screenshot:
+
+```ts
+framing: {
+  rootSelector: '#storybook-root',
+  background: '#ffffff',
+  align: 'center',
+  padding: 0
+}
+```
+
+Use it when the approved baseline is a fixed Figma frame: `background` should match the Figma frame fill, `align: 'center'` centers the story root content, and `padding` reserves explicit frame padding. `rootSelector` defaults to `#storybook-root`.
+
 Pseudo-state policy:
 
 - Prefer story-controlled variants for hover, focus, active, selected, open, and disabled states.

package/docs/getting-started.md

@@ -20,6 +20,14 @@ pnpm exec reflection doctor
 
 The package install exposes both `reflection` and `reflection-check` binaries. The docs use `reflection` as the primary command.
 
+You can preview the setup Reflection would suggest without writing files:
+
+```bash
+pnpm exec reflection init --dry-run --preset vite-react
+```
+
+`init --dry-run` prints proposed install commands, config, and script guidance. It is read-only; creating or updating files still happens manually.
+
 For local tarball testing before a registry publish, create and install a packed artifact instead.
 
 From the Reflection repository:
@@ -84,18 +92,24 @@ reflection run --config reflection.config.ts --mode smoke
 reflection review --latest
 ```
 
+Pass the config to `doctor` when you want a read-only preflight of the consuming repository setup:
+
+```bash
+reflection doctor --config reflection.config.ts
+```
+
 During Reflection development, use the built CLI:
 
 ```bash
 pnpm build
-node dist/cli.js doctor
+node dist/cli.js doctor --config examples/basic-react/reflection.config.ts
 node dist/cli.js run --config examples/basic-react/reflection.config.ts --mode smoke
 node dist/cli.js review --latest
 ```
 
 `reflection run` writes reports and artifacts under `.reflection/runs/<run-id>/` by default.
 
-`reflection doctor` is currently a lightweight setup check. The configured project contract is exercised by `reflection run --config reflection.config.ts ...`.
+`reflection doctor --config` validates that the config can be loaded, summarizes enabled contracts and server settings, checks local runtime readiness, and does not start servers or mutate baselines. Use `--check-server` when you explicitly want it to probe the configured server `readyUrl` without starting the server.
 
 Important files:
 
@@ -147,7 +161,7 @@ Use Reflection as the UI evidence gate before claiming frontend work is complete
 Run:
 
 ```bash
-reflection doctor
+reflection doctor --config reflection.config.ts
 reflection run --config reflection.config.ts --mode smoke
 reflection review --json
 ```

package/docs/plans/reflection-dogfood-feedback-implementation-guide.md

@@ -18,8 +18,8 @@ This guide must be updated during implementation:
 - Record timestamps on phase completions for velocity tracking.
 - Update the test coverage map as tests are written.
 
-**Last updated:** 2026-06-01
-**Current phase:** Patch 0.0.2 candidate
+**Last updated:** 2026-06-02
+**Current phase:** Complete
 
 ---
 
@@ -109,7 +109,7 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 **Goal:** Fix the Sourcer-discovered limitation where missing-baseline dry-run/update could not promote the current actual screenshot.
 **Depends on:** Current `0.0.1` package shape
-**Status:** Complete in working tree, pending full release validation and publish
+**Status:** Complete in working tree; full package validation passed. The combined release candidate is now `reflection-check@0.0.3`, and `npm publish --dry-run --access public` passes.
 
 #### Inputs
 
@@ -157,10 +157,10 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 #### Patch Exit Criteria
 
 - [x] Focused visual/update tests pass.
-- [ ] Full validation passes.
-- [ ] Version bumped for patch release.
+- [x] Full validation passes.
+- [x] Version bumped for patch release.
 - [ ] Sourcer verifies first login baseline dry-run against the patched package.
-- [ ] Guide updated with publish outcome.
+- [x] Guide updated with publish outcome.
 
 #### Failure Protocol
 
@@ -174,16 +174,16 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 ### Phase 1: Useful `doctor --config`
 
-**Goal:** Turn `doctor` from a placeholder into a real read-only preflight for consuming repos.
+**Goal:** Turn `doctor` from a shallow status command into a real read-only preflight for consuming repos.
 **Depends on:** Current `0.0.1` package shape
-**Status:** Not started
+**Status:** Complete
 
 #### Inputs
 
 - Existing `src/commands/doctor.ts`.
 - Existing config loader in `src/core/config.ts`.
 - Server readiness behavior in `src/core/server-manager.ts`.
-- Sourcer feedback: doctor currently only prints a placeholder.
+- Sourcer feedback: doctor previously only printed a one-line status message.
 
 #### Outputs
 
@@ -205,38 +205,45 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 #### Tasks
 
-- [ ] Add failing unit tests for valid config, missing config, invalid config, and config summary output.
+- [x] Add failing unit tests for valid config, missing config, invalid config, and config summary output.
   - **Tool:** edit
   - **Verify:** `pnpm exec vitest run tests/unit/doctor-command.test.ts`
 
-- [ ] Implement config-aware doctor output.
+- [x] Implement config-aware doctor output.
   - **Tool:** edit
   - **Verify:** focused doctor tests pass.
 
-- [ ] Add runtime checks that do not mutate or start target state unexpectedly.
+- [x] Add runtime checks that do not mutate or start target state unexpectedly.
   - **Tool:** edit
   - **Verify:** tests cover Playwright/package readiness and safe server summary.
 
-- [ ] Update docs to stop calling doctor a placeholder.
+- [x] Update docs to describe doctor as a config-aware preflight.
   - **Tool:** edit
-  - **Verify:** `rg "placeholder|lightweight" docs src tests`
+  - **Verify:** stale doctor wording search returns no matches in active docs, source, or tests.
+
+#### Implementation Notes
+
+- `reflection doctor --config` now validates config presence/import/schema and exits with `ExitCode.ToolOrConfigError` for invalid config.
+- `doctor` reports Node version, Playwright package readiness, Chromium executable presence when available, enabled contract counts, base URL, and server configuration.
+- Doctor remains read-only: it does not start configured servers, mutate baselines, or write reports.
+- Added `--check-server` for an explicit one-shot `readyUrl` probe without starting the server.
 
 #### Tests for This Phase
 
 | Test Type | What to Test | Exists? | Path / Command |
 |---|---|---|---|
-| Unit | Doctor config success/failure summaries | No → create | `tests/unit/doctor-command.test.ts` |
-| CLI | `reflection doctor --config` exit behavior | Partial | `tests/unit/cli.test.ts` |
+| Unit | Doctor config success/failure summaries | Yes | `tests/unit/doctor-command.test.ts` |
+| CLI | `reflection doctor --config` exit behavior | Yes | `tests/unit/cli.test.ts` |
 | Type safety | Doctor options/types | Auto | `pnpm typecheck` |
 | Package smoke | Installed CLI can run doctor | Yes | `pnpm smoke:package` |
 
 #### Phase Exit Criteria
 
-- [ ] `doctor --config` reports meaningful setup information.
-- [ ] Invalid config exits non-zero with actionable error.
-- [ ] Docs match behavior.
-- [ ] `pnpm test`, `pnpm typecheck`, `pnpm smoke:package` pass.
-- [ ] Guide updated with completion status.
+- [x] `doctor --config` reports meaningful setup information.
+- [x] Invalid config exits non-zero with actionable error.
+- [x] Docs match behavior.
+- [x] `pnpm test`, `pnpm typecheck`, `pnpm smoke:package` pass.
+- [x] Guide updated with completion status.
 
 #### Failure Protocol
 
@@ -252,7 +259,7 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 **Goal:** Support authenticated app smoke tests without Sourcer-specific hacks.
 **Depends on:** Phase 1
-**Status:** Not started
+**Status:** Complete
 
 #### Inputs
 
@@ -262,7 +269,7 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 #### Outputs
 
-- Config schema supports a safe browser setup mechanism, such as route-level or browser-level `storageState`, `localStorage`, or `beforeNavigate` script.
+- Config schema supports browser-level and route-level `setup.localStorage` / `setup.sessionStorage`.
 - Route runner applies setup before visiting a route.
 - Metadata records that setup was applied without logging sensitive values.
 - Docs include examples for non-secret test tokens and mock/test-mode auth.
@@ -280,38 +287,45 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 #### Tasks
 
-- [ ] Design the smallest setup API and document rejected alternatives.
+- [x] Design the smallest setup API and document rejected alternatives.
   - **Tool:** research/edit guide
   - **Verify:** decision recorded before implementation.
 
-- [ ] Add failing config tests for setup schema.
+- [x] Add failing config tests for setup schema.
   - **Tool:** edit
   - **Verify:** `pnpm exec vitest run tests/unit/config.test.ts`
 
-- [ ] Add failing integration test proving localStorage/session setup before route navigation.
+- [x] Add failing integration test proving localStorage/session setup before route navigation.
   - **Tool:** edit
   - **Verify:** `pnpm exec vitest run tests/integration/browser-contract.test.ts`
 
-- [ ] Implement setup support and metadata redaction.
+- [x] Implement setup support and metadata redaction.
   - **Tool:** edit
   - **Verify:** focused tests pass.
 
+#### Decision Notes
+
+- Chosen API: `setup.localStorage` and `setup.sessionStorage` as string key/value maps at browser and route scope.
+- Browser-level setup applies to every route; route-level setup extends or overrides browser-level keys.
+- Rejected for this phase: arbitrary `beforeNavigate` script hooks because they are too broad and harder to make safe; `storageState` files because the current Sourcer need is simple seeded browser storage and key-only metadata.
+- Report metadata records only storage key names, not values.
+
 #### Tests for This Phase
 
 | Test Type | What to Test | Exists? | Path / Command |
 |---|---|---|---|
-| Unit | Config schema accepts setup and rejects unsafe shapes | No → create | `tests/unit/config.test.ts` |
-| Integration | Route sees seeded storage before render | No → create | `tests/integration/browser-contract.test.ts` |
-| Redaction | Setup metadata does not leak token values | No → create if metadata stores keys | `tests/unit/redaction.test.ts` |
-| Docs | Example compiles conceptually | Manual | `docs/configuration.md` |
+| Unit | Config schema accepts setup and rejects unsafe shapes | Yes | `tests/unit/config.test.ts` |
+| Integration | Route sees seeded storage before render | Yes | `tests/integration/browser-contract.test.ts` |
+| Redaction | Setup metadata does not leak token values | Yes, integration metadata assertion | `tests/integration/browser-contract.test.ts` |
+| Docs | Example compiles conceptually | Manual | `docs/configuration.md`, `docs/browser-contract.md` |
 
 #### Phase Exit Criteria
 
-- [ ] Auth setup can be expressed without real credentials.
-- [ ] Route runner applies setup before assertions.
-- [ ] Sensitive values are not printed in report metadata.
-- [ ] Sourcer can add one authenticated route without app-specific Reflection changes.
-- [ ] Full validation passes.
+- [x] Auth setup can be expressed without real credentials.
+- [x] Route runner applies setup before assertions.
+- [x] Sensitive values are not printed in report metadata.
+- [x] Sourcer can add one authenticated route without app-specific Reflection changes.
+- [x] Full validation passes.
 
 #### Failure Protocol
 
@@ -327,7 +341,7 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 **Goal:** Replace generic next steps with report suggestions derived from actual run results.
 **Depends on:** Phase 1
-**Status:** Not started
+**Status:** Complete
 
 #### Inputs
 
@@ -356,15 +370,15 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 #### Tasks
 
-- [ ] Add tests for suggested steps by result type.
+- [x] Add tests for suggested steps by result type.
   - **Tool:** edit
   - **Verify:** `pnpm exec vitest run tests/unit/review-command.test.ts tests/unit/report-schema.test.ts`
 
-- [ ] Implement derived suggestions.
+- [x] Implement derived suggestions.
   - **Tool:** edit
   - **Verify:** focused tests pass.
 
-- [ ] Update docs with examples of pass/fail/review suggestions.
+- [x] Update docs with examples of pass/fail/review suggestions.
   - **Tool:** edit
   - **Verify:** docs mention dry-run update for visual review.
 
@@ -372,15 +386,15 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 | Test Type | What to Test | Exists? | Path / Command |
 |---|---|---|---|
-| Unit | Derived suggestions for fail/review/pass | Partial → extend | `tests/unit/review-command.test.ts` |
+| Unit | Derived suggestions for fail/review/pass | Yes | `tests/unit/report-schema.test.ts` |
 | Schema | Suggested step shape remains stable | Yes | `tests/unit/report-schema.test.ts` |
-| E2E | CI report has useful next steps | Partial | `tests/e2e/ci-mode.test.ts` |
+| E2E | CI report has useful next steps | Yes | `tests/e2e/ci-mode.test.ts` |
 
 #### Phase Exit Criteria
 
-- [ ] No report emits the old generic implementation suggestion for consuming-project passes.
-- [ ] Review JSON remains parseable.
-- [ ] Full validation passes.
+- [x] No report emits the old generic implementation suggestion for consuming-project passes.
+- [x] Review JSON remains parseable.
+- [x] Full validation passes.
 
 #### Failure Protocol
 
@@ -395,7 +409,7 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 **Goal:** Make first-time setup easier while preserving read-only safety by default.
 **Depends on:** Phase 1
-**Status:** Not started
+**Status:** Complete
 
 #### Inputs
 
@@ -406,7 +420,7 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 #### Outputs
 
 - `reflection init --dry-run` detects package manager and prints proposed files/scripts.
-- Optional explicit `reflection init --write` can create minimal config after a later human-approved phase.
+- `reflection init --dry-run` is read-only and refuses to write. Any future write mode must be explicit and separately approved.
 - Preset support starts explicit, for example `--preset vite-react`.
 
 #### Relevant Paths
@@ -421,15 +435,15 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 #### Tasks
 
-- [ ] Add failing CLI tests for `init --dry-run`.
+- [x] Add failing CLI tests for `init --dry-run`.
   - **Tool:** edit
   - **Verify:** `pnpm exec vitest run tests/unit/init-command.test.ts tests/unit/cli.test.ts`
 
-- [ ] Implement read-only dry-run with detected package manager and suggested commands.
+- [x] Implement read-only dry-run with detected package manager and suggested commands.
   - **Tool:** edit
   - **Verify:** focused tests pass.
 
-- [ ] Document that `init --write` is not required for `0.0.1` consumers and must be explicit if added.
+- [x] Document that `init --write` is not required for consumers and must be explicit if added.
   - **Tool:** edit
   - **Verify:** docs mention dry-run safety.
 
@@ -437,16 +451,16 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 | Test Type | What to Test | Exists? | Path / Command |
 |---|---|---|---|
-| Unit | Dry-run output for pnpm repo | No → create | `tests/unit/init-command.test.ts` |
-| CLI | Command registration and invalid options | No → extend | `tests/unit/cli.test.ts` |
+| Unit | Dry-run output for pnpm repo | Yes | `tests/unit/init-command.test.ts` |
+| CLI | Command registration and invalid options | Yes | `tests/unit/cli.test.ts` |
 | Package smoke | New CLI still works installed | Yes | `pnpm smoke:package` |
 
 #### Phase Exit Criteria
 
-- [ ] `reflection init --dry-run` is read-only.
-- [ ] Output matches current package name `reflection-check`.
-- [ ] No repo files are mutated without `--write`.
-- [ ] Full validation passes.
+- [x] `reflection init --dry-run` is read-only.
+- [x] Output matches current package name `reflection-check`.
+- [x] No repo files are mutated without `--write`.
+- [x] Full validation passes.
 
 #### Failure Protocol
 
@@ -461,7 +475,7 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 **Goal:** Make consuming-repo CI and visual baseline workflows obvious and hard to misuse.
 **Depends on:** Phases 1-3
-**Status:** Not started
+**Status:** Complete
 
 #### Inputs
 
@@ -488,15 +502,15 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 #### Tasks
 
-- [ ] Update CI docs around `pnpm add -D reflection-check` and `reflection run --ci`.
+- [x] Update CI docs around `pnpm add -D reflection-check` and `reflection run --ci`.
   - **Tool:** edit
   - **Verify:** docs contain public package install path.
 
-- [ ] Add or update CI-mode e2e tests if command shape changes.
+- [x] Add or update CI-mode e2e tests if command shape changes.
   - **Tool:** edit
   - **Verify:** `pnpm exec vitest run tests/e2e/ci-mode.test.ts`.
 
-- [ ] Improve baseline update dry-run messaging if needed.
+- [x] Improve baseline update dry-run messaging if needed.
   - **Tool:** edit
   - **Verify:** `pnpm exec vitest run tests/integration/update-command.test.ts`.
 
@@ -504,15 +518,15 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 | Test Type | What to Test | Exists? | Path / Command |
 |---|---|---|---|
-| E2E | CI report root and review | Yes | `tests/e2e/ci-mode.test.ts` |
-| Integration | Baseline update dry-run safety | Yes | `tests/integration/update-command.test.ts` |
+| E2E | CI report root, docs, and review | Yes | `tests/e2e/ci-mode.test.ts` |
+| Integration | Baseline update dry-run safety and messaging | Yes | `tests/integration/update-command.test.ts` |
 | Package | Public install smoke remains valid | Yes | `pnpm smoke:package` |
 
 #### Phase Exit Criteria
 
-- [ ] Consuming repo CI docs are copy-pasteable.
-- [ ] Baseline update process is clear and safe.
-- [ ] Full validation passes.
+- [x] Consuming repo CI docs are copy-pasteable.
+- [x] Baseline update process is clear and safe.
+- [x] Full validation passes.
 
 #### Failure Protocol
 
@@ -537,20 +551,20 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 **Unit done when:**
 
-- [ ] Focused tests pass.
-- [ ] `pnpm test`, `pnpm typecheck`, and `pnpm smoke:package` pass.
-- [ ] Public package docs remain accurate.
-- [ ] Guide updated.
+- [x] Focused tests pass.
+- [x] `pnpm test`, `pnpm typecheck`, and `pnpm smoke:package` pass.
+- [x] Public package docs remain accurate.
+- [x] Guide updated.
 
 ### Units
 
 | Unit | Status | Tests | Validation | Notes |
 |---|---|---|---|---|
-| Useful doctor | Not started | needed | — | Highest value from Sourcer feedback |
-| Browser setup hooks | Not started | needed | — | Enables authenticated Sourcer coverage |
-| Actionable next steps | Not started | needed | — | Replaces generic report suggestion |
-| Init dry-run | Not started | needed | — | Improves new project setup |
-| CI/baseline docs polish | Not started | partial | — | Needed before broader use |
+| Useful doctor | Complete | focused and full pass | full pass; publish dry-run passed for 0.0.3 | Highest value from Sourcer feedback |
+| Browser setup hooks | Complete | focused and full pass | full pass; publish dry-run passed for 0.0.3 | Enables authenticated Sourcer coverage |
+| Actionable next steps | Complete | focused and full pass | full pass; publish dry-run passed for 0.0.3 | Replaces generic report suggestion |
+| Init dry-run | Complete | focused and full pass | full pass; package smoke verifies installed init | Improves new project setup |
+| CI/baseline docs polish | Complete | focused and full pass | full pass; publish dry-run passed for 0.0.3 | Needed before broader use |
 
 ---
 
@@ -567,11 +581,11 @@ Convert feedback into small, test-first package improvements. Prioritize improve
 
 | Phase | What's Tested | Test Type | Exists? | Path |
 |---|---|---|---|---|
-| Phase 1 | Doctor config preflight | Unit/CLI | No | `tests/unit/doctor-command.test.ts`, `tests/unit/cli.test.ts` |
-| Phase 2 | Browser setup hooks | Unit/integration | No | `tests/unit/config.test.ts`, `tests/integration/browser-contract.test.ts` |
-| Phase 3 | Derived next steps | Unit/e2e | Partial | `tests/unit/review-command.test.ts`, `tests/e2e/ci-mode.test.ts` |
-| Phase 4 | Init dry-run | Unit/CLI | No | `tests/unit/init-command.test.ts`, `tests/unit/cli.test.ts` |
-| Phase 5 | CI/baseline docs and safety | E2E/integration | Partial | `tests/e2e/ci-mode.test.ts`, `tests/integration/update-command.test.ts` |
+| Phase 1 | Doctor config preflight | Unit/CLI | Yes | `tests/unit/doctor-command.test.ts`, `tests/unit/cli.test.ts` |
+| Phase 2 | Browser setup hooks | Unit/integration | Yes | `tests/unit/config.test.ts`, `tests/integration/browser-contract.test.ts` |
+| Phase 3 | Derived next steps | Unit/e2e | Yes | `tests/unit/report-schema.test.ts`, `tests/e2e/ci-mode.test.ts` |
+| Phase 4 | Init dry-run | Unit/CLI/package smoke | Yes | `tests/unit/init-command.test.ts`, `tests/unit/cli.test.ts`, `scripts/smoke-package-install.mjs` |
+| Phase 5 | CI/baseline docs and safety | E2E/integration | Yes | `tests/e2e/ci-mode.test.ts`, `tests/integration/update-command.test.ts` |
 
 ### Full Validation Run
 
@@ -606,18 +620,18 @@ npm publish --dry-run --access public
 
 | Phase | Title | Status | Tests | Validation | Completed |
 |---|---|---|---|---|---|
-| Patch | Missing Baseline Promotion | In progress | focused pass | pending full | — |
-| 1 | Useful `doctor --config` | Not started | — | — | — |
-| 2 | Browser Setup Hooks for Authenticated Apps | Not started | — | — | — |
-| 3 | Actionable Report Suggestions | Not started | — | — | — |
-| 4 | Safe `reflection init --dry-run` | Not started | — | — | — |
-| 5 | CI and Baseline Workflow Polish | Not started | — | — | — |
+| Patch | Missing Baseline Promotion | Complete | full pass | included in 0.0.3 candidate; publish dry-run passed | 2026-06-02 |
+| 1 | Useful `doctor --config` | Complete | full pass | included in 0.0.3 candidate; publish dry-run passed | 2026-06-02 |
+| 2 | Browser Setup Hooks for Authenticated Apps | Complete | full pass | included in 0.0.3 candidate; publish dry-run passed | 2026-06-02 |
+| 3 | Actionable Report Suggestions | Complete | full pass | included in 0.0.3 candidate; publish dry-run passed | 2026-06-02 |
+| 4 | Safe `reflection init --dry-run` | Complete | full pass | package smoke verifies installed init; publish dry-run passed | 2026-06-02 |
+| 5 | CI and Baseline Workflow Polish | Complete | full pass | included in 0.0.3 candidate; publish dry-run passed | 2026-06-02 |
 
 ---
 
 ## 7. Post-Completion Checklist
 
-- [ ] All phases marked complete or skipped with reason.
+- [x] All phases marked complete or skipped with reason.
 - [ ] Full validation suite passes.
 - [ ] `pnpm smoke:package` proves public install surface.
 - [ ] `npm publish --dry-run --access public` has no warnings.

package/docs/target-ir-and-adapters.md

@@ -59,7 +59,7 @@ console.log(ir.targets.map((target) => `${target.family}:${target.id}`));
 // ]
 ```
 
-The compiler preserves visual metadata that matters to later review, including zero-valued thresholds. Do not use truthiness checks when copying optional numeric metadata; use explicit `!== undefined` checks so values like `0` survive.
+The compiler preserves visual metadata that matters to later review, including zero-valued thresholds, explicit component `viewportSize` values, and component `framing`. Do not use truthiness checks when copying optional numeric metadata; use explicit `!== undefined` checks so values like `0` survive.
 
 ## Adapter contract
 
@@ -72,7 +72,7 @@ A good adapter is:
 - **optional** — normal Reflection config works without it;
 - **validated** — malformed adapter input fails before runner execution;
 - **neutral** — no external product names leak into core commands or reports unless the user explicitly names their own target ids;
-- **lossless enough for review** — route paths, viewports, expectations, baselines, thresholds, and blocking semantics are preserved in IR.
+- **lossless enough for review** — route paths, viewports, component viewport sizes, component framing, expectations, baselines, thresholds, and blocking semantics are preserved in IR.
 
 ## Route manifest adapter proof