EPIC: onboarding a new client — what the ten-step process needs that does not exist

[ssdavidai]

Research epic, written 2026-08-13 from Sir's onboarding design. Nothing here
is committed work. It records what the ten-step process needs versus what the
code does today, so the gaps are visible before anyone starts building.

The promise

Point A — a solo consultant with 4–15 clients whose day starts with "what
did I promise to whom?" Agreements live in their head. Prep happens at 9pm.
The AI tools they bought made it worse, because the AI forgets between sessions
and they rebuild context for the tool as well as for themselves.

Point B — same business, memory problem gone. Briefed before every call.
Every promise, decision and open loop tracked until it closes. 15–20 hours a
month returned, shown on a signed monthly report.

---

What already exists, and fits well

Steps 4–6 are largely built. The onboarding ritual
(/awaken → /reading-the-room → /verify → /soul → /composing → /preparing → /first-brief → /desk) already pulls ~100 days of mail, extracts facts chunked,
discovers instinct patterns, writes USER.md / SOUL.md / RULES.md,
materialises a matter pack and an errand pack, seeds day-one Desk cards and
composes a first brief. That is substantially "Alfred shows what it learned
about you" and "build your Matters".

Step 9 is a precise fit, not a coincidence. "Day 60 — discretion on" is the
tier ladder: Asking → Confirming → Acting, where reaching Acting requires
the principal's explicit approval (#452), enforced at two independent points
that read the shared reader in matching/tiers.py and fail closed. Day 60 is
literally the principal working the Approve/Decline queue on /instincts. The
ladder was built for this shape after the 2026-08-06 incident.

Step 6's training loop is real and verified. Desk click → decision →
observation → nightly reflection → tier change. Confirmed end to end.

Point A's core complaint has its primitive. "What did I promise to whom" is
the commitment canonical type (#469–#471), with an 11-state lifecycle because
the coarse four-value status cannot express delivered_awaiting_acceptance.

---

Gap 1 — there is no way in

Step 1 (application at alfred.black) does not exist. Wasp auth only lets
someone sign into an Alfred that already exists for them. There is no
application, no queue, no provisioning trigger.

Step 3 (deployment) is a project, not a step. Provisioning is manual.

Gap 2 — day 1 requires SSH

"Connect your ChatGPT or Claude account" is, today, exactly this — it is what
HermesAuthBanner.tsx:66 tells the operator to run:

docker exec -it alfred-black-hermes-1 hermes auth login --provider openai-codex
docker compose restart hermes

A paying consultant cannot be handed a terminal on day 1. This is the real
content of #300 — not "one OAuth ceremony or two" but "can it happen in a
browser at all". A device flow is the natural shape (the dashboard shows a code
and a link, Hermes polls), mirroring the existing Tailscale card.

Note the direction: this is Alfred authenticating to the principal's ChatGPT
subscription, the opposite of the app OAuth in #546. It is also a commercial
advantage worth keeping — no per-seat model cost, no API keys in custody — but
it is unavoidable, because everything the principal sees is produced by Hermes.

Workspace choice is two of three. Slack works. The Claude connector works.
ChatGPT is #546, parked, and blocked on the one-VM-one-URL problem.

Gap 3 — the number on the signed report cannot be computed

This is the one that matters.

Point B promises 15–20 hours a month returned, on a signed monthly report.
Step 2 says "we count the hours leaking". Step 7 is "Alfred presents how it
will save you 15+ hours".

A grep across the entire repository for saved-time instrumentation returns
exactly one hit:

packages/learn/src/activities/onboarding.py:676
    "estimated_time_saved": "e.g. 30 min/week"

That is a string inside a prompt template — an LLM's guess, not a measurement.

The hours machinery that does exist (#468, alfred-hours-reconstruction)
reconstructs billable client hours from cross-source evidence for
invoicing. That is the opposite direction: it answers "how long did I work on
X", not "how much did Alfred give back".

So the central commercial claim has no instrumentation behind it. And a delta
needs a baseline, which step 2 assumes was captured on the sales call and which
nothing stores.

Why this is hard, not merely unbuilt

Attributing saved time is easy to fake and hard to defend. "Alfred handled 40
Desk cards, at 3 minutes each, therefore 2 hours" is a number that survives
exactly one sceptical question from the person signing it.

Design constraints worth committing to before any code:

• Measure at the moment of action, not retrospectively. A monthly
  reconstruction is a story; a per-action record with provenance is evidence.
• The principal signs, Alfred proposes. P2: ship evidence-based hours reconstruction as a per-matter opt-in — propose, never auto-accept #468 already establishes this
  pattern — an auditable per-period proposal that is never accepted
  automatically at any confidence. The saved-hours report should reuse it.
• A defensible small number beats an impressive one. This report is shown
  to someone deciding whether to keep paying. One inflated month costs more
  trust than a year of conservative ones earns.
• No baseline, no claim. If step 2's measurement was not captured, the day
  30 report should say so rather than compare against an assumption.

Gap 4 — step 7 has no surface

Nothing presents "here is the plan". Day 30 currently has no artifact.

---

What is genuinely fine

Steps 4, 5, 6, 9 and 10 rest on machinery that exists and works. The weekly
check-ins in steps 6 and 8 are human process and need no code. Step 10 is the
Desk, which is the daily surface already.

Sequencing

#	Work	Why this order
1	Web-based Codex auth (#300)	Nothing in day 1 is repeatable without it, and it is the smallest of these
2	Answer: do OpenAI's terms permit a daemon on a personal ChatGPT subscription?	If no, the model changes; cheaper to know before a funnel exists
3	Saved-hours instrumentation + baseline capture	The commercial promise; also the longest lead time because the design question is real
4	Day-30 plan surface	Consumes (3)
5	Signup + provisioning	Largest, and only needed when hand-holding each deployment stops scaling

Items 1 and 2 are independent and worth doing regardless.

The honest summary

Steps 4, 5, 6, 9 and 10 mostly work today. Steps 1, 2, 3 and 7 do not exist.

The binding constraint is not the onboarding ritual — that is the part that is
built. It is that the thing being sold is measured nowhere, and that day 1
currently requires a terminal.

[github-actions]

This issue is missing prioritization dimensions, so it will not
appear correctly in Now/Next/Later portfolio views.

#562 EPIC: onboarding a new client — what the ten-step process needs th
    missing:     kind, impact, effort, priority, horizon, customer, theme, area

0/1 open issues fully classified.

Rubric: docs/ISSUE-TAXONOMY.md

[ssdavidai]

Implementation spec

Scope

Turn the onboarding research epic into independently shippable slices without pretending the already-built ritual needs replacement. The work is ordered: browser-based model auth, terms/product decision, saved-time baseline and evidence, day-30 plan surface, then signup/provisioning. Existing /awaken through /desk, commitment lifecycle, tier ladder, and Desk learning loop remain integration points.

LANES

Lane I — browser-based Codex authentication (#300 dependency)

• Specify a device-flow contract: dashboard displays a short code and verification URL; Hermes polls from the tenant until success, expiry, cancellation, or provider error.
• Store only the minimum pending state and provider/account binding; never expose the subscription credential to the browser or persist it in vault records.
• Reuse the existing device-flow/Tailscale-style surface and make restart/poll retries idempotent.

Lane II — onboarding state and provisioning boundary

• Define a tenant onboarding state machine covering application received, review/acceptance, provisioning, auth pending, workspace connected, first brief ready, and active.
• Keep provisioning behind an explicit server-side command/workflow boundary; no browser request may directly mutate host/container state.
• Record durable status and failure reason so a resumed onboarding does not duplicate a tenant or deployment.

Lane III — saved-time evidence and baseline

• Capture a baseline before claiming savings: agreed period, work categories, minutes/hours, measurement method, and principal confirmation.
• Add the per-action evidence ledger and nightly recap specified by EPIC: the NAR ledger — compute Net Attention Returned from traces, not estimates #563; use provenance and conservative explicit-only headline arithmetic.
• Represent missing baseline as “no claim,” not zero savings or an assumed rate.

Lane IV — day-30 plan/report surface

• Add a principal-facing plan artifact that consumes the baseline and evidence proposal, states scope/coverage, shows assumptions, and remains unsigned until the principal confirms it.
• Link evidence back to Desk decisions/commitments/session traces; do not duplicate the source of truth.

Lane V — signup/provisioning rollout

• Only after the preceding contracts are stable, define the application intake, approval/eligibility decision, provisioning job, and notification boundaries.
• Treat OpenAI terms/subscription eligibility as a product/legal gate recorded as a decision, not hidden inside implementation.

CONTRACTS

1. Auth contract: device code + verification URL are ephemeral, single-use/expiry-bound, poll-safe, and never contain a reusable secret.
2. Tenant contract: one accepted application maps to one tenant/provisioning run; retries resume or return the existing run rather than duplicate infrastructure.
3. Onboarding contract: every state transition has actor, timestamp, reason, and recoverable failure state; auth and provisioning are separate states.
4. Evidence contract: no baseline means no savings claim; every report line is labelled measured, estimated, inferred, or unavailable and links to evidence.
5. Surface contract: day-30 plan and monthly report are principal-facing vault/UI artifacts; Alfred proposes and the principal signs.
6. Existing-system contract: onboarding integrates with the current ritual, commitments, tier ladder, Desk, and first brief instead of reimplementing them.
7. Terms gate: implementation must not assume a personal ChatGPT subscription may be used by a daemon; record the answer and alternative architecture before enabling a funnel.

Acceptance criteria

• A new user can complete the supported model-auth ceremony in a browser without SSH, with visible pending/success/expired/error states.
• Reconnects, refreshes, worker restarts, and duplicate callbacks do not create duplicate auth records, tenants, or deployments.
• A baseline is captured and confirmed before any saved-hours headline; absent baseline yields an explicit no-claim report.
• Day-30 plan output is generated from the baseline/evidence contracts, is auditable, and requires principal confirmation.
• Existing onboarding steps 4–6, 9, and 10 continue to pass their current integration tests.
• Provisioning failures are resumable and observable, with no leaked credentials and no partial “active” tenant.
• The product/legal decision about personal-subscription daemon use is an explicit prerequisite to launch.

Smoke plan

1. Run the existing onboarding pipeline/first-brief integration smoke with a fixture tenant and assert current ritual outputs remain intact.
2. Exercise device auth in a browser-equivalent test: start, poll pending, succeed, expire, cancel, retry after restart, and duplicate callback.
3. Run a first-day baseline capture and verify the stored confirmation plus a no-claim report before evidence exists.
4. Feed synthetic explicit Desk evidence and generate a day-30 plan; verify provenance and sign-off gating.
5. Fail provisioning midway, resume it, and assert one tenant/deployment with a visible recoverable state.

[ssdavidai]

Foreman specification — Phase 0 readiness contract only

This research epic explicitly says nothing is committed work. Do not build signup, provisioning, or the ten-step funnel monolithically. This gate covers only a checked-in readiness/dependency contract that makes later child work independently approvable.

LANES

• Lane IV — onboarding readiness contract: codify the ten steps, existing implementation evidence, missing capabilities, owners, dependency order, and verifiable readiness gates.
• Lane I/III — narrow probes: add non-mutating checks that report whether browser Codex auth, workspace connection, NAR baseline/statement prerequisites, and provisioning hooks are available; no provisioning action.

CONTRACTS

• Existing onboarding steps 4–6 and 9–10 remain untouched except for evidence links/tests.
• Missing capabilities are represented as explicit blocked gates linked to their dedicated issues (not reimplemented inside EPIC: onboarding a new client — what the ten-step process needs that does not exist #562).
• The readiness probe is read-only, contains no credentials, and never provisions, authenticates, or changes tier state.
• Sequence remains: browser Codex auth/terms decision → NAR instrumentation/baseline → day-30 plan → signup/provisioning.
• Each future implementation phase requires its own GitHub issue/spec/build approval.

ACCEPTANCE CRITERIA

1. A versioned onboarding-readiness document/schema maps all ten steps to ready|blocked|manual, evidence, dependency, and owning issue.
2. Automated checks validate links/required fields and expose a bounded readiness result for operator use.
3. Current blockers include browser-based Codex auth/terms, NAR baseline/statement prerequisites, day-30 artifact, application queue, and provisioning trigger.
4. No new OAuth flow, public signup, tenant provisioning, or sales claim is implemented.
5. Existing onboarding tests remain green; probe tests prove read-only/fail-closed behavior.

SMOKE PLAN

• Run the readiness validator against current fixtures and assert known built/manual/blocked steps.
• Exercise the probe with capabilities present and absent; verify no writes or secret values.
• Review generated dependency order against integrations: hosted mobile-safe OAuth wizard with durable authorization state #300 and EPIC: the NAR ledger — compute Net Attention Returned from traces, not estimates #563 and include the exact readiness report under ## Smoke evidence.