# Svalta

> Svalta creates websites from starter packs, with managed source workspaces, private previews, and publishing.

A user can begin without an account, keep the site private on a free Svalta subdomain, then register later to claim, connect a domain, or publish.

First read the [guest quickstart](https://www.svalta.com/docs/getting-started/create-site.md). Ask only what the website is for, its name, and the desired style if missing. Suggest defaults and start. Never make the user learn APIs or create an account before a useful preview.

API base URL: `https://www.svalta.com/v1`

## Build first, save later

This deployment allows guest private previews and saving a draft to an account. Studio access and public publishing still require approval. Saving does not approve the account or publish the site.

Give the user a working private preview, inspect it, and fix obvious issues before offering signup. Offer saving once after that preview; remind again only on a request to save/publish or within 24 hours of trial expiry. Read `meta.agent.onboarding` for the current handoff and quotas.

When the user wants to keep the website, `POST /v1/trial-session/claim-handoff` with the trial secret and a fresh idempotency key. Give them `data.claim_url` privately. The link lasts at most one hour, grants only the right to confirm a claim, and opens a human confirmation/registration page. It does not contain the trial editing secret. Never collect passwords, accept terms or complete signup for the user. No email delivery is required for this save handoff; email verification is separate.

Poll `data.status_url` using `X-Svalta-Claim-Handoff: <data.status_token>` (30 requests/minute maximum; prefer every 10–15 seconds while the user is acting). A `claimed` status confirms ownership transfer; stop using the trial secret. An expired token or failed trial request does not prove a claim succeeded. Reconnecting the agent later requires an explicitly authorized, scoped account API key. Never create one automatically.

Source authority: the Svalta source workspace API is the source of truth for managed Astro sites. A local folder, ZIP extract, or agent note is only scratch. Svalta is not a Git hosting remote; do not expect branches, pull requests, pushes, or external CI. Use source workspace revisions, changesets, builds, preview links, releases, and rollback operations.

Content/presentation split: store structured business content and user-owned media in Svalta CMS and media APIs. Use managed Astro source for presentation, layout, styling, client islands, and public build-time data views.

Operating modes: external local agents may fetch a source workspace revision into a disposable local mirror because their editing model is file-based. That mirror is only scratch used to calculate Svalta changesets. The in-product Svalta assistant works directly against the remote source workspace through tools and does not require source files on the user's computer.

Git-shaped vocabulary: source `revision` is commit-like, `base_revision` is the parent revision edited against, source `changeset` is patch-like, `base_revision_stale` is the conflict signal, managed build is CI-like but run by Svalta, and release is deployment-like but preview, publish, hosting, and rollback stay inside Svalta.


## Start Here

- [Create a site from a blueprint](https://www.svalta.com/docs/getting-started/create-site.md): Create the first private site with the access available on this deployment.
- [Resume a trial](https://www.svalta.com/docs/getting-started/resume-trial.md): Continue an unclaimed trial workspace in the same browser/session.
- [Claim a workspace](https://www.svalta.com/docs/getting-started/claim-workspace.md): Register or sign in after the first useful version exists.
- [External agents](https://www.svalta.com/docs/ai-and-automation/external-agents.md): How outside agents should discover and use Svalta.
- [Managed Astro source workspaces](https://www.svalta.com/docs/ai-and-automation/managed-astro-workspaces.md): Source authority, editable paths, build policy, previews, publish, rollback, and resume.

## Agent Workflow

1. Read this file, then the linked Markdown docs before calling mutating routes.
2. For a no-account trial, call `POST /v1/site-starts` with `Accept: application/json`, `X-Svalta-Bootstrap-Key`, and `Idempotency-Key`; store the one-time `data.trial_secret` privately.
3. Resume guest work with `GET /v1/trial-session` plus `X-Svalta-Trial-Secret`; resume claimed work with `GET /v1/projects/{project}/workspace` or `GET /v1/workspaces`.
4. When `workspace_available=true`, read `current_revision.revision_ulid`, list or download files, inspect `.svalta/**`, create a changeset, apply it, create a draft-preview build, poll logs, then preview.
5. Before package, lockfile, hydration, Astro config, or browser-runtime edits on claimed projects, read `GET /v1/projects/{project}/workspace/build-policy`; guest trials cannot call that route, so use the pinned package and hydration contract in the linked Managed Astro docs.
6. Publish only after claim through release operations. Preview links and draft-preview builds do not publish; publish and rollback return synchronous `data.result` envelopes.

## Credentials

- Guest trial: `X-Svalta-Trial-Secret` or the `svalta_trial` cookie on `/v1/trial-session/*` routes.
- Browser account: signed-in Studio session with project access.
- Team token: `Authorization: Bearer <token>` with the needed abilities, including `api:site-starts:create`, `api:workspace:read`, `api:workspace:write`, `api:workspace-builds:read`, `api:workspace-builds:write`, `api:publish:preview`, `api:publish:execute`, or `api:publish:rollback`.
- Mutating calls require `Idempotency-Key`. Reuse a key only for the same method, path, and body.

## Managed Astro Rules

- Writable paths: `src/**`, non-reserved `public/**`, root `astro.config.mjs`, `package.json`, `package-lock.json`, `tsconfig.json`, and root `tailwind.config.*`, `postcss.config.*`, or `svalta.config.*`. Public source files are accepted for build input, but normal visitor assets should use Svalta media APIs because build delivery serves non-HTML artifacts only from `/_assets/astro/{artifact_set_public_id}/...`.
- Common managed presentation source files include `src/**/*.astro`, `src/**/*.ts`, `src/**/*.js`, `src/**/*.tsx`, `src/**/*.jsx`, and `src/**/*.css`.
- Forbidden paths: absolute paths, parent traversal, directory targets, hidden path segments, `.git`, `node_modules`, `.env*`, nested lockfiles, generated `.svalta/**`, and reserved public runtime paths such as `public/robots.txt`, `public/sitemap.xml`, `public/llms.txt`, `public/agents.md`, `public/.well-known/**`, `public/_access/**`, `public/_assets/**`, `public/_media/**`, `public/_preview/**`, and `public/_astro/**`.
- Default build policy: `starter-astro-v1` with `starter-astro-v1-2026-08-28`; default client interactivity: `bundled_client` with `astro-client-interactivity-v1-2026-08-28`.
- Direct packages are pinned by policy. Base packages include `astro@7.2.9`, `@svalta/astro@1.0.0`, `typescript@7.0.2`, `tailwindcss@4.3.3`, and `@tailwindcss/vite@4.3.3`; bundled client adds `@astrojs/react@6.0.4`, `react@19.2.8`, and `react-dom@19.2.8`.
- Supported dynamic behavior: static Astro output from generated Svalta data, same-origin assets under `/_assets/astro/{artifact_set_public_id}/...`, Svalta media API assets, and React islands with `client:load`, `client:idle`, `client:visible`, or `client:media`.
- Not supported: server rendering, adapters, middleware, endpoint routes, Actions, server islands, tenant server APIs, external browser resources, external connect targets, external embeds, client-side redirects, inline event/style attributes, Astro `is:inline` directives, `client:only`, `server:defer`, unsafe eval, and direct `.svalta/**` writes.

## Dynamic-Site Capability Matrix

| Request | First managed Astro release |
| --- | --- |
| Directories, catalogs, calculators, galleries, tabs, accordions, menus, client-side filters, client-side sort/pagination, and lightweight search | Supported when they run from explicitly public build-time data in the browser |
| 100-property real estate directory | Store properties in Svalta CMS records, emit only visitor-public fields through public-data projection, and filter/search with a React client island |
| Simple map/list UI | Conditionally supported with same-origin static data or Svalta-hosted media |
| Visitor writes or contact forms | Use the documented Svalta forms primitive when capability discovery says it is available; no tenant-defined form backend |
| Server-side filtering/search, private visitor personalization, tenant API routes, tenant sessions/auth, arbitrary server jobs, external databases, external map scripts, external tile providers, external API calls, external embeds/assets, or static JSON endpoint routes | Not supported unless a documented Svalta-owned primitive says otherwise |

Rule of thumb: if behavior can run from public data in the browser, build it as a client island. If it requires private data, secrets, per-user server logic, or writes, use a documented Svalta-owned primitive or mark it unsupported. The first client-side search/filter pattern is for small-to-medium public datasets such as the 100-property fixture, not large private catalogs or thousands-of-record faceted search.

## Recovery

- Stale edits: if a changeset returns `status=conflict` and `failure_code=base_revision_stale`, read `current_revision.revision_ulid`, inspect `conflicts[]`, recreate the changeset against that revision, and apply the new draft.
- Compile failures: if a build returns `failure_code=astro_compile_failed`, read the build logs, fix the reported source syntax, import, type, or Astro error, apply a new changeset, then build the new revision. Retrying the same revision will fail the same way.
- Build failures: read `failure_code`, `retryable`, and build logs. Fix dependency, client interactivity, server runtime, external resource, inline markup, public data projection, quota, timeout, memory, output, or file-count issues before retrying.
- Trial setup: follow `trial_session.setup_run.safe_next_action`. If setup is `stale_pending`, check the setup worker when you operate the deployment, otherwise keep polling briefly and report the setup run id and state.
- Rate limits and idempotency: follow `Retry-After` and keep method/path/body/idempotency key stable.

## Starter Packs

Choose starter packs with `presentation_driver=astro` for new sites. `legacy_liquid` entries are compatibility-only and do not imply automatic migration.

- [Business Polished](https://www.svalta.com/docs/api/starter-blueprints.md): `business-polished`; presentation_driver=`astro`; workspace_required=`true` - A higher-polish service-business starter with deliberate navigation, stronger visual defaults, and agent-facing replacement guidance.
- [Business](https://www.svalta.com/docs/api/starter-blueprints.md): `business`; presentation_driver=`astro`; workspace_required=`true` - A polished service-business starter with a marketing home page, service catalog, about page, contact page, and blog.
- [Magazine](https://www.svalta.com/docs/api/starter-blueprints.md): `magazine`; presentation_driver=`astro`; workspace_required=`true` - A publication starter with an editorial home page, article index, contributor profiles, and curated featured-story rails.
- [Directory](https://www.svalta.com/docs/api/starter-blueprints.md): `directory`; presentation_driver=`astro`; workspace_required=`true` - A directory starter with a curated home page, filterable listing index, detail pages, and support content for a boutique real-estate brand.
- [Portfolio](https://www.svalta.com/docs/api/starter-blueprints.md): `portfolio`; presentation_driver=`astro`; workspace_required=`true` - A portfolio starter with a showcase home page, browsable project index, detailed case studies, and support pages for a design studio.

## API Docs

- [API overview](https://www.svalta.com/docs/api.md): Main public API entry point.
- [API authentication](https://www.svalta.com/docs/api/auth.md): Team API tokens, headers, and auth failures.
- [Starter blueprints API](https://www.svalta.com/docs/api/starter-blueprints.md): Discover starter packs.
- [Site starts API](https://www.svalta.com/docs/api/site-starts.md): Start a private trial site from a starter pack.
- [Trial sessions API](https://www.svalta.com/docs/api/trial-sessions.md): Read, edit, recover, and claim guest trial sessions.
- [Workspaces API](https://www.svalta.com/docs/api/workspaces.md): Read, change, build, preview, and diagnose managed Astro source.
- [Preview links API](https://www.svalta.com/docs/api/preview-links.md): Create private links for draft releases and successful draft-preview builds.
- [Releases API](https://www.svalta.com/docs/api/releases.md): Create, validate, publish, schedule, and roll back releases after claim.
- [External agent API](https://www.svalta.com/docs/api/external-agents.md): Cross-cutting operation map for agent integrations.
- [Operations API](https://www.svalta.com/docs/api/operations.md): Poll async setup work.
- [Errors and recovery](https://www.svalta.com/docs/api/errors.md): Error envelope and retry behavior.

## Machine Contracts

- [Documentation search index](https://www.svalta.com/docs/search-index.json): Searchable docs metadata.
- [Operation catalog](https://www.svalta.com/docs/api/contracts/catalog): Machine-readable operation catalog.
- [Ability catalog](https://www.svalta.com/docs/api/contracts/ability-catalog): Capability and ability mapping.
- [Contract specification](https://www.svalta.com/docs/api/contracts/spec): Shared API response contracts.
- [UI/API parity matrix](https://www.svalta.com/docs/api/contracts/parity-matrix): Workflow parity notes.

## Optional

- [Human docs home](https://www.svalta.com/docs): Browser documentation.
- [Markdown docs home](https://www.svalta.com/docs.md): Markdown counterpart for the docs home.

## Svalta forms

Read `public_interaction_primitives.forms` from the workspace build-policy response before creating contact or inquiry forms. The exact endpoint is `/_forms/{public_form_id}/submissions`; `.svalta/forms.json`, `getForms()`, `getForm(key)`, and `@svalta/astro/SvaltaForm.astro` provide the admitted native contract. Preview/trial leads never send email. Use confirmed form and workspace tools; publish the website through Studio. Never invent Astro Actions, endpoints, external form providers, or browser connects.

- [Forms API and Astro examples](https://www.svalta.com/docs/api/forms.md): Schema management, lead privacy, delivery, limits, and assistant workflow.