memory-loop

# Copilot Instructions

- **Scope**: Memory Loop is a Bun monorepo (backend library, Next.js 15 App Router frontend, shared Zod schemas). Core types live in [shared/src/types.ts](shared/src/types.ts) and are the source of truth for API and SSE event types.
- **Dev commands**: From repo root run `bun install`; `bun run --cwd nextjs dev` starts the Next.js dev server on port 3000; `bun run test` runs all workspaces sequentially; `bun run typecheck` and `bun run lint` fan out to all workspaces.
- **Environments**: Requires `VAULTS_DIR` pointing at folders containing a `CLAUDE.md` per vault. Optional `MOCK_SDK=true` disables real Anthropic calls; Next.js serves on `PORT`/`HOSTNAME` (defaults 3000/0.0.0.0). Production uses `bun run --cwd nextjs build` then [scripts/launch.sh](scripts/launch.sh).
- **Backend shape**: Backend is a library (no HTTP server) consumed by Next.js API routes. Domain logic lives in [backend/src/](backend/src/): session management, vault operations, streaming, note capture, file browsing. Next.js API routes in [nextjs/app/api/](nextjs/app/api/) are thin wrappers that call backend functions.
- **SSE streaming**: AI chat uses SSE via POST to `/api/chat`. The [Active Session Controller](nextjs/lib/controller.ts) is a singleton (survives Next.js HMR via globalThis) that manages the live SDK connection. Frontend sends prompts via REST, reads the SSE stream for incremental responses. Stop/permission/answer requests are separate REST calls alongside the stream.
- **Sessions**: Claude Agent SDK sessions are created/resumed via [backend/src/session-manager.ts](backend/src/session-manager.ts). Session metadata persists to vault metadata directory and is pruned to the most recent five per vault; IDs are validated to avoid traversal.
- **Vault discovery and goals**: [backend/src/vault-manager.ts](backend/src/vault-manager.ts) scans `VAULTS_DIR` for directories containing `CLAUDE.md`, extracts the first `#` heading as the vault name, detects inbox paths from common patterns, and optionally loads goals from `06_Metadata/memory-loop/goals.md`. Goals are parsed into sections with a 9-item cap.
- **Note capture**: [backend/src/note-capture.ts](backend/src/note-capture.ts) writes to `00_Inbox/YYYY-MM-DD.md` (creates inbox as needed), appends under `## Capture` with `- [HH:MM] text`, preserves existing content, and normalizes CRLF. Empty text returns a protocol error.
- **File browsing**: [backend/src/file-browser.ts](backend/src/file-browser.ts) whitelists markdown reads only, rejects symlinks, enforces vault-boundary checks (`realpath`), and truncates reads >1MB. Directory listings skip dotfiles and sort dirs-first.
- **Inspiration**: [backend/src/inspiration-manager.ts](backend/src/inspiration-manager.ts) pulls contextual prompts from `06_Metadata/memory-loop/contextual-prompts.md` (weekday-only generation) and weekly quotes from `06_Metadata/memory-loop/general-inspiration.md`. Context gathering prioritizes recent daily notes and project/area README/index files with a 3200-char budget.
- **Frontend state**: [nextjs/contexts/SessionContext.tsx](nextjs/contexts/SessionContext.tsx) is the single source of truth (useReducer). Modes: home, note, discussion, browse. Vault ID and browser path persist via localStorage; messages are server-sourced only. Pinned folders are stored per-vault locally.
- **SSE client**: [nextjs/hooks/useChat.ts](nextjs/hooks/useChat.ts) sends a POST to `/api/chat`, reads the SSE response stream, and dispatches events to SessionContext. Event types include `session_ready`, `response_chunk`, `tool_start`/`tool_end`, `request_permission`, and `ask_question`.
- **UI composition**: Root shell in [nextjs/app/page.tsx](nextjs/app/page.tsx) gates on vault selection (`VaultSelect`), then renders mode-specific components (`HomeView`, `NoteCapture`, `Discussion`, `BrowseMode`) with header actions for new session and vault switch dialogs.
- **Testing**: Backend tests use Bun's test runner under [backend/src/__tests__](backend/src/__tests__), often using temp dirs and mocked SDK. Next.js tests use `@testing-library/react` with happy-dom via [nextjs/test-setup.ts](nextjs/test-setup.ts). Shared tests live in [shared/src/__tests__](shared/src/__tests__).
- **Testing constraints**: Tests cannot run in parallel (filesystem contention causes flaky failures). Do not use `mock.module()` (causes infinite loops in Bun); use dependency injection instead. The SDK uses a provider pattern ([backend/src/sdk-provider.ts](backend/src/sdk-provider.ts)); tests use `configureSdkForTesting(mockFn)` to prevent accidental API calls.
- **Common pitfalls**: File reads must be `.md` relative to vault root. When mocking, set `MOCK_SDK=true`; otherwise the SDK will try to spawn Claude Code. SSE events are newline-delimited JSON with `data:` prefix.