UI polish: header start-editing button, avatar initials, icon updates

.dev.vars.example

@@ -1,3 +1,9 @@
 # Fathom analytics (optional — omit to disable)
 VITE_FATHOM_SITE_ID=
 VITE_FATHOM_DOMAINS=
+
+# Identity (optional — omit to keep sign-in disabled). SESSION_SECRET signs
+# session JWTs (Workers secret in prod, `openssl rand -base64 32` locally);
+# GOOGLE_CLIENT_ID is the public Google OAuth client id for GSI sign-in.
+SESSION_SECRET=
+GOOGLE_CLIENT_ID=

.gitignore

@@ -21,3 +21,4 @@ worker-configuration.d.ts
 
 # Coverage
 /coverage/
+.superpowers/

CLAUDE.md

@@ -1,21 +1,34 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This repo follows the Artifact Primer: https://github.com/arfct/ops/tree/main/primer
 
-## Start of Session
+- Standards (style, commits, branches): https://github.com/arfct/ops/blob/main/primer/standards.md
+- Work tracking: Linear workspace `arfct`, team Artifact (A) — https://github.com/arfct/ops/blob/main/primer/linear.md
+- Bugs: https://github.com/arfct/ops/blob/main/primer/bugs.md · Deployment: https://github.com/arfct/ops/blob/main/primer/deployment.md
+- Agent conventions and boundaries: https://github.com/arfct/ops/blob/main/primer/agents.md
+
+## This repo
+
+vapor is a collaborative markdown editor — a fork of [mist](https://github.com/inanimate-tech/mist), deployed at https://vapor.fyi. `npm run dev` for local development, `npm run deploy` (with `CLOUDFLARE_ACCOUNT_ID` set) to ship to Cloudflare Workers. This is a fork: keep upstream's build tooling (ESLint config, CI) unchanged unless upstream changes it — don't propose tooling swaps here.
+
+### Start of Session
 
 Read project documents to load context:
 
 - `docs/design-system.md` — visual design, typography, colours, layout
 - `docs/technical-architecture.md` — platform, framework stack, directory structure, critical rules
+- `docs/plans/2026-08-30-agent-collaborators-design.md` — agent collaborators spec (tool surface, performance engine)
+- `docs/plans/2026-08-30-identity-design.md` — identity phase spec (Google sign-in, MCP OAuth, counterpart agents)
 
 Also check `plans/` for any active plan.
 
-## Project Overview
+### Project Overview
+
+vapor is a collaborative markdown editor — a cross between GitHub Gist and Google Docs. Users can quickly share and do multiplayer editing on markdown documents in real-time. Everything is public by URL. Sign-in (Google) is optional and adds identity/attribution, never a wall. Documents persist live with no save button. Documents auto-expire after 99 hours. AI agents can join documents as human-like collaborators over MCP (see "Agent collaborators" below).
 
-MIST is a collaborative markdown editor — a cross between GitHub Gist and Google Docs. Users can quickly share and do multiplayer editing on markdown documents in real-time. Everything is public by URL (no auth yet). Documents persist live with no save button. Documents auto-expire after 99 hours.
+Naming is "vapor" throughout: `APP_NAME`, page titles, the export frontmatter key (`vapor:`), and the theme localStorage key (`vapor-theme`).
 
-## Tech Stack
+### Tech Stack
 
 - **Backend:** Cloudflare Workers + Durable Objects (SQLite storage)
 - **Frontend:** React Router 7 (SSR) + Cloudflare Agents SDK
@@ -24,15 +37,15 @@ MIST is a collaborative markdown editor — a cross between GitHub Gist and Goog
 - **Language:** TypeScript (strict mode)
 - **Testing:** Vitest with v8 coverage
 
-## Prerequisites
+### Prerequisites
 
 Requires Node.js 22+ (see `.nvmrc`). Before running commands:
 
 ```bash
 source ~/.nvm/nvm.sh && nvm use
 ```
 
-## Commands
+### Commands
 
 ```bash
 npm run dev          # Local development server
@@ -51,29 +64,48 @@ npx vitest run tests/unit/lib/critic-parser.test.ts
 npx vitest run -t "pattern"
 ```
 
-## Architecture
+### Architecture
 
 See `docs/technical-architecture.md` for full details.
 
-### Directory Layout
+#### Directory Layout
 
-- `agents/` — Server-side Durable Object agents (currently just `DocumentAgent`)
+- `agents/` — Server-side Durable Object agents: `DocumentAgent` (document state), `VaporMcp` (MCP server), `Registry` (global identity + OAuth state)
 - `app/components/` — React UI components
 - `app/lib/` — Editor logic, CriticMarkup, Yjs provider, utilities
 - `app/shared/` — Constants and types shared between client and server
-- `app/routes/` — File-based routing (`home.tsx`, `docs.$id.tsx`, `new.ts`)
+- `app/routes/` — File-based routing (`home.tsx`, `doc.$id.tsx`, `new.ts`)
 - `workers/app.ts` — Cloudflare Worker entry point
+- `workers/routes.ts` — Pure handlers for `/:id.md` and the `/mcp` help page
 - `tests/` — Unit tests (`tests/unit/`) and integration tests (`tests/integration/`)
 
-### Import Path Alias
+#### Routes
+
+Documents render at the root path, not under `/docs`:
+
+| Route | Handler |
+|---|---|
+| `/` | `home.tsx` |
+| `/new` | `new.ts` |
+| `/:id` | `doc.$id.tsx` |
+| `/:id.md` | `workers/routes.ts` — raw markdown export |
+| `/mcp` | `agents/mcp.ts` (`VaporMcp`) — OAuth-gated MCP server |
+| `/mcp/anonymous` | `agents/mcp.ts` (`VaporMcp`) — tokenless MCP server |
+| `/auth/*` | `workers/routes.ts` — Google sign-in sessions |
+| `/oauth/*`, `/.well-known/oauth-*` | `workers/oauth.ts` — OAuth 2.1 AS for MCP |
+| `/agents/*` | `agents/document.ts` (`DocumentAgent`) — Yjs WebSocket |
+
+Root slugs share one namespace with a small reserved-word list (`app/shared/constants.ts`); the id generator and the `/:id` loader both guard against collisions.
+
+#### Import Path Alias
 
 `~` resolves to `app/` (configured in tsconfig and vitest). Use `~/lib/foo` instead of relative paths.
 
-### Critical Rule: Server/Client Separation
+#### Critical Rule: Server/Client Separation
 
 Client-side React components must **never** import from `agents/`. The `agents` package uses `cloudflare:` protocol imports that don't exist in the browser. Use `app/shared/` for types needed by both sides.
 
-### Real-Time Collaboration Flow
+#### Real-Time Collaboration Flow
 
 The multiplayer system works as follows:
 
@@ -82,7 +114,7 @@ The multiplayer system works as follows:
 3. **TipTap** uses `@tiptap/extension-collaboration` (bound to the Yjs doc's `XmlFragment`) and `@tiptap/extension-collaboration-caret` for cursor awareness.
 4. **Worker entry** (`workers/app.ts`) — `routeAgentRequest()` intercepts `/agents/:agent/:name` requests before React Router handles the rest.
 
-### CriticMarkup / Suggest Mode
+#### CriticMarkup / Suggest Mode
 
 Track-changes functionality spans multiple files:
 
@@ -92,13 +124,30 @@ Track-changes functionality spans multiple files:
 - `app/lib/critic-serializer.ts` — Serializes marks back to CriticMarkup delimiter syntax
 - `app/lib/critic-markup.ts` — TipTap extension that wires up the CriticMarkup marks and delimiter decorations
 
-### Testing Constraints
+#### Agent collaborators
+
+AI agents connect as MCP clients and edit through the same CriticMarkup/Yjs machinery humans use, with a performance engine that paces their typing to look human. Full design: `docs/plans/2026-08-30-agent-collaborators-design.md`.
+
+- **`VaporMcp`** (`agents/mcp.ts`) — an `McpAgent` (Cloudflare Agents SDK) served at `/mcp`. Stateless per document: each tool call names a `doc_id` and forwards to that doc's `DocumentAgent` via DO-to-DO RPC. Tool schemas and definitions live in `agents/mcp-tools.ts`.
+- **`DocumentAgent`** (extended) — owns the agent roster, performance queue, and event log alongside the Yjs doc; all mutations happen inside the DO that owns the document. Agent RPCs take a verified `AgentIdentity` (principal or anonymous) and enroll it into the roster on first touch — there are no per-doc tokens.
+- **`workers/routes.ts`** — pure (no `cloudflare:` imports) handlers for `GET /:id.md`, the MCP help page, and `/auth/*` sign-in, wired into `workers/app.ts`.
+
+#### Identity (Google sign-in + MCP OAuth)
+
+Ported from subpixel's dependency-free auth stack. Full design: `docs/plans/2026-08-30-identity-design.md`.
+
+- **`app/lib/auth.server.ts`** — Google ID-token verification (WebCrypto), HMAC session JWTs, the `vp_session` cookie. Identity is a principal (`email:<addr>`); sign-in is optional.
+- **`agents/registry.ts`** (`Registry` DO, one `"global"` instance) — profiles, counterpart agent slugs, and OAuth clients/codes/refresh tokens.
+- **`workers/oauth.ts`** — OAuth 2.1 AS (PKCE, dynamic registration, discovery). Access tokens are 1-hour session JWTs carrying the granted capabilities; the consent page (`app/lib/oauth-pages.ts`) is where write is granted. `/mcp` requires one of these; `/mcp/anonymous` needs none.
+- Secrets: `SESSION_SECRET` (Workers secret), `GOOGLE_CLIENT_ID` (public var). See `.dev.vars.example`.
+
+#### Testing Constraints
 
 - The `agents` package uses `cloudflare:` imports — it **cannot** be imported in plain Vitest. Test agent logic through integration tests or mock the imports. Unit tests should focus on pure logic in `app/lib/` and `app/shared/`.
 - Coverage thresholds ramp linearly from 0% to 80% between Feb–Dec 2026 (see `vitest.config.ts`).
 - Tests live in `tests/unit/` and `tests/integration/`, mirroring the source structure.
 
-### ESLint Conventions
+#### ESLint Conventions
 
 - Unused variables must be prefixed with `_` (e.g., `_args`, `_ctx`).
 - Tagged template expressions are allowed (for `this.sql` in Durable Objects).

README.md

@@ -1,95 +1,67 @@
-# mist
+# vapor
 
-Collaborative markdown editor. A cross between GitHub Gist and Google Docs — share and do multiplayer editing on markdown documents, quickly.
+You paste a draft into chat and now there are two copies, both going stale. vapor gives the draft one URL instead: a live markdown document anyone can open and edit, people and AI agents side by side, each with a cursor. It deletes itself after 99 hours.
 
-Everything is public by URL. Documents persist live with no save button. Multiple users see each other's cursors in real time.
+Running at [vapor.fyi](https://vapor.fyi). A fork of [mist](https://github.com/inanimate-tech/mist).
 
-## Features
+## Documents
 
-- **Real-time multiplayer editing** via TipTap + Yjs, backed by Cloudflare Durable Objects
-- **Live markdown formatting** — inline styles render as you type, with formatting characters shown in grey
-- **Suggest mode** — track changes using CriticMarkup (additions, deletions, comments, highlights)
-- **Threaded comments** with highlight anchoring
-- **Preview mode** — rendered markdown with click, hover, or keypress toggle
-- **CLI upload** — `curl https://your-domain/new -T file.md`
-- **Drag and drop** `.md` files to create new documents
-- **Dark/light/auto themes**
-- **Documents auto-expire** after 99 hours
+Anyone with the URL can read and edit. Live markdown with track changes (CriticMarkup), comments anchored to highlights, and a rendered preview. No accounts required, no save button, nothing kept past 99 hours—export before then.
 
-## Tech stack
-
-- [Cloudflare Workers](https://developers.cloudflare.com/workers/) + [Durable Objects](https://developers.cloudflare.com/durable-objects/) (backend + persistence)
-- [Cloudflare Agents SDK](https://developers.cloudflare.com/agents/) (real-time WebSocket agent)
-- [React Router 7](https://reactrouter.com/) (SSR)
-- [TipTap 3](https://tiptap.dev/) (editor)
-- [Yjs](https://yjs.dev/) (CRDT for multiplayer)
-- [Tailwind CSS 4](https://tailwindcss.com/) (styling)
-- TypeScript, Vitest
+```bash
+curl https://vapor.fyi/new -T notes.md    # create from a file
+curl https://vapor.fyi/<id>.md            # raw markdown back
+```
 
-## Getting started
+## People and agents
 
-### Prerequisites
+Sign-in (Google) is optional and only changes attribution:
 
-- Node.js 22+ (see `.nvmrc`)
-- A Cloudflare account (free tier works)
+| | Human | Agent |
+|---|---|---|
+| Anonymous | Curious Ladybug 🐞 | Agentic Butterfly 🦋 |
+| Signed in | Ada Lovelace | Ada's Agent |
 
-### Setup
+Your anonymous animal lives in localStorage and follows you between documents. Sign in and your name takes over, earlier comments included.
 
-```bash
-git clone https://github.com/inanimate-tech/mist.git
-cd mist
-npm install
-```
+## Connecting an agent
 
-### Development
+vapor is an [MCP](https://modelcontextprotocol.io) server. Two ways in:
 
 ```bash
-npm run dev
-```
+# signed in: stable identity, write access if you grant it
+claude mcp add --transport http vapor https://vapor.fyi/mcp
 
-### Deploy
+# anonymous: no setup, suggest and comment only
+claude mcp add --transport http vapor https://vapor.fyi/mcp/anonymous
+```
 
-Set your Cloudflare account ID via environment variable:
+Agents get suggest and comment by default; full write is a separate grant on the consent screen. Their edits type in at human pace with a visible cursor (`pace: "instant"` skips the show). Mention `@agent-name` in a document to wake an agent waiting on `await_events`.
 
-```bash
-export CLOUDFLARE_ACCOUNT_ID=your-account-id
-npm run deploy
-```
+Tools: `read_document` · `insert` · `replace` · `suggest` · `comment` · `reply` · `join` · `leave` · `await_events` · `create_document`. Each document's Agents panel lists who's enrolled, with revoke.
 
-### Optional: Analytics
+## How it's built
 
-To enable [Fathom](https://usefathom.com/) analytics, set these environment variables (or add to `.dev.vars`):
+Each document is one Cloudflare Durable Object holding the [Yjs](https://yjs.dev/) doc, agent roster, and event log. [TipTap](https://tiptap.dev/) and [React Router 7](https://reactrouter.com/) on the front, the [Agents SDK](https://developers.cloudflare.com/agents/) underneath, and a dependency-free auth stack (Google sign-in, OAuth 2.1 with PKCE and CIMD) ported from [subpixel](https://subpixel.app).
 
 ```
-VITE_FATHOM_SITE_ID=your-site-id
-VITE_FATHOM_DOMAINS=your-domain.com
+agents/    Durable Objects: DocumentAgent, VaporMcp, Registry
+app/       React Router app
+workers/   Worker entry, routes, OAuth server
+tests/     Unit + integration
 ```
 
-### Commands
-
-```bash
-npm run dev          # Local development server
-npm run build        # Production build
-npm run deploy       # Build and deploy to Cloudflare Workers
-npm run typecheck    # TypeScript type checking
-npm run lint         # ESLint
-npm run test         # Vitest with coverage
-npm run test:watch   # Vitest in watch mode
-```
+## Developing
 
-## Project structure
+Node 22+.
 
-```
-agents/       Durable Object agents (server-side document state)
-app/
-  components/ UI components
-  lib/        Editor logic, utilities, CriticMarkup, Yjs provider
-  routes/     File-based routing
-  shared/     Types and constants shared between client and server
-workers/      Cloudflare Worker entry point
-tests/        Test suite
+```bash
+npm install
+npm run dev      # local server
+npm run test     # also: typecheck, lint
+npm run deploy   # needs CLOUDFLARE_ACCOUNT_ID
 ```
 
-## Licence
+Sign-in needs `GOOGLE_CLIENT_ID` (a wrangler var) and `SESSION_SECRET` (a Workers secret); both optional in development. See `.dev.vars.example`. Design docs live in [docs/plans/](docs/plans/).
 
-[MIT](LICENSE)
+[Privacy](https://vapor.fyi/privacy) · [Terms](https://vapor.fyi/terms) · [MIT](LICENSE)