sites:sites-building

skill://sites@openai-curated-remote/root/.codex/plugins/cache/openai-curated-remote/sites/0.1.32/skills/sites-building/SKILL.md

---
name: sites-building
description: Use Sites to build websites, including landing pages, portfolios, dashboards, portals, trackers, hubs, and internal tools. Always use Sites when the project contains `.openai/hosting.json`.
---

# Sites building

Build the requested site in its lifecycle checkout, then use `sites-hosting`
to publish coherent milestones and the complete experience unless the user
explicitly asks to keep it local.

## Site lifecycle ownership

The Site-owning agent is the main agent responsible for the user's requested
Site, including an independently started background or invisible task. Only
that agent may initialize or edit the checkout or `.openai/hosting.json`, run
`sites-building` or `sites-hosting`, obtain source credentials, call Sites tools,
publish, or verify deployment status. A spawned subagent may return an assigned
image, asset, or research result, but must not invoke Sites skills or tools,
edit the checkout, initialize another Site, or spawn another agent. Keep
publishing and status polling with the Site-owning agent.

For asset delegation, use `fork_turns="none"` and pass only the asset brief
plus these ownership restrictions. The subagent saves outside `checkout_path`
and returns its asset path; the Site-owning agent inspects and integrates it.

## 1. Start with the project

### Workflow surfaces

Use these terms consistently:

- **Agent preview:** the live current checkout started with `sites-preview` and
  tested by the agent in the cloud browser during source iteration. It is
  internal and not deployed.
- **Checkpoint deployment:** an immutable production version prepared by
  `checkpoint`, saved and deployed through direct main-agent `codex_apps` calls,
  confirmed through deployment-status verification, and shared for user iteration.

Agent preview is optional and only runs when the user explicitly requests
browser, visual, or end-to-end testing. Deployment-status verification always
confirms platform state and does not require agent preview.

Agent preview is the only surface the agent opens in the cloud browser. Never navigate the cloud browser to a checkpoint deployment or any live Sites URL; live Sites URLs are not reachable from that runtime. Direct deployment-status verification surfaces the URL to the user, who can open it in their own browser.

### Lifecycle CLI

Resolve the CLI directly from this skill file. After loading this skill, invoke the matching command as the first task action, before any workspace inspection, source edit, connector call, package-manager action, or follow-up question. This lifecycle-first rule takes precedence over later uses of “first.”

```sh
# Preflight a new Site with the standard Vinext starter.
python3 "$(dirname "<absolute path of this SKILL.md>")/../sites-hosting/scripts/sites.py" create \
  --title "<title>" \
  --slug "<slug>" \
  --starter vinext

# Preflight a new Site from a retained template source directory.
python3 "$(dirname "<absolute path of this SKILL.md>")/../sites-hosting/scripts/sites.py" create \
  --title "<title>" \
  --slug "<slug>" \
  --starter "<absolute path to assets/source>"

# Open an existing Site by slug. Omit --slug inside its checkout.
python3 "$(dirname "<absolute path of this SKILL.md>")/../sites-hosting/scripts/sites.py" edit \
  --slug "<slug>"
```

For a new Site, `create` only validates the request and returns
`status: ready_to_create` with the exact remote-create arguments. Follow
**Create** below: use `sites-hosting` to register the Site, then run
`initialize` for that returned project. Treat the checkout as usable
only when `initialize` returns:

```json
{
  "status": "ready",
  "checkout_path": "/workspace/sites/<slug>",
  "dependencies": "<installed|reused|not-required>"
}
```

A successful `edit` instead returns dynamic text with its mandatory
`sites_get_site` main-conversation instruction first, followed by `Status:
ready`, the absolute `Checkout` path, and dependency state. Follow that
instruction before inspecting or editing source, then continue from the
reported checkout.

Treat `checkout_path` as the sole source working directory and
`.openai/hosting.json` as its identity; do not maintain a separate Site catalog.
Pass only the opaque project ID to `initialize`, never a credential returned
by a tool. The CLI acquires its own process-local Git credentials. Follow
`sites-hosting` for native MCP creation, publishing, and credential boundaries.

Once the command has been invoked, any necessary follow-up questions may be
asked while asynchronous initialization continues. Do not inspect or edit site
source until the command returns a ready `checkout_path`. If the request only
inspects or manages an already-hosted site without changing source, use
`sites-hosting` directly.

If `initialize` yields a still-running command session, continue polling that same
session until it exits; missing `status: ready` while the process is still
active is not a failure, and you must not run `edit` concurrently.

#### Create

Derive a concise title and slug from the request as given; later clarification does not justify creating a second Site. A slug must be at least five characters, start with a lowercase ASCII letter, contain only lowercase ASCII letters, digits, and single hyphens, and have no leading, trailing, or consecutive hyphens. Vinext is the standard starter and CLI default. Use `--starter worker` only when the request specifically requires the buildless Worker starter. For a Site template, pass the absolute retained `assets/source` directory as `--starter`; the template source itself is the starter, so do not initialize or copy a built-in starter first.

1. Run `create` as the local preflight. It validates the slug, destination, and
   starter before any remote creation. If it fails, repair that input and retry
   preflight; do not create a remote Site yet.
2. Once it returns `ready_to_create`, follow **Register a new Site** in
   `sites-hosting` with the returned `create.arguments`. Keep the returned
   project ID for initialization; do not create another Site during hosting.
3. Run `initialize` with that ID and the preflight's exact slug and starter:

   ```sh
   python3 "$(dirname "<absolute path of this SKILL.md>")/../sites-hosting/scripts/sites.py" initialize \
     --project-id "<create response id>" \
     --slug "<validated slug>" \
     --starter "<validated starter>"
   ```

`initialize` verifies the existing Site, acquires a process-local Git credential,
copies the selected starter, writes `project_id` into `.openai/hosting.json`,
initializes the empty checkout, and installs dependencies. Template initialization
preserves the package manager, lockfile, architecture, and logical D1/R2 bindings.
Do not copy a starter manually. If initialization fails before creating the
checkout, retry `initialize` for the same project; if the checkout exists,
recover with `edit`. Never create a second remote Site to recover initialization.

During the first generated iteration, replace starter document metadata with the authoritative `site_title` returned by `initialize`. For Vinext, update the exported metadata in `app/layout.tsx`; for the buildless Worker starter, update the `<title>` in `worker/index.js`. For a retained template, update its existing title mechanism without replacing its architecture. Ensure the rendered HTML `<title>` matches the Site title before the first preview or checkpoint. Never leave `Starter Project` or another unrequested starter title in the generated Site.

#### Edit

Run exactly one initial `edit`. From inside a Site checkout, pass no reference. Otherwise pass exactly one known identifier:

```sh
python3 "$(dirname "<absolute path of this SKILL.md>")/../sites-hosting/scripts/sites.py" edit --slug "<slug>"
python3 "$(dirname "<absolute path of this SKILL.md>")/../sites-hosting/scripts/sites.py" edit --project-id "<project_id>"
python3 "$(dirname "<absolute path of this SKILL.md>")/../sites-hosting/scripts/sites.py" edit --path "<checkout_path>"
```

A warm checkout is a valid Git checkout containing `.openai/hosting.json`; it makes no Sites RPC call. If missing, `edit` resolves and clones the remote Site before installing dependencies. Preserve the existing package manager, lockfile, architecture, hosting manifest, and binding names. Preserve scripts unless explicitly requested browser testing requires the minimal agent-preview compatibility change allowed below.

### Choose the execution path

Use the **one-shot fast path** only when all of these are true:

- this is a new site;
- one route can satisfy the request;
- the request does not require D1, R2, uploads, app-owned authentication,
  or external connectors; and
- the normal deliverable is a private deployed URL.

Use the **capability path** otherwise. This includes existing-site changes,
multi-route sites, persistent data, uploads, authentication, and external data.
Explicitly requested browser, visual, or end-to-end testing uses the capability
path. Ordinary creation, editing, and publishing requests do not authorize
agent-preview QA.

An explicit local-only request uses the capability path. Build the complete
site in the lifecycle checkout, then run the project's production build once
as the final gate. Only use agent preview if browser, visual, or end-to-end
testing was explicitly requested. Skip checkpoint deployment and the Hosting
handoff for local-only work.

## 2. Design the experience

Keep this planning lightweight and internal. Make these decisions while project setup continues, and revise them together when implementation reveals a better direction. Do not turn design planning into a mandatory interview or approval gate, generate design options, or pause for visual selection unless the user explicitly asks to compare designs.

### Frame the product and scope

Determine:

- who the site is for and the primary task they need to complete;
- the essential content, functionality, and requested capabilities; and
- the smallest coherent scope that fully satisfies the request without speculative features.

For a new Site, implement only the content and product capabilities the user
requested, plus the minimum structure, accessibility, responsive behavior, and
basic document metadata needed for that experience to work. “Polished” changes
the quality of execution, not the product scope. Do not add routes,
interactions, forms, search, filters, sharing, persistence, authentication,
uploads, or other optional capabilities unless the user explicitly requests
them. For an existing Site, preserve its current capabilities unless the
requested change requires altering them, but do not add new ones without a
request.

Do not invent sections, calls to action, features, data, or workflows merely
because they are common or easy to add.

Choose the dominant presentation mode from the user's intent:

- **Working surface by default:** When the primary goal is to explore, compare, monitor, decide, or act—especially for personal or internal use. The first viewport must expose core controls and at least one useful result when relevant; keep framing brief and secondary.
- **Narrative surface when intended:** When the primary goal is to publish, persuade, teach, sell, or tell a story.
- A topic resembling a report, review, or article does not by itself imply narrative intent.

Infer these decisions from the request and existing product when possible. Ask one concise group of up to three discovery questions only when important context is missing and the unresolved details would materially affect functionality or force a risky assumption. Otherwise proceed immediately with best judgment.

### Shape the experience

Make a lightweight implementation plan:

- Identify the primary flow and what the first viewport must show or enable.
- Add routes and navigation only when the request requires multiple views.
- Account for relevant loading, empty, error, and success states.
- Choose layout, density, and responsive behavior around the primary task; working surfaces must not put a marketing or editorial hero before it.

### Establish the visual direction

Before the first source edit, derive one concise visual thesis from the
request's subject, audience, and tone. Let it drive page silhouette, typography,
surfaces, spacing rhythm, and imagery. Choose a coherent palette, border and
corner treatment, icon style, and motion approach. Use the user's content,
brand, references, audience, and domain to create recognizable cues rather than
a formulaic default. Make this decision quickly; do not narrate it or delay
editing. Different briefs should produce meaningfully different compositions,
not the same generic structure with new copy and colors. For polished or
strongly visual work, include at least one memorable, request-appropriate visual
decision without inventing content, sections, capabilities, or actions. Carry
the selected rules through routes, responsive states, interaction states, and
later edits.

### Select existing UI primitives

The standard Vinext starter already includes the supported Shadcn catalog. For
a new Site created from that starter, a requested control or interaction with a
direct catalog match must use the matching vendored primitive on its first
implementation; do not hand-build a substitute. Map side navigation to
`sidebar`, tabbed views to `tabs`, modal flows to `dialog`, right-side detail
panels to `sheet`, destructive confirmations to `alert-dialog`, searchable
pickers to `combobox`, command or search menus to `command`, boolean choices to
`switch` or `checkbox`, constrained choices to `select` or `radio-group`,
ranges to `slider`, contextual actions to `dropdown-menu`, hover help to
`tooltip`, verification codes to `input-otp`, structured tables to `table`,
progress indicators to `progress`, page navigation to `pagination`, empty and
loading placeholders to `empty` and `skeleton`, and transient feedback to
`sonner`. In a Site created from the standard starter, import each selected
primitive directly from `@/components/ui/<component>`, then compose and restyle
it at the call site. For an existing or template-derived Vinext Site, apply this
requirement only to matching primitives already present in the project and use
the project's existing import path.

Use semantic HTML and custom React/CSS for page layout, art direction,
substantial data visualization not covered by the vendored chart wrapper, or UI
the catalog does not cover. Do not add content, actions, routes, workflows,
state, or capabilities merely to use a component or satisfy a component quota.
Do not inventory the catalog or scan component implementations. The semantic
match is sufficient for selection; unfamiliarity with an API is not a reason
to build a substitute. When a selected component's exported API is unclear,
open only that implementation when needed for the next source edit.

Do not run the Shadcn CLI, install another component package, modify
`package.json` or `package-lock.json`, or edit vendored files under
`components/ui` merely to obtain, recreate, or restyle an already-vendored
primitive; compose and restyle it at the call site instead.

**For imagery, do:**

