lhumina_code/hero_onboarding

Fork 0

Hero onboarding website + billing backend — full plan #1

New issue

Open

opened 2026-05-20 15:54:04 +00:00 by mik-tf · 0 comments

mik-tf commented

2026-05-20 15:54:04 +00:00

Owner

Hero onboarding website + billing backend — full plan

Source: meeting Kristof + Emre, 2026-05-20.

This issue captures the full plan for the onboarding website (login + payment + dashboard) and the billing backend (per-node forge billing-record repos + centralized aggregator). It is intentionally one meta-issue rather than many small ones — the parts are tightly coupled and the cross-cutting design decisions need a single review surface.

Sub-tasks are listed under "Phased delivery" below. Each phase will get its own follow-up issue once this meta-plan is agreed.

Scope

In scope (this repo):

(A) Onboarding website — mycelium-address login, payment (Stripe + ClickPesa, sandbox first then live), dashboard with credit balance + active services + usage breakdown.
(B) Billing backend — usage logging on every Hero node, per-node Forge repos that hold the billing records, centralized aggregator service that pulls all node repos and consolidates per-user balances.

Out of scope (tracked elsewhere):

(C) Common-services migration — hero_embedder / hero_aibroker / hero_voice / hero_proxy moving from per-user to multi-tenant common hosts attached over Mycelium. Owners: embedder / voice / aibroker / proxy teams.
(D) macOS CI runner — needed for full-matrix builds; needs an owner with a Mac kept up. Operational, not code.
Auto-deploy of the underlying VM — when a user pays, the VM itself may come from a pre-deployed pool (v0) or be spun up via TFchain (v1+). The provisioner mechanism is abstracted (see "Architecture > Provisioning"); the actual TFchain auto-deploy work is a separate effort.

Pricing model (from meeting notes)

Resource	Price
VMs (2 GB each)	$10 / month for 5 machines · $20 / month for 10 machines
Hero OS per-instance	$0.10 / hour + 10% margin
LLM passthrough (OpenRouter / Groq / etc.)	provider list price + 10% margin

Discount ladder (applies to Hero OS hourly + LLM):

After 1 week of continuous usage: −50%
After 1 month of continuous usage: an additional −50% on top of the first discount

Auth model

Mycelium-address only. Users authenticate by proving control of a Mycelium address. No email/password fallback in v0.

This matches the hero_login design pattern: every Hero context is mycelium-addressable, so the same identity flows through onboarding, billing, and later service install / start-stop admin actions.

Email/password / OAuth providers can be added later if a real user requirement surfaces — kept out of v0 to avoid surface area we don't yet need.

Architecture

Service shape

Website itself ships as a Hero service (kind=web per the canonical lab / hero_proc convention). Deployed via lab + hero_proc on a VM. No fancy orchestration in v0 — single instance, redeploy via the existing lab build --upload + lab build --download --install flow.
Workspace layout follows the canonical D-10 / D-11 pattern: hero_onboarding_server/ (web), hero_onboarding_admin/ (admin daemon), hero_onboarding/ (CLI launcher), hero_onboarding_schema/ (oschema definitions), 3× service.toml, build.rs for codegen.

Schema

User data + billing state live in an OSIS schema written in oschema (the existing Hero schema definition language under hero_skills/skills/oschema/). build.rs runs oschema_code_generation to produce Rust types + OSIS handlers + an RPC server.

Entities (v0):

User — mycelium address (canonical identifier), display name, created-at, last-active.
Billing — credit balance, lifetime paid, current discount tier (week / month).
UsageRecord — append-only log of "user X consumed Y units of resource Z at timestamp T on node N." This is the atomic unit pushed to per-node Forge repos.
PaymentEvent — Stripe / ClickPesa webhook outcome: provider, amount, currency, status, external-ref, applied-to-user.

Schema is the canonical interface; everything else (RPC, UI, billing aggregator) generates from it.

Per-node billing-record repos (the "real" design, no shortcuts)

Each Hero node — embedder host, aibroker host, hero_proxy host, individual user VM host, etc. — runs a hero_proc cron service that pushes its local usage log to a dedicated per-node Forge repo every hour.

