Documentation index
Everything written down about core, and where it lives.
This folder holds only what spans the whole system. Anything specific to one service lives with that service, so it stays next to the code that can make it wrong.
Start here
| architecture.md | How the pieces fit together. Read this first. |
| api-surfaces.md | Customer publication policy and the private route catalog. |
| public-documentation.md | API wording, overview pages, search metadata, and owner check marks. |
| email-forwarding.md | Signed incoming support email and inbox forwarding. |
| errors.md | The response envelope and the error contract, for contributors and for consumers. |
| deployment.md | What ships where, and how a change reaches production. |
| search-visibility.md | Search Console checks after publishing the site and docs. |
| commits-and-releases.md | Commit subjects, reviewed public release notes, and changelog repairs. |
| infrastructure.md | Standing the VPS up from scratch, and how it behaves once running. |
| operations.md | One-time procedures, production data access, package releases. |
| testing.md | Focused commands and the standard for retaining tests. |
| Core Tower | coto, the read-only CLI for production errors, alerts, releases and business numbers. |
Per-service
Each service documents itself. Go there for anything specific.
| Service | Docs | What it is |
|---|---|---|
apps/api | apps/api/docs/ | The Hono API gateway. Auth, credits, routing, observability. |
apps/worker | apps/worker/docs/ | The Python fetch worker. Module map, env vars, per-site routes. |
apps/web | apps/web/ | The two Next.js apps and the shared UI design guide. |
The public API reference is not in this repo as prose. It is generated from
/openapi.json and published at docs.toolzerhub.com; the site that builds
it is apps/web/toolzerhub-docs/, which is a deployed app rather than
documentation about one.
Reference material
research/ | Per-site reverse-engineering notes — what each source exposes, how it gates, what was tried and failed. One folder per site. |
research/METHODOLOGY.md | The playbook for researching a new site. Read before adding one. |
infrastructure/runbooks/ | What to do when a specific alert fires. One file per alert. |
AGENTS.md | Conventions this codebase enforces. The rules; errors.md is the reasoning. |
Rules
Two, both learned the hard way:
Code wins. When a document and the code disagree, the code is right and the document is a bug. Fix it or delete it — do not reword it.
Do not write what the code already says. A document that restates a file tree or a function signature is guaranteed to go stale and buys nothing. Write down the reasoning, the constraint, the thing that looks wrong until explained.