- Use HTML, CSS, and SVG for functional interface styling and geometry, simple non-representational accents, trusted icons, diagrams, and data visualizations.
- For imagery not explicitly required by the user's requested content, choose
  **0–3 discretionary final-site images**. A final-site image is an in-page image
  asset integrated into the delivered Site; it may be user-provided,
  web-sourced, or AI-generated. Social-preview images and deployment thumbnails
  are separate explicit-request-only workflows and do not count toward this
  decision. This discretionary budget does not cap suitable user-provided assets
  or images explicitly requested by the user or required as the content of a
  requested portfolio, gallery, catalog, or similar experience; include those
  as requested. It does not expand the bounded **1–3 generated in-page assets**
  execution below. Use **1–3 discretionary images** for visually led marketing,
  brand, editorial, portfolio, consumer, or storytelling Sites. For inherently
  visual consumer subjects—including pets, food, travel, fashion, and
  homes—include at least
  one final-site image unless the user explicitly requests an image-free
  direction. Use **0 discretionary images** for technical, data-heavy,
  dashboard, admin, developer, or other utilitarian Sites when typography,
  layout, icons, or data visualization carry the design.
- Choose the image source explicitly. Prefer a suitable user-provided asset.
  Use web image search for real or factually specific people, places, products,
  events, and subjects. Use image generation for original, illustrative,
  editorial, or brand-specific imagery.
- When using `imagegen`, give a subagent only the image brief; the Site-owning agent saves and integrates the returned asset.

**Do not:**

- Build representational images or decorative artwork, including illustrations, objects, or scenes, from styled HTML, CSS shapes, pseudo-elements, or hand-written SVG.
- Add imagery that does not support the site's purpose.

#### TPP image-generation execution

For **1–3 generated in-page assets**, spawn exactly one image-generation
sub-agent. For one asset, make one request. For two or three assets, make one
request per chosen asset together as one parallel batch. Do not generate
variants or retry. The sub-agent writes outside `checkout_path`; the main agent
remains the sole source editor, never calls image generation directly, inspects
the returned images, and integrates only ready, useful outputs.

Generate clean standalone assets rather than screenshots containing page text
or interface chrome. Keep generation purposeful; do not create imagery when
typography, layout, color, icons, or simple CSS accents already express the direction.

The buildless Worker starter deploys only `worker/index.js` and the hosting manifest. Do not add standalone asset files to that starter. If essential generated raster imagery is used, embed its bytes in `worker/index.js` and serve or reference them as a data URL; otherwise choose a design that does not require file assets.

### Latency

Latency here means the user's wait from their request until a complete deployed
Site can be returned. Optimize that path for the earliest coherent edit and
deployment:

- Once `initialize` returns ready, decide the requested scope and one visual thesis,
  then make the earliest coherent source edit. Do not draft the full page twice,
  add a planning-only round, inspect speculative files, or create alternate
  candidate pages.
- Do not spend delivery time on unrequested sections, features, actions, routes,
  data, or workflows. Apply requested polish to execution quality inside the
  requested scope.
- When using generated final-site images, start exactly one image-generation
  sub-agent as soon as the direction is stable, while the main agent begins
  editing and continues through authoring and validation. Parallel work overlaps
  image generation with coding; it does not make image generation free or
  instant.
- Never wait for optional images before the first source edit or earliest
  deployable checkpoint. If they are not ready and useful when the Site is
  otherwise ready, deploy without them. An image required by the user's request
  or the visual-consumer rule is not optional; use the chosen source or a
  permitted fallback before the final checkpoint. If no suitable asset is
  available, report the Site as incomplete instead of silently dropping it.

These authoring shortcuts must never skip or weaken Site creation, dependency
installation, the production build, checkpointing, deployment, or terminal
deployment-status verification.

## 3. Build, preview, and deliver

### Social previews

Generate or refresh a social-preview image only when the user explicitly
requests a social-preview or social-sharing image. Otherwise preserve an
existing preview image and its metadata unchanged. If none exists, omit it; do
not start an image-generation sub-agent, add `public/og.png`, or add
social-preview image metadata.

1. **Never delay the first coherent checkpoint.** When explicitly requested,
   once the site's direction and copy are stable, spawn exactly one
   image-generation subagent under the asset-delegation rules above to make
   one image-generation request. Create one cohesive branded landscape card
   showing the site's exact title or primary headline and concise supporting
   copy as legible typography. Match its palette, typography, and distinctive
   visual motifs; exclude credentials and private user data. Inspect for
   incorrect, missing, or invented text; retry once only if the card is
   unusable. The main agent remains the sole site-source editor.
