chore: rename master branch to main and refresh project docs

Rename default branch from master to main across all CI workflows,
documentation, and PRD. Also adds comprehensive project documentation
generated by the initialise skill (CLAUDE.md, docs/ structure).

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

Author: amostt

.github/workflows/deploy-staging.yml

@@ -3,7 +3,7 @@ name: Deploy to Staging
 on:
   push:
     branches:
-      - master
+      - main
 
 jobs:
   deploy:

.github/workflows/latest-changes.yml

@@ -3,7 +3,7 @@ name: Latest Changes
 on:
   pull_request_target:
     branches:
-      - master
+      - main
     types:
       - closed
   workflow_dispatch:

.github/workflows/playwright.yml

@@ -3,7 +3,7 @@ name: Playwright Tests
 on:
   push:
     branches:
-    - master
+    - main
   pull_request:
     types:
     - opened

.github/workflows/test-backend.yml

@@ -3,7 +3,7 @@ name: Test Backend
 on:
   push:
     branches:
-      - master
+      - main
   pull_request:
     types:
       - opened

.github/workflows/test-docker-compose.yml

@@ -3,7 +3,7 @@ name: Test Docker Compose
 on:
   push:
     branches:
-      - master
+      - main
   pull_request:
     types:
       - opened

CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+## Project Overview
+
+Full-stack web app template: FastAPI backend + React frontend + PostgreSQL. JWT auth, user management, CRUD, auto-generated API client. Docker Compose-based monorepo with Traefik reverse proxy.
+
+## Technology Stack
+
+| Category | Technology |
+|----------|-----------|
+| Backend | Python >=3.10, FastAPI >=0.114.2 |
+| ORM | SQLModel >=0.0.21 (SQLAlchemy) |
+| Database | PostgreSQL 18, Alembic migrations |
+| Frontend | TypeScript 5.9, React 19.1, Vite 7.3 (SWC) |
+| Routing | TanStack Router 1.157+ (file-based) |
+| Server State | TanStack Query 5.90+ |
+| Styling | Tailwind CSS 4.2, shadcn/ui (new-york) |
+| Auth | JWT (HS256) via PyJWT, Argon2+Bcrypt |
+
+**Key Libraries:** Zod 4.x, React Hook Form 7.x, Axios 1.13, lucide-react, sonner
+
+## Architecture Overview
+
+**Pattern:** Layered monorepo — `backend/` (Python) + `frontend/` (TypeScript)
+
+```
+backend/app/
+  api/routes/       # FastAPI endpoint handlers
+  core/             # config.py, db.py, security.py
+  alembic/versions/ # Database migrations
+  models.py         # SQLModel tables + Pydantic schemas
+  crud.py           # Data access functions
+frontend/src/
+  routes/           # TanStack file-based routing (pages)
+  components/       # UI (Admin/, Items/, Common/, UserSettings/, Sidebar/, ui/)
+  client/           # Auto-generated OpenAPI client — DON'T EDIT
+  hooks/            # Custom React hooks
+```
+
+**Important Patterns:**
+- Backend models: `ModelBase → ModelCreate → ModelUpdate → Model(table=True) → ModelPublic`
+- `src/client/`, `src/routeTree.gen.ts`, `src/components/ui/` are auto-generated — don't edit
+
+**Key Files:** `backend/app/main.py` (FastAPI entry), `backend/app/core/config.py` (settings from `.env`), `frontend/src/main.tsx` (React app + QueryClient + Router)
+
+## Development Commands
+
+```bash
+# Setup
+cd backend && uv sync                # Backend deps
+bun install                           # Frontend deps
+cd backend && uv run prek install -f  # Pre-commit hooks
+docker compose watch                  # Start full stack
+
+# Development
+docker compose watch                  # Full stack (recommended)
+bun run dev                           # Frontend only (:5173)
+cd backend && fastapi dev app/main.py # Backend only (:8000)
+
+# Testing
+bash ./scripts/test.sh                # All backend tests (Pytest)
+bunx playwright test                  # Frontend E2E
+bunx playwright test tests/login.spec.ts  # Single E2E test
+
+# Quality
+bun run lint                          # Frontend (Biome)
+uv run ruff check --fix               # Backend lint
+uv run ruff format                    # Backend format
+uv run mypy backend/app               # Backend type check
+
+# Utilities
+bash ./scripts/generate-client.sh     # Regenerate OpenAPI client
+```
+
+## Code Conventions
+
+- **Backend:** snake_case files/functions, PascalCase classes, absolute imports `from app.*`, Ruff + strict mypy
+- **Frontend:** PascalCase components, camelCase utils, `@/` alias → `./src/*`, Biome (double quotes, no semicolons)
+
+## Testing
+
+**Backend:** Pytest in `backend/tests/` (api/routes/, crud/, scripts/) — `uv run pytest backend/tests/path/to/test.py`
+**Frontend:** Playwright E2E in `frontend/tests/` — `bunx playwright test tests/file.spec.ts`
+
+See `@docs/testing/strategy.md` for coverage requirements and mocking patterns.
+
+## Database & Migrations
+
+**ORM:** SQLModel | **Models:** `backend/app/models.py`
+
+```bash
+alembic revision --autogenerate -m "desc"  # Create migration
+alembic upgrade head                        # Apply pending
+alembic downgrade -1                        # Rollback last
+alembic history --verbose                   # View history
+```
+
+Always review autogenerated migrations before applying. See `@docs/data/models.md`.
+
+## Known Issues
+
+- `SECRET_KEY`, `POSTGRES_PASSWORD`, `FIRST_SUPERUSER_PASSWORD` default to `changethis` — change for staging/production
+- Backend syntax errors crash dev container — restart with `docker compose watch`
+- Pre-commit hook auto-regenerates frontend SDK on backend changes
+- Alembic autogenerated migrations need manual review
+
+## Documentation
+
+Key references in `docs/`:
+- `@docs/getting-started/setup.md` - Setup and environment
+- `@docs/getting-started/development.md` - Daily development workflow
+- `@docs/architecture/overview.md` - System architecture
+- `@docs/api/overview.md` - API documentation
+- `@docs/data/models.md` - Data models and schemas
+- `@docs/testing/strategy.md` - Testing approach
+- `@docs/deployment/environments.md` - Deployment guides
+- `@docs/deployment/ci-pipeline.md` - CI/CD pipeline documentation

README.md

@@ -86,7 +86,7 @@ git remote add upstream git@github.com:fastapi/full-stack-fastapi-template.git
 - Push the code to your new repository:
 
 ```bash
-git push -u origin master
+git push -u origin main
 ```
 
 ### Update From the Original Template
@@ -107,7 +107,7 @@ upstream    git@github.com:fastapi/full-stack-fastapi-template.git (push)
 - Pull the latest changes without merging:
 
 ```bash
-git pull --no-commit upstream master
+git pull --no-commit upstream main
 ```
 
 This will download the latest changes from this template without committing them, that way you can check everything is right before committing.
@@ -184,7 +184,7 @@ If you have `pipx` and you didn't install `copier`, you can run it directly:
 pipx run copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust
 ```
 
-**Note** the `--trust` option is necessary to be able to execute a [post-creation script](https://github.com/fastapi/full-stack-fastapi-template/blob/master/.copier/update_dotenv.py) that updates your `.env` files.
+**Note** the `--trust` option is necessary to be able to execute a [post-creation script](https://github.com/fastapi/full-stack-fastapi-template/blob/main/.copier/update_dotenv.py) that updates your `.env` files.
 
 ### Input Variables
 

deployment.md

@@ -310,7 +310,7 @@ The current Github Actions workflows expect these secrets:
 
 There are GitHub Action workflows in the `.github/workflows` directory already configured for deploying to the environments (GitHub Actions runners with the labels):
 
-* `staging`: after pushing (or merging) to the branch `master`.
+* `staging`: after pushing (or merging) to the branch `main`.
 * `production`: after publishing a release.
 
 If you need to add extra environments you could use those as a starting point.

docs/README.md

@@ -0,0 +1,31 @@
+# Project Documentation
+
+Welcome to the Aygentic Starter Template documentation. This directory contains comprehensive technical documentation for the full-stack FastAPI + React application.
+
+## Documentation Structure
+
+- **[Getting Started](./getting-started/)** - Setup, development environment, and contribution guides
+- **[PRD](./prd/)** - Product requirements and feature specifications
+- **[Architecture](./architecture/)** - System design, diagrams, and architectural decisions
+- **[API](./api/)** - API documentation and endpoint references
+- **[Data](./data/)** - Data models, schemas, and database documentation
+- **[Testing](./testing/)** - Testing strategy, test registry, and test plans
+- **[Deployment](./deployment/)** - Deployment guides and infrastructure documentation
+- **[Runbooks](./runbooks/)** - Operational procedures and incident response
+
+## Quick Links
+
+- [Setup Guide](./getting-started/setup.md)
+- [Development Guide](./getting-started/development.md)
+- [Contributing](./getting-started/contributing.md)
+- [Architecture Overview](./architecture/overview.md)
+- [API Overview](./api/overview.md)
+- [Data Models](./data/models.md)
+- [Testing Strategy](./testing/strategy.md)
+- [Test Registry](./testing/test-registry.md)
+- [Environments](./deployment/environments.md)
+- [Incidents](./runbooks/incidents.md)
+
+---
+
+**Last Updated**: 2026-02-26