learning_ai_notes/docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md

NoteLett Production Readiness Handoff Roadmap

Date: May 5, 2026 Repo: learning_ai_notes Common platform repo: ../learning_ai/learning_ai_common_plat Status: Ready for incremental implementation

Purpose

Use this document as the source of truth for finishing NoteLett end to end and making it production ready. It reconciles the existing product roadmaps, current code, and the reusable capabilities in learning_ai_common_plat.

The implementation rule is simple: complete one checklist item or one small cluster at a time, run the stated verification, commit with the repo convention, push, and record the commit hash in this document before moving on.

Current Baseline

This baseline is from repo inspection on May 5, 2026.

Area	Current state
Backend	Fastify 5 product backend with notes, workspaces, relationships, tasks, artifacts, agent actions, saved views, prompts, intake, collaborators, shares, versions, Palace integration, MCP tools, Cosmos registration
Web	Next.js 16 App Router with auth routes, dashboard, workspaces, search, reviews, note detail, prompts/intake/settings, shared clients, E2E specs
Mobile	Expo app with auth, tabs, note/capture/intake/prompt flows, stores, shared platform clients, MMKV persistence
Tests present	67 local test/spec files: 42 backend, 24 web including 9 E2E specs, 10 mobile
DevOps present	backend/Dockerfile, web/Dockerfile, docker-compose.yml, GitHub Actions CI, docker prep script
Common platform packages present	backend-config, backend-flags, backend-telemetry, fastify-auth, field-encrypt, palace, blob-client, extraction, dashboard-components, react-native-platform-sdk, sync, and other @bytelyst/* packages exist in common platform

Critical Observations

• Several older docs are stale. For example, docs/AGENT_TASK_ROADMAP.md still says common-platform backend package sources are missing, but those package directories now exist in learning_ai_common_plat/packages/.
• docs/ROADMAP.md, AGENTS.md, and older gap docs under docs/ disagree on implemented status, test counts, endpoints, and platform integration maturity.
• Web has many hardcoded hex/RGBA colors and fallback values in app/component styles. This conflicts with the project rule that colors come from --nl-* tokens and @bytelyst/design-tokens.
• Mobile still has hardcoded colors in a few screens, especially provider/intake labels and button text. These should move to NoteLettTheme or shared token-derived mappings.
• Backend startup still writes Cosmos init messages through process.stdout / process.stderr; production paths should use app.log or shared logger patterns.
• Backend config has development-friendly defaults (DB_PROVIDER=memory, default JWT secret, telemetry/flags off). Production must fail closed unless explicitly configured.
• Web MCP defaults are aligned by P2.1 to the common-platform mcp-server on port 4007.
• CI currently covers backend and web lint/typecheck/test/build, and mobile typecheck. It should also run mobile tests, web E2E where practical, Docker builds, and shared platform smoke checks.
• The repo uses many common platform packages already, but production readiness should verify runtime behavior against platform-service, extraction-service, blob, telemetry, diagnostics, flags, kill switch, and MCP rather than only checking dependencies.

Non-Negotiable Implementation Rules

• Do not edit .npmrc directly. Sync from ../learning_ai_common_plat/scripts/npmrc.template if needed.
• Do not move NoteLett domain logic into common platform unless another product has a concrete reuse need.
• Do not add repo-local substitutes for platform concerns already covered by @bytelyst/* packages or platform-service.
• Do not hardcode colors in web or mobile product code. Use --nl-* CSS variables, @bytelyst/design-tokens, or NoteLettTheme.
• Do not use console.log or raw stdout/stderr in production backend code. Use req.log, app.log, or shared logger wrappers.
• Do not change tests just to pass. Fix the implementation.
• Every production Cosmos document must include productId: PRODUCT_ID.
• Keep every implementation commit small enough to review independently.

Handoff Prompt For Codex Desktop

Use this one-liner to start implementation:

In /Users/saravana/BytelystAI/learning_ai_notes, implement docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md one checklist item at a time. For each item: inspect current code, make the minimal production-quality change, run the listed verification, commit with type(scope): description, push, then update the roadmap row with the commit hash and any verification notes before moving to the next item. Fully leverage /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat for platform concerns.

Use this shorter resume prompt after interruptions:

Resume docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md from the first unchecked item, preserve prior work, commit/push each completed item, and record the commit hash plus verification notes in the roadmap.

Commit Tracking Format

After each completed item, update that checklist row:

- [x] **P1.1** Task title — Commit: `abc1234`; Verified: `pnpm --filter ...`

If an item is intentionally deferred:

- [ ] **P1.1** Task title — Deferred: reason, owner, date

Phase P0 — Verify Baseline Before Changes

Goal: establish a trustworthy starting point and avoid implementing against stale assumptions.

• P0.1 Run git status --short and confirm the worktree is clean or identify user-owned changes. Commit: fa30191; Verified: git status --short --branch returned ## main...origin/main with no modified or untracked files before production-readiness edits began.
• P0.2 Run pnpm install --frozen-lockfile if dependencies are not installed. Commit: 282bb8d; Verified: repaired stale common-platform workspace path from ../learning_ai_common_plat/packages/* to ../learning_ai/learning_ai_common_plat/packages/*, refreshed pnpm-lock.yaml against the local common-platform checkout, then GITEA_NPM_TOKEN=dummy pnpm install --frozen-lockfile passed. Notes: pnpm reported existing peer/build-script warnings for common-platform Azure Cosmos/Expo packages; these are baseline observations for later hardening.
• P0.3 Run baseline checks: pnpm run typecheck, pnpm run test, and pnpm run build. Commit: 5c02ce4; Verified: all three commands were run. Result: baseline failure. pnpm run typecheck and pnpm run build fail in @notelett/backend TypeScript compilation; pnpm run test runs 30 backend files and 171 tests successfully, then fails 12 backend suites during collection. Primary failure family: NoteLett Palace/embedding/prompt code is out of sync with the local learning_ai_common_plat @bytelyst/palace and @bytelyst/llm package APIs. Full failure inventory is tracked in P0.5 before fixes.
• P0.4 Run targeted lint checks: pnpm --filter @notelett/backend run lint, pnpm --filter @notelett/web run lint, and pnpm --filter @notelett/mobile run lint. Commit: b469d16; Verified: all three lint commands were run independently. Result: baseline failure. Backend lint fails before analysis because backend/eslint.config.js cannot resolve @eslint/js; web lint reports 16 errors and 4 warnings, mostly React compiler rules (react-hooks/set-state-in-effect, react-hooks/refs, react-hooks/immutability) plus unused-symbol warnings; mobile lint reports 1 error (import/no-unresolved for @bytelyst/billing-client) and 16 warnings.
• P0.5 Record any baseline failures in this document before fixing them. Commit: 45b16d9; Verified: baseline failures from P0.2-P0.4 are recorded below before any production-readiness fixes were attempted.

Baseline failure inventory from May 5, 2026:

Failure	Evidence	Owner task
Dependency install depended on stale local registry behavior before repair	Initial pnpm install --frozen-lockfile failed with ECONNREFUSED for http://localhost:3300/api/packages/bytelyst/npm/...; P0.2 repaired the stale common-platform workspace path and refreshed the lockfile.	P2.2/P8.5 should document and automate local common-platform package resolution and registry expectations.
Root typecheck fails in backend	pnpm run typecheck stops in @notelett/backend; errors include missing/changed @bytelyst/palace entry/types, removed or changed @bytelyst/llm helpers (embed, buildVisionMessage, hasVisionContent), and NoteLett Palace domain types drifting from common-platform package types.	P2.7/P5.4 should align backend AI/Palace integration with current common-platform APIs and add regression tests.
Root tests fail during backend collection	pnpm run test passes 30 backend files and 171 tests, then fails 12 backend suites because Vite cannot resolve @bytelyst/palace from Palace/embedding/prompt modules.	P2.7/P5.4 should restore package entry resolution and test coverage for Palace, embeddings, prompts, MCP, and scheduler paths.
Root build fails in backend	pnpm run build fails with the same TypeScript errors as typecheck before web build runs.	P2.7/P5.4 should be complete before final P10 verification.
Backend lint cannot start	pnpm --filter @notelett/backend run lint fails because backend/eslint.config.js cannot resolve @eslint/js.	P8.1/P8.5 should normalize lint dependencies and CI lint coverage.
Web lint fails	pnpm --filter @notelett/web run lint reports 16 errors and 4 warnings, primarily React compiler lint rules around synchronous effect state updates/ref writes plus several unused symbols.	P4.3/P6.3 should fix interactive/client robustness while preserving behavior.
Mobile lint fails	pnpm --filter @notelett/mobile run lint reports 1 unresolved import error for @bytelyst/billing-client and 16 warnings.	P2.5/P7.4/P8.1 should align shared mobile clients and lint coverage.
Baseline install warnings remain	Frozen install now passes, but pnpm reports common-platform Azure Cosmos peer warnings, Expo/React Native peer warnings, and ignored build scripts for esbuild, sharp, and unrs-resolver.	P2.2/P8.6 should document or resolve dependency health expectations.

Acceptance criteria:

• The next implementer knows exactly what passed before production-readiness edits began.
• Any baseline failure has a named owner task in a later phase.

Phase P1 — Documentation Truth Alignment

Goal: remove roadmap drift so agents do not chase already completed or obsolete work.

• P1.1 Reconcile docs/ROADMAP.md with actual implemented status for product identity, ports, CRUD, tests, Docker, CI, MCP, Smart Actions, intake, Palace, and platform integrations. Commit: 3553b6e; Verified: git diff --check; roadmap now reflects NoteLett identity, port 4016, implemented CRUD/MCP/review/search/mobile/platform surfaces, and the active May 5 Palace/LLM/lint/smoke blockers instead of March draft checkboxes.
• P1.2 Update AGENTS.md with current module list, endpoint list, test counts, route modules, containers, shared packages, and verification commands. Commit: 99efad8; Verified: git diff --check; AGENTS now points at the active production-readiness roadmap, the correct common-platform path, current backend/web/mobile modules, 14 API route modules, expanded endpoint/container lists, current test inventory, lint/E2E commands, and the May 5 baseline failure note.
• P1.3 Update README.md quick start with required common-platform services, auth expectations, Docker path, local memory mode, and production env requirements. Commit: 014b098; Verified: git diff --check; README now documents the local common-platform checkout, platform/extraction/MCP ports, memory-mode command, Docker compose smoke path, auth expectations, production env requirements, and current baseline caveat.
• P1.4 Mark stale docs/GAP_ANALYSIS.md, docs/AGENT_TASK_ROADMAP.md, and older reuse roadmaps as historical or reconcile their open items with this roadmap. Commit: 6307c60; Verified: git diff --check; added historical/superseded banners to the March gap analysis, agent task roadmap, architecture review, and reuse alignment roadmaps, including a correction that the common-platform backend package-source blocker is stale.
• P1.5 Add a concise architecture boundary section: product-local NoteLett logic versus common platform responsibilities. Commit: 8798fdd; Verified: git diff --check; README and AGENTS now document product-local NoteLett domain ownership versus common-platform responsibilities and warn against premature extraction or repo-local platform substitutes.

Acceptance criteria:

• No active roadmap says common-platform packages are missing when they exist.
• AGENTS.md, README.md, and docs/ROADMAP.md agree on current state.
• This document remains the active production-readiness checklist.

Phase P2 — Common Platform Runtime Alignment

Goal: prove that NoteLett is using common platform services and packages at runtime, not just declaring dependencies.

• P2.1 Align MCP URL defaults and examples across web/src/lib/product-config.ts, web/.env.example, settings copy, Docker env, and docs. Use common platform mcp-server port 4007 unless the shared server exposes a different production route. Commit: da3129c; Verified: legacy MCP port audit returned no matches outside git history, and rg "NEXT_PUBLIC_MCP_SERVER_URL|MCP_SERVER_URL" web README.md docker-compose.yml docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md shows web default/env/settings/Docker now use http://localhost:4007/api, matching common-platform mcp-server tool routes.
• P2.2 Add or update platform smoke documentation for platform-service, extraction-service, mcp-server, telemetry, diagnostics, flags, kill switch, blob, and NoteLett backend health. Commit: 85b682a; Verified: git diff --check; added docs/PLATFORM_SMOKE_CHECKS.md covering common-platform startup, env, unauthenticated health, telemetry, diagnostics, flags/kill switch, blob SAS, extraction, MCP registry/call, NoteLett backend health/bootstrap/diagnostics, and result recording.
• P2.3 Add a local smoke script or extend existing scripts to check GET /health, GET /api/bootstrap, platform dependencies, and one authenticated product-backend flow in memory mode. Prefer reusing common platform smoke/self-test conventions. Commit: a2053a7; Verified: bash -n scripts/local-smoke.sh; GITEA_NPM_TOKEN=dummy pnpm run smoke:local -- --skip-platform; git diff --check. Added pnpm run smoke:local with common-platform @bytelyst/palace/@bytelyst/llm linked-build guards, NoteLett health/bootstrap checks, platform-service/extraction-service/mcp-server health checks, local access-token generation matching shared @bytelyst/fastify-auth, and authenticated workspace/note create/read cleanup in DB_PROVIDER=memory. Local Docker is unavailable (docker: command not found), so the live run skipped platform health while retaining those checks for environments with common-platform services running.
• P2.4 Verify web and mobile shared clients propagate product identity, auth token, and request IDs where supported by common platform clients. Add tests where behavior is local. Commit: efa2097; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/web exec vitest run src/lib/api-helpers.test.ts src/lib/platform.test.ts; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/mobile exec vitest run src/api/client.test.ts src/lib/platform-api.test.ts; git diff --check. Added local web/mobile tests proving product API clients send x-product-id, bearer auth, and shared @bytelyst/api-client request IDs, and proving platform-client wrappers are configured with NoteLett product identity plus auth-token accessors.
• P2.5 Decide whether mobile should adopt @bytelyst/react-native-platform-sdk now or explicitly defer it. If adopted, replace redundant local composition; if deferred, document why direct clients are still preferred. Commit: bea7579; Verified: git diff --check; rg -n "react-native-platform-sdk|direct shared-client|MOBILE_PLATFORM_SDK_DECISION|Mobile Platform SDK Decision" docs/ROADMAP.md docs/MOBILE_DELEGATION_ROADMAP.md docs/roadmaps/04_MOBILE_ROADMAP.md docs/MOBILE_PLATFORM_SDK_DECISION.md. Deferred direct SDK adoption in docs/MOBILE_PLATFORM_SDK_DECISION.md because current mobile already uses direct shared @bytelyst/* clients and the SDK does not yet cover product-backend API calls, blob uploads, diagnostics metadata, billing, feedback, offline queue, or the existing MMKV auth-client token contract without duplicate initialization.
• P2.6 Decide whether @bytelyst/sync should back mobile offline/sync behavior now or be deferred. Record the decision and update implementation accordingly. Commit: f90f358; Verified: git diff --check; rg -n "@bytelyst/sync|MOBILE_SYNC_DECISION|Mobile Sync Decision|offline-queue" docs/MOBILE_SYNC_DECISION.md docs/MOBILE_DELEGATION_ROADMAP.md docs/roadmaps/04_MOBILE_ROADMAP.md docs/ROADMAP.md. Deferred @bytelyst/sync in docs/MOBILE_SYNC_DECISION.md because current mobile uses a narrower @bytelyst/offline-queue retry model and full sync adoption needs explicit backend sync windows, tombstones, conflict strategy, MMKV migration, telemetry, and stale/conflict UX.
• P2.7 Evaluate backend LLM usage against @bytelyst/llm-router. Either adopt the router for provider/model/fallback governance or document why @bytelyst/llm remains sufficient for NoteLett release 1. Commit: 744b938; Verified: git diff --check; rg -n 'llm-router|BACKEND_LLM_ROUTER_DECISION|Backend LLM Router Decision|@bytelyst/llm' docs/BACKEND_LLM_ROUTER_DECISION.md docs/ROADMAP.md docs/SMART_ACTIONS_ROADMAP.md docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md. Deferred router adoption in docs/BACKEND_LLM_ROUTER_DECISION.md because release-1 backend needs @bytelyst/llm chat, embeddings, mock provider, Azure/OpenAI env compatibility, and multipart vision prompt support; current @bytelyst/llm-router is useful future governance but does not yet replace the full LLMProvider contract.

Acceptance criteria:

• Platform-service, extraction-service, blob, telemetry, diagnostics, flags, kill switch, and MCP are documented with real smoke steps.
• Shared package usage has no unnecessary product-local duplicate for platform concerns.
• Deferrals are explicit, not implied by absence.

Phase P3 — Security And Production Config Hardening

Goal: production starts fail closed and do not silently run with development-only security.

• P3.1 Change backend config validation so production cannot use default JWT_SECRET, memory DB, disabled encryption by accident, or missing Cosmos credentials. Keep test/dev ergonomics intact. Commit: e7d381f; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend run typecheck; node --import tsx --input-type=module -e "import { parseConfig } from './src/lib/config.ts'; ..." accepted a safe production env and rejected unsafe defaults; git diff --check. Added exported parseConfig(), safe string boolean parsing, development JWT defaulting only for non-production ergonomics, production rejection for default/short JWT secrets, memory DB, missing Cosmos endpoint/key/database, disabled field encryption, and production memory key provider.
• P3.2 Add tests for production config validation: missing secret, default secret, memory DB in production, missing Cosmos env, encryption provider requirements. Commit: 8007fac; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend exec vitest run src/lib/config.test.ts; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend run typecheck; git diff --check. Added 11 focused config tests covering dev ergonomics, safe production config, missing/default/short production JWTs, memory DB rejection, missing Cosmos env, disabled encryption, production memory provider rejection, env key requirements, and AKV URL requirements.
• P3.3 Review all unauthenticated backend endpoints. Keep /health, /api/bootstrap, and public share reads intentional; protect diagnostics or make them explicitly dev/admin-gated. Commit: 56a051a; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend exec vitest run src/diagnostics.test.ts src/server.test.ts; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend run typecheck; git diff --check. Kept /health, /api/bootstrap, and /api/public/note-shares/:token intentionally public; moved diagnostics into diagnosticsRoutes() with dev/test open access and production admin/owner auth via shared auth middleware.
• P3.4 Add or verify rate limiting and abuse controls for public share, auth-facing, prompt, intake, and LLM-backed endpoints using shared platform patterns where available. Commit: ee4a8ab; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend exec vitest run src/lib/rate-limit.test.ts src/modules/notes/copilot.test.ts src/modules/note-prompts/note-prompts.test.ts src/modules/intake/routes.test.ts; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend run typecheck; git diff --check. Added a shared in-memory sliding-window limiter backed by TooManyRequestsError from @bytelyst/errors, replaced the local intake limiter, and guarded public share reads plus prompt, Smart Action, embedding, URL extraction, merge/compare, copilot, title suggestion, and workspace chat endpoints before expensive work begins. Auth-facing endpoints remain owned by common-platform platform-service.
• P3.5 Verify agent write paths enforce role, product scope, workspace membership, idempotency, dry-run, and audit trail behavior. Add missing tests. Commit: 8a53dfd; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend exec vitest run src/mcp/note-tools.test.ts src/mcp/register-note-tools.test.ts src/modules/note-agent-actions/routes.test.ts src/modules/note-agent-actions/routes.integration.test.ts; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend run typecheck; git diff --check. Added defense-in-depth role checks inside executable MCP tools, user/product/workspace/note scope guards before writes, duplicate idempotency-key rejection before side effects, and regression coverage for dry-run no-persistence, audit metadata, scoped updates, create-draft workspace ownership, and link-note product scope.
• P3.6 Verify field encryption coverage for note body, sensitive artifact metadata, prompt content if needed, and agent action details. Add migration notes if fields are newly encrypted. Commit: 6b37b72; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend exec vitest run src/lib/encryption-coverage.test.ts src/modules/note-artifacts/routes.integration.test.ts src/modules/note-prompts/note-prompts.test.ts src/modules/note-agent-actions/routes.integration.test.ts; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend run typecheck; git diff --check. Added shared optional text-field encryption helpers; encrypted artifact title, description, and blobPath; prompt description, systemPrompt, and userPromptTemplate; and agent action reason, beforeSummary, afterSummary, and reviewNote, while preserving plaintext query metadata and backward-compatible plaintext reads. Added raw-storage encryption tests and migration notes in docs/FIELD_ENCRYPTION_COVERAGE.md.

Acceptance criteria:

• A production container cannot start with unsafe defaults.
• Public and diagnostic surfaces are intentionally scoped.
• Agent and AI write paths are auditable and permissioned.

Phase P4 — Design System And Accessibility Compliance

Goal: remove local visual drift and meet interaction accessibility expectations.

• P4.1 Replace web hardcoded hex/RGBA colors and token fallbacks in web/src/app and web/src/components with --nl-* tokens or shared component primitives. Commit: 6ede2be; Verified: rg -n "#[0-9a-fA-F]{3,8}|rgba?\\(|var\\(--nl-[^)]+," web/src/app web/src/components --glob '!**/*.test.*' returned no matches; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/web run test; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/web run typecheck after building linked @bytelyst/billing-client; git diff --check. Added semantic CSS token aliases for overlays, translucent surfaces, muted accent/status backgrounds, and command shadows, then replaced app/component hex, RGB/RGBA, and --nl-* fallback values with tokens.
• P4.2 Replace mobile hardcoded colors in screens and label mappings with NoteLettTheme, token-derived values, or named semantic mappings. Commit: 6bbbac8; Verified: rg -n "#[0-9a-fA-F]{3,8}|rgba?\\(" mobile/src --glob '!**/*.test.*' returned no matches; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/mobile run typecheck; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/mobile run test; git diff --check. Added token-derived colors.onAccent and colors.overlayBackdrop, replaced white button text and modal overlay literals, and moved intake content-type badge colors to semantic theme mappings.
• P4.3 Audit web interactive elements for visible text or aria-label, including icon buttons, modals, editor controls, review actions, prompt actions, and settings. Commit: 01c2d31; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/web run typecheck; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/web run test; rg -n "<button[^>]*>\\s*(&times;|✕|×|<X|<Menu|<Chevron|<Search|<Trash|<Share|<More)" web/src/app web/src/components --glob '!**/*.test.*' now only reports the survey dismiss button, which has aria-label="Dismiss survey"; git diff --check. Added explicit accessible names for survey controls, editor toolbar and dismiss controls, note/workspace/link modals, settings form controls, artifact controls, and task review description.
• P4.4 Audit mobile pressables/buttons for accessibility labels, roles, disabled states, and Dynamic Type tolerance. Commit: f9903fe; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/mobile run typecheck; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/mobile run test; TypeScript AST audit confirmed Pressable/TouchableOpacity controls use labels and button roles, disabled controls expose disabled state, and TextInput fields are labeled; git diff --check. Added shared mobile accessibility helpers, applied accessible role/label/state coverage across auth, capture, intake, inbox, settings, note detail, prompt result, broadcast, and survey surfaces, and capped dense control text scaling while allowing content text to continue scaling.
• P4.5 Replace custom web buttons/cards/badges with @bytelyst/ui or @bytelyst/dashboard-components where the shared component is appropriate. Keep notes editor-specific UI local. Commit: d26a4ae; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/web run typecheck; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/web run test; custom-button grep audit returned no btn/inline primary/surface-muted button matches outside web/src/components/NoteEditor.tsx; stale shorthand token grep audit returned no --nl-red, --nl-primary, --nl-orange, --nl-blue, --nl-accent, --nl-border, or --nl-surface matches in app/component code; git diff --check. Added NoteLett token-wrapped @bytelyst/ui Button/Card/Badge primitives, mapped shared --bl-* aliases to --nl-*, replaced generic buttons/cards/badges across auth, shell, settings, prompts, modals, intake, workspace, chat, palace, survey, extracted tasks, and prompt result surfaces, and intentionally kept notes editor toolbar controls local.
• P4.6 Run visual checks for desktop and mobile web widths. Fix overlapping text, unstable toolbar dimensions, nested cards, or clipped controls. Commit: 837a187; Verified: Playwright visual audit with mocked local APIs captured landing, login, dashboard, workspaces, note detail, and settings at 1440x900 and 390x844; the audit passed with no document horizontal overflow, viewport-overflowing controls, or clipped compact controls after excluding intentional offscreen skip/sidebar affordances; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/web run typecheck; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/web run test; git diff --check. Collapsed note detail and workspace fixed two-column grids below tablet width, wrapped note page actions, and reduced mobile main panel padding so narrow layouts stay inside the viewport.

Acceptance criteria:

• rg "#[0-9a-fA-F]{3,8}|rgba?\\(" web/src mobile/src --glob '!**/*.test.*' has only documented exceptions.
• Interactive controls are accessible.
• Shared UI packages are used where sensible without making NoteLett-specific editor UX generic.

Phase P5 — Backend Reliability And Observability

Goal: backend behavior is production observable, testable, and consistent with common platform service conventions.

• P5.1 Replace raw process.stdout.write / process.stderr.write in backend startup paths with app logger or shared logger-compatible handling. Commit: 7016fc1; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend run typecheck; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend exec vitest run src/server.test.ts src/modules/note-prompts/scheduler.test.ts; rg -n "process\\.(stdout|stderr)\\.write" backend/src --glob '!**/*.test.*' returned no matches; git diff --check. Routed Cosmos startup diagnostics through @bytelyst/logger, passed the Fastify app logger into the scheduler loop, and updated server bootstrap coverage to assert logger propagation.
• P5.2 Ensure request IDs are propagated to extraction-service, platform-service, blob, LLM, webhook, and MCP calls where supported. Add tests for local propagation helpers. Commit: c31f51d; Verified: GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend run typecheck; GITEA_NPM_TOKEN=dummy pnpm --filter @notelett/backend exec vitest run src/lib/request-context.test.ts src/lib/extraction-client.test.ts src/lib/field-encrypt.test.ts src/server.test.ts src/modules/notes/routes.test.ts; request propagation audit confirmed note summarization passes inbound x-request-id to extraction-service, startup platform-service flag polling sends a generated outbound x-request-id, MCP write audit trails already default correlation IDs from req.id, and no backend blob/LLM/webhook local call path exposes supported request-id headers beyond shared package ownership; git diff --check.
• P5.3 Add health/dependency readiness coverage for datastore, encryption, platform-service, extraction-service, and MCP. Prefer @bytelyst/monitoring patterns if suitable. Commit: 874dda2; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm install --offline' to link local @bytelyst/monitoring; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend exec vitest run src/lib/dependency-readiness.test.ts src/diagnostics.test.ts'; git diff --check. Added /api/diagnostics/readiness with datastore, field-encryption, platform-service, extraction-service, and MCP dependency checks using common-platform monitoring status vocabulary and local MCP registration coverage.
• P5.4 Add structured error mapping tests for validation, auth, forbidden, not found, conflict, extraction failure, LLM timeout, and blob failure paths. Commit: ff33a05; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend exec vitest run src/lib/error-mapping.test.ts src/lib/extraction-client.test.ts src/modules/note-prompts/runner.test.ts'; git diff --check. Added stable dependency error mapping helpers for extraction-service, LLM, and blob failures, mapped extraction HTTP/fetch failures and LLM timeout failures to structured ServiceError responses, and added regression tests for validation, auth, forbidden, not-found, conflict, extraction failure, LLM timeout, and blob failure response shapes.
• P5.5 Review Cosmos partition keys and query patterns for current containers; document any cross-partition or count-heavy operations and add repository tests for scope isolation. Commit: 205c44b; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend exec vitest run src/modules/repository-scope.test.ts src/modules/note-shares/repository.test.ts src/modules/note-agent-actions/routes.integration.test.ts'; git diff --check. Added docs/COSMOS_QUERY_REVIEW.md documenting container partition keys, intentional cross-partition/count-heavy operations, guardrails, and follow-ups; added repository regression tests for notes, agent actions, shares, and collaborators across user/product/workspace/note scope boundaries.
• P5.6 Verify webhook/scheduler loops shut down cleanly on Fastify close and do not start unexpectedly in tests. Commit: 3aa3857; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend exec vitest run src/modules/note-prompts/scheduler.test.ts src/lib/webhook-subscriber.test.ts src/server.test.ts'; git diff --check. Added scheduler running-state checks, made webhook subscriber initialization idempotent with test reset helpers, verified route registration does not start the scheduler loop, and asserted server onClose stops both scheduler and webhook subscriber.

Acceptance criteria:

• Backend production logs are structured.
• Readiness tells operators whether dependencies are healthy.
• Failure modes are covered by tests and return stable errors.

Phase P6 — Web Product Completeness And Robustness

Goal: the web app is the production-grade primary NoteLett surface.

• P6.1 Verify auth middleware and client auth state against real platform-service flows, including expired token, refresh failure, logout, and unauthenticated redirects. Commit: 6418ab2; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web exec vitest run src/lib/auth-session.test.ts src/components/AuthGuard.test.tsx src/lib/api-helpers.test.ts'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run test'; git diff --check. Added product-scoped auth session helpers, configured @bytelyst/react-auth with NoteLett product id and safe session restore, refreshed expired access tokens through platform-service before rendering protected routes, cleared sessions on refresh failure/logout cleanup, and added coverage for expired token, refresh success/failure, unauthenticated redirects, and kill-switch gating.
• P6.2 Verify all mutation flows use offline queue or clear retry UX where appropriate: note create/update/archive/restore, workspace CRUD, link note, task/artifact creation, prompts, intake, reviews. Commit: 454b200; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web exec vitest run src/lib/mutation-retry.test.ts src/lib/notes-client.test.ts src/lib/prompt-client.test.ts src/lib/api-helpers.test.ts'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run test'; git diff --check. Added a shared mutation retry helper, queued offline-safe note/workspace/link/task/artifact/template/intake-rule mutations through @bytelyst/offline-queue, and added clear reconnect-and-retry errors for prompt runs, intake submissions, review decisions, and collaboration mutations that need immediate server results.
• P6.3 Add user-facing error states and empty states for backend down, platform down, extraction down, blob upload failure, and feature disabled. Commit: a72d6b7; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web exec vitest run src/lib/user-facing-states.test.ts src/components/StateNotice.test.tsx src/components/AuthGuard.test.tsx'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run test'; git diff --check. Added shared user-facing dependency state mapping and notice UI; surfaced backend-down/empty dashboard states, platform readiness failures and feature-disabled kill-switch states, extraction empty/down states, and blob upload failure/empty artifact states.
• P6.4 Complete import/export readiness: JSON and Markdown export, deterministic metadata, auth checks, and web download UX. If import is deferred, document scope and acceptance criteria. Commit: 09f30c0; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend exec vitest run src/modules/notes/export.test.ts src/modules/notes/routes.integration.test.ts'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web exec vitest run src/lib/notes-client.test.ts'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend run test'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run test'; git diff --check. Hardened authenticated JSON/Markdown export with paged backend reads, stable notelett.notes.export.v1 metadata, deterministic note fields/sorting, safe filenames, web JSON/Markdown download actions, and documented import deferral scope plus acceptance criteria in docs/IMPORT_EXPORT_READINESS.md.
• P6.5 Verify note sharing/collaboration flows: public share safety, workspace collaborator access, revocation, and UI copy. Commit: e71febe; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend exec vitest run src/modules/notes/routes.integration.test.ts src/modules/note-collaborators/routes.test.ts src/modules/notes/routes.test.ts'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web exec vitest run src/lib/notes-client.test.ts src/components/ShareDialog.test.tsx'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend run test'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run test'; git diff --check. Added expiring public shares, list/revoke endpoints, no-store/noindex public share responses, direct collaborator read/edit authorization checks, owner-gated collaborator listing, collaborator-safe export/deep-link access, and web share-dialog copy plus revoke/remove controls.
• P6.6 Add Playwright coverage for create note, edit note, archive/restore, link note, review approve/reject, prompt run, intake URL, settings smoke, and public share. Commit: 62cda1f; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web exec playwright test e2e/release-flows.spec.ts --reporter=list --workers=1'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run test'; git diff --check. Added mocked deterministic Playwright release journeys for dashboard note creation and intake URL processing, note edit/archive/restore/link/prompt-run flows, review approve/reject decisions, settings smoke, and public share rendering.
• P6.7 Add web build analysis for bundle regressions and remove unused route/runtime code. Commit: 6b89694; Verified: zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run typecheck'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run test'; zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/web run build:analyze'; git diff --check. Added dependency-free web/scripts/analyze-build.mjs and pnpm --filter @notelett/web run build:analyze to summarize gzipped route chunks and enforce route/shared bundle budgets; removed unused RunPromptModal and PromptResultView runtime code and their orphaned test.

Acceptance criteria:

• Main web workflows work against real backend clients.
• Broken dependencies produce useful UI states.
• Playwright covers the release-critical journeys.

Phase P7 — Mobile Product Completeness And Robustness

Goal: mobile is a reliable companion app, not a scaffolded surface.

• P7.1 Verify mobile auth against platform-service: login, register, token persistence, refresh/logout, auth-gated store hydration, and offline startup. Commit:
• P7.2 Add or strengthen mobile tests for note list/detail/edit, capture, workspace selection, inbox approvals, intake, prompt result, settings, feedback, broadcast/survey, and offline queue. Commit:
• P7.3 Verify mobile blob upload, share intent intake, and prompt/intake flows use shared clients and handle offline/failure states. Commit:
• P7.4 Verify mobile feature flags, kill switch, diagnostics, telemetry, and app metadata are initialized and flushed at lifecycle boundaries. Commit:
• P7.5 Add Expo production build notes and smoke checklist for iOS/Android simulators or devices. Commit:

Acceptance criteria:

• Mobile has meaningful tests for release-critical flows.
• Shared platform features are initialized intentionally.
• Production build and smoke steps are documented.

Phase P8 — CI, Docker, And Release Automation

Goal: the production-readiness checks run in automation, not only locally.

• P8.1 Extend CI mobile job to run mobile tests and lint, not only typecheck. Commit:
• P8.2 Add CI web E2E job or documented gated workflow with Playwright browser install/cache. Commit:
• P8.3 Add CI Docker build job for backend and web images. Commit:
• P8.4 Add or document compose smoke: build, start backend/web, hit /health, /api/bootstrap, and a web smoke endpoint. Commit:
• P8.5 Add secret scan and hardcoded token/color checks, reusing common platform scripts where possible. Commit:
• P8.6 Add dependency health workflow or scheduled check for @bytelyst/*, Next, React, Expo, Fastify, Vitest, and Playwright compatibility. Commit:
• P8.7 Add release notes template and production deploy checklist with environment variables, rollback, migrations, smoke tests, and monitoring links. Commit:

Acceptance criteria:

• CI blocks obvious type, test, lint, E2E, Docker, secret, and design-token regressions.
• Release can be executed from documented steps.

Phase P9 — Data, Migration, And Operational Readiness

Goal: production data can be created, migrated, backed up, and debugged safely.

• P9.1 Document Cosmos containers, partition keys, indexes, retention expectations, and backup/restore approach. Commit:
• P9.2 Add seed/bootstrap strategy for built-in prompt templates, intake rules, default workspace, and feature flags. Commit:
• P9.3 Add migration plan for encrypted fields, schema changes, and backfills; reuse common platform migration scripts where practical. Commit:
• P9.4 Define telemetry event taxonomy and diagnostic breadcrumbs for notes, prompts, intake, reviews, mobile capture, and MCP actions. Commit:
• P9.5 Add operator runbook: incident triage, dependency outage behavior, stuck scheduler/webhook recovery, failed blob upload recovery, failed LLM/extraction recovery. Commit:

Acceptance criteria:

• Operators know what data exists, how it is protected, and how to recover.
• Built-ins and migrations are deterministic.

Phase P10 — Final Production Gate

Goal: prove the product is ready to release.

• P10.1 Run full local verification: pnpm run verify. Commit:
• P10.2 Run lint for backend, web, and mobile. Commit:
• P10.3 Run web Playwright E2E. Commit:
• P10.4 Run Docker compose build and smoke. Commit:
• P10.5 Run common-platform dependency smoke with platform-service, extraction-service, and mcp-server available. Commit:
• P10.6 Run hardcoded color/token audit, secret scan, and API URL/product ID drift audit. Commit:
• P10.7 Update docs/ROADMAP.md, AGENTS.md, README.md, and this document with final status, commit hashes, known deferrals, and release notes. Commit:
• P10.8 Push all commits and confirm remote branch status. Commit:

Acceptance criteria:

• All checks pass or have explicit signed-off deferrals.
• The final roadmap includes commit hashes for every completed item.
• The remote branch contains the completed production-readiness work.

Suggested Commit Sequence

Use this sequence unless implementation findings require reordering:

1. docs(roadmap): add production readiness handoff
2. docs(roadmap): reconcile current implementation status
3. fix(config): harden production backend config
4. fix(platform): align shared service urls and smoke checks
5. refactor(ui): replace hardcoded web colors with tokens
6. refactor(mobile): replace hardcoded native colors with theme tokens
7. fix(backend): tighten diagnostics and startup logging
8. test(backend): cover production security and failure paths
9. test(web): expand release-critical e2e coverage
10. test(mobile): cover companion app release flows
11. ci: expand production readiness checks
12. docs(release): add runbook and final gate checklist

Definition Of Done

NoteLett is production ready when:

• All P0-P10 tasks are checked or explicitly deferred with reason and owner.
• Each completed task has a commit hash recorded here.
• pnpm run verify, lint, E2E, Docker smoke, platform smoke, secret scan, and design-token checks pass.
• Production config fails closed on unsafe defaults.
• Web and mobile use shared platform packages for platform concerns and shared tokens for visual styling.
• Backend preserves product-local NoteLett logic while using common platform packages/services for auth, datastore, errors, logging, telemetry, diagnostics, flags, blob, extraction, encryption, LLM governance, MCP, and monitoring where appropriate.
• docs/ROADMAP.md, AGENTS.md, and README.md agree with implementation reality.