# Client Acquisition System — Single Source of Truth
*Generated on 2026-09-07 · Version v1.0.0 · Author: Claude Code (cc)*

## Adaptation note

This SSOT follows the structural spirit of `/Users/paul/ref/agent-SSOT-docs/SSOT-spec.md` (metadata block, required/recommended sections, self-contained, extensible), but that spec is written for a software product — API contracts, database schemas, CI pipelines. This system is a consulting-delivery process with some software components embedded in it, not a software product with a process bolted on. The tech-only sections (API Contract, Data Model as SQL schema, Testing Strategy as a coverage table) are replaced here with the sections that actually remove ambiguity for this system: a step-by-step process, a timeline, and a responsibility chart. Where real software exists (the System Guide App, the Presentation Deck Builder, the fullrefit-site implementation), it's documented under Architecture and Deployment like any other component.

**This document is structural and process truth. It does not describe today's status, blockers, or in-flight client work — that lives in the dual-published State-of-the-Project Brief and is expected to change weekly. If this SSOT and the current SOTP disagree about what a component *is supposed to do*, this SSOT wins. If they disagree about what's *currently true*, the SOTP wins.** Current SOTP: `sotp-client-acquisition-system-cc_090726.md`.

---

## 📋 Metadata

- **Project name:** Client Acquisition System
- **SSOT version:** v1.0.0
- **Created:** 2026-09-07
- **Last updated:** 2026-09-07
- **Status:** ☑️ Active
- **Stakeholders:** Paul Chambers (owner/operator), full/REFIT
- **Canonical project root:** `/Users/paul/projects-5/client-acquisition-system/`
- **Live production surfaces:** `https://client-acquisition-system-guide.vercel.app` (System Guide App); `/Users/paul/dev-4/1-fullREFIT/fullrefit-site/` deployed to `fullrefit.com` (Preflight + Proposal Pages implementation)
- **Compliance tags:** none formal; the system enforces its own client-data and payment-verification rules (see Security & Trust Rules below)

---

## 🎯 Purpose & Scope

The Client Acquisition System is the reusable spec-and-skill layer that runs a client from first contact through delivered, paid engagement — six numbered components plus one cross-cutting operator dashboard. It does not itself generate net-new leads (that is a separate, unrelated system) and it does not hold client-specific data (every client's actual proposals, decks, transcripts, and evidence live in that client's own Dropbox folder; this project holds only the reusable pattern, referenced into the client folder by symlink). This document describes what the system *is* and how it is *supposed to* run. Current in-flight client status is out of scope here — see the SOTP.

---

## 🗺️ System Map

```mermaid
flowchart LR
    subgraph Pre["Before payment"]
        A["1. Preflight Questionnaire"] --> B["client-intake-forge (skill)"]
        B --> C["2. Proposal Pages"]
    end
    subgraph Post["After payment — commercial language banned"]
        D["3. Post-Call Analysis"] --> E["4. Client HQ"]
        E --> F["5. Presentation Deck Builder\n(client-presentation-deck-builder skill)"]
    end
    C -->|payment or booking verified by provider| D
    E -.next call.-> D
    G["6. System Guide App"] -.tracks status of.-> A
    G -.tracks status of.-> C
    G -.tracks status of.-> D
    G -.tracks status of.-> E
    G -.tracks status of.-> F
```

**The one rule that governs everything else:** before payment, Preflight and Proposal Pages may discuss scope, terms, pricing, PayPal, and booking. After payment is verified, Post-Call Analysis and every client-facing deck must focus only on solving the client's problem, recording decisions, delivering the work, and proving the result — commercial language is banned client-side past that line. This line is stated identically in `README.md`, `docs/README.md`, and `docs/client-system-master-spec-hermes_090426.md`.

---

## 🧭 Step-by-Step Process

| # | Step | Owner (component / skill) | Input | Output | Handoff trigger |
|---|---|---|---|---|---|
| 1 | Author and seed a Preflight questionnaire for the client/vertical | Paul, using **1-preflight-questionnaire** template | Nothing (manual authoring) | A questionnaire schema | Schema ready |
| 2 | Mint and personally walk a demo invite before any live send | Paul | Questionnaire schema | Verified demo run | Demo passes |
| 3 | Send the live invite; client submits responses | 1-preflight-questionnaire (implementation: `fullrefit-site`) | Live invite link | Stored response (Supabase only, never a file) | Response submitted |
| 4 | Assemble the response into a briefing; deliver to 4 channels (respondent email, operator email, Slack webhook, Slack agent bot) | 1-preflight-questionnaire's briefing pipeline (no LLM in this path, by design) | Stored response | Delivered briefing | Briefing delivered |
| 5 | Build the evidence brief and source manifest from Preflight + any discovery artifacts | **client-intake-forge** (skill; no dedicated numbered folder — sits between components 1 and 2) | Briefing + discovery artifacts | Evidence brief, root-cause hypotheses, disconfirming questions | Evidence brief complete |
| 6 | Select one bounded first engagement; keep broader implementation conditional | client-intake-forge → **2-proposal-pages** | Evidence brief | Scoped first-engagement recommendation | Recommendation accepted |
| 7 | Build/update proposal, terms, PayPal, and calendar surfaces; freeze an acceptance version bound to exact proposal+terms versions | **proposal-system-operations** (skill, physically at `2-proposal-pages/proposal-system-operations-skill/`) | Scoped recommendation | Live proposal route + frozen accepted version | Client accepts (pays or books, per pattern below) |
| 8 | Verify the deployed route, event receipts, provider payment state, and booking result directly from the provider — never from a redirect, URL parameter, or UI text | proposal-system-operations | Client action (pay/book) | Provider-verified truth | Verification passes |
| 9 | Run the paid client's working call from the Client HQ workspace | **4-client-HQ** (operating surface) | Verified engagement | Live call | Call completes |
| 10 | Analyze the call against Preflight evidence, accepted scope, and prior commitments — hard-gated on `engagement_stage = paid_delivery`, verified from system state, never inferred from a name list | **client-post-call-analysis** (skill) / **3-post-call-analysis** | Call transcript + prior state | Delivery decisions, claim ledger, next-session commitments | Analysis delivered |
| 11 | Update Client HQ: completed work, decisions, owner commitments, risks, next checkpoint | 4-client-HQ | Post-call analysis output | Updated client workspace | HQ updated |
| 12 | Build a client-facing deck only when it helps the next delivery interaction, using **client-presentation-deck-builder** only — never the generic deck skill, never commercial content | **5-presentation-deck-builder** | Client HQ state | Client-safe deck | Deck delivered (if built) |
| 13 | Store every engagement artifact in the client's own Dropbox folder — never a second editable copy in the shared system project | Cross-cutting rule, enforced by the `examples/` symlink pattern in every component | Any artifact | Symlinked reference in the system project | Always |
| 14 | Track every step above — done/not-done, by whom, with what evidence link — and forward status/decision events to Hermes/Slack | **6-system-guide-app** (sits outside the linear flow; it is the operator dashboard, not a delivery step) | Status of steps 1-13 | Tracked checklist + Hermes/Slack event | Continuous |

**Two lifecycle patterns exist for step 7-8 and must never be combined on the same client:**
- **Pay-first pattern (e.g. Eleanor):** review → pay via PayPal → verify provider-backed payment → reveal calendar route → confirm sessions.
- **Book-first pattern (e.g. Barry):** review → book the working session → complete session + follow-up → request/verify payment after the follow-up.

---

## ⏱️ Timeline

### A. Per-engagement timeline (how a client moves through the system)

There is no fixed calendar duration mandated anywhere in the source specs — each stage is gated on verified completion of the previous one, not on a clock. The realistic shape, reconstructed from the process above and from how Greg, Barry, and Eleanor have each actually moved through it:

```
Day 0            Demo walked, live invite sent
Day 0-N          Client submits Preflight response (N = however long the client takes)
+ a few days     Evidence brief built, first engagement scoped, proposal built
+ hours-days     Proposal reviewed → paid or booked (provider-verified before proceeding)
+ scheduling gap Working call happens (Client HQ)
Same day         Post-call analysis run, engagement_stage gate checked
+ hours-days     Client HQ updated; deck built only if it helps the next interaction
Ongoing          Next call / next scoped session, repeat from step 9
```

The only two hard timing rules found anywhere in the source material: (1) a demo invite must be personally walked before any live send — no skipping ahead; (2) `engagement_stage` must be verified from system state at the moment of call analysis, not assumed from who was on the call.

### B. System build timeline (when each component came online)

Reconstructed from file dates found across the project (component specs, release docs, audits):

| Date | Event |
|---|---|
| 2026-08-15 | Presentation Deck Builder archaeology: generic builder audited against a public reference deck |
| 2026-08-22 | Proposal Pages historical planning artifacts authored (now superseded, kept in `docs/history/`) |
| 2026-08-26 – 08-31 | Preflight Questionnaire built and specified; first (and so far only) live client, Greg Johnson, onboarded on the household-systems-v1 schema |
| 2026-09-04 | Root project normalized to its current canonical structure; 3-post-call-analysis and the paid-client deck/analysis skills created; Zoom Call Analyzer production incident (Eleanor misclassified) discovered same week |
| 2026-09-05 | Client artifact ownership audit: 25 client-specific project copies replaced with symlinks to canonical Dropbox client folders; Zoom Call Analyzer fix released and fixture-verified |
| 2026-09-05 – 09-06 | System Guide App (component 6) built and released to production, `client-acquisition-system-guide.vercel.app` |
| 2026-09-06 | Full-system SOTP produced (Hermes) covering the Eleanor/Barry release program |
| 2026-09-07 | Project root renamed from a space-containing path to the current hyphenated path (unrelated filesystem fix); Barry/Eleanor decision-brief and handoff-hub formatting fixed; this SSOT and its companion SOTP produced |

This section is a fixed historical record — update it only when a genuinely new component is added, not on every routine fix. Ongoing status belongs in the SOTP, not here.

---

## 👥 Responsibility Chart (RACI)

R = Responsible (does the work) · A = Accountable (owns the outcome) · C = Consulted · I = Informed

| Activity | Paul | client-intake-forge | proposal-system-operations | client-post-call-analysis | client-presentation-deck-builder | agents-md-forge | System Guide App | Hermes / Slack | External providers (PayPal, Cal.com, Zoom) |
|---|---|---|---|---|---|---|---|---|---|
| Author/seed a Preflight questionnaire | R/A | | | | | | | | |
| Walk the demo invite before live send | R/A | | | | | | | | |
| Assemble briefing, deliver to 4 channels | I | | | | | | | I | |
| Build evidence brief / root-cause hypotheses | A | R | | | | | | | |
| Select bounded first engagement | A | C | R | | | | | | |
| Build proposal/terms/PayPal/calendar; freeze accepted version | A | | R | | | | | | C |
| Verify payment/booking is provider-backed, not a redirect | A | | R | | | | | | R (source of truth) |
| Approve production deployment of any client-facing route | R/A | | | | | | | | |
| Run the paid working call | R/A | | | | | | | | |
| Gate call analysis on verified `engagement_stage` | A | | | R | | | | | |
| Analyze paid call, produce delivery decisions | A | | | R | | | | | |
| Update Client HQ workspace | A | | | C | R | | | | |
| Build a client-facing deck (paid client) | A | | | | R | | | | |
| Build a non-client / generic deck | A | | | | I (not used — generic skill instead) | | | | |
| Edit a protected client `AGENTS.md` / instructions file | A | | | | | R | | | |
| Track checklist status across all 6 components | I | I | I | I | I | | R/A | | |
| Deliver verified status/decision events | I | | | | | | R | R/A | |
| Rotate/manage credentials (PayPal, Zoom, 1Password, Keychain) | R/A | | | | | | | | C |
| Restart/repair the Hermes gateway | R/A | | | | | | | C | |
| Hold live payment/booking/recording state as ground truth | I | | | | | | | | R/A |

**How to read a gap:** every row has exactly one Accountable owner, always Paul or the one skill built for that job. No row has two skills marked Responsible — that would mean the same failure mode the system's own specs repeatedly warn against (combining sales-stage and paid-delivery analysis, or letting a generic skill touch client-commercial content).

---

## 🏗️ Component Reference

| # | Component | Spec location (this project) | Live implementation | Canonical skill |
|---|---|---|---|---|
| 1 | Preflight Questionnaire | `1-preflight-questionnaire/` (`AGENTS.md`, `docs/SPEC-preflight-questionnaire-system-cc_082926.md`) | `/Users/paul/dev-4/1-fullREFIT/fullrefit-site/`, reached only via `reference/` symlinks | none (manual authoring); downstream analysis is `client-intake-forge` |
| 2 | Proposal Pages | `2-proposal-pages/` (`docs/proposal-pages-system-spec-hermes_090426.md`) | Same `fullrefit-site` deployment | `proposal-system-operations` |
| 3 | Post-Call Analysis | `3-post-call-analysis/` (`docs/post-call-analysis-system-spec-hermes_090426.md`) | n8n workflow (Zoom Call Analyzer, workflow ID `VEEt4McYYTsg8ddm`) | `client-post-call-analysis` |
| 4 | Client HQ | `4-client-HQ/` (`docs/client-hq-system-spec-hermes_090426.md`) | Per-client, at `/Users/paul/Library/CloudStorage/Dropbox/1-full-REFIT-db/clients/{client}/client-hq/` | none named; operating surface, not a skill |
| 5 | Presentation Deck Builder | `5-presentation-deck-builder/` | Two skills, kept deliberately separate | `presentation-deck-builder` (generic, non-client) and `client-presentation-deck-builder` (paid-client only) |
| 6 | System Guide App | `6-system-guide-app/` (Next.js 16, App Router, Turbopack) | `https://client-acquisition-system-guide.vercel.app` | none; it is the product, not a skill |

Client-specific proposals, decks, transcripts, analyses, and evidence are **never** stored a second time in this project — every `examples/` folder here is a symlink into the client's own Dropbox folder, kept only for pattern demonstration.

---

## 📊 Evidence & State Model

Every claim anywhere in this system is labeled with one of these states — this is the closest thing the system has to a formal data model, and it is what makes the SOTP's claims auditable:

| Label | Meaning |
|---|---|
| `Verified` / `Verified live` | Checked directly against the live external or production system |
| `Verified locally` | Checked against current local files, tests, or runtime |
| `Documented` | Asserted by a source but not independently checked in the current pass |
| `Stale pending check` | Previously verified, but freshness matters and it was not rechecked |
| `Inferred` | Supported by named evidence but not directly observed |
| `Contested` / conflict | Two equal-authority sources disagree — must be reported, never silently resolved |
| `Unknown` | Insufficient evidence |

The single most important controlled field in the whole system is **`engagement_stage`**, with values `preflight_received | proposal_sent | proposal_accepted | paid_delivery | completed`. It is the sole authority on whether a call gets analyzed as sales or as paid delivery. Participant name lists are supporting metadata only — never the routing decision.

---

## 🔐 Security & Trust Rules

- Never accept a redirect, URL parameter, or UI text as proof of payment or booking — always verify against the provider (PayPal, Cal.com, Zoom) directly.
- Never edit a protected client `AGENTS.md` or `CLAUDE-PROJECT-INSTRUCTIONS.md` by direct overwrite — route through `agents-md-forge`, even when the file is known-stale.
- A stable, unguessable URL (noindex/no-store) is not authentication — track it as an explicit gap, not a control, until real auth is added.
- Never store workflow credentials inside an n8n code node or any other workflow definition — a live incident (2026-09-04/05) found exactly this and required Zoom credential rotation.
- Never store a second live copy of client-owned material inside this shared system project — symlink to the client's Dropbox folder instead.
- Every outbound Hermes/Slack event requires an id, a dedupe key, a subject-artifact hash, and confirmation the receiving side actually processed it (`body.ok === true`) — an HTTP 200 from the webhook call is not proof of delivery.

---

## 🚀 Deployment & Operations

- **Preflight + Proposal Pages:** implemented in and deployed from `/Users/paul/dev-4/1-fullREFIT/fullrefit-site/` → `fullrefit.com`. This project holds the spec and the reusable skill only.
- **Post-Call Analysis:** implemented as an n8n workflow on Paul's n8n instance; the prompt and pipeline contract live in this project.
- **Client HQ:** each client gets a real, live workspace under their own Dropbox client folder; this project holds only the reusable spec and symlinked pattern examples.
- **Presentation Deck Builder:** decks are built and deployed per-client to their own Vercel projects (e.g. `barry-l-deck-fullrefit.vercel.app`, `eleanor-l-deck-fullrefit.vercel.app`); the generic and paid-client skills that produce them live in this project.
- **System Guide App:** a standalone Next.js app, deployed to Vercel from `6-system-guide-app/`, using Upstash Redis for durable state and an HMAC-signed session cookie for auth. Its access key belongs in Paul's central 1Password vault (migration pending as of this writing — see SOTP).

---

## 📦 Release & Versioning

- **Versioning policy:** bump the SSOT's version (semantic: MAJOR.MINOR.PATCH) only when a component is added, removed, or its ownership/process structure genuinely changes. Routine bug fixes, one-off client repairs, and status changes do not bump this document — they belong in the SOTP.
- **Changelog:**
  - v1.0.0 (2026-09-07) — initial SSOT, covering all 6 components as they exist after the 2026-09-04/05 canonical-root normalization and client-artifact-ownership correction.

---

## 🗂️ Glossary

- **Engagement stage:** the controlled field (`preflight_received | proposal_sent | proposal_accepted | paid_delivery | completed`) that gates how a call gets analyzed. See Evidence & State Model.
- **Pay-first / book-first pattern:** the two named, non-combinable proposal lifecycles. See Step-by-Step Process.
- **Client HQ:** a private, per-client operating workspace — not a client-facing portal by default.
- **Symlink pattern:** the rule that any client-specific artifact appearing inside this shared system project is a symlink to the client's own Dropbox folder, never an independent copy.

## 📚 Appendix — Source Documents

- System master spec: `docs/client-system-master-spec-hermes_090426.md`
- Per-component specs: see Component Reference table above for exact paths
- Current system state: `chat-recap_project-handoff/sotp-client-acquisition-system-cc_090726.md` (and its canonical Dropbox twin)
- This document's research basis: a full file-by-file inventory of the project performed 2026-09-07 (not separately filed; incorporated directly into this SSOT and the companion SOTP)