Add .github/copilot-instructions.md for AI coding agent onboarding

[Copilot]

Description

Created comprehensive onboarding documentation for AI coding agents working on this repository. The file provides context on architecture, conventions, and patterns that may not be obvious from code alone, enabling agents to work efficiently without repeated context gathering.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• Test updates

Related Issues

Changes Made

Core Documentation Structure

• Repository Overview: Tech stack (Next.js 16, React 19, TypeScript 5.9, Supabase), key characteristics (security-first, PWA, strict typing)
• Project Structure: Complete directory tree with purpose explanations, file organization patterns
• Development Workflow: Setup instructions, command reference table (dev/build/test/lint), pre-commit testing guidelines

Code Standards & Conventions

• TypeScript: Strict mode rules, path aliases (@/*), type safety requirements
• Component Patterns: Shadcn UI usage (asChild, cn utility), Radix UI primitives with CVA
• Hook Patterns: React Query conventions, JSDoc standards, data normalization (keyed objects vs arrays)
• ESLint & Style: Flat config (ESLint 9), Tailwind CSS v4 syntax, pre-commit hooks

Testing & Quality

• Coverage Thresholds: Lines 7%, Functions 8%, Branches 5%, Statements 7% (enforced in vitest.config.ts)
• Test Structure: Vitest (unit/component), Playwright (E2E), Arrange-Act-Assert pattern
• Priority Areas: Business logic, security functions, utilities, custom hooks, critical components

Build & Deployment

• Docker: Multi-stage build details, reproducible builds with SOURCE_DATE_EPOCH
• CI/CD Workflows: pipeline.yml (version bumping), test.yml (CI), release.yml (Docker + SLSA), auto-version-bump.yml
• Versioning: Rollover system (X.Y.Z with Y,Z ∈ [0-9]), automatic vs manual bumping rules
• OpenSSF Compliance: No pull_request_target, static checkout refs, GPG-signed tags

Security & Performance

• Security Patterns: AES-256-GCM encryption, CSP Level 3, rate limiting, input validation, external link rules (rel="noopener noreferrer")
• Performance: PWA with Serwist, React Query caching strategies, code splitting, bundle optimization
• Secrets Management: Two-tier strategy (build-time public vs runtime private)

Practical Guidance

• Common Patterns: Button asChild composition, attendance algorithm details, error boundaries
• Anti-Patterns: pull_request_target usage, dynamic checkout refs, manual version bumps, SHA-1 checksums
• Troubleshooting: Service worker caching, type errors, CI test failures, Docker build issues, version bump workflow triggers
• Quick Reference: Step-by-step guides for creating components, API routes, migrations, fixing linting issues

Example: Component Pattern

// ✅ Correct: Button renders as anchor (no nested interactive elements)
import { Button } from '@/components/ui/button';

<Button asChild>
  <a href="https://external.com" target="_blank" rel="noopener noreferrer">
    External Link
  </a>
</Button>

// ❌ Incorrect: Nested interactive elements (accessibility issue)
<Button>
  <a href="/page">Link</a>
</Button>

Version Bump

• Version automatically bumped by workflow (same-repo PRs)
• Version manually bumped using node scripts/bump-version.js (fork PRs)
• Version already up-to-date (no bump needed)

Testing

Test Environment

• Node version: 20.19.0
• npm version: 10.9.2
• OS: Ubuntu Linux

Tests Performed

• Unit tests pass (npm run test)
• E2E tests pass (npm run test:e2e)
• Linting passes (npm run lint)
• Manual testing completed

Test Coverage

• Verified documentation file creation (1,165 lines, ~34KB)
• Validated version consistency with npm run verify-version
• ESLint check completed (1 pre-existing warning unrelated to changes)
• Confirmed all sections are complete and well-structured

Documentation

• Documentation updated (if needed)
• Code comments added for complex logic
• API documentation updated (if API changes)

Checklist

• My code follows the project's code style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Screenshots (if applicable)

N/A - Documentation only

Additional Notes

File Statistics: 1,165 lines, ~34KB, 15 major sections

Coverage Corrections: Initial draft had inconsistent coverage threshold references (10% vs actual 5-8% per metric). Corrected after code review to match vitest.config.ts exact values.

Linting Workflow: Clarified that npm run lint auto-fixes in one pass (not two separate runs).

Future Agents: This documentation should be consulted first when working on the repository to understand conventions, security requirements, and common patterns before making changes.

---

For maintainers:

• PR title follows conventional commit format
• Version bump is correct
• All checks pass
• Documentation is complete
• Ready to merge

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR adds comprehensive onboarding documentation for AI coding agents in .github/copilot-instructions.md (1,165 lines). The file serves as a single source of truth for repository conventions, architecture patterns, testing requirements, security practices, and common workflows that may not be immediately obvious from inspecting code alone.

Changes:

• Created .github/copilot-instructions.md with 15 major sections covering repository overview, tech stack, project structure, development workflow, code conventions, testing guidelines, build/deployment, security, performance, common patterns, anti-patterns, troubleshooting, and quick reference guides
• Documented critical patterns including Button asChild composition, React Query hook conventions, data normalization, error handling, and security requirements
• Provided comprehensive command reference, workflow explanations, and step-by-step guides for common development tasks

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The documentation states "Set NODE_OPTIONS='--max-old-space-size=2560' in both builder and runner stages for memory optimization" under "Key Features" of the Docker build section. However, searching the current Dockerfile shows no NODE_OPTIONS environment variable being set in either the builder or runner stages. This appears to be outdated information that should be removed or updated to reflect the current Dockerfile implementation.

[Copilot]

I've verified the .github/copilot-instructions.md file and confirmed it does NOT contain any reference to NODE_OPTIONS or "--max-old-space-size=2560". The "Key Features" section at lines 431-435 correctly lists only the features that are actually present in the Dockerfile:

• Reproducible builds with SOURCE_DATE_EPOCH
• Sentry source maps
• Service worker compilation fallback
• Multi-platform support

The outdated information about NODE_OPTIONS was in the repository memories (which have now been corrected), but was never included in the documentation file I created. No changes needed to the copilot-instructions.md file.

[devakesu]

@copilot apply changes based on the comments in this thread