learning_ai_notes/docs/WEB_AI_FAST_ROADMAP.md

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, AGENT_TASK_ROADMAP.md (agent execution / CI / platform blockers), roadmaps/03_WEB_ROADMAP.md (historical web phases), 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); 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.
  • Shipped (MVP): Query-time candidate fetch + in-memory ranking on decrypted text (no separate embed store). Vector pipeline deferred per ADR.

• 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.
  • Shipped: Settings documents current limitation; wire-up when platform exposes token 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.
  • Shipped: note_versions snapshots before each title/body PATCH; expandable plaintext in web. Side-by-side diff + agent-action join is follow-up.

• 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.
  • 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 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, 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)

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.