Repository navigation
docs: add Cursor rules, syntax cheat sheet, and AI agent context - #1606
Conversation
Single-page quick reference covering syntax kinds, keywords mental model, operators, objects, arrays, composition, morphs, type inference, error handling, and common gotchas. Placed after Intro in sidebar navigation. Addresses arktypeio#1562 per maintainer request for "markdown page with code and comments" covering common operators, keyword patterns, syntax kinds, and common issues new users run into.
Adds .cursor/rules/arktype.mdc with common ArkType patterns and pitfalls for AI coding assistants. Adapted from the battle-tested cheat sheet in arktypeio#1539 that was shared across teams adopting ArkType with Cursor. Addresses arktypeio#1539 follow-up item for improving LLM knowledge.
Provides ArkType-specific guidance for Claude Code, Codex, and other AI agents that read CLAUDE.md/AGENTS.md. Covers monorepo structure, code style, key patterns, syntax cheat sheet, and common gotchas. AGENTS.md is symlinked to CLAUDE.md so both agent conventions are served from a single source of truth.
Follow-up ideas for AI/LLM adoptionBeyond the Cursor rules and cheat sheet in this PR, a couple more ideas that could significantly lower the adoption barrier: 1. ArkType skill/plugin for AI agentsA dedicated ArkType skill (e.g. for Claude Code, Cursor, Copilot) that provides context-aware guidance when working with ArkType code — auto-activated when 2. Migration skills from other validation librariesPurpose-built migration guides (or interactive AI skills) for teams moving from:
Each would map the source library's API to ArkType equivalents — e.g. This would directly address the adoption friction mentioned in #1539 — teams are often not starting fresh but migrating existing codebases. Happy to contribute either of these as follow-up PRs if there's interest. |
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overall this is a solid contribution — the content is accurate and well-structured, and addressing #1539/#1562 in one PR makes sense. Three issues worth resolving before merge, one of which is a correctness problem.
- Remove auth-schema.ts gotcha (doesn't exist in arktype repo) - Set cursor rules globs to "**/*.ts" so rule auto-activates - Wrap default operator example in object context - Add sync comment noting overlapping content locations
Drop the Cursor rule and CLAUDE.md (Claude Code reads AGENTS.md) so agent context lives in one shared file. AGENTS.md now points at arktype.io/llms.txt, the full docs concatenated from ark/docs/content, with the cheat sheet as its abbreviated version. Also correct the Record gotcha: "Record<string, T>" parses fine with keyword arguments; only a JS variable inside the string fails. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
ssalbdivad
left a comment
ssalbdivad
left a comment
There was a problem hiding this comment.
Thanks! I trimmed this down to the cheat sheet plus a single AGENTS.md and pointed agents to arktype.io/llms.txt, which this cheat sheet makes a great abbreviated version of.
Bumps all publishable packages and documents the changes merged since 2.2.7: - add string.base58 (#1604, @WolfieLeader) - return empty props for object instead of throwing (#1682, fixes #1177, @SunilRathod27) - keep object values from meta in JSON Schema (#1677, @lprnmns) - report invalid generic definitions on TypeScript 7 (#1681) @ark/attest goes to 0.57.0 for its breaking changes: tsVersions and getPrimaryTsVersionUnderTest are removed and the position APIs are singular, alongside TypeScript 7.1+ support (changelog entry added with the attest changes). #1683 and #1606 only change the docs and agent context, so they have no changelog entries. llms.txt is regenerated to include #1606's cheat sheet. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Brings in #1606 (agent docs), #1680 (attest TypeScript 7 support) and the Infinity default on this branch. Conflicts: package.json keeps testBuild beside main's new testTsVersions, testTsCompat and testTypedLoose scripts; arktype's CHANGELOG puts the unreleased section above main's 2.2.8; attest's puts this branch's bench changes under Unreleased above main's released 0.57.0. Ported for TypeScript 7, which main now installs: - bundle.ts and testBuild.ts import `ts` from ts-morph, since TS 7 has no JS API (main's jsdocGen.ts made the same move). - bench/scenarios.ts annotates the cyclic arktype Tree, which TS 7's declaration emit can't serialize (TS5088). - cyclic.test.ts casts the generic-plus-variadic scope in "deferred checks resolving aliases" to never. Once TS 7's checker infers that scope, attest's per-node queries read later spreads and module members as `any` (9 assertions in spread, imports and submodule tests). A full tsc run infers them correctly; the test only asserts the runtime throw. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2 participants
Summary
Closes #1539, closes #1562
Adds three resources to improve AI/LLM integration with ArkType:
.cursor/rules/arktype.mdc— Cursor rules file with common ArkType patterns andpitfalls, adapted from the battle-tested cheat sheet in improve llm knowledge #1539. Activates when working
with ArkType code in Cursor.
ark/docs/content/docs/cheat-sheet.mdx— Syntax cheat sheet covering operators,keywords mental model, syntax kinds, and common gotchas. Per maintainer request in Create syntax cheat sheet #1562:
"markdown page with code and comments." Automatically included in
llms.txtvia theexisting
writeLlmsTxt()build step.CLAUDE.md+AGENTS.md(symlinked) — AI agent context file covering monorepostructure, code style, key patterns, and common gotchas. Read by Claude Code, Codex,
and other agent systems.
The cheat sheet is placed after Intro in sidebar navigation — the natural place a new user
looks after the getting-started tutorial.
Follow-up items from #1539 (llms.txt optimization, node_modules packaging) tracked separately.
Test plan
pnpm buildDocssucceeds — all MDX code blocks compile cleanlyllms.txtpnpm checkPrettierpassespnpm checkEslintpasses