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:**
```bash
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

- [x] **0.5.1** Replace broken `@bytelyst/ui` ToastProvider with `sonner` — [`7babee7`](https://github.com/saravanakumardb1/learning_ai_notes/commit/7babee7)
- [x] **0.5.2** Adopt `@bytelyst/dashboard-components` (ErrorPage, NotFoundPage, LoadingSpinner) — [`7babee7`](https://github.com/saravanakumardb1/learning_ai_notes/commit/7babee7)
- [x] **0.5.3** Replace raw `extraction-client.ts` with `@bytelyst/extraction` — [`7babee7`](https://github.com/saravanakumardb1/learning_ai_notes/commit/7babee7)

---

## Phase 1 — Critical Web Gaps

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

- [x] **1.1** Add auth pages — login, register, forgot-password — [`839218a`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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)/`

- [x] **1.2** Add `middleware.ts` for route protection — [`839218a`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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`

- [x] **1.3** Replace plain textarea with a rich note editor — [`839218a`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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`

- [x] **1.4** Add workspace CRUD from web — [`839218a`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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

- [x] **1.5** Wire toast notifications — [`839218a`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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

- [x] **2.1** Add integration tests for all route modules (already complete) — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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)

- [x] **2.2** Add DELETE endpoints for notes, workspaces, tasks, artifacts, relationships — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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`

- [x] **2.3** Enforce role-based access on REST routes — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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

- [x] **2.4** Enforce workspace member authorization — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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`

- [x] **2.5** Activate telemetry — call `trackEvent()` on key business actions — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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`

- [x] **2.6** Activate feature flags in route logic — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/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
  - 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)

```bash
# 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
```