Add overview docs page

README.md

@@ -36,7 +36,7 @@
 
 # TanStack Intent
 
-A toolkit for packaging agent-readable skills with your npm libraries. Auto-discovered, versioned with your code, and compatible across every major package manager.
+A CLI for library maintainers to generate, validate, and ship [Agent Skills](https://agentskills.io) alongside their npm packages. Auto-discovered, versioned with your code, and compatible with the open Agent Skills standard.
 
 ### <a href="https://tanstack.com/intent">Read the docs →</b></a>
 

docs/config.json

@@ -12,14 +12,6 @@
         {
           "label": "Overview",
           "to": "overview"
-        },
-        {
-          "label": "Installation",
-          "to": "installation"
-        },
-        {
-          "label": "Quick Start",
-          "to": "quick-start"
         }
       ]
     }

docs/overview.md

@@ -0,0 +1,84 @@
+---
+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 install
+```
+
+No per-library setup. No hunting for rules files. Install the package, run `npx @tanstack/intent install`, and the agent understands the tool. Update the package, and skills update too.
+
+List available skills from installed packages:
+
+```bash
+npx @tanstack/intent list
+```
+
+## For library maintainers
+
+Generate skills for your library by telling your AI coding agent to run:
+
+```bash
+npx @tanstack/intent 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 validate
+```
+
+Check for skills that have fallen behind their sources:
+
+```bash
+npx @tanstack/intent stale
+```
+
+Copy CI workflow templates into your repo so validation and staleness checks run on every push:
+
+```bash
+npx @tanstack/intent setup-github-actions
+```
+
+## Keeping skills current
+
+The real risk with any derived artifact is staleness. `npx @tanstack/intent 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 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 install` | Set up skill-to-task mappings in agent config files |
+| `npx @tanstack/intent list [--json]` | Discover intent-enabled packages |
+| `npx @tanstack/intent meta` | List meta-skills for library maintainers |
+| `npx @tanstack/intent scaffold` | Print the guided skill generation prompt |
+| `npx @tanstack/intent validate [dir]` | Validate SKILL.md files |
+| `npx @tanstack/intent setup-github-actions` | Copy CI templates into your repo |
+| `npx @tanstack/intent stale [--json]` | Check skills for version drift |
+| `npx @tanstack/intent feedback` | Submit skill feedback |

packages/intent/README.md

@@ -1,23 +1,23 @@
 # @tanstack/intent
 
-Ship compositional knowledge for AI coding agents alongside your npm packages.
+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 without flagging which applies. Once a breaking change ships, models contain _both_ versions forever with no way to disambiguate.
+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: the fourth artifact
+## Skills: versioned knowledge in npm
 
-You ship code, docs, and types. Skills are the fourth artifact — knowledge encoded for the thing writing most of your code.
-
-Skills are npm packages of knowledge — encoding how tools compose, which patterns fit which goals, and what to avoid. When a library ships skills using `@tanstack/intent`, that knowledge travels with the tool via `npm update` — not the model's training cutoff. Versioned knowledge the maintainer owns, updated when the package updates.
+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.
+
 ## Quick Start
 
 ### For library consumers
@@ -28,7 +28,7 @@ Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .
 npx @tanstack/intent install
 ```
 
-No per-library setup. No hunting for rules files. Install the package, run `intent install`, and the agent understands the tool. Update the package, and skills update too.
+No per-library setup. No hunting for rules files. Install the package, run `npx @tanstack/intent install`, and the agent understands the tool. Update the package, and skills update too.
 
 List available skills from installed packages:
 
@@ -44,7 +44,7 @@ Generate skills for your library by telling your AI coding agent to run:
 npx @tanstack/intent scaffold
 ```
 
-This prints a prompt that walks the agent through domain discovery, skill tree generation, and skill creation — one step at a time with your review at each stage.
+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:
 
@@ -61,27 +61,27 @@ npx @tanstack/intent stale
 Copy CI workflow templates into your repo so validation and staleness checks run on every push:
 
 ```bash
-npx @tanstack/intent setup
+npx @tanstack/intent setup-github-actions
 ```
 
 ## Keeping skills current
 
 The real risk with any derived artifact is staleness. `npx @tanstack/intent 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 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`.
+The feedback loop runs both directions. `npx @tanstack/intent 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 install`        | Set up skill-to-task mappings in agent config files |
-| `npx @tanstack/intent list [--json]`  | Discover intent-enabled packages                    |
-| `npx @tanstack/intent meta`           | List meta-skills for library maintainers            |
-| `npx @tanstack/intent scaffold`       | Print the guided skill generation prompt            |
-| `npx @tanstack/intent validate [dir]` | Validate SKILL.md files                             |
-| `npx @tanstack/intent setup`          | Copy CI templates, generate shim, create labels     |
-| `npx @tanstack/intent stale [--json]` | Check skills for version drift                      |
-| `npx @tanstack/intent feedback`       | Submit skill feedback                               |
+| Command                                     | Description                                         |
+| ------------------------------------------- | --------------------------------------------------- |
+| `npx @tanstack/intent install`              | Set up skill-to-task mappings in agent config files |
+| `npx @tanstack/intent list [--json]`        | Discover intent-enabled packages                    |
+| `npx @tanstack/intent meta`                 | List meta-skills for library maintainers            |
+| `npx @tanstack/intent scaffold`             | Print the guided skill generation prompt            |
+| `npx @tanstack/intent validate [dir]`       | Validate SKILL.md files                             |
+| `npx @tanstack/intent setup-github-actions` | Copy CI templates into your repo                    |
+| `npx @tanstack/intent stale [--json]`       | Check skills for version drift                      |
+| `npx @tanstack/intent feedback`             | Submit skill feedback                               |
 
 ## License