Correct publishing, retention, and traffic guidance

content/(concepts)/spaces.mdx

@@ -48,7 +48,7 @@ The substring class survives numeric suffixing, so `paypal-2` fails for the same
 
 Dashboard route names are reserved too, and the reservation is scoped to the position. `settings` is refused as a Space slug and accepted as a team slug. Refused as Space slugs: `agents`, `api-keys`, `billing`, `connect`, `domains`, `drop`, `handoffs`, `members`, `new`, `partners`, `resume`, `settings`, `variables`, `webhooks`. The `422` carries a `details.suggestion` you can take as-is.
 
-A retired slug stays taken. After a rename the old slug belongs to that Space forever, and anyone else asking for it gets `422` `slug_unavailable`.
+A rename keeps the old slug reserved for that Space. Other Spaces asking for it get `422` `slug_unavailable`.
 
 Check before you commit with [`getSlugAvailability`](/api/reference/spaces/getslugavailability).
 

content/(concepts)/versions.mdx

@@ -96,7 +96,7 @@ An explicit promote is never held by a manual policy. That hold only applies to
 
 ## Per-version URLs
 
-Every version that reaches ready gets a permanent hostname of its own, computed once and stored:
+Every version that reaches ready gets a fixed hostname of its own, computed once and stored. It serves that snapshot while the version is retained:
 
 ```text
 https://my-site--v7.space.fast/

content/(publish)/ci.mdx

@@ -123,7 +123,7 @@ Every value shows up on the version, so version history says which commit and wh
           echo "Preview: $(jq -r '.data.version.immutableUrl' receipt.json)"
 ```
 
-`version.immutableUrl` is that version's permanent hostname, which keeps serving that exact build no matter what goes live later. `activation.outcome` comes back `unpromoted`, and promoting it later is one call to the URL in `links.promote`.
+`version.immutableUrl` is that version's fixed hostname. It serves that exact build while the version is retained, regardless of what goes live later. `activation.outcome` comes back `unpromoted`, and promoting it later is one call to the URL in `links.promote`.
 
 A preview on an existing Space refuses `--name`, `--mode`, and a non-`auto` `--spa`, because a preview must not change settings live traffic shares.
 

content/(publish)/publish.mdx

@@ -154,7 +154,7 @@ The parts you actually read:
 | `space.liveUrl` | The URL to open |
 | `version.id`, `version.ref`, `version.number` | The version this publish created |
 | `version.status` | `ready` means finalized |
-| `version.immutableUrl` | The permanent per-version URL, null while finalizing |
+| `version.immutableUrl` | The fixed URL for a retained version, null while finalizing |
 | `activation.outcome` | `activated`, `unpromoted`, `superseded`, or `pending` |
 | `next.action` | `done`, `upload`, `finalize`, or `poll` |
 | `next.url` | Where to go for that action |

content/(reference)/config-file.mdx

@@ -5,7 +5,7 @@ sidebar:
   order: 1
 ---
 
-`sf.jsonc` is the project config Spacefast reads when a version finalizes. This page lists every key the schema accepts. After it you can write the file by hand and know which defaults are real.
+`sf.jsonc` is the project config Spacefast reads when a version finalizes. The reference below lists accepted keys and their defaults.
 
 ## A full example
 

content/(reference)/glossary.mdx

@@ -5,7 +5,7 @@ sidebar:
   order: 3
 ---
 
-The terms below show up starting on the homepage and get used without re-explanation everywhere after. If a word stopped you somewhere else in these docs, it's probably here.
+Definitions of Spacefast terms, with links to the guides that explain them.
 
 ## Ability
 

content/(serve)/caching.mdx

@@ -101,7 +101,7 @@ For the browser, a publish changes nothing that needs waiting on. `max-age=0` me
     ```
   </Step>
   <Step title="Open the version URL">
-    Every version keeps a permanent hostname of its own, which serves that exact build regardless of what is live. See [URLs and hostnames](/urls).
+    Each retained, ready version has a fixed hostname that serves its exact build, regardless of what is live. See [URLs and hostnames](/urls).
   </Step>
 </Steps>
 

content/(serve)/stats.mdx

@@ -17,21 +17,21 @@ Open the Space and go to **Settings → Stats**. A segmented control labelled **
 
 Thirty days is the widest window. There is no longer one.
 
-The page shows two totals, **Requests** and **Views**, then three sections.
+The page shows **Requests**, **Visitor requests**, and **Visitors per day**. Visitor requests include assets, not only page loads. Visitors per day averages complete UTC days in the selected window.
 
 | Section | What it lists |
 | --- | --- |
 | Traffic by period | One row per bucket, with requests, views, and bandwidth |
-| Unique visitors | Distinct visitors per day |
+| Visitors | Daily distinct counts in the period table. The hourly window lists daily counts under the visitor card |
 | Top paths | The busiest paths in the window |
 
-Buckets are labelled in UTC, not your timezone, because that is the boundary the edge measured. Bandwidth is available in the table's field picker but hidden by default, since bandwidth is unlimited on every plan.
+Buckets are labelled in UTC. Bandwidth is available in the table's field picker but hidden by default. Delivery has [plan allowances and usage rates](/usage).
 
 ## What counts as a view
 
 A **request** is any HTTP request the Space answered. A **view** is a request from something that is not a crawler with a status under 400, assets included. So `views` cannot exceed `requests`, and the gap comes from crawlers and responses with a status of 400 or higher.
 
-**Unique visitors** come from a separate daily measurement. It ignores the crawler and status filters, and it merges every hostname mapped to the Space into one count. Daily is the finest resolution available, and days are never summed into a window total. That's why the page lists them one by one instead of showing a single number.
+**Unique visitors** come from a separate daily measurement. It ignores the crawler and status filters, and it merges every hostname mapped to the Space into one count. Daily is the finest resolution available, and days are never summed into a window total. The dashboard shows daily counts and an average over complete days, rather than adding daily visitors into a window total.
 
 **Top paths** and top hosts are capped at 10 entries each.
 
@@ -74,6 +74,6 @@ curl "https://api.spacefast.com/v1/spaces/spc_xxxxxxxx/analytics?window=7d" \
 
 There is no window-level request total in the payload. Sum `series[].requests` for it, which is what the dashboard does.
 
-## This is not Google Analytics
+## Add browser analytics
 
-These numbers are the edge's own accounting, and they are all you get from Spacefast. If you want page-level product analytics, add your own tag. **Customization → Google Analytics** takes a GA4 measurement id or a Tag Manager container id and injects it into every published page. That is a separate feature with a separate switch. See [Customization](/customization).
+For browser analytics, add your own tag. **Customization → Google Analytics** takes a GA4 measurement id or a Tag Manager container id. Its own switch controls whether the tag loads. See [Customization](/customization).

content/(serve)/urls.mdx

@@ -26,7 +26,7 @@ A slug cannot contain `--`, because `--` is the separator between a version or b
 
 ## Version URLs
 
-Every version that reaches ready gets a permanent hostname of its own:
+Every version that reaches ready gets a fixed hostname of its own:
 
 ```text
 https://{label}--v{number}.{apex}/

content/_llms-preamble.md

@@ -23,7 +23,7 @@ source named under Reference surfaces.
 
 ## Set up an agent
 
-Any agent that can fetch a URL learns to publish from one prompt:
+An agent that can fetch URLs and make HTTP requests can follow this publishing guide:
 
 ```
 Fetch https://spacefast.com/setup.md

content/api/long-running-operations.mdx

@@ -122,7 +122,7 @@ curl -sS "https://api.spacefast.com/v1/operations?spaceId=spc_4a7f9c2e8b1d0a6f5c
 | `resourceType` | Everything touching one resource type, for example `space`. |
 | `resourceId` | Everything touching one resource. |
 
-The list is cursor-paginated like every other list. See [Pagination](/api/pagination).
+This list uses cursor pagination. See [Pagination](/api/pagination) for the cursor fields and endpoint-specific exceptions.
 
 Authorization is checked per row through the resource each operation touches, so the feed never shows work your credential could not already reach.
 

content/cli/agents.mdx

@@ -31,7 +31,7 @@ That detects your agent clients, installs the Spacefast skill, and writes MCP co
 
 Pick `--local` instead when you want the MCP server to publish files from your working directory. Pick `--remote --oauth` when you want the editor to own the credential rather than the CLI.
 
-For the tool list, scopes, the `execute` sandbox, and the approval model, see [the MCP server](/agents/mcp-server). For the long form of the setup flow, including what each client gets written where, see [sf setup agent](/agents/sf-setup).
+For API operation tools, Apps, scopes, and saved approvals, see [the MCP server](/agents/mcp-server). For setup steps and the files written for each client, see [sf setup agent](/agents/sf-setup).
 
 ## sf mcp install
 

content/cli/publish.mdx

@@ -104,7 +104,7 @@ Every value here is recorded on the version. On GitHub Actions, GitLab CI, and B
 
 | Flag | Default | What it does |
 | --- | --- | --- |
-| `--show-secret` | off | Print the access URL and claim link in JSON or non-interactive output |
+| `--show-secret` | off | Print secret fields, including the separate Space key. Anonymous preview and claim links are already included outside CI |
 | `--allow-unsupported-platform-features` | off | Publish even when imported platform config includes features Spacefast cannot convert |
 
 ## How publish decides what to do
@@ -165,14 +165,14 @@ The team-wide default for future Spaces is `sf teams defaults`, on the [teams pa
 
 ## Anonymous publish and the claim key
 
-With no login and no linked Space, publish creates an anonymous Space. It saves the key (`sfc_…`), claim URL, and expiry in `.spacefast/state.json`, which the CLI adds to `.gitignore`. The claim link prints once, on the publish that created the Space. Later publishes point at `sf spaces claim` instead.
+With no login and no linked Space, publish creates an anonymous Space. It saves the key (`sfc_…`), claim URL, and expiry in `.spacefast/state.json`, which the CLI adds to `.gitignore`. Anonymous publish receipts include a preview URL, claim URL, expiry, and a message to relay to the person who will claim the Space.
 
 ```bash
 sf spaces claim                                  # claim the Space saved here
 sf continue                                      # swap the key for a durable API key
 ```
 
-In `--json` or non-interactive output the key, its URL form, and the claim URL are all `[REDACTED]` unless you pass `--show-secret`. The `expiresAt` field is never masked, so a script can always tell an anonymous receipt from a permanent one. The clock, the caps, and the claim itself are on [Publish without an account](/anonymous-and-claim).
+Anonymous preview and claim links remain available in `--json` and non-interactive publish output so an agent can relay them. Both links contain the Space key. CI masks them unless you pass `--show-secret`; the separate `claim.key` field follows the CLI's secret-output policy. `expiresAt` remains visible. See [Publish without an account](/anonymous-and-claim) for deadlines and claiming.
 
 ## Examples
 

generated/errors/anonymous_expired.md

@@ -5,7 +5,7 @@ description: "This anonymous space expired before it was claimed."
 
 This anonymous space expired before it was claimed.
 
-**How to resolve:** Publish a fresh space and share its claim link right away this time. If you meant to update a live space, check .spacefast/ (or your saved receipt) for its spaceId. Publish to that space with its credential instead of creating a new space.
+**How to resolve:** Open the saved claim link to recover the Space while its recovery window is still open. If the Space has been purged, publish again and keep the new claim link. To update a different existing Space, select its spaceId and use its credential.
 
 <div data-pagefind-ignore>
 

generated/errors/domain_contact_identity_locked.md

@@ -0,0 +1,40 @@
+---
+title: "domain_contact_identity_locked"
+description: "Only the person who saved this contact can change its name, company name, or email address."
+---
+
+Only the person who saved this contact can change its name, company name, or email address.
+
+**How to resolve:** Ask them to make the change, or save a contact of your own. Other fields, like the address and phone, you can still edit.
+
+<div data-pagefind-ignore>
+
+## Error shape
+
+Every Spacefast API error is an RFC 9457 problem document, served as
+`application/problem+json`.
+
+- `code` is stable and machine-readable.
+- `type` links to this page.
+- `title` is a short label.
+- `status` repeats the HTTP status.
+- `detail` explains this occurrence.
+- `pointer`, when present, is an RFC 6901 JSON Pointer at the offending field in the request body.
+- `details`, when present, carries structured context.
+
+Match on `code`, never on `detail`.
+
+```json
+{
+  "type": "https://spacefast.com/docs/errors/domain_contact_identity_locked",
+  "title": "Domain contact identity locked",
+  "status": 400,
+  "detail": "Only the person who saved this contact can change its name, company name, or email address.",
+  "code": "domain_contact_identity_locked",
+  "requestId": "req_4mz0v8qk"
+}
+```
+
+See the full list of error codes in the [error reference](/errors).
+
+</div>

generated/errors/domain_contact_not_owned.md

@@ -0,0 +1,40 @@
+---
+title: "domain_contact_not_owned"
+description: "This contact belongs to someone else, so you can't register or move a domain to it."
+---
+
+This contact belongs to someone else, so you can't register or move a domain to it.
+
+**How to resolve:** Pass one of your own contacts (`viewerOwns: true` in listDomainContacts), or create one first.
+
+<div data-pagefind-ignore>
+
+## Error shape
+
+Every Spacefast API error is an RFC 9457 problem document, served as
+`application/problem+json`.
+
+- `code` is stable and machine-readable.
+- `type` links to this page.
+- `title` is a short label.
+- `status` repeats the HTTP status.
+- `detail` explains this occurrence.
+- `pointer`, when present, is an RFC 6901 JSON Pointer at the offending field in the request body.
+- `details`, when present, carries structured context.
+
+Match on `code`, never on `detail`.
+
+```json
+{
+  "type": "https://spacefast.com/docs/errors/domain_contact_not_owned",
+  "title": "Domain contact not owned",
+  "status": 400,
+  "detail": "This contact belongs to someone else, so you can't register or move a domain to it.",
+  "code": "domain_contact_not_owned",
+  "requestId": "req_4mz0v8qk"
+}
+```
+
+See the full list of error codes in the [error reference](/errors).
+
+</div>

generated/errors/domain_contact_requires_person.md

@@ -0,0 +1,40 @@
+---
+title: "domain_contact_requires_person"
+description: "Contacts belong to a person, and this credential acts as no one."
+---
+
+Contacts belong to a person, and this credential acts as no one.
+
+**How to resolve:** Team API keys act as the team, not a person. Sign in as yourself with `sf login`, or save the contact in the dashboard.
+
+<div data-pagefind-ignore>
+
+## Error shape
+
+Every Spacefast API error is an RFC 9457 problem document, served as
+`application/problem+json`.
+
+- `code` is stable and machine-readable.
+- `type` links to this page.
+- `title` is a short label.
+- `status` repeats the HTTP status.
+- `detail` explains this occurrence.
+- `pointer`, when present, is an RFC 6901 JSON Pointer at the offending field in the request body.
+- `details`, when present, carries structured context.
+
+Match on `code`, never on `detail`.
+
+```json
+{
+  "type": "https://spacefast.com/docs/errors/domain_contact_requires_person",
+  "title": "Domain contact requires person",
+  "status": 400,
+  "detail": "Contacts belong to a person, and this credential acts as no one.",
+  "code": "domain_contact_requires_person",
+  "requestId": "req_4mz0v8qk"
+}
+```
+
+See the full list of error codes in the [error reference](/errors).
+
+</div>

generated/errors/index.md

@@ -8,7 +8,7 @@ It carries a stable `code` and a `type` URI that links to one of the pages below
 `code` in clients. The meaning of a `code` stays stable, while `detail` text can change.
 Retired codes leave with the API that owns them.
 
-There are 802 error codes in the registry.
+There are 807 error codes in the registry.
 
 | Code | Meaning |
 | --- | --- |
@@ -182,7 +182,10 @@ There are 802 error codes in the registry.
 | [`domain_cart_duplicate`](/errors/domain_cart_duplicate) | The cart lists the same domain more than once. |
 | [`domain_checkout_pending`](/errors/domain_checkout_pending) | One or more of these domains is already waiting on an open payment. |
 | [`domain_checkout_total_changed`](/errors/domain_checkout_total_changed) | The live price of the cart no longer matches the total you expected. |
+| [`domain_contact_identity_locked`](/errors/domain_contact_identity_locked) | Only the person who saved this contact can change its name, company name, or email address. |
 | [`domain_contact_not_found`](/errors/domain_contact_not_found) | The registrant contact does not exist, or belongs to another team. |
+| [`domain_contact_not_owned`](/errors/domain_contact_not_owned) | This contact belongs to someone else, so you can't register or move a domain to it. |
+| [`domain_contact_requires_person`](/errors/domain_contact_requires_person) | Contacts belong to a person, and this credential acts as no one. |
 | [`domain_facet_already_managed`](/errors/domain_facet_already_managed) | This facet of the domain is already managed by Spacefast. |
 | [`domain_facet_external`](/errors/domain_facet_external) | This facet of the domain is managed outside Spacefast. |
 | [`domain_facet_not_applicable`](/errors/domain_facet_not_applicable) | The requested facet does not apply to this domain. |
@@ -415,6 +418,7 @@ There are 802 error codes in the registry.
 | [`repository_commit_unchanged`](/errors/repository_commit_unchanged) | The commit changes no files: the branch already holds this exact tree, so there is nothing to save. |
 | [`repository_patch_invalid`](/errors/repository_patch_invalid) | The repository refused the diff: it is malformed or does not apply to the selected base branch. |
 | [`repository_path_invalid`](/errors/repository_path_invalid) | The repository provider refused the requested file path. |
+| [`repository_reauthorization_required`](/errors/repository_reauthorization_required) | Spacefast can no longer reach this Space's connected repository: its access was revoked, or the Space moved to a team that has not connected it yet. |
 | [`repository_ref_not_found`](/errors/repository_ref_not_found) | The branch, tag, or commit you asked to read does not exist in this repository. A repository nothing has been pushed to yet answers this for its own default branch. |
 | [`repository_resource_not_found`](/errors/repository_resource_not_found) | The requested repository resource does not exist. |
 | [`repository_source_already_initialized`](/errors/repository_source_already_initialized) | The repository already has source history. |
@@ -633,6 +637,7 @@ There are 802 error codes in the registry.
 | [`transfer_push_failed`](/errors/transfer_push_failed) | The source runtime cannot push the space blobs into the transfer bucket. |
 | [`transfer_source_changed`](/errors/transfer_source_changed) | The space changed since the transfer was created, so it must be re-confirmed. |
 | [`transfer_target_same_as_source`](/errors/transfer_target_same_as_source) | The transfer target is the same principal that already owns the space. |
+| [`transfer_team_to_customer_unsupported`](/errors/transfer_team_to_customer_unsupported) | A team's space can only move to another team, not to a partner customer. |
 | [`transfer_verify_failed`](/errors/transfer_verify_failed) | The target runtime cannot verify transferred blob content. |
 | [`unauthorized`](/errors/unauthorized) | The request carried no valid credential. |
 | [`unsupported_publish_media_type`](/errors/unsupported_publish_media_type) | The publish content-type is not supported. |