A brief on Brief

# Brief Usage Guide

Brief is a documentation framework. It builds a documentation site from page files and
configuration that describes how those pages are organized. It supports navigation, multiple
versions and languages, search, and text outputs that agents can read. The included starter
uses Next.js and CoMark Markdown.

## Repair diagnostics

When asked to repair a problem, make the repair and verify it before finishing; diagnosis or a
proposed next step is not completion. Start with `brief check`. Choose `--json` instead of the
text report when you need structured codes or fix proposals; do not run both without a reason.
Read the reported file and help before exploring unrelated commands or configuration.

Prefer an offered `brief check --fix` correction to a manual rewrite. Use `--dangerous` only
after confirming that the proposed destination or ordering matches the request. Preview with
`--dry-run` if the scope is uncertain. The fix command revalidates the result and reports remaining
diagnostics: read that report before running another check or changing the repaired value again.
If a fix is unavailable or skipped, correct the source directly using the diagnostic's guidance.

Invalid directory names are excluded from the index, so structural CLI commands cannot address
them. Rename the directory on disk, preserve its contents, and update any parent order entry and
links that refer to it. This source repair is an exception to using the CLI for structural changes.

For manual edits, verify with `brief check` once afterward. Check that the requested diagnostic
is absent and that every requested property is satisfied, not just that the command exits zero.
Warnings and tips do not fail the command. Preserve explicit configuration requirements instead
of relying on a default that happens to produce the same output today. Stop when the repair is
complete; report unrelated findings without broadening the task.

An invalid `order` declaration can block structural commands. Correct its metadata directly or
use the offered fix. Ordering commands position an entry and write a resolved list; they are not
needed to repair repeated entries or rest markers and can remove an intentionally retained `...`.
Broken-link and anchor suggestions require checking the intended destination; preserve the label,
query string, and fragment. Match heading depth to the actual hierarchy without adding empty sections.

Use `brief tree` when paths or navigation are unclear, not before every content repair. For an
unfamiliar format or configuration contract, consult the supplied docs or the installed public
types before guessing through repeated edits. When searching Markdown in a shell, single-quote
literal patterns containing backticks or `$()` so the shell does not execute the examples.

## Content and authoring

A site contains tabs, such as guides and API reference. Each tab contains versions, and each
version contains pages and groups of pages. Groups can contain other groups.

Each page has its own folder. In a CoMark project, it contains one Markdown file per language,
such as `en.md` and `pt-PT.md`. The YAML block at the top of each file, called
frontmatter, contains its title, description, and optional URL slug:

```md
---
title: Create a page
description: Add a documentation page with the Brief CLI.
---

## Add the page

Run `brief page add docs/v1/getting-started` to create a page in the docs tab's v1 version.
```

The standard Brief UI displays the title as the page's H1 heading. Start headings in the body
at H2 (`##`) to avoid repeating it. Follow the project's examples and schemas when adding other
frontmatter fields.

Settings shared by all translations belong in `page.meta.toml`. These include `draft`,
`redirectFrom`, and `routeKey`. The route key is a stable identifier that lets Brief recognize
the same page after it moves. Keep it when moving a page. Site, tab, version, and group settings
belong in their respective `*.meta.toml` files; their `order` fields control navigation order.

Link to the URL a reader would visit, including its language, tab, version, and heading fragment
where needed. Do not link to the Markdown file on disk. Brief checks whether the destination
exists; it does not guess which version or translation you intended.

CoMark adds components to Markdown through directives. Use the components and properties
configured by the project. For example, the standard UI includes this callout:

```md
:::Callout{color="yellow" icon="warning" title="Before you start"}
Create the tab and version before adding a page inside them.
:::
```

## Prefer the CLI for structure

Use the CLI to add, move, and remove documentation. These commands update the files that describe
the site's structure and can fix links when URLs change. Edit page prose directly. Use settings
commands for metadata when the page format supports them.

Inspect a target with `brief page inspect docs/v1/getting-started --locale en --json`.
The result includes authored values, effective values, source files, and published routes.
Use `page update`, `group update`, `tab update`, `version update`, or `site update` to change
settings. Structural paths are relative to the documentation root; site commands need no path.

```sh
pnpm exec brief page update docs/v1/getting-started --locale en --title "Getting started"
pnpm exec brief page update docs/v1/getting-started --hidden true --dry-run
pnpm exec brief page update docs/v1/getting-started --unset hidden
```

Boolean flags take `true` or `false`. `--set key=JSON` accepts typed values such as arrays;
`--unset key` removes a declaration. `--input file.json` (or `--input -` for stdin) accepts
`{"set":{},"unset":[],"custom":{"set":{},"unset":[]}}`. Custom metadata uses the explicit
`custom` object and cannot overwrite built-in fields. Locale-specific structural edits write
the locale override file. Page-wide settings remain in `page.meta.toml`.
Changes are reloaded and validated before writing. Slug updates migrate supported links;
use `--no-update-links` to leave them unchanged and synchronize redirects before publication.
Settings commands can repair missing required metadata and route collisions from retained source.
Unrelated existing errors remain reported; new validation errors reject the edit. Malformed YAML
or TOML still needs a direct syntax correction. A repaired route collision must produce an
unambiguous index; link migration is unavailable when the original routes were ambiguous.

Run the installed CLI from the documentation app, for example with `pnpm exec brief`.
Page and group paths are relative to the documentation folder (`brief/case/` by default).
Use `brief tree` when you need to discover paths or inspect navigation. A page must belong to an
existing version. When the task already identifies the target, use the matching command directly;
inspect its help if you need an option. `page move` moves one page, while `group move` moves a group
and its descendants. Do not remove an emptied parent group unless that is part of the request.

```sh
pnpm exec brief page add docs/v1/getting-started --title "Getting started" --description "Create your first Brief page."
pnpm exec brief page move docs/v1/old-name docs/v1/new-name --dry-run
pnpm exec brief page move docs/v1/old-name docs/v1/new-name
pnpm exec brief page remove docs/v1/obsolete --redirect-to docs/v1/replacement
pnpm exec brief group add docs/v1/guides --title "Guides"
pnpm exec brief version add v2 --tab docs --from v1
pnpm exec brief locale add pt-PT --name "Portuguese (PT)"
```

### Command reference

Use `page order <path> --before <sibling-path>` or `--after <sibling-path>` to position an entry.
`--first` and `--last` are also available; no placement means last. Groups, tabs, and versions
have the same `order` command. Paths identify siblings under the same parent. The command writes
their current resolved sequence with the requested placement; future unlisted children still
appear at the bottom alphabetically. Use `--locale` for a localized order and `--dry-run` to preview.

Choose the command for the entry being positioned, not the metadata file that stores its order:
`group order` positions a group within its parent; `version order` positions a version within a tab.

Prefix each command with `brief`. Use `brief <command> --help` for its full options.

| Command                           | Purpose                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------ |
| `init [dir]`                      | Create a Next.js documentation site with CoMark, search, and agent skills.                 |
| `tree [path]`                     | Show the documentation structure; add `--all-versions` to include older versions.          |
| `check`                           | Check pages, settings, and links.                                                          |
| `page add <path>`                 | Add a page; set its `--title` and `--description`.                                         |
| `page move <from> <to>`           | Move a page and update supported links. Alias: `mv`.                                       |
| `page remove <path>`              | Remove a page; choose `--redirect-to <page>` or `--allow-404`. Alias: `rm`.                |
| `group add <path>`                | Add a group; set its `--title`.                                                            |
| `group move <from> <to>`          | Move a group and its pages. Alias: `mv`.                                                   |
| `group remove <path>`             | Remove a group and its pages; choose `--redirect-to <page>` or `--allow-404`. Alias: `rm`. |
| `tab list`                        | List the site's tabs.                                                                      |
| `tab add <tab>`                   | Add a tab with `--title <text>` and an optional initial `--version <name>`.                |
| `tab rename <tab> <name>`         | Rename a tab.                                                                              |
| `tab remove <tab>`                | Remove a tab and its pages; choose `--redirect-to <page>` or `--allow-404`. Alias: `rm`.   |
| `tab set-default <tab>`           | Choose the default tab.                                                                    |
| `version list`                    | List versions in a tab.                                                                    |
| `version add <version>`           | Copy a version with `--from <version>`, or start with `--empty`.                           |
| `version rename <version> <name>` | Rename a version.                                                                          |
| `version remove <version>`        | Delete a version and its pages; requires `--force`.                                        |
| `version set-default <version>`   | Choose the default version for a tab.                                                      |
| `locale list`                     | List the site's languages.                                                                 |
| `locale add <tag>`                | Register a language; provide its display name with `--name <text>`.                        |
| `locale remove <tag>`             | Remove a language from the site configuration; keep its content files.                     |
| `locale set-default <tag>`        | Choose the default language.                                                               |
| `updates sync [path]`             | Record changed body hashes and update times; defaults to all pages, including drafts.      |
| `redirects sync`                  | Record current page URLs and update redirects from older URLs.                             |
| `skills install`                  | Install the Brief skills; use `--agent`, `--dir`, or `--dry-run` as needed.                |
| `help [command]`                  | Show command help.                                                                         |

When a site has several tabs, version commands need `--tab`. `page add` creates files for every
language enabled for that version; complete them according to the project's translation policy.
Use `page add --extension` if the project supports several writable page formats. `locale add`
only registers the language, so translations still need to be written.

## Moving pages and keeping old links working

Moving a page creates two separate problems. Links in your documentation may still point to its
old URL, and readers may have bookmarked that URL or found it on another website.

`page move` addresses the first problem by updating links in your page files. Use `--dry-run`
to see the proposed changes before applying them. Link updates depend on the page format's
editing support, so read any notices about links left unchanged and run `brief check` afterward.
Use `--no-update-links` when you intend to leave links unchanged.

A redirect addresses the second problem: it sends a reader from an old URL to the page's current
URL. Brief records page URLs in `brief.history.json`. The sync command compares that record with
the current pages, creates the necessary redirects, and records the new URLs for next time:

```sh
pnpm exec brief redirects sync --dry-run
pnpm exec brief redirects sync
```

Review the preview and run sync when the URL changes are ready for release, before publishing.
Include the resulting history and page metadata in the same commit when committing is part of
the task. Sync covers the documentation folder, so check for unrelated pending URL changes before
applying it. Let the command maintain the history file.

When removing a page, `--redirect-to <page>` records where to send its readers during the next
sync. Use `--allow-404` only when the old URL should return "page not found." Do not choose it
merely to bypass the redirect decision.

## Recording page update times

After body edits and link rewrites, preview `pnpm exec brief updates sync --dry-run` and synchronize
when the content is ready to publish. With no path, this updates all changed pages, including
drafts. Pass a page path and optional `--locale` to limit the operation to the intended content.
Use `--date YYYY-MM-DD` for midnight UTC or `--time` with an ISO timestamp and timezone when a
specific update time is required. Otherwise the command uses the current time.

The command maintains `updatedAt` and `contentHash` together in localized frontmatter. Do not
calculate or edit hashes manually. Frontmatter-only edits do not require synchronization.
`updated-at-out-of-sync` warnings identify missing checkpoints and body edits awaiting sync.
Commit the resulting metadata with the content when committing is part of the task.

## Checking your changes

Run `brief check` after other edits too. Add `--drafts` to include draft pages. Errors fail the command.
Use `brief check --fix --dry-run` to preview mechanical corrections and `brief check --fix` to
apply them. Add `--dangerous` to permit suggested broken-link and anchor replacements, removal
of stale order entries, and selection of the first repeated `...` marker. Review these changes:
they infer author intent. Fixes preserve code examples and only edit syntax supported by the format.
The report includes applied or skipped corrections and diagnostics remaining after validation.
JSON diagnostics carry concrete proposals in `fix`, including their safety and persistence effects.
Terminal diagnostics advertise proposals with a colored `fixable` command. A format may still lack
the editing capability needed to apply a proposal; the fix report explains skipped changes.
Overlapping corrections are recomputed against the updated source before writing.

`--fail-on warning` makes warnings fail too. Follow the project's CI settings. Quality tips are
suggestions and do not cause failure; `--no-tips` hides them.

For agent-facing changes, read the page's `.md` URL as well as its HTML page. If a custom component
adds information through attributes or generated content, give it a Markdown export so the text
version includes that information. `brief check` warns about empty portable Markdown and unclosed
code fences.

Fix problems caused by your changes and report existing problems separately. Use the app's
development or build command when you need to check how a page renders. Edit the source pages
and configuration; Brief recreates files such as `brief/generated.ts` and search indexes.

# Thermonuclear SEO Review

Review how well the documentation helps readers find an answer, understand it, and complete
their task. Be demanding about accuracy and page purpose. Explain each problem with evidence
from the pages, and propose specific improvements.

This skill covers documentation content and its organization. Analytics, advertising, backlinks,
and changes to the application or hosting setup require a separate request.

## Choose what to review

Use the pages or folders the user names. The following selectors are also supported; they are
instructions to the agent, not CLI commands.

| Selector               | What to review                                                                        |
| ---------------------- | ------------------------------------------------------------------------------------- |
| One or more page paths | Those pages.                                                                          |
| One or more folders    | Pages in those folders and their subfolders.                                          |
| `all`                  | All documentation in the configured Brief site.                                       |
| `changed`              | Documentation changed on the branch, including staged, unstaged, and untracked files. |
| `changed base=<ref>`   | Changed documentation compared with the specified Git reference.                      |
| `staged`               | Documentation prepared for the next commit, read from the Git index.                  |

If the user does not specify a scope, use `changed`. Use their chosen base branch, the current
PR's target branch, or the repository's default branch, in that order. Compare from the last
commit shared by that branch and the current branch, and report the branch and commit used.
The upstream tracking branch is not necessarily the PR target. If you cannot establish the
base, review the local changes you can identify and explain what is missing. Ask for the base
when it is needed to complete the requested review.

For `changed`, read each changed page in full but focus on the changed material. For `staged`,
read the staged version, not the working copy, and use staged versions of related files where
needed. A deleted or renamed page can leave gaps in coverage and break incoming links; include
those effects in the review. If no documentation matches, report that instead of reviewing
the whole site.

Use the Brief configuration to identify the documentation folder and supported page formats.
Not every Markdown file in the repository is a documentation page. Read neighboring pages when
needed to understand prerequisites, repeated explanations, or links, and label suggestions that
would affect pages outside the selected scope. For a large review, list the pages and work
through related groups. State which pages you could not review.

## Understand the intended reader

Read the project's writing conventions, glossary, version policy, and translation policy.
For each page, identify the reader's question, the knowledge it assumes, and the result it
promises. Judge the page against its purpose: a short API reference may be complete, while a
tutorial needs enough steps for a reader to reach the promised result.

Check technical claims against available implementation, tests, or product documentation.
Distinguish a demonstrated error from an editorial judgment or a claim that still needs
verification. Do not invent product behavior, limits, performance results, or example output.
Do not run examples with unknown side effects just to review them.

Use the installed `brief check` command to find problems with metadata and links, and
`brief tree --all-versions` to see how pages are organized. Run them from the documentation app,
using its configured paths and package manager. For `staged`, these commands inspect the
working copy unless run against a separate copy of the staged files; do not present their
results as validation of staged content. Explain checks you could not run.

## Review the content and organization

Look for the following problems and explain how each affects the reader:

- Missing prerequisites, incomplete steps, unclear expected results, or omitted limits and
  failure recovery. Check whether a reader can actually finish the task.
- Examples with unexplained inputs, missing output, or assumptions that do not hold for the
  documented version. Label examples whose behavior you could not verify.
- Overlapping pages that leave readers unsure which explanation to follow. Cite the repeated
  passages before recommending that pages be combined, split, or reordered.
- Related pages that are difficult to discover. Suggest an overview page and supporting pages
  when that would help readers navigate a topic; distinguish existing pages from proposed ones.
- Claims separated from their conditions, ambiguous pronouns, missing units, or unstated
  versions. Keep enough context in each passage for it to make sense when quoted on its own.
- Inconsistent terminology or unexplained acronyms. Preserve distinctions that matter between
  products, versions, and languages.
- Instructions contradicted by current behavior. Age alone does not make documentation stale.

