# homepage/content — provenance and drift rules

This directory holds the hand-written documentation rendered at `/docs/`. It is
**not** a route: nothing under `content/` is served, and this file in particular
exists for whoever edits the docs next.

## Why these are hand-written rather than rendered from the root docs

The obvious move is to render `SETUP.md`, `PUBLISH.md` and friends
directly, and keep one copy. That was rejected for a decisive reason:

> `SETUP.md` was written for a contributor with the repository, and its
> acquisition path is not the public one. The public copy is the read-only
> mirror at `/source/archilyzer.git` (regenerated per deploy, with different
> commit ids) and the tarball at `/downloads/`; `docs/install.md` says so in
> an operator's terms. (Until release 12 there was no public repository at all,
> which is when this rule was made.)

The root docs also lean on contributor furniture that actively confuses an
operator: `pnpm wt` worktrees, the machine-global e2e queue, `plans/`, shard
counts, wall-time tables for the test suite. Someone who wants to archive a
channel does not need to know that the e2e suite serializes on a lock file.

## The accepted cost

These pages will drift from the root docs. That is the trade, taken knowingly.
Symlinking or transcluding would only move the problem: the two audiences
genuinely want different documents, and a shared file would end up serving
neither. The mitigation is this table — when you change a root doc, check whether
its public counterpart needs the same change.

| Public page | Derived from | Watch for drift in |
|---|---|---|
| `docs/what-is-archilyzer.md` | `README.md` | package list, pipeline modes |
| `docs/install.md` | `SETUP.md` | tool versions, env-var table, backend list, the Windows path |
| `docs/operate.md` | `README.md`, `SCHEDULED_SYNC.md` | editor routes, scheduler settings |
| `docs/deploy-cloudflare.md` | `PUBLISH.md` (Cloudflare, R2, cost-abuse) | the 25 MB Pages limit, R2 options |
| `docs/deploy-docker.md` | `PUBLISH.md` (building every site in containers) | phase structure, settings names |
| `docs/ai-and-mcp.md` | `mcp/README.md`, `README.md` §1 and §4 | tool names, `corpus.json` shape, the Ten-minute setup's commands, `pnpm --silent -C … archilyzer mcp` (README §1/§4, mcp/README's "Add to Claude Code" and its `mcp.json`, and AGENTS.md's no-corpus block are copies of them: change them together) |
| `docs/faq.md` | — (written for this site) | claims about cost and hardware |

## House rules for these files

- **No frontmatter.** Title, blurb, group and order live in `content/docs.ts`.
- **No raw HTML and no `<!-- comments -->`.** The renderer is `markdown-to-jsx`
  with `disableParsingRawHTML` **off**, so raw markup would be parsed and
  rendered, not escaped. (The header comment on
  `common/components/Markdown.tsx` claims otherwise; it is wrong.)
- **Relative links** to other doc pages (`/docs/install/`) render as client-side
  navigation; absolute `http(s)://` links open in a new tab. That behaviour is
  in `app/components/DocBody.tsx`, not in the Markdown.
- **A leading `# Title` is stripped** by the loader, because the page renders its
  own `<h1>` from the manifest. Keep it in the file anyway so each document is
  valid standalone.
- **Adding a page** means adding the file *and* the `DOCS` entry. A manifest
  entry whose file is missing is filtered out of both the index and
  `generateStaticParams`, so it 404s rather than breaking the build — which is
  the safe failure, but it is still a mistake.