docs: finalize product spec, architecture, and design for MVP buildout (#18)

- Rewrite docs/product-spec.md with all decisions locked in:
  Lexical editor, personal + team workspaces (3 limit),
  email/password auth, realtime deferred, members in scope
- Add data model (5 tables), acceptance criteria, URL routing,
  explicit dependency chains for Feature Planner issue decomposition
- Update .agents/architecture.md: Lexical implementation plan
  (packages, plugins, custom nodes), corrected data model,
  planned route structure
- Fix .agents/design.md: remove 'color' from toolbar items
  to match product spec acceptance criteria

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

Author: zacharias-ona

.agents/architecture.md

@@ -2,24 +2,25 @@
 
 ## Overview
 
-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.
+Memo is a Notion-style workspace app: Lexical block editor, nested pages, personal +
+team workspaces, member invitations. Built with Next.js 16 on Vercel, Supabase for
+data and auth, Sentry for error tracking. Realtime collaboration is deferred to post-MVP.
 
 ## System Diagram
 
 ```
 Browser
   ├── Server Components → Supabase server client (read data, cookie-based auth)
-  ├── Client Components → Supabase browser client (mutations, realtime subscriptions)
+  ├── Client Components → Supabase browser client (mutations, Lexical editor)
   ├── 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
+  ├── PostgreSQL → profiles, workspaces, members, workspace_invites, pages
+  ├── Auth → email/password (OAuth deferred — buttons rendered with "coming soon")
+  ├── Storage → image uploads for editor
+  ├── DB Triggers → handle_new_user (profile + personal workspace + owner membership)
+  └── RLS → row-level security per workspace membership
 
 Sentry → error tracking, source maps, performance monitoring, session replay
 Vercel → hosting, preview deploys per PR, production deploys on merge
@@ -29,45 +30,123 @@ Vercel → hosting, preview deploys per PR, production deploys on merge
 
 No database migrations exist yet. The schema below is the planned target model.
 Create migrations in `supabase/migrations/` as features are implemented.
+See `docs/product-spec.md` → Data Model for the full column-level schema.
 
 ```
-workspace
-  ├── has many: members (user_id + role)
+profiles (1:1 with auth.users)
+  └── created automatically on sign-up via handle_new_user trigger
+
+workspaces
+  ├── is_personal: boolean (personal workspace = non-deletable, always listed first)
+  ├── created_by → profiles.id
+  ├── Constraint: max 3 workspaces per user (created_by count, enforced via DB trigger)
+  ├── Constraint: one personal workspace per user (partial unique index)
+  ├── has many: members (user_id + role: owner | admin | member)
+  ├── has many: workspace_invites (email + role + token)
   └── 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)
