verstak-docs/07_Full_Implementation_Roadmap.md

Verstak Implementation Roadmap

1. Goal

Bring Verstak to a complete standalone local-first desktop product:

• core platform and UI shell can run without official plugins;
• official plugins provide the user-facing tools;
• vault data stays human-readable and local-first;
• sync UI/settings, browser capture, activity, journal, preview, search, and secrets are plugin/runtime extensions; sync correctness (scanner, operation log, reconciliation, and workspace identity) stays in Desktop core;
• workspaces can be nested inside plain folders; identity through UUID markers (.verstak/workspace.json) at any depth; folder metadata (icon, color, order) lives in .verstak/folder-metadata/.

2. Non-negotiable Constraints

• No notes/files/editor/activity/journal/browser inbox feature may become a required core module.
• User documents remain ordinary vault files unless a feature explicitly needs protected storage, such as secrets.
• Overview.md is an ordinary Markdown filename, not a special UI entity.
• New plugin-facing behavior must go through public API contracts and SDK/schema updates.
• Every significant step must be verified, committed, and pushed separately.

3. Current Baseline

Implemented:

• plugin discovery, manifest validation, lifecycle states, enable/disable;
• capability, permission, contribution, event, settings, storage foundations;
• bundled frontend plugin host and VerstakPluginAPI;
• Command Palette UI host for commands contributions;
• Status Bar UI host for statusBarItems, vault status, and settings menu;
• workspace top-level folder model, workspace item host, workspace templates;
• Files Core API with safe path policy, durable snapshot scanning, atomic text/binary writes, and core sync operation recording;
• public files.openExternal / files.showInFolder API;
• mode-aware Workbench open/edit provider routing and default editor plugin;
• all official plugins: Files, Notes, Default Editor, File Preview, Activity, Journal, Browser Inbox, Search, Secrets, Todo, Trash, Sync, Templates;
• browser inbox local receiver with paired mode, domain bindings, and create-note/link/file conversion;
• sync server with device/user auth, operation push/pull, Blob transport, embedded web console, and real two-vault smoke scenarios;
• SDK manifest/types/schema coverage for plugin APIs;
• persisted System/English/Russian application language selection, localized desktop shell, public api.i18n plugin contract, and bilingual catalogs for all official plugins;
• automated Go, frontend, official plugin, SDK, and real-sync smoke checks;
• tray icon with native menu and native desktop notifications;
• AES-GCM secret store with master password, UI plugin;
• nested workspace model: identity markers at any depth, folder metadata, recursive tree in sidebar, workspace creation with parent folder selector.

Known remaining gaps:

• Sidecar host is not implemented (bundled plugins run in shared JS context).
• Chunked streaming/large-file import is deferred; bounded text (2 MB) and byte (8 MB) APIs are the current limits.
• UX polish is ongoing: Today flow as work-resume surface, Activity-to-Journal review, mobile/responsive layout, search in workspace header.
• Production-grade packaging, auto-update, and release workflow is partial: build scripts exist, but not a polished update channel.
• Sync operation-log retention/compaction is intentionally deferred.
• Secrets, plugin settings, Todo, Journal, Activity, and Browser Inbox are not synchronized yet.
• Browser extension chunked large-file capture is future work.
• Automatic conflict resolution is intentionally absent.

4. Implementation Phases

Phase 1 - Platform Runtime Completion

Goal: finish generic host surfaces that plugins need before adding more product plugins.

Tasks:

• implement Command Palette UI for commands contributions;
• host statusBarItems;
• define and host generic contextMenuEntries;
• host fileActions and noteActions through Files/Notes surfaces;
• add lifecycle events for workspace creation, rename, trash, selection;
• replace deprecated workspace compatibility wrappers in frontend code where practical;
• document each public API in SDK schemas and desktop runtime docs.

Status: done.

Phase 2 - Files And Notes Product Surface

Goal: make Files and Notes feel like complete daily-use tools while keeping storage as ordinary Markdown/files.

Tasks:

• improve Notes list filtering, sorting, and filtered empty states;
• improve Notes rename/conflict UX;
• add Notes delete/trash through Files API with confirmation;
• add Files restore metadata view;
• add Files restore command;
• define external open/show-in-folder as a public v2 API;
• add watcher-based refresh for Files/Notes after external changes;
• add safe binary read/streaming contract.

Status: done.

Phase 3 - Sync Hardening

Goal: make local-first cross-device file/workspace sync reliable and harden the optional self-hosted relay without making it the source of vault truth.

Verified in the current implementation:

• define conflict UX contract for desktop and sync plugin;
• add server/device revocation checks for sync auth paths;
• persist and display sync errors in Sync plugin;
• add retry/backoff for sync client operations;
• persist an atomic core snapshot under .verstak/sync/;
• reconcile initial vaults safely;
• apply pulled operations strictly by server_sequence;
• sync workspace create, rename, trash, and restore through core-owned entity with durable workspaceId;
• add real two-vault smoke scenarios;
• document deployment and backup procedures for sync-server;
• bind sync-server to loopback by default, set HTTP timeouts/graceful shutdown, publish health/readiness/build data;
• bounded JSON/push fields and pull pages;
• add streamed Blob transport with SHA-256/size verification;
• hash tokens, persist sessions, require CSRF for browser mutations;
• add embedded sync-server web console with shared responsive templates;
• remove hardcoded server HTML, split into shared layout/sidebar plus per-section templates.

Known limits:

• Files plugin API remains bounded to 2 MB text / 8 MB byte reads.
• External rename is represented as delete + create.
• Operation-log retention/compaction is intentionally deferred.
• Secrets, plugin settings, Todo, Journal, Activity, and Browser Inbox are not synchronized.

Status: core sync foundations complete. Retention and additional data domains are future milestones.

Phase 4 - Preview, Search, Activity, Journal

Goal: add the next visible product layer as replaceable plugins.

Tasks:

• keep Markdown preview inside verstak.default-editor, with no separate provider competing for .md files;
• implement basic image metadata preview plugin;
• implement baseline verstak.search workspace plugin;
• add type-as-you-search behavior and vault path/name matches;
• implement baseline verstak.activity event log plugin;
• expose Activity and Browser Inbox as global sidebar views;
• implement persistent search index and cross-provider runtime hosting;
• implement activity reconstruction and worklog suggestions;
• implement journal/worklog plugin that can consume activity suggestions.

Status: done. Remaining work is UX depth (Today flow, reporting, timers).

Phase 5 - Browser Inbox

Goal: capture browser context into the local vault through a public local receiver and an official inbox plugin.

Tasks:

• define browser capture payload protocol;
• implement minimal verstak.browser-inbox plugin;
• implement browser extension capture scaffold;
• define local receiver permission/pairing model;
• require an installation-local pairing token;
• add domain-to-workspace binding;
• convert inbox entries into notes through public plugin APIs;
• record converted inbox entries in Activity;
• convert inbox entries into link files;
• convert captured text file attachments;
• convert captured bounded binary attachments.

Status: done. Remaining work: capture-from-clipboard/manual capture, chunked large-file capture.

Phase 6 - Secrets

Goal: provide protected storage for credentials without turning secrets into notes or plain files.

Tasks:

• define secret-store capability and permissions;
• implement encrypted local secret storage;
• add UI-only official secrets plugin;
• integrate secret references with workspaces.

Status: done.

Phase 7 - Sidecar/Sandbox Boundary

Goal: move from trusted bundled plugin JavaScript toward safer plugin execution.

Tasks:

• implement sidecar launch protocol and local RPC;
• permission-scope sidecar APIs;
• stop sidecars on plugin disable;
• surface sidecar logs and health in Plugin Manager;
• document supported sidecar languages and packaging rules.

Status: not started.

Phase 8 - Packaging, Update, Release

Goal: produce installable, recoverable releases.

Tasks:

• define release artifact matrix (desktop, plugins, SDK, sync server, browser extension);
• add build scripts for .deb, AppImage, Windows portable, and plugin packages;
• add plugin package signing/verification or equivalent integrity checks;
• add backup/restore docs for vault and sync server;
• add crash/log collection for local diagnostics;
• build release smoke checklist.

Status: packaging scripts exist and produce release artifacts. Signing, auto-update, and release smoke checklist are future work.

Phase 9 - Nested Workspaces and Folder Tree

Goal: workspaces can live at any depth inside plain vault folders.

Tasks:

• workspace identity markers at any depth (recursive discovery)
• folder metadata API (icon, color, order)
• recursive tree rendering in sidebar with collapsible folders
• workspace creation with parent folder selector
• move workspaces between plain folders (MoveNode)
• workspaceTree contribution point for plugin replacement
• verstak.workspace-folders plugin: drag-and-drop, IconPicker, color picker
• folder creation from sidebar ("Create Folder" modal)
• workspace rename from sidebar in tree mode

Status: core infrastructure complete. Plugin with rich UX (drag-and-drop, icon/color picker) is next.

5. Immediate Execution Order

1. Command Palette UI host.
2. Status bar item host.
3. External open public API.
4. Notes trash/delete UX.
5. Sync hardening pass.
6. Browser inbox protocol, extension scaffold, local receiver, inbox plugin, and conversions.
7. Product UX follow-up: make the shell-level Today flow the command center for captures, recent activity, Activity worklog suggestions, and Journal import/review. This should reuse existing official plugin contracts instead of moving Activity, Browser Inbox, or Journal into desktop core.

6. Stop Conditions

Work can continue autonomously until one of these occurs:

• a decision requires product policy not present in docs;
• implementation needs credentials, signing keys, or external infrastructure;
• a repeated blocker appears after three evidence-based attempts;
• a repository has user changes that directly conflict with the next edit.