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

.picasso/rules.md

@@ -0,0 +1,82 @@
+# Picasso UI Kit — agent rules (v2)
+
+Rules for AI agents writing application code that **consumes** Toptal's Picasso
+design system (`@toptal/picasso*`). This file stays small on purpose: it carries
+the stable, high-value rules inline and points to the hosted, always-current
+docs for everything else.
+
+## Documentation lookup (fetch on demand)
+
+Component docs are **hosted** — do not vendor them into the repo. Before using an
+unfamiliar Picasso component, fetch the docs on demand:
+
+1. Fetch the index: <https://toptal.github.io/picasso/llm-docs/llms.txt> — every
+   component and tutorial is linked as an absolute URL with a one-line summary.
+2. From the index, fetch the specific component page you need, e.g.
+   <https://toptal.github.io/picasso/llm-docs/components/button.md> (props,
+   variants, examples).
+3. For layout, forms, spacing, or SSR questions, fetch the relevant guide from
+   the index's **Tutorials** section.
+
+Fetch only what the task needs. If your runtime cannot reach the network, fetch
+the index plus the specific component pages once and cache them for the session —
+still preferred over committing the whole tree.
+
+## Package imports
+
+| Package                          | Import for                          | Example                                                              |
+| -------------------------------- | ----------------------------------- | -------------------------------------------------------------------- |
+| `@toptal/picasso`                | UI components and icons             | `import { Button, Container, Modal, More16 } from '@toptal/picasso'` |
+| `@toptal/picasso/utils`          | utilities, hooks, spacing constants | `import { useNotifications } from '@toptal/picasso/utils'`           |
+| `@toptal/picasso-forms`          | Final Form-based form components    | `import { Form, Input, Select } from '@toptal/picasso-forms'`        |
+| `@toptal/picasso-provider`       | root provider only                  | `import Picasso from '@toptal/picasso-provider'`                     |
+| `@toptal/picasso-tailwind-merge` | merging Tailwind classes            | `import { twMerge } from '@toptal/picasso-tailwind-merge'`           |
+
+Import from package barrels, never deep paths.
+
+## Mandatory rules
+
+1. **Use Picasso components, not raw HTML, for UI** — no raw `<button>`,
+   `<input>`, `<select>`, `<table>`, `<h1>`–`<h6>`, or `<p>` for styled UI. Use
+   the Picasso equivalent (`Button`, `Input`, `Select`, `Table`, `Typography`, …).
+2. **All text goes through `Typography`.**
+3. **Lay out with `Container` / `Grid`** (12-column) and the `Page` parts — not
+   ad-hoc margins.
+4. **Merge classes with `twMerge`** from `@toptal/picasso-tailwind-merge`, and put
+   the consumer `className` **last** so it wins on conflicts.
+5. **Style hooks are `className` and `style` only** — never `classes`, `sx`,
+   `css`, or slot-level class props.
+6. **Use Picasso / BASE design tokens** (colors, spacing, typography) — no raw
+   hex/rgb and no arbitrary px. Fetch the hosted tokens docs for the authoritative
+   token names and the spacing scale.
+7. **Icons are named `{Name}{Size}`** (e.g. `More16`, `Search16`, `Settings24`),
+   imported from `@toptal/picasso`.
+
+## Component reference
+
+Common building blocks, for orientation only — **the hosted index is
+authoritative**; fetch it (see _Documentation lookup_) for the full, current list
+and for any component's API.
+
+- **Layout:** `Container`, `Grid` / `Grid.Item`, `Page` (`.TopBar`, `.Content`,
+  `.Sidebar`, `.Footer`), `Paper`, `Section`
+- **Typography:** `Typography`
+- **Actions:** `Button`, `Dropdown`, `Menu`
+- **Forms:** `Form`, `Input`, `Select`, `Checkbox`, `Radio`, `Switch`,
+  `Autocomplete`, `DatePicker`, `NumberInput` (form-bound variants from
+  `@toptal/picasso-forms`)
+- **Data display:** `Table`, `Accordion`, `List`, `Tag`, `Badge`, `OverviewBlock`
+- **Feedback:** `Alert`, `Notification`, `Loader`, `SkeletonLoader`, `ProgressBar`
+- **Navigation:** `Tabs`, `Breadcrumbs`, `Pagination`, `Stepper`
+- **Overlays:** `Modal`, `Drawer`, `Tooltip`
+
+---
+
+Version-agnostic: the hosted docs always reflect the latest published Picasso.
+Fetch them at edit/build time for current APIs.
+
+**Changed from v1:** docs are now fetched on demand from the hosted index rather
+than vendored as a ~1 MB tree into each consumer repo; `llms.txt` links are
+absolute; v1's stale `patterns/` / `tokens/` / "96 docs" pointers are dropped in
+favour of the authoritative hosted index; these rules now live canonically here
+in the Picasso repo instead of as drifting per-tool copies.

README.md

@@ -15,6 +15,13 @@ This repository is the home for all of Toptal's reusable UI, split up into disti
 - [@toptal/picasso-codemod](./packages/picasso-codemod/README.md) - scripts that help developers migrate to the latest version
 - [@toptal/picasso-shared](./packages/picasso-shared/README.md) - shared utilities between the packages
 
+## Using Picasso with AI coding agents
+
+Picasso ships LLM-optimized docs so AI tools (Cursor, Claude Code, …) generate correct Picasso code. Point your agent at the hosted index and have it fetch component docs on demand:
+
+- Index of all components: <https://toptal.github.io/picasso/llm-docs/llms.txt>
+- Agent rules + the one-time setup snippet: [`.picasso/rules.md`](./.picasso/rules.md) and the [`@toptal/picasso` README](./packages/picasso/README.md#using-picasso-with-ai-coding-agents)
+
 ## Contributing
 
 Please read our documentation [here](./CONTRIBUTING.md)

bin/doc-gen/markdown-renderer.mjs

@@ -5,6 +5,18 @@
 
 /* eslint-disable import/no-extraneous-dependencies */
 
+const DEFAULT_LLM_DOCS_BASE_URL = 'https://toptal.github.io/picasso/llm-docs/'
+
+/**
+ * Base URL prepended to the links in llms.txt so an AI agent can resolve every
+ * component/tutorial doc on demand from the hosted docs — without vendoring the
+ * full tree into the consumer repo. Override via the LLM_DOCS_BASE_URL env var
+ * (e.g. to point a PR-preview deployment at its own path). Always ends in "/".
+ */
+// eslint-disable-next-line no-process-env
+const rawLlmDocsBaseUrl = process.env.LLM_DOCS_BASE_URL || DEFAULT_LLM_DOCS_BASE_URL
+const LLM_DOCS_BASE_URL = rawLlmDocsBaseUrl.replace(/\/?$/, '/')
+
 const escapePipe = (str) => str.replace(/\\/g, '\\\\').replace(/\|/g, '\\|')
 
 const renderPropsTable = (props) => {
@@ -336,12 +348,13 @@ const renderLlmsHeader = () => [
   '',
   '> Picasso is Toptal\'s React component library implementing the BASE design system.',
   '> This documentation is optimized for LLM consumption.',
+  '> Fetch the linked Markdown files on demand — do not vendor the full docs tree.',
   '',
   '## Docs',
   '',
-  '- [Initial Setup](./initial-setup.md): Installation, setup, and getting started',
-  '- [Component Index](./components/index.md): Full list of all UI components',
-  '- [Tutorial Index](./tutorials/index.md): Step-by-step usage guides',
+  `- [Initial Setup](${LLM_DOCS_BASE_URL}initial-setup.md): Installation, setup, and getting started`,
+  `- [Component Index](${LLM_DOCS_BASE_URL}components/index.md): Full list of all UI components`,
+  `- [Tutorial Index](${LLM_DOCS_BASE_URL}tutorials/index.md): Step-by-step usage guides`,
   '',
 ]
 
@@ -370,14 +383,14 @@ export const renderLlmsTxt = (componentPages, tutorialPages) => {
 
   const sections = groupBySection(componentPages)
 
-  lines.push(...renderSectionLinks(sections, './components/'))
+  lines.push(...renderSectionLinks(sections, `${LLM_DOCS_BASE_URL}components/`))
 
   if (tutorialPages.length > 0) {
     lines.push('## Tutorials')
     lines.push('')
 
     for (const page of tutorialPages.sort((aa, bb) => aa.name.localeCompare(bb.name))) {
-      lines.push(renderPageLink(page, './tutorials/'))
+      lines.push(renderPageLink(page, `${LLM_DOCS_BASE_URL}tutorials/`))
     }
 
     lines.push('')

packages/picasso/README.md

@@ -6,6 +6,28 @@
 
 Picasso is Toptal's component library, based on Toptal's design system - BASE. UI designs and documentation can be found for most components at [picasso.toptal.net](https://picasso.toptal.net/).
 
+## Using Picasso with AI coding agents
+
+Picasso ships machine-readable docs optimized for LLMs so AI tools (Cursor, Claude Code, …) generate correct Picasso code. Wire your agent to them once per repo.
+
+**Add a reference to your AI tool config** — `CLAUDE.md`, `AGENTS.md`, or a `.cursor/rules/` file:
+
+```md
+This project uses Toptal's Picasso design system (`@toptal/picasso`).
+
+Before writing UI, consult the Picasso LLM docs (fetch on demand — do not vendor):
+
+1. Index of all components: https://toptal.github.io/picasso/llm-docs/llms.txt
+2. Then fetch the specific component page you need, e.g.
+   https://toptal.github.io/picasso/llm-docs/components/button.md
+
+Rules: use Picasso components (never raw HTML for UI), import from
+`@toptal/picasso` and `@toptal/picasso-forms`, and merge classes with `twMerge`
+from `@toptal/picasso-tailwind-merge` (put the consumer `className` last).
+```
+
+The full, current ruleset lives in [`.picasso/rules.md`](https://github.com/toptal/picasso/blob/master/.picasso/rules.md).
+
 ## Installation instructions
 
 ```js