# `lyt help patterns` — Lyt patterns

> Patterns are Lyt's operational layer. Each pattern is a directory of `pattern.yon` (declarative manifest) + `templates/*.md` (Markdown templates with frontmatter). The `lyt pattern *` verb set installs / links / forks / runs them. The patterns ship Alex's operational scaffolding so every Lyt vault gets the same vocabulary out of the box.

---

## The default pattern

Bundled with `@younndai/lyt-vault` and copied to `~/lyt/patterns/<name>/` by the postinstall hook on `npm install -g`.

| Pattern               | Verbs            | What it covers                                                                                                        |
| --------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| **knowledge-capture** | capture · recall | Save a Figment (markdown note with frontmatter); search the vault by keyword. Used by `/lyt-capture` + `/lyt-recall`. |

> Lyt ships a deliberately small, unopinionated pattern set. It bundles only `knowledge-capture` (the capture/recall substrate). Opinionated workflow patterns — planning, handoffs, decision logs, project lifecycles — are intentionally NOT bundled; install your own with `lyt pattern install --from <dir>`.

---

## CLI surface — `lyt pattern *` (8 subcommands)

### `lyt pattern list [--vault <name>] [--json]`

Show every pattern installed at `~/lyt/patterns/`. Pass `--vault <name>` to also show which patterns are linked into that vault.

### `lyt pattern install --from <local-dir> [--as <name>] [--force]`

Install a pattern from a local directory containing `pattern.yon`. The `--as <name>` flag overrides the installed name (default: basename of `--from`). Pass `--force` to overwrite an existing installation.

> v1 supports local-path install only. Git-URL and npm-package install land in v1.5.

### `lyt pattern uninstall <name> [--force]`

Remove a pattern from `~/lyt/patterns/`. Refuses if any active vault has a symlink to this pattern; pass `--force` to unlink first, then remove. The verb reports which vaults are affected.

### `lyt pattern link <name> --vault <vault-name>`

Create a symlink at `<vault-path>/.lyt/patterns/<name>` pointing to `~/lyt/patterns/<name>`. On Windows-no-admin or other failure, falls back to a directory copy (status: `copied-fallback`). After linking, the vault's `agents.md` "Installed patterns + skills" section is regenerated.

### `lyt pattern unlink <name> --vault <vault-name>`

Remove the vault-side symlink. Regenerates `agents.md` accordingly.

### `lyt pattern fork <source> --as <new-name>`

Copy `~/lyt/patterns/<source>/` to `~/lyt/patterns/<new-name>/` for customization without modifying the master. To switch a vault to the fork: `pattern unlink <source> --vault <v>` then `pattern link <new-name> --vault <v>`.

### `lyt pattern verbs <name> [--json]`

List the verbs a pattern declares (from its `pattern.yon`).

### `lyt pattern run <pattern> <verb> --vault <v> [--project <p>] [--slug <s>] [--vars k=v...]`

Execute a verb: read the template, fill frontmatter tokens (`<date>`, `<slug>`, `<project>`, `<owner>`, plus any `--vars`), resolve the path-glob, and write the file. Pattern-backed workflows use this runtime; most `/lyt-*` skills route directly to their corresponding CLI family.

---

## Symlink + gitignore mechanics

Pattern symlinks live at `<vault>/.lyt/patterns/<name>`. They're **gitignored from the vault repo** (via the `.lyt/patterns/` rule) — pattern infrastructure is machine-local, not committed. Living under `.lyt/` means they're Lyt-owned (users never touch them) and are removed for free when `.lyt/` is torn down on `vault abandon`/`delete`.

- `lyt vault adopt <path>` and `lyt vault join <path>` auto-call `pattern link` for every installed pattern when registering a new vault, so cloning a vault on a new machine and running `join` rebuilds the symlinks per-machine.
- The `agents.md` "Installed patterns + skills" section is auto-regenerated by `pattern link` / `pattern unlink` (and again by `lyt vault sync-metadata --apply`).
- The master `~/lyt/patterns/<name>/` is the source of truth. Direct edits to it are not supported; use `pattern fork` to customize.

---

## Open caveats (v1.0.0)

- **No pattern version migration in v1.** Installing a newer version of a pattern overwrites the master; symlinks resolve to the new version automatically. Files already created from the old template are NOT migrated. A `lyt pattern migrate` verb is post-v1.
- **Verb conflicts are addressed explicitly.** Two installed patterns can both declare the same verb (e.g. a `note` verb). Use `lyt pattern run <pattern-id> note` (explicit pattern qualification). Skills disambiguate by package convention; a second `note`-providing pattern installs as `/lyt-<pattern-id>-note`.
- **Char-class globs in vault filters are escaped literally.** `lyt vault sync-metadata --vaults "[ab]*"` matches the literal `[ab]*`, not a class. Use comma-separated patterns instead.

See also: `lyt help skills` for focused harness guidance. `/lyt-capture` uses the bundled `knowledge-capture` write verb; `/lyt-recall` uses search directly. Invoke verbs from patterns you install yourself through `/lyt-pattern run <pattern> <verb>`.