+        ├── parent_id → pages.id (nullable, enables nesting)
+        ├── content: jsonb (Lexical editor state — NOT a separate blocks table)
+        ├── position: integer (ordering among siblings)
+        └── created_by → profiles.id
+
+Sign-up flow (atomic, via DB trigger):
+  1. auth.users row created by Supabase Auth
+  2. handle_new_user trigger fires → creates:
+     a. profiles row
+     b. workspaces row (is_personal = true, name = "{display_name}'s Workspace")
+     c. members row (role = owner)
 ```
 
 ## Key Technical Decisions
 
 | 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 |
+| Editor library | **Lexical** (Meta, MIT) | Full control, MIT license, Meta-backed. Build from lexical-playground reference, adapt to Tailwind + shadcn/ui. |
+| Content storage | Lexical JSON in PostgreSQL `jsonb` | `editorState.toJSON()` stored in `pages.content`. No separate blocks table. |
+| Auth | Supabase Auth — email/password | OAuth (GitHub, Google) deferred to post-MVP. Buttons rendered with "coming soon" tooltip. |
+| Workspace model | Personal + team workspaces | Auto-created personal workspace on sign-up (non-deletable). Max 3 created workspaces per user. Unlimited joined via invite. |
+| Realtime | Deferred to post-MVP | Yjs + Supabase Realtime adds complexity. Ship single-user editing first. |
 | 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 |
+| Floating UI | `@floating-ui/react` | Positioning for slash command menu, floating toolbar, link editor (same as Lexical playground) |
+| Image storage | Supabase Storage | Bucket for uploaded images, public URL stored in ImageNode |
+| Full-text search | PostgreSQL `tsvector` + `tsquery` | Generated column or trigger on page title + extracted content text |
+
+## Lexical Editor — Implementation Plan
+
+The Lexical playground (`facebook/lexical/packages/lexical-playground`) is the reference.
+We do NOT fork it. We build a Memo-specific editor using official Lexical packages,
+referencing the playground for patterns. All UI rebuilt with Tailwind + shadcn/ui.
+
+### Official Lexical packages (install from npm)
+
+| Package | Purpose |
+|---|---|
+| `lexical` | Core editor engine |
+| `@lexical/react` | React bindings (LexicalComposer, plugins, hooks) |
+| `@lexical/rich-text` | Headings, quotes, rich text support |
+| `@lexical/list` | Bullet, numbered, and check lists |
+| `@lexical/code` | Code blocks |
+| `@lexical/link` | Link nodes and auto-linking |
+| `@lexical/selection` | Selection utilities |
+| `@lexical/utils` | Shared utilities |
+| `@lexical/markdown` | Markdown import/export transforms |
+| `@lexical/clipboard` | Copy/paste handling |
+
+Pin to a specific version to avoid breaking changes.
+
+### Custom plugins (referencing playground)
+
+| Plugin | Playground reference | Complexity |
+|---|---|---|
+| ComponentPickerPlugin (slash commands) | `plugins/ComponentPickerPlugin` | Medium |
+| DraggableBlockPlugin (drag-and-drop) | `plugins/DraggableBlockPlugin` | High |
+| FloatingTextFormatToolbarPlugin | `plugins/FloatingTextFormatToolbarPlugin` | High |
+| FloatingLinkEditorPlugin | `plugins/FloatingLinkEditorPlugin` | Medium |
+| ImagesExtension | `plugins/ImagesExtension` | High |
+| CodeHighlightExtension | `plugins/CodeHighlightExtension` | Medium |
+| CollapsibleExtension (toggle blocks) | `plugins/CollapsibleExtension` | Medium |
+| ToolbarPlugin (top toolbar) | `plugins/ToolbarPlugin` | High |
+
+### Custom nodes
+
+| Node | Type | Purpose |
+|---|---|---|
+| ImageNode | DecoratorNode | Image display with caption, resize handles |
+| CalloutNode | ElementNode | Callout/alert block with emoji + text |
+| DividerNode | HorizontalRuleNode (`@lexical/extension`) | Horizontal divider |
+
+### Skipped plugins (not needed for MVP)
+
+ExcalidrawPlugin, EquationsPlugin, PollPlugin, FigmaExtension, MentionsPlugin,
+SpeechToTextPlugin, AutocompletePlugin, CommentPlugin, TablePlugin, LayoutPlugin,
+DateTimeExtension, VersionsPlugin.
+
+### Content storage flow
+
+```
+Save: editor.getEditorState().toJSON() → Supabase pages.content (jsonb)
+Load: editor.setEditorState(editor.parseEditorState(json))
+Auto-save: debounce 500ms on editor change → write to Supabase
+```
 
 ## Request Flow
 
 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
+3. Client component hydrates, initializes Lexical editor with saved content from `pages.content`
+4. User edits content → Lexical editor state changes → debounced auto-save writes `editorState.toJSON()` to Supabase
 5. Errors captured by Sentry (client via `instrumentation-client.ts`, server via `src/instrumentation.ts`)
 
 ## Component Map
 
+Current state (infrastructure only — no product features yet):
+
 ```
 src/
 ├── app/                    # Next.js App Router
-│   ├── layout.tsx          # Root layout (Geist fonts, global styles)
+│   ├── layout.tsx          # Root layout (currently Geist fonts — will switch to JetBrains Mono)
 │   ├── page.tsx            # Landing page
 │   ├── manifest.ts         # PWA manifest (name, icons, display mode)
 │   ├── global-error.tsx    # Sentry error boundary
@@ -88,6 +167,37 @@ Root config files:
 └── sentry.client.config.ts    # Sentry client SDK config
 ```
 
+Planned structure (added as features are built):
+
+```
+src/
+├── app/
+│   ├── (auth)/                        # Unauthenticated routes
+│   │   ├── sign-in/page.tsx           # /sign-in
+│   │   ├── sign-up/page.tsx           # /sign-up
+│   │   └── invite/[token]/page.tsx    # /invite/[token]
+│   ├── (app)/                         # Authenticated routes
+│   │   ├── layout.tsx                 # App shell (sidebar + main content)
+│   │   └── [workspaceSlug]/
+│   │       ├── page.tsx               # /[workspaceSlug] (workspace home)
+│   │       ├── [pageId]/page.tsx      # /[workspaceSlug]/[pageId] (editor)
+│   │       └── settings/
+│   │           ├── page.tsx           # /[workspaceSlug]/settings
+│   │           └── members/page.tsx   # /[workspaceSlug]/settings/members
+│   └── api/
+│       ├── health/                    # Existing
+│       └── ...                        # Additional API routes as needed
+├── components/
+│   ├── ui/                 # shadcn/ui components
+│   ├── editor/             # Lexical editor + plugins
+│   ├── sidebar/            # Sidebar, page tree, workspace switcher
+│   └── ...                 # Feature-specific components
+├── lib/
+│   ├── supabase/           # Existing
+│   └── types.ts            # Shared TypeScript types
+└── ...
+```
+
 ## Observability
 
 - **Sentry client**: session replay (10% normal, 100% on error), route transition tracking

.agents/design.md

@@ -229,7 +229,7 @@ Each block is a full-width element with consistent vertical spacing.
 ### Toolbar
 
 - Floating toolbar appears on text selection.
-- Items: bold, italic, underline, strikethrough, code, link, color.
+- Items: bold, italic, underline, strikethrough, code, link.
 - Icon-only buttons, 28px square, `gap-0.5`.
 - `bg-popover border border-white/[0.06] shadow-md p-1`. Sharp corners.