docs: add AI agent style-rules guide

[tenphi]

What

Adds docs/ai-agents.md — a 206-line, rule-based brief on writing correct tasty styles, aimed at AI coding agents working in consumer projects (not at this repo).

It is deliberately not an API tour. It covers every rule enforced by @tenphi/eslint-plugin-tasty in the smallest form that still works as standalone, publishable markdown, so an agent briefed with it writes lint-clean styles on the first pass.

Also links it from the docs hub (By Task) and the README reference list, and adds the eslint plugin as a devDependency (separate commit).

Why

Agents reliably get tasty's value syntax wrong in predictable ways — raw hex instead of #tokens, calc() instead of (…), var(--x) instead of $x, CSS longhands instead of shorthands, state maps missing the '' default. The plugin catches all of it, but only after the code is written. This gives the same ruleset up front, in a form that fits in a context window.

Structure

Ordered so a reader can stop early and still be mostly correct. Rules are stated as ❌ → ✅ pairs and tables rather than prose, which is what agents follow most reliably.

§	Rules covered
0. Read the project config	valid-color-token, valid-preset, valid-recipe, valid-custom-unit, no-unknown-state-alias
1. Where styles go	no-styles-prop, no-runtime-styles-mutation
2. Property names	known-property, prefer-shorthand-property, prefer-longhand-property, prefer-hide
3. Values	valid-value, valid-custom-property, no-raw-color-values, prefer-custom-property-syntax, consistent-token-usage, prefer-auto-calc, valid-boolean-property, no-important, valid-directional-modifier, valid-radius-shape, prefer-directional-shorthand, valid-transition
4. State maps	valid-state-key, require-default-state, valid-default-state-order, no-nested-state-map, valid-styles-structure, no-own-at-root, valid-state-definition
5. Sub-elements	valid-sub-element, no-nested-selector
6. Special keys	valid-styles-structure (at-rule shapes, recipe)
7. tastyStatic()	static-no-dynamic-values, static-valid-selector
8. Checklist	one-line recap of all of the above

All 34 rules in the plugin's recommended + strict configs are covered.

Reviewer notes

• dock and single-corner radius modifiers are deliberately omitted. The plugin's constants.ts documents inset: '0 bottom dock' and corner names (top-left, …) as requiring tasty >= 2.10, but this repo is at 2.9.0 and src/styles/radius.ts only matches DIRECTIONS (top/right/bottom/left), with no dock handling anywhere in src/. Worth a look separately: prefer-directional-shorthand's autofix for a 4-value radius currently emits syntax 2.9.0 cannot parse.
• No changeset, per CONTRIBUTING — doc-only updates don't need one. Note that docs/ is in package.json files, so the guide reaches npm consumers on whatever release lands next.
• Prettier was not run on the markdown. The repo's format script targets src/**/*.{ts,tsx} only, and the existing docs use compact (unpadded) tables; formatting this file made it both inconsistent with its neighbours and larger.
• The dep bump is @tenphi/eslint-plugin-tasty@0.11.3 and is not wired into eslint.config.js — enabling it will start linting the style objects under src/, which belongs in its own PR. pnpm lint passes as-is.

🤖 Generated with Claude Code

[github-actions]

📦 Snapshot release

Published 0.0.0-snapshot.ad24ec8.

pnpm add @tenphi/tasty@0.0.0-snapshot.ad24ec8