Document scanner product roadmap and Gitea workflow

2026-07-09 10:28:17 +02:00
parent eb666febb6
commit 28d60eb915
9 changed files with 558 additions and 19 deletions
@@ -62,11 +62,14 @@ flowchart LR
 | `src/features/scan/hooks/scanViewScanActions.ts` | Manual scan and visible-grid scan orchestration |
 | `src/features/scan/hooks/scanViewEntryActions.ts` | Guided auto-entry choreography for visible inventory, direct inventory, and IK-style fallback paths |
 | `src/features/scan/hooks/useScanGoodInterop.ts` | Scan-page GOOD import/export actions against renderer repository ports |
 | `src/features/inventory/*` | Planned scanned-artifact inventory, compact result list/grid, filters, and artifact detail views |
 | `src/lib/artifactOcrParser.ts` | Converts OCR output into a parsed artifact candidate with confidence and notes |
 | `src/lib/fuzzyMatch.ts` | Generic fuzzy string matching for OCR text against known game data |
 | `src/lib/genshinLookup.ts` | Pure lookup and validation API for generated Genshin data |
 | `src/lib/autoScanEntry.ts` | Pure entry-mode planning and auto-scan preflight validation |
 | `src/lib/cardReadyGate.ts` | Detail/page fingerprint readiness gate for scan timing |
 | `src/lib/artifactEvaluation.ts` | Planned deterministic artifact value evaluation with score reasons and review-safe output |
 | `src/lib/upgradeProjection.ts` | Planned best/middle/worst upgrade projection for under-leveled artifacts |
 | `src/lib/scoring.ts` | Recommendation and build scoring logic |
 | `src/lib/demoData.ts` | Temporary local demo snapshot |
 | `src/data/genshinGameData.json` | Generated local dictionary of characters, artifact sets, slots, and stats |
@@ -116,6 +119,9 @@ sequenceDiagram
 | OCR crops | Electron main | Electron main | Details modal, parser |
 | Game dictionary | `genshin-db` generated JSON | `src/data/genshinGameData.json` | OCR parser |
 | Parsed artifact candidate | OCR parser | Renderer domain logic | Result panel, future local DB |
 | Scan result entry | Scan loop and parser/evaluator | Renderer domain logic | Live scan rail, artifact inventory, summary |
 | Artifact evaluation | Deterministic evaluator | `src/lib` | Result pills, inventory sort/filter, detail reasons |
 | Upgrade projection | Projection helper | `src/lib` | Artifact detail view only |
 | Review samples | User action in Scan UI | Electron userData `review-samples.jsonl` | Future regression tests and OCR training |
 | Stored artifacts | Manual/automatic scans | Electron userData `artifact-store.json` (dedupe by content signature) | Future triage, recommendations, SQLite migration |
 | Recommendations | Scoring module | Renderer domain logic | Triage and builds views |
@@ -173,6 +179,58 @@ Auto-scan artifact captures also bypass Electron source-list enumeration and use
 the GDI capture helper directly once the selected source/Genshin state has been
 preflighted. Manual captures and source refresh still use `desktopCapturer`.
 ## Scan Results And Inventory UX
 The next product surface is documented in
 [scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md).
 Architecture rules:
 - The active scan view is an operator surface, not the full evaluator. It should
  show the screenshot/preview, the right-side live result rail, Stop/status
  controls, and review access.
 - The live result rail receives completed artifact results only. Intermediate
  OCR/debug stats stay in diagnostics or detail.
 - A scan result row preserves extraction status and artifact value status as
  separate data even when the UI shows one compact pill.
 - The artifact inventory view owns browsing, filtering, sorting, and opening
  detail.
 - The artifact detail view owns screenshot/crop inspection, OCR confidence,
  parser notes, value score reasons, and upgrade projection.
 - Upgrade projection is a local deterministic/probabilistic helper, never a
  claim that an artifact will roll a specific way.
 Planned result flow:
 ```mermaid
 flowchart LR
    ScanLoop["Scan loop"]
    Parsed["Parsed artifact"]
    ReviewGate["Extraction confidence / review gate"]
    Value["Artifact value evaluator"]
    Store["Artifact store"]
    Rail["Live result rail"]
    Inventory["Artifact inventory"]
    Detail["Artifact detail"]
    ScanLoop --> Parsed
    Parsed --> ReviewGate
    ReviewGate --> Value
    Value --> Store
    Value --> Rail
    Store --> Inventory
    Rail --> Detail
    Inventory --> Detail
 ```
 Future queue refactor:
 - One capture/game-control worker may click, scroll, focus, and poll failsafes.
 - OCR/parse/evaluation may process bounded queued screenshot/crop jobs.
 - Queueing must preserve stop behavior, duplicate handling, review decisions,
  and the existing read-only safety boundary.
 - The queue refactor is secondary to content extraction and result/inventory
  contracts while current scan speed remains acceptable.
 ## Security And Safety
 | Area | Policy |
