build: Dumping Content to dist folders on build for LLM guidance.

packages/components-native/package.json

@@ -29,12 +29,13 @@
   ],
   "scripts": {
     "clean": "rm -rf dist/* tsconfig.tsbuildinfo",
-    "build": "npm run build:clean && npm run compile",
+    "build": "npm run build:clean && npm run compile && npm run copy:docs",
     "bootstrap": "npm run build",
     "prepack": "npm run build",
     "watch": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
     "compile": "tsc -p tsconfig.build.json",
     "build:clean": "rm -rf ./dist",
+    "copy:docs": "node ../../scripts/copyDocumentationContent.mjs mobile packages/components-native/dist/docs",
     "storybook": "storybook dev -p 6008 --disable-telemetry",
     "storybook:build": "storybook build --disable-telemetry"
   },

packages/components/package.json

@@ -454,7 +454,8 @@
   "scripts": {
     "build": "npm run build:pre && rollup --config && npm run build:post",
     "build:pre": "npm run css:types:build && PREBUILD_CSS=true rollup --config && cp dist/styles.css ./styles.css.backup && npm run clean",
-    "build:post": "mv ./styles.css.backup dist/styles.css",
+    "build:post": "mv ./styles.css.backup dist/styles.css && npm run copy:docs",
+    "copy:docs": "node ../../scripts/copyDocumentationContent.mjs web packages/components/dist/docs",
     "bootstrap": "npm run clean; npm run build",
     "clean": "rm -rf dist/* tsconfig.rollup.tsbuildinfo",
     "css:types:watch": "tcm -w -p \"**/*.module.css\" src",
@@ -541,4 +542,4 @@
     "> 1%",
     "IE 10"
   ]
-}
+}

packages/site/src/content/guides/choosing-components.md

@@ -0,0 +1,53 @@
+# Choosing the Right Component
+
+Decision guides for selecting the correct Atlantis component by intent.
+
+---
+
+## "I need a dropdown / selection"
+
+- **Small fixed list (< 10 items), no search needed** → `Combobox`
+- **Large or dynamic list, needs search/filter** → `Autocomplete` with
+  `version={2}`
+- **Multiple selections from a list** → `Autocomplete` v2 with `multiple` prop,
+  or `Combobox` with multi-select
+- **Binary on/off toggle** → `Switch`
+- **Single choice from 2–5 options, all visible** → `RadioGroup`
+- ~~`Select`~~ → Deprecated. Use `Combobox`.
+- ~~`MultiSelect`~~ → Deprecated. Use `Autocomplete` v2 or `Combobox`.
+
+## "I need to display data"
+
+- **Tabular data with sorting/filtering** → `DataTable`
+- **Label-value pairs (detail view)** → `DescriptionList`
+- **Simple list of items** → `List`
+- **Empty view with no data** → `EmptyState`
+
+## "I need to build a form"
+
+Compose: `Form` > `Content` > `FormField` > input component.
+
+All form inputs must use `version={2}` where available. See
+[usage-rules.md](./usage-rules.md) for the full form composition example.
+
+## "I need to confirm a destructive action"
+
+Use `ConfirmationModal` (not a plain `Modal`). It provides the confirm/cancel
+pattern with a destructive button variation.
+
+## "I need to show feedback after an action"
+
+- **Temporary, non-blocking** → `Toast`
+- **Persistent, in-page** → `Banner`
+
+## "I need layout structure"
+
+- **Vertical stacking with spacing** → `Stack`
+- **Horizontal wrapping items** → `Cluster`
+- **Grid of same-sized cards** → `Tiles`
+- **Side-by-side with sidebar** → `SideKick`
+- **Responsive horizontal↔vertical** → `ResponsiveSwitcher`
+- **Padding and backgrounds** → `Box`
+- **Fixed aspect ratio (images/video)** → `Frame`
+- **Full-height centered content** → `Cover`
+- **Full page structure** → `Page`

packages/site/src/content/guides/usage-rules.md

@@ -0,0 +1,85 @@
+# Atlantis Usage Rules
+
+Conventions and rules that apply to all Atlantis component usage. Read this
+before generating any Atlantis code.
+
+---
+
+## Always use version={2} for migrated components
+
+The following components have a v2 implementation. **Always pass
+`version={2}`**. Never generate v1 usage for these components — v1 is
+deprecated.
+
+| Component        | Import                                                                   | v2 prop                                         |
+| ---------------- | ------------------------------------------------------------------------ | ----------------------------------------------- |
+| Autocomplete     | `import { Autocomplete } from "@jobber/components/Autocomplete"`         | `version={2}` — fully controlled, async support |
+| Checkbox         | `import { Checkbox } from "@jobber/components/Checkbox"`                 | `version={2}`                                   |
+| InputDate        | `import { InputDate } from "@jobber/components/InputDate"`               | `version={2}`                                   |
+| InputEmail       | `import { InputEmail } from "@jobber/components/InputEmail"`             | `version={2}`                                   |
+| InputNumber      | `import { InputNumber } from "@jobber/components/InputNumber"`           | `version={2}`                                   |
+| InputPhoneNumber | `import { InputPhoneNumber } from "@jobber/components/InputPhoneNumber"` | `version={2}`                                   |
+| InputText        | `import { InputText } from "@jobber/components/InputText"`               | `version={2}`                                   |
+| InputTime        | `import { InputTime } from "@jobber/components/InputTime"`               | `version={2}`                                   |
+| Modal            | `import { Modal } from "@jobber/components/Modal"`                       | `version={2}`                                   |
+
+## Deprecated components — do not use
+
+| Deprecated            | Replacement                                           | Notes                                                                 |
+| --------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- |
+| `Select`              | `Combobox`                                            | Select v1 is deprecated. Select v2 is experimental — prefer Combobox. |
+| `MultiSelect`         | `Autocomplete` v2 with `multiple` prop, or `Combobox` | Fully deprecated, no longer supported.                                |
+| `RecurringSelect`     | None (will be removed)                                | Deprecated, will be removed in next major version.                    |
+| `Chips` (dismissible) | `Autocomplete` v2 with `multiple` prop                | Dismissible Chips variant is deprecated.                              |
+
+## Import pattern
+
+Always use named imports from subpath exports:
+
+```tsx
+// ✅ Correct
+import { Button } from "@jobber/components/Button";
+import { InputText } from "@jobber/components/InputText";
+
+// ❌ Wrong — do not use barrel imports
+import { Button, InputText } from "@jobber/components";
+```
+
+## Design tokens
+
+Never hardcode colors, spacing, or other visual values. Use CSS Modules with CSS
+custom properties from `@jobber/design`:
+
+```css
+/* ✅ Correct */
+.header {
+  color: var(--color-heading);
+  padding: var(--space-base);
+  border-radius: var(--radius-base);
+}
+
+/* ❌ Wrong */
+.header {
+  color: #1a1a1a;
+  padding: 16px;
+  border-radius: 4px;
+}
+```
+
+## Form composition
+
+Form inputs must be wrapped in `FormField` inside a `Form`:
+
+```tsx
+<Form onSubmit={handleSubmit}>
+  <Content>
+    <FormField>
+      <InputText version={2} name="name" placeholder="Name" />
+    </FormField>
+    <FormField>
+      <InputEmail version={2} name="email" placeholder="Email" />
+    </FormField>
+    <Button type="submit" label="Save" />
+  </Content>
+</Form>
+```