Concepts

For anyone in the org.

The handful of terms the guides lean on, each in plain language, with a link to the guide that covers it in full.

Plan tier

The plan your org is on — Free or the paid plan. It sets your monthly usage limits and which retrieval mode chat uses. The paid plan is split into repo-count bands (below), and above the top band sits an operator-only Enterprise tier (unlimited repos, arranged with whoever operates your deployment — never self-serve). See Plans, usage & your account.

Plan band

Which repo-count band a paid org is on — Starter, Growth, or Scale (25 / 100 / 500 repositories at the launch defaults). The band modulates only your repository cap; the token and operation budgets are the same across all paid bands. It’s tracked separately from the plan tier, so a band value never changes whether your org counts as paid — it only sets how many repos you may keep governed. You switch bands, up or down, through the Stripe customer portal. See Plans, usage & your account.

Retrieval mode

How chat finds the material it answers from: keyword (matches the same words as your question — the Free plan) or semantic (matches the meaning and writes a cited AI answer — the Team plan). See Ask Hekkos & MCP.

Model role

The job an LLM call is doing. The classifier role handles the cheap, high-volume yes/no checks; the writer roles produce user-facing prose — doc sections, gap suggestions, and chat answers. See LLM keys & providers.

Authority tier

How much a document is trusted as a statement of current state: canonical (the document of record), reference (counts as coverage, warnings only), historical (kept for lineage, raises no drift), or ignored (never ingested). See Drift & enforcement.

Suggestion PR

The pull request Hekkos opens when a doc is missing or off-standard, with the fix already written. You review and merge it like any PR — or dismiss it. See Standards & conformance.

Real state

What your code actually contains — the routes, env vars, functions, types, and CLI flags Hekkos extracts by scanning your repos. Docs and chat answers are checked against it.

Trust

The org-wide headline score for how well your docs hold up — Trust = Coverage × Accuracy. It leads Home as the Real-State Trust card — a ring with its Coverage × Accuracy factor meters and a Trust over time trend — and is decomposed again on Insights. Principle and advisory violations are deliberately kept out of it. See Drift & enforcement and Standards & conformance.

Coverage

How much is documented — measured two different ways, so the guides name them distinctly:

• Doc-type coverage — per repo: how many of the doc types your standards expect are actually present. It’s the Coverage column on Home → Repositories.
• Real-State Coverage — org-wide: how much of your extracted real state (routes, env vars, functions, …) is documented at all. It’s one of the bars on Insights, and a factor in Trust.

Drift

When a doc’s claims no longer match the code’s real state. Distinct from a conformance gap (which is about the standard, not the code) — Hekkos never spells drift as a conformance status. See Drift & enforcement.

Standard

What a good document of a given kind should contain — a per-doc-type list of expected sections you define on the Standards page (Standards → Standards). A standard can be set org-wide or scoped to a single initiative or repository. Each standard also carries an enforcement level: Blocking (a missing required doc or section fails the PR merge check), Advisory (checked and suggested, never blocks), or Off (not tracked). See Standards & conformance.

Conformance

How closely a repo’s docs match the standards your org defines — the read side of standards, shown per repo on Home → Repositories (and each repo’s detail drawer). A doc type’s status is conformant, missing/sections missing (what a Blocking level acts on), off-standard (the doc exists but diverged from the standard), stale, or unchecked. See Standards & conformance.

Violations

Findings where your code — not its docs — is at fault, listed on Home → Violations. Two lenses: principle (the code breaks a rule you declared) and advisory (a known-bad practice even when code and docs agree). Distinct from drift, and kept out of the Trust score. See Drift & enforcement.

Policies

Rules checked against your code — the second of Hekkos’s two governance nouns (Standards govern your documents; Policies govern your code). They live on the Policies page (Standards → Policies) and come through two doors into one rule engine:

• Your policies — rules extracted from your own written standards documents (a security policy, an architecture guide, a wiki page). You attach a document at a scope (Organization, Initiative, or Repository), review the extracted rule candidates, and apply only the ones you choose.
• Library — a catalogue of ready-made code checks (weak crypto, an unguarded tenant route, plaintext http://) you turn on without authoring anything. It’s the Library sub-view of the Policies page (the catalogue formerly shown as a separate Principles tab).

Every policy rule starts advisory — it surfaces as a violation but never blocks — until an org admin opts it in; a deterministic rule can then be set Blocking to gate a merge. See Policies.

Initiative (project)

An admin-assigned set of repositories — a department’s platform, a product line — shown on the Projects page as a “project”. A repository can belong to several initiatives, or to none (it then sits in the Not in a project bucket). Standards, policies, and documents attached to an initiative apply to every repository in it. See what applies here.

What applies here

The rule Hekkos uses to decide what governs any given repository: it’s judged against the union of everything attached at the org, at every initiative it belongs to, and at the repo itself (org ∪ initiatives ∪ repo). Every applied rule, document, and required standard is tagged with an origin — Org, an Initiative, or This repo — with a Manage at ⟨level⟩ link that jumps to where the requirement is set. When the same rule is attached at more than one scope the effective view collapses it to one row, and the stricter severity wins — a laxer scope can never soften a stricter one. Open a repository on the Repositories page to see its full “what applies here” panel. See Policies.

Waiver

A per-repo, per-doc-type “not applicable” — a repo that legitimately doesn’t need a doc type (e.g. no public API → no API doc). A waived doc type drops out of the conformance score and is never blocked by a Blocking level. Set by an admin from a repo’s conformance detail. See Standards & conformance.