kite/.planning/ROADMAP.md

DocuVault Roadmap: v0.3 Reimagining Cloud Storage integration

Status: Proposed Phases: 12-16 Requirements: 36 Defined: 2026-06-17

Milestone Goal

Make connected cloud storage behave like first-class DocuVault storage: users can navigate and manage provider-owned files as if they were local, selectively analyze them, and find them through unified keyword and semantic search while DocuVault minimizes locally cached file bytes.

Mandatory Cross-Cutting Gates

Before any phase is marked complete:

1. Backend and frontend test suites pass with zero failures; every new function, endpoint, store, and component has focused coverage.
2. Security gate verifies user/connection/item ownership, credential secrecy, SSRF defenses, metadata-only audit logs, cache isolation, and no admin document-content access.
3. Dependency audits report no high/critical vulnerabilities.
4. Provider integration tests cover supported capabilities and explicit unsupported behavior.
5. User-facing changes update AGENTS.md, relevant README sections, and application patch/minor versions according to project protocol.

Phase Summary

Phase	Name	Goal	Requirements
12	6/6	Complete	2026-06-21
13	Virtual-Local Cloud Operations	Make cloud browsing and core file actions feel local while preserving provider semantics and security	CONN-01..03, CLOUD-02..07, CLOUD-09
14	Selective Analysis and Byte Cache	Analyze selected cloud scopes through cancellable jobs backed by bounded, private, on-demand byte caching	ANALYZE-01..07, CACHE-03..05
15	Unified Smart Search	Search local and analyzed cloud documents by exact text or semantic ideas without downloading files during queries	SEARCH-01..07
16	Change Tracking and Reliability	Detect external provider changes, mark stale indexes, remove deleted items, and harden refresh behavior	SYNC-02..04

Phase Details

Phase 12: Cloud Resource Foundation

Goal: DocuVault has a provider-neutral cloud file capability contract and durable per-user cloud item index, and the shared browser can render cloud resources and supported actions without copying full provider files into local storage.

Depends on: Phase 11 Requirements: CONN-04, CLOUD-01, CLOUD-08, CACHE-01, CACHE-02, SYNC-01

Success Criteria:

1. Every supported provider reports normalized capabilities for browse, open, preview, upload, folder creation, rename, move, delete, and change tracking.
2. Browsing any connected provider persists normalized, owner-scoped cloud item metadata including provider ID/path, parent, type, size, modification time, and version/etag.
3. StorageBrowser.vue remains the single file browser and renders cloud actions from capabilities, including disabled actions with provider-specific explanations.
4. Provider-owned bytes remain outside DocuVault while metadata, extracted text placeholders, topic links, and semantic-index state can be persisted independently.
5. Ownership and admin-negative tests prove cloud connection and cloud item metadata cannot cross user boundaries.

Phase 13: Virtual-Local Cloud Operations

Goal: Users can maintain healthy cloud connections and perform the main file-management workflows in connected storage with the same shared browser interactions used for local files.

Depends on: Phase 12 Requirements: CONN-01, CONN-02, CONN-03, CLOUD-02, CLOUD-03, CLOUD-04, CLOUD-05, CLOUD-06, CLOUD-07, CLOUD-09

Success Criteria:

1. Users can connect, test, reconnect, and disconnect providers while seeing current health and actionable reauthentication/error states.
2. Users can open or preview supported cloud documents and upload files into the current cloud folder through authorized DocuVault endpoints.
3. Users can create folders, rename items, move items within one connection, and delete items after confirmation wherever the provider supports each action.
4. Successful mutations immediately invalidate affected listings/index entries, refresh the shared browser, and write metadata-only audit events.
5. Provider-specific tests verify operation semantics, conflict/error responses, token refresh persistence, SSRF protection, and explicit unsupported capabilities.

Phase 14: Selective Analysis and Byte Cache

Goal: Users can analyze individual files, selected scopes, or whole connections through observable and controllable background jobs, while file bytes are hydrated only on demand and evicted safely.

Depends on: Phase 13 Requirements: ANALYZE-01, ANALYZE-02, ANALYZE-03, ANALYZE-04, ANALYZE-05, ANALYZE-06, ANALYZE-07, CACHE-03, CACHE-04, CACHE-05

Success Criteria:

1. Users can analyze one file, a multi-selection, a folder tree, or a whole connection after reviewing recursive file-count and byte-size estimates.
2. The UI exposes aggregate and per-item queued, downloading, extracting, classifying, indexed, cancelled, and failed states with retry and queued-work cancellation.
3. Analysis jobs are idempotent by cloud item and provider version/etag, and they never mutate the provider-owned file.
4. Cloud bytes are cached only for active opening, preview, or analysis work and are evicted by configurable limits without interrupting pinned active jobs.
5. Cache ownership, cache-key versioning, cancellation, duplicate-job, failure-retry, and eviction behavior have dedicated tests.

Phase 15: Unified Smart Search

Goal: One search experience finds local and analyzed cloud documents by keywords, sentences, or semantic ideas and opens cloud results through on-demand hydration.

Depends on: Phase 14 Requirements: SEARCH-01, SEARCH-02, SEARCH-03, SEARCH-04, SEARCH-05, SEARCH-06, SEARCH-07

Success Criteria:

1. A single query returns authorized local and analyzed cloud results ranked through full-text and semantic relevance.
2. Keyword and sentence searches match persisted extracted text, while idea searches use persisted embeddings or equivalent semantic indexes.
3. Results clearly show source, provider, cloud location, topics, and current analysis/stale status and can be filtered by those fields.
4. Search execution performs no provider file download; only opening or previewing a result may hydrate bytes.
5. Search isolation, ranking, filtering, stale-result handling, and no-download-on-query invariants have automated coverage.

Phase 16: Change Tracking and Reliability

Goal: DocuVault remains accurate when users or other applications modify connected cloud storage outside DocuVault.

Depends on: Phase 15 Requirements: SYNC-02, SYNC-03, SYNC-04

Success Criteria:

1. Provider delta feeds or bounded metadata refreshes detect changed versions and mark previously analyzed items stale until reanalysis.
2. Items deleted outside DocuVault disappear from navigation and are excluded from search without deleting unrelated user data.
3. Refresh jobs are idempotent, cursor-aware where supported, rate-limited, and retry transient failures with bounded exponential backoff.
4. Users can see refresh/stale/error state and deliberately reanalyze changed items.
5. End-to-end UAT verifies cloud-as-local operations, selective analysis, cache offload, unified smart search, and external-change recovery across supported provider classes.

Coverage

• v0.3 requirements: 36
• Mapped to phases: 36
• Unmapped: 0
• Duplicate mappings: 0

---

Roadmap proposed: 2026-06-17