> For the complete documentation index, see [llms.txt](https://suigar.gitbook.io/suigar-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://suigar.gitbook.io/suigar-docs/end-to-end-ai-map.md).

# Codex maintenance

Use this map before broad Suigar passes that touch frontend, backend, admin, infra, or generated casino assets.

## First Checks

1. Run git status --short from repo root and identify unrelated dirty work.
2. Read nearest AGENTS.md for every subtree you plan to touch.
3. Read docs/codex/frontend.md for the production frontend, docs/codex/frontend-v3.md for the casino-gacha prototype, and docs/codex/backend.md for the Nest API.
4. Run `./scripts/with-runtime.sh pnpm run plan:validation` to get the path-based validation checklist for the current diff when the ambient shell is drifted.
5. Run `./scripts/with-runtime.sh pnpm run audit:refactor -- --json --min-lines=200` to rank authored hotspots across active workspaces, shared packages, Suigar v2 Move, Python, and root tooling without scanning generated or vendored trees.
6. Run `./scripts/with-runtime.sh pnpm run check:readiness` before broad maintenance handoff when feasible; it includes the path-only repository hygiene check. Run `./scripts/with-runtime.sh pnpm run check:toolchain` before broad CI, dependency, workflow, or environment changes. Run `./scripts/with-runtime.sh pnpm run check:runtime` before investigating local-only build/test/dependency failures. Run `./scripts/with-runtime.sh pnpm run check:workflows` when GitHub Actions YAML changes if ambient `pnpm` is drifted.
7. Pick one reversible slice. Avoid sweeping refactors across dirty backend/admin/frontend files unless the user explicitly asks for that exact slice.

## Area Boundaries

* frontend/: production Vite app. Use its own AGENTS.md and existing UI system.
* poc-frontend-v3/: experimental white-label casino frontend. Keep art, tenant content, texture docs, and casino primitives centralized.
* backend/: NestJS and Prisma. Follow backend/AGENTS.md before migrations or schema work.
* admin-panel/: Next admin UI. Follow admin-panel/AGENTS.md before editing pages/components.
* packages/: shared packages and MCP code. Keep generated dist changes intentional.
* infrastructure/: Terraform and deploy notes. Treat as ops-sensitive.

## Best-Practice Defaults

* Prefer typed shared helpers over repeated local maps or conditionals.
* Extract pure policy/formatting logic before changing behavior.
* Keep controller/services and page components as orchestration/composition layers.
* Keep user-facing strings simple and do not leak technical internals.
* Do not modify applied Prisma migrations without explicit instruction.
* Do not rotate model credentials to bypass quota, rate, spend, or account limits.
* Never revert unrelated dirty work.
* Never re-track recipient exports, retired generated clients, bytecode, Playwright output, or `.codex-artifacts/`; `pnpm run check:repo-hygiene` enforces this without reading file contents.
* Keep Node pinned exactly across root `package.json`, `.node-version`, `.nvmrc`, `.mise.toml`, and GitHub Actions. Use `./scripts/with-runtime.sh pnpm run check:toolchain` after any runtime metadata change.

## Validation Ladder

Use the smallest meaningful gate for the slice:

* Toolchain, CI, or dependency metadata: `./scripts/with-runtime.sh pnpm run check:readiness`; for narrower slices use `./scripts/with-runtime.sh pnpm run check:toolchain`, `./scripts/with-runtime.sh pnpm run check:runtime` for local shell drift, `./scripts/with-runtime.sh pnpm run check:workflows` for GitHub Actions YAML, then the narrow workflow/script validator if one exists.
* Unsure which commands apply: `./scripts/with-runtime.sh pnpm run plan:validation`. Use `./scripts/with-runtime.sh pnpm run plan:validation:strict` after changing planner coverage or broad repo structure.
* Docs only: markdown inspection plus link/path checks.
* poc-frontend-v3 code/assets: `pnpm run validate:all`, then `pnpm run build` from `poc-frontend-v3/`.
* production frontend code: `pnpm run typecheck`, targeted tests, then `pnpm run build` from `frontend/` depending on scope.
* backend code: pnpm run test for targeted specs when available, then pnpm run build.
* Prisma/migrations: inspect migration SQL, run Prisma status/dev checks per backend/AGENTS.md.
* Cross-area behavior: run the narrow frontend/backend tests that cover the contract.

## Local Tool Prerequisites

* `pnpm run check:workflows` runs pinned `actionlint` through `pnpm exec mise exec -- actionlint`. If the tool is missing locally, run `pnpm run setup:tools actionlint`.
* `./scripts/with-runtime.sh <command>` runs commands under the repo-pinned Node and pnpm. It prefers local/global `mise` and falls back to the pinned npm `@jdxcode/mise` package.

## Useful Next Slices

* Move poc-frontend-v3 hero-stage placements into typed data to reduce JSX complexity.
* Add a visual QA route for poc-frontend-v3 casino primitives and generated art placement recipes.
* Update docs/codex/backend.md after the current payments/ops changes settle.
* Add backend domain maps for payments, ops monitoring, social integrations, and user profile currency once those dirty files are stable.