---
title: "How these docs work"
source: "docs/README.md"
---

> Part of [Overview](/overview/llms.txt). Every page: [llms.txt](/llms.txt).

# 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

```bash
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.

```bash
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.