# Shuke

> Everything about Shuke (codename 述刻), the spoken-expression trainer: product, design, API, each app and service, decisions and launch. For people and agents.

Each module has its own index (`llms.txt`) and all its pages in one file (`llms-full.txt`). Every page is also Markdown at its URL plus `index.md`. Every page in one file: [llms-full.txt](/llms-full.txt) (763 KB).

## Overview

What the repo holds, its tracks, the first deployed environment, and how these docs work. Index: [llms.txt](/overview/llms.txt) · All pages: [llms-full.txt](/overview/llms-full.txt) (18 KB)

- [Shuke](/overview/index.md)
- [How these docs work](/overview/docs/index.md)
- [Deployment](/overview/deployment/index.md): The first Cloudflare environment: Workers, D1, KV, R2, queues and secrets.

## Product

The PRD review and the original PRD text: who the app is for, what was decided, what is still open. Index: [llms.txt](/product/llms.txt) · All pages: [llms-full.txt](/product/llms-full.txt) (6 KB)

- [PRD review](/product/index.md): TPM review of PRD v1.0: what is strong, the gaps and risks, and what ADR-001 resolved.
- [PRD v1.0 (extracted text)](/product/prd-v1.0-extracted.txt): The original PRD (Chinese), extracted from the PDF.

## Brand and design

The hi-fi design: brand, design system and tokens, the screen list, hi-fi screens with their data-binding maps, flows, states, onboarding, paywall, engagement, iOS handoff, screenshots. Index: [llms.txt](/design/llms.txt) · All pages: [llms-full.txt](/design/llms-full.txt) (627 KB) · View: [Hi-fi gallery](/design/gallery/index.html)

### Pages

- [Design](/design/index.md): The hi-fi gallery, the botgumi stages mapped onto it, the checks and the pending gates.

### Stages

- [Brand brief](/design/brand/index.md): Stage 1: codename, promise, voice, mark, do and don't; name and domain open.
- [Design system](/design/design-system/index.md): Stage 2: where the system lives (tokens.css, tokens.md, base.css) and the token source.
- [Design tokens](/design/tokens/index.md): Colour roles and limits, type styles, spacing, radii, elevation, motion and haptics, with the SwiftUI mapping.
- [Screens](/design/screens/index.md): Stage 3: every screen with its ID, states, flows and stage. The contract of what exists.
- [Hi-fi screens](/design/hifi/index.md): Stage 4: one folder per screen with its contract, boards per state and data-binding map.
- [Screenshot direction](/design/screenshots/index.md): Stage 5: not started; waits for the hi-fi and brand gates.

### Specs

- [User flows](/design/flows/index.md): Nine flows as Mermaid and step tables: screen, trigger, API, success, failure, exit.
- [State matrix](/design/states/index.md): Every screen by loading, empty, error (retryable or fatal), offline and partial data.
- [Data binding](/design/data-binding/index.md): Every visible data point to its API field or local state, and the contract change requests.
- [Onboarding](/design/onboarding/index.md): Rationale, questions, mapping to /v1/onboarding and the plan.
- [Paywall](/design/paywall/index.md): Projection formula, calendar rules, honesty rules.
- [Engagement](/design/engagement/index.md): Quests, XP, streaks, levels, achievements, notifications, haptics and motion per moment.
- [iOS handoff](/design/ios-handoff/index.md): SwiftUI component map, SF Symbols, localization, Dynamic Type, VoiceOver labels, hit targets.
- [Copy deck](/design/copy/index.md): Every client string by key, in en and zh-Hans; generated from strings.json.

### Hi-fi screens

- [S01 Onboarding · Welcome](/design/hifi/s01/index.md): Contract, a board per state (default, loading, empty, error, offline), tokens and strings.
- [S01 bindings](/design/hifi/s01/bindings/index.md): Data-binding map of Onboarding · Welcome: every field to its source, and what each required state shows.
- [S02 Onboarding · Practice language](/design/hifi/s02/index.md): Contract, a board per state (selected, loading, empty, error, offline), tokens and strings.
- [S02 bindings](/design/hifi/s02/bindings/index.md): Data-binding map of Onboarding · Practice language: every field to its source, and what each required state shows.
- [S03 Onboarding · Goal](/design/hifi/s03/index.md): Contract, a board per state (default, selected, loading, empty, error, offline), tokens and strings.
- [S03 bindings](/design/hifi/s03/bindings/index.md): Data-binding map of Onboarding · Goal: every field to its source, and what each required state shows.
- [S04 Onboarding · Scenario + topics](/design/hifi/s04/index.md): Contract, a board per state (default, selected, loading, empty, error, offline), tokens and strings.
- [S04 bindings](/design/hifi/s04/bindings/index.md): Data-binding map of Onboarding · Scenario + topics: every field to its source, and what each required state shows.
- [S05 Onboarding · Self-assessed level](/design/hifi/s05/index.md): Contract, a board per state (default, selected, loading, empty, error, offline), tokens and strings.
- [S05 bindings](/design/hifi/s05/bindings/index.md): Data-binding map of Onboarding · Self-assessed level: every field to its source, and what each required state shows.
- [S06 Onboarding · Weekly days + reminder time](/design/hifi/s06/index.md): Contract, a board per state (default, selected, loading, empty, error, offline), tokens and strings.
- [S06 bindings](/design/hifi/s06/bindings/index.md): Data-binding map of Onboarding · Weekly days + reminder time: every field to its source, and what each required state shows.
- [S07 Onboarding · Notification priming](/design/hifi/s07/index.md): Contract, a board per state (default, loading, empty, error, offline), tokens and strings.
- [S07 bindings](/design/hifi/s07/bindings/index.md): Data-binding map of Onboarding · Notification priming: every field to its source, and what each required state shows.
- [S08 Diagnostic · Diagnostic · intro](/design/hifi/s08/index.md): Contract, a board per state (default, loading, empty, error, offline), tokens and strings.
- [S08 bindings](/design/hifi/s08/bindings/index.md): Data-binding map of Diagnostic · Diagnostic · intro: every field to its source, and what each required state shows.
- [S09 Diagnostic · Diagnostic · read](/design/hifi/s09/index.md): Contract, a board per state (normal, loading, empty, error, offline), tokens and strings.
- [S09 bindings](/design/hifi/s09/bindings/index.md): Data-binding map of Diagnostic · Diagnostic · read: every field to its source, and what each required state shows.
- [S10 Diagnostic · Mic purpose sheet (pre-permission)](/design/hifi/s10/index.md): Contract, a board per state (sheet, loading, empty, error, offline), tokens and strings.
- [S10 bindings](/design/hifi/s10/bindings/index.md): Data-binding map of Diagnostic · Mic purpose sheet (pre-permission): every field to its source, and what each required state shows.
- [S11 Diagnostic · Diagnostic · retell](/design/hifi/s11/index.md): Contract, a board per state (idle, recording, paused, autostop, too-short, permission-denied, loading, empty, error, offline), tokens and strings.
- [S11 bindings](/design/hifi/s11/bindings/index.md): Data-binding map of Diagnostic · Diagnostic · retell: every field to its source, and what each required state shows.
- [S12 Diagnostic · Diagnostic · processing](/design/hifi/s12/index.md): Contract, a board per state (uploading, transcribing, assessing, failed, unreliable, loading, empty, error, offline), tokens and strings.
- [S12 bindings](/design/hifi/s12/bindings/index.md): Data-binding map of Diagnostic · Diagnostic · processing: every field to its source, and what each required state shows.
- [S13 Diagnostic · Diagnostic result · animated reveal](/design/hifi/s13/index.md): Contract, a board per state (reveal, loading, empty, error, offline), tokens and strings.
- [S13 bindings](/design/hifi/s13/bindings/index.md): Data-binding map of Diagnostic · Diagnostic result · animated reveal: every field to its source, and what each required state shows.
- [S14 Plan · 14-day plan](/design/hifi/s14/index.md): Contract, a board per state (default, loading, empty, error, offline), tokens and strings.
- [S14 bindings](/design/hifi/s14/bindings/index.md): Data-binding map of Plan · 14-day plan: every field to its source, and what each required state shows.
- [S15 Paywall · Paywall](/design/hifi/s15/index.md): Contract, a board per state (default, loading-products, purchasing, purchase-failed, restored, expired-return, loading, empty, error, offline), tokens and strings.
- [S15 bindings](/design/hifi/s15/bindings/index.md): Data-binding map of Paywall · Paywall: every field to its source, and what each required state shows.
- [S16 Home · Home](/design/hifi/s16/index.md): Contract, a board per state (first-time, normal, in-progress, completed, streak-risk, offline, no-quest, topic-empty, loading, error, empty), tokens and strings.
- [S16 bindings](/design/hifi/s16/bindings/index.md): Data-binding map of Home · Home: every field to its source, and what each required state shows.
- [S17 Library · Library](/design/hifi/s17/index.md): Contract, a board per state (loading, list, language-en, filtered, filter-empty, error, empty, offline), tokens and strings.
- [S17 bindings](/design/hifi/s17/bindings/index.md): Data-binding map of Library · Library: every field to its source, and what each required state shows.
- [S18 Read · Read](/design/hifi/s18/index.md): Contract, a board per state (normal, long-scroll, dynamic-type-xl, loading, empty, error, offline), tokens and strings.
- [S18 bindings](/design/hifi/s18/bindings/index.md): Data-binding map of Read · Read: every field to its source, and what each required state shows.
- [S19 Record · Retell · round 1](/design/hifi/s19/index.md): Contract, a board per state (idle, recording, paused, autostop, too-short, permission-denied, interrupted, loading, empty, error, offline), tokens and strings.
- [S19 bindings](/design/hifi/s19/bindings/index.md): Data-binding map of Record · Retell · round 1: every field to its source, and what each required state shows.
- [S20 Processing · Processing](/design/hifi/s20/index.md): Contract, a board per state (uploading, transcribing, assessing, failed, unreliable, long-wait, offline, loading, empty, error), tokens and strings.
- [S20 bindings](/design/hifi/s20/bindings/index.md): Data-binding map of Processing · Processing: every field to its source, and what each required state shows.
- [S21 Feedback · Feedback](/design/hifi/s21/index.md): Contract, a board per state (full, low-confidence, achieved, playback, exemplar-pending, exemplar-failed, loading, empty, error, offline), tokens and strings.
- [S21 bindings](/design/hifi/s21/bindings/index.md): Data-binding map of Feedback · Feedback: every field to its source, and what each required state shows.
- [S22 Compress · Second take · round 2](/design/hifi/s22/index.md): Contract, a board per state (idle, recording, paused, autostop, too-short, permission-denied, interrupted, loading, empty, error, offline), tokens and strings.
- [S22 bindings](/design/hifi/s22/bindings/index.md): Data-binding map of Compress · Second take · round 2: every field to its source, and what each required state shows.
- [S23 Complete · Complete](/design/hifi/s23/index.md): Contract, a board per state (improved, same, shorter-lost, level-up, achievement, replayed, loading, empty, error, offline), tokens and strings.
- [S23 bindings](/design/hifi/s23/bindings/index.md): Data-binding map of Complete · Complete: every field to its source, and what each required state shows.
- [S24 Growth · Growth](/design/hifi/s24/index.md): Contract, a board per state (empty, baseline, ready, gap, loading, error, offline), tokens and strings.
- [S24 bindings](/design/hifi/s24/bindings/index.md): Data-binding map of Growth · Growth: every field to its source, and what each required state shows.
- [S25 Profile · Me · anonymous user](/design/hifi/s25/index.md): Contract, a board per state (normal, loading, empty, error, offline), tokens and strings.
- [S25 bindings](/design/hifi/s25/bindings/index.md): Data-binding map of Profile · Me · anonymous user: every field to its source, and what each required state shows.
- [S26 Profile · This week's quests](/design/hifi/s26/index.md): Contract, a board per state (default, loading, empty, error, offline), tokens and strings.
- [S26 bindings](/design/hifi/s26/bindings/index.md): Data-binding map of Profile · This week's quests: every field to its source, and what each required state shows.
- [S27 Profile · Settings](/design/hifi/s27/index.md): Contract, a board per state (default, language, delete-data-confirm, delete-account-confirm, loading, empty, error, offline), tokens and strings.
- [S27 bindings](/design/hifi/s27/bindings/index.md): Data-binding map of Profile · Settings: every field to its source, and what each required state shows.
- [S28 Profile · Sign in with Apple upgrade](/design/hifi/s28/index.md): Contract, a board per state (sheet, loading, empty, error, offline), tokens and strings.
- [S28 bindings](/design/hifi/s28/bindings/index.md): Data-binding map of Profile · Sign in with Apple upgrade: every field to its source, and what each required state shows.
- [S29 Profile · Privacy & AI disclosure](/design/hifi/s29/index.md): Contract, a board per state (default, loading, empty, error, offline), tokens and strings.
- [S29 bindings](/design/hifi/s29/bindings/index.md): Data-binding map of Profile · Privacy & AI disclosure: every field to its source, and what each required state shows.
- [S30 Global · Resume session](/design/hifi/s30/index.md): Contract, a board per state (sheet, loading, empty, error, offline), tokens and strings.
- [S30 bindings](/design/hifi/s30/bindings/index.md): Data-binding map of Global · Resume session: every field to its source, and what each required state shows.
- [S31 Global · Leave recording confirm](/design/hifi/s31/index.md): Contract, a board per state (alert, loading, empty, error, offline), tokens and strings.
- [S31 bindings](/design/hifi/s31/bindings/index.md): Data-binding map of Global · Leave recording confirm: every field to its source, and what each required state shows.
- [S32 Global · Offline toast](/design/hifi/s32/index.md): Contract, a board per state (toast, loading, empty, error, offline), tokens and strings.
- [S32 bindings](/design/hifi/s32/bindings/index.md): Data-binding map of Global · Offline toast: every field to its source, and what each required state shows.
- [S33 Global · Generic error](/design/hifi/s33/index.md): Contract, a board per state (generic, loading, empty, error, offline), tokens and strings.
- [S33 bindings](/design/hifi/s33/bindings/index.md): Data-binding map of Global · Generic error: every field to its source, and what each required state shows.
- [S34 Global · Force update](/design/hifi/s34/index.md): Contract, a board per state (default, loading, empty, error, offline), tokens and strings.
- [S34 bindings](/design/hifi/s34/bindings/index.md): Data-binding map of Global · Force update: every field to its source, and what each required state shows.

### Files

- [Hi-fi gallery](/design/gallery/): Every screen and state as live HTML, in zh-Hans and en, with its spec panel; the paywall is interactive. Open gallery/ and pick a screen.
- [Example data](/design/examples/): The API-shaped example responses behind every number on the boards, per locale, indexed by index.json and validated against the contract.
- [tokens.css](/design/tokens.css): The design tokens the boards use (colour, type, spacing, radii, elevation, motion).
- [base.css](/design/base.css): The shared components the boards are built from.
- [base.js](/design/base.js): The board viewer: theme, type size, data-bind outlines, count-ups.
- [strings.json](/design/strings.json): Every client string, keyed, in en and zh-Hans.

## API

The contracts between the apps and the backend. The OpenAPI files are the source. Index: [llms.txt](/api/llms.txt) · All pages: [llms-full.txt](/api/llms-full.txt) (3 KB) · View: [API reference](/api/reference.html)

- [API](/api/index.md)
- [API reference](/api/reference.html): Both contracts rendered by Redoc: the client API and the admin API.
- [OpenAPI contract (client API)](/api/openapi.yaml): Every endpoint, schema and error of the client API, as it is in the repo.
- [OpenAPI contract (admin API)](/api/openapi-admin.yaml): The admin API the dashboard consumes (ADR-002), as it is in the repo.

## Backend

The Cloudflare Workers API: auth, sessions, the audio to ASR to assessment pipeline, settlement, growth, paywall, content operations. Index: [llms.txt](/backend/llms.txt) · All pages: [llms-full.txt](/backend/llms-full.txt) (28 KB)

- [Backend](/backend/index.md)

## iOS

The native iOS app, and what the App Store needs. Index: [llms.txt](/ios/llms.txt) · All pages: [llms-full.txt](/ios/llms-full.txt) (10 KB)

### Pages

- [iOS app](/ios/index.md)

### App Store

- [App Store assets](/ios/app-store-assets/index.md)
- [App Store compliance](/ios/app-store-compliance/index.md)

## Landing page

The public site: home with waitlist, privacy, terms, support, in en and zh-Hans. Index: [llms.txt](/landing/llms.txt) · All pages: [llms-full.txt](/landing/llms-full.txt) (5 KB) · View: [clarisay.com](https://clarisay.com)

- [Landing page](/landing/index.md)

## Dashboard

The operator dashboard for content operations, and its data binding to the admin API. Index: [llms.txt](/dashboard/llms.txt) · All pages: [llms-full.txt](/dashboard/llms-full.txt) (39 KB) · View: [Operator dashboard (dash.clarisay.com, behind Cloudflare Access)](https://dash.clarisay.com)

- [Dashboard](/dashboard/index.md)
- [Dashboard data binding](/dashboard/data-binding/index.md): Every visible data point to its admin API path and field.

## Decisions

The app's ADRs. Binding once accepted. Index: [llms.txt](/decisions/llms.txt) · All pages: [llms-full.txt](/decisions/llms-full.txt) (25 KB)

- [ADR-001: product decisions](/decisions/adr-001/index.md): Every open decision in the PRD, resolved: training path, scoring, rewards, accounts, paywall, languages.
- [ADR-002: content operations](/decisions/adr-002/index.md): Automated content supply, licensed sources and AI originals, QA, auto-publish, the admin API.

## Go live

What must be true before launch, and every secret the app uses. Index: [llms.txt](/go-live/llms.txt) · All pages: [llms-full.txt](/go-live/llms-full.txt) (2 KB)

- [Go-live checklist](/go-live/index.md)
- [Secrets inventory](/go-live/secrets-inventory/index.md)