2. **Wire the site-wide preview.** When a new card is generated, save it as `public/og.png` and set site-specific Open Graph and X title, description, and image metadata in `app/layout.tsx`. Use an absolute URL from a trusted request or deployment origin; never blindly trust forwarded host headers. If generation fails, preserve any existing valid preview; omit `og:image` only when neither an existing nor generated image is available. Never use a generic fallback. Include the asset and metadata in the final checkpoint.
3. **Handle requested item-specific previews.** When the explicit social-preview request covers independently shareable detail pages, use `generateMetadata` or its equivalent to set page title and description and Open Graph/X title, description, and image from the rendered record. Reuse its existing primary image with an absolute trusted-origin URL; otherwise clear both inherited Open Graph and X images. Never reuse `public/og.png` or generate images per record. Validate the root and every detail page when there are at most two; otherwise check at least two representative detail pages. Before final validation, verify that each checked page's title, description, and Open Graph/X fields match its record.

### One-shot build

After setup and any necessary clarification, build and deploy the complete site
in one focused pass.

1. For Vinext, inspect `app/page.tsx`, `app/layout.tsx`, `app/globals.css`, and
   `.openai/hosting.json`. For the buildless Worker starter, inspect
   `worker/index.js`, its README, and `.openai/hosting.json` instead. For a
   retained template, inspect its existing application entrypoints, package
   configuration, and `.openai/hosting.json`. Read other files only when
   implementation needs them. Avoid broad scans and speculative research.

2. Build the complete product in coherent milestones. Prefer one page component
   and one stylesheet when that fits the product. Include all requested content,
   interactions, responsive behavior, keyboard and touch behavior when
   relevant, and accessible labels.

3. Follow the shared Hosting handoff and checkpoint cadence below. For a
   multilayer site, checkpoint the earliest coherent visible slice and continue
   the next milestone while its deployment runs. Use a single checkpoint only
   when no independently useful intermediate state exists.

For hosted work, use the build and packaging gate in `sites-hosting`; do not
duplicate it with a separate foreground build or artifact validator. It uses
the existing project build script and preserves the remote-build fallback for
local environment failures.

### Capability path

#### Project setup

- Use the checkout returned by `initialize` or the initial `edit`; do not run another
  initializer.
- For an existing or template-derived site, preserve its package manager,
  lockfile, architecture, and `.openai/hosting.json`. Only for explicitly
  requested browser, visual, or end-to-end testing, allow minimal `dev`-script
  and Vite server-config changes required by agent-preview troubleshooting if
  they do not alter the production build. Do not replace a working structure
  merely to use the starter.
- Keep site code within `checkout_path`.

#### Expand the design consistently

- For a new Vinext site, remove the temporary `codex-preview` metadata marker, update `app/layout.tsx` with the finished site's title and description, and replace any other starter metadata before the final checkpoint.
- Use concrete, product-specific copy and realistic data.
- Apply the chosen UX, layout, and visual rules consistently without making every page mechanically identical.
- Avoid unnecessary client state.
- For Vinext, preserve the starter's `sites()` Vite plugin. For the buildless
  Worker starter, follow its README and edit `worker/index.js` without
  introducing Vite. For a retained template, preserve its existing architecture.
  Preserve Cloudflare Worker-compatible ESM output for server-backed sites.

Server-backed builds must produce `dist/server/index.js` as ESM with a default object containing callable `fetch(request, env, ctx)`, plus valid `dist/.openai/hosting.json`. Preserve emitted static assets and require `dist/.openai/drizzle/**` when migrations exist. Preserve each starter's build script and any starter-provided validation commands; checkpoint runs the build locally by default, and the remote Sites builder runs it from the pushed commit when `--use-remote-build` is needed.

Static-only builds without runtime bindings, capabilities, or migrations may publish Cloudflare-compatible static output without a Worker. Examples include `dist/index.html`, Next.js exports (`out/`), and vinext exports (`dist/client/`). All static-only builds must set `static.directory` in `.openai/hosting.json` to a supported public output directory (`dist`, `dist/client`, `out`, `build`, or `.output/public`). For Next.js/vinext exports, use `output: 'export'`; select only public assets, excluding any server intermediates.

#### Add only requested capabilities

