> ## 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.
# Status Banners: Stamp Staleness Warnings Into Your Docs
> Hibi writes a staleness banner directly into the top of any stale document so readers and AI agents can never miss it, even reading the raw file.
A **status banner** is a block of plain, visible text that Hibi writes into the
top of a stale document. It exists for one reason: a naive consumer (a teammate
skimming a README, or an AI agent reading `CLAUDE.md` before it edits) reads the
raw file and trusts it. If the only signal that a doc has drifted lives in CI logs
or a JSON report, that consumer never sees it. So the status has to be visible
**in the file**, not only in a side channel.
A banner is the in-artifact form of a flag. Like every flag, it is a request to
**re-verify**, not a claim that the doc is wrong.
Stamping is opt-in: a banner is written only when you pass `--write` to `check`
or `diff`, and only an **enforced** claim (a confirmed, well-anchored one) can
stamp the strong banner. A suggested claim never stamps and never gates.
## What a banner looks like
A banner is delimited by two **sentinel** lines (fixed markers Hibi owns) with
the suspect claims listed between them. In a Markdown file it reads like this:
```markdown theme={null}
> [!WARNING]
> STALE DOCUMENT — 2 suspect claim(s) — re-verify before trusting.
>
> [code:changed] (retry-backoff) Failed uploads retry up to 5 times with backoff.
> [doc:orphaned] (sort-order) Results are returned sorted ascending by score.
```
Everything between the two sentinels is engine-owned. Everything outside them is
your prose, untouched.
* **`HIBI:BEGIN v1 `** and **`HIBI:END v1 sha=<8-hex>`**: the
sentinels. They are line-anchored and version-tagged (`v1`). `` is a
per-repo value; `sha=<8-hex>` is a checksum over the body. Both are explained
below.
* **Headline**: the default is `STALE DOCUMENT — N suspect claim(s) — re-verify
before trusting.`, where `N` is the count of suspect propositions.
* **Body lines**: one per suspect proposition, **sorted by id**, in the form
`[STATUS] (id) text`. The status is side-tagged (`code:changed`,
`doc:orphaned`) and can carry a lifecycle marker (`superseded`, `amended`,
`retracted`). The text is the documented sentence.
There are **no timestamps and no run-ids** in a banner. Hibi is
deterministic (the same working tree must produce the same banner bytes), and a
timestamp would break that.
## The four guarantees
A banner has to survive being committed, re-read, and re-stamped without ever
corrupting the file or firing on the wrong one. Four properties make that safe.
`init` generates a random **nonce** for the repository and stores it in the
claim store config. Every sentinel carries it (`HIBI:BEGIN v1 7f3a9c2e`). A
document that only *quotes* the banner format (for instance, this very page)
uses a different (or no) nonce, so Hibi never mistakes it for a real banner
and never overwrites it.
The END sentinel ends with `sha=<8-hex>`: an **FNV-1a (32-bit)** checksum over
the banner body, rendered as 8 hex characters. If someone hand-edits the text
between the sentinels, the checksum no longer matches. Under
`--fail-on tamper`, Hibi refuses to overwrite the tampered region and reports
it; otherwise the recomputed stamp wins and self-heals the banner.
Sentinels are matched on whole lines and carry the `v1` tag. That keeps
detection unambiguous and lets the format evolve without misreading an old
banner as a new one.
All whitespace inside and around the banner region belongs to the engine.
Clearing a banner restores the **exact pre-banner bytes**: removing it leaves
no trailing blank line or stray newline behind.
Because the region between the sentinels is replaced on each write,
stamping is **idempotent**: re-stamping a document whose status hasn't changed
produces no diff (it is byte-stable). Each write resolves to one of four actions:
`insert`, `replace`, `remove`, or `noop`.
## Where the banner goes
The banner is always placed at the **top of the file**, within roughly the first
30 lines. This is not cosmetic. Long inputs suffer from "lost in the middle":
readers and language models attend far less to content buried in the body than to
the start. A warning the agent never reads is no warning at all, and agents are
the consumers Hibi protects.
The one adjustment: if the file opens with a `---` frontmatter fence, the banner
goes **immediately after** that fence so it doesn't break the frontmatter.
Otherwise it goes at the very top, never the middle or the end.
## Comment style per format
Hibi treats docs as text, so the banner adapts its comment syntax to the file's
format. The sentinels and body are wrapped so they read as a comment (or, in
Markdown, as visible prose) rather than corrupting the document.
| Format | Comment style |
| ----------------------------------------- | ------------------ |
| Markdown | `` |
| Python, shell, YAML, TOML | `#` per line |
| TypeScript, JavaScript, Rust, C, Go, Java | `//` per line |
| `.txt` | none (plain lines) |
## Attention-budget files
`CLAUDE.md`, `AGENTS.md`, and editor rule files are loaded into an agent's context
on **every** turn, so their length is a running budget. A multi-line
banner there is waste.
Which files qualify is store configuration: **`StoreConfig.instructionFiles`**
is a list of globs, defaulting to `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and
`.github/copilot-instructions.md`. For a document matching any of them, the
banner body collapses to a **single-line pointer**:
```markdown theme={null}
> STALE — 2 claim(s); run `hibi status --doc CLAUDE.md`
```
Only the body shrinks. The single line is still sentinel-wrapped, still
checksummed in the END sentinel, and still placed at the top of the file; every
guarantee above applies unchanged. The pointer says only that the file is stale
and how to get the detail; the full per-claim breakdown lives in the JSON output
and `hibi status`. The always-loaded instruction file stays lean.
Run `hibi status --doc ` to see the full suspect set for any file: it's
the read-time gate an agent calls before trusting a doc, and the side channel
the single-line pointer refers you to.
## Frontmatter status
For Markdown files that already carry frontmatter, Hibi can also write a
`frontmatterStatus` field alongside the banner. It only does this where
frontmatter already exists, and it **never clobbers an author's own `status`
key**: that field belongs to you.
## Pristine documents
Some documents should never be written to at all: a vendored spec, a
third-party README, a read-only file you track but do not own. Mark these
**pristine** and Hibi never stamps them — no banner, no `frontmatterStatus`,
even under `--write`. A `check --write` over a pristine document leaves its
bytes exactly as they were; its verdicts surface only through the JSON output,
`hibi status`, and exit codes.
A document becomes pristine in either of two ways:
* **Per document** — record it with `hibi record --pristine`.
* **By pattern** — list globs in **`StoreConfig.pristine`**. The globs are
evaluated **at stamp time**, so adding `vendor/**` to the config later
protects documents whose claims were recorded before the glob existed.
The protection story for a pristine document is the read-time gate: a reader or
agent runs `hibi status --doc ` before trusting it, exactly as with any
other file. The verdict just never lives in the artifact itself.
## What the engine writes, and what it doesn't
A banner stamps **status** into a document: which claims are suspect, why, and a
prompt to re-verify. It never edits your prose. Fixing the wording is the
human's or agent's job: Hibi flags, you (or your agent) rewrite, then re-run
`check`. The engine owns the banner region and the lifecycle marks; the prose
between banners is always yours.
A banner means *re-verify*, not *rewrite blindly*. The status tells you the
evidence under a claim moved; confirming whether the documented sentence is
still true is a human or agent decision.
## Where to go next
Which claims may stamp a strong banner, how supersession and remediation
drive the lifecycle marks you see in the body.
Wire `check --write` and the `status` read-time gate into CI, a git hook, or
an agent's pre-edit lookup.