Guide first builds through one connected AI conversation

content/(publish)/anonymous-and-claim.mdx

@@ -36,13 +36,13 @@ In `--json` or non-interactive output the key and the claim link are masked. Pas
 
 The claim link is a fragment URL on purpose. Browsers never send a fragment to a server, so the key reaches the claim page without being logged anywhere in between.
 
-From the dashboard, **Drop** does the same thing while signed out. The eyebrow reads **Anonymous drop · Claim it later**, and the result carries a **Claim this space** button.
+From the dashboard, **Drop** does the same thing while signed out. The result explains that the Space has no account owner yet and offers **Save to my account**. Saving it removes the anonymous publishing deadline, lets you find it again and publish updates, and keeps its existing sharing settings unchanged. A Space you already published to your account does not need this step.
 
 Before claiming, you can publish updates, promote or roll back to a version ID from an earlier receipt, and create and revoke scoped viewer links. Listing version history, downloading files, and exporting app data return `space_unclaimed` until someone claims the Space. Run `sf spaces claim` in the publishing directory, sign in, then retry.
 
 ## The clock
 
-An anonymous Space serves for **33 hours and 20 minutes** after creation or the latest publish, then stops. A publish that changes nothing creates no version and leaves the deadline where it was.
+An unclaimed Space normally stops serving **33 hours and 20 minutes after its latest publish that changes files**. A publish that changes nothing creates no version and leaves the deadline where it was. The claim page shows the current deadline. Opening it near expiry can extend the deadline by up to six hours.
 
 It is recoverable after that. The key stays valid for another **7 days**, during which you can still claim the Space and bring it back. After that window the Space is gone.
 
@@ -70,16 +70,16 @@ One more difference. An unclaimed Space accepts every file type, but only *serve
 ## Claim it
 
 <Steps>
-<Step title="Open the claim link">
+<Step title="Open the private link">
 
-Open the `claimUrl` from your receipt, or run `sf spaces claim` in the directory you published from.
+Open the `claimUrl` from your receipt, or run `sf spaces claim` in the directory you published from. The page shows the Space and its current serving deadline.
 
-The claim page header reads **Handed off to you**. Before you claim anything you can already manage **Private links** on it, so you can share the site while you decide.
+The page explains that the Space was published without an account. Saving it to your account keeps it available after the anonymous deadline and lets you find it again and publish updates. Existing sharing settings stay the same.
 
 </Step>
 <Step title="Sign in">
 
-Signed out, the button reads **Sign in & claim**. Signed in, it reads **Claim**, or **Claim & keep access** when the agent that published the Space can stay connected.
+Signed out, choose **Sign in & save this Space**. Signed in, choose **Save to my account**. If eligible, a separate unchecked option lets the publishing agent keep permission to publish updates after the Space is saved. Leaving it unchecked ends that access.
 
 The CLI equivalent starts a browser login for you if you are not signed in.
 

content/meta.ts

@@ -4,6 +4,7 @@ export default defineMeta({
   pages: [
     "index",
     "quickstart",
+    "workshop-start",
     "troubleshooting",
     "setup",
     "concepts",

content/workshop-start.mdx

@@ -0,0 +1,47 @@
+---
+title: Build and share your first Space
+description: Connect an AI tool, describe your idea, and build and share a Space.
+sidebar:
+  label: Your first Space
+---
+
+Connect Spacefast to the AI tool you already use, then make and share one small page.
+
+## Connect your AI tool
+
+Open the setup guide for your tool and follow it through authorization. Keep your email inbox available if Spacefast asks you to sign in.
+
+| Your tool | Setup guide | Before connecting |
+| --- | --- | --- |
+| ChatGPT | [Connect ChatGPT](https://my.spacefast.com/start/chatgpt) | Use ChatGPT on the web. Plugin availability and custom MCP connections depend on your account and workspace security settings. |
+| Claude | [Connect Claude](https://my.spacefast.com/start/claude-app) | Sign in to Claude. On a Team or Enterprise plan, an owner must add the connector first. |
+| Codex | [Connect Codex](https://my.spacefast.com/start/codex) | Use a Codex session where you can install the plugin or configure an MCP server. |
+
+## Start with your idea
+
+In the same conversation where you connected Spacefast, describe what you want to make and ask the AI tool to build and publish it with Spacefast. For example: “Make a simple page for tracking my garden, then publish it privately with Spacefast and give me a link to view it.”
+
+If you are unsure where to start, [browse starter recipes](https://my.spacefast.com/first-recipe) for ideas and prompts you can copy into that conversation.
+
+Review the page the AI tool creates, then ask for changes in the same conversation. Start with fictional or non-sensitive data while you explore.
+
+If your AI tool asks which account or team to use, choose where you want to keep the Space. If the connection fails, return to your tool’s setup guide and reconnect.
+
+## Open and share the result
+
+When publishing finishes, open the link your AI tool returns and check the page. For a private Space, use a viewer link when sharing with someone who does not have account access. Test the link in a private browser window where you are signed out, or ask someone else to open it.
+
+If the agent does not return a viewer link, open the Space in [your dashboard](https://my.spacefast.com), choose **Access → Create share link → Can view**, and test that link while signed out. See [Sharing and access](/access) for other access options.
+
+To make a change, return to the same AI conversation and ask the agent to update the existing Space. Open the viewer link again to check the result.
+
+Publishing through your connected account saves the Space there; it does not require a claim step. If you choose [Drop](https://my.spacefast.com/drop) and publish without signing in, see [Publish without an account](/anonymous-and-claim) for the claim link and expiry details.
+
+## If you get stuck
+
+| What you see | What to do |
+| --- | --- |
+| Spacefast is missing or cannot reach your account | Reopen the setup guide, confirm installation and authorization, and enable Spacefast in the conversation if your tool asks. Check workspace policy if the connection is blocked. |
+| Publishing failed | Record the visible error and job or request ID, check the publish status, then use [Troubleshooting](/troubleshooting). Do not create another Space solely to retry an uncertain publish. |
+| The viewer link says private or returns 403 | In the intended Space, create a **Can view** share link under **Access**. Test that link while signed out. |
+| You published through Drop without signing in | Keep the private claim link and follow [Publish without an account](/anonymous-and-claim) before its displayed deadline. |

scripts/build-llms-index.test.mjs

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { fileURLToPath } from "node:url";
 
 import { buildLlmsIndex, discoveryFileForUrl, routeOf } from "./build-llms-index.mjs";
 import { routesFromSidebar } from "./sidebar-routes.mjs";
@@ -146,7 +147,7 @@ test("throws when the result would exceed the size ceiling", () => {
 
 test("the sidebar parser agrees with the real config", async () => {
   const { readSidebarRoutes } = await import("./sidebar-routes.mjs");
-  const routes = await readSidebarRoutes(new URL("..", import.meta.url).pathname);
+  const routes = await readSidebarRoutes(fileURLToPath(new URL("..", import.meta.url)));
   assert.ok(routes.has("/errors"));
   assert.ok(routes.has("/changelog"));
   assert.ok(routes.size > 40);

scripts/docs-experience.test.mjs

@@ -56,6 +56,19 @@ test("Quickstart gives a no-install route before the CLI steps", async () => {
   assert.match(quickstart.slice(drop, install), /\[Drop\]\(\/docs\/publish#publish\)/u);
 });
 
+test("first Space guide starts with the reader's idea and offers recipes as optional help", async () => {
+  const guide = await builtPage("/workshop-start");
+  const sameConversation = guide.indexOf("same conversation where you connected Spacefast");
+  const directPrompt = guide.indexOf("describe what you want to make and ask the AI tool to build and publish it with Spacefast");
+  const recipe = guide.indexOf("If you are unsure where to start, [browse starter recipes](https://my.spacefast.com/first-recipe)");
+  const viewer = guide.indexOf("For a private Space, use a viewer link when sharing");
+  const recovery = guide.indexOf("If the agent does not return a viewer link");
+  assert.ok(sameConversation >= 0 && directPrompt > sameConversation && recipe > directPrompt);
+  assert.ok(viewer > recipe, "sharing follows the build rather than blocking it");
+  assert.ok(recovery > viewer, "dashboard share-link instructions are a recovery path");
+  assert.match(guide, /Publishing through your connected account saves the Space there; it does not require a claim step\./u);
+});
+
 test("unfamiliar homepage terms have a linked glossary with definitions", async () => {
   const home = await builtPage("/");
   const glossary = await builtPage("/glossary");

scripts/verify-routes.mjs

@@ -289,7 +289,8 @@ for (const [file, present, absent] of sidebarExpectations) {
 }
 // Docs previous/next skip the generated /setup pages; /setup keeps Blume's order.
 for (const [file, prev, next] of [
-  ["troubleshooting/index.html", "/quickstart", "/spaces"],
+  ["workshop-start/index.html", "/quickstart", "/troubleshooting"],
+  ["troubleshooting/index.html", "/workshop-start", "/spaces"],
   ["spaces/index.html", "/troubleshooting", "/versions"],
   ["setup/vscode/index.html", "/setup/cursor", "/setup/github-copilot"],
 ]) {