docs: add agent knowledge base (#4)

Co-authored-by: Ona <no-reply@ona.com>

Author: zacharias-ona

.agents/README.md

@@ -1,12 +1,23 @@
 # Agent Knowledge Base
 
 This directory is the system of record for agent context. AGENTS.md in the repo root
-is the entry point — it points here for details.
+is the entry point and routing table — it points here for details.
 
-| File | Purpose | Updated by |
+Agents: start with AGENTS.md, then read the relevant file here before working.
+
+## Contents
+
+| File | Purpose | When to read |
 |---|---|---|
-| `architecture.md` | System architecture, component map, data flow | After structural changes |
-| `conventions.md` | Detailed coding patterns with examples | After new patterns emerge |
-| `quality.md` | Quality grades per domain | Automation Auditor (weekly) |
-| `plans/active/` | Current sprint plans | Feature Planner |
-| `plans/completed/` | Done plans | Moved here when complete |
+| `architecture.md` | System design, data model, component map | Before making structural changes or adding new features |
+| `conventions.md` | Coding patterns with examples | Before writing any new code |
+| `quality.md` | Quality grades per domain, known gaps | When deciding what to improve |
+| `plans/active/` | Current feature plans | Before picking up work |
+| `plans/completed/` | Done plans (context on past decisions) | When you need to understand why something was built a certain way |
+
+## How to update these files
+
+- `architecture.md` — update when adding new system components, changing data model, or making infrastructure decisions
+- `conventions.md` — update when a new coding pattern emerges that should be replicated, or when an anti-pattern is discovered
+- `quality.md` — updated weekly by the Automation Auditor, or manually after significant changes
+- Plans move from `active/` to `completed/` when all issues in the plan are closed

.agents/architecture.md

@@ -1,88 +1,85 @@
 # Architecture
 
-## System Overview
+## Overview
 
-Memo is a Notion-style workspace app. The stack is a standard Next.js App Router
-application backed by Supabase for persistence, auth, and realtime.
+Memo is a Notion-style workspace app: block-based editor, nested pages, workspaces,
+real-time collaboration. Built with Next.js 16 on Vercel, Supabase for data and auth,
+Sentry for error tracking.
+
+## System Diagram
 
 ```
-┌─────────────────────────────────────────────┐
-│                  Vercel                      │
-│  ┌───────────────────────────────────────┐   │
-│  │         Next.js 16 (App Router)       │   │
-│  │  ┌─────────┐  ┌──────────┐  ┌──────┐ │   │
-│  │  │  Pages   │  │   API    │  │ Mid- │ │   │
-│  │  │ (RSC +   │  │  Routes  │  │ ware │ │   │
-│  │  │  Client) │  │          │  │      │ │   │
-│  │  └────┬─────┘  └────┬─────┘  └──┬───┘ │   │
-│  │       │              │           │     │   │
-│  │       └──────┬───────┘           │     │   │
-│  │              │                   │     │   │
-│  │     ┌────────▼────────┐          │     │   │
-│  │     │  Supabase SSR   │◄─────────┘     │   │
-│  │     │  (client/server │                │   │
-│  │     │   /proxy)        │                │   │
-│  │     └────────┬────────┘                │   │
-│  └──────────────┼────────────────────────┘   │
-└─────────────────┼────────────────────────────┘
-                  │
-        ┌─────────▼─────────┐
-        │     Supabase      │
-        │  ┌─────────────┐  │
-        │  │ PostgreSQL   │  │
-        │  │ (RLS)        │  │
-        │  ├─────────────┤  │
-        │  │ Auth         │  │
-        │  ├─────────────┤  │
-        │  │ Realtime     │  │
-        │  └─────────────┘  │
-        └───────────────────┘
+Browser
+  ├── Server Components → Supabase server client (read data, cookie-based auth)
+  ├── Client Components → Supabase browser client (mutations, realtime subscriptions)
+  ├── API Routes (/api/*) → server-side logic, health checks
+  └── Proxy (src/proxy.ts) → Supabase session refresh, route protection
+
+Supabase
+  ├── PostgreSQL → workspaces, pages, blocks, members
+  ├── Auth → GitHub/Google OAuth, email/password
+  ├── Realtime → live collaboration (page edits, presence)
+  └── RLS → row-level security per workspace
+
+Sentry → error tracking, source maps, performance monitoring, session replay
+Vercel → hosting, preview deploys per PR, production deploys on merge
 ```
 
 ## Data Model
 
-The core entities follow a workspace → pages → blocks hierarchy:
+```
+workspace
+  ├── has many: members (user_id + role)
+  └── has many: pages
+        ├── belongs to: workspace
+        ├── has one: parent_page (nullable → enables nesting)
+        └── has many: blocks (ordered by position)
+              ├── type: text | heading_1 | heading_2 | heading_3 | bullet_list |
+              │         numbered_list | todo | code | image | divider | callout | toggle
+              └── content: JSON (structure varies by type)
+```
 
-- **Workspace**: top-level container, owns pages and members
-- **Page**: a document within a workspace, supports nesting (parent_id)
-- **Block**: content unit within a page, stored as JSON (Tiptap/BlockNote format)
+## Key Technical Decisions
 
-All tables use Supabase Row Level Security (RLS) to enforce access control.
+| Decision | Choice | Rationale |
+|---|---|---|
+| Editor library | Tiptap or BlockNote (evaluate before building) | Do NOT build a custom editor — this is months of work |
+| Content storage | JSON block tree in PostgreSQL | Flexible, queryable, no HTML parsing needed |
+| Auth | Supabase Auth with RLS | Row-level security at the DB layer, no app-level auth checks needed per query |
+| Realtime | Supabase Realtime subscriptions | Built into the client, no extra infrastructure |
+| Styling | Tailwind v4 + shadcn/ui | No custom CSS, consistent design system |
+| Package manager | pnpm | Strict dependency resolution, faster installs |
+| Session management | Next.js 16 proxy (not middleware) | `src/proxy.ts` with `updateSession` — Next.js 16 convention replacing middleware |
 
-## Key Decisions
+## Request Flow
 
-| Decision | Rationale |
-|---|---|
-| Next.js App Router | Server components by default, streaming, built-in layouts |
-| Supabase (not raw Postgres) | Auth, RLS, Realtime, and JS SDK out of the box |
-| Tiptap or BlockNote for editor | Block-based editing with slash commands, JSON output |
-| JSON block storage | Flexible schema for diverse block types |
-| No ORM | Direct Supabase client calls — simpler, fewer abstractions |
-| Tailwind + shadcn/ui | Consistent design system without custom CSS |
+1. User visits a page → proxy (`src/proxy.ts`) refreshes Supabase session via `updateSession`
+2. Server component renders with data from Supabase server client (`@/lib/supabase/server`)
+3. Client component hydrates, subscribes to Realtime for live updates
+4. User edits a block → client component writes to Supabase → Realtime broadcasts to other users
+5. Errors captured by Sentry (client via `instrumentation-client.ts`, server via `src/instrumentation.ts`)
 
 ## Component Map
 
 ```
 src/
 ├── app/                    # Next.js App Router
-│   ├── layout.tsx          # Root layout (fonts, global styles)
+│   ├── layout.tsx          # Root layout (Geist fonts, global styles)
 │   ├── page.tsx            # Landing page
 │   ├── global-error.tsx    # Sentry error boundary
-│   ├── api/
-│   │   └── health/         # Health check endpoint
-│   └── (auth)/             # Auth routes (future)
-├── components/
-│   └── ui/                 # shadcn/ui primitives
+│   └── api/
+│       └── health/route.ts # Health check endpoint (DB connectivity)
 ├── lib/
 │   └── supabase/
-│       ├── client.ts       # Browser client
-│       ├── server.ts       # Server component client
-│       └── proxy.ts        # Session refresh
-├── proxy.ts                 # Root proxy (Supabase session, Next.js 16 convention)
-└── instrumentation.ts      # Sentry server/edge init
+│       ├── client.ts       # Browser client (createBrowserClient)
+│       ├── server.ts       # Server component client (createServerClient + cookies)
+│       └── proxy.ts        # Session refresh logic (updateSession)
+├── proxy.ts                # Root proxy — calls updateSession, skips static/health routes
+└── instrumentation.ts      # Sentry server/edge init (register + onRequestError)
 ```
 
 ## Observability
 
-- **Sentry**: error tracking, performance monitoring, session replay
-- **Health endpoint**: `/api/health` — checks DB connectivity
+- **Sentry client**: session replay (10% normal, 100% on error), route transition tracking
+- **Sentry server**: PII enabled, local variables, 10% trace sampling in production
+- **Health endpoint**: `GET /api/health` — checks DB connectivity, returns status + latency