From 6dc5464dd53a29d99a1a72e2da46ce5fd180ac0a Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Tue, 31 Mar 2026 12:50:21 -0700 Subject: [PATCH] docs: add WEB_AI_FAST_ROADMAP and index cross-links - New phased plan for web (command palette, autosave, saved views, task scan, context packs, semantic search, copilot, MCP onboarding, sharing, polish) - Link from AGENT_TASK_ROADMAP; index entry in ROADMAP.md - Fix task-summary table total row; rename meta sections to avoid clash with Phase N Made-with: Cursor --- docs/AGENT_TASK_ROADMAP.md | 4 + docs/ROADMAP.md | 1 + docs/WEB_AI_FAST_ROADMAP.md | 229 ++++++++++++++++++++++++++++++++++++ 3 files changed, 234 insertions(+) create mode 100644 docs/WEB_AI_FAST_ROADMAP.md diff --git a/docs/AGENT_TASK_ROADMAP.md b/docs/AGENT_TASK_ROADMAP.md index 1cb134f..88b3801 100644 --- a/docs/AGENT_TASK_ROADMAP.md +++ b/docs/AGENT_TASK_ROADMAP.md @@ -18,6 +18,10 @@ **Package resolution note:** 5 backend `@bytelyst/*` packages (`backend-config`, `backend-flags`, `backend-telemetry`, `fastify-auth`, `field-encrypt`) do not have source directories in `learning_ai_common_plat/packages/`. They resolve via `^0.1.0` from the private Gitea npm registry but their source must be created in common_plat. This is a shared blocker with NomGap — see Phase 0 below. +### Web — AI-fast product roadmap + +For **sequenced web features** (command palette, context export, semantic retrieval, copilot, sharing, MCP onboarding), see **[`WEB_AI_FAST_ROADMAP.md`](./WEB_AI_FAST_ROADMAP.md)**. + ### Mobile — sequential handoff For **ordered mobile implementation** (Expo app under `mobile/`), use **[`MOBILE_DELEGATION_ROADMAP.md`](./MOBILE_DELEGATION_ROADMAP.md)** — blocks, file pointers, and acceptance criteria in one place. Update the **Current State** table above when mobile capabilities change materially. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index d7f3ec4..61150d7 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -56,6 +56,7 @@ Detailed implementation plans live under `docs/roadmaps/`. - [x] `docs/roadmaps/05_MCP_AGENT_ROADMAP.md` - [ ] `docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md` - [x] `docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md` +- [x] `docs/WEB_AI_FAST_ROADMAP.md` — web product phases (AI-fast velocity, retrieval, copilot, sharing) # 4. Master Phase Tracker diff --git a/docs/WEB_AI_FAST_ROADMAP.md b/docs/WEB_AI_FAST_ROADMAP.md new file mode 100644 index 0000000..7dadde2 --- /dev/null +++ b/docs/WEB_AI_FAST_ROADMAP.md @@ -0,0 +1,229 @@ +# NoteLett — Web “AI-fast” Product Roadmap + +**Date:** March 31, 2026 +**Product:** NoteLett (`notelett`) — structured notes for humans + AI agents +**Repo:** `learning_ai_notes` +**Scope:** **Web app** (`web/`) first; calls out backend/platform dependencies explicitly. + +**Companion docs:** [`AGENT_TASK_ROADMAP.md`](./AGENT_TASK_ROADMAP.md) (agent execution / CI / platform blockers), [`roadmaps/03_WEB_ROADMAP.md`](./roadmaps/03_WEB_ROADMAP.md) (historical web phases), [`roadmaps/05_MCP_AGENT_ROADMAP.md`](./roadmaps/05_MCP_AGENT_ROADMAP.md) (MCP tooling). + +--- + +## 1. Goals + +| Goal | Signal | +|------|--------| +| **Fast** | Fewer clicks to capture, find, and ship context to an LLM or agent. | +| **Trustworthy** | Human-in-the-loop for AI suggestions; visible provenance for agent edits. | +| **Spreadable** | Obvious paths to share context and onboard teammates + external tools (MCP, exports). | + +**Non-goals for this doc:** Mobile-specific work (see [`MOBILE_DELEGATION_ROADMAP.md`](./MOBILE_DELEGATION_ROADMAP.md)); re-litigating stack choices. + +--- + +## 2. Phase overview + +| Phase | Theme | Outcome | +|-------|--------|---------| +| **1** | Velocity & clarity | Command palette, editor autosave, real dashboard views, explicit task extraction UX | +| **2** | Context out | Markdown “context pack” export/copy; optional workspace-scoped bundles | +| **3** | Smarter retrieval | Semantic or hybrid search + basic match explainability (backend + web) | +| **4** | Copilot surfaces | In-editor AI actions; optional workspace chat (RAG) behind feature flag | +| **5** | Agent connection | In-app MCP / API connection guidance; deep links and safe key UX | +| **6** | Distribution | Read-only share links; onboarding sample workspace | +| **7** | Depth | Note history / diff for agent edits; templates library; PWA/sync affordances | + +Phases **1–2** are mostly **web-only** or small backend additions. **3–4** usually need **platform or backend** (embeddings, LLM, or existing shared services). **5–7** mix product, security, and infra. + +--- + +## Phase 1 — Velocity & clarity (web-first) + +**Objective:** Match power-user expectations (keyboard, save state) and remove “fake” dashboard data; make extraction legible. + +- [ ] **1.1 Command palette (⌘K / Ctrl+K)** + - **AC:** Opens from anywhere in `(app)`; fuzzy match on note titles + workspace names + static actions (New note, Search, Reviews, Settings, Dashboard). + - **Files:** `web/src/components/CommandPalette.tsx` (new), wire in `web/src/app/(app)/layout.tsx` or `KeyboardShortcuts.tsx`, reuse `listNoteSummaries` / `listWorkspaceSummaries` or lightweight search endpoint. + - **Tests:** Unit for reducer/filter; optional Playwright happy path. + +- [ ] **1.2 Note editor autosave + save status** + - **AC:** Debounced persist after idle (e.g. 1–2s) with “Saving / Saved / Error” indicator; manual save still available; avoid duplicate concurrent PATCH. + - **Files:** `web/src/components/NoteEditor.tsx`, `web/src/app/(app)/notes/[noteId]/page.tsx`. + - **Tests:** Vitest for debounce/abort behavior (mock API). + +- [ ] **1.3 Dashboard: backend-backed saved views** + - **AC:** “Saved views” / quick links on dashboard use `saved-views` API (or derived queries) instead of hardcoded cards only; empty states when none. + - **Files:** `web/src/app/(app)/dashboard/page.tsx`, `web/src/lib/saved-views-client.ts`. + - **Depends on:** Saved view scopes already supported by API (`search`, etc.); extend if workspace scope needed. + +- [ ] **1.4 Explicit “Scan for tasks” on note detail** + - **AC:** Button runs extraction (`extractSuggestedTasks`); shows proposed rows with Accept (creates `note-task` via API) / Dismiss; does not silently inflate task list on every load unless user opts in or a setting enables auto-merge. + - **Files:** `web/src/lib/notes-client.ts` (split `getNoteDetail` vs optional extraction), `web/src/components/TaskReviewPanel.tsx` or new `ExtractedTasksPanel.tsx`, `web/src/app/(app)/notes/[noteId]/page.tsx`. + - **Note:** Aligns UX with `/reviews` human-in-the-loop story. + +**Verification (Phase 1):** +`cd web && pnpm run typecheck && pnpm test && pnpm run build` + +--- + +## Phase 2 — Context out (export for LLMs & agents) + +**Objective:** One-click packaging of notes for Cursor, Claude, ChatGPT, or custom agents. + +- [ ] **2.1 “Copy context pack” from note** + - **AC:** Produces markdown with title, tags, body (plain or markdown strip), links to related note titles/IDs, optional tasks list; copies to clipboard; toast on success. + - **Files:** `web/src/lib/context-pack.ts` (pure formatter), button on `notes/[noteId]/page.tsx`. + +- [ ] **2.2 “Export workspace context pack”** + - **AC:** From workspace page or modal: select max notes / depth; download `.md` or `.zip` (if artifacts included later); respect pagination (chunked fetch). + - **Files:** `web/src/app/(app)/workspaces/page.tsx`, client helper calling existing `exportNotes` or new backend if limits hit. + +- [ ] **2.3 Optional: frontmatter convention** + - **AC:** Stable YAML frontmatter (`notelett_version`, `workspace_id`, `exported_at`) so downstream tools can parse reliably. + - **Files:** shared builder in `context-pack.ts`. + +**Verification:** Manual smoke + unit tests for formatter (no network). + +--- + +## Phase 3 — Smarter retrieval (backend + platform) + +**Objective:** Move beyond lexical search where product promises “retrieval.” + +- [ ] **3.1 Discovery** + - Document choice: embeddings in NoteLett backend vs shared search/RAG platform; latency and cost model. + - **Output:** short ADR in `docs/roadmaps/` or appendix in this file. + +- [ ] **3.2 Indexing pipeline** + - **AC:** On note create/update (or batch job): chunk + embed + store; workspace-scoped ACL matches REST. + - **Files:** `backend/` new module or integration with existing platform indexer. + +- [ ] **3.3 `POST /notes/search` (semantic/hybrid)** + - **AC:** Accepts `q`, optional `workspaceId`, returns ranked hits with `score` + snippet + `noteId`; falls back to lexical when flag off. + - **Files:** `backend/src/modules/notes/routes.ts`, repository, feature flag. + +- [ ] **3.4 Web search UI** + - **AC:** Toggle or auto hybrid mode; show why matched (e.g. “semantic” vs “title”); preserves saved searches. + - **Files:** `web/src/app/(app)/search/page.tsx`, `web/src/lib/notes-client.ts`. + +**Verification:** +`cd backend && pnpm run typecheck && pnpm test` +`cd web && pnpm run typecheck && pnpm test && pnpm run build` + +--- + +## Phase 4 — Copilot surfaces (editor + optional chat) + +**Objective:** AI actions where users already work; keep approvals explicit. + +- [ ] **4.1 In-editor toolbar actions** + - **AC:** Selection-based: shorten, expand, bulletize, fix grammar (call platform LLM or extraction-service pattern); insert as replacement or new block; undo. + - **Files:** `web/src/components/NoteEditor.tsx`, new `web/src/lib/copilot-client.ts` (platform route). + - **Depends on:** Authenticated API on platform with rate limits. + +- [ ] **4.2 “Generate title” from body** + - **AC:** One click; user confirms before apply. + - **Files:** note detail page + small client. + +- [ ] **4.3 Workspace chat (RAG) — feature-flagged** + - **AC:** Side panel or `/chat`: asks question, returns answer + citation links to notes; no write without explicit user action. + - **Files:** new route `web/src/app/(app)/chat/page.tsx` (or drawer), backend or platform RAG endpoint. + - **Depends on:** Phase 3 indexing + prompt/tooling policy. + +**Verification:** E2E for one happy-path copilot action; contract tests for API. + +--- + +## Phase 5 — Agent connection (MCP & keys in-product) + +**Objective:** Close the gap between “MCP exists in common platform” and “users know how to connect.” + +- [ ] **5.1 Settings → “Connect your agent”** + - **AC:** Steps + copyable MCP config snippet; link to docs; product ID and base URLs from env. + - **Files:** `web/src/app/(app)/settings/page.tsx`, `web/src/lib/product-config.ts`. + +- [ ] **5.2 Scoped API tokens (if platform supports)** + - **AC:** Create/revoke token for MCP or automation; never show full token twice. + - **Depends on:** platform-service APIs. + +- [ ] **5.3 Deep links** + - **AC:** `notelett://note/:id` or `https://app.../notes/:id` documented for agent tools. + - **Files:** docs + optional handler page. + +--- + +## Phase 6 — Distribution & onboarding + +**Objective:** Viral and activation loops. + +- [ ] **6.1 Read-only share links** + - **AC:** User generates link for a note (optional expiry/password); unauthenticated read view with clear branding; audit logged. + - **Files:** `backend` share-token module + `web/src/app/share/[token]/page.tsx` (public layout). + +- [ ] **6.2 Onboarding workspace** + - **AC:** New user seed workspace with 2–3 sample notes + one pending review item; tooltip tour optional. + - **Files:** backend bootstrap or platform hook + `web` first-login detection. + +--- + +## Phase 7 — Depth & polish + +**Objective:** Auditability, templates, offline clarity. + +- [ ] **7.1 Note version history / diff** + - **AC:** List revisions; diff view for agent-proposed changes (tie to `note-agent-actions`). + - **Depends on:** backend storing versions or reconstructing from actions. + +- [ ] **7.2 Note templates** + - **AC:** Create note from template (meeting, decision, spec); stored as markdown/HTML snippets. + - **Files:** `web` modal + backend `templates` or static config v1. + +- [ ] **7.3 PWA + offline status** + - **AC:** Install prompt optional; visible sync queue state using existing offline-queue patterns. + - **Files:** `web/next.config.ts`, manifest, settings indicator. + +--- + +## Execution order (recommended) + +1. Land **Phase 1** entirely (low dependency, high daily value). +2. Run **Phase 2** in parallel with **3.1 discovery** if two streams exist. +3. Implement **Phase 3** before **4.3** (RAG needs an index). +4. **Phase 5** can start after **2.1** (docs/snippets) even if tokens wait on platform. +5. **Phase 6** after auth/public-route security review. +6. **Phase 7** as ongoing polish. + +--- + +## Task summary + +| Phase | Tasks | Primary owner | +|-------|-------|---------------| +| 1 — Velocity & clarity | 4 | Web | +| 2 — Context out | 3 | Web (+ small backend if export limits) | +| 3 — Retrieval | 4 | Backend + platform + Web | +| 4 — Copilot | 3 | Web + platform | +| 5 — Agent connection | 3 | Web + platform | +| 6 — Distribution | 2 | Backend + Web | +| 7 — Depth | 3 | Full stack | +| **Total** | **22** | — | + +When a task ships, check the box here and optionally add a commit hash in [`AGENT_TASK_ROADMAP.md`](./AGENT_TASK_ROADMAP.md) style. + +--- + +## Verification commands (standing) + +```bash +cd web && pnpm run typecheck && pnpm test && pnpm run build +cd backend && pnpm run typecheck && pnpm test +cd web && pnpm exec playwright test # when E2E touched +``` + +--- + +## Changelog + +| Date | Change | +|------|--------| +| 2026-03-31 | Initial roadmap; task-summary table fix, unnumbered meta sections, maintenance note for checkboxes. |