# Recipes

Multi-file payloads beyond components: skill bundles, the scaffold template set, and screen slices (controller + view + system test, blocks pulled as dependencies) - installable with bin/rails g poetry:add <name> or any shadcn-compatible registry client.

## agent-embed

An opt-in page-agent loader for a poetry app as a Stimulus controller: pinned CDN script (?autoInit=false), session-only BYO key, Turbo-hardened (remounts on turbo:load, idle-only rebuild, module-init catch-up), poetry operator instructions built in. Wire a form with targets model/baseUrl/apiKey/status.

Install: `bin/rails g poetry:add agent-embed` (or `npx shadcn@latest add @poetry/agent-embed`). Files: `app/javascript/controllers/agent_demo_controller.js`.

## scaffold-templates

The lib/templates override set that makes the STANDARD `rails g scaffold` emit poetry-composed views and a matching controller - the same files `bin/rails g poetry:scaffold_templates` copies.

Install: `bin/rails g poetry:add scaffold-templates` (or `npx shadcn@latest add @poetry/scaffold-templates`). Files: `lib/templates/erb/scaffold/_form.html.erb.tt`, `lib/templates/rails/scaffold_controller/controller.rb.tt`, `lib/templates/erb/scaffold/edit.html.erb.tt`, `lib/templates/erb/scaffold/index.html.erb.tt`, `lib/templates/erb/scaffold/new.html.erb.tt`, `lib/templates/erb/scaffold/partial.html.erb.tt`, `lib/templates/erb/scaffold/show.html.erb.tt`.

## screen-data-index

The data-index block as a working feature slice: OrdersController, its index view rendering the block, and a system test. Add `resources :orders, only: :index` to routes.

Install: `bin/rails g poetry:add screen-data-index` (or `npx shadcn@latest add @poetry/screen-data-index`). Files: `app/controllers/orders_controller.rb`, `app/views/orders/index.html.erb`, `test/system/orders_index_test.rb`. Pulls blocks: data-index.

## screen-settings

A settings page composed from the page-header, section-card, and destructive-panel blocks: SettingsController, the composed view, and a system test. Add `resource :settings, only: :show` to routes.

Install: `bin/rails g poetry:add screen-settings` (or `npx shadcn@latest add @poetry/screen-settings`). Files: `app/controllers/settings_controller.rb`, `app/views/settings/show.html.erb`, `test/system/settings_show_test.rb`. Pulls blocks: page-header, section-card, destructive-panel.

## skill-poetry

The component-usage Claude Code skill (SKILL.md + per-family references), generated from the live registry - the same files `bin/rails g poetry:skill` installs.

Install: `bin/rails g poetry:add skill-poetry` (or `npx shadcn@latest add @poetry/skill-poetry`). Files: `.claude/skills/poetry/SKILL.md`, `.claude/skills/poetry/references/forms.md`, `.claude/skills/poetry/references/overlays.md`, `.claude/skills/poetry/references/data.md`, `.claude/skills/poetry/references/feedback.md`, `.claude/skills/poetry/references/navigation.md`, `.claude/skills/poetry/references/foundations.md`, `.claude/skills/poetry/references/chat.md`, `.claude/skills/poetry/references/layout.md`, `.claude/skills/poetry/references/blocks.md`, `.claude/skills/poetry/references/deciding.md`, `.claude/skills/poetry/references/charts.md`.

## skill-poetry-component

The component-authoring Claude Code skill (anatomy / documentation / audit references) - the same files `bin/rails g poetry:skill` installs.

Install: `bin/rails g poetry:add skill-poetry-component` (or `npx shadcn@latest add @poetry/skill-poetry-component`). Files: `.claude/skills/poetry-component/SKILL.md`, `.claude/skills/poetry-component/references/anatomy.md`, `.claude/skills/poetry-component/references/checklist.md`, `.claude/skills/poetry-component/references/documentation.md`.

## skill-poetry-design

The design-taste Claude Code skill (theme / compose / audit / study references) - the same files `bin/rails g poetry:skill` installs.

Install: `bin/rails g poetry:add skill-poetry-design` (or `npx shadcn@latest add @poetry/skill-poetry-design`). Files: `.claude/skills/poetry-design/SKILL.md`, `.claude/skills/poetry-design/references/audit.md`, `.claude/skills/poetry-design/references/compose.md`, `.claude/skills/poetry-design/references/figma.md`, `.claude/skills/poetry-design/references/paper.md`, `.claude/skills/poetry-design/references/study.md`, `.claude/skills/poetry-design/references/theme.md`.