- For durable state, records, uploads, or other persistence, read
  [Persistence and storage](references/persistence-and-storage.md).
- For identity-aware or sign-in-gated behavior, read
  [Authentication](references/authentication.md).
- Hosted Sites do not support raw TCP sockets (`connect()`); use HTTP-based clients or APIs for external databases and services.
- Use browser storage only for device-local preferences or explicitly local
  state.
- For new sites, store only `project_id` plus optional `static` configuration
  and logical `d1` and `r2` bindings in `.openai/hosting.json`. Preserve an existing site's manifest
  fields. Sites owns the real Cloudflare resources and deployment wiring.
- Keep local `.env` and `.env.example` keys aligned. Manage hosted runtime
  values through Sites.

#### Validate capability work

When a hosted capability milestone is ready, use `sites-hosting` to validate
and publish it. First run the single requested QA pass only when the user
explicitly requested browser, visual, or end-to-end testing; defer deployment
when passing QA is a publication condition. If a D1 schema changed, generate
and inspect its migration before hosting. Fix source failures in the checkout
before preparing another checkpoint. For local-only work, finish the complete
implementation and run the production build without publishing.

### Preview rules

Only start an agent preview, load a browser-control skill, or perform screenshots,
DOM inspection, clicking, resizing, or visual and interaction QA when the user
explicitly requests browser, visual, or end-to-end testing. Requests to create,
edit, build, improve, or publish a Site do not authorize browser QA. Otherwise,
skip this section and proceed directly to the normal checkpoint or local-only
production-build final gate.

For requested QA, run one primary-flow pass. Aim for a first usable screenshot
within 20 seconds and use a best-effort 60-second total budget. Allow at most
one source-defect fix and recheck within that same budget; do not start
additional QA or troubleshooting after it expires.

Before the first cloud-browser action in a task, load and read the skill `$control-browser` and follow it for browser setup, selection, navigation, interaction, screenshots, waits, and cleanup. Do this before initializing the browser runtime, selecting a tab, or navigating to `terminal.local`. If the skill is unavailable, treat agent preview as unavailable and follow the bounded fallback below; do not improvise with standalone Playwright, Computer Use, or another browser surface.

Requested agent preview is best effort unless the user made passing browser QA
a condition of deployment. If its environment is unavailable, stop
troubleshooting within the same 60-second budget and explain that the requested
test could not run. Continue with a checkpoint deployment for hosted work or
the production-build final gate for local-only work unless the user required
successful browser QA before deployment.

The buildless Worker starter has no compatible `dev` server. Explain that
requested browser testing is unavailable for that starter and continue with the
normal checkpoint or local-only final gate unless passing browser QA was an
explicit condition of deployment.

From the Site root, run:

```bash
sites-preview start "$PWD"
```

Open the agent preview in the cloud browser at:

```text
http://terminal.local:4173/
```

Use plain HTTP, never HTTPS. Do not substitute `localhost`, `127.0.0.1`, `0.0.0.0`, another hostname, another port, or a live Sites URL. `0.0.0.0` is only the dev-server bind address. The agent-preview address is an internal implementation detail: never mention it, link it, or expose it to the user.

For an explicit post-navigation wait in the cloud browser, use the `load` state rather than `networkidle`; `networkidle` is unsupported in this runtime.

Do not start the dev server directly. The Vinext starter is already configured for agent preview. For an older Vite/Vinext Site, use the compatibility recipes in [Agent-preview troubleshooting](../sites-preview-troubleshooting/SKILL.md); the `dev` script must ultimately invoke Vite directly and accept the forwarded flags. Preserve compatible wrappers and environment prefixes. When a compatibility repair makes agent preview work, keep it in the checkout and include it in the next checkpoint commit so later runs inherit the working setup; do not revert it as temporary preview-only state. Inspect the rendered primary route and exercise its primary interactions. Fix source problems found there before creating a checkpoint deployment.

If agent preview does not start or the cloud browser cannot reach it, read and follow [Agent-preview troubleshooting](../sites-preview-troubleshooting/SKILL.md). Stay within the requested QA budget; infrastructure failure must not block an otherwise valid checkpoint deployment or local-only final gate unless the user explicitly required successful browser QA before deployment.

### Hosting handoff

