feat: update createSpace docs

src/components/code.tsx

@@ -4,19 +4,22 @@ import { Lang, Theme } from 'shiki'
 const w3upExample = `
 import * as Client from '@web3-storage/w3up-client'
 import { filesFromPaths } from 'files-from-path'
+import * as UcantoClient from '@ucanto/client'
+import { HTTP } from '@ucanto/transport'
+import * as CAR from '@ucanto/transport/car'
 
 const client = await Client.create()
 
 // first time setup!
 if (!Object.keys(client.accounts()).length) {
   // waits for you to click the link in your email to verify your identity
   const account = await client.login('you@example.org')
-  // create a space for your uploads
-  const space = await client.createSpace('lets-go')
+  // create a space for your uploads and authorize the Storacha Gateway by default
+  const space = await client.createSpace('lets-go', {
+    account, // associate this space with your account & configure recovery
+  })
   // save the space to the store, and set as "current"
   await space.save()
-  // associate this space with your account
-  await account.provision(space.did())
 }
 
 // content-address your files

src/pages/download-sc.md

@@ -1,9 +1,6 @@
 # Download Source Code
+
 Download the w3up client source code and start building today. Simply click the download button below to get the complete package.
 Questions or need help? Check out our documentation or reach out to support@storacha.network.
 
-
 [Download here](https://github.com/storacha/w3up/archive/refs/heads/main.zip)
-
-
-

src/pages/how-to/create-space.mdx

@@ -31,8 +31,8 @@ The Space you create can be used to [upload](/how-to/upload/) data using the CLI
 ## Using the JS client
 
 1. Install the client library from npm using your command line: `npm install @web3-storage/w3up-client`.
-2. Call `client.createSpace('Documents')` and wait for the promise to resolve.
+2. Execute `client.createSpace('Documents', { skipGatewayAuthorization: true })` and wait for the promise to resolve.
 
 <Callout>
-  The space must be provisioned by an account before it can be used for uploads. See [our guide](/w3up-client/#create-and-provision-a-space) for details.
+  The space must be provisioned by an account before it can be used for uploads. Additionally, it needs to authorize a Gateway to serve the files you upload. See [our guide](/w3up-client/#create-and-provision-a-space) for more details.
 </Callout>

src/pages/w3cli.mdx

@@ -51,12 +51,15 @@ To create a space using the `w3` command line tool, use the `w3 space create` co
 w3 space create Documents
 ```
 
+If no Gateways are specified (`authorizeGatewayServices`), or if the `skipGatewayAuthorization` flag is not set, the client will automatically grant access to the [Storacha Gateway](https://github.com/storacha/freeway) to serve the content you upload to your space.
+
 The DID for the new space will be printed to the console. It should look something like this, although the part after `did:key` will be unique to your space:
 
 ```bash
 did:key:z6MkixXechJLc3TWibQj9RN6AiFx8VoMY9HNB3Y97WcwK3fm
 ```
 
+
 You can now run `w3 space ls` to show a list of your spaces:
 
 ```bash

src/pages/w3up-client.md

@@ -51,25 +51,64 @@ If your account doesn't have a payment plan yet, you'll be prompted to select on
 await account.plan.wait();
 ```
 
-Spaces can be created using the `createSpace` client method:
+Spaces can be created using the `createSpace` client method. When creating a space, you can specify which Gateways are authorized to serve the content you upload. To achieve this, you must first establish a connection with the desired Gateway. This connection enables the client to publish the necessary delegations that grant the Gateway permission to serve your content. 
+
+If no Gateways are specified (`authorizeGatewayServices`), or if the `skipGatewayAuthorization` flag is not set, the client will automatically grant access to the [Storacha Gateway](https://github.com/storacha/freeway) to serve the content you upload to your space.
+
+To configure other Gateways to serve the content you upload to your new space, follow these steps:
 
 ```js
-const space = await client.createSpace("my-awesome-space", { account });
+import * as UcantoClient from '@ucanto/client'
+import { HTTP } from '@ucanto/transport'
+import * as CAR from '@ucanto/transport/car'
+
+// Connects to Storacha Freeway Gateway
+const storachaGateway = UcantoClient.connect({
+    id: id,
+    codec: CAR.outbound,
+    channel: HTTP.open({ url: new URL('https://freeway.dag.haus') }),
+});
 ```
 
-Alternatively, you can use the w3cli command [`w3 space create`](https://github.com/storacha/w3cli#w3-space-create-name).
-
-The `name` parameter is optional. If provided, it will be stored in your client's local state store and can be used to provide a friendly name for user interfaces.
+Once connected to the Gateway, you can create a space:
 
-If an `account` is provided in the options, a delegated recovery account is automatically created and provisioned, allowing you to store data and delegate access to the recovery account. This means you can access your space from other devices, as long as you have access to your account.
+```js
+const space = await client.createSpace("my-awesome-space", { 
+  account,
+  authorizeGatewayServices: [storachaGateway],
+});
+```
 
-If this is your Agent's first space, it will automatically be set as the "current space." If you already have spaces and want to set the new one as current, you can do so manually:
+If you want to ensure that no Gateway is authorized to serve the content of your space, you can use the `skipGatewayAuthorization` flag:
 
 ```js
-await client.setCurrentSpace(space.did());
+const space = await client.createSpace("my-awesome-space", { 
+  account,
+  skipGatewayAuthorization: true,
+});
 ```
 
-ℹ️ Note: If you do not create the space passing the account parameter you run the risk of losing access to your space!
+Alternatively, you can use the `w3cli` command [`w3 space create`](https://github.com/storacha/w3cli#w3-space-create-name) for a streamlined approach.
+
+**Additional Notes**
+
+1.  :warning: **Important**  :warning:
+    If you do not provide the `account` parameter when creating a space, you risk losing access to your space in case of device loss or credential issues.
+
+2.  **Account Parameter**\
+    Supplying an `account` in the options automatically provisions a delegated recovery account. This enables you to store data securely and delegate access to the recovery account, allowing access to your space from other devices as long as you have your account credentials.
+
+3.  **Name Parameter**\
+    The `name` parameter is optional. If provided, it will be stored in your client’s local state and can serve as a user-friendly identifier for interfaces.
+
+4.  **Current Space**
+
+    - If this is your Agent's first space, it will be automatically set as the "current space."
+    - For additional spaces, you can manually set a new space as the current one using:
+
+    ```js
+    await client.setCurrentSpace(space.did());
+    ```
 
 ## Upload files