mantine-analytics-dashboard: Instructions file for Codex

AGENTS.md — Mantine Analytics Dashboard

Package manager

• Lockfile is pnpm-lock.yaml. Use pnpm, not npm/yarn, even though README and CI workflows reference npm/yarn.

Commands

pnpm dev             # localhost:3000, React Compiler enabled
pnpm build           # next build
pnpm start           # next start
pnpm lint            # next lint
pnpm prettier        # prettier . --write
pnpm storybook       # port 6006
pnpm build-storybook
pnpm changeset:add   # add a changeset before PRs
pnpm generate:component Foo [basic|interactive|table|card]

• There is no test runner. "test": "" in package.json and .husky/pre-commit runs npm test (no-op).
• lint-staged is configured in package.json but NOT wired to husky — Prettier does not run on staged files automatically.
• pnpm generate:component is buggy: it writes to ./components/ instead of ./src/components/. Verify paths and move files manually.

Architecture

• Single Next.js 16 app (not a monorepo). App Router in src/app/.
• Mock API routes in src/app/api/*/route.ts read JSON from public/mocks/*.json and return: { succeeded, data, errors: string[], message } (no timestamp; errors is string[], not the IApiError[] in src/types/api-response.ts).
• middleware.ts is at the project root (not src/app/). It is a no-op — all routes are public.
• Provider nesting: SystemNotificationsProvider → ThemeProvider.
• SystemNotificationsProvider loads the latest announcement from public/system-announcements.json and persists dismissed IDs in localStorage (system-notifications). If every loaded announcement is already dismissed, it clears old dismissals and retries so genuinely new announcements surface.
• Theme is static: layout defaults are fixed in src/layouts/Main/MainLayout.tsx; no dynamic theme customizer or localStorage theme persistence.
• Single fetch idiom: useApiGet for GET, useApiWrite for POST/PUT/DELETE. All endpoint paths come from src/routes/api.ts; never hardcode /api/... strings.
• Server components never fetch the app's own /api routes over HTTP, and there is no NEXT_PUBLIC_API_URL. Read fixtures directly with loadMock (never throws, returns { data, error }) or readMock from src/lib/api/mock-route.ts, or mockStore for by-id reads. Client components use useApiGet/useDashboardResource.
• Dead hook file src/lib/hooks/useApi.ts has been removed. The remaining convenience hooks live in src/lib/hooks/useApiGet.ts for GET and src/lib/hooks/useApiWrite.ts for writes.