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 system and carry exact file:line spans, kept in sync with the code through git. For ANY task here — understanding how something works, finding where code lives, or scoping a change — get context from the graph before grepping or opening source files. Re-ask freely (it's cheap) and reuse literal identifiers you already have (symbol, error string, file name) as the query. New to this repo? Run `graft map` first — a token-budgeted orientation (dir clusters, hubs, hotspots), no LLM, no key. - Run `graft ask "" --source` → ranked nodes with the relevant code spans inlined (each hit's ≤8-line crux by default; `--full` for whole definitions when the crux isn't enough). Match the tool to the task shape: for understanding or editing, the top node IS the answer — cite its `covers:` file:line spans and edit straight from `--source`. For exhaustive tasks ("every occurrence / every caller of this pattern"), ranked results are top-N, not complete — run `graft grep ""` instead (exhaustive over indexed files, grouped by enclosing symbol), falling back to raw `grep -rn` only for unindexed files. - `graft skeleton ` → every definition's signature + span, ~10× cheaper than reading the file; use it to skim an API surface. - `graft callers ` gives precomputed, exact edges — who calls this. Add `--direction out` for what it calls, or `--depth N` to walk transitively for the full blast radius. For structural questions, skip ranking and use this directly. - Or browse: `graft/INDEX.md` lists every node; follow the links. - Monorepos and folders of multiple repos rank fairly across sub-projects — hits carry `[scope/]` labels naming which one they're from. Narrow with `graft ask "" --in /` once you know where you're working. If a returned span is truncated ("+N more lines"), open the file at that exact range before finalizing. Only open source files when a node genuinely lacks a needed detail, and then at the exact file:line the node points to — never re-read whole files. After big code changes, refresh the graph with `graft build` (deterministic, no API key, $0). ## Coding standards 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. ## Done Run `mix precommit` and fix what it flags. Type-check risky changes with `mix dialyzer` (not part of `mix precommit`; the first run builds a PLT and is slow). ## Agent skills ### Issue tracker Issues live in GitHub Issues for `TheRealOwenRees/chess-endgame-trainer`, driven by the `gh` CLI. See `docs/agents/issue-tracker.md`. ### Triage labels 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`. ### Domain docs Single-context: `GLOSSARY.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`. ## Authentication - **Always** handle authentication flow at the router level with proper redirects - **Always** be mindful of where to place routes. `phx.gen.auth` creates multiple router plugs and `live_session` scopes: - A plug `:fetch_current_scope_for_user` that is included in the default browser pipeline - A plug `:require_authenticated_user` that redirects to the log in page when the user is not authenticated - A `live_session :current_user` scope - for routes that need the current user but don't require authentication, similar to `:fetch_current_scope_for_user` - A `live_session :require_authenticated_user` scope - for routes that require authentication, similar to the plug with the same name - In both cases, a `@current_scope` is assigned to the Plug connection and LiveView socket - A plug `redirect_if_user_is_authenticated` that redirects to a default path in case the user is authenticated - useful for a registration page that should only be shown to unauthenticated users - **Always let the user know in which router scopes, `live_session`, and pipeline you are placing the route, AND SAY WHY** - `phx.gen.auth` assigns the `current_scope` assign - it **does not assign a `current_user` assign** - Always pass the assign `current_scope` to context modules as first argument. When performing queries, use `current_scope.user` to filter the query results - To derive/access `current_user` in templates, **always use the `@current_scope.user`**, never use **`@current_user`** in templates or LiveViews - **Never** duplicate `live_session` names. A `live_session :current_user` can only be defined __once__ in the router, so all routes for the `live_session :current_user` must be grouped in a single block - Anytime you hit `current_scope` errors or the logged in session isn't displaying the right content, **always double check the router and ensure you are using the correct plug and `live_session` as described below** ### Routes that require authentication LiveViews that require login should **always be placed inside the __existing__ `live_session :require_authenticated_user` block**: scope "/", AppWeb do pipe_through [:browser, :require_authenticated_user] live_session :require_authenticated_user, on_mount: [{ChesstrainerWeb.UserAuth, :require_authenticated}] do # phx.gen.auth generated routes live "/users/settings", UserLive.Settings, :edit live "/users/settings/confirm-email/:token", UserLive.Settings, :confirm_email # our own routes that require logged in user live "/", MyLiveThatRequiresAuth, :index end end Controller routes must be placed in a scope that sets the `:require_authenticated_user` plug: scope "/", AppWeb do pipe_through [:browser, :require_authenticated_user] get "/", MyControllerThatRequiresAuth, :index end ### Routes that work with or without authentication LiveViews that can work with or without authentication, **always use the __existing__ `:current_user` scope**, ie: scope "/", MyAppWeb do pipe_through [:browser] live_session :current_user, on_mount: [{ChesstrainerWeb.UserAuth, :mount_current_scope}] do # our own routes that work with or without authentication live "/", PublicLive end end Controllers automatically have the `current_scope` available if they use the `:browser` pipeline.