[Artifacts] Document repository creation lifecycle

src/content/docs/artifacts/api/rest-api.mdx

@@ -59,6 +59,7 @@ export type Scope = "read" | "write";
 export type TokenState = "active" | "expired" | "revoked";
 export type ArtifactToken = string;
 export type Cursor = string;
+export type RepoStatus = "creating" | "ready" | "importing" | "forking";
 export type RepoSortField =
 	| "created_at"
 	| "updated_at"
@@ -115,6 +116,10 @@ export interface RepoWithRemote extends RepoInfo {
 	remote: string;
 }
 
+export interface RepoListItem extends RepoWithRemote {
+	status: RepoStatus;
+}
+
 export interface TokenInfo {
 	id: string;
 	scope: Scope;
@@ -189,6 +194,8 @@ curl --request POST "$ARTIFACTS_BASE_URL/repos" \
 
 Create, fork, and import responses return the token string only. The token encodes its expiry directly in the `?expires=` suffix. The separate `POST /tokens` route also returns `expires_at` alongside the plaintext token.
 
+When repo creation returns successfully, provisioning is complete and the repository is ready for follow-up control-plane or Git operations.
+
 ### List repos
 
 Route: `GET /repos?limit=&cursor=&search=&sort=&direction=`
@@ -212,7 +219,7 @@ export interface ListReposQuery {
 	direction?: SortDirection;
 }
 
-export type ListReposResponse = ApiEnvelope<RepoWithRemote[]>;
+export type ListReposResponse = ApiEnvelope<RepoListItem[]>;
 ```
 
 ```bash
@@ -233,7 +240,8 @@ curl "$ARTIFACTS_BASE_URL/repos?limit=20&sort=updated_at&direction=desc" \
 			"last_push_at": "<ISO_TIMESTAMP>",
 			"source": null,
 			"read_only": false,
-			"remote": "https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/default/starter-repo.git"
+			"remote": "https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/default/starter-repo.git",
+			"status": "ready"
 		}
 	],
 	"success": true,
@@ -580,6 +588,14 @@ export interface ApiError {
 }
 ```
 
+Operations that require a ready repository can return `409 Conflict` while repository provisioning is still in progress. These responses include a retriable message and a `Retry-After` header.
+
+| Repository lifecycle state | HTTP status    | Error code |
+| -------------------------- | -------------- | ---------- |
+| Creating                   | `409 Conflict` | `10304`    |
+| Importing                  | `409 Conflict` | `10302`    |
+| Forking                    | `409 Conflict` | `10303`    |
+
 ## Next steps
 
 <LinkCard

src/content/docs/artifacts/api/workers-binding.mdx

@@ -85,14 +85,16 @@ async function createRepo(artifacts: Artifacts) {
 
 </TypeScriptExample>
 
-The returned token encodes its expiry directly in the `?expires=` suffix.
+The returned token encodes its expiry directly in the `?expires=` suffix. When `create()` resolves, the repository has completed provisioning and is ready for follow-up binding or Git operations.
 
 ### `get(name)`
 
 - `name` <Type text="RepoName" /> <MetaInfo text="required" />
 - Returns <Type text="Promise<ArtifactsRepo>" />
 - Throws if the repo does not exist or is not ready yet.
 
+If repository creation is still completing, Artifacts throws an `ArtifactsError` with code `CREATE_IN_PROGRESS`. Repositories that are still importing or forking use their corresponding in-progress error codes.
+
 <TypeScriptExample>
 
 ```ts
@@ -128,7 +130,7 @@ async function listRepos(artifacts: Artifacts) {
 
 </TypeScriptExample>
 
-Each listed repo includes a `status` value of `ready`, `importing`, or `forking`.
+Each listed repo includes a `status` value of `creating`, `ready`, `importing`, or `forking`.
 
 ### `import(params)`
 

src/content/docs/artifacts/get-started/rest-api.mdx

@@ -85,7 +85,7 @@ The response resembles the following:
 
 The REST control-plane base URL and the returned Git remote use different hosts. Use the exact `result.remote` value for Git operations. The example above uses `<ACCOUNT_ID>` as a placeholder for your Cloudflare account ID.
 
-The returned token encodes its expiry directly in the `?expires=` suffix.
+The returned token encodes its expiry directly in the `?expires=` suffix. Once this create call succeeds, the repository is ready to use with the returned remote and token.
 
 Copy the `remote` and `token` values from `result` into local shell variables:
 

src/content/docs/artifacts/get-started/workers.mdx

@@ -180,7 +180,7 @@ The response resembles the following:
 
 Use the exact `remote` value from the response. The example above uses `<ACCOUNT_ID>` as a placeholder for your Cloudflare account ID.
 
-The returned token encodes its expiry directly in the `?expires=` suffix.
+The returned token encodes its expiry directly in the `?expires=` suffix. Once this create call succeeds, the repository is ready to use with the returned remote and token.
 
 Copy the `remote` and `token` values into local shell variables: