docs: end-user artifact verification guide

[ld-singh]

Summary

Add a consumer-facing guide, docs/user/artifact-verification.md, covering how to verify aicr artifacts (deployment bundles and recipe-evidence bundles) across public-trust, KMS-key/PEM, and offline deployment shapes.

Motivation / Context

The V1 acceptance bar calls for a documented verification path that works in air-gapped, private, and public-trust deployments. Verification knowledge was scattered across aicr verify help and signing-side docs; this consolidates it into one end-user guide with copy-pasteable commands.

Fixes: #1157
Related: #1149, #1153, #1154

Type of Change

• Documentation update

Component(s) Affected

• Docs/examples (docs/, examples/)

Implementation Notes

• New page docs/user/artifact-verification.md: what-can-be-verified table, trust levels, public-trust verification, min-trust enforcement, KMS-key and local-PEM verification, offline/air-gapped considerations, recipe-evidence verification, JSON-for-CI gating, and troubleshooting.
• Not-yet-shipped paths (private Sigstore trust root, full tlog-free offline) are documented as unsupported with links to the tracking issues feat(verify): private Sigstore trust root for bundle verification #1153 / feat(verify): offline / air-gapped verification (skip tlog) #1154.
• Registered the page in the Fern sidebar (docs/index.yml) and the user-section index (docs/user/index.md).
• .claude/skills/creating-slide-decks/skeleton.html gains the standard license header (added automatically by make license; required for a clean gate).

Testing

make qualify

make qualify passes: unit tests (race + coverage), lint (Go/YAML/license/agents-sync/docs-filenames/docs-mdx/bom-pinning), 22/22 e2e chainsaw tests, and vulnerability scan. Doc anchors verified against cli-reference.md and internal headings.

Risk Assessment

• Low — Documentation only plus an auto-generated license header; trivially reversible.

Rollout notes: N/A

Checklist

• Tests pass locally (make test with -race)
• Linter passes (make lint)
• I did not skip/disable tests to make CI green
• I added/updated tests for new functionality (N/A — docs only)
• I updated docs if user-facing behavior changed
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

Welcome to AICR, @ld-singh! Thanks for your first pull request.

Before review, please ensure:

• All commits are signed off per the DCO
• CI checks pass (tests, lint, security scan)
• The PR description explains the why behind your changes

A maintainer will review this soon.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 1925a133-689f-4340-a450-83f742af648d

📥 Commits

Reviewing files that changed from the base of the PR and between 24f29df and fb07ef0.

📒 Files selected for processing (3)

• docs/index.yml
• docs/user/artifact-verification.md
• docs/user/index.md

---

📝 Walkthrough

Walkthrough

A new end-user documentation guide docs/user/artifact-verification.md (242 lines) is added, covering how to verify aicr-produced artifacts. The guide documents verification scope (deployment bundles, recipe-evidence bundles, embedded recipe catalog), trust-level semantics, public-trust verification modes (checksum, bundle attestation, binary attestation provenance), KMS-key and local PEM key verification, offline/air-gapped constraints, recipe evidence verification via aicr evidence verify, CI JSON output with exit-code mapping, and troubleshooting steps. The new page is registered in docs/index.yml navigation and added to the documents table in docs/user/index.md.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: end-user artifact verification guide' accurately and concisely summarizes the main change: adding a new consumer-facing documentation guide for artifact verification.
Description check	✅ Passed	The PR description is comprehensive and directly related to the changeset, explaining the motivation, implementation, testing, and risk assessment for the new artifact verification documentation.
Linked Issues check	✅ Passed	The PR fully addresses issue #1157 by delivering a consolidated end-user artifact verification guide covering public-trust, KMS-key, and offline verification scenarios as required by the V1 acceptance bar.
Out of Scope Changes check	✅ Passed	The PR appropriately stays within scope: new artifact verification documentation (docs/user/artifact-verification.md), sidebar registration (docs/index.yml), index update (docs/user/index.md), and an auto-generated license header, all directly supporting issue #1157.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mchmarny]

Welcome to AICR, @ld-singh — this is exactly the consolidation the verification docs needed. The trust level table with explicit ordering and the "max auto-detects" explanation are particularly useful; that model is non-obvious from the CLI help alone.

All four anchor links (#aicr-verify, #aicr-evidence-verify, #aicr-trust-update, #aicr-recipe-verify-catalog) check out against cli-reference.md. The offline/air-gapped section correctly reflects the two unsupported paths and links the tracking issues. One inline concern on the JSON-for-CI case statement — the pipeline form is fragile under set -o pipefail which is common in CI; see the comment.

Three mechanics items before merge:

• CI hasn't run. This is a fork PR, so only labeling workflows fired — the test/lint/lychee anchor-check suite needs a maintainer to approve the workflow run.
• Branch is behind main. Rebase + squash + sign needed.
• Missing theme/* label. theme/supply-chain fits here.

[ArangoGutierrez]

Welcome, @ld-singh — really nice first contribution. The trust-level table and the honest air-gapped / private-Sigstore limitations make this genuinely useful, and the verification flows are correct. I checked the links (CI has not run yet): the three tracking issues (#1154, #1149, #1153) and all four cli-reference.md anchors resolve.

No objection to merging as-is and handling the set -o pipefail nit from @mchmarny's comment in a follow-up — that example fails closed (it aborts rather than passing an invalid bundle through), so deferring it is safe. Tracked in #1364 so it does not get lost.

Two notes, neither blocking the content: this is an advisory approval — docs/** is owned by aicr-write, so it does not satisfy the code-owner gate (an aicr-write member still needs to approve). And the fork CI (test / lint / lychee / docs build) should run green before merge, since lychee is the only anchor-link net.

[mchmarny]

Thanks for this, @ld-singh! Before it can merge, the commit-signing gate needs all commits to be cryptographically signed (-S), and one commit here is currently unsigned:

• f76a5e2c — docs: add end-user artifact verification guide → unsigned

(The merge commit 8def53c0 is already signed.)

AICR uses cryptographic signing to satisfy DCO — the project doesn't use Signed-off-by sign-off, so the -S signature is what the check looks for. Here's how to fix it.

1. Set up signing (one-time, skip if already configured)

SSH signing is the simplest path if you already push over SSH:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub   # your public key
git config --global commit.gpgsign true

Then add that same key as a Signing key under GitHub → Settings → SSH and GPG keys (a signing key is a separate entry from an auth key, even if it's the same key).

Prefer GPG?

gpg --quick-gen-key "Your Name <your@email>"   # only if you don't have a key yet
git config --global user.signingkey <KEY_ID>
git config --global commit.gpgsign true
gpg --armor --export <KEY_ID>                   # paste into GitHub → GPG keys

2. Re-sign the commit and push

Your branch has a merge commit sitting on top of the unsigned one, so the cleanest fix is to rebase onto main (this also drops the merge commit) and sign every replayed commit in one shot:

git fetch origin
git rebase --exec 'git commit --amend --no-edit -S' origin/main
git push --force-with-lease

If you'd rather sign just the single commit interactively:

git rebase -i origin/main         # mark f76a5e2c as 'edit'
git commit --amend --no-edit -S
git rebase --continue
git push --force-with-lease

3. Verify before pushing

git log --show-signature -1

You should see a Good signature line. After the push, GitHub will show Verified next to the commit and the signing check should go green.

Happy to help if you hit any snags with the signing setup.

[coderabbitai]

♻️ Duplicate comments (1)

docs/user/artifact-verification.md (1)

208-214: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Fix shell pipeline pattern that breaks with set -o pipefail (duplicate of past feedback).

The command substitution using a pipeline with aicr evidence verify will fail in scripts with set -o pipefail enabled (common in CI). When the command exits non-zero, the pipeline status propagates and aborts the script before the case statement runs. Write to a file first and read from it instead:

-case "$(aicr evidence verify recipes/evidence/<recipe>.yaml --format json | jq '.exit')" in
+aicr evidence verify recipes/evidence/<recipe>.yaml --format json -o result.json || true
+case "$(jq '.exit' result.json)" in

The || true absorbs the non-zero exit so the script continues, and jq reads from the file rather than a potentially-disrupted pipe.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/user/artifact-verification.md` around lines 208 - 214, The shell
pipeline in the command substitution using `aicr evidence verify
recipes/evidence/<recipe>.yaml --format json | jq '.exit'` will break when `set
-o pipefail` is enabled because a non-zero exit from the command propagates
through the pipeline and aborts the script before the case statement executes.
Fix this by writing the output of `aicr evidence verify` to a temporary file
with `|| true` appended to absorb non-zero exit codes, then read from that file
with `jq '.exit'` instead of relying on the pipe. This ensures the script
continues execution regardless of the aicr command's exit status.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@docs/user/artifact-verification.md`:
- Around line 208-214: The shell pipeline in the command substitution using
`aicr evidence verify recipes/evidence/<recipe>.yaml --format json | jq '.exit'`
will break when `set -o pipefail` is enabled because a non-zero exit from the
command propagates through the pipeline and aborts the script before the case
statement executes. Fix this by writing the output of `aicr evidence verify` to
a temporary file with `|| true` appended to absorb non-zero exit codes, then
read from that file with `jq '.exit'` instead of relying on the pipe. This
ensures the script continues execution regardless of the aicr command's exit
status.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: bcb7f159-c9c4-43a2-99d1-4660a028cdf0

📥 Commits

Reviewing files that changed from the base of the PR and between f76a5e2 and 24f29df.

📒 Files selected for processing (3)

• docs/index.yml
• docs/user/artifact-verification.md
• docs/user/index.md

[ld-singh]

Thanks for the thorough review and the warm welcome, @mchmarny @ArangoGutierrez. Much appreciated for a first contribution!

I have re-signed the commit and force-pushed: the branch is now a single commit (24f29dfc), cryptographically signed and showing Verified. The original signature got stripped when I rebased to resolve the docs/user/index.md conflict, so I have since set commit.gpgsign true to prevent a recurrence. I also rebased onto the latest main while I was at it, which dropped the stray merge commit.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-docs-artifact-verification.docs.buildwithfern.com/aicr