TanStack · LadyBluenotes · Sep 6, 2026 · Sep 6, 2026 · Sep 6, 2026 · Sep 6, 2026
diff --git a/docs/cli/intent-exclude.md b/docs/cli/intent-exclude.md
@@ -1,43 +1,49 @@
----
-title: intent exclude
-id: intent-exclude
----
-
-`intent exclude` manages `package.json#intent.exclude` entries.
-
-```bash
-npx @tanstack/intent@latest exclude [list|add|remove] [pattern] [--json]
-```
-
-## Options
-
-- `--json`: print the configured exclude patterns as JSON
-
-## Actions
-
-1. `list` (default): print current excludes
-2. `add <pattern>`: append one exclude pattern
-3. `remove <pattern>`: remove one exclude pattern
-
-## Examples
-
-```bash
-npx @tanstack/intent@latest exclude
-npx @tanstack/intent@latest exclude list --json
-npx @tanstack/intent@latest exclude add @tanstack/router#experimental-*
-npx @tanstack/intent@latest exclude remove @tanstack/router#experimental-*
-```
-
-## Behavior
-
-- Reads and writes the current working directory `package.json`
-- Creates `intent.exclude` when missing
-- Keeps existing excludes and appends new patterns in order
-- Validates pattern syntax before writing
-- Refuses invalid `package.json` structures for `intent` and `intent.exclude`
-
-## Related
-
-- [Configuration](../concepts/configuration)
-- [intent list](./intent-list)
-- [intent load](./intent-load)
+---
+title: intent exclude
+id: intent-exclude
+---
+
+`intent exclude` manages `package.json#intent.exclude` entries.
+
+<!-- ::start:tabs variant="package-manager" mode="local-install" -->
+
+@tanstack/intent@latest exclude [list|add|remove] [pattern] [--json]
+
+<!-- ::end:tabs -->
+
+## Options
+
+- `--json`: print the configured exclude patterns as JSON
+
+## Actions
+
+1. `list` (default): print current excludes
+2. `add <pattern>`: append one exclude pattern
+3. `remove <pattern>`: remove one exclude pattern
+
+## Examples
+
+<!-- ::start:tabs variant="package-manager" mode="local-install" -->
+
+```text
+@tanstack/intent@latest exclude
+@tanstack/intent@latest exclude list --json
+@tanstack/intent@latest exclude add @tanstack/router#experimental-*
+@tanstack/intent@latest exclude remove @tanstack/router#experimental-*
+```
+
+<!-- ::end:tabs -->
+
+## Behavior
+
+- Reads and writes the current working directory `package.json`
+- Creates `intent.exclude` when missing
+- Keeps existing excludes and appends new patterns in order
+- Validates pattern syntax before writing
+- Refuses invalid `package.json` structures for `intent` and `intent.exclude`
+
+## Related
+
+- [Configuration](../concepts/configuration)
+- [intent list](./intent-list)
+- [intent load](./intent-load)
diff --git a/docs/cli/intent-hooks.md b/docs/cli/intent-hooks.md
@@ -5,9 +5,11 @@ id: intent-hooks
 
 `intent hooks install` installs lifecycle hooks that surface available Intent skills and gate supported edit tools until they observe an Intent guidance check.
 
-```bash
-npx @tanstack/intent@latest hooks install [--scope project|user] [--agents copilot,claude,codex|all]
-```
+<!-- ::start:tabs variant="package-manager" mode="local-install" -->
+
+@tanstack/intent@latest hooks install [--scope project|user] [--agents copilot,claude,codex|all]
+
+<!-- ::end:tabs -->
 
 ## Options
 
