learning_ai_notes/docs/AGENT_TASK_ROADMAP.md

NoteLett — Agent Task Roadmap

Date: March 31, 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 (5 missing source in common_plat)
Web	6 pages, 13 components, 15 lib files	7 unit + 7 E2E	✅ next build	10 (all used)
Mobile	5 tabs incl. settings, note detail, auth (+ register + session-aware index), kill-switch gate, broadcast + survey in root layout, feedback on settings, auth-gated store hydrates + broadcast/survey polling, offline queue flush (after auth, boot + foreground), flushTelemetry on background, app-metadata for telemetry versions, Vitest RN mocks + component smokes (auth, home, settings), 5 stores	33 tests (7 files)	✅ typecheck	Direct @bytelyst/* clients (+ optional future RN platform SDK)

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.

Mobile — sequential handoff

For ordered mobile implementation (Expo app under mobile/), use MOBILE_DELEGATION_ROADMAP.md — blocks, file pointers, and acceptance criteria in one place. Update the Current State table above when mobile capabilities change materially.

Mobile — remaining gaps (March 2026 review)

Shipped: Session-aware index, register, kill-switch UI, broadcast/survey, feedback, offline queue, app-metadata, auth-gated hydrates (notes/workspaces/inbox + polling only when isAuthenticated), flushTelemetry() on background, settings smoke test, capture → blob-upload comment.

Still open (see MOBILE_DELEGATION_ROADMAP.md § Remaining / deferred):

1. Deeper RNTL — fireEvent / richer assertions (Block H TODO in delegation doc).
2. Optional — @bytelyst/react-native-platform-sdk alignment with NomGap (A §A.3).
3. Optional — @bytelyst/sync (Block I).

---

Phase 0 — Missing Platform Package Source (SHARED BLOCKER)

These 5 backend packages are depended on by both NoteLett and NomGap but have no source directory in learning_ai_common_plat/packages/. They must be created there before either product's backend can be built from a clean checkout of common_plat.

• 0.1 Create @bytelyst/backend-config in learning_ai_common_plat/packages/backend-config/

  • Base Zod config schema extended by all product backends
  • Imported by: backend/src/lib/config.ts

• 0.2 Create @bytelyst/backend-flags in learning_ai_common_plat/packages/backend-flags/

  • Feature flag registry for backend services
  • Imported by: backend/src/lib/feature-flags.ts

• 0.3 Create @bytelyst/backend-telemetry in learning_ai_common_plat/packages/backend-telemetry/

  • Buffered telemetry event tracking for backends
  • Imported by: backend/src/lib/telemetry.ts

• 0.4 Create @bytelyst/fastify-auth in learning_ai_common_plat/packages/fastify-auth/

  • JWT auth middleware (RS256 JWKS + HS256 fallback), extractAuth, requireRole, createRequestContext
  • Imported by: backend/src/lib/auth.ts, backend/src/lib/request-context.ts, all route modules

• 0.5 Create @bytelyst/field-encrypt in learning_ai_common_plat/packages/field-encrypt/

  • Field-level encryption/decryption with AKV/env/memory key providers
  • Imported by: backend/src/lib/field-encrypt.ts, backend/src/modules/notes/repository.ts

Note: These tasks require changes in learning_ai_common_plat, not in this repo. Coordinate with the common platform agent. NomGap also depends on all 5 of these.

Verification:

cd ../learning_ai_common_plat && pnpm run build
cd ../learning_ai_notes/backend && pnpm install && pnpm run typecheck

---

Phase 0.5 — Fix Broken Imports + Adopt Dashboard Components

• 0.5.1 Replace broken @bytelyst/ui ToastProvider with sonner — 7babee7
• 0.5.2 Adopt @bytelyst/dashboard-components (ErrorPage, NotFoundPage, LoadingSpinner) — 7babee7
• 0.5.3 Replace raw extraction-client.ts with @bytelyst/extraction — 7babee7

---

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 — 839218a

  • 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 — 839218a

  • 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 — 839218a

  • 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 — 839218a

  • 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 — 839218a

  • 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 (already complete) — 8d84bcb 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 — 8d84bcb

  • 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 — 8d84bcb

  • 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 — 8d84bcb

  • 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 — 8d84bcb

  • 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 — 8d84bcb

  • 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 — a5b0a89

  • 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 — a5b0a89

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

• 3.3 Fix listApprovalQueue N+1 (already uses /note-agent-actions/pending) — a5b0a89

  • 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 via @bytelyst/dashboard-components — 7babee7

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

• 3.5 Add file upload UI for artifacts — a5b0a89

  • 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 unused dependencies (zustand, zod) — a5b0a89

  • Remove zustand and zod from web package.json (declared, never imported anywhere in web/src/)

• 3.7 Fix SSR crash risk — lazy-init already applied — 7babee7

  • 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 (already in types.ts) — a5b0a89

  • 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 — New Common Platform Integrations

• 4.1 Add @bytelyst/feedback-client — feedback button in settings page — 02bcb0d
• 4.2 Add @bytelyst/broadcast-client — BroadcastBanner in app layout — 02bcb0d
• 4.3 Add @bytelyst/survey-client — SurveyBanner in app layout — 02bcb0d
• 4.4 Add @bytelyst/offline-queue — persistent retry queue, flush on boot — 02bcb0d
• 4.5 Revamp settings page — profile, password, sign out, feedback form, danger zone — 02bcb0d
• 4.6 Register NoteLett tools in shared MCP server (10 tools: notes CRUD, workspaces, tasks, artifacts, summarize) — 6997dff

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 GitHub Actions CI workflow with lint steps — 02bcb0d
• 5.2 Fix docker-compose.yml — add all env vars (PRODUCT_ID, MCP, telemetry, encryption, correct branding) — 02bcb0d
• 5.3 Fix web/.env.example — correct branding to NoteLett/notelett, add EXTRACTION_SERVICE_URL — 02bcb0d

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
0 — Missing Platform Packages	5	CRITICAL	4–6 hours (in common_plat)
1 — Critical Web Gaps	5	HIGH	6–8 hours
2 — Backend Hardening	6	HIGH	5–7 hours
3 — Web UX Polish	7	MEDIUM	4–5 hours
4 — MCP & AI	3	MEDIUM	2–3 hours
5 — DevOps & CI	3	MEDIUM	1–2 hours
6 — Docs	3	LOW	1 hour
Total	32		23–32 hours

Phase 0 must be done first — it requires changes in learning_ai_common_plat and unblocks both NoteLett and NomGap backends.

---

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