docs: simpler landing examples, Markdown docs for agents, and an ArkType skill

[ssalbdivad]

Makes arktype.io easier to take in at a glance and easier for coding agents to use, without changing its look.

Landing page

Before	After

Hovering either User in the new section shows the same type:

Mobile: before, after.

• 1:1 section under the hero: a TypeScript User type beside the ArkType definition, both twoslash-hoverable to the identical type.
• One idea per card snippet: errors (3 lines, with the ArkErrors: runtime line), .extends (3 lines), reduction (number > 0 and number >= 10 → number >= 10). The 2.0 post keeps the old snippets.
• Plainer card copy: "Unparalleled DX" → "Types You Already Know", "unlike anything you've ever seen" and similar dropped. Benchmark numbers kept.
• TypeScript 7 line in "Faster... everything": consumer@7.0.2 in testTsVersions passes locally and in CI.
• "Teach your agent ArkType" section with npx skills add arktypeio/arktype and links to /llms.txt and the new Agents page.

Docs for agents

• Every page as Markdown at /docs/<slug>.md, generated at build into public/docs (gitignored) by lib/writeMarkdown.ts, which replaces lib/writeLlmsTxt.ts.
• MDX to Markdown: twoslash cuts and @errors/^? directives stripped, SyntaxTabs become labeled blocks, callouts become blockquotes, ApiTable and keyword tables become Markdown, relative links become absolute.
• llms.txt is now that Markdown in sidebar order with an llms.txt-style header, instead of raw MDX in directory order (which opened with the 2.0 post).
• Page actions under each title: Copy Markdown, View Markdown, Open in Claude / ChatGPT / Cursor.
• Agents page (/docs/agents): the skill, Markdown docs, and a line for AGENTS.md.
• Keyword table data moved to lib/keywords.ts so the page and the Markdown share it.

Agent Skill

• ark/type/skills/arktype/SKILL.md: define/infer/validate, syntax table, composition, morphs, .narrow, scopes, undeclared keys, integrations, common mistakes. npx skills add finds it (checked against a local clone).
• Shipped in the npm package ("skills" added to files) for skills-npm. The Agents page says this applies to releases after 2.2.8.
• Every claim checked against the built package: all 6 code blocks type-check on TS 7.1-dev and 5.9 and run; every keyword in the tables parses. Three draft claims were wrong and are fixed (Uint8Array isn't a keyword, value-side "string?" is valid, react-hook-form uses arktypeResolver).
• AGENTS.md points at the skill and the .md pages.

Not done

• /llms.txt stays the full docs rather than becoming an index plus /llms-full.txt, since AGENTS.md and docs: split docs into per-project ArkType and Attest sections #1686 define it that way. Easy to split if you want the standard layout.
• No Fumadocs upgrade: 15.2.3 predates includeProcessedMarkdown and the page-actions components, and the site is a static export with no rewrites. The build-time generator and a small PageActions component do the same job.
• Hero unchanged: the demo video with its Playground toggle is already above the fold.
• No new problem-shaped pages ("validate env vars", "parse a request body"). They'd fit, but they're new content, not a pass over the existing site.
• Stale "Introducing ArkRegex" banner left alone.
• No test that type-checks SKILL.md: checked once. AGENTS.md now asks that its examples keep type-checking.

Verified

• pnpm buildDocs succeeds; 34 .md pages plus both llms.txt in out/.
• Playwright on the static export: screenshots above, hovers match, Copy Markdown fills the clipboard, View Markdown serves text/markdown.
• pnpm typecheckRepo, prettier and eslint clean.

🤖 Generated with Claude Code

[pullfrog]

✅ No new issues found.

Reviewed changes

• Build-time Markdown generator: ark/docs/lib/writeMarkdown.ts replaces writeLlmsTxt.ts, converting the 34 (arktype) and attest MDX pages into per-page Markdown at /docs/<slug>.md and rebuilding both llms.txt files in sidebar order. I regenerated it against the branch and the output byte-matches the committed ark/docs/public/llms.txt and ark/docs/public/docs/attest/llms.txt.
• Docs for agents: new agents.mdx page plus a PageActions client component (copy, view, and open in Claude / ChatGPT / Cursor), with the shared keyword data moved into ark/docs/lib/keywords.ts.
• Landing page: new 1:1 TypeScript/ArkType hover section, one-idea-per-card snippets (readableErrors, assignability, reduction), a "Teach your agent" section, and copy edits; the new twoslash snippets are registered in writeSnippetsEntrypoint.ts/contentsById.ts.
• Agent skill: ark/type/skills/arktype/SKILL.md, shipped via "skills" in the package files, with AGENTS.md pointers. I spot-checked the inference, syntax, morph, .narrow, scope, extra-key, and keyword examples and they parse and run as written.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}