--- title: "Token Efficiency" description: "How @farming-labs/docs keeps your project lean for AI-assisted development — without sacrificing flexibility" canonical_url: "https://docs.farming-labs.dev/docs/token-efficiency" markdown_url: "https://docs.farming-labs.dev/docs/token-efficiency.md" last_updated: "2018-10-20" agent: tokenBudget: 900 task: "Reduce agent context usage while preserving the evidence needed to implement and verify a docs task." outcome: "Retrieval returns the relevant page and executable evidence within the configured UTF-8 context budget." appliesTo: framework: - "nextjs" - "tanstackstart" - "sveltekit" - "astro" - "nuxt" version: - ">=0.2.60" package: - "@farming-labs/docs" prerequisites: - "The docs corpus already has accurate page descriptions, related routes, and task-specific agent contracts." - "Measure a representative retrieval task before compacting content." files: - "docs.config.ts" - "docs.config.tsx" - "src/lib/docs.config.ts" - "app/docs/example/page.mdx" - "app/docs/example/agent.md" - "docs/example/page.mdx" - "docs/example/agent.md" commands: - run: "pnpm exec docs agent compact --changed --dry-run" description: "Preview page-level compaction without writing agent.md files." - run: "pnpm exec docs doctor --agent" description: "Measure retrieval, usefulness, and configured context budgets." sideEffects: - "Running compaction without --dry-run creates or replaces sibling agent.md files used by machine-readable surfaces." verification: - run: "pnpm exec docs doctor --agent" expect: "Golden tasks pass their relevant-source, citation, example, scope, and UTF-8 budget requirements." - description: "Compare the compacted page with its human source and structured contract." expect: "Required commands, constraints, verification, and recovery guidance remain intact." rollback: - "Restore the previous agent.md files and raise or remove page token budgets that discard required evidence." failureModes: - symptom: "Context is under budget but omits the command or expected result." resolution: "Improve retrieval and structured contracts before increasing compaction aggressiveness." - symptom: "The relevant page ranks below generic overview pages." resolution: "Strengthen its task, description, applicability, and related links, then rerun the golden task." --- ## Agent Contract Task: Reduce agent context usage while preserving the evidence needed to implement and verify a docs task. Outcome: Retrieval returns the relevant page and executable evidence within the configured UTF-8 context budget. ### Applies To - Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt` - Version: `>=0.2.60` - Package: `@farming-labs/docs` ### Prerequisites - The docs corpus already has accurate page descriptions, related routes, and task-specific agent contracts. - Measure a representative retrieval task before compacting content. ### Files - `docs.config.ts` - `docs.config.tsx` - `src/lib/docs.config.ts` - `app/docs/example/page.mdx` - `app/docs/example/agent.md` - `docs/example/page.mdx` - `docs/example/agent.md` ### Commands - `pnpm exec docs agent compact --changed --dry-run` — Preview page-level compaction without writing agent.md files. - `pnpm exec docs doctor --agent` — Measure retrieval, usefulness, and configured context budgets. ### Side Effects - Running compaction without --dry-run creates or replaces sibling agent.md files used by machine-readable surfaces. ### Verification - Run `pnpm exec docs doctor --agent` - Expected: Golden tasks pass their relevant-source, citation, example, scope, and UTF-8 budget requirements. - Compare the compacted page with its human source and structured contract. - Expected: Required commands, constraints, verification, and recovery guidance remain intact. ### Rollback - Restore the previous agent.md files and raise or remove page token budgets that discard required evidence. ### Failure Modes - Context is under budget but omits the command or expected result. — Recovery: Improve retrieval and structured contracts before increasing compaction aggressiveness. - The relevant page ranks below generic overview pages. — Recovery: Strengthen its task, description, applicability, and related links, then rerun the golden task. # Token Efficiency ## Token Efficiency task Task: Reduce agent context usage while preserving the evidence needed to implement and verify a docs task. Expected result: Retrieval returns the relevant page and executable evidence within the configured UTF-8 context budget. Exact implementation: ```ts title="docs.config.ts" export default defineDocs({ entry: "docs", agent: { compact: { apiKeyEnv: "DOCS_CLOUD_API_KEY", model: "docs-cloud-compress-v1", aggressiveness: 0.3, protectJson: true, }, }, }); ``` ```bash title="terminal" pnpm exec docs agent compact installation configuration pnpm exec docs agent compact --all ``` ## Token Efficiency prerequisites - The docs corpus already has accurate page descriptions, related routes, and task-specific agent contracts. - Measure a representative retrieval task before compacting content. - Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs. ## Token Efficiency verification - Run pnpm exec docs doctor --agent. Expected: Golden tasks pass their relevant-source, citation, example, scope, and UTF-8 budget requirements. - Compare the compacted page with its human source and structured contract. Expected: Required commands, constraints, verification, and recovery guidance remain intact. - Failure: Context is under budget but omits the command or expected result. - Recovery: Improve retrieval and structured contracts before increasing compaction aggressiveness. - Rollback: Restore the previous agent.md files and raise or remove page token budgets that discard required evidence. ## Token Efficiency agent guidance Measure retrieval before compacting. Set per-page `agent.tokenBudget` in `page.mdx` and configure `agent.compact` in `docs.config.ts[x]`; keep the Docs Cloud key outside source control through `agent.compact.apiKeyEnv`. Preview writes with `pnpm exec docs agent compact --changed --dry-run`, then compact only pages whose task commands, constraints, expected results, and recovery steps remain recoverable. For SvelteKit or Astro, append `--config src/lib/docs.config.ts` to this command and the doctor command below. Run `pnpm exec docs doctor --agent` after compaction. Any configured golden tasks should still satisfy their source, citation, scope, example, and UTF-8 budget requirements. Remember that a generated sibling `agent.md` replaces only machine-readable page output; the rendered `page.mdx` remains unchanged. If a compacted result drops required evidence or lowers the relevant page below an overview, restore the prior `agent.md`, improve its contract and retrieval metadata, and rerun the task before raising compaction aggressiveness. ## docs-cloud-compress-v1 protectJson docs agent compact --all Configure `model: "docs-cloud-compress-v1"` with `protectJson: true`, then run `pnpm exec docs agent compact --all` and verify retrieval with `pnpm exec docs doctor --agent`. ## docs-cloud-compress-v1 agent context model Use `model: "docs-cloud-compress-v1"` for page-level agent compaction and keep its API key outside source control. ## protectJson compact agent context Set `protectJson: true` so compaction preserves structured configuration and schema examples. ## docs agent compact --all token budget verification Run `pnpm exec docs agent compact --all`, then confirm golden retrieval, citations, executable examples, version selection, and context usage with `pnpm exec docs doctor --agent`. ## 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).