Getting started

For org admins setting up Hekkos.

This guide takes you from signing in to your first scan — the point where Hekkos has extracted your repos’ real state and starts holding the docs to it. It assumes Hekkos is already running (if you’re standing it up yourself, start with the operator material: self-hosted install runbook).

1. Sign in

Go to your Hekkos URL and click Continue with GitHub. Hekkos uses your GitHub identity — it never asks for a password.

2. Create your org

If your GitHub account doesn’t belong to any Hekkos org yet, you land on Create org. The form is just a name — submit it and you’re the org’s admin. Membership starts in manual mode (invite links), so nobody joins until you say so; you can switch to mirroring later, in the wizard’s Team step or in Settings.

Not the person setting things up? The same screen has a Joining an existing team? panel: it names any org you have a pending invite to, and opening an invite link and signing in adds you automatically — see Your team.

3. The setup wizard

Creating the org drops you into a short setup wizard: Connect → Preferences → Team → Confirm. Each step asks one decision, everything has a safe default, and nothing except the Team step’s mirroring choice takes effect until you hit Confirm at the end.

Connect — now or later?

The first decision is whether to connect your code now. Connecting installs the Hekkos GitHub App (a separate authorization from the login you just did): the wizard sends you to GitHub to confirm you administer the org you’re connecting, then brings you back, and scanning starts immediately and keeps running in the background while you finish the rest of setup — the scan is read-only, nothing opens a PR without your approval, and you can uninstall the app from GitHub anytime. If you’ve already installed the app on GitHub, this same step finds it and links it — no reinstall needed. Installing the app needs GitHub organization-owner rights: if you’re not an owner, GitHub asks an owner to approve it, so you don’t dead-end at the install wall. Continue without connecting is the off-ramp — it defers connecting; everything else in the wizard still works, you just won’t have scan results until you come back to this step (the Confirm step offers a jump back), and scanning begins once an owner approves the install.

Caution

No source appears after connecting? First, on the Settings → Connections page use Link it now — the link flow finds an app you’ve already installed and binds it, no reinstall needed. If connecting never returns from GitHub at all, your deployment’s GitHub App is likely missing its OAuth callback URL (or its client id / secret) — a deployment-side fix, so ask whoever operates your deployment; the operator material is GitHub App configuration.

After connecting, the step shows live scan counts and optionally asks your org’s primary languages — answer or ignore, it only helps tailor suggestions.

Preferences — keep the defaults or customize?

Preferences shows its settled defaults as plain sentences: which document types your standard covers (README, CONTRIBUTING, SECURITY, CODEOWNERS, all treated as Advisory) and the rollout pace for suggestion PRs (pilot first: 5 repos open now, the rest open automatically after 48h so you can sanity-check the pilot). Each doc type’s enforcement is one of Blocking (a gap fails the PR merge check), Advisory (checked and suggested, never blocks), or Off (not tracked) — the same three levels the Standards page uses. The decision is simply whether those defaults fit — if they do, move on; if not, each row has a Customize expander, and orgs offered bring-your-own-key get a third, optional row for adding their own AI provider key (see LLM keys).

Team — invite links or mirroring?

This step asks how people join your org. Manual (the default) works with invite links and is the only option every sign-in method supports; you can generate invite links right here in the step. GitHub org (mirrored) syncs members and roles from your GitHub org as each person signs in — it’s only selectable once a GitHub source is connected, and it’s the one wizard choice that applies immediately, after its own explicit confirmation (which spells out the consequences). SSO groups (mirrored) is configured in Settings after setup. The full detail, including roles and invite-link mechanics, is in Your team.

Confirm — the review pass

Confirm reads back exactly what will be saved — rollout pace, standards, team mode, AI model choice if offered — with an Edit jump next to each line. Confirming saves your choices and lets suggestion PRs open at your chosen pace; until you confirm, nothing opens a PR.

Leaving early is safe. From Preferences onward the footer offers Finish with defaults, and the Connect step has a quieter Skip for now — both finish setup the same way, saving the defaults you’ve seen (including the safe pilot pace) without touching team setup. Everything the wizard configures can be changed later in Settings.

4. Where you land

Finishing the wizard lands you on Home — the consolidated place to act on your org’s documentation. Leading the page is your worklist — a cross-repo triage bar that counts what’s waiting for you in three verbs: Fix (doc suggestions ready to review), Review (drift to acknowledge), and Gap (a missing or failing doc). It’s the same Fix / Review / Gap language the per-repo findings table on Repositories uses, so the number you see up top is your whole queue across every repo; click a verb to go act on it. When all three are zero it collapses to a single “all caught up” line. Below it is a grid of focus cards:

• Real-State Trust — your org-wide trust score, shown as a ring alongside the Coverage × Accuracy factor meters it decomposes into (with an inline = Trust formula) and a single open-issues-by-severity bar. On a brand-new org it reads a neutral — (“adopt a standard to measure”) rather than 0%: Trust is Coverage × Accuracy, so it only becomes a real score once you’ve adopted a standard and a scan has something to measure against.
• Needs attention — the repos with drift, a conformance gap, a scan error, or open violations, ranked worst-first.
• Ready to merge — doc-improvement suggestions (queued + open) ready to review.

Below those cards, a full-width Trust over time trend charts your trust score across scans (it appears once you have a couple of scans to connect), and a Suggestion outcomes panel shows your doc-suggestion acceptance rate (last 30 days) next to the top reasons suggestions get dismissed.

On Home, an admin-only Setup checklist tracks the five things a working org needs: GitHub connected, your first scan results, a doc standard defined, a code principle turned on, your team invited. The scan step ticks as soon as a scan has produced results — including a repo whose suggestion PR is still held by your rollout pace (the scan ran; only the PR is waiting). While setup is incomplete the checklist collapses to a single line that surfaces your next step with its own action — a Connect GitHub button, live scan status, or a link to choose a standard, turn on a principle, or invite your team. When the last item lands you get a brief “you’re all set” line, then the checklist disappears. From then on, opening Hekkos takes you straight to Chat whenever your org has scanned content to answer from — and to Home otherwise.

Further down, two expandable sections carry the full detail, both visible to every member (not just admins):

• Repositories — one row per repo showing its drift severity, conformance Gaps, open Violations, and doc-type Coverage; a repo that carries acknowledged or resolved drift also notes those counts under its severity (e.g. 2 acked · 1 resolved). Click a row for a detail drawer with its per-doc-type conformance and a Fix this action. This is where you see how each repo measures up — see Standards & conformance.

• Suggestions — your org’s own doc-improvement suggestions:

  • Queued — a fix is composed and will open automatically under your rollout pace; the card shows when it’s due to open, and — if the rollout is holding it — why. Nothing to do; it opens itself.
  • Open — a suggestion PR is ready to review on GitHub.

  If Hekkos also reviewed incoming pull requests for documentation impact, those appear in a separate “Open PRs flagged for doc impact” section below, shown only when there are any.

Org-wide principle and advisory findings about your code aren’t a separate tab — they fold into the Needs attention card. See Drift & enforcement.

Home is where you act; Insights (below) is where you oversee.

Finding your way around — the breadcrumb and Projects

Two pieces of chrome keep the org → initiative → repo hierarchy visible everywhere:

• The global breadcrumb across the top of every page shows where you are — Acme ▸ Payments ▸ acme/checkout — and each segment is a switcher, so you can hop up to the org or across to another scope from anywhere.
• Projects (in the sidebar) is the map of your org: every initiative (“project”) with the repositories under it, plus a Not in a project bucket for loose repos. An initiative is an admin-assigned set of repositories — a department’s platform, a product line — and a repo can belong to several. Admins create, rename, assign repos to, and delete projects here. A small dot marks any node that needs attention; it’s a map, not a scoreboard.

The nav item that lists your repositories is Repositories (it was previously Sources). Opening a repo there shows one unified panel of everything that governs it — see What applies to a repo.

(This structure is the default; governance can be rolled back via GOVERNANCE_V2_ENABLED=false.)

5. Insights — how the program is landing

Where Home is for acting, Insights is the read-only oversight view — “how the program is landing” across your whole org, visible to every member. It gathers:

• Real-State Trust, decomposed into Trust = Coverage × Accuracy, with a surface inventory (routes, env vars, …) and your open-drift posture.
• A Conformance rollup — aggregate counts of conformant / off-standard / missing doc types across every repo.
• A Violations posture — principle vs advisory findings (which don’t affect Trust).
• Acceptance by document type (all-time) and the reasons suggestions get dismissed — so you can see which docs your team actually accepts.

Nothing here is an action; it’s the scoreboard you check to see whether the effort on Home is paying off. (“Coverage” appears in two senses — the per-repo doc-type coverage column on Home, and the org-wide, entity-based Coverage row here on Insights, one of the three factors behind Real-State Trust; see Concepts.)

6. What happens next

• Where Hekkos finds a documentation gap, it opens a suggestion PR on that repo with a concrete fix — surfaced on Home (the Suggestions section) as it opens. Review them like any PR.
• Ask questions about your codebase in Chat.
• Tune what “good documentation” means for your org under Standards, and draft/preview docs interactively in Doc Studio (no PR until you’re happy).
• Turn your org’s written standards into conformance rules on Policies — see Policies.
• Prefer French? The dashboard is bilingual — a language toggle (EN / FR) in the sidebar footer switches the whole interface to French-Canadian and remembers your choice. The marketing site is bilingual too (at /fr/).

Where next

• Your team — membership modes, invite links, and roles.
• Standards & conformance — adopt or customize your doc standard (the Standards page), scope it to an initiative or repo, and review suggestion PRs.
• Policies — turn your written standards documents into conformance rules checked against your code.
• Ask Hekkos — chat over your docs, with cited answers.
• Plans, usage & your account — Free chat uses keyword search; Team unlocks semantic (AI-answer) chat. What each plan includes, and how to upgrade, export, or delete your org.