Skip to content

[Feature] Add a per-step preflight callout to every step (02-09) #6

Description

Problem or opportunity

scripts/preflight.py already supports per-step validation via --step N, with checks tailored to each step's requirements (e.g. step 3 verifies MCP_SERVER_LABEL / MCP_SERVER_URL, step 5 verifies AZURE_AI_SEARCH_ENDPOINT / AZURE_AI_SEARCH_INDEX_NAME).

However, only Step 0 (docs/steps/00-intro.md) and Step 1 (docs/steps/01-basic.md) actually instruct learners to run preflight. Steps 02–09 never mention it. As a result, learners can start a step with missing or misconfigured .env values and only discover the problem via cryptic runtime errors mid-step, rather than catching it up front.

Proposed improvement

Add a "Before you start" preflight callout to each of steps 02–09, matching the pattern already used at the top of docs/steps/01-basic.md:

Before you start: ... If python scripts/preflight.py --step N is green, you're ready.

Details:

  • Use the correct --step N value for each step's doc.
  • Mirror the existing dual-command guidance (activated .venv vs. uv run) already used elsewhere in the docs.
  • Keep wording consistent with the Step 1 callout so the experience is uniform across steps.

Affected files:

  • docs/steps/02-tools.md
  • docs/steps/03-mcp.md
  • docs/steps/04-toolbox.md
  • docs/steps/05-rag.md
  • docs/steps/06-skills.md
  • docs/steps/07-multi-agent.md
  • docs/steps/08-workflow.md
  • docs/steps/09-memory.md

Alternatives considered

  • Only recommending preflight generically (no per-step callout) — rejected: less actionable and doesn't leverage the existing --step checks.
  • Expanding preflight's per-step checks — out of scope here; this issue is purely about surfacing the existing capability in the docs.

Migrated from pmalarme/foundry-workshop-template#57.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions