[PF-1997] Add .picasso/ v2 rules and absolute-URL llms.txt index

[dulishkovych]

PF-1997

Targets the integration branch feature/picasso-agent-experience, not master. The whole Agent Experience effort lands there and is promoted to master only once a phase is complete, so production GitHub Pages / llms.txt stay untouched until then. (release.yml deploys production only on push to master; PRs here get an ephemeral prs/<n>/ preview.)

Description

This is the Foundation PR (1 of ~6) for making Picasso usable by AI coding agents (Cursor, Claude Code, …). The goal of the effort: agents reliably generate correct, on-brand Picasso instead of guessing props, reaching for raw HTML, or importing from the wrong package.

We already generate LLM docs (llms.txt + per-component pages) and host them on gh-pages — but nothing tells an agent they exist, and v1 "adoption" meant copy-pasting the whole ~1 MB doc tree into a consumer repo. This PR fixes discovery and reachability:

• .picasso/rules.md — a single canonical, always-on ruleset for agents: how to look up docs (fetch on demand), package imports, and mandatory usage rules. Replaces the v1 per-tool copies that had already drifted.
• README pointers — root README.md (GitHub landing) and packages/picasso/README.md (npm + what the generator copies into llm-docs/initial-setup.md) now tell an agent to wire CLAUDE.md / .cursor rules to the hosted docs. The package README carries the copy-paste setup snippet; the others point to it (single source, no drift).
• Absolute-URL llms.txt — the generator (bin/doc-gen/markdown-renderer.mjs) now emits absolute links via LLM_DOCS_BASE_URL (default the production gh-pages URL, env-overridable for previews), so the index resolves from anywhere and agents fetch the one component doc they need without vendoring the tree.

What this PR deliberately does NOT do (tracked as later PRs on the same branch): rebuild the generator to trim Storybook-demo bloat + add an authored per-component layer (usage + composition recipes), top-20 scoping, llms-full.txt, packaging the rules into the npm package, and Skills.

How to test

• Preview: https://toptal.github.io/picasso/prs/5018/ — and the preview index at …/prs/5018/llm-docs/llms.txt shows absolute URLs, while production …/picasso/llm-docs/llms.txt is unchanged (proves nothing leaks to prod).
• pnpm generate:llm-docs → confirm llm-docs/llms.txt links are absolute (https://toptal.github.io/picasso/llm-docs/components/<name>.md).
• Override the base: LLM_DOCS_BASE_URL=https://example.test/docs node bin/generate-docs.mjs → links use that base (trailing slash normalized).
• Read .picasso/rules.md and the new "Using Picasso with AI coding agents" section in packages/picasso/README.md.

Screenshots

N/A — no visual/UI changes (docs-generation tooling + agent rules only).

Development checks

• Add changeset according to guidelines (if needed) — not needed: no published-package or consumer-facing behavior change (bin/ tooling + repo-level .picasso/ + READMEs)
• Double check if picasso-tailwind-merge requires major update (check its README.md) — N/A, untouched
• Read CONTRIBUTING.md and Component API principles
• Make sure that additions and changes on the design follow Toptal's BASE design, and it's been already discussed with designers at #-base-core — N/A, no design changes
• Annotate all props in component with documentation — N/A, no component changes
• Create examples for component — N/A, no component changes
• Ensure that deployed demo has expected results and good examples — verified llms.txt output + preview
• Ensure the changed/created components have not caused accessibility issues. How to use accessibility plugin in storybook. — N/A, no component changes
• Self reviewed
• Covered with tests (visual tests included) — N/A, docs-generation tooling + markdown; validated by running the generator + eslint/prettier + CI preview

Breaking change

• codemod is created and showcased in the changeset
• test alpha package of Picasso in StaffPortal

All development checks should be done and set checked to pass the
GitHub Bot: TODOLess action

Alpha packages

Manually trigger the publish.yml workflow to publish alpha packages. Specify pull request number as a parameter (only digits, e.g. 123).

PR Review Guidelines

When to approve? ✅

You are OK with merging this PR and

1. You have no extra requests.
2. You have optional requests.
   1. Add nit: to your comment. (ex. nit: I'd rename this variable from makeCircle to getCircle)

When to request changes? ❌

You are not OK with merging this PR because

1. Something is broken after the changes.
2. Acceptance criteria is not reached.
3. Code is dirty.

When to comment (neither ✅ nor ❌)

You want your comments to be addressed before merging this PR in cases like:

1. There are leftovers like unnecessary logs, comments, etc.
2. You have an opinionated comment regarding the code that requires a discussion.
3. You have questions.

How to handle the comments?

1. An owner of a comment is the only one who can resolve it.
2. An owner of a comment must resolve it when it's addressed.
3. A PR owner must reply with ✅ when a comment is addressed.

[changeset-bot]

⚠️ No Changeset found

Latest commit: ac79c39

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

	Fails
🚫	Please assign someone to this PR before merging.

Generated by 🚫 dangerJS against ac79c39

[github-actions]

📖 Storybook Preview

🚀 Your Storybook preview is ready: View Storybook

📍 Preview URL: https://toptal.github.io/picasso/prs/5018/

This preview is updated automatically when you push changes to this PR.