@@ -198,3 +256,5 @@ The app keeps a Tesseract.js worker pool, can use the Inventory-Kamera
 `genshin_fast_09_04_21.traineddata` path for comparison, and reports capture,
 OCR, card-ready, scroll-ready, active-scan, and projected-100 timings. A default
 engine change requires a same-capture benchmark and a qualified live soak result.
 For the next product phase, performance work should not displace extraction
 quality, result clarity, or review safety unless evidence shows a regression.
@@ -42,6 +42,21 @@
 - [ ] Desktop viewport is checked manually.
 - [ ] `npm run build` passes.
 ## Scan Results And Inventory UX
 - [ ] The scan page keeps preview, Stop/status, and the live result rail visible without page-level scrolling.
 - [ ] The live rail shows finished artifact rows only, not intermediate OCR/debug state.
 - [ ] Each live row has scan number, artifact name or compact fallback, value score, and a short status pill.
 - [ ] Extraction confidence and artifact value remain separate in the data model.
 - [ ] Low-confidence or conflicting reads show `Review` instead of a normal weak/strong value decision.
 - [ ] Duplicate state is represented separately from artifact quality.
 - [ ] The artifact inventory view can browse stored scan results without opening diagnostics.
 - [ ] Inventory filters/sorting cover review, score, set, slot, equipped, locked, and newest scan where data exists.
 - [ ] Artifact detail shows screenshot/crop, parsed fields, OCR confidence, parser notes, value reasons, and review state.
 - [ ] Upgrade projection, if shown, is labeled as a projection and includes worst/middle/best cases.
 - [ ] Unit tests cover score/status derivation and projection edge cases when those modules change.
 - [ ] Scanner safety rules and existing quality gates are unchanged.
 ## Parser Or Scoring Change
 - [ ] Known-good OCR samples still parse correctly.
@@ -56,3 +71,21 @@
 - [ ] App starts outside browser preview.
 - [ ] Smart Capture bridge is available.
 - [ ] No generated debug artifacts are included accidentally.
 ## Git Merge And Gitea Push
 - [ ] `git status --short --branch` is checked before switching branches,
      committing, merging, or pushing.
 - [ ] Work is committed on the intended feature branch before merging into
      `main`.
 - [ ] Merge into `main` uses fast-forward when possible, or a deliberate merge
      commit when the history requires it.
 - [ ] `main` is clean before push except for explicitly ignored or deliberately
      untracked local files.
 - [ ] `git remote -v` points to the intended Gitea remote before pushing.
 - [ ] Gitea HTTPS credentials are stored through Git Credential Manager, not in
      repository files or remote URLs.
 - [ ] If authentication fails, refresh the credential using
      [GITEA_AUTH.md](GITEA_AUTH.md), then rerun the same `git push`.
 - [ ] After push, `git status --short --branch` shows `main...origin/main`
      without ahead/behind drift.
@@ -22,8 +22,11 @@ This document defines project engineering standards.
 ## UI Rules
 - The scan page should prioritize the capture workspace over secondary status content.
 - The active scan view should read as preview plus compact result rail, not as a dashboard of live diagnostics.
 - Details and debug information belong in modals or secondary panels.
 - Avoid long, overfilled cards on scanner pages.
 - Do not collapse OCR/extraction confidence and artifact value into one ambiguous UI state; uncertain reads should be visibly `Review`.
 - Artifact value pills should be short, stable labels backed by deterministic data, with detailed reasons behind click-through detail.
 - The design direction is dark purple fintech glassmorphism with premium, focused controls.
 - Disable buttons when their required data does not exist.
@@ -52,3 +55,8 @@ This document defines project engineering standards.
 - Update `docs/PROJECT.md` when product scope changes.
 - Update `docs/ARCHITECTURE.md` when module boundaries or flows change.
 - Add an ADR to `docs/DECISIONS.md` for durable technical trade-offs.
 - Keep workflow/runbook docs linked from `docs/PROJECT.md` so future sessions
  do not depend on chat history.
 - Do not store tokens, passwords, cookies, or generated credentials in project
  files. Use Git Credential Manager for Gitea HTTPS credentials; document only
  the setup path in `docs/GITEA_AUTH.md`.
