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).

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.

Connecting more than one GitHub org. An org can govern repos across several GitHub organizations. Once one is connected, Settings → Connections shows an Add another GitHub org action — it opens GitHub’s app-install page so you pick the next org, then binds it here. Each connected org appears as its own row, and you can Disconnect any of them (its repos stop scanning; existing history is kept). Disconnecting the last connected GitHub source while membership mirrors a GitHub org breaks member sync, so the confirm warns you first.

After connecting, the step shows live scan counts and optionally asks your org’s primary languages — answer or ignore, it only helps tailor suggestions. The count reads “N of M scanned so far”; if any repo’s scan fails (a permission or access error, say), the step flags that separately — “K repos failed to scan” with a link to Repositories to see why — so a failed scan never hides inside the “still scanning” total.

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 Required (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 Overview — 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 line — but that line is only the green “all caught up” once something has actually been measured (a scan produced results and a standard is adopted). On a brand-new org that hasn’t configured anything yet it reads a neutral “nothing measured yet — adopt a standard” instead, so the page never congratulates you before there’s anything to be caught up on. Below it is a grid of focus cards:

Real-State Trust — your org-wide Trust number, 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, an attestation gap, a scan error, or open violations, ranked worst-first. When it’s empty it distinguishes “No issues detected” (a scan ran and found nothing) from a neutral “Repos not yet scanned” (nothing has been measured yet). A scan-error row offers a Rescan action to admins; members see the error reason with an “ask an admin” hint instead.
Ready to merge — doc-improvement suggestions (queued + open) ready to review. Its green “All clear” fires only once a scan produced results and a standard is adopted (the same honesty gate as the worklist).

Below those cards, a full-width Trust over time trend charts your Trust number 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), a merged tally with its merge rate (are your fix-PRs landing?), and the top reasons suggestions get dismissed. When a project/repo scope is active, these org-wide panels (the Trust ring, the trend, and Suggestion outcomes) are labelled org-wide so their numbers aren’t misread as the selected initiative’s.

On Overview, 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 Overview otherwise.

Further down, two always-visible sections carry the full detail, both shown to every member (not just admins) — no expand/collapse toggle; the cards above scroll you to the matching section:

Repositories — one row per repo showing its drift severity, attestation Gaps, open Violations, and doc-type Coverage, with a link out to the repo on GitHub beside its name; 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 attestation and a Fix this action. This is where you see how each repo measures up — see Standards & attestation.
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.

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

Finding your way around — the header and the Repositories page

A two-tier header keeps both “where you are” answers visible everywhere:

The structural trail (top line) shows your place in the app — Govern ▸ Standards ▸ Policies — so you always know which nav group, page, and tab you’re on. The page and tab are links back up the trail; the group is just a label. It’s on every surface, Repositories included.
The scope chip (below it) shows the org → initiative → repo hierarchy — 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. Off the scope-aware surfaces it collapses to just your org name.
Repositories (in the sidebar) is the single governance surface for your repos and projects — there is no longer a separate Projects or Sources nav item. It’s a three-pane page: a left organizer that lists your repositories grouped by the project they belong to (with a Not in a project bucket for loose repos, and your connected Confluence spaces as their own rows), a center detail pane, and a right Activity rail for the selected repo (the rail starts collapsed to a slim strip on narrower screens like tablets so the detail pane has room — click it to expand). A project (initiative) is an admin-assigned set of repositories — a department’s platform, a product line — and a repo can belong to several. A small binary dot marks any node that needs attention; it’s a map, not a scoreboard.
The sidebar footer carries your identity and the app-wide controls — language, light/dark theme, sign-out, and a Docs link that opens this documentation in a new tab, so guidance is one click away from any page.

Selecting a repo in the organizer opens its detail. It leads with an at-a-glance stat strip — open findings, documentation coverage, and the most common finding type — where clicking the open-findings or finding-type card filters the findings list below to match (an Active filter · Clear chip lets you drop the filter); it’s triage, not a single repo “score”. What governs the repo — policies in force + documents required — is folded just beneath it behind a collapsed Governance context disclosure, so the day-to-day view leads with what needs doing: a Document these first panel ranking the highest-impact undocumented code, then the repo’s findings table. Findings and the ranked items link out to the exact file, doc, or PR on GitHub. A governance drawer button opens the full picture (incl. the policy documents): repo-admins see Edit governance (editable), everyone else sees View governance (the same drawer, read-only) (see What applies to a repo). Selecting a project shows a read-only glance of its member repos, edited from its own drawer; selecting a space shows that Confluence source’s detail.

Admins create a project from the organizer (a small “New project” modal — a name is all it takes), then edit it in a wide right-side drawer that holds the project’s name, its standards + policies, and a Contents area to assign repos and enroll knowledge sources at project scope. Admins also rename, delete, and re-assign from here. Members see the same organizer read-only — a labelled map of how repos are grouped, each node linking to its governance view — with no create/edit/delete controls.

A brand-new org lands on “connect a source,” not an empty project map. Until a GitHub source is connected and repos appear, the organizer shows the connect call-to-action (admins get the connect button; members get an “ask an admin” line) — never a dead “create a project” prompt, since a project with no repos to hold is a dead end.

5. Insights — how the program is landing

Where Overview 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.
An Attestation rollup — aggregate counts of attested / 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 Overview is paying off. (“Coverage” appears in two senses — the per-repo doc-type coverage column on Overview, 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 Overview (the Suggestions section) as it opens. Review them like any PR.
Empty repos are marked “Skipped,” not failed. A granted repo that has no commits yet (a fresh placeholder) has no content to scan, so its first discovery/drift-baseline pass does nothing and shows in the Activity feed as a Skipped “Drift check” with the reason “No files to scan yet” — not the alarming “Resource not found (repo or installation may be gone).” This holds when you re-connect too: re-clicking Connect GitHub re-runs discovery over every currently-granted repo, and any that are still empty are skipped rather than surfaced as failures. Once such a repo has a first commit, the next scan picks it up. (A repo that already has a recorded baseline and then can’t be fetched is treated as a transient error and retried — never silently resolved — so its standing drift PR is never closed by a hiccup.)
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 policy 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 & attestation — adopt or customize your org’s doc standard (the Standards page), let projects and repos add stricter standards for doc types the org doesn’t govern, and review suggestion PRs.
Policies — turn your written standards documents into policy 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.