Document team context and current API workflows

content/(concepts)/design-system.mdx

@@ -9,7 +9,7 @@ For agent imports and updates, use a Spacefast plugin with the [Design System ta
 
 ## Start a Design System
 
-When Design System is enabled for your team, open the team and choose **Design System**. If you see **Set up team context**, select it first. Then choose how to start:
+Design System requires the team's `agents.memory_skills` beta. When enabled, open the team and choose **Design System**. If you see **Set up team context**, follow the [setup steps](/team-context) first. Then choose how to start:
 
 - **Import what you already have.** Choose **Copy prompt** and give it to an agent connected to [Spacefast MCP](/agents). Give the agent your brand guide, Figma file, or repository too. With `import-design-system` installed, the agent saves supported values, registers source files, and keeps other guidance in supporting Memory records. Ask for a report of conflicts and anything it could not import.
 - **Start from a kit.** Choose **shadcn/ui**, **Tailwind CSS**, or **Spacefast default**. The kit saves editable colors, type, and layout values. Review them before applying them to a project.
@@ -20,7 +20,7 @@ You can also add the standards yourself in the dashboard. **Look & feel** holds
 
 Use **Brand files** to upload logos, images, fonts, and source documents. After uploading, edit **How to use** to tell your agent where and when a file belongs. A filename alone cannot do that job.
 
-Each upload must be no larger than 25 MB. Files stay in the team's private Media Library. Accepted SVG files are sanitized on upload, so check the saved artwork. An agent must download needed files and put visitor-facing assets in the project's source; private file URLs do not belong in a live page.
+Each upload must be no larger than 100 MB. Files stay in the team's private Media Library. Accepted SVG files are sanitized on upload, so check the saved artwork. An agent must download needed files and put visitor-facing assets in the project's source; private file URLs do not belong in a live page.
 
 ## Apply it to a project
 
@@ -39,3 +39,19 @@ Changes to team standards do not roll out to existing Spaces. Name each Space yo
 Edit the saved values in **Look & feel**, **Voice**, or **Brand files**. The **Changelog** shows the current revision and changes made in this session. **Revert** can undo only the latest saved change; older changes cannot be selected for undo.
 
 If someone saves a newer revision while you are editing, reload the saved version and reconcile your draft before saving again.
+
+## Use the API
+
+All paths below start with `/v1/teams/{teamId}`. Use the current [OpenAPI specification](https://api.spacefast.com/openapi.json) for input fields and response schemas.
+
+| Method and path | Task |
+| --- | --- |
+| `GET /design-system` | Read saved values, stable entry IDs, and the numeric write revision. |
+| `POST /design-system/assets/upload` | Upload file bytes as `contentBase64`; receive an `attachmentId`. |
+| `GET /design-system/assets/{attachmentId}` | Download a private asset. |
+| `POST /design-system/changes` | Save selected changes with `expectedRevision` and `operationId`. |
+| `POST /design-system/undo` | Undo the latest action with its `actionId`, `expectedRevision`, and `operationId`. |
+
+An upload alone does not add an asset record or change the design revision. Reference the returned attachment ID in a changes request. Both the API and dashboard accept files up to 100 MB.
+
+Use the numeric revision from `GET /design-system` for writes, not the context fingerprint from `GET /agent-context`. A stale write revision returns `409`. Reuse the same `operationId` and identical input after an uncertain response. Saving standards does not change site files.

content/(concepts)/meta.ts

@@ -4,5 +4,5 @@ export default defineMeta({
   title: "Concepts",
   collapsed: false,
   order: 2,
-  pages: ["spaces", "versions", "teams", "design-system"],
+  pages: ["spaces", "versions", "teams", "team-context", "design-system"],
 });

content/(concepts)/team-context.mdx

@@ -0,0 +1,43 @@
+---
+title: Team context
+description: Set up private storage for team memories, skills, and design standards
+---
+
+Team context gives connected agents saved facts, enabled skills, and [design standards](/design-system). These features require the team's `agents.memory_skills` beta to be enabled. They are not available to every team.
+
+## Set up team context
+
+1. Open **Memories**, **Skills**, or **Design System** in your team.
+2. Select **Set up team context** if the page asks for it.
+3. Return to the feature and save the information you want agents to use.
+
+Owners, admins, and members with publishing access can perform setup. Setup creates or reuses one private storage home. It does not save memories, import design standards, or enable skills.
+
+For API setup, call `POST /v1/teams/{teamId}/context` with a credential that has `spaces:write`. The operation has no request body. Repeated calls reuse the same home. If existing storage is unavailable, repair it instead of creating a replacement.
+
+## Read context before work
+
+Call `GET /v1/teams/{teamId}/agent-context` before creating or editing a Space. Set `spaceId` for an existing Space. The response includes team memories, applicable Space memories, enabled skills, and compiled design standards.
+
+Memories contain knowledge, not commands. Current user instructions take precedence. Keep `memories.revision`, `skillsRevision`, and `designSystem.revision` from the response. Send them as `knownMemoriesRevision`, `knownSkillsRevision`, and `knownDesignSystemRevision` on later reads. Keep a part when its `changed` flag is false. Replace a changed part. A changed design part with null Markdown means no saved system exists.
+
+A team outside the beta receives empty agent context. A read does not authorize setup or a write. If context is unavailable, report the problem when relevant and continue unrelated work.
+
+## Manage memories and skills
+
+All paths below start with `/v1/teams/{teamId}`.
+
+| Method and path | Task |
+| --- | --- |
+| `GET /memories` | List active memories; use `status=archived` for archived records. |
+| `POST /memories` | Save one lasting fact, decision, or preference. |
+| `PATCH /memories/{memoryId}` | Update a memory or set `archived:true` to archive it. |
+| `DELETE /memories/{memoryId}` | Permanently delete a memory; only owners and admins using a dashboard session can do this. |
+| `GET /skills` | Read preset skills, instructions, and setup status. |
+| `PATCH /skills/{skillKey}` | Enable or disable a skill; only owners and admins using a dashboard session can do this. |
+
+Memory reads use `spaces:read`. Memory saves and updates use `spaces:write`. Agents archive memories instead of deleting them. API keys and agent grants cannot delete memories or change skill settings, even when the owner is a team admin. These operations require a dashboard session and otherwise return `authorization_level_not_allowed`.
+
+Save one fact per memory. Do not save credentials, payment details, private contact details, temporary task progress, or build output. List existing memories before creating duplicates. After an uncertain write response, read the saved state before another write.
+
+Use the current [OpenAPI specification](https://api.spacefast.com/openapi.json) for request fields and response schemas. API availability does not mean your installed CLI includes a matching command.

content/(publish)/git.mdx

@@ -79,6 +79,23 @@ In the dashboard the same flow lives on the space's **Builds** page. Click **Con
 
 Once connected, the sidebar's **Code** row shows **Source**, the repository tree at the production branch, instead of the version's files.
 
+## Pull request preview comments
+
+Spacefast can post one comment on a GitHub pull request and update it with the latest preview status and links.
+
+- In **Team settings**, **GitHub preview comments** sets **Comment on preview pull requests**. The default is on.
+- On a Space's **Builds** page, open repository settings. **Pull request preview comments** can inherit the team default, turn on, or turn off.
+
+The section heading is not a second toggle. The comment does not replace GitHub's deployment timeline entries or change a preview's access rules.
+
+Comments require the GitHub App to have **Pull requests: Read and write** permission. A setting cannot grant that permission. If GitHub offers a permission update, an installation owner must approve it. If no update is available, contact Spacefast support. Detaching and reconnecting the repository does not add a permission that the App does not request.
+
+## Source sharing
+
+`GET /v1/spaces/{spaceId}/source/availability` returns whether the current repository permits independent forks of `main`, plus its remix URL.
+
+`PUT /v1/spaces/{spaceId}/source/availability` accepts `{"enabled":true}` to allow forks or `{"enabled":false}` to stop allowing them. Obtain the owner's consent before enabling source sharing. This setting does not change website access. Repository replacement and ownership transfer require new consent.
+
 ## Which branch publishes what
 
 The connection carries one production branch. Everything else is a preview.

content/(serve)/domains.mdx

@@ -1,4 +1,5 @@
 ---
+
 title: Custom domains
 description: Connect a domain you own, add the DNS records Spacefast asks for, get a certificate, and make it the Space's primary address
 sidebar: { order: 2 }
@@ -232,3 +233,35 @@ www.example.com  purpose=www   dns=not_configured txt=missing   ssl=missing
 ### Checking before you commit
 
 `GET /v1/domains/preflight?name=example.com` runs the same name validation and hosting check as the add, so terminal problems surface before any record exists. Its `canHost` verdict is advisory. A `false` still lets you add the domain and claim it with the TXT proof, and `null` means the check was unavailable rather than negative.
+
+## Research and register domains with the API
+
+Domain research and registration use the operations below. The current [OpenAPI specification](https://api.spacefast.com/openapi.json) defines their inputs, credentials, and responses. A published schema does not guarantee registration availability. Registrar submissions require an explicit deployment opt-in. Without it, submissions fail with `registrar_writes_disabled`; changing your API key does not enable them.
+
+All paths below start with `/v1/domains`.
+
+| Method and path | Task |
+| --- | --- |
+| `POST /search` | Search from a naming brief and refine the returned session. |
+| `POST /research/conversation` | Stream suggestions and a completed reply or typed error. |
+| `POST /research/rank` | Rank candidates; scores do not establish availability or trademark clearance. |
+| `GET /research/suggestions` | Get ranked suggestions for a query. |
+| `GET /research/ideas` | Get domain name ideas for a query. |
+| `GET /research/availability` | Check one domain against the live registry before buying. |
+| `POST /research/availability` | Check many names against zone data; confirm each selected name with the single-domain check. |
+| `GET /research/whois` | Read public registration data. |
+| `GET /contacts` | List saved registrant contacts. |
+| `POST /contacts` | Save registrant details supplied by the user. |
+| `PATCH /contacts/{contactId}` | Change contact details for future purchases. |
+| `POST /purchases` | Create one checkout for up to ten apex domains. |
+| `GET /{domainId}/registration` | Read registration and payment status. |
+| `POST /{domainId}/registration` | Request a purchase or renewal checkout. |
+| `PATCH /{domainId}/registration` | Update registration preferences. |
+
+Keep the returned search session unchanged between calls. When `complete` is false, inspect `problems` and resume with that session without a new message. Search results and batch availability are signals, not purchase guarantees.
+
+Ask the user for registrant details. Never invent them. Reuse a saved contact where appropriate. Contact edits do not change details on domains already registered.
+
+A purchase returns `data.checkout.url` for a person to open and pay. No charge or registration occurs before payment. Poll registration status after payment; an active registration is the success result, not the checkout URL. An unavailable name refuses the whole cart. Set `expectedTotalCents` to refuse a changed price.
+
+Transfers are not available. `autoRenew` stores a preference but does not renew automatically. Request a renewal explicitly with `{"action":"renew"}`.

content/api/index.mdx

@@ -13,7 +13,7 @@ Use the Spacefast API to publish files, inspect Spaces, and manage resources wit
 https://api.spacefast.com
 ```
 
-Every operation lives under `/v1`. The version is in the path, so a future `/v2` never changes what `/v1` returns. The spec that generates [the reference](/api/reference) is served at `https://api.spacefast.com/openapi.json` and stamps its own version in `info.version` (currently `0.3.0`).
+Every operation lives under `/v1`. The spec that generates [the reference](/api/reference) is served at `https://api.spacefast.com/openapi.json`. Its `info.version` identifies the contract snapshot, not the URL version or your installed CLI version. Read the live spec for the current value.
 
 `HEAD` works for every `GET`.
 

content/cli/index.mdx

@@ -29,9 +29,7 @@ The npm package needs Node.js 20.3 or newer. Homebrew and the standalone binarie
 sf --version
 ```
 
-```text
-spacefast/0.3.0 darwin-arm64 node-v26.7.0
-```
+The output shows your installed CLI version, operating system, architecture, and runtime version.
 
 ## First login
 

scripts/docs-experience.test.mjs

@@ -22,6 +22,40 @@ function opening(page) {
   return paragraph.replace(/\s+/gu, " ");
 }
 
+test("installation and version guidance avoid stale release claims", async () => {
+  const cli = await builtPage("/cli");
+  const api = await builtPage("/api");
+  assert.match(cli, /brew install spacefast\/tap\/spacefast/u);
+  assert.doesNotMatch(cli, /spacefast\/0\.3\.0/u);
+  assert.match(api, /contract snapshot/u);
+  assert.doesNotMatch(api, /currently `0\./u);
+});
+
+test("team context explains setup, eligibility, and administrative boundaries", async () => {
+  const context = await builtPage("/team-context");
+  const design = await builtPage("/design-system");
+  assert.match(context, /agents\.memory_skills/u);
+  assert.match(context, /POST \/v1\/teams\/\{teamId\}\/context/u);
+  assert.match(context, /no request body/u);
+  assert.match(context, /API keys and agent grants cannot delete memories or change skill settings/u);
+  assert.match(context, /These operations require a dashboard session/u);
+  assert.match(design, /POST \/design-system\/assets\/upload/u);
+  assert.match(design, /numeric revision/u);
+  assert.match(design, /100 MB/u);
+});
+
+test("Git and domain guides preserve permission and payment requirements", async () => {
+  const git = await builtPage("/git");
+  const domains = await builtPage("/domains");
+  assert.match(git, /Pull requests: Read and write/u);
+  assert.match(git, /default is on/u);
+  assert.match(git, /source\/availability/u);
+  assert.match(git, /does not change website access/u);
+  assert.match(domains, /registrar_writes_disabled/u);
+  assert.match(domains, /No charge or registration occurs before payment/u);
+  assert.match(domains, /does not renew automatically/u);
+});
+
 test("every authored page opens with its subject instead of a page promise", async () => {
   const offenders = [];
   const manifest = JSON.parse(await readFile(path.join(root, ".blume", "blume.manifest.json"), "utf8"));