docs: add Cursor rules, syntax cheat sheet, and AI agent context#1606
docs: add Cursor rules, syntax cheat sheet, and AI agent context#1606WolfieLeader wants to merge 10 commits intoarktypeio:mainfrom
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
1 participant
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