Preview Verification

How preview verification works, what gets checked, and what gets recorded.

Workflow Rules · /home/jonas/social-carousel-codex/docs/preview-verification.md

Last modified: 2026-03-29T10:17:15.208Z

# Preview Verification

## Purpose

Phase 7 strengthens preview verification beyond artifact existence.

Primary command:

```bash
python3 scripts/runtime_state.py verify-preview <folder_name> --idea-id <idea_id> --version V1 --base-url http://127.0.0.1:3101
```

Optional public-host verification:

```bash
python3 scripts/runtime_state.py verify-preview <folder_name> --idea-id <idea_id> --version V1 --base-url http://127.0.0.1:3101 --public-base-url https://agent.jonaswilbert.com
```

## What It Verifies

### Artifact Checks

The verifier now checks:

- `request.json` exists
- `carousel.json` exists
- `manifest.json` exists
- `carousel.json` is a valid preview payload
- manifest folder metadata matches the requested folder

### HTTP Checks

When HTTP verification is enabled, the verifier performs bounded requests against:

- `GET /preview/<folder_name>`
- `GET /api/preview/<folder_name>`

For each target base URL it records:

- viewer HTTP status
- viewer response size
- whether the folder name appears in the HTML response
- preview API HTTP status
- preview API response size
- whether the API payload is valid preview JSON
- whether the API payload folder matches the requested folder

## Durable Output

Canonical file:

- `artifacts/previews/<folder_name>/verification.json`

Current schema version:

- `phase8-preview-verification.v3`

Current top-level fields include:

- `idea_id`
- `version`
- `folder_name`
- `preferred_target_label`
- `viewer_url`
- `api_url`
- `artifact_viewer_url`
- `artifact_api_url`
- `public_viewer_url`
- `public_api_url`
- `artifact_checks`
- `http_checks`
- `status`
- `verification_scope`
- `http_timeout_seconds`
- `verified_at`

## Status Rules

Current status values:

- `verified`
- `missing_or_invalid_artifact`
- `http_verification_failed`

`record-preview` should only be used after `status: verified`.

When `--public-base-url` is supplied and the public checks pass:

- top-level `viewer_url` and `api_url` become the public verified URLs
- `preferred_target_label` is `public`
- the local artifact-backed URLs remain available in `artifact_viewer_url` and `artifact_api_url`

## Operational Notes

- The app must be running on the target base URL for HTTP verification to pass.
- By default, the local runtime target is `http://127.0.0.1:3101`.
- Public-host verification is optional because it depends on the public route being reachable in the current environment.
- New preview payloads now use version-specific folder names such as `idea-20260329-protein-breakfast-satiety-realrun-01-v2`.
- Older per-idea preview folders remain valid and can still be verified; the new naming is a forward-only migration for newly built previews.
- If you need artifact-only verification for a bounded offline case, use:

```bash
python3 scripts/runtime_state.py verify-preview <folder_name> --skip-http
```

That escape hatch exists for recovery work, not as the default workflow.

## Verified In Phase 7

Verified local HTTP checks:

- `python3 scripts/runtime_state.py verify-preview idea-local-phase6-helpers --idea-id IDEA-local-phase6-helpers --version V1 --base-url http://127.0.0.1:3101`

Verified local plus public HTTP checks:

- `python3 scripts/runtime_state.py verify-preview idea-local-phase6-helpers --idea-id IDEA-local-phase6-helpers --version V1 --base-url http://127.0.0.1:3101 --public-base-url https://agent.jonaswilbert.com`

Verified after the Phase 8 approved-rule implementation:

- `python3 scripts/runtime_state.py verify-preview idea-20260329-protein-breakfast-satiety-realrun-01-v2 --idea-id IDEA-20260329-protein-breakfast-satiety-realrun-01 --version V2 --base-url http://127.0.0.1:3101 --public-base-url https://agent.jonaswilbert.com`

Ready