shd.build/AGENTS.md

Repository Instructions

SHD design-system maintenance

Treat docs/DESIGN_SYSTEM.md and the shared tokens and patterns in src/app.css as maintained parts of the product.

Whenever a change makes a significant visual or interaction-design decision, update the design system in the same change. This includes:

• introducing or changing colors, typography, spacing, borders, elevation, or motion;
• creating a new reusable layout, navigation, table, editor, form, card, status, or feedback pattern;
• materially changing dashboard density, hierarchy, responsive behavior, or accessibility behavior;
• changing the semantic meaning of an existing visual state;
• establishing a pattern that future pages or components should follow.

For significant design changes:

1. Reuse or extend the CSS custom properties in src/app.css; do not scatter near-duplicate hard-coded values throughout new components.
2. Update docs/DESIGN_SYSTEM.md with the new or revised rule, token, pattern, usage guidance, and responsive or accessibility considerations.
3. Refactor repeated UI into a reusable component when that makes the pattern clearer and reduces divergence.
4. Preserve the SHD design principles: tactical but restrained, data-first, square and engineered, orange reserved for action and emphasis, and explicit textual state indicators.
5. Verify hover, pressed, focus-visible, pending, disabled, error, success, and reduced-motion behavior where applicable.
6. Run npm run check and npm run build before completing the change.

Minor alignment fixes, isolated bug fixes, and corrections that do not introduce or revise a reusable design decision do not require a documentation update.

If uncertain whether a visual change is significant, update the design system.

Database preservation

Development data is valuable and may be entered by non-technical contributors. Treat embedded database files as persistent user data, not disposable build artifacts.

Before deleting, replacing, recreating, renaming, or destructively migrating a database—and before any major schema change—create a timestamped JSON backup with npm run db:backup.

Database work must follow these rules:

1. Confirm which environment and exact database path are in scope.
2. Stop processes that hold the embedded database lock before backup or restore.
3. Create and verify a JSON backup before destructive work.
4. Never overwrite or delete the only available backup.
5. Keep backups out of Git; they can contain user records and password hashes.
6. Prefer additive, repeatable schema migrations over database recreation.
7. After a restore, run the schema migration and verify record counts and critical entities before resuming data entry.
8. Report the backup path when completing database-destructive work.

Use npm run db:restore -- <backup-file> only with an empty, migrated target database. The restore script intentionally refuses to merge into a populated database.