@tanstack/intent 0.0.9 → 0.0.10

package/README.md

@@ -2,15 +2,21 @@
 
 Ship compositional knowledge for AI coding agents alongside your npm packages.
 
-Skills are npm packages of knowledge — encoding how tools work together, what patterns apply for which goals, and what to avoid. Skills travel with the tool via `npm update`, not the model's training cutoff.
+## The problem
 
-`@tanstack/intent` is the toolkit for generating, discovering, and maintaining skills for your library.
+Your docs are good. Your types are solid. Your agent still gets it wrong.
 
-## Install
+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.
 
-```bash
-pnpm add -D @tanstack/intent
-```
+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
+
+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.
+
+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.
 
 ## Quick Start
 
@@ -22,6 +28,8 @@ 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.
+
 List available skills from installed packages:
 
 ```bash
@@ -44,12 +52,24 @@ Validate your skill files:
 npx @tanstack/intent validate
 ```
 
-Copy CI workflow templates into your repo:
+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
 ```
 
+## Keeping skills current
+
+The real risk with any derived artifact is staleness. `intent stale` flags skills whose source docs have changed, and CI templates catch drift before it ships.
+
+The feedback loop runs both directions. `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`.
+
 ## CLI Commands
 
 | Command                 | Description                                         |
@@ -61,6 +81,7 @@ npx @tanstack/intent setup
 | `intent validate [dir]` | Validate SKILL.md files                             |
 | `intent setup`          | Copy CI templates, generate shim, create labels     |
 | `intent stale [--json]` | Check skills for version drift                      |
+| `intent feedback`       | Submit skill feedback                               |
 
 ## License
 

package/meta/feedback-collection/SKILL.md

@@ -145,6 +145,27 @@ Determine the target repo from the skill's package. The repo is typically
 derivable from the `repository` field in the package's `package.json`, or
 from the `sources` field in the SKILL.md frontmatter.
 
+### Privacy check
+
+Before submitting, determine whether the user's project is public or private.
+Check with `gh repo view --json visibility` or look for a `private` field in
+the project's `package.json`. If you can't determine visibility, assume private.
+
+**Private repos:** Feedback is submitted to a public issue tracker, so it must
+not contain project-specific details. Before submission:
+
+1. Strip any project-specific code, file paths, internal API names, service
+   URLs, or business logic from all fields
+2. Rewrite the "Task" field to describe the _type_ of task generically
+   (e.g. "set up authenticated data fetching" not "set up auth for our
+   internal billing API at api.acme.corp/billing")
+3. Rewrite "What Failed" and "Missing" entries to reference only the
+   skill's own APIs and patterns, not the user's code
+4. Show the sanitized feedback to the user and ask them to confirm it's
+   safe to submit before proceeding
+
+**Public repos:** No sanitization needed. Proceed directly to submission.
+
 ### If `gh` CLI is available
 
 Submit directly as a GitHub issue:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/intent",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Ship compositional knowledge for AI coding agents alongside your npm packages",
   "license": "MIT",
   "type": "module",