---
status: resolved
phase: 12-cloud-resource-foundation
source:
  - 12-01-SUMMARY.md
  - 12-02-SUMMARY.md
  - 12-03-SUMMARY.md
  - 12-04-SUMMARY.md
  - 12-05-SUMMARY.md
started: 2026-06-19T20:21:31+02:00
updated: 2026-06-21T23:59:00+02:00
---

## Current Test

[testing paused — 3 items blocked by diagnosed cloud connection/navigation defects]

## Tests

### 1. Cold Start Smoke Test
expected: Start DocuVault from a clean stopped state. PostgreSQL migration 0006 completes, the backend and frontend become healthy without startup errors, and the authenticated Cloud Storage page loads normally.
result: pass
verified: "Automated cold start: Compose migration gate exited 0 at Alembic 0006; backend and frontend returned 200; regular-user /cloud loaded; startup logs and browser console had no warnings or errors."

### 2. Connection Roots and Custom Names
expected: Cloud Storage shows each connected account as its own top-level row. Two accounts from the same provider remain distinct; default duplicate names are disambiguated, and renaming one connection in Settings updates only that connection.
result: issue
reported: |
  1. I connected a test account on my nextcloud instance and I still cannot connect. It shows "HTTP 422" Please check whats wrong.
  5. It seems that I still can only connect one storage per provider. I connected a nextcloud storage and cannot connect another one.
severity: blocker

### 3. Shared Cloud Folder Browser
expected: Opening a connection shows its files and folders in the same StorageBrowser layout used for local documents. The breadcrumb begins with the connection name, folder navigation works, and provider IDs or technical metadata do not clutter normal rows.
result: issue
reported: |
  2. If I am on the nextcloud connection, which fails to synchronize, I cannot click on "Cloud" in the breadcrumb to go back to the cloud provider overview.
  3. The "CloudStorage" navigator button on the sidebar is always highlighted if I am on a specific cloud storage folder and not either the cloud provider I am currently in or even the folder itself I am in.
  4. It seems that the breadcumb in the cloud storage is not working as intended. If I am in my nextcloud connection I want there to be shown "Cloud > Nextcloud (or the custom name) > Folder1 > ...."
severity: major

### 4. Unsupported Action Explanations
expected: Unsupported cloud actions remain visible in their normal positions but appear gray; temporarily unavailable actions appear amber. Hover or keyboard focus shows the specific explanation, and tapping/clicking an unavailable action explains it without executing it.
result: blocked
blocked_by: prior-phase
reason: "I cannot procede with the verification until the cloud storage is fixed as mentioned before."

### 5. Cached-First Refresh and Warning State
expected: Revisiting a previously browsed folder shows saved metadata immediately while a subtle refresh indicator runs. If provider refresh fails, cached rows remain usable and a warning reports the last successful refresh and automatic retry instead of replacing the folder with an error.
result: blocked
blocked_by: prior-phase
reason: "I cannot procede with the verification until the cloud storage is fixed as mentioned before."

### 6. Session-Only Folder Memory
expected: Leaving and reopening a connection in the same browser session resumes its last folder. Starting a fresh tab/session begins at the connection root, and no credentials or document content are stored in browser session storage.
result: blocked
blocked_by: prior-phase
reason: "I cannot procede with the verification until the cloud storage is fixed as mentioned before."

## Summary

total: 6
passed: 1
issues: 2
pending: 0
skipped: 0
blocked: 3

## Gaps

- truth: "Each cloud connection is addressed by its UUID, and a user can create and manage multiple independent connections for the same provider."
  status: resolved
  reason: "User reported that a successfully connected Nextcloud account opens as HTTP 422 and that a second Nextcloud connection cannot be added."
  severity: blocker
  test: 2
  root_cause: "The connection POST succeeded with 201, but CloudProviderTreeItem still routes and browses by provider slug; /cloud/nextcloud/root makes CloudFolderView call the UUID endpoint with 'nextcloud', producing FastAPI's 422 UUID validation response. Separately, _upsert_cloud_connection selects by (user_id, provider) and SettingsCloudTab.connectionFor() renders only the first provider match, so same-provider connections are overwritten/hidden."
  artifacts:
    - path: "frontend/src/components/cloud/CloudProviderTreeItem.vue"
      issue: "Uses deprecated provider-keyed browse API and pushes /cloud/{provider}/root instead of the connection UUID."
    - path: "frontend/src/components/cloud/CloudFolderTreeItem.vue"
      issue: "Propagates provider slugs rather than connection IDs through nested sidebar navigation."
    - path: "backend/api/cloud/connections.py"
      issue: "_upsert_cloud_connection updates the first (user_id, provider) row instead of creating an independent connection."
    - path: "frontend/src/components/settings/SettingsCloudTab.vue"
      issue: "connectionFor(providerKey) collapses all same-provider connections to one row and removes the add-another flow."
  missing:
    - "Use connection UUIDs for all sidebar browse requests and routes."
    - "Replace provider upsert semantics with independent connection creation plus connection-ID editing."
    - "Render every connection in Settings and retain an explicit Add connection action per provider."
    - "Show structured FastAPI validation details instead of reducing them to HTTP 422."
  debug_session: ""

- truth: "Cloud navigation identifies the active connection/folder and exposes a working Cloud > connection > folder hierarchy."
  status: resolved
  reason: "User reported that Cloud cannot be clicked from a failed connection, the generic Cloud Storage sidebar entry stays highlighted, connection/folder nodes are not highlighted, and the breadcrumb hierarchy is incomplete."
  severity: major
  test: 3
  root_cause: "StorageBrowser substitutes the connection name for the breadcrumb root and CloudFolderView maps only folder path segments; its null-root handler returns to the connection root rather than /cloud. AppSidebar marks the generic Cloud Storage link active for every /cloud path, while TreeItem receives no route-aware selected state. The stale provider-keyed sidebar route compounds all three symptoms."
  artifacts:
    - path: "frontend/src/components/storage/StorageBrowser.vue"
      issue: "Uses connectionRoot.name as rootLabel, eliminating the separate Cloud overview crumb."
    - path: "frontend/src/views/CloudFolderView.vue"
      issue: "Breadcrumb excludes Cloud and connection segments; null navigation targets the connection root."
    - path: "frontend/src/components/layout/AppSidebar.vue"
      issue: "Generic Cloud Storage link is active for every path beginning with /cloud."
    - path: "frontend/src/components/cloud/CloudProviderTreeItem.vue"
      issue: "Connection node is not route-selected and routes by provider slug."
    - path: "frontend/src/components/cloud/CloudFolderTreeItem.vue"
      issue: "Folder nodes are not route-selected and route by provider slug."
  missing:
    - "Render Cloud > connection display name > provider folder segments with independently navigable IDs."
    - "Route the Cloud crumb to /cloud even when refresh fails."
    - "Highlight the deepest active sidebar node; highlight generic Cloud Storage only on /cloud."
  debug_session: ""

- truth: "A developer can start the complete local stack from the repository root without missing-variable errors or configuration warnings."
  status: resolved
  reason: "User reported: To verify is create a complete development .env file and exclude it from git. Please remeber (codex and claude) to edit this .env file so I can spin up the app without errors or warnings."
  severity: major
  test: 1
  root_cause: "The ignored local .env predated later cloud and observability configuration: CLOUD_CREDS_KEY and the Compose-required GRAFANA_ADMIN_PASSWORD were missing, and no agent-facing rule required .env to stay synchronized with .env.example."
  artifacts:
    - path: ".env"
      issue: "Local development configuration lacked required Phase 5/6 variables and explicit defaults."
    - path: ".env.example"
      issue: "Template omitted observability, auth-duration, AI-default, and MINIO_PUBLIC_ENDPOINT entries."
    - path: "AGENTS.md"
      issue: "No Codex maintenance contract for the ignored local environment file."
    - path: "CLAUDE.md"
      issue: "No Claude maintenance contract for the ignored local environment file."
  missing: []
  debug_session: ""

- truth: "A clean start applies migration 0006 and the authenticated Cloud Storage page loads without backend schema errors."
  status: resolved
  reason: "User reported: GET /api/cloud/connections raises psycopg.errors.UndefinedColumn because cloud_connections.display_name_override does not exist in the live PostgreSQL schema."
  severity: blocker
  test: 1
  root_cause: "The live database is at Alembic revision 0005 because docker-compose.yml starts backend/workers directly and has no migration service or dependency that runs alembic upgrade head. ORM metadata expects revision 0006."
  artifacts:
    - path: "docker-compose.yml"
      issue: "No migration service; backend and Celery services depend only on PostgreSQL health."
    - path: "backend/migrations/versions/0006_cloud_resource_foundation.py"
      issue: "Required migration exists but is not applied during Compose startup."
    - path: "backend/tests/test_alembic.py"
      issue: "No PostgreSQL regression covering upgrade from revision 0005 to head."
  missing:
    - "Run alembic upgrade head before backend and worker startup."
    - "Add cold-start migration regression and deployment documentation."
  debug_session: ".planning/debug/phase-12-cloud-schema-cold-start.md"
- truth: "A user can connect Nextcloud accounts and each connected account appears as an independently renameable cloud root."
  status: resolved
  reason: "User reported: Cannot connect Nextcloud test users; POST /api/cloud/connections/webdav fails because cloud_connections.display_name_override does not exist."
  severity: blocker
  test: 2
  root_cause: "Same schema-drift root cause as Test 1: Nextcloud connection creation queries the Phase 12 ORM while PostgreSQL remains at revision 0005."
  artifacts:
    - path: "docker-compose.yml"
      issue: "No migration gate before the cloud connection API starts."
    - path: "backend/api/cloud/connections.py"
      issue: "Correctly queries CloudConnection, which exposes the unapplied schema immediately."
  missing:
    - "Apply revision 0006/head before accepting cloud connection requests."
  debug_session: ".planning/debug/phase-12-cloud-schema-cold-start.md"