@@ -17,6 +17,7 @@ This document contains Architecture Decision Records.
 | ADR-009 | Resolution-anchored layout profiles and OCR preprocessing over color detection | Accepted | 2026-07-05 |
 | ADR-010 | Elevated dev runner and bounded live automation probes | Accepted | 2026-07-07 |
 | ADR-011 | Quality-gated Inventory Kamera comparison before OCR default changes | Accepted | 2026-07-07 |
 | ADR-012 | Separate live scan results, artifact inventory, and value evaluation | Accepted | 2026-07-09 |
 ## ADR-001: Build A Local Electron App First
@@ -339,3 +340,60 @@ winner and a complete `current` vs. `ik-traineddata` comparison.
 - The validated `:wait` scan scripts are acceptable for manual post-UAC startup;
  non-waiting scripts remain useful when automation should fail fast.
 - The goal remains open until the 100-artifact qualified comparison is captured.
 ## ADR-012: Separate Live Scan Results, Artifact Inventory, And Value Evaluation
 ### Status
 Accepted
 ### Context
 The visible-inventory scanner baseline is fast enough for the current product
 phase. The next user value comes from better artifact content extraction and a
 clearer surface for scanned artifacts, not from another broad speed pass.
 The scan page currently has more diagnostic/result detail than the operator
 needs during a live scan. Showing every stat, confidence value, and evaluation
 while the scanner is running makes the main workspace noisy and increases the
 risk that a user treats uncertain OCR as a final artifact judgment.
 The desired product flow is:
 - left side: screenshot/preview,
 - right side: compact live list of finished artifact results,
 - later menu item: browsable scanned artifact inventory,
 - click-through detail: screenshot, parsed stats, OCR confidence, evaluation
  reasons, and upgrade projection.
 ### Decision
 Adopt a split scan/result/inventory model:
 - The active scan page shows the latest screenshot/preview and a compact live
  result rail.
 - The live rail shows only scan number, artifact name or compact fallback,
  artifact value score `0-100`, and a result pill after evaluation has finished.
 - Extraction confidence and artifact value are separate data concepts. A low
  confidence read becomes `Review`; it must not be silently displayed as a
  normal weak artifact.
 - Debug stats, raw OCR, confidence breakdowns, and detailed evaluation belong in
  diagnostics, scan summary, or artifact detail.
 - Add a scanned artifact inventory view for browsing, filtering, sorting, and
  opening details.
 - Add artifact detail evaluation before promoting broad recommendations.
 - Add upgrade projection only as a detail-level feature, with worst/middle/best
  projected value scores and clear uncertainty labeling.
 - Keep the producer/consumer screenshot queue as a later implementation phase:
  one game-control worker may click/scroll/capture, while OCR/parse/evaluation
  workers can process bounded queued jobs once the UI/data contracts are stable.
 ### Consequences
 - The scan page becomes calmer and more task-focused.
 - The app can surface useful artifact outcomes without hiding OCR uncertainty.
 - Inventory and detail views become the natural place for richer analysis.
 - Recommendation work has a cleaner dependency chain: trusted scans, compact
  results, artifact inventory, detail evaluation, then build recommendations.
 - Speed work remains possible, but it is secondary unless measured timings show
  a real regression.
@@ -1,4 +1,4 @@
-# Gitea authentication
+# Gitea Authentication
 Remote:
@@ -13,7 +13,8 @@ https://git.noveria.net/user/settings/applications
 ```
 Use the token as the HTTPS password when Git asks for credentials. Do not save
-tokens, passwords, or generated credentials in this repository.
+tokens, passwords, or generated credentials in this repository, in `.env`
 files, or in the remote URL.
 On Windows, this repository uses Git Credential Manager from the system Git
 config:
@@ -28,3 +29,24 @@ Credential Manager or let Git Credential Manager prompt again during:
 ```powershell
 git push origin main
 ```
 Recommended push check:
 ```powershell
 git status --short --branch
 git remote -v
 git push origin main
 git status --short --branch
 ```
 Expected clean result after a successful push:
 ```text
 ## main...origin/main
 ```
 If Git reports `Failed to authenticate user`, do not change the remote to embed
 a token. Open the token page above, create or refresh a token with repository
 write access, clear the stale Windows credential for `git.noveria.net` if
 needed, and rerun the same push command so Git Credential Manager can store the
 new credential safely.
@@ -5,14 +5,17 @@ This document is the source of truth for project intent, scope, runtime facts, a
 For implementation structure, see [ARCHITECTURE.md](ARCHITECTURE.md). For engineering standards, see [CONVENTIONS.md](CONVENTIONS.md).
 For the latest Inventory-Kamera comparison work, see
 [scanner-ik-progress-report.md](scanner-ik-progress-report.md).
 For the next scan-result and artifact-inventory product phase, see
 [scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md).
 For the 2026-07-09 scanner merge evidence, see [MERGE_READINESS.md](MERGE_READINESS.md).
 For Gitea push/authentication setup, see [GITEA_AUTH.md](GITEA_AUTH.md).
 ## Project Identity
 | Field | Value |
 | --- | --- |
 | Project name | Genshin Artifact Assistant |
-| Status | Scanner baseline merged to `main`; repeatability, corpus growth, and recommendation work are next |
+| Status | Scanner baseline merged to `main`; scan result rail, artifact inventory, extraction quality, and corpus growth are next |
 | Platform | Windows desktop |
 | Target users | Genshin Impact players who want artifact decisions without complex optimizer setup |
 | Runtime | Electron app with React UI and TypeScript |
@@ -29,6 +32,9 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
 - Build one local canonical Genshin data package for artifact sets, pieces, slots, stats, and characters.
 - Parse artifact name, slot, main stat, substats, set, equipped state, and confidence deterministically against that package.
 - Save weak or failed reads automatically as review samples and turn corrections into reusable local fixes.
 - Present finished scan results as a compact artifact list instead of a debug-heavy live stats surface.
 - Keep extraction confidence separate from artifact value so uncertain OCR becomes review, not a misleading low score.
 - Provide a browsable local artifact inventory with detail views before promoting broader recommendations.
 - Keep the app offline-first and usable without Genshin Optimizer, Inventory Kamera, Enka, or HoYoLAB.
 - Re-introduce recommendations only after the scanner base is trustworthy.
@@ -54,6 +60,9 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
 | FR-009 | Provide account-level artifact triage after scanner trust is acceptable. | Should | Pending |
 | FR-010 | Provide 1-3 simple build suggestions per character from owned artifacts after scanner trust is acceptable. | Should | Pending |
 | FR-011 | Farming overlay for reward scans. | Later | Prototype shell |
 | FR-012 | Show active scan results as a minimal right-side rail with artifact number, name or compact fallback, value score, and status pill. | Should | Planned |
 | FR-013 | Provide a scanned artifact inventory view with compact score pills, filters, sorting, and click-through detail. | Should | Planned |
 | FR-014 | Provide artifact detail evaluation with screenshot/crops, parsed fields, OCR confidence, value reasons, and optional upgrade projection. | Should | Planned |
 ## Non-Functional Requirements
@@ -64,6 +73,7 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
 | IK target | First 100 artifacts should scan with accuracy at least as good as Inventory Kamera and equal or better speed. | `npm run scan:goal:compare:validated` or `npm run scan:goal:compare:validated:wait` quality-gated report |
 | Privacy | Captures and parsed data stay local by default. | No remote upload in scanner path |
 | Reliability | Uncertain OCR must be visible to the user. | Confidence and details view |
 | Score integrity | Extraction confidence and artifact value are separate concepts. | Review state can block or qualify a value score |
 | Learning loop | Scanner mistakes should become reusable local review samples. | `review-samples.jsonl` |
 | Maintainability | Scanner heuristics must be isolated and documented. | Parser tests, scan-loop tests, data generator, review sample pipeline |
@@ -128,8 +138,11 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
  2026-07-08.
 - OCR quality is still inconsistent enough that some fields are recovered by fallback and derivation more often than they should be.
 - Learned fixes currently focus on text replacements; they do not yet update crop offsets, UI profile variants, or scanner targeting rules in a structured way.
- The scan page is cleaner than before, but it still exposes too much operator/debug state in the main flow.
+- The scan page is cleaner than before, but it still needs the next minimalist
- Recommendations and build logic exist, but the scanner is not yet reliable enough to make them the core focus.
+  result-rail pass so the main flow shows preview plus completed artifact
  outcomes instead of live diagnostic/stat content.
 - Recommendations and build logic exist, but artifact inventory, detail review,
  and value scoring should land first so recommendations have trustworthy inputs.
 - The latest source has completed the final current-vs-IK-traineddata live
  comparison for this environment. Repeatability and 3 artifacts/second are
  still open.
@@ -140,9 +153,10 @@ The app has crossed from OCR-demo/prototype into a validated scanner baseline on
 `main`. The current merge-ready path is the visible-inventory scan flow: the
 operator opens Artifact inventory with a visible detail card, the app verifies
 the state, scans read-only, persists parsed artifacts, and keeps uncertain data
-reviewable. The next product phase is not another broad scanner rewrite; it is
+reviewable. The next product phase is not another broad speed rewrite; current
-repeatability, corpus growth, UI polish, and then recommendations on top of the
+speed is acceptable for now. The priority is better content extraction, a
-trusted artifact store.
+minimal scan-result rail, a browsable artifact inventory, detail evaluation, and
 corpus growth before recommendations become the core product surface.
 ## Product Direction
@@ -151,6 +165,11 @@ trusted artifact store.
 - Team building stays out of the critical path until artifact ingestion is stable.
 - Inventory Kamera remains a reference for scan choreography and page movement, not a runtime dependency.
 - Self-learning stays deterministic and local first: review samples, aliases, crop offsets, and UI profile tuning before any ML retraining discussion.
 - The scan workspace should be an operator surface: preview, live result rail,
  Stop, status, and review access. Detailed stats and debug evidence belong in
  diagnostics, summaries, or artifact detail.
 - Artifact value scoring must not hide OCR uncertainty. `Review` is a distinct
  outcome, not just a weak artifact score.
 ## Execution Plan
@@ -270,31 +289,69 @@ Status:
  crop adjustment proposals, and UI-profile adjustment proposals. Crop/profile
  changes still require live review before being auto-applied.
-### Phase 6 - Recommendations come back on top of a trusted scanner
+### Phase 6 - Minimal scan result rail and artifact inventory
 Outcome:
 - The scan page shows a large screenshot/preview and a compact right-side rail
  of finished artifact evaluations.
 - Each row shows scan number, artifact name or compact fallback, value score,
  and a colored status pill.
 - Debug stats, confidence breakdowns, and OCR internals move out of the main
  scan surface.
 - A new artifact inventory menu provides compact browsing, filters, sorting,
  and click-through details.
 Status:
 - Planned. See
  [scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md)
  for the implementation phases and acceptance criteria.
 ### Phase 7 - Artifact detail evaluation and upgrade projection
 Outcome:
 - Artifact detail explains parsed fields, OCR confidence, scoring reasons, and
  review needs.
 - Upgrade projection is available only when enough data is known and is labeled
  as probabilistic, with worst/middle/best projected value scores.
 - Low-confidence OCR disables or qualifies value conclusions instead of showing
  false certainty.
 Status:
 - Planned after the scan result rail and inventory data contracts.
 ### Phase 8 - Recommendations come back on top of a trusted scanner
 Outcome:
 - Account snapshot and build suggestions are only promoted once scan quality is high enough to trust owned artifacts.
 - Recommendations explain uncertainty and surface conflicts instead of pretending perfect certainty.
 Status:
- Next major product area after repeatability and corpus work. Do not promote
+- Next major product area after inventory, detail evaluation, repeatability, and
-  recommendation UX until stored artifact quality is backed by more confirmed
+  corpus work. Do not promote recommendation UX until stored artifact quality is
-  review samples and repeat live scan runs.
+  backed by more confirmed review samples and repeat live scan runs.
 ## Immediate Next Implementation Order
 1. Keep the visible-inventory scanner path as the production baseline and avoid
   promoting `auto-entry`, `direct-inventory`, or `paimon-menu` until they pass
   their own low-limit live validations.
-2. Grow the confirmed OCR corpus from review samples exported by
+2. Implement the scan result and inventory data contracts from
   [scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md),
   preserving separate extraction confidence and artifact value.
 3. Rework the scan page into preview plus minimal result rail; keep diagnostic
   stats out of the primary scan surface.
 4. Add the artifact inventory menu and detail view before expanding broad build
   recommendations.
 5. Grow the confirmed OCR corpus from review samples exported by
   `npm run eval:review-candidates` and prepared through
   `npm run eval:prepare-confirmed`.
-3. Repeat live scanner runs in later sessions to prove repeatability across
+6. Repeat live scanner runs in later sessions to prove repeatability across
   pages, locked/unlocked artifacts, equipped footers, and duplicate handling.
-4. Continue the optional `3 artifacts/second` work only if the next change can
+7. Continue the optional `3 artifacts/second` work only if the next change can
   reduce OCR/capture transport time without weakening quality gates.
-5. Start recommendation/product UX work only after repeat scan quality and
+8. Start recommendation/product UX work only after inventory/detail evaluation,
-   confirmed corpus coverage are strong enough to trust stored artifacts.
+   repeat scan quality, and confirmed corpus coverage are strong enough to trust
   stored artifacts.
 ## Open Questions
@@ -303,4 +360,6 @@ Status:
 | Is the current C# helper sufficient for production packaging, or does a later Rust/C++ sidecar still materially reduce latency or packaging risk? | Open |
 | When should UI-profile learning be allowed to change crop geometry automatically versus requiring review approval? | Open |
 | What scan-quality threshold is high enough before recommendations should be considered user-facing again? | Open |
 | What exact first-pass value formula should drive the `0-100` artifact score before build-aware recommendations exist? | Open |
 | Which upgrade projection model is honest enough for early UX: deterministic roll buckets, probability-weighted outcomes, or a deliberately simple best/middle/worst estimate? | Open |
 | Which Genshin UI languages should be supported after English once the scanner contract is stable? | Open |
@@ -366,7 +366,11 @@ Expected bottleneck sequence:
 4. Repeat equipped/locked live samples in later sessions if confidence or UI
   behavior changes, but the first positive locked proof has passed.
 5. Keep recommendations secondary until scanner quality remains stable across
-   repeated live sessions.
+   repeated live sessions and the result rail, artifact inventory, and detail
   evaluation flow are implemented.
 6. Treat current speed as acceptable for the next product phase; prioritize
   artifact content extraction and review-safe value scoring before another
   broad speed pass.
 ## Definition of Done for the IK Target
@@ -0,0 +1,270 @@
 # Scanner Results And Artifact Inventory Roadmap
 This document defines the next product phase after the validated visible-inventory
 scanner baseline. The scanner is already fast enough for the current milestone;
 the next work should improve artifact content extraction, review safety, and a
 minimal inventory experience that makes scanned artifacts useful.
 ## Product Stance
 - Keep the scan workspace focused on operation, not analysis.
 - Keep the live preview as the dominant surface.
 - Move debug metrics, OCR internals, and detailed evaluation behind details,
  diagnostics, or the inventory view.
 - Do not merge scan confidence and artifact value into one ambiguous score.
 - Treat uncertain OCR as review, not as a low-quality artifact.
 - Prioritize extracting correct artifact content over another speed pass unless
  live timings regress materially.
 ## Target User Flow
 1. The user opens Artifact inventory in Genshin with a visible detail card.
 2. The scanner runs the existing read-only visible-inventory flow.
 3. The scan view shows the latest screenshot/preview on the left.
 4. A compact live result rail on the right receives one row per finished
   artifact evaluation.
 5. Each row shows only:
   - scan number,
   - artifact name or compact slot/set fallback,
   - artifact value score from `0` to `100`,
   - a colored result pill.
 6. After the scan, the user opens the inventory menu to browse all scanned
   artifacts.
 7. Clicking an artifact opens a detail view with screenshot, parsed fields,
   OCR confidence, scoring reasons, and optional upgrade projection.
 ## Score Contract
 The UI must keep two concepts separate:
 | Concept | Meaning | UI behavior |
 | --- | --- | --- |
 | Extraction confidence | How reliable the scan/OCR/parser result is. | Drives `Review`, warnings, and detail confidence rows. |
 | Artifact value score | How useful the artifact appears for builds. | Drives the `0-100` value and good/mid/weak pill. |
 Rules:
 - If extraction confidence is too low, show `Review` instead of a normal value
  decision, even when a tentative value score exists.
 - If the artifact is a duplicate, show duplicate state separately from value.
 - The live rail may show one compact pill, but the data model should preserve
  separate `extractionStatus` and `valueStatus` fields.
 - Score labels should be stable and simple:
 | Value score | Label |
 | --- | --- |
 | `90-100` | Strong |
 | `70-89` | Good |
 | `45-69` | Mid |
 | `0-44` | Weak |
 | unknown or unsafe | Review |
 The exact formula can start simple and deterministic. It should explain its
 reasons in the detail view before it becomes a recommendation source.
 ## Planned Pipeline Shape
 The current scan loop can keep shipping while the UI and data contracts are
 built. A fuller producer/consumer pipeline is a later implementation step:
 ```mermaid
 flowchart LR
    Capture["Single capture and game-control worker"]
    Queue["Bounded screenshot/crop queue"]
    OCR["OCR and parse workers"]
    Eval["Artifact evaluation"]
    Aggregate["Aggregator and store"]
    UI["Live rail and inventory"]
    Capture --> Queue
    Queue --> OCR
    OCR --> Eval
    Eval --> Aggregate
    Aggregate --> UI
 ```
 Constraints:
 - Only one worker may control Genshin input, focus, click, scroll, or failsafe
  polling.
 - OCR/parse/evaluation workers may run concurrently on already captured
  screenshot/crop jobs.
 - The queue must be bounded, initially around `4-8` jobs, so the scanner does
  not outrun retries, review decisions, or stop requests.
 - The pipeline must preserve current safety rules: no memory reads, hooks,
  injection, game-file changes, deleting, feeding, enhancing, locking/unlocking,
  or spending resources.
 - Do not implement the queue refactor before the result/inventory contracts are
  stable, unless timing evidence shows the current loop has become the blocker.
 ## Implementation Phases
 ### Phase 0 - Documentation and contracts
 Status: prepared by this document.
 Outcome:
 - Product direction is documented.
 - Main docs point to this roadmap.
 - Acceptance criteria and checklists exist before code changes.
 ### Phase 1 - Result data model
 Outcome:
 - Add a durable scan result entry model with sequence number, capture metadata,
  parsed artifact identity, extraction status, artifact value score, value
  status, duplicate/review flags, and timestamps.
 - Keep existing stored artifact records compatible.
 - Add tests for status derivation so low-confidence OCR cannot become a normal
  `Good` or `Strong` result.
 Likely files:
 - `src/types/domain.ts`
 - `src/types/storage.ts`
 - `src/lib/scannerSession.ts`
 - `src/lib/storedArtifactAdapter.ts`
 - `src/lib/scanReviewUtils.ts`
 ### Phase 2 - Minimal live result rail
 Outcome:
 - Rework the scan main section into preview plus right-side result rail.
 - Remove live evaluation cards and noisy stats from the primary scan area.
 - Append rows only after an artifact has finished parse/evaluation.
 - Keep Stop, scan status, and review access available.
 - Keep debug stats in diagnostics or summary modals.
 Likely files:
 - `src/features/scan/components/ScanMainSection.tsx`
 - `src/features/scan/components/ScanResultCards.tsx`
 - `src/features/scan/components/hooks/useScanMainSectionModel.ts`
 - `src/features/scan/components/hooks/useScanResultCardsModel.ts`
 - `src/styles/base.css`
 ### Phase 3 - Artifact inventory view
 Outcome:
 - Add a menu item for scanned artifact inventory.
 - Show a compact, minimal list or dense grid of stored artifacts.
 - Each entry shows the same score/pill language as the live rail.
 - Provide filters and sorting for review, score, set, slot, equipped, locked,
  and newest scan.
 - Avoid a marketing/landing layout; the first screen is the actual inventory.
 Likely files:
 - `src/features/inventory/*`
 - `src/features/layout/navigation.ts`
 - `src/pages/app/*`
 - `src/lib/artifactStore.ts`
 - repository bridge/storage files as needed
 ### Phase 4 - Artifact detail view
 Outcome:
 - Clicking a live row or inventory item opens detail.
 - Detail shows screenshot or detail crop when available.
 - Detail lists parsed fields, OCR confidence, parser notes, extraction status,
  value score, and scoring reasons.
 - Review-required items make the uncertainty explicit and do not present their
  score as final.
 Likely files:
 - `src/features/inventory/components/*`
 - `src/features/scan/components/modals/*`
 - `src/lib/artifactOcrParser.ts`
 - `src/lib/scoring.ts`
 ### Phase 5 - Artifact value evaluation
 Outcome:
 - Add a deterministic artifact value evaluator before promoting build
  recommendations.
 - Explain the score through factors such as set, slot, main stat, substat
  quality, level, locked/equipped state, and available character/build context.
 - The evaluator must accept incomplete data and return review/unknown instead
  of confident nonsense.
 Likely files:
 - `src/lib/artifactEvaluation.ts`
 - `src/lib/scoring.ts`
 - `src/lib/substatRolls.ts`
 - `src/lib/genshinLookup.ts`
 - targeted unit tests under `src/lib/*.test.ts`
 ### Phase 6 - Upgrade projection
 Outcome:
 - For artifacts below max level, show optional projection only in detail.
 - Provide `worst`, `middle`, and `best` projected value scores.
 - Label projection as probabilistic and not a guaranteed result.
 - Use known Genshin upgrade constraints and current substats; unknown or
  partially read data must disable or soften the projection.
 Likely files:
 - `src/lib/upgradeProjection.ts`
 - `src/lib/substatRolls.ts`
 - `src/features/inventory/components/*`
 - parser/scoring tests
 ### Phase 7 - Queue-based analysis pipeline
 Outcome:
 - Introduce a bounded screenshot/crop job queue only after the UI/data contract
  is stable.
 - Keep one game-control worker.
 - Allow OCR/parse/evaluation workers to process queued jobs.
 - Preserve stop/failsafe behavior and review decisions.
 - Compare throughput against the current baseline without weakening accuracy.
 Likely files:
 - `src/lib/autoScanLoop.ts`
 - `src/lib/scannerSession.ts`
 - Electron capture/OCR boundary in `electron/main.ts` or extracted services
 - scan-loop tests and live soak scripts
 ### Phase 8 - Recommendation promotion
 Outcome:
 - Promote account-level recommendations only after scan result quality,
  inventory browsing, detail review, and value scoring are trustworthy.
 - Recommendations must reference stored artifact quality and uncertainty.
 ## Acceptance Criteria
 - The scan page still fits the primary workflow without page-level scrolling.
 - The preview remains visible during active scan.
 - The right rail shows finished artifact evaluations, not noisy intermediate
  parser/debug state.
 - Review items are visibly different from weak artifacts.
 - Artifact value score and extraction confidence remain separate in data.
 - Inventory view can browse stored scan results without opening diagnostics.
 - Detail view explains why an artifact received its score.
 - Upgrade projection never implies a guaranteed future roll.
 - Existing safety constraints and scan quality gates remain intact.
 ## Validation Plan
 - `npm run lint`
 - `npm test`
 - `npm run build`
 - Add unit tests for score/status derivation and upgrade projection.
 - For scanner-facing changes, run a low-limit visible-inventory live scan before
  wider validation.
 - Keep `npm run scan:repeatability:wait` for later regression checks, not for
  every UI-only pass.
@@ -4,6 +4,8 @@ Progress on the approved scanner/OCR rework. See ADR-007/008/009/010 in
 [DECISIONS.md](DECISIONS.md) for the decisions behind these. For the current
 live automation runbook, see
 [AUTOMATION_LIVE_SCAN.md](AUTOMATION_LIVE_SCAN.md).
 For the next result/inventory product phase, see
 [scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md).
 ## Current Scanner Status
@@ -35,6 +37,10 @@ Current status after the 2026-07-09 merge to `main`:
  equipped characters (`Citlali`, `Linnea`), unlocked artifacts reported
  `locked: false`, a visibly locked artifact reported `locked: true`, and a
  bounded auto-scan persisted the locked/equipped state.
 - Current speed is acceptable for the next product phase. The next work should
  prioritize correct artifact content extraction, a minimal live result rail,
  scanned artifact inventory, detail evaluation, and review-safe value scoring
  before another broad speed pass.
 ## Done (implemented, unit-tested, build green)
@@ -223,7 +229,26 @@ Current status after the 2026-07-09 merge to `main`:
  pixels because Electron's native bitmap channel order was ambiguous in live
  captures.
-## Remaining — needs the live environment or a UI pass
+## Next product phase - result rail and inventory
 The next implementation pass is planned in
 [scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md).
 Summary:
 1. Add result data contracts that preserve extraction confidence separately from
   artifact value score.
 2. Rework the scan view into screenshot/preview plus a compact right-side live
   result rail.
 3. Add a scanned artifact inventory menu with minimal list/grid rows and
   score/review pills.
 4. Add click-through artifact detail with screenshot/crops, parsed fields, OCR
   confidence, value reasons, and review state.
 5. Add upgrade projection later as a detail-only feature with worst/middle/best
   cases and explicit uncertainty.
 6. Defer the full screenshot queue/worker pipeline until the result/inventory
   contracts are stable or timing evidence shows the current loop is the blocker.
 ## Remaining - needs the live environment or a UI pass
 These cannot be finished/validated without Genshin running at the user's
 resolution or without UI work best tested live: