Imported from kosciak9/prizmo (AGENTS.md). Install upstream with npx skills add kosciak9/prizmo. Copyright stays with the author.

Prizmo is a Phoenix/Ash application with a React SPA built by Volt.

Development server

When running, assume the local application and required services are managed through mix dev.up or wt (worktrunk). Parallel worktrees run on the same host, so they use different ports stored in .env.local and .server.port.

Accessing the dev server:

Check .server.port for the current Phoenix port, for example http://localhost:4003
Use mix dev.up to start local services and mix dev.down to stop them
Worktrunk generates .env.local with hashed ports for feature branches
The default local domain is prizmo.localhost; worktrees use {branch}.prizmo.localhost
Tidewave MCP should be available at http://localhost:{PORT}/tidewave/mcp

Avoid starting or restarting shared local servers blindly. You can interfere with other active worktrees if you kill the wrong process.

Project guidelines

Use mix check 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

Knowledge base

Prizmo's persistent LLM-readable project memory lives under knowledge-base/. Use the llm-wiki skill when maintaining it.

knowledge-base/raw/ stores immutable external source captures.
knowledge-base/wiki/ stores compiled articles, the global index, and the newest-first operation log.
knowledge-base/battle-logs/ stores Prizmo-specific PTCGL battle log artifacts and parsed outputs.
Do not create repo-root raw/ or wiki/ directories.
After implementation work, update knowledge-base/wiki/ and knowledge-base/wiki/log.md when durable project knowledge changes: architecture, product direction, TCG engine behavior, supported mechanics, UI/playtest flow, known limitations, validation state, or handoff state.
For codebase-driven updates, prefer updating existing wiki articles and operational handoffs over creating raw files; raw files are for external or pasted source material.
If a code change also updates wiki/log documentation, keep those documentation edits with the related code change.

Quality gate

mix check is the canonical local and CI quality gate. It runs:

mix format
mix sobelow --config --compact --private
mix compile --warnings-as-errors
mix deps.unlock --check-unused
mix xref graph --label compile-connected --fail-above 50
mix check.filenames
mix check.service_images
mix ash_typescript.codegen
mix ash_typescript.codegen --check
mix credo --strict
mix dialyzer
mix test

Use mix check --no-test only when tests are being run separately. Use mix check --verbose when you need full output for debugging.

Commit policy

Unlike other repositories, this one is agent-first and expects agents to constantly commit their atomic changes.

Before committing, inspect git status, git diff, and recent history; stage only the intended files and leave unrelated work untouched.
Use Conventional Commit style. For knowledge-base/wiki-only documentation changes, use the docs type with wiki scope, for example docs(wiki): capture renderer research.
If a code change also updates wiki/log documentation, commit those docs with the related code change instead of making a separate docs-only commit.

Frontend

Product UI lives in the Volt React SPA under lib/prizmo_web/spa/.
Root JavaScript/TypeScript configuration lives at the repository root.
Use npm ci via mix assets.setup; do not add a second package manager workflow.
Generated AshTypescript files live under lib/prizmo_web/spa/lib/ash/generated/ and are intentionally gitignored to keep diffs clean.
Run mix ash_typescript.codegen after changing Ash resources, actions, or RPC-facing fields, and before SPA builds/checks in a fresh checkout or worktree.
Use mix ash_typescript.codegen --check to verify the ignored generated files are up to date.

Ash migrations

Prefer Ash-generated migrations and snapshots for resource changes.
Do not hand-edit generated migrations unless the generated SQL is demonstrably wrong or incomplete.
After changing Ash resources, run the appropriate Ash migration/codegen tasks and verify snapshots are updated intentionally.

Sobelow findings

Fix Sobelow findings when possible.
If a finding is intentionally safe, add a narrow sobelow_skip with a clear reason near the code being skipped.

Repository boundaries

Keep generated runtime data, local uploads, credentials, and dependency caches out of git.
game/* is reserved for Godot TCG player experiments. Do not edit, delete, format, move, or clean files under game/* unless the user explicitly asks for Godot/game/* work.
Use /tmp/opencode for scratch work outside the repository.
Verify APIs against the installed dependency versions before relying on examples from the internet.

ash usage

A declarative, extensible framework for building Elixir applications.

ash usage rules

ash:actions usage

ash:actions usage rules

ash:aggregates usage

ash:aggregates usage rules

ash:authorization usage

ash:authorization usage rules

ash:calculations usage

ash:calculations usage rules

ash:code_interfaces usage

ash:code_interfaces usage rules

ash:code_structure usage

ash:code_structure usage rules

ash:data_layers usage

ash:data_layers usage rules

ash:exist_expressions usage

ash:exist_expressions usage rules

ash:generating_code usage

ash:generating_code usage rules

ash:migrations usage

ash:migrations usage rules

ash:query_filter usage

ash:query_filter usage rules

ash:querying_data usage

ash:querying_data usage rules

ash:relationships usage

ash:relationships usage rules

ash:testing usage

ash:testing usage rules

ash_postgres usage

The PostgreSQL data layer for Ash Framework

ash_postgres usage rules

ash_postgres:advanced_features usage

ash_postgres:advanced_features usage rules

ash_postgres:best_practices usage

ash_postgres:best_practices usage rules

ash_postgres:check_constraints usage

ash_postgres:check_constraints usage rules

ash_postgres:configuration usage

ash_postgres:configuration usage rules

ash_postgres:custom_indexes usage

ash_postgres:custom_indexes usage rules

ash_postgres:custom_sql_statements usage

ash_postgres:custom_sql_statements usage rules

ash_postgres:foreign_keys usage

ash_postgres:foreign_keys usage rules

ash_postgres:migrations usage

ash_postgres:migrations usage rules

ash_postgres:multitenancy usage

ash_postgres:multitenancy usage rules

usage_rules:elixir usage

usage_rules:elixir usage rules

usage_rules:otp usage

usage_rules:otp usage rules

About