How these docs work

The docs of Shuke are Markdown files in this repo, next to the code they describe. docs/manifest.json lists every page by module. @botgumi/docs builds them into docs for agents (botgumi ADR-0005) and a small HTML site, in docs/public/, which is committed.

#Modules

Module	Pages	Owner
overview	the repo README, this page	docs
product	the PRD review; the extracted PRD text as a file (no tracking plan page yet; ADR-001 D12 names the events)	docs
design	brand, design system, lo-fi, hi-fi screens with their data-binding maps, screenshot direction	design
api	the API page; the OpenAPI file, linked as it is	docs
backend, ios, landing, dashboard	each track's README and specs; the App Store checklists under ios (Shuke ships iOS only)	that track
decisions	the app's ADRs	docs
go-live	the go-live checklist, the secrets inventory	docs

A new page is a Markdown file plus one line in docs/manifest.json, under its module.

#What gets built

Path	What
/llms.txt	Every module and page, grouped by module
/llms-full.txt	Every page in one file
/{module}/llms.txt	One module's pages
/{module}/llms-full.txt	One module's pages in one file
/{module}/{page}/index.md	One page as Markdown, with its title, description and source
/{module}/{page}/	The same page as HTML
/api/openapi.yaml, /api/openapi-admin.yaml	The contracts, as they are

Any page URL also answers Markdown when the request sends Accept: text/markdown.

#Run

pnpm docs:dev     # http://127.0.0.1:4321, rebuilt from the Markdown on every request
pnpm docs:build   # writes docs/public/; commit it with the change
pnpm docs:check   # CI: fails when docs/public/ is not what a build would write, or a source is missing

An agent working in this repo can read docs/public/llms.txt and the index.md files directly, without a server.

#Host

docs/wrangler.jsonc deploys docs/public/ as a Cloudflare Worker with static assets on docs.clarisay.com (docs/worker.ts answers Markdown requests and sets the content types). The PRD is private, so the hostname sits behind Cloudflare Access by default: one Access application for docs.clarisay.com, allowing the owner. The workers.dev and preview URLs are off, so Access cannot be bypassed. Making the docs public is the owner's choice: remove the Access application.

pnpm docs:deploy

#Keeping them current

• Every PR that changes behaviour, a contract or a design updates its module's page and runs pnpm docs:build. The reviewer blocks a PR whose docs do not match its change.
• pnpm docs:check runs before a PR and in CI (.github/workflows/design.yml). @botgumi/docs is botgumi's published package, installed from GitHub Packages by npm alias ("@botgumi/docs": "npm:@ottervolt-labs/botgumi-docs@0.1.0", botgumi ADR-0006 D10); pnpm install needs NODE_AUTH_TOKEN, a token with read:packages (.npmrc).
• The botgumi upgrade PR refreshes the copied checklists and rebuilds the docs.