Client Website Platform

Context & problem

Why this exists, and the constraint window.

Brynn runs HOFMI ministry development + Transformate consultancy. There is an immediate batch of HOFMI ministry websites to (re)build, plus an external pipeline starting with a Witbank veterinarian. Today, building and maintaining client websites is bespoke work that consumes Brynn personally — every change request goes through him. This doesn't scale to the HOFMI cohort and burns ministry hours that should go elsewhere.

This spec defines a productized client-website platform that:

• Generates new client websites end-to-end through a guided pipeline (HOFMI trainee can run it)
• Provides clients with a self-serve maintenance portal where they request changes via in-context comments on their own site
• Routes change requests through Codesmith with a human review gate before clients see anything
• Bills changes against retainers or credits, with cost shown to the client before they approve

Two sub-products, two repos

Generation and maintenance are different problems with different lifecycles. They share infrastructure but ship as distinct codebases.

Orchestrating documentation (this spec, the trainee playbook, runbooks) lives in brynnclaw/website-build-playbook.

Three locked design principles

Load-bearing values — everything downstream must respect these.

Three locked architectural locks

Implementation invariants. Drift here = compounding pain later.

Sub-product A · site-studio v2

Extends the existing 13-stage pipeline. Biggest shift: Stage 7 retargets output from Astro to OD-native HTML+DESIGN.md projects that Open Design can open and edit directly.

Stage list with phasing

Trainee entry — Option D (hybrid)

• CLI for heavy stages — pnpm site-studio init <slug> walks the brief + runs stages 1–7. KIE image gen takes minutes; CLI is the right surface.
• site-keeper web UI for human-touch stages — brief refinement, brand kit input, OD composition handoff, deploy go-button. Same portal Brynn / Matt / Gian use to review change requests is also the operator UI for new-engagement kickoff. Avoids spawning a third UI.

Per-client repo structure

brynnclaw/site-<slug>/
├── README.md          — client-facing handoff doc
├── CLAUDE.md          — agent operating context for Codesmith
├── AGENTS.md          — change-request handling rules for Codesmith
├── DESIGN.md          — brand kit (OD-readable)
├── pages/
│   ├── index.html
│   └── ...
├── assets/            — images, fonts (OD generates / fetches)
├── partials/          — header.html, footer.html (shared, included)
└── deploy/
    └── cloudflare-pages.yaml

main branch = live. agent/<change-request-id> branches = previews. CF Pages auto-deploys both.

Sub-product B · site-keeper portal

Next.js 16 + Self-hosted Supabase. Single public surface (CF tunnel), everything else Tailscale-internal.

Topology · A → C migration path

Skipping topology B (always-on per-client) — pays for idle.

Hosts

Auth · self-hosted Supabase

GoTrue magic-link primary; OAuth optional. Per-tenant claim in JWT (org_id) used by Postgres RLS to enforce tenant isolation. One-app multi-tenant — clients = organizations in one site-keeper deployment, not subdomain-per-client.

User roles

• client — sees only their own org's projects, comments, change requests
• reviewer — Matt + Gian; sees all orgs' change requests in internal_review state
• operator — Brynn + Warden; full access including new-engagement kickoff
• admin — schema migrations, billing meter access, system config

Edit primitive — element-level via OD adoption

Client clicks any element on their site preview, leaves a comment. OD's edit-mode bridge handles element selection + position + selector + screenshot. We adopted OD's engine; we did not build it.

MVP routing rule: ALL changes route to agent + review. Self-serve direct-edit lane (text/image/link via manualEditPatch) reserved for Phase 2 once the system has earned trust.

Quality control on every edit: the site-edit-worker invokes the impeccable skill against the diff before transitioning to internal_review. New ban violations introduced by an edit must be self-fixed or flagged on escalation. Reviewer sees the impeccable report alongside the preview.

Change-request state machine

The full end-to-end flow including the 2-min scoping pass and blocked-on-topup gate that protect unit economics.

Off-happy-path states

• failed — Codesmith couldn't apply patch (selector ambiguous, source malformed). Falls back to manual queue.
• escalated_to_manual — internal review rejected Codesmith's output. Human handles → resumes at internal_review.
• cancelled — client cancelled (no charge), or Brynn cancelled (no charge).
• stale_archived — client_review hit 14 days no response.

Billing & pricing model

Two billing modes per client. Estimate shown before approval — the email itself is the cost gate.

Currency

• Per-client currency: ZAR for South African clients, USD for international
• Stored in clients.currency
• Display always in client's currency; internal accounting consolidated to USD

Estimator (the 2-minute scoping pass)

Produces estimated time (minutes), estimated cost (in client currency), and risk flags ("looks like a structural change," "needs new env var," etc.).

MVP estimator — heuristic table by patch kind

Phase 2: Sonnet pre-classifies the request based on comment text + element + project history.

Pricing tier ladder · Phase 3 wiring

Schema fields exist in MVP; logic wired in Phase 3:

Data model · Supabase Postgres + RLS

Implementer-facing. Skim unless you're writing the migration.

-- Tenancy
CREATE TABLE clients (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  slug text UNIQUE NOT NULL,
  name text NOT NULL,
  domain text,
  currency text NOT NULL CHECK (currency IN ('ZAR','USD')),
  billing_mode text NOT NULL CHECK (billing_mode IN ('retainer','credit')),
  retainer_hours_per_month numeric,
  retainer_used_minutes_this_period int DEFAULT 0,
  retainer_period_resets_at timestamptz,
  credit_balance_minor int DEFAULT 0,
  subscription_tier text DEFAULT 'starter',
  github_repo text NOT NULL,
  od_project_id text,
  created_at timestamptz DEFAULT now()
);

CREATE TABLE users (
  id uuid PRIMARY KEY,
  email text UNIQUE NOT NULL,
  client_id uuid REFERENCES clients(id),
  role text NOT NULL CHECK (role IN ('client','reviewer','operator','admin')),
  created_at timestamptz DEFAULT now()
);

CREATE TYPE change_request_status AS ENUM (
  'submitted','queued','scoping','scoped','blocked_on_topup','blocked_on_human_secret',
  'processing','internal_review','client_review',
  'approved','live','done_replaced',
  'cancelled','failed','escalated_to_manual','stale_archived'
);

CREATE TABLE change_requests (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  client_id uuid NOT NULL REFERENCES clients(id),
  page_path text NOT NULL,
  od_comment_id text,
  od_element_selector text,
  od_element_screenshot_url text,
  client_note text NOT NULL,
  status change_request_status NOT NULL DEFAULT 'submitted',
  estimated_minutes int,
  estimated_cost_minor int,
  actual_minutes int,
  actual_cost_minor int,
  billing_source text,
  estimate_shown_to_client_at timestamptz,
  estimate_approved_by_client_at timestamptz,
  reviewer_user_id uuid REFERENCES users(id),
  reviewer_decision text,
  reviewer_decision_at timestamptz,
  agent_branch text,
  preview_url text,
  pr_url text,
  parent_change_request_id uuid REFERENCES change_requests(id),
  created_at timestamptz DEFAULT now(),
  updated_at timestamptz DEFAULT now()
);
CREATE INDEX ON change_requests (client_id, status, created_at DESC);
CREATE INDEX ON change_requests (status, updated_at DESC);

CREATE TABLE billing_meter (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  client_id uuid NOT NULL REFERENCES clients(id),
  change_request_id uuid REFERENCES change_requests(id),
  minutes int NOT NULL,
  cost_minor int NOT NULL,
  currency text NOT NULL,
  source text NOT NULL,
  occurred_at timestamptz DEFAULT now()
);

CREATE TABLE audit_log (
  id bigserial PRIMARY KEY,
  actor_user_id uuid REFERENCES users(id),
  actor_role text,
  action text NOT NULL,
  target_table text,
  target_id uuid,
  payload jsonb,
  occurred_at timestamptz DEFAULT now()
);

RLS shape: clients see only their own rows via app.current_client_id JWT claim; reviewers see internal_review across clients; operators & admins see all. Production policies will be more granular.

Email cadence

Exactly 4 client-facing triggers + 2 conditional ones. Every email is a tax on attention.

NOT emailed: submitted, queued, scoping, processing, internal_review, rejected_by_internal, failed. The in-portal Realtime indicator handles those.

Open Design integration

Three integration points. OD is the editor, deploy mechanism, and (eventually) the per-client container.

1. OD instance(s) — MVP topology A: one container, multi-project, each client = an OD project keyed by clients.od_project_id. Topology C: ephemeral per-session containers spawned via Coolify. Project files mounted from per-client GitHub repo (clone on container start).
2. Comment storage sync — OD writes to SQLite via /api/comments. A 30-second polling sync (Node.js) reads new/changed comments → upserts to change_requests in Supabase. The 30s lag is invisible against the 24h SLA.
3. Source-patches application — Codesmith uses OD's applyManualEditPatch(source, patch) for trivial patches. For structural changes Codesmith does its own editing (branching off the per-client repo) and commits.

OD version pinning

Pin docker image to a specific SHA (docker.io/vanjayak/open-design@sha256:...), not :latest. Per FLEETSEC doctrine: update only after release-notes review + 1-2 week soak. Sentinel watches the OD release feed.

11.5 · Design quality references

Skills + repos the platform consumes (not platform code — inputs).

These references live in their upstream repos and are linked from per-client CLAUDE.md files so the site-edit-worker can pull principles into project context on every invocation — without retaining state itself.

Agent integration

The bridge runtime routes change_request work to a stateless ephemeral agent (site-edit-worker), distinct from the persistent Codesmith dev-work lane. See §4.4 for the lock.

12.1 · Site-edit-worker (the maintenance agent)

• Model: Sonnet 4.6 (claude-sonnet-4-6)
• Lifecycle: ephemeral, fire-and-forget per change_request. No persistent identity. No /home/<agent>/ workspace. No memory between invocations.
• Spawn trigger: Supabase Edge Function fires on change_requests.status transition to processing, POSTs to the bridge with task_type=site_edit. Bridge router dispatches a fresh worker.

Inputs (read-only)

• The change_request row (id, page_path, element selector, screenshot URL, client note, estimated minutes)
• The per-client GitHub repo (CLAUDE.md, AGENTS.md, source files in pages/, partials/, assets/)
• The element screenshot in Supabase Storage (signed URL)

Outputs

• Commits on agent/<change-request-id> branch in the per-client repo
• Pushed to GitHub; CF Pages auto-deploys preview
• Updated change_request row: agent_branch, preview_url, pr_url, actual_minutes, status → internal_review

Required workflow steps

1. Read CLAUDE.md + AGENTS.md from the client's repo (project context — voice, brand, gotchas)
2. Check out main, branch agent/<change-request-id>
3. Apply the requested edit (using OD's applyManualEditPatch for trivial patches, or direct file edits for structural changes)
4. Run impeccable audit on the diff — auto-fix catchable violations; flag the rest with impeccable.violations on the change_request row
5. Commit, push, open PR
6. Update change_request row, transition status to internal_review

12.2 · Codesmith (the development agent — separate lane)

Codesmith is not used for client-website-platform change_request work. Codesmith retains its existing role: development work on Brynn's platforms (arkon, arkon-os, arkonhelm, etc.) where multi-session continuity, named identity, and persistent workspace are valuable. Per project_codesmith_persistent_workspace.md (2026-05-06): Codesmith has /home/codesmith/, MEMORY.md, synced identity.

Why not unify: cross-tenant leakage risk if one persistent agent handles all clients; Codesmith's workspace would balloon with high-volume routine edits; Principle 3.3 (agent stateless between requests) is cleanly enforced when the maintenance agent literally cannot retain state.

12.3 · Bridge router

Minor extension to dispatch by task_type:

// pseudocode
async function dispatch(taskType: string, payload: any) {
  switch (taskType) {
    case 'codesmith_session':
      return spawnCodesmith(payload); // existing path
    case 'site_edit':
      return spawnSiteEditWorker(payload); // NEW — ephemeral, stateless
    default:
      throw new Error(`unknown task_type: ${taskType}`);
  }
}

spawnSiteEditWorker mints a fresh Claude Agent SDK worker, no /home/ directory, no MEMORY.md, no identity sync. The system prompt is built from §12.1 inputs only; nothing carried over from prior invocations.

12.4 · Self-wake + monitoring

• Bridge-Warden uptime is now externally SLA-bearing — clients depend on it
• Existing self-wake / governor-watch infrastructure tightens alert thresholds during MVP rollout
• Per Brynn's directive 2026-05-09: bridge-Warden being down for 24h+ is an incident, not a fail-over scenario. Matt + Gian as second-line, not substitute
• Site-edit-worker failures (timeout, model error, patch error) bubble up to bridge-level error handling → change_request status → failed → manual queue

MVP scope · cut to ship in days

What's in, what's deferred. Push back here if anything needs to flip.

In MVP 12 items

1. site-studio v2 retargeted to OD-native output (Stage 7 swap)
2. Per-client GitHub repo provisioning (manual create-repo script)
3. site-keeper Next.js shell + Supabase Auth + reverse-proxy to OD (topology A)
4. Supabase data model with RLS policies
5. SQLite → Supabase comment sync (30s polling)
6. Edge Function trigger to Codesmith on scoped → processing
7. Heuristic estimator (patch-kind table)
8. Internal review queue UI in site-keeper
9. Email pipeline (Resend or Supabase SMTP) with the 4 triggers
10. Preview deploy via OD's CF Pages integration
11. Approval → auto-merge + deploy
12. Matt + Gian provisioned as reviewer + ~30 min training

Phase 2 — next 2-4 weeks 7 items

• Topology C migration (cold-spin per-client containers)
• Niche research module automation (Stage 0.5)
• Brand-kit auto-generation (Stage 1)
• Playwright FB scraping (Stage 2)
• Self-serve direct-edit lane
• AI sub-review for low-risk changes
• Sonnet-based estimator

Phase 3 — post-MVP soak 5 items

• Pricing tier wiring (rush, enterprise)
• AOE module (Stage 6.5)
• Stripe / payment integration for credit top-ups
• Client analytics dashboard
• Scope-boundary metering UI (live cost meter)

Out of scope

• WordPress migration tooling (bespoke track only)
• Email sending FROM client sites (clients use their own ESP)
• E-commerce / payment processing on client sites (bespoke track)
• Mobile app — site-keeper is web-only, mobile-responsive
• Self-hosted CF Pages alternative — locked to CF Pages for MVP
• Real-time co-editing between client and Brynn — async only

Open implementation questions

Defer to writing-plans.

1. Estimator heuristic table — exact minute values per patch kind (validate against actuals after first 10 change_requests)
2. Cold-start orchestration — Coolify vs plain compose profiles vs k8s for Topology C
3. Custom-domain CF Pages binding — automation script vs manual at MVP
4. Codesmith branch cleanup — auto-delete merged? archive after N days?
5. Stale change_requests beyond 30 days — purge / archive / retain?
6. Cross-client analytics for Brynn — top-down view of MRR, retention, volume
7. HOFMI sub-domain pattern — eu.hofmi.org / na.hofmi.org or per-domain?
8. Auth.js fallback if Supabase Auth has issues — abstraction layer or accept lock-in?

Risks & mitigations

Helm work-item plan

After spec approval, file the umbrella WI under transformate tenant and decompose into 9 implementation sub-WIs in writing-plans phase.

Sub-WIs to spawn

1. site-studio v2 OD-native retarget (Stage 7)
2. Self-hosted Supabase deployment + schema migration
3. site-keeper Next.js + Auth + reverse-proxy
4. SQLite → Supabase comment sync worker
5. Agent integration — bridge router (task_type dispatch) + ephemeral site-edit-worker (Sonnet 4.6, stateless) + impeccable invocation in workflow
6. Internal review queue UI
7. Email pipeline + 4 triggers
8. CF Pages provisioning per client
9. Operational runbook + Matt/Gian training

Approval

• ☐ Brynn reads this spec end-to-end
• ☐ Brynn flags any sections that don't match intent
• ☐ Once approved → Helm WI filed → handoff to writing-plans skill for implementation plan