# AGENTS.md — Dashboard Starter Master Index

Read this file first. Open only the referenced document or source file needed for the current task; do not rescan the whole template.

## Stack

- Next.js 16 App Router, React 19, strict TypeScript
- MUI 9 + Emotion with CSS variables and light/dark modes
- Arabic (default RTL) and English (LTR) via i18next
- React Hook Form + Zod for forms
- Axios + SWR for remote data
- Yarn 1.22, Node.js 22.12+

## Commands

```bash
yarn dev
yarn build
yarn lint
yarn lint:fix
yarn fm:check
yarn fm:fix
yarn tsc:check
```

The development server uses port 8082.

## Source map

| Directory | Ownership |
| --- | --- |
| `src/app` | Thin App Router pages and layouts |
| `src/sections` | Feature/domain screens; `records` is the local reference example. `access-control` owns roles, the permission tree, and the pages that feed it |
| `src/components` | Reusable, domain-independent UI |
| `src/layouts` | Dashboard shell, header, navigation, account UI |
| `src/theme` | Tokens, palettes, typography, shadows, component overrides |
| `src/locales` | i18n setup and Arabic/English JSON resources |
| `src/routes` | Central route paths and router wrappers |
| `src/lib` | Axios client, endpoint registry, enums, schema helpers |
| `src/hooks` | Application-specific data/filter hooks |

## Read by task

- Components: `docs/COMPONENTS.md`
- Table/list pages: `docs/TABLE-PATTERN.md`
- Layout, page, route, and nav work: `docs/LAYOUTS.md`
- Theme/styling: `docs/THEME.md`
- Forms: `docs/FIELDS.md`
- Icons: `docs/ICONS.md`
- Backend integration: `docs/API-INTEGRATION.md`
- Roles and permissions: `src/sections/access-control` — the role screen (`/dashboard/access-control/roles/[id]`) both assigns permissions and edits the tree they come from. Ticks stay a local working copy until "save"; the tree endpoint returns only the request locale, so edit dialogs refetch the record for both locales before opening.
- Architecture and ownership: `docs/ARCHITECTURE.md`

## Working rules

1. Search with `rg` before opening files. Ignore `node_modules`, `.next`, `out`, `dist`, `build`, and generated assets.
2. Use `src/...` imports. There is no `@/` alias.
3. Keep App Router pages thin. Put domain behavior in `src/sections/<domain>/`.
4. Put reusable, data-agnostic behavior in `src/components/<name>/` with an `index.ts` barrel; update `docs/COMPONENTS.md` in the same change.
5. Reuse existing components before adding a wrapper or dependency.
6. Forms must use React Hook Form + Zod + `Form`/`Field.*`; do not manage form fields with ad-hoc `useState`.
7. Use theme tokens through `sx`, `theme.vars`, and `theme.spacing`. Do not hardcode colors. Keep RTL logical and verify Arabic and English.
8. Use the project `Iconify` wrapper only; register missing offline icons as described in `docs/ICONS.md`.
9. Add routes to `src/routes/paths.ts` and navigation to `src/layouts/nav-config-dashboard.tsx`.
10. Keep API configuration in `src/lib/axios.ts`; do not create parallel fetch clients.
11. Use `DataTable` for list screens and the server-shaped page/search/filter contract shown in `docs/TABLE-PATTERN.md`.
12. Never ship mock data from the example as production data. Keep mocks visibly named and replace them when the first real API is connected.
13. Add every user-facing string to both `ar` and `en` locale files.
14. Run formatting, lint, TypeScript, and a production build before handoff.
15. Do not use Playwright or any browser automation for verification, and do not add E2E browser tests. The user performs all visual and interaction testing manually; agents verify only with formatting, lint, TypeScript, and production builds.
16. Every form field required by its Zod schema or API contract must pass the component's `required` prop so its label displays `*`. Keep optional fields unmarked, and add or update a component test that verifies the required state whenever a form is created or changed.

## Authentication mode

`NEXT_PUBLIC_AUTH_SKIP=true` enables the local demo user and makes the starter open immediately. Before production, set it to `false`, implement the backend contract in `src/auth/context/jwt/`, verify cookie/CSRF behavior, and add the sign-in route.

## graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

When the user types `/graphify`, invoke the `skill` tool with `skill: "graphify"` before doing anything else.

Rules:
- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).