<!-- GENERATED by scripts/build-docs.mjs from the live Commander tree (src/cli/program.ts). Do not edit by hand. -->

# pai zettel

> Zettelkasten intelligence: explore, surprise, converse, themes, health, suggest

## Synopsis

```
pai zettel <subcommand> [options]
```

## Subcommands

| Command | Description |
|---------|-------------|
| [`pai zettel explore <note>`](#pai-zettel-explore-note) | Follow link chains from a starting note |
| [`pai zettel health`](#pai-zettel-health) | Vault structural health audit: dead links, orphans, connectivity |
| [`pai zettel surprise <note>`](#pai-zettel-surprise-note) | Find semantically similar but graph-distant notes (surprising connections) |
| [`pai zettel suggest <note>`](#pai-zettel-suggest-note) | Suggest new wikilink connections for a note |
| [`pai zettel converse <question>`](#pai-zettel-converse-question) | Ask the vault a question and get a synthesis prompt with relevant notes |
| [`pai zettel themes`](#pai-zettel-themes) | Detect emerging theme clusters in recently edited notes |

### pai zettel explore <note>

Follow link chains from a starting note

**Arguments**

| Argument | Kind |
|----------|------|
| `<note>` | required |

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--depth <n>` | Maximum traversal depth (1-10) | `3` |
| `--direction <d>` | Link direction: forward \| backward \| both | `both` |
| `--mode <m>` | Edge mode: sequential \| associative \| all | `all` |


### pai zettel health

Vault structural health audit: dead links, orphans, connectivity

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--scope <s>` | Scope: full \| recent \| project | `full` |
| `--project <path>` | Project path prefix (requires --scope project) |  |
| `--days <n>` | Look-back window in days (requires --scope recent) | `30` |
| `--include <types>` | Comma-separated subset: dead_links,orphans,disconnected,low_connectivity |  |


### pai zettel surprise <note>

Find semantically similar but graph-distant notes (surprising connections)

**Arguments**

| Argument | Kind |
|----------|------|
| `<note>` | required |

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--vault-project-id <n>` | Project ID for the vault in the federation DB |  |
| `--limit <n>` | Maximum results | `10` |
| `--min-similarity <f>` | Minimum cosine similarity (0–1) | `0.3` |
| `--min-distance <n>` | Minimum graph distance | `3` |


### pai zettel suggest <note>

Suggest new wikilink connections for a note

**Arguments**

| Argument | Kind |
|----------|------|
| `<note>` | required |

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--vault-project-id <n>` | Project ID for the vault in the federation DB |  |
| `--limit <n>` | Maximum suggestions | `5` |
| `--no-exclude-linked` | Include notes already linked from this one |  |


### pai zettel converse <question>

Ask the vault a question and get a synthesis prompt with relevant notes

**Arguments**

| Argument | Kind |
|----------|------|
| `<question>` | required |

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--vault-project-id <n>` | Project ID for the vault in the federation DB |  |
| `--depth <n>` | Graph expansion depth around matched notes | `2` |
| `--limit <n>` | Maximum relevant notes to include | `15` |


### pai zettel themes

Detect emerging theme clusters in recently edited notes

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--vault-project-id <n>` | Project ID for the vault in the federation DB |  |
| `--days <n>` | Look-back window in days | `30` |
| `--min-size <n>` | Minimum notes per cluster | `3` |
| `--max-themes <n>` | Maximum themes to return | `10` |
| `--threshold <f>` | Similarity threshold for clustering (0–1) | `0.65` |


## Examples

```bash
# Explore the neighbourhood of a note
pai zettel explore "token factory"

# Surface an unexpected connection
pai zettel surprise

# Emergent themes across the vault
pai zettel themes

# Vault connectivity health (orphans, dead links)
pai zettel health
```

## See also

[`pai audit`](audit.md) · [`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai config`](config.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai identity`](identity.md) · [`pai kg`](kg.md) · [`pai launch`](launch.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai worker`](worker.md)

Run `pai help <area>` to read any of these in the terminal.