Shukellms.txt

Overview

Shuke (codename) — 每天十分钟，把复杂的事讲清楚

Working codename: Shuke / 述刻. Final app name, branding and domain are TBD; everything brand-specific lives behind a single token layer so it can be swapped later.

The repo follows the botgumi template, version 0.0.0+1b57100 (see .botgumi.json): agent instructions in AGENTS.md and .claude/agents/, the design stages in design/, docs for agents in docs/, the checklists in docs/checklists/. Shuke predates the template, so its tracks keep their own CI and the design gates are retroactive (design/README.md).

A spoken-expression trainer (multilingual: English and Simplified Chinese first, built for more). The user reads a short article, retells it aloud in their own words, gets AI feedback with one thing to change, retells it compressed, and sees a measurable delta. iOS-first, subscription business model with a hard paywall after a free diagnostic.

Repository layout

Path What Stack Owner PR label
docs/ PRD, review, decisions (ADRs), API contract, prototype references Markdown / OpenAPI 3.1 docs
design/ Hi-fi design: tokens, screens (HTML), flows, states, onboarding, paywall prototype, data-binding tables; the five botgumi stages on top (brand/, system/, lofi/, hifi/, screenshots/, see design/README.md), checked by node design/check.mjs Static HTML/CSS/JS, stdlib Python generators design
backend/ API + AI pipeline Cloudflare Workers, Hono, D1, R2, KV, Queues, Workers AI; dynamic AI providers (ASR / LLM / TTS) backend
landing/ Super simple landing page TanStack Start, deployed to Cloudflare landing
ios/ Native iOS app Swift 6, SwiftUI, iOS 17+, XcodeGen, RevenueCat (StoreKit 2), Sign in with Apple local ios/scripts/ci.sh (no GitHub CI)
dashboard/ Operator dashboard for content ops (sources, generation, review queue, providers, quality) TanStack Start, Cloudflare Access, talks to /v1/admin/* dashboard
docs/public/ Docs for agents, built from every page in docs/manifest.json (pnpm docs:build) @botgumi/docs, Cloudflare Worker behind Access docs

Source of truth (read in this order)

  1. docs/prd/prd-v1.0-extracted.txt — the original PRD (Chinese).
  2. docs/prd/PRD-REVIEW.md — TPM review: gaps, risks, what changed.
  3. docs/decisions/ADR-001-product-decisions.md — every open decision in the PRD, resolved. Binding.
  4. docs/api/openapi.yaml — the API contract between ios/ and backend/. Binding. Change it via PR with both sides updated.
  5. docs/decisions/ADR-002-content-operations.md + docs/api/openapi-admin.yaml — automated content supply (licensed sources + AI originals, QA, auto-publish) and the admin API the dashboard consumes. Binding.
  6. design/README.md — design system and screen specs (produced by the design track).

Working agreement

  • Trunk is main. All work lands via PR from a branch named <track>/<topic> (e.g. backend/sessions-pipeline).
  • Every PR: description (what / why / how tested), passing CI for its track, no cross-track edits unless the PR says so.
  • The API contract is the integration boundary. If a client needs a field, add it to docs/api/openapi.yaml first.
  • Every visible data point in the app must be traceable to an API field or a documented local state (see design/data-binding.md).
  • No fake data in production paths. Seeded demo content is explicitly labelled source: "seed".
  • The product is multilingual. UI locales in v1: en, zh-Hans; practice/content languages in v1: en, zh-Hans (see ADR-001 D13). Code, commits and docs are in English.

Docs

Every page about this app is Markdown in this repo, listed by module in docs/manifest.json and built into docs/public/: /llms.txt (every page by module), /llms-full.txt, each module's llms.txt and llms-full.txt, and index.md for every page. Agents read docs/public/llms.txt first. pnpm docs:dev serves them locally, pnpm docs:build rewrites docs/public/ (commit it with the change) and pnpm docs:check fails when it is stale; docs/README.md says how they are hosted. Install with pnpm install at the repo root; botgumi's packages come from GitHub Packages, so set NODE_AUTH_TOKEN to a token with read:packages first (.npmrc). CI runs the docs check.

Getting started

# backend
cd backend && pnpm install && pnpm dev

# landing
cd landing && pnpm install && pnpm dev

# ios
cd ios && xcodegen generate && open Shuke.xcodeproj

# docs and design checks, at the repo root (botgumi's packages: a token with read:packages)
gh auth refresh -s read:packages && export NODE_AUTH_TOKEN=$(gh auth token)
pnpm install && pnpm docs:check && pnpm design:check