diff --git a/docs/cli/intent-install.md b/docs/cli/intent-install.md
new file mode 100644
index 0000000..ff6d002
--- /dev/null
+++ b/docs/cli/intent-install.md
@@ -0,0 +1,37 @@
+---
+title: intent install
+id: intent-install
+---
+
+`intent install` prints instructions for setting up an `intent-skills` mapping block in your project guidance file.
+
+```bash
+npx @tanstack/intent@latest install
+```
+
+The command prints text only. It does not edit files.
+
+## Output
+
+The printed instructions include this tagged block template:
+
+```yaml
+<!-- intent-skills:start -->
+# Skill mappings — when working in these areas, load the linked skill file into context.
+skills:
+  - task: "describe the task or code area here"
+    load: "node_modules/package-name/skills/skill-name/SKILL.md"
+<!-- intent-skills:end -->
+```
+
+They also ask you to:
+
+1. Check for an existing block first
+2. Run `intent list` to discover installed skills
+3. Add task-to-skill mappings
+4. Preserve all content outside the tagged block
+
+## Related
+
+- [intent list](./intent-list)
+- [Setting Up Agent Config](../guides/consumers/agent-config-setup)
diff --git a/docs/cli/intent-list.md b/docs/cli/intent-list.md
new file mode 100644
index 0000000..3aa6606
--- /dev/null
+++ b/docs/cli/intent-list.md
@@ -0,0 +1,67 @@
+---
+title: intent list
+id: intent-list
+---
+
+`intent list` discovers skill-enabled packages and prints available skills.
+
+```bash
+npx @tanstack/intent@latest list [--json]
+```
+
+## Options
+
+- `--json`: print JSON instead of text output
+
+## What you get
+
+- Scans installed dependencies for intent-enabled packages and skills
+- Includes warnings from discovery
+- If no packages are discovered, prints `No intent-enabled packages found.`
+- Summary line with package count, skill count, and detected package manager
+- Package table columns: `PACKAGE`, `VERSION`, `SKILLS`, `REQUIRES`
+- Skill tree grouped by package
+- Optional warnings section (`⚠ ...` per warning)
+
+`REQUIRES` uses `intent.requires` values joined by `, `; empty values render as `–`.
+
+## JSON output
+
+`--json` prints the `ScanResult` object:
+
+```json
+{
+  "packageManager": "npm | pnpm | yarn | bun | unknown",
+  "packages": [
+    {
+      "name": "string",
+      "version": "string",
+      "intent": {
+        "version": 1,
+        "repo": "string",
+        "docs": "string",
+        "requires": ["string"]
+      },
+      "skills": [
+        {
+          "name": "string",
+          "path": "string",
+          "description": "string",
+          "type": "string (optional)",
+          "framework": "string (optional)"
+        }
+      ]
+    }
+  ],
+  "warnings": ["string"]
+}
+```
+
+`packages` are ordered using `intent.requires` when possible.
+
+## Common errors
+
+- Scanner failures are printed as errors
+- Unsupported environments:
+  - Yarn PnP without `node_modules`
+  - Deno projects without `node_modules`
diff --git a/docs/cli/intent-meta.md b/docs/cli/intent-meta.md
new file mode 100644
index 0000000..e700f23
--- /dev/null
+++ b/docs/cli/intent-meta.md
@@ -0,0 +1,32 @@
+---
+title: intent meta
+id: intent-meta
+---
+
+`intent meta` lists bundled meta-skills or prints one meta-skill file.
+
+```bash
+npx @tanstack/intent@latest meta
+npx @tanstack/intent@latest meta <name>
+```
+
+## Arguments
+
+- `<name>` is a meta-skill directory under `node_modules/@tanstack/intent/meta/`
+- Rejected values: any name containing `..`, `/`, or `\\`
+
+## Output
+
+- Without `<name>`:
+  - one line per meta-skill
+  - `name` + description from frontmatter
+  - description is normalized and truncated to 60 characters
+- With `<name>`:
+  - raw markdown from `meta/<name>/SKILL.md`
+
+## Common errors
+
+- Meta directory not found
+- Invalid `<name>` format
+- Unknown `<name>` (message suggests running `npx @tanstack/intent meta`)
+- Read failure for target `SKILL.md`
diff --git a/docs/cli/intent-scaffold.md b/docs/cli/intent-scaffold.md
new file mode 100644
index 0000000..eceb0e7
--- /dev/null
+++ b/docs/cli/intent-scaffold.md
@@ -0,0 +1,40 @@
+---
+title: intent scaffold
+id: intent-scaffold
+---
+
+`intent scaffold` prints a phased scaffold prompt for generating skills.
+
+```bash
+npx @tanstack/intent@latest scaffold
+```
+
+## Behavior
+
+- Prints prompt text to stdout
+- Does not create files
+
+## Output
+
+The printed prompt defines three ordered phases:
+
+1. `domain-discovery`
+2. `tree-generator`
+3. `generate-skill`
+
+Each phase includes a stop gate before continuing.
+
+The prompt also includes a post-generation checklist:
+
+- Run `npx @tanstack/intent@latest validate` and fix issues
+- Commit generated `skills/` and `skills/_artifacts/`
+- Ensure `@tanstack/intent` is in `devDependencies`
+- Run setup commands as needed:
+  - `npx @tanstack/intent@latest add-library-bin`
+  - `npx @tanstack/intent@latest edit-package-json`
+  - `npx @tanstack/intent@latest setup-github-actions`
+
+## Related
+
+- [intent validate](./intent-validate)
+- [setup commands](./intent-setup)
diff --git a/docs/cli/intent-setup.md b/docs/cli/intent-setup.md
new file mode 100644
index 0000000..953ecfc
--- /dev/null
+++ b/docs/cli/intent-setup.md
@@ -0,0 +1,56 @@
+---
+title: setup commands
+id: intent-setup
+---
+
+Intent exposes setup as three separate commands.
+
+```bash
+npx @tanstack/intent@latest add-library-bin
+npx @tanstack/intent@latest edit-package-json
+npx @tanstack/intent@latest setup-github-actions
+```
+
+## Commands
+
+- `add-library-bin`: create a package-local `intent` shim in `bin/`
+- `edit-package-json`: add or normalize `package.json` entries needed to publish skills
+- `setup-github-actions`: copy workflow templates to `.github/workflows`
+
+## What each command changes
+
+- `add-library-bin`
+  - Creates `bin/intent.js` when `package.json.type` is `module`, otherwise `bin/intent.mjs`
+  - If either shim already exists, command skips creation
+  - Shim imports `@tanstack/intent/intent-library`
+- `edit-package-json`
+  - Requires a valid `package.json` in current directory
+  - Ensures `bin.intent` points to `./bin/intent.<ext>`
+  - Ensures `files` includes required publish entries
+  - Preserves existing indentation and existing `bin` entries
+  - Converts string shorthand `bin` to object when needed
+- `setup-github-actions`
+  - Copies templates from `@tanstack/intent/meta/templates/workflows` to `.github/workflows`
+  - Applies variable substitution for `PACKAGE_NAME`, `REPO`, `DOCS_PATH`, `SRC_PATH`
+  - Skips files that already exist at destination
+
+## Required `files` entries
+
+`edit-package-json` enforces different `files` sets based on package location:
+
+- Monorepo package: `skills`, `bin`
+- Non-monorepo package: `skills`, `bin`, `!skills/_artifacts`
+
+## Common errors
+
+- Missing or invalid `package.json` when running `edit-package-json`
+- Missing template source when running `setup-github-actions`
+
+## Notes
+
+- `add-library-bin` and `setup-github-actions` skip existing files
+
+## Related
+
+- [intent validate](./intent-validate)
+- [intent scaffold](./intent-scaffold)
diff --git a/docs/cli/intent-stale.md b/docs/cli/intent-stale.md
new file mode 100644
index 0000000..b532c4d
--- /dev/null
+++ b/docs/cli/intent-stale.md
@@ -0,0 +1,81 @@
+---
+title: intent stale
+id: intent-stale
+---
+
+`intent stale` reports whether shipped skills may need review.
+
+```bash
+npx @tanstack/intent@latest stale [--json]
+```
+
+## Options
+
+- `--json`: print JSON array of staleness reports
+
+## Behavior
+
+- Scans installed intent-enabled packages
+- Computes one staleness report per package
+- Prints text output by default or JSON with `--json`
+- If no packages are found, prints `No intent-enabled packages found.`
+
+## JSON report schema
+
+`--json` outputs an array of reports:
+
+```json
+[
+  {
+    "library": "string",
+    "currentVersion": "string | null",
+    "skillVersion": "string | null",
+    "versionDrift": "major | minor | patch | null",
+    "skills": [
+      {
+        "name": "string",
+        "reasons": ["string"],
+        "needsReview": true
+      }
+    ]
+  }
+]
+```
+
+Report fields:
+
+- `library`: package name
+- `currentVersion`: latest version from npm registry (or `null` if unavailable)
+- `skillVersion`: `library_version` from skills (or `null`)
+- `versionDrift`: `major | minor | patch | null`
+- `skills`: array of per-skill checks
+
+Skill fields:
+
+- `name`
+- `reasons`: one or more staleness reasons
+- `needsReview`: boolean (`true` when reasons exist)
+
+Reason generation:
+
+- `version drift (<skillVersion> → <currentVersion>)`
+- `new source (<path>)` when a declared source has no stored sync SHA
+
+## Text output
+
+- Report header format: `<library> (<skillVersion> → <currentVersion>) [<versionDrift> drift]`
+- When no skill reasons exist: `All skills up-to-date`
+- Otherwise: one warning line per stale skill (`⚠ <name>: <reason1>, <reason2>, ...`)
+
+## Common errors
+
+- Package scan failure: prints a scanner error
+- Registry fetch failures do not crash command; `currentVersion` may be `null`
+
+## Notes
+
+- Source staleness checking is conservative: it flags missing source SHAs in sync-state, not remote content differences.
+
+## Related
+
+- [intent list](./intent-list)
diff --git a/docs/cli/intent-validate.md b/docs/cli/intent-validate.md
new file mode 100644
index 0000000..8e4b292
--- /dev/null
+++ b/docs/cli/intent-validate.md
@@ -0,0 +1,58 @@
+---
+title: intent validate
+id: intent-validate
+---
+
+`intent validate` checks `SKILL.md` files and artifacts for structural problems.
+
+```bash
+npx @tanstack/intent@latest validate [<dir>]
+```
+
+## Arguments
+
+- `<dir>`: directory containing skills; default is `skills`
+- Relative paths are resolved from the current working directory
+
+## Validation checks
+
+For each discovered `SKILL.md`:
+
+- Frontmatter delimiter and structure are valid
+- YAML frontmatter parses successfully
+- Required fields exist: `name`, `description`
+- `name` matches skill directory path under the target root
+- `description` length is at most 1024 characters
+- `type: framework` requires `requires` to be an array
+- Total file length is at most 500 lines
+
+If `<dir>/_artifacts` exists, it also validates artifacts:
+
+- Required files: `domain_map.yaml`, `skill_spec.md`, `skill_tree.yaml`
+- Required files must be non-empty
+- `.yaml` artifacts must parse successfully
+
+## Packaging warnings
+
+Packaging warnings are always computed from `package.json` in the current working directory:
+
+- `@tanstack/intent` missing from `devDependencies`
+- Missing `bin.intent` entry
+- Missing shim (`bin/intent.js` or `bin/intent.mjs`)
+- Missing `files` entries when `files` array exists:
+  - `skills`
+  - `bin`
+  - `!skills/_artifacts`
+
+Warnings are informational; they are printed on both pass and fail paths.
+
+## Common errors
+
+- Missing target directory: `Skills directory not found: <abs-path>`
+- No skill files discovered: `No SKILL.md files found`
+- Validation failures: aggregated file-specific errors and count
+
+## Related
+
+- [intent scaffold](./intent-scaffold)
+- [setup commands](./intent-setup)
diff --git a/docs/config.json b/docs/config.json
index 552d60c..9134108 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -1,19 +1,60 @@
-{
-  "$schema": "https://raw.githubusercontent.com/TanStack/tanstack.com/main/tanstack-docs-config.schema.json",
-  "docSearch": {
-    "appId": "",
-    "apiKey": "",
-    "indexName": "tanstack-agents"
-  },
-  "sections": [
-    {
-      "label": "Getting Started",
-      "children": [
-        {
-          "label": "Overview",
-          "to": "overview"
-        }
-      ]
-    }
-  ]
-}
+{
+  "$schema": "https://raw.githubusercontent.com/TanStack/tanstack.com/main/tanstack-docs-config.schema.json",
+  "docSearch": {
+    "appId": "",
+    "apiKey": "",
+    "indexName": "tanstack-agents"
+  },
+  "sections": [
+    {
+      "label": "Getting Started",
+      "children": [
+        {
+          "label": "Overview",
+          "to": "overview"
+        },
+        {
+          "label": "Quick Start (Consumers)",
+          "to": "getting-started/quick-start-consumers"
+        },
+        {
+          "label": "Quick Start (Maintainers)",
+          "to": "getting-started/quick-start-maintainers"
+        }
+      ]
+    },
+    {
+      "label": "CLI Reference",
+      "children": [
+        {
+          "label": "intent install",
+          "to": "cli/intent-install"
+        },
+        {
+          "label": "intent list",
+          "to": "cli/intent-list"
+        },
+        {
+          "label": "intent meta",
+          "to": "cli/intent-meta"
+        },
+        {
+          "label": "intent scaffold",
+          "to": "cli/intent-scaffold"
+        },
+        {
+          "label": "intent validate",
+          "to": "cli/intent-validate"
+        },
+        {
+          "label": "intent setup-github-actions",
+          "to": "cli/intent-setup"
+        },
+        {
+          "label": "intent stale",
+          "to": "cli/intent-stale"
+        }
+      ]
+    }
+  ]
+}
diff --git a/docs/getting-started/quick-start-consumers.md b/docs/getting-started/quick-start-consumers.md
new file mode 100644
index 0000000..4b39ae9
--- /dev/null
+++ b/docs/getting-started/quick-start-consumers.md
@@ -0,0 +1,80 @@
+---
+title: Quick Start for Consumers
+id: quick-start-consumers
+---
+
+Get started using Intent to set up skill-to-task mappings for your agent.
+
+## 1. Run install
+
+The install command guides your agent through the setup process:
+
+```bash
+npx @tanstack/intent@latest install
+```
+
+This prints a skill that instructs your AI agent to:
+1. Check for existing `intent-skills` mappings in your config files (CLAUDE.md, .cursorrules, etc.)
+2. Run `intent list` to discover available skills from installed packages
+3. Scan your repository structure to understand your project
+4. Propose relevant skill-to-task mappings based on your codebase patterns
+5. Write or update an `intent-skills` block in your agent config
+
+Your agent will create mappings like:
+
+```markdown
+<!-- intent-skills:start -->
+# Skill mappings — when working in these areas, load the linked skill file into context.
+skills:
+  - task: "implementing data fetching with TanStack Query"
+    load: "node_modules/@tanstack/react-query/skills/core/SKILL.md"
+  - task: "setting up routing with TanStack Router"
+    load: "node_modules/@tanstack/react-router/skills/core/SKILL.md"
+<!-- intent-skills:end -->
+```
+
+## 2. Use skills in your workflow
+
+When your agent works on a task that matches a mapping, it automatically loads the corresponding SKILL.md into context to guide implementation.
+
+## 3. Keep skills up-to-date
+
+Skills version with library releases. When you update a library:
+
+```bash
+npm update @tanstack/react-query
+```
+
+The new version brings updated skills automatically — you don't need to do anything. The skills are shipped with the library, so you always get the version that matches your installed code.
+
+If you need to see what skills have changed, run:
+
+```bash
+npx @tanstack/intent@latest list
+```
+
+Or use `--json` for machine-readable output:
+
+```bash
+npx @tanstack/intent@latest list --json
+```
+
+You can also check if any skills reference outdated source documentation:
+
+```bash
+npx @tanstack/intent@latest stale
+```
+
+## 4. Submit feedback (optional)
+
+After using a skill, you can submit feedback to help maintainers improve it:
+
+```bash
+npx @tanstack/intent@latest meta feedback-collection
+```
+
+This prints a skill that guides your agent to collect structured feedback about gaps, errors, and improvements.
+
+
+
+
diff --git a/docs/getting-started/quick-start-maintainers.md b/docs/getting-started/quick-start-maintainers.md
new file mode 100644
index 0000000..f310aa1
--- /dev/null
+++ b/docs/getting-started/quick-start-maintainers.md
@@ -0,0 +1,200 @@
+---
+title: Quick Start for Maintainers
+id: quick-start-maintainers
+---
+
+Get started scaffolding, validating, and shipping skills for your library.
+
+## Install
+
+<!-- ::start:tabs variant="package-manager" mode="dev-install" -->
+react: @tanstack/intent
+solid: @tanstack/intent
+vue: @tanstack/intent
+svelte: @tanstack/intent
+angular: @tanstack/intent
+lit: @tanstack/intent
+<!-- ::end:tabs -->
+
+Or run commands without installing:
+
+```bash
+npx @tanstack/intent@latest scaffold
+```
+
+> [!WARNING]
+> When using `npx` or `bunx`, always include `@latest`. Intent-enabled libraries ship a local `intent` binary shim, and without `@latest`, your package manager may resolve to that shim instead of the real CLI.
+
+---
+
+## Initial Setup (With Agent)
+
+### 1. Scaffold skills
+
+Start the scaffolding process **with your AI agent**:
+
+```bash
+npx @tanstack/intent@latest scaffold
+```
+
+This prints a comprehensive prompt that walks you and your agent through three phases:
+
+**Phase 1: Domain Discovery**
+- Scans your documentation, source code, and GitHub issues
+- Conducts an interactive interview to surface implicit knowledge
+- Produces `domain_map.yaml` and `skill_spec.md` artifacts
+
+**Phase 2: Tree Generation**
+- Designs a skill taxonomy based on the domain map
+- Creates a hierarchical skill structure
+- Produces `skill_tree.yaml` artifact
+
+**Phase 3: Skill Generation**
+- Writes complete SKILL.md files for each skill
+- Includes patterns, failure modes, and API references
+- Validates against the Intent specification
+
+> [!NOTE]
+> This is a context-heavy process that involves domain discovery, GitHub issues analysis, and interactive maintainer interviews. The agent will scan your documentation, recent issues and discussions, and ask targeted questions to surface implicit knowledge and common failure modes. The more information you provide about your library's patterns, pitfalls, and real-world usage problems, the better the generated skills will be. Expect multiple rounds of refinement and regular context compaction before completion.
+
+### 2. Validate skills
+
+After scaffolding, validate that all SKILL.md files are well-formed:
+
+```bash
+npx @tanstack/intent@latest validate
+```
+
+This checks:
+- Valid YAML frontmatter in every SKILL.md
+- Required fields (`name`, `description`) are present
+- Skill names match their directory paths
+- Description length <= 1024 characters
+- Line count limits (500 lines max per skill)
+- Framework skills have a `requires` array
+- Artifact files exist and are non-empty
+
+If any artifacts are present (domain_map.yaml, skill_spec.md, skill_tree.yaml), they must parse as valid YAML.
+
+### 3. Commit skills and artifacts
+
+Commit both generated skills and the artifacts used to create them:
+
+```
+skills/
+  core/SKILL.md
+  react/SKILL.md
+  _artifacts/
+    domain_map.yaml
+    skill_spec.md
+    skill_tree.yaml
+```
+
+Artifacts enforce a consistent skill structure across versions, making it easier to audit, refresh, or extend the skill set without starting from scratch.
+
+---
+
+## Publish Configuration
+
+### 4. Configure your package for publishing
+
+Run these commands to prepare your package for skill publishing:
+
+```bash
+# Generate the bin shim that consumers use for discovery
+npx @tanstack/intent@latest add-library-bin
+
+# Update package.json with required fields
+npx @tanstack/intent@latest edit-package-json
+
+# Copy CI workflow templates (validate + stale checks)
+npx @tanstack/intent@latest setup-github-actions
+```
+
+**What these do:**
+
+- `add-library-bin` creates `bin/intent.js` or `bin/intent.mjs` — a shim that lets consumers run `npx your-package intent` to access Intent CLI features
+- `edit-package-json` adds:
+  - `intent` field in package.json with version, repo, and docs metadata
+  - `bin.intent` entry pointing to the shim
+  - `files` array entries for `skills/` and `bin/`
+  - For single packages: also adds `!skills/_artifacts` to exclude artifacts from npm
+  - For monorepos: skips the artifacts exclusion (artifacts live at repo root)
+- `setup-github-actions` copies workflow templates to `.github/workflows/` for automated validation and staleness checking
+
+### 5. Ship skills with your package
+
+Skills ship inside your npm package. When you publish:
+
+```bash
+npm publish
+```
+
+Consumers who install your library automatically get the skills. They discover them with `intent list` and map them with `intent install`.
+
+**Version alignment:**
+- Skills version with your library releases
+- Agents always load the skill matching the installed library version
+- No drift between code and guidance
+
+---
+
+## Ongoing Maintenance (Manual or Agent-Assisted)
+
+### 6. Set up CI workflows
+
+After running `setup-github-actions`, you'll have three workflows in `.github/workflows/`:
+
+**validate-skills.yml** (runs on PRs touching `skills/`)
+- Validates SKILL.md frontmatter and structure
+- Ensures files stay under 500 lines
+- Runs automatically on every pull request that modifies skills
+
+**check-skills.yml** (runs on release or manual trigger)
+- Automatically detects stale skills after you publish a new release
+- Opens a review PR with an agent-friendly prompt
+- Requires you to copy the prompt into Claude Code, Cursor, or your agent to update skills
+
+**notify-intent.yml** (runs on docs/source changes to main)
+- Sends a webhook to TanStack/intent when your docs or source change
+- Enables cross-library skill staleness tracking
+- Requires a fine-grained GitHub token (`INTENT_NOTIFY_TOKEN`) secret
+
+### 7. Update stale skills
+
+When you publish a new release, `check-skills.yml` automatically opens a PR flagging skills that need review.
+
+Manually check which skills need updates with:
+
+```bash
+npx @tanstack/intent@latest stale
+```
+
+This detects:
+- **Version drift** — skill targets an older library version than currently installed
+- **New sources** — sources declared in frontmatter that weren't tracked before
+
+**To update stale skills:**
+1. Review the PR opened by `check-skills.yml`
+2. Copy the agent prompt from the PR description
+3. Paste it into Claude Code, Cursor, or your coding agent
+4. The agent reads the stale skills and updates them based on library changes
+5. Run `npx @tanstack/intent@latest validate` locally to verify
+6. Commit and merge the PR
+
+> [!NOTE]
+> Skills are updated through agent assistance, not full automation. The workflow detects what's stale and provides the prompt — your agent handles the actual updates.
+
+Use `--json` output for CI integration or scripting.
+
+### 8. Maintain and iterate
+
+As your library evolves:
+
+1. **When APIs change:** Update relevant SKILL.md files with new patterns
+2. **When docs change:** Run `intent stale` to identify affected skills
+3. **When issues are filed:** Check if the failure mode should be added to "Common Mistakes"
+4. **After major releases:** Consider re-running domain discovery to catch new patterns
+
+> [!TIP]
+> Create GitHub issue labels matching your skill names (`skill:core`, `skill:react`). When users file issues, tag them with the relevant skill label to track which areas need the most improvement.
diff --git a/docs/overview.md b/docs/overview.md
index ecb0d91..3c765a7 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -1,84 +1,61 @@
----
-title: Overview
----
-
-`@tanstack/intent` is a CLI for library maintainers to generate, validate, and ship [Agent Skills](https://agentskills.io) alongside their npm packages.
-
-## The problem
-
-Your docs are good. Your types are solid. Your agent still gets it wrong.
-
-Docs target humans who browse. Types check individual API calls but can't encode intent. Training data snapshots the ecosystem as it _was_, mixing versions with no way to tell which applies. Once a breaking change ships, models develop a permanent split-brain — training data contains _both_ versions forever with no way to disambiguate.
-
-The ecosystem already moves toward agent-readable knowledge — Cursor rules, CLAUDE.md files, skills directories. But delivery is stuck in copy-paste: hunt for a community-maintained rules file, paste it into your config, repeat for every tool. No versioning, no update path, no staleness signal.
-
-## Skills: versioned knowledge in npm
-
-A skill is a short, versioned document that tells agents how to use a specific capability of your library — correct patterns, common mistakes, and when to apply them. Skills ship inside your npm package and travel with the tool via `npm update` — not the model's training cutoff, not community-maintained rules files, not prompt snippets in READMEs. Versioned knowledge the maintainer owns, updated when the package updates.
-
-Each skill declares its source docs. When those docs change, the CLI flags the skill for review. One source of truth, one derived artifact that stays in sync.
-
-The [Agent Skills spec](https://agentskills.io) is an open standard already adopted by VS Code, GitHub Copilot, OpenAI Codex, Cursor, Claude Code, Goose, Amp, and others.
-
-## For library consumers
-
-Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .cursorrules, etc.):
-
-```bash
-npx @tanstack/intent@latest install
-```
-
-No per-library setup. No hunting for rules files. Install the package, run `npx @tanstack/intent@latest install`, and the agent understands the tool. Update the package, and skills update too.
-
-List available skills from installed packages:
-
-```bash
-npx @tanstack/intent@latest list
-```
-
-## For library maintainers
-
-Generate skills for your library by telling your AI coding agent to run:
-
-```bash
-npx @tanstack/intent@latest scaffold
-```
-
-This walks the agent through domain discovery, skill tree generation, and skill creation — one step at a time with your review at each stage.
-
-Validate your skill files:
-
-```bash
-npx @tanstack/intent@latest validate
-```
-
-Check for skills that have fallen behind their sources:
-
-```bash
-npx @tanstack/intent@latest stale
-```
-
-Copy CI workflow templates into your repo so validation and staleness checks run on every push:
-
-```bash
-npx @tanstack/intent@latest setup-github-actions
-```
-
-## Keeping skills current
-
-The real risk with any derived artifact is staleness. `npx @tanstack/intent@latest stale` flags skills whose source docs have changed, and CI templates catch drift before it ships.
-
-The feedback loop runs both directions. `npx @tanstack/intent@latest feedback` lets users submit structured reports when a skill produces wrong output — which skill, which version, what broke. That context flows back to the maintainer, and the fix ships to everyone on the next `npm update`. Every support interaction produces an artifact that prevents the same class of problem for all future users — not just the one who reported it.
-
-## CLI Commands
-
-| Command | Description |
-| --- | --- |
-| `npx @tanstack/intent@latest install` | Set up skill-to-task mappings in agent config files |
-| `npx @tanstack/intent@latest list [--json]` | Discover intent-enabled packages |
-| `npx @tanstack/intent@latest meta` | List meta-skills for library maintainers |
-| `npx @tanstack/intent@latest scaffold` | Print the guided skill generation prompt |
-| `npx @tanstack/intent@latest validate [dir]` | Validate SKILL.md files |
-| `npx @tanstack/intent@latest setup-github-actions` | Copy CI templates into your repo |
-| `npx @tanstack/intent@latest stale [--json]` | Check skills for version drift |
-| `npx @tanstack/intent@latest feedback` | Submit skill feedback |
+---
+title: Overview
+id: overview
+---
+
+`@tanstack/intent` is a CLI for shipping and consuming Agent Skills as package artifacts.
+
+Skills are markdown documents that teach AI coding agents how to use your library correctly. Intent versions them with your releases, ships them inside npm packages, discovers them from `node_modules`, and helps agents load them automatically when working on matching tasks.
+
+## What Intent does
+
+Intent provides tooling for two workflows:
+
+**For consumers:**
+- Discover skills from installed dependencies
+- Generate task-to-skill mappings for your agent config
+- Keep skills synchronized with library versions
+
+**For maintainers (library teams):**
+- Scaffold skills through AI-assisted domain discovery
+- Validate SKILL.md format and packaging
+- Ship skills in the same release pipeline as code
+- Track staleness when source docs change
+
+## How it works
+
+### Discovery and installation
+
+```bash
+npx @tanstack/intent@latest list
+```
+
+Scans `node_modules` for intent-enabled packages and shows available skills with paths and descriptions.
+
+```bash
+npx @tanstack/intent@latest install
+```
+
+Prints instructions for your agent to create `intent-skills` mappings in your config files (CLAUDE.md, .cursorrules, etc.).
+
+### Scaffolding and validation
+
+```bash
+npx @tanstack/intent@latest scaffold
+```
+
+Guides your agent through domain discovery, tree generation, and skill authoring with interactive maintainer interviews.
+
+```bash
+npx @tanstack/intent@latest validate
+```
+
+Enforces SKILL.md format rules and packaging requirements before publish.
+
+### Staleness tracking
+
+```bash
+npx @tanstack/intent@latest stale
+```
+
+Detects when skills reference outdated source documentation or library versions.