For a proposed link, give the source passage, destination page and heading, suggested link text,
and reason the reader needs it. Verify the destination exists in the appropriate version and
language. Link to the published page URL, not its Markdown file, and do not invent heading anchors.

Suggest concrete replacements for weak titles, descriptions, headings, and introductions.
Recommend a table or diagram when it would explain a comparison or relationship more clearly,
and describe what it should show.

Do not impose keyword density, link quotas, word counts, mandatory FAQs, or duplicate pages
created only to target search terms. Passing Brief's checks does not guarantee search ranking
or citations by agents. Text exports make documentation accessible to agents; they do not prove
that a search engine has indexed it.

## Present findings and make requested edits

A review produces findings and proposed changes. Apply edits when the user has requested them,
including authorization already given in the conversation.

Order findings by their effect on readers and your confidence in the evidence. Separate
`high priority` findings from `nit picky` suggestions. Each finding should name the page and
section, show the evidence, explain the reader impact, and provide replacement prose, an
outline, or a specific link proposal. State any unresolved factual question and how to check it.
Group repeated symptoms that share a cause; do not invent findings to meet a quota.

If you propose moving or combining pages, identify the affected URLs, headings, and incoming
links. Moving a page may require updates to links in the documentation. Readers arriving through
bookmarks or external links also need redirects from the old URLs to the new ones.

When editing, use Brief's CLI for structural changes and preserve each page's `routeKey` so Brief
can recognize it after a move. Preview `brief redirects sync --dry-run` and apply sync when the
URL changes are ready for release. It compares saved URLs with current pages, updates redirects,
and records the current URLs for the next comparison. Review the complete preview before applying
it, since other page moves may be pending. For more authoring details, read `../brief/SKILL.md`.

Preserve technical meaning and code examples unless correcting them is part of the task.
Run the relevant documentation checks after edits and verify new links and headings. Report
compiler problems separately from content findings. Finish with the pages reviewed, any edits
made, checks and their results, and unresolved questions.

# Update documentation

Decide which Brief documentation needs to change by identifying the consequences for its readers.
Follow the project's `AGENTS.md` for local conventions and the [Brief skill](../brief/SKILL.md),
when available, for authoring mechanics, structural edits, and validation.

## Establish the change and audience

Identify the requested scope: a code comparison, working changes, a release, or a described product
change. Use the available repository or review tools without assuming a hosting platform, target
branch, or that the latest commit contains the whole change. Preserve existing local edits and
include uncommitted product changes only when they are in scope. Ask for the comparison if it
cannot be established from the request and repository context.

Read the relevant implementation and tests alongside the change description. Confirm which
behavior and product versions they describe before using them to update examples. If evidence
is missing or contradictory, identify the uncertainty rather than inventing a supported behavior.

Identify who uses the affected documentation and what they are trying to accomplish. Implementation
details may matter in a contributor guide while adding nothing useful to an end-user tutorial.

## Decide what readers need to know

For each change, determine whether it affects what readers can do, must do, or can rely on.
Look for changes to public APIs, commands, configuration, defaults, prerequisites, limitations,
error recovery, and supported workflows. Check whether existing explanations, examples, or
workarounds become inaccurate.

If the documentation remains accurate and sufficient, leave it unchanged. Internal refactors and
private instrumentation usually need no user documentation. Do not infer performance benefits or
new guarantees from implementation changes without supporting evidence. A bug fix may need no
edit when it restores documented behavior, but may make a documented workaround obsolete.

Find all affected explanations, including repeated facts in guides, reference pages, examples,
and troubleshooting advice. Search for concepts as well as changed identifiers: the same default
may appear as a number in a table and as prose elsewhere. Update only the versions to which the
change applies, and follow the project's translation policy.

## Choose the editorial change

- Edit an existing page when the reader's task stays the same but its instructions or explanation
  change. Add a section when a new aspect belongs within that task.
- Add a page when a distinct reader task or concept needs its own coherent explanation and a
  discoverable place in the documentation. A new API symbol alone does not require a new page.
- Combine or move pages when the change makes their existing organization confusing or forces
  readers to assemble one workflow from overlapping explanations. Preserve useful content and
  consider how readers will find it afterward.
- Remove a section or page when its guidance is obsolete and no longer serves a supported
  audience. Check whether older versions or migrating users still need it before removing it.

Keep introductory workflows focused. An optional advanced feature can belong in a guide or
reference without complicating the quickstart. Explain current behavior directly; add old-to-new
instructions where users actually need to migrate. Preserve supported compatibility paths, and
follow the project's release policy for changelog entries.

## Make complete, focused edits

Update every affected statement while preserving unrelated explanations, examples, qualifications,
and structure. Keep edits within the requested scope; avoid opportunistic rewriting or a broad
reorganization. Match the surrounding style and explain consequences in terms readers can act on.
Documentation should help them use the product, not narrate how its implementation was changed.

Check signatures, option names, defaults, and sample output against the relevant implementation
or tests. Retain useful prerequisites and limitations. Remove obsolete workarounds without
discarding advice that still applies. Use the Brief skill and project instructions to carry out
any structural changes and preserve navigation and link continuity.

## Verify and report

Review the resulting pages for factual accuracy, contradictory guidance, missing affected examples,
and unsupported claims. Check that the reader can still complete the task and that unrelated
information survived. Run the relevant project and Brief validation, and test changed executable
examples when possible. A successful build does not establish editorial correctness.

Summarize the reader-facing changes covered, the checks performed, and any unresolved evidence,
translation, or release work. If no edits were needed, explain why the existing documentation
already covers the behavior. Distinguish pre-existing problems from problems introduced by the edit.

# Brief Usage Guide

Brief is a documentation framework. It builds a documentation site from page files and
configuration that describes how those pages are organized. It supports navigation, multiple
versions and languages, search, and text outputs that agents can read. The included starter
uses Next.js and CoMark Markdown.

## Repair diagnostics

When asked to repair a problem, make the repair and verify it before finishing; diagnosis or a
proposed next step is not completion. Start with `brief check`. Choose `--json` instead of the
text report when you need structured codes or fix proposals; do not run both without a reason.
Read the reported file and help before exploring unrelated commands or configuration.

Prefer an offered `brief check --fix` correction to a manual rewrite. Use `--dangerous` only
after confirming that the proposed destination or ordering matches the request. Preview with
`--dry-run` if the scope is uncertain. The fix command revalidates the result and reports remaining
diagnostics: read that report before running another check or changing the repaired value again.
If a fix is unavailable or skipped, correct the source directly using the diagnostic's guidance.

Invalid directory names are excluded from the index, so structural CLI commands cannot address
them. Rename the directory on disk, preserve its contents, and update any parent order entry and
links that refer to it. This source repair is an exception to using the CLI for structural changes.

For manual edits, verify with `brief check` once afterward. Check that the requested diagnostic
is absent and that every requested property is satisfied, not just that the command exits zero.
Warnings and tips do not fail the command. Preserve explicit configuration requirements instead
of relying on a default that happens to produce the same output today. Stop when the repair is
complete; report unrelated findings without broadening the task.

An invalid `order` declaration can block structural commands. Correct its metadata directly or
use the offered fix. Ordering commands position an entry and write a resolved list; they are not
needed to repair repeated entries or rest markers and can remove an intentionally retained `...`.
Broken-link and anchor suggestions require checking the intended destination; preserve the label,
query string, and fragment. Match heading depth to the actual hierarchy without adding empty sections.

Use `brief tree` when paths or navigation are unclear, not before every content repair. For an
unfamiliar format or configuration contract, consult the supplied docs or the installed public
types before guessing through repeated edits. When searching Markdown in a shell, single-quote
literal patterns containing backticks or `$()` so the shell does not execute the examples.

## Content and authoring

A site contains tabs, such as guides and API reference. Each tab contains versions, and each
version contains pages and groups of pages. Groups can contain other groups.

Each page has its own folder. In a CoMark project, it contains one Markdown file per language,
such as `en.md` and `pt-PT.md`. The YAML block at the top of each file, called
frontmatter, contains its title, description, and optional URL slug:

```md
---
title: Create a page
description: Add a documentation page with the Brief CLI.
---

## Add the page

Run `brief page add docs/v1/getting-started` to create a page in the docs tab's v1 version.
```

The standard Brief UI displays the title as the page's H1 heading. Start headings in the body
at H2 (`##`) to avoid repeating it. Follow the project's examples and schemas when adding other
frontmatter fields.

Settings shared by all translations belong in `page.meta.toml`. These include `draft`,
`redirectFrom`, and `routeKey`. The route key is a stable identifier that lets Brief recognize
the same page after it moves. Keep it when moving a page. Site, tab, version, and group settings
belong in their respective `*.meta.toml` files; their `order` fields control navigation order.

Link to the URL a reader would visit, including its language, tab, version, and heading fragment
where needed. Do not link to the Markdown file on disk. Brief checks whether the destination
exists; it does not guess which version or translation you intended.

CoMark adds components to Markdown through directives. Use the components and properties
configured by the project. For example, the standard UI includes this callout:

```md
:::Callout{color="yellow" icon="warning" title="Before you start"}
Create the tab and version before adding a page inside them.
:::
```

## Prefer the CLI for structure

Use the CLI to add, move, and remove documentation. These commands update the files that describe
the site's structure and can fix links when URLs change. Edit page prose directly. Use settings
commands for metadata when the page format supports them.

Inspect a target with `brief page inspect docs/v1/getting-started --locale en --json`.
The result includes authored values, effective values, source files, and published routes.
Use `page update`, `group update`, `tab update`, `version update`, or `site update` to change
settings. Structural paths are relative to the documentation root; site commands need no path.

```sh
pnpm exec brief page update docs/v1/getting-started --locale en --title "Getting started"
pnpm exec brief page update docs/v1/getting-started --hidden true --dry-run
pnpm exec brief page update docs/v1/getting-started --unset hidden
```

Boolean flags take `true` or `false`. `--set key=JSON` accepts typed values such as arrays;
`--unset key` removes a declaration. `--input file.json` (or `--input -` for stdin) accepts
`{"set":{},"unset":[],"custom":{"set":{},"unset":[]}}`. Custom metadata uses the explicit
`custom` object and cannot overwrite built-in fields. Locale-specific structural edits write
the locale override file. Page-wide settings remain in `page.meta.toml`.
Changes are reloaded and validated before writing. Slug updates migrate supported links;
use `--no-update-links` to leave them unchanged and synchronize redirects before publication.
Settings commands can repair missing required metadata and route collisions from retained source.
Unrelated existing errors remain reported; new validation errors reject the edit. Malformed YAML
or TOML still needs a direct syntax correction. A repaired route collision must produce an
unambiguous index; link migration is unavailable when the original routes were ambiguous.

Run the installed CLI from the documentation app, for example with `pnpm exec brief`.
Page and group paths are relative to the documentation folder (`brief/case/` by default).
Use `brief tree` when you need to discover paths or inspect navigation. A page must belong to an
existing version. When the task already identifies the target, use the matching command directly;
inspect its help if you need an option. `page move` moves one page, while `group move` moves a group
and its descendants. Do not remove an emptied parent group unless that is part of the request.

```sh
pnpm exec brief page add docs/v1/getting-started --title "Getting started" --description "Create your first Brief page."
pnpm exec brief page move docs/v1/old-name docs/v1/new-name --dry-run
pnpm exec brief page move docs/v1/old-name docs/v1/new-name
pnpm exec brief page remove docs/v1/obsolete --redirect-to docs/v1/replacement
pnpm exec brief group add docs/v1/guides --title "Guides"
pnpm exec brief version add v2 --tab docs --from v1
pnpm exec brief locale add pt-PT --name "Portuguese (PT)"
```

### Command reference

Use `page order <path> --before <sibling-path>` or `--after <sibling-path>` to position an entry.
`--first` and `--last` are also available; no placement means last. Groups, tabs, and versions
have the same `order` command. Paths identify siblings under the same parent. The command writes
their current resolved sequence with the requested placement; future unlisted children still
appear at the bottom alphabetically. Use `--locale` for a localized order and `--dry-run` to preview.

Choose the command for the entry being positioned, not the metadata file that stores its order:
`group order` positions a group within its parent; `version order` positions a version within a tab.

Prefix each command with `brief`. Use `brief <command> --help` for its full options.

| Command                           | Purpose                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------ |
| `init [dir]`                      | Create a Next.js documentation site with CoMark, search, and agent skills.                 |
| `tree [path]`                     | Show the documentation structure; add `--all-versions` to include older versions.          |
| `check`                           | Check pages, settings, and links.                                                          |
| `page add <path>`                 | Add a page; set its `--title` and `--description`.                                         |
| `page move <from> <to>`           | Move a page and update supported links. Alias: `mv`.                                       |
| `page remove <path>`              | Remove a page; choose `--redirect-to <page>` or `--allow-404`. Alias: `rm`.                |
| `group add <path>`                | Add a group; set its `--title`.                                                            |
| `group move <from> <to>`          | Move a group and its pages. Alias: `mv`.                                                   |
| `group remove <path>`             | Remove a group and its pages; choose `--redirect-to <page>` or `--allow-404`. Alias: `rm`. |
| `tab list`                        | List the site's tabs.                                                                      |
| `tab add <tab>`                   | Add a tab with `--title <text>` and an optional initial `--version <name>`.                |
| `tab rename <tab> <name>`         | Rename a tab.                                                                              |
| `tab remove <tab>`                | Remove a tab and its pages; choose `--redirect-to <page>` or `--allow-404`. Alias: `rm`.   |
| `tab set-default <tab>`           | Choose the default tab.                                                                    |
| `version list`                    | List versions in a tab.                                                                    |
| `version add <version>`           | Copy a version with `--from <version>`, or start with `--empty`.                           |
| `version rename <version> <name>` | Rename a version.                                                                          |
| `version remove <version>`        | Delete a version and its pages; requires `--force`.                                        |
| `version set-default <version>`   | Choose the default version for a tab.                                                      |
| `locale list`                     | List the site's languages.                                                                 |
| `locale add <tag>`                | Register a language; provide its display name with `--name <text>`.                        |
| `locale remove <tag>`             | Remove a language from the site configuration; keep its content files.                     |
| `locale set-default <tag>`        | Choose the default language.                                                               |
| `updates sync [path]`             | Record changed body hashes and update times; defaults to all pages, including drafts.      |
| `redirects sync`                  | Record current page URLs and update redirects from older URLs.                             |
| `skills install`                  | Install the Brief skills; use `--agent`, `--dir`, or `--dry-run` as needed.                |
| `help [command]`                  | Show command help.                                                                         |

When a site has several tabs, version commands need `--tab`. `page add` creates files for every
language enabled for that version; complete them according to the project's translation policy.
Use `page add --extension` if the project supports several writable page formats. `locale add`
only registers the language, so translations still need to be written.

## Moving pages and keeping old links working

Moving a page creates two separate problems. Links in your documentation may still point to its
old URL, and readers may have bookmarked that URL or found it on another website.

`page move` addresses the first problem by updating links in your page files. Use `--dry-run`
to see the proposed changes before applying them. Link updates depend on the page format's
editing support, so read any notices about links left unchanged and run `brief check` afterward.
Use `--no-update-links` when you intend to leave links unchanged.

A redirect addresses the second problem: it sends a reader from an old URL to the page's current
URL. Brief records page URLs in `brief.history.json`. The sync command compares that record with
the current pages, creates the necessary redirects, and records the new URLs for next time:

```sh
pnpm exec brief redirects sync --dry-run
pnpm exec brief redirects sync
```

Review the preview and run sync when the URL changes are ready for release, before publishing.
Include the resulting history and page metadata in the same commit when committing is part of
the task. Sync covers the documentation folder, so check for unrelated pending URL changes before
applying it. Let the command maintain the history file.

When removing a page, `--redirect-to <page>` records where to send its readers during the next
sync. Use `--allow-404` only when the old URL should return "page not found." Do not choose it
merely to bypass the redirect decision.

## Recording page update times

After body edits and link rewrites, preview `pnpm exec brief updates sync --dry-run` and synchronize
when the content is ready to publish. With no path, this updates all changed pages, including
drafts. Pass a page path and optional `--locale` to limit the operation to the intended content.
Use `--date YYYY-MM-DD` for midnight UTC or `--time` with an ISO timestamp and timezone when a
specific update time is required. Otherwise the command uses the current time.

The command maintains `updatedAt` and `contentHash` together in localized frontmatter. Do not
calculate or edit hashes manually. Frontmatter-only edits do not require synchronization.
`updated-at-out-of-sync` warnings identify missing checkpoints and body edits awaiting sync.
Commit the resulting metadata with the content when committing is part of the task.

## Checking your changes

Run `brief check` after other edits too. Add `--drafts` to include draft pages. Errors fail the command.
Use `brief check --fix --dry-run` to preview mechanical corrections and `brief check --fix` to
apply them. Add `--dangerous` to permit suggested broken-link and anchor replacements, removal
of stale order entries, and selection of the first repeated `...` marker. Review these changes:
they infer author intent. Fixes preserve code examples and only edit syntax supported by the format.
The report includes applied or skipped corrections and diagnostics remaining after validation.
JSON diagnostics carry concrete proposals in `fix`, including their safety and persistence effects.
Terminal diagnostics advertise proposals with a colored `fixable` command. A format may still lack
the editing capability needed to apply a proposal; the fix report explains skipped changes.
Overlapping corrections are recomputed against the updated source before writing.

`--fail-on warning` makes warnings fail too. Follow the project's CI settings. Quality tips are
suggestions and do not cause failure; `--no-tips` hides them.

For agent-facing changes, read the page's `.md` URL as well as its HTML page. If a custom component
adds information through attributes or generated content, give it a Markdown export so the text
version includes that information. `brief check` warns about empty portable Markdown and unclosed
code fences.

Fix problems caused by your changes and report existing problems separately. Use the app's
development or build command when you need to check how a page renders. Edit the source pages
and configuration; Brief recreates files such as `brief/generated.ts` and search indexes.

# Thermonuclear SEO Review

Review how well the documentation helps readers find an answer, understand it, and complete
their task. Be demanding about accuracy and page purpose. Explain each problem with evidence
from the pages, and propose specific improvements.

This skill covers documentation content and its organization. Analytics, advertising, backlinks,
and changes to the application or hosting setup require a separate request.

## Choose what to review

Use the pages or folders the user names. The following selectors are also supported; they are
instructions to the agent, not CLI commands.

| Selector               | What to review                                                                        |
| ---------------------- | ------------------------------------------------------------------------------------- |
| One or more page paths | Those pages.                                                                          |
| One or more folders    | Pages in those folders and their subfolders.                                          |
| `all`                  | All documentation in the configured Brief site.                                       |
| `changed`              | Documentation changed on the branch, including staged, unstaged, and untracked files. |
| `changed base=<ref>`   | Changed documentation compared with the specified Git reference.                      |
| `staged`               | Documentation prepared for the next commit, read from the Git index.                  |

If the user does not specify a scope, use `changed`. Use their chosen base branch, the current
PR's target branch, or the repository's default branch, in that order. Compare from the last
commit shared by that branch and the current branch, and report the branch and commit used.
The upstream tracking branch is not necessarily the PR target. If you cannot establish the
base, review the local changes you can identify and explain what is missing. Ask for the base
when it is needed to complete the requested review.

For `changed`, read each changed page in full but focus on the changed material. For `staged`,
read the staged version, not the working copy, and use staged versions of related files where
needed. A deleted or renamed page can leave gaps in coverage and break incoming links; include
those effects in the review. If no documentation matches, report that instead of reviewing
the whole site.

Use the Brief configuration to identify the documentation folder and supported page formats.
Not every Markdown file in the repository is a documentation page. Read neighboring pages when
needed to understand prerequisites, repeated explanations, or links, and label suggestions that
would affect pages outside the selected scope. For a large review, list the pages and work
through related groups. State which pages you could not review.

## Understand the intended reader

Read the project's writing conventions, glossary, version policy, and translation policy.
For each page, identify the reader's question, the knowledge it assumes, and the result it
promises. Judge the page against its purpose: a short API reference may be complete, while a
tutorial needs enough steps for a reader to reach the promised result.

Check technical claims against available implementation, tests, or product documentation.
Distinguish a demonstrated error from an editorial judgment or a claim that still needs
verification. Do not invent product behavior, limits, performance results, or example output.
Do not run examples with unknown side effects just to review them.

Use the installed `brief check` command to find problems with metadata and links, and
`brief tree --all-versions` to see how pages are organized. Run them from the documentation app,
using its configured paths and package manager. For `staged`, these commands inspect the
working copy unless run against a separate copy of the staged files; do not present their
results as validation of staged content. Explain checks you could not run.

## Review the content and organization

Look for the following problems and explain how each affects the reader:

- Missing prerequisites, incomplete steps, unclear expected results, or omitted limits and
  failure recovery. Check whether a reader can actually finish the task.
- Examples with unexplained inputs, missing output, or assumptions that do not hold for the
  documented version. Label examples whose behavior you could not verify.
- Overlapping pages that leave readers unsure which explanation to follow. Cite the repeated
  passages before recommending that pages be combined, split, or reordered.
- Related pages that are difficult to discover. Suggest an overview page and supporting pages
  when that would help readers navigate a topic; distinguish existing pages from proposed ones.
- Claims separated from their conditions, ambiguous pronouns, missing units, or unstated
  versions. Keep enough context in each passage for it to make sense when quoted on its own.
- Inconsistent terminology or unexplained acronyms. Preserve distinctions that matter between
  products, versions, and languages.
- Instructions contradicted by current behavior. Age alone does not make documentation stale.

For a proposed link, give the source passage, destination page and heading, suggested link text,
and reason the reader needs it. Verify the destination exists in the appropriate version and
language. Link to the published page URL, not its Markdown file, and do not invent heading anchors.

Suggest concrete replacements for weak titles, descriptions, headings, and introductions.
Recommend a table or diagram when it would explain a comparison or relationship more clearly,
and describe what it should show.

Do not impose keyword density, link quotas, word counts, mandatory FAQs, or duplicate pages
created only to target search terms. Passing Brief's checks does not guarantee search ranking
or citations by agents. Text exports make documentation accessible to agents; they do not prove
that a search engine has indexed it.

## Present findings and make requested edits

A review produces findings and proposed changes. Apply edits when the user has requested them,
including authorization already given in the conversation.

Order findings by their effect on readers and your confidence in the evidence. Separate
`high priority` findings from `nit picky` suggestions. Each finding should name the page and
section, show the evidence, explain the reader impact, and provide replacement prose, an
outline, or a specific link proposal. State any unresolved factual question and how to check it.
Group repeated symptoms that share a cause; do not invent findings to meet a quota.

If you propose moving or combining pages, identify the affected URLs, headings, and incoming
links. Moving a page may require updates to links in the documentation. Readers arriving through
bookmarks or external links also need redirects from the old URLs to the new ones.

When editing, use Brief's CLI for structural changes and preserve each page's `routeKey` so Brief
can recognize it after a move. Preview `brief redirects sync --dry-run` and apply sync when the
URL changes are ready for release. It compares saved URLs with current pages, updates redirects,
and records the current URLs for the next comparison. Review the complete preview before applying
it, since other page moves may be pending. For more authoring details, read `../brief/SKILL.md`.

Preserve technical meaning and code examples unless correcting them is part of the task.
Run the relevant documentation checks after edits and verify new links and headings. Report
compiler problems separately from content findings. Finish with the pages reviewed, any edits
made, checks and their results, and unresolved questions.

# Update documentation

Decide which Brief documentation needs to change by identifying the consequences for its readers.
Follow the project's `AGENTS.md` for local conventions and the [Brief skill](../brief/SKILL.md),
when available, for authoring mechanics, structural edits, and validation.

## Establish the change and audience

Identify the requested scope: a code comparison, working changes, a release, or a described product
change. Use the available repository or review tools without assuming a hosting platform, target
branch, or that the latest commit contains the whole change. Preserve existing local edits and
include uncommitted product changes only when they are in scope. Ask for the comparison if it
cannot be established from the request and repository context.

Read the relevant implementation and tests alongside the change description. Confirm which
behavior and product versions they describe before using them to update examples. If evidence
is missing or contradictory, identify the uncertainty rather than inventing a supported behavior.

Identify who uses the affected documentation and what they are trying to accomplish. Implementation
details may matter in a contributor guide while adding nothing useful to an end-user tutorial.

## Decide what readers need to know

For each change, determine whether it affects what readers can do, must do, or can rely on.
Look for changes to public APIs, commands, configuration, defaults, prerequisites, limitations,
error recovery, and supported workflows. Check whether existing explanations, examples, or
workarounds become inaccurate.

If the documentation remains accurate and sufficient, leave it unchanged. Internal refactors and
private instrumentation usually need no user documentation. Do not infer performance benefits or
new guarantees from implementation changes without supporting evidence. A bug fix may need no
edit when it restores documented behavior, but may make a documented workaround obsolete.

Find all affected explanations, including repeated facts in guides, reference pages, examples,
and troubleshooting advice. Search for concepts as well as changed identifiers: the same default
may appear as a number in a table and as prose elsewhere. Update only the versions to which the
change applies, and follow the project's translation policy.

## Choose the editorial change

- Edit an existing page when the reader's task stays the same but its instructions or explanation
  change. Add a section when a new aspect belongs within that task.
- Add a page when a distinct reader task or concept needs its own coherent explanation and a
  discoverable place in the documentation. A new API symbol alone does not require a new page.
- Combine or move pages when the change makes their existing organization confusing or forces
  readers to assemble one workflow from overlapping explanations. Preserve useful content and
  consider how readers will find it afterward.
- Remove a section or page when its guidance is obsolete and no longer serves a supported
  audience. Check whether older versions or migrating users still need it before removing it.

Keep introductory workflows focused. An optional advanced feature can belong in a guide or
reference without complicating the quickstart. Explain current behavior directly; add old-to-new
instructions where users actually need to migrate. Preserve supported compatibility paths, and
follow the project's release policy for changelog entries.

## Make complete, focused edits

Update every affected statement while preserving unrelated explanations, examples, qualifications,
and structure. Keep edits within the requested scope; avoid opportunistic rewriting or a broad
reorganization. Match the surrounding style and explain consequences in terms readers can act on.
Documentation should help them use the product, not narrate how its implementation was changed.

Check signatures, option names, defaults, and sample output against the relevant implementation
or tests. Retain useful prerequisites and limitations. Remove obsolete workarounds without
discarding advice that still applies. Use the Brief skill and project instructions to carry out
any structural changes and preserve navigation and link continuity.

## Verify and report

Review the resulting pages for factual accuracy, contradictory guidance, missing affected examples,
and unsupported claims. Check that the reader can still complete the task and that unrelated
information survived. Run the relevant project and Brief validation, and test changed executable
examples when possible. A successful build does not establish editorial correctness.

Summarize the reader-facing changes covered, the checks performed, and any unresolved evidence,
translation, or release work. If no edits were needed, explain why the existing documentation
already covers the behavior. Distinguish pre-existing problems from problems introduced by the edit.

# Brief Usage Guide

Brief is a documentation framework. It builds a documentation site from page files and
configuration that describes how those pages are organized. It supports navigation, multiple
versions and languages, search, and text outputs that agents can read. The included starter
uses Next.js and CoMark Markdown.

## Repair diagnostics

When asked to repair a problem, make the repair and verify it before finishing; diagnosis or a
proposed next step is not completion. Start with `brief check`. Choose `--json` instead of the
text report when you need structured codes or fix proposals; do not run both without a reason.
Read the reported file and help before exploring unrelated commands or configuration.

Prefer an offered `brief check --fix` correction to a manual rewrite. Use `--dangerous` only
after confirming that the proposed destination or ordering matches the request. Preview with
`--dry-run` if the scope is uncertain. The fix command revalidates the result and reports remaining
diagnostics: read that report before running another check or changing the repaired value again.
If a fix is unavailable or skipped, correct the source directly using the diagnostic's guidance.

Invalid directory names are excluded from the index, so structural CLI commands cannot address
them. Rename the directory on disk, preserve its contents, and update any parent order entry and
links that refer to it. This source repair is an exception to using the CLI for structural changes.

For manual edits, verify with `brief check` once afterward. Check that the requested diagnostic
is absent and that every requested property is satisfied, not just that the command exits zero.
Warnings and tips do not fail the command. Preserve explicit configuration requirements instead
of relying on a default that happens to produce the same output today. Stop when the repair is
complete; report unrelated findings without broadening the task.

An invalid `order` declaration can block structural commands. Correct its metadata directly or
use the offered fix. Ordering commands position an entry and write a resolved list; they are not
needed to repair repeated entries or rest markers and can remove an intentionally retained `...`.
Broken-link and anchor suggestions require checking the intended destination; preserve the label,
query string, and fragment. Match heading depth to the actual hierarchy without adding empty sections.

Use `brief tree` when paths or navigation are unclear, not before every content repair. For an
unfamiliar format or configuration contract, consult the supplied docs or the installed public
types before guessing through repeated edits. When searching Markdown in a shell, single-quote
literal patterns containing backticks or `$()` so the shell does not execute the examples.

## Content and authoring

A site contains tabs, such as guides and API reference. Each tab contains versions, and each
version contains pages and groups of pages. Groups can contain other groups.

Each page has its own folder. In a CoMark project, it contains one Markdown file per language,
such as `en.md` and `pt-PT.md`. The YAML block at the top of each file, called
frontmatter, contains its title, description, and optional URL slug:

```md
---
title: Create a page
description: Add a documentation page with the Brief CLI.
---

## Add the page

Run `brief page add docs/v1/getting-started` to create a page in the docs tab's v1 version.
```

The standard Brief UI displays the title as the page's H1 heading. Start headings in the body
at H2 (`##`) to avoid repeating it. Follow the project's examples and schemas when adding other
frontmatter fields.

Settings shared by all translations belong in `page.meta.toml`. These include `draft`,
`redirectFrom`, and `routeKey`. The route key is a stable identifier that lets Brief recognize
the same page after it moves. Keep it when moving a page. Site, tab, version, and group settings
belong in their respective `*.meta.toml` files; their `order` fields control navigation order.

Link to the URL a reader would visit, including its language, tab, version, and heading fragment
where needed. Do not link to the Markdown file on disk. Brief checks whether the destination
exists; it does not guess which version or translation you intended.

CoMark adds components to Markdown through directives. Use the components and properties
configured by the project. For example, the standard UI includes this callout:

```md
:::Callout{color="yellow" icon="warning" title="Before you start"}
Create the tab and version before adding a page inside them.
:::
```

## Prefer the CLI for structure

Use the CLI to add, move, and remove documentation. These commands update the files that describe
the site's structure and can fix links when URLs change. Edit page prose directly. Use settings
commands for metadata when the page format supports them.

Inspect a target with `brief page inspect docs/v1/getting-started --locale en --json`.
The result includes authored values, effective values, source files, and published routes.
Use `page update`, `group update`, `tab update`, `version update`, or `site update` to change
settings. Structural paths are relative to the documentation root; site commands need no path.

```sh
pnpm exec brief page update docs/v1/getting-started --locale en --title "Getting started"
pnpm exec brief page update docs/v1/getting-started --hidden true --dry-run
pnpm exec brief page update docs/v1/getting-started --unset hidden
```

Boolean flags take `true` or `false`. `--set key=JSON` accepts typed values such as arrays;
`--unset key` removes a declaration. `--input file.json` (or `--input -` for stdin) accepts
`{"set":{},"unset":[],"custom":{"set":{},"unset":[]}}`. Custom metadata uses the explicit
`custom` object and cannot overwrite built-in fields. Locale-specific structural edits write
the locale override file. Page-wide settings remain in `page.meta.toml`.
Changes are reloaded and validated before writing. Slug updates migrate supported links;
use `--no-update-links` to leave them unchanged and synchronize redirects before publication.
Settings commands can repair missing required metadata and route collisions from retained source.
Unrelated existing errors remain reported; new validation errors reject the edit. Malformed YAML
or TOML still needs a direct syntax correction. A repaired route collision must produce an
unambiguous index; link migration is unavailable when the original routes were ambiguous.

Run the installed CLI from the documentation app, for example with `pnpm exec brief`.
Page and group paths are relative to the documentation folder (`brief/case/` by default).
Use `brief tree` when you need to discover paths or inspect navigation. A page must belong to an
existing version. When the task already identifies the target, use the matching command directly;
inspect its help if you need an option. `page move` moves one page, while `group move` moves a group
and its descendants. Do not remove an emptied parent group unless that is part of the request.

