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 (5 missing source in common_plat)
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	—

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.

---

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 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 unused dependencies

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

• 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 Review and enable CI workflows

  • Gitea CI (.gitea/workflows/ci.yml) is already active
  • GitHub Actions (.github/workflows/ci.yml.disabled) exists but is disabled — review, update, rename to ci.yml if GitHub is the target
  • Files: .github/workflows/ci.yml, .gitea/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 Fix web/.env.example

  • Bug: Product identity is stale — shows NEXT_PUBLIC_PRODUCT_NAME=ByteLyst Agentic Notes and NEXT_PUBLIC_PRODUCT_ID=agentic-notes instead of NoteLett / notelett
  • Missing vars: NEXT_PUBLIC_EXTRACTION_SERVICE_URL and NEXT_PUBLIC_PLATFORM_SERVICE_ORIGIN are used in code but not listed
  • 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
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