From 96f0ad956f689ed99e09deaffd9a0b163762297b Mon Sep 17 00:00:00 2001 From: Albert Mavashev Date: Fri, 8 May 2026 10:00:54 -0400 Subject: [PATCH 1/3] chore(seo): broaden quickstart messaging to spend / risky actions / audit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A read-only audit of quickstart/ found 8 pages framing Cycles as a spend/budget tool, missing the other two pillars (risky tool actions and audit gaps). Earlier today we made the same correction in the cycles-client-rust crate metadata, README, and the related blog post (runcycles/cycles-client-rust#31, #32, #33; runcycles/docs#585). This commit applies the same pattern to the public quickstart surface using a light-touch approach: - Frontmatter `description` rewritten on each page to name spend + action + audit (replaces "budget enforcement" framing) - One short ::: tip ::: callout inserted near the top of each page, listing the three pillars with concrete primitives — caps for risky actions, signed events for audit - No title changes, no restructuring, no code-example edits Pages updated (8): Light SDK pattern (4): same callout, identical except for SDK name - quickstart/getting-started-with-the-python-client.md - quickstart/getting-started-with-the-typescript-client.md - quickstart/getting-started-with-the-cycles-spring-boot-starter.md - quickstart/getting-started-with-the-rust-client.md MCP server (1): callout uses MCP tool names (cycles_decide, cycles_create_event) instead of generic primitives - quickstart/getting-started-with-the-mcp-server.md Explainer / strategy (3): same callout + small body tweaks - quickstart/what-is-cycles.md (one-line opener also broadened) - quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md - quickstart/how-to-choose-a-first-cycles-rollout-...md (callout adds a sentence noting which pillar each rollout option primarily addresses, since the page is about choosing scope) Pages intentionally NOT changed (audited and judged appropriate as-is): - quickstart/index.md (already cross-links to /protocol/, /how-to/) - quickstart/end-to-end-tutorial.md (runbook format) - quickstart/architecture-overview-* (technical reference) - quickstart/deploying-* and self-hosting-* (operations focus) - quickstart/mcp-claude-* + cursor + windsurf (setup guides; existing warning correctly clarifies MCP availability ≠ enforcement) Title and URL slug on each page intentionally preserved to keep inbound search-link equity. The two spend-only strategy pages (spring-ai how-to, rollout-choice) keep their existing slugs since those are the canonical search targets for "spring ai budget limit" and "cycles rollout" queries respectively. Diff shape: each file gets a description swap (1 line replaced) and a callout insertion (5-7 lines added). +59 insertions / -9 deletions total across 8 files. Verified: - 83/83 tests pass - npm run build succeeds (98s) - rendered HTML reflects new copy - rendered HTML contains the callout block exactly once per page --- ...ting-started-with-the-cycles-spring-boot-starter.md | 8 +++++++- quickstart/getting-started-with-the-mcp-server.md | 8 +++++++- quickstart/getting-started-with-the-python-client.md | 8 +++++++- quickstart/getting-started-with-the-rust-client.md | 8 +++++++- .../getting-started-with-the-typescript-client.md | 8 +++++++- ...-add-hard-budget-limits-to-spring-ai-with-cycles.md | 8 +++++++- ...ant-budgets-run-budgets-or-model-call-guardrails.md | 10 +++++++++- quickstart/what-is-cycles.md | 10 ++++++++-- 8 files changed, 59 insertions(+), 9 deletions(-) diff --git a/quickstart/getting-started-with-the-cycles-spring-boot-starter.md b/quickstart/getting-started-with-the-cycles-spring-boot-starter.md index 94d373fc..87d9a6bd 100644 --- a/quickstart/getting-started-with-the-cycles-spring-boot-starter.md +++ b/quickstart/getting-started-with-the-cycles-spring-boot-starter.md @@ -1,6 +1,6 @@ --- title: "Getting Started with the Cycles Spring Boot Starter" -description: "Integrate budget enforcement into Spring Boot apps using the @Cycles annotation for automatic reserve, commit, and release lifecycle management." +description: "Integrate runtime authority — spend, action, and audit controls — into Spring Boot AI apps using the @Cycles annotation for automatic reserve, commit, and release lifecycle management." --- # Getting Started with the Cycles Spring Boot Starter @@ -24,6 +24,12 @@ The starter wraps any annotated method in a reserve → execute → commit lifec 3. **After the method returns:** commits actual usage and releases any unused remainder 4. **If the method throws:** releases the reservation to return budget to the pool +::: tip Cycles enforces three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions +- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns +- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +::: + All of this happens transparently through Spring AOP. ## Try the demo app first diff --git a/quickstart/getting-started-with-the-mcp-server.md b/quickstart/getting-started-with-the-mcp-server.md index 9e4e30d7..a76f1f15 100644 --- a/quickstart/getting-started-with-the-mcp-server.md +++ b/quickstart/getting-started-with-the-mcp-server.md @@ -1,6 +1,6 @@ --- title: "Getting Started with the Cycles MCP Server" -description: "Expose Cycles budget tools — reserve, commit, release, decide, check balance — to Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible AI agent. No SDK code changes." +description: "Expose Cycles runtime-authority tools — reserve, commit, release, decide, balance, signed audit events — to Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible AI agent. No SDK code changes." --- # Getting Started with the Cycles MCP Server @@ -22,6 +22,12 @@ Use this for: For deterministic production enforcement, make the Cycles check part of the tool execution path itself — at the SDK, gateway, or framework adapter layer. ::: +::: tip Cycles enforces three runtime-authority pillars +- **Spend** — `cycles_reserve` / `cycles_commit` / `cycles_release` enforce budget before the agent's expensive tool actions +- **Risky actions** — `cycles_decide` returns `Allow` / `AllowWithCaps` / `Deny` with caps for tool denylists, max tokens, max steps, and cooldowns +- **Audit** — `cycles_create_event` and every reserve/commit/release call drop signed events into an exportable ledger for compliance and incident review +::: + ## Prerequisites - **A running Cycles stack** with a tenant, API key, and budget. If you don't have one yet, follow [Deploy the Full Stack](/quickstart/deploying-the-full-cycles-stack) first. diff --git a/quickstart/getting-started-with-the-python-client.md b/quickstart/getting-started-with-the-python-client.md index abaee54a..a67d51be 100644 --- a/quickstart/getting-started-with-the-python-client.md +++ b/quickstart/getting-started-with-the-python-client.md @@ -1,6 +1,6 @@ --- title: "Getting Started with the Python Client" -description: "Add budget enforcement to Python apps using the runcycles package with the @cycles decorator, async support, and programmatic CyclesClient." +description: "Add runtime authority — spend, action, and audit controls — to Python AI apps using the runcycles package. Quickstart for the @cycles decorator, async support, and the programmatic CyclesClient." --- # Getting Started with the Python Client @@ -16,6 +16,12 @@ The decorator wraps any function in a reserve → execute → commit lifecycle: 3. **After the function returns:** commits actual usage and releases any unused remainder 4. **If the function raises:** releases the reservation to return budget to the pool +::: tip Cycles enforces three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions +- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns +- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +::: + ## Prerequisites You need a running Cycles stack with a tenant, API key, and budget. If you don't have one yet, follow [Deploy the Full Stack](/quickstart/deploying-the-full-cycles-stack) first. diff --git a/quickstart/getting-started-with-the-rust-client.md b/quickstart/getting-started-with-the-rust-client.md index 5068c010..ebffa6c6 100644 --- a/quickstart/getting-started-with-the-rust-client.md +++ b/quickstart/getting-started-with-the-rust-client.md @@ -1,6 +1,6 @@ --- title: "Rust Client Quickstart — Budget Control for AI Agents" -description: "Add hard spending limits and runtime authority to Rust AI agents. Quickstart for the Cycles Rust client (runcycles crate) — async, Tokio-native, with reserve-commit budget enforcement for LLM calls, tool actions, and multi-step agent workflows." +description: "Add runtime authority — spend, risky tool actions, and audit gaps — to Rust AI agents. Quickstart for the Cycles Rust client (runcycles crate) — async, Tokio-native, with reserve-commit budget enforcement, RAII-safe caps, and signed audit events." head: - - meta - name: keywords @@ -15,6 +15,12 @@ Building AI agents in Rust with Tokio? You need hard limits on LLM spending and Same wire protocol as the [Python](/quickstart/getting-started-with-the-python-client), [TypeScript](/quickstart/getting-started-with-the-typescript-client), and [Spring Boot](/quickstart/getting-started-with-the-cycles-spring-boot-starter) clients — switch languages without changing your Cycles server. +::: tip Cycles enforces three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions +- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns +- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +::: + The `runcycles` crate provides three levels of budget enforcement for any async Rust application: 1. **`with_cycles()`** — automatic reserve → execute → commit/release (like Python's `@cycles` decorator) diff --git a/quickstart/getting-started-with-the-typescript-client.md b/quickstart/getting-started-with-the-typescript-client.md index 3e9042dd..7731d6da 100644 --- a/quickstart/getting-started-with-the-typescript-client.md +++ b/quickstart/getting-started-with-the-typescript-client.md @@ -1,6 +1,6 @@ --- title: "Getting Started with the TypeScript Client" -description: "Add budget enforcement to Node.js apps using the runcycles TypeScript package with the withCycles HOF, streaming support, and programmatic client." +description: "Add runtime authority — spend, action, and audit controls — to Node.js AI apps using the runcycles TypeScript package. Quickstart for the withCycles HOF, streaming support, and the programmatic client." --- # Getting Started with the TypeScript Client @@ -16,6 +16,12 @@ The `withCycles` HOF wraps any async function in a reserve → execute → commi 3. **After the function returns:** commits actual usage and releases any unused remainder 4. **If the function throws:** releases the reservation to return budget to the pool +::: tip Cycles enforces three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions +- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns +- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +::: + ## Prerequisites You need a running Cycles stack with a tenant, API key, and budget. If you don't have one yet, follow [Deploy the Full Stack](/quickstart/deploying-the-full-cycles-stack) first. diff --git a/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md b/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md index 98fb48c8..7a347c02 100644 --- a/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md +++ b/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md @@ -1,6 +1,6 @@ --- title: "How to Add Hard Budget Limits to Spring AI with Cycles" -description: "Add pre-execution budget enforcement to Spring AI applications using the Cycles reserve-commit lifecycle for model calls, tools, and agent loops." +description: "Add pre-execution runtime authority — spend, action, and audit controls — to Spring AI applications. Cycles reserve-commit lifecycle for model calls, tools, and agent loops, plus caps-based action constraints and signed audit events." --- # How to Add Hard Budget Limits to Spring AI with Cycles @@ -20,6 +20,12 @@ At that point, you need a control layer that can decide **before execution** whe That is where Cycles fits. +::: tip Cycles enforces three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions +- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns +- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +::: + ## The problem In a simple application, one request often maps to one model call. diff --git a/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md b/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md index 7c460797..f32a04e9 100644 --- a/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md +++ b/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md @@ -1,6 +1,6 @@ --- title: "Your First Cycles Rollout: Budgets vs Guardrails" -description: "Decide where to start with Cycles: tenant budgets for cost isolation, run budgets for runaway prevention, or model-call guardrails for low-friction adoption." +description: "Decide where to start with Cycles. Tenant budgets isolate cost; run budgets bound risky agent loops; model-call guardrails add per-call action authority. All three rollouts produce a signed audit trail by default." --- # How to Choose a First Cycles Rollout: Tenant Budgets, Run Budgets, or Model-Call Guardrails? @@ -26,6 +26,14 @@ Each is valid. Each solves a different problem. The best choice depends on the failure mode you are trying to prevent first. +::: tip Cycles enforces three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions +- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns +- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review + +All three rollouts on this page produce a signed audit trail by default. Tenant budgets and run budgets primarily address spend; run budgets also bound risky agent loops; model-call guardrails are the per-call action-authority option. +::: + ## The wrong way to start A common mistake is to begin with a fully generalized policy hierarchy: diff --git a/quickstart/what-is-cycles.md b/quickstart/what-is-cycles.md index 0c16ee7f..fa837a70 100644 --- a/quickstart/what-is-cycles.md +++ b/quickstart/what-is-cycles.md @@ -1,11 +1,17 @@ --- title: "What is Cycles?" -description: "Cycles is a runtime authority for autonomous agents that enforces hard spend limits on AI agents and workflows before expensive actions happen." +description: "Cycles is a runtime authority for autonomous agents — it enforces hard limits on agent spend, risky tool actions, and audit gaps before they happen." --- # What is Cycles? -Cycles is a **runtime authority for autonomous agents**. It enforces hard limits on agent spend and actions — **before they happen, not after**. +Cycles is a **runtime authority for autonomous agents**. It enforces hard limits on agent spend and risky actions — **before they happen, not after** — and produces a signed audit trail of every decision. + +::: tip Cycles enforces three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions +- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns +- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +::: ## Choose your path From 23fc50cb7cd570d4fac3138c481ac89201fb2b22 Mon Sep 17 00:00:00 2001 From: Albert Mavashev Date: Fri, 8 May 2026 10:15:25 -0400 Subject: [PATCH 2/3] =?UTF-8?q?chore(seo):=20review=20fixes=20=E2=80=94=20?= =?UTF-8?q?protocol=20casing,=20structured=20records,=20description=20trim?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Five categorical fixes across the 8 quickstart pages from the previous commit: 1. Frontmatter descriptions trimmed to 130-144 chars (target ~140). Tighter snippets in search results. 2. Decision values use the protocol's actual UPPER casing in all callouts: ALLOW / ALLOW_WITH_CAPS / DENY (was Allow / AllowWithCaps / Deny). Aligns with cycles-protocol-v0.yaml and the wire format. 3. Audit bullet de-overpromised: "every reservation, commit, release, and decision is a signed event" → "reservations, commits, releases, and decisions produce structured records for compliance and incident review". Signing is configurable per deployment; "structured records" is what the protocol actually guarantees. Same fix applied to the body lead in what-is-cycles.md. 4. Rollout page (how-to-choose-a-first-cycles-rollout-...md): model- call guardrails reframed as "per-call LLM spend enforcement" rather than per-call action authority. That's what guardrails primarily address; action authority is the run-budget / caps surface. Description updated to match. 5. Rust SDK code examples in the body preserved with PascalCase enum names (Decision::Allow, etc.) — those are the language-idiomatic identifiers; only the protocol-side decision values in the callout change to UPPER. Plus minor accuracy improvements: - Added "tool allowlists/" alongside denylists in the caps bullet (protocol supports both) - MCP audit bullet adds "for export" to point at events service / webhook delivery as the canonical export path - what-is-cycles.md body lead rewritten: "produces a signed audit trail" → "records the evidence operators need to audit decisions later" Verified: 83/83 tests pass; production build succeeds (95s). --- ...getting-started-with-the-cycles-spring-boot-starter.md | 6 +++--- quickstart/getting-started-with-the-mcp-server.md | 6 +++--- quickstart/getting-started-with-the-python-client.md | 6 +++--- quickstart/getting-started-with-the-rust-client.md | 6 +++--- quickstart/getting-started-with-the-typescript-client.md | 6 +++--- ...-to-add-hard-budget-limits-to-spring-ai-with-cycles.md | 6 +++--- ...tenant-budgets-run-budgets-or-model-call-guardrails.md | 8 ++++---- quickstart/what-is-cycles.md | 8 ++++---- 8 files changed, 26 insertions(+), 26 deletions(-) diff --git a/quickstart/getting-started-with-the-cycles-spring-boot-starter.md b/quickstart/getting-started-with-the-cycles-spring-boot-starter.md index 87d9a6bd..e21dd9bd 100644 --- a/quickstart/getting-started-with-the-cycles-spring-boot-starter.md +++ b/quickstart/getting-started-with-the-cycles-spring-boot-starter.md @@ -1,6 +1,6 @@ --- title: "Getting Started with the Cycles Spring Boot Starter" -description: "Integrate runtime authority — spend, action, and audit controls — into Spring Boot AI apps using the @Cycles annotation for automatic reserve, commit, and release lifecycle management." +description: "Add runtime authority to Spring Boot AI apps with @Cycles: reserve, commit, release, caps-aware decisions, and structured audit records." --- # Getting Started with the Cycles Spring Boot Starter @@ -26,8 +26,8 @@ The starter wraps any annotated method in a reserve → execute → commit lifec ::: tip Cycles enforces three runtime-authority pillars - **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns -- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review ::: All of this happens transparently through Spring AOP. diff --git a/quickstart/getting-started-with-the-mcp-server.md b/quickstart/getting-started-with-the-mcp-server.md index a76f1f15..411040a5 100644 --- a/quickstart/getting-started-with-the-mcp-server.md +++ b/quickstart/getting-started-with-the-mcp-server.md @@ -1,6 +1,6 @@ --- title: "Getting Started with the Cycles MCP Server" -description: "Expose Cycles runtime-authority tools — reserve, commit, release, decide, balance, signed audit events — to Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible AI agent. No SDK code changes." +description: "Expose Cycles runtime-authority tools — reserve, commit, release, decide, balance, and events — to Claude, Cursor, Windsurf, and MCP agents." --- # Getting Started with the Cycles MCP Server @@ -24,8 +24,8 @@ For deterministic production enforcement, make the Cycles check part of the tool ::: tip Cycles enforces three runtime-authority pillars - **Spend** — `cycles_reserve` / `cycles_commit` / `cycles_release` enforce budget before the agent's expensive tool actions -- **Risky actions** — `cycles_decide` returns `Allow` / `AllowWithCaps` / `Deny` with caps for tool denylists, max tokens, max steps, and cooldowns -- **Audit** — `cycles_create_event` and every reserve/commit/release call drop signed events into an exportable ledger for compliance and incident review +- **Risky actions** — `cycles_decide` returns `ALLOW` / `ALLOW_WITH_CAPS` / `DENY` with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — `cycles_create_event` and reserve/commit/release calls create structured records for export, compliance, and incident review ::: ## Prerequisites diff --git a/quickstart/getting-started-with-the-python-client.md b/quickstart/getting-started-with-the-python-client.md index a67d51be..7adc5536 100644 --- a/quickstart/getting-started-with-the-python-client.md +++ b/quickstart/getting-started-with-the-python-client.md @@ -1,6 +1,6 @@ --- title: "Getting Started with the Python Client" -description: "Add runtime authority — spend, action, and audit controls — to Python AI apps using the runcycles package. Quickstart for the @cycles decorator, async support, and the programmatic CyclesClient." +description: "Add runtime authority to Python AI apps with runcycles: @cycles, async support, reserve-commit lifecycle, caps, and audit records." --- # Getting Started with the Python Client @@ -18,8 +18,8 @@ The decorator wraps any function in a reserve → execute → commit lifecycle: ::: tip Cycles enforces three runtime-authority pillars - **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns -- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review ::: ## Prerequisites diff --git a/quickstart/getting-started-with-the-rust-client.md b/quickstart/getting-started-with-the-rust-client.md index ebffa6c6..21068084 100644 --- a/quickstart/getting-started-with-the-rust-client.md +++ b/quickstart/getting-started-with-the-rust-client.md @@ -1,6 +1,6 @@ --- title: "Rust Client Quickstart — Budget Control for AI Agents" -description: "Add runtime authority — spend, risky tool actions, and audit gaps — to Rust AI agents. Quickstart for the Cycles Rust client (runcycles crate) — async, Tokio-native, with reserve-commit budget enforcement, RAII-safe caps, and signed audit events." +description: "Add runtime authority to Rust AI agents with the runcycles crate: async reserve-commit enforcement, RAII guards, caps, and audit records." head: - - meta - name: keywords @@ -17,8 +17,8 @@ Same wire protocol as the [Python](/quickstart/getting-started-with-the-python-c ::: tip Cycles enforces three runtime-authority pillars - **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns -- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review ::: The `runcycles` crate provides three levels of budget enforcement for any async Rust application: diff --git a/quickstart/getting-started-with-the-typescript-client.md b/quickstart/getting-started-with-the-typescript-client.md index 7731d6da..6aa049c0 100644 --- a/quickstart/getting-started-with-the-typescript-client.md +++ b/quickstart/getting-started-with-the-typescript-client.md @@ -1,6 +1,6 @@ --- title: "Getting Started with the TypeScript Client" -description: "Add runtime authority — spend, action, and audit controls — to Node.js AI apps using the runcycles TypeScript package. Quickstart for the withCycles HOF, streaming support, and the programmatic client." +description: "Add runtime authority to Node.js AI apps with runcycles: withCycles, streaming support, reserve-commit enforcement, caps, and audit records." --- # Getting Started with the TypeScript Client @@ -18,8 +18,8 @@ The `withCycles` HOF wraps any async function in a reserve → execute → commi ::: tip Cycles enforces three runtime-authority pillars - **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns -- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review ::: ## Prerequisites diff --git a/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md b/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md index 7a347c02..d31de579 100644 --- a/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md +++ b/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md @@ -1,6 +1,6 @@ --- title: "How to Add Hard Budget Limits to Spring AI with Cycles" -description: "Add pre-execution runtime authority — spend, action, and audit controls — to Spring AI applications. Cycles reserve-commit lifecycle for model calls, tools, and agent loops, plus caps-based action constraints and signed audit events." +description: "Add pre-execution runtime authority to Spring AI: reserve-commit enforcement for model calls, tools, agent loops, caps, and audit records." --- # How to Add Hard Budget Limits to Spring AI with Cycles @@ -22,8 +22,8 @@ That is where Cycles fits. ::: tip Cycles enforces three runtime-authority pillars - **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns -- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review ::: ## The problem diff --git a/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md b/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md index f32a04e9..8dd7d673 100644 --- a/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md +++ b/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md @@ -1,6 +1,6 @@ --- title: "Your First Cycles Rollout: Budgets vs Guardrails" -description: "Decide where to start with Cycles. Tenant budgets isolate cost; run budgets bound risky agent loops; model-call guardrails add per-call action authority. All three rollouts produce a signed audit trail by default." +description: "Choose your first Cycles rollout: tenant budgets for cost isolation, run budgets for runaway loops, or model-call guardrails for LLM spend." --- # How to Choose a First Cycles Rollout: Tenant Budgets, Run Budgets, or Model-Call Guardrails? @@ -28,10 +28,10 @@ The best choice depends on the failure mode you are trying to prevent first. ::: tip Cycles enforces three runtime-authority pillars - **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns -- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review -All three rollouts on this page produce a signed audit trail by default. Tenant budgets and run budgets primarily address spend; run budgets also bound risky agent loops; model-call guardrails are the per-call action-authority option. +All three rollouts on this page produce structured audit records. Tenant budgets and run budgets primarily address spend; run budgets also bound risky agent loops; model-call guardrails are the lowest-friction way to start with per-call LLM spend enforcement. ::: ## The wrong way to start diff --git a/quickstart/what-is-cycles.md b/quickstart/what-is-cycles.md index fa837a70..7cf75227 100644 --- a/quickstart/what-is-cycles.md +++ b/quickstart/what-is-cycles.md @@ -1,16 +1,16 @@ --- title: "What is Cycles?" -description: "Cycles is a runtime authority for autonomous agents — it enforces hard limits on agent spend, risky tool actions, and audit gaps before they happen." +description: "Cycles is a runtime authority for autonomous agents: it enforces spend and risky-action limits before execution and records audit evidence." --- # What is Cycles? -Cycles is a **runtime authority for autonomous agents**. It enforces hard limits on agent spend and risky actions — **before they happen, not after** — and produces a signed audit trail of every decision. +Cycles is a **runtime authority for autonomous agents**. It enforces hard limits on agent spend and risky actions — **before they happen, not after** — and records the evidence operators need to audit decisions later. ::: tip Cycles enforces three runtime-authority pillars - **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`Allow` / `AllowWithCaps` / `Deny`) with caps for tool denylists, max tokens, max steps, and cooldowns -- **Audit** — every reservation, commit, release, and decision is a signed event for compliance and incident review +- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review ::: ## Choose your path From d265b42a1edb909b303b888d705586d8667ec1fd Mon Sep 17 00:00:00 2001 From: Albert Mavashev Date: Fri, 8 May 2026 10:32:46 -0400 Subject: [PATCH 3/3] chore(seo): refine quickstart runtime authority messaging Tighten quickstart SEO descriptions and align runtime authority framing with protocol terminology. Clarify that Cycles applies to instrumented paths, includes RISK_POINTS action authority, and creates structured audit records without overclaiming signed audit semantics. --- ...ting-started-with-the-cycles-spring-boot-starter.md | 8 ++++---- quickstart/getting-started-with-the-mcp-server.md | 10 +++++----- quickstart/getting-started-with-the-python-client.md | 8 ++++---- quickstart/getting-started-with-the-rust-client.md | 8 ++++---- .../getting-started-with-the-typescript-client.md | 8 ++++---- ...-add-hard-budget-limits-to-spring-ai-with-cycles.md | 8 ++++---- ...ant-budgets-run-budgets-or-model-call-guardrails.md | 10 +++++----- quickstart/what-is-cycles.md | 8 ++++---- 8 files changed, 34 insertions(+), 34 deletions(-) diff --git a/quickstart/getting-started-with-the-cycles-spring-boot-starter.md b/quickstart/getting-started-with-the-cycles-spring-boot-starter.md index e21dd9bd..6b7928c6 100644 --- a/quickstart/getting-started-with-the-cycles-spring-boot-starter.md +++ b/quickstart/getting-started-with-the-cycles-spring-boot-starter.md @@ -24,10 +24,10 @@ The starter wraps any annotated method in a reserve → execute → commit lifec 3. **After the method returns:** commits actual usage and releases any unused remainder 4. **If the method throws:** releases the reservation to return budget to the pool -::: tip Cycles enforces three runtime-authority pillars -- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns -- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review +::: tip Cycles provides three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before instrumented LLM calls and tool actions +- **Risky actions** — `ALLOW` / `ALLOW_WITH_CAPS` / `DENY` decisions with `RISK_POINTS` budgets and caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions create structured records for compliance, attribution, and incident review ::: All of this happens transparently through Spring AOP. diff --git a/quickstart/getting-started-with-the-mcp-server.md b/quickstart/getting-started-with-the-mcp-server.md index 411040a5..11385b4d 100644 --- a/quickstart/getting-started-with-the-mcp-server.md +++ b/quickstart/getting-started-with-the-mcp-server.md @@ -1,6 +1,6 @@ --- title: "Getting Started with the Cycles MCP Server" -description: "Expose Cycles runtime-authority tools — reserve, commit, release, decide, balance, and events — to Claude, Cursor, Windsurf, and MCP agents." +description: "Expose Cycles runtime-authority tools to Claude Desktop, Claude Code, Cursor, Windsurf, and MCP agents: reserve, commit, decide, events." --- # Getting Started with the Cycles MCP Server @@ -22,10 +22,10 @@ Use this for: For deterministic production enforcement, make the Cycles check part of the tool execution path itself — at the SDK, gateway, or framework adapter layer. ::: -::: tip Cycles enforces three runtime-authority pillars -- **Spend** — `cycles_reserve` / `cycles_commit` / `cycles_release` enforce budget before the agent's expensive tool actions -- **Risky actions** — `cycles_decide` returns `ALLOW` / `ALLOW_WITH_CAPS` / `DENY` with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns -- **Audit** — `cycles_create_event` and reserve/commit/release calls create structured records for export, compliance, and incident review +::: tip Cycles provides three runtime-authority pillars +- **Spend** — `cycles_reserve` / `cycles_commit` / `cycles_release` enforce budget before instrumented agent actions +- **Risky actions** — `cycles_decide` returns `ALLOW` / `ALLOW_WITH_CAPS` / `DENY` with `RISK_POINTS` budgets and caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — `cycles_create_event` and reserve/commit/release calls create structured records for export, compliance, attribution, and incident review ::: ## Prerequisites diff --git a/quickstart/getting-started-with-the-python-client.md b/quickstart/getting-started-with-the-python-client.md index 7adc5536..d96ad921 100644 --- a/quickstart/getting-started-with-the-python-client.md +++ b/quickstart/getting-started-with-the-python-client.md @@ -16,10 +16,10 @@ The decorator wraps any function in a reserve → execute → commit lifecycle: 3. **After the function returns:** commits actual usage and releases any unused remainder 4. **If the function raises:** releases the reservation to return budget to the pool -::: tip Cycles enforces three runtime-authority pillars -- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns -- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review +::: tip Cycles provides three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before instrumented LLM calls and tool actions +- **Risky actions** — `ALLOW` / `ALLOW_WITH_CAPS` / `DENY` decisions with `RISK_POINTS` budgets and caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions create structured records for compliance, attribution, and incident review ::: ## Prerequisites diff --git a/quickstart/getting-started-with-the-rust-client.md b/quickstart/getting-started-with-the-rust-client.md index 21068084..ffeef29b 100644 --- a/quickstart/getting-started-with-the-rust-client.md +++ b/quickstart/getting-started-with-the-rust-client.md @@ -15,10 +15,10 @@ Building AI agents in Rust with Tokio? You need hard limits on LLM spending and Same wire protocol as the [Python](/quickstart/getting-started-with-the-python-client), [TypeScript](/quickstart/getting-started-with-the-typescript-client), and [Spring Boot](/quickstart/getting-started-with-the-cycles-spring-boot-starter) clients — switch languages without changing your Cycles server. -::: tip Cycles enforces three runtime-authority pillars -- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns -- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review +::: tip Cycles provides three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before instrumented LLM calls and tool actions +- **Risky actions** — `ALLOW` / `ALLOW_WITH_CAPS` / `DENY` decisions with `RISK_POINTS` budgets and caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions create structured records for compliance, attribution, and incident review ::: The `runcycles` crate provides three levels of budget enforcement for any async Rust application: diff --git a/quickstart/getting-started-with-the-typescript-client.md b/quickstart/getting-started-with-the-typescript-client.md index 6aa049c0..5677c93f 100644 --- a/quickstart/getting-started-with-the-typescript-client.md +++ b/quickstart/getting-started-with-the-typescript-client.md @@ -16,10 +16,10 @@ The `withCycles` HOF wraps any async function in a reserve → execute → commi 3. **After the function returns:** commits actual usage and releases any unused remainder 4. **If the function throws:** releases the reservation to return budget to the pool -::: tip Cycles enforces three runtime-authority pillars -- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns -- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review +::: tip Cycles provides three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before instrumented LLM calls and tool actions +- **Risky actions** — `ALLOW` / `ALLOW_WITH_CAPS` / `DENY` decisions with `RISK_POINTS` budgets and caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions create structured records for compliance, attribution, and incident review ::: ## Prerequisites diff --git a/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md b/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md index d31de579..d53fd8ed 100644 --- a/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md +++ b/quickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.md @@ -20,10 +20,10 @@ At that point, you need a control layer that can decide **before execution** whe That is where Cycles fits. -::: tip Cycles enforces three runtime-authority pillars -- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns -- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review +::: tip Cycles provides three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before instrumented LLM calls and tool actions +- **Risky actions** — `ALLOW` / `ALLOW_WITH_CAPS` / `DENY` decisions with `RISK_POINTS` budgets and caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions create structured records for compliance, attribution, and incident review ::: ## The problem diff --git a/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md b/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md index 8dd7d673..23fdf726 100644 --- a/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md +++ b/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md @@ -26,12 +26,12 @@ Each is valid. Each solves a different problem. The best choice depends on the failure mode you are trying to prevent first. -::: tip Cycles enforces three runtime-authority pillars -- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns -- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review +::: tip Cycles provides three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before instrumented LLM calls and tool actions +- **Risky actions** — `ALLOW` / `ALLOW_WITH_CAPS` / `DENY` decisions with `RISK_POINTS` budgets and caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions create structured records for compliance, attribution, and incident review -All three rollouts on this page produce structured audit records. Tenant budgets and run budgets primarily address spend; run budgets also bound risky agent loops; model-call guardrails are the lowest-friction way to start with per-call LLM spend enforcement. +All three rollouts on this page create structured audit records. Tenant budgets and run budgets primarily address spend; run budgets also bound risky agent loops; model-call guardrails are the lowest-friction way to start with per-call LLM spend enforcement. ::: ## The wrong way to start diff --git a/quickstart/what-is-cycles.md b/quickstart/what-is-cycles.md index 7cf75227..bc3869af 100644 --- a/quickstart/what-is-cycles.md +++ b/quickstart/what-is-cycles.md @@ -7,10 +7,10 @@ description: "Cycles is a runtime authority for autonomous agents: it enforces s Cycles is a **runtime authority for autonomous agents**. It enforces hard limits on agent spend and risky actions — **before they happen, not after** — and records the evidence operators need to audit decisions later. -::: tip Cycles enforces three runtime-authority pillars -- **Spend** — reserve-commit budget enforcement before LLM calls and tool actions -- **Risky actions** — three-way decisions (`ALLOW` / `ALLOW_WITH_CAPS` / `DENY`) with caps for tool allowlists/denylists, max tokens, max steps, and cooldowns -- **Audit** — reservations, commits, releases, and decisions produce structured records for compliance and incident review +::: tip Cycles provides three runtime-authority pillars +- **Spend** — reserve-commit budget enforcement before instrumented LLM calls and tool actions +- **Risky actions** — `ALLOW` / `ALLOW_WITH_CAPS` / `DENY` decisions with `RISK_POINTS` budgets and caps for tool allowlists/denylists, max tokens, max steps, and cooldowns +- **Audit** — reservations, commits, releases, and decisions create structured records for compliance, attribution, and incident review ::: ## Choose your path