Use `sites-hosting` with the existing `checkout_path` and a concise checkpoint
message when a coherent milestone is ready. That skill owns checkpoint
preparation, approval, native MCP save/deploy, and direct status verification.
The Site-owning agent follows both skills itself; do not delegate hosting or
polling to a monitoring subagent. Do not finish with only a local build unless
the user requested local-only work. The verified deployed URL is the primary
deliverable.

#### Checkpoint cadence

Bias toward the earliest coherent checkpoint, not the latest polished one.

For a normal one-route Site, the expected cadence is:

1. **First visible slice:** the primary route, first viewport, visual direction,
   and representative content are present.
2. **Complete experience:** requested sections, interactions, responsive
   behavior, accessibility, and final content are complete.

Create additional checkpoints only for genuinely independent capabilities or
useful review points. Do not checkpoint cosmetic edits individually.

The first checkpoint lets deployment overlap continued implementation. After
launch, the Site-owning agent may return to source work while polling that
checkpoint itself through `sites-hosting`. Complete its terminal verification
before preparing another checkpoint for the same Site. Announce each verified
milestone as described in the hosting handoff, without waiting for feedback
unless the user requested review gates. Never let an older checkpoint stand in
for the latest requested work.

### Recovery rules

- If dependency installation fails during `initialize`, fix the reported lockfile or environment issue and recover with `edit` using the reported checkout; never create another remote Site. If it fails during `edit`, fix it and rerun that `edit`.
- Follow `sites-hosting` for approval, source-push, save, and deployment failures. Return here for source repairs; do not redeploy a failed saved version automatically.

### Completion checklist

- The first task action after loading this skill was exactly one `create` or `edit` command.
- Remote create, save, and deploy used direct main-agent `codex_apps` calls;
  creation preflight and checkpoint preparation were not mistaken for completion.
- All source edits stayed inside the returned `checkout_path`.
- For hosted work, the first checkpoint was created at the earliest deployable state that clearly represented the requested Site.
- When multiple implementation layers existed, checkpoint deployment time overlapped continued source work.
- For hosted work, the final checkpoint represented the complete requested experience.
- The final build or checkpoint included the validated site-specific social
  card and metadata when the user explicitly requested one and generation
  succeeded.
- No checkpoint captured only the untouched starter, a knowingly broken state, or an isolated cosmetic edit.
- Browser QA ran only when explicitly requested; an unavailable preview did not block an otherwise valid checkpoint or local-only final gate unless the user required passing browser QA before deployment.
- The Site-owning agent completed `sites-hosting` verification for every launched checkpoint, using its exact immutable IDs; no subagent result or commentary URL substituted for the main-conversation status call.

The current Sites connector schema and tool descriptions are the source of truth for remote creation, deployment, environment variables, and access controls.

## Communicate with the user

Assume the user is a nontechnical knowledge worker. Talk about their site,
choices, progress, and results. Keep tools, commands, files, runtimes, browser
software, permissions, dependencies, source control, credentials, IDs, builds,
and deployment internals out of user-facing messages unless the user asks or
must take action.

Ask follow-up questions only when important context is missing and the unresolved
details would materially affect the Site or force a risky assumption. For
source-changing work, first invoke the required `create` or `edit` lifecycle
command. After that invocation, this may happen during any phase, including
design, content, functionality, data, access, and publishing. When
`request_user_input` is available, use it for this context-gathering turn;
otherwise ask directly in the conversation. Ask
one concise group of one to three tailored questions, then wait for the user's
answer. Ask only what cannot be inferred from the user's request or the current
Site, skip questions the user already answered, and proceed with best judgment
when the user asks you to decide or the remaining ambiguity is low-impact.
Do not generate multiple design options or pause for a visual selection unless
the user explicitly asks to compare designs.

Use no more than one short update for each user-visible phase: preparing the
site, building it, and publishing. If a phase takes longer
than 60 seconds, give one plain-language update. Keep recoverable technical
problems private; say only that you hit a problem and are trying another method.
Keep Git, remotes, branches, commits, pushes, and other source-control mechanics
out of commentary.
Keep opaque identifiers returned by `codex_apps` out of commentary, including
site/project, version, deployment, and resource IDs. Use them only in tool calls
and internal coordination unless the user explicitly asks for them or needs one
to act.

Clarification questions, approval requests, and required verified checkpoint
notifications are decision points or deliverables, not progress updates, and
do not count against this limit. A verified checkpoint notification consists of
the required direct main-conversation status call plus its accompanying
commentary.