Files
kandev/docs/plans/settings-storage-tabs/plan.md
T

14 KiB

created, status, requirements, system_design, legacy_specs
created status requirements system_design legacy_specs
2026-09-15 completed
REQ-UI-SETTINGS-HEADER-TABS-001
REQ-UI-SETTINGS-HEADER-TABS-002
REQ-SYSTEM-PAGE-DATA-STORAGE-PAGES-001
REQ-SYSTEM-PAGE-DATA-STORAGE-PAGES-002
REQ-SYSTEM-PAGE-DATA-STORAGE-PAGES-003
REQ-SYSTEM-PAGE-DATA-STORAGE-PAGES-004
../../specs/ui/system-design/settings-header-tabs.md
../../specs/system-page/system-design/system-data-storage-pages.md

Implementation Plan: Settings Header Tabs and Storage UX

Overview

Create reusable tabs inside the existing page header, then reorganize Data & Logs and Storage. Improve retention controls, status, temporary-file explanations, and compaction width. Implement sequentially: shared navigation, retention presentation, remaining cards, then public documentation. The user explicitly selected right-aligned desktop tabs and phone tabs below the description. Implementation is tracked by the work orders below without delegation.

Scope

In scope

  • Shared SettingsTabs and optional tabs in the existing SettingsPageHeader.
  • Data & Logs: Database and Logs. Storage: Host and Office retention.
  • URL selection, legacy/search/health destinations, and preserved save lifecycles.
  • Compact desktop controls, touch help drawers, translated product labels, and accurate retention status.
  • Full-row message compaction and clear temporary-file copy.
  • Focused desktop/phone tests and public maintenance instructions.

Out of scope

  • New retention policy, database migrations, cleanup eligibility, APIs, or background jobs.
  • Persisted sweep history, predicted next cleanup, or a new manual Office sweep action.
  • Migration of unrelated settings pages, global tab restyling, or new runtime flags.
  • Product screenshot recapture as a separate media project. Existing stale screenshots can be removed or relabeled without claiming a new capture.

Technical approach

Use the UI design for shared controls and state lifetime. Use the system-page design for domain composition and status derivation. The ADR records the user-selected header placement and replaces the old no-tabs constraint.

Existing SettingsPageHeader already has title, description, and actions. Extend it instead of adding another header. SystemRouteShell/SystemPageShell expose the optional tabs slot. Each consuming page owns one Tabs root. Use the existing router and query subscriptions. Tab clicks replace the current history entry and retain forms. Guard bypass applies only to validated same-path tab replacements. Page exit still uses the save coordinator. Keep one target registration per discovery ID. Activate a hidden target's tab before focus/highlight. Office health fix links change, but health identifiers and retention wire contracts do not.

ASCII UI preview

Structure is required; spacing, example values, and exact copy are illustrative. All text inside UI code must use localization. Examples below use ASCII (i) for the information icon.

UI-01: Header tabs, desktop

Entry: Settings > Data & Logs or Settings > Storage. State: selected tab, loaded content. Before: the header has no tabs; Data & Logs stacks Database, Office retention, compaction, backups, and Logs. After:

Data & Logs                              [ Database | Logs ]
Database statistics, backups, and server logs.
------------------------------------------------------------
[ Database status and actions                             ]
[ Message compaction: full content width                  ]
[ Backups                                                ]

Storage                           [ Host | Office retention ]
Manage disk usage and history retention.
------------------------------------------------------------
[ Content of the selected tab                            ]

Tabs belong inside the existing title/description header. There is no second content tab row. Header and content use the existing page scroll owner; neither gains a new fixed position. Maps to AC-UI-SETTINGS-HEADER-TABS-001.1/.3/.6 and AC-SYSTEM-PAGE-DATA-STORAGE-PAGES-002.1/.2.

UI-02: Header tabs, phone

Entry: the mobile Settings navigation. State: Storage, Office retention selected.

Storage
Manage disk usage and history
retention.

[ Host | Office retention ]
------------------------------
Retention status
Automatic cleanup          On
Last cleanup
Today, 09:00          Completed

Routine history         1,240
Agent run history         860
Run events             12,400

> Cleanup details
------------------------------
Retention policy
Automatically delete old
history                  [ON]
Active work remains protected.

Routine history
Keep for                  (i)
[ 30                    ] days
Minimum per routine       (i)
[ 50                 ] records

> Advanced settings

          [ Save changes ]

Tabs move below the description inside the header. Counts and fields form a single column. The existing floating save control appears only for dirty settings and clears the safe area. Maps to AC-UI-SETTINGS-HEADER-TABS-001.2/.5 and AC-SYSTEM-PAGE-DATA-STORAGE-PAGES-004.6.

UI-03: Office retention, desktop and status variants

Entry: Storage > Office retention. State: loaded, saved policy.

Storage                           [ Host | Office retention ]
Manage disk usage and history retention.
------------------------------------------------------------
Retention status                       Automatic cleanup: On
Last cleanup                  Today, 09:00 - Completed
Routine history       Agent run history       Run events
1,240 records         860 records             12,400 records
Updated today, 09:00
Stored counts include protected work.
> Cleanup details
------------------------------------------------------------
Retention policy                         Automatic cleanup [ON]
Old finished history and related details are deleted.
Active work remains protected.

Routine history
Keep for (i) [30] days       Minimum per routine (i) [50]
Agent run history
Keep for (i) [30] days       Minimum per agent profile (i) [50]

v Advanced settings
Cleanup interval (i) [6] hours      Batch limit (i) [5000]
Warn above (i)
Routine records [25000]  Agent run records [25000]
Run events [250000]

Changed states:

Loading:    [spinner] Loading retention settings
Load error: Unable to load retention settings. [existing retry path]
No result:  No cleanup recorded since server startup.
Unavailable count: Routine history: Not available
Stale count:       Run events: 12,400 (out of date, timestamp)
Preview:    Routine history: Preview, 120 eligible, 0 deleted
Mixed:      Routine history: Preview | Agent run history: 40 deleted
Error:      Cleanup completed with errors. 40 records deleted.
Backlog:    More eligible history remains for a later cleanup.
Disabled:   Automatic cleanup: Off | Stored counts remain visible

The retry path means the existing hook/page reload behavior; it does not require a new API. Error/backlog/stale notices remain outside collapsed details. Preview totals never count as deletions. Use saved settings for status while a policy draft is dirty. Maps to AC-SYSTEM-PAGE-DATA-STORAGE-PAGES-003.1-.4 and -004.1-.6.

UI-04: Temporary files and help

Entry: Storage > Host. State: cleanup available, automatic cleanup off.

Temporary Kandev files
Diagnostic bundles and utility working folders.
Clean inactive temporary files (i)                    [OFF]
Inactive for at least 24 hours. Files move to quarantine.
[ Clean temporary files ]

Desktop help opens on hover or focus. Phone tap opens the shared inset Drawer:

+--------------------------------+
| About temporary Kandev files    |
| Registered diagnostic bundles  |
| and utility working folders.   |
| Shared temporary folders and   |
| unrelated caches are excluded. |
|                        [Close] |
+--------------------------------+

The Drawer owns its temporary scroll area only when content exceeds available height. Its close action returns focus to the information icon. Existing cleanup confirmation and disabled reasons remain intact. Maps to AC-SYSTEM-PAGE-DATA-STORAGE-PAGES-003.2/.5.

Tests

Each named new test is a deliverable, not an existing suite. Test names below define the expected cases.

Criteria Evidence
UI -001.1-.6 settings-tabs.test.tsx: shared composition, manual keyboard activation, panel associations, no-tabs compatibility; rendered header tests
UI -002.1/.4/.5; system -002.4 use-settings-tab.test.tsx: default/invalid query, target precedence, repeated target, query preservation, history destination; route/discovery tests
UI -002.2/.3; system -001.9/-002.5 settings-save-provider.test.tsx plus tab integration: retained dirty contributors, save failure, discard and guarded exit
system -002.1-.3 settings-routes.test.ts: correct tab composition and legacy mapping
system -003.1-.4 retention-settings-card.test.tsx: labels, full saved payload, advanced fields and help
system -004.1-.6 retention-status.test.ts: absent sweep, saved-enabled state, zero/unavailable/stale, differing timestamps, threshold equality/zero, mixed preview/deletion, partial errors, backlog, skip and attribution
system -003.5/.6 Existing storage-policy and tool-payload card suites: retained actions and copy semantics
system -002.4 Go retention/health tests: new Office retention FixURL

E2E tests

Flow File and project Criteria
Header placement, long labels, keyboard selection, URL/reload/history, dirty tab round-trip, guarded exit, search reveal system/settings-header-tabs.spec.ts, chromium UI -001/-002; system -002
Phone header, 767/768 boundary checks, coarse-pointer target checks, tab strip overflow and focus system/mobile-settings-header-tabs.spec.ts, mobile-chrome UI -001; system -001.7/.8
Retention edit/save/reload, advanced help, saved-policy status and mixed/error fixtures system/retention-settings.spec.ts, chromium system -003.1-.4/-004
Retention touch help Drawer, close/focus return, single-column summary, controls >=44px system/mobile-retention-settings.spec.ts, mobile-chrome system -003.2/.3/-004.6
Existing temporary cleanup and compaction workflows, full card width, help Existing temporary-folders and tool-payload specs, chromium/mobile-chrome system -003.5/.6
Existing database/backups/logs navigation and actions Existing system specs in task 01 system -001/-002
Member read-only host/database and denied Office mutations after tab changes Existing data-storage member-gating specs, auth system -002.5

Use API fixtures for saved data and controlled response fixtures for rare status combinations. Assertions operate through rendered UI. Restore modified settings after each test. Measure desktop input height at 28px within 1px and touch targets at least 44px. Measure header title/tab alignment and card width against the actual parent, not visibility alone. Capture focused rendered desktop/phone evidence in each UI work order. Check pseudo-locale and long translated labels.

Work orders

Verification setup

From the repository root, install dependencies once before implementation checks:

(cd apps && pnpm install --frozen-lockfile)

Each work order lists exact targeted commands. Run E2E commands sequentially without worker overrides. The managed runner builds current sources. Use the configured chromium, mobile-chrome, and auth projects. After locale edits, run (cd apps/web && pnpm run i18n:zh-hant) before the task's i18n checks.

Results

Implemented the four work orders in sequence. The two system pages now use shared header tabs with URL-addressable selection, preserved drafts, target activation, and legacy redirects. Office retention has the revised policy and status presentation, host maintenance retains its existing operations, and Database contains message compaction and backups.

Validation passed for focused Vitest coverage (16 files, 167 tests), frontend typecheck and lint, i18n checks and ratchet, public documentation and specification validation, gofmt, focused Office retention and health tests, and the affected desktop, mobile, and authenticated E2E suites. The full backend matrix still reports unrelated failures in existing process probe timing, ambient config discovery, launcher setup, and an Office FTS migration test; the changed retention backend packages pass independently. New components/hooks must meet scoped lint limits. Run pnpm exec eslint from apps/web on every changed TS/TSX source and test path. No generic review, QA, simplify, or broad verification work order is added.

Companion packages

The page-split, Office run-retention, tool-payload-retention, and storage-temp-artifacts packages are historical inputs. Their completed results remain historical. This package owns all new route and presentation verification. Their manifests link here so future work can find the changed allocation.

Verification results

Implementation is complete. All four work orders are done. Focused Vitest, frontend typecheck and lint, i18n, public documentation, specification, Go, desktop, mobile, and authenticated E2E checks passed. Fresh desktop and mobile PR captures were published from the affected pages.

The full backend matrix still has unrelated failures in existing process probe timing, ambient config discovery, launcher setup, and an Office FTS migration test. The changed retention backend packages pass independently.

Risks

  • Query updates can unregister dirty forms or bypass page-exit protection if mounted state is not preserved.
  • Hidden panels can consume discovery focus before their tab opens.
  • A mixed preview/deletion sweep or stale count can produce a misleading summary if flattened into one success badge.
  • Raw technical IDs can leak through errors; diagnostics remain available, but normal labels must be translated.
  • Retention is admin-scoped even though Host contains member-readable information.
  • Old screenshots and links can describe the previous layout until the documentation work order ships.