docs: add AGENTS.md, README.md, and update roadmap with session commit refs

- AGENTS.md: full AI agent onboarding guide following ecosystem conventions - README.md: quick start, architecture overview, env setup, test commands - ROADMAP.md: added commit references for identity lock, MCP tools, platform integrations, blob client - Marked resolved blockers (product identity, blob artifacts)
2026-03-10 19:01:48 -07:00 · 2026-03-10 19:01:48 -07:00 · 9d392eab39
commit 9d392eab39
parent 196b2106d8
3 changed files with 300 additions and 3 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,230 @@
+# AGENTS.md — AI Coding Agent Instructions
+
+> **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.
+
+---
+
+## 1. Project Identity
+
+| Key | Value |
+|-----|-------|
+| **Product** | NoteLett |
+| **Product ID** | `notelett` |
+| **Bundle ID (iOS)** | `com.bytelyst.notelett` |
+| **Bundle ID (Android)** | `com.notelett.app` |
+| **Domain** | notelett.app |
+| **Repo** | `learning_ai_notes` |
+| **Ecosystem** | ByteLyst (shares platform-service with LysnrAI, MindLyst, ChronoMind, JarvisJr, NomGap, PeakPulse) |
+
+## 2. Repo Layout
+
+```
+learning_ai_notes/
+├── backend/                          # Fastify 5 + TypeScript ESM backend (port 4016)
+│   ├── src/
+│   │   ├── lib/
+│   │   │   ├── config.ts             # Zod-validated env config
+│   │   │   ├── product-config.ts     # Product identity from shared/product.json
+│   │   │   ├── auth.ts               # JWT extraction helper
+│   │   │   ├── request-context.ts    # getUserId(req), getRequestProductId(req)
+│   │   │   ├── cosmos-init.ts        # Cosmos container registration
+│   │   │   ├── datastore.ts          # @bytelyst/datastore provider (Cosmos or memory)
+│   │   │   └── errors.ts             # Re-export from @bytelyst/errors
+│   │   ├── modules/
+│   │   │   ├── notes/                # Note CRUD (types, repository, routes, test)
+│   │   │   ├── workspaces/           # Workspace CRUD (types, repository, routes, test)
+│   │   │   ├── note-relationships/   # Note linking (types, repository, routes, test)
+│   │   │   ├── note-tasks/           # Task CRUD (types, repository, routes, test)
+│   │   │   ├── note-artifacts/       # Artifact CRUD (types, repository, routes, test)
+│   │   │   └── note-agent-actions/   # Agent action audit trail (types, repository, routes, test)
+│   │   ├── 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 (6 route modules + MCP)
+│   ├── package.json
+│   └── tsconfig.json
+│
+├── web/                              # Next.js 16 + React 19 web app (App Router)
+│   ├── src/
+│   │   ├── app/
+│   │   │   ├── page.tsx              # Landing page
+│   │   │   ├── layout.tsx            # Root layout
+│   │   │   └── (app)/               # Authenticated route group
+│   │   │       ├── dashboard/        # Dashboard with metrics + recent notes
+│   │   │       ├── workspaces/       # Workspace list + filters
+│   │   │       ├── search/           # Search with saved queries
+│   │   │       ├── reviews/          # Approval queue + agent timeline
+│   │   │       └── notes/[noteId]/   # Note detail with editor
+│   │   ├── components/               # React UI components
+│   │   │   ├── Sidebar.tsx
+│   │   │   ├── AppShell.tsx
+│   │   │   ├── MetadataPanel.tsx
+│   │   │   ├── LinkedNotesPanel.tsx
+│   │   │   └── AgentTimeline.tsx
+│   │   └── lib/                      # Pure TS clients + config
+│   │       ├── product-config.ts     # Product identity + API URLs
+│   │       ├── auth.ts               # @bytelyst/react-auth provider
+│   │       ├── notes-client.ts       # Notes API client (backend)
+│   │       ├── platform.ts           # @bytelyst/platform-client
+│   │       ├── telemetry.ts          # @bytelyst/telemetry-client
+│   │       ├── diagnostics.ts        # @bytelyst/diagnostics-client
+│   │       ├── feature-flags.ts      # @bytelyst/feature-flag-client
+│   │       ├── kill-switch.ts        # @bytelyst/kill-switch-client
+│   │       ├── extraction-client.ts  # Extraction-service task extraction
+│   │       ├── blob-client.ts        # SAS-based blob upload/download
+│   │       └── types.ts              # Shared TypeScript interfaces
+│   ├── package.json
+│   └── tsconfig.json
+│
+├── mobile/                           # React Native + Expo companion app
+│   ├── src/
+│   │   ├── app/                      # Expo Router screens
+│   │   │   ├── (tabs)/              # 4-tab navigator (home, inbox, capture, settings)
+│   │   │   ├── note/[noteId].tsx    # Note detail
+│   │   │   └── 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
+│   │   ├── store/                   # Zustand stores
+│   │   │   ├── auth-store.ts
+│   │   │   ├── inbox-store.ts
+│   │   │   └── mmkv-storage.ts      # MMKV persistent storage
+│   │   └── theme/                   # Design tokens
+│   ├── app.json                     # Expo config
+│   └── package.json
+│
+├── shared/
+│   └── product.json                 # Canonical product identity
+│
+├── docs/
+│   ├── PRD.md                       # Product requirements
+│   ├── ROADMAP.md                   # Master execution tracker
+│   ├── ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md
+│   └── roadmaps/                    # Per-workstream roadmaps
+│       ├── 00_MASTER_EXECUTION_PLAN.md
+│       ├── 01_FOUNDATIONS_AND_DECISIONS.md
+│       ├── 02_BACKEND_ROADMAP.md
+│       ├── 03_WEB_ROADMAP.md
+│       └── 04_MOBILE_ROADMAP.md
+│
+├── AGENTS.md                        # This file
+└── README.md
+```
+
+## 3. Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| **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` |
+| **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"` |
+| **Tests** | Vitest — 18 backend tests (10 files), 6 web tests (5 files) |
+
+## 4. Coding Conventions
+
+### MUST follow
+
+- Every Cosmos document MUST include a `productId: "notelett"` field
+- Backend modules follow `types.ts` → `repository.ts` → `routes.ts` pattern
+- All repositories use `@bytelyst/datastore` getCollection() — never direct Cosmos SDK calls
+- Web engine logic in `web/src/lib/` — pure TS, no React imports
+- Web components in `web/src/components/` — React UI only
+- Mobile API clients in `mobile/src/api/` — pure TS
+- Theme tokens use `--nl-*` CSS custom properties (web) or `NoteLettTheme` (native)
+- Commit messages: `type(scope): description` — types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+
+### MUST NOT do
+
+- Never use `console.log` in production code — use `req.log` or `app.log` in Fastify
+- Never use `any` type — use Zod inference or explicit types
+- Never hardcode colors — use theme tokens
+- Never hardcode API URLs — use env vars or config
+- Never hardcode product ID — use `PRODUCT_ID` from `product-config.ts`
+- Never modify tests to make them pass — fix the actual code
+- Never delete existing comments or documentation unless explicitly asked
+- Never add emojis to code unless explicitly asked
+
+## 5. Key Design Decisions
+
+### MCP Tool Architecture
+- 8 MCP tools: list, get, search, create_draft, update, link_notes, extract_tasks, attach_artifact
+- Every write tool records an agent action audit trail
+- All tools enforce product scope and user authentication
+- Dry-run, idempotency key, and correlation ID support on all write tools
+
+### Datastore Abstraction
+- `@bytelyst/datastore` provides `CosmosDatastoreProvider` and `MemoryDatastoreProvider`
+- `DB_PROVIDER` env var controls which provider is used (default: cosmos, test: memory)
+- All 6 repositories use `getCollection()` — no direct Cosmos SDK calls
+
+### Agent Action Audit Trail
+- Every MCP tool write operation creates a `NoteAgentActionDoc` record
+- Actions track: actorId, actorType, toolName, actionType, state, reason, before/after summaries
+- Supports approval workflows: draft → proposed → approved/rejected → applied
+
+### Cosmos Containers
+- `notes` (partition: `/workspaceId`)
+- `workspaces` (partition: `/userId`)
+- `note_relationships` (partition: `/workspaceId`)
+- `note_tasks` (partition: `/workspaceId`)
+- `note_artifacts` (partition: `/workspaceId`)
+- `note_agent_actions` (partition: `/workspaceId`)
+
+## 6. Build & Test Commands
+
+```bash
+# ── Backend ────────────────────────────────────────
+cd backend && npm run dev              # Dev server (port 4016)
+cd backend && npm run typecheck        # tsc --noEmit
+cd backend && npm test                 # 18 Vitest tests
+
+# ── Web ────────────────────────────────────────────
+cd web && npm run dev -- --webpack     # Dev server (port 3000)
+cd web && npm run build -- --webpack   # Production build
+cd web && npm run typecheck            # tsc --noEmit
+cd web && npm test                     # 6 Vitest tests
+
+# ── Mobile ─────────────────────────────────────────
+cd mobile && npm start                 # Expo dev server
+cd mobile && npm run typecheck         # tsc --noEmit
+```
+
+## 7. Backend API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET/POST | `/api/notes` | List / create notes |
+| GET/PATCH | `/api/notes/:id` | Note CRUD |
+| GET/POST | `/api/workspaces` | List / create workspaces |
+| GET/PATCH | `/api/workspaces/:id` | Workspace CRUD |
+| GET/POST | `/api/note-relationships` | List / create relationships |
+| GET/POST | `/api/note-tasks` | List / create tasks |
+| GET/PATCH | `/api/note-tasks/:id` | Task CRUD |
+| GET/POST | `/api/note-artifacts` | List / create artifacts |
+| PATCH | `/api/note-artifacts/:id` | Update artifact |
+| GET/POST | `/api/note-agent-actions` | List / create agent actions |
+| GET/PATCH | `/api/note-agent-actions/:id` | Agent action CRUD |
+| GET | `/health` | Health check |
+
+## 8. MCP Tools
+
+| Tool Name | Description | Role |
+|-----------|-------------|------|
+| `notes.notes.list` | List notes in a workspace | viewer |
+| `notes.notes.get` | Get a single note | viewer |
+| `notes.notes.search` | Search notes with lexical query | viewer |
+| `notes.notes.create_draft` | Create a note draft | admin |
+| `notes.notes.update` | Update note title/body/status/tags | admin |
+| `notes.relationships.link` | Create typed relationship between notes | admin |
+| `notes.tasks.extract` | Extract tasks from note body | admin |
+| `notes.artifacts.attach` | Attach artifact to a note | admin |
--- a/README.md
+++ b/README.md
@ -0,0 +1,53 @@
+# NoteLett
+
+Structured notes platform for humans and AI agents — part of the ByteLyst ecosystem.
+
+## Quick Start
+
+```bash
+# Backend (port 4016)
+cd backend && npm install && npm run dev
+
+# Web (port 3000)
+cd web && npm install && npm run dev -- --webpack
+
+# Mobile
+cd mobile && npm install && npm start
+```
+
+## Architecture
+
+| Surface | Stack | Port |
+|---------|-------|------|
+| **Backend** | Fastify 5 + TypeScript ESM | 4016 |
+| **Web** | Next.js 16 + React 19 | 3000 |
+| **Mobile** | Expo + React Native | 8081 |
+| **Platform** | platform-service (shared) | 4003 |
+| **Extraction** | extraction-service (shared) | 4005 |
+
+## Key Features
+
+- **6 backend modules**: notes, workspaces, relationships, tasks, artifacts, agent actions
+- **8 MCP tools**: list, get, search, create_draft, update, link_notes, extract_tasks, attach_artifact
+- **Agent audit trail**: every write tool records agent action history
+- **Datastore abstraction**: Cosmos DB in production, in-memory for tests
+- **Platform integrations**: auth (JWT), telemetry, diagnostics, feature flags, kill-switch, blob storage
+
+## Environment
+
+Copy `backend/.env.example` to `backend/.env` and fill in:
+- `JWT_SECRET` — shared secret with platform-service
+- `COSMOS_ENDPOINT` / `COSMOS_KEY` — Azure Cosmos DB credentials (or use `DB_PROVIDER=memory`)
+
+## Tests
+
+```bash
+cd backend && npm test    # 18 tests (10 files)
+cd web && npm test        # 6 tests (5 files)
+```
+
+## Docs
+
+- [`AGENTS.md`](AGENTS.md) — AI agent onboarding guide
+- [`docs/PRD.md`](docs/PRD.md) — Product requirements
+- [`docs/ROADMAP.md`](docs/ROADMAP.md) — Master execution tracker
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@ -465,15 +465,29 @@ Detailed implementation plans live under `docs/roadmaps/`.
  - 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