One Forge repo per node, under a service account (proposed: hero_ops or hero_deploy — naming TBD; see Open questions).
Standard naming so the aggregator can enumerate without manual config (proposed: hero_ops/billing-<node-name> — naming TBD).
Cron pushes use the existing lab repo push mechanic (or equivalent).
Records are append-only TSV / JSONL files committed in chronological chunks (one file per hour, or rotated by size — TBD in Phase 4 design).

Hash-resume semantics (the "HARD part" called out in the meeting):

The aggregator tracks the last-consumed commit hash per node-repo.
On each poll: git log <last-hash>..HEAD enumerates new commits → new usage records.
Successful aggregation advances the hash; failed aggregation does NOT advance — the next poll retries from the same hash.
Explicit success / failure modes:
- Success: every new record consumed, balance updated, hash advanced.
- Failure: any parse error, any consistency violation (e.g. negative balance attempt without explicit refund), or any duplicate idempotency-key collision → hash stays put, alert emitted, no partial application.
Double-charge prevention: every UsageRecord carries an idempotency key (proposed: (node_id, local_seq, timestamp)). The aggregator rejects duplicates.

Centralized aggregator

A separate Hero service (hero_onboarding_aggregator/ — naming TBD) that:

Enumerates known node-repos (configured list or service-account-repo-pattern discovery).
For each repo: git pull → walk new commits → parse new UsageRecord entries → apply to the corresponding user's Billing row in the central OSIS schema.
Emits aggregation metrics (records consumed, balances updated, errors).
Runs on the same host as the onboarding website in v0 (separate host later when scale demands).

Provisioning (agnostic, plug-in)

Define a Provisioner trait / interface. v0 ships one impl + room for more:

trait Provisioner {
    fn allocate(&self, user: &User, sku: ResourceSku) -> Result<Allocation, ProvisionError>;
    fn release(&self, allocation: &Allocation) -> Result<(), ProvisionError>;
    fn status(&self, allocation: &Allocation) -> Result<AllocationStatus, ProvisionError>;
}

v0 impl: PoolAssignmentProvisioner — ops pre-deploys a pool of VMs (the same way the existing herodemo VM was deployed); the website assigns an unallocated VM from the pool when a user pays.
v1+ impl: TfchainAutoDeployProvisioner — full TFchain contract creation on demand, no pre-deployed pool. Separate effort, separate session.

This way the website's payment-success flow and the underlying VM acquisition flow are decoupled; we don't lock in a design that's wrong for v1.

Reused in-house components

A neighboring in-house product has already shipped, end-to-end-tested, and proven in production all three external integrations Phase 2 / 3 / 6 need. We lift, we don't reinvent.

Stripe + ClickPesa top-up flows — wallet top-up paths covering checkout, webhook signature verification, idempotent payment recording, currency handling, refund mechanics. Implementation includes provider abstractions, SDK models, end-to-end Playwright coverage of the happy path + retry-on-failure + duplicate-webhook protection. Lift posture: SDK models + provider abstractions + webhook handlers transfer cleanly (same wire contracts as Stripe / ClickPesa public APIs). UI components are Dioxus-based and get rewritten into the hero_website_framework Tera-template idiom — the business logic doesn't change, only the presentation layer.
Idenfy KYC integration — production-grade flow covering session creation, browser redirect, callback handling, retry-on-failure, KYC-reset-and-re-create, and tier-based access gating. Already-shipped artifacts:
- kyc.oschema schema — written in the same canonical Hero schema language we're using for hero_onboarding. Direct copy possible at the schema layer; zero rewrite.
- Backend crate with OpenRPC interface (openrpc.json + rpc.rs), code-generated types (types_generated.rs), and core logic cleanly separated into a core/ module. Transfers cleanly modulo renaming.
- Frontend Dioxus components (step_kyc_terms.rs + multi-step wizard integration) — same UI impedance-mismatch as Stripe / ClickPesa; logic transfers, UI rewrites.
- 6+ Playwright e2e scenarios including KYC session creation, retry on failed verification, browser-flow happy path, full reset → re-create → complete arc.
- Provider: Idenfy. Same vendor account / tenant credentials can be reused (subject to account-level confirmation) or fresh Idenfy credentials provisioned for the Hero tenant.
oschema + oschema_code_generation skills (under hero_skills/skills/oschema/) — canonical Hero schema definition language. No separate template to wait on.
hero_website_framework — kind=web scaffold with pages, blog, auth, admin.
hero_proc cron — built-in scheduled-job mechanism for the hourly billing-record push.
lab repo push — for the cron's actual git push to each node-repo.

Phased delivery

Each phase will get its own follow-up issue linked back to this meta-issue once this plan is agreed.

Phase 1 — Schema scaffold + skeleton web service

Workspace layout (Cargo.toml, 3 crates, 3 service.toml, build.rs).
hero_onboarding_schema/ — User, Billing, UsageRecord, PaymentEvent in oschema.
hero_onboarding_server/ — kind=web skeleton, mycelium-address login, dashboard (balance + placeholder for active services), payment stubbed (button → 200 OK → fake credit applied).
hero_onboarding_admin/ — kind=admin daemon skeleton.
README + service.toml entries follow canonical D-10 / D-11 shape.
Acceptance: lab build --release --install clean; lab infocheck clean; lab service hero_onboarding_server --start opens the page; mycelium-address login + dashboard render.

Phase 2 — Stripe sandbox integration

Lift Stripe SDK + provider components from the in-house wallet top-up flow.
Sandbox keys in hero_proc secrets context (per existing META env convention).
Top-up flow: user clicks pay → Stripe Checkout sandbox → webhook → PaymentEvent recorded → Billing.credit_balance incremented.
Acceptance: end-to-end sandbox top-up applies a credit visible on the dashboard; webhook idempotency tested (replay does NOT double-credit).

Phase 3 — ClickPesa sandbox integration

Symmetric to Phase 2, sibling provider.
Acceptance: same as Phase 2 against ClickPesa sandbox.

Phase 4 — Per-node billing-record push (hero_proc cron + lab repo push)

Define the UsageRecord wire format (TSV or JSONL; TBD).
Implement a small library / nu module a Hero node embeds to write local usage records.
hero_proc cron service that, every hour, commits the new records and pushes to the node's Forge repo.
Acceptance: a test node generates synthetic usage records; cron pushes them on schedule; the per-node Forge repo shows hourly commits.

Phase 5 — Centralized aggregator + hash-resume idempotency

hero_onboarding_aggregator/ service.
Hash-resume logic: per-node last-consumed-commit tracking + safe retry semantics.
Idempotency-key enforcement.
Failure modes (parse error / consistency violation / dup key) → alert + no partial application.
Acceptance: aggregator consumes records from a real test node-repo; balance updates appear in the central schema; failure injection (corrupt a commit) → aggregation halts cleanly on that repo, others continue.

Phase 6 — Production keys, Idenfy KYC, pool-assignment Provisioner, live wiring

Stripe + ClickPesa production keys (after sandbox cycles are clean).
Idenfy KYC integration — lift from the in-house implementation (see "Reused in-house components" above). Direct copy of kyc.oschema into hero_onboarding_schema/; lift the backend crate (rename + adapt to hero_onboarding's OSIS dispatcher); rewrite the Dioxus wizard step into a Tera template + small JS for the Idenfy browser redirect; reuse the 6+ Playwright e2e scenarios as the acceptance gate. Decision: same Idenfy account or fresh tenant credentials.
PoolAssignmentProvisioner impl: ops pre-deploys VMs, the website assigns one on payment success.
End-to-end happy-path: user logs in → completes KYC → tops up → an actual VM is assigned + provisioned with their Hero context.

Optional rescope: Idenfy KYC could move earlier (e.g. between Phase 3 and Phase 4) if KYC is a hard gate before any payment — that decision is one of the open questions below. Phase 6 keeps it as the default to land it after sandbox payment flows are clean.

Open questions for Kristof + Emre

Service account name for the per-node billing-record repos: hero_ops / hero_deploy / hero_billing / something else?
Per-node repo naming convention: hero_ops/billing-<node-name> / hero_ops/<node-name>-billing / something else? The aggregator's discoverability depends on this being stable.
UsageRecord wire format: TSV / JSONL / oschema-OTOML? Trade-off: TSV is easiest for git diff, JSONL is easiest for tooling, OTOML matches the rest of the Hero stack.
Idenfy KYC tenancy: reuse the same Idenfy account / tenant credentials as the in-house wallet product, or provision fresh Idenfy credentials for the Hero tenant? Both are technically viable; question is account / billing / branding.
KYC gating order: is KYC a hard gate before any payment (move to Phase 4 or earlier), or after the first top-up (stays in Phase 6)? Affects flow shape.
Pool size for v0: how many VMs does ops pre-deploy for the launch? (Phase 6 question.)
Discount ladder mechanics: is "1 week of continuous usage" measured wall-clock since first payment, or total active hours? Edge case: user pays, doesn't use for 8 days, then uses heavily — do they get the −50%?
Refunds: out of v0 entirely (manual ops intervention), or do we wire a refund path through Stripe / ClickPesa from day 1?
Multi-currency: Stripe defaults to USD; ClickPesa is regional. Do we display unified USD balances or per-currency balances?

Out of scope / follow-up issues to file

Common-services migration (embedder / aibroker / voice / proxy → multi-tenant common hosts attached over Mycelium) — separate META.
macOS CI runner — operational, needs Mac-equipped owner.
TFchain auto-deploy of underlying VMs — replaces the PoolAssignmentProvisioner impl with TfchainAutoDeployProvisioner impl; separate session post-v0.
Multi-region / HA aggregator — single instance is fine until scale demands otherwise.

hero_website_framework — kind=web skeleton.
hero_skills/skills/oschema/ + oschema_code_generation — schema → codegen pipeline.
hero_proc — supervision + cron + secrets context.
hero_router — service entry / discovery / MCP gateway (the onboarding website registers behind it).
hero_login pattern (when / if it exists as a separate crate; otherwise wire mycelium-address auth directly using the documented context + claim format).
lab — build / install / publish / repo-push orchestrator used by Phase 4's cron.

# Hero onboarding website + billing backend — full plan Source: meeting Kristof + Emre, 2026-05-20. This issue captures the full plan for the onboarding website (login + payment + dashboard) and the billing backend (per-node forge billing-record repos + centralized aggregator). It is intentionally one meta-issue rather than many small ones — the parts are tightly coupled and the cross-cutting design decisions need a single review surface. Sub-tasks are listed under "Phased delivery" below. Each phase will get its own follow-up issue once this meta-plan is agreed. --- ## Scope **In scope (this repo):** - **(A) Onboarding website** — mycelium-address login, payment (Stripe + ClickPesa, sandbox first then live), dashboard with credit balance + active services + usage breakdown. - **(B) Billing backend** — usage logging on every Hero node, per-node Forge repos that hold the billing records, centralized aggregator service that pulls all node repos and consolidates per-user balances. **Out of scope (tracked elsewhere):** - **(C) Common-services migration** — `hero_embedder` / `hero_aibroker` / `hero_voice` / `hero_proxy` moving from per-user to multi-tenant common hosts attached over Mycelium. Owners: embedder / voice / aibroker / proxy teams. - **(D) macOS CI runner** — needed for full-matrix builds; needs an owner with a Mac kept up. Operational, not code. - **Auto-deploy of the underlying VM** — when a user pays, the VM itself may come from a pre-deployed pool (v0) or be spun up via TFchain (v1+). The provisioner mechanism is abstracted (see "Architecture > Provisioning"); the actual TFchain auto-deploy work is a separate effort. --- ## Pricing model (from meeting notes) | Resource | Price | |---|---| | VMs (2 GB each) | $10 / month for 5 machines · $20 / month for 10 machines | | Hero OS per-instance | $0.10 / hour + 10% margin | | LLM passthrough (OpenRouter / Groq / etc.) | provider list price + 10% margin | **Discount ladder** (applies to Hero OS hourly + LLM): - After 1 week of continuous usage: −50% - After 1 month of continuous usage: an additional −50% on top of the first discount --- ## Auth model **Mycelium-address only.** Users authenticate by proving control of a Mycelium address. No email/password fallback in v0. This matches the `hero_login` design pattern: every Hero context is mycelium-addressable, so the same identity flows through onboarding, billing, and later service install / start-stop admin actions. Email/password / OAuth providers can be added later if a real user requirement surfaces — kept out of v0 to avoid surface area we don't yet need. --- ## Architecture ### Service shape - **Website itself** ships as a Hero service (`kind=web` per the canonical lab / hero_proc convention). Deployed via lab + hero_proc on a VM. No fancy orchestration in v0 — single instance, redeploy via the existing `lab build --upload` + `lab build --download --install` flow. - **Workspace layout** follows the canonical D-10 / D-11 pattern: `hero_onboarding_server/` (web), `hero_onboarding_admin/` (admin daemon), `hero_onboarding/` (CLI launcher), `hero_onboarding_schema/` (oschema definitions), 3× `service.toml`, `build.rs` for codegen. ### Schema User data + billing state live in an OSIS schema written in **oschema** (the existing Hero schema definition language under `hero_skills/skills/oschema/`). `build.rs` runs `oschema_code_generation` to produce Rust types + OSIS handlers + an RPC server. **Entities (v0):** - `User` — mycelium address (canonical identifier), display name, created-at, last-active. - `Billing` — credit balance, lifetime paid, current discount tier (week / month). - `UsageRecord` — append-only log of "user X consumed Y units of resource Z at timestamp T on node N." This is the atomic unit pushed to per-node Forge repos. - `PaymentEvent` — Stripe / ClickPesa webhook outcome: provider, amount, currency, status, external-ref, applied-to-user. Schema is the canonical interface; everything else (RPC, UI, billing aggregator) generates from it. ### Per-node billing-record repos (the "real" design, no shortcuts) Each Hero node — embedder host, aibroker host, hero_proxy host, individual user VM host, etc. — runs a `hero_proc` cron service that pushes its local usage log to a dedicated per-node Forge repo every hour. - One Forge repo per node, under a service account (proposed: `hero_ops` or `hero_deploy` — naming TBD; see Open questions). - Standard naming so the aggregator can enumerate without manual config (proposed: `hero_ops/billing-<node-name>` — naming TBD). - Cron pushes use the existing `lab repo push` mechanic (or equivalent). - Records are append-only TSV / JSONL files committed in chronological chunks (one file per hour, or rotated by size — TBD in Phase 4 design). **Hash-resume semantics** (the "HARD part" called out in the meeting): - The aggregator tracks the last-consumed commit hash per node-repo. - On each poll: `git log <last-hash>..HEAD` enumerates new commits → new usage records. - Successful aggregation advances the hash; failed aggregation does NOT advance — the next poll retries from the same hash. - **Explicit success / failure modes:** - Success: every new record consumed, balance updated, hash advanced. - Failure: any parse error, any consistency violation (e.g. negative balance attempt without explicit refund), or any duplicate idempotency-key collision → hash stays put, alert emitted, no partial application. - Double-charge prevention: every `UsageRecord` carries an idempotency key (proposed: `(node_id, local_seq, timestamp)`). The aggregator rejects duplicates. ### Centralized aggregator A separate Hero service (`hero_onboarding_aggregator/` — naming TBD) that: 1. Enumerates known node-repos (configured list or service-account-repo-pattern discovery). 2. For each repo: `git pull` → walk new commits → parse new `UsageRecord` entries → apply to the corresponding user's `Billing` row in the central OSIS schema. 3. Emits aggregation metrics (records consumed, balances updated, errors). 4. Runs on the same host as the onboarding website in v0 (separate host later when scale demands). ### Provisioning (agnostic, plug-in) Define a `Provisioner` trait / interface. v0 ships **one impl** + room for more: ``` trait Provisioner { fn allocate(&self, user: &User, sku: ResourceSku) -> Result<Allocation, ProvisionError>; fn release(&self, allocation: &Allocation) -> Result<(), ProvisionError>; fn status(&self, allocation: &Allocation) -> Result<AllocationStatus, ProvisionError>; } ``` - **v0 impl: `PoolAssignmentProvisioner`** — ops pre-deploys a pool of VMs (the same way the existing herodemo VM was deployed); the website assigns an unallocated VM from the pool when a user pays. - **v1+ impl: `TfchainAutoDeployProvisioner`** — full TFchain contract creation on demand, no pre-deployed pool. Separate effort, separate session. This way the website's payment-success flow and the underlying VM acquisition flow are decoupled; we don't lock in a design that's wrong for v1. ### Reused in-house components A neighboring in-house product has already shipped, end-to-end-tested, and proven in production all three external integrations Phase 2 / 3 / 6 need. We lift, we don't reinvent. - **Stripe + ClickPesa top-up flows** — wallet top-up paths covering checkout, webhook signature verification, idempotent payment recording, currency handling, refund mechanics. Implementation includes provider abstractions, SDK models, end-to-end Playwright coverage of the happy path + retry-on-failure + duplicate-webhook protection. **Lift posture:** SDK models + provider abstractions + webhook handlers transfer cleanly (same wire contracts as Stripe / ClickPesa public APIs). UI components are Dioxus-based and get rewritten into the hero_website_framework Tera-template idiom — the business logic doesn't change, only the presentation layer. - **Idenfy KYC integration** — production-grade flow covering session creation, browser redirect, callback handling, retry-on-failure, KYC-reset-and-re-create, and tier-based access gating. Already-shipped artifacts: - **`kyc.oschema` schema** — written in the same canonical Hero schema language we're using for `hero_onboarding`. **Direct copy possible at the schema layer; zero rewrite.** - **Backend crate** with OpenRPC interface (`openrpc.json` + `rpc.rs`), code-generated types (`types_generated.rs`), and core logic cleanly separated into a `core/` module. Transfers cleanly modulo renaming. - **Frontend Dioxus components** (`step_kyc_terms.rs` + multi-step wizard integration) — same UI impedance-mismatch as Stripe / ClickPesa; logic transfers, UI rewrites. - **6+ Playwright e2e scenarios** including KYC session creation, retry on failed verification, browser-flow happy path, full reset → re-create → complete arc. - **Provider: Idenfy.** Same vendor account / tenant credentials can be reused (subject to account-level confirmation) or fresh Idenfy credentials provisioned for the Hero tenant. - **oschema + oschema_code_generation skills** (under `hero_skills/skills/oschema/`) — canonical Hero schema definition language. No separate template to wait on. - **hero_website_framework** — `kind=web` scaffold with pages, blog, auth, admin. - **hero_proc cron** — built-in scheduled-job mechanism for the hourly billing-record push. - **lab repo push** — for the cron's actual git push to each node-repo. --- ## Phased delivery Each phase will get its own follow-up issue linked back to this meta-issue once this plan is agreed. ### Phase 1 — Schema scaffold + skeleton web service - Workspace layout (`Cargo.toml`, 3 crates, 3 `service.toml`, `build.rs`). - `hero_onboarding_schema/` — `User`, `Billing`, `UsageRecord`, `PaymentEvent` in oschema. - `hero_onboarding_server/` — `kind=web` skeleton, mycelium-address login, dashboard (balance + placeholder for active services), payment **stubbed** (button → 200 OK → fake credit applied). - `hero_onboarding_admin/` — `kind=admin` daemon skeleton. - README + service.toml entries follow canonical D-10 / D-11 shape. - Acceptance: `lab build --release --install` clean; `lab infocheck` clean; `lab service hero_onboarding_server --start` opens the page; mycelium-address login + dashboard render. ### Phase 2 — Stripe sandbox integration - Lift Stripe SDK + provider components from the in-house wallet top-up flow. - Sandbox keys in `hero_proc` secrets context (per existing META env convention). - Top-up flow: user clicks pay → Stripe Checkout sandbox → webhook → `PaymentEvent` recorded → `Billing.credit_balance` incremented. - Acceptance: end-to-end sandbox top-up applies a credit visible on the dashboard; webhook idempotency tested (replay does NOT double-credit). ### Phase 3 — ClickPesa sandbox integration - Symmetric to Phase 2, sibling provider. - Acceptance: same as Phase 2 against ClickPesa sandbox. ### Phase 4 — Per-node billing-record push (hero_proc cron + lab repo push) - Define the `UsageRecord` wire format (TSV or JSONL; TBD). - Implement a small library / nu module a Hero node embeds to write local usage records. - `hero_proc` cron service that, every hour, commits the new records and pushes to the node's Forge repo. - Acceptance: a test node generates synthetic usage records; cron pushes them on schedule; the per-node Forge repo shows hourly commits. ### Phase 5 — Centralized aggregator + hash-resume idempotency - `hero_onboarding_aggregator/` service. - Hash-resume logic: per-node last-consumed-commit tracking + safe retry semantics. - Idempotency-key enforcement. - Failure modes (parse error / consistency violation / dup key) → alert + no partial application. - Acceptance: aggregator consumes records from a real test node-repo; balance updates appear in the central schema; failure injection (corrupt a commit) → aggregation halts cleanly on that repo, others continue. ### Phase 6 — Production keys, Idenfy KYC, pool-assignment Provisioner, live wiring - Stripe + ClickPesa production keys (after sandbox cycles are clean). - **Idenfy KYC integration** — lift from the in-house implementation (see "Reused in-house components" above). Direct copy of `kyc.oschema` into `hero_onboarding_schema/`; lift the backend crate (rename + adapt to hero_onboarding's OSIS dispatcher); rewrite the Dioxus wizard step into a Tera template + small JS for the Idenfy browser redirect; reuse the 6+ Playwright e2e scenarios as the acceptance gate. Decision: same Idenfy account or fresh tenant credentials. - `PoolAssignmentProvisioner` impl: ops pre-deploys VMs, the website assigns one on payment success. - End-to-end happy-path: user logs in → completes KYC → tops up → an actual VM is assigned + provisioned with their Hero context. **Optional rescope:** Idenfy KYC could move earlier (e.g. between Phase 3 and Phase 4) if KYC is a hard gate before any payment — that decision is one of the open questions below. Phase 6 keeps it as the default to land it after sandbox payment flows are clean. --- ## Open questions for Kristof + Emre 1. **Service account name** for the per-node billing-record repos: `hero_ops` / `hero_deploy` / `hero_billing` / something else? 2. **Per-node repo naming convention**: `hero_ops/billing-<node-name>` / `hero_ops/<node-name>-billing` / something else? The aggregator's discoverability depends on this being stable. 3. **`UsageRecord` wire format**: TSV / JSONL / oschema-OTOML? Trade-off: TSV is easiest for `git diff`, JSONL is easiest for tooling, OTOML matches the rest of the Hero stack. 4. **Idenfy KYC tenancy**: reuse the same Idenfy account / tenant credentials as the in-house wallet product, or provision fresh Idenfy credentials for the Hero tenant? Both are technically viable; question is account / billing / branding. 5. **KYC gating order**: is KYC a hard gate **before** any payment (move to Phase 4 or earlier), or **after** the first top-up (stays in Phase 6)? Affects flow shape. 6. **Pool size for v0**: how many VMs does ops pre-deploy for the launch? (Phase 6 question.) 7. **Discount ladder mechanics**: is "1 week of continuous usage" measured wall-clock since first payment, or total active hours? Edge case: user pays, doesn't use for 8 days, then uses heavily — do they get the −50%? 8. **Refunds**: out of v0 entirely (manual ops intervention), or do we wire a refund path through Stripe / ClickPesa from day 1? 9. **Multi-currency**: Stripe defaults to USD; ClickPesa is regional. Do we display unified USD balances or per-currency balances? --- ## Out of scope / follow-up issues to file - Common-services migration (embedder / aibroker / voice / proxy → multi-tenant common hosts attached over Mycelium) — separate META. - macOS CI runner — operational, needs Mac-equipped owner. - TFchain auto-deploy of underlying VMs — replaces the `PoolAssignmentProvisioner` impl with `TfchainAutoDeployProvisioner` impl; separate session post-v0. - Multi-region / HA aggregator — single instance is fine until scale demands otherwise. --- ## Related repos / patterns - `hero_website_framework` — `kind=web` skeleton. - `hero_skills/skills/oschema/` + `oschema_code_generation` — schema → codegen pipeline. - `hero_proc` — supervision + cron + secrets context. - `hero_router` — service entry / discovery / MCP gateway (the onboarding website registers behind it). - `hero_login` pattern (when / if it exists as a separate crate; otherwise wire mycelium-address auth directly using the documented context + claim format). - `lab` — build / install / publish / repo-push orchestrator used by Phase 4's cron.