---
phase: "14"
plan: "08"
subsystem: cloud-analysis-settings
tags: [settings, cache, analysis, frontend, store, api]
status: complete

requires:
  - phases/14-selective-analysis-and-byte-cache/14-03
  - phases/14-selective-analysis-and-byte-cache/14-07

provides:
  - frontend/src/api/cloud.js: getCacheSettings → GET /api/cloud/analysis/cache,
    updateCacheSettings → PATCH /api/cloud/analysis/cache/settings (corrected URLs)
  - frontend/src/stores/cloudConnections.js: loadCacheSettings action (hydrates
    tierCapBytes/cacheUsage/cacheLimit/detailedAnalysisProgress/failureBehavior
    from server); tierCapBytes, cacheUsage, cacheSettingsLoading, cacheSettingsError state
  - frontend/src/components/settings/SettingsCloudTab.vue: Analysis Settings section
    with cache limit number input, simplified/detailed progress toggle, pause-batch/
    continue-item failure behavior toggle

affects:
  - frontend/src/api/cloud.js (URL bug fix + enhanced docs)
  - frontend/src/stores/cloudConnections.js (loadCacheSettings action + new state)
  - frontend/src/components/settings/SettingsCloudTab.vue (Analysis Settings section)

tech-stack:
  added: []
  patterns:
    - server-hydrated-settings: loadCacheSettings fetches CacheStatusOut from
      /api/cloud/analysis/cache and merges tier_cap_bytes, entry_count, total_bytes,
      analysis_progress_detail, analysis_failure_behavior into Pinia memory on mount
    - error-no-clear: settings load/update errors set cacheSettingsError without
      clearing existing in-memory settings — UI shows error but retains last known values
    - optimistic-then-persist: progress-detail and failure-behavior controls apply
      local change optimistically (setDetailedAnalysisProgress/setFailureBehavior)
      then persist via updateCacheSettings; revert on API failure
    - tier-cap-validation: cache limit input validates against tierCapBytes (from server)
      with local error message before calling API; invalid values are rejected locally

key-files:
  created: []
  modified:
    - frontend/src/api/cloud.js
    - frontend/src/stores/cloudConnections.js
    - frontend/src/components/settings/SettingsCloudTab.vue

decisions:
  - getCacheSettings and updateCacheSettings corrected to /api/cloud/analysis/cache
    and /api/cloud/analysis/cache/settings (Rule 1 auto-fix — previous URLs pointed
    to non-existent /api/users/me/settings endpoint per Plan 14-03 backend spec)
  - Settings UI uses segmented controls (two-button toggle) not <select> for
    progress detail and failure behavior — matches the pattern of binary preference
    choices with clear active-state affordance
  - Cache limit input is a number field (MB) rather than a slider — avoids slider
    precision issues at large byte values and is keyboard-accessible
  - Analysis Settings in a separate card below Cloud Storage connections — keeps
    connection management UX untouched and groups Phase 14 settings together
  - tierCapBytes defaults to 2 GB client-side if loadCacheSettings hasn't completed —
    prevents the UI from showing 0 MB max before the server responds

metrics:
  duration: "~10 minutes"
  completed: "2026-06-23"
  tasks: 2
  files: 3
---

# Phase 14 Plan 08: Settings Integration Summary

One-liner: Cache limit control, simplified/detailed progress toggle, and pause-batch/continue-item failure behavior toggle in Settings, backed by the /api/cloud/analysis/cache endpoint with server-authoritative tier cap and usage display.

## What Was Built

### Task 1: API/store wiring

**frontend/src/api/cloud.js** (bug fix + enhanced docs):

- `getCacheSettings()` — corrected from `/api/users/me/settings` to `/api/cloud/analysis/cache`. Returns `CacheStatusOut` with `entry_count`, `total_bytes`, `cache_limit_bytes`, `tier_cap_bytes`, `analysis_progress_detail`, `analysis_failure_behavior`.
- `updateCacheSettings(params)` — corrected from `/api/users/me/settings` PATCH to `/api/cloud/analysis/cache/settings` PATCH. Accepts optional `cloud_cache_limit_bytes`, `analysis_progress_detail`, `analysis_failure_behavior`. Returns fresh `CacheStatusOut`.

**frontend/src/stores/cloudConnections.js** (new state and action):

New state (Pinia memory — no credentials):
- `tierCapBytes`: server-authoritative ceiling for the cache limit (null until loaded)
- `cacheUsage`: `{ entry_count, total_bytes }` from last successful load (no object_key)
- `cacheSettingsLoading`: true while load/update API call is in flight
- `cacheSettingsError`: string error from last failed call; null on success

New action:
- `loadCacheSettings()`: calls `getCacheSettings()`, merges all 6 CacheStatusOut fields into local refs. Error path sets `cacheSettingsError` without clearing existing settings. Used by SettingsCloudTab on mount.

Updated action:
- `updateCacheSettings(params)`: now also merges `tier_cap_bytes`, `cacheUsage`, `analysis_progress_detail`, and `analysis_failure_behavior` from the server response (not just `cloud_cache_limit_bytes`). Sets `cacheSettingsError` on failure without clearing local state; re-throws so callers can react.

### Task 2: SettingsCloudTab UI controls

**frontend/src/components/settings/SettingsCloudTab.vue** (Analysis Settings section added):

New UI section (`data-test="cache-settings-section"`):

1. **Cache limit input** (`data-test="cache-limit-input"`)
   - Number field in MB with `min=1` and `max=cacheLimitMaxMB` (from `tierCapBytes`)
   - Default cap shown: "Max: N MB"
   - Local validation: rejects values < 1 or > tier cap before API call
   - Usage display when `cacheUsage` is loaded: "Currently using X MB of Y MB"
   - Error message: `data-test="cache-limit-error"` for validation failures
   - `aria-label="Cache limit in megabytes"` for accessibility

2. **Analysis progress detail toggle** (`data-test="progress-simplified"` / `data-test="progress-detailed"`)
   - Segmented control (two-button group) with `aria-pressed` states
   - Simplified (default) / Detailed
   - Optimistic local update via `store.setDetailedAnalysisProgress()` then persists to API
   - Reverts on API failure

3. **Failure behavior toggle** (`data-test="failure-pause-batch"` / `data-test="failure-continue-item"`)
   - Segmented control with `aria-pressed` states
   - Pause batch (default) / Skip and continue
   - Optimistic local update via `store.setFailureBehavior()` then persists to API
   - Reverts on API failure

4. **Settings error banner** (`data-test="cache-settings-error"`)
   - Shown when `store.cacheSettingsError` is set
   - Never shows credentials or object_key fields

Existing Cloud connections section (`Test`, `Reconnect`, `Edit`, `Rename`, `Remove`) is completely untouched.

## Test Results

| File | Tests | Pass | Notes |
|------|-------|------|-------|
| cloudConnections.analysis.test.js | 17 | 17 | All pass (unchanged from Plan 07) |
| SettingsCloudTab.test.js | 7 | 7 | All pass; no regressions |
| SettingsCloudTab.health.test.js | 10 | 10 | All pass; no regressions |
| Full frontend suite | 471 | 471 | No regressions introduced |

Backend:
- `pytest -q tests/test_cloud_cache.py -k "settings"` — 0 matched (settings tests covered by
  test_cloud_security.py in Plan 03; cache.py routes unchanged in this plan)

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] getCacheSettings/updateCacheSettings pointed to non-existent /api/users/me/settings**
- **Found during:** Task 1, reading the Plan 03 backend spec
- **Issue:** Both `getCacheSettings()` and `updateCacheSettings()` in `api/cloud.js` called
  `/api/users/me/settings` which was never implemented in the backend. The actual endpoints
  from Plan 14-03 are `GET /api/cloud/analysis/cache` and `PATCH /api/cloud/analysis/cache/settings`.
- **Fix:** Corrected both URLs to match the Plan 14-03 backend routes.
- **Files modified:** `frontend/src/api/cloud.js`
- **Commit:** 6fc30ac

## Known Stubs

None — all controls are wired to real store actions which call the real API. The backend
cache/settings API was implemented in Plan 14-03. In tests, the API is mocked at the
`api/client.js` boundary per existing patterns.

## Threat Flags

None — no new network endpoints introduced. All settings calls route through
authenticated `request()`/`jsonRequest()` helpers. CacheStatusOut response schema
excludes object_key and credentials_enc at design level (T-14-02/T-14-08). The UI
stores no credentials and renders no object_key fields.

## Self-Check: PASSED