Add comprehensive documentation for Cycles protocol and client#3
Merged
Add comprehensive documentation for Cycles protocol and client#3
Conversation
…ty gaps High priority: - Architecture overview with system diagram and component descriptions - Self-hosting guide with Docker Compose, source build, and production config - Full API reference with curl examples for all 9 endpoints - Budget allocation and management guide - API key management and tenant isolation guide Medium priority: - Programmatic CyclesClient usage guide - SpEL expression reference with examples and troubleshooting - Client configuration reference (all cycles.* properties) - Server configuration reference (all env vars and properties) - Testing guide (unit tests, mocking, integration tests) - Error handling patterns in client code - Custom field resolvers guide Also updates VitePress sidebar with new Configuration Reference section and integrates all new articles into the navigation. https://claude.ai/code/session_01PaV6ZU7TtM8fmbteKVk7fA
- Amount constructor: fix parameter order to (Unit, Long) matching source - Action: replace nonexistent .builder() with constructor (kind, name, tags) - CyclesMetrics: replace nonexistent .builder() with new() + setters - CyclesResponse: replace .ok()/.error() with .success()/.httpError() - Bean names: fix evaluator, retryEngine, aspect to match method names - Public paths: list all 9 paths from SecurityConfig, fix health endpoint pattern to exact match (not wildcard) - Docker: clarify docker-compose.yml must be created (not in repo), add Dockerfile example and build step https://claude.ai/code/session_01PaV6ZU7TtM8fmbteKVk7fA
Moves all markdown files from the flat root directory into six topic-based folders: quickstart/, concepts/, how-to/, protocol/, configuration/, and incidents/. Updates VitePress sidebar links to reflect the new paths. https://claude.ai/code/session_01PaV6ZU7TtM8fmbteKVk7fA
amavashev
added a commit
that referenced
this pull request
Apr 11, 2026
Two review fixes to the Contact CTA section:
1. Button text: "Start the conversation →" → "Talk to the team →"
Mirrors the section headline ("Talk to the people building Cycles.")
and feels more human and direct than the slightly generic
"Start the conversation".
2. Fourth reason: "Building something adjacent" → "Evaluating Cycles
for production".
The original fourth card was the weakest from a qualified-inbound
perspective — "adjacent builders" (observability vendors, policy
engines, frameworks) is a real audience but a small one, and the
abstract framing didn't give readers a concrete hook.
The new framing captures a distinct funnel stage the other three
reasons miss: teams in vendor eval or architecture review who aren't
yet piloting (#1 covered pilots) and don't have specific protocol
feedback (#3 covered that). It names real comparison categories
(rate limiters, LLM gateways, observability tools) so the card
feels concrete like the others, and offers three specific things
in return (spec walkthrough, runtime demo, integration questions).
Verified via `npm run build` — both strings ("Talk to the team",
"Evaluating Cycles for production") present in dist/index.html, neither
of the old strings remain.
5 tasks
4 tasks
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
2 participants
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
This PR adds extensive documentation for the Cycles budget protocol and Spring Boot client, covering API reference, configuration, testing, error handling, and deployment guides.
Key Changes
New Documentation Files:
protocol/api-reference-for-the-cycles-protocol.md) — Complete endpoint documentation with request/response formats, curl examples, and error codes for all 9 Cycles protocol endpointshow-to/using-the-cycles-client-programmatically.md) — Programmatic usage ofCyclesClientinterface with lifecycle examples and error handling patternshow-to/testing-with-cycles.md) — Unit and integration testing strategies for@Cycles-annotated methods andCyclesClientusage with mocking examplesconfiguration/spel-expression-reference-for-cycles.md) — Comprehensive guide to Spring Expression Language usage in@Cyclesannotations for dynamic cost estimationhow-to/custom-field-resolvers-in-cycles.md) — How to implementCyclesFieldResolverfor dynamic Subject field resolutionquickstart/self-hosting-the-cycles-server.md) — Docker Compose setup, source build instructions, and configuration referencequickstart/architecture-overview-how-cycles-fits-together.md) — System diagram and component descriptions showing how Cycles integrates with applications and Redishow-to/error-handling-patterns-in-cycles-client-code.md) — Practical patterns for handlingCyclesProtocolExceptionand implementing degradation strategiesconfiguration/client-configuration-reference-for-cycles-spring-boot-starter.md) — Complete property reference for Spring Boot Starter configurationconfiguration/server-configuration-reference-for-cycles.md) — Complete property reference for Cycles server configurationhow-to/budget-allocation-and-management-in-cycles.md) — How budget allocation works, scope hierarchy, and management via Cycles Adminhow-to/api-key-management-in-cycles.md) — API key lifecycle, tenant isolation, and usage patternsDocumentation Structure Updates:
.vitepress/config.tsto group documentation into logical sections: Quickstart, Protocol, How-To, Configuration, and Conceptsquickstart/,protocol/,how-to/,configuration/)Notable Implementation Details
CyclesClienthttps://claude.ai/code/session_01PaV6ZU7TtM8fmbteKVk7fA