Skip to content

docs: add Billing section (trial, seats, spillover, lifecycle, FAQ)#4

Open
maekuss wants to merge 4 commits into
mainfrom
docs/billing-detail-spillover-trial-skip
Open

docs: add Billing section (trial, seats, spillover, lifecycle, FAQ)#4
maekuss wants to merge 4 commits into
mainfrom
docs/billing-detail-spillover-trial-skip

Conversation

@maekuss
Copy link
Copy Markdown

@maekuss maekuss commented May 16, 2026

Summary

Adds a 6-page Billing group under the Platform tab covering everything `platform/billing-access.mdx` doesn't go deep on:

  • `platform/billing/overview.mdx` — what you pay for, where each topic lives
  • `platform/billing/trial.mdx` — 14-day trial, three end-of-trial paths, the trial-skip path (one-time-per-org `has_used_trial` is documented explicitly)
  • `platform/billing/seats.mdx` — peak (HWM) billing with a worked Day/Event/Seats/Invoice example table
  • `platform/billing/spillover.mdx` — full PR overage flow: 4-condition eligibility (LD × ACTIVE × owner opt-in × not OSS-exempt), meter event mechanics with 3-layer idempotency, lazy meter-item attach, mid-period toggle semantics, deny copy precedence
  • `platform/billing/lifecycle.mdx` — cancel → grace → reactivate / past-due / resubscribe, with a state-by-state action matrix
  • `platform/billing/faq.mdx` — 10 named scenarios (hired mid-month, hit the spillover cap, canceled mid-period, payment failed, …) plus a glossary

Voice and structure follow conventions from Greptile and CodeRabbit docs: one-sentence lead, `` role-badge callout for Owner-only pages, named accordion scenarios over generic Q&A, "What's next" CardGroups on every non-terminal page, worked-example tables for math.

Nav: new `Billing` group added to `docs.json` under the Platform tab, between Overview and the rest. `platform/billing-access.mdx` is unchanged on this PR — its factual issues are listed in `docs-audit.md` for a follow-up.

Also shipped

  • `docs-audit.md` — independent drift audit of every existing docs page against `iva/origin/main` and `hecktron/origin/main` with `file:line` citations. Lists ~30 drift items across 14 pages and a Top-10 prioritized fix list. No existing pages were modified on this PR; the audit is intended as the scope spec for a follow-up "docs accuracy" PR.

    Highlights worth pulling forward separately:

    • `api-reference/findings/list-findings.mdx` documents `impact`/`root_cause`/`remediation` — fields that don't exist on the `Finding` entity
    • `platform/billing-access.mdx` says "200 PRs per seat" — the actual cap defaults to 50 (200 is the file-change-per-PR cap, an unrelated knob)
    • Pentest "Owner-only start" is wrong everywhere — UI gates Admin+Owner, backend allows any Member, only credit purchase is owner-only
    • Roles table lists 5 roles; the enum has 4 ("Unassigned" is a People-page UI label, not a role)
    • Swagger UI URL points to `/docs` (internal, basic-auth); public path is `/api-docs`
    • Rate-limits doc covers 1 of 3 throttlers running concurrently

Test plan

  • Run Mintlify locally (`pnpm dev` or the configured equivalent) and walk every new page top-to-bottom
  • Confirm the `Billing` group appears under the Platform tab in nav order: Overview → Trial → Seats → Spillover → Lifecycle → FAQ
  • Confirm every `` "What's next" link resolves
  • Confirm every intra-billing link (`/platform/billing/*`) and the back-link to `/platform/billing-access` resolves
  • Confirm the hero `` on `overview.mdx` renders the existing `/images/platform-billing-dark.png`
  • Sanity-check three accuracy claims against the iva codebase:
    • `spillover.mdx` four-condition eligibility matches `apps/iva/src/seat/dev/dev-seat-policy.service.ts:815-830`
    • `seats.mdx` peak-billing math matches `apps/iva/src/seat/dev/dev-seat-billing.service.ts:182-235`
    • `trial.mdx` one-time-per-org claim matches `apps/iva/src/payments/trial.service.ts:140-144`

