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.mdindex 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 agentssrc/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.tsxapi/- 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 projectserver/- 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 MCPactions/- 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 agentsopenclaw/- 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 + cronsdb/- 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.tssecrets/- 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 / decryptcomponents/- app-sidebar.tsx # Sidebar with project switcher + nav + cost meter+ app-sidebar.tsx # Sidebar with project switcher + nav + status pillproject-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 composerschedule-cron-dialog.tsxcron-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 MCPapproval-card.tsx+ skills-list.tsxonboarding-flow.tsx- ui/ # shadcn primitives+ client-mount-gate.tsx # Defer client-only children until after mount+ ui/ # shadcn primitives++ hooks/+ use-mobile.tslib/- 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 definitionstypes/- 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.mdindex 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.gitcd notfair-cmopnpm 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 shapeSee `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 feature1. 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`.## Licensediff --git a/README.md b/README.mdindex 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 --versionnotfair-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.