docs: rewrite apps/docs and packages/cli READMEs (#3)

Author: decimozs

apps/docs/README.md

@@ -1,45 +1,28 @@
-# docs
+# regtrace docs
 
-This is a Next.js application generated with
-[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
+Documentation site for [regtrace](https://github.com/decimozs/regtrace) built with Next.js and Fumadocs.
 
-Run development server:
+## Development
 
 ```bash
-npm run dev
-# or
-pnpm dev
-# or
-yarn dev
+bun run --cwd apps/docs dev       # dev server at http://localhost:3000
+bun run --cwd apps/docs build     # production build
+bun run --cwd apps/docs start     # serve production build
+bun run docs:typecheck            # typecheck docs source
 ```
 
-Open http://localhost:3000 with your browser to see the result.
+All commands are also available from the repo root via `bun run docs:*`.
 
-## Explore
+## What's here
 
-In the project, you can see:
+| Path | Content |
+|---|---|
+| `content/docs/` | All documentation pages (MDX) |
+| `content/docs/reference/` | CLI, config, golden set references |
+| `content/docs/explanation/` | Architecture, how it works |
+| `content/docs/how-to/` | CI integration guides |
+| `content/docs/troubleshooting/` | Common issues and fixes |
+| `lib/` | Fumadocs content source config |
+| `app/` | Next.js pages and layouts |
 
-- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
-- `lib/layout.shared.tsx`: Shared options for layouts, optional but preferred to keep.
-
-| Route                     | Description                                            |
-| ------------------------- | ------------------------------------------------------ |
-| `app/(home)`              | The route group for your landing page and other pages. |
-| `app/docs`                | The documentation layout and pages.                    |
-| `app/api/search/route.ts` | The Route Handler for search.                          |
-
-### Fumadocs MDX
-
-A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
-
-Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
-
-## Learn More
-
-To learn more about Next.js and Fumadocs, take a look at the following
-resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
-  features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs
+Stat: 99 pages, 0 build errors.

packages/cli/README.md

@@ -1,15 +1,50 @@
-# cli
+# `regtrace` CLI
 
-To install dependencies:
+The regtrace CLI binary — evaluates LLM outputs against golden-set expectations across Factuality, Format, Tone, and Regression.
+
+## Development
 
 ```bash
-bun install
+bun install                        # install workspace deps
+bun run --cwd packages/cli test    # run 159 tests
+bun test -t "test name"           # single test by name
 ```
 
-To run:
+## Build
 
 ```bash
-bun run index.ts
+bun run build                      # compile + minify → ./regtrace
+bun run build --outfile ./myname   # custom output path
+```
+
+Uses `bun build --compile --minify src/index.ts`. Version injected via `--define __VERSION__`.
+
+## Layout
+
 ```
+src/
+├── cli/          Commander commands (run, init, list, history, watch, baseline)
+├── judge/        LLM providers (anthropic, openai, gemini, groq, ollama)
+├── metrics/      Evaluators (factuality, format, tone, regression)
+├── reports/      Terminal, JSON, markdown reporters + quality gates
+├── schema/       Zod v5 schemas (config, golden-set, run-record)
+├── storage/      Config/GS loading, JSON/SQLite persistence
+├── utils/        Concurrency, env, hashing, logging
+└── index.ts      Entrypoint
+tests/
+├── unit/         Unit tests mirrored to src/ structure
+├── integration/  cli.test.ts, baseline.test.ts
+└── fixtures/     Configs, golden sets, run records
+```
+
+## Conventions
+
+- No comments in source. Self-documenting code only.
+- Zod v5 for schemas. No `z.infer` — write explicit types.
+- `noUncheckedIndexedAccess: true` — always guard array access.
+- Biome lint/format: tabs, double quotes.
+- CLI output via `src/cli/print.ts` — never raw `console.log`.
+
+## Integration tests
 
-This project was created using `bun init` in bun v1.3.14. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+Spawn `Bun.spawn` child processes with minimal env. Temp dirs under `.test-tmp/`. Two tests have pre-existing stream-race flakiness; CI uses `--retry 2`.