pieceboard 0.0.0-stage → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+## 0.1.0-alpha.3 — 2026-11-07
+
+- Connect the lower-left and upper-right blue pieces in the logo and small vector mark for clearer recognition at header size.
+- Point npm README images and source links to this immutable release tag.
+
+## 0.1.0-alpha.2 — 2026-11-07
+
+- Unpublished staged candidate superseded by alpha.3 before npm approval.
+
+## 0.1.0-alpha.1 — 2026-11-07
+
+- Rename the public package and primary CLI to Pieceboard, retain the `ui-sheet` command and serialized format for existing projects, and ship the owner-selected connected-piece logo.
+- Frame visual review as a clear this-or-that choice between observed versions; keep source revision and reported served revision separate in supplied capture context.
+- Validate optional role, school, viewport, timestamp, served revision, and image hash for manually supplied screenshots; show the context beside the image without treating it as deployment proof.
+- Expand installation, safe sharing, and alpha publication instructions; verify the packed package from a fresh consumer.
+- Add explicit layout checks for text clearance, signed element gaps, computed spacing, approved logo source paths, and distortion, with separate screen/print-preview context.
+- Show measured layout findings and real previews in the report; add an image-free CI check and a reproducible synthetic demo.
+- Treat missing, unsupported, hidden, or unstable layout evidence as incomplete rather than clean.
+- Audit selected pages at multiple browser widths in one run, with width-specific overflow, clipped-text, and overlap evidence, privacy-masked screenshots, and reviewable CSS suggestions.
+
+## 0.1.0-alpha.0 — 2026-11-04
+
+- Record scoped CSS custom-property declarations and approve/check source token values without a browser; preserve theme, media, and layer contexts and distinguish missing, ambiguous, and unscanned evidence.
+- Improve token value/label contrast and check token cards and scoped details with automated accessibility rules at desktop and narrow widths.
+- Include the owner-approved security policy in the repository and package.
+
+- Add opacity and safe CSS filter comparison, repeated-deviation findings, strict-majority ambiguity, and explicit migration to button baseline v4/element baseline v2.
+- List every observed source occurrence for a selected finding, with a bounded CLI query and expandable report lists.
+- Add configured-family appearance/location queries and visual approval import/export.
+- Track per-page scan phases without retaining URLs or secrets in completion markers; reject completion with unvisited planned pages.
+- Preserve the first separately authored evaluation result, including its misses, and add a reproducible multi-control demo and privacy-canary checks.
+
+- Compare explicitly configured inputs, dropdowns, selectors, tabs, headers, sidebars, navigation, headings and text with state separation, source evidence and real previews; keep these new families experimental.
+- Approve configured-family references separately from button baselines, with page/state/context scope and optional cross-page authority.
+- Bound capture and browser cleanup, publish evidence transactionally, and support explicit verified focus/hover setup per page.
+- Ship JSON schemas and compatibility documentation; return structured errors from `check --json`.
+- Record separate coding-agent and accessibility exercises; fix count contrast and light/dark/mobile focus indicators found during review.
+
+- Scan supported source files into an offline UI inventory with searchable source references and category filters.
+- Capture real rendered controls and identify possible differences between comparable native buttons.
+- Show high-density examples, measured differences, coverage, and source-confidence information.
+- Record findings through the report or CLI, preserve existing decisions during export, and approve observed button appearances for a specific page, viewport, and theme.
+- Define comparable button groups with project-specific CSS selectors and omit selected source paths or mask screenshot regions.
+- Configure multiple routes and capture a selected viewport and browser color preference, with optional user-provided demo authentication state.
+- Provide image-free CLI summaries, comparison with compatible prior reports, and installable Codex and Claude Code skills.
+- List observed button-family occurrences across selected routes, with source-confidence clues.
+- Optionally compare explicitly grouped button appearances across selected pages, counting a style once per page.
+- Approve a cross-page button reference so a widespread drift can be detected even when the approved style is no longer visible.
+- Distinguish source-linked inventory preview counts from comparison-preview counts in scan output.
+- Allow explicitly configured, clearly labeled source links when automatic matching is ambiguous.
+- Let projects classify exact CSS classes as UI types to include custom controls in the visual inventory without broadening the native-button comparison.
+- Keep reviewed findings stable across line moves for unique static element IDs; regenerate older comparison reports and review decisions whose IDs become stale.
+- Treat source-scan warnings or missing warning metadata as incomplete coverage in checks.
+- Exclude possibly blocked buttons and report offscreen or otherwise unverified visibility as incomplete coverage.
+- Improve report keyboard navigation, focus visibility, and reduced-motion behavior.
+- Increase the size and contrast of key report labels and source paths.
+- Add a repeatable, explicitly limited public-source association spot check.
+- Queue and export approved appearances from the visual report, preserving imported baseline rules.
+- Verify that a source-only CLI scan works with network calls blocked and AI credentials absent.
+- Warn and leave package imports unresolved when selected projects contain duplicate workspace package names.
+- Compare each border side's width, style, and color. Regenerate older comparisons and reapprove appearances into a new v2 baseline file; missing measurements cannot be safely inferred.
+- Track CLI scan completion and prevent checks from treating a failed, interrupted, concurrent, or mismatched run as a fresh report.
+- Improve contrast and text sizes across report navigation, summaries, and details; add automated accessibility checks for selected desktop, mobile, review, and dialog states.
+- Show the source scan time in the report footer.
+- Add an opt-in Vite development plugin that links supported JSX/TSX controls using source locations and file fingerprints, with incomplete-coverage reporting for missing or invalid markers.
+- Add a separate, labeled browser evaluation with recorded false positives and misses.
+- Compare supported gradients, font style, text transform, and decoration; exclude unsupported image backgrounds from comparison. Reapprove older baselines with the new measurements.
+- Capture at configurable 1×–4× density and inspect original pixels with a resolution-aware zoom control; keep comparisons scoped to the capture density.
+- Record browser version and local source-revision context when available.
+- Avoid attributing entirely untracked or ignored source files to an enclosing Git revision, and report tracked-source coverage for mixed scans.
+
+This is an unreleased prototype. See [the project plan](PROJECT_PLAN.md) for outstanding work and [the README](README.md) for supported behavior.

