Capabilities

# Capabilities

Exact stable and experimental feature gates recognized by TidyPress.

Capabilities are a closed registry. Unknown names fail configuration validation;
they are not general feature flags for arbitrary project code.

## Registry

| Key | Scope | Default | Meaning |
|---|---|---:|---|
| `docs` | collection | on | Built-in docs collection and routes |
| `writing` | collection | on | Writing collection and routes |
| `pages` | collection | on | Root-page collection and routes |
| `theming` | feature | on | Theme switching and theme surface |
| `themingCustom` | feature | off | Required for `theme.mode: 'custom'` |
| `llmsTxt` | feature | on | Full published Markdown build artifact |
| `editor` | experimental | off | Guard for the unimplemented editor scaffold |
| `export` | experimental | off | Guard for the unimplemented export scaffold |
| `ai` | experimental | off | Guard for the unimplemented AI scaffold |

`projects`, `search`, `rss`, `archive`, `tags`, `readingTime`, `i18n`, and
`versioning` are **not** capability keys. Configure those through their actual
collection or feature fields.

## Resolution

```ts
capabilities: {
  disable: ['pages', 'llmsTxt'],
  enable: ['themingCustom'],
}
```

Resolution order is baseline defaults, direct collection/experimental config,
`capabilities.disable`, then `capabilities.enable`. A name cannot appear in both
lists.

## Collections

For built-in `docs`, `writing`, and `pages`, direct collection `enabled` values
participate in capability resolution:

```ts
collections: {
  docs: { enabled: false, basePath: '/docs' },
}
```

Starter presets set both the public collection shape and the relevant gates.

## Custom theming

```ts
capabilities: { enable: ['themingCustom'] },
theme: {
  mode: 'custom',
  tokens: {
    light: { bg: '#ffffff', fg: '#111111' },
    dark: { bg: '#0a0a0a', fg: '#fafafa' },
  },
}
```

Custom mode requires complete light and dark token objects. The baseline
guardrailed mode remains active when the custom capability is absent.

## Experimental means unavailable

The `editor`, `export`, and `ai` commands currently validate both a config gate
and an explicit CLI flag, then exit with `EXPERIMENTAL_NOT_IMPLEMENTED`. Their
presence reserves and tests the future interface; it is not a promise that the
feature works in the current release.

Capabilities are a closed registry. Unknown names fail configuration validation; they are not general feature flags for arbitrary project code.

Registry

Key	Scope	Default	Meaning
`docs`	collection	on	Built-in docs collection and routes
`writing`	collection	on	Writing collection and routes
`pages`	collection	on	Root-page collection and routes
`theming`	feature	on	Theme switching and theme surface
`themingCustom`	feature	off	Required for `theme.mode: 'custom'`
`llmsTxt`	feature	on	Full published Markdown build artifact
`editor`	experimental	off	Guard for the unimplemented editor scaffold
`export`	experimental	off	Guard for the unimplemented export scaffold
`ai`	experimental	off	Guard for the unimplemented AI scaffold

projects, search, rss, archive, tags, readingTime, i18n, and versioning are not capability keys. Configure those through their actual collection or feature fields.

Resolution

capabilities: {
  disable: ['pages', 'llmsTxt'],
  enable: ['themingCustom'],
}

Resolution order is baseline defaults, direct collection/experimental config, capabilities.disable, then capabilities.enable. A name cannot appear in both lists.

Collections

For built-in docs, writing, and pages, direct collection enabled values participate in capability resolution:

collections: {
  docs: { enabled: false, basePath: '/docs' },
}

Starter presets set both the public collection shape and the relevant gates.

Custom theming

capabilities: { enable: ['themingCustom'] },
theme: {
  mode: 'custom',
  tokens: {
    light: { bg: '#ffffff', fg: '#111111' },
    dark: { bg: '#0a0a0a', fg: '#fafafa' },
  },
}

Custom mode requires complete light and dark token objects. The baseline guardrailed mode remains active when the custom capability is absent.

Experimental means unavailable

The editor, export, and ai commands currently validate both a config gate and an explicit CLI flag, then exit with EXPERIMENTAL_NOT_IMPLEMENTED. Their presence reserves and tests the future interface; it is not a promise that the feature works in the current release.