Plans, usage & your account

For org admins.

This guide covers the self-serve side of running a Hekkos org: your plan tier and what it unlocks, how usage is measured, what happens when you hit a limit, and how to export or delete your org’s data. For the operator side (configuring Stripe, flipping enforcement), see the SaaS go-live runbook.

Plans at a glance

The paid plan comes in repo-count bands — you pay for the number of repositories you keep governed, and the per-repo price falls as you scale up. Every paid band shares the same operation limits (documents standardized, questions answered); the repository cap and the included monthly AI budget both scale up with the band, so a bigger band gets proportionally more monthly headroom (roughly the same per-repo allowance at every band — you are never given less room per repo for scaling up). The exact numbers and prices are set by your deployment’s operator; the launch defaults are shown here.

	Free	Starter	Growth	Scale	Enterprise
Repositories scanned	5	25	100	500	Unlimited
Price (monthly)	—	$99	$299	$799	Custom
Price (annual, ~2 months free)	—	$990	$2,990	$7,990	Custom
Included monthly AI budget (LLM tokens)	500K	5M	20M	100M	Custom
Documents standardized / month	50	1,000	1,000	1,000	1,000
Questions answered / month	200	5,000	5,000	5,000	5,000
Chat retrieval	Keyword (full-text)	Semantic + AI answers	Semantic + AI answers	Semantic + AI answers	Semantic + AI answers

Enterprise is unlimited and sits above Scale — it isn’t a self-serve checkout option; it’s arranged with whoever operates your deployment and set on their side. Scale is a finite 500-repo band on purpose: past it you move to Enterprise rather than an unlimited flat price.

The current numbers for your org — your band, repo count against its cap, and prices — are always shown on the Usage & Billing page and the Plans comparison (pricing) table in the dashboard, which reflect the effective values, never a hardcoded marketing number.

What “usage” means

Hekkos meters two things a customer can reason about, plus one internal guardrail:

Documents standardized — each time a suggestion PR standardizes a doc type for a repo, it’s one doc_standardized operation. (This metric is labelled Documents standardized consistently across the usage gauge, the plan table, and the usage-trend chart.)
Questions answered — each grounded chat / RAG (retrieval-augmented generation) answer is one question_answered operation. If Hekkos can’t ground an answer — it finds no strongly-matching source, or replies that it doesn’t know — that reply is not billed and does not count against your quota.
Included AI budget (internal guardrail) — the raw LLM tokens spent this month against the headroom included in your plan. This is not a meter: you are never charged per token or per call, and there is no overage line item. It’s an included allowance that also acts as a cost cap to stop runaway use, and — as of the band-scaled budget change — the allowance scales with your band, so bigger bands get proportionally more monthly headroom rather than buying tokens à la carte. You rarely think about it directly. If a scan reaches the budget mid-run, the repo is marked partial (never silently dropped) and automatically finishes on its own once your budget resets next month — this holds whether the work ran as a direct scan or as a paced rollout.

All three reset monthly. The Usage & Billing page shows current-period gauges and a short history of prior months. It leads with Operations this period — documents standardized + questions answered, the value work your plan meters — then your Capacity: the repositories you keep governed (the visible value axis) and, beneath them, the Token budget with a plain “cost guardrail, not a per-use charge” line so the guardrail never reads as the headline. A metric with no cap on your plan (an “unlimited” limit) shows a plain “N used · Unlimited” line instead of a percentage gauge. When repos are paused for exceeding a band cap, the Repositories block shows an “N paused — over your plan’s cap” notice right where you’d upgrade to resume them (the same signal Overview surfaces as a banner). A paused repo is fully idle — it consumes no scan, indexing, or AI budget while paused — and upgrading a band resumes the paused repos within seconds, not on the next daily cycle.

Chat retrieval by plan

Chat answers questions over your committed docs, and your plan sets the retrieval mode: Free matches by keyword and returns the matching passages; Team matches by meaning and writes a cited AI answer. Both are scoped to your org and respect per-document access restrictions identically — the full keyword-vs-semantic comparison lives in retrieval modes.

Hitting a limit

When an org reaches a plan limit, Hekkos tells you clearly instead of failing silently:

In chat, an over-quota or over-budget question returns a typed prompt: admins see an Upgrade button; members see “ask an admin to upgrade.”
On Overview, an admin sees an inline banner when the org is at (or near) a limit.
Approaching a limit (~80%), the Usage & Billing page nudges before you’re cut off.

Enforcement is a deployment setting (OPERATION_BILLING_ENABLED). When it’s off, usage is still recorded and displayed — you just aren’t cut off.

Effective tier & the past-due grace period

Your effective tier can differ from the raw plan for a short window:

A past-due Team org (a failed payment, in Stripe dunning) keeps full Team functionality for a 7-day grace period, then degrades to Free-tier limits until payment recovers — paying the outstanding invoice restores Team automatically.
A self-hosted deployment with no valid license is treated as Free regardless of plan.

The Usage & Billing page always shows the effective budget and limits — the figures actually enforced — not a stale column value.

Upgrading, downgrading & managing your subscription (SaaS)

From Usage & Billing (admin only):

