learning_ai_notes/docs/AGENT_TASK_ROADMAP.md

NoteLett — Agent Task Roadmap

Date: March 29, 2026 Product: NoteLett (notelett) — Structured notes for humans + AI agents Repo: learning_ai_notes Stack: Fastify 5 backend (port 4016) · Next.js 16 web (port 3000) · Expo mobile Platform deps: 23 @bytelyst/* packages (all resolve against learning_ai_common_plat)

---

Current State

Surface	Routes / Modules	Tests	Build	Platform Pkgs
Backend	7 modules, ~32 endpoints, 8 MCP tools	20 files (unit + integration)	✅ tsc	13 (all used)
Web	6 pages, 13 components, 15 lib files	7 unit + 7 E2E	✅ next build	10 (all used)
Mobile	4 tabs, note detail, auth, 5 stores	23 tests (4 files)	✅ typecheck	—

All @bytelyst/* dependencies exist in learning_ai_common_plat and resolve correctly.

---

Phase 1 — Critical Web Gaps

These block the web app from being usable by real users.

• 1.1 Add auth pages — login, register, forgot-password

  • Create web/src/app/(auth)/login/page.tsx, register/page.tsx, forgot-password/page.tsx
  • Wire to existing @bytelyst/react-auth config in web/src/lib/auth.ts
  • Include form validation, error states, loading states
  • Files: new pages under web/src/app/(auth)/

• 1.2 Add middleware.ts for route protection

  • Redirect unauthenticated users from (app)/* routes to /login
  • Redirect authenticated users from /login to /dashboard
  • Check kill-switch status (call checkKillSwitch() from web/src/lib/kill-switch.ts)
  • File: web/src/middleware.ts

• 1.3 Replace plain textarea with a rich note editor

  • Current NoteEditor.tsx is a bare <textarea> — inadequate for a notes product
  • Add markdown support (headings, bold, italic, lists, code blocks) at minimum
  • Consider Tiptap, Lexical, or MDXEditor
  • File: web/src/components/NoteEditor.tsx

• 1.4 Add workspace CRUD from web

  • Backend already has POST /workspaces and PATCH /workspaces/:id
  • Add create-workspace modal/form on the workspaces page
  • Add edit/delete actions on workspace cards
  • Files: web/src/app/(app)/workspaces/page.tsx, new modal component

• 1.5 Wire toast notifications

  • ToastProvider from @bytelyst/ui is mounted but zero toasts are triggered
  • Replace window.confirm() calls with a confirmation dialog component
  • Add success/error toasts after note create, update, archive, link, task create, artifact create
  • Files: all page files + components that do mutations

Verification:

cd web && pnpm run typecheck && pnpm test && pnpm run build

---

Phase 2 — Backend Hardening

• 2.1 Add integration tests for all route modules using buildTestApp() + Fastify .inject()

  • Current route tests only check handler registration counts
  • Need real request/response tests: happy path, validation errors, auth enforcement, 404s
  • Modules needing inject tests: notes, workspaces, note-relationships, note-tasks, note-artifacts, note-agent-actions, saved-views
  • Files: backend/src/modules/*/routes.integration.test.ts (7 new files)

• 2.2 Add DELETE endpoints for notes, workspaces, tasks, artifacts, relationships

  • Currently only saved-views has DELETE
  • Notes support archive but not hard delete — add soft-delete with a deletedAt timestamp
  • Files: backend/src/modules/*/routes.ts + repository.ts

• 2.3 Enforce role-based access on REST routes

  • requireRole is exported and tested but not used on any REST route
  • At minimum: write routes (POST/PATCH/DELETE) should require editor or admin role
  • File: every routes.ts file

• 2.4 Enforce workspace member authorization

  • workspace.members array is stored but never checked
  • Note CRUD should verify the requesting user is a member of the target workspace
  • Files: backend/src/modules/notes/routes.ts, backend/src/modules/workspaces/repository.ts

• 2.5 Activate telemetry — call trackEvent() on key business actions

  • Buffer and flush infrastructure exist but no route handler actually calls trackEvent()
  • Track: note.created, note.updated, note.archived, note.searched, workspace.created, agentAction.approved, agentAction.rejected
  • Files: all routes.ts files + backend/src/lib/telemetry.ts

• 2.6 Activate feature flags in route logic

  • 6 flags registered with defaults but no route checks isFeatureEnabled()
  • At minimum: gate MCP write tools behind mcp.enabled, gate export behind a flag
  • Files: backend/src/lib/feature-flags.ts, relevant route files

Verification:

cd backend && pnpm run typecheck && pnpm test

---

Phase 3 — Web UX Polish

• 3.1 Add pagination to all list views

  • Backend already returns total, limit, offset — web ignores them and fetches everything
  • Add pagination controls to: notes list, workspaces list, search results, review queue, saved views
  • Files: all page files under web/src/app/(app)/

• 3.2 Fix getNoteDetail — use GET /notes/:id instead of fetching all notes

  • File: web/src/lib/notes-client.ts line ~291

• 3.3 Fix listApprovalQueue N+1 — add backend cross-workspace pending-actions endpoint

  • Currently fetches all workspaces, then all actions per workspace
  • Add GET /note-agent-actions/pending (already exists) usage in web client
  • Files: web/src/lib/review-client.ts

• 3.4 Add skeleton loading states per section (not just global spinner)

  • File: new Skeleton.tsx component + integration in each page

• 3.5 Add file upload UI for artifacts

  • blob-client.ts supports uploadArtifact() but no component triggers it
  • Add file picker + upload progress to ArtifactPanel
  • File: web/src/components/ArtifactPanel.tsx

• 3.6 Remove dead code

  • Delete web/src/lib/mock-data.ts (228 lines, zero imports)
  • Delete web/src/lib/review-data.ts (46 lines, zero imports)
  • Remove zustand and zod from web package.json (declared, never imported)

• 3.7 Fix SSR crash risk — lazy-init module-scope API clients

  • extraction-client.ts and blob-client.ts instantiate clients at module scope
  • Apply lazy singleton pattern (init on first call, not on import)
  • Add "use client" to notes-client.ts or refactor extraction-client
  • Files: web/src/lib/extraction-client.ts, web/src/lib/blob-client.ts, web/src/lib/notes-client.ts

• 3.8 Consolidate duplicate type definitions

  • NoteAgentActionDoc, NoteDoc, etc. duplicated across notes-client.ts, review-client.ts, extraction-client.ts
  • Move to web/src/lib/types.ts and import from there
  • Files: web/src/lib/types.ts + all client files

Verification:

cd web && pnpm run typecheck && pnpm test && pnpm run build

---

Phase 4 — MCP & AI Enrichment

• 4.1 Wire MCP tool registration to shared mcp-server

  • MCP_SERVER_URL=http://localhost:4007 is configured but no outbound call exists
  • Backend exposes tools via register-note-tools.ts — need HTTP client to register them with the shared MCP server at startup
  • File: backend/src/server.ts or new backend/src/lib/mcp-registration.ts

• 4.2 Add note summarization to web UI

  • Backend POST /notes/:id/summarize already works via extraction-service
  • Add "Summarize" button to note detail page that calls the endpoint and shows the result
  • Files: web/src/app/(app)/notes/[noteId]/page.tsx, web/src/lib/notes-client.ts

• 4.3 Add note export UI

  • Backend GET /notes/export already supports JSON and Markdown formats
  • Add "Export" button to dashboard or workspace pages
  • Files: web/src/app/(app)/dashboard/page.tsx or workspaces page

Verification:

cd backend && pnpm run typecheck && pnpm test
cd web && pnpm run typecheck && pnpm test && pnpm run build

---

Phase 5 — DevOps & CI

• 5.1 Enable CI workflow

  • .github/workflows/ci.yml.disabled exists and is fully written
  • Review, update if needed, rename to ci.yml
  • File: .github/workflows/ci.yml

• 5.2 Fix Docker Compose platform-service reference

  • docker-compose.yml references localhost:4003 and localhost:4005 but doesn't define those services
  • Either add platform-service and extraction-service as services, or document that they must be run separately
  • File: docker-compose.yml

• 5.3 Add .env.example missing variables

  • NEXT_PUBLIC_EXTRACTION_SERVICE_URL and NEXT_PUBLIC_PLATFORM_SERVICE_ORIGIN are used in code but missing from .env.example
  • File: web/.env.example

Verification:

docker compose build
docker compose up -d && curl http://localhost:4016/api/bootstrap

---

Phase 6 — Docs Alignment

• 6.1 Update docs/ROADMAP.md phase checklists

  • Many Phase 0–3 items remain unchecked despite being implemented (per progress notes in §8)
  • File: docs/ROADMAP.md

• 6.2 Update AGENTS.md with current test counts and any new endpoints added in this roadmap

• 6.3 Update README.md with current quick-start that reflects real auth and data flow

---

Task Summary

Phase	Tasks	Priority	Est. Effort
1 — Critical Web Gaps	5	HIGH	6–8 hours
2 — Backend Hardening	6	HIGH	5–7 hours
3 — Web UX Polish	8	MEDIUM	4–6 hours
4 — MCP & AI	3	MEDIUM	2–3 hours
5 — DevOps & CI	3	MEDIUM	1–2 hours
6 — Docs	3	LOW	1 hour
Total	28		19–27 hours

---

Verification Commands (run after each phase)

# Backend
cd backend && pnpm run typecheck && pnpm test && pnpm run build

# Web
cd web && pnpm run typecheck && pnpm test && pnpm run build

# Mobile
cd mobile && pnpm run typecheck && pnpm test

# E2E
cd web && pnpm exec playwright test