learning_ai_notes/AGENTS.md

AGENTS.md — AI Coding Agent Instructions

Read first (ecosystem-wide agent behavior): ../learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md

The link above is the single source of truth for agent behavior across every ByteLyst repo (Karpathy + ByteLyst rules: tests sacred, verify before done, no shared-infra hand-edits, no console.log/print, productId on every Cosmos doc, conventional commits, style preservation).

The per-repo content below extends — never duplicates — the canonical rules.

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 for full product spec, docs/ROADMAP.md for implementation status, docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md for the production-readiness checklist, and docs/UI_UX_PLATFORM_CORE_ROADMAP.md for UI/UX platform-core migration.

---

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)

1.1 Production-Readiness Status

As of May 22, 2026 (Sprint A + Sprint B re-verification), pnpm run verify is green end-to-end. See docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md § Post-Sprint-A Re-verification and docs/NEXT_SPRINT_ROADMAP.md for current sprint plan.

• Passing local gates: pnpm run verify (backend 382/382, web 96/96, mobile 97/97), backend/web/mobile lint (warnings only), pnpm run audit:release-guards, git diff --check.
• Operational runbooks: docs/runbooks/MEK_ROTATION.md, docs/runbooks/SECRET_MANAGEMENT.md.
• Archived (no longer active) execution docs live under docs/archive/ — keep them for context but do not use them as work sources.
• Environment deferrals: Docker compose smoke needs a Docker-capable host; shared-service smoke needs platform-service, extraction-service, mcp-server, and Cosmos credentials.

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 — backend, web, mobile, and Playwright E2E coverage. The May 5 production-readiness handoff passed local verify/lint/E2E gates with explicit Docker/shared-service environment deferrals recorded in docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md.

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
• For UI/UX migration work, follow docs/UI_UX_PLATFORM_CORE_ROADMAP.md: common-platform core UI first, thin NoteLett adapter second, product-local domain components only when behavior is NoteLett-specific
• 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)

docker-prep.sh — NEVER edit directly

scripts/docker-prep.sh and its _docker-prep-*.js helpers are managed by a canonical template in learning_ai_common_plat. Never hand-edit — drift across 9 repos compounds linearly.

• Template: ../learning_ai_common_plat/scripts/docker-prep.template.sh
• Helpers: ../learning_ai_common_plat/scripts/_docker-prep-{inject,strip}.js
• Sync: cd ../learning_ai_common_plat && bash scripts/sync-docker-prep.sh
• Drift check (CI): bash scripts/check-docker-prep-drift.sh
• Lint: bash scripts/docker-doctor.sh (or make doctor for both gitea-doctor + docker-doctor)

Local package source toggle

NoteLett defaults to local @bytelyst/* packages from ../learning_ai/learning_ai_common_plat through .pnpmfile.cjs; do not use Gitea unless explicitly needed.

• Local/common-platform install: pnpm run install:common-plat
• Registry fallback: source ~/.zshrc && pnpm run install:gitea
• Override common-platform path: BYTELYST_COMMON_PLAT_ROOT=/path/to/learning_ai_common_plat

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

Product/Common Platform Boundary

• Keep NoteLett domain logic product-local: notes, workspaces, relationships, tasks, artifacts, agent action audit trails, saved views, prompt templates/runners, intake, sharing/collaboration, versions, Palace memory/KG UX, and NoteLett-specific web/mobile workflows.
• Use ../learning_ai/learning_ai_common_plat for platform concerns: auth/session primitives, API clients, datastore/Cosmos abstractions, errors, config/logging conventions, telemetry, diagnostics, feature flags, kill switch, blob, extraction, design tokens, shared UI primitives where appropriate, MCP server integration, webhook dispatch, encryption helpers, and automation scripts.
• Do not move notes-specific contracts or behavior into common platform unless another ByteLyst product has a concrete reuse need.
• Do not add repo-local substitutes for platform services or packages that already exist in common platform.

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

# ── 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 production-readiness note: local verify, lint, web E2E, and release-guard audits pass. Docker compose and live shared-service smoke checks are explicit environment deferrals on this host; see docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md Phase P10 for exact commands and commit hashes.

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

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.