From ca4878055d413307ecd6d0b2931de7b86a84f3d5 Mon Sep 17 00:00:00 2001 From: Owen Date: Sun, 1 Nov 2026 20:23:49 +0100 Subject: [PATCH] update docs and agents files in preparation for agents --- .gitignore | 5 + AGENTS.md | 457 +---------------------------------- CODING_STANDARDS.md | 118 +++++++++ docs/agents/domain.md | 36 +++ docs/agents/issue-tracker.md | 46 ++++ docs/agents/triage-labels.md | 15 ++ opencode.json | 6 +- 7 files changed, 236 insertions(+), 447 deletions(-) create mode 100644 CODING_STANDARDS.md create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md diff --git a/.gitignore b/.gitignore index d8df129..9c3b264 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,8 @@ chesstrainer-*.tar # In case you use Node.js/npm, you want to ignore these. npm-debug.log /assets/node_modules/ + +.codegraph/ + +# graft's local graph cache — regenerable, not committed (run `graft build`). +/graft/ diff --git a/AGENTS.md b/AGENTS.md index c5e7277..817fa3c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,6 @@ -This is a web application written using the Phoenix web framework. +Phoenix 1.8 web app — an endgame trainer. LiveView 1.2, Ecto/Postgres, chessground for board rendering. Modules are `Chesstrainer` and `ChesstrainerWeb`. - ## Graft — repo context graph This repo is indexed in `graft/`: small linked markdown nodes that explain each @@ -41,458 +40,26 @@ re-read whole files. After big code changes, refresh the graph with `graft build` (deterministic, no API key, $0). - -## Project guidelines +## Coding standards -- Use `mix precommit` alias when you are done with all changes and fix any pending issues -- Use the already included and available `:req` (`Req`) library for HTTP requests, **avoid** `:httpoison`, `:tesla`, and `:httpc`. Req is included by default and is the preferred HTTP client for Phoenix apps +Read `CODING_STANDARDS.md` before writing code. Read the section for the layer you're touching: Elixir, Ecto, Phoenix, HEEx, LiveView, Forms, Assets, or Testing. -### Phoenix v1.8 guidelines +## Done -- **Always** begin your LiveView templates with `` which wraps all inner content -- The `MyAppWeb.Layouts` module is aliased in the `my_app_web.ex` file, so you can use it without needing to alias it again -- Anytime you run into errors with no `current_scope` assign: - - You failed to follow the Authenticated Routes guidelines, or you failed to pass `current_scope` to `` - - **Always** fix the `current_scope` error by moving your routes to the proper `live_session` and ensure you pass `current_scope` as needed -- Phoenix v1.8 moved the `<.flash_group>` component to the `Layouts` module. You are **forbidden** from calling `<.flash_group>` outside of the `layouts.ex` module -- Out of the box, `core_components.ex` imports an `<.icon name="hero-x-mark" class="w-5 h-5"/>` component for hero icons. **Always** use the `<.icon>` component for icons, **never** use `Heroicons` modules or similar -- **Always** use the imported `<.input>` component for form inputs from `core_components.ex` when available. `<.input>` is imported and using it will save steps and prevent errors -- If you override the default input classes (`<.input class="myclass px-2 py-1 rounded-lg">)`) class with your own values, no default classes are inherited, so your - custom classes must fully style the input +Run `mix precommit` and fix what it flags. -### JS and CSS guidelines +## Agent skills -- **Use Tailwind CSS classes and custom CSS rules** to create polished, responsive, and visually stunning interfaces. -- Tailwindcss v4 **no longer needs a tailwind.config.js** and uses a new import syntax in `app.css`: +### Issue tracker - @import "tailwindcss" source(none); - @source "../css"; - @source "../js"; - @source "../../lib/my_app_web"; +Issues live in GitHub Issues for `TheRealOwenRees/chess-endgame-trainer`, driven by the `gh` CLI. See `docs/agents/issue-tracker.md`. -- **Always use and maintain this import syntax** in the app.css file for projects generated with `phx.new` -- **Never** use `@apply` when writing raw css -- **Always** manually write your own tailwind-based components instead of using daisyUI for a unique, world-class design -- Out of the box **only the app.js and app.css bundles are supported** - - You cannot reference an external vendor'd script `src` or link `href` in the layouts - - You must import the vendor deps into app.js and app.css to use them - - **Never write inline tags within templates** +### Triage labels -### UI/UX & design guidelines +The five canonical triage roles, each label string equal to its name (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`. -- **Produce world-class UI designs** with a focus on usability, aesthetics, and modern design principles -- Implement **subtle micro-interactions** (e.g., button hover effects, and smooth transitions) -- Ensure **clean typography, spacing, and layout balance** for a refined, premium look -- Focus on **delightful details** like hover effects, loading states, and smooth page transitions +### Domain docs - - - - -## Elixir guidelines - -- Elixir lists **do not support index based access via the access syntax** - - **Never do this (invalid)**: - - i = 0 - mylist = ["blue", "green"] - mylist[i] - - Instead, **always** use `Enum.at`, pattern matching, or `List` for index based list access, ie: - - i = 0 - mylist = ["blue", "green"] - Enum.at(mylist, i) - -- Elixir variables are immutable, but can be rebound, so for block expressions like `if`, `case`, `cond`, etc - you _must_ bind the result of the expression to a variable if you want to use it and you CANNOT rebind the result inside the expression, ie: - - # INVALID: we are rebinding inside the `if` and the result never gets assigned - if connected?(socket) do - socket = assign(socket, :val, val) - end - - # VALID: we rebind the result of the `if` to a new variable - socket = - if connected?(socket) do - assign(socket, :val, val) - end - -- **Never** nest multiple modules in the same file as it can cause cyclic dependencies and compilation errors -- **Never** use map access syntax (`changeset[:field]`) on structs as they do not implement the Access behaviour by default. For regular structs, you **must** access the fields directly, such as `my_struct.field` or use higher level APIs that are available on the struct if they exist, `Ecto.Changeset.get_field/2` for changesets -- Elixir's standard library has everything necessary for date and time manipulation. Familiarize yourself with the common `Time`, `Date`, `DateTime`, and `Calendar` interfaces by accessing their documentation as necessary. **Never** install additional dependencies unless asked or for date/time parsing (which you can use the `date_time_parser` package) -- Don't use `String.to_atom/1` on user input (memory leak risk) -- Predicate function names should not start with `is_` and should end in a question mark. Names like `is_thing` should be reserved for guards -- Elixir's builtin OTP primitives like `DynamicSupervisor` and `Registry`, require names in the child spec, such as `{DynamicSupervisor, name: MyApp.MyDynamicSup}`, then you can use `DynamicSupervisor.start_child(MyApp.MyDynamicSup, child_spec)` -- Use `Task.async_stream(collection, callback, options)` for concurrent enumeration with back-pressure. The majority of times you will want to pass `timeout: :infinity` as option - -## Mix guidelines - -- Read the docs and options before using tasks (by using `mix help task_name`) -- To debug test failures, run tests in a specific file with `mix test test/my_test.exs` or run all previously failed tests with `mix test --failed` -- `mix deps.clean --all` is **almost never needed**. **Avoid** using it unless you have good reason - -## Test guidelines - -- **Always use `start_supervised!/1`** to start processes in tests as it guarantees cleanup between tests -- **Avoid** `Process.sleep/1` and `Process.alive?/1` in tests - - Instead of sleeping to wait for a process to finish, **always** use `Process.monitor/1` and assert on the DOWN message: - - ref = Process.monitor(pid) - assert_receive {:DOWN, ^ref, :process, ^pid, :normal} - - - Instead of sleeping to synchronize before the next call, **always** use `_ = :sys.get_state/1` to ensure the process has handled prior messages - - - - -## Phoenix guidelines - -- Remember Phoenix router `scope` blocks include an optional alias which is prefixed for all routes within the scope. **Always** be mindful of this when creating routes within a scope to avoid duplicate module prefixes. - -- You **never** need to create your own `alias` for route definitions! The `scope` provides the alias, ie: - - scope "/admin", AppWeb.Admin do - pipe_through :browser - - live "/users", UserLive, :index - end - - the UserLive route would point to the `AppWeb.Admin.UserLive` module - -- `Phoenix.View` no longer is needed or included with Phoenix, don't use it - - - - -## Ecto Guidelines - -- **Always** preload Ecto associations in queries when they'll be accessed in templates, ie a message that needs to reference the `message.user.email` -- Remember `import Ecto.Query` and other supporting modules when you write `seeds.exs` -- `Ecto.Schema` fields always use the `:string` type, even for `:text`, columns, ie: `field :name, :string` -- `Ecto.Changeset.validate_number/2` **DOES NOT SUPPORT the `:allow_nil` option**. By default, Ecto validations only run if a change for the given field exists and the change value is not nil, so such as option is never needed -- You **must** use `Ecto.Changeset.get_field(changeset, :field)` to access changeset fields -- Fields which are set programmatically, such as `user_id`, must not be listed in `cast` calls or similar for security purposes. Instead they must be explicitly set when creating the struct -- **Always** invoke `mix ecto.gen.migration migration_name_using_underscores` when generating migration files, so the correct timestamp and conventions are applied - - - - -## Phoenix HTML guidelines - -- Phoenix templates **always** use `~H` or .html.heex files (known as HEEx), **never** use `~E` -- **Always** use the imported `Phoenix.Component.form/1` and `Phoenix.Component.inputs_for/1` function to build forms. **Never** use `Phoenix.HTML.form_for` or `Phoenix.HTML.inputs_for` as they are outdated -- When building forms **always** use the already imported `Phoenix.Component.to_form/2` (`assign(socket, form: to_form(...))` and `<.form for={@form} id="msg-form">`), then access those forms in the template via `@form[:field]` -- **Always** add unique DOM IDs to key elements (like forms, buttons, etc) when writing templates, these IDs can later be used in tests (`<.form for={@form} id="product-form">`) -- For "app wide" template imports, you can import/alias into the `my_app_web.ex`'s `html_helpers` block, so they will be available to all LiveViews, LiveComponent's, and all modules that do `use MyAppWeb, :html` (replace "my_app" by the actual app name) - -- Elixir supports `if/else` but **does NOT support `if/else if` or `if/elsif`**. **Never use `else if` or `elseif` in Elixir**, **always** use `cond` or `case` for multiple conditionals. - - **Never do this (invalid)**: - - <%= if condition do %> - ... - <% else if other_condition %> - ... - <% end %> - - Instead **always** do this: - - <%= cond do %> - <% condition -> %> - ... - <% condition2 -> %> - ... - <% true -> %> - ... - <% end %> - -- HEEx require special tag annotation if you want to insert literal curly's like `{` or `}`. If you want to show a textual code snippet on the page in a `
` or `` block you _must_ annotate the parent tag with `phx-no-curly-interpolation`:
-
-      
-        let obj = {key: "val"}
-      
-
-  Within `phx-no-curly-interpolation` annotated tags, you can use `{` and `}` without escaping them, and dynamic Elixir expressions can still be used with `<%= ... %>` syntax
-
-- HEEx class attrs support lists, but you must **always** use list `[...]` syntax. You can use the class list syntax to conditionally add classes, **always do this for multiple class values**:
-
-      Text
-
-  and **always** wrap `if`'s inside `{...}` expressions with parens, like done above (`if(@other_condition, do: "...", else: "...")`)
-
-  and **never** do this, since it's invalid (note the missing `[` and `]`):
-
-       ...
-      => Raises compile syntax error on invalid HEEx attr syntax
-
-- **Never** use `<% Enum.each %>` or non-for comprehensions for generating template content, instead **always** use `<%= for item <- @collection do %>`
-- HEEx HTML comments use `<%!-- comment --%>`. **Always** use the HEEx HTML comment syntax for template comments (`<%!-- comment --%>`)
-- HEEx allows interpolation via `{...}` and `<%= ... %>`, but the `<%= %>` **only** works within tag bodies. **Always** use the `{...}` syntax for interpolation within tag attributes, and for interpolation of values within tag bodies. **Always** interpolate block constructs (if, cond, case, for) within tag bodies using `<%= ... %>`.
-
-  **Always** do this:
-
-        
- {@my_assign} - <%= if @some_block_condition do %> - {@another_assign} - <% end %> -
- - and **Never** do this – the program will terminate with a syntax error: - - <%!-- THIS IS INVALID NEVER EVER DO THIS --%> -
- {if @invalid_block_construct do} - {end} -
- - - - - -## Phoenix LiveView guidelines - -- **Never** use the deprecated `live_redirect` and `live_patch` functions, instead **always** use the `<.link navigate={href}>` and `<.link patch={href}>` in templates, and `push_navigate` and `push_patch` functions LiveViews -- **Avoid LiveComponent's** unless you have a strong, specific need for them -- LiveViews should be named like `AppWeb.WeatherLive`, with a `Live` suffix. When you go to add LiveView routes to the router, the default `:browser` scope is **already aliased** with the `AppWeb` module, so you can just do `live "/weather", WeatherLive` - -### LiveView streams - -- **Always** use LiveView streams for collections for assigning regular lists to avoid memory ballooning and runtime termination with the following operations: - - basic append of N items - `stream(socket, :messages, [new_msg])` - - resetting stream with new items - `stream(socket, :messages, [new_msg], reset: true)` (e.g. for filtering items) - - prepend to stream - `stream(socket, :messages, [new_msg], at: -1)` - - deleting items - `stream_delete(socket, :messages, msg)` - -- When using the `stream/3` interfaces in the LiveView, the LiveView template must 1) always set `phx-update="stream"` on the parent element, with a DOM id on the parent element like `id="messages"` and 2) consume the `@streams.stream_name` collection and use the id as the DOM id for each child. For a call like `stream(socket, :messages, [new_msg])` in the LiveView, the template would be: - -
-
- {msg.text} -
-
- -- LiveView streams are _not_ enumerable, so you cannot use `Enum.filter/2` or `Enum.reject/2` on them. Instead, if you want to filter, prune, or refresh a list of items on the UI, you **must refetch the data and re-stream the entire stream collection, passing reset: true**: - - def handle_event("filter", %{"filter" => filter}, socket) do - # re-fetch the messages based on the filter - messages = list_messages(filter) - - {:noreply, - socket - |> assign(:messages_empty?, messages == []) - # reset the stream with the new messages - |> stream(:messages, messages, reset: true)} - end - -- LiveView streams _do not support counting or empty states_. If you need to display a count, you must track it using a separate assign. For empty states, you can use Tailwind classes: - -
- -
- {task.name} -
-
- - The above only works if the empty state is the only HTML block alongside the stream for-comprehension. - -- When updating an assign that should change content inside any streamed item(s), you MUST re-stream the items - along with the updated assign: - - def handle_event("edit_message", %{"message_id" => message_id}, socket) do - message = Chat.get_message!(message_id) - edit_form = to_form(Chat.change_message(message, %{content: message.content})) - - # re-insert message so @editing_message_id toggle logic takes effect for that stream item - {:noreply, - socket - |> stream_insert(:messages, message) - |> assign(:editing_message_id, String.to_integer(message_id)) - |> assign(:edit_form, edit_form)} - end - - And in the template: - -
-
- {message.username} - <%= if @editing_message_id == message.id do %> - <%!-- Edit mode --%> - <.form for={@edit_form} id="edit-form-#{message.id}" phx-submit="save_edit"> - ... - - <% end %> -
-
- -- **Never** use the deprecated `phx-update="append"` or `phx-update="prepend"` for collections - -### LiveView JavaScript interop - -- Remember anytime you use `phx-hook="MyHook"` and that JS hook manages its own DOM, you **must** also set the `phx-update="ignore"` attribute -- **Always** provide an unique DOM id alongside `phx-hook` otherwise a compiler error will be raised - -LiveView hooks come in two flavors, 1) colocated js hooks for "inline" scripts defined inside HEEx, -and 2) external `phx-hook` annotations where JavaScript object literals are defined and passed to the `LiveSocket` constructor. - -#### Inline colocated js hooks - -**Never** write raw embedded ` - -- colocated hooks are automatically integrated into the app.js bundle -- colocated hooks names **MUST ALWAYS** start with a `.` prefix, i.e. `.PhoneNumber` - -#### External phx-hook - -External JS hooks (`
`) must be placed in `assets/js/` and passed to the -LiveSocket constructor: - - const MyHook = { - mounted() { ... } - } - let liveSocket = new LiveSocket("/live", Socket, { - hooks: { MyHook } - }); - -#### Pushing events between client and server - -Use LiveView's `push_event/3` when you need to push events/data to the client for a phx-hook to handle. -**Always** return or rebind the socket on `push_event/3` when pushing events: - - # re-bind socket so we maintain event state to be pushed - socket = push_event(socket, "my_event", %{...}) - - # or return the modified socket directly: - def handle_event("some_event", _, socket) do - {:noreply, push_event(socket, "my_event", %{...})} - end - -Pushed events can then be picked up in a JS hook with `this.handleEvent`: - - mounted() { - this.handleEvent("my_event", data => console.log("from server:", data)); - } - -Clients can also push an event to the server and receive a reply with `this.pushEvent`: - - mounted() { - this.el.addEventListener("click", e => { - this.pushEvent("my_event", { one: 1 }, reply => console.log("got reply from server:", reply)); - }) - } - -Where the server handled it via: - - def handle_event("my_event", %{"one" => 1}, socket) do - {:reply, %{two: 2}, socket} - end - -### LiveView tests - -- `Phoenix.LiveViewTest` module and `LazyHTML` (included) for making your assertions -- Form tests are driven by `Phoenix.LiveViewTest`'s `render_submit/2` and `render_change/2` functions -- Come up with a step-by-step test plan that splits major test cases into small, isolated files. You may start with simpler tests that verify content exists, gradually add interaction tests -- **Always reference the key element IDs you added in the LiveView templates in your tests** for `Phoenix.LiveViewTest` functions like `element/2`, `has_element/2`, selectors, etc -- **Never** tests again raw HTML, **always** use `element/2`, `has_element/2`, and similar: `assert has_element?(view, "#my-form")` -- Instead of relying on testing text content, which can change, favor testing for the presence of key elements -- Focus on testing outcomes rather than implementation details -- Be aware that `Phoenix.Component` functions like `<.form>` might produce different HTML than expected. Test against the output HTML structure, not your mental model of what you expect it to be -- When facing test failures with element selectors, add debug statements to print the actual HTML, but use `LazyHTML` selectors to limit the output, ie: - - html = render(view) - document = LazyHTML.from_fragment(html) - matches = LazyHTML.filter(document, "your-complex-selector") - IO.inspect(matches, label: "Matches") - -### Form handling - -#### Creating a form from params - -If you want to create a form based on `handle_event` params: - - def handle_event("submitted", params, socket) do - {:noreply, assign(socket, form: to_form(params))} - end - -When you pass a map to `to_form/1`, it assumes said map contains the form params, which are expected to have string keys. - -You can also specify a name to nest the params: - - def handle_event("submitted", %{"user" => user_params}, socket) do - {:noreply, assign(socket, form: to_form(user_params, as: :user))} - end - -#### Creating a form from changesets - -When using changesets, the underlying data, form params, and errors are retrieved from it. The `:as` option is automatically computed too. E.g. if you have a user schema: - - defmodule MyApp.Users.User do - use Ecto.Schema - ... - end - -And then you create a changeset that you pass to `to_form`: - - %MyApp.Users.User{} - |> Ecto.Changeset.change() - |> to_form() - -Once the form is submitted, the params will be available under `%{"user" => user_params}`. - -In the template, the form form assign can be passed to the `<.form>` function component: - - <.form for={@form} id="todo-form" phx-change="validate" phx-submit="save"> - <.input field={@form[:field]} type="text" /> - - -Always give the form an explicit, unique DOM ID, like `id="todo-form"`. - -#### Avoiding form errors - -**Always** use a form assigned via `to_form/2` in the LiveView, and the `<.input>` component in the template. In the template **always access forms this**: - - <%!-- ALWAYS do this (valid) --%> - <.form for={@form} id="my-form"> - <.input field={@form[:field]} type="text" /> - - -And **never** do this: - - <%!-- NEVER do this (invalid) --%> - <.form for={@changeset} id="my-form"> - <.input field={@changeset[:field]} type="text" /> - - -- You are FORBIDDEN from accessing the changeset in the template as it will cause errors -- **Never** use `<.form let={f} ...>` in the template, instead **always use `<.form for={@form} ...>`**, then drive all form references from the form assign as in `@form[:field]`. The UI should **always** be driven by a `to_form/2` assigned in the LiveView module that is derived from a changeset - - - +Single-context: `GLOSSARY.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`. diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md new file mode 100644 index 0000000..b1f1349 --- /dev/null +++ b/CODING_STANDARDS.md @@ -0,0 +1,118 @@ +# Coding Standards + +How to write code in this repo. Read the section for the layer you're touching. + +## Elixir + +- Index lists with `Enum.at(list, i)`. Elixir lists don't implement `Access`, so `list[i]` fails. +- Bind the result of a block expression: `socket = if connected?(socket), do: assign(socket, :val, val)`. Rebinding inside the block doesn't escape it. +- One module per file — nested modules invite cyclic dependencies. +- Read struct fields directly (`my_struct.field`). Structs don't implement `Access`; for changesets use `Ecto.Changeset.get_field/2`. +- Convert user input with `String.to_existing_atom/1` or a fixed map of atoms — `String.to_atom/1` leaks atoms. +- Predicates end in `?`. Reserve the `is_` prefix for guards. +- Name OTP primitives in their child spec: `{DynamicSupervisor, name: Chesstrainer.MyDynamicSup}`, then `DynamicSupervisor.start_child(Chesstrainer.MyDynamicSup, spec)`. +- Enumerate concurrently with `Task.async_stream(collection, fun, timeout: :infinity)`. +- Date and time come from stdlib `Time`, `Date`, `DateTime`, `Calendar`. `date_time_parser` is the only parsing dep we allow; ask before adding another. +- HTTP requests use `Req` (already a dep). `:httpoison`, `:tesla` and `:httpc` are not used. + +## Ecto + +- Preload associations that templates touch, e.g. `message.user.email`. +- Every text column is `:string`, including `:text` ones: `field :name, :string`. +- `validate_number/2` has no `:allow_nil` — validations only run on a present change, so the option is redundant. +- Programmatic fields like `user_id` are set on the struct at insert time, never listed in `cast`. +- Generate migrations with `mix ecto.gen.migration name_using_underscores` so the timestamp and conventions are right. +- `priv/repo/seeds.exs` needs `import Ecto.Query`. + +## Phoenix + +- `scope` prefixes its routes' alias: `scope "/admin", ChesstrainerWeb.Admin` makes `live "/users", UserLive` resolve to `ChesstrainerWeb.Admin.UserLive`. Adding your own `alias` duplicates the prefix. +- `Phoenix.View` is not part of Phoenix any more. + +## HEEx + +- Templates are `~H` or `.html.heex`. +- Begin every LiveView template with ``. `Layouts` is already aliased in `chesstrainer_web.ex`. +- `<.flash_group>` lives only in `layouts.ex`. +- A missing `current_scope` assign means the route sits in the wrong `live_session`. Move it there and pass `current_scope` through. +- Icons come from `core_components.ex`: `<.icon name="hero-x-mark" class="w-5 h-5"/>`. +- Multiple conditionals use `cond` or `case`. +- Literal `{`/`}` inside `
` or ``: annotate the parent tag with `phx-no-curly-interpolation`. Dynamic `<%= ... %>` still works inside it.
+- Class attributes use list syntax, with `if` wrapped in parens:
+
+      Text
+
+- Generate collections with `<%= for item <- @collection do %>`.
+- Comments use `<%!-- ... --%>`.
+- Interpolate attributes and tag bodies with `{...}`. `<%= %>` is for block constructs in tag bodies.
+
+## LiveView
+
+- Navigate with `<.link navigate={href}>` and `<.link patch={href}>`; use `push_navigate` and `push_patch` in handlers.
+- Name LiveViews `SomethingLive`. The `:browser` scope is already aliased to `ChesstrainerWeb`, so `live "/weather", WeatherLive` is enough.
+- Reach for a LiveView before a LiveComponent; a LiveComponent earns its place when it needs isolated state or genuine reuse.
+
+### Streams
+
+- Assign collections through streams: append `stream(socket, :messages, [msg])`, reset `stream(socket, :messages, msgs, reset: true)`, prepend `at: -1`, remove `stream_delete(socket, :messages, msg)`.
+- The parent element carries `phx-update="stream"` and a DOM id; each child is `:for={{id, msg} <- @streams.messages} id={id}`.
+- Streams aren't enumerable. To filter, refetch the data and re-stream it with `reset: true`.
+- Streams don't count or render empty states. Track the count in a separate assign, and put the empty state in a `hidden only:block` sibling of the `:for`.
+- When an assign changes content inside streamed items, re-stream the item with `stream_insert/3` so the item re-renders.
+
+### Hooks
+
+- A `phx-hook` element needs a unique DOM id, plus `phx-update="ignore"` when the hook owns its DOM.
+- Client-side JS is a colocated hook inside the template:
+
+      
+
+  The leading `.` on the name is required. Hooks shared across pages live in `assets/js/hooks/` and are passed to `LiveSocket`.
+- `push_event/3` returns the socket — rebind it or return it from the handler.
+- In the hook: `this.handleEvent("name", data => ...)` receives, `this.pushEvent("name", payload, reply => ...)` sends. The server replies with `{:reply, payload, socket}`.
+
+## Forms
+
+- Build the form in the LiveView with `to_form/2`, pass it to `<.form for={@form} id="...">`, and read fields as `@form[:field]` through `<.input>`:
+
+      assign(socket, form: to_form(changeset))
+
+      <.form for={@form} id="todo-form" phx-change="validate" phx-submit="save">
+        <.input field={@form[:field]} type="text" />
+      
+
+- `to_form/1` on a plain map expects string keys. Nest params with `to_form(params, as: :user)`.
+- From a changeset: `Ecto.Changeset.change(user) |> to_form()`. Submitted params arrive as `%{"user" => ...}`.
+- Every form gets a unique DOM id — the tests select on it.
+- `<.input>` with custom classes inherits none of the defaults, so style it fully.
+
+## Assets
+
+- `assets/css/app.css` is authoritative for the Tailwind v4 setup: `@import "tailwindcss" source(none)`, the `@source` lines, the chessground stylesheets and `phoenix-colocated/chesstrainer/colocated.css`. Keep that import block current.
+- Custom CSS uses plain declarations. `@apply` is off-limits.
+- Components are hand-written Tailwind. daisyUI is not used.
+- Only the `app.js` and `app.css` bundles ship. Vendor dependencies are imported into them, not linked from layouts.
+
+## Testing
+
+- Start processes with `start_supervised!/1`.
+- Wait for a process with `Process.monitor/1` and `assert_receive {:DOWN, ^ref, :process, ^pid, :normal}` instead of `Process.sleep/1`.
+- Synchronise before the next call with `_ = :sys.get_state(pid)`.
+- LiveView tests use `Phoenix.LiveViewTest` and `LazyHTML`; drive forms with `render_submit/2` and `render_change/2`.
+- Assert on elements with the ids from the template: `assert has_element?(view, "#my-form")`, `element/2`. Text content changes; ids don't.
+- Debug a stubborn selector:
+
+      html = render(view)
+      document = LazyHTML.from_fragment(html)
+      matches = LazyHTML.filter(document, "your-complex-selector")
+      IO.inspect(matches, label: "Matches")
+
+## Precommit
+
+`mix precommit` runs `compile --warnings-as-errors`, `deps.unlock --unused`, `format` and `test`.
diff --git a/docs/agents/domain.md b/docs/agents/domain.md
new file mode 100644
index 0000000..f907c29
--- /dev/null
+++ b/docs/agents/domain.md
@@ -0,0 +1,36 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`GLOSSARY.md`** at the repo root, or
+- **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+This repo is single-context:
+
+```
+/
+├── GLOSSARY.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── lib/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_
diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
new file mode 100644
index 0000000..a63510f
--- /dev/null
+++ b/docs/agents/issue-tracker.md
@@ -0,0 +1,46 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view  --json number,title,body,labels,comments`.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Make an issue a sub-issue of a parent**: `gh issue create --parent  ...`, or `gh issue edit  --add-sub-issue ` afterwards (`gh` 2.94+). Older `gh`: `gh api --method POST repos///issues//sub_issues -F sub_issue_id=` (database id, as in **Blocking** below). Without sub-issues, put `Part of #` at the top of the child body.
+- **Comment on an issue**: `gh issue comment  --body "..."`
+- **Apply / remove labels**: `gh issue edit  --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close  --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view  --comments` and `gh pr diff ` for the diff.
+- **List external PRs for triage**: `gh api --paginate 'repos/{owner}/{repo}/pulls?state=open' --jq '.[] | select(.author_association | IN("OWNER","MEMBER","COLLABORATOR") | not) | {number, title, author: .user.login, author_association, labels: [.labels[].name]}'`.
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Read it as in **Read an issue** above.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (see **Make an issue a sub-issue of a parent**). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #` at the top of the child body. Labels: `wayfinder:` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos///issues//dependencies/blocked_by -F issue_id=`, where `` is the blocker's numeric **database id** (`gh api repos///issues/ --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #, #` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit  --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment  --body ""`, then `gh issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far.
diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md
new file mode 100644
index 0000000..5276464
--- /dev/null
+++ b/docs/agents/triage-labels.md
@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the "Label in our tracker" column to match whatever vocabulary you actually use.
diff --git a/opencode.json b/opencode.json
index 17f3f8d..32d36b7 100644
--- a/opencode.json
+++ b/opencode.json
@@ -1,9 +1,11 @@
 {
-  "$schema": "https://opencode.ai/config.json",
   "mcp": {
     "graft": {
       "type": "local",
-      "command": ["npx", "-y", "@nanonets/graft", "mcp"],
+      "command": [
+        "graft",
+        "mcp"
+      ],
       "enabled": true
     }
   }