```sh
pnpm exec brief page add docs/v1/getting-started --title "Getting started" --description "Create your first Brief page."
pnpm exec brief page move docs/v1/old-name docs/v1/new-name --dry-run
pnpm exec brief page move docs/v1/old-name docs/v1/new-name
pnpm exec brief page remove docs/v1/obsolete --redirect-to docs/v1/replacement
pnpm exec brief group add docs/v1/guides --title "Guides"
pnpm exec brief version add v2 --tab docs --from v1
pnpm exec brief locale add pt-PT --name "Portuguese (PT)"
```

### Command reference

Use `page order <path> --before <sibling-path>` or `--after <sibling-path>` to position an entry.
`--first` and `--last` are also available; no placement means last. Groups, tabs, and versions
have the same `order` command. Paths identify siblings under the same parent. The command writes
their current resolved sequence with the requested placement; future unlisted children still
appear at the bottom alphabetically. Use `--locale` for a localized order and `--dry-run` to preview.

Choose the command for the entry being positioned, not the metadata file that stores its order:
`group order` positions a group within its parent; `version order` positions a version within a tab.

Prefix each command with `brief`. Use `brief <command> --help` for its full options.

| Command                           | Purpose                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------ |
| `init [dir]`                      | Create a Next.js documentation site with CoMark, search, and agent skills.                 |
| `tree [path]`                     | Show the documentation structure; add `--all-versions` to include older versions.          |
| `check`                           | Check pages, settings, and links.                                                          |
| `page add <path>`                 | Add a page; set its `--title` and `--description`.                                         |
| `page move <from> <to>`           | Move a page and update supported links. Alias: `mv`.                                       |
| `page remove <path>`              | Remove a page; choose `--redirect-to <page>` or `--allow-404`. Alias: `rm`.                |
| `group add <path>`                | Add a group; set its `--title`.                                                            |
| `group move <from> <to>`          | Move a group and its pages. Alias: `mv`.                                                   |
| `group remove <path>`             | Remove a group and its pages; choose `--redirect-to <page>` or `--allow-404`. Alias: `rm`. |
| `tab list`                        | List the site's tabs.                                                                      |
| `tab add <tab>`                   | Add a tab with `--title <text>` and an optional initial `--version <name>`.                |
| `tab rename <tab> <name>`         | Rename a tab.                                                                              |
| `tab remove <tab>`                | Remove a tab and its pages; choose `--redirect-to <page>` or `--allow-404`. Alias: `rm`.   |
| `tab set-default <tab>`           | Choose the default tab.                                                                    |
| `version list`                    | List versions in a tab.                                                                    |
| `version add <version>`           | Copy a version with `--from <version>`, or start with `--empty`.                           |
| `version rename <version> <name>` | Rename a version.                                                                          |
| `version remove <version>`        | Delete a version and its pages; requires `--force`.                                        |
| `version set-default <version>`   | Choose the default version for a tab.                                                      |
| `locale list`                     | List the site's languages.                                                                 |
| `locale add <tag>`                | Register a language; provide its display name with `--name <text>`.                        |
| `locale remove <tag>`             | Remove a language from the site configuration; keep its content files.                     |
| `locale set-default <tag>`        | Choose the default language.                                                               |
| `updates sync [path]`             | Record changed body hashes and update times; defaults to all pages, including drafts.      |
| `redirects sync`                  | Record current page URLs and update redirects from older URLs.                             |
| `skills install`                  | Install the Brief skills; use `--agent`, `--dir`, or `--dry-run` as needed.                |
| `help [command]`                  | Show command help.                                                                         |

When a site has several tabs, version commands need `--tab`. `page add` creates files for every
language enabled for that version; complete them according to the project's translation policy.
Use `page add --extension` if the project supports several writable page formats. `locale add`
only registers the language, so translations still need to be written.

## Moving pages and keeping old links working

Moving a page creates two separate problems. Links in your documentation may still point to its
old URL, and readers may have bookmarked that URL or found it on another website.

`page move` addresses the first problem by updating links in your page files. Use `--dry-run`
to see the proposed changes before applying them. Link updates depend on the page format's
editing support, so read any notices about links left unchanged and run `brief check` afterward.
Use `--no-update-links` when you intend to leave links unchanged.

A redirect addresses the second problem: it sends a reader from an old URL to the page's current
URL. Brief records page URLs in `brief.history.json`. The sync command compares that record with
the current pages, creates the necessary redirects, and records the new URLs for next time:

```sh
pnpm exec brief redirects sync --dry-run
pnpm exec brief redirects sync
```

Review the preview and run sync when the URL changes are ready for release, before publishing.
Include the resulting history and page metadata in the same commit when committing is part of
the task. Sync covers the documentation folder, so check for unrelated pending URL changes before
applying it. Let the command maintain the history file.

When removing a page, `--redirect-to <page>` records where to send its readers during the next
sync. Use `--allow-404` only when the old URL should return "page not found." Do not choose it
merely to bypass the redirect decision.

## Recording page update times

After body edits and link rewrites, preview `pnpm exec brief updates sync --dry-run` and synchronize
when the content is ready to publish. With no path, this updates all changed pages, including
drafts. Pass a page path and optional `--locale` to limit the operation to the intended content.
Use `--date YYYY-MM-DD` for midnight UTC or `--time` with an ISO timestamp and timezone when a
specific update time is required. Otherwise the command uses the current time.

The command maintains `updatedAt` and `contentHash` together in localized frontmatter. Do not
calculate or edit hashes manually. Frontmatter-only edits do not require synchronization.
`updated-at-out-of-sync` warnings identify missing checkpoints and body edits awaiting sync.
Commit the resulting metadata with the content when committing is part of the task.

## Checking your changes

Run `brief check` after other edits too. Add `--drafts` to include draft pages. Errors fail the command.
Use `brief check --fix --dry-run` to preview mechanical corrections and `brief check --fix` to
apply them. Add `--dangerous` to permit suggested broken-link and anchor replacements, removal
of stale order entries, and selection of the first repeated `...` marker. Review these changes:
they infer author intent. Fixes preserve code examples and only edit syntax supported by the format.
The report includes applied or skipped corrections and diagnostics remaining after validation.
JSON diagnostics carry concrete proposals in `fix`, including their safety and persistence effects.
Terminal diagnostics advertise proposals with a colored `fixable` command. A format may still lack
the editing capability needed to apply a proposal; the fix report explains skipped changes.
Overlapping corrections are recomputed against the updated source before writing.

`--fail-on warning` makes warnings fail too. Follow the project's CI settings. Quality tips are
suggestions and do not cause failure; `--no-tips` hides them.

For agent-facing changes, read the page's `.md` URL as well as its HTML page. If a custom component
adds information through attributes or generated content, give it a Markdown export so the text
version includes that information. `brief check` warns about empty portable Markdown and unclosed
code fences.

Fix problems caused by your changes and report existing problems separately. Use the app's
development or build command when you need to check how a page renders. Edit the source pages
and configuration; Brief recreates files such as `brief/generated.ts` and search indexes.

# Thermonuclear SEO Review

Review how well the documentation helps readers find an answer, understand it, and complete
their task. Be demanding about accuracy and page purpose. Explain each problem with evidence
from the pages, and propose specific improvements.

This skill covers documentation content and its organization. Analytics, advertising, backlinks,
and changes to the application or hosting setup require a separate request.

## Choose what to review

Use the pages or folders the user names. The following selectors are also supported; they are
instructions to the agent, not CLI commands.

| Selector               | What to review                                                                        |
| ---------------------- | ------------------------------------------------------------------------------------- |
| One or more page paths | Those pages.                                                                          |
| One or more folders    | Pages in those folders and their subfolders.                                          |
| `all`                  | All documentation in the configured Brief site.                                       |
| `changed`              | Documentation changed on the branch, including staged, unstaged, and untracked files. |
| `changed base=<ref>`   | Changed documentation compared with the specified Git reference.                      |
| `staged`               | Documentation prepared for the next commit, read from the Git index.                  |

