@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/phoenix/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: phoenix
+description: "Use when building an Elixir web app with Phoenix — contexts, Ecto schemas, changesets and migrations, LiveView, channels and PubSub, the generators, and the boundary between domain logic and the web layer. Covers the classic LiveView over-rendering and Ecto N+1 traps. NOT pure OTP work with no web or Ecto layer — GenServers, supervision trees, releases (that is `elixir`)."
+tags: [phoenix, elixir, liveview, ecto, channels, contexts, web, beam]
+recommends: [elixir, postgresdb, docker]
+origin: ai-hub
+---
+
+# Phoenix
+
+You are building a web application on the BEAM with Phoenix. There is one mental model that keeps a Phoenix app coherent as it grows: **contexts are the public API of your domain; the web layer (controllers, LiveViews, channels) is a thin caller of contexts.** A LiveView that reaches into `Repo` directly, or a controller stuffed with business rules, is the first crack. Push logic down into a context function and the web layer stays a presentation shell you can swap (HTML → JSON → LiveView) without rewriting the domain.
+
+Target the current stack: **Phoenix 1.8.7** (1.8.0 shipped 2025-08-05), **LiveView 1.1** (1.1.x patch line; 1.0 shipped 2024-12-03), **Ecto** as the data layer, **Erlang/OTP 25+**. The headline 1.8 change is **scopes**: generators thread the current actor (user/org) through every context function and into the query, so *secure-by-default data access is the norm, not something you bolt on later*. New apps ship daisyUI + Tailwind theming, a single root layout, and an `AGENTS.md` for LLM-assisted work.
+
+If the question has no web, Ecto or LiveView in it — it is a GenServer, a supervision tree, a `mix release` — that is the runtime, route to `../elixir/SKILL.md`.
+
+## Where does this code go — generator decision
+
+Pick the layer first, then the generator. Getting this wrong means rewriting the boundary later.
+
+| You are building | Use | Generator |
+|---|---|---|
+| Stateless page or JSON endpoint, request→response | Controller + view | `mix phx.gen.html` / `phx.gen.json` |
+| Stateful interactive UI, server-rendered, live updates | LiveView | `mix phx.gen.live` |
+| Raw bidirectional WebSocket / fan-out to many clients | Channel + PubSub | hand-wire, no generator |
+| Domain logic with no UI yet (just the boundary) | Context only | `mix phx.gen.context` |
+| Login, sessions, password reset, scopes | Auth scaffold | `mix phx.gen.auth` |
+
+Rule: **generate the context first, then the web layer on top of it.** `phx.gen.live` and `phx.gen.html` already produce a context — don't hand-write a controller that calls `Repo` and skip the context.
+
+## Contexts — the domain boundary
+
+A context is a module like `Accounts`, `Catalog`, `Orders` that owns a slice of the domain. The web layer calls `Catalog.list_products(scope)`; it never calls `Repo` and never builds an `Ecto.Query`.
+
+Rule: **the public contract is plain data and functions, not Ecto schemas.** Schemas are an implementation detail. Leak them and every caller couples to your column names. Why: you can refactor the table without touching controllers.
+
+Rule: **thread the scope through every context function** (1.8). The scope carries the current actor; the context filters every query by it. Why: a forgotten `where: user_id ==` is a data leak — scoping makes the safe path the default path.
+
+```elixir
+# Bad — Repo + business logic in the controller, no scope, anyone reads anyone's data.
+def index(conn, _params) do
+  products = Repo.all(Product)            # raw Repo in web layer
+  render(conn, :index, products: products)
+end
+
+# Good — controller calls a context function that takes the scope.
+def index(conn, _params) do
+  products = Catalog.list_products(conn.assigns.current_scope)
+  render(conn, :index, products: products)
+end
+
+# In lib/my_app/catalog.ex — the boundary owns the query and the scope filter.
+def list_products(%Scope{} = scope) do
+  Product
+  |> where(org_id: ^scope.org.id)         # secure by default
+  |> Repo.all()
+end
+```
+
+Depth on defining and threading scopes, magic-link auth, sudo mode and query-level enforcement lives in `references/auth-and-scopes.md`.
+
+## Ecto — the data layer
+
+Ecto gives you `Repo`, schemas, `Ecto.Changeset` (cast + validate), `Ecto.Multi` (transactional pipelines) and `Ecto.Query`.
+
+Rule: **validate at the boundary with a changeset, never with `try/rescue`.** A changeset casts external params, applies validations and constraints, and hands you `{:ok, struct}` or `{:error, changeset}` you can render straight into a form. Why: validation errors are expected data flow, not exceptions.
+
+Rule: **multi-write operations go through `Ecto.Multi`** so they commit or roll back as a unit. Why: a half-written order with no payment row is corruption.
+
+Rule: **preload associations — never trigger a query per row.** Why: the N+1 is the single most common Phoenix performance bug.
+
+```elixir
+# Bad — N+1: each post in the loop fires a separate query for post.author.
+posts = Repo.all(Post)
+for post <- posts, do: post.author.name   # one SELECT per post
+
+# Good — one query for posts, one for all authors.
+posts = Post |> preload(:author) |> Repo.all()
+for post <- posts, do: post.author.name
+```
+
+Migrations are forward-only facts about schema history — write a new one, don't edit a shipped migration. Changeset recipes, `Ecto.Multi`, advanced queries/preloads, constraints and sandbox config are in `references/ecto-patterns.md`.
+
+## LiveView — stateful server-rendered UI
+
+A LiveView holds state in `socket.assigns`, renders HEEx, and reacts to events. The lifecycle:
+
+| Callback | Fires when | Use it for |
+|---|---|---|
+| `mount/3` | First connect (and the dead render) | Load initial data, set up subscriptions |
+| `handle_params/3` | Mount and every live patch | React to URL/query changes |
+| `handle_event/3` | A client event (`phx-click`, form submit) | Mutate state, call a context |
+| `handle_info/2` | A message arrives (PubSub, `send/2`) | Apply external/async updates |
+
+Rule: **use streams for collections — do not hold the full list in an assign.** A stream keeps the list off the socket; `stream_insert/3` of one item sends only that item over the wire. Why: assigning the whole list re-sends and re-diffs every row on every change — that is exactly the "re-renders the entire list when one row is added" symptom. For per-row change tracking wrap each entry in a LiveComponent.
+
+```elixir
+# Bad — full list in assigns; one insert re-diffs the entire collection.
+def mount(_p, _s, socket), do: {:ok, assign(socket, :messages, Chat.list_messages())}
+def handle_info({:new, msg}, socket) do
+  {:noreply, assign(socket, :messages, socket.assigns.messages ++ [msg])}
+end
+
+# Good — stream; only the new row crosses the wire.
+def mount(_p, _s, socket), do: {:ok, stream(socket, :messages, Chat.list_messages())}
+def handle_info({:new, msg}, socket), do: {:noreply, stream_insert(socket, :messages, msg)}
+```
+
+```heex
+<div id="messages" phx-update="stream">
+  <div :for={{dom_id, msg} <- @streams.messages} id={dom_id}>{msg.body}</div>
+</div>
+```
+
+Build forms with `to_form/2` (carry the changeset, render errors). Route with **verified routes** — the `~p` sigil (`~p"/products/#{product}"`) is compile-checked, the default since 1.7. LiveView 1.1 adds **colocated hooks** (`<script :type={Phoenix.LiveView.ColocatedHook} name="...">`, extracted at compile time, requires Phoenix 1.8+), ColocatedJS, official TypeScript types for the JS client, and keyed comprehensions. Full lifecycle, streams + LiveComponent change tracking, forms/uploads, JS commands, colocated hooks and `assign_async` are in `references/liveview.md`.
+
+## Channels & PubSub — real-time fan-out
+
+Reach for a **channel** when you need raw bidirectional WebSocket messaging or to broadcast to many clients (chat fan-out, presence, live dashboards feeding many sockets). Reach for **LiveView** when one user drives a server-rendered UI — most "real-time" UI is just LiveView + `Phoenix.PubSub`.
+
+```elixir
+Phoenix.PubSub.subscribe(MyApp.PubSub, "room:42")   # in mount/3
+Phoenix.PubSub.broadcast(MyApp.PubSub, "room:42", {:new, msg})  # from a context
+```
+
+`Phoenix.Presence` tracks who is online on a topic. Keep channel callbacks thin — they call contexts too.
+
+## Auth & scopes
+
+`mix phx.gen.auth` in 1.8 **defaults to magic-link (passwordless) auth**, with a re-auth "sudo mode" plug for sensitive operations; email+password is still available. It also sets up the **default scope** that generators thread through contexts. Treat scope-based filtering as the authorization layer: the query never returns rows the scope can't see, so authz is enforced in the data access, not in a forgotten `if`. Flow, sudo mode, custom scopes and testing authz are in `references/auth-and-scopes.md`.
+
+## Testing — test at the right layer
+
+| Test target | Helper | Isolation |
+|---|---|---|
+| Controllers / JSON | `Phoenix.ConnTest` via `ConnCase` | SQL sandbox |
+| Context / Ecto logic | `DataCase` | SQL sandbox |
+| LiveView UI | `Phoenix.LiveViewTest` (`live/2`, `render_click`, `element/2`) | SQL sandbox |
+| Concurrent DB tests | `Ecto.Adapters.SQL.Sandbox` | per-test transaction |
+
+Rule: **test domain rules at the context (DataCase), test interaction at the LiveView (LiveViewTest).** Why: a context test that drives the UI is slow and brittle; a LiveView test that re-asserts every validation rule duplicates the context test.
+
+```elixir
+test "creating a product shows it in the list", %{conn: conn} do
+  {:ok, view, _html} = live(conn, ~p"/products")
+  view |> form("#product-form", product: %{name: "Widget"}) |> render_submit()
+  assert render(view) =~ "Widget"
+end
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `Repo.all/insert` called from a controller or LiveView | Web layer couples to the DB; logic can't be reused or tested in isolation | Call a context function; keep `Repo` inside the context |
+| Returning Ecto schemas as the public contract | Callers couple to column names; refactors ripple outward | Expose functions over plain data; schemas stay internal |
+| Holding the full collection in `socket.assigns` | Every insert re-sends and re-diffs the whole list (lag, bandwidth) | `stream/3` + `stream_insert/3`; LiveComponent for per-row tracking |
+| `try/rescue` around persistence to "validate" | Hides expected errors as exceptions; no field-level messages | `Ecto.Changeset` → `{:ok, _}` / `{:error, changeset}` |
+| Looping over records touching an association | N+1 — one query per row | `preload/2` (or a join) before the loop |
+| Forgetting to filter a query by the scope | Cross-tenant data leak — the worst kind of bug | Thread `scope` through every context fn; filter in the query |
+| Multi-write without a transaction | Partial writes leave corrupt state | `Ecto.Multi`, commit or roll back as one |
+| Fat schema modules full of business logic | Domain rules scatter; the boundary blurs | Logic lives in the context; schema holds fields + changeset |
+| Hardcoded path strings in templates | Breaks silently when routes change | Verified routes — the `~p` sigil, compile-checked |
+
+## See also
+
+- `../elixir/SKILL.md` — OTP, GenServers, supervision trees, the runtime Phoenix builds on.
+- `../postgresdb/SKILL.md` — raw SQL tuning, index design and DB ops below the Ecto line.
+- `references/liveview.md`, `references/ecto-patterns.md`, `references/auth-and-scopes.md` — branch-specific depth.

package/skills/shared/phoenix/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — phoenix
+
+These cases check two things, neither of which is an automated unit test. First, **routing**: feed each `should_trigger` prompt to the skill router and confirm it selects `phoenix`, and feed each `should_not_trigger` prompt and confirm it routes to the named sibling (`elixir`, `postgresdb`, `fly-io`, `django`) instead — the non-obvious cases (the re-rendering list, the N+1, the Catalan context prompt) are the ones worth watching. Second, the **capability** case is graded by hand or by a judge model: have the agent implement the Catalog/Product LiveView scenario and check the generated code against the `must_include` rubric (context boundary, changeset validation, scope threaded into the query, streams over full-list assigns, `to_form`, `~p` routes, LiveViewTest + DataCase). Pass means every rubric item is satisfied in real Phoenix 1.8 / LiveView 1.1 code, not just mentioned.

package/skills/shared/phoenix/evals/cases.yaml

@@ -0,0 +1,40 @@
+skill: phoenix
+
+should_trigger:
+  - prompt: "Build a LiveView CRUD page for products with a list, create form and delete."
+    why: Core LiveView use — mount/handle_event, streams, forms, verified routes.
+  - prompt: "How should I structure the Accounts context so my controllers stay thin?"
+    why: Context boundary — the central Phoenix mental model (web is a thin caller).
+  - prompt: "Set up passwordless / magic-link login with phx.gen.auth."
+    why: Phoenix 1.8 magic-link auth default plus the scope wiring it scaffolds.
+  - prompt: "My LiveView re-renders the entire message list every time one row is added — how do I fix it?"
+    why: Non-obvious symptom whose real fix is streams (off-socket collections); names no Phoenix API directly.
+  - prompt: "Every post in my loop fires a separate query for its author — how do I stop the N+1?"
+    why: Web-app data layer; Ecto preload. The symptom, not the API name, is the trigger.
+  - prompt: "Crea un context Comandes i un LiveView per gestionar-les amb accés per usuari."
+    why: Catalan trigger — context + LiveView + scope-based per-user access.
+
+should_not_trigger:
+  - prompt: "Design a supervision tree and restart strategy for a pool of workers."
+    route_to: elixir
+    why: Pure OTP/runtime — no web, Ecto or LiveView layer.
+  - prompt: "Add a GIN index and tune this slow Postgres query plan."
+    route_to: postgresdb
+    why: Raw SQL/index design below the Ecto line, framework-independent.
+  - prompt: "Containerize the release and deploy it to Fly.io."
+    route_to: fly-io
+    why: Shipping/runtime of the release, not Phoenix application code.
+  - prompt: "Build the REST API in Django with DRF serializers."
+    route_to: django
+    why: A different web framework, explicitly named — not Phoenix.
+
+capability:
+  - scenario: "Implement a Catalog context managing a Product schema plus a LiveView index, scoped to the current user's org, with a create form and tests."
+    must_include:
+      - "Context functions are the public API; the LiveView/controller never calls Repo or builds a query directly"
+      - "Ecto.Changeset casts and validates (required fields, price > 0) at the boundary"
+      - "The scope (current user/org) is threaded into every context function and applied inside the query (where org_id ==), not in a post-fetch if"
+      - "LiveView uses stream/stream_insert for the product list, not a full-list assign"
+      - "Form uses to_form/2 and renders changeset errors on {:error, changeset}"
+      - "Verified routes (~p sigil) used for links/redirects, not hardcoded path strings"
+      - "Phoenix.LiveViewTest with live/2 and render_submit/render_click; context logic tested with DataCase"

package/skills/shared/phoenix/references/auth-and-scopes.md

@@ -0,0 +1,82 @@
+# Auth & scopes — depth
+
+Phoenix 1.8 makes authorization a property of data access via **scopes**, and `mix phx.gen.auth` scaffolds the whole login flow around them.
+
+## `mix phx.gen.auth` in 1.8
+
+```bash
+mix phx.gen.auth Accounts User users
+```
+
+Defaults to **magic-link (passwordless) auth**: the user enters an email, receives a one-time login link, and is signed in — no password to store or leak. Email+password is still available if you opt in. The generator produces:
+
+- The `Accounts` context (`User`, tokens, registration/login functions).
+- LiveViews for login, registration, settings, confirmation.
+- A `require_authenticated_user` plug/on_mount hook.
+- A **sudo mode** re-auth gate (`require_sudo_mode`-style) for sensitive operations (changing email/password) — recent confirmation is required even when already logged in.
+- The **default scope** wired into the router and `conn.assigns` / `socket.assigns`.
+
+## Scopes — secure-by-default access
+
+A scope is a struct carrying the current actor and whatever it is scoped to (user, org/tenant). Generators thread it through every context function and into every query.
+
+```elixir
+defmodule MyApp.Accounts.Scope do
+  defstruct [:user, :org]
+  def for_user(%User{} = user), do: %__MODULE__{user: user, org: user.org}
+end
+```
+
+```elixir
+# Router puts the scope on assigns once.
+# Every context function takes it and filters by it.
+def list_products(%Scope{} = scope) do
+  from(p in Product, where: p.org_id == ^scope.org.id) |> Repo.all()
+end
+
+def get_product!(%Scope{} = scope, id) do
+  from(p in Product, where: p.id == ^id and p.org_id == ^scope.org.id) |> Repo.one!()
+end
+```
+
+Rule: the scope filter goes **in the query**, not in an `if` after the fetch. Why: `get_product!(scope, other_orgs_id)` then raises `NoResultsError` (a clean 404) instead of returning a row you forgot to check. The unsafe path stops compiling/working, the safe path is the only path.
+
+## In LiveView
+
+```elixir
+# router.ex
+live_session :authenticated, on_mount: [{MyAppWeb.UserAuth, :require_authenticated}] do
+  live "/products", ProductLive.Index, :index
+end
+
+# the on_mount hook puts current_scope on the socket; use it everywhere:
+def mount(_p, _s, socket) do
+  {:ok, stream(socket, :products, Catalog.list_products(socket.assigns.current_scope))}
+end
+```
+
+## Sudo mode for sensitive actions
+
+```elixir
+# Re-confirm recent authentication before allowing email/password changes.
+plug :require_sudo_mode when action in [:update_email, :update_password]
+```
+
+If the user authenticated too long ago, they are bounced to re-confirm. This limits the blast radius of a hijacked session.
+
+## Testing authz
+
+```elixir
+# DataCase — the scope filter is the authorization; test that cross-scope access fails.
+test "get_product!/2 cannot read another org's product", %{scope: scope} do
+  other = product_fixture(scope_fixture())          # different org
+  assert_raise Ecto.NoResultsError, fn -> Catalog.get_product!(scope, other.id) end
+end
+
+# ConnCase / LiveViewTest — unauthenticated request redirects to login.
+test "redirects when not logged in", %{conn: conn} do
+  assert {:error, {:redirect, %{to: "/users/log-in"}}} = live(conn, ~p"/products")
+end
+```
+
+Rule: test authorization at the context with `DataCase` (the scope filter is where authz lives), and test the redirect/gate at the web layer with `ConnCase`/`LiveViewTest`. Why: proving the query refuses cross-scope rows is the real security assertion; the web test just proves the gate is wired.

package/skills/shared/phoenix/references/ecto-patterns.md

@@ -0,0 +1,93 @@
+# Ecto patterns — depth
+
+Ecto is the data layer: `Repo` (the gateway to the DB), schemas (struct + field map), `Ecto.Changeset` (cast + validate + constraints), `Ecto.Multi` (transactional pipelines), `Ecto.Query`. `phoenix_ecto` adds the Phoenix integration and the concurrent SQL sandbox for tests.
+
+## Changeset recipes
+
+A changeset casts external params, applies validations, and maps DB constraints to field errors.
+
+```elixir
+def changeset(product, attrs) do
+  product
+  |> cast(attrs, [:name, :price, :sku, :org_id])
+  |> validate_required([:name, :price, :org_id])
+  |> validate_number(:price, greater_than: 0)
+  |> validate_length(:name, max: 120)
+  |> unique_constraint(:sku)                 # turns a DB unique violation into a field error
+  |> foreign_key_constraint(:org_id)
+end
+```
+
+Rule: validate in the changeset, not with `try/rescue`. `unique_constraint`/`foreign_key_constraint` require the matching DB index/constraint — they convert the DB error into `{:error, changeset}` instead of an exception. Why: only the database can atomically enforce uniqueness under concurrency; the changeset just translates the failure.
+
+Use a separate changeset per operation when rules differ (`registration_changeset` vs `update_changeset`) rather than one changeset with conditional branches.
+
+## `Ecto.Multi` — atomic multi-write
+
+```elixir
+def place_order(scope, cart) do
+  Ecto.Multi.new()
+  |> Ecto.Multi.insert(:order, Order.changeset(%Order{org_id: scope.org.id}, cart))
+  |> Ecto.Multi.insert_all(:items, OrderItem, &build_items(&1.order, cart))
+  |> Ecto.Multi.update(:inventory, fn _ -> decrement_stock(cart) end)
+  |> Repo.transaction()
+end
+# => {:ok, %{order: order, items: ..., inventory: ...}}  or  {:error, step, changeset, changes_so_far}
+```
+
+Every step commits or the whole thing rolls back. Each step can read the results of prior steps via the function form. Pattern-match `{:error, failed_step, changeset, _}` to know which step failed.
+
+## Queries & preloads — killing N+1
+
+```elixir
+import Ecto.Query
+
+# Preload (two queries: posts, then all authors) — preferred for has_many.
+Post |> preload(:author) |> Repo.all()
+
+# Join + preload in one query — for filtering/ordering by the association.
+from(p in Post, join: a in assoc(p, :author), where: a.active, preload: [author: a])
+|> Repo.all()
+
+# Scoped, paginated, ordered.
+from(p in Product,
+  where: p.org_id == ^scope.org.id,
+  order_by: [desc: p.inserted_at],
+  limit: ^limit, offset: ^offset
+) |> Repo.all()
+```
+
+Rule: never touch `record.assoc` inside a loop without preloading first — that is the N+1. Use `preload` for plain loading; use `join: ... preload:` when you also filter or sort by the association.
+
+## Migrations & constraints
+
+```elixir
+def change do
+  create table(:products) do
+    add :name, :string, null: false
+    add :sku, :string, null: false
+    add :org_id, references(:orgs, on_delete: :delete_all), null: false
+    timestamps()
+  end
+  create unique_index(:products, [:sku])
+  create index(:products, [:org_id])         # back the scope filter with an index
+end
+```
+
+Migrations are forward-only history: write a new migration to change schema, never edit a migration that has shipped. Constraints (`null: false`, `unique_index`, FK) belong in the migration; the changeset translates their violations into field errors. Index the columns the scope filters on, or every scoped query is a table scan.
+
+## SQL sandbox for tests
+
+```elixir
+# config/test.exs
+config :my_app, MyApp.Repo, pool: Ecto.Adapters.SQL.Sandbox
+
+# test/support/data_case.ex setup
+setup tags do
+  pid = Ecto.Adapters.SQL.Sandbox.start_owner!(MyApp.Repo, shared: not tags[:async])
+  on_exit(fn -> Ecto.Adapters.SQL.Sandbox.stop_owner(pid) end)
+  :ok
+end
+```
+
+Each test runs in its own transaction that is rolled back at the end, so tests stay isolated and can run `async: true` concurrently. LiveView/Conn tests that spawn processes need `shared: true` (non-async) so the spawned process sees the same sandbox connection.

package/skills/shared/phoenix/references/liveview.md

@@ -0,0 +1,134 @@
+# LiveView (1.1) — depth
+
+Targets LiveView 1.1.x on Phoenix 1.8.7. LiveView holds UI state in `socket.assigns`, renders HEEx, and reacts to events over a persistent WebSocket (with a dead HTTP render first).
+
+## Lifecycle in detail
+
+```elixir
+def mount(params, session, socket) do
+  # Runs twice: once for the dead (HTTP) render, once on WS connect.
+  # Gate expensive/subscription work on connected?/1.
+  if connected?(socket), do: Phoenix.PubSub.subscribe(MyApp.PubSub, "products")
+  {:ok, stream(socket, :products, Catalog.list_products(socket.assigns.current_scope))}
+end
+
+def handle_params(params, _uri, socket) do
+  # Every live_patch / URL change lands here. Use for tab/filter/pagination state.
+  {:noreply, apply_action(socket, socket.assigns.live_action, params)}
+end
+
+def handle_event("delete", %{"id" => id}, socket) do
+  product = Catalog.get_product!(socket.assigns.current_scope, id)
+  {:ok, _} = Catalog.delete_product(socket.assigns.current_scope, product)
+  {:noreply, stream_delete(socket, :products, product)}
+end
+
+def handle_info({:created, product}, socket) do
+  # External event (PubSub broadcast, send/2 from a Task). Apply to the stream.
+  {:noreply, stream_insert(socket, :products, product, at: 0)}
+end
+```
+
+`assign/2,3` for scalar state; `assign_new/3` to avoid recomputing on reconnect. Keep assigns small — they are state held per connected socket.
+
+## Streams — collections without server-held lists
+
+A stream keeps the collection in the DOM, not in `socket.assigns`. The server tracks only DOM ids, so a single `stream_insert/3` ships one row.
+
+```elixir
+stream(socket, :products, products)            # initial load
+stream_insert(socket, :products, p, at: 0)     # prepend; at: -1 appends
+stream_delete(socket, :products, p)            # remove one row
+stream(socket, :products, [], reset: true)     # clear and reload
+```
+
+```heex
+<table>
+  <tbody id="products" phx-update="stream">
+    <tr :for={{dom_id, p} <- @streams.products} id={dom_id}>
+      <td>{p.name}</td>
+      <td>{p.price}</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+The container needs an `id` and `phx-update="stream"`; each row's `id` must come from the stream's `{dom_id, item}`. For per-row change tracking (a row that re-renders independently), wrap the row in a `Phoenix.LiveComponent` keyed by id — only that component re-diffs.
+
+## Forms with `to_form/2`
+
+```elixir
+def mount(_p, _s, socket) do
+  {:ok, assign(socket, :form, to_form(Catalog.change_product(%Product{})))}
+end
+
+def handle_event("validate", %{"product" => attrs}, socket) do
+  form = %Product{} |> Catalog.change_product(attrs) |> Map.put(:action, :validate) |> to_form()
+  {:noreply, assign(socket, :form, form)}
+end
+
+def handle_event("save", %{"product" => attrs}, socket) do
+  case Catalog.create_product(socket.assigns.current_scope, attrs) do
+    {:ok, _product} -> {:noreply, socket |> put_flash(:info, "Created") |> push_navigate(to: ~p"/products")}
+    {:error, changeset} -> {:noreply, assign(socket, :form, to_form(changeset))}
+  end
+end
+```
+
+```heex
+<.form for={@form} phx-change="validate" phx-submit="save">
+  <.input field={@form[:name]} label="Name" />
+  <.button>Save</.button>
+</.form>
+```
+
+`to_form/2` wraps a changeset; rendering the same form back on `{:error, changeset}` surfaces field errors automatically. Setting `:action` makes "validate" errors show without a submit.
+
+## Uploads
+
+```elixir
+socket = allow_upload(socket, :photo, accept: ~w(.jpg .png), max_entries: 1)
+# in save: consume_uploaded_entries(socket, :photo, fn %{path: path}, _entry -> ... end)
+```
+
+## JS commands — client interactivity without a round trip
+
+```heex
+<button phx-click={JS.toggle(to: "#menu") |> JS.add_class("open", to: "#menu")}>Menu</button>
+```
+
+`Phoenix.LiveView.JS` runs show/hide/toggle/transition/dispatch on the client with no server message — use it for purely visual state.
+
+## Colocated hooks & ColocatedJS (1.1, requires Phoenix 1.8+)
+
+Define a JS hook next to the element that uses it; the compiler extracts it into the bundle.
+
+```heex
+<div id="chart" phx-hook=".Chart" data-series={Jason.encode!(@series)}>
+  <script :type={Phoenix.LiveView.ColocatedHook} name=".Chart">
+    export default { mounted() { renderChart(this.el); } }
+  </script>
+</div>
+```
+
+`ColocatedJS` extracts arbitrary colocated `<script>` modules. LiveView 1.1 also ships official TypeScript types for the JS client and **keyed comprehensions** (`:for` tracks items by key for finer diffs).
+
+## Async assigns
+
+Offload slow loads so mount returns immediately.
+
+```elixir
+def mount(_p, _s, socket) do
+  {:ok, assign_async(socket, :stats, fn -> {:ok, %{stats: Reports.expensive_stats()}} end)}
+end
+```
+
+```heex
+<.async_result :let={stats} assign={@stats}>
+  <:loading>Computing…</:loading>
+  <:failed :let={_reason}>Could not load.</:failed>
+  {stats.total}
+</.async_result>
+```
+
+`assign_async/3` runs the work in a Task and pushes the result; the template renders loading/failed/ready states. Use it instead of blocking `mount/3` on a slow query.

package/skills/shared/phoenix/scripts/verify.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# verify.sh — read-only gates for a Phoenix / Elixir target.
+#
+# When run inside a mix project it runs the standard project gates:
+#   - mix format --check-formatted        (style)
+#   - mix compile --warnings-as-errors    (warning-free compile)
+#   - mix test                            (only if a test/ dir exists)
+#
+# It never fails a toolchain-free or empty target: it exits 0 with a skip note
+# when mix is absent or there is no mix.exs to check. Read-only: no writes, no
+# network and no database are required to pass the compile/format gates.
+#
+# Usage: bash scripts/verify.sh [TARGET_DIR]   (default: current directory)
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify: target '$TARGET' is not a directory — nothing to check. SKIP."
+  exit 0
+fi
+
+# Toolchain gate: no mix on PATH -> skip cleanly (never fail without a toolchain).
+if ! command -v mix >/dev/null 2>&1; then
+  echo "verify: 'mix' not found on PATH — Elixir/Phoenix toolchain not installed. SKIP."
+  exit 0
+fi
+
+# Find a mix project root (a directory containing mix.exs), shallowest first.
+mix_root=""
+if [ -f "$TARGET/mix.exs" ]; then
+  mix_root="$TARGET"
+else
+  mix_root="$(find "$TARGET" -maxdepth 4 -name mix.exs -not -path '*/deps/*' -not -path '*/_build/*' 2>/dev/null \
+    | awk '{ print gsub(/\//,"/"), $0 }' | sort -n | head -n1 | cut -d' ' -f2- || true)"
+  [ -n "$mix_root" ] && mix_root="$(dirname "$mix_root")"
+fi
+
+if [ -z "$mix_root" ]; then
+  echo "verify: no mix.exs under '$TARGET' — not a mix project, nothing to check. SKIP."
+  exit 0
+fi
+
+echo "verify: mix project root -> $mix_root"
+status=0
+
+echo "verify: mix format --check-formatted"
+if ! ( cd "$mix_root" && mix format --check-formatted ); then
+  echo "verify: FAIL — files are not formatted (run: mix format)"
+  status=1
+fi
+
+echo "verify: mix compile --warnings-as-errors"
+if ! ( cd "$mix_root" && mix compile --warnings-as-errors ); then
+  echo "verify: FAIL — compile produced warnings or errors"
+  status=1
+fi
+
+if [ -d "$mix_root/test" ]; then
+  echo "verify: mix test"
+  if ! ( cd "$mix_root" && mix test ); then
+    echo "verify: FAIL — test suite did not pass"
+    status=1
+  fi
+else
+  echo "verify: no test/ directory — skipping mix test."
+fi
+
+if [ "$status" -eq 0 ]; then
+  echo "verify: OK"
+fi
+exit "$status"