Skip to content

Commit ff603db

Browse files
LadyBluenotesLadyBluenotes
committed
Merge branch 'docs' into docs-stuff
2 parents 63268f8 + 3d7fdc7 commit ff603db

File tree

14 files changed

+1511
-842
lines changed

14 files changed

+1511
-842
lines changed

‎docs/cli/intent-install.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: intent install
3+
id: intent-install
4+
---
5+
6+
`intent install` prints instructions for setting up an `intent-skills` mapping block in your project guidance file.
7+
8+
```bash
9+
npx @tanstack/intent@latest install
10+
```
11+
12+
The command prints text only. It does not edit files.
13+
14+
## Output
15+
16+
The printed instructions include this tagged block template:
17+
18+
```yaml
19+
<!-- intent-skills:start -->
20+
# Skill mappings — when working in these areas, load the linked skill file into context.
21+
skills:
22+
- task: "describe the task or code area here"
23+
load: "node_modules/package-name/skills/skill-name/SKILL.md"
24+
<!-- intent-skills:end -->
25+
```
26+
27+
They also ask you to:
28+
29+
1. Check for an existing block first
30+
2. Run `intent list` to discover installed skills
31+
3. Add task-to-skill mappings
32+
4. Preserve all content outside the tagged block
33+
34+
## Related
35+
36+
- [intent list](./intent-list)
37+
- [Setting Up Agent Config](../guides/consumers/agent-config-setup)

‎docs/cli/intent-list.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: intent list
3+
id: intent-list
4+
---
5+
6+
`intent list` discovers skill-enabled packages and prints available skills.
7+
8+
```bash
9+
npx @tanstack/intent@latest list [--json]
10+
```
11+
12+
## Options
13+
14+
- `--json`: print JSON instead of text output
15+
16+
## What you get
17+
18+
- Scans installed dependencies for intent-enabled packages and skills
19+
- Includes warnings from discovery
20+
- If no packages are discovered, prints `No intent-enabled packages found.`
21+
- Summary line with package count, skill count, and detected package manager
22+
- Package table columns: `PACKAGE`, `VERSION`, `SKILLS`, `REQUIRES`
23+
- Skill tree grouped by package
24+
- Optional warnings section (`⚠ ...` per warning)
25+
26+
`REQUIRES` uses `intent.requires` values joined by `, `; empty values render as `–`.
27+
28+
## JSON output
29+
30+
`--json` prints the `ScanResult` object:
31+
32+
```json
33+
{
34+
"packageManager": "npm | pnpm | yarn | bun | unknown",
35+
"packages": [
36+
{
37+
"name": "string",
38+
"version": "string",
39+
"intent": {
40+
"version": 1,
41+
"repo": "string",
42+
"docs": "string",
43+
"requires": ["string"]
44+
},
45+
"skills": [
46+
{
47+
"name": "string",
48+
"path": "string",
49+
"description": "string",
50+
"type": "string (optional)",
51+
"framework": "string (optional)"
52+
}
53+
]
54+
}
55+
],
56+
"warnings": ["string"]
57+
}
58+
```
59+
60+
`packages` are ordered using `intent.requires` when possible.
61+
62+
## Common errors
63+
64+
- Scanner failures are printed as errors
65+
- Unsupported environments:
66+
- Yarn PnP without `node_modules`
67+
- Deno projects without `node_modules`

‎docs/cli/intent-meta.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: intent meta
3+
id: intent-meta
4+
---
5+
6+
`intent meta` lists bundled meta-skills or prints one meta-skill file.
7+
8+
```bash
9+
npx @tanstack/intent@latest meta
10+
npx @tanstack/intent@latest meta <name>
11+
```
12+
13+
## Arguments
14+
15+
- `<name>` is a meta-skill directory under `node_modules/@tanstack/intent/meta/`
16+
- Rejected values: any name containing `..`, `/`, or `\\`
17+
18+
## Output
19+
20+
- Without `<name>`:
21+
- one line per meta-skill
22+
- `name` + description from frontmatter
23+
- description is normalized and truncated to 60 characters
24+
- With `<name>`:
25+
- raw markdown from `meta/<name>/SKILL.md`
26+
27+
## Common errors
28+
29+
- Meta directory not found
30+
- Invalid `<name>` format
31+
- Unknown `<name>` (message suggests running `npx @tanstack/intent meta`)
32+
- Read failure for target `SKILL.md`

‎docs/cli/intent-scaffold.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: intent scaffold
3+
id: intent-scaffold
4+
---
5+
6+
`intent scaffold` prints a phased scaffold prompt for generating skills.
7+
8+
```bash
9+
npx @tanstack/intent@latest scaffold
10+
```
11+
12+
## Behavior
13+
14+
- Prints prompt text to stdout
15+
- Does not create files
16+
17+
## Output
18+
19+
The printed prompt defines three ordered phases:
20+
21+
1. `domain-discovery`
22+
2. `tree-generator`
23+
3. `generate-skill`
24+
25+
Each phase includes a stop gate before continuing.
26+
27+
The prompt also includes a post-generation checklist:
28+
29+
- Run `npx @tanstack/intent@latest validate` and fix issues
30+
- Commit generated `skills/` and `skills/_artifacts/`
31+
- Ensure `@tanstack/intent` is in `devDependencies`
32+
- Run setup commands as needed:
33+
- `npx @tanstack/intent@latest add-library-bin`
34+
- `npx @tanstack/intent@latest edit-package-json`
35+
- `npx @tanstack/intent@latest setup-github-actions`
36+
37+
## Related
38+
39+
- [intent validate](./intent-validate)
40+
- [setup commands](./intent-setup)

‎docs/cli/intent-setup.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: setup commands
3+
id: intent-setup
4+
---
5+
6+
Intent exposes setup as three separate commands.
7+
8+
```bash
9+
npx @tanstack/intent@latest add-library-bin
10+
npx @tanstack/intent@latest edit-package-json
11+
npx @tanstack/intent@latest setup-github-actions
12+
```
13+
14+
## Commands
15+
16+
- `add-library-bin`: create a package-local `intent` shim in `bin/`
17+
- `edit-package-json`: add or normalize `package.json` entries needed to publish skills
18+
- `setup-github-actions`: copy workflow templates to `.github/workflows`
19+
20+
## What each command changes
21+
22+
- `add-library-bin`
23+
- Creates `bin/intent.js` when `package.json.type` is `module`, otherwise `bin/intent.mjs`
24+
- If either shim already exists, command skips creation
25+
- Shim imports `@tanstack/intent/intent-library`
26+
- `edit-package-json`
27+
- Requires a valid `package.json` in current directory
28+
- Ensures `bin.intent` points to `./bin/intent.<ext>`
29+
- Ensures `files` includes required publish entries
30+
- Preserves existing indentation and existing `bin` entries
31+
- Converts string shorthand `bin` to object when needed
32+
- `setup-github-actions`
33+
- Copies templates from `@tanstack/intent/meta/templates/workflows` to `.github/workflows`
34+
- Applies variable substitution for `PACKAGE_NAME`, `REPO`, `DOCS_PATH`, `SRC_PATH`
35+
- Skips files that already exist at destination
36+
37+
## Required `files` entries
38+
39+
`edit-package-json` enforces different `files` sets based on package location:
40+
41+
- Monorepo package: `skills`, `bin`
42+
- Non-monorepo package: `skills`, `bin`, `!skills/_artifacts`
43+
44+
## Common errors
45+
46+
- Missing or invalid `package.json` when running `edit-package-json`
47+
- Missing template source when running `setup-github-actions`
48+
49+
## Notes
50+
51+
- `add-library-bin` and `setup-github-actions` skip existing files
52+
53+
## Related
54+
55+
- [intent validate](./intent-validate)
56+
- [intent scaffold](./intent-scaffold)

‎docs/cli/intent-stale.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: intent stale
3+
id: intent-stale
4+
---
5+
6+
`intent stale` reports whether shipped skills may need review.
7+
8+
```bash
9+
npx @tanstack/intent@latest stale [--json]
10+
```
11+
12+
## Options
13+
14+
- `--json`: print JSON array of staleness reports
15+
16+
## Behavior
17+
18+
- Scans installed intent-enabled packages
19+
- Computes one staleness report per package
20+
- Prints text output by default or JSON with `--json`
21+
- If no packages are found, prints `No intent-enabled packages found.`
22+
23+
## JSON report schema
24+
25+
`--json` outputs an array of reports:
26+
27+
```json
28+
[
29+
{
30+
"library": "string",
31+
"currentVersion": "string | null",
32+
"skillVersion": "string | null",
33+
"versionDrift": "major | minor | patch | null",
34+
"skills": [
35+
{
36+
"name": "string",
37+
"reasons": ["string"],
38+
"needsReview": true
39+
}
40+
]
41+
}
42+
]
43+
```
44+
45+
Report fields:
46+
47+
- `library`: package name
48+
- `currentVersion`: latest version from npm registry (or `null` if unavailable)
49+
- `skillVersion`: `library_version` from skills (or `null`)
50+
- `versionDrift`: `major | minor | patch | null`
51+
- `skills`: array of per-skill checks
52+
53+
Skill fields:
54+
55+
- `name`
56+
- `reasons`: one or more staleness reasons
57+
- `needsReview`: boolean (`true` when reasons exist)
58+
59+
Reason generation:
60+
61+
- `version drift (<skillVersion> → <currentVersion>)`
62+
- `new source (<path>)` when a declared source has no stored sync SHA
63+
64+
## Text output
65+
66+
- Report header format: `<library> (<skillVersion> → <currentVersion>) [<versionDrift> drift]`
67+
- When no skill reasons exist: `All skills up-to-date`
68+
- Otherwise: one warning line per stale skill (`⚠ <name>: <reason1>, <reason2>, ...`)
69+
70+
## Common errors
71+
72+
- Package scan failure: prints a scanner error
73+
- Registry fetch failures do not crash command; `currentVersion` may be `null`
74+
75+
## Notes
76+
77+
- Source staleness checking is conservative: it flags missing source SHAs in sync-state, not remote content differences.
78+
79+
## Related
80+
81+
- [intent list](./intent-list)

‎docs/cli/intent-validate.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: intent validate
3+
id: intent-validate
4+
---
5+
6+
`intent validate` checks `SKILL.md` files and artifacts for structural problems.
7+
8+
```bash
9+
npx @tanstack/intent@latest validate [<dir>]
10+
```
11+
12+
## Arguments
13+
14+
- `<dir>`: directory containing skills; default is `skills`
15+
- Relative paths are resolved from the current working directory
16+
17+
## Validation checks
18+
19+
For each discovered `SKILL.md`:
20+
21+
- Frontmatter delimiter and structure are valid
22+
- YAML frontmatter parses successfully
23+
- Required fields exist: `name`, `description`
24+
- `name` matches skill directory path under the target root
25+
- `description` length is at most 1024 characters
26+
- `type: framework` requires `requires` to be an array
27+
- Total file length is at most 500 lines
28+
29+
If `<dir>/_artifacts` exists, it also validates artifacts:
30+
31+
- Required files: `domain_map.yaml`, `skill_spec.md`, `skill_tree.yaml`
32+
- Required files must be non-empty
33+
- `.yaml` artifacts must parse successfully
34+
35+
## Packaging warnings
36+
37+
Packaging warnings are always computed from `package.json` in the current working directory:
38+
39+
- `@tanstack/intent` missing from `devDependencies`
40+
- Missing `bin.intent` entry
41+
- Missing shim (`bin/intent.js` or `bin/intent.mjs`)
42+
- Missing `files` entries when `files` array exists:
43+
- `skills`
44+
- `bin`
45+
- `!skills/_artifacts`
46+
47+
Warnings are informational; they are printed on both pass and fail paths.
48+
49+
## Common errors
50+
51+
- Missing target directory: `Skills directory not found: <abs-path>`
52+
- No skill files discovered: `No SKILL.md files found`
53+
- Validation failures: aggregated file-specific errors and count
54+
55+
## Related
56+
57+
- [intent scaffold](./intent-scaffold)
58+
- [setup commands](./intent-setup)

0 commit comments

Comments
 (0)