chore(seo): broaden quickstart messaging to spend / risky actions / audit#591
Merged
Conversation
…udit 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; #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 <meta name="description"> reflects new copy - rendered HTML contains the callout block exactly once per page
…iption trim
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).
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
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. Same correction we applied earlier today across the Rust crate (cycles-client-rust#31, #32, #33) and the Rust blog post (#585), now applied to the public quickstart surface.Light-touch pattern: frontmatter
descriptionrewritten to name spend + action + audit, plus one short::: tip :::callout block 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)
quickstart/getting-started-with-the-python-client.mdquickstart/getting-started-with-the-typescript-client.mdquickstart/getting-started-with-the-cycles-spring-boot-starter.mdquickstart/getting-started-with-the-rust-client.mdquickstart/getting-started-with-the-mcp-server.mdcycles_decide,cycles_create_event)quickstart/what-is-cycles.mdquickstart/how-to-add-hard-budget-limits-to-spring-ai-with-cycles.mdquickstart/how-to-choose-a-first-cycles-rollout-...mdPages intentionally NOT changed (audited as appropriate for their audience)
index.md— already cross-links to/protocol/,/how-to/end-to-end-tutorial.md— runbook formatarchitecture-overview-*— technical referencedeploying-*andself-hosting-*— operations focusmcp-claude-*/mcp-cursor.md/mcp-windsurf.md— setup guides; existing warning correctly clarifies that MCP availability ≠ enforcementWhy titles and URLs are preserved
Each page keeps its existing H1 and URL slug to maintain inbound search-link equity. The two spend-only strategy pages (Spring AI how-to, rollout-choice) keep their slugs since those are the canonical search targets for
"spring ai budget limit"and"cycles rollout"queries respectively.Diff shape
8 files, +59 insertions / -9 deletions. Each file: 1 description line replaced, 5-7 lines added (callout block + blank line). Reviewer can scan the pattern once and verify across all 8.
Test plan
npx vitest run— 83/83 passnpm run build— succeeds (98s)<meta name="description">reflects new copy on Python client pageCycles enforces three runtime-authority pillars) appears exactly once per page in.vitepress/dist/quickstart/<page>.html