siteplane

Image-policy preparation: When the scan includes image fields, withSiteplane prepares Next Image and existing Next-config CSP headers for Siteplane's image route and your website's /siteplane-assets/ path. Existing image sources stay in place. Local builds require the same public HTTPS SITEPLANE_SITE_ORIGIN supplied by setup deploy. The wrapper adds only those exact patterns: existing sources, custom loaders and redirect settings remain unchanged. Preflight still flags custom loaders and CSP in middleware, proxy or app source for explicit delivery checks. Keep existing policies and verify Siteplane images through the website's actual renderer. This preparation does not authorize hosting.

Public Siteplane CLI for connected-site setup, field synchronization, Analytics instrumentation and Booking integration.

Controlled guest review

After a controlled accountless setup reaches ready_for_review, run siteplane setup review in the same website repository. Its protected local installation key opens access to that project's saved review without creating another site or deployment. Give the one-time link to the user; they choose Open review in their own browser. Do not consume the link on their behalf. Issue a fresh link only when needed. The URL fragment is a short-lived credential, so do not write it to source, documentation, analytics or shared logs. Guest review can organize and finish the setup; activation and account ownership require the later claim step. This entry remains controlled by the existing beta and launch gates.

Controlled claim confirmation

When the signed-in review supplies a claim code, run siteplane setup claim inspect --code <code> in the original repository. Show the returned account, workspace and website to the user. After they explicitly approve that concrete request, run siteplane setup claim confirm --code <code> --request <requestId>. Inspection never confirms automatically. A code alone cannot claim a website; the command also requires the original local installation key.

Confirmation saves the receipt in the ignored local credentials file before acknowledging it to the server. If the response is lost, retry the same code and request. Keep the existing project, connection and deployment. Claim revokes guest access and preserves only the still-open setup rights; it does not activate modules or reopen a finished setup. The browser Auth/claim flow is still under development, and the general accountless entry remains closed.

Initial setup

Copy the setup prompt in Siteplane, then run its exact one-time command in the website repository:

npx -y siteplane@<exact-version> setup preflight
npx -y siteplane@<exact-version> init --setup-token <one-time-setup-grant>
npx siteplane setup context

init exchanges the short-lived grant for the run-bound Project Connection and stores it only in the ignored .siteplane/credentials.json. No browser approval is required. The same connection resumes the open setup and review corrections until the owner completes or revokes the setup.

setup context returns the single siteplane.setup-task.v2 task: exact packages, current run, authorized modules/scopes, separate unchanged user instructions, environment provenance and one next action. An initial instruction such as Only prices does not start a correction workflow. The agent integrates Siteplane's existing CMS editing layer, preserving the website; it does not build a separate CMS.

Report observed work with siteplane setup activity --phase inspecting (also integrating, deploying, verifying or repairing). Reports are limited to one per 30 seconds; context polling is not activity. Optional Analytics preparation uses this same connection with explicit authorization. It grants no activation, import, reporting, booking or publishing rights. Standalone bootstrap cannot replace an open task.

setup prepare installs the task's exact packages and creates the narrow official runtime integration. The agent chooses and instruments content, then persists a separate, bounded summary:

For a direct field ID, put siteplane.attrs(fieldId, { routeKey }) on the visible element using the same canonical route pattern as its value call. The value call does not attach DOM metadata. Missing or mismatched DOM routes block apply and the Next build; dynamic pages use their pattern, such as /services/[slug]. Direct attrs defaults to fieldType: "text"; for longText, link and image, pass the matching fieldType explicitly. The value call does not infer it for attrs. setup apply reports field_scan.attrs_field_type_mismatch before any contract write. This type diagnostic remains a scanner warning for normal website builds.

siteplane setup apply --definition editor-definition.json --selection-summary-file selection.txt
siteplane setup deploy --wait

Commit only intended source before deploy. The CLI securely transfers its Production environment, adopts or starts one matching deployment and verifies the actual build and signed runtime. Unchanged resume creates no new deployment. If the linked project has multiple verified, non-redirecting Production domains, select the canonical one on the first run with siteplane setup deploy --wait --production-origin <https-origin>. The CLI rejects foreign, redirect, branch and unverified domains, stores the binding and reuses it on resume. A saved 15-minute provider deadline and operation identity prevent blind retries after response loss. If that deadline expires after the deploy was requested, rerun the same command: each invocation gets a bounded 120-second readback of that same operation. A ready result is adopted; a still-running or unreachable provider remains resumable and never authorizes a second deploy. Uploads use committed source in a temporary checkout; local credentials are never copied into it.

For a lost connection, the owner chooses Replace local connection in the same open setup. Its new grant preserves the Site, Run, runtime key, revalidation generation, selected fields and provider admin-session secret. Completed setup credentials remain closed. Known package/workspace/provider conflicts are diagnosed before writes; support ranges do not trigger automatic framework or package-manager upgrades.

Accountless start

Use setup start for an explicit user request to integrate a website before creating an account. Save the user's exact editing instructions in a text file and pass --instructions-file; inline --instructions is not supported. Omit the file only when the user asks the agent to choose.

Before starting, add .siteplane/credentials.json to the repository’s .gitignore. Start rejects tracked or unprotected credentials before any provisioning request.

npx -y [email protected] setup start --modules editing --instructions-file instructions.txt
npx -y [email protected] setup context

Start performs read-only preflight and saves the installation key and original request privately before the first provisioning call. Select editing,analytics only when explicitly requested. Retry in the same directory with the same request after interruption; configuration without credentials produces a diagnosis, never a silent replacement project. The returned task carries the provisional assignment and deadline. After verification, setup review opens the saved guest review. The user can create an account or sign in from that review; inspect and confirm only their concrete claim request in this repository. Claim preserves the review and returns it to the owner's account; it does not activate editing or analytics.

Approved fields

Run the exact command from Siteplane's compact apply prompt. It authenticates with the local Project Connection and reads the approved snapshot without asking the user to paste its JSON:

siteplane setup fields apply-context --plan-id <plan-id> --snapshot-hash <sha256>
siteplane setup fields apply-context --plan-id <plan-id> --snapshot-hash <sha256> --route / --offset 0

The first call returns route counts. Route calls return at most 25 approved fields and a nextOffset; continue until it is null.

Analytics

siteplane analytics init --agent-client codex
siteplane analytics check
siteplane analytics sync
siteplane analytics test --page-url https://example.com
siteplane analytics import --file provider-export.json

Analytics commands reuse siteplane.config.json and the untracked .siteplane/credentials.json Project Connection. Provider import apply requires --apply --confirm-hash <hash> --yes and an active owner-approved grant.

Booking without Editor setup

import { withSiteplane } from "siteplane/next";
export default withSiteplane(nextConfig, { booking: { site: "<immutable-site-id>" } });

The wrapper adds /booking/:path* as a beforeFiles rewrite to Siteplane and preserves existing rewrite sections. Without siteplane.config.json, it skips Editor scanning, headers and build proof. Use <a href="/booking"> instead of next/link; exclude this path from customer middleware. Configure the public booking address in Siteplane and permit Siteplane/Stripe assets and connections in the customer CSP. siteplane booking check verifies the Site ID in next.config.*. The public API uses Site ID plus allowed Origin; no raw Booking key is needed.