420 lines
26 KiB
Markdown
420 lines
26 KiB
Markdown
# 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 status, and [`docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md) for the active production-readiness checklist.
|
|
|
|
---
|
|
|
|
## 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
|
|
│ │ │ ├── llm.ts # @bytelyst/llm lazy singleton
|
|
│ │ │ ├── copilot-transform.ts # Copilot text transforms (shorten, expand, bulletize, etc.)
|
|
│ │ │ ├── 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
|
|
│ │ │ ├── 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)
|
|
│ │ │ ├── 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 + batch review (types, repository, routes, test)
|
|
│ │ │ ├── saved-views/ # Persisted saved views CRUD (types, repository, routes)
|
|
│ │ │ ├── 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 (14 API route modules + public/diagnostic routes + scheduler)
|
|
│ ├── 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
|
|
│ │ │ ├── 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
|
|
│ │ │ ├── MetadataPanel.tsx
|
|
│ │ │ ├── LinkedNotesPanel.tsx
|
|
│ │ │ ├── AgentTimeline.tsx
|
|
│ │ │ ├── CreateNoteModal.tsx # Create note modal (workspace, title, body, tags)
|
|
│ │ │ └── LinkNoteModal.tsx # Link note relationship modal
|
|
│ │ └── lib/ # Pure TS clients + config
|
|
│ │ ├── product-config.ts # Product identity + API URLs
|
|
│ │ ├── api-helpers.ts # Shared getAccessToken() + createNotesApiClient()
|
|
│ │ ├── auth.ts # @bytelyst/react-auth provider
|
|
│ │ ├── notes-client.ts # Notes API client (backend)
|
|
│ │ ├── review-client.ts # Approval queue, timeline, batch review
|
|
│ │ ├── saved-views-client.ts # Saved views CRUD client
|
|
│ │ ├── 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 # @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
|
|
│ ├── package.json
|
|
│ └── tsconfig.json
|
|
│
|
|
├── mobile/ # React Native + Expo companion app
|
|
│ ├── src/
|
|
│ │ ├── app/ # Expo Router screens
|
|
│ │ │ ├── (tabs)/ # 4-tab navigator (home, inbox, capture, settings)
|
|
│ │ │ ├── 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-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-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
|
|
│ └── 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
|
|
│
|
|
├── 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 # Docker preparation helper
|
|
├── .github/workflows/ci.yml # GitHub Actions CI (backend + web + mobile)
|
|
├── 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`, `@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 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
|
|
|
|
### 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`
|
|
- Use `@bytelyst/ui` components (Button, Card, Badge, Toast, etc.) — never build custom equivalents
|
|
- All colors via `--nl-*` CSS custom properties from `@bytelyst/design-tokens` — never hardcode hex values
|
|
- Every interactive element must have `aria-label` or visible text label
|
|
|
|
|
|
### .npmrc — NEVER edit directly
|
|
|
|
**`.npmrc` is managed by a canonical template in `learning_ai_common_plat`.** Never create or hand-edit `.npmrc` — it will drift.
|
|
|
|
- **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
|
|
|
|
- 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 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`)
|
|
- `saved_views` (partition: `/userId`)
|
|
- `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
|
|
|
|
```bash
|
|
# ── Backend ────────────────────────────────────────
|
|
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/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 |
|
|
| GET/PATCH/DELETE | `/api/saved-views/:id` | Saved view CRUD |
|
|
| POST | `/api/notes/:id/copilot` | Copilot text transform (shorten, expand, bulletize, etc.) |
|
|
| POST | `/api/notes/:id/suggest-title` | AI-generated title suggestion |
|
|
| POST | `/api/notes/:id/suggest-tags` | AI-generated tag suggestions |
|
|
| POST | `/api/notes/:id/check-duplicates` | Duplicate/similar note detection |
|
|
| POST | `/api/notes/:id/suggest-links` | Related note suggestions |
|
|
| POST | `/api/notes/compare` | Compare 2-5 notes via LLM |
|
|
| POST | `/api/notes/merge` | Merge 2-10 notes via LLM |
|
|
| POST | `/api/notes/chat` | Workspace RAG chat |
|
|
| 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 |
|
|
| GET | `/api/prompt-schedules/diagnostics` | Scheduler health |
|
|
| GET/POST | `/api/prompt-webhooks` | List / create webhook triggers |
|
|
| GET/PATCH/DELETE | `/api/prompt-webhooks/:id` | Webhook CRUD |
|
|
| 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
|
|
|
|
| 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 |
|
|
|
|
|
|
---
|
|
|
|
## Cross-Repo Automation
|
|
|
|
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/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.
|