# AGENTS.md

## Purpose
Repository-level operating rules for Codex and collaborators.

## Core Workflow Rules
- Never run `git push` unless the user explicitly asks for it in the current turn.
- After code changes, stop at local verification and report status before any remote action.
- Prefer `npm.cmd` / `npx.cmd` in this Windows + Codex environment.
- Distinguish sandbox issues from project issues before changing env vars or system setup.

## Editing Rules
- Use `apply_patch` as the default file editing method.
- If `apply_patch` fails (especially with no actionable error output), use the PowerShell fallback workflow in `DEBUGGING.md` under `File Edit Fallback (apply_patch -> PowerShell)`.
- In fallback mode, always read before write and verify after write to prevent accidental overwrites.

## Safety Rules
- Do not run destructive commands unless explicitly requested.
- Treat these as destructive/high-risk: `git reset --hard`, `git clean -fdx`, recursive forced delete.
- If a command can affect remote history or shared environments, require explicit user confirmation in the same turn.

## Runtime Validation Rules
- `npm run build` is required but not sufficient for homepage/runtime-heavy changes.
- For Home/Hero/Navbar or visual-runtime changes, run `npm.cmd run smoke:home` when feasible.
- If smoke fails with sandbox-style spawn/permission errors, retry with elevated execution before concluding code is broken.

## Reference Docs
- Runtime/white-screen troubleshooting: `DEBUGGING.md`
- PR validation checklist: `PR_CHECKLIST.md`

## Notes
- Keep this file concise and behavior-focused.
- Put detailed diagnostics and step-by-step playbooks in `DEBUGGING.md`.

## Task Completion Reporting
- At the end of each task, report:
  - files changed
  - verification commands run
  - key outputs (pass/fail or important errors)