diff --git a/AGENTS.md b/AGENTS.md index d81df3a..914ff81 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ > **For:** Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf Cascade, and any AI coding agent. > **Repo:** `learning_ai_notes` — NoteLett structured notes platform for humans and AI agents. -> **See also:** [`docs/PRD.md`](docs/PRD.md) for full product spec, [`docs/ROADMAP.md`](docs/ROADMAP.md) for implementation plan. +> **See also:** [`docs/PRD.md`](docs/PRD.md) for full product spec, [`docs/ROADMAP.md`](docs/ROADMAP.md) for implementation status, and [`docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md) for the active production-readiness checklist. --- @@ -37,7 +37,10 @@ learning_ai_notes/ │ │ │ ├── embeddings.ts # Embedding utilities (duplicate detection, related notes) │ │ │ ├── feature-flags.ts # 20 feature flags (core + Smart Actions) │ │ │ ├── telemetry.ts # Telemetry event buffer -│ │ │ └── field-encrypt.ts # @bytelyst/field-encrypt singleton +│ │ │ ├── field-encrypt.ts # @bytelyst/field-encrypt singleton +│ │ │ ├── ecosystem-phase1.ts # Cross-product transcript import helpers +│ │ │ ├── ecosystem-phase3.ts # Cross-product trail report import helpers +│ │ │ └── webhook-subscriber.ts # Prompt webhook subscriber registry │ │ ├── modules/ │ │ │ ├── notes/ # Note CRUD (types, repository, routes, test) │ │ │ ├── workspaces/ # Workspace CRUD (types, repository, routes, test) @@ -46,19 +49,26 @@ learning_ai_notes/ │ │ │ ├── note-artifacts/ # Artifact CRUD (types, repository, routes, test) │ │ │ ├── note-agent-actions/ # Agent action audit trail + batch review (types, repository, routes, test) │ │ │ ├── saved-views/ # Persisted saved views CRUD (types, repository, routes) -│ │ │ └── note-prompts/ # Smart Actions: prompt templates, runner, scheduler, webhooks +│ │ │ ├── note-prompts/ # Smart Actions: prompt templates, runner, scheduler, webhooks │ │ │ ├── types.ts # PromptTemplateDoc, CRUD + Run schemas │ │ │ ├── repository.ts # Prompt template CRUD │ │ │ ├── routes.ts # Template CRUD + run + reading-time + suggest-tags + duplicates + links + compare + merge + URL extract + knowledge gaps │ │ │ ├── runner.ts # executePrompt() with retry + timeout │ │ │ ├── scheduler.ts # Cron schedules + webhook triggers + routes │ │ │ └── seed.ts # 20 built-in prompt templates +│ │ │ ├── intake/ # URL/text intake, jobs, and rules +│ │ │ ├── note-collaborators/ # Share-with-user, collaborators, shared-with-me, deep links +│ │ │ ├── note-shares/ # Public note share repository and tokens +│ │ │ ├── note-versions/ # Note version repository +│ │ │ ├── palace/ # MemPalace memory, KG, wake-up, stats routes +│ │ │ ├── ecosystem-phase1/ # Transcript import route +│ │ │ └── ecosystem-phase3/ # Trail report import route │ │ ├── mcp/ │ │ │ ├── note-tool-contracts.ts # 8 MCP tool Zod schemas + definitions │ │ │ ├── note-tools.ts # 8 executable MCP tool implementations │ │ │ ├── register-note-tools.ts # Fastify plugin to register MCP tools │ │ │ └── *.test.ts # MCP test files -│ │ └── server.ts # Fastify entrypoint (11 route modules + MCP + scheduler) +│ │ └── server.ts # Fastify entrypoint (14 API route modules + public/diagnostic routes + scheduler) │ ├── package.json │ └── tsconfig.json │ @@ -72,7 +82,12 @@ learning_ai_notes/ │ │ │ ├── workspaces/ # Workspace list + filters │ │ │ ├── search/ # Search with saved queries │ │ │ ├── reviews/ # Approval queue + agent timeline -│ │ │ └── notes/[noteId]/ # Note detail with editor +│ │ │ ├── notes/[noteId]/ # Note detail with editor +│ │ │ ├── prompts/ # Prompt template and Smart Action management +│ │ │ ├── intake/ # URL/text intake workflows +│ │ │ ├── settings/ # MCP/platform settings +│ │ │ ├── palace/ # MemPalace knowledge surface +│ │ │ └── chat/ # Workspace chat/RAG surface │ │ ├── components/ # React UI components │ │ │ ├── Sidebar.tsx │ │ │ ├── AppShell.tsx @@ -95,6 +110,14 @@ learning_ai_notes/ │ │ ├── kill-switch.ts # @bytelyst/kill-switch-client │ │ ├── extraction-client.ts # Extraction-service task extraction │ │ ├── blob-client.ts # @bytelyst/blob-client wrapper +│ │ ├── prompt-client.ts # Prompt templates, runs, schedules, webhooks +│ │ ├── intake-client.ts # Intake rules/jobs/client calls +│ │ ├── palace-client.ts # Palace memory/KG/wake-up client +│ │ ├── broadcast-client.ts # @bytelyst/broadcast-client wrapper +│ │ ├── billing-client.ts # @bytelyst/billing-client wrapper +│ │ ├── feedback-client.ts # @bytelyst/feedback-client wrapper +│ │ ├── survey-client.ts # @bytelyst/survey-client wrapper +│ │ ├── offline-queue.ts # @bytelyst/offline-queue wrapper │ │ ├── use-keyboard-shortcuts.ts # Global keyboard shortcuts hook │ │ ├── use-debounce.ts # Debounce hook for search │ │ └── types.ts # Shared TypeScript interfaces @@ -105,20 +128,34 @@ learning_ai_notes/ │ ├── src/ │ │ ├── app/ # Expo Router screens │ │ │ ├── (tabs)/ # 4-tab navigator (home, inbox, capture, settings) -│ │ │ ├── note/[noteId].tsx # Note detail +│ │ │ ├── note/[id].tsx # Note detail +│ │ │ ├── intake.tsx # URL/text intake screen +│ │ │ ├── prompt-result.tsx # Prompt run result screen │ │ │ └── auth.tsx # Auth screen │ │ ├── api/ # API clients │ │ │ ├── config.ts # Product identity + API URLs │ │ │ ├── auth.ts # @bytelyst/auth-client │ │ │ ├── notes.ts # Notes API client -│ │ │ └── note-agent-actions.ts # Agent actions API client +│ │ │ ├── note-agent-actions.ts # Agent actions API client +│ │ │ ├── note-prompts.ts # Prompt template/run client +│ │ │ ├── intake.ts # Intake client +│ │ │ └── blob-upload.ts # Blob upload helper │ │ ├── lib/ # Platform SDK wrappers -│ │ │ └── platform.ts # Telemetry, feature flags, kill switch, blob client +│ │ │ ├── platform.ts # Telemetry, feature flags, kill switch, blob client +│ │ │ ├── platform-api.ts # Platform API helper +│ │ │ ├── offline-queue.ts # @bytelyst/offline-queue wrapper +│ │ │ ├── broadcast-client.ts # Broadcast client wrapper +│ │ │ ├── feedback-client.ts # Feedback client wrapper +│ │ │ ├── billing-client.ts # Billing client wrapper +│ │ │ ├── survey-client.ts # Survey client wrapper +│ │ │ └── share-intent.ts # Share intent helper │ │ ├── store/ # Zustand stores │ │ │ ├── auth-store.ts │ │ │ ├── inbox-store.ts │ │ │ ├── workspace-store.ts │ │ │ ├── notes-store.ts +│ │ │ ├── intake-store.ts +│ │ │ ├── prompt-store.ts │ │ │ └── mmkv-storage.ts # MMKV persistent storage │ │ └── theme/ # Design tokens │ ├── app.json # Expo config @@ -141,7 +178,7 @@ learning_ai_notes/ ├── backend/Dockerfile # Multi-stage Docker build for backend ├── web/Dockerfile # Multi-stage Docker build for web ├── docker-compose.yml # Backend (4016) + web (3000) -├── scripts/docker-prep.sh # Pack @bytelyst/* tarballs for Docker +├── scripts/docker-prep.sh # Docker preparation helper ├── .github/workflows/ci.yml # GitHub Actions CI (backend + web + mobile) ├── AGENTS.md # This file └── README.md @@ -154,13 +191,13 @@ learning_ai_notes/ | **Backend** | Fastify 5, TypeScript ESM, Zod, jose (JWT), @bytelyst/datastore (Cosmos or memory) | | **Web** | Next.js 16 (App Router), React 19, TailwindCSS v4, Zustand, Vitest | | **Mobile** | React Native (Expo), TypeScript, expo-router, Zustand, MMKV | -| **Shared packages** | `@bytelyst/fastify-core`, `@bytelyst/config`, `@bytelyst/cosmos`, `@bytelyst/errors`, `@bytelyst/datastore`, `@bytelyst/api-client`, `@bytelyst/react-auth`, `@bytelyst/auth-client`, `@bytelyst/telemetry-client`, `@bytelyst/diagnostics-client`, `@bytelyst/feature-flag-client`, `@bytelyst/kill-switch-client`, `@bytelyst/platform-client`, `@bytelyst/blob-client` | +| **Shared packages** | `@bytelyst/fastify-core`, `@bytelyst/config`, `@bytelyst/cosmos`, `@bytelyst/errors`, `@bytelyst/datastore`, `@bytelyst/api-client`, `@bytelyst/react-auth`, `@bytelyst/auth-client`, `@bytelyst/telemetry-client`, `@bytelyst/diagnostics-client`, `@bytelyst/feature-flag-client`, `@bytelyst/kill-switch-client`, `@bytelyst/platform-client`, `@bytelyst/blob-client`, `@bytelyst/extraction`, `@bytelyst/offline-queue`, `@bytelyst/broadcast-client`, `@bytelyst/survey-client`, `@bytelyst/feedback-client`, `@bytelyst/billing-client`, `@bytelyst/palace`, `@bytelyst/webhook-dispatch` | | **Design system** | `@bytelyst/design-tokens` (CSS custom properties), `@bytelyst/ui` (shared React components) | | **Platform** | platform-service (port 4003) for auth, flags, telemetry, billing, blob | | **Extraction** | extraction-service (port 4005) for AI-powered task extraction | | **Database** | Azure Cosmos DB via `@bytelyst/datastore` — `productId: "notelett"` | | **LLM** | `@bytelyst/llm` (mock/openai/azure providers), retry + timeout hardening | -| **Tests** | Vitest — 192 backend tests (32 files), 45 web tests (11 files), 50 mobile tests (10 files), 9 Playwright E2E specs | +| **Tests present** | Vitest/Playwright — 42 backend test files, 15 web unit/component test files, 10 mobile test files, and 9 Playwright E2E specs. May 5 baseline currently fails before all tests can pass; see `docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md` P0.5. | ## 4. Coding Conventions @@ -183,8 +220,8 @@ learning_ai_notes/ **`.npmrc` is managed by a canonical template in `learning_ai_common_plat`.** Never create or hand-edit `.npmrc` — it will drift. -- **Template:** `../learning_ai_common_plat/scripts/npmrc.template` -- **Sync:** `cd ../learning_ai_common_plat && bash scripts/sync-npmrc.sh` +- **Template:** `../learning_ai/learning_ai_common_plat/scripts/npmrc.template` +- **Sync:** `cd ../learning_ai/learning_ai_common_plat && bash scripts/sync-npmrc.sh` - **Key rule:** Never hardcode `gitea.bytelyst.com` — use `${GITEA_NPM_HOST:-localhost}:3300` (SSH tunnel on corp network) ### MUST NOT do @@ -209,7 +246,7 @@ learning_ai_notes/ ### Datastore Abstraction - `@bytelyst/datastore` provides `CosmosDatastoreProvider` and `MemoryDatastoreProvider` - `DB_PROVIDER` env var controls which provider is used (default: cosmos, test: memory) -- All 7 repositories use `getCollection()` — no direct Cosmos SDK calls +- All repositories use `getCollection()` — no direct Cosmos SDK calls ### Agent Action Audit Trail - Every MCP tool write operation creates a `NoteAgentActionDoc` record @@ -227,6 +264,17 @@ learning_ai_notes/ - `note_prompts` (partition: `/userId`) - `note_prompt_schedules` (partition: `/userId`) - `note_prompt_webhooks` (partition: `/userId`) +- `note_shares` (partition: `/workspaceId`) +- `note_versions` (partition: `/workspaceId`) +- `note_intake_rules` (partition: `/userId`) +- `note_intake_jobs` (partition: `/userId`) +- `note_collaborators` (partition: `/sharedWithUserId`) +- `palace_wings` (partition: `/userId`) +- `palace_rooms` (partition: `/userId`) +- `palace_memories` (partition: `/userId`) +- `palace_tunnels` (partition: `/userId`) +- `palace_kg` (partition: `/userId`) +- `palace_diaries` (partition: `/userId`) ## 6. Build & Test Commands @@ -235,41 +283,57 @@ learning_ai_notes/ pnpm --filter @notelett/backend run dev # Dev server (port 4016) pnpm --filter @notelett/backend run typecheck # tsc --noEmit pnpm --filter @notelett/backend run test # backend Vitest tests +pnpm --filter @notelett/backend run lint # backend ESLint # ── Web ──────────────────────────────────────────── pnpm --filter @notelett/web run dev # Dev server (port 3000) pnpm --filter @notelett/web run build # Production build pnpm --filter @notelett/web run typecheck # tsc --noEmit pnpm --filter @notelett/web run test # web Vitest tests +pnpm --filter @notelett/web run lint # web ESLint +pnpm --filter @notelett/web run test:e2e # Playwright E2E # ── Mobile ───────────────────────────────────────── pnpm --filter @notelett/mobile run start # Expo dev server pnpm --filter @notelett/mobile run typecheck # tsc --noEmit pnpm --filter @notelett/mobile run test # mobile tests +pnpm --filter @notelett/mobile run lint # mobile ESLint # ── Full verification ────────────────────────────── pnpm run verify ``` +May 5, 2026 baseline note: `pnpm install --frozen-lockfile` passes after the workspace was aligned to `../learning_ai/learning_ai_common_plat/packages/*`. `pnpm run typecheck`, `pnpm run test`, `pnpm run build`, and targeted lint currently have known baseline failures recorded in `docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md` P0.5. Do not hide those by weakening tests or lint rules; fix the underlying implementation/configuration in the owning roadmap tasks. + ## 7. Backend API Endpoints | Method | Path | Description | |--------|------|-------------| | GET/POST | `/api/notes` | List / create notes | | GET/PATCH | `/api/notes/:id` | Note CRUD | +| DELETE | `/api/notes/:id` | Delete note | +| GET | `/api/notes/:id/versions` | List note versions | | POST | `/api/notes/:id/archive` | Archive note | | POST | `/api/notes/:id/restore` | Restore note | | POST | `/api/notes/:id/summarize` | Summarize note via extraction-service | +| POST | `/api/notes/:id/share` | Create public note share | | GET | `/api/notes/export` | Export notes (JSON or Markdown) | -| GET | `/api/notes/search` | Search notes | +| GET/POST | `/api/notes/search` | Search notes | | GET/POST | `/api/workspaces` | List / create workspaces | +| GET | `/api/workspaces/summaries` | Workspace summaries with note counts | | GET/PATCH | `/api/workspaces/:id` | Workspace CRUD | +| DELETE | `/api/workspaces/:id` | Delete workspace | +| POST | `/api/workspaces/onboarding-seed` | Seed onboarding workspace and notes | | GET/POST | `/api/note-relationships` | List / create relationships | +| DELETE | `/api/note-relationships/:id` | Delete relationship | | GET/POST | `/api/note-tasks` | List / create tasks | | GET/PATCH | `/api/note-tasks/:id` | Task CRUD | +| DELETE | `/api/note-tasks/:id` | Delete task | | GET/POST | `/api/note-artifacts` | List / create artifacts | | PATCH | `/api/note-artifacts/:id` | Update artifact | +| DELETE | `/api/note-artifacts/:id` | Delete artifact | | GET/POST | `/api/note-agent-actions` | List / create agent actions | +| GET | `/api/note-agent-actions/pending` | Pending agent actions | | PATCH | `/api/note-agent-actions/:id` | Update agent action state | | POST | `/api/note-agent-actions/batch-review` | Batch approve/reject (up to 50) | | GET/POST | `/api/saved-views` | List / create saved views | @@ -285,6 +349,8 @@ pnpm run verify | GET/POST | `/api/note-prompts` | List / create prompt templates | | GET/PATCH/DELETE | `/api/note-prompts/:id` | Template CRUD | | POST | `/api/note-prompts/run` | Run a prompt template against a note | +| POST | `/api/note-prompts/run-stream` | Stream prompt run output | +| GET | `/api/note-prompts/history` | Prompt run history | | POST | `/api/note-prompts/url-extract` | Extract + summarize URL content | | GET/POST | `/api/prompt-schedules` | List / create scheduled actions | | GET/PATCH/DELETE | `/api/prompt-schedules/:id` | Schedule CRUD | @@ -294,6 +360,38 @@ pnpm run verify | POST | `/api/prompt-webhooks/:id/trigger` | Manually trigger a webhook | | POST | `/api/workspaces/:wsId/knowledge-gaps` | Knowledge gap detection | | GET | `/api/notes/:id/reading-time` | Reading time estimate | +| POST | `/api/intake` | Create intake job from URL/text | +| GET | `/api/intake/jobs` | List intake jobs | +| GET | `/api/intake/jobs/:id` | Get intake job | +| GET/POST | `/api/intake-rules` | List / create intake rules | +| PATCH/DELETE | `/api/intake-rules/:id` | Update / delete intake rule | +| POST | `/api/notes/:id/share-with-user` | Share note with another user | +| GET | `/api/notes/:id/collaborators` | List note collaborators | +| DELETE | `/api/notes/:noteId/collaborators/:userId` | Remove collaborator | +| GET | `/api/shared-with-me` | List notes shared with current user | +| POST | `/api/notes/:id/export-text` | Export note text payload | +| GET | `/api/notes/:id/deep-link` | Build note deep link | +| GET | `/api/public/note-shares/:token` | Public read-only note share | +| GET | `/api/palace/search` | Search Palace memories | +| GET | `/api/palace/wings` | List Palace wings | +| GET/DELETE | `/api/palace/wings/:wingId` | Get / delete Palace wing | +| GET | `/api/palace/wings/:wingId/rooms` | List Palace rooms | +| GET/POST | `/api/palace/memories` | List / create Palace memories | +| DELETE | `/api/palace/memories/:id` | Delete Palace memory | +| GET | `/api/palace/kg/entity/:entity` | Palace KG entity facts | +| GET | `/api/palace/kg/timeline/:entity` | Palace KG entity timeline | +| GET | `/api/palace/kg/contradictions` | Palace KG contradictions | +| GET | `/api/palace/wake-up/:wingId` | Build wake-up context | +| POST | `/api/palace/backfill-embeddings` | Backfill Palace embeddings | +| POST | `/api/palace/prune` | Prune Palace memory | +| GET | `/api/palace/health` | Palace health | +| GET | `/api/palace/stats` | Palace stats | +| POST | `/api/ecosystem/phase1/import-latest-transcript` | Import latest transcript | +| POST | `/api/ecosystem/phase3/import-latest-trail-report` | Import latest trail report | +| GET | `/api/bootstrap` | Product bootstrap metadata | +| GET | `/api/diagnostics/flags` | Feature flag diagnostics | +| GET/POST | `/api/diagnostics/telemetry` | Read / flush telemetry diagnostics | +| GET | `/api/diagnostics/config` | Backend config diagnostics | | GET | `/health` | Health check | ## 8. MCP Tools @@ -316,6 +414,6 @@ pnpm run verify For periodic maintenance tasks that span all ByteLyst repos (test audits, coverage gaps, dependency checks, secret scans, typecheck sweeps), see the **Coding Agent Automation Playbook**: -> [`../learning_ai_common_plat/docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md`](../learning_ai_common_plat/docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md) +> [`../learning_ai/learning_ai_common_plat/docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md`](../learning_ai/learning_ai_common_plat/docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md) Key tasks: workspace hygiene sweep, cross-repo test suite, backend/web coverage gap analysis, TypeScript typecheck sweep, dependency health check, secret scan, code quality audit, AGENTS.md consistency check. diff --git a/docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md b/docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md index 6f8ed03..fb11051 100644 --- a/docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md +++ b/docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md @@ -107,7 +107,7 @@ Acceptance criteria: Goal: remove roadmap drift so agents do not chase already completed or obsolete work. - [x] **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: +- [x] **P1.2** Update `AGENTS.md` with current module list, endpoint list, test counts, route modules, containers, shared packages, and verification commands. Commit: `pending`; 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: - [ ] **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: - [ ] **P1.5** Add a concise architecture boundary section: product-local NoteLett logic versus common platform responsibilities. Commit: