> From [PageWeave Design](https://pageweave-design.pageweave.site) — a working library for agentic web development. Full index: [llms.txt](https://pageweave-design.pageweave.site/llms.txt)

# Environments & Releases

The shipping model: dev previews, immutable releases, dry-runs, and rollback discipline.

- Section: Ship
- Tags: release deploy environments rollback

PageWeave separates editing from shipping. Understanding this model prevents 90% of launch anxiety.

## The surfaces

- **Live (default)**: the public environment on your subdomain/hostname. Tracks latest UNLESS a release is attached.
- **Dev**: `*.env.pageweave.site` — noindex, no analytics, live-reload, shows draft rows. This is your workshop.
- **Releases**: immutable snapshots with `*.r.pageweave.site` permalinks. Attaching one FREEZES an environment to exactly that manifest.

## The ritual

1. **Build on dev.** Iterate against the dev URL; drafts visible; nothing public moves.
2. **Dry-run the release**: `create_release(dry_run: true)` previews the changeset — which pages/snippets/components/theme versions ride along, what conflicts exist.
3. **Create the release** (`scope: mine` for your edits, `all` to re-pin everything, `selection` for deliberate picks). Get the permalink.
4. **Dry-run the attach**: `attach_release(dry_run: true)` shows drift — reverts, disappearing items, unpublishings. Read this carefully; it's your last exit.
5. **Attach.** The live surface now serves EXACTLY the manifest: absent pages 404, absent snippets 404, absent components excluded, theme falls back to built-in default.
6. **Verify live**: homepage, one template page, one `.md` URL, llms.txt.

## What a release contains

Everything is version-pinned: pages at exact versions, component instances with their conditions, snippets, theme. Items created after the release's base are INVISIBLE until a later release includes them — "why isn't my new page live?" usually means this.

## Rollback

Attach an older release number. That's the whole procedure — no rebuilding, no panic. Keep the last known-good release number written down.

## Discipline rules

- Never attach without reading both dry-runs.
- One release = one reviewable unit. Don't bundle a redesign with a typo fix.
- Unattached releases past 50 get pruned; permalinks live as long as the release is retained.