@@ -20,7 +22,8 @@ npx @tanstack/intent@latest hooks install [--scope project|user] [--agents copil
 
 - Installs hook behavior without writing an `intent-skills` guidance block.
 - Returns a session-start skill catalog as agent context with available `skill-id: description` entries.
-- Blocks supported edit tools until the hook observes a recognized `intent list` or `intent load <skill-id>` command. If no listed skill matches the task, the agent can continue without loading one.
+- Builds that catalog with the project's installed `@tanstack/intent` CLI when one is resolvable from `node_modules`. When that same installation has a `node_modules/.bin/intent` shim, the catalog suggests `node_modules/.bin/intent load <skill-id>` for loads; without a shim, or without a local install, it suggests the package-manager runner (`npx @tanstack/intent@latest`, `pnpm dlx`, ...), which resolves the package against the registry on every run. Without a local install the catalog itself is also built through that runner.
+- Blocks supported edit tools until the hook observes a recognized `intent list` or `intent load <skill-id>` command, including the `node_modules/.bin/intent` form. If no listed skill matches the task, the agent can continue without loading one.
 - Uses `package.json#intent.skills` and `package.json#intent.exclude` to control which skills appear in the session catalog.
 
 ### Installation behavior

diff --git a/docs/cli/intent-install.md b/docs/cli/intent-install.md
@@ -5,9 +5,13 @@ id: intent-install
 
 `intent install` confirms skill-source permissions on first use, then creates or updates an `intent-skills` guidance block in a project guidance file.
 
-```bash
-npx @tanstack/intent@latest install [--map] [--dry-run] [--print-prompt] [--global] [--global-only] [--no-notices]
-```
+<!-- ::start:tabs variant="package-manager" mode="local-install" -->
+
+@tanstack/intent@latest install [--maintainer] [--review] [--map] [--dry-run] [--print-prompt] [--global] [--global-only] [--no-notices]
+
+<!-- ::end:tabs -->
+
+Keep `@tanstack/intent` in devDependencies and commit the lockfile before using the generated guidance. The generated commands use `pnpm exec`, `npm exec --no`, `yarn exec`, or `bunx --no-install`; install a missing CLI explicitly instead of allowing later agent sessions to fetch `latest`.
 
 ## Options
 
@@ -29,6 +33,17 @@ npx @tanstack/intent@latest install [--map] [--dry-run] [--print-prompt] [--glob
 
 ## Behavior
 
+### Maintainer workflow
+
+For the full command workflow, use [`intent maintainer setup`](./intent-maintainer). `install --maintainer` remains available when only the repository instruction block is needed.
+
+`install --maintainer` enables initial skill batches and source-aware skill maintenance in repository agent instructions. It works without an interactive terminal or existing consumer permissions. It writes a separate `intent-maintainer` block, preserves consumer guidance, and is idempotent. `--dry-run` previews the block.
+
+Run it from the library root. The block loads the packaged authoring procedure for substantial library work; that procedure covers the cumulative domain map, spec, and skill tree, source review, task checks, and revision-bound outcomes. It updates the file that already contains either Intent managed block, or creates `AGENTS.md` when neither exists. It cannot be combined with `--review`, `--map`, `--print-prompt`, `--global`, or `--global-only`. See [Quick Start for Maintainers](../getting-started/quick-start-maintainers).
+
+> [!NOTE] Maintainer installation writes guidance
+> It does not add Intent to `package.json`, configure consumer skill permissions, install agent hooks, or add CI. The managed block uses the detected package manager's runner with `@tanstack/intent@latest`.
+
 ### Default install
 
 If `intent.skills` is already configured, including through workspace inheritance, `install` only updates guidance. It does not prompt or change `package.json`. Run `intent install --review` to change permissions.
@@ -73,9 +88,11 @@ After permissions are saved, Intent updates an existing managed guidance block i
 
 ### Review existing permissions
 
-```bash
-npx @tanstack/intent@latest install --review
-```
+<!-- ::start:tabs variant="package-manager" mode="local-install" -->
+
+@tanstack/intent@latest install --review
+
+<!-- ::end:tabs -->
 
 Review starts from the current `intent.skills` rules. Continue with them, add packages/scopes/individual skills, remove explicit rules, or review individual skills within enabled packages. Existing rules stay intact unless you change them, including rules for packages or skills that are **not discovered**. Removing a rule requires unchecking it; Intent never removes it automatically.
 
@@ -103,34 +120,11 @@ Supported config files: `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.github/copil
 
 ## Default output
 
-The default block tells agents to discover skills and load matching guidance on demand:
-
-```markdown
-<!-- intent-skills:start -->
-## Skill Loading
-
-Before editing files for a substantial task:
-- Run `npx @tanstack/intent@latest list` from the workspace root to see available local skills.
-- If a listed skill matches the task, run `npx @tanstack/intent@latest load <package>#<skill>` before changing files.
-- Use the loaded `SKILL.md` guidance while making the change.
-- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
-- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.
-<!-- intent-skills:end -->
-```
+The managed `intent-skills` block instructs agents to discover skills with `intent list`, load matching guidance with `intent load`, and apply it before editing. It tells agents to work from the workspace root, prefer the most specific local skill, and load additional skills only when the task spans multiple concerns. Generated commands use the detected package manager's runner with `@tanstack/intent@latest`.
 
 ## Mapping output
 
-`--map` writes compact skill identities and commands:
-
-```yaml
-<!-- intent-skills:start -->
-# TanStack Intent - before editing files, run the matching guidance command.
-tanstackIntent:
-  - id: "@tanstack/query#fetching"
-    run: "npx @tanstack/intent@latest load @tanstack/query#fetching"
-    for: "Query data fetching patterns"
-<!-- intent-skills:end -->
-```
+`--map` writes a `tanstackIntent` list inside the managed `intent-skills` block. Each mapping contains:
 
 - `id`: portable skill identity in `<package>#<skill>` format
 - `run`: package-manager-aware command agents should run before editing

diff --git a/docs/cli/intent-list.md b/docs/cli/intent-list.md
@@ -5,9 +5,11 @@ id: intent-list
 
 `intent list` discovers skill-enabled packages and shows the skills available under the project's permissions and exclusions. It does not change permissions or write guidance.
 
-```bash
-npx @tanstack/intent@latest list [--json] [--debug] [--global] [--global-only] [--show-hidden] [--no-notices]
-```
+<!-- ::start:tabs variant="package-manager" mode="local-install" -->
+
+@tanstack/intent@latest list [--json] [--debug] [--global] [--global-only] [--show-hidden] [--no-notices]
+
+<!-- ::end:tabs -->
 
 ## Options
 
@@ -25,6 +27,9 @@ npx @tanstack/intent@latest list [--json] [--debug] [--global] [--global-only] [
 
 ## Behavior
 
+> [!NOTE]
+> `list` is the consumer catalog for skills shipped by project and workspace dependencies. Library maintainers load Intent's packaged authoring procedures through `intent meta` or the installed maintainer block; `intent maintainer` handles setup, registration, synchronization, and checks.
+
 ### Default list
 
 Intent scans project and workspace dependencies, applies `package.json#intent.skills`, then removes packages and skills matched by `intent.exclude`. It uses project `node_modules` when available and Yarn's PnP API in PnP projects without usable `node_modules`.
@@ -81,7 +86,7 @@ Text output includes:
 - A skill tree grouped by package, with descriptions and commands to load each skill.
 - Version conflicts and discovery warnings, when present.
 
-Load commands use the detected package manager and preserve the selected global scan scope. `SOURCE` distinguishes local discovery from explicit global scanning.
+Load commands use the detected package manager's `@tanstack/intent@latest` runner and preserve the selected global scan scope. `SOURCE` distinguishes local discovery from explicit global scanning.
 
 Text output and discovery warnings go to stdout. Policy notices and `--debug` details go to stderr.
 
@@ -99,7 +104,8 @@ Text output and discovery warnings go to stdout. Policy notices and `--debug` de
       "packageVersion": "5.0.0",
       "packageSource": "local",
       "skillName": "fetching",
-      "description": "Query data fetching patterns",
+      "description": "Use when fetching and caching server data with TanStack Query.",
+      "purpose": "Query data fetching patterns",
       "type": "core",
       "framework": "react"
     }
@@ -124,6 +130,8 @@ Text output and discovery warnings go to stdout. Policy notices and `--debug` de
 | Field | Meaning |
 | --- | --- |
 | `skills` | Available skills. `use` is the portable `<package>#<skill>` identity; `type` and `framework` are optional. |
+| Skill `description` | Standard agent-discovery text describing when to use the skill. Also used in the text listing. |
+| Skill `purpose` | Optional descriptive explanation from `metadata.purpose`, kept separate from activation guidance. Omitted from JSON when absent. |
 | `packages` | Selected packages, their source and location, and permitted skill counts. |
 | `hiddenSourceCount` | Number of packages hidden by the explicit allowlist. |
 | `hiddenSources` | Objects with `name` and `skillCount` in human sessions, even without `--show-hidden`. Always empty in agent sessions. |
@@ -156,6 +164,7 @@ JSON includes diagnostics in the object instead of printing separate warning or
 
 - [intent install](./intent-install)
 - [intent load](./intent-load)
+- [intent meta](./intent-meta)
 - [intent exclude](./intent-exclude)
 - [Configuration](../concepts/configuration)
 - [Trust model](../concepts/trust-model)
diff --git a/docs/cli/intent-load.md b/docs/cli/intent-load.md
@@ -5,10 +5,14 @@ id: intent-load
 
 `intent load` loads a compact skill identity from the current install and prints the matching `SKILL.md` content.
 
-```bash
-npx @tanstack/intent@latest load <package>#<skill> [--path] [--json] [--debug] [--global] [--global-only]
+<!-- ::start:tabs variant="package-manager" mode="local-install" -->
+
+```text
+@tanstack/intent@latest load <package>#<skill> [--path] [--json] [--debug] [--global] [--global-only]
 ```
 
+<!-- ::end:tabs -->
+
 ## Options
 
 - `--path`: print the resolved skill path instead of the file content
@@ -44,12 +48,14 @@ The package can be scoped or unscoped. The skill can include slash-separated sub
 
 Examples:
 
-```bash
-npx @tanstack/intent@latest load @tanstack/query#fetching
-npx @tanstack/intent@latest load @tanstack/query#core/fetching
-npx @tanstack/intent@latest load @tanstack/router-core#auth-and-guards
-npx @tanstack/intent@latest load some-lib#core --path
-```
+<!-- ::start:tabs variant="package-manager" mode="local-install" -->
+
+@tanstack/intent@latest load @tanstack/query#fetching
+@tanstack/intent@latest load @tanstack/query#core/fetching
+@tanstack/intent@latest load @tanstack/router-core#auth-and-guards
+@tanstack/intent@latest load some-lib#core --path
+
+<!-- ::end:tabs -->
 
 ## JSON output