Diagnostics and escape hatches

# Diagnostics and escape hatches

Resolve publish-root ambiguity, clear generated state, and isolate extension failures.

Start with `tidypress doctor`. The checks below are for ambiguous repositories,
engine upgrades, and project extension failures—not normal configuration.

## Confirm the publish root

The CLI searches the current directory, then conventional `site/` and nearby
locations for `tidypress.config.ts`. When more than one candidate is plausible,
run from the intended publish root or set a temporary override:

```bash
TIDYPRESS_PUBLISH_ROOT=./site npx tidypress doctor
```

Do not persist this variable unless CI genuinely cannot express the working
directory. The config file location is the normal contract.

## Clear generated state

```bash
npx tidypress clean
npx tidypress build
```

`clean` removes the publish-root output and the active project's TidyPress cache.
It does not delete authored Markdown, config, public assets, agent settings, or
environment files.

## Isolate project extensions

If a project builds before a presentation extension is enabled:

1. Check every project module path begins with `./` and stays inside the publish root.
2. Remove one `plugins`, `markdown`, `mdx.components`, `ui`, or custom `render` entry at a time.
3. Re-run `doctor` and `build` after each change.
4. Treat a missing export or broken registered Astro view as a real build error.

TidyPress intentionally does not swallow a registered view failure and fall back
to unrelated baseline markup.

## Inspect generated contracts

After a successful build, verify:

```txt
site/build/index.html
site/build/pagefind/
site/build/llms.txt
site/build/sitemap-index.xml   # when a production siteUrl is available
```

Pagefind and sitemap filenames may include additional generated files. Validate
the public behavior rather than editing anything inside `build/`.

## No hidden environment installer

`npm install tidypress`, `tidypress --version`, and ordinary CLI commands do not
install agent skills or modify the shell. Skill installation is explicit:

```bash
npx tidypress skills install
```

It writes only the TidyPress skill folder in the detected supported agent
location and preserves existing files unless `--force` is supplied.

Start with tidypress doctor. The checks below are for ambiguous repositories, engine upgrades, and project extension failures—not normal configuration.

Confirm the publish root

The CLI searches the current directory, then conventional site/ and nearby locations for tidypress.config.ts. When more than one candidate is plausible, run from the intended publish root or set a temporary override:

TIDYPRESS_PUBLISH_ROOT=./site npx tidypress doctor

Do not persist this variable unless CI genuinely cannot express the working directory. The config file location is the normal contract.

Clear generated state

npx tidypress clean
npx tidypress build

clean removes the publish-root output and the active project’s TidyPress cache. It does not delete authored Markdown, config, public assets, agent settings, or environment files.

Isolate project extensions

If a project builds before a presentation extension is enabled:

Check every project module path begins with ./ and stays inside the publish root.
Remove one plugins, markdown, mdx.components, ui, or custom render entry at a time.
Re-run doctor and build after each change.
Treat a missing export or broken registered Astro view as a real build error.

TidyPress intentionally does not swallow a registered view failure and fall back to unrelated baseline markup.

Inspect generated contracts

After a successful build, verify:

site/build/index.html
site/build/pagefind/
site/build/llms.txt
site/build/sitemap-index.xml   # when a production siteUrl is available

Pagefind and sitemap filenames may include additional generated files. Validate the public behavior rather than editing anything inside build/.

No hidden environment installer

npm install tidypress, tidypress --version, and ordinary CLI commands do not install agent skills or modify the shell. Skill installation is explicit:

npx tidypress skills install

It writes only the TidyPress skill folder in the detected supported agent location and preserves existing files unless --force is supplied.