CLAUDE.md@.claude/apps/dev-tools-help-docs git:20261006.8052ed0A

Immutable. This exact content never changes and is served at /api/v1/blob/a62607781da0b88f.

# CLAUDE.md — `apps/dev-tools-help-docs`

The documentation site (1computer.online): Next.js + Fumadocs,
with AI chat, full-text search, and an auto-generated API reference built from
TypeScript types and OpenAPI specs.

## The one rule everyone trips on

**This is the only Biome workspace in the repo.** `check`, `lint`, `format` and
`check:write` here are Biome; nothing outside `apps/dev-tools-help-docs` is
formatted by it and there is no repo-wide formatter. Never run Biome over the
rest of the monorepo — it will rewrite files that nobody formats that way.

It also carries its own `commitlint.config.ts`, `cspell` config and
`bunfig.toml`, all scoped to this app.

## Content comes from two places

- `content/docs/` — pages written here.
- Package READMEs, pulled in by `bun run docs:sync` (root) or
  `bun ./scripts/sync-readme-docs.ts`. **Synced pages are generated** — edit the
  package README, then re-sync. Editing the synced copy is lost on the next run.
  Every `packages/*` folder with a README is synced; add new packages to the
  `PACKAGES` list in the script for a proper title / icon / category, or they
  land under "Other" with the `Package` icon. `.github/workflows/docs-sync.yml`
  runs the sync on every push to `master` that touches a README and commits
  the result. Hand-written pages in the synced folders (no generated banner)
  are left alone.

Remember the package README's own header is itself generated by
`bun run readmes`, so the chain is:
`package.json` → `.github/scripts/sync-package-readmes.mjs` → `README.md` → `docs:sync`
→ this site.

## Build is staged

```bash
bun run dev
bun run build          # bun --bun next build
bun run build:full     # build:pre → next build → build:post
bun run typecheck      # runs typegen (fumadocs-mdx + next typegen) first
```

`postinstall` runs `fumadocs-mdx`. A missing content type or a "cannot find
`.source`" error after a fresh clone almost always means that did not run —
re-run `bun install` or `bunx fumadocs-mdx` rather than hand-writing the type.

## Renders `code-tree-graph`

The dependency graphs, file trees and type tables on this site come from
`packages/code-tree-graph`. A change to that package's props breaks the docs
build, not its own tests.

## Sections and search

`content/docs/meta.json` lists three root folders, each a separate tab with its
own sidebar: `(index)` (Docs), `api-reference` and `changelog`. A new top-level
section needs `"root": true` in its `meta.json` and an entry in the root
`meta.json`. Search results are tagged by that first path segment, so update
`src/lib/constants/tags.ts` and `category.ts` too.

API Reference pages render `<APIPage document="…" />`; the schema IDs are
registered in `src/lib/openapi/index.ts` (currently `verify-phone-sms`, read
straight from the package's `openapi.json`).

The search bar lives in the sidebar, not the navbar, using
`src/components/fumadocs/layout/sidebar-search.tsx` — a copy of the same file
in `starter-templates/template-fumadocs`. Keep the two in sync.

## Homepage package catalog

The homepage (`src/app/(home)/`) is driven by `packages-data.ts`: each entry
has a short `description` (cards, search), a `longDescription` (hover text in
the `HeroParallax` showcase), an `href` and an `image`. The images in
`public/packages/*.svg` are **generated** — after changing a package's name,
description, icon or commands, run `bun ./scripts/generate-package-covers.tsx`
and commit the output.