# 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.

## ISAC editor lifecycle

All ISAC data-management editors must follow the same successful-save behavior:

1. Saving an edit to an existing record closes the editor and returns the user
   to the registry.
2. Saving a newly added record keeps the editor open with a fresh blank record
   so consecutive data entry remains fast.
3. Validation errors keep the editor open and preserve the entered values.
4. Server actions must return the add/edit mode and a unique result token;
   client-side reactive handling must consume each token only once to avoid
   repeated state updates.

Apply this convention whenever an ISAC editor is added or materially changed.

## 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.