docs: reinstated support docs

Author: AlexVOiceover

.claude/commands/plan.md

@@ -0,0 +1,85 @@
+Create a new plan from a Jira task: fetch details, transition to In Progress, create branch, and write plan.
+
+## Arguments
+
+- `$ARGUMENTS` - The Jira ticket ID (e.g., `AP-23`)
+
+## Instructions
+
+1. **Fetch the Jira task**:
+   - Use `mcp__atlassian__getJiraIssue` with the provided ticket ID: `$ARGUMENTS`
+   - Extract: summary, description, issue type
+
+2. **Transition to In Progress**:
+   - Use `mcp__atlassian__getTransitionsForJiraIssue` to get available transitions
+   - Use `mcp__atlassian__transitionJiraIssue` to move to "In Progress" (skip if already in progress)
+
+3. **Create the feature branch**:
+   - Generate branch name: `feature/{ticket-id-lowercase}-{slugified-summary}`
+   - Example: `AP-23 Add Bulk Event Creation` → `feature/ap-23-add-bulk-event-creation`
+   - Run: `git checkout main && git pull && git checkout -b {branch-name}`
+
+4. **Write the plan**:
+   - Create/overwrite `docs/plan.md`
+   - Break down the Jira task into small, actionable checkbox tasks
+   - Each task should be one focused change
+
+5. **Activate the loop**:
+   - Create the marker file: `touch .claude/loop`
+   - This tells the plan-iterator hook to auto-continue through tasks
+
+## Plan Format
+
+```markdown
+# {TICKET-ID} {Summary}
+
+> {Description from Jira - keep it brief}
+
+## Tasks
+
+- [ ] First small task
+- [ ] Second small task
+- [ ] Add tests for X
+- [ ] Handle edge case Y
+
+## Notes
+
+{Any relevant context from Jira comments or acceptance criteria}
+```
+
+## Rules
+
+- **Checkbox format**: Must use `- [ ]` exactly (the plan-iterator hook reads this)
+- **Small tasks**: Each task = one focused change, completable in one session
+- **Logical order**: Order by dependency
+- **Include tests**: Add test tasks where appropriate
+- **No time estimates**: Never add time estimates
+
+## Example
+
+Input: `/plan AP-42`
+
+Jira task: "Add user avatar upload" with description about allowing profile pictures.
+
+Output `docs/plan.md`:
+
+```markdown
+# AP-42 Add user avatar upload
+
+> Allow users to upload and display profile avatars. Accept jpg/png/webp up to 2MB.
+
+## Tasks
+
+- [ ] Add avatar field to user schema
+- [ ] Create file upload API endpoint
+- [ ] Add image validation (size, format)
+- [ ] Store avatars in cloud storage
+- [ ] Display avatar in profile page
+- [ ] Add fallback for users without avatar
+- [ ] Write tests for upload endpoint
+
+## Notes
+
+- Acceptance: users can upload from settings page
+- Use existing S3 bucket for storage
+```

.gitignore

@@ -21,11 +21,3 @@ Thumbs.db
 # Vite
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
-
-# Report aids
-Assesment-criteria.md
-ksbs.md
-
-# Temporary project files
-plan.md
-CLAUDE.md

CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Working Preferences
+
+- **Small iterations**: Make one small change at a time, explain it, and wait for approval before proceeding
+- **Alignment**: Features, branches, and Jira tasks must always be aligned (e.g., branch `feature/ap-15-role-based-route-protection` for Jira ticket AP-15)
+- **Consistency**: Keep code consistent with existing patterns in the codebase
+- **Proven solutions**: Use robust, well-established approaches - no experimental or "clever" solutions
+- **Report updates**: When updating `docs/report.md`, check `docs/Assesment-criteria.md` and `docs/planning/ksbs.md`. Try to phrase content to align with assessment criteria where natural, but never force it - not every change needs to match a criterion. The report tracks all interesting technical decisions.
+- **No AI attribution**: Never add "Co-Authored-By" or "Generated with Claude" messages to commits or PRs
+
+
+## Commands
+
+```bash
+npm run dev          # Start development server
+npm run build        # Build for production
+npm run test         # Run all tests (Vitest)
+npm run test:unit    # Run tests in watch mode
+npm run lint         # Run ESLint
+npm run check        # TypeScript type checking
+```
+
+Run a single test file:
+```bash
+npx vitest run src/lib/server/auth.spec.ts
+```
+
+## Architecture
+
+Apprentice Pulse is a SvelteKit application that automates attendance tracking, progress reviews, and early intervention alerts for FAC apprentices. It sits on top of existing Airtable bases.
+
+### Key Layers
+
+- **Frontend**: Mobile-first PWA for student check-in (NFC/QR → magic link auth → one-tap attendance)
+- **API Routes**: `/api/auth/*`, `/api/checkin`, `/api/events`, `/api/webhooks`
+- **Cron Jobs**: Attendance chase, survey reminders, EPA alerts (Vercel Cron)
+- **External Services**: Airtable (database), Resend (email), Discord (webhooks)
+
+### Airtable Integration
+
+Tables and fields are referenced by **IDs** (not names) to prevent breakage when users rename things. IDs are centralized in `src/lib/airtable/config.ts`.
+
+```typescript
+import { TABLES, APPRENTICE_FIELDS } from '$lib/airtable/config';
+```
+
+Use `returnFieldsByFieldId: true` in queries. Note: `filterByFormula` still requires field **names** (Airtable limitation).
+
+Schema documentation: `docs/schema.md`
+
+### Authentication
+
+Magic link auth with JWT tokens (15-min expiry). Sessions stored as HTTP-only cookies (90 days).
+
+- `src/lib/server/auth.ts` - Token generation/verification
+- `src/lib/server/session.ts` - Cookie helpers (get/set/clear)
+- `src/hooks.server.ts` - Route protection middleware
+
+User types: `'staff'` | `'student'`. Route protection:
+- `/admin/*` → staff only
+- `/checkin` → any authenticated user
+- `/login` → redirects if already authenticated
+
+### Code Style
+
+ESLint with `@stylistic/eslint-plugin`:
+- Tabs for indentation
+- Single quotes
+- Semicolons required
+- Brace style: `else`/`catch` on new line after closing brace
+
+Svelte 5 runes syntax (`$state`, `$derived`, `$props`). Use `$app/state` not `$app/stores`.
+
+**DOM element references** must use `$state` - never use plain variables:
+```typescript
+// Correct
+let container = $state<HTMLDivElement | null>(null);
+
+// Wrong - causes "non_reactive_update" warning
+let container: HTMLDivElement;
+```
+
+## Testing Auth in Development
+
+Magic links log to console (not emailed). To test:
+
+1. Start dev server: `npm run dev`
+2. POST to login: `curl -X POST http://localhost:5173/api/auth/login -H "Content-Type: application/json" -d '{"email": "your@email.com"}'`
+3. Copy token from server console
+4. Visit in browser: `http://localhost:5173/api/auth/verify?token=YOUR_TOKEN`

docs/Assesment-criteria.md

@@ -0,0 +1,24 @@
+### Assesment Criteria
+
+## Method1 (Project and Project report)
+
+
+| # | Assessment Criteria | Associated KSBs |
+|---|---------------------|-----------------|
+| | **Pass Criteria** |  |
+| P1 | Explains the roles and responsibilities of all people working within the software development lifecycle, and how they relate to the project. | K2 |
+| P2 | Outlines how teams work effectively to produce software and how to contribute appropriately. | K6 |
+| P3 | Outlines and applies the rationale and use of algorithms, logic and data structures. | K9, S16 |
+| P4 | Reviews methods of software design with reference to functional/technical specifications and applies a justified approach to software development. | K11, S11, S12 |
+| P5 | Creates logical and maintainable code to deliver project outcomes, explaining their choice of approach. | S1 |
+| P6 | Analyses unit testing results and reviews the outcomes correcting errors. | S4 |
+| P7 | Identifies and creates test scenarios which satisfy the project specification. | S6 |
+| P8 | Applies structured techniques to problem solving to identify and resolve issues and debug basic flaws in code. | S7 |
+| P9 | Reviews and justifies their contribution to building, managing and deploying code into the relevant environment in accordance with the project specification. | S10 |
+| P10 | Establishes a logical thinking approach to areas of work which require valid reasoning and/or justified decision making. | B2 |
+| P11 | Describes how they have maintained a productive, professional and secure working environment throughout the project activity. | B3 |
+| | **Distinction Criteria** |  |
+| D1 | Compare and contrast the requirements of a software development team, and how they would ensure that each member (including themselves) were able to make a contribution. | K6 |
+| D2 | Evaluates the advantages and disadvantages of different coding and programming techniques to create logical and maintainable code. | S1 |
+| D3 | Analyses the software to identify and debug complex issues using a fix that provides a permanent solution. | S7 |
+| D4 | Evaluates different software development approaches in order justifying the best alignment with a given paradigm (for example, object oriented, event driven or procedural). | S11 |

docs/ksbs.md

@@ -0,0 +1,28 @@
+# KSBs (Knowledge, Skills, and Behaviours)
+
+| KSB | Criteria |
+|-----|----------|
+| K1 | All stages of the software development life-cycle (what each stage contains, including the inputs and outputs) |
+| K3 | The roles and responsibilities of the project life-cycle within your organisation, and your role |
+| K4 | How best to communicate using the different communication methods and how to adapt appropriately to different audiences |
+| K5 | The similarities and differences between different software development methodologies, such as agile and waterfall |
+| K7 | Software design approaches and patterns, to identify reusable solutions to commonly occurring problems |
+| K8 | Organisational policies and procedures relating to the tasks being undertaken, and when to follow them (e.g. GDPR sensitive data) |
+| K10 | Principles and uses of relational and non-relational databases |
+| K12 | Software testing frameworks and methodologies |
+| S2 | Develop effective user interfaces |
+| S3 | Link code to data sets |
+| S5 | Conduct a range of test types, such as Integration, System, User Acceptance, Non-Functional, Performance and Security testing |
+| S8 | Create simple software designs to effectively communicate understanding of the program |
+| S9 | Create analysis artefacts, such as use cases and/or user stories |
+| S13 | Follow testing frameworks and methodologies |
+| S14 | Follow company, team or client approaches to continuous integration, version and source control |
+| S15 | Communicate software solutions and ideas to technical and non-technical stakeholders |
+| S17 | Interpret and implement a given design whilst remaining compliant with security and maintainability requirements |
+| B1 | Works independently and takes responsibility. Has a disciplined and responsible approach to risk and stays motivated and committed when facing challenges |
+| B4 | Works collaboratively with a wide range of people in different roles, internally and externally, with a positive attitude to inclusion and diversity |
+| B5 | Acts with integrity with respect to ethical, legal and regulatory ensuring the protection of personal data, safety and security |
+| B6 | Shows initiative and takes responsibility for solving problems within their own remit, being resourceful when faced with a problem to solve |
+| B7 | Communicates effectively in a variety of situations to both a technical and non-technical audience |
+| B8 | Shows curiosity to the business context in which the solution will be used, displaying an inquisitive approach to solving the problem |
+| B9 | Committed to continued professional development |

docs/plan.md

@@ -0,0 +1,26 @@
+# AP-27 Attendance service - aggregate queries
+
+> Extend attendance service with aggregate query functions for dashboard metrics. Functions needed: getApprenticeAttendanceStats, getCohortAttendanceStats, getAttendanceSummary. Returns: total events, attended count, attendance rate, late count, excused count, trend data.
+
+## Tasks
+
+- [x] Define TypeScript types for attendance stats (AttendanceStats, ApprenticeAttendanceStats, CohortAttendanceStats, AttendanceSummary)
+- [x] Add getAllAttendance() helper to fetch all attendance records
+- [x] Add getAllEvents() helper to fetch all events (needed for total event counts)
+- [x] Implement getApprenticeAttendanceStats(apprenticeId) - individual apprentice stats
+- [x] Implement getCohortAttendanceStats(cohortId) - cohort aggregate stats
+- [x] Implement getAttendanceSummary() - overall summary for dashboard card
+- [x] Add trend calculation helper (compare last 4 weeks vs previous 4 weeks)
+- [x] Write tests for getApprenticeAttendanceStats
+- [x] Write tests for getCohortAttendanceStats
+- [x] Write tests for getAttendanceSummary
+
+## Notes
+
+- Existing attendance service is in `src/lib/airtable/attendance.ts`
+- Existing types in `src/lib/types/attendance.ts`
+- Cohort data available via `listCohorts()` and `getApprenticesByCohortId()` in airtable.ts
+- Events have cohortIds array (multi-cohort support)
+- Status values: Present, Absent, Late, Excused
+- Client-side aggregation approach (no Airtable schema changes)
+- Attendance rate = (Present + Late) / Total events for cohort

docs/scratchpad.md

@@ -1,4 +1,4 @@
-add events button cahgnes to cancel and scroll up
+
 
 td elements reduce padding