diff --git a/elixir/SKILL.md b/elixir/SKILL.md
index 388fad5..dc682a2 100644
--- a/elixir/SKILL.md
+++ b/elixir/SKILL.md
@@ -10,6 +10,7 @@
| Cortex Status | Elixir **not yet installed** on cortex.hydrascale.net |
| AI Agent Tooling | `usage_rules` hex package (~> 1.2) — **always include** |
| Production Framework | **Ash Framework** for substantial projects |
+| Agent Framework | **Jido** (~> 2.1) for multi-agent systems |
| Paradigm | Functional, concurrent, fault-tolerant on BEAM VM |
---
@@ -17,1473 +18,51 @@
## CRITICAL RULES — Read First
1. **Target Elixir 1.19.5** — not 1.15, not 1.17. Use current idioms and features.
-2. **Always add `usage_rules`** to every project: `{:usage_rules, "~> 1.1", only: [:dev]}` — it generates `AGENTS.md`/`CLAUDE.md` from dependency docs, giving AI agents rich context about the libraries in use.
-3. **Use Ash Framework** for production/substantial projects (not necessarily POCs). Ash provides declarative resources, built-in authorization, and extensions for Postgres, Phoenix, GraphQL, JSON:API.
-4. **Cortex is Elixir-first** — Elixir is the primary orchestrator language, with interop to Python (Erlport/ports), Rust (Rustler NIFs), and Zig when needed.
-5. **Never use deprecated patterns** from pre-1.16 code (see Breaking Changes section).
+2. **Always add `usage_rules`** to every project: `{:usage_rules, "~> 1.1", only: [:dev]}`.
+3. **Use Ash Framework** for production/substantial projects (not necessarily POCs).
+4. **Cortex is Elixir-first** — Elixir is the primary orchestrator, with interop to Python/Rust/Zig.
+5. **Never use deprecated patterns** from pre-1.16 code (see Part 1).
+6. **Phoenix 1.8** — always specify `:formats` on controllers, use `~p` verified routes, use scopes.
+7. **For agentic workflows** — consider `GenStateMachine` over GenServer (built-in timeouts, state enter, postpone). For multi-agent orchestration, use **Jido**.
---
-## Elixir 1.19 — What's New
+## Guide Structure — Load What You Need
-### Gradual Set-Theoretic Type System
+This guide is split into focused parts. Load the part relevant to your current task:
-Elixir 1.19 significantly advances the built-in type system. It is **sound**, **gradual**, and **set-theoretic** (types compose via union, intersection, negation).
+### Part 1: Core Language & OTP (`elixir-part1-core.md`)
+Elixir 1.19 features, type system, breaking changes since 1.15, pattern matching, pipelines, with expressions, structs, protocols, behaviours, Mix project structure, testing.
-**Current capabilities (1.19):**
-- Type inference from existing code — no annotations required yet (user-provided signatures coming in future releases)
-- **Protocol dispatch type checking** — the compiler warns when you pass a value to string interpolation, `for` comprehensions, or other protocol-dispatched operations that don't implement the required protocol
-- **Anonymous function type inference** — `fn` literals and `&captures` now propagate types, catching mismatches at compile time
-- Types: `atom()`, `binary()`, `integer()`, `float()`, `pid()`, `port()`, `reference()`, `tuple()`, `list()`, `map()`, `function()`
-- Compose with: `atom() or integer()` (union), `atom() and integer()` (intersection → `none()`), `atom() and not nil` (difference)
-- `dynamic()` type for gradual typing — represents runtime-checked values
-- Tuple precision: `{:ok, binary()}`, open tuples with `...`: `{:ok, binary(), ...}`
-- Map types: `%{key: value}` for closed maps, `%{optional(atom()) => term()}` for open maps
-- Function types: `(integer() -> boolean())`
+### Part 2: Concurrency & OTP (`elixir-part2-concurrency.md`)
+BEAM processes, message passing, GenServer, Supervisors, DynamicSupervisor, Task, GenStateMachine (state machines for agentic workflows), Registry, ETS.
-**What this means in practice:** The compiler now catches real bugs — passing a struct to string interpolation that doesn't implement `String.Chars`, using a non-enumerable in `for`, type mismatches in anonymous function calls. These are warnings today, errors in the future.
+### Part 3: Phoenix Framework (`elixir-part3-phoenix.md`)
+Phoenix 1.8.5 — router/pipelines, verified routes, controllers, HEEx components, LiveView, Channels, contexts, Ecto, authentication, scopes, telemetry, security, testing, generators, deployment.
-### Up to 4x Faster Compilation
-
-Two major improvements:
-
-1. **Lazy module loading** — modules are no longer loaded immediately when defined. The parallel compiler controls both compilation and loading, reducing pressure on the Erlang code server. Reports of 2x+ speedup on large projects.
-
-2. **Parallel dependency compilation** — set `MIX_OS_DEPS_COMPILE_PARTITION_COUNT` env var to partition OS dep compilation across CPU cores.
-
-**Potential regressions:** If you spawn processes during compilation that invoke other project modules, use `Kernel.ParallelCompiler.pmap/2` or `Code.ensure_compiled!/1` before spawning. Also affects `@on_load` callbacks that reference sibling modules.
-
-### Other 1.19 Features
-
-- `min/2` and `max/2` allowed in guards
-- `Access.values/0` — traverse all values in a map/keyword
-- `String.count/2` — count occurrences of a pattern
-- Unicode 17.0.0 support
-- Multi-line IEx prompts
-- `mix help Mod.fun/arity` — get help for specific functions
-- New pretty printing infrastructure
-- OpenChain compliance with Source SBoM
-- Erlang/OTP 28 support
+### Part 4: Ecosystem & Production (`elixir-part4-ecosystem.md`)
+Ash Framework, Jido (multi-agent systems), usage_rules, OTP releases, Docker deployment, distributed Erlang, monitoring (PromEx/Prometheus/Grafana), CI/CD, interop (Python/Rust/Zig), common libraries, cortex deployment plan, anti-patterns.
---
-## Breaking Changes Since 1.15
-
-These are critical to know — older books and tutorials will use the old patterns.
-
-### Struct Update Syntax (1.18+)
-```elixir
-# OLD (1.15) — no longer valid
-%User{user | name: "new"}
-
-# NEW (1.18+) — explicit pattern match required
-%User{} = user
-%User{user | name: "new"}
-# Or in one expression:
-%User{name: "new"} = Map.merge(user, %{name: "new"})
-```
-Actually the change is: `%URI{my_uri | path: "/new"}` now requires `my_uri` to match `%URI{}`. If the compiler can't verify it's the right struct type, it warns.
-
-### Regex as Struct Field Defaults (OTP 28)
-```elixir
-# BROKEN on OTP 28 — regex literals can't be struct field defaults
-defmodule MyMod do
- defstruct pattern: ~r/foo/ # Compile error on OTP 28
-end
-
-# FIX — use @default_pattern or compute at runtime
-defmodule MyMod do
- @default_pattern ~r/foo/
- defstruct pattern: @default_pattern # Still fails — use nil + init
-end
-```
-
-### Logger Backends Deprecated
-```elixir
-# OLD
-config :logger, backends: [:console]
-
-# NEW — use LoggerHandler (Erlang's logger)
-config :logger, :default_handler, []
-config :logger, :default_formatter, format: "$time $metadata[$level] $message\n"
-```
-
-### Mix Task Separator
-```elixir
-# OLD — comma separator
-mix do compile, test
-
-# NEW (1.17+) — plus separator
-mix do compile + test
-```
-
-### mix cli/0 Replaces Multiple Config Keys
-```elixir
-# OLD
-def project do
- [default_task: "phx.server",
- preferred_cli_env: [test: :test],
- preferred_cli_target: [...]]
-end
-
-# NEW
-def cli do
- [default_task: "phx.server",
- preferred_envs: [test: :test],
- preferred_targets: [...]]
-end
-```
-
----
-
-## Core Language Patterns
-
-### The Pipeline Principle
-Elixir code flows through transformations via `|>`. Design functions to take the "subject" as the first argument.
-
-```elixir
-orders
-|> Enum.filter(&(&1.status == :pending))
-|> Enum.sort_by(& &1.created_at, DateTime)
-|> Enum.map(&process_order/1)
-```
-
-### Pattern Matching — The Heart of Elixir
-```elixir
-# Function head matching — preferred over conditionals
-def process(%Order{status: :pending} = order), do: ship(order)
-def process(%Order{status: :shipped} = order), do: track(order)
-def process(%Order{status: :delivered}), do: :noop
-
-# Pin operator to match against existing values
-expected = "hello"
-^expected = some_function() # Asserts equality
-
-# Map/struct matching is partial — only listed keys must match
-%{name: name} = %{name: "Michael", age: 42} # name = "Michael"
-```
-
-### With Expressions for Happy-Path Chaining
-```elixir
-with {:ok, user} <- fetch_user(id),
- {:ok, account} <- fetch_account(user),
- {:ok, balance} <- check_balance(account) do
- {:ok, balance}
-else
- {:error, :not_found} -> {:error, "User not found"}
- {:error, :insufficient} -> {:error, "Insufficient funds"}
- error -> {:error, "Unknown: #{inspect(error)}"}
-end
-```
-
-### Structs and Protocols
-```elixir
-defmodule Money do
- defstruct [:amount, :currency]
-
- defimpl String.Chars do
- def to_string(%Money{amount: a, currency: c}), do: "#{a} #{c}"
- end
-
- defimpl Inspect do
- def inspect(%Money{amount: a, currency: c}, _opts) do
- "#Money<#{a} #{c}>"
- end
- end
-end
-```
-
-### Behaviours for Contracts
-```elixir
-defmodule PaymentProvider do
- @callback charge(amount :: integer(), currency :: String.t()) ::
- {:ok, transaction_id :: String.t()} | {:error, reason :: term()}
- @callback refund(transaction_id :: String.t()) ::
- {:ok, term()} | {:error, reason :: term()}
-end
-
-defmodule Stripe do
- @behaviour PaymentProvider
-
- @impl true
- def charge(amount, currency), do: # ...
-
- @impl true
- def refund(transaction_id), do: # ...
-end
-```
-
----
-
-## Concurrency Model — BEAM Processes
-
-### Fundamentals
-- **Processes are cheap** — ~2KB initial memory, microseconds to spawn, millions can run concurrently
-- **No shared memory** — processes communicate via message passing only
-- **Each process has its own heap** — GC is per-process, no stop-the-world pauses
-- **Preemptive scheduling** — one scheduler per CPU core, ~4000 reductions then yield
-- **Process isolation** — one process crashing doesn't affect others
-
-### Spawning and Messaging
-```elixir
-# Basic spawn + message passing
-pid = spawn(fn ->
- receive do
- {:greet, name} -> IO.puts("Hello, #{name}!")
- end
-end)
-
-send(pid, {:greet, "Michael"})
-
-# Linked processes — bidirectional crash propagation
-pid = spawn_link(fn -> raise "boom" end) # Caller also crashes
-
-# Monitored processes — one-directional crash notification
-ref = Process.monitor(pid)
-receive do
- {:DOWN, ^ref, :process, ^pid, reason} -> IO.puts("Crashed: #{reason}")
-end
-```
-
-### Task — Structured Concurrency
-```elixir
-# Fire and forget
-Task.start(fn -> send_email(user) end)
-
-# Async/await (linked to caller)
-task = Task.async(fn -> expensive_computation() end)
-result = Task.await(task, 30_000) # 30s timeout
-
-# Parallel map
-Task.async_stream(urls, &fetch_url/1, max_concurrency: 10, timeout: 15_000)
-|> Enum.to_list()
-```
-
-### GenServer — Stateful Server Processes
-```elixir
-defmodule Counter do
- use GenServer
-
- # Client API
- def start_link(initial \\ 0), do: GenServer.start_link(__MODULE__, initial, name: __MODULE__)
- def increment, do: GenServer.cast(__MODULE__, :increment)
- def get, do: GenServer.call(__MODULE__, :get)
-
- # Server callbacks
- @impl true
- def init(initial), do: {:ok, initial}
-
- @impl true
- def handle_cast(:increment, count), do: {:noreply, count + 1}
-
- @impl true
- def handle_call(:get, _from, count), do: {:reply, count, count}
-
- @impl true
- def handle_info(:tick, count) do
- IO.puts("Count: #{count}")
- Process.send_after(self(), :tick, 1000)
- {:noreply, count}
- end
-end
-```
-
-**Key design principle:** GenServer callbacks run sequentially in a single process — this is both the synchronization mechanism and the potential bottleneck. Keep callbacks fast; delegate heavy work to spawned tasks.
-
-### Supervisors — Let It Crash
-```elixir
-defmodule MyApp.Application do
- use Application
-
- @impl true
- def start(_type, _args) do
- children = [
- # Order matters — started top to bottom, stopped bottom to top
- MyApp.Repo, # Ecto repo
- {MyApp.Cache, []}, # Custom GenServer
- {Task.Supervisor, name: MyApp.TaskSupervisor},
- MyAppWeb.Endpoint # Phoenix endpoint last
- ]
-
- opts = [strategy: :one_for_one, name: MyApp.Supervisor]
- Supervisor.start_link(children, opts)
- end
-end
-```
-
-**Restart strategies:**
-- `:one_for_one` — only restart the crashed child (most common)
-- `:one_for_all` — restart all children if any crashes (tightly coupled)
-- `:rest_for_one` — restart crashed child and all children started after it
-
-### DynamicSupervisor — Runtime Child Management
-```elixir
-defmodule MyApp.SessionSupervisor do
- use DynamicSupervisor
-
- def start_link(_), do: DynamicSupervisor.start_link(__MODULE__, :ok, name: __MODULE__)
- def init(:ok), do: DynamicSupervisor.init(strategy: :one_for_one)
-
- def start_session(session_id) do
- spec = {MyApp.Session, session_id}
- DynamicSupervisor.start_child(__MODULE__, spec)
- end
-end
-```
-
----
-
-## OTP Releases & Deployment
-
-### Building a Release
-```bash
-# Generate release config (Phoenix projects)
-mix phx.gen.release
-
-# Build the release
-MIX_ENV=prod mix release
-
-# The release is self-contained — no Erlang/Elixir needed on target
-_build/prod/rel/my_app/bin/my_app start # Foreground
-_build/prod/rel/my_app/bin/my_app daemon # Background
-_build/prod/rel/my_app/bin/my_app remote # Attach IEx to running node
-_build/prod/rel/my_app/bin/my_app eval "MyApp.Seeds.run()" # One-off command
-```
-
-### Release Configuration Files
-- `config/config.exs` — **compile-time** config (before code compiles)
-- `config/runtime.exs` — **runtime** config (executed on every boot) — use for env vars, secrets
-- `rel/env.sh.eex` — shell environment for the release (VM flags, env vars)
-- `rel/vm.args.eex` — Erlang VM flags (node name, cookie, memory limits)
-
-### Docker Multistage Build Pattern
-```dockerfile
-# === Builder Stage ===
-FROM hexpm/elixir:1.19.5-erlang-27.3-debian-bookworm-20250317 AS builder
-
-RUN apt-get update -y && apt-get install -y build-essential git && apt-get clean
-WORKDIR /app
-
-ENV MIX_ENV=prod
-RUN mix local.hex --force && mix local.rebar --force
-
-COPY mix.exs mix.lock ./
-RUN mix deps.get --only prod && mix deps.compile
-
-COPY config/config.exs config/prod.exs config/
-COPY priv priv
-COPY lib lib
-COPY assets assets # If Phoenix
-
-RUN mix assets.deploy # If Phoenix
-RUN mix compile
-RUN mix release
-
-# === Runner Stage ===
-FROM debian:bookworm-slim AS runner
-
-RUN apt-get update -y && \
- apt-get install -y libstdc++6 openssl libncurses5 locales ca-certificates && \
- apt-get clean && rm -f /var/lib/apt/lists/*_*
-
-ENV LANG=en_US.UTF-8
-RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
-
-WORKDIR /app
-RUN useradd --create-home app && chown -R app:app /app
-USER app
-
-COPY --from=builder --chown=app:app /app/_build/prod/rel/my_app ./
-
-CMD ["bin/my_app", "start"]
-```
-
-### Distributed Erlang in Production
-```elixir
-# In rel/env.sh.eex — set node name and cookie
-export RELEASE_DISTRIBUTION=name
-export RELEASE_NODE=my_app@${HOSTNAME}
-export RELEASE_COOKIE=my_secret_cookie
-
-# Or in runtime.exs
-config :my_app, MyApp.Cluster,
- strategy: Cluster.Strategy.DNSPoll,
- config: [
- polling_interval: 5_000,
- query: "my-app.local",
- node_basename: "my_app"
- ]
-```
-
-**Key libraries for clustering:** `libcluster` (automatic node discovery), `Horde` (distributed supervisor/registry), `Phoenix.PubSub` (cross-node pub/sub already built into Phoenix).
-
----
-
-## Monitoring & Instrumentation
-
-### The Elixir Observability Stack
-- **PromEx** — Elixir library exposing `/metrics` endpoint for Prometheus scraping. Includes plugins for Phoenix, Ecto, LiveView, BEAM VM, Oban
-- **Prometheus** — scrapes and stores time-series metrics
-- **Loki** + **Promtail** — log aggregation (Promtail scrapes Docker container logs → Loki stores)
-- **Grafana** — visualization dashboards for both metrics and logs
-- **Alloy** — OpenTelemetry collector bridging metrics to Prometheus
-
-### Adding PromEx to a Phoenix App
-```elixir
-# mix.exs
-{:prom_ex, "~> 1.9"}
-
-# lib/my_app/prom_ex.ex
-defmodule MyApp.PromEx do
- use PromEx, otp_app: :my_app
-
- @impl true
- def plugins do
- [
- PromEx.Plugins.Application,
- PromEx.Plugins.Beam,
- {PromEx.Plugins.Phoenix, router: MyAppWeb.Router},
- {PromEx.Plugins.Ecto, repos: [MyApp.Repo]},
- PromEx.Plugins.Oban
- ]
- end
-
- @impl true
- def dashboards do
- [{:prom_ex, "application.json"}, {:prom_ex, "beam.json"},
- {:prom_ex, "phoenix.json"}, {:prom_ex, "ecto.json"}]
- end
-end
-```
-
-### Key BEAM Metrics to Watch
-- `erlang_vm_process_count` — total BEAM processes (normal: thousands, alarm at millions)
-- `erlang_vm_memory_bytes_total` — total VM memory
-- `erlang_vm_atom_count` — atoms are never GC'd; watch for leaks
-- `phoenix_endpoint_stop_duration_milliseconds` — request latency
-- `ecto_repo_query_duration_milliseconds` — database query time
-
----
-
-## usage_rules — AI Agent Documentation
-
-**Always include in every project.** This is non-negotiable.
-
-```elixir
-# mix.exs deps
-{:usage_rules, "~> 1.1", only: [:dev]}
-
-# mix.exs project config
-def project do
- [
- # ... other config
- usage_rules: [
- packages: :all, # Or specific: ["phoenix", "ecto", ~r/ash/]
- output: :agents_md, # Generates AGENTS.md
- mode: :linked # Or :inlined for single-file
- ]
- ]
-end
-```
-
-**Key commands:**
-```bash
-mix usage_rules.gen # Generate AGENTS.md from deps
-mix usage_rules.search_docs # Search hex documentation
-mix usage_rules.gen_skill # Generate SKILL.md for Cowork
-```
-
-This consolidates `usage-rules.md` files from all dependencies into a single reference document, giving any AI agent working on the project full context about library APIs, patterns, and conventions.
-
----
-
-## Ash Framework — Production Backend
-
-Ash is a **declarative, resource-oriented** framework for building Elixir backends. Use it for substantial projects — it handles data layer, authorization, validation, and API generation.
-
-### Core Concepts
-- **Resources** — the central abstraction (like models but richer): attributes, actions, relationships, calculations, aggregates, policies
-- **Domains** — organizational containers that group related resources and define the public API
-- **Actions** — CRUD + custom actions defined declaratively on resources
-- **Data Layers** — pluggable persistence (AshPostgres, AshSqlite, ETS for dev)
-- **Policies** — declarative authorization rules on resources/actions
-- **Extensions** — AshPhoenix, AshGraphql, AshJsonApi, AshAuthentication, AshOban
-
-### Quick Start
-```bash
-mix igniter.new my_app --install ash,ash_postgres,ash_phoenix
-```
-
-### Resource Example
-```elixir
-defmodule MyApp.Blog.Post do
- use Ash.Resource,
- domain: MyApp.Blog,
- data_layer: AshPostgres.DataLayer
-
- postgres do
- table "posts"
- repo MyApp.Repo
- end
-
- attributes do
- uuid_primary_key :id
- attribute :title, :string, allow_nil?: false
- attribute :body, :string, allow_nil?: false
- attribute :status, :atom, constraints: [one_of: [:draft, :published]], default: :draft
- timestamps()
- end
-
- actions do
- defaults [:read, :destroy]
-
- create :create do
- accept [:title, :body]
- end
-
- update :publish do
- change set_attribute(:status, :published)
- change set_attribute(:published_at, &DateTime.utc_now/0)
- end
- end
-
- relationships do
- belongs_to :author, MyApp.Accounts.User
- has_many :comments, MyApp.Blog.Comment
- end
-
- policies do
- policy action_type(:create) do
- authorize_if actor_attribute_equals(:role, :author)
- end
- policy action_type(:read) do
- authorize_if always()
- end
- end
-end
-```
-
-### Domain Example
-```elixir
-defmodule MyApp.Blog do
- use Ash.Domain
-
- resources do
- resource MyApp.Blog.Post
- resource MyApp.Blog.Comment
- end
-end
-```
-
-### Using Resources
-```elixir
-# Create
-MyApp.Blog.Post
-|> Ash.Changeset.for_create(:create, %{title: "Hello", body: "World"})
-|> Ash.create!()
-
-# Read with filters
-MyApp.Blog.Post
-|> Ash.Query.filter(status == :published)
-|> Ash.Query.sort(inserted_at: :desc)
-|> Ash.Query.limit(10)
-|> Ash.read!()
-
-# Custom action
-post |> Ash.Changeset.for_update(:publish) |> Ash.update!()
-```
-
----
-
-## Mix Project Structure
-
-```
-my_app/
-├── config/
-│ ├── config.exs # Compile-time config
-│ ├── dev.exs
-│ ├── prod.exs
-│ ├── runtime.exs # Runtime config (secrets, env vars)
-│ └── test.exs
-├── lib/
-│ ├── my_app/
-│ │ ├── application.ex # OTP Application + supervisor tree
-│ │ ├── repo.ex # Ecto Repo
-│ │ └── ... # Domain modules
-│ └── my_app_web/ # Phoenix web layer (if applicable)
-│ ├── endpoint.ex
-│ ├── router.ex
-│ ├── controllers/
-│ ├── live/ # LiveView modules
-│ └── components/
-├── priv/
-│ ├── repo/migrations/
-│ └── static/
-├── test/
-│ ├── support/
-│ └── ...
-├── mix.exs
-├── mix.lock
-├── .formatter.exs
-└── AGENTS.md # Generated by usage_rules
-```
-
----
-
-## Testing
-
-```elixir
-# test/my_app/blog_test.exs
-defmodule MyApp.BlogTest do
- use MyApp.DataCase, async: true # Async when no shared state
-
- describe "creating posts" do
- test "creates with valid attributes" do
- assert {:ok, post} = Blog.create_post(%{title: "Hi", body: "World"})
- assert post.title == "Hi"
- assert post.status == :draft
- end
-
- test "fails without title" do
- assert {:error, changeset} = Blog.create_post(%{body: "World"})
- assert "can't be blank" in errors_on(changeset).title
- end
- end
-end
-```
-
-**Testing philosophy:** Use `async: true` wherever possible. Ecto's SQL Sandbox allows concurrent test execution. For GenServer tests, start under a test supervisor. For external services, use `Mox` for behaviour-based mocking.
-
----
-
-## Phoenix Framework — v1.8.5 (Current)
-
-Phoenix is the web framework for Elixir. Version 1.8.5 is current. It provides MVC controllers, real-time LiveView, Channels for WebSocket communication, and comprehensive tooling for authentication, testing, and deployment.
-
-### What's New in Phoenix 1.8
-
-- **Scopes** in generators — secure data access by default (e.g., `current_user` automatically applied)
-- **Magic links** (passwordless auth) and **"sudo mode"** in `mix phx.gen.auth`
-- **daisyUI** integration — light/dark/system mode support out of the box
-- **Simplified layouts** — single `root.html.heex` wraps everything; dynamic layouts are function components
-- **`use Phoenix.Controller` now requires `:formats`** — must specify `formats: [:html]` or `formats: [:html, :json]`
-- **Updated security headers** — `content-security-policy` with `base-uri 'self'; frame-ancestors 'self'`; dropped deprecated `x-frame-options` and `x-download-options`
-- **`config` variable removed** from `Phoenix.Endpoint` — use `Application.compile_env/3` instead
-- **Deprecated**: `:namespace`, `:put_default_views`, layouts without modules, `:trailing_slash` in router
-
-### Project Setup
-
-```bash
-# New project (Phoenix Express — quickest path)
-curl https://new.phoenixframework.org/my_app | sh
-
-# Traditional setup
-mix phx.new my_app
-mix phx.new my_app --no-ecto # Without database
-mix phx.new my_app --no-html # API only
-mix phx.new my_app --database sqlite3 # SQLite instead of Postgres
-```
-
-### Directory Structure
-
-```
-my_app/
-├── lib/
-│ ├── my_app/ # Business logic (contexts, schemas)
-│ │ ├── application.ex # Supervision tree
-│ │ ├── repo.ex # Ecto Repo
-│ │ └── catalog/ # Context: Catalog
-│ │ ├── product.ex # Schema
-│ │ └── catalog.ex # Context module
-│ └── my_app_web/ # Web layer
-│ ├── endpoint.ex # HTTP entry point
-│ ├── router.ex # Routes + pipelines
-│ ├── components/
-│ │ ├── core_components.ex # Shared UI components
-│ │ └── layouts.ex # Layout components
-│ ├── controllers/
-│ │ ├── page_controller.ex
-│ │ └── page_html/ # Templates for controller
-│ │ └── home.html.heex
-│ └── live/ # LiveView modules
-│ └── counter_live.ex
-├── config/
-│ ├── config.exs # Compile-time config
-│ ├── dev.exs / prod.exs
-│ └── runtime.exs # Runtime config (env vars, secrets)
-├── priv/
-│ ├── repo/migrations/
-│ └── static/ # Static assets
-├── test/
-│ ├── support/
-│ │ ├── conn_case.ex # Test helpers for controllers
-│ │ └── data_case.ex # Test helpers for data layer
-│ └── my_app_web/
-└── mix.exs
-```
-
-### Router & Pipelines
-
-```elixir
-defmodule MyAppWeb.Router do
- use MyAppWeb, :router
-
- pipeline :browser do
- plug :accepts, ["html"]
- plug :fetch_session
- plug :fetch_live_flash
- plug :put_root_layout, html: {MyAppWeb.Layouts, :root}
- plug :protect_from_forgery
- plug :put_secure_browser_headers
- end
-
- pipeline :api do
- plug :accepts, ["json"]
- end
-
- scope "/", MyAppWeb do
- pipe_through :browser
-
- get "/", PageController, :home
- live "/counter", CounterLive # LiveView route
- resources "/products", ProductController # RESTful CRUD
- end
-
- scope "/api", MyAppWeb do
- pipe_through :api
-
- resources "/items", ItemController, except: [:new, :edit]
- end
-end
-```
-
-### Verified Routes — `~p` Sigil
-
-**Always use `~p` instead of string paths.** Compile-time verified against your router.
-
-```elixir
-# In templates (HEEx)
-~H"""
-View
-Edit
-"""
-
-# In controllers
-redirect(conn, to: ~p"/products/#{product}")
-
-# With query params
-~p"/products?page=#{page}&sort=name"
-~p"/products?#{%{page: 1, sort: "name"}}"
-
-# URL generation (includes host)
-url(~p"/products/#{product}")
-# => "https://example.com/products/42"
-```
-
-### Controllers (1.8 Style)
-
-```elixir
-defmodule MyAppWeb.ProductController do
- use MyAppWeb, :controller
-
- # REQUIRED in 1.8: specify formats
- # This is typically set in MyAppWeb :controller function
-
- def index(conn, _params) do
- products = Catalog.list_products()
- render(conn, :index, products: products)
- end
-
- def show(conn, %{"id" => id}) do
- product = Catalog.get_product!(id)
- render(conn, :show, product: product)
- end
-
- def create(conn, %{"product" => product_params}) do
- case Catalog.create_product(product_params) do
- {:ok, product} ->
- conn
- |> put_flash(:info, "Product created.")
- |> redirect(to: ~p"/products/#{product}")
-
- {:error, %Ecto.Changeset{} = changeset} ->
- render(conn, :new, changeset: changeset)
- end
- end
-end
-```
-
-**View module naming:** For `ProductController`, Phoenix looks for `ProductHTML` (for `:html` format) and `ProductJSON` (for `:json` format).
-
-```elixir
-# lib/my_app_web/controllers/product_html.ex
-defmodule MyAppWeb.ProductHTML do
- use MyAppWeb, :html
- embed_templates "product_html/*" # Loads .heex files from directory
-end
-
-# lib/my_app_web/controllers/product_json.ex
-defmodule MyAppWeb.ProductJSON do
- def index(%{products: products}), do: %{data: for(p <- products, do: data(p))}
- def show(%{product: product}), do: %{data: data(product)}
- defp data(product), do: %{id: product.id, title: product.title, price: product.price}
-end
-```
-
-### Components and HEEx
-
-```elixir
-defmodule MyAppWeb.CoreComponents do
- use Phoenix.Component
-
- # Declare attributes with types and docs
- attr :type, :string, default: "button"
- attr :class, :string, default: nil
- attr :rest, :global # Passes through all other HTML attrs
- slot :inner_block, required: true
-
- def button(assigns) do
- ~H"""
-
- """
- end
-
- # Table component with slots
- attr :rows, :list, required: true
- slot :col, required: true do
- attr :label, :string
- end
-
- def table(assigns) do
- ~H"""
-
-
-
- | {col[:label]} |
-
-
-
-
- | {render_slot(col, row)} |
-
-
-
- """
- end
-end
-```
-
-**HEEx syntax notes:**
-- `{@var}` — render assign (curly braces, not `<%= %>`)
-- `:if={condition}` — conditional rendering on any tag
-- `:for={item <- list}` — iteration on any tag
-- `<.component_name />` — call function component with dot notation
-- `` — call remote component with module name
-- `{render_slot(@inner_block)}` — render slot content
-- `<:slot_name>content` — named slot content
-
-### LiveView
-
-```elixir
-defmodule MyAppWeb.SearchLive do
- use MyAppWeb, :live_view
-
- def mount(_params, _session, socket) do
- {:ok, assign(socket, query: "", results: [])}
- end
-
- def handle_params(%{"q" => query}, _uri, socket) do
- {:noreply, assign(socket, query: query, results: search(query))}
- end
-
- def handle_params(_params, _uri, socket), do: {:noreply, socket}
-
- def handle_event("search", %{"query" => query}, socket) do
- {:noreply,
- socket
- |> assign(query: query, results: search(query))
- |> push_patch(to: ~p"/search?q=#{query}")}
- end
-
- def render(assigns) do
- ~H"""
-
-
-
-
-
{result.title}
-
{result.summary}
-
-
Count: {@count}
-
-
- """
- end
-end
-```
-
----
-
-## Resources
-
-- [Elixir Official Docs](https://hexdocs.pm/elixir/) — always check 1.19.5 version
-- [Ash Framework Docs](https://hexdocs.pm/ash/) — resource-oriented patterns
-- [Phoenix HexDocs](https://hexdocs.pm/phoenix/) — web framework
-- [Elixir Forum](https://elixirforum.com/) — community Q&A
-- [Elixir School](https://elixirschool.com/) — learning resource
-- "Elixir in Action" by Saša Jurić — deep BEAM/OTP understanding (note: covers 1.15, check breaking changes above)
-- "Engineering Elixir Applications" by Fairholm & D'Lacoste — BEAMOps deployment patterns
diff --git a/elixir/elixir-part1-core.md b/elixir/elixir-part1-core.md
new file mode 100644
index 0000000..219d04c
--- /dev/null
+++ b/elixir/elixir-part1-core.md
@@ -0,0 +1,208 @@
+# Elixir Part 1: Core Language & Modern Idioms
+
+## Elixir 1.19 — What's New
+
+### Gradual Set-Theoretic Type System
+
+Elixir 1.19 significantly advances the built-in type system. It is **sound**, **gradual**, and **set-theoretic** (types compose via union, intersection, negation).
+
+**Current capabilities (1.19):**
+- Type inference from existing code — no annotations required yet
+- **Protocol dispatch type checking** — warns on invalid protocol usage (e.g., string interpolation on structs without `String.Chars`)
+- **Anonymous function type inference** — `fn` literals and `&captures` propagate types
+- Types: `atom()`, `binary()`, `integer()`, `float()`, `pid()`, `port()`, `reference()`, `tuple()`, `list()`, `map()`, `function()`
+- Compose: `atom() or integer()` (union), `atom() and not nil` (difference)
+- `dynamic()` type for gradual typing — runtime-checked values
+- Tuple precision: `{:ok, binary()}`, open tuples: `{:ok, binary(), ...}`
+- Map types: `%{key: value}` closed, `%{optional(atom()) => term()}` open
+- Function types: `(integer() -> boolean())`
+
+### Up to 4x Faster Compilation
+
+1. **Lazy module loading** — modules no longer loaded when defined; parallel compiler controls loading
+2. **Parallel dependency compilation** — set `MIX_OS_DEPS_COMPILE_PARTITION_COUNT` env var
+
+**Caveat:** If spawning processes during compilation that invoke sibling modules, use `Code.ensure_compiled!/1` first.
+
+### Other 1.19 Features
+
+- `min/2` and `max/2` allowed in guards
+- `Access.values/0` — traverse all values in a map/keyword
+- `String.count/2` — count occurrences
+- Unicode 17.0.0, multi-line IEx prompts
+- `mix help Mod.fun/arity`
+- Erlang/OTP 28 support
+
+---
+
+## Breaking Changes Since 1.15
+
+### Struct Update Syntax (1.18+)
+```elixir
+# The compiler now verifies the variable matches the struct type
+%URI{my_uri | path: "/new"} # my_uri must be verified as %URI{}
+```
+
+### Regex as Struct Field Defaults (OTP 28)
+```elixir
+# BROKEN on OTP 28 — regex can't be struct field defaults
+defstruct pattern: ~r/foo/ # Compile error
+# FIX: use nil default, set at runtime
+```
+
+### Logger Backends Deprecated
+```elixir
+# OLD: config :logger, backends: [:console]
+# NEW: use LoggerHandler (Erlang's logger)
+config :logger, :default_handler, []
+```
+
+### Mix Task Separator
+```elixir
+# OLD: mix do compile, test
+# NEW: mix do compile + test
+```
+
+### mix cli/0 Replaces Config Keys
+```elixir
+# OLD: default_task, preferred_cli_env in project/0
+# NEW: def cli, do: [default_task: "phx.server", preferred_envs: [test: :test]]
+```
+
+---
+
+## Core Language Patterns
+
+### The Pipeline
+```elixir
+orders
+|> Enum.filter(&(&1.status == :pending))
+|> Enum.sort_by(& &1.created_at, DateTime)
+|> Enum.map(&process_order/1)
+```
+
+### Pattern Matching
+```elixir
+# Function head matching — preferred over conditionals
+def process(%Order{status: :pending} = order), do: ship(order)
+def process(%Order{status: :shipped} = order), do: track(order)
+def process(%Order{status: :delivered}), do: :noop
+
+# Pin operator
+expected = "hello"
+^expected = some_function()
+
+# Partial map matching
+%{name: name} = %{name: "Michael", age: 42}
+```
+
+### With Expressions
+```elixir
+with {:ok, user} <- fetch_user(id),
+ {:ok, account} <- fetch_account(user),
+ {:ok, balance} <- check_balance(account) do
+ {:ok, balance}
+else
+ {:error, :not_found} -> {:error, "User not found"}
+ error -> {:error, "Unknown: #{inspect(error)}"}
+end
+```
+
+### Structs and Protocols
+```elixir
+defmodule Money do
+ defstruct [:amount, :currency]
+
+ defimpl String.Chars do
+ def to_string(%Money{amount: a, currency: c}), do: "#{a} #{c}"
+ end
+end
+```
+
+### Behaviours
+```elixir
+defmodule PaymentProvider do
+ @callback charge(integer(), String.t()) :: {:ok, String.t()} | {:error, term()}
+ @callback refund(String.t()) :: {:ok, term()} | {:error, term()}
+end
+
+defmodule Stripe do
+ @behaviour PaymentProvider
+ @impl true
+ def charge(amount, currency), do: # ...
+ @impl true
+ def refund(transaction_id), do: # ...
+end
+```
+
+---
+
+## Mix Project Structure
+
+```
+my_app/
+├── config/
+│ ├── config.exs # Compile-time config
+│ ├── dev.exs / prod.exs / test.exs
+│ └── runtime.exs # Runtime config (secrets, env vars)
+├── lib/
+│ ├── my_app/
+│ │ ├── application.ex # OTP Application + supervisor tree
+│ │ └── ... # Domain modules
+│ └── my_app_web/ # Phoenix web layer (if applicable)
+├── priv/repo/migrations/
+├── test/
+├── mix.exs
+├── .formatter.exs
+└── AGENTS.md # Generated by usage_rules
+```
+
+---
+
+## Testing
+
+```elixir
+defmodule MyApp.BlogTest do
+ use MyApp.DataCase, async: true
+
+ describe "creating posts" do
+ test "creates with valid attributes" do
+ assert {:ok, post} = Blog.create_post(%{title: "Hi", body: "World"})
+ assert post.title == "Hi"
+ end
+
+ test "fails without title" do
+ assert {:error, changeset} = Blog.create_post(%{body: "World"})
+ assert "can't be blank" in errors_on(changeset).title
+ end
+ end
+end
+```
+
+Use `async: true` wherever possible. Use `Mox` for behaviour-based mocking.
+
+---
+
+## usage_rules — AI Agent Documentation
+
+**Always include in every project.**
+
+```elixir
+# mix.exs deps
+{:usage_rules, "~> 1.1", only: [:dev]}
+
+# mix.exs project config
+usage_rules: [packages: :all, output: :agents_md, mode: :linked]
+```
+
+```bash
+mix usage_rules.gen # Generate AGENTS.md from deps
+mix usage_rules.search_docs # Search hex documentation
+mix usage_rules.gen_skill # Generate SKILL.md for Cowork
+```
+
+---
+
+## Pro Tip: Local Docs
+
+Elixir packages ship excellent local documentation. Once Elixir is installed on cortex, accessing docs locally via `mix hex.docs fetch ` or `h Module.function` in IEx may be more efficient than fetching URLs. Consider installing Elixir on cortex to enable this workflow.
diff --git a/elixir/elixir-part2-concurrency.md b/elixir/elixir-part2-concurrency.md
new file mode 100644
index 0000000..08e4a26
--- /dev/null
+++ b/elixir/elixir-part2-concurrency.md
@@ -0,0 +1,278 @@
+# Elixir Part 2: Concurrency, OTP & State Machines
+
+## BEAM Process Fundamentals
+
+- **Processes are cheap** — ~2KB initial memory, microseconds to spawn, millions concurrent
+- **No shared memory** — message passing only
+- **Per-process GC** — no stop-the-world pauses
+- **Preemptive scheduling** — one scheduler per CPU core, ~4000 reductions then yield
+- **Process isolation** — one crash doesn't affect others
+
+### Spawning and Messaging
+```elixir
+pid = spawn(fn ->
+ receive do
+ {:greet, name} -> IO.puts("Hello, #{name}!")
+ end
+end)
+send(pid, {:greet, "Michael"})
+
+# Linked — bidirectional crash propagation
+pid = spawn_link(fn -> raise "boom" end)
+
+# Monitored — one-directional crash notification
+ref = Process.monitor(pid)
+receive do
+ {:DOWN, ^ref, :process, ^pid, reason} -> handle_crash(reason)
+end
+```
+
+### Task — Structured Concurrency
+```elixir
+Task.start(fn -> send_email(user) end) # Fire and forget
+task = Task.async(fn -> expensive_computation() end) # Async/await
+result = Task.await(task, 30_000)
+
+Task.async_stream(urls, &fetch_url/1, max_concurrency: 10) # Parallel map
+|> Enum.to_list()
+```
+
+---
+
+## GenServer — Stateful Server Processes
+
+```elixir
+defmodule Counter do
+ use GenServer
+
+ # Client API
+ def start_link(initial \\ 0), do: GenServer.start_link(__MODULE__, initial, name: __MODULE__)
+ def increment, do: GenServer.cast(__MODULE__, :increment)
+ def get, do: GenServer.call(__MODULE__, :get)
+
+ # Server callbacks
+ @impl true
+ def init(initial), do: {:ok, initial}
+
+ @impl true
+ def handle_cast(:increment, count), do: {:noreply, count + 1}
+
+ @impl true
+ def handle_call(:get, _from, count), do: {:reply, count, count}
+
+ @impl true
+ def handle_info(:tick, count) do
+ Process.send_after(self(), :tick, 1000)
+ {:noreply, count}
+ end
+end
+```
+
+**Key principle:** Callbacks run sequentially — this is both the synchronization mechanism and potential bottleneck. Keep callbacks fast; delegate heavy work to spawned tasks.
+
+---
+
+## GenStateMachine — State Machines for Agentic Workflows
+
+**Why GenStateMachine over GenServer for agents?** GenServer has a single state and handles all messages uniformly. GenStateMachine (wrapping Erlang's `:gen_statem`) provides:
+- **Explicit states** with per-state event handling
+- **Built-in timeouts** — state timeouts (reset on state change), generic timeouts, event timeouts
+- **Postpone** — defer events until the right state
+- **State enter callbacks** — run setup logic when entering a state
+- **Event types** — distinguish calls, casts, info, timeouts, internal events
+
+These map naturally onto agentic patterns: an agent in "thinking" state ignores new requests (postpone), has retry timeouts, transitions through well-defined phases, and runs setup on each state entry.
+
+### Installation
+```elixir
+{:gen_state_machine, "~> 3.0"}
+```
+
+### Callback Modes
+
+**`:handle_event_function`** (default) — single `handle_event/4` for all states:
+```elixir
+defmodule AgentFSM do
+ use GenStateMachine
+
+ # Client API
+ def start_link(opts), do: GenStateMachine.start_link(__MODULE__, opts)
+ def submit(pid, task), do: GenStateMachine.call(pid, {:submit, task})
+ def status(pid), do: GenStateMachine.call(pid, :status)
+
+ # Server callbacks
+ def init(opts) do
+ {:ok, :idle, %{tasks: [], results: [], config: opts}}
+ end
+
+ # State: idle
+ def handle_event({:call, from}, {:submit, task}, :idle, data) do
+ {:next_state, :processing, %{data | tasks: [task]},
+ [{:reply, from, :accepted}, {:state_timeout, 30_000, :timeout}]}
+ end
+
+ def handle_event({:call, from}, :status, state, data) do
+ {:keep_state_and_data, [{:reply, from, {state, length(data.results)}}]}
+ end
+
+ # State: processing — with timeout
+ def handle_event(:state_timeout, :timeout, :processing, data) do
+ {:next_state, :error, %{data | error: :timeout}}
+ end
+
+ # Internal event for completion
+ def handle_event(:info, {:result, result}, :processing, data) do
+ {:next_state, :complete, %{data | results: [result | data.results]}}
+ end
+
+ # Postpone submissions while processing
+ def handle_event({:call, _from}, {:submit, _task}, :processing, _data) do
+ {:keep_state_and_data, :postpone}
+ end
+end
+```
+
+**`:state_functions`** — each state is a separate function (states must be atoms):
+```elixir
+defmodule WorkflowFSM do
+ use GenStateMachine, callback_mode: [:state_functions, :state_enter]
+
+ def init(_), do: {:ok, :pending, %{}}
+
+ # State enter callbacks — run on every state transition
+ def pending(:enter, _old_state, data) do
+ {:keep_state, %{data | entered_at: DateTime.utc_now()}}
+ end
+
+ def pending({:call, from}, {:start, params}, data) do
+ {:next_state, :running, %{data | params: params},
+ [{:reply, from, :ok}, {:state_timeout, 60_000, :execution_timeout}]}
+ end
+
+ def running(:enter, :pending, data) do
+ # Setup when entering running from pending
+ send(self(), :execute)
+ {:keep_state, data}
+ end
+
+ def running(:info, :execute, data) do
+ result = do_work(data.params)
+ {:next_state, :complete, %{data | result: result}}
+ end
+
+ def running(:state_timeout, :execution_timeout, data) do
+ {:next_state, :failed, %{data | error: :timeout}}
+ end
+
+ # Postpone any calls while running
+ def running({:call, _from}, _request, _data) do
+ {:keep_state_and_data, :postpone}
+ end
+
+ def complete(:enter, _old, data), do: {:keep_state, data}
+ def complete({:call, from}, :get_result, data) do
+ {:keep_state_and_data, [{:reply, from, {:ok, data.result}}]}
+ end
+
+ def failed(:enter, _old, data), do: {:keep_state, data}
+ def failed({:call, from}, :get_error, data) do
+ {:keep_state_and_data, [{:reply, from, {:error, data.error}}]}
+ end
+end
+```
+
+### Timeout Types
+
+| Type | Behavior | Use Case |
+|------|----------|----------|
+| `{:timeout, ms, event}` | Generic — survives state changes | Periodic polling |
+| `{:state_timeout, ms, event}` | Resets on state change | Per-state deadlines |
+| `{:event_timeout, ms, event}` | Resets on any event | Inactivity detection |
+
+### Key Actions in Return Tuples
+
+```elixir
+# Return format: {:next_state, new_state, new_data, actions}
+actions = [
+ {:reply, from, response}, # Reply to caller
+ {:state_timeout, 30_000, :deadline}, # State-scoped timeout
+ {:timeout, 5_000, :poll}, # Generic timeout
+ :postpone, # Defer event to next state
+ :hibernate, # Reduce memory footprint
+ {:next_event, :internal, :setup} # Queue internal event
+]
+```
+
+### When to Use GenStateMachine vs GenServer
+
+| Scenario | Use |
+|----------|-----|
+| Simple key-value state, CRUD | GenServer |
+| Request/response server | GenServer |
+| Well-defined state transitions | **GenStateMachine** |
+| Need built-in timeouts per state | **GenStateMachine** |
+| Events valid only in certain states | **GenStateMachine** |
+| Agentic workflow with phases | **GenStateMachine** |
+| Need postpone/defer semantics | **GenStateMachine** |
+
+---
+
+## Supervisors — Let It Crash
+
+```elixir
+defmodule MyApp.Application do
+ use Application
+
+ @impl true
+ def start(_type, _args) do
+ children = [
+ MyApp.Repo,
+ {MyApp.Cache, []},
+ {Task.Supervisor, name: MyApp.TaskSupervisor},
+ MyAppWeb.Endpoint
+ ]
+ opts = [strategy: :one_for_one, name: MyApp.Supervisor]
+ Supervisor.start_link(children, opts)
+ end
+end
+```
+
+**Strategies:**
+- `:one_for_one` — restart only crashed child (most common)
+- `:one_for_all` — restart all if any crashes (tightly coupled)
+- `:rest_for_one` — restart crashed + all started after it
+
+### DynamicSupervisor
+```elixir
+defmodule MyApp.SessionSupervisor do
+ use DynamicSupervisor
+
+ def start_link(_), do: DynamicSupervisor.start_link(__MODULE__, :ok, name: __MODULE__)
+ def init(:ok), do: DynamicSupervisor.init(strategy: :one_for_one)
+
+ def start_session(session_id) do
+ DynamicSupervisor.start_child(__MODULE__, {MyApp.Session, session_id})
+ end
+end
+```
+
+---
+
+## Registry & Process Discovery
+
+```elixir
+# In supervisor
+{Registry, keys: :unique, name: MyApp.Registry}
+
+# Register a process
+Registry.register(MyApp.Registry, "session:#{id}", %{})
+
+# Lookup
+case Registry.lookup(MyApp.Registry, "session:#{id}") do
+ [{pid, _value}] -> {:ok, pid}
+ [] -> {:error, :not_found}
+end
+
+# Use as GenServer name
+GenServer.start_link(MyWorker, arg, name: {:via, Registry, {MyApp.Registry, "worker:#{id}"}})
+```
diff --git a/elixir/elixir-part3-phoenix.md b/elixir/elixir-part3-phoenix.md
new file mode 100644
index 0000000..090b87a
--- /dev/null
+++ b/elixir/elixir-part3-phoenix.md
@@ -0,0 +1,628 @@
+# Elixir Part 3: Phoenix Framework — v1.8.5 (Current)
+
+Phoenix is the web framework for Elixir. Version 1.8.5 is current. It provides MVC controllers, real-time LiveView, Channels for WebSocket communication, and comprehensive tooling for authentication, testing, and deployment.
+
+## What's New in Phoenix 1.8
+
+- **Scopes** in generators — secure data access by default (e.g., `current_user` automatically applied)
+- **Magic links** (passwordless auth) and **"sudo mode"** in `mix phx.gen.auth`
+- **daisyUI** integration — light/dark/system mode support out of the box
+- **Simplified layouts** — single `root.html.heex` wraps everything; dynamic layouts are function components
+- **`use Phoenix.Controller` now requires `:formats`** — must specify `formats: [:html]` or `formats: [:html, :json]`
+- **Updated security headers** — `content-security-policy` with `base-uri 'self'; frame-ancestors 'self'`; dropped deprecated `x-frame-options` and `x-download-options`
+- **`config` variable removed** from `Phoenix.Endpoint` — use `Application.compile_env/3` instead
+- **Deprecated**: `:namespace`, `:put_default_views`, layouts without modules, `:trailing_slash` in router
+
+---
+
+## Project Setup
+
+```bash
+# New project (Phoenix Express — quickest path)
+curl https://new.phoenixframework.org/my_app | sh
+
+# Traditional setup
+mix phx.new my_app
+mix phx.new my_app --no-ecto # Without database
+mix phx.new my_app --no-html # API only
+mix phx.new my_app --database sqlite3 # SQLite instead of Postgres
+```
+
+## Directory Structure
+
+```
+my_app/
+├── lib/
+│ ├── my_app/ # Business logic (contexts, schemas)
+│ │ ├── application.ex # Supervision tree
+│ │ ├── repo.ex # Ecto Repo
+│ │ └── catalog/ # Context: Catalog
+│ │ ├── product.ex # Schema
+│ │ └── catalog.ex # Context module
+│ └── my_app_web/ # Web layer
+│ ├── endpoint.ex # HTTP entry point
+│ ├── router.ex # Routes + pipelines
+│ ├── components/
+│ │ ├── core_components.ex # Shared UI components
+│ │ └── layouts.ex # Layout components
+│ ├── controllers/
+│ │ ├── page_controller.ex
+│ │ └── page_html/ # Templates for controller
+│ │ └── home.html.heex
+│ └── live/ # LiveView modules
+│ └── counter_live.ex
+├── config/
+│ ├── config.exs # Compile-time config
+│ ├── dev.exs / prod.exs
+│ └── runtime.exs # Runtime config (env vars, secrets)
+├── priv/
+│ ├── repo/migrations/
+│ └── static/ # Static assets
+├── test/
+│ ├── support/
+│ │ ├── conn_case.ex # Test helpers for controllers
+│ │ └── data_case.ex # Test helpers for data layer
+│ └── my_app_web/
+└── mix.exs
+```
+
+---
+
+## Router & Pipelines
+
+```elixir
+defmodule MyAppWeb.Router do
+ use MyAppWeb, :router
+
+ pipeline :browser do
+ plug :accepts, ["html"]
+ plug :fetch_session
+ plug :fetch_live_flash
+ plug :put_root_layout, html: {MyAppWeb.Layouts, :root}
+ plug :protect_from_forgery
+ plug :put_secure_browser_headers
+ end
+
+ pipeline :api do
+ plug :accepts, ["json"]
+ end
+
+ scope "/", MyAppWeb do
+ pipe_through :browser
+
+ get "/", PageController, :home
+ live "/counter", CounterLive # LiveView route
+ resources "/products", ProductController # RESTful CRUD
+ end
+
+ scope "/api", MyAppWeb do
+ pipe_through :api
+
+ resources "/items", ItemController, except: [:new, :edit]
+ end
+end
+```
+
+---
+
+## Verified Routes — `~p` Sigil
+
+**Always use `~p` instead of string paths.** Compile-time verified against your router.
+
+```elixir
+# In templates (HEEx)
+~H"""
+View
+Edit
+"""
+
+# In controllers
+redirect(conn, to: ~p"/products/#{product}")
+
+# With query params
+~p"/products?page=#{page}&sort=name"
+~p"/products?#{%{page: 1, sort: "name"}}"
+
+# URL generation (includes host)
+url(~p"/products/#{product}")
+# => "https://example.com/products/42"
+```
+
+---
+
+## Controllers (1.8 Style)
+
+```elixir
+defmodule MyAppWeb.ProductController do
+ use MyAppWeb, :controller
+
+ # REQUIRED in 1.8: specify formats
+ # This is typically set in MyAppWeb :controller function
+
+ def index(conn, _params) do
+ products = Catalog.list_products()
+ render(conn, :index, products: products)
+ end
+
+ def show(conn, %{"id" => id}) do
+ product = Catalog.get_product!(id)
+ render(conn, :show, product: product)
+ end
+
+ def create(conn, %{"product" => product_params}) do
+ case Catalog.create_product(product_params) do
+ {:ok, product} ->
+ conn
+ |> put_flash(:info, "Product created.")
+ |> redirect(to: ~p"/products/#{product}")
+
+ {:error, %Ecto.Changeset{} = changeset} ->
+ render(conn, :new, changeset: changeset)
+ end
+ end
+end
+```
+
+**View module naming:** For `ProductController`, Phoenix looks for `ProductHTML` (for `:html` format) and `ProductJSON` (for `:json` format).
+
+```elixir
+# lib/my_app_web/controllers/product_html.ex
+defmodule MyAppWeb.ProductHTML do
+ use MyAppWeb, :html
+ embed_templates "product_html/*" # Loads .heex files from directory
+end
+
+# lib/my_app_web/controllers/product_json.ex
+defmodule MyAppWeb.ProductJSON do
+ def index(%{products: products}), do: %{data: for(p <- products, do: data(p))}
+ def show(%{product: product}), do: %{data: data(product)}
+ defp data(product), do: %{id: product.id, title: product.title, price: product.price}
+end
+```
+
+---
+
+## Components and HEEx
+
+```elixir
+defmodule MyAppWeb.CoreComponents do
+ use Phoenix.Component
+
+ # Declare attributes with types and docs
+ attr :type, :string, default: "button"
+ attr :class, :string, default: nil
+ attr :rest, :global # Passes through all other HTML attrs
+ slot :inner_block, required: true
+
+ def button(assigns) do
+ ~H"""
+
+ """
+ end
+
+ # Table component with slots
+ attr :rows, :list, required: true
+ slot :col, required: true do
+ attr :label, :string
+ end
+
+ def table(assigns) do
+ ~H"""
+
+
+
+ | {col[:label]} |
+
+
+
+
+ | {render_slot(col, row)} |
+
+
+
+ """
+ end
+end
+```
+
+**HEEx syntax notes:**
+- `{@var}` — render assign (curly braces, not `<%= %>`)
+- `:if={condition}` — conditional rendering on any tag
+- `:for={item <- list}` — iteration on any tag
+- `<.component_name />` — call function component with dot notation
+- `` — call remote component with module name
+- `{render_slot(@inner_block)}` — render slot content
+- `<:slot_name>content` — named slot content
+
+---
+
+## LiveView
+
+```elixir
+defmodule MyAppWeb.SearchLive do
+ use MyAppWeb, :live_view
+
+ def mount(_params, _session, socket) do
+ {:ok, assign(socket, query: "", results: [])}
+ end
+
+ def handle_params(%{"q" => query}, _uri, socket) do
+ {:noreply, assign(socket, query: query, results: search(query))}
+ end
+
+ def handle_params(_params, _uri, socket), do: {:noreply, socket}
+
+ def handle_event("search", %{"query" => query}, socket) do
+ {:noreply,
+ socket
+ |> assign(query: query, results: search(query))
+ |> push_patch(to: ~p"/search?q=#{query}")}
+ end
+
+ def render(assigns) do
+ ~H"""
+
+
+
+
+
{result.title}
+
{result.summary}
+