Add TypeScript client quickstart and configuration reference

[amavashev]

Summary

This PR adds comprehensive documentation for the TypeScript/Node.js client library (runcycles), including a complete quickstart guide and configuration reference. It also updates navigation to surface the Python client quickstart as the primary entry point and adds a reference to the runaway agent demo in the incidents documentation.

Key Changes

• New quickstart guide (getting-started-with-the-typescript-client.md): Complete walkthrough covering:

  • Installation and configuration (programmatic and environment variables)
  • withCycles higher-order function with fixed and dynamic estimates
  • Actual cost calculation and custom metrics
  • Runtime context access via getCyclesContext()
  • Decision handling and exception hierarchy
  • Streaming support with reserveForStream
  • Programmatic CyclesClient usage with wire format mappers
  • Progressive walkthrough examples (5 steps from basic to advanced)
  • Full lifecycle summary

• New configuration reference (typescript-client-configuration-reference.md): Detailed reference for:

  • CyclesConfig constructor options (required fields, subject defaults, HTTP timeouts)
  • Retry configuration with exponential backoff explanation
  • Environment variable mapping with custom prefix support
  • Default client/config setup patterns
  • Subject field resolution order

• Updated navigation (.vitepress/config.ts and index.md):

  • Changed primary quickstart link from "Deploy the Full Stack" to "Getting Started with the Python Client"
  • Maintains consistency across homepage and sidebar navigation

• Enhanced incidents documentation (runaway-agents-tool-loops-and-budget-overruns-the-incidents-cycles-is-designed-to-prevent.md):

  • Added "See it in action: the runaway agent demo" section
  • References the cycles-runaway-demo repository
  • Includes setup instructions and explanation of the failure mode demonstration

Notable Implementation Details

• Documentation covers all three usage patterns: withCycles HOF (simplest), reserveForStream (streaming), and CyclesClient (full control)
• Includes complete exception hierarchy with use cases for each error type
• Demonstrates both typed mappers and raw snake_case JSON for programmatic client usage
• Retry configuration section explains exponential backoff with concrete examples
• Progressive walkthrough guides users from basic fixed estimates to advanced metrics and error handling

https://claude.ai/code/session_01G5yRZBXrczLDVtrHzCZWdu