chore(home): seven quick wins — framing, icons, a11y, copy hygiene

Stacked on perf/homepage-shiki-video (#840) because two items touch
files introduced/changed there.

- HomeProblems: add a section heading ("Four incidents Cycles
  prevents") — the incident cards previously appeared with no framing.
- Features grid: new /icons/file-code.svg for Protocol Reference,
  which shared book-text.svg with Topic Guides.
- Hero image alt text: replace arrow-chain shorthand ("agents -> gate
  -> allow/block") with a screen-reader-friendly sentence.
- snippets.data.ts: GPT-5 per-token prices (125/1000 microcents) are
  now single constants interpolated into both the Java and Vercel
  snippets — a price change can't half-update the homepage.
- HomeIntegrations: chips without a real brand icon (AWS Bedrock,
  Google Gemini, LlamaIndex, CrewAI, Pydantic AI, AutoGen, Groq,
  Ollama) now use a neutral layers glyph instead of a misleading
  TypeScript/Python logo. Language icons stay on language-framework
  chips (Django, Next.js, ...).
- HomeCodeSnippet: proper WAI-ARIA tabs — role=tablist/tab/tabpanel,
  aria-selected, roving tabindex, ArrowLeft/Right/Home/End keyboard
  navigation.
- Social proof: row now reads "N+ package installs · Apache 2.0 ·
  self-hosted · no prompt storage". GitHub stars are fetched in
  installs.data.ts and tracked in the cache/installs.json for
  analytics but deliberately NOT displayed (count is too small to be
  persuasive — same rationale as clones). Stars are not a high-water
  mark: they can legitimately decrease, so a successful fetch wins and
  the cached value is only an API-failure fallback; the field is
  excluded from MONOTONIC_FIELDS.

Verified: vitest 93/93, npm run build:fast clean, rendered homepage
checked via vitepress preview + headless Edge (heading, chips, stat
row, tablist SSR markup, interpolated Java snippet all correct).
installs-cache.json / public/installs.json build side-effects left
uncommitted; the stars field appears there on the next counts refresh.

Author: amavashev

.vitepress/theme/FrameworkIcons.ts

@@ -34,5 +34,8 @@ export const anthropicPath = 'M17.304 0H13.68L24 24h3.624zm-10.608 0L0 24h3.696l
 /** Mozilla — dinosaur head mark (Simple Icons, CC0) */
 export const mozillaPath = 'M3.346 1.168C1.632 2.326.586 4.142.21 6.07c-.376 1.929-.147 3.97.445 5.758a13.03 13.03 0 0 0 2.876 4.878c1.238 1.318 2.784 2.384 4.473 2.612 1.056.143 2.146-.036 3.058-.535.912-.499 1.624-1.344 1.924-2.341.274-.912.167-1.888-.069-2.822-.235-.935-.597-1.839-.834-2.771-.197-.774-.31-1.582-.175-2.371.134-.788.53-1.558 1.167-2.035.638-.477 1.547-.603 2.27-.276.724.326 1.185 1.097 1.341 1.869.156.773.076 1.573-.046 2.354-.183 1.17-.44 2.326-.517 3.501-.078 1.176.04 2.391.586 3.422.547 1.032 1.605 1.83 2.811 1.826 1.095-.004 2.124-.667 2.804-1.517.68-.85 1.11-1.876 1.395-2.93.57-2.109.536-4.396-.172-6.453-.708-2.058-2.103-3.861-3.888-5.107C18.875.457 16.765-.144 14.66.037c-1.583.136-3.133.72-4.354 1.746-1.222 1.027-2.086 2.513-2.28 4.141-.12.999.016 2.027.287 3.01.27.983.672 1.927.944 2.895.202.718.33 1.485.182 2.218-.147.733-.594 1.437-1.272 1.718-.737.306-1.609.054-2.168-.508-.56-.562-.862-1.323-1.055-2.099-.386-1.552-.381-3.19-.065-4.746.316-1.555.943-3.036 1.853-4.321L3.346 1.168Z'
 
+/** Generic integration — layers mark, used when no brand icon is available (a wrong brand logo misleads more than a neutral glyph) */
+export const genericIntegrationPath = 'M12 2 22 8l-10 6L2 8l10-6zM3.8 10.9 2 12l10 6 10-6-1.8-1.1-8.2 4.92-8.2-4.92zM3.8 14.9 2 16l10 6 10-6-1.8-1.1-8.2 4.92-8.2-4.92z'
+
 /** Spring AI — leaf mark reused from Spring Boot, with AI label context */
 export const springAiPath = 'm23.693 10.7058-4.73-8.1844c-.4094-.7106-1.4166-1.2942-2.2402-1.2942H7.2725c-.819 0-1.8308.5836-2.2402 1.2942L.307 10.7058c-.4095.7106-.4095 1.873 0 2.5837l4.7252 8.189c.4094.7107 1.4166 1.2943 2.2402 1.2943h9.455c.819 0 1.826-.5836 2.2402-1.2942l4.7252-8.189c.4095-.7107.4095-1.8732 0-2.5838zM10.9763 5.7547c0-.5365.4377-.9742.9742-.9742s.9742.4377.9742.9742v5.8217c0 .5366-.4377.9742-.9742.9742s-.9742-.4376-.9742-.9742zm.9742 12.4294c-3.6427 0-6.6077-2.965-6.6077-6.6077.0047-2.0896.993-4.0521 2.6685-5.304a.8657.8657 0 0 1 1.2142.1788.8657.8657 0 0 1-.1788 1.2143c-2.1602 1.6048-2.612 4.6592-1.0072 6.8194 1.6049 2.1603 4.6593 2.612 6.8195 1.0072 1.2378-.9177 1.9673-2.372 1.9673-3.9157a4.8972 4.8972 0 0 0-1.9861-3.925c-.386-.2824-.466-.8284-.1836-1.2143.2824-.386.8283-.466 1.2143-.1835 1.6895 1.2471 2.6826 3.2238 2.6873 5.3228 0 3.6474-2.965 6.6077-6.6077 6.6077z'

.vitepress/theme/HomeCodeSnippet.vue

@@ -27,6 +27,21 @@ const tabs = [
   { key: 'vercel', label: 'Vercel AI', icon: vercelPath },
   { key: 'openclaw', label: 'OpenClaw', icon: openclawPath },
 ]
+
+// WAI-ARIA tabs pattern: arrow keys move between tabs (roving tabindex),
+// Home/End jump to the ends.
+function onTablistKeydown(e) {
+  if (!['ArrowRight', 'ArrowLeft', 'Home', 'End'].includes(e.key)) return
+  e.preventDefault()
+  const current = tabs.findIndex(t => t.key === activeTab.value)
+  let next
+  if (e.key === 'ArrowRight') next = (current + 1) % tabs.length
+  else if (e.key === 'ArrowLeft') next = (current - 1 + tabs.length) % tabs.length
+  else if (e.key === 'Home') next = 0
+  else next = tabs.length - 1
+  activeTab.value = tabs[next].key
+  document.getElementById(`snippet-tab-${tabs[next].key}`)?.focus()
+}
 </script>
 
 <template>
@@ -35,10 +50,15 @@ const tabs = [
     <h2 class="code-heading">Add runtime authority in a few lines</h2>
     <p class="code-caption"><code>@cycles</code> reserves budget before the action runs. No remaining cycles — no action.</p>
     <div class="code-container">
-      <div class="tab-bar">
+      <div class="tab-bar" role="tablist" aria-label="Integration code examples" @keydown="onTablistKeydown">
         <button
           v-for="tab in tabs"
           :key="tab.key"
+          :id="`snippet-tab-${tab.key}`"
+          role="tab"
+          :aria-selected="activeTab === tab.key"
+          aria-controls="snippet-panel"
+          :tabindex="activeTab === tab.key ? 0 : -1"
           :class="['tab', { active: activeTab === tab.key }]"
           @click="activeTab = tab.key"
         >
@@ -48,7 +68,7 @@ const tabs = [
           {{ tab.label }}
         </button>
       </div>
-      <div class="code-block">
+      <div class="code-block" role="tabpanel" id="snippet-panel" :aria-labelledby="`snippet-tab-${activeTab}`">
         <button class="copy-btn" @click="copyCode" :aria-label="copied ? 'Copied' : 'Copy code'">
           {{ copied ? 'Copied!' : 'Copy' }}
         </button>

.vitepress/theme/HomeIntegrations.vue

@@ -2,6 +2,7 @@
 import {
   pythonPath, typescriptPath, springAiPath, mcpPath, langchainPath,
   openaiAgentsPath, vercelPath, openclawPath, anthropicPath, mozillaPath,
+  genericIntegrationPath,
 } from './FrameworkIcons'
 
 const integrations = [
@@ -14,15 +15,15 @@ const integrations = [
   { name: 'MCP', icon: mcpPath, link: '/how-to/integrating-cycles-with-mcp' },
   { name: 'OpenAI Agents', icon: openaiAgentsPath, link: '/how-to/integrating-cycles-with-openai-agents' },
   { name: 'OpenClaw', icon: openclawPath, link: '/how-to/integrating-cycles-with-openclaw' },
-  { name: 'AWS Bedrock', icon: typescriptPath, link: '/how-to/integrating-cycles-with-aws-bedrock' },
-  { name: 'Google Gemini', icon: typescriptPath, link: '/how-to/integrating-cycles-with-google-gemini' },
-  { name: 'LlamaIndex', icon: pythonPath, link: '/how-to/integrating-cycles-with-llamaindex' },
-  { name: 'CrewAI', icon: pythonPath, link: '/how-to/integrating-cycles-with-crewai' },
-  { name: 'Pydantic AI', icon: pythonPath, link: '/how-to/integrating-cycles-with-pydantic-ai' },
-  { name: 'AutoGen', icon: pythonPath, link: '/how-to/integrating-cycles-with-autogen' },
+  { name: 'AWS Bedrock', icon: genericIntegrationPath, link: '/how-to/integrating-cycles-with-aws-bedrock' },
+  { name: 'Google Gemini', icon: genericIntegrationPath, link: '/how-to/integrating-cycles-with-google-gemini' },
+  { name: 'LlamaIndex', icon: genericIntegrationPath, link: '/how-to/integrating-cycles-with-llamaindex' },
+  { name: 'CrewAI', icon: genericIntegrationPath, link: '/how-to/integrating-cycles-with-crewai' },
+  { name: 'Pydantic AI', icon: genericIntegrationPath, link: '/how-to/integrating-cycles-with-pydantic-ai' },
+  { name: 'AutoGen', icon: genericIntegrationPath, link: '/how-to/integrating-cycles-with-autogen' },
   { name: 'AnyAgent', icon: mozillaPath, link: '/how-to/integrating-cycles-with-anyagent' },
-  { name: 'Groq', icon: pythonPath, link: '/how-to/integrating-cycles-with-groq' },
-  { name: 'Ollama', icon: pythonPath, link: '/how-to/integrating-cycles-with-ollama' },
+  { name: 'Groq', icon: genericIntegrationPath, link: '/how-to/integrating-cycles-with-groq' },
+  { name: 'Ollama', icon: genericIntegrationPath, link: '/how-to/integrating-cycles-with-ollama' },
   { name: 'Next.js', icon: typescriptPath, link: '/how-to/integrating-cycles-with-nextjs' },
   { name: 'Express', icon: typescriptPath, link: '/how-to/integrating-cycles-with-express' },
   { name: 'Django', icon: pythonPath, link: '/how-to/integrating-cycles-with-django' },

.vitepress/theme/HomeProblems.vue

@@ -34,6 +34,7 @@ const problems = [
 <template>
   <section class="home-problems">
     <div class="inner">
+      <h2 class="heading">Four incidents Cycles prevents</h2>
       <div class="grid">
         <a
           v-for="item in problems"
@@ -71,6 +72,18 @@ const problems = [
   margin: 0 auto;
 }
 
+.heading {
+  font-size: 24px;
+  font-weight: 700;
+  color: var(--vp-c-text-1);
+  margin: 0 0 32px;
+  letter-spacing: -0.02em;
+  line-height: 1.3;
+  text-align: center;
+  border: none;
+  padding: 0;
+}
+
 .grid {
   display: grid;
   grid-template-columns: 1fr;

.vitepress/theme/HomeSocialProof.vue

@@ -21,8 +21,8 @@ const showInstalls = computed(() => installs.value > 0)
 </script>
 
 <template>
-  <p v-if="showInstalls" class="social-proof">
-    <span class="stat">
+  <p class="social-proof">
+    <span v-if="showInstalls" class="stat">
       <svg
         class="stat-icon"
         xmlns="http://www.w3.org/2000/svg"
@@ -38,6 +38,9 @@ const showInstalls = computed(() => installs.value > 0)
       </svg>
       <span class="stat-text">{{ formatted.format(installs) }}+ package installs</span>
     </span>
+    <span class="stat">
+      <span class="stat-text">Apache 2.0 &#183; self-hosted &#183; no prompt storage</span>
+    </span>
   </p>
 </template>
 
@@ -64,6 +67,12 @@ const showInstalls = computed(() => installs.value > 0)
   white-space: nowrap;
 }
 
+.stat + .stat::before {
+  content: '\00b7';
+  margin-right: 14px;
+  color: var(--vp-c-text-3);
+}
+
 .stat-icon { flex-shrink: 0; }
 .stat-text { font-variant-numeric: tabular-nums; }
 </style>

.vitepress/theme/installs.data.ts

@@ -21,6 +21,12 @@ export interface InstallsData {
   total: number
   /** Accumulated clone count across tracked repos (cumulative via day-cursor). */
   clones: number
+  /** GitHub stars across first-party org repos. Tracked for analytics but
+   *  NOT displayed on the homepage (count is currently too small to be
+   *  persuasive — same rationale as clones). Fresh value wins when the
+   *  fetch succeeds (stars can legitimately decrease, so no HWM); the
+   *  cached value is only a fallback for API failures. */
+  stars: number
   fetchedAt: string
 }
 
@@ -48,6 +54,7 @@ interface InstallsCache {
   releasesByRepo: Record<string, number>
   ghPackages: number
   maven: number
+  stars: number
   total: number
   fetchedAt: string
 }
@@ -71,7 +78,7 @@ function readCache(): InstallsCache {
       clones: 0, clonesByRepo: {},
       releases: 0, releasesByRepo: {},
       ghPackages: 0,
-      maven: 0, total: 0, fetchedAt: '',
+      maven: 0, stars: 0, total: 0, fetchedAt: '',
     }
   }
 
@@ -106,6 +113,7 @@ function readCache(): InstallsCache {
     releasesByRepo:  raw.releasesByRepo ?? {},
     ghPackages:      raw.ghPackages ?? 0,
     maven:           raw.maven ?? 0,
+    stars:           raw.stars ?? 0,
     total:           raw.total ?? 0,
     fetchedAt:       raw.fetchedAt ?? '',
   }
@@ -328,6 +336,39 @@ async function listOrgRepos(): Promise<string[]> {
   return repos
 }
 
+// ── GitHub stars ─────────────────────────────────────────────────────
+// Public endpoint (auth raises rate limits). Stars can legitimately
+// decrease, so this is NOT a high-water mark: a successful fetch wins
+// outright and the cache is only a fallback for API failures. `stars`
+// is deliberately absent from MONOTONIC_FIELDS for the same reason.
+async function fetchGithubStars(): Promise<number | null> {
+  let total = 0
+  let sawAny = false
+  let page = 1
+  while (page < 10 /* hard cap to avoid runaway loops */) {
+    try {
+      const res = await fetch(
+        `https://api.github.com/orgs/${GITHUB_ORG}/repos?per_page=100&page=${page}`,
+        { headers: ghHeaders() }
+      )
+      if (!res.ok) break
+      const list = await res.json() as Array<{
+        fork: boolean; archived: boolean; stargazers_count?: number
+      }>
+      if (list.length === 0) break
+      sawAny = true
+      for (const r of list) {
+        if (!r.fork && !r.archived) total += r.stargazers_count ?? 0
+      }
+      if (list.length < 100) break
+      page++
+    } catch {
+      break
+    }
+  }
+  return sawAny ? total : null
+}
+
 // ── GitHub clones ────────────────────────────────────────────────────
 // API returns a 14-day rolling window with per-day counts. We accumulate
 // by tracking the lastSeenDay cursor per repo and only adding strictly
@@ -465,13 +506,15 @@ export default {
       clonesResult,
       releasesResult,
       mavenFetched,
+      starsFetched,
     ] = await Promise.all([
       fetchNpmDownloads(),
       fetchPypiDownloads(),
       fetchCratesDownloads(),
       fetchGithubClones(cached.clonesByRepo),
       fetchGithubReleaseDownloads(cached.releasesByRepo),
       Promise.resolve(fetchMavenDownloads()),
+      fetchGithubStars(),
     ])
 
     // Per-package HWM: each package's count never decreases independently.
@@ -497,6 +540,10 @@ export default {
     const ghPackagesFetched = fetchManualPackageCounts()
     const ghPackages = Math.max(ghPackagesFetched, cached.ghPackages)
 
+    // Stars: fresh value wins on a successful fetch (no HWM — see
+    // fetchGithubStars); cache is only the API-failure fallback.
+    const stars = starsFetched ?? cached.stars
+
     // Displayed total — excludes `clones`. Clones are still tracked in
     // the cache for analytics, but the home-page counter is limited to
     // "deliberately pulled the package" sources because total clones
@@ -528,7 +575,7 @@ export default {
       clones, clonesByRepo: clonesResult.updatedByRepo,
       releases, releasesByRepo: releasesResult.updatedByRepo,
       ghPackages,
-      maven, total, fetchedAt: now,
+      maven, stars, total, fetchedAt: now,
     }
 
     if (
@@ -540,6 +587,7 @@ export default {
       || releases > cached.releases
       || ghPackages > cached.ghPackages
       || maven > cached.maven
+      || stars !== cached.stars
     ) {
       writeCache(newCache)
     }
@@ -548,10 +596,10 @@ export default {
     try {
       writeFileSync(
         PUBLIC_PATH,
-        JSON.stringify({ total, clones, fetchedAt: now }) + '\n',
+        JSON.stringify({ total, clones, stars, fetchedAt: now }) + '\n',
       )
     } catch { /* non-critical */ }
 
-    return { total, clones, fetchedAt: now }
+    return { total, clones, stars, fetchedAt: now }
   },
 }

.vitepress/theme/snippets.data.ts

@@ -20,6 +20,12 @@ export interface HomeSnippet {
 
 export declare const data: Record<string, HomeSnippet>
 
+// GPT-5 list price in USD microcents per token ($1.25/1M in, $10/1M out).
+// Interpolated into the Java and Vercel snippets so a price change can't
+// half-update the homepage.
+const GPT5_IN_MICROCENTS = 125
+const GPT5_OUT_MICROCENTS = 1000
+
 const snippets: Record<string, { lang: string; code: string }> = {
   python: {
     lang: 'python',
@@ -55,8 +61,8 @@ const ask = withCycles(
 import org.springframework.ai.chat.client.ChatClient;
 import org.springframework.ai.openai.OpenAiChatOptions;
 
-// GPT-5: 125 microcents/token in, 1000 out ($1.25 / $10 per 1M)
-@Cycles(value = "#prompt.length() / 4 * 125 + #maxTokens * 1000",
+// GPT-5: ${GPT5_IN_MICROCENTS} microcents/token in, ${GPT5_OUT_MICROCENTS} out ($1.25 / $10 per 1M)
+@Cycles(value = "#prompt.length() / 4 * ${GPT5_IN_MICROCENTS} + #maxTokens * ${GPT5_OUT_MICROCENTS}",
         actionKind = "llm.completion",
         actionName = "gpt-5")
 public String chat(String prompt, int maxTokens) {
@@ -133,7 +139,7 @@ const handle = await reserveForStream({
 const result = streamText({
   model: openai("gpt-5"), messages,
   onFinish: async ({ usage }) =>
-    handle.commit((usage.promptTokens ?? 0) * 125 + (usage.completionTokens ?? 0) * 1000),
+    handle.commit((usage.promptTokens ?? 0) * ${GPT5_IN_MICROCENTS} + (usage.completionTokens ?? 0) * ${GPT5_OUT_MICROCENTS}),
 });`,
   },
 

index.md

@@ -11,7 +11,7 @@ hero:
   image:
     light: /runcycles-hero.svg?v=8
     dark: /runcycles-hero-dark.svg?v=8
-    alt: Cycles hero — agents → gate → allow/block → signed audit ledger
+    alt: Three AI agents submit actions to the Cycles gate; allowed actions proceed, blocked ones are denied, and every decision is appended to a signed audit log.
   actions:
     - theme: brand
       text: "Start with Claude or Codex"
@@ -59,7 +59,7 @@ features:
     link: /how-to/add-cycles-with-claude-or-codex
     linkText: Browse guides
   - icon:
-      src: /icons/book-text.svg
+      src: /icons/file-code.svg
       alt: Protocol icon
     title: "Protocol Reference"
     details: "Reserve-commit lifecycle, authentication, scope derivation, units, caps, overage policies, TTL, decide, dry run, events, debt, balances, metrics, and error handling."