Enhance SEO, search, and UI with metadata and view transitions

.vitepress/config.ts

@@ -17,14 +17,40 @@ export default defineConfig({
   base: '/',
   title: 'Cycles Docs',
   description: 'Documentation for Cycles, a budget authority for autonomous execution.',
-  srcExclude: ['cycles-protocol/**', 'cycles-server-admin/**'],
+  cleanUrls: true,
+  lang: 'en',
+  titleTemplate: ':title - Cycles Docs',
+  srcExclude: ['README.md', 'cycles-protocol/**', 'cycles-server-admin/**'],
   head: [
     ['link', { rel: 'icon', href: '/runcycles-favicon.png' }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:title', content: 'Cycles Docs' }],
+    ['meta', { property: 'og:description', content: 'Documentation for Cycles, a budget authority for autonomous execution.' }],
+    ['meta', { property: 'og:image', content: 'https://runcycles.io/runcycles-logo-1k.png' }],
+    ['meta', { property: 'og:url', content: 'https://runcycles.io' }],
+    ['meta', { name: 'twitter:card', content: 'summary' }],
   ],
+  sitemap: {
+    hostname: 'https://runcycles.io'
+  },
+  markdown: {
+    image: {
+      lazyLoading: true
+    }
+  },
   lastUpdated: true,
   themeConfig: {
     search: {
-      provider: 'local'
+      provider: 'local',
+      options: {
+        detailedView: true,
+        miniSearch: {
+          searchOptions: {
+            fuzzy: 0.2,
+            prefix: true,
+          }
+        }
+      }
     },
     logo: '/runcycles-logo-64.png',
     externalLinkIcon: true,
@@ -50,7 +76,7 @@ export default defineConfig({
         text: 'API Reference',
         items: [
           { text: 'Cycles Protocol API', link: '/api/' },
-          { text: 'RunCyles Admin API', link: '/admin-api/' },
+          { text: 'RunCycles Admin API', link: '/admin-api/' },
         ],
       },
       { text: 'Protocol', link: 'https://github.com/runcycles/cycles-protocol' },
@@ -68,7 +94,7 @@ export default defineConfig({
       ],
       '/admin-api/': [
         {
-          text: 'RunCyles Admin API',
+          text: 'RunCycles Admin API',
           items: [
             { text: 'Overview', link: '/admin-api/' },
             ...adminApiSidebar.generateSidebarGroups(),
@@ -196,6 +222,10 @@ export default defineConfig({
         }
       ],
     },
+    footer: {
+      message: 'Released under the Apache 2.0 License.',
+      copyright: 'Copyright 2024-present RunCycles'
+    },
     socialLinks: [
       { icon: 'github', link: 'https://github.com/runcycles/docs' }
     ]

.vitepress/theme/index.ts

@@ -1,6 +1,8 @@
 import DefaultTheme from 'vitepress/theme'
 import type { Theme } from 'vitepress'
+import { useRoute } from 'vitepress'
 import { theme, useOpenapi } from 'vitepress-openapi/client'
+import { nextTick, onMounted, watch } from 'vue'
 import 'vitepress-openapi/dist/style.css'
 import spec from '../../public/openapi.json'
 
@@ -9,5 +11,18 @@ export default {
   async enhanceApp({ app }) {
     useOpenapi({ spec })
     theme.enhanceApp({ app })
+  },
+  setup() {
+    const route = useRoute()
+    onMounted(() => {
+      watch(
+        () => route.path,
+        () => {
+          if (document.startViewTransition) {
+            document.startViewTransition(() => nextTick())
+          }
+        }
+      )
+    })
   }
 } satisfies Theme

admin-api/index.md

@@ -2,6 +2,7 @@
 aside: false
 outline: false
 title: Admin API Reference
+description: Interactive API reference for the RunCycles Admin API. Manage budgets, tenants, and governance policies.
 ---
 
 <script setup lang="ts">

api/index.md

@@ -2,6 +2,7 @@
 aside: false
 outline: false
 title: API Reference
+description: Interactive API reference for the Cycles Protocol. Explore endpoints for reservations, commits, events, balances, and more.
 ---
 
 <OASpec />

changelog.md

@@ -1,3 +1,8 @@
+---
+title: "Changelog"
+description: "Release history and version notes for the Cycles Protocol and reference implementations."
+---
+
 # Changelog
 
 Release history for the Cycles Protocol and reference implementations.

concepts/from-observability-to-enforcement-how-teams-evolve-from-dashboards-to-budget-authority.md

@@ -1,3 +1,8 @@
+---
+title: "From Observability to Enforcement: How Teams Evolve from Dashboards to Budget Authority"
+description: "Explore how teams progress from dashboards and alerts to runtime budget enforcement as autonomous systems mature."
+---
+
 # From Observability to Enforcement: How Teams Evolve from Dashboards to Budget Authority
 
 Most teams do not begin with enforcement.

concepts/how-cycles-compares-to-rate-limiters-observability-provider-caps-in-app-counters-and-job-schedulers.md

@@ -1,3 +1,8 @@
+---
+title: "How Cycles Compares to Rate Limiters, Observability, Provider Caps, In-App Counters, and Job Schedulers"
+description: "See how Cycles differs from rate limiters, observability tools, provider caps, in-app counters, and job schedulers for budget governance."
+---
+
 # How Cycles Compares to Rate Limiters, Observability, Provider Caps, In-App Counters, and Job Schedulers
 
 Teams building autonomous systems usually already have some controls in place.

concepts/idempotency-retries-and-concurrency-why-cycles-is-built-for-real-failure-modes.md

@@ -1,3 +1,8 @@
+---
+title: "Idempotency, Retries, and Concurrency: Why Cycles Is Built for Real Failure Modes"
+description: "Learn how Cycles handles idempotency, retries, and concurrency to provide reliable budget enforcement under real-world failure conditions."
+---
+
 # Idempotency, Retries, and Concurrency: Why Cycles Is Built for Real Failure Modes
 
 Most budget systems look correct in the happy path.

concepts/what-cycles-is-not-billing-rate-limiting-orchestration-and-other-category-confusion.md

@@ -1,3 +1,8 @@
+---
+title: "What Cycles Is Not: Billing, Rate Limiting, Orchestration, and Other Category Confusion"
+description: "Understand what Cycles is not — it is not billing, rate limiting, orchestration, or observability, but a budget authority for autonomous execution."
+---
+
 # What Cycles Is Not: Billing, Rate Limiting, Orchestration, and Other Category Confusion
 
 When people first encounter Cycles, they often try to map it onto an existing category.

concepts/why-rate-limits-are-not-enough-for-autonomous-systems.md

@@ -1,3 +1,8 @@
+---
+title: "Why Rate Limits Are Not Enough for Autonomous Systems"
+description: "Learn why rate limits alone cannot govern autonomous systems and how budget authority provides the missing control layer."
+---
+
 # Why Rate Limits Are Not Enough for Autonomous Systems
 
 Autonomous systems do not fail like traditional software.

configuration/client-configuration-reference-for-cycles-spring-boot-starter.md

@@ -1,3 +1,8 @@
+---
+title: "Client Configuration Reference for the Cycles Spring Boot Starter"
+description: "Complete reference for all configuration properties in the Cycles Spring Boot Starter client library."
+---
+
 # Client Configuration Reference for the Cycles Spring Boot Starter
 
 ::: tip Using Python?

configuration/python-client-configuration-reference.md

@@ -1,3 +1,8 @@
+---
+title: "Python Client Configuration Reference"
+description: "Complete reference for all configuration options in the runcycles Python client, including connection, retry, and timeout settings."
+---
+
 # Python Client Configuration Reference
 
 This is the complete reference for all configuration options available in the `runcycles` Python client.

configuration/server-configuration-reference-for-cycles.md

@@ -1,3 +1,8 @@
+---
+title: "Server Configuration Reference for Cycles"
+description: "Complete reference for all Cycles server configuration properties, including server, Redis, and Spring Boot settings."
+---
+
 # Server Configuration Reference for Cycles
 
 This is the complete reference for all configuration properties available in the Cycles server.

configuration/spel-expression-reference-for-cycles.md

@@ -1,3 +1,8 @@
+---
+title: "SpEL Expression Reference for Cycles"
+description: "Comprehensive reference for writing SpEL expressions in the @Cycles annotation to dynamically evaluate estimate and actual costs."
+---
+
 # SpEL Expression Reference for Cycles
 
 The `@Cycles` annotation uses Spring Expression Language (SpEL) to evaluate `estimate` and `actual` cost values dynamically. This page is a comprehensive reference for writing SpEL expressions in Cycles.

configuration/typescript-client-configuration-reference.md

@@ -1,3 +1,8 @@
+---
+title: "TypeScript Client Configuration Reference"
+description: "Complete reference for all configuration options in the runcycles TypeScript client, including connection, retry, and timeout settings."
+---
+
 # TypeScript Client Configuration Reference
 
 This is the complete reference for all configuration options available in the `runcycles` TypeScript client.

how-to/adding-cycles-to-an-existing-application.md

@@ -1,3 +1,8 @@
+---
+title: "Adding Cycles to an Existing Application"
+description: "Incrementally adopt Cycles budget governance in an existing application using shadow mode, single-call wrapping, and staged enforcement."
+---
+
 # Adding Cycles to an Existing Application
 
 This guide covers how to incrementally add budget governance to an application that already makes LLM or API calls. Rather than rewriting your integration layer, you can adopt Cycles in stages.

how-to/api-key-management-in-cycles.md

@@ -1,3 +1,8 @@
+---
+title: "API Key Management in Cycles"
+description: "Learn how to create, manage, and rotate API keys in Cycles, including tenant isolation and key lifecycle states."
+---
+
 # API Key Management in Cycles
 
 Every request to the Cycles server requires an API key. This page explains how API keys work, how to create and manage them, and how they relate to tenant isolation.

how-to/budget-allocation-and-management-in-cycles.md

@@ -1,3 +1,8 @@
+---
+title: "Budget Allocation and Management in Cycles"
+description: "Learn how budget allocation works in Cycles, how to set up scope-level budgets, and how to manage them over time."
+---
+
 # Budget Allocation and Management in Cycles
 
 Before you can enforce budgets with Cycles, budgets need to be allocated to scopes. This page explains how budget allocation works, how to set it up, and how to manage budgets over time.

how-to/choosing-the-right-integration-pattern.md

@@ -1,3 +1,8 @@
+---
+title: "Choosing the Right Integration Pattern"
+description: "Pick the right Cycles integration pattern for your use case: decorator, streaming adapter, middleware, or programmatic client."
+---
+
 # Choosing the Right Integration Pattern
 
 Each Cycles SDK offers multiple integration patterns. This guide helps you pick the right one for your use case.

how-to/common-budget-patterns.md

@@ -1,3 +1,8 @@
+---
+title: "Common Budget Patterns"
+description: "Practical recipes for common budget governance scenarios including per-user daily budgets, per-workflow limits, and scope hierarchies."
+---
+
 # Common Budget Patterns
 
 Practical recipes for common budget governance scenarios. Each pattern shows the scope hierarchy and budget allocation needed.

how-to/cost-estimation-cheat-sheet.md

@@ -1,3 +1,8 @@
+---
+title: "Cost Estimation Cheat Sheet"
+description: "Quick reference for estimating LLM call costs in Cycles, including USD_MICROCENTS conversions and provider pricing tables."
+---
+
 # Cost Estimation Cheat Sheet
 
 This guide answers the most common question when adopting Cycles: **how much should I reserve for a given LLM call?**

how-to/custom-field-resolvers-in-cycles.md

@@ -1,3 +1,8 @@
+---
+title: "Custom Field Resolvers in Cycles"
+description: "Use CyclesFieldResolver to dynamically resolve Subject fields like tenant and workspace at runtime in the Spring Boot Starter."
+---
+
 # Custom Field Resolvers in Cycles
 
 The `CyclesFieldResolver` interface lets you resolve Subject fields dynamically at runtime in the Spring Boot Starter. This is useful when values like tenant, workspace, or agent depend on the current request context, user session, or database lookup.

how-to/error-handling-patterns-in-cycles-client-code.md

@@ -1,3 +1,8 @@
+---
+title: "Error Handling Patterns in Cycles Client Code"
+description: "Handle Cycles protocol errors, transport failures, and budget exceeded responses in Python, Java, and TypeScript client code."
+---
+
 # Error Handling Patterns in Cycles Client Code
 
 This guide covers practical patterns for handling Cycles errors in your application — both with the decorator/annotation and with the programmatic client.

how-to/error-handling-patterns-in-python.md

@@ -1,3 +1,8 @@
+---
+title: "Error Handling Patterns in Python"
+description: "Practical patterns for handling Cycles errors in Python using the @cycles decorator and the programmatic CyclesClient."
+---
+
 # Error Handling Patterns in Python
 
 This guide covers practical patterns for handling Cycles errors in Python applications — both with the `@cycles` decorator and with the programmatic `CyclesClient`.

how-to/error-handling-patterns-in-typescript.md

@@ -1,3 +1,8 @@
+---
+title: "Error Handling Patterns in TypeScript"
+description: "Practical patterns for handling Cycles errors in TypeScript with withCycles, reserveForStream, and the programmatic CyclesClient."
+---
+
 # Error Handling Patterns in TypeScript
 
 This guide covers practical patterns for handling Cycles errors in TypeScript applications — with `withCycles`, `reserveForStream`, and the programmatic `CyclesClient`.

how-to/handling-streaming-responses-with-cycles.md

@@ -1,3 +1,8 @@
+---
+title: "Handling Streaming Responses with Cycles"
+description: "Learn the reserve, stream, and commit pattern for managing budget reservations with streaming LLM responses in Cycles."
+---
+
 # Handling Streaming Responses with Cycles
 
 Streaming LLM responses require special handling because the actual cost is only known after the stream completes. This guide shows the reserve → stream → commit pattern.

how-to/how-to-estimate-exposure-before-execution-practical-reservation-strategies-for-cycles.md

@@ -1,3 +1,8 @@
+---
+title: "How to Estimate Exposure Before Execution: Practical Reservation Strategies for Cycles"
+description: "Practical strategies for estimating budget reservations before execution, including how to handle over- and under-reserving in Cycles."
+---
+
 # How to Estimate Exposure Before Execution: Practical Reservation Strategies for Cycles
 
 One of the first practical questions teams ask when adopting Cycles is:

how-to/how-to-model-tenant-workflow-and-run-budgets-in-cycles.md

@@ -1,3 +1,8 @@
+---
+title: "How to Model Tenant, Workflow, and Run Budgets in Cycles"
+description: "Design budget policies using tenant, workflow, and run scopes to bound autonomous execution across multiple levels in Cycles."
+---
+
 # How to Model Tenant, Workflow, and Run Budgets in Cycles
 
 Once a team understands reserve → commit, the next question is usually:

how-to/how-to-think-about-degradation-paths-in-cycles-deny-downgrade-disable-or-defer.md

@@ -1,3 +1,8 @@
+---
+title: "How to Think About Degradation Paths in Cycles: Deny, Downgrade, Disable, or Defer?"
+description: "Choose the right degradation strategy when a budget boundary is hit: deny, downgrade to a cheaper model, disable features, or defer work."
+---
+
 # How to Think About Degradation Paths in Cycles: Deny, Downgrade, Disable, or Defer?
 
 A budget boundary should not always mean a hard stop.

how-to/integrating-cycles-with-anthropic.md

@@ -1,3 +1,8 @@
+---
+title: "Integrating Cycles with Anthropic"
+description: "Guard Anthropic Messages API calls with Cycles budget reservations, including per-tool-call tracking for agentic workflows."
+---
+
 # Integrating Cycles with Anthropic
 
 This guide shows how to guard Anthropic Messages API calls with Cycles budget reservations, including per-tool-call budget tracking for agentic workflows.

how-to/integrating-cycles-with-aws-bedrock.md

@@ -1,3 +1,8 @@
+---
+title: "Integrating Cycles with AWS Bedrock"
+description: "Add budget governance to AWS Bedrock model invocations using the runcycles TypeScript client."
+---
+
 # Integrating Cycles with AWS Bedrock
 
 This guide shows how to add budget governance to AWS Bedrock model invocations using the `runcycles` TypeScript client and the `@aws-sdk/client-bedrock-runtime`.

how-to/integrating-cycles-with-express.md

@@ -1,3 +1,8 @@
+---
+title: "Integrating Cycles with Express"
+description: "Add budget governance to an Express.js application using reusable middleware and inline patterns with Cycles."
+---
+
 # Integrating Cycles with Express
 
 This guide shows how to add budget governance to an Express.js application using reusable middleware.

how-to/integrating-cycles-with-fastapi.md

@@ -1,3 +1,8 @@
+---
+title: "Integrating Cycles with FastAPI"
+description: "Add budget management to a FastAPI application using middleware, dependency injection, and per-tenant isolation with Cycles."
+---
+
 # Integrating Cycles with FastAPI
 
 This guide shows how to add budget management to a FastAPI application using middleware, dependency injection, per-tenant isolation, and exception handling.

how-to/integrating-cycles-with-google-gemini.md

@@ -1,3 +1,8 @@
+---
+title: "Integrating Cycles with Google Gemini"
+description: "Add budget governance to Google Gemini API calls using the runcycles TypeScript client and the @google/generative-ai SDK."
+---
+
 # Integrating Cycles with Google Gemini
 
 This guide shows how to add budget governance to Google Gemini API calls using the `runcycles` TypeScript client and the `@google/generative-ai` SDK.

how-to/integrating-cycles-with-langchain.md

@@ -1,3 +1,8 @@
+---
+title: "Integrating Cycles with LangChain"
+description: "Add budget management to LangChain apps using a custom callback handler that wraps every LLM call with a Cycles reservation."
+---
+
 # Integrating Cycles with LangChain
 
 This guide shows how to add budget management to LangChain applications using a custom callback handler that wraps every LLM call with a Cycles reservation.