Docs Validation

Documentation Validation Skill

Validates SaladCloud tutorials and how-to guides by actually following them step-by-step to ensure they work end-to-end.

Core Philosophy

The best way to validate a tutorial is to follow it. Don't just check syntax - actually attempt each step as a user would. If a step fails or is unclear, that's a validation failure.

Quick Start

Validate a single file

Validate container-engine/tutorials/quickstart.mdx

Validate all tutorials

Validate all tutorials in container-engine/

Validate changed files only

Validate documentation files changed in this PR

What Gets Validated

End-to-End Walkthrough (Primary)

The most important validation - actually following the tutorial:

• Attempt each step as documented
• Execute API calls and verify responses
• Follow portal UI instructions in a real browser
• Verify the workflow achieves its stated goal
• Report any step that fails, is unclear, or produces unexpected results

Code Blocks

• Python syntax and imports
• Dockerfile instructions
• Bash/shell commands
• JSON/YAML validity

API Examples

• curl commands match OpenAPI specs
• Required headers present
• Request bodies have required fields
• Endpoints exist
• Live execution when credentials are available

Portal UI (with authentication)

• Navigation paths work
• Button/link text matches
• Form fields exist
• Screenshots match current UI

Content Freshness

• Last updated dates
• Version references
• Terminology consistency
• External link validity

Authentication Setup

For portal UI validation, set credentials as environment variables:

export MCPROXY_CREDENTIAL_SALAD_EMAIL="your-email@example.com"
export MCPROXY_CREDENTIAL_SALAD_PASSWORD="your-password"

The AI agent never sees actual credential values - only references them by name.

See AUTH.md for detailed setup instructions.

Validation Modes

Full Walkthrough (Default)

Actually follows the tutorial end-to-end:

1. tutorial-walkthrough-validator - Attempts each step as a user would
2. code-block-validator - Validates code syntax
3. api-validator - Checks API examples against specs and executes them
4. portal-validator - Verifies UI instructions in real browser
5. content-validator - Checks freshness and terminology

This is the recommended mode - it catches issues that syntax checking misses.

Quick Validation

Skips browser-based and live API checks:

• Code block validation (syntax only)
• API example validation (spec matching only)
• Content freshness check

Use when you don't have credentials or need fast feedback.

Syntax-Only Validation

Just checks code block syntax:

• Python, Dockerfile, Bash, JSON, YAML
• No API or portal checks
• Fastest mode

File Locations

Tutorials

• container-engine/tutorials/
• gateway-service/tutorials/
• transcription/tutorials/

How-to Guides

• container-engine/how-to-guides/
• transcription/how-to-guides/

API Specs (for validation)

• api-specs/salad-cloud.yaml
• api-specs/salad-cloud-imds.yaml
• api-specs/transcribe.json
• api-specs/s4.yml

Report Format

# Validation Report: quickstart.mdx

## Summary

| Check        | Status | Issues |
| ------------ | ------ | ------ |
| End-to-End   | FAIL   | 1      |
| Code Blocks  | PASS   | 0      |
| API Examples | WARN   | 2      |
| Portal UI    | FAIL   | 1      |
| Content      | PASS   | 0      |

## Walkthrough Results

| Step | Description             | Status | Notes                         |
| ---- | ----------------------- | ------ | ----------------------------- |
| 1    | Obtain API Key          | PASS   | Found in portal as documented |
| 2    | Deploy Container Image  | FAIL   | 400 error - missing field     |
| 3    | Select Multiple GPUs    | SKIP   | Depends on Step 2             |
| 4    | Check Deployment Status | SKIP   | No deployment to check        |

**End-to-End Result:** FAIL - Could not complete tutorial as written

## Issues

### WALK-001 (Failure)

**Step:** 2 - Deploy Container Image **Type:** API Error **Details:** POST request returned 400 Bad Request - response:
"autostart_policy is required" **Impact:** User cannot complete tutorial as written **Fix:** Add
`"autostart_policy": false` to the JSON example

### API-001 (Warning)

**Location:** Line 89 **Type:** Missing header **Details:** curl example missing Content-Type header **Fix:** Add
`-H "Content-Type: application/json"`

### UI-001 (Failure)

**Location:** Line 45, Step 3 **Type:** UI text mismatch **Details:** Button says "New Container Group", docs say
"Create Container Group" **Fix:** Update button text in documentation

Specialized Agents

This skill coordinates several specialized validation agents:

• tutorial-walkthrough-validator - Actually follows the tutorial step-by-step (PRIMARY)
• code-block-validator - Validates code syntax and structure
• api-validator - Checks API examples against OpenAPI specs, executes when possible
• portal-validator - Browser-based UI validation
• content-validator - Freshness and terminology checks

CI/CD Integration

# GitHub Actions example
- name: Validate Documentation
  env:
    MCPROXY_CREDENTIAL_SALAD_EMAIL: ${{ secrets.DOCS_VALIDATOR_EMAIL }}
    MCPROXY_CREDENTIAL_SALAD_PASSWORD: ${{ secrets.DOCS_VALIDATOR_PASSWORD }}
  run: |
    claude "Validate changed MDX files in this PR"

Converted and distributed by TomeVault — claim your Tome and manage your conversions.