shd.build/AGENTS.md

# Repository Instructions

## Parallel task execution

For substantial changes, use subagents as a standard practice when the work can
be divided into concrete, independent tasks that provide real parallel progress.

1. Delegate bounded mechanical work to faster, lower-reasoning agents. Suitable
   tasks include focused code discovery, repetitive call-site updates,
   documentation, and isolated test coverage.
2. Keep architecture, security-sensitive behavior, database migrations, shared
   data-model decisions, and complex debugging with a suitably capable agent.
3. Assign explicit file or subsystem ownership before parallel edits. Avoid
   having multiple agents edit the same files unless their work is deliberately
   sequenced.
4. Do not delegate tightly coupled work merely to increase agent count. Keep it
   with the primary agent when coordination would cost more than it saves.
5. The primary agent remains responsible for integrating results, reviewing
   diffs, resolving cross-cutting concerns, and running the final required
   validation.
6. Subagents must follow every repository rule that applies to their assigned
   work, including design-system maintenance, audit logging, and database
   preservation.

## Documentation prose

Use the `stop-slop` skill whenever an agent creates or changes project
documentation. Apply its review to the complete affected document, including
sections that the change did not introduce.

Preserve technical meaning, commands, paths, formulas, links, policy strength,
and product terminology. Remove filler, vague claims, formulaic contrasts,
manufactured emphasis, false agency, and repetition. Prefer active voice and
specific subjects. Do not weaken terms such as `must`, `never`, or `always`
when they express a real requirement.

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

## Reusable interface patterns

Favor shared, generic components whenever a visual or interaction pattern is
used in more than one place or is likely to recur. Before adding page-local
markup and styles, check `src/lib/components` and extend an appropriate shared
component when practical. When introducing a reusable pattern, migrate the
clearest existing duplicate in the same change so the component has more than
one real consumer.

For small, finite option sets, prefer the shared segmented-choice pattern over
a dropdown. Use radio semantics for exactly one choice and checkbox semantics
for additive independent choices. Reserve dropdowns for long, dynamic, or
search-oriented option sets. Preserve native form semantics, keyboard access,
focus-visible, selected, disabled, pressed, responsive, and reduced-motion
behavior in shared controls.

## 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.
5. When a successful add keeps an icon-enabled editor open, increment the
   shared upload reset token so the native file input, generated preview,
   filename, drag/paste state, validation message, and removal state are fresh
   for the next record.

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

## ISAC audit logging

Every successful server-side mutation performed through ISAC must create an
append-only audit event. Audit coverage is a required part of implementing or
changing any ISAC module, action, endpoint, bulk operation, moderation control,
identity operation, access-policy change, archive action, or destructive action.

Follow these rules:

1. Use the shared audit utilities in `src/lib/server/audit.ts`; do not invent
   module-specific audit formats or write directly to `audit_log` in new code.
2. Record the authenticated operator ID, stable category, specific action,
   target entity ID, timestamp, and useful before/after snapshots.
3. Categories describe durable operational domains such as `game_data`,
   `user_access`, `user_moderation`, `identity`, and `role_management`.
   Actions describe the exact event in namespaced past tense, such as
   `weapon.updated`, `attribute.archived`, or `moderation.blocked`.
4. Capture changes to the primary row and its relationships. When an action
   replaces permission sets, compatible brands, talents, effects, tiers, or
   other linked records, include the meaningful previous and resulting sets.
5. Create audit records only after validation succeeds and the requested
   mutation has completed. Rejected, unauthorized, or validation-failed
   requests must not appear as successful mutation events.
6. Never include password hashes, session tokens, magic-link tokens, OAuth
   state, passkey public-key bytes, SMTP credentials, environment secrets, or
   other authentication secrets in audit snapshots. Minimize personal data to
   what is necessary for security, support, and accountability.
7. Audit visibility is controlled by `audit.view`. The read-only `Auditor` role
   grants `isac.access` and `audit.view`; it must not implicitly grant mutation,
   moderation, identity-management, or user-access permissions.
8. New audit categories and actions must remain searchable in the Audit History
   registry. Update its grouped filters when a new durable operational domain is
   introduced.
9. Preserve audit history during normal record archival and soft deletion.
   Never add an ISAC action that edits or deletes audit records without an
   explicit retention policy, legal review, and separately audited authority.
10. Tests and handoff verification for an ISAC mutation must include confirming
    that its audit event contains the correct actor, category, action, target,
    and change evidence.
11. Audit reversion is a separately authorized compensating action, never a
    history rewrite. Require `audit.revert`, an explicit confirmation
    interaction, current-state comparison against the original after-snapshot,
    relationship validation, and a new `audit.reverted` event referencing the
    original event. Block stale, already-reverted, unsupported, destructive
    identity, and incomplete-snapshot events rather than guessing.

## 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, create a timestamped JSON backup with `npm run db:backup`. Create the
same backup before any major schema change.

Database work must follow these rules:

1. Confirm which environment and exact database path are in scope.
2. Before every database backup or restore, inspect running processes and stop
   only this project's development-server process tree. The embedded Turso
   database holds an exclusive file lock while the dev server is running, so do
   not attempt the backup first and wait for a locking failure.
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.

## Development database maintenance

The development server is no longer a shared contributor-facing service, so
development database work does not need to optimize for minimum downtime.
Database safety remains mandatory:

1. Prefer additive, repeatable migrations and finish the migration logic before
   operating on persistent data.
2. Identify the exact environment and database path, then inspect running
   processes and stop only this project's development-server process tree.
3. Run and verify `npm run db:backup` before migration, export, restore, or
   destructive schema work. Retain and report the backup path.
4. Apply the migration or maintenance operation and verify schema state, record
   counts, and critical entities before restarting the server.
5. If an operation fails, preserve logs and the verified backup rather than
   repeatedly improvising against the database.
6. Restart the development server when maintenance and useful verification are
   complete, then confirm a basic health or page check.

Production and staging remain persistent shared environments. Their deployment,
backup, synchronization, and maintenance safeguards are defined separately in
`docs/DEPLOYMENT.md`.