# ByteLyst Agentic Notes — Master Roadmap

Version: 2.0
Date: March 10, 2026
Status: Draft
Companion Docs: `docs/PRD.md`

# 1. Purpose

This is the **master execution tracker** for the notes platform.

Use this document to:

- track phase status,
- understand sequencing and dependencies,
- assign workstreams to coding agents,
- link out to smaller roadmap documents with focused execution detail.

Detailed implementation plans live under `docs/roadmaps/`.

# 2. Confirmed Stack

- **Web**
  - Next.js 16
  - React 19
  - TypeScript

- **Backend**
  - Fastify 5
  - TypeScript ESM
  - Zod

- **Mobile MVP**
  - React Native + Expo

- **Shared Services**
  - `platform-service`
  - `extraction-service`
  - `mcp-server`

# 3. Roadmap Document Index

- [ ] `docs/roadmaps/00_MASTER_EXECUTION_PLAN.md`
- [ ] `docs/roadmaps/01_FOUNDATIONS_AND_DECISIONS.md`
- [x] `docs/roadmaps/02_BACKEND_ROADMAP.md`
- [x] `docs/roadmaps/03_WEB_ROADMAP.md`
- [x] `docs/roadmaps/04_MOBILE_ROADMAP.md`
- [x] `docs/roadmaps/05_MCP_AGENT_ROADMAP.md`
- [ ] `docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md`
- [x] `docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md`

# 4. Master Phase Tracker

## Phase 0 — Foundations and Decisions

### Goals

- finalize product identity and product manifest inputs
- choose the single MVP mobile path
- define repo structure and ownership boundaries
- define initial domain objects and module boundaries
- lock reuse strategy against the ByteLyst workspace

### Checklist

- [ ] product name finalized
- [ ] `productId` finalized
- [ ] backend port assigned
- [ ] domain / bundle identifiers assigned
- [ ] token namespace requested
- [ ] mobile path confirmed as React Native MVP
- [ ] repo folder structure finalized
- [ ] initial Cosmos container strategy defined
- [ ] operator vs shared admin boundary defined
- [ ] PRD and roadmap aligned

### Owner Docs

- `docs/roadmaps/00_MASTER_EXECUTION_PLAN.md`
- `docs/roadmaps/01_FOUNDATIONS_AND_DECISIONS.md`

## Phase 1 — Core Product Skeleton

### Goals

- stand up web, backend, and mobile skeletons
- complete auth, app shells, and first persistence layer
- establish notes/workspaces as end-to-end vertical slices

### Checklist

- [x] web app boots with authenticated shell
- [x] backend boots with health and first modules
- [x] mobile app boots with auth and navigation shell
- [ ] notes CRUD works end-to-end
- [ ] workspaces CRUD works end-to-end
- [ ] first telemetry events are flowing

### Owner Docs

- `docs/roadmaps/02_BACKEND_ROADMAP.md`
- `docs/roadmaps/03_WEB_ROADMAP.md`
- `docs/roadmaps/04_MOBILE_ROADMAP.md`
- `docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md`

## Phase 2 — Notes Product MVP

### Goals

- complete human-facing notes product MVP
- add relationships, tasks, artifacts, and useful mobile parity
- harden auditability for meaningful write paths

### Checklist

- [ ] note CRUD complete
- [ ] workspace switching and permissions work
- [ ] note relationships work
- [ ] tasks can be extracted and linked
- [ ] artifact upload/download works
- [ ] mobile quick capture and retrieval are functional
- [ ] audit log exists for important write paths

### Owner Docs

- `docs/roadmaps/02_BACKEND_ROADMAP.md`
- `docs/roadmaps/03_WEB_ROADMAP.md`
- `docs/roadmaps/04_MOBILE_ROADMAP.md`
- `docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md`
- `docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md`

## Phase 3 — Agentic Layer

### Goals

- ship safe MCP tools
- add approval and audit workflows
- support AI-assisted and AI-mediated knowledge flows

### Checklist

- [ ] core MCP tools work end-to-end
- [ ] agent write paths support approval where required
- [ ] audit and review UX is functional
- [ ] extraction-backed workflows have fallback behavior
- [ ] operator workflows are documented

### Owner Docs

- `docs/roadmaps/05_MCP_AGENT_ROADMAP.md`
- `docs/roadmaps/02_BACKEND_ROADMAP.md`
- `docs/roadmaps/03_WEB_ROADMAP.md`
- `docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md`

## Phase 4 — Search and Knowledge Acceleration

### Goals

- make search, retrieval, and context navigation genuinely strong
- support scalable knowledge workflows for humans and agents

### Checklist

- [ ] search is fast and useful
- [ ] linked-note navigation is meaningful
- [ ] retrieval is scoped and explainable
- [ ] search telemetry is measurable
- [ ] web UX supports dense knowledge usage

### Owner Docs

- `docs/roadmaps/02_BACKEND_ROADMAP.md`
- `docs/roadmaps/03_WEB_ROADMAP.md`
- `docs/roadmaps/04_MOBILE_ROADMAP.md`
- `docs/roadmaps/05_MCP_AGENT_ROADMAP.md`
- `docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md`

## Phase 5 — Production Readiness and Release

### Goals

- ensure builds, tests, release flows, and runbooks are stable
- prepare the repo for continued multi-agent execution

### Checklist

- [ ] build/test/release flows documented
- [ ] core smoke tests pass on all chosen surfaces
- [ ] production-readiness checklist passes
- [ ] deferred list documented
- [ ] roadmap status updated after implementation

### Owner Docs

- `docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md`
- all workstream docs

# 5. Parallelization Rules

## Safe Parallel Tracks After Phase 0

- **Agent 1**
  - backend core modules

- **Agent 2**
  - web shell and notes/workspace routes

- **Agent 3**
  - mobile shell and quick capture flows

- **Agent 4**
  - MCP tool schemas and read-only tools

- **Agent 5**
  - platform integrations, telemetry, diagnostics, extraction wiring

- **Agent 6**
  - QA docs, smoke plans, release-readiness docs

## High-Collision Areas

- shared product config files
- root package/dependency manifests
- shared route registration
- top-level navigation/layout files
- shared token/theme entrypoints
- shared auth setup

## Merge Order

- [ ] foundations
- [ ] backend core modules
- [ ] web shell and CRUD flows
- [ ] mobile shell and core flows
- [ ] MCP core tools
- [ ] integrations and enrichments
- [ ] QA hardening and release docs

# 6. Suggested First Sprint

- [ ] finalize product identity and mobile path
- [ ] scaffold `web/`, `mobile/`, and `backend/`
- [x] implement backend `notes` and `workspaces`
- [x] build web authenticated shell and note list/detail pages
- [x] build mobile shell and quick capture
- [x] define MCP tool schemas for list/get/search/create-draft
- [ ] wire telemetry, diagnostics, and extraction clients

# 7. Definition of Done

- [ ] web app supports real end-to-end note workflows
- [ ] mobile app supports meaningful capture/retrieval for MVP
- [ ] backend modules are tested and production-shaped
- [ ] MCP tools exist for core note workflows
- [ ] shared platform integrations are stable
- [ ] roadmap, PRD, and build/test commands are aligned
- [ ] release readiness is documented and repeatable

# 8. Progress Notes

- 2026-03-10 — Web workstream materially advanced:
  - `learning_ai_notes/web/` was scaffolded from scratch
  - authenticated shell and core route surfaces now exist
  - dashboard, workspaces, note detail, search, settings, and error states are implemented with mock data
  - the web roadmap is now tracking real implementation state instead of draft-only planning
- 2026-03-10 — Backend workstream materially advanced:
  - `learning_ai_notes/backend/` was scaffolded from scratch
  - Fastify 5 + TypeScript ESM service bootstrap now exists with shared `@bytelyst/*` package wiring
  - `/health` and readiness-capable service bootstrap were added via `@bytelyst/fastify-core`
  - `notes`, `workspaces`, `note-relationships`, `note-tasks`, `note-artifacts`, and `note-agent-actions` modules now exist with schemas, repositories, routes, and starter tests
  - explicit `/notes/search` support now exists in the backend
  - product bootstrap identity currently uses provisional values pending final product naming and manifest alignment
- 2026-03-10 — Web/backend verification materially advanced:
  - `web/` dependencies are now installed
  - `web` `npm run typecheck` passes
  - `web` `npm run build` passes after fixing the auth `BaseUser` shape and guarding demo session init from server-side `localStorage`
  - `backend/` dependencies are now installed
  - `backend` `npm run typecheck` passes after normalizing Fastify type boundaries for `file:` workspace deps
  - `backend` `npm test` passes after fixing hoisted Vitest mock patterns and stale route registration count assertions
- 2026-03-10 — Web operator/search density materially advanced:
  - saved views are now represented across dashboard, workspaces, and search
  - search results now expose a denser operational layout with status, owner, and workspace metadata
  - operator workflow summary surfaces now exist on dashboard and reviews
  - workspace cards now expose ownership context for denser navigation
  - `web/` verification passed again after wiring the richer saved-view/search/operator workflow slice (`npm run typecheck`, `npm test`, `npm run build`)
- 2026-03-10 — MCP design work materially advanced:
  - product-side MCP core tool contracts now exist under `backend/src/mcp/`
  - namespace, role gating, read-only vs mutating classification, workspace scoping, and dry-run/idempotency/correlation expectations are now encoded for the first core tool set
- 2026-03-10 — MCP execution and registration materially advanced:
  - product-side executable note MCP tools now exist for list/get/search/create-draft
  - the mutating create-draft path now records a `note-agent-actions` audit/proposal document
  - product-side MCP note tools now export through a registration adapter compatible with the shared `mcp-server` tool model
  - backend typecheck passes and backend tests pass with MCP execution coverage included
- 2026-03-10 — Mobile workstream materially advanced:
  - `learning_ai_notes/mobile/` was scaffolded from scratch
  - Expo + TypeScript root config and Expo Router entrypoints now exist
  - auth shell, tab navigation, home/recent notes, search, quick capture, inbox, and note detail surfaces now exist
  - shared mobile wiring now exists for auth, platform client, offline queue, token-based theme usage, and first-pass Zustand stores
  - mobile currently uses provisional product config values and fallback note/workspace data pending final identity and contract alignment
- 2026-03-10 — Mobile utility materially advanced:
  - home/search/capture are workspace-aware, and home exposes a retrieval summary surface
  - capture exposes offline queue readiness details for the scaffold
  - note detail supports lightweight local editing, artifact summary, and first-pass loading polish
  - inbox supports simple approval/reject flows plus a lightweight activity feed
- 2026-03-10 — Mobile verification materially advanced:
  - mobile dependencies now install successfully with corrected sibling `@bytelyst/*` package paths
  - `npm run typecheck`, `npm run lint`, and `npm test` now pass in `learning_ai_notes/mobile/`
  - token-backed placeholder and border colors replaced the remaining raw hardcoded mobile color fallbacks

# 9. Current Known Blockers / Deferrals

- **Blocker**
  - Product identity and backend contract details are still not finalized in the planning docs, so the web app currently uses provisional config values and mock data.
- **Blocker**
  - `@bytelyst/react-native-platform-sdk` is part of the intended mobile architecture, but the current workspace package does not appear ready for direct runtime consumption in this app yet.
- **Deferred**
  - Real CRUD wiring
  - Artifacts
  - Approval/review/audit UX
  - Persisted saved views, keyboard shortcut expansion, and deeper performance hardening