From 9d392eab39942c241fccb85ba5ecdd39184ef72d Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Tue, 10 Mar 2026 19:01:48 -0700 Subject: [PATCH] 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) --- AGENTS.md | 230 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 53 +++++++++++ docs/ROADMAP.md | 20 ++++- 3 files changed, 300 insertions(+), 3 deletions(-) create mode 100644 AGENTS.md create mode 100644 README.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bcee7d3 --- /dev/null +++ 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 | diff --git a/README.md b/README.md new file mode 100644 index 0000000..e6de05c --- /dev/null +++ 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 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 022b61a..062db7e 100644 --- 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