Imported from caltman24/Zap (AGENTS.md). Install upstream with npx skills add caltman24/Zap. Copyright stays with the author.

AGENTS

Use this file as project-specific implementation context.

Architecture

• Remix app (client/):
  • Browser should not call the .NET API directly. Use Remix loaders/actions and the shared client in client/app/services/api.server/apiClient.ts.
  • Auth state lives in cookie session (client/app/services/sessions.server.ts) with tokens and user. In protected loaders/actions, call apiClient.auth.getValidToken(session) and forward returned Set-Cookie headers when present.
  • Use client/app/data/permissions.ts with validateRole for role checks instead of ad-hoc role logic.
  • Reuse shared route logic when available (for example client/app/commonRoutes/projectDetails/*) instead of duplicating behavior across route variants.
• .NET API (server/Zap.Api):
  • Follow Vertical Slice Architecture: place feature code under Features/<Feature>/{Endpoints,Services,Filters} and keep endpoint handlers thin.
  • Endpoints follow the IEndpoint pattern (static Map) and must be registered in Configuration/Endpoints.cs.
  • Enforce tenant/role access with existing extensions and filters (WithCompanyMember, WithProjectCompanyValidation, WithTicketCompanyValidation) rather than custom ad-hoc checks.
  • Prefer FluentValidation request validators with .WithRequestValidation<TRequest>().

Working Rules

• Prefer existing patterns over introducing new abstractions.
• Keep changes aligned with the current system design.
• Add new logs only when they provide clear operational value or are needed to diagnose a real failure path.
• Do not add logs just because a code path exists; avoid routine success logs, duplicated logs, and low-signal debug noise.
• For Development, prefer readable diagnostic logs that help local debugging.
• For Production, log only the minimum needed for support and incident response: startup/shutdown, request failures, slow requests, rate limiting, and other abnormal or security-relevant events.
• Never log secrets, tokens, passwords, claims dumps, request bodies, or other sensitive user data.

Testing Strategy

• Keep server/Zap.Tests/Features/ for integration tests that verify HTTP behavior, auth, filters, persistence, and role-sensitive workflows end to end.
• Keep server/Zap.Tests/Unit/ for fast isolated tests around validators, permission rules, capability logic, history/formatting helpers, and other branching business logic.
• Do not add unit tests for thin endpoint handlers, filters, auth wiring, or provider-specific query behavior unless there is clear branching logic worth isolating.
• Prefer integration tests when the real value is routing, database interaction, or full request/response flow.
• Prefer unit tests when the real value is a rule matrix, a validator, or a side-effect decision that is easier to verify in isolation.

Make small, reviewable changes only.

Follow these constraints strictly:

1. LIMIT FILE CHANGES Do not modify more than 5–8 files in a single implementation step.

If a change requires more files, split the work into multiple steps and stop after the first step.

2. ONE CONCERN PER STEP Each implementation step should solve only one concern.

Examples:

• update server authorization
• update database query filtering
• update API endpoint behavior
• update client UI
• add tests

Do not combine multiple concerns in a single change.

3. DO NOT TOUCH UNRELATED CODE Only modify files directly required for the change. Do not refactor, rename, or reorganize unrelated files.

4. FOLLOW EXISTING ARCHITECTURE Reuse existing patterns, services, helpers, and structure. Do not introduce new patterns unless explicitly instructed.

5. AVOID DUPLICATED LOGIC Before adding new logic, search the repository for similar functionality and reuse existing code when possible.

6. NO LARGE REFACTORING Do not perform sweeping refactors while implementing features. If refactoring is needed, propose it separately.

7. STOP AFTER IMPLEMENTATION After completing the implementation step, stop and summarize:

• files changed
• what logic was introduced
• potential follow-up steps

Do not automatically proceed to additional steps unless asked.

Your priority is safe, incremental changes that are easy to review.