# 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. |