add-route

name	add-route
description	Add a new route to the Arizona router configuration. Use when creating new pages or endpoints.
argument-hint	["path"]
allowed-tools	Read, Edit, Grep, Glob

Add a route for path $ARGUMENTS to the router configuration.

1. Find the route config

Search for compile_routes calls to locate where routes are defined (typically in the app module or config).

2. Route types

Choose the appropriate route type based on the user's intent:

Live page (most common):

{live, Path, Handler, Opts}

• Path -- route pattern, e.g. <<"/">> or <<"/users/:id">>
• Handler -- a handler module that includes arizona_stateful.hrl and exports mount/1, render/1
• Opts -- map with optional keys:
  • bindings => map() -- initial bindings passed to mount/1 (default #{})
  • layout => {LayoutMod, LayoutFun} -- layout to wrap the page (optional)
  • on_mount => [Hook] -- on_mount hooks run before the handler's mount/1
  • middlewares => [fun((az:request(), map()) -> {cont, az:request(), map()} | {halt, az:request()})]

WebSocket endpoint:

{ws, Path, Opts}

Static assets:

{asset, Path, {priv_dir, App, SubDir}}
{asset, Path, {dir, AbsoluteDir}}

Controller (HTTP, method-gated; reached via arizona_js:fetch/2):

{post, Path, Handler, Opts}            %% also get/put/patch/delete/head/options
{match, Spec, Path, Handler, Opts}     %% multi/custom/any-method (Spec: verb | [verbs] | binary | '*')

Opts is controller_opts(): #{state, action, middlewares, check_origin} (action defaults to handle). A wrong-verb request gets 405 + Allow.

3. If creating a new live page

Also scaffold the handler module using the /new-handler skill pattern (choose "route-level page"):

• Include arizona_stateful.hrl
• mount/1 takes (Bindings) and must set id => <<"page">> (or appropriate view id); request data (path bindings, query params) arrives via middlewares => [arizona_middleware:extract([...])]
• render/1 with ?html(...)
• handle_event/3 if interactive

4. Verify

After adding the route, check that:

• The handler module exists
• The path doesn't conflict with existing routes
• The layout module exists if layout is specified in opts