bytelyst/learning_ai_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(agents): refresh current project guide

Browse Source
This commit is contained in:
Saravana Achu Mac 2026-05-05 09:13:33 -07:00
parent 87e9eed597
commit 99efad80c0
2 changed files with 115 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
AGENTS.md
View File

@ -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.

2
docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md
View File

@ -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: