Check an assistant setup guide before authorizing its actions.
GuideCheck reports the exact guide hash, achieved conformance level, and blocking findings without executing the guide.
Here is a guide rejected because an action invokes repository code outside the bounded instruction surface. This is its only action block:
[action]
id: check-version
class: code-executing
approval: required
command: npm --prefix subdir run check
runner: argv
cwd: .
notes: Prints local version information only.
[/action]
This is the local reference verifier's compact report for that guide, with a requested gate of Level 3:
Verifier: guidecheck-reference-local 2.0.0
Guide: fixtures/profiles/2.0.0/corrected-bound-unpinned/guide.txt
Profile: 2.0.0 (declared 2.0.0)
Content policy: corrected-content-1
Anchor policy: 1.0.0-strict
Qualifying anchors: 0
Level: 2
SHA-256: 980af0ed73303120f7a9a5d643630b1b02e21579d1578c733174c1445518545c
Blocking findings: 2
Warnings: 0
Hash pinned: no
Proceed? no
Blocking finding action.exec-unbounded: the action asks for approval, but nothing bounds the repository code it runs. Achieved Level 2 against a requested Level 3; the verifier exited 1.
fixtures/profiles/2.0.0/corrected-bound-unpinned/guide.txt. Reproduce it with the README local trial; complete reports are in the trial evidence file.Conformance checks do not establish that the instructions are safe, the publisher is trustworthy, or a runtime will execute only approved instructions.
The reason for the check is the trust boundary. AI setup guides reach assistants through HTML, rendered Markdown, PDFs, and copied terminal output. Those surfaces can hide text from a human while feeding it to a model. GuideCheck is the open standard that turns that trust boundary into one plain-text document: small enough, strict enough, and verifiable enough to review before delegated authority acts.
Humans approve one surface. Agents may execute another.
A presentation layer sits between a guide's author and the assistant that acts on it. HTML, rendered Markdown, PDFs, documentation sites, copied issue comments, terminal output, screenshots — each can transform, append to, or conceal content on its way to the model. The human reviews the rendered output. The model ingests the raw source. Nothing guarantees those are the same document.
Invisible to the eye
Hidden HTML comments, offscreen CSS, zero-height elements, white-on-white text, script-inserted content. Rendered to nothing for the human; delivered as plain instructions to the model.
Invisible in the bytes
Bidi controls, zero-width characters, and homoglyphs that read one way to a person and another to a tokenizer. Terminal escape sequences that rewrite what a copied command appears to say.
Buried in plain sight
A directive deep in a long guide the reviewer skimmed, or an instruction block below the fold no human scrolled to. Technically visible. Genuinely reviewed, no.
Why this is not cosmetic
A tool-using assistant has real blast radius. It runs shell commands, edits files, installs packages, and calls APIs with the operator's credentials. A hidden instruction is not a rendering quirk — it is an unreviewed command executed under delegated authority. The concrete outcomes are a credential exposed, a destructive command run, a malicious dependency installed, or safeguards disabled while the human believed they had read and approved the entire guide.
How GuideCheck repairs the trust boundary
GuideCheck removes the presentation layer from agent instructions. The profile describes one artifact — a plain-text file named assistant-guide.txt, served at /.well-known/assistant-guide.txt — carrying assistant-facing install, implementation, remediation, migration, and operational instructions for a single bounded task. Three properties support review integrity: keeping the instructions humans approve the same as the instructions agents execute.
Bounded, so you can read all of it
A strict ASCII byte profile and an 8 KiB size cap. No hidden bytes, no homoglyphs, no offscreen text — and short enough to read in full in one sitting, not skim.
Structured, so nothing is buried
Instructions live in explicit [action] blocks with declared classes, approval gates, and command restrictions. A conforming assistant executes blocks, never loose prose — there is no below the fold. Mechanical enforcement of that contract requires a Level 5 runtime.
Verifiable, so a swap is detectable
A sidecar manifest and cross-channel hash publication let a guide's identity be confirmed without trusting any single hosted service.
Conformance is not safety
Conformance to this profile, at any level, does not mean a guide is safe to follow, that the publisher is trustworthy, or that an assistant may skip the security practices a competent operator would already apply. A verifier confirms form. The human confirms meaning. The standard is one layer in a defense stack — it does not replace sandboxing, least privilege, or human approval.
Six conformance levels
The conformance ladder is additive and honest. Each level states exactly what it has checked and what it has not. Higher levels add structure and provenance — never a safety claim.
| Level | What it establishes |
|---|---|
| 0 | Instructions are only available through surfaces that can hide or transform text. |
| 1 | A plain-text guide exists, is reachable, and carries the compact verification instruction. |
| 2 | Strict ASCII byte profile, size limits, and no disallowed constructs. |
| 3 | Assistant safety contract, all required sections, and explicit approval gates. |
| 4 | Verifiable provenance: a sidecar manifest and a cross-channel hash on an independent control plane. |
| 5 | A guide plus a conformant assistant runtime that mechanically enforces the execution contract. |
Level 4 adds verifiable provenance but not a safety claim. Level 5 is explicitly a guide-plus-runtime claim, not a guide-only claim, because runtime behavior cannot be asserted by a file.
Adopt the profile
Publishing a conformant guide is plain-text work. Write the artifact, serve it at the well-known path, and check it against the verifier conformance profile. No registry, no account, no central oracle. The adoption guide gives a level-by-level path and a guide-author checklist.
For agent ecosystems, the same pattern applies at protocol boundaries. MCP server authors can use GuideCheck for install, tool, resource, and approval review; A2A implementers can use it for delegated-task guidance and returned artifacts that would otherwise become executable instructions. These are integration patterns, not conformance dependencies.
Existing AGENTS.md, CLAUDE.md, README, or skill files can be scanned with python3 scripts/guidecheck_scan.py for supported hidden-instruction channels. The scanner does not award a conformance level, and a scan with no findings does not mean the file is safe. See scanning an instruction file.
assistant-guide.txt
[assistant-guide-metadata] identifier: assistant-guide profile: human-verifiable-assistant-guide profile-version: 0.7.1 guide-version: 0.7.1 applies-to: example-project 1.x canonical-url: https://example.com/.well-known/assistant-guide.txt source-path: /.well-known/assistant-guide.txt last-reviewed: 2026-05-22 status: active recommended-verifier: https://guidecheck.org/verify [/assistant-guide-metadata]
Strict ASCII, 8 KiB maximum, plain text only — no HTML, no Markdown, no hidden bytes.
This example keeps the supported legacy 0.7.1 declaration, as GuideCheck's own guide does. To adopt 2.0.0, declare profile-version: 2.0.0 in both the guide and its manifest; see the adoption guide.
Serve and verify
# Serve the artifact at the well-known path GET /.well-known/assistant-guide.txt # Run a conformant verifier against the URL. # Output reports: guide SHA-256, achieved # level, and any blocking findings. # A conformance claim is valid only when # backed by verifier output, guide hash, # achieved level, and findings.
Anyone may build a conformant verifier. The fixture suite exists so independent implementations can show they agree. Today the only implementations are GuideCheck's own reference verifiers, and the hosted one is a preview.
Verify a guide
GuideCheck publishes a primary verifier for usability — never as the only authoritative verifier and never as a root of trust. It reports what it checked and what it did not. Guide files score up to Level 4 of 4; Level 5 is a separate runtime enforcement claim. The hosted verifier scores Levels 1 to 3: it reports a guide's declared Level 4 anchor evidence but does not verify it, so it does not award Level 4. Optional agent and expected-level fields help identify compatibility gaps without storing full submitted URLs, prompts, model responses, IP addresses, or stable visitor identifiers as product telemetry.
The hosted verifier is a preview. The local reference CLI evaluates Levels 1-3 from a source checkout without executing the guide. Under a 1.0.0 or 2.0.0 profile, a guide that declares manifest-url reports the blocking finding anchor.independent.missing locally, because Level 4 needs fetched evidence. A captured failed verification and a step-by-step trial are in the README trial.