rivet check of docs

[avrabe]

When a document is created I don't see today an easy way that a human or ai agent can check if this can be seen by rivet

I see rivet serve is called and checked by looking at the website

---

Acceptance / kill-criterion (pinned for the issue-fixing routine)

Fixed when rivet check docs (a new dedicated subcommand) enumerates every candidate path the doc scanner considered and tags each loaded / skipped (<reason>) / excluded (allowlist), supports --format json for mechanical assertions, and exits non-zero under --strict when any candidate is skipped.

Verified on gale's three live skip cases — docs/mcuboot-coverage-analysis.md (no frontmatter), docs/release-plan.md (missing field id), docs/wasm-module-distribution.md (no frontmatter): each must appear in the JSON with its correct reason, and --strict must exit non-zero until those three are either given valid frontmatter or excluded via docs[].exclude.

Scope (single slice, not narrowed): one PR delivering enumerate + per-path reason + --format json + --strict. Rationale: --strict is the part that makes it a CI-gateable oracle (the actual ask — "a check"), and it's trivial once the enumeration exists. A dedicated subcommand (not folding into rivet validate's warning stream) so the status is queryable without a full validation pass and mirrors the existing rivet docs check --coverage --strict oracle pattern.

[avrabe]

Grounded from a live consumer (gale): this friction is real and reproducible — here's what rivet surfaces today and where the actual gap is.

A partial answer already exists — rivet validate reports doc-scan visibility:

warning: rivet doc scanner skipping ./docs/mcuboot-coverage-analysis.md: no YAML frontmatter
warning: rivet doc scanner skipping ./docs/release-plan.md: Schema error: document frontmatter: missing field `id`
warning: rivet doc scanner skipping ./docs/wasm-module-distribution.md: no YAML frontmatter
rivet docs: 0 loaded, 3 skipped (warnings above), 0 excluded by allowlist

So today an agent can check "is my doc seen?" by running validate and looking for the doc path in the skip warnings plus the N loaded / M skipped / K excluded tally — and each line already gives the actionable reason (no frontmatter / missing id) and the docs[].exclude hint.

But the gap you're naming is legitimate: that status is a side-effect buried in validate's warning stream, not a first-class, queryable check. And rivet docs is the built-in help-topic browser (--list / --grep / check --coverage) — same word, different thing — so it's natural to look there and not find a project-doc-scan view. rivet list can't fill the gap either: skipped docs never become artifacts, so list --type doc only ever shows the ones that already loaded — never the ones you're trying to debug.

Suggested shape — a dedicated doc-scan status, mirroring the oracle pattern rivet already uses for docs check --coverage:

• rivet docs scan [--format json] (or rivet check docs) that enumerates every candidate path the scanner considered, each tagged loaded / skipped (<reason>) / excluded (allowlist).
• --format json so an agent asserts visibility mechanically (a doc-visibility oracle), and a --strict / exit-nonzero-on-skip mode for CI — exactly like docs check --coverage --strict does today for undocumented subcommands.

That turns "spin up serve and look at the website" into a one-shot, CI-gateable check. Happy to dogfood it against gale's docs/ when it lands — we have the 3 live skip cases above to exercise the reason-reporting.

[avrabe]

Triage from the issue-fixing routine: solid friction trace, and the follow-up comment above sketches a clear shape (rivet docs scan / rivet check docs with per-path loaded / skipped (<reason>) / excluded rows, --format json, optional --strict). What the routine needs before it can open a PR is one explicit "fixed when …" line so the kill-criterion is unambiguous and testable.

Format matches #532's kill-criterion. A useful shape for this issue, lifted directly from your follow-up:

Kill-criterion: fixed when rivet docs scan (or rivet check docs) enumerates every candidate path the scanner considered, tags each loaded / skipped (<reason>) / excluded (allowlist), supports --format json for mechanical assertions, and exits non-zero under --strict when any candidate is skipped. Verified on gale's three live skip cases (mcuboot-coverage-analysis.md / release-plan.md / wasm-module-distribution.md) — each appears in the JSON with the correct reason, and --strict exits non-zero until those three are either given valid frontmatter or excluded via docs[].exclude.

If you'd rather narrow it (e.g. JSON output only this PR, --strict deferred; or surface the per-path status inside the existing rivet validate warning stream rather than a new subcommand), say which slice and the routine will queue that. Once a single kill-criterion is pinned in the body I'll pick it up.

Process side-rail (carried from every recent triage thread on this repo): https://pulseengine.eu/blog/ is still HTTP 503 — verified at the start and end of this run; same expired-TLS / site-infra symptom flagged on #420, #422, #431, #436, #456, #468, #479, #482, #488, #490, #500, #508, #509, #516, #522, #523, #530, #532, #538. The binding workflow guidance can't be consulted, so no PR will land from this triage run regardless. Comment is the AC ask only.

Not implemented this run.

---

Generated by Claude Code — issue-triage agent run 2026-06-17.

---

Generated by Claude Code

[avrabe]

Pinned the kill-criterion in the issue body — not narrowed: one PR with enumerate + per-path reason + --format json + --strict.

Two scope calls, with rationale so the routine can run with them:

• Keep --strict in this PR (not deferred). The issue title is literally "rivet check of docs" — the CI-gateable exit-non-zero-on-skip is the check; without it you've got a report, not a gate. It's a few lines once the enumeration exists.
• New rivet check docs subcommand, not folded into validate. Keeps the status queryable without a full validation pass, emits clean JSON (validate's stream is noisy), and matches the docs check --coverage --strict oracle you already ship.

Standing offer holds: I'll dogfood it against gale's three live skip cases the moment it lands — --strict should exit non-zero on our docs/ until those three are fixed or excluded, and each should show in the JSON with the right reason.

(Noted the pulseengine.eu/blog 503 blocks PR-landing this cycle — that's site-infra/TLS, nothing I can resolve from here; the AC is pinned and ready for whenever the routine can proceed.)

[avrabe]

Draft PR open: #541. Adds rivet check docs (enumerate + per-path reason + --format json + --strict), built on a new scan_documents that returns per-path detail without disturbing load_documents_with_report (so rivet validate's stderr-warning output is byte-identical). Verified against synthetic fixtures matching the three gale skip modes (no-frontmatter, missing-id frontmatter, excluded-by-glob). Held as draft pending the blog-down process gate (pulseengine.eu/blog/ is 503 again — same incident as #538/#532/#530/etc.). cargo fmt / clippy -D warnings / cargo test -p rivet-core -p rivet-cli / rivet validate on the repo itself are all green; rivet check docs --strict exits 0 here (no skips in this repo's docs/).

---

Generated by Claude Code