+- 2026-03-10 — Product identity locked as NoteLett (`e1fde25`):
+  - productId: notelett, domain: notelett.app, backend port: 4016
+  - iOS bundle: com.bytelyst.notelett, Android bundle: com.notelett.app
+  - rippled through all config, docs, source, and test files across backend/web/mobile
+  - registered in learning_ai_common_plat/products/notelett/
+- 2026-03-10 — 4 remaining MCP tools implemented (`12058ed`):
+  - notes.notes.update, notes.relationships.link, notes.tasks.extract, notes.artifacts.attach
+  - all 8 MCP tools now have full audit trail, dry-run, idempotency, and correlation support
+- 2026-03-10 — Platform integrations wired (`8755661`):
+  - feature-flag-client and kill-switch-client added to web surface
+  - telemetry, diagnostics, extraction were already wired
+- 2026-03-10 — Blob artifact upload/download (`196b210`):
+  - SAS-based upload/download via platform-service blob endpoints
+- 2026-03-10 — QA / release hardening:
+  - AGENTS.md and README.md created following ecosystem conventions

 # 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 still derives some operator/saved-view summaries client-side.
+- ~~**Blocker** — Product identity not finalized~~ **Resolved:** locked as NoteLett (`e1fde25`)
 - **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**
  - Complete real end-to-end CRUD wiring across every web/mobile surface
-  - Blob-backed artifacts and upload/download flows
+  - ~~Blob-backed artifacts and upload/download flows~~ **Resolved:** SAS-based blob client (`196b210`)
  - Fully integrated approval/review/audit UX across every surface
  - Persisted saved views, keyboard shortcut expansion, and deeper performance hardening