Saravana Achu Mac
a697752d15
Phase 1: Command palette (⌘K), editor autosave with quiet auto-saves, dashboard saved views from API + quick links + onboarding seed CTA, explicit task scan panel. Phase 2: Context pack formatter with YAML frontmatter, copy on note + workspace .md export. Phase 3: ADR for hybrid search without embeddings; POST /notes/search (lexical + ranked hybrid); search UI mode toggle. Phase 4: POST copilot + suggest-title; in-editor copilot actions; /chat retrieval answers with citations (backend chat.rag_enabled). Phase 5: Settings MCP snippet, offline queue note, API token deferral; DEEP_LINKS.md. Phase 6: Note shares + public GET; share page; POST onboarding-seed. Phase 7: note_versions on PATCH; version panel; create-note templates; PWA manifest. Flags: search.hybrid_enabled, copilot.enabled, chat.rag_enabled, onboarding.seed_enabled. Made-with: Cursor
256 lines
13 KiB
Markdown
256 lines
13 KiB
Markdown
# 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:** [`PRD.md`](./PRD.md), [`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.
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **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).
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **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`.
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **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.”
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **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.
|
||
- **Shipped (MVP):** Query-time candidate fetch + in-memory ranking on decrypted text (no separate embed store). Vector pipeline deferred per ADR.
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **4.2 “Generate title” from body**
|
||
- **AC:** One click; user confirms before apply.
|
||
- **Files:** note detail page + small client.
|
||
|
||
- [x] **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.”
|
||
|
||
- [x] **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`.
|
||
|
||
- [x] **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.
|
||
- **Shipped:** Settings documents current limitation; wire-up when platform exposes token APIs.
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **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).
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **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.
|
||
- **Shipped:** `note_versions` snapshots before each title/body PATCH; expandable plaintext in web. Side-by-side diff + agent-action join is follow-up.
|
||
|
||
- [x] **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.
|
||
|
||
- [x] **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.
|
||
- **Shipped:** `public/manifest.json`, `metadata.manifest`, settings offline-queue blurb + verify button. Icons/service worker optional follow-up.
|
||
|
||
---
|
||
|
||
## 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.
|
||
|
||
---
|
||
|
||
## Implementation summary (March 31, 2026)
|
||
|
||
| Area | What shipped |
|
||
|------|----------------|
|
||
| **Web** | `CommandPalette`, editor autosave + quiet saves, dashboard API saved views + onboarding seed CTA, `ExtractedTasksPanel`, context pack copy + workspace `.md` export, hybrid/lexical search UI, `/chat`, note templates, copilot toolbar + suggest title, share link + public `/share/[token]`, `NoteVersionsPanel`, sidebar chat link, settings MCP/offline/token guidance, PWA manifest. |
|
||
| **Backend** | `POST /notes/search`, `POST /notes/chat`, `POST /notes/:id/copilot`, `POST /notes/:id/suggest-title`, `POST /notes/:id/share`, `GET /notes/:id/versions`, version append on PATCH, `POST /workspaces/onboarding-seed`, `GET /api/public/note-shares/:token`, `note_shares` / `note_versions` collections, feature flags, ranking + copilot helpers. |
|
||
| **Docs** | [`DEEP_LINKS.md`](./DEEP_LINKS.md), [`ADR-2026-03-31-hybrid-search-without-embeddings.md`](./roadmaps/ADR-2026-03-31-hybrid-search-without-embeddings.md). |
|
||
|
||
---
|
||
|
||
## Open questions for reviewers
|
||
|
||
1. **Scale:** At what workspace size should hybrid search move from in-memory ranking to a dedicated index or vector store?
|
||
2. **Shares:** Do we need expiry, password, revoke list, and audit export for compliance?
|
||
3. **Platform tokens:** Exact API paths and UI for MCP/CI token lifecycle?
|
||
4. **PWA:** Add maskable icons and an offline service worker (`next-pwa` or equivalent)?
|
||
5. **Copilot output:** Prefer structured ProseMirror JSON from the extraction service instead of escaped HTML paragraphs?
|
||
6. **Telemetry:** Should new events (`note.share_created`, `note.chat_query`, `workspace.onboarding_seeded`, etc.) be registered in a central schema?
|
||
|
||
---
|
||
|
||
## 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 (table fix, meta sections, checkbox maintenance note); companion link to PRD.md. |
|
||
| 2026-03-31 | Full implementation pass: all phases marked complete; summary + reviewer questions. |
|