grit init writes a CLAUDE.md / AGENTS.md template that codifies framework conventions

[MUKE-coder]

Problem

I learned the rules by doing — "always SearchableSelect for >5 options", "always CurrencyField for money", "always Drawer for forms", "always envelope responses", "always `formatCurrency(amount, currency)`". Each new dev (or AI assistant) re-learns them on PR review.

Proposal

`grit init` writes a `CLAUDE.md` at the repo root with the framework's hard rules:

```md

Grit conventions

Forms

• Always use for monetary inputs (auto-formats commas).
• Always use for FK fields and enums with > 5 options.
• Always use / — never raw <input type="date">.
• Mount create/edit forms inside , not modals.

Data

• All list endpoints return { data, meta: { total, page, page_size, pages } }.
• Use makeList / makeGet / useCreate / useUpdate / useDelete from @grit/hooks.
• Mutations auto-toast — pass successMessage: false to opt out.

Auth

• Gate routes with RequirePermission("module.action"), not RequireRole.
• Add new permissions to the catalogue in models/role_seed.go — they seed on next boot.

Backend

• Errors: respond.NotFound / respond.Validation / respond.Forbidden — never raw c.JSON.
• Activity log fires automatically; don't hand-roll audit writes.
  ```

Subdirs that diverge get their own (e.g. `apps/web/AGENTS.md` for breaking-change Next.js).

Acceptance

A new contributor or AI assistant reads one file and gets the conventions right on first PR.

Reference

rental-manager has a `apps/web/AGENTS.md` flagging Next.js breaking changes — same idea, framework-wide.

[MUKE-coder]

Shipped in v3.17.0 (commit 7863ad5).

New CLI command grit init writes CLAUDE.md + AGENTS.md to the current directory. Both files have the same content — different LLM tooling looks for different filenames, and shipping both means the conventions are found regardless of which assistant the developer is using.

The doc covers the framework's hard rules:

• Forms — CurrencyField / SearchableSelect / DateField / Drawer / FormGrid+FormSection+FormActions / StatusBadge
• Frontend stdlib — format helpers, apiErrorMessage, apiErrorCode, apiErrorFields
• Data — paginate.List envelope, Searchable + Sortable conventions
• Backend — respond.NotFound / Validation / Forbidden helpers, activity log auto-fires, realtime hub topics
• Resources — grit generate resource flags, field modifiers (:optional), belongs_to:User syntax, the auto-Export endpoint
• Sync — local-first writes, manual Sync trigger, conflict dialog, Version columns
• Auth — RequireRole middleware, refresh-token interceptor skip-list, Idempotency-Key
• What NOT to do — direct GORM in handlers, raw <input type=number> for money, hand-rolled audit writes

Skips existing files unless --force is passed. Re-run with --force after a major framework upgrade to refresh.

Closing.