Upgrade — starts a Stripe Checkout for the band you pick. If your deployment offers annual billing, the page defaults to annual (2 months free) with a toggle to switch to monthly; otherwise billing is monthly. You’ll be asked to accept the terms (a consent checkbox) before checkout opens on Stripe’s hosted page (with address/tax collection if the deployment enabled it). On success your org flips to the paid plan at that band, its included AI budget is raised to that band’s headroom, and repo discovery re-runs so any repos the Free cap skipped get scanned. If you cancel at checkout, no charge is made and nothing changes. If your org already has an active subscription — for example you left an old checkout tab open and subscribed elsewhere — checkout won’t start a second one; it points you to Manage subscription instead, so you’re never double-charged.
Manage subscription — opens the Stripe customer portal to update the card, download invoices, switch bands (up or down), or cancel. A cancellation returns the org to Free at period end.

Changing bands (up or down)

Band changes are self-serve, both directions, through the Stripe customer portal (Manage subscription). In the band ladder on the Usage & Billing page, each row’s “Switch to ” button opens that same portal — a short note by the ladder says so, since the portal (not the button) is where you select and confirm the new band. If your deployment offers annual billing, an annual / monthly toggle sits above the ladder so you can compare band prices in either cadence before clicking through. A switch is immediate and prorated by Stripe — moving Starter → Growth mid-cycle charges the prorated difference and raises your cap right away; moving Growth → Starter lowers it and credits the unused portion. Because the band you’re entitled to is always derived from the price you’re actually paying, the change takes effect as soon as Stripe confirms it:

Moving up re-runs repo discovery so repositories your smaller cap had skipped get picked up under the larger one, and raises your included AI budget to the new band’s headroom right away.
Moving down applies the smaller cap through the freeze behavior below. Your included AI budget keeps the larger band’s headroom until your next monthly refresh, then settles to the new band — you’re never dropped below what you’ve already used mid-cycle.

When a downgrade puts you over the new cap

If you downgrade to a band whose cap is below your current governed-repo count (say Growth/100 → Starter/25 while 40 repos are active), Hekkos never deletes anything. Instead it freezes the newest-over-cap repositories. The plan ladder on Usage & Billing tells you this before you commit: a move to a smaller band shows an inline line — “You have 40 repos; Starter covers 25. Your 15 newest repos will be paused — never deleted — and resume automatically if you move back up.” — right at the switch button, so the consequence and the never-delete promise are never a surprise after the fact.

The newest repos (by the date they were added) are frozen first, so your longest-standing, most-relied-on repos keep being governed.
A frozen repo is paused, not removed — its docs, history, and scan data stay intact. It is skipped by scanning and drift, excluded from chat answers (so a paused repo can’t serve stale truth), and its Trust badge shows “paused” instead of a score. Opening a pull request on a paused repo runs no drift review and incurs no AI budget, but any required Hekkos merge check still passes automatically so the PR is never blocked.
Usage & Billing shows an “N repos paused” count, and Overview shows a banner, so you can see exactly how many are over the cap.
Re-upgrade restores them — moving back up unfreezes repos oldest-first until you’re back under the new cap, exactly reversing the freeze. Nothing is lost by downgrading and later changing your mind.

The governed-unit meter

By default a band is metered against your repository count — the “N of M repos” line on Usage & Billing. Some deployments enable a governed-unit (GU) meter instead, which measures the governed surface you keep true rather than raw repo count. It exists because a monorepo can hold far more governed documents than it has repositories: one repo governing 40 service docs delivers the value of 40 single-doc repos, but a repo-count meter would only ever see one.

When the meter is on and it counts on the documents dimension, the capacity block is headed “Governed documents” (its honest name) rather than “Repositories” — the number is documents, not repos, so the heading says so directly instead of a footnote correcting it underneath. The band is compared against GU = max(repos, ⌈governed_docs / D⌉) — so a monorepo’s governed documents can push GU (and the “used of cap” figure) above its repo count. D is the deployment’s governed-docs-per-unit size. Only present, per-repo-authored documents count toward the surface; a document type you haven’t authored (or one covered by your org’s shared .github defaults) adds nothing, and paused repos are excluded.

Because GU has two dimensions, going over the cap has two different remedies:

Repo dimension (too many repositories) — the physical remedy still applies: the newest over-cap repos are frozen exactly as described above, and a re-upgrade unfreezes them oldest-first.
Docs dimension (governed surface exceeds the cap on a small repo count) — there is no freeze; you can’t pause a monorepo’s only repo without un-governing everything. The only remedy is to upgrade to a band whose cap covers the surface. Hekkos never destructively un-governs documents to fit a cap.

If the meter is on, Usage & Billing may also show an activation nudge comparing the surface you’ve been granted against what you’re actually governing, pointing you toward the band that fits. The GU meter is off by default — where it isn’t enabled, the “N of M repos” line means exactly what it says, and nothing on this page changes.

Exporting your data

Settings → Your data → Download my data (admin) returns a single org-scoped JSON bundle: your org profile, members, repos, doc standards & paths, selections, suggestions, attestation, the principles you authored (your governance rules), and the drift findings and daily Trust/Coverage trend Hekkos measured — so your data is genuinely portable, not locked in. The file is a versioned envelope (schema_version, exported_at, org_id, data). It contains no secrets (no encrypted keys or credentials) and no other org’s data.

Deleting your organization

Settings → Danger zone → Delete organization (admin) permanently removes the org. To guard against accident it requires you to type the org’s exact name to confirm. On confirm, Hekkos:

Cancels the live Stripe subscription (if any), then
Enqueues a background purge of the org’s data.

Legal

Public legal pages are served at /legal/terms, /legal/privacy, and /legal/dpa. Until your deployment’s operator has had counsel review and approve them, they show a “template — have counsel review” banner. Checkout includes a consent step, and a dismissible cookie notice appears on first visit.

Related: chat & retrieval modes · getting started · operator: SaaS go-live runbook