If the user does not specify a scope, use `changed`. Use their chosen base branch, the current
PR's target branch, or the repository's default branch, in that order. Compare from the last
commit shared by that branch and the current branch, and report the branch and commit used.
The upstream tracking branch is not necessarily the PR target. If you cannot establish the
base, review the local changes you can identify and explain what is missing. Ask for the base
when it is needed to complete the requested review.

For `changed`, read each changed page in full but focus on the changed material. For `staged`,
read the staged version, not the working copy, and use staged versions of related files where
needed. A deleted or renamed page can leave gaps in coverage and break incoming links; include
those effects in the review. If no documentation matches, report that instead of reviewing
the whole site.

Use the Brief configuration to identify the documentation folder and supported page formats.
Not every Markdown file in the repository is a documentation page. Read neighboring pages when
needed to understand prerequisites, repeated explanations, or links, and label suggestions that
would affect pages outside the selected scope. For a large review, list the pages and work
through related groups. State which pages you could not review.

## Understand the intended reader

Read the project's writing conventions, glossary, version policy, and translation policy.
For each page, identify the reader's question, the knowledge it assumes, and the result it
promises. Judge the page against its purpose: a short API reference may be complete, while a
tutorial needs enough steps for a reader to reach the promised result.

Check technical claims against available implementation, tests, or product documentation.
Distinguish a demonstrated error from an editorial judgment or a claim that still needs
verification. Do not invent product behavior, limits, performance results, or example output.
Do not run examples with unknown side effects just to review them.

Use the installed `brief check` command to find problems with metadata and links, and
`brief tree --all-versions` to see how pages are organized. Run them from the documentation app,
using its configured paths and package manager. For `staged`, these commands inspect the
working copy unless run against a separate copy of the staged files; do not present their
results as validation of staged content. Explain checks you could not run.

## Review the content and organization

Look for the following problems and explain how each affects the reader:

- Missing prerequisites, incomplete steps, unclear expected results, or omitted limits and
  failure recovery. Check whether a reader can actually finish the task.
- Examples with unexplained inputs, missing output, or assumptions that do not hold for the
  documented version. Label examples whose behavior you could not verify.
- Overlapping pages that leave readers unsure which explanation to follow. Cite the repeated
  passages before recommending that pages be combined, split, or reordered.
- Related pages that are difficult to discover. Suggest an overview page and supporting pages
  when that would help readers navigate a topic; distinguish existing pages from proposed ones.
- Claims separated from their conditions, ambiguous pronouns, missing units, or unstated
  versions. Keep enough context in each passage for it to make sense when quoted on its own.
- Inconsistent terminology or unexplained acronyms. Preserve distinctions that matter between
  products, versions, and languages.
- Instructions contradicted by current behavior. Age alone does not make documentation stale.

For a proposed link, give the source passage, destination page and heading, suggested link text,
and reason the reader needs it. Verify the destination exists in the appropriate version and
language. Link to the published page URL, not its Markdown file, and do not invent heading anchors.

Suggest concrete replacements for weak titles, descriptions, headings, and introductions.
Recommend a table or diagram when it would explain a comparison or relationship more clearly,
and describe what it should show.

Do not impose keyword density, link quotas, word counts, mandatory FAQs, or duplicate pages
created only to target search terms. Passing Brief's checks does not guarantee search ranking
or citations by agents. Text exports make documentation accessible to agents; they do not prove
that a search engine has indexed it.

## Present findings and make requested edits

A review produces findings and proposed changes. Apply edits when the user has requested them,
including authorization already given in the conversation.

Order findings by their effect on readers and your confidence in the evidence. Separate
`high priority` findings from `nit picky` suggestions. Each finding should name the page and
section, show the evidence, explain the reader impact, and provide replacement prose, an
outline, or a specific link proposal. State any unresolved factual question and how to check it.
Group repeated symptoms that share a cause; do not invent findings to meet a quota.

If you propose moving or combining pages, identify the affected URLs, headings, and incoming
links. Moving a page may require updates to links in the documentation. Readers arriving through
bookmarks or external links also need redirects from the old URLs to the new ones.

When editing, use Brief's CLI for structural changes and preserve each page's `routeKey` so Brief
can recognize it after a move. Preview `brief redirects sync --dry-run` and apply sync when the
URL changes are ready for release. It compares saved URLs with current pages, updates redirects,
and records the current URLs for the next comparison. Review the complete preview before applying
it, since other page moves may be pending. For more authoring details, read `../brief/SKILL.md`.

Preserve technical meaning and code examples unless correcting them is part of the task.
Run the relevant documentation checks after edits and verify new links and headings. Report
compiler problems separately from content findings. Finish with the pages reviewed, any edits
made, checks and their results, and unresolved questions.

# Update documentation

Decide which Brief documentation needs to change by identifying the consequences for its readers.
Follow the project's `AGENTS.md` for local conventions and the [Brief skill](../brief/SKILL.md),
when available, for authoring mechanics, structural edits, and validation.

## Establish the change and audience

Identify the requested scope: a code comparison, working changes, a release, or a described product
change. Use the available repository or review tools without assuming a hosting platform, target
branch, or that the latest commit contains the whole change. Preserve existing local edits and
include uncommitted product changes only when they are in scope. Ask for the comparison if it
cannot be established from the request and repository context.

Read the relevant implementation and tests alongside the change description. Confirm which
behavior and product versions they describe before using them to update examples. If evidence
is missing or contradictory, identify the uncertainty rather than inventing a supported behavior.

Identify who uses the affected documentation and what they are trying to accomplish. Implementation
details may matter in a contributor guide while adding nothing useful to an end-user tutorial.

## Decide what readers need to know

For each change, determine whether it affects what readers can do, must do, or can rely on.
Look for changes to public APIs, commands, configuration, defaults, prerequisites, limitations,
error recovery, and supported workflows. Check whether existing explanations, examples, or
workarounds become inaccurate.

If the documentation remains accurate and sufficient, leave it unchanged. Internal refactors and
private instrumentation usually need no user documentation. Do not infer performance benefits or
new guarantees from implementation changes without supporting evidence. A bug fix may need no
edit when it restores documented behavior, but may make a documented workaround obsolete.

Find all affected explanations, including repeated facts in guides, reference pages, examples,
and troubleshooting advice. Search for concepts as well as changed identifiers: the same default
may appear as a number in a table and as prose elsewhere. Update only the versions to which the
change applies, and follow the project's translation policy.

## Choose the editorial change

- Edit an existing page when the reader's task stays the same but its instructions or explanation
  change. Add a section when a new aspect belongs within that task.
- Add a page when a distinct reader task or concept needs its own coherent explanation and a
  discoverable place in the documentation. A new API symbol alone does not require a new page.
- Combine or move pages when the change makes their existing organization confusing or forces
  readers to assemble one workflow from overlapping explanations. Preserve useful content and
  consider how readers will find it afterward.
- Remove a section or page when its guidance is obsolete and no longer serves a supported
  audience. Check whether older versions or migrating users still need it before removing it.

Keep introductory workflows focused. An optional advanced feature can belong in a guide or
reference without complicating the quickstart. Explain current behavior directly; add old-to-new
instructions where users actually need to migrate. Preserve supported compatibility paths, and
follow the project's release policy for changelog entries.

## Make complete, focused edits

Update every affected statement while preserving unrelated explanations, examples, qualifications,
and structure. Keep edits within the requested scope; avoid opportunistic rewriting or a broad
reorganization. Match the surrounding style and explain consequences in terms readers can act on.
Documentation should help them use the product, not narrate how its implementation was changed.

Check signatures, option names, defaults, and sample output against the relevant implementation
or tests. Retain useful prerequisites and limitations. Remove obsolete workarounds without
discarding advice that still applies. Use the Brief skill and project instructions to carry out
any structural changes and preserve navigation and link continuity.

## Verify and report

Review the resulting pages for factual accuracy, contradictory guidance, missing affected examples,
and unsupported claims. Check that the reader can still complete the task and that unrelated
information survived. Run the relevant project and Brief validation, and test changed executable
examples when possible. A successful build does not establish editorial correctness.

Summarize the reader-facing changes covered, the checks performed, and any unresolved evidence,
translation, or release work. If no edits were needed, explain why the existing documentation
already covers the behavior. Distinguish pre-existing problems from problems introduced by the edit.