From 9a15f364855867eca3c384d3a394c45676d87cdb Mon Sep 17 00:00:00 2001 From: LLLin000 <809867916@qq.com> Date: Mon, 20 Jul 2026 01:49:33 +0800 Subject: [PATCH] docs: define control center UX redesign --- CONTEXT-MAP.md | 3 + CONTEXT.md | 19 +- PROJECT-MANAGEMENT.md | 42 +- docs/adr/0001-capability-action-semantics.md | 3 + paperforge/plugin/CONTEXT.md | 137 +++++++ paperforge/plugin/DESIGN.md | 191 +++++++++ project/current/control-center-ux-redesign.md | 361 ++++++++++++++++++ project/current/ocr-v2-active-queue.md | 22 +- 8 files changed, 748 insertions(+), 30 deletions(-) create mode 100644 docs/adr/0001-capability-action-semantics.md create mode 100644 paperforge/plugin/CONTEXT.md create mode 100644 paperforge/plugin/DESIGN.md create mode 100644 project/current/control-center-ux-redesign.md diff --git a/CONTEXT-MAP.md b/CONTEXT-MAP.md index 23beacc0..91bf4b49 100644 --- a/CONTEXT-MAP.md +++ b/CONTEXT-MAP.md @@ -4,8 +4,11 @@ - [OCR Quality Report](./CONTEXT.md) — quality signals, quality indicators, readiness policy, and human validation for OCR outputs. - [Retrieval Layer](./paperforge/memory/CONTEXT.md) — paper-native retrieval units, lookup intents, corpus recall, and structured paper navigation. +- [Plugin Control Center](./paperforge/plugin/CONTEXT.md) — presents device foundation, module health, recovery actions, and configuration in user-facing language ## Relationships - **OCR Quality Report → Retrieval Layer**: OCR quality produces diagnostics and boundary facts that the retrieval layer may use for local junk veto and build health, but not for paper-level trust penalties. - **Retrieval Layer ↔ OCR Quality Report**: Retrieval consumes structured OCR outputs and structure boundaries; it must not redefine OCR readiness as retrieval importance. +- **OCR Quality Report → Plugin Control Center**: OCR readiness and recovery facts are presented as module health and contextual actions without redefining their meaning. +- **Retrieval Layer → Plugin Control Center**: Retrieval readiness and maintenance facts are presented as Memory health and contextual actions without exposing storage implementation as primary navigation. diff --git a/CONTEXT.md b/CONTEXT.md index dd5c7acc..84a8965b 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -15,7 +15,7 @@ A stable, opinion-free normalization of raw signals into a status (`green | yell *Not:* a score or composite. Each indicator stands alone. ### User Readiness -A **policy-based estimate** of whether the OCR result is usable by an end user. It is *not* ground truth — it is `policy_estimated_readiness`. +A **policy-based internal estimate** of whether the OCR result supports a use case. It is not ground truth and does not by itself create a user-visible problem or maintenance item. ```python user_readiness = { @@ -27,6 +27,13 @@ user_readiness = { } ``` +### Usable OCR Result +An OCR result that supports the user's intended reading or retrieval task despite ordinary recognition and layout imperfections. + +### User-visible OCR Failure +An OCR outcome that prevents reading or retrieval and has a concrete recovery action likely to improve or restore the result. +*Not:* a low confidence score, minor defect, or internal quality warning with no useful action. + ### Recommended Use A per-use-case assessment, each with its own gate. - `reading` — rendered text integrity + body flow @@ -66,19 +73,19 @@ The user-facing capability for finding either a known paper or knowledge inside Regenerable data derived from the Source Corpus for search: FTS indexes, embeddings, vector tables, and their companion metadata. Retrieval Artifacts may be discarded and rebuilt; they are not preservation targets or sources of truth. ### Capability State -The current usability of one PaperForge module. Installation, Library, OCR, Memory, Maintenance, and Help each report their own state; there is no global “setup complete” state. +The current usability of one operational module. Foundation, Library, OCR, Smart Retrieval, and Agent Integration each report their own state; Maintenance and Help are not modules. ### Activity State -Work currently being performed by a module, such as installing, rebuilding, or stopping. Activity is independent of capability: a module may keep a warning while repair is running. +Work currently being performed by a module, such as installing, rebuilding, or stopping. Activity is independent of capability: a module may remain usable while maintenance runs. ### Attention State -Whether a module currently needs a user decision or action. Normal capability stays quiet; warnings expose one concrete primary action. +Whether a module has a concrete user-visible problem and a backend-authorized action. Internal quality warnings and non-actionable imperfections stay quiet. ### Maintenance Inbox -A derived view of actionable stale, failed, or corrupt work reported by the other modules. It is not an independent source of truth, and successful work leaves the inbox. +A derived view of unresolved user-visible problems that have concrete recovery actions. It excludes internal quality signals, non-actionable imperfections, and completed work. ### Managed Runtime -The verified, versioned PaperForge execution environment selected by the plugin. Installation, health checks, upgrades, and rollback operate on one runtime identity; commands fail closed when that identity is unknown or stale. +The verified, versioned execution component inside Foundation. Runtime identity and recovery are advanced diagnostics; normal user language refers to the Foundation or PaperForge environment. ## Architecture layers diff --git a/PROJECT-MANAGEMENT.md b/PROJECT-MANAGEMENT.md index 58956ca9..a2fe7ef5 100644 --- a/PROJECT-MANAGEMENT.md +++ b/PROJECT-MANAGEMENT.md @@ -1,13 +1,13 @@ > **Branch:** `master` | **Last Updated:** 2026-07-19 -> **Active work:** [Control-center PRD #74](https://github.com/LLLin000/PaperForge/issues/74) is split into eight dependency-linked implementation issues (#75–#82). Setup/config (#75), capability envelopes (#76), Managed Runtime/navigation (#77), Library/OCR/Memory capability tracers (#78), SecretStorage (#79), and Maintenance probe (#80) are implemented; Release N+1 owner cutover (#81) is next. +> **Active work:** Control-center UX redesign is now the approved next program after live #78–#80 verification exposed release-package and information-architecture failures. > > --- > -> **Current state:** Retrieval recovery is merged and live. OCR multi-key rebuild/redo streams progress and refreshes canonical maintenance state. The control plane now includes schema-v1 capability envelopes plus a machine-local Managed Runtime with immutable slots, atomic activation, rollback, cancellation, and managed-first command dispatch. +> **Current state:** Retrieval recovery and the current control plane are live, but the shipped UX contract is superseded. Literature-hub is temporarily pinned to the probe-capable `v1.5.15` runtime because the published `1.5.15` package lacks `paperforge probe`; the `v1.5.15_build2` slot remains the previous runtime. > -> #71/#72 prototypes and #73 migration contract are complete. PRD #74 defines the six-module production program; #75–#80 are implemented. The Wayfinder overview and `概览 / 模块详情 / 维护 / 帮助` shell are live; #78 added real Library/OCR/Memory detail tracers, #80 promoted Maintenance from placeholder to a real backend-derived probe with actionable-only rows, privacy-safe local draft, and accessible destructive confirmation. +> Live diagnosis confirmed duplicated runtime actions, stale-as-“待接入” presentation, and an asymmetric Module Detail implementation: Installation renders a one-item legacy selector while Library/OCR/Memory use the shared selector. A user grilling session approved a five-module model (Foundation, Library, OCR, Smart Retrieval, Agent Integration), three top-level destinations (Overview, Maintenance, Help), a four-stage dynamic setup journey, user-problem-only Maintenance, and Obsidian-native progressive disclosure. > -> Next: implement [#81](https://github.com/LLLin000/PaperForge/issues/81) (Release N+1 owner cutover) in a fresh Matt `/implement` session. +> Next: publish and clean-venv verify a backend package containing `paperforge probe`; then route `project/current/control-center-ux-redesign.md` through Ask Matt into dependency-linked agent-ready issues, beginning with the capability presentation contract. ## 1. Architecture ### 1.1 The problem (pre-v2) @@ -55,7 +55,7 @@ raw observations → structural signatures → stable anchors/families → zone | 86-paper pre-merge corpus diff | **86/86 no diff** ✅ | | 6 fixture-backed v3 parity gates | **6/6 pass** ✅ | | Focused OCR rebuild/redo/maintenance paths | **99 passed, 1 Windows signal test skipped, 1 unrelated empty-result regression deselected** ✅ | -| Plugin tests + TypeScript + production build | **93 passed; typecheck/build clean** ✅ | +| Plugin tests + TypeScript + production build | **384/384 passed; typecheck/build clean; production bundle 259.3KB** ✅ | | Live Literature-hub maintenance UI | **734 All / 700 Recommended; no captured errors** ✅ | | Maintenance regression action model | **19/19 passed** ✅ (per-row canonical action routing, redo confirmation gate, cache manifest preservation) | | Canonical setup/config migration (#75) | **61 passed, 0 failed** ✅ (fresh/v1/v2 config, CLI routing, path forwarding, failure exit, idempotent rerun) | @@ -90,7 +90,7 @@ raw observations → structural signatures → stable anchors/families → zone | **Control-plane contracts** | ✅ Orthogonal capability/activity/attention model and managed-runtime immutable-slot architecture chosen; documented in `docs/research/2026-07-14-capability-state-action-contract.md` and `docs/research/2026-07-14-managed-runtime-architecture.md` | | **Setup/config migration** | ✅ Bare, headless, and modular setup share `SetupPlan`; schema-v2 `vault_config` is authoritative with warned v1 read fallback | | **Capability tracer** | ✅ Installation/Help backend envelopes feed the six-module Overview; malformed/stale persistence fails closed; setup/update actions route to the setup flow | -| **Managed Runtime** | ✅ Immutable machine-local slots, atomic pointer activation, rollback/cancel/retention, managed-first command dispatch | +| **Managed Runtime** | ✅ Immutable machine-local slots, atomic pointer activation, rollback/cancel/retention, exclusive managed dispatch, and startup `status()` warmup before settings/probes | | **Agent workflow controls** | ✅ `.omp/RULES.md` + `matt-guard.ts` enforce one-writer Matt flow, worktree isolation, and post-mutation verification before release operations | | **Library/OCR/Memory detail tracers** | ✅ Real capability probes with module-detail-navigation, installation-navigation, and capability-state views; Python owns capability fact definitions; TypeScript render uses exact allowlist, fails closed on unknown keys | | **Maintenance probe (#80)** | ✅ Backend-derived actionable-only rows, privacy-safe local draft, owned inert cleanup, accessible destructive confirmation with exact backend effect; redacted editable issue draft, no token input/auto-open, explicit GitHub open only, URL re-redaction @@ -134,6 +134,7 @@ raw observations → structural signatures → stable anchors/families → zone | 36 | — | Maintenance probe: backend-derived rows, privacy-safe local draft, accessible destructive confirmation (#80) | Feature | Implementation in Issue #80 worktree. Backend-focused gate 77/77; plugin full suite 381/382 (pre-existing capability-state test expecting help.stale but receiving help.invalid_response); typecheck/build clean; production bundle 264.4KB; Obsidian 1.12.7 smoke 730/768 with actionable-only rows, keyboard Enter, accessible destructive confirmation with exact backend effect, focus trap/restoration, owned inert cleanup, redacted editable issue draft, no token input/auto-open, explicit GitHub open only, URL re-redaction, no horizontal overflow. | — | +| 37 | — | Literature-hub loaded duplicate `.obsidian/plugins/paperforge.bak`, while the correct bundle used an unwarmed Managed Runtime and the published 1.5.15 backend lacked `probe` | Deployment/runtime fix | Moved the duplicate outside the plugin scan path, migrated both credentials with readback verification, installed the current backend into the canonical managed venv, restored idempotent migration on startup, shared and warmed the runtime before dispatch, synchronized manifest `minAppVersion` 1.11.4, rebuilt and redeployed. Live cold-start verification: #78 overview/detail, #79 configured secret state, #80 three-row Maintenance inbox; no captured Obsidian errors. | — | ## 3. Remaining Issues — Release-Readiness Layers ### Layer 1: OCR Truth Coverage — Layout-Category Audit @@ -169,14 +170,15 @@ The OCR maintenance slice has a canonical All/Recommended state model, selected Remaining legacy OCR issues (carried forward): ## 4. Active Queue -1. 🔴 **[Control-center PRD #74](https://github.com/LLLin000/PaperForge/issues/74)** — published and split into eight native dependency-linked issues (#75–#82). #75–#80 are implemented; #81 Release N+1 owner cutover is the next unblocked slice. -2. ✅ **[Capability-state vocabulary](https://github.com/LLLin000/PaperForge/issues/69)** — resolved at `issuecomment-4971161072`. Orthogonal availability/activity/attention axes, 6-state capability ordinal, 12 canonical verbs, backend-owned severity and primary actions, maintenance projection. -3. ✅ **[Managed runtime](https://github.com/LLLin000/PaperForge/issues/70)** — resolved at `issuecomment-4971239398`. Plugin-managed immutable runtime slots, system-Python bootstrap with validated-triplet fallback, single `active-runtime.json` pointer, `ManagedRuntime` class with `current()`/`status()`/`ensure()`, fail-closed command resolution. -4. ✅ **[Control-center prototype](https://github.com/LLLin000/PaperForge/issues/71)** — resolved with independent Critical/Important PASS review and browser verification at 768px. Six-module control-center HTML prototype covers 5 scenarios with plain-button switcher, primary attention zone, responsive layout, and capability-gated actions. Design decisions recorded in `docs/prototypes/2026-07-14-six-module-control-center.html/.md`. No production implementation before #73. -5. ✅ **[Maintenance prototype](https://github.com/LLLin000/PaperForge/issues/72)** — resolved with independent Critical/Important PASS review and browser verification at 768px. Actionable-only inbox with single-action rows, inline issue-draft review, local redacted export, and confirmation-first report flow. Design decisions recorded in `docs/prototypes/2026-07-14-maintenance-issue-reporting.html/.md`. -6. ✅ **[Migration and acceptance contract #73](https://github.com/LLLin000/PaperForge/issues/73)** — closed after five-domain code audit, user grilling, and independent acceptance reviews. The implementation frontier moved to PRD #74 and child issues #75–#82. -7. 🟡 **Downstream tooling** — section-aware chunking and separate figure/table handling. -8. ⏳ **Compatibility naming cleanup** — deferred post-release. +1. ✅ **[Control-center PRD #74](https://github.com/LLLin000/PaperForge/issues/74)** — all eight implementation issues (#75–#82) are complete and live-verified in Literature-hub after duplicate-plugin and cold-runtime recovery. +2. 🟡 **Control-center UX redesign** — approved design baseline in `project/current/control-center-ux-redesign.md`; replaces Installation-as-module, six mixed module cards, top-level Module Detail, raw backend labels, per-card Check actions, and non-actionable OCR quality maintenance. Implementation must be split through Ask Matt after the probe-capable package release. +3. ✅ **[Capability-state vocabulary](https://github.com/LLLin000/PaperForge/issues/69)** — resolved at `issuecomment-4971161072`. Orthogonal availability/activity/attention axes, 6-state capability ordinal, 12 canonical verbs, backend-owned severity and primary actions, maintenance projection. +4. ✅ **[Managed runtime](https://github.com/LLLin000/PaperForge/issues/70)** — resolved at `issuecomment-4971239398`. Plugin-managed immutable runtime slots, system-Python bootstrap with validated-triplet fallback, single `active-runtime.json` pointer, `ManagedRuntime` class with `current()`/`status()`/`ensure()`, fail-closed command resolution. +5. ✅ **[Control-center prototype](https://github.com/LLLin000/PaperForge/issues/71)** — resolved with independent Critical/Important PASS review and browser verification at 768px. Six-module control-center HTML prototype covers 5 scenarios with plain-button switcher, primary attention zone, responsive layout, and capability-gated actions. Design decisions recorded in `docs/prototypes/2026-07-14-six-module-control-center.html/.md`. No production implementation before #73. +6. ✅ **[Maintenance prototype](https://github.com/LLLin000/PaperForge/issues/72)** — resolved with independent Critical/Important PASS review and browser verification at 768px. Actionable-only inbox with single-action rows, inline issue-draft review, local redacted export, and confirmation-first report flow. Design decisions recorded in `docs/prototypes/2026-07-14-maintenance-issue-reporting.html/.md`. +7. ✅ **[Migration and acceptance contract #73](https://github.com/LLLin000/PaperForge/issues/73)** — closed after five-domain code audit, user grilling, and independent acceptance reviews. The implementation frontier moved to PRD #74 and child issues #75–#82. +8. 🟡 **Downstream tooling** — section-aware chunking and separate figure/table handling. +9. ⏳ **Compatibility naming cleanup** — deferred post-release. ### 4.1 Immediate Next Steps - [x] OCR rebuild streaming protocol @@ -199,7 +201,9 @@ Remaining legacy OCR issues (carried forward): - [x] Expose Library, OCR, and Memory capabilities end to end ([#78](https://github.com/LLLin000/PaperForge/issues/78)) — 65 backend tests + 178 focused plugin tests, 324 full plugin tests across 11 files; typecheck/build clean; fail-closed recognizable config for Library/OCR; red rebuild_result stays non-destructive rebuild; queued OCR progress starts at 0; failed/null Library sync exit outcome is forwarded into fresh Python probe and remains sync actionable - [x] Implement SecretStorage for capability secrets ([#79](https://github.com/LLLin000/PaperForge/issues/79)) — backend-focused gate passes; plugin full suite passes; typecheck/build clean - [x] Implement Maintenance probe with backend-derived rows, privacy-safe local draft, and accessible destructive confirmation ([#80](https://github.com/LLLin000/PaperForge/issues/80)) — backend focused gate 77/77; plugin full suite 381/382 (only pre-existing capability-state test expecting help.stale but receiving help.invalid_response); typecheck/build clean; production bundle 264.4KB; real Obsidian 1.12.7 smoke at 730 and 768 confirmed actionable-only rows, keyboard Enter, accessible destructive confirmation with exact backend effect, focus trap/restoration, owned inert cleanup, redacted editable issue draft, no token input/auto-open, explicit GitHub open only, URL re-redaction, no horizontal overflow -- [ ] Implement Release N+1 owner cutover ([#81](https://github.com/LLLin000/PaperForge/issues/81)) +- [x] Implement Release N+1 owner cutover ([#81](https://github.com/LLLin000/PaperForge/issues/81)) and N+2 clean cutover ([#82](https://github.com/LLLin000/PaperForge/issues/82)) + - [ ] Publish a backend package containing the `probe` command before removing the Literature-hub editable runtime + - [ ] Route the approved control-center UX redesign through Ask Matt into dependency-linked implementation issues; first slice is the capability presentation contract. ## 5. Key File Map @@ -358,6 +362,12 @@ Remaining legacy OCR issues (carried forward): | 2026-07-18 | Enforce Matt with sticky rules plus a minimal deterministic hook | Prose alone cannot prevent orchestration drift. Keep lifecycle guidance in `.omp/RULES.md`; use the hook only for mechanically provable boundaries: one writer, worktree isolation, and verification-after-last-mutation before release operations. | | 2026-07-18 | Capability facts are Python-owned; TypeScript renders via exact allowlist, fail-closed | Python owns all capability fact definitions and cross-module consistency. TypeScript receives only pre-classified display objects; rendering uses an exact allowlist of known content component keys. Unknown keys render nothing (fail-closed) rather than guessing a classification. TypeScript forwards operation exit outcomes but Python classifies sync failure. This avoids duplicating classification logic across the stack. | | 2026-07-19 | Maintenance is a backend-derived probe, not a frontend projection | Prior design (2026-07-14) treated maintenance as a frontend-projected view over capability-state data. Real implementation showed that actionable rows (stale, failed, corrupt) and their canonical verbs must come from the backend's `probe maintenance --json` — the frontend cannot reconstruct per-paper rebuild eligibility from capability state alone. Backend owns exact actions; frontend renders via derived model with primary null for quality-ok items. This keeps Maintenance as a true probe while remaining a projection over backend OCR facts rather than a separate pipeline output. Privacy-safe local draft and owned inert modal cleanup are frontend-only concerns. | +| 2026-07-19 | A plugin deployment is valid only when the loaded manifest directory and backend command surface are verified | Copying `main.js` proved nothing while Obsidian loaded a duplicate `paperforge.bak`; the managed venv also contained a published package without `probe`. Release verification must assert `manifest.dir`, cold `ManagedRuntime.status()`, and a real `paperforge probe` command before UI acceptance. | +| 2026-07-19 | Installation is an action; Foundation is the persistent module | Users should not have to understand why an “Installation” module remains after installation. Foundation owns the PaperForge environment; Runtime and Python remain support/recovery details. | +| 2026-07-19 | The control center has five operational modules and three top-level destinations | Foundation, Library, OCR, Smart Retrieval, and Agent Integration have independent lifecycles. Overview, Maintenance, and Help are destinations; Module Detail is contextual drill-down, while Maintenance and Help are not health-reporting modules. | +| 2026-07-19 | Maintenance contains only user-visible, resolvable problems | Internal OCR quality estimates, ordinary OCR imperfections, stale cache, optimization suggestions, and optional capabilities never enabled do not merit user attention. A problem must block use, fail a requested task, make output unusable, or create material data risk and have a concrete action. | +| 2026-07-19 | Backend owns action semantics; plugin owns localized presentation | Stable action IDs, exact commands, scope, and safety facts remain backend-authorized, while the plugin supplies user language and visual priority. This prevents frontend action guessing without leaking English CLI labels. | +| 2026-07-19 | PaperForge UI is Obsidian-native with progressive disclosure | Default surfaces show outcomes, impact, and one next step. Technical detail becomes a one-click privacy-safe Support Diagnostic rather than ordinary UI content. | --- @@ -465,6 +475,8 @@ python -m ruff check paperforge/worker/ocr_*.py | 2026-07-18 | OMP Matt workflow enforcement | Removed all discoverable Superpowers installations, retained canonical Ask Matt skills, added sticky project rules, and installed an auto-discovered hook for one-writer batches, worktree isolation, and fresh verification gates. Fresh OMP smoke reached the hook; 7/7 deterministic guard cases passed. | `.omp/RULES.md`, `.omp/hooks/pre/matt-guard.ts` | | 2026-07-18 | Library/OCR/Memory capability tracers (#78) | Implemented real capability probes for Library, OCR, and Memory with module-detail-navigation, installation-navigation, and capability-state views. Python owns capability facts; TypeScript exact allowlist/fail-closed rendering avoids duplicate classification. Verification: 58 backend + 171 plugin tests, typecheck/build clean, Obsidian 730px/768px smoke (no overflow, keyboard focus/restore, heading focus/restore, diagnostic disclosure, OCR rebuild progress 3/10, cooperative stop, idle/re-probe). | §2-4 | | 2026-07-19 | SecretStorage (#79) + Maintenance probe (#80) | Implemented SecretStorage capability secrets (backend-focused gate, plugin full suite). Implemented Maintenance probe: backend-derived actionable-only rows, privacy-safe local draft, accessible destructive confirmation via derived VerbModel with primary null for quality-ok items. Backend owns exact actions from `probe maintenance --json`; frontend renders downstream. Verification: backend focused gate 77/77; plugin full suite 381/382 (pre-existing capability-state test expecting help.stale but receiving help.invalid_response); typecheck/build clean; production bundle 264.4KB; Obsidian 1.12.7 smoke at 730 and 768 (entry focus, actionable-only, keyboard Enter, destructive confirmation with backend effect, focus trap/restoration, owned inert cleanup, redacted editable draft, no token/auto-open, explicit GitHub open only, URL re-redaction, no overflow). | §2-4 | +| 2026-07-19 | Literature-hub #78–#80 deployment recovery | Found Obsidian loading duplicate `.obsidian/plugins/paperforge.bak`; moved it outside plugin discovery, migrated OCR/Vector secrets with readback verification, synchronized manifest 1.11.4, installed the current backend into the canonical managed venv, restored startup migration, and warmed the shared Managed Runtime before dispatch. Live cold-restart checks showed real Library/OCR/Memory actions, four-button detail selector, three actionable Maintenance rows, configured secrets with no plaintext, and no captured errors. Verification: 384/384 plugin tests, typecheck/build clean, 259.3KB bundle. | §2-6 | +| 2026-07-19 | Control-center UX domain redesign | Live diagnosis proved that the current six-module vocabulary and navigation were not understandable despite passing earlier implementation gates. Completed a user grilling/domain-modeling session; approved five operational modules, three top-level destinations, dynamic setup, six user statuses, navigation-only cards, module-owned configuration, actionable-problem-only Maintenance, separate OCR workspace, and one-click redacted diagnostics. Added plugin domain language, ADR, Obsidian-native `DESIGN.md`, full UX specification, acceptance matrix, and ten dependency-ordered implementation slices. No production code changed. | `paperforge/plugin/CONTEXT.md`, `paperforge/plugin/DESIGN.md`, `project/current/control-center-ux-redesign.md`, `docs/adr/0001-capability-action-semantics.md` | ## 9. Historical Detail Archive diff --git a/docs/adr/0001-capability-action-semantics.md b/docs/adr/0001-capability-action-semantics.md new file mode 100644 index 00000000..3341dd8a --- /dev/null +++ b/docs/adr/0001-capability-action-semantics.md @@ -0,0 +1,3 @@ +# Separate Capability Action Semantics from Presentation + +PaperForge capability probes own which action is available, its stable action ID, exact executable command, and safety metadata. The Obsidian plugin owns localized labels, explanatory copy, and visual priority keyed by that action ID; it must never infer an action from status alone. This preserves backend authority without leaking CLI terminology or English-only backend labels into the user experience. diff --git a/paperforge/plugin/CONTEXT.md b/paperforge/plugin/CONTEXT.md new file mode 100644 index 00000000..9a86ee9a --- /dev/null +++ b/paperforge/plugin/CONTEXT.md @@ -0,0 +1,137 @@ +# Plugin Control Center + +The control center presents PaperForge health, actions, and configuration using user-facing concepts rather than implementation vocabulary. + +## Language + +**Foundation**: +The persistent capability that makes PaperForge operational on this device, including its managed environment and required integration state. +_Avoid_: Installation, runtime + +**Installation**: +A one-time recovery action shown only when the Foundation does not yet exist. +_Avoid_: Installation module, installation page + +**Managed Runtime**: +A technical implementation detail of the Foundation, exposed only in advanced diagnostics or recovery. +_Avoid_: Runtime as a primary navigation destination + +**Module Detail**: +A contextual drill-down for one operational module, entered from Overview or Maintenance rather than a permanent top-level destination. +_Avoid_: Module Detail tab, defaulting detail navigation to Foundation + +**Setup Journey**: +A four-stage guided first-use experience: establish Foundation, connect Library, configure only the Optional Capabilities the user selects, then review and begin normal operation. +_Avoid_: Fixed empty steps for skipped capabilities, exposing all configuration and diagnostics during first use + +**Setup Completion**: +A durable transition from the Setup Journey to normal operation; later health failures never reverse it automatically. +_Avoid_: Inferring first-use state from current module health + +**Operational Baseline**: +The minimum completed setup: a ready Foundation and a connected literature library. Optional capabilities do not block Setup Completion. +_Avoid_: Requiring every capability before PaperForge can be used + +**Control Center Summary**: +The overall statement of whether the Operational Baseline is usable, followed by the count of enabled-module problems in Maintenance. Not Enabled optional capabilities never lower this summary. +_Avoid_: Aggregating the worst status across all modules, “all modules ready” as the usability requirement + +**Module Card**: +A navigation-only overview of one operational module, showing its Module Status, a plain-language summary, and at most one key metric. The whole card opens Module Detail and never executes an operation. +_Avoid_: Check buttons, repair actions, or competing click targets inside overview cards + +**Optional Capability**: +An independently enabled feature such as OCR, Smart Retrieval, or Agent Integration whose absence is explained but never blocks the Operational Baseline or enters Maintenance. +_Avoid_: Treating skipped optional setup as installation failure or unresolved maintenance + +**Operational Module**: +An independently understandable capability with its own availability, health, setup, and recovery lifecycle. The five modules are Foundation, Library, OCR, Smart Retrieval, and Agent Integration. +_Avoid_: Treating Maintenance or Help as modules + +**Agent Integration**: +The optional operational module that manages a target AI agent platform, deployment state, and the available system and user Skills. +_Avoid_: Hiding Agent Integration inside Foundation diagnostics, claiming a live connection when integration is file deployment + +**Maintenance**: +An actionable projection of enabled module problems that block use, fail a requested task, make an output unusable, or create material data risk. It contains no optimization suggestions and is not an independently healthy or unhealthy module. +_Avoid_: Maintenance module, feature recommendations, non-actionable quality warnings + +**Maintenance Action**: +A safe, reversible retry may run in place; configuration, scoped, batch, or destructive work navigates to the owning module or Operational Workspace with the affected context preserved. +_Avoid_: Blind destructive execution from Maintenance, routing every trivial retry through another page + +**Help**: +A task-oriented support destination for getting started, completing common workflows, resolving current user-visible problems, and copying a privacy-safe diagnostic report. +_Avoid_: Help module, capability status badges, raw log console as the default surface + +**Refresh Status**: +A single control-center action that re-evaluates every operational module; individual retry appears only for a module whose detection failed. +_Avoid_: Check, Check Status, Re-check, per-module refresh controls in normal states + +**Module Status**: +One of six user-facing states shared by every operational module: Checking, Ready, Not Enabled, Setup Required, Action Required, or Detection Failed. +_Avoid_: Pending, Unknown, stale as a visible status, or module-specific badge vocabularies + +**Capability Action**: +A backend-authorized operation identified by a stable action ID and safety metadata, with localized user-facing copy supplied by the plugin. +_Avoid_: Raw CLI commands as labels, backend-only English labels, or actions inferred from status + +**Module Detail Shell**: +The fixed cross-module frame containing return navigation, the five-module switcher, title, Module Status, primary action area, and advanced diagnostics entry. Each module owns a task-specific body inside this frame. +_Avoid_: Forcing identical body layouts or moving shell controls between modules + +**Module-Owned Configuration**: +Configuration is edited only within the operational module that owns its meaning: Zotero in Library, OCR credentials in OCR, vector settings in Memory, and platform plus Skills in Agent Integration. Foundation owns only the PaperForge environment. +_Avoid_: A duplicate all-settings section inside Foundation + +**Contextual Primary Action**: +The single operation currently recommended for a module; it is absent when the module is Ready and changes only with backend-authorized module state. +_Avoid_: Persistent maintenance buttons, action menus requiring users to diagnose the problem, or multiple competing primary actions + +**Library**: +The Zotero-connected literature corpus available to PaperForge, presented through connection state, corpus size, synchronization activity, and source configuration. +_Avoid_: Library Index as the primary user-facing name, database-centric health dashboards + +**OCR Module**: +The control-center surface for OCR availability, summary statistics, service configuration, and entry into paper-level OCR work. +_Avoid_: Embedding the full paper queue inside Settings + +**Operational Workspace**: +A full-width PaperForge view for high-volume, paper-level work such as filtering, selecting, and reprocessing OCR records. Module Detail links to it but does not duplicate it. +_Avoid_: Long operational tables and nested scrolling inside the Settings dialog + +**Smart Retrieval**: +The user-facing operational module that enables paper lookup, content discovery, paper navigation, and scoped evidence fetch across the Library. +_Avoid_: Memory Layer, Semantic Retrieval as the umbrella name, Vector Database + +**Support Diagnostic**: +A one-click, privacy-safe clipboard report containing versions, module status, stable error code, recent action, exit information, and a bounded error excerpt. It excludes secrets, document content, local identity, and raw absolute paths. +_Avoid_: Asking users to interpret diagnostics, copying raw logs, or requiring a preview step before routine support handoff + +**User-visible Problem**: +A plain-language message structured as what happened, what is and is not affected, and the single next step. A Support Diagnostic is adjacent but never required for understanding. +_Avoid_: Bare failure labels, raw exception text, or error codes as explanation + +**Module Activity**: +Visible work in progress, presented separately from Module Status with task label, bounded progress, affected scope, and a safe stop control when supported. Activity enters Maintenance only after a terminal failure. +_Avoid_: Replacing availability with “Running”, treating in-progress work as unresolved maintenance, notification-only long tasks + +**Impact Confirmation**: +A confirmation for high-impact work that names the affected scope, replaced derived outputs, preserved source and user data, interruptibility, and a concrete action verb. +_Avoid_: Generic “Are you sure?”, technical destructive labels without preservation facts, typed confirmation for regenerable artifacts + +**Configuration Summary**: +A safe, read-only presentation of module-owned settings with an explicit Change entry. Editing is local to one configuration group and ends with Cancel or Save and Verify; credentials show configured state, never plaintext. +_Avoid_: Always-editable settings walls, saving unvalidated drafts on every keystroke, repopulating stored secrets + +**Navigation Memory**: +The persisted last top-level destination or selected operational module. Reopening refreshes current state and never restores drafts, selections, confirmations, diagnostics disclosure, scroll position, or other transient interaction state. +_Avoid_: Always reopening at Overview, restoring stale or sensitive interaction state + +**Interface Language**: +The plugin presentation language, inherited from Obsidian by default with an explicit PaperForge override. Backend reason and action IDs are localized by the plugin rather than displayed as backend prose. +_Avoid_: Mixed-language surfaces, raw backend labels, forcing a language choice during first use + +**Last Known Status**: +The most recent successful module result shown immediately while a background refresh runs. Refresh activity is separate; on Detection Failed, the last successful status remains explicitly timestamped as historical reference. +_Avoid_: Converting stale cache into Not Enabled or Detection Failed before a refresh attempt, blanking every card on open diff --git a/paperforge/plugin/DESIGN.md b/paperforge/plugin/DESIGN.md new file mode 100644 index 00000000..b82ad434 --- /dev/null +++ b/paperforge/plugin/DESIGN.md @@ -0,0 +1,191 @@ +# PaperForge Plugin Design System + +## 1. Atmosphere & Identity + +PaperForge is an Obsidian-native, quiet professional control center: calm when work is healthy, explicit when the user must act, and technical only when support needs evidence. Its signature is progressive clarity — every surface leads with a plain-language outcome, while implementation detail stays out of the reading path. + +## 2. Color + +PaperForge inherits the active Obsidian theme. It does not define independent light/dark hex palettes. + +| Role | Obsidian token | Usage | +| ----------------- | ------------------------------------ | ---------------------------------------- | +| Primary surface | `--background-primary` | Page and card background | +| Secondary surface | `--background-secondary` | Grouped sections, historical status | +| Hover surface | `--background-modifier-hover` | Hovered rows and navigation | +| Default border | `--background-modifier-border` | Cards, dividers, inputs | +| Hover border | `--background-modifier-border-hover` | Hovered clickable cards | +| Primary text | `--text-normal` | Headings and body | +| Secondary text | `--text-muted` | Explanations and metadata | +| Tertiary text | `--text-faint` | Nonessential timestamps only | +| Accent | `--interactive-accent` | Primary action, active navigation, focus | +| Accent text | `--text-on-accent` | Text on accent surfaces | +| Success | `--text-success` | Ready state only | +| Warning | `--text-warning` | Setup Required and Action Required | +| Error | `--text-error` | Detection Failed and destructive effects | + +Rules: + +- Color communicates status or interactivity; it is never decorative. +- `Not Enabled` is neutral, not warning-colored. +- `Checking` uses muted text plus activity, not a warning color. +- Status color is always paired with text; color is never the only signal. +- Raw RGB or hex values are prohibited. Alpha tints use `color-mix()` with an Obsidian semantic token. + +## 3. Typography + +PaperForge inherits Obsidian font families and UI scale. + +| Level | Token / value | Weight | Usage | +| ------------------ | ---------------------------------- | ----------------- | ----------------------------------------------- | +| Page heading | `--font-ui-large` | `--font-semibold` | Overview, Maintenance, Help | +| Module heading | `18px` | `--font-semibold` | Module Detail title | +| Section heading | `--font-ui-medium` | `--font-semibold` | Module body sections | +| Body | `--font-ui-small` | normal | Explanations and configuration summaries | +| Metadata | `12px` | normal | Counts, timestamps, secondary facts | +| Badge | `11px` | medium | Six-state labels | +| Diagnostic excerpt | `--font-monospace-theme` at `12px` | normal | Copied or explicitly revealed support data only | + +Rules: + +- User-facing content uses Obsidian’s interface font; technical excerpts alone use monospace. +- Body copy is never smaller than Obsidian’s configured small UI font. +- Headings use sentence case. Uppercase eyebrow labels are removed. +- Error codes and raw commands never serve as headings or explanatory copy. + +## 4. Spacing & Layout + +### Base unit + +All PaperForge spacing is a multiple of 4px. + +| Token | Value | Usage | +| --------- | ----: | -------------------------------- | +| `space-1` | 4px | Icon-to-label, compact metadata | +| `space-2` | 8px | Inline groups and list gaps | +| `space-3` | 12px | Compact panel padding | +| `space-4` | 16px | Card padding and section gaps | +| `space-5` | 20px | Summary panel horizontal padding | +| `space-6` | 24px | Major section separation | +| `space-8` | 32px | Page-level separation | + +### Layout + +- Settings content uses the host-provided width; PaperForge does not impose a competing page width. +- Overview module cards use two columns above a 620px container width and one column at or below 620px. +- Module Detail uses five visible module tabs above 620px and one native module select at or below 620px. +- Forms and maintenance items become one column at or below 620px. +- Nested vertical scrolling inside Settings is prohibited; long operational tables open in a full-width PaperForge workspace. + +## 5. Components + +### Control Center Navigation + +- **Structure**: three top-level tabs — Overview, Maintenance, Help. +- **States**: default, hover, active, focus-visible. +- **Accessibility**: tab semantics, arrow-key movement, Enter/Space activation, visible focus. +- **Rule**: Module Detail is contextual and never appears as a top-level tab. + +### Control Center Summary + +- **Structure**: baseline conclusion, one supporting sentence, maintenance count, last-updated state, global Refresh Status. +- **Variants**: baseline ready, baseline blocked, refreshing, refresh failed with last-known result. +- **Rule**: Not Enabled optional capabilities do not lower the baseline conclusion. + +### Module Card + +- **Structure**: module name, six-state badge, one plain-language sentence, at most one key metric, navigation affordance. +- **Interaction**: the entire card opens Module Detail; no operation executes from the card. +- **States**: default, hover, active, focus-visible, refreshing, detection failed. +- **Accessibility**: one keyboard-focusable target with an accessible name containing module and status. + +### Module Status Badge + +- **Variants**: Checking, Ready, Not Enabled, Setup Required, Action Required, Detection Failed. +- **Rule**: badge wording is identical across modules; reason-specific detail belongs in body copy. +- **Accessibility**: text label is mandatory; status changes use polite live announcements. + +### Module Detail Shell + +- **Structure**: return navigation, responsive five-module switcher, module title, Module Status, plain-language summary, Contextual Primary Action area, custom module body, Support Diagnostic entry. +- **Responsive states**: tab list above 620px; native select at or below 620px. +- **Navigation memory**: persist only top-level destination or selected module; refresh state on reopen. +- **Accessibility**: restore focus to the source card or maintenance item on return. + +### Contextual Primary Action + +- **Structure**: one backend-authorized action localized by stable action ID. +- **States**: absent when Ready, enabled, hover, active, focus-visible, disabled while starting, running in Module Activity, terminal error. +- **Rule**: multiple competing primary actions and generic action menus are prohibited. + +### Module Activity + +- **Structure**: task label, bounded current/total progress when known, affected scope, safe Stop when supported. +- **Rule**: activity is separate from Module Status and does not enter Maintenance until terminal failure. +- **Accessibility**: `role="progressbar"` for bounded progress; polite live updates; Stop always remains reachable. + +### Configuration Summary + +- **Structure**: safe read-only value or configured state, explanation, explicit Change control. +- **Edit state**: local form with Cancel and Save and Verify. +- **Credentials**: show configured/not configured only; never repopulate plaintext. +- **Error state**: keep the verified saved value while explaining why the draft failed validation. + +### User-visible Problem + +- **Structure**: what happened, what is and is not affected, one next step, Copy Diagnostic Information. +- **Rule**: raw stderr, reason codes, paths, and exception text are excluded from the user explanation. +- **Accessibility**: error heading receives focus after a failed foreground action; copied state is announced. + +### Maintenance Item + +- **Structure**: owning module, User-visible Problem, affected scope, one Maintenance Action. +- **Eligibility**: only enabled-module blockers, failed requested tasks, unusable outputs, or material data risk. +- **Excluded**: optional modules never enabled, optimization suggestions, internal OCR quality signals, stale cache alone. +- **Interaction**: safe retry may run in place; configuration, scoped, batch, or destructive work navigates with context. + +### Impact Confirmation + +- **Structure**: affected count/scope, replaced derived outputs, preserved sources and user data, interruptibility, Cancel, concrete action verb. +- **Rule**: generic “Are you sure?” and typed confirmation for regenerable artifacts are prohibited. +- **Accessibility**: focus trap, Escape cancellation, initial focus on Cancel, restore focus to invoker. + +### Setup Journey + +- **Structure**: four dynamic stages — Foundation, Library, selected Optional Capabilities, review and begin. +- **States**: checking, ready to continue, validation failed, operation running, optional capability skipped, complete. +- **Rule**: Setup Completion never reverses automatically because of later health failures. + +## 6. Motion & Interaction + +| Type | Duration | Easing | Usage | +| -------- | -------: | ----------- | -------------------------------------- | +| Micro | 120ms | ease-out | Hover, press, focus surface response | +| Standard | 180ms | ease-in-out | Disclosure and module-body replacement | + +Rules: + +- Motion is subordinate to Obsidian and limited to opacity and transform. +- Progress uses transform-based fill where practical. +- No entrance choreography, decorative animation, or layout-property animation. +- `prefers-reduced-motion: reduce` disables nonessential transitions. +- A visible hover, active, and focus-visible state is required for every interactive element. + +## 7. Depth & Surface + +**Strategy: borders-only.** PaperForge uses Obsidian surfaces and borders, without decorative shadows. + +| Surface | Treatment | +| --------------- | ----------------------------------------------------------- | +| Page | `--background-primary`, no border | +| Clickable card | primary surface, 1px default border, host radius | +| Grouped section | secondary surface or a top divider, not a nested card stack | +| Status tint | semantic text color mixed at low opacity with transparency | +| Modal | Obsidian-owned modal surface and elevation | + +Rules: + +- Avoid cards inside cards. +- Use spacing before adding a divider; use a divider before adding another container. +- PaperForge does not override Obsidian modal shadows or global radii. +- Current “Vercel-inspired” styling, inline CSS duplication, raw emoji warning icons, overview action buttons, and permanently visible technical diagnostics are migration targets, not accepted primitives. diff --git a/project/current/control-center-ux-redesign.md b/project/current/control-center-ux-redesign.md new file mode 100644 index 00000000..a55aeb22 --- /dev/null +++ b/project/current/control-center-ux-redesign.md @@ -0,0 +1,361 @@ +# PaperForge Control Center UX Redesign + +**Status:** Approved design baseline +**Date:** 2026-07-19 +**Scope:** Obsidian plugin setup, control center, operational module details, maintenance, help, and OCR workspace entry +**Design system:** [`paperforge/plugin/DESIGN.md`](../../paperforge/plugin/DESIGN.md) +**Domain language:** [`paperforge/plugin/CONTEXT.md`](../../paperforge/plugin/CONTEXT.md) + +## 1. Problem + +The current settings surface exposes implementation concepts and duplicate actions without a stable user model. “Installation” acts as a permanent module while also containing runtime, Python, Zotero, Agent, and Skills configuration. `Install`, `Sync Runtime`, `Check`, `Check Status`, `Retry`, `Update Runtime`, and `Rollback` overlap without telling the user which outcome each produces. Module Detail is a top-level destination but the Installation renderer exposes only its own selector, while Library, OCR, and Memory use a separate four-module shell. Cached probe expiry is rendered as “Pending/待接入,” making a healthy installation appear absent. + +The redesign must make the control center understandable without knowledge of Python, runtime slots, probe envelopes, schema versions, or CLI commands. + +## 2. Product model + +### 2.1 Operational baseline + +PaperForge is usable when: + +1. Foundation is ready. +2. Library is connected. + +OCR, Smart Retrieval, and Agent Integration are optional. A capability the user never enabled does not block Setup Completion, lower the overall summary, or enter Maintenance. + +### 2.2 Operational modules + +The five modules are: + +1. **Foundation** — the PaperForge environment on this device. +2. **Library** — Zotero connection and literature synchronization. +3. **OCR** — OCR availability, summary, service configuration, and entry to paper-level work. +4. **Smart Retrieval** — retrieval coverage, freshness, and service configuration. +5. **Agent Integration** — target agent platform, deployment state, and Skills management. + +Maintenance and Help are destinations, not modules. + +### 2.3 Status vocabulary + +Every module maps backend facts into exactly one user status: + +| User status | Meaning | Default user treatment | +|---|---|---| +| Checking | A refresh is running | Preserve Last Known Status and show separate refresh activity | +| Ready | Capability is usable | Quiet; no Contextual Primary Action | +| Not Enabled | Optional capability was not selected | Neutral explanation and an Enable entry in detail only | +| Setup Required | Required information is missing | Explain the missing user choice and offer one setup action | +| Action Required | Enabled capability has a blocking, failed, unusable, or materially risky condition | Explain impact and offer one backend-authorized action | +| Detection Failed | Current status cannot be confirmed | Show Retry and a timestamped Last Known Status when available | + +`unknown`, `stale`, TTL expiry, internal quality color, and raw reason code are not user statuses. + +### 2.4 Action ownership + +The backend owns: + +- stable action ID; +- exact executable command and scope; +- availability; +- destructive flag and preservation facts; +- confirmation requirement. + +The plugin owns: + +- localized label and explanation; +- visual priority; +- whether a safe action runs in place or routes to context; +- focus, progress, and completion feedback. + +The plugin must not infer an action from status alone. Backend labels and CLI commands must not be displayed as user copy. + +## 3. Information architecture + +```text +First use +└─ Setup Journey + ├─ 1 Foundation + ├─ 2 Connect Library + ├─ 3 Selected Optional Capabilities + └─ 4 Review and Begin + +Normal Control Center +├─ Overview +│ ├─ Control Center Summary +│ └─ Five Module Cards +├─ Maintenance +└─ Help + +Module Detail — contextual drill-down +├─ Foundation +├─ Library +├─ OCR ──→ full-width OCR Operational Workspace +├─ Smart Retrieval +└─ Agent Integration +``` + +Module Detail is not a top-level tab. It is entered from a Module Card or Maintenance Action. The fixed detail shell contains return navigation, responsive module switching, title, status, summary, primary action area, and Support Diagnostic entry. Bodies are module-specific. + +The last top-level destination or selected module is persisted. Reopening refreshes current state but does not restore drafts, selections, confirmations, disclosure state, or scroll position. + +## 4. Screen specifications + +### 4.1 Setup Journey + +The Setup Journey appears only before durable Setup Completion. + +1. **Foundation:** automatically check and establish PaperForge. Do not expose Runtime or Python unless recovery fails. +2. **Connect Library:** configure and validate Zotero plus safe default vault locations. +3. **Optional Capabilities:** let the user select OCR, Smart Retrieval, and Agent Integration; render configuration only for selected capabilities. +4. **Review and Begin:** summarize what is ready, what was intentionally skipped, and where skipped capabilities can be enabled later. + +Later module health failures never reopen the Setup Journey automatically. Module-owned Change actions handle reconfiguration. + +### 4.2 Overview + +Header: + +- overall statement based on Operational Baseline; +- count of Maintenance items for enabled modules; +- last update or refresh activity; +- one global **Refresh Status** action. + +Module Cards: + +- Foundation, Library, OCR, Smart Retrieval, Agent Integration; +- six-state badge; +- one plain-language summary; +- at most one key metric; +- full-card navigation to Module Detail; +- no Check, repair, configuration, destructive, or secondary action buttons. + +On open, show Last Known Status immediately and refresh in the background. Never replace stale cached data with Not Enabled or Detection Failed before attempting refresh. + +### 4.3 Foundation Detail + +Default body: + +- PaperForge version and compatibility in user language; +- current environment availability; +- update or recovery outcome when relevant. + +Action rules: + +| Condition | Contextual Primary Action | +|---|---| +| Ready | None | +| Foundation absent | Install PaperForge | +| Plugin/backend version mismatch | Complete Update | +| Environment damaged | Repair PaperForge | +| Detection failed | Retry | + +Runtime slot, Python executable, raw path, rollback, and support logs are excluded from default content. Rollback remains an advanced recovery action and must target the previous runtime identity, not merely a matching version number. + +### 4.4 Library Detail + +A connection and synchronization workbench: + +- Zotero connection state; +- corpus size; +- last synchronization and its result; +- current sync activity and progress; +- source configuration summary; +- an explicit Change flow for Zotero path and synchronization scope; +- a normal-use Sync Literature action inside the sync section, not as a health warning. + +Zotero configuration exists only here and in the relevant Setup Journey stage. + +### 4.5 OCR Detail + +Settings body: + +- OCR availability; +- usable, pending, running, and unusable result counts; +- current OCR activity; +- OCR provider and credential Configuration Summary; +- entry to the full-width OCR Operational Workspace. + +The full-width workspace owns: + +- all paper-level OCR records; +- filtering and sorting; +- selection and scope preview; +- paper-level failure explanation; +- batch reprocessing; +- live progress and cooperative stop. + +An OCR result enters Maintenance only when it cannot support reading or retrieval and a concrete recovery action is likely to restore or improve it. Internal quality scores, ordinary OCR imperfections, and non-actionable low-confidence signals remain internal. + +### 4.6 Smart Retrieval Detail + +The body focuses on: + +- retrievable papers versus Library total; +- coverage percentage; +- last successful build/update; +- current build activity; +- model/provider Configuration Summary; +- one build/update action only when backend facts authorize it. + +Schema, vector dimensions, database paths, manifest internals, and “Memory Layer” terminology are excluded from user copy. + +### 4.7 Agent Integration Detail + +The body contains: + +- selected agent platform; +- target deployment location as a safe summary; +- deployment state: Not Configured, Configured, Synchronized, or Synchronization Required; +- system and user Skills counts; +- Skills search, grouping, and enable/disable controls; +- Sync to Agent only when content drift exists. + +Do not claim a live connection when integration is file deployment. + +### 4.8 Maintenance + +Maintenance contains only enabled-module problems that: + +- block use; +- fail a requested task; +- make an output unusable; or +- create material data risk; + +and have a concrete backend-authorized resolution. + +Every item shows: + +1. what happened; +2. what is and is not affected; +3. affected scope; +4. one next step. + +Safe reversible retries may execute in place. Configuration, scoped, batch, or destructive work navigates to the owning Module Detail or Operational Workspace with context preserved. Optional modules never enabled, optimization suggestions, stale cache alone, and internal OCR quality signals are excluded. Successful resolution removes the item automatically. + +### 4.9 Help + +Help provides: + +- getting-started entries for Library, OCR, Smart Retrieval, and Agent Integration; +- common task guidance; +- guidance for current User-visible Problems; +- one-click Copy Diagnostic Information; +- links to deeper documentation and issue reporting. + +Help has no capability status badge. + +## 5. User-visible problems and support diagnostics + +All user-facing failures use: + +1. **What happened** — direct, nontechnical title. +2. **Impact** — what cannot currently happen and what data/capability remains safe. +3. **Next step** — one concrete action. + +**Copy Diagnostic Information** produces a privacy-safe clipboard report containing: + +- timestamp; +- plugin and backend versions; +- module and internal state; +- stable reason/action IDs; +- recent attempted action; +- exit code or process outcome; +- bounded error excerpt. + +It excludes secrets, environment variables containing credentials, document content, local username, and raw absolute paths. Paths are represented as logical locations. Copy completes in one action and announces success. + +## 6. Activity and impact confirmation + +Module Activity is separate from Module Status. Running work shows task name, progress or indeterminate activity, scope, and Stop when supported. Running work does not enter Maintenance; terminal failure may. + +High-impact confirmation states: + +- affected object count and scope; +- derived output that will be replaced; +- source and user data that remain preserved; +- whether work can be stopped; +- concrete confirmation verb. + +Generic “Are you sure?” and raw backend destructive text are prohibited. + +## 7. Responsive and accessibility contract + +- Use Obsidian theme variables and native controls. +- Five module tabs appear above 620px container width; a native module select replaces them at or below 620px. +- Overview is two columns above 620px and one column below. +- No nested vertical scrolling or horizontal overflow in Settings. +- Every interaction supports keyboard activation and visible focus. +- Tab semantics and arrow-key behavior apply to top navigation and wide module switching. +- Focus returns to the originating card or maintenance item after back navigation or modal closure. +- Status and copied feedback use appropriate live regions. +- Impact confirmation traps focus, starts on Cancel, supports Escape, and restores focus. +- Reduced-motion preferences disable nonessential transitions. +- Status never relies on color alone. + +## 8. Acceptance matrix + +| Surface | Required observable contract | +|---|---| +| First open, incomplete | Four-stage Setup Journey; optional capabilities can be skipped; completion persists independently of health | +| Reopen, completed | Restore last top-level destination or selected module; refresh state; no draft/selection restoration | +| Overview | Three top-level destinations; five navigation-only Module Cards; one global refresh; baseline summary ignores Not Enabled optional modules | +| Refreshing | Last Known Status remains visible with separate activity; no false Pending/Not Enabled transition | +| Refresh failed | Detection Failed plus Retry and timestamped last successful state; plain-language impact and diagnostic copy | +| Detail navigation | No top-level Module Detail tab; fixed five-module shell; responsive select at narrow width; correct return context | +| Foundation Ready | No primary action and no Runtime/Python terminology in default body | +| Foundation mismatch | One Complete Update action; successful update refreshes Foundation and Help | +| Library | Connection, corpus, sync result/activity, and module-owned Zotero configuration appear in one workbench | +| OCR | Settings summary links to full workspace; only unusable actionable outcomes enter Maintenance | +| Smart Retrieval | Coverage and freshness are primary; Memory/vector/schema language remains internal | +| Agent Integration | Platform, deployment state, Skills search/group/toggles; no false live-connection wording | +| Maintenance empty | Clear no-action-needed state and no module-health fiction | +| Maintenance populated | Only qualifying problems; one action each; safe retry inline; complex work routes with context | +| Help | Task guidance, current problem guidance, one-click privacy-safe diagnostic, no health badge | +| Running work | Status and activity both visible; progress announced; Stop reachable; no Maintenance item until terminal failure | +| High-impact action | Scope, replacement, preservation, interruptibility, concrete confirm verb, focus restoration | +| Localization | Obsidian language by default, explicit override, no raw backend English labels in localized UI | +| Visual QA | Obsidian light/dark themes, 730px and 620px-adjacent widths, hover/focus/disabled/loading/empty/error states, no overflow | + +## 9. Dependency-ordered implementation slices + +Each slice must be one agent-ready issue and one authoritative worktree under the Ask Matt lifecycle. + +1. **Capability presentation contract** + Add stable action IDs, six-state mapping inputs, user-impact fields, preservation facts, and Maintenance eligibility. Separate internal OCR quality from User-visible OCR Failure. No UI redesign depends on backend prose after this slice. + +2. **Shared control-center state and primitives** + Implement Last Known Status refresh behavior, global Refresh Status, Support Diagnostic redaction, navigation memory, and reusable design-system primitives with a state showcase. + +3. **Information architecture and Overview** + Remove Module Detail as a top-level tab; render Overview/Maintenance/Help; replace six mixed cards with five navigation-only module cards and baseline summary. + +4. **Setup Journey and Foundation** + Implement durable Setup Completion, four dynamic stages, Foundation user model, one contextual action, and advanced recovery separation. Correct rollback to target previous runtime identity. + +5. **Library module** + Build the connection/synchronization workbench and move Zotero configuration ownership out of Foundation. + +6. **Smart Retrieval module** + Replace Memory user language; render coverage/update body; move provider configuration ownership; keep technical index facts internal. + +7. **Agent Integration module** + Add the fifth module contract, platform/deployment state, module-owned platform configuration, and Skills management. + +8. **Maintenance and Help** + Enforce qualifying-problem-only projection, contextual routing, task support, plain-language failure anatomy, and one-click Support Diagnostic. + +9. **OCR module and Operational Workspace** + Reduce Settings OCR detail to summary/configuration/workspace entry; build full-width paper-level filtering, selection, batch actions, progress, stop, and Impact Confirmation. + +10. **Cutover and consistency cleanup** + Delete legacy Installation/Runtime wording, duplicate Sync/Check controls, old four-module selector, raw backend labels, stale-as-pending mapping, inline duplicated styles, and obsolete tests. Run full Obsidian light/dark and responsive accessibility verification. + +## 10. Non-goals + +- A new visual brand independent of Obsidian. +- A general system-monitoring dashboard. +- Exposing raw probe envelopes or CLI commands to ordinary users. +- Treating optional capability adoption as maintenance debt. +- Showing every internal OCR quality concern. +- Embedding large operational tables inside Settings. +- Reintroducing a global health-derived `setup_complete` boolean. diff --git a/project/current/ocr-v2-active-queue.md b/project/current/ocr-v2-active-queue.md index c46e84f9..3ef5d9cf 100644 --- a/project/current/ocr-v2-active-queue.md +++ b/project/current/ocr-v2-active-queue.md @@ -1,5 +1,5 @@ # OCR-v2 Active Queue -> Status: OCR-v2 is stable; all eight PRD #74 child issues (#75–#80) are implemented and verified; #81 Release N+1 owner cutover is next. +> Status: OCR-v2 is stable; PRD #74 issues #75–#82 are implemented. Live use exposed a missing-probe release package and a superseded control-center UX contract; publish the backend package first, then route the approved redesign through Ask Matt. > Last updated: 2026-07-19 ## Current checkpoint @@ -13,8 +13,8 @@ - Cache refresh preserves the backend manifest (was overwriting it with empty on each refresh). - Source Corpus data remains authoritative and was not modified during verification. Only the deployed plugin bundle and disposable maintenance cache were refreshed. - [Current-contract audit](https://github.com/LLLin000/PaperForge/issues/66#issuecomment-4968837257) identified the migration boundary: preserve durable OCR/SQLite truth and recovery actions; replace global setup state, duplicate runtime/config resolution, and freshness-free snapshots. -- [Obsidian-native research](https://github.com/LLLin000/PaperForge/issues/67#issuecomment-4970653461) preserves the six-module IA, progressive setup, capability-gated commands, and minimal transient status chrome. -- [Desktop runtime/recovery research](https://github.com/LLLin000/PaperForge/issues/68#issuecomment-4970660288) establishes module-scoped repair, compatibility-gated updates, local redacted diagnostics, and user-reviewed issue drafts. +- The approved replacement is `control-center-ux-redesign.md`: five operational modules, three top-level destinations, contextual Module Detail, progressive setup, user-problem-only Maintenance, and Obsidian-native presentation. +- The plugin design system is now explicit in `paperforge/plugin/DESIGN.md`; product language is defined in `paperforge/plugin/CONTEXT.md`. - **[#69](https://github.com/LLLin000/PaperForge/issues/69) resolved** at `issuecomment-4971161072`: orthogonal availability/activity/attention axes, 6-state capability ordinal, 12 canonical verbs, backend-owned severity and primary actions, maintenance projection. - **[#70](https://github.com/LLLin000/PaperForge/issues/70) resolved** at `issuecomment-4971239398`: plugin-managed immutable runtime slots, system-Python bootstrap with validated-triplet fallback, single `active-runtime.json` pointer, `ManagedRuntime` class with `current()`/`status()`/`ensure()`, fail-closed command resolution. @@ -24,16 +24,17 @@ - **[#74](https://github.com/LLLin000/PaperForge/issues/74) published**: split into eight agent-ready issues (#75–#82) with native dependencies. - **[#75](https://github.com/LLLin000/PaperForge/issues/75) implemented and reviewed**: bare/headless/modular setup share `SetupPlan`; schema-v2 `vault_config` wins; v1 path keys are warned read fallback; all configured directories are forwarded; required failures return non-zero. - **[#76](https://github.com/LLLin000/PaperForge/issues/76) implemented**: schema-v1 Installation/Help probes flow through the six-module Overview; persisted malformed/stale envelopes fail closed; backend set_config/update actions route to setup. -- **Wayfinder navigation refinement approved and implemented**: `概览 / 模块详情 / 维护 / 帮助` shell live across #77/#78/#80. Installation owns Agent platform/Skills under Agent 集成; no empty placeholder detail pages. All six modules (Installation, Library, OCR, Memory, Maintenance, Help) are real probes. +- **Current navigation is superseded**: the live `概览 / 模块详情 / 维护 / 帮助` shell and Installation-owned Agent/Skills are retained only until the redesign issues land. The approved target removes top-level Module Detail, makes Foundation the persistent environment module, and makes Agent Integration a fifth operational module. - **[#77](https://github.com/LLLin000/PaperForge/issues/77) implemented**: Managed Runtime lifecycle with immutable slots, synchronous fail-closed `current`, probed `status`, install/repair/update/rollback/cancel/retention, managed-first dispatch, Release-N fallback, four-destination navigation shell. Verification: 192 focused + 289 full tests; typecheck/build clean. Merged to `master`. - **[#78](https://github.com/LLLin000/PaperForge/issues/78) implemented**: real Library/OCR/Memory capability probes with module-detail-navigation, installation-navigation, and capability-state views. Python owns capability facts; TypeScript exact allowlist/fail-closed rendering. Verification: 58 backend + 171 plugin tests; typecheck/build clean; Obsidian smoke verified. - **[#79](https://github.com/LLLin000/PaperForge/issues/79) implemented**: SecretStorage for capability secrets. Backend-focused gate passes; plugin full suite passes; typecheck/build clean. - **[#80](https://github.com/LLLin000/PaperForge/issues/80) implemented**: Maintenance probe with backend-derived actionable-only rows, privacy-safe local issue drafts, and accessible destructive confirmation. Backend owns exact actions from `probe maintenance --json`; frontend renders via derived VerbModel with primary null for quality-ok items. Verification: backend focused gate 77/77; plugin full suite 381/382 (pre-existing capability-state test expecting help.stale but receiving help.invalid_response); typecheck/build clean; production bundle 264.4KB; Obsidian 1.12.7 smoke 730/768: entry focus, actionable-only rows, keyboard Enter, accessible destructive confirmation with exact backend effect, focus trap/restoration, owned inert cleanup, redacted editable issue draft, no token input/auto-open, explicit GitHub open only, URL re-redaction, no horizontal overflow. +- **Literature-hub deployment recovered, then safely rolled back**: duplicate plugin discovery and plaintext credentials remain fixed. The active pointer now targets the probe-capable `v1.5.15` slot because the published `1.5.15` installed into `v1.5.15_build2` lacks `paperforge probe`; do not update/repair until a probe-capable package is published and clean-venv verified. ## Verification status - Focused Python OCR paths: **99 passed, 1 Windows SIGINT test skipped, 1 unrelated empty-result regression deselected**. -- Plugin: **93 passed**; TypeScript check and production build passed. +- Plugin: **384/384 passed**; TypeScript check and production build passed (**259.3KB**). - Maintenance regression tests: **19/19 passed** (canonical action routing, confirmation gate, cache manifest preservation). - Live Obsidian verification: PaperForge 1.5.15 loaded without captured errors; maintenance rendered **734 All** rows and **700 Recommended** rows from the canonical backend flag. - Live progress-state harness showed the floating progress bar, current key, Stop control, and disabled row actions. @@ -46,6 +47,7 @@ - Issue #80 verification: **backend focused gate 77/77; plugin full suite 381/382** (only pre-existing capability-state test expecting help.stale but receiving help.invalid_response); typecheck/build clean; production bundle 264.4KB; real Obsidian 1.12.7 smoke at 730 and 768 confirmed all acceptance criteria. - Issue #75 verification: **61/61 focused tests passed**; independent review returned **Spec PASS / Quality APPROVED**. - Issue #76 verification: **21/21 backend probe tests and 169/169 plugin tests passed**; TypeScript check and production build passed; live Obsidian stale-cache/action-label smoke test and independent review passed. +- Live rollback verification: active Runtime is `windows-x64\\v1.5.15\\venv\\Scripts\\python.exe`; Installation and Help are ready, Library/OCR/Memory return real probe envelopes, Maintenance returns three backend-derived items, and Obsidian captured no errors. - No production plugin code was modified during prototype work. - The repository-wide Python suite remains blocked during collection by the pre-existing `test_pr9a_resume_rebuild.py` import of removed `_assert_collections_healthy`. ## Frontier @@ -59,11 +61,13 @@ - [x] Expose Library, OCR, Memory capability tracers ([#78](https://github.com/LLLin000/PaperForge/issues/78)). - [x] Implement SecretStorage for capability secrets ([#79](https://github.com/LLLin000/PaperForge/issues/79)). - [x] Implement Maintenance probe with backend-derived rows, privacy-safe draft, destructive confirmation ([#80](https://github.com/LLLin000/PaperForge/issues/80)). -- [ ] Implement Release N+1 owner cutover ([#81](https://github.com/LLLin000/PaperForge/issues/81)). +- [x] Implement Release N+1 owner cutover ([#81](https://github.com/LLLin000/PaperForge/issues/81)) and Release N+2 cutover ([#82](https://github.com/LLLin000/PaperForge/issues/82)). +- [x] Grill and domain-model the replacement control-center UX; write `DESIGN.md`, glossary, ADR, full screen specification, acceptance matrix, and dependency-ordered slices. +- [ ] Publish a backend package containing `paperforge probe`; remove the Literature-hub editable runtime only after package-level verification. +- [ ] Route `control-center-ux-redesign.md` through Ask Matt into one parent PRD and agent-ready issues; begin with the capability presentation contract after the package release. ## Deferred -- Vector rebuild UX (PRD Slice 1): deferred. -- Memory/global maintenance cleanup (PRD Slice 3): deferred. +- Vector rebuild UX and Memory/global maintenance naming are superseded by the approved Smart Retrieval and user-problem-only Maintenance design; implementation remains pending in the new slices. - OCR ETA and real-time per-row mutation: out of scope for the completed OCR slice. -- Release N+2 cutover shim deletion remains blocked by its native issue dependency (#82). +- Compatibility naming cleanup remains deferred post-release.