Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

docs: polish README/ARCHITECTURE/CONTRIBUTING for v0.1.0 GitHub push

Yuting Zhongebeb62c66db3
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index ceb3a840..57b79b49 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -14,35 +14,47 @@ USER'S MACHINE
│ │ │ │ on loopback │ │
│ │ ┌──────────────────────────────┐ │ └──────────┬───────────┘ │
│ │ │ Frontend (React + shadcn) │ │ │ subprocess │
-│ │ │ - Sidebar shell + nav │ │ ▼ │
-│ │ │ - CMO chat (SSE-streamed) │ │ ┌──────────────────────┐ │
-│ │ │ - Cron tab │ │ │ openclaw CLI │ │
-│ │ │ - Approval inbox (V0.1: stub)│ │ │ - agents add/list │ │
-│ │ │ - Cost meter (V0.1: zero) │ │ │ - cron add/list/rm │ │
-│ │ │ - Connections (OAuth) │ │ │ - agent (chat turn) │ │
-│ │ │ - Settings (guardrails) │ │ │ - memory search │ │
-│ │ └──────────────────────────────┘ │ └──────────────────────┘ │
+│ │ │ - Sidebar + project switcher│ │ ▼ │
+│ │ │ - Per-agent chat (SSE) │ │ ┌──────────────────────┐ │
+│ │ │ + threads + tool steps │ │ │ openclaw CLI │ │
+│ │ │ - Cron tab + calendar │ │ │ - agents add/list │ │
+│ │ │ - Approvals inbox (V1.1) │ │ │ - cron add/list/rm │ │
+│ │ │ - Tasks board (V1.1) │ │ │ - mcp set/show/unset│ │
+│ │ │ - Activity (audit log) │ │ │ - agent (chat turn) │ │
+│ │ │ - Connections (MCP catalog) │ │ │ - memory search │ │
+│ │ │ - Settings (guardrails) │ │ │ - skills add/rm │ │
+│ │ │ - Paired OpenClaw pill │ │ └──────────────────────┘ │
+│ │ │ - Onboarding (SSE stream) │ │ │
+│ │ └──────────────────────────────┘ │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ Server actions + API routes │ │ │
-│ │ │ - createProjectAction │ │ │
-│ │ │ (provisions 3 agents) │ │ │
-│ │ │ - scheduleCronAction │ │ │
-│ │ │ - pause/resume/deleteCron │ │ │
-│ │ │ - archiveProjectAction │ │ │
-│ │ │ (cascade-disables crons) │ │ │
+│ │ │ - createProject (provisions │ │ │
+│ │ │ 3 agents + MCPs) │ │ │
+│ │ │ - clone/create/rename/ │ │ │
+│ │ │ delete agent │ │ │
+│ │ │ - schedule/pause/resume/ │ │ │
+│ │ │ delete cron │ │ │
+│ │ │ - archive project (cascade │ │ │
+│ │ │ disables crons) │ │ │
+│ │ │ - MCP connect/disconnect │ │ │
+│ │ │ (one-click PKCE OAuth) │ │ │
│ │ │ - /api/chat (SSE) │ │ │
+│ │ │ - /api/onboarding/stream │ │ │
+│ │ │ - /api/mcp-oauth/callback │ │ │
│ │ │ - /api/oauth/{provider}/* │ │ │
+│ │ │ (env-var scaffold, V1.1) │ │ │
│ │ └──────────────────────────────┘ │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ Local SQLite │ │ │
│ │ │ ~/.notfair-cmo/db.sqlite │ │ │
│ │ │ - projects │ │ │
-│ │ │ - tasks (V0.2 wires up) │ │ │
-│ │ │ - approvals (V0.2) │ │ │
-│ │ │ - cost_events (V0.2) │ │ │
+│ │ │ - tasks (V1.1 wires up) │ │ │
+│ │ │ - approvals (V1.1) │ │ │
+│ │ │ - cost_events (V1.1) │ │ │
│ │ │ - oauth_tokens (encrypted) │ │ │
│ │ │ - guardrails (config) │ │ │
│ │ │ - agent_actions (audit log) │ │ │
+│ │ │ - sequence_runs │ │ │
│ │ └──────────────────────────────┘ │ │
│ └────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
@@ -55,22 +67,28 @@ USER'S MACHINE
- Cron scheduler with agent attribution + run history
- Built-in memory subsystem with REM (reflective episodic memory)
- WebSocket gateway with auth modes
-- MCP server registration framework
+- MCP client (`openclaw mcp set/show/unset`) with per-agent allowlists
- Multi-channel delivery (Telegram, Slack, iMessage, etc.)
We don't reimplement any of that. notfair-cmo adds:
- A product-shaped chat + management UI scoped per marketing project
- A consistent naming convention (`<project> / <agent> / <cron>`) so OpenClaw's flat namespace becomes hierarchical to the user
+- A project-scoped MCP catalog with one-click PKCE OAuth onboarding (`/connections`)
- Local SQLite for product-specific state (tasks, approvals, cost events, OAuth tokens) that doesn't belong in OpenClaw's model
- AES-256-GCM encrypted OAuth token vault with OS-keychain master key
+- An append-only `agent_actions` audit log surfaced as the Activity tab
+
+## Agent ↔ notfair-cmo interaction (V1)
-## Agent ↔ notfair-cmo interaction (V0.1)
+Two interaction layers:
-Agents are taught (via system prompt in their workspace `IDENTITY.md`) to use OpenClaw's built-in `exec` tool to run `openclaw cron add ...` directly. The system prompt enforces the project-namespaced naming convention so our cron tab parses + groups correctly.
+1. **Chat turn over the gateway WebSocket.** `/api/chat` proxies to OpenClaw's gateway via a pooled WS connection (`server/openclaw/gateway-client.ts`), streams tool calls + assistant text back as SSE, and persists the thread file through the gateway so reloads see full history.
-There is **no MCP server** in V0.1. We considered one but found agents have direct CLI access via `exec`, which made the MCP layer redundant.
+2. **Cron creation by the agent.** Agents are taught (via system prompt in `IDENTITY.md`) to use OpenClaw's built-in `exec` tool to run `openclaw cron add ...` directly. The system prompt enforces the project-namespaced naming convention so our cron tab parses + groups correctly.
-V0.2 wires the autonomy/cost/approval features through MCP tools (the implementations exist as backend helpers — they just don't get exposed to agents yet).
+**No MCP server hosted by notfair-cmo.** We don't expose tools as an MCP server — agents call third-party MCP servers (e.g. `notfair-googleads`) that OpenClaw connects to on their behalf. The Connections page is the UI for that wiring; cross-project visibility is enforced by OpenClaw's `codex.agents` allowlist which `actions/mcp.ts` keeps in sync with the active project's agent ids.
+
+The autonomy/cost/approval features land in V1.1 — the SQLite tables, server helpers, and UI stubs are in place; the agent-side `record_cost` / `approve_action` enforcement hooks aren't wired yet.
## Distribution
@@ -78,70 +96,134 @@ V0.2 wires the autonomy/cost/approval features through MCP tools (the implementa
- Next.js standalone build (`.next/standalone/server.js` shipped, started by `bin/cli.mjs`)
- Native deps: `better-sqlite3` (Node 24 prebuilds available), `keytar` (prebuilds for major platforms)
- Runtime requires: Node 20+, OpenClaw installed and gateway running
+- `scripts/copy-standalone-assets.mjs` runs after `next build` so the npm tarball ships a runnable `.next/standalone` tree (Next omits `.next/static` + `public` by default).
## Module map
```
bin/
- cli.mjs # CLI entry: `notfair-cmo` (start, doctor, stop)
+ cli.mjs # CLI entry: `notfair-cmo` (start, doctor, stop)
+
+scripts/
+ copy-standalone-assets.mjs # post-build: dereference symlinks into standalone tree
+ e2e-provision.ts # dev helper: create a project + provision its agents
src/
app/
- layout.tsx # Root layout (TooltipProvider, Toaster)
- (app)/ # Sidebar-shell route group
- layout.tsx # SidebarProvider + AppSidebar + main
- page.tsx # Project home (KPIs + recent actions)
- chat/ # CMO chat (SSE-streamed)
- approvals/ # Approval inbox (V0.2 wires fully)
- tasks/ # Task board (V0.2 wires fully)
- crons/ # Cron tab — read+write via UI + agent exec
- connections/ # OAuth: Google Ads + GSC
- settings/ # Guardrails config
- projects/ # List + new
- onboarding/ # Magic moment (placeholder steps)
+ layout.tsx # Root layout (TooltipProvider, Toaster, theme)
+ globals.css
+ (app)/ # Sidebar-shell route group
+ layout.tsx # SidebarProvider + AppSidebar + main
+ page.tsx # Project home (KPIs + recent actions)
+ agents/ # Per-agent surface
+ page.tsx # Agent index for the active project
+ [agent]/
+ page.tsx # Agent overview
+ chat/ # Threaded chat (SSE)
+ page.tsx
+ [thread]/page.tsx
+ cron/page.tsx # Per-agent crons
+ files/page.tsx # Workspace files
+ settings/page.tsx # Rename + danger zone
+ skills/page.tsx # OpenClaw skills assigned to this agent
+ activity/page.tsx # Append-only agent_actions audit log
+ approvals/page.tsx # Pending approvals (V1.1 wires fully)
+ tasks/page.tsx # Task board (V1.1 wires fully)
+ crons/page.tsx # All crons for the project (calendar + list)
+ connections/page.tsx # MCP catalog: connect/disconnect per project
+ settings/page.tsx # Autonomy guardrails + project rename/danger
+ projects/ # List + new
+ page.tsx
+ new/page.tsx
+ onboarding/ # Magic-moment first run
+ layout.tsx
+ page.tsx
api/
- chat/ # POST → SSE stream from openclaw agent
- oauth/ # OAuth start/callback for Google Ads, GSC
- projects/[slug]/provision/ # Re-provision agents
+ chat/route.ts # POST → SSE stream via gateway WS
+ onboarding/stream/route.ts # SSE: magic-moment provisioning
+ mcp-oauth/callback/route.ts # One-click MCP PKCE callback
+ oauth/[provider]/start/route.ts # Env-var direct OAuth (scaffold)
+ oauth/[provider]/callback/route.ts # Env-var direct OAuth (scaffold)
+ projects/[slug]/provision/route.ts # Re-provision agents for a project
server/
- active-project.ts # cookie-backed current project
+ active-project.ts # cookie-backed current project
+ agent-meta.ts # per-agent display metadata (name, role, color)
+ agent-templates.ts # CMO / google_ads / seo definitions + IDENTITY.md writer
+ mcp-catalog.ts # static known-MCP catalog (notfair-googleads, …)
+ mcp-pending.ts # in-memory pending OAuth flows (PKCE state)
+ mcp-state.ts # merged config + health probe per MCP
actions/
- projects.ts # create (+provision), archive (cascade), rename, switch
- crons.ts # schedule, pause, resume, delete
- approvals.ts # approve, reject (V0.2 fully wired)
- guardrails.ts # update thresholds
- agent-templates.ts # CMO / google_ads / seo definitions + IDENTITY.md writer
+ projects.ts # create (+provision), archive (cascade), rename, switch
+ agents.ts # clone, create, rename, delete (cascade)
+ crons.ts # schedule, pause, resume, delete
+ cron-runs.ts # surface run history from OpenClaw
+ approvals.ts # approve, reject (V1.1 fully wired)
+ guardrails.ts # update thresholds
+ mcp.ts # one-click PKCE connect/disconnect
+ skills.ts # assign/remove OpenClaw skills on agents
openclaw/
- cli.ts # subprocess wrapper: openclaw(args)
- agent-turn.ts # streaming agent invocation
- crons.ts # cron list parser + naming convention
+ cli.ts # subprocess wrapper: openclaw(args)
+ gateway-client.ts # pooled WebSocket client + token discovery
+ gateway-rpc.ts # request/response over the gateway WS
+ agent-turn.ts # streaming agent invocation
+ sessions.ts # chat-session lookup + pending-key registry
+ crons.ts # cron list parser + naming convention + cache
+ cron-schedule.ts # next-fire calculation (cron-parser)
+ clone-agent.ts # `openclaw agents clone` wrapper
+ project-delete.ts # cascade-delete a project's agents + crons
db/
- db.ts # better-sqlite3 singleton + migration runner
- migrations.ts # embedded SQL migrations (forward-only)
+ db.ts # better-sqlite3 singleton + migration runner
+ migrations.ts # embedded SQL migration manifest
+ migrations/001_init.sql # canonical SQL (mirrored into migrations.ts)
projects.ts, tasks.ts, approvals.ts, cost.ts,
oauth.ts, guardrails.ts, agent-actions.ts
secrets/
- master-key.ts # OS keychain (keytar) master key
- cipher.ts # AES-256-GCM encrypt / decrypt
+ master-key.ts # OS keychain (keytar) master key
+ cipher.ts # AES-256-GCM encrypt / decrypt
components/
- app-sidebar.tsx # Sidebar with project switcher + nav + cost meter
+ app-sidebar.tsx # Sidebar with project switcher + nav + status pill
project-switcher.tsx
- cost-meter.tsx # Sidebar widget with hover breakdown
- cmo-chat.tsx # Streamed chat with Stop button
+ paired-openclaw-pill.tsx # Sidebar pill → opens gateway dashboard with token
+ agent-nav.tsx # Sidebar's per-agent navigation
+ agent-tabs.tsx # Agent sub-nav (chat / cron / files / settings / skills)
+ agent-chat.tsx # Streamed chat with Stop button + inline tool steps
+ thread-selector.tsx # Thread picker in the agent chat
+ markdown.tsx # GFM markdown renderer (assistant output)
+ slash-command-popover.tsx # /command popover in chat composer
schedule-cron-dialog.tsx
cron-row-actions.tsx
+ cron-calendar.tsx
+ create-agent-button.tsx
+ create-agent-dialog.tsx
+ agent-rename-card.tsx
+ agent-danger-zone.tsx
+ reprovision-button.tsx
+ project-rename-card.tsx
+ danger-zone.tsx
+ disable-source-crons-dialog.tsx
+ mcp-card.tsx # Per-MCP card on the Connections page
+ mcp-flash-banner.tsx # Post-redirect success/error banner
+ google-ads-mcp-banner.tsx # Inline prompt in Google Ads chat to connect MCP
approval-card.tsx
+ skills-list.tsx
onboarding-flow.tsx
- ui/ # shadcn primitives
+ client-mount-gate.tsx # Defer client-only children until after mount
+ ui/ # shadcn primitives
+
+ hooks/
+ use-mobile.ts
lib/
- slug.ts # slugify + reserved-word check
- utils.ts # cn() for shadcn
+ slug.ts # slugify + reserved-word check
+ utils.ts # cn() for shadcn
+ agent-colors.ts # deterministic per-agent accent
+ slash-commands.ts # /command registry for the chat composer
+ onboarding/steps.ts # magic-moment step definitions
types/
- index.ts # Project, Task, Approval, CostEvent, etc.
+ index.ts # Project, Task, Approval, CostEvent, etc.
```
## What we deliberately don't have
@@ -149,13 +231,22 @@ src/
- No auth, no sessions, no users table — single-user local
- No multi-tenancy, no RLS — single SQLite file
- No webhook signing / reconciliation — loopback only, trusted
-- No MCP server (V0.1) — agents use OpenClaw's native `exec`
+- No notfair-hosted MCP server — agents talk to OpenClaw's MCP clients
- No telemetry — opt-in only when added in a later version
-- No Docker / Tauri distribution (V0.1) — npm only
+- No Docker / Tauri distribution (V1) — npm only
+
+## Deferred to V1.1
+
+- Approval enforcement: the `approvals` table + UI are live; agent-side `approve_action` gating isn't wired
+- Cost tracking: `cost_events` + helpers + Settings thresholds exist; per-LLM-call middleware that records cost isn't wired (the sidebar shows a Paired OpenClaw pill instead of a cost meter in V1)
+- Task lifecycle UI: the `tasks` table + types exist; the board reflects them, but the proposer/approver loop isn't end-to-end
+- Cross-project signal sharing (agents reading each other's REM)
+- Eval harness + test suite (Vitest unit + Playwright E2E; mocked at the `openclaw/cli.ts` boundary)
+- Direct env-var OAuth UI (Google Ads / GSC) — the API routes scaffold the flow; no Connections-page UI surface yet (the MCP one-click flow covers the V1 Google Ads path)
## Trade-offs to know about
- **Agent name discipline depends on system prompt.** If the agent forgets the `<project> / <agent> / <name>` convention, the cron lands in our "ungrouped" bucket — graceful degradation, not broken.
-- **Cost meter shows zero by default** until V0.2 wires in the AI SDK middleware that records LLM usage via our `record_cost` helper.
-- **Approval inbox is a placeholder** until V0.2 wires the `approve_action` enforcement into agent flows.
+- **Connections is project-scoped, but OpenClaw's `mcp` config is workspace-global.** We namespace stored keys with the project slug (`<slug>-<catalog-key>`) and rewrite `codex.agents` to that project's agents so tokens don't bleed across projects.
- **No agent ↔ agent direct messaging.** Agents coordinate by reading each other's OpenClaw memory entries (which agents already do natively via `memory search`).
+- **Gateway WS is pooled and reused per request.** Cold-start cost lives in the first chat turn; subsequent turns hit a warm connection via `gateway-client.ts`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c12d8d98..7aad0091 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,63 +5,123 @@ Thanks for poking around! notfair-cmo is small, opinionated, and willing to grow
## Dev setup
```bash
-git clone <repo>
+git clone https://github.com/notfair-co/notfair-cmo.git
cd notfair-cmo
pnpm install
```
-Native deps (`better-sqlite3`, `keytar`) need build approvals on pnpm — already configured in `package.json` under `pnpm.onlyBuiltDependencies`, just runs on install.
+Native deps (`better-sqlite3`, `keytar`) need build approvals on pnpm — already
+configured in `package.json` under `pnpm.onlyBuiltDependencies`, so they build
+on install with no extra prompts.
Make sure you have:
-- Node 20+ (24 preferred)
-- OpenClaw installed and `openclaw gateway` running
-- Whatever LLM provider your OpenClaw uses (the project inherits `agents.defaults.model`)
+- Node 20+ (24 preferred — that's what the prebuilt `better-sqlite3` / `keytar` binaries target)
+- OpenClaw installed and `openclaw gateway` running (`openclaw health` should return ok)
+- Whatever LLM provider your OpenClaw uses configured under `agents.defaults.model`
+
+Quickest way to verify the host machine is set up is the doctor, which the
+shipped CLI exposes and which you can run against the dev source too:
+
+```bash
+pnpm cli doctor # same checks the published `notfair-cmo doctor` runs
+```
+
+## Dev loop
```bash
-pnpm typecheck # tsc --noEmit
-pnpm dev # next dev --turbopack
-pnpm build # next build (standalone output)
-pnpm cli # tsx bin/cli.ts (CLI in dev)
+pnpm dev # next dev --turbopack on port 3326 (avoids the 3000 prod default)
+pnpm typecheck # tsc --noEmit
+pnpm lint # next lint
+pnpm build # next build + scripts/copy-standalone-assets.mjs (npm-tarball-ready)
+pnpm cli # tsx bin/cli.ts in dev (the published CLI is bin/cli.mjs)
```
+`pnpm dev` is the day-to-day. The dev server points at the same
+`~/.notfair-cmo/db.sqlite` as a globally installed `notfair-cmo` does, so if
+you also run the published CLI on this machine, point one of them at a
+different data dir to avoid stomping each other's state:
+
+```bash
+NOTFAIR_CMO_DATA_DIR=$PWD/.notfair-cmo-dev pnpm dev
+```
+
+`.notfair-cmo-dev/` is already gitignored.
+
+To reset local state for a clean run, stop any running server and:
+
+```bash
+rm ~/.notfair-cmo/db.sqlite # blow away product state
+rm -rf ~/.notfair-cmo/agents/ # blow away agent workspaces
+openclaw agents rm <agent-name> # remove any orphaned agents
+```
+
+Migrations are forward-only (`src/server/db/migrations/00N_<name>.sql`,
+mirrored into `src/server/db/migrations.ts`), so the next start re-creates
+schema cleanly.
+
## Project shape
See `ARCHITECTURE.md`. Short version:
-- Frontend: Next.js 16 App Router + React 19 + Tailwind 4 + shadcn/ui
-- Backend: Next.js server actions + SQLite (better-sqlite3) + subprocess wrapper around `openclaw`
-- No MCP server — agents use OpenClaw's built-in `exec` tool
+- Frontend: Next.js 16 App Router + React 19 + Tailwind 4 + shadcn/ui (zinc palette, Inter font)
+- Backend: Next.js server actions + SQLite (better-sqlite3) + subprocess wrapper around `openclaw` + pooled WebSocket client into OpenClaw's gateway
+- AI SDK v4 today (the `ai` package + `@ai-sdk/{anthropic,openai}` v1) — v6 migration tracked in PLAN.md
+- We don't host an MCP server; agents talk to third-party MCP servers (e.g. NotFair Google Ads) that OpenClaw connects to. Connections page is the UI for that.
## Adding a feature
1. Open an issue describing the user-facing change (the *what* and *why*).
-2. Branch off main.
+2. Branch off `main`.
3. Build it. Keep modules small. shadcn primitives over custom CSS.
-4. Run `pnpm typecheck && pnpm build`. Both must pass.
-5. If you're touching cron / agent / approval / OAuth flows, exercise it end-to-end against a real OpenClaw install — the test agents we ship as scripts/ examples are the right starting point.
+4. Run `pnpm typecheck && pnpm lint && pnpm build`. All three must pass.
+5. If you're touching cron / agent / approvals / OAuth / MCP flows, exercise it end-to-end against a real OpenClaw install — `scripts/e2e-provision.ts` is a starting point for spinning up a fresh project + agents from a script.
6. Update README / ARCHITECTURE if behavior changed.
7. Open a PR. Describe what you changed and how to verify.
## Module conventions
-- Server-only modules live in `src/server/`. Anything in there can use `node:*` modules + native deps.
-- Client components: start the file with `"use client";`.
-- Server actions: `"use server";`. Throw on validation failure (form actions) or return discriminated `{ok: true, ...} | {ok: false, error}` (programmatic).
-- Database access: only via helpers in `src/server/db/`. Don't reach for `getDb()` from a component or route.
-- OpenClaw access: only via helpers in `src/server/openclaw/`. Don't shell out to `openclaw` directly from a route.
-- Slugs: only via `src/lib/slug.ts`. Reserved words checked.
-- Types: shared types go in `src/types/`. Server-only types stay near their server module.
+- **Server-only modules** live in `src/server/`. Anything in there can use `node:*` modules + native deps.
+- **Client components**: start the file with `"use client";`.
+- **Server actions**: `"use server";`. Throw on validation failure (form actions) or return discriminated `{ ok: true, ... } | { ok: false, error }` (programmatic).
+- **Database access**: only via helpers in `src/server/db/`. Don't reach for `getDb()` from a component or route.
+- **OpenClaw access**: only via helpers in `src/server/openclaw/`. Don't shell out to `openclaw` directly from a route; don't open a fresh gateway WS — use `gateway-client.ts` (it's pooled).
+- **Slugs**: only via `src/lib/slug.ts`. Reserved words checked.
+- **Types**: shared types go in `src/types/`. Server-only types stay near their server module.
## Style
- TypeScript strict mode. No `any` unless interfacing with untyped externals.
- Prefer named exports. Default exports only for Next.js pages/layouts/route handlers.
-- shadcn/ui defaults — no custom color palette, no custom typography, no decorative blobs. The zinc neutral palette is the brand for V0.x.
+- shadcn/ui defaults — no custom color palette, no custom typography, no decorative blobs. The zinc neutral palette is the brand for V1.
+- No comments unless the *why* is non-obvious. Identifiers do the explaining; PR descriptions carry the context.
+
+## Commits + PRs
+
+- One logical change per commit. Subject line in active voice (`add`, `fix`, `wire`, `remove`) and conventional-commit prefix when natural (`feat:`, `fix:`, `perf:`, `build:`, `feat(chat):`). Look at `git log` — recent history is the template.
+- End every commit with the Paperclip co-author trailer (this is how the founding engineer + future contributors are credited):
+
+ ```
+ Co-Authored-By: Paperclip <[email protected]>
+ ```
+
+- Never bypass hooks (`--no-verify`), never skip signing, never force-push without an explicit ask.
+- Don't commit secrets. If a `.env`, OAuth token, or API key shows up in a diff, stop and fix the diff before pushing.
+
+## Known lint noise
+
+`pnpm lint` currently reports a handful of React-19 strictness warnings
+(`react-hooks/set-state-in-effect`, `react-hooks/purity`,
+`react-hooks/static-components`) that were not surfaced by Next 15's
+`next lint`. None of them are runtime bugs — they flag patterns React 19
+wants migrated (set-state-in-effect → derived state or `key` resets;
+`Math.random` / `Date.now` in render → memoize or move outside render).
+Tracked for cleanup before broad public push. New code should not add to
+the list — if you hit one, fix it in the same PR.
## Testing
-V0.1 doesn't ship a test suite (intentionally — we validated end-to-end against a real OpenClaw install instead of writing mocks). Test infrastructure lands in V0.2 along with the eval harness.
+V1 doesn't ship a test suite (intentionally — we validated end-to-end against a real OpenClaw install instead of writing mocks). Test infrastructure lands in V1.1 along with the eval harness.
-If you want to add tests now: Vitest for unit, Playwright for E2E. Mock OpenClaw at the subprocess wrapper level (`src/server/openclaw/cli.ts`).
+If you want to add tests now: Vitest for unit, Playwright for E2E. Mock OpenClaw at the subprocess wrapper level (`src/server/openclaw/cli.ts`) and the gateway WS at `gateway-client.ts`.
## License
diff --git a/README.md b/README.md
index e3b63b79..5e665282 100644
--- a/README.md
+++ b/README.md
@@ -6,26 +6,27 @@ Open source. Runs entirely on your machine. Bring your own LLM credentials (via
## What it gives you
-- A **CMO chat** per project — talk to a marketing-shaped agent that can launch campaigns, audit SEO, kick off cron jobs.
-- **Specialist agents** (Google Ads, SEO) auto-provisioned per project, isolated in their own OpenClaw workspaces.
-- A **cron tab** that parses OpenClaw's cron list and groups it by project + agent so attribution is obvious.
-- An **approval inbox** and **cost meter** sketched into the sidebar (placeholders in v0.1; live in v0.2 when autonomy guardrails wire up).
-- **Connections** UI for OAuth (Google Ads, Google Search Console).
+- **Per-agent chat** scoped to each project — talk to a marketing-shaped agent that can launch campaigns, audit SEO, kick off cron jobs. Tool calls + MCP invocations stream inline as collapsible step rows.
+- **Specialist agents** (CMO + Google Ads + SEO) auto-provisioned per project, isolated in their own OpenClaw workspaces. Clone or create more from the sidebar.
+- A **cron tab** (calendar + list) that parses OpenClaw's cron list and groups it by project + agent so attribution is obvious.
+- **Project-scoped MCP connections** — one-click PKCE OAuth to bring third-party tools (e.g. Google Ads via NotFair's hosted MCP) into the agents' toolbox without touching environment variables.
+- An **Activity log** — every autonomous decision and scheduled run lands in an append-only audit trail.
+- An **approvals inbox**, **autonomy guardrails**, and **task board** scaffolded for V1.1 (the SQLite tables and UI are in place; agent-side enforcement wires up in the next milestone).
## Prerequisites
- **[OpenClaw](https://docs.openclaw.ai/install)** installed and the gateway running on this machine (`openclaw gateway`).
-- **Node 20+** (Node 24 recommended).
+- **Node 20+** (Node 24 recommended for native-module prebuilds).
- An LLM provider configured in your OpenClaw config (the project inherits `agents.defaults.model` — primary + fallbacks chain).
-Run `notfair-cmo doctor` to verify all three.
+Run `notfair-cmo doctor` to verify all of the above plus your data dir and port.
## Install + run
```bash
# One-shot, no install:
npx notfair-cmo@latest doctor # verify env
-npx notfair-cmo@latest # launch UI on localhost:3000
+npx notfair-cmo@latest # launch UI on http://127.0.0.1:3000
# Or install globally:
npm install -g notfair-cmo
@@ -44,14 +45,17 @@ notfair-cmo --version
notfair-cmo --help
```
-Options on `start`: `--port <n>`, `--no-open`, `--data-dir <path>`.
+Options on `start`: `--port <n>` (default 3000), `--no-open`, `--data-dir <path>`.
Options on `doctor`: `--port <n>`, `--data-dir <path>`.
-`doctor` verifies, in order: Node ≥20, OpenClaw on PATH, OpenClaw gateway
-reachable on loopback, an LLM provider configured per `agents.defaults.model`
-(from your OpenClaw config), your data dir is writable, and the preferred port
-is free (probes 3000 → +5). Exits 0 if all checks pass; 1 otherwise, with a
-`Fix:` line under each failure naming the exact command to run.
+`doctor` runs six checks in order: Node ≥ 20 (24 recommended), `openclaw` on
+PATH, OpenClaw gateway reachable on loopback (defaults to `openclaw health`,
+falls back to a TCP probe on `gateway.port`), an LLM provider configured per
+`agents.defaults.model` (chain-aware: primary + fallbacks; either the OpenClaw
+config or a recognized `*_API_KEY` env var counts as configured), the data dir
+writable, and the preferred port free (probes the preferred port + 5 above
+it). Exits 0 if all checks pass, 1 otherwise, with a `Fix:` line under each
+failure naming the exact command to run.
## What happens when you create a project
@@ -60,30 +64,32 @@ is free (probes 3000 → +5). Exits 0 if all checks pass; 1 otherwise, with a
- `<slug>-cmo` — Chief Marketing Officer
- `<slug>-google-ads` — Google Ads specialist
- `<slug>-seo` — SEO specialist
- Each gets its own workspace at `~/.notfair-cmo/agents/<name>/` and a `IDENTITY.md` system prompt scoped to its role.
-3. You're redirected to the project home. Click **Chat with CMO** to start.
-## Scheduling recurring work
+ Each gets its own workspace at `~/.notfair-cmo/agents/<name>/` and an `IDENTITY.md` system prompt scoped to its role.
+3. The onboarding stream walks you through the "magic moment" preview steps over SSE, then redirects to the project home. Click into any agent to start a thread.
-Agents have OpenClaw's built-in `exec` tool, so they create their own cron jobs by running `openclaw cron add` with our naming convention. You can also schedule manually via the **+ New cron** button on the Crons tab.
+## Scheduling recurring work
-Cron names follow `<project-slug> / <agent-slug> / <cron-slug>` so the tab can group them.
+Agents have OpenClaw's built-in `exec` tool, so they create their own cron jobs by running `openclaw cron add ...` with our naming convention. You can also schedule manually via the **+ New cron** button on the Crons tab.
-## OAuth setup (optional, for Google Ads / GSC agents to do real work)
+Cron names follow `<project-slug> / <agent-slug> / <cron-slug>` so the tab can group them and the calendar can lay them out.
-The agents are useful in chat without OAuth, but to actually pull live data or push changes, register a Google Cloud OAuth app and set:
+## Connecting MCP servers (for live ad-platform data)
-```bash
-# In your shell or .env
-export GOOGLE_ADS_CLIENT_ID="..."
-export GOOGLE_ADS_CLIENT_SECRET="..."
-export GSC_CLIENT_ID="..."
-export GSC_CLIENT_SECRET="..."
-```
+The Connections page lists the MCP servers in our catalog (currently:
+NotFair Google Ads). Click **Connect** to start a one-click PKCE OAuth flow
+— no environment variables to set, no Google Cloud project of your own to
+register. The token is persisted into OpenClaw's `mcp` config under a
+project-namespaced key, with `codex.agents` rewritten to that project's
+agents so MCPs don't bleed across projects.
-Set the redirect URI in Google Cloud Console to `http://localhost:3000/api/oauth/google_ads/callback` (and similar for `gsc`). Then visit **Connections** in the UI and click **Connect**.
+Direct env-var OAuth (Google Ads / GSC) has scaffold API routes at
+`/api/oauth/[provider]/{start,callback}` for users who want to bring their
+own Google Cloud OAuth client. There's no Connections-page UI for that path
+in V1; it lands in V1.1 alongside the wider Search Console + GA4 surface.
-Tokens are AES-256-GCM encrypted with a master key stored in your OS keychain (via `keytar`) and persisted to your local SQLite.
+OAuth refresh tokens are AES-256-GCM encrypted with a master key stored in
+your OS keychain (via `keytar`) and persisted to your local SQLite.
## Data location
@@ -91,11 +97,11 @@ Tokens are AES-256-GCM encrypted with a master key stored in your OS keychain (v
- Agent workspaces: `~/.notfair-cmo/agents/<agent-name>/`
- OpenClaw config: `~/.openclaw/openclaw.json` (managed by OpenClaw, not us)
-## What v0.1 is and isn't
+## What V1 is and isn't
-**Is:** an agent runner + chat portal + cron management UI. Talk to project-scoped OpenClaw agents, schedule their recurring work, see attribution.
+**Is:** an agent runner + per-agent chat portal + cron management UI + MCP connection hub + activity audit log. Talk to project-scoped OpenClaw agents, schedule their recurring work, connect their tools, see attribution.
-**Isn't (yet):** a fully autonomous CMO. The approval inbox, autonomy guardrails, automatic cost tracking, and cross-agent signal sharing are scaffolded but not wired. They land in v0.2.
+**Isn't (yet):** a fully autonomous CMO. The approvals inbox, autonomy guardrails enforcement, per-LLM-call cost tracking, eval harness, and cross-agent signal sharing are scaffolded but not wired end-to-end. They land in V1.1.
See `ARCHITECTURE.md` for the design and `CONTRIBUTING.md` for development setup.