> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation

> Where docs live, doc rules, i18n, docs sync, the coverage lifecycle, and the link strategy

# Documentation

This guide owns docs placement, the doc rules, i18n, docs sync, the coverage lifecycle and the link strategy.

## Placement and rules

* English source lives in `docs/`. `docs/zh-CN/**` and `docs/ja-JP/**` are generated; do not edit them directly.
* i18n pipeline: update the English page, adjust `docs/.i18n/glossary.zh-CN.json`, then run `scripts/docs-i18n`.
* Internal doc links are root-relative with no `.md` or `.mdx` extension, for example `[Config](/configuration)`. When a page is mapped to a different site route, use its absolute `https://docs.wednesdayai.dev/...` URL so unchanged sync output targets the published page.
* Headings avoid em dashes and apostrophes, because they break anchor generation.
* Content must be generic: no personal device names, hostnames, or paths. Use placeholders such as `user@gateway-host`.
* Store screenshots under `docs/.screenshots/` (gitignored). Never commit screenshots or leave them at the repo root.
* Frontmatter uses `title`, `summary` and `read_when`. Developer pages add `audience: developer`.
* After editing docs, run `pnpm check:docs` (format, docs lint and the link audit). `pnpm docs:list` lists docs for a quick sanity check.
* When code, a README or a skill links to `https://docs.wednesdayai.dev`, run `pnpm docs:check-site-links`. It needs network access. It checks every such link the repo emits against the live site's `sitemap.xml` and page anchors, and reports any route missing from site navigation or any anchor missing from its page. It also runs weekly (`.github/workflows/docs-site-links.yml`) and opens a `docs site link gaps` issue. A route that fails only because the page is not synced yet clears once `scripts/docs-sync.sh` publishes it.

## Docs sync

The docs site repository (`ExpansionX/WednesdayAI-docs`, Mintlify at `docs.wednesdayai.dev`) holds three versions of the same pages:

* The **latest release** sits at the root (`admin/`, `users/`, `developers/`, `reference/`, `index.mdx`, `changelog.mdx`). It is the default version, so its URLs never change.
* `next/` is the unreleased version. `scripts/docs-sync.sh` rebuilds it from one core `main` SHA after every core merge.
* `vA.B/` directories pin older release minors, newest first.

```
docs repo root
├── docs.json                 navigation.versions: latest (default) | next | vA.B ...
├── admin/ users/ developers/ reference/ index.mdx changelog.mdx   latest release
├── next/admin/ ... next/changelog.mdx                             unreleased
├── v0.6/admin/ ...                                                pinned snapshot
└── .wednesdayai-sync/next.json release.json                       source SHA markers
```

Edit core, never the docs repo, for any synced page. A fix made in the docs repo is overwritten by the next sync.

`scripts/docs-sync.sh` syncs English core docs to the site through the single `mapCoreDocToPersona` mapping in `scripts/docs-drift.mjs` (`gateway/` to `admin/gateway/`, `CONTRIBUTING.md` to the single page `developers/contributing`, and so on). Only pages listed in a `dev-docs/wai-feature-list.json` feature under `core_doc_paths` are synced; `scripts/docs-sync.test.ts` enforces that every `docs-surface.yaml` entry whose `docs_page` is the persona-mapped target of its core `source` is covered. When the site page already exists, `scripts/docs-sync-frontmatter.mjs` merges the frontmatter: core keys win and site-only keys (`description`, `sidebarTitle`) are kept.

Two gates run in core before anything is published:

* `pnpm docs:check-mdx` compiles every published core doc with `@mdx-js/mdx` (issue #2519). HTML comments and bare `<word>` placeholders in prose fail; use the repo's MDX comment form `{/_ note _/ && null}` (oxfmt-stable in `.md`) and backticks instead.
* `pnpm docs:check-published-links` resolves every internal link and image of the published docs against core. A link must reach a published core doc, an existing asset, or a docs-repo page route.

After a core PR merges, run `scripts/docs-sync.sh` once from the repo root. It rebuilds `next/` from a single core SHA on a fresh `docs-sync/next` branch, force-pushes, and squash-merges its own PR; never merge docs-sync PRs by hand. It skips the run when docs `next` is already at or past that SHA, and it exits with guidance when the site has no versions yet. The one-time bootstrap is `scripts/docs-sync.sh --release <latest tag> --ref origin/main`: `--ref` overrides the release source when the tag predates a sync fix, and the run prints the override. `scripts/docs-sync.sh --dry-run` prints the mapping and pushes nothing; `--feature <slug>` narrows a dry run only.

`scripts/docs-sync.sh --release vX.Y.Z` cuts the default version from the tag. On a minor bump it snapshots the previous root to `vA.B/`; retention keeps four minors (the latest at the root plus three snapshots) and a pruned version redirects `/vX.Y/:slug*` to `/:slug*`. It sets the release banner, opens the `docs: WednesdayAI vX.Y.Z` PR, and merges it only once the GitHub release is published (not draft): rerun the command after publishing. See [Release](https://docs.wednesdayai.dev/next/developers/contributing/release.md).

Adding a new page takes two steps: add the core doc to the feature's `core_doc_paths` in `dev-docs/wai-feature-list.json`, then add the page to the `next` version's navigation in the docs repo's `docs.json` (next mode never edits docs.json). At release, the root navigation takes over whatever `next` carried.

The sync rewrites internal links and images to their own version prefix and copies images to content-addressed `media/` paths shared by every version.

## Docs coverage lifecycle

* **Source of truth**: `docs-surface.yaml` at the repo root maps every documentable surface (hook, SDK export, config key, channel, provider, CLI command, concept) to its expected docs page. It is the single mapping; the docs repository never holds a second copy.
* **Two tiers**:
  1. A cheap deterministic gate, `scripts/docs-surface-check.mjs`, runs locally before a PR (the core `docs-surface.yml` workflow is archived; ADR 2399). `node scripts/docs-surface-check.mjs --mode=source` checks that each `source` path still exists. `--mode=pages --docs-root=<docs checkout>` (docs CI) checks that each `docs_page`, plus optional `#anchor`, resolves.
  2. A periodic deep audit, a manual review of real surfaces against `docs-surface.yaml`, finds new undocumented surfaces that the cheap gate cannot see.
* **Advisory only**: branch protection is unavailable on the free-plan private repo, so the check never hard-fails a merge. It exits `0` and prints warnings. `--strict` (`pnpm docs:surface:strict`) gives a non-zero exit.
* **Cadence**: run the cheap gate before each PR that touches a documentable surface. Run the deep audit each release cycle and after large surface changes.
* **Follow-ups**: a detected gap becomes a tracked follow-up, keyed by the surface `id` so it is idempotent: a GitHub issue (label `docs-coverage`). Entries with `coverage: gap` or `wrong` carry the known-bad baseline until a docs PR flips them to `documented`.

## Link strategy

The core repository is private. A link resolves only if the reader can reach its target.

| File class | Readers | Allowed links |
| - | - | - |
| npm-shipped (`README.md`) | npm, public GitHub mirrors | Absolute `https://docs.wednesdayai.dev/...` URLs, Discord, `mailto:`. Images by absolute public URL. An npm version badge, not private CI badges |
| Published to the site (`docs/**`, the `CONTRIBUTING.md` rendering) | Public | `docs/**`: root-relative, no `.md`, or absolute site URLs for mapped routes. `CONTRIBUTING.md`: absolute site URLs. Repo-only files are named as code paths, never hyperlinked |
| Repo-only (`AGENTS.md`, `ARCHITECTURE.md`, `ROADMAP.md`, `VISION.md`, `SECURITY.md`, `SUPPORT.md`, `CODE_OF_CONDUCT.md`, `dev-docs/**`, `.agents/**`) | People with repo access | Repo-relative paths, and site URLs for published topics |

`SUPPORT.md` and the `CONTRIBUTING.md` rendering state the security contact (`security@expansionx.com.au`) inline, so the public path never depends on reading `SECURITY.md`.

## Related

* [Coding style](https://docs.wednesdayai.dev/developers/contributing/coding-style.md)
* [Release](https://docs.wednesdayai.dev/developers/contributing/release.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.