TanStack · LadyBluenotes · Sep 6, 2026 · Sep 6, 2026 · Sep 6, 2026 · Sep 6, 2026
diff --git a/docs/cli/intent-adopt.md b/docs/cli/intent-adopt.md
@@ -0,0 +1,57 @@
+---
+title: intent maintainer adopt
+id: intent-adopt
+---
+
+Register existing library skills without rewriting their content. No AI agent is required. Use your repository's installed Intent command for these examples.
+
+## Interactive adoption
+
+```sh
+intent maintainer adopt
+```
+
+The command discovers Git-visible `skills/**/SKILL.md` files, identifies their owning packages, and compares them with the planning record. Dependency files and hidden agent directories are excluded. Use `--path <directory>` to include a non-hidden custom skill directory relative to the repository root.
+
+Select registrations, supply missing domains, and choose repository distribution separately. Existing domain assignments and distribution choices are retained unless explicitly changed. A final preview lists the registrations and planning files before confirmation. Canceling writes nothing.
+
+Duplicate names, invalid guidance, and missing registered files are reported. Planned and retired entries remain separate; adoption does not reactivate or delete them.
+
+## Agents and automation
+
+Preview and apply are separate operations:
+
+```sh
+intent maintainer adopt --json > adoption.json
+intent maintainer adopt --apply adoption.json
+```
+
+Between these commands, review the plan. Set `selected: true` on each unregistered skill to adopt and supply its `domain`. Keep every entry, identity, and fingerprint. The `distribution` object accepts the current choice, `{ "mode": "none" }`, or a repository selection:
+
+```json
+{
+  "mode": "repo",
+  "repository": "owner/library",
+  "skills": ["query"]
+}
+```
+
+New skills are not selected automatically. Apply rechecks source, records, and relevant instruction files; regenerate the plan if they changed. With several planning locations, pass the same `--artifacts <directory>` on preview and apply.
+
+## CI
+
+CI never opens interactive prompts, even with an attached terminal. `adopt --json` is read-only and returns zero when it successfully produces a report; unregistered skills in that report do not mean the report failed. Applying a reviewed plan is an explicit repository mutation, not a routine CI check.
+
+For a read-only CI gate after adoption, run:
+
+```sh
+intent maintainer check --base <available-base-commit>
+```
+
+This checks authored coverage, synchronization, validation, and recorded review. It exits nonzero for unresolved work. Make the comparison commit available in the checkout. CI does not supply semantic review decisions automatically.
+
+## After adoption
+
+Adoption creates missing planning records, appends registrations, preserves skill text and purpose, and installs maintainer guidance. Repeating the flow with a fresh unchanged plan preserves records. It does not synchronize package metadata, generate exports, publish, or record semantic review outcomes.
+
+Run `intent maintainer status`, complete task coverage, synchronize, assess and record source review, then run `intent maintainer check`. Registration does not establish that guidance is correct.
diff --git a/docs/cli/intent-exclude.md b/docs/cli/intent-exclude.md
@@ -1,43 +1,74 @@
----
-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" -->
+
+react: @tanstack/intent@latest exclude [list|add|remove] [pattern] [--json]
+solid: @tanstack/intent@latest exclude [list|add|remove] [pattern] [--json]
+vue: @tanstack/intent@latest exclude [list|add|remove] [pattern] [--json]
+svelte: @tanstack/intent@latest exclude [list|add|remove] [pattern] [--json]
+angular: @tanstack/intent@latest exclude [list|add|remove] [pattern] [--json]
+lit: @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
+react: @tanstack/intent@latest exclude
+react: @tanstack/intent@latest exclude list --json
+react: @tanstack/intent@latest exclude add @tanstack/router#experimental-*
+react: @tanstack/intent@latest exclude remove @tanstack/router#experimental-*
+solid: @tanstack/intent@latest exclude
+solid: @tanstack/intent@latest exclude list --json
+solid: @tanstack/intent@latest exclude add @tanstack/router#experimental-*
+solid: @tanstack/intent@latest exclude remove @tanstack/router#experimental-*
+vue: @tanstack/intent@latest exclude
+vue: @tanstack/intent@latest exclude list --json
+vue: @tanstack/intent@latest exclude add @tanstack/router#experimental-*
+vue: @tanstack/intent@latest exclude remove @tanstack/router#experimental-*
+svelte: @tanstack/intent@latest exclude
+svelte: @tanstack/intent@latest exclude list --json
+svelte: @tanstack/intent@latest exclude add @tanstack/router#experimental-*
+svelte: @tanstack/intent@latest exclude remove @tanstack/router#experimental-*
+angular: @tanstack/intent@latest exclude
+angular: @tanstack/intent@latest exclude list --json
+angular: @tanstack/intent@latest exclude add @tanstack/router#experimental-*
+angular: @tanstack/intent@latest exclude remove @tanstack/router#experimental-*
+lit: @tanstack/intent@latest exclude
+lit: @tanstack/intent@latest exclude list --json
+lit: @tanstack/intent@latest exclude add @tanstack/router#experimental-*
+lit: @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,16 @@ 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" -->
+
+react: @tanstack/intent@latest hooks install [--scope project|user] [--agents copilot,claude,codex|all]
+solid: @tanstack/intent@latest hooks install [--scope project|user] [--agents copilot,claude,codex|all]
+vue: @tanstack/intent@latest hooks install [--scope project|user] [--agents copilot,claude,codex|all]
+svelte: @tanstack/intent@latest hooks install [--scope project|user] [--agents copilot,claude,codex|all]
+angular: @tanstack/intent@latest hooks install [--scope project|user] [--agents copilot,claude,codex|all]
+lit: @tanstack/intent@latest hooks install [--scope project|user] [--agents copilot,claude,codex|all]
+
+<!-- ::end:tabs -->
 
 ## Options
 
@@ -20,7 +27,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,16 @@ 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" -->
+
+react: @tanstack/intent@latest install [--maintainer] [--review] [--map] [--dry-run] [--print-prompt] [--global] [--global-only] [--no-notices]
+solid: @tanstack/intent@latest install [--maintainer] [--review] [--map] [--dry-run] [--print-prompt] [--global] [--global-only] [--no-notices]
+vue: @tanstack/intent@latest install [--maintainer] [--review] [--map] [--dry-run] [--print-prompt] [--global] [--global-only] [--no-notices]
+svelte: @tanstack/intent@latest install [--maintainer] [--review] [--map] [--dry-run] [--print-prompt] [--global] [--global-only] [--no-notices]
+angular: @tanstack/intent@latest install [--maintainer] [--review] [--map] [--dry-run] [--print-prompt] [--global] [--global-only] [--no-notices]
+lit: @tanstack/intent@latest install [--maintainer] [--review] [--map] [--dry-run] [--print-prompt] [--global] [--global-only] [--no-notices]
+
+<!-- ::end:tabs -->
 
 ## Options
 
@@ -29,6 +36,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 +91,16 @@ 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" -->
+
+react: @tanstack/intent@latest install --review
+solid: @tanstack/intent@latest install --review
+vue: @tanstack/intent@latest install --review
+svelte: @tanstack/intent@latest install --review
+angular: @tanstack/intent@latest install --review
+lit: @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 +128,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,16 @@ 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" -->
+
+react: @tanstack/intent@latest list [--json] [--debug] [--global] [--global-only] [--show-hidden] [--no-notices]
+solid: @tanstack/intent@latest list [--json] [--debug] [--global] [--global-only] [--show-hidden] [--no-notices]
+vue: @tanstack/intent@latest list [--json] [--debug] [--global] [--global-only] [--show-hidden] [--no-notices]
+svelte: @tanstack/intent@latest list [--json] [--debug] [--global] [--global-only] [--show-hidden] [--no-notices]
+angular: @tanstack/intent@latest list [--json] [--debug] [--global] [--global-only] [--show-hidden] [--no-notices]
+lit: @tanstack/intent@latest list [--json] [--debug] [--global] [--global-only] [--show-hidden] [--no-notices]
+
+<!-- ::end:tabs -->
 
 ## Options
 
@@ -25,6 +32,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 +91,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 +109,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 +135,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 +169,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)