fix(intent): review stale skills against artifact coverage (#120)

* remove notify workflow template

* harden check-skills

* Add stale `signals`

* Parse `_artifacts`

* Add artifact consistency signals

* Add missing package coverage and artifact ignore support

* Fix workspace-root skill resolution and private package coverage noise

* Add workflow update advisory

* fix release script

* changeset

* ci: apply automated fixes

* update docs

* ci: apply automated fixes

* rm empty codex file

* fix up

* small fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: LadyBluenotes

.changeset/ten-shrimps-bow.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/intent': patch
+---
+
+Improve `intent stale` for monorepos by checking repo `_artifacts` coverage, flagging uncovered public workspace packages, and ignoring private workspaces.
+
+The generated skills workflow now opens one grouped review PR with maintainer prompts, includes a workflow version stamp, and `intent stale` warns when maintainers should rerun `intent setup`.

docs/cli/intent-scaffold.md

@@ -29,9 +29,9 @@ 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 edit-package-json`
-  - `npx @tanstack/intent@latest setup-github-actions`
+- Run setup commands as needed:
+  - `npx @tanstack/intent@latest edit-package-json`
+  - `npx @tanstack/intent@latest setup`
 
 ## Related
 

docs/cli/intent-setup.md

@@ -3,17 +3,18 @@ title: setup commands
 id: intent-setup
 ---
 
-Intent exposes setup as two separate commands.
-
-```bash
-npx @tanstack/intent@latest edit-package-json
-npx @tanstack/intent@latest setup-github-actions
-```
+Intent exposes publishing setup as two commands.
+
+```bash
+npx @tanstack/intent@latest edit-package-json
+npx @tanstack/intent@latest setup
+```
 
 ## Commands
 
-- `edit-package-json`: add or normalize `package.json` entries needed to publish skills
-- `setup-github-actions`: copy workflow templates to `.github/workflows`
+- `edit-package-json`: add or normalize `package.json` entries needed to publish skills
+- `setup`: copy workflow templates to `.github/workflows`
+- `setup-github-actions`: legacy alias for `setup`
 
 ## What each command changes
 
@@ -22,12 +23,11 @@ npx @tanstack/intent@latest setup-github-actions
   - Ensures `keywords` includes `tanstack-intent`
   - Ensures `files` includes required publish entries
   - Preserves existing indentation
-- `setup-github-actions`
-  - Copies templates from `@tanstack/intent/meta/templates/workflows` to `.github/workflows`
-  - Applies variable substitution (`PACKAGE_NAME`, `PACKAGE_LABEL`, `PAYLOAD_PACKAGE`, `REPO`, `DOCS_PATH`, `SRC_PATH`, `WATCH_PATHS`)
-  - Detects the workspace root in monorepos and writes repo-level workflows there
-  - Generates monorepo-aware watch paths for package `src/` and docs directories
-  - Skips files that already exist at destination
+- `setup`
+  - Copies templates from `@tanstack/intent/meta/templates/workflows` to `.github/workflows`
+  - Applies variable substitution (`PACKAGE_NAME`, `PACKAGE_LABEL`, `PAYLOAD_PACKAGE`, `REPO`, `DOCS_PATH`, `SRC_PATH`, `WATCH_PATHS`)
+  - Detects the workspace root in monorepos and writes repo-level workflows there
+  - Skips files that already exist at destination
 
 ## Required `files` entries
 
@@ -39,12 +39,12 @@ npx @tanstack/intent@latest setup-github-actions
 ## Common errors
 
 - Missing or invalid `package.json` when running `edit-package-json`
-- Missing template source when running `setup-github-actions`
+- Missing template source when running `setup`
 
 ## Notes
 
-- `setup-github-actions` skips existing files
-- In monorepos, run `setup-github-actions` from either the repo root or a package directory; Intent writes workflows to the workspace root
+- `setup` skips existing files
+- In monorepos, run `setup` from either the repo root or a package directory; Intent writes workflows to the workspace root
 
 ## Related
 

docs/cli/intent-stale.md

@@ -15,11 +15,28 @@ npx @tanstack/intent@latest stale [--json]
 
 ## Behavior
 
-- Checks the current package by default, or all skill-bearing packages in the current workspace when run from a monorepo root
-- When `dir` is provided, scopes the check to the targeted package or skills directory
-- 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.`
+- Checks the current package by default
+- From a monorepo root, checks workspace packages that ship skills and also reports public workspace packages with no skill or artifact coverage
+- When `dir` is provided, scopes the check to the targeted package or skills directory
+- Computes one staleness report per package
+- Reads repo-root `_artifacts/*domain_map.yaml` and `_artifacts/*skill_tree.yaml` when present
+- Flags public workspace packages that are not represented by generated skills or artifact coverage
+- Skips workspace packages with `"private": true`
+- Prints text output by default or JSON with `--json`
+- Prints a non-failing workflow update reminder when `.github/workflows/check-skills.yml` is missing the current `intent-workflow-version` stamp
+- If no packages are found, prints `No intent-enabled packages found.`
+
+Artifact coverage ignores can be recorded in `_artifacts/*skill_tree.yaml` or `_artifacts/*domain_map.yaml`:
+
+```yaml
+coverage:
+  ignored_packages:
+    - '@tanstack/internal-tooling'
+    - name: packages/devtools-fixture
+      reason: test fixture only
+```
+
+Ignored packages are excluded from missing coverage signals. Private workspace packages are excluded automatically.
 
 ## JSON report schema
 
@@ -32,41 +49,54 @@ npx @tanstack/intent@latest stale [--json]
     "currentVersion": "string | null",
     "skillVersion": "string | null",
     "versionDrift": "major | minor | patch | null",
-    "skills": [
-      {
-        "name": "string",
-        "reasons": ["string"],
-        "needsReview": true
-      }
-    ]
-  }
-]
+    "skills": [
+      {
+        "name": "string",
+        "reasons": ["string"],
+        "needsReview": true
+      }
+    ],
+    "signals": [
+      {
+        "type": "missing-package-coverage",
+        "library": "string",
+        "subject": "string",
+        "reasons": ["string"],
+        "needsReview": true,
+        "packageName": "string",
+        "packageRoot": "string"
+      }
+    ]
+  }
+]
 ```
 
 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
+- `versionDrift`: `major | minor | patch | null`
+- `skills`: array of per-skill checks
+- `signals`: array of artifact and workspace coverage 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
+Reason generation:
+
+- `version drift (<skillVersion> → <currentVersion>)`
+- `new source (<path>)` when a declared source has no stored sync SHA
+- artifact parse warnings, unresolved artifact skill paths, source drift, artifact library version drift, and missing workspace package coverage
 
 ## 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>, ...`)
+- 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 or review signal (`⚠ <name>: <reason1>, <reason2>, ...`)
 
 ## Common errors
 

docs/config.json

@@ -55,7 +55,7 @@
           "to": "cli/intent-validate"
         },
         {
-          "label": "intent setup-github-actions",
+          "label": "intent setup",
           "to": "cli/intent-setup"
         },
         {

docs/getting-started/quick-start-maintainers.md

@@ -101,8 +101,8 @@ Run these commands to prepare your package for skill publishing:
 # 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
+# Copy CI workflow templates (validate + stale checks)
+npx @tanstack/intent@latest setup
 ```
 
 **What these do:**
@@ -112,7 +112,7 @@ npx @tanstack/intent@latest setup-github-actions
   - `files` array entries for `skills/`
   - 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
+- `setup` copies workflow templates to `.github/workflows/` for automated validation and staleness checking
 
 ### 5. Ship skills with your package
 
@@ -135,24 +135,19 @@ Consumers who install your library automatically get the skills. They discover l
 
 ### 6. Set up CI workflows
 
-After running `setup-github-actions`, you'll have three workflows in `.github/workflows/`:
+After running `setup`, you'll have two 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
+**check-skills.yml** (runs on release or manual trigger)
+- Automatically detects stale skills and coverage gaps after you publish a new release
+- Opens one grouped review PR with an agent-friendly prompt
+- Requires you to copy the prompt into Claude Code, Cursor, or your agent to update skills
+
+### 7. Update stale skills
 
 When you publish a new release, `check-skills.yml` automatically opens a PR flagging skills that need review.
 
@@ -162,11 +157,25 @@ Manually check which skills need updates with:
 npx @tanstack/intent@latest stale
 ```
 
-When run from a package, this checks that package's shipped skills. When run from a monorepo root, it checks the workspace packages that ship skills.
-
-This detects:
-- **Version drift** — skill targets an older library version than currently installed
-- **New sources** — sources declared in frontmatter that weren't tracked before
+When run from a package, this checks that package's shipped skills. When run from a monorepo root, it checks workspace packages with skills and flags public workspace packages missing skill or `_artifacts` coverage.
+
+This detects:
+- **Version drift** — skill targets an older library version than currently installed
+- **New sources** — sources declared in frontmatter that weren't tracked before
+- **Artifact drift** — `_artifacts` entries that no longer match generated skills
+- **Missing package coverage** — public workspace packages not represented by generated skills or artifact coverage
+
+If a public workspace package is intentionally out of scope for skills, record that decision in repo-root `_artifacts`:
+
+```yaml
+coverage:
+  ignored_packages:
+    - '@tanstack/internal-tooling'
+    - name: packages/devtools-fixture
+      reason: test fixture only
+```
+
+Private workspace packages are skipped automatically.
 
 **To update stale skills:**
 1. Review the PR opened by `check-skills.yml`

docs/registry.md

@@ -59,10 +59,10 @@ npx @tanstack/intent@latest stale
 Flags skills whose source docs have changed since the skill was last updated.
 
 ```bash
-npx @tanstack/intent@latest setup-github-actions
+npx @tanstack/intent@latest setup
 ```
 
-Copies CI workflow templates into your repo so validation and staleness checks run on every push. Catch drift before it ships.
+Copies CI workflow templates into your repo so validation and staleness checks run in GitHub Actions. Catch drift before it ships.
 
 ## Requesting a library
 

packages/intent/README.md

@@ -90,10 +90,10 @@ npx @tanstack/intent@latest stale
 
 From a monorepo root, `intent stale` checks every workspace package that ships skills. To scope it to one package, pass a directory like `intent stale packages/router`.
 
-Copy CI workflow templates into your repo so validation and staleness checks run on every push:
+Copy CI workflow templates into your repo so validation and staleness checks can run in GitHub Actions:
 
 ```bash
-npx @tanstack/intent@latest setup-github-actions
+npx @tanstack/intent@latest setup
 ```
 
 ## Compatibility
@@ -108,14 +108,14 @@ npx @tanstack/intent@latest setup-github-actions
 
 ## Monorepos
 
-- Run `npx @tanstack/intent@latest setup-github-actions` from either the repo root or a package directory. Intent detects the workspace root and writes workflows to the repo-level `.github/workflows/` directory.
-- Generated workflows are monorepo-aware: validation loops over workspace packages with skills, staleness checks run from the workspace root, and notify workflows watch package `src/` and docs paths.
+- Run `npx @tanstack/intent@latest setup` from either the repo root or a package directory. Intent detects the workspace root and writes workflows to the repo-level `.github/workflows/` directory.
+- Generated workflows are monorepo-aware: validation loops over workspace packages with skills, and staleness checks run from the workspace root.
 - Run `npx @tanstack/intent@latest validate packages/<pkg>/skills` from the repo root to validate one package without root-level packaging warnings.
-- Run `npx @tanstack/intent@latest stale` from the repo root to check all workspace packages with skills, or `intent stale packages/<pkg>` to check one package.
+- Run `npx @tanstack/intent@latest stale` from the repo root to check workspace packages with skills and public workspace packages missing skill or `_artifacts` coverage, or `intent stale packages/<pkg>` to check one package.
 
 ## 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 real risk with any derived artifact is staleness. `npx @tanstack/intent@latest stale` flags skills whose source docs have changed, generated skills that drift from `_artifacts`, and public workspace packages missing coverage. 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 package 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.
 
@@ -129,7 +129,7 @@ The feedback loop runs both directions. `npx @tanstack/intent@latest feedback` l
 | `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 setup`                | Copy CI templates into your repo                    |
 | `npx @tanstack/intent@latest stale [dir] [--json]` | Check skills for version drift                      |
 | `npx @tanstack/intent@latest feedback`             | Submit skill feedback                               |