---
title: "Docs Cloud"
description: "Overview of Docs Cloud projects, deploys, analytics, and the docs.json contract"
canonical_url: "https://docs.farming-labs.dev/docs/cloud"
markdown_url: "https://docs.farming-labs.dev/docs/cloud.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 800
  task: "Connect a Farming Labs docs project to the Docs Cloud repository contract."
  outcome: "docs.config and docs.json agree, secrets remain outside source control, and Cloud checks can inspect the project."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "The repository already contains a working Farming Labs docs project."
    - "The team has Docs Cloud access and knows which project should own the integration."
  files:
    - "docs.config.ts"
    - "docs.config.tsx"
    - "src/lib/docs.config.ts"
    - "docs.json"
    - ".env.local"
  commands:
    - run: "pnpm dlx @farming-labs/docs cloud sync"
      description: "Materialize the serializable repository contract."
    - run: "pnpm dlx @farming-labs/docs cloud check --no-network"
      description: "Compare local config, docs.json, and environment requirements without a network request."
  sideEffects:
    - "cloud sync creates or updates docs.json."
  verification:
    - run: "pnpm dlx @farming-labs/docs cloud check --no-network"
      expect: "The local config loads and docs.json is current with no raw API key value."
  rollback:
    - "Restore the previous docs.config and docs.json from version control."
    - "Remove Cloud-only environment variables when disconnecting the project."
  failureModes:
    - symptom: "docs.json is stale after editing docs.config."
      resolution: "Run cloud sync again and review the generated diff before committing it."
    - symptom: "A raw API key appears in a tracked file."
      resolution: "Revoke the key, remove it from Git history, and keep only the environment variable name in config."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Connect a Farming Labs docs project to the Docs Cloud repository contract.
Outcome: docs.config and docs.json agree, secrets remain outside source control, and Cloud checks can inspect the project.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- The repository already contains a working Farming Labs docs project.
- The team has Docs Cloud access and knows which project should own the integration.

### Files

- `docs.config.ts`
- `docs.config.tsx`
- `src/lib/docs.config.ts`
- `docs.json`
- `.env.local`

### Commands

- `pnpm dlx @farming-labs/docs cloud sync` — Materialize the serializable repository contract.
- `pnpm dlx @farming-labs/docs cloud check --no-network` — Compare local config, docs.json, and environment requirements without a network request.

### Side Effects

- cloud sync creates or updates docs.json.

### Verification

- Run `pnpm dlx @farming-labs/docs cloud check --no-network`
  - Expected: The local config loads and docs.json is current with no raw API key value.

### Rollback

- Restore the previous docs.config and docs.json from version control.
- Remove Cloud-only environment variables when disconnecting the project.

### Failure Modes

- docs.json is stale after editing docs.config. — Recovery: Run cloud sync again and review the generated diff before committing it.
- A raw API key appears in a tracked file. — Recovery: Revoke the key, remove it from Git history, and keep only the environment variable name in config.
<!-- farming-labs:agent-contract:end -->

# Docs Cloud

## Docs Cloud Sync repository contract task

Task: Connect a Farming Labs docs project to the Docs Cloud repository contract.

Expected result: docs.config and docs.json agree, secrets remain outside source control, and Cloud checks can inspect the project.

Exact implementation:

```bash title="terminal"
pnpm dlx @farming-labs/docs cloud sync
```
## Docs Cloud Sync repository prerequisites

- The repository already contains a working Farming Labs docs project.
- The team has Docs Cloud access and knows which project should own the integration.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Docs Cloud Sync repository verification

- Run pnpm dlx @farming-labs/docs cloud check --no-network. Expected: The local config loads and docs.json is current with no raw API key value.
- Failure: docs.json is stale after editing docs.config.
- Recovery: Run cloud sync again and review the generated diff before committing it.
- Rollback: Restore the previous docs.config and docs.json from version control.

## Docs Cloud agent guidance

Use this page when the user asks about this topic: Docs Cloud overview, Cloud project shape, Docs Cloud API keys, docs.config.ts cloud config, docs.json, hosted deploys, analytics, and publish defaults.
Keep answers grounded in the pages linked from this overview. Never suggest committing raw API key values to docs.config.ts, docs.json, or source control.
If the request is about hosted preview deploys, point to /docs/cloud/deploy. If the request is about hosted analytics, project identity, or event storage, point to /docs/cloud/analytics.
If the request is about the docs.json contract itself, point to /docs/guides/docs-json. If the request is about every config option, point to /docs/configuration.
## Docs Cloud Sync repository contract command

Run `pnpm dlx @farming-labs/docs cloud sync` to generate the `docs.json` repository contract. Commit `docs.json`, but keep the raw Docs Cloud API key outside source control.

```bash title="terminal"
pnpm dlx @farming-labs/docs cloud sync
```

## Docs Cloud sync prerequisites

Before Cloud sync, confirm the repository has a working docs config and that the Docs Cloud API key is available only through the configured environment variable.

## Docs Cloud sync verification

After Cloud sync, review the generated `docs.json`, run `pnpm dlx @farming-labs/docs cloud check --no-network`, and confirm no raw key was written to source control.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).