[Artifacts] reframe concepts docs

Author: elithrar

src/content/docs/artifacts/concepts/best-practices.mdx

@@ -63,6 +63,36 @@ Start new repos from a trusted baseline when agents need the same starter files,
 
 This keeps your starting point consistent and makes downstream diffs easier to review. It also lets you merge back only the results you want.
 
+This example forks a reviewed baseline repo into a session-specific repo.
+
+<TypeScriptExample filename="src/index.ts" typescriptFirst={true}>
+
+```ts
+interface Env {
+	ARTIFACTS: Artifacts;
+}
+
+async function forkFromBaseline(env: Env, sessionId: string) {
+	const baseline = await env.ARTIFACTS.get("starter-repo");
+	if (!baseline) {
+		throw new Error("Baseline repo not found");
+	}
+
+	const forked = await baseline.fork(`starter-repo-${sessionId}`, {
+		description: `Fork for session ${sessionId}`,
+		defaultBranchOnly: true,
+		readOnly: false,
+	});
+
+	return {
+		name: forked.name,
+		remote: forked.remote,
+	};
+}
+```
+
+</TypeScriptExample>
+
 ## Scope access narrowly
 
 ### Mint least-privilege repo tokens

src/content/docs/artifacts/concepts/how-artifacts-works.mdx

@@ -1,39 +1,48 @@
 ---
 title: How Artifacts works
-description: Understand the distributed architecture behind Artifacts.
+description: Understand namespaces, repos, and durability.
 pcx_content_type: concept
 sidebar:
   order: 1
 ---
 
-Artifacts is built on [Durable Objects](/durable-objects/). Each repository maps to its own isolated unit of stateful compute.
+Artifacts creates Git repos on demand. Each repo is an isolated service with its own identity, access model, and durable state.
 
-Each repository runs its own Git server and keeps persistent internal state on top of SQLite-backed Durable Object storage. A front-end Worker handles authentication and routing, then dispatches requests to the Durable Object for that repository.
+Each Artifacts repo is its own independent Git server, with its own remote URL, tokens, and durable state.
 
-![Artifacts architecture showing a Worker routing Git and HTTP requests to one Durable Object per repo, with metrics, token cache, and snapshots.](~/assets/images/artifacts/artifacts_diagram_architecture.png)
+## Core model
 
-## Stateful and isolated by repository
+Namespaces are the top-level container for repos. A repo lives inside one namespace, and its name is unique within that namespace.
 
-Each repository in Artifacts is isolated from every other repository. Repository history, writes, and in-memory state do not need to be shared across unrelated workloads.
+A namespace provides the naming and routing boundary for repos. Together, the namespace and repo name form the repo's stable address, and API responses also return a repo ID.
 
-[Durable Objects](/durable-objects/concepts/what-are-durable-objects/) fit this model because they combine stateful compute with durable local storage. Artifacts uses that foundation so repository operations run against a consistent, repo-local view of refs, objects, and metadata.
+Like [Durable Objects](/durable-objects/concepts/what-are-durable-objects/), a repo is a single logical instance that Cloudflare can route to from any region.
 
-Persistent internal state lives on top of [SQLite-backed Durable Object storage](/durable-objects/api/sqlite-storage-api/). This keeps compute and storage together inside the same repository runtime instead of treating Git as a stateless layer in front of external storage.
+Because each repo is isolated, it has its own:
 
-## Replicated and loaded on demand
+- Git history and refs
+- access tokens and remote URL
+- lifecycle and durable state
 
-Artifacts repositories are replicated across multiple Cloudflare data centers by default. Repository snapshots are also written to object storage by default, so durable state does not depend on a single active in-memory instance.
+Repos can be created as needed. This lets Artifacts model many small units of work across separate repos.
 
-A repository does not need to stay active everywhere at all times. Artifacts can load repositories quickly and on the fly when an agent, Worker, or Git client needs access.
+Forking follows the same model. A fork creates a new repo that starts from an existing repo's history, then diverges independently with its own tokens, routing, and lifecycle.
 
-This separates active execution from durable storage. Repository state remains available even when a repository is not currently loaded in memory.
+Access is also repo-scoped. Each repo has its own tokens, and each token can be limited to a specific level of access:
 
-## Addressable globally
+- `read` for clone, fetch, pull, indexing, and review
+- `write` for push and other mutations
 
-Every repository has a unique identity and is addressable globally. Agents can access repositories they are authorized to use no matter where those agents are running.
+Your Worker or API layer decides when to mint those tokens. That keeps authentication and authorization outside the repo while still making the repo usable from Workers, the REST API, or any standard Git client.
 
-Each repository is globally addressable and is not tied to a single machine or location. The entry Worker routes each request to the correct repository runtime, while Artifacts handles placement and loading behind the scenes.
+## Durability
+
+Artifacts is durable by default. A repo does not depend on one process staying alive or on one data center staying available.
+
+Behind the scenes, Cloudflare replicates repo data synchronously across multiple data centers and copies it asynchronously to object storage and snapshots. You do not need to build your own replication, failover, or snapshot pipeline to keep repository state available.
+
+Artifacts handles the Git server lifecycle and storage infrastructure underneath these Git workflows.
 
 ## Learn more
 
-For product updates, refer to the [Artifacts changelog](/artifacts/platform/changelog/). For background on the underlying model, refer to [Durable Objects: Easy, Fast, Correct — Choose three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/) and [Zero-latency SQLite storage in every Durable Object](https://blog.cloudflare.com/sqlite-in-durable-objects/).
+For repo patterns, refer to [Best practices for Artifacts](/artifacts/concepts/best-practices/). For token behavior, refer to [Git protocol](/artifacts/api/git-protocol/). For product updates, refer to the [Artifacts changelog](/artifacts/platform/changelog/).