package/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+Pieceboard is an early prototype. Small, well-scoped changes with evidence are especially helpful. Please read [the project plan](PROJECT_PLAN.md) for the current goals and limitations before starting substantial work.
+
+## Development setup
+
+Use Node.js 22 or newer and a recent npm:
+
+```sh
+npm ci
+npx playwright install chromium
+npm test
+npm run test:package
+npm run evaluate:buttons
+```
+
+The test suite uses a local synthetic web server and closes it when the test finishes. Set `UI_SHEET_TEST_BROWSER` to a compatible Chromium-based browser executable if you prefer an already installed browser. Browser tests are skipped when neither that variable nor Playwright Chromium is available; install a browser before considering the full suite verified.
+
+Routine GitHub Actions pushes and pull requests run the full browser suite and package check once on Ubuntu/Node 24, plus a short Windows/Node 24 scan-status and Vite capture smoke. To qualify a release across Node 22, 24 and 26 on both systems, start the CI workflow manually with **full_matrix** enabled. The full Windows suite runs serially to avoid unrelated browser processes competing on a runner. CI only tests Pieceboard; it does not deploy a website.
+
+Run `npm run demo` for real captures of synthetic fields, tabs, dropdowns, selectors and actions, or `npm run demo:consistency` for the smaller button report. `npm run demo:inventory` is the source-only example with supplied SVG illustrations. Generated reports are ignored by Git. Use `npm run screenshot:demo` after the button demo, or `node scripts/export-demo-image.js --elements` after the default demo, to refresh the corresponding synthetic README images.
+
+## Making a change
+
+- Explain the user-facing problem, the expected behavior, and any important tradeoffs.
+- Add a focused fixture or test when behavior changes, including intentional variants or incomplete evidence where relevant.
+- Preserve the distinction between measured values, inferred grouping, possible source matches, and approved conventions.
+- Keep browser interaction opt-in. Do not submit forms, collect private browser state, or upload project data as part of a scan.
+- Update the README and project plan when supported behavior or limitations change.
+- Run the relevant tests and report any skipped browser checks or remaining limitations in the pull request.
+
+Use synthetic data in fixtures, screenshots, issues, and pull requests. Do not include credentials, browser state files, or real user records.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UI Sheet contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROJECT_PLAN.md

@@ -0,0 +1,190 @@
+# Pieceboard: project plan
+
+## Product goal
+
+Help people and coding agents keep an application's UI consistent. Pieceboard should discover relevant interface elements, show clear images of comparable examples, identify possible inconsistencies, and provide evidence about where to investigate the code.
+
+For example, if comparable Save buttons usually have an 8 px border radius and one has a 3 px radius, the report should show both appearances, explain the difference and their observed frequency, and link to the relevant source when that link can be established. A rare appearance is a suggestion for review, not automatically an error.
+
+The package should be useful without an AI provider. Optional Codex and Claude Code skills should enable agents to consult existing UI patterns before making changes and review findings afterward.
+
+## Principles
+
+- Focus on interface controls and design foundations, not ordinary page content or unrelated data.
+- Capture genuine, readable examples; never invent what a component looks like.
+- Compare like with like: component family, purpose, state, theme, and viewport matter.
+- Count occurrences before selecting or deduplicating preview images.
+- Separate measured facts, inferred relationships, manually supplied information, and unknowns.
+- Prefer approved project conventions over an assumption that the most common appearance is correct.
+- Operate locally by default and make rendering, authentication, and page interactions explicit.
+- Keep findings useful without requiring an AI service or an API key.
+
+## Current status
+
+The alpha scans JSX/TSX, static HTML and PHP template markup, CSS custom properties, fonts and image assets. It generates an offline visual inventory with real high-density captures, compares native buttons and explicitly configured UI groups, and supports approved references and source-anchored review decisions. It can inspect selected pages at multiple browser widths for possible overflow, clipping, and text overlap. It ships JSON schemas, coding-agent instructions and report-only CI checks. A second coding agent exercised the documented workflow, and a separately authored accessibility review found and verified fixes for three issues. Configured non-button families remain experimental; representative accuracy, real screen-reader/native-zoom review, and Claude execution remain open. The checklist records those limits rather than treating an alpha as the entire roadmap.
+
+## Milestone 1: protect the prototype and establish the baseline
+
+- [x] Review and preserve the existing prototype and its tests; keep local reports and screenshots out of the public repository.
+- [x] Document the supported environments, the actual current commands, and the distinction between source scanning and opt-in page rendering.
+- [x] Establish the automated test and package-verification baseline.
+- [x] Define versioned current-producer schemas, compact public interchange contracts, and a clear regeneration path for older reports.
+
+**Acceptance:** the existing prototype runs from a clean checkout, reports are not accidentally committed, and changes begin from a tested baseline.
+
+## Milestone 2: make the first button comparison work
+
+- [x] Start with native buttons on one accessible page in a desktop viewport, excluding disabled controls and common toggle/disclosure states.
+- [ ] Track focus, hover, occlusion and other inherited states before claiming complete default-state coverage.
+- [x] Document source definitions/usages, rendered observations, groups/variants/states, appearances and findings as separate evidence in the schemas.
+- [x] Record eligible rendered occurrences independently of preview capture limits and count excluded controls.
+- [ ] Account for inaccessible, covered and changing controls in coverage and sample confidence.
+- [x] Count representative button previews that were captured, unavailable, or omitted by the per-page limit, and mark incomplete preview evidence as partial coverage.
+- [x] Exclude buttons with failed in-viewport hit tests and report offscreen or unverified visibility as incomplete coverage.
+- [x] Measure normalized rendered properties such as background and text colors, typography, border, radius, padding and shadow.
+- [x] Measure border width, style and color on each side, and require old approvals to be recaptured when those measurements are absent.
+- [x] Measure supported gradients and additional text styling; exclude unsupported image backgrounds and report incomplete coverage.
+- [x] Measure opacity and supported resource-free filters, require a genuine majority, and report repeated minority deviations.
+- [x] Group comparable controls conservatively and identify rare or unexpected appearances with an explanation and sample counts.
+- [x] Show a side-by-side comparison with the precise values that differ, page context, and source evidence when available.
+- [x] Retain existing inventory functionality and label uncertain or undersampled comparisons clearly.
+
+**Acceptance:** a seeded inconsistent button is reported, an intentionally different destructive button is not presented as a definite error, and a reviewer can see why the finding was made.
+
+## Milestone 3: readable visuals and trustworthy evidence
+
+- [x] Capture actual component images at high pixel density, after fonts and layout have settled, with suitable size limits and honest fallback behavior.
+- [x] Provide readable comparison previews, original-size viewing and zoom without stretching low-resolution images.
+- [ ] Test image clarity on standard- and high-density displays and recapture low-resolution examples where possible.
+- [x] Record viewport, detected theme and route for comparisons.
+- [x] Record Chromium version and local Git revision/working-tree status when available; label this as local context rather than proof of deployment.
+- [x] Report how many scanned source files are tracked in the enclosing checkout and omit Git context when none are tracked.
+- [x] Allow a user-supplied selector and recorded source location to supplement ambiguous automatic matches; label this evidence as manual.
+- [x] Allow explicitly classified static CSS classes to add custom elements to the visual inventory and type filters, without treating them as native buttons.
+- [x] Label source evidence as instrumented, likely, manually linked or unresolved; do not present an inferred match as verified.
+- [x] Add opt-in Vite development instrumentation for selected JSX/TSX controls, with file-fingerprint matching and explicit coverage limits.
+- [x] Exercise instrumented captures on a standalone component from a local project using sample data, without modifying its repository.
+
+**Acceptance:** comparison labels and details are readable, genuine screenshots are used, and no finding fabricates a source location.
+
+## Milestone 4: review and approved patterns
+
+- [x] Let reviewers record intentional, needs-fix, deferred and false-positive decisions through the CLI.
+- [x] Store source-anchored decisions that become stale when their appearance, group, page or source identity changes.
+- [x] Preserve a finding identity across a line move when a static element ID is unique in selected source and the rendered page.
+- [x] Add in-report review controls with import and export of source-anchored decisions.
+- [ ] Support reliable decisions for more kinds of source evidence.
+- [x] Allow an explicitly approved button appearance to take precedence over frequency-based suggestions for a page, viewport, theme and stable group.
+- [x] Support approving observed button appearances without an existing finding.
+- [x] Allow captured appearances to be approved and exported from the visual report, with an import path for existing baselines.
+- [x] Add separate approved references for explicitly configured UI families, scoped to observed state and rendering context.
+- [x] Approve exact source CSS token declarations by file, selector and complete at-rule context; check changed, missing, ambiguous and unscanned declarations without a browser.
+- [ ] Evaluate token contracts and each added component family beyond synthetic fixtures; runtime token cascade/value enforcement remains outside the source contract.
+- [ ] Separate light and dark themes, responsive breakpoints, and normal, disabled, selected, focused and hover states.
+- [x] Allow project-specific button group and variant definitions using non-overlapping CSS selectors.
+
+**Acceptance:** intentional variations can be accepted without suppressing unrelated issues, and approved patterns are honored on subsequent runs.
+
+## Milestone 5: realistic capture coverage
+
+- [x] Configure or explicitly select multiple routes and source scopes; analyze each route separately.
+- [x] Scan selected UI paths from multiple local projects under a common parent, and warn when workspace package names are ambiguous.
+- [x] List observed occurrences of a button family across the selected routes, with available source clues.
+- [x] Offer compact configured-family queries and finding-specific lookup for every matching observed occurrence, including unresolved sources and truncation.
+- [x] Offer opt-in cross-page comparison for explicitly named button groups and variants, with page-frequency evidence and representative captures.
+- [x] Support an explicitly approved cross-page button reference that takes precedence over frequency for the same group, viewport and theme.
+- [x] Configure one viewport and browser light/dark color preference per captured scan; keep their baselines and decisions separate.
+- [ ] Broaden cross-page comparison to additional well-evaluated component families and application-specific theme switches.
+- [x] Track requested pages, completed observation/capture phases and failed page indexes; report observed controls, omissions and incomplete evidence separately.
+- [x] Keep focus/hover actions opt-in per exact page, verify their setup, record their context, and provide no automatic clicks or form submission.
+- [x] Bound capture and browser cleanup time and publish evidence only after a successful capture.
+- [x] Support a dedicated demo/test account through a user-led authentication flow or explicitly provided local browser state.
+- [x] Keep authentication material out of generated reports and provide an ignored local state directory for this repository.
+- [x] Allow configurable CSS-selector masks in automatically captured screenshots.
+- [x] Allow configured and CLI source-path exclusions, including paths nested inside selected source directories.
+- [x] Document data boundaries and exercise synthetic privacy canaries for browser state, resource URLs, field values and matching screenshot masks.
+- [x] Exercise isolated selected UI components from two local projects with synthetic content; do not claim full application or deployment coverage.
+
+**Acceptance:** several chosen demo pages can be examined, coverage limitations are visible, and private authentication data is not embedded in reports.
+
+## Milestone 6: coding-agent integration
+
+- [x] Document the prototype's versioned, provider-neutral JSON outputs and regeneration behavior.
+- [x] Ship schemas and compatibility rules for current alpha reports, compact queries/checks, baselines, decisions, source evidence and coverage.
+- [ ] Stabilize the complete interface for a production release after external integration feedback.
+- [x] Provide installable Codex and Claude Code skill instructions for consulting existing patterns and reviewing a fresh report.
+- [x] Explain uncertain findings, deliberate variants, authorization boundaries and coverage to coding agents.
+- [x] Exercise the agent-facing CLI workflow on a small project with both a consistent change and a seeded regression.
+- [x] Have a fresh second Codex agent exercise the documented workflow without implementation knowledge; fix its structured-error finding.
+- [x] Have another fresh Codex agent exercise source token approvals against stale and incomplete reports without implementation knowledge, preserving current source and approval files.
+- [ ] Evaluate actual Codex and Claude behavior independently, including cases where the tool is incomplete or stale.
+- [x] Keep source-only scanning functional without AI access, model training, or network access.
+
+**Acceptance:** a coding agent can consult an existing button pattern, make a UI change, run a check, and report a known inconsistency with useful evidence.
+
+## Milestone 7: evaluate accuracy and broaden support
+
+- [x] Add a labeled synthetic button development set that reports false positives and false negatives without claiming representative accuracy.
+- [x] Prepare a separate set of labeled synthetic browser scenarios before scoring them, with authorship and sampling limitations documented.
+- [x] Record an initial precision, recall, preview-count, and source-association result on those frozen scenarios without claiming representative accuracy.
+- [x] Record an exploratory public-site check with intentional variations and explicitly unresolved source links.
+- [x] Exercise a second public application against selected upstream source files and document an unsupported custom-control case.
+- [x] Make the six selected public source-link spot checks repeatable, with pinned source and an HTML hash comparison.
+- [x] Build synthetic fixtures with known differences and intentional variants across configured families, observed states, browser themes and selected viewports.
+- [x] Freeze separately authored labels before scoring and preserve the first runtime's precision, recall, errors, source associations and preview counts.
+- [ ] Evaluate the revised detector against fresh labels after tuning; the preserved first score remains below the provisional targets.
+- [ ] Measure coverage, screenshot readability, source-link accuracy and reviewer false-positive feedback.
+- [ ] Treat 90% precision and 80% recall on the early evaluation set as provisional goals, not claims; document sample size and limitations.
+- [x] Add opt-in experimental comparisons for configured inputs, dropdowns, selectors, tabs, headers, sidebars, navigation, headings and text, with state separation and genuine previews.
+- [ ] Promote additional families beyond experimental support only after their own labeled evaluation meets acceptance criteria.
+- [x] Retain tested static HTML/PHP inventory and capture support, with the separate PHP component sample's manual/likely evidence clearly labeled.
+
+**Acceptance:** tests demonstrate useful detection without overwhelming reviewers, and supported component families have documented limits.
+
+## Milestone 8: package, CI and release
+
+- [x] Provide non-overwriting init, documented source/route/group configuration, reproducible demos and packed-install verification.
+- [x] Add a report-only CLI check with image-free JSON, optional failure for all actionable findings, and explicit incomplete-coverage handling.
+- [x] Compare compatible reports and optionally fail for new, source-anchored actionable findings; treat incomplete evidence as inconclusive.
+- [x] Mark scans with source warnings or missing warning metadata as incomplete in CI checks.
+- [x] Record failed or interrupted CLI scans and make checks require a matching completed record for full coverage.
+- [ ] Detect introduced findings reliably when source locations move or cannot be linked confidently.
+- [x] Reject failed/interrupted/mismatched scans and expose incomplete evidence; strict coverage checks exit unsuccessfully.
+- [x] Test a packed installation and move the Node support policy to maintained releases.
+- [x] Prepare alpha package metadata and verify that the current npm name was not published when checked; availability is not reserved.
+- [x] Confirm the initial CI matrix across Windows and Linux on Node 22, 24 and 26.
+- [x] Prepare a README with a real synthetic-demo capture, examples, contribution guide, changelog and issue templates.
+- [x] Exercise keyboard navigation, focus visibility, dialogs and reduced motion in a browser smoke test.
+- [x] Check the contrast of key report labels and source paths in a browser smoke test.
+- [x] Run automated accessibility rules on selected desktop, mobile, review, and dialog states, and address the issues found in the synthetic report.
+- [x] Complete a separately authored agent accessibility review of the synthetic report and verify fixes for its three findings.
+- [ ] Complete external human accessibility review, including screen-reader output and native browser zoom.
+- [x] Establish an owner-approved security reporting policy, verify its application to the source tree, and include it in the package. The policy provides a fallback when private reporting is unavailable.
+- [ ] Recheck package name availability, review release contents, and publish an alpha before considering a stable release.
+- [x] Compare and document how UI Sheet complements Storybook and visual regression testing.
+
+**Acceptance:** an independent developer can install the package, configure a small project, review a meaningful finding, and understand its limitations without help.
+
+## Layout, typography, and brand anomaly extension
+
+- [x] Add opt-in rules for actual text/container clearance, signed gaps between elements, computed margin/padding/word-spacing values, and approved logo image sources/aspect ratio.
+- [x] Separate these explicit layout rules from existing frequency-based appearance identities and approvals.
+- [x] Keep missing, hidden, unsupported, bounded, and unstable evidence incomplete; show measured requirements, manual source links, and real previews in the report.
+- [x] Support separate screen/print-preview layout contexts and a compact CI check with strict incomplete-evidence handling.
+- [x] Add synthetic wordmark-overlap, crowded-callout, spacing, and approved-image fixtures; keep uploaded PDFs and private brand assets out of tracked examples.
+- [ ] Evaluate against separately authored real-world layout cases, responsive states, and deliberate overlaps; this first version is experimental.
+- [ ] Add direct PDF glyph/container geometry and embedded-logo checks with honest source-provenance limits.
+- [ ] Add exact approved asset-byte verification and additional rendered-content checks beyond descendant text rectangles.
+
+## Initial delivery order
+
+1. Preserve the prototype and create focused test fixtures.
+2. Record rendered button occurrences and normalized style evidence.
+3. Compare similar button occurrences and explain candidate differences.
+4. Show crisp side-by-side previews with source-confidence labels.
+5. Test against known positive and intentional-variant examples.
+6. Add multiple routes, approved patterns, agent integration and CI incrementally.
+
+## Planning estimates
+
+For one full-time developer, the rough target is 2–3 weeks for a focused proof of concept, 5–8 weeks for a private alpha, 10–14 weeks for a public beta, and 4–6 months for a stable release. These are estimates, not guarantees. Grouping, source mapping, authenticated capture, and reducing false positives are the largest unknowns.