Skip to content

[codex] Improve agent onboarding docs#1652

Draft
arjxnt wants to merge 1 commit into
a16z:mainfrom
arjxnt:codex/agent-docs-quickstart-guard
Draft

[codex] Improve agent onboarding docs#1652
arjxnt wants to merge 1 commit into
a16z:mainfrom
arjxnt:codex/agent-docs-quickstart-guard

Conversation

@arjxnt

@arjxnt arjxnt commented Jun 27, 2026

Copy link
Copy Markdown

Summary

This PR makes the Jolt onboarding path for humans and AI coding agents match the current jolt new scaffold and adds CI coverage so it stays that way.

Changes:

  • update the Quickstart guest and host snippets to mirror the generated scaffold in src/main.rs
  • update the Hosts guide for the current preprocess_verifier_*(_, _, blindfold_setup) API
  • add a new Jolt Book page for AI-agent-oriented proof scaffolding, signature adaptation, input privacy choices, and debugging
  • link the new page from the README and book summary
  • add scripts/ci/check_docs_scaffold.py to check quickstart/scaffold drift, SUMMARY links, README linkage, and expected agent-workflow sections
  • add a Docs workflow that runs the scaffold check and builds the mdBook on docs-related PRs
  • document the local docs checks in CONTRIBUTING

Why

The book examples had drifted from what jolt new currently emits. In particular, the quickstart omitted preprocess_shared_*().unwrap(), omitted the third verifier preprocessing argument, and placed #![no_main] in the library snippet even though the generated scaffold keeps that in guest/src/main.rs.

That is exactly the first-run friction new contributors and coding agents hit. The new checker makes that drift visible in CI without requiring a full Rust workspace compile.

Validation

Local:

  • python -m py_compile scripts/ci/check_docs_scaffold.py passed
  • python scripts/ci/check_docs_scaffold.py passed using the Codex bundled Python runtime
  • git diff --check HEAD passed

GitHub:

  • Spec Workflow checks passed
  • Socket checks passed
  • Docs and Build and Test Jolt were enqueued but are currently action_required before any jobs start, which appears to require maintainer approval for forked PR Actions/new workflow execution

Not run locally:

  • mdbook build ./book; this Windows environment does not have a working Rust linker/binutils setup for installing mdbook plugins locally
  • Rust package tests; MSVC failed due missing link.exe, and GNU failed due missing dlltool.exe on this machine

@github-actions github-actions Bot added the no-spec PR has no spec file label Jun 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-spec PR has no spec file

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant