Add repo docs for agent guidance

AGENTS.md

@@ -18,89 +18,107 @@ This file gives general operating guidance for coding agents working in this rep
 - Check whether there are existing tests, scripts, or conventions to follow.
 - Do not assume missing context; infer from the codebase first.
 
+## Repo State Preflight
+
+- Before starting work, inspect `git status --short`.
+- Treat pre-existing dirty files as user-owned by default.
+- Do not include pre-existing user edits in agent commits unless explicitly approved.
+- If requested work overlaps with user-owned uncommitted files, pause and ask how to proceed.
+- Encourage the user to commit or stash their work before continuing when appropriate.
+
 ## Implementation Guidance
 
 - Match the style and structure already used in the repository.
-- Avoid broad refactors unless they are necessary to complete the task.
+- Avoid broad refactors unless necessary to complete the task.
 - Add comments only where intent would otherwise be unclear.
-- Prefer explicit, boring code over abstractions introduced too early.
+- Prefer explicit, simple code over premature abstraction.
 - Keep public APIs, file layouts, and naming stable unless the task calls for a change.
 
 ## Testing Expectations
 
 - Create or update tests for every non-trivial behavior change.
-- Prefer tests that prove the user-visible or contract-level behavior, not just implementation details.
-- Run relevant tests frequently while working, not only at the end.
-- After each meaningful code change, run the smallest test scope that gives fast feedback.
-- Before finishing, run the most relevant broader verification available for the touched area.
-- If a change is not practical to test automatically, state that clearly and explain the gap.
+- Prefer tests that prove user-visible or contract-level behavior.
+- Run relevant tests frequently while working.
+- After each meaningful change, run the smallest test scope that gives fast feedback.
+- Before finishing, run broader verification for the touched area.
+- If a change cannot be tested automatically, state that clearly.
 
 ## Safety Rules
 
 - Never overwrite or revert user changes unless explicitly asked.
-- Avoid destructive commands unless the user clearly requested them.
+- Avoid destructive commands unless clearly requested.
 - Call out assumptions when they materially affect behavior.
-- If you find unrelated problems, note them separately rather than folding them into the same change.
+- If you find unrelated problems, note them separately.
 
 ## Verification
 
-- Run the smallest relevant verification available after making changes.
+- Run the smallest relevant verification after making changes.
 - If tests or checks cannot be run, say so explicitly.
-- When possible, verify both the happy path and the most likely failure path.
+- Verify both the happy path and the most likely failure path when possible.
+
+## Documentation
+
+- Re-read `AGENTS.md`, `PLAN.md`, and relevant files in `docs/` before planning or implementing.
+- Update `docs/` when behavior, structure, or standards change.
+- Update `PLAN.md` when work is completed, deferred, or split into follow-up work.
+- Do not consider work complete until code and docs are aligned.
 
 ## Commit Discipline
 
-- Commit work in logical, reviewable increments rather than as one large batch.
-- Prefer a commit after each completed unit of work that passes relevant verification.
+- Commit work in logical, reviewable increments.
+- Prefer a commit after each completed unit of work that passes verification.
 - Keep commits focused; avoid mixing unrelated changes.
-- Use clear commit messages that describe the behavior or intent of the change.
-- Do not commit broken work unless the user explicitly asks for a checkpoint commit.
+- Use clear commit messages describing behavior or intent.
+- Do not commit broken work unless explicitly requested.
 
 ## Branch Discipline
 
-- Do new feature work on a dedicated branch rather than directly on the main line.
-- Use a distinct branch for each feature, fix, or clearly scoped task.
-- Do not mix unrelated work on the same branch.
-- Start new work from `dev` unless the user specifies otherwise.
-- Keep branch names descriptive and scoped to the task.
-- Before switching branches, check for uncommitted work and avoid carrying unrelated changes forward.
-- If the current branch is not appropriate for the requested task, create or switch to a better-scoped branch before editing code.
-- Merge completed feature branches into `dev` after relevant verification passes.
+- Do new feature work on a dedicated branch.
+- Use a distinct branch per feature, fix, or scoped task.
+- Start new work from `dev` unless specified otherwise.
+- Keep branch names descriptive and scoped.
+- Do not carry unrelated uncommitted changes across branches.
+- Merge completed feature branches into `dev` after verification.
 - Reserve `main` for release-ready code.
 
-## AI Metadata Branch
+## AI Metadata
 
-- Keep AI coordination files on a dedicated `ai` branch unless the user specifies otherwise.
-- Treat files such as `AGENTS.md`, `PLAN.md`, task notes, and other agent-only working documents as AI metadata rather than product code.
+- Keep purely agent-only working notes on the `ai` branch unless specified otherwise.
 - Do not mix AI metadata commits with application feature commits.
-- When updating AI metadata, switch to `ai` before editing or committing those files.
-- Keep the `ai` branch distinct from `dev` and `main` unless the user explicitly wants those files promoted.
+- If a file is required for active repo guidance, keep it in the working branch.
 
 ## Agent Identity
 
-- Use a dedicated Git author identity for AI-created commits instead of the user's personal identity.
-- Set the Git author name for agent work to `Codex`.
-- Set the Git author email for agent work to `codex@local`.
-- Prefer per-commit identity flags such as `git -c user.name="Codex" -c user.email="codex@local" commit ...` instead of changing Git configuration.
-- If explicit author metadata is needed, use `--author="Codex <codex@local>"`.
-- Do not change the user's global Git identity for agent work.
-- Do not rely on inherited global Git identity for AI-authored commits.
+- Use a dedicated Git author identity for AI-created commits.
+- Default agent identity:
+  - Name: `Codex`
+  - Email: `codex@local`
+- Prefer per-commit identity flags:
+  - `git -c user.name="Codex" -c user.email="codex@local" commit ...`
+- Do not change the user's global Git identity.
+
+## Commit Ownership
+
+- The user and agents use separate Git identities.
+- Only agent-authored changes should be included in agent commits.
+- Do not include pre-existing user edits in agent commits unless explicitly approved.
+- If overlap exists, pause and ask before proceeding.
 
 ## Release And Versioning
 
-- Treat `dev` as the active integration branch for ongoing work.
-- Merge `dev` into `main` only when preparing a release.
-- Bump the project version only as part of release preparation unless the user asks otherwise.
-- Keep version changes in a dedicated release commit or tightly grouped release branch work.
-- Tag releases from `main` when the repository adopts a release process.
+- Treat `dev` as the active integration branch.
+- Merge `dev` into `main` only for releases.
+- Bump versions only during release preparation unless instructed otherwise.
+- Keep version changes grouped into release commits.
+- Tag releases from `main` when applicable.
 
 ## Communication
 
 - Be concise and concrete.
-- Summarize what changed, why it changed, and how it was verified.
-- Surface risks, tradeoffs, and follow-up work plainly.
+- Summarize what changed, why, and how it was verified.
+- Surface risks, tradeoffs, and follow-up work clearly.
 
 ## Scope
 
 - This file is intentionally general.
-- Add stack-specific or workflow-specific guidance here as the repository grows.
+- Add stack-specific or workflow-specific guidance as the repository grows.

docs/architecture.md

@@ -0,0 +1,38 @@
+# Architecture
+
+Walkup is a baseball walk-up song app with a React PWA frontend and a FastAPI backend.
+
+## System Overview
+
+- The frontend runs as a browser app and PWA.
+- The backend owns authentication, persisted app data, and media processing.
+- TeamSnap is the source of truth for teams, members, events, lineups, and availability.
+- The backend stores only app-owned data plus TeamSnap external IDs and tokens needed for the session flow.
+
+## Frontend
+
+- `frontend/` contains the React application.
+- The app uses React Router for navigation and TanStack Query for server state.
+- TeamSnap data is loaded through the official JavaScript SDK from the browser after the backend provides an access token.
+- The UI includes player, operator, and library views for clip management and gameday playback.
+- The app is shipped as a PWA with install and offline-prep behavior.
+
+## Backend
+
+- `backend/` contains the FastAPI application.
+- The backend handles TeamSnap OAuth start, callback, and token refresh.
+- It manages session state, clip metadata, game assignment state, and normalized media storage.
+- Media files are stored locally in the backend storage path during development.
+
+## Data Boundaries
+
+- TeamSnap entities are not durably mirrored as first-class backend records.
+- App-owned records include media assets, clips, playback assignments, and related metadata.
+- Game-day clip pinning is modeled as app state that references TeamSnap game IDs and clip IDs.
+
+## Local Development
+
+- Docker Compose is the normal development path.
+- The frontend is served separately through Vite in development.
+- The backend is run through FastAPI with local storage and Docker secrets for TeamSnap credentials.
+- `README.md` contains the setup steps and environment expectations.

docs/coding-standards.md

@@ -0,0 +1,42 @@
+# Coding Standards
+
+These rules apply to Walkup-specific work in this repository.
+
+## General
+
+- Prefer the smallest change that fully solves the problem.
+- Preserve existing behavior unless the task explicitly requires a change.
+- Keep control flow straightforward and naming explicit.
+- Avoid broad refactors unless they are necessary to complete the task.
+
+## Frontend
+
+- Match the existing Bootstrap-based UI patterns.
+- Use Bootstrap Icons for iconography rather than custom SVG drawing.
+- Keep interactive controls readable and compact, especially in menus and toolbars.
+- Prefer UI changes that fit the current layout and spacing conventions.
+
+## Backend
+
+- Keep route handlers thin and push shared logic into helper functions when it improves clarity.
+- Treat tests as part of the implementation for non-trivial behavior changes.
+- Preserve API shape unless the change requires a contract update.
+
+## Testing
+
+- Add or update tests for user-visible behavior changes.
+- Run the smallest useful verification first, then broader checks for the touched area.
+- If a change cannot be covered automatically, call out the gap clearly.
+
+## Git And Workflow
+
+- Work on a dedicated branch for a scoped change.
+- Use the `Codex <codex@local>` identity for agent-authored commits.
+- Keep commits focused and reviewable.
+- Do not mix unrelated changes into the same commit.
+
+## Docs
+
+- Keep `docs/architecture.md` aligned with the current app structure.
+- Keep `docs/coding-standards.md` aligned with actual repo practice.
+- Update `PLAN.md` when work is completed, deferred, or split.