> ## Documentation Index
> Fetch the complete documentation index at: https://npupko.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Hibi and Record Your First Code-Anchored Claim

> Install Hibi, record your first claim anchored to real source code, run a drift check, and read your first verdict — all in a few commands.

You're about to edit `src/auth.ts`. Does any doc ride on it? `hibi query --path
src/auth.ts` lists the two claims — one in `README.md`, one in `CLAUDE.md` — that
both anchor to the 30-minute token TTL you're about to touch. You change the
constant, run `hibi diff --since origin/main`, and Hibi tells you exactly which
two sentences you just broke — and hands you the command to fix each. That is the
whole point: docs that flag themselves the moment the code beneath them moves.

Hibi tracks **claims**: sentences in your docs or AI-agent instructions that
assert how the code behaves. You anchor each claim to the code that backs it, and
`hibi check` flags the claim whenever either side drifts, so no reader, and no
agent, acts on a page that has fallen out of sync with the source.

This page takes you from nothing to a checked claim. The whole loop is three
verbs: **record** a claim, **check** it, and read the verdict. A flag is a request
to **re-verify**, not a claim that the doc is wrong.

## Install

Hibi ships as a single self-contained executable, with no runtime to install. You
can also add it to a Bun project from npm.

<CodeGroup>
  ```sh Prebuilt binary theme={null}
  # Single-file executable, no runtime needed
  curl -fsSL https://raw.githubusercontent.com/npupko/hibi/main/scripts/install.sh | sh
  ```

  ```sh Bun theme={null}
  # In a Bun/JS project
  bun add @npupko/hibi
  ```
</CodeGroup>

<Note>
  The npm package is **Bun-targeted**: it runs under [Bun](https://bun.sh). For
  a zero-runtime install on any machine, use the prebuilt binary above.
</Note>

## Record and check a claim

<Steps>
  <Step title="Initialize the store">
    `hibi init` creates a committed `.claims/` directory beside your docs, with a
    per-repo banner nonce. Each claim becomes its own file in here, so merges stay
    scoped: there is no monolithic lockfile.

    ```sh theme={null}
    hibi init
    ```
  </Step>

  <Step title="Record a claim, anchored to the code that backs it">
    Hibi is **span-first**: you point at the documented sentence and at the code
    it describes, and the doc span supplies the claim text. The example below
    binds a line of your README to the constant that enforces it.

    ```sh theme={null}
    hibi record \
      --doc README.md --doc-quote "Retries are capped at 5 attempts" \
      --code-file src/retry.ts --code-quote "MAX_ATTEMPTS = 5" \
      --trust verified --ref PR-1024 --owner alice
    ```

    Because the code side mentions the literal `5`, changing `MAX_ATTEMPTS` to
    `50` later will trip this claim even if nothing else in the file moves.
  </Step>

  <Step title="Verify every claim">
    `hibi check` re-finds each claim's anchors in your current files and computes
    a verdict. Add `--write` to stamp a status banner into any doc whose claims
    are now suspect, so the staleness is visible in the file itself.

    ```sh theme={null}
    hibi check              # verify every claim
    hibi check --write      # verify, and stamp status banners into affected docs
    ```
  </Step>
</Steps>

A verdict reads like `doc:unchanged · code:changed · behavior:at-risk`: one
short, side-prefixed status per axis. `hibi check` exits `0` when everything is
clean, `2` when an enforced claim has a gating problem (changed, orphaned, or
ambiguous on either side, expired, or refuted), and `3` for a re-anchorable
warning (moved or at-risk). A `moved` claim never fails the build on its own.

## Everyday commands

```sh theme={null}
hibi diff --since origin/main     # what did this change invalidate?
hibi query --path src/retry.ts    # before editing: which claims cover this file?
hibi list --state gating          # triage: one lean row per drifting claim
hibi coverage --doc README.md     # which blocks of a doc are backed by a claim vs uncovered?
hibi reanchor <claim-id> --doc-quote "…" --code-file src/retry.ts  # re-resolve a drifted claim
hibi retire <claim-id>            # withdraw a single obsolete claim
hibi relocate --from docs/old.md --to docs/merged.md  # re-home every claim onto the merged doc
hibi doctor                       # store-health report (informational; always exits 0)
hibi status --doc README.md       # is this one doc still current?
```

`hibi status --doc <path>` is the read-time gate an agent runs before it trusts a
doc; `hibi diff --since <ref>` is the write-time loop that reports what a change
invalidated. Both exit `2` on a gating problem and `3` on an advisory warning, so
they drop straight into CI or a git hook.

Every drift verdict comes with a **remediation menu** — a `recommended` next step
and a list of actions, each with a ready-to-run command where Hibi can perform the
fix (`hibi reanchor asrt_…`, `hibi retire asrt_…`). You rarely have to figure out
the fix yourself; the verdict hands it to you.

<Note>
  Output is TTY-aware: a rich human view in a terminal, compact JSON when piped or
  in CI. Pass `--json` to force the machine contract, `--pretty` to force the human
  view. The JSON is **concise by default** — add `--explain` for the full evidence
  tail, or `--no-hints` to drop the remediation menu.
</Note>

<Tip>
  See the [CLI reference](/cli-reference) for every command, flag, exit code, and
  strictness level (`--fail-on gating|warn|tamper|never`).
</Tip>

<Card title="How it works" icon="diagram-project" href="/concepts">
  Claims, redundant anchors, the doc-first resolution flow, and how verdicts are
  graded, deterministically, with no model in the check loop.
</Card>