Basic Docs

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)

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`

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`

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)

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)

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)

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)