Companion PR on `HacktronAI/iva` (state diagram with code citations, target: staging): https://github.com/HacktronAI/iva/pull/821

Followups (out of scope for this PR)

  • Screenshots to match the existing pages' `` treatment — see "Pictures to add" section in the PR conversation
  • Apply the `docs-audit.md` fixes in a separate PR

🤖 Generated with Claude Code

maekuss and others added 4 commits May 16, 2026 15:22
@maekuss @claude
docs: add Billing section (trial, seats, spillover, lifecycle, FAQ)
4d09355 
Introduce a 6-page Billing cluster under the Platform tab that goes
deeper than billing-access.mdx: a map page, the trial mechanics with
the explicit trial-skip path, peak/HWM math with a worked example,
the full spillover (PR overage) decision tree and toggle semantics,
the cancel/grace/reactivate/past-due/resubscribe lifecycle, and a
named-scenario FAQ.

Voice and structure follow the conventions of Greptile and
CodeRabbit's docs: one-sentence lead, role-badge callout for
owner-only pages, named accordion scenarios over generic Q&A,
"What's next" card grids, worked-example tables for billing math.

Also ships docs-audit.md, an independent audit of every other docs
page against iva/main and hecktron/main with file:line citations
for each drift item. Not applied here — billing additions only on
this branch — but ready for a follow-up PR.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@maekuss @claude
docs(billing): use existing billing screenshot, drop internal link
2518e62 
Reuse the existing platform-billing-dark.png hero card on the billing
overview to match the visual treatment of platform/billing-access.mdx.
Drop the internal iva-repo state-diagram link from lifecycle.mdx —
public docs shouldn't reference a private repo path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@maekuss @claude
docs(billing): add screenshot placeholders mapped to hecktron components
801ef9b 
Drops <Frame> placeholders at 8 spots across the billing pages, each
with alt text and caption that describe the exact frontend component
or route to capture. Adds /images/screenshot-placeholder.svg as a
visual marker during review, plus platform/billing/IMAGES.md as a
checklist mapping each placeholder to the source component on
hecktron/origin/main (with the suggested PNG filename).

Once real screenshots land, replace each <img src> with the named
file from /images/ and delete IMAGES.md + the placeholder SVG.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@maekuss @claude
docs(billing): correct against iva/hecktron main (trial-skip + spillo…
23792d4 
…ver gates)

Two factual bugs fixed after verifying every claim against
iva/origin/main and hecktron/origin/main:

1. **Trial-skip is not a separate entry point.** There is no "Start
   paid plan" button. Every paid subscription starts as a trial —
   adding a payment method on a trial-eligible org auto-starts the
   trial (usePaymentMethodSetup + savePaymentMethod). To get to paid
   billing same-day, start the trial and click "Skip trial" on the
   Billing sidebar (applySubscriptionAction with action='end-trial').
   Same-day Skip still flips has_used_trial permanently. Updated:
   trial.mdx (rewrote the skip section), faq.mdx (skip scenario +
   glossary), lifecycle.mdx (state matrix), overview.mdx (glossary).

2. **Spillover has 3 gates, not 4.** On main, eligibility is:
   subscription ACTIVE + owner opt-in + not OSS-exempt. There is no
   LaunchDarkly master switch in dev-seat-policy.service.ts:858-861.
   The earlier 4-condition claim came from a planning doc, not the
   shipped code. Internal-unlimited orgs bypass everything separately.
   Updated: spillover.mdx (steps, deny table, troubleshooting).

Also tightened:
- Lifecycle state-action matrix: Past-due no longer shows a Cancel
  button (isActive gate excludes past_due); Canceled state split by
  trial-already-used to reflect the trialCtaVisible vs Resubscribe
  branch in billing.vue.
- Permissions table footnote naming the four roles (Viewer / Member
  / Admin / Owner) and noting higher-role inheritance.
- HWM "monotonically increases" → "monotonically non-decreasing within
  a period; reset on rollover" — precise wording.
- "How the trial starts" step 4 reworded — adding a PM auto-starts;
  there is no separate confirm step.
- Trial troubleshooting accordion rewritten to match real UI labels.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@maekuss