Skip to content
agentOS

Tutorial IA And Consistency Reviewer

Goal

Section titled “Goal”

Review the tutorial ladder as one information architecture, not fourteen independent pages.

What You Build

Section titled “What You Build”

A reviewer checklist that keeps beginner tutorials ordered, non-duplicative, and honest about which checkpoints are local proofs versus live smokes.

Prerequisites

Section titled “Prerequisites”

Steps

Section titled “Steps”

  1. Check the sidebar source of truth:

    Terminal window
    jq -r '.tutorials[].label' docs/tutorials/sidebar.json

  2. Confirm every tutorial file appears exactly once in that list:

    Terminal window
    bun run docs:check

  3. Review each page for the required tutorial headings:

    Goal
    What You Build
    Prerequisites
    Steps
    Checkpoint
    Next

  4. Enforce proof language:

    local proof       typecheck, unit test, fake provider, bundle build
    live smoke        opt-in provider/deploy run with credentials
    not proven        anything not executed by the tutorial evidence

  5. Reject source-shape drift:

    no @agent-os/*/src imports
    no workspace: or file: consumer install path
    no raw provider URL or token in docs examples
    no duplicate kill criterion in package docs

Checkpoint

Section titled “Checkpoint”

The ladder reads in this order:

A1 durable fact
A2 tool loop
A3 tool contract
A4 projection
A5 background work
A6 output stream
A7 bidirectional stream
A8 Cloudflare app
A9 provider material
A10 npm consumption
A11 ops
A12 deploy
A13 full app
A14 review

The sidebar must match the same order. If a future tutorial appears in docs/tutorials/*.md but not in docs/tutorials/sidebar.json, docs:check must fail.

Next

Section titled “Next”

Use the ladder as the starting point for the next real agent app tutorial.