docs(12): capture phase context

2026-06-18 22:07:26 +02:00
parent a323276e37
commit 09814c28a9
2 changed files with 189 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Phase 12: Cloud Resource Foundation - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md; this log preserves the alternatives considered.
+
+**Date:** 2026-06-18
+**Phase:** 12-cloud-resource-foundation
+**Areas discussed:** Cloud navigation identity, Unsupported actions, Metadata freshness, Cloud item presentation
+
+---
+
+## Cloud Navigation Identity
+
+| Question | Options considered | Selected |
+|----------|--------------------|----------|
+| First Cloud Storage screen | All connections as roots; provider picker; last-used connection | All connections as roots |
+| Connection naming | Customizable name; provider and account; provider only | Customizable, defaulting to provider |
+| Breadcrumb identity | Connection first; Cloud then connection; provider then connection | Connection first |
+| Reopening a connection | Last visited; root; remember during session | Remember during session |
+
+**Notes:** Multiple accounts from the same provider must be supported. Each account is a separate customizable root. A new browser session starts at that connection's root.
+
+---
+
+## Unsupported Actions
+
+| Question | Options considered | Selected |
+|----------|--------------------|----------|
+| Unsupported action visibility | Disabled in place; hidden; limitations menu | Disabled in place |
+| Touch explanation | Tap; adjacent info marker; long press | Tap |
+| Explanation detail | Exact reason/remedy; provider-level reason; generic | Exact dynamic reason/remedy |
+| Temporary versus permanent limits | Different states; same state; hide temporary | Different states |
+
+**Notes:** Capability detection must be dynamic per connection. Use provider features, permissions, and safe checks; never mutate user files to test support. A future documentation link from tooltips was deferred.
+
+---
+
+## Metadata Freshness
+
+| Question | Options considered | Selected |
+|----------|--------------------|----------|
+| Previously visited folder | Cached-first background refresh; wait for provider; manual refresh | Cached-first |
+| Refresh visibility | Subtle folder indicator; silent unless failed; mark every row | Subtle folder indicator |
+| External changes | Update with notice; update silently; ask before apply | Update silently |
+| Refresh failure | Keep cached with warning; replace with error; hide warning | Keep cached with warning |
+
+**Notes:** Show the last successful refresh time after failures and keep retrying with bounded, increasing delays.
+
+---
+
+## Cloud Item Presentation
+
+| Question | Options considered | Selected |
+|----------|--------------------|----------|
+| Source repetition | Contextual only; provider icon per row; connection badge per row | Contextual only |
+| Normal row metadata | Match local rows; analysis column; technical details | Match local rows |
+| Byte availability | Compact status icon; text label; dedicated column | Compact status icon |
+| Breadcrumb sync state | Three states; binary; activity only | Three states |
+
+**Notes:** The breadcrumb shows refreshing, up-to-date, or warning state. Metadata does not consume document quota. Actual file bytes retained by DocuVault do consume quota until evicted; transient in-memory streaming does not.
+
+---
+
+## Claude's Discretion
+
+- Exact iconography, accessible tooltip wording, warning styling, retry intervals, and duplicate-name disambiguation.
+
+## Deferred Ideas
+
+- Link capability tooltips to DocuVault documentation after a documentation flow exists.
+- Permanent offline/downloaded copies remain a future phase rather than Phase 12 scope.