Add project documentation and update workflow plan

Adds AGENTS.md, DESIGN.md, and docs/* covering architecture,
conventions, decisions, checklists, branching, release process,
and prompts. Updates README and workflow-feedback-plan to reflect
the decoupled GroupName nomination model.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

AGENTS.md

@@ -0,0 +1,256 @@
+# Repository Guidelines
+
+## Read First
+
+Before changing code or durable documentation, inspect the current repository
+state and read the docs that match the task:
+
+- `docs/PROJECT.md` for project intent, runtime facts, environments and docs map.
+- `docs/ARCHITECTURE.md` for system boundaries, source-of-truth and deployment flow.
+- `docs/CONVENTIONS.md` for coding, validation, review and documentation standards.
+- `docs/DECISIONS.md` for accepted architecture and operations trade-offs.
+- `docs/CHECKLISTS.md` for task-specific quality gates.
+- `DESIGN.md` for UI, visual language, admin/public layout and responsive rules.
+
+Treat these files as the durable starter-kit structure for this existing
+project. Preserve existing project-specific docs and merge improvements instead
+of replacing them with generic templates.
+
+## Confidence Gate
+
+If requirements are below roughly 95% clear, ask concise clarifying questions
+before implementing. If ambiguity affects data loss, security, authentication,
+authorization, public behavior, migrations, deployment or irreversible changes,
+stop and ask.
+
+If ambiguity is isolated and low risk, make the smallest reasonable assumption
+and state it in the final summary.
+
+## Execution Philosophy
+
+Your objective is not to generate code as quickly as possible.
+
+Your objective is to solve engineering problems with the judgment of an experienced senior software engineer.
+
+Always determine the most appropriate execution strategy before writing code.
+
+For every task, first decide:
+
+- Does this require deeper reasoning?
+- Can the work be decomposed?
+- Can independent parts be executed in parallel?
+- Would delegated agents improve efficiency?
+- Is additional clarification required?
+
+Choose the execution strategy that maximizes correctness, maintainability, and cost efficiency.
+
+Treat delegation, planning, and implementation as engineering decisions rather than fixed rules.
+
+## Project Structure & Module Organization
+
+- `frontend/` contains the Vue 3/Vite app. Main source lives in `frontend/src/`, with views in `views/`, reusable UI in `components/`, stores in `stores/`, API helpers in `lib/` and `lib/api/`, and static assets in `assets/` or `public/`.
+- `Backend/` contains the ASP.NET Core 8 API. Domain models are in `Domain/`, EF Core setup and migrations in `Data/` and `Migrations/`, HTTP endpoints in `Endpoints/`, contracts in `Contracts/`, and shared services/repositories in `Services/` and `Repositories/`.
+- `.gitea/workflows/ci.yaml` defines build, hygiene, deploy, and live verification.
+- `docs/` holds planning and workflow notes.
+
+Do not commit generated output such as `frontend/dist`, `Backend/bin`, `Backend/obj`, archives, prototype exports, or handoff documents.
+
+## Build, Test, and Development Commands
+
+Start the local database:
+
+```bash
+docker compose -f docker-compose.dev.yml up -d
+```
+
+Run the backend:
+
+```bash
+cd Backend
+dotnet restore
+dotnet ef database update
+ASPNETCORE_ENVIRONMENT=Development dotnet run --urls http://127.0.0.1:5084
+```
+
+Run the frontend:
+
+```bash
+cd frontend
+npm ci
+cp .env.example .env
+npm run dev
+```
+
+Validate before pushing:
+
+```bash
+cd frontend && npm run build
+cd .. && dotnet build Backend/Backend.csproj --configuration Release
+git diff --check
+```
+
+`npm run build` runs `vue-tsc -b` and `vite build`.
+
+## Coding Style & Naming Conventions
+
+Use TypeScript with Vue single-file components. Keep `.vue` files focused; split large admin or workflow screens into smaller components/composables. Name Vue components in `PascalCase.vue`, composables as `useThing.ts`, and API helpers by feature. Backend code uses nullable-enabled C# with implicit usings; align endpoint, contract, service, and repository names by feature.
+
+## Testing Guidelines
+
+There is no dedicated test project checked in yet. Treat the frontend build, backend Release build, CI hygiene checks, and relevant manual endpoint/browser verification as required validation. Add future .NET tests in a separate test project and frontend tests near the feature they cover.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses short imperative subjects, for example `Fix team profile auth recovery` or `Refine admin risk workspace`. Keep commits scoped and describe the user-visible behavior or operational change.
+
+Pull requests should include a summary, validation commands run, linked issue or context when available, screenshots for UI changes, and notes for database migrations, deployment risk, or configuration changes.
+
+## Security & Configuration Tips
+
+Use `Backend/appsettings.Development.json` only for local defaults. Non-local environments should provide `VTSA_POSTGRES` or `ConnectionStrings__Postgres`. Never hardcode secrets, tokens, API keys, or production credentials in `Backend/` or `frontend/src/`; CI scans these paths.
+
+## Task Execution Strategy
+
+## Task Classification
+
+Before beginning any work, classify the request based on the amount of reasoning required.
+
+### Simple
+
+Small, isolated tasks with minimal reasoning.
+
+Examples:
+
+- formatting
+- typo fixes
+- documentation
+- repository searches
+- updating comments
+- locating references
+- simple bug fixes
+- small refactorings
+- straightforward unit tests
+- boilerplate generation
+- dependency lookups
+
+Prefer delegation to faster, lower-cost agents when available.
+
+---
+
+### Moderate
+
+Tasks requiring understanding of multiple files or components.
+
+Examples:
+
+- implementing a feature
+- extending existing functionality
+- API endpoints
+- service implementations
+- medium-sized refactoring
+
+Delegate independent supporting work where beneficial while keeping overall coordination in the primary reasoning process.
+
+---
+
+### Complex
+
+Tasks requiring significant reasoning or architectural understanding.
+
+Examples:
+
+- architecture
+- authentication
+- authorization
+- security
+- database design
+- distributed systems
+- major refactoring
+- performance-critical systems
+- cross-module changes
+
+The primary reasoning process should remain responsible.
+
+Delegate only isolated supporting tasks.
+
+---
+
+## Intelligent Task Delegation
+
+Continuously evaluate whether the current task should be handled entirely by the primary reasoning process or decomposed into smaller independent tasks.
+
+When delegated agents are available:
+
+- automatically identify independent subtasks
+- delegate low-risk work to faster and lower-cost agents
+- keep architectural decisions within the primary reasoning process
+- merge delegated work only after validating correctness
+
+Do not ask for permission before delegating unless delegation could affect correctness, security, or architecture.
+
+Suitable delegated work includes:
+
+- searching the repository
+- finding references
+- documentation updates
+- dependency analysis
+- duplicate code detection
+- code formatting
+- renaming symbols
+- generating boilerplate
+- simple implementations
+- isolated unit tests
+- isolated bug fixes
+
+Keep these tasks in the primary reasoning process:
+
+- architecture decisions
+- business logic
+- security-sensitive code
+- API design
+- database design
+- system integration
+- cross-module refactoring
+- final implementation review
+
+---
+
+## Parallel Execution
+
+Whenever independent work can safely execute in parallel:
+
+- identify parallelizable subtasks
+- execute them concurrently using delegated agents when available
+- validate all results before integration
+- ensure consistency before presenting the final solution
+
+Prefer parallel execution whenever it improves efficiency without compromising correctness.
+
+---
+
+## Delegation Principles
+
+Optimize for the following priorities:
+
+1. Correctness
+2. Engineering quality
+3. Maintainability
+4. Cost efficiency
+5. Execution speed
+
+Use delegated agents only when they improve efficiency without reducing solution quality.
+
+Always keep final responsibility, integration, validation, and architectural reasoning within the primary reasoning process.
+
+## Definition of Done
+
+A task is complete when:
+
+- the requested behavior or documentation exists;
+- changes are consistent with `docs/ARCHITECTURE.md` and `docs/CONVENTIONS.md`;
+- relevant builds, checks or manual validation have been run;
+- documentation is updated when setup, architecture, operations or public
+  behavior changed;
+- the diff is reviewed for unrelated changes, secrets, generated output and
+  accidental overwrites;
+- remaining risks or skipped validation are clearly communicated.

DESIGN.md

@@ -0,0 +1,118 @@
+# Design Guidelines
+
+This guide keeps new pages, modals, and components visually aligned with the VTuber Star Awards product. The brand can be magical and expressive, but every surface should still feel like part of one system.
+
+## Design Personality
+
+The shared identity is soft, celebratory, and operationally clear:
+
+- Public pages may feel theatrical: stars, glow, gradients, character art, glass panels, and animated voting moments.
+- Admin pages should feel calm and work-focused: dense cards, clear status, restrained motion, and predictable navigation.
+- Both surfaces use the same violet, lavender, blush, and gold family. Avoid introducing unrelated color themes.
+
+## Foundations
+
+Use the global fonts from [frontend/src/style.css](/Users/azu/Desktop/VTubeAwards/frontend/src/style.css):
+
+- Body and admin UI: `Outfit`.
+- Display headlines: `Cormorant Garamond`.
+- Friendly labels, counters, and brand accents: `Fredoka`.
+- Script accents only for special public hero moments: `Great Vibes` or `Sacramento`.
+
+Core colors:
+
+- Deep text: `#3f3556`, `#1f2337`, `#0f172a`.
+- Brand violet: `#8b6cdb`, `#7355c8`, `#5f44ad`.
+- Lavender surfaces: `#f4eefb`, `#f6f0fe`, `#fbf8ff`.
+- Gold accent: `#e7b13e`, `#ffd27a`.
+- Blush accent: `#e9a8c9`, `#ff8fc0`.
+- Status colors: emerald for healthy, amber for pending/warning, rose for risk/error.
+
+Use soft borders (`violet-100`/`violet-200`), translucent white surfaces, and shadows tinted violet rather than neutral black.
+
+## Layout System
+
+Use generous spacing on public pages and tighter rhythm in admin.
+
+- Public sections: full-width bands, immersive backgrounds, `max-width: 1200px`, `24px` desktop side padding, `16px` mobile padding.
+- Admin pages: `space-y-6` page rhythm, card grids with `gap-4` or `gap-6`, and the sidebar/content grid from [AdminLayoutView.vue](/Users/azu/Desktop/VTubeAwards/frontend/src/views/admin/AdminLayoutView.vue).
+- Admin desktop layout should keep navigation at `292px` and content fluid.
+- Prefer one primary task area per card. Do not nest cards inside cards unless the inner item is a repeated list item or metric tile.
+
+## Public Landing Page Style
+
+Follow the patterns in [HomeHeroMasthead.vue](/Users/azu/Desktop/VTubeAwards/frontend/src/components/home/HomeHeroMasthead.vue) and [homeLandingExperience.css](/Users/azu/Desktop/VTubeAwards/frontend/src/components/home/homeLandingExperience.css).
+
+Public pages can use:
+
+- Radial gradients, star particles, soft glow, character art, and glass cards.
+- Hero headlines in `Cormorant Garamond`, with gold gradient accents for award wording.
+- Rounded interactive controls: `14px` to `24px`; pill CTAs use `999px`.
+- Voting and nomination flows with wizard rails, sticky footers, and celebration bursts.
+
+Keep copy readable over decorative backgrounds. Every hero must still expose the main action, current phase/status, and one clear next step.
+
+## Admin Panel Style
+
+Admin screens should use the reusable UI layer first:
+
+- `Card.vue` for main panels.
+- `Button.vue` for actions.
+- `Modal.vue` for dialogs.
+- `AdminPageHeader.vue` for page headers.
+
+Admin cards use white or `white/80` surfaces, violet borders, `rounded-2xl` to `rounded-[28px]`, and soft shadows. Headers use compact uppercase eyebrows (`text-[11px]`, bold, wide tracking) and short operational descriptions. Icons should come from `@lucide/vue`, placed in `h-9 w-9` or `h-11 w-11` rounded squares.
+
+Use dense but scannable layouts: metrics in grids, filters in bars, forms in grouped sections, and status badges near the affected data.
+
+## Components & States
+
+Buttons:
+
+- Primary: violet background, white text, slight lift on hover.
+- Secondary: amber tint for supportive actions.
+- Ghost: white/violet outline for neutral actions.
+- Disabled states must remove lift and reduce opacity.
+
+Forms:
+
+- Labels are uppercase, `text-xs` or `text-[11px]`, semibold/bold, with slate or violet text.
+- Inputs use rounded corners (`xl`/`2xl`), violet border, white-to-lavender background, and focus rings in violet.
+- Error states use rose border/background plus clear text.
+
+Modals:
+
+- Use `Modal.vue` unless a public landing flow needs the custom home modal shell.
+- Header gradient should stay lavender-to-warm cream.
+- Use `md`, `lg`, or `xl` sizes; avoid one-off modal widths.
+
+## Motion
+
+Motion should feel soft and intentional:
+
+- Standard admin transitions: `160ms` to `200ms`.
+- Preferred easing: `cubic-bezier(0.22, 1, 0.36, 1)`.
+- Hover lift: `translateY(-1px)` or `translateY(-2px)`.
+- Public decorative loops can be slower (`3s` to `9s`) and subtle.
+- Always respect `prefers-reduced-motion`; decorative star/burst effects should stop or simplify.
+
+## Responsive Rules
+
+Design mobile first for admin usability and public readability.
+
+- Check `360px`, `390px`, `768px`, and desktop widths.
+- No horizontal overflow: compare `document.documentElement.scrollWidth` to `window.innerWidth`.
+- Admin navigation becomes a drawer below `xl`.
+- Public hero text, host cards, modal rails, and sticky controls must wrap instead of shrinking into unreadable text.
+- Use stable dimensions for icon buttons, badges, counters, and grid tiles so hover or loading states do not shift layout.
+
+## Implementation Checklist
+
+Before adding a new UI surface:
+
+1. Reuse existing components before creating a new visual pattern.
+2. Pick the surface mode: expressive public page or operational admin page.
+3. Use the shared fonts, violet/lavender/gold palette, rounded cards, and tinted shadows.
+4. Include empty, loading, disabled, success, warning, and error states where relevant.
+5. Verify mobile layout and text wrapping.
+6. Run `npm run build` after frontend changes.

README.md

@@ -13,10 +13,25 @@ Production monorepo for the VTuber Star Awards platform.
 - `frontend/` Vue application and public assets
 - `Backend/` ASP.NET Core API, EF Core migrations, services and endpoints
 - `.gitea/workflows/ci.yaml` build, hygiene, deploy and live verification pipeline
+- `docs/PROJECT.md` project facts, runtime expectations and documentation map
+- `docs/ARCHITECTURE.md` system structure, source-of-truth and deployment flow
+- `docs/CONVENTIONS.md` coding, validation, review and documentation standards
+- `docs/DECISIONS.md` durable architecture and operations decisions
 - `docker-compose.dev.yml` optional local PostgreSQL container for development
 
 Generated archives, prototype exports, Word handoff files and local document-update scripts are intentionally ignored and should not be committed.
 
+## Engineering Docs
+
+Start with:
+
+- [AGENTS.md](AGENTS.md) for the engineering execution contract.
+- [docs/PROJECT.md](docs/PROJECT.md) for project/runtime facts.
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for system boundaries.
+- [docs/CONVENTIONS.md](docs/CONVENTIONS.md) for coding and validation standards.
+- [docs/CHECKLISTS.md](docs/CHECKLISTS.md) for quality gates.
+- [DESIGN.md](DESIGN.md) for UI and product design guidance.
+
 ## Local Development
 
 Start the database:
@@ -96,3 +111,6 @@ The pipeline:
 7. Verifies live health, database connectivity and frontend assets.
 
 Production runs at `https://award.noveria.net`.
+
+See [docs/release-process.md](docs/release-process.md) for release readiness,
+smoke tests and rollback expectations.

docs/ARCHITECTURE.md

@@ -0,0 +1,206 @@
+# Architecture
+
+This document describes the structure, boundaries, flows, and technical rules of
+the VTuber Star Awards system. For project facts, see [PROJECT.md](PROJECT.md).
+For coding standards, see [CONVENTIONS.md](CONVENTIONS.md).
+For recorded trade-offs, see [DECISIONS.md](DECISIONS.md).
+
+## High-Level Overview
+
+VTuber Star Awards is a production monorepo with a Vue/Vite frontend, an
+ASP.NET Core 8 minimal API backend, and a PostgreSQL database managed by EF Core
+migrations.
+
+```mermaid
+flowchart LR
+    Public["Public users"]
+    Team["Team/admin users"]
+    Frontend["Vue/Vite frontend"]
+    Api["ASP.NET Core API"]
+    Domain["Domain models and services"]
+    Database["PostgreSQL"]
+    Twitch["Twitch OAuth"]
+    CI["Gitea Actions"]
+
+    Public --> Frontend
+    Team --> Frontend
+    Frontend --> Api
+    Api --> Domain
+    Domain --> Database
+    Api --> Twitch
+    CI --> Api
+    CI --> Frontend
+    CI --> Database
+```
+
+The frontend is the user interface. The backend is the source of truth for
+season state, content, team permissions, moderation, workflow rules, and public
+overview data.
+
+## Architecture Style
+
+| Field | Value |
+| --- | --- |
+| Style | Layered modular monolith |
+| Runtime shape | One frontend app, one backend API, one PostgreSQL database |
+| Primary reason | Keep deployment simple while preserving clearer internal feature boundaries. |
+| Main trade-off | Boundaries depend on code organization and review discipline rather than service isolation. |
+
+## Repository Structure
+
+```text
+VTubeAwards/
+  frontend/
+    src/
+      views/
+      components/
+      stores/
+      lib/
+      types/
+  Backend/
+    Common/
+    Configuration/
+    Contracts/
+    Data/
+    Domain/
+    Endpoints/
+    Extensions/
+    Migrations/
+    Repositories/
+    Security/
+    Services/
+  docs/
+  .gitea/workflows/
+```
+
+| Folder | Responsibility |
+| --- | --- |
+| `frontend/src/views` | Route-level Vue views. |
+| `frontend/src/components` | Reusable public/admin UI components and composables. |
+| `frontend/src/lib` | API clients, HTTP helpers, formatting, and shared frontend utilities. |
+| `frontend/src/types` | TypeScript contract and payload types. |
+| `Backend/Endpoints` | Minimal API endpoint groups and endpoint-specific mapping helpers. |
+| `Backend/Contracts` | Request and response DTOs. |
+| `Backend/Domain` | Persistent domain entities and core business concepts. |
+| `Backend/Data` | EF Core `DbContext`, seed/bootstrap code, and design-time setup. |
+| `Backend/Repositories` | Domain-specific persistence boundaries. |
+| `Backend/Services` | Use-case, audit, session, risk, and workflow services. |
+| `Backend/Security` | Session filters, role/permission catalog, and security middleware. |
+| `docs` | Durable project, architecture, workflow, and decision documentation. |
+
+## Backend Flow
+
+```mermaid
+sequenceDiagram
+    participant Client as Frontend or API client
+    participant Endpoint as Minimal API endpoint
+    participant Filter as Admin/session filter
+    participant Service as Service or repository
+    participant Db as EF Core/PostgreSQL
+
+    Client->>Endpoint: HTTP request
+    Endpoint->>Filter: Auth and permission checks when required
+    Endpoint->>Service: Validate intent and execute use case
+    Service->>Db: Query or persist through DbContext/repository
+    Db-->>Service: Domain data
+    Service-->>Endpoint: Contract DTO
+    Endpoint-->>Client: JSON response or problem result
+```
+
+Endpoint files should stay focused on transport concerns, authorization,
+mapping, and orchestration. Domain rules and cross-endpoint behavior belong in
+services, repositories, or domain-specific helpers.
+
+## Frontend Flow
+
+```mermaid
+flowchart TD
+    Route["Vue route/view"]
+    Components["Focused components"]
+    Composables["Composables and stores"]
+    ApiClient["frontend/src/lib/api"]
+    Backend["Backend API"]
+
+    Route --> Components
+    Components --> Composables
+    Composables --> ApiClient
+    ApiClient --> Backend
+```
+
+Public pages should render backend/admin truth. Admin pages should favor clear
+workspace structure, permission-aware controls, explicit loading/error states,
+and smaller Vue files split by feature.
+
+## Data Ownership
+
+| Data | Owner | Notes |
+| --- | --- | --- |
+| Seasons, categories, candidates, winners | Backend | Public and admin views read from canonical backend state. |
+| Nominations and clip submissions | Backend | Public writes are validated and reviewed through admin workflows. |
+| Site settings, landing content, footer links, showacts, sponsors | Backend | Content hub/admin settings own public presentation data. |
+| Team members, roles, permissions, sessions | Backend | UI may hide controls, but API authorization is authoritative. |
+| Risk flags and audit entries | Backend | Used for admin review, diagnostics, and accountability. |
+| Frontend interaction state | Frontend | Local state is allowed only for view state and unsaved form state. |
+
+## Persistence Boundary
+
+The backend uses EF Core with PostgreSQL. Domain-specific repositories exist for
+session, risk flag, and audit behavior. Direct `AwardsDbContext` use is still
+acceptable inside endpoint groups or services when the operation is simple and
+local to one feature, but repeated or cross-feature persistence behavior should
+move behind a repository or focused service.
+
+Production migrations are applied by the Gitea deploy workflow. Development can
+auto-apply migrations during API startup.
+
+## Authentication And Authorization
+
+- Team/admin authentication is session-based.
+- Twitch OAuth is handled through backend auth endpoints.
+- Admin endpoints use session/permission checks at the trusted backend boundary.
+- The frontend should reflect permissions to improve UX, but never be the only
+  authorization layer.
+- `creator` is not a normal assignable role in team management.
+
+## Security Posture
+
+| Area | Policy |
+| --- | --- |
+| CORS | Non-development environments require explicit configured frontend origins. |
+| Public writes | Rate-limited and validated server-side. |
+| Secrets | Environment variables only; no checked-in production credentials. |
+| Demo data | Controlled by seed/demo environment flags. Production defaults must remain safe. |
+| Headers | Security headers are applied by backend middleware. |
+| Audit | Admin-relevant changes should emit useful audit records where supported. |
+
+## Deployment Flow
+
+```mermaid
+flowchart LR
+    Push["Push to main or manual dispatch"]
+    Verify["Build, typecheck, hygiene"]
+    Sync["Sync code to production host"]
+    Backup["Predeploy PostgreSQL backup"]
+    Migrate["Apply EF Core migrations"]
+    Restart["Recreate api and web services"]
+    Smoke["Health, database, and asset checks"]
+
+    Push --> Verify
+    Verify --> Sync
+    Sync --> Backup
+    Backup --> Migrate
+    Migrate --> Restart
+    Restart --> Smoke
+```
+
+The production deploy path is encoded in `.gitea/workflows/ci.yaml`.
+
+## Known Constraints
+
+- There is no dedicated checked-in test project yet.
+- Build/type checks and targeted manual verification are currently required for
+  most changes.
+- Production database migration rollback must be considered before risky schema
+  changes; the pipeline writes backups but does not make destructive migrations
+  automatically safe.
+- Large admin and public Vue surfaces should continue to be split as they grow.

docs/CHECKLISTS.md

@@ -0,0 +1,92 @@
+# Checklists
+
+Use these concise checklists as quality gates. Expand them only when repeated
+project experience proves that more detail is necessary.
+
+For workflow details, see [workflow.md](workflow.md). For code standards, see
+[CONVENTIONS.md](CONVENTIONS.md). For releases, see
+[release-process.md](release-process.md).
+
+## Feature Development
+
+- [ ] Objective, users, acceptance criteria, and non-goals are clear.
+- [ ] Relevant docs and existing implementation were read.
+- [ ] Frontend/backend contract and source of truth are identified.
+- [ ] Permission, workflow, empty, loading, error, and disabled states are handled.
+- [ ] Docs are updated when behavior, setup, or architecture changed.
+- [ ] Frontend build, backend build, and targeted manual checks are run.
+
+## Bug Fix
+
+- [ ] Observed behavior is understood.
+- [ ] Expected behavior is confirmed.
+- [ ] Root cause is identified before changing code.
+- [ ] Fix is scoped to the cause.
+- [ ] Regression coverage or targeted manual verification covers the failing path.
+- [ ] Remaining risk is documented.
+
+## Frontend UI Change
+
+- [ ] Existing components, composables, and design guidance were checked.
+- [ ] Public UI uses backend/admin truth when available.
+- [ ] Admin UI is scannable and permission-aware.
+- [ ] Text wraps without overlap at mobile and desktop widths.
+- [ ] Browser checks include relevant routes and responsive widths.
+- [ ] `npm run build` passes.
+
+## API Change
+
+- [ ] Request and response contracts are stable and typed.
+- [ ] Authorization is enforced server-side.
+- [ ] Validation errors are consistent and actionable.
+- [ ] Public writes are rate-limited where appropriate.
+- [ ] Idempotency, pagination, filtering, or sorting are considered when relevant.
+- [ ] Frontend clients and TypeScript types are updated.
+
+## Database Change
+
+- [ ] Data ownership and invariants are clear.
+- [ ] Migration operations are reviewed manually.
+- [ ] Constraints and indexes match expected behavior.
+- [ ] Backfill and deployment order are documented when needed.
+- [ ] Rollback or forward-fix path is understood.
+- [ ] Database health and pending migrations are checked after applying.
+
+## Security Review
+
+- [ ] Authentication is required where expected.
+- [ ] Authorization is enforced on the backend.
+- [ ] Inputs are validated.
+- [ ] Outputs are safely serialized or encoded.
+- [ ] Secrets are not logged or committed.
+- [ ] Sensitive user or team data exposure is minimized.
+- [ ] Demo, seed, and local-only behavior cannot leak into production.
+
+## Pull Request
+
+- [ ] Summary explains what and why.
+- [ ] Scope is focused.
+- [ ] Validation commands and manual checks are listed.
+- [ ] Screenshots or recordings are included for visible UI changes.
+- [ ] Migration and deployment notes are included when relevant.
+- [ ] Risks, skipped validation, and follow-ups are documented.
+- [ ] No generated output, secrets, debug code, or unrelated files are included.
+
+## Release
+
+- [ ] Release scope and target commit are known.
+- [ ] Required CI checks passed.
+- [ ] Migration risk is reviewed.
+- [ ] Configuration and secrets are ready.
+- [ ] Predeploy backup is confirmed by the pipeline.
+- [ ] Health, database, and frontend asset checks pass.
+- [ ] Rollback or recovery path is understood.
+
+## Production Readiness
+
+- [ ] Runtime environments and URLs are documented.
+- [ ] Health checks exist and are reachable.
+- [ ] Database connectivity and pending migrations can be inspected.
+- [ ] Production CORS, seed mode, and demo login settings are safe.
+- [ ] Backups and restore expectations are documented.
+- [ ] Operational ownership and alerting gaps are explicit.

docs/CONVENTIONS.md

@@ -0,0 +1,130 @@
+# Engineering Conventions
+
+This document defines project engineering standards. It should stay practical,
+specific, and enforceable. For architecture boundaries, see
+[ARCHITECTURE.md](ARCHITECTURE.md). For quality gates, see
+[CHECKLISTS.md](CHECKLISTS.md).
+
+## General Rules
+
+- Prefer correctness, maintainability, and clear ownership over speed.
+- Read nearby code and docs before editing.
+- Keep changes scoped; do not mix unrelated cleanup with behavior changes.
+- Preserve user work and unrelated local changes.
+- Treat missing business logic as an unknown, not as permission to invent it.
+- Update documentation when setup, architecture, operations, or public behavior
+  changes.
+
+## Naming
+
+- Use domain terms over technical shorthand.
+- Name Vue components in `PascalCase.vue`.
+- Name composables as `useThing.ts`.
+- Name API helpers by feature or API area.
+- Name backend endpoints, contracts, services, and repositories by feature.
+- Name booleans as predicates, such as `isEnabled`, `hasPermission`, or
+  `canSubmit`.
+
+## Frontend
+
+- Use Vue 3 single-file components with TypeScript.
+- Keep `.vue` files focused; split large admin or workflow screens into smaller
+  components and composables.
+- Keep route-level views in `frontend/src/views`.
+- Keep reusable UI in `frontend/src/components`.
+- Keep API calls in `frontend/src/lib/api` or established API helpers.
+- Keep local state limited to UI interaction and unsaved form state when backend
+  data exists.
+- Public pages should use backend/admin truth instead of duplicated demo data.
+- Admin pages should be dense, scannable, permission-aware, and operationally
+  clear.
+- Use existing design guidance in [../DESIGN.md](../DESIGN.md) before creating
+  new visual patterns.
+
+## Backend
+
+- Use nullable-enabled C# with implicit usings.
+- Keep endpoint groups focused on HTTP shape, mapping, authorization, and
+  orchestration.
+- Put reusable use-case behavior in services.
+- Put persistence-specific behavior in repositories when it is repeated,
+  cross-feature, or domain-significant.
+- Keep request/response DTOs in `Backend/Contracts`; do not expose persistence
+  entities as public contracts by default.
+- Keep auth and permission behavior server-side, even when the frontend hides
+  controls.
+- Prefer explicit validation responses over relying on database exceptions for
+  expected user errors.
+
+## Database And Migrations
+
+- Use EF Core migrations for schema changes.
+- Review migration names and generated operations before committing.
+- Consider indexes, constraints, backfill, and rollback/recovery before schema
+  changes.
+- Production migrations are applied by the deploy workflow; do not add
+  production startup auto-migrations without an explicit decision.
+- Keep demo/presentation seed behavior controlled by environment flags.
+
+## Configuration And Secrets
+
+- Use `Backend/appsettings.Development.json` only for local defaults.
+- Keep `Backend/appsettings.json` production-safe.
+- Use `VTSA_POSTGRES` or `ConnectionStrings__Postgres` outside local defaults.
+- Never hardcode secrets, tokens, API keys, production credentials, or private
+  URLs in source.
+- Non-development CORS origins must be explicit HTTP(S) origins.
+
+## Validation
+
+Default validation before pushing application changes:
+
+```bash
+cd frontend
+npm run build
+
+cd ..
+dotnet build Backend/Backend.csproj --configuration Release
+git diff --check
+```
+
+Add targeted checks when risk is higher:
+
+- API `curl` checks for endpoint behavior.
+- Browser checks for public/admin UI changes.
+- Mobile width checks at `360px`, `390px`, `768px`, and desktop for responsive
+  UI changes.
+- Authenticated admin checks for permission or team-management changes.
+- Live health checks only when the user explicitly moves the task to live or a
+  release/deploy task requires it.
+
+## Git And PRs
+
+- Keep commits focused and imperative, for example `Fix team profile auth recovery`.
+- Use PR descriptions with summary, validation, risks, screenshots for UI
+  changes, and migration/deployment notes when relevant.
+- Do not commit generated output such as `frontend/dist`, `Backend/bin`,
+  `Backend/obj`, archives, prototype exports, or handoff documents.
+- Explain failed or skipped validation clearly.
+
+## Documentation
+
+- Keep one authoritative source per topic and link to it instead of duplicating
+  large sections.
+- Use [PROJECT.md](PROJECT.md) for project facts and runtime expectations.
+- Use [ARCHITECTURE.md](ARCHITECTURE.md) for system structure and boundaries.
+- Use [DECISIONS.md](DECISIONS.md) for durable trade-offs.
+- Use [workflow-feedback-plan.md](workflow-feedback-plan.md) and similar docs
+  for scoped product plans.
+
+## Review Priorities
+
+Reviews should prioritize:
+
+- user-visible correctness;
+- security and authorization;
+- data integrity and migrations;
+- backend/admin truth versus duplicated state;
+- operational risk and deploy safety;
+- maintainability and file size;
+- adequate validation evidence.

docs/DECISIONS.md

@@ -0,0 +1,226 @@
+# Decisions
+
+This document contains Architecture Decision Records (ADRs). Record decisions
+that materially affect architecture, operations, security, data ownership,
+public contracts, or long-term maintainability.
+
+For architecture context, see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Status Values
+
+- Proposed: under discussion.
+- Accepted: current decision.
+- Superseded: replaced by a newer decision.
+- Deprecated: no longer recommended, but still present.
+- Rejected: considered and intentionally not chosen.
+
+## ADR Index
+
+| ID | Title | Status | Date |
+| --- | --- | --- | --- |
+| ADR-001 | Keep durable engineering documentation in the repository | Accepted | 2026-06-28 |
+| ADR-002 | Use a Vue and ASP.NET Core monorepo | Accepted | 2026-06-28 |
+| ADR-003 | Keep backend/admin data as public truth | Accepted | 2026-06-28 |
+| ADR-004 | Apply production migrations in the deploy pipeline | Accepted | 2026-06-28 |
+| ADR-005 | Require explicit validation evidence for application changes | Accepted | 2026-06-28 |
+
+## ADR Template
+
+### Status
+
+Proposed
+
+### Date
+
+YYYY-MM-DD
+
+### Context
+
+Describe the forces, constraints, project stage, and previous behavior.
+
+### Problem
+
+State the specific problem being solved.
+
+### Alternatives
+
+| Alternative | Summary |
+| --- | --- |
+| Option A | Summary. |
+| Option B | Summary. |
+
+### Decision
+
+State the chosen option and why it fits the current constraints.
+
+### Consequences
+
+- Expected benefit.
+- Expected cost or trade-off.
+- Follow-up or review trigger.
+
+## ADR-001: Keep Durable Engineering Documentation In The Repository
+
+### Status
+
+Accepted
+
+### Date
+
+2026-06-28
+
+### Context
+
+The project uses AI-assisted development and has accumulated product, runtime,
+security, admin, deployment, and design knowledge across code and local context.
+
+### Problem
+
+Important engineering knowledge is harder to maintain when it lives only in
+chat, memory, or transient planning notes.
+
+### Decision
+
+Keep durable engineering documentation in `docs/` and link high-level entry
+points from `README.md` and `AGENTS.md`.
+
+### Consequences
+
+- Architecture, conventions, workflow, release, and decision context can be
+  reviewed with code changes.
+- Planning notes may still exist for scoped work, but accepted project rules
+  should move into durable docs.
+- Documentation must be maintained when architecture or operations change.
+
+## ADR-002: Use A Vue And ASP.NET Core Monorepo
+
+### Status
+
+Accepted
+
+### Date
+
+2026-06-28
+
+### Context
+
+The platform has a tightly related public frontend, admin frontend, backend API,
+database migrations, and deployment pipeline.
+
+### Problem
+
+Splitting the application too early would increase coordination cost for a
+small product surface whose frontend and backend contracts evolve together.
+
+### Decision
+
+Keep the Vue/Vite frontend and ASP.NET Core backend in one monorepo, with clear
+folder boundaries and shared validation through the Gitea workflow.
+
+### Consequences
+
+- Cross-stack changes can be reviewed and deployed together.
+- CI can enforce frontend and backend build health in one place.
+- Internal boundaries must be protected through conventions and review, not
+  repository separation.
+
+## ADR-003: Keep Backend/Admin Data As Public Truth
+
+### Status
+
+Accepted
+
+### Date
+
+2026-06-28
+
+### Context
+
+The public landing page and workflow screens need to reflect seasons, settings,
+showacts, sponsors, footer links, voting state, and participation state managed
+through the backend/admin surface.
+
+### Problem
+
+Parallel frontend-only demo data creates drift between what admins configure
+and what users see.
+
+### Decision
+
+Use backend/admin state as the source of truth for public pages whenever a
+backend-backed model exists.
+
+### Consequences
+
+- Public UI should use `/api/public/*` data instead of local duplicate content.
+- Admin changes need API and frontend contract updates when public content
+  changes.
+- Local-only state is reserved for interaction state, draft forms, and
+  optimistic UI where appropriate.
+
+## ADR-004: Apply Production Migrations In The Deploy Pipeline
+
+### Status
+
+Accepted
+
+### Date
+
+2026-06-28
+
+### Context
+
+The backend can auto-apply migrations in development, while production deploys
+run through `.gitea/workflows/ci.yaml`.
+
+### Problem
+
+Automatic production startup migrations make rollback and failure handling less
+predictable.
+
+### Decision
+
+Apply EF Core migrations during the production deploy workflow after a
+predeploy PostgreSQL backup and before service restart. Keep development
+startup migrations for local convenience.
+
+### Consequences
+
+- Production schema changes are visible in deployment logs.
+- Backups are written before migrations.
+- Destructive or hard-to-reverse migrations still require manual review and a
+  recovery plan before release.
+
+## ADR-005: Require Explicit Validation Evidence For Application Changes
+
+### Status
+
+Accepted
+
+### Date
+
+2026-06-28
+
+### Context
+
+The repository currently relies on frontend type/build checks, backend Release
+builds, CI hygiene checks, and targeted manual verification. A dedicated test
+project is not checked in yet.
+
+### Problem
+
+Without explicit validation evidence, reviewers cannot reliably distinguish a
+verified full-stack change from a plausible but untested edit.
+
+### Decision
+
+Every non-trivial application change should include the commands and manual
+checks that were run, plus any failures or skipped checks.
+
+### Consequences
+
+- Final work summaries and PR descriptions must name validation.
+- UI, auth, migration, and live/deploy changes need targeted checks beyond a
+  generic build when practical.
+- Missing automated regression coverage remains visible as residual risk until
+  test projects are added.

docs/PROJECT.md

@@ -0,0 +1,148 @@
+# VTuber Star Awards Project
+
+This document is the durable source of truth for project intent, runtime facts,
+and operational expectations. For system structure, see [ARCHITECTURE.md](ARCHITECTURE.md).
+For engineering standards, see [CONVENTIONS.md](CONVENTIONS.md).
+
+## Project Identity
+
+| Field | Value |
+| --- | --- |
+| Project name | VTuber Star Awards |
+| Repository | `https://git.noveria.net/bao/vtuber-awards.git` |
+| Primary product | Public awards platform with admin operations tooling |
+| Production URL | `https://award.noveria.net` |
+| Status | Active production application |
+
+## Vision
+
+VTuber Star Awards is a public awards platform for nominations, clip
+submissions, voting, winner presentation, showact applications, sponsor content,
+and supporting public information pages.
+
+The platform should be expressive and celebratory for public users while giving
+operators a clear admin workspace for content, seasons, moderation, risk review,
+team access, release visibility, and operational readiness.
+
+## Goals
+
+- Keep public pages driven by backend/admin truth rather than duplicated demo
+  state.
+- Support the full awards workflow: season setup, nominations, clip review,
+  voting, results, landing content, sponsors, showacts, and static policy pages.
+- Make admin workflows scannable, permission-aware, auditable, and reliable.
+- Keep local development reproducible with a local PostgreSQL database and
+  explicit frontend/backend validation.
+- Keep production deployment repeatable through the Gitea pipeline, database
+  backups, EF Core migrations, health checks, and frontend asset verification.
+
+## Non-Goals
+
+- Do not self-host user-submitted video clips unless that product decision is
+  explicitly revisited.
+- Do not keep parallel frontend-only demo data when backend-backed data exists.
+- Do not expose privileged roles, especially `creator`, as normal assignable
+  team roles.
+- Do not rely on checked-in secrets or production credentials.
+
+## Users And Roles
+
+| Role | Description | Key Access |
+| --- | --- | --- |
+| Public visitor | Views current awards content, winners, schedules, policies, and extras. | Public pages and read-only public APIs. |
+| Participant | Submits nominations, clips, votes, or showact applications when enabled. | Public write APIs with rate limits and workflow gates. |
+| Team member | Authenticated operator with scoped permissions. | Admin routes permitted by role and `TeamRolePermission` records. |
+| Admin | Maintains seasons, categories, candidates, moderation, content, settings, and team operations. | Broad admin API access with audit expectations. |
+| Creator | Bootstrap/owner-level identity. | Not a regular assignable UI role. |
+
+## Tech Stack
+
+| Area | Choice | Notes |
+| --- | --- | --- |
+| Frontend | Vue 3, Vite, TypeScript, Pinia, Tailwind CSS, PrimeVue, lucide icons | Source under `frontend/src`. |
+| Backend | ASP.NET Core 8 minimal API | Entry point in `Backend/Program.cs`; endpoint groups under `Backend/Endpoints`. |
+| Database | PostgreSQL with EF Core 8 and Npgsql | Migrations under `Backend/Migrations`. |
+| Auth | Session-based team/admin auth plus Twitch OAuth support | Auth endpoints under `Backend/Endpoints/Auth*`; idle timeout is configurable in admin operational settings with a minimum of 3 hours. |
+| Delivery | Gitea Actions, Docker Compose, Nginx-served frontend, ASP.NET API | Pipeline in `.gitea/workflows/ci.yaml`. |
+
+## Runtime Environments
+
+| Environment | Entry Point | Notes |
+| --- | --- | --- |
+| Local database | `localhost:5433` | Started with `docker compose -f docker-compose.dev.yml up -d`. |
+| Local backend | `http://127.0.0.1:5084` | Run from `Backend/` with `ASPNETCORE_ENVIRONMENT=Development dotnet run --urls http://127.0.0.1:5084`. |
+| Local frontend | Vite dev server, usually `http://localhost:5173` | Run from `frontend/` with `npm run dev`. |
+| Production | `https://award.noveria.net` | Deployed by Gitea Actions on `main` pushes and manual dispatches. |
+
+Default local database connection:
+
+```text
+Host=localhost;Port=5433;Database=vtuber_star_awards_dev;Username=vtsa_dev;Password=change-me-local-only
+```
+
+Non-local environments must provide `VTSA_POSTGRES` or
+`ConnectionStrings__Postgres`.
+
+## CI/CD
+
+The Gitea workflow in `.gitea/workflows/ci.yaml`:
+
+- rejects tracked build output, handoff artifacts, and obvious secret patterns;
+- restores and builds the .NET backend;
+- runs the frontend typecheck/build through `npm run build`;
+- deploys `main` or manual dispatches to the production host;
+- writes a PostgreSQL predeploy backup;
+- applies EF Core migrations before restarting production services;
+- verifies API health, database connectivity, pending migrations, and frontend
+  asset version metadata.
+
+## Required Local Validation
+
+Before pushing application changes, run:
+
+```bash
+cd frontend
+npm run build
+
+cd ..
+dotnet build Backend/Backend.csproj --configuration Release
+git diff --check
+```
+
+`npm run build` already runs `vue-tsc -b` before `vite build`.
+
+Use manual API or browser validation for user-facing, auth, moderation,
+settings, deployment, and responsive UI changes.
+
+## Security And Configuration
+
+- Use `Backend/appsettings.Development.json` only for local defaults.
+- Keep `Backend/appsettings.json` production-safe and secret-free.
+- Provide production secrets through environment variables.
+- Configure explicit frontend CORS origins in non-development environments.
+- Keep server-side authorization as the trusted boundary for admin routes.
+- Keep public write endpoints rate-limited and validated.
+
+## Documentation Map
+
+| File | Purpose |
+| --- | --- |
+| [../README.md](../README.md) | Quick start, stack, validation, and deployment overview. |
+| [../AGENTS.md](../AGENTS.md) | AI-agent and engineering execution contract. |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System boundaries, module responsibilities, data flow, and security posture. |
+| [CONVENTIONS.md](CONVENTIONS.md) | Coding, validation, review, and documentation standards. |
+| [DECISIONS.md](DECISIONS.md) | Accepted architecture and operations decisions. |
+| [CHECKLISTS.md](CHECKLISTS.md) | Quality gates for common change types. |
+| [workflow.md](workflow.md) | Day-to-day delivery flow. |
+| [branching.md](branching.md) | Branch and commit policy. |
+| [release-process.md](release-process.md) | Release, deploy, smoke test, and rollback expectations. |
+| [../DESIGN.md](../DESIGN.md) | Product visual language and UI implementation guidance. |
+| [workflow-feedback-plan.md](workflow-feedback-plan.md) | Product feedback implementation plan for awards workflow improvements. |
+
+## Open Questions
+
+| Question | Why It Matters | Status |
+| --- | --- | --- |
+| Dedicated automated test project | Builds currently protect compile/type safety, but durable regression coverage is still limited. | Open |
+| Production alerting owner and channels | Release docs can define checks, but ownership and paging policy are not encoded in the repo. | Open |
+| Formal rollback drills | The pipeline writes backups, but restore rehearsal policy is not documented in code. | Open |

docs/PROMPTS.md

@@ -0,0 +1,154 @@
+# Reusable Engineering Prompts
+
+Use these prompts with [../AGENTS.md](../AGENTS.md),
+[PROJECT.md](PROJECT.md), [ARCHITECTURE.md](ARCHITECTURE.md), and
+[CONVENTIONS.md](CONVENTIONS.md).
+
+## Feature Development
+
+```text
+Act as a senior engineer in the VTuber Star Awards repository.
+
+Objective:
+Implement <feature>.
+
+Context:
+- Product goal: <goal>
+- Relevant docs: docs/PROJECT.md, docs/ARCHITECTURE.md, docs/CONVENTIONS.md
+- Relevant files: <files>
+
+Requirements:
+- <requirement>
+
+Non-goals:
+- <non-goal>
+
+Before coding:
+- Inspect current frontend/backend behavior.
+- Confirm the backend/admin source of truth.
+- Ask concise questions if confidence is below 95%.
+
+After coding:
+- Run npm run build, dotnet build Backend/Backend.csproj --configuration Release,
+  git diff --check, and targeted manual checks.
+- Summarize changed files, validation, and residual risk.
+```
+
+## Bug Investigation
+
+```text
+Investigate this bug before changing code.
+
+Observed behavior:
+<observed behavior>
+
+Expected behavior:
+<expected behavior>
+
+Evidence:
+<logs, screenshots, steps, URLs>
+
+Task:
+- Reproduce or reason from available evidence.
+- Identify the most likely root cause.
+- Locate affected frontend, backend, database, or deployment code.
+- Propose the smallest maintainable fix.
+- Implement only after the cause is understood.
+- Add or describe regression validation.
+```
+
+## Admin UI Audit
+
+```text
+Audit this admin page for logical structure, all-at-a-glance clarity, duplicate
+controls, permissions, and component-level behavior.
+
+Scope:
+<route or files>
+
+Expectations:
+- Preserve backend/admin truth.
+- Split oversized Vue files where useful.
+- Keep operational UI dense and scannable.
+- Verify the page in browser when practical.
+- Report validation and any remaining risks.
+```
+
+## Architecture Review
+
+```text
+Review the architecture of <system or module>.
+
+Use:
+- docs/PROJECT.md
+- docs/ARCHITECTURE.md
+- docs/DECISIONS.md
+- Relevant source files
+
+Focus on:
+- Boundary clarity.
+- Backend/admin source of truth.
+- Data ownership.
+- Failure modes.
+- Security and authorization assumptions.
+- Operational complexity.
+- Maintainability over the next release cycle.
+
+Return findings ordered by severity, then trade-offs and recommended ADR updates.
+```
+
+## Security Review
+
+```text
+Perform a security review of <scope>.
+
+Focus on:
+- Authentication.
+- Authorization.
+- Input validation.
+- Output encoding.
+- Secrets handling.
+- Data exposure.
+- Demo or seed behavior.
+- Logging of sensitive data.
+- SSRF, injection, XSS, CSRF, path traversal, and insecure deserialization where relevant.
+
+For each finding include impact, exploitability, evidence, recommended fix, and
+validation strategy.
+```
+
+## Documentation Update
+
+```text
+Improve documentation for <area>.
+
+Goals:
+- Make setup and maintenance easier.
+- Preserve existing project-specific docs.
+- Remove outdated or duplicated information.
+- Add links to authoritative docs.
+- Avoid placeholders and invented policy.
+
+Validate:
+- Links are correct.
+- Commands match the repository.
+- The document is useful to a new contributor.
+```
+
+## Release Verification
+
+```text
+Verify the latest release for VTuber Star Awards.
+
+Scope:
+<commit, PR, or change summary>
+
+Check:
+- CI/deploy status when available.
+- https://award.noveria.net/api/health
+- https://award.noveria.net/api/health/database
+- Frontend asset version when relevant.
+- One targeted public or authenticated workflow affected by the change.
+
+Return confirmed facts, failures, and residual risk.
+```

docs/branching.md

@@ -0,0 +1,76 @@
+# Branching Strategy
+
+This repository uses a simple trunk-based model with short-lived branches and
+`main` as the deploy branch.
+
+For delivery workflow, see [workflow.md](workflow.md). For PR expectations, see
+[CONVENTIONS.md](CONVENTIONS.md#git-and-prs).
+
+## Default Model
+
+```mermaid
+gitGraph
+    commit id: "main"
+    branch docs-change
+    checkout docs-change
+    commit id: "work"
+    commit id: "validate"
+    checkout main
+    merge docs-change
+    commit id: "deploy"
+```
+
+## Branch Types
+
+| Type | Pattern | Purpose |
+| --- | --- | --- |
+| Feature | `feature/<short-description>` | New user-facing or system capability. |
+| Bug fix | `fix/<short-description>` | Defect correction. |
+| Refactor | `refactor/<short-description>` | Behavior-preserving structural work. |
+| Documentation | `docs/<short-description>` | Documentation-only changes. |
+| Chore | `chore/<short-description>` | Tooling or maintenance work. |
+| AI-assisted local work | `codex/<short-description>` | Short-lived Codex branch when branch creation is useful. |
+| Hotfix | `hotfix/<short-description>` | Urgent production correction. |
+
+## Main Branch
+
+`main` should remain deployable.
+
+Minimum expectations:
+
+- required checks pass;
+- risky migrations and config changes are documented;
+- production-impacting changes include validation evidence;
+- direct pushes are limited to maintainers or automation.
+
+## Feature Branches
+
+- Keep scope focused.
+- Rebase or merge from `main` according to reviewer preference.
+- Delete branches after merge.
+- Avoid stacking unrelated changes.
+- Do not include generated build output or handoff artifacts.
+
+## Commit Messages
+
+Use short imperative subjects that describe the outcome.
+
+Examples:
+
+- `Fix team profile auth recovery`
+- `Refine admin risk workspace`
+- `Document engineering workflow`
+
+Use a longer body when context, migration notes, or validation evidence is
+important for future archaeology.
+
+## Hotfixes
+
+Hotfixes should restore production safely:
+
+1. Branch from the deployed commit or current `main`.
+2. Apply the smallest safe fix.
+3. Validate the failing path.
+4. Deploy.
+5. Merge back to `main`.
+6. Add follow-up cleanup or tests when the hotfix intentionally stayed narrow.

docs/release-process.md

@@ -0,0 +1,99 @@
+# Release Process
+
+This document defines release expectations for VTuber Star Awards.
+
+For daily delivery flow, see [workflow.md](workflow.md). For branch policy, see
+[branching.md](branching.md). For release checklist, see
+[CHECKLISTS.md](CHECKLISTS.md#release).
+
+## Release Principles
+
+- Keep releases small when practical.
+- Prefer repeatable automation over manual server edits.
+- Validate before and after deployment.
+- Review migration and configuration risk before deploy.
+- Keep rollback or recovery options ready.
+
+## Release Types
+
+| Type | Description |
+| --- | --- |
+| Standard | Planned change deployed from `main` through the Gitea workflow. |
+| Hotfix | Urgent production correction with the smallest safe change. |
+| Documentation-only | Docs update that does not require runtime deployment validation. |
+| Infrastructure | Runtime, hosting, Docker, database, network, or secret/config change. |
+
+## Versioning
+
+The frontend package version lives in `frontend/package.json`. The deploy
+workflow appends build metadata and writes `VITE_BUILD_VERSION` plus
+`VITE_BUILD_DATE` before building production assets.
+
+## Readiness
+
+Before releasing application changes:
+
+- frontend build passes;
+- backend Release build passes;
+- `git diff --check` passes;
+- migration operations are reviewed;
+- target environment config and secrets are present;
+- demo, seed, CORS, and production safety settings are understood;
+- UI or API behavior has targeted validation evidence.
+
+## Automated Deployment
+
+The production deploy job in `.gitea/workflows/ci.yaml` runs on `main` pushes
+and manual dispatches.
+
+Pipeline responsibilities:
+
+1. Verify repository hygiene.
+2. Build backend and frontend.
+3. Resolve version/build metadata.
+4. Verify production host layout.
+5. Sync repository contents to the production app directory.
+6. Write frontend build metadata.
+7. Build Docker images.
+8. Write a PostgreSQL predeploy backup.
+9. Apply EF Core migrations.
+10. Recreate `api` and `web` services.
+11. Verify API health, database connectivity, pending migrations, and frontend
+    assets.
+
+## Smoke Tests
+
+Minimum automated smoke signals:
+
+- `https://award.noveria.net/api/health`
+- `https://award.noveria.net/api/health/database`
+- `pendingMigrations` is empty;
+- frontend index serves current JS and CSS assets;
+- JS asset contains expected build version metadata.
+
+Add manual smoke checks for the changed workflow, especially for admin,
+auth/permissions, voting, nomination, clip review, showact, sponsor, or content
+management changes.
+
+## Rollback And Recovery
+
+Rollback planning should address:
+
+- application artifact rollback or redeploy from a previous commit;
+- database restore or forward-fix path;
+- configuration rollback;
+- disabling demo/seed/optional public features;
+- communication of degraded public workflows.
+
+If a migration is destructive or hard to reverse, document the recovery path
+before deployment.
+
+## Post-Release Review
+
+After production-impacting releases:
+
+- confirm health checks and relevant public/admin workflows;
+- check for unexpected database migration state;
+- record incidents or anomalies;
+- update docs, checklists, or ADRs when release steps drift;
+- add follow-up tests or runbooks for gaps found during release.

docs/workflow-feedback-plan.md

@@ -10,7 +10,7 @@ Die erste grosse Aenderung sollte den Core Workflow stabilisieren: Nominierung,
 Die wichtigsten Produktentscheidungen:
 
 - Kategorien mit Viewer-Groessen werden als einzelne Kategorien pro Unterkategorie abgebildet, gruppiert ueber `GroupName`.
-- Viewer duerfen pro Kategorie bis zu drei Stream- oder Kanal-Links nominieren.
+- Viewer duerfen pro Hauptkategorie so viele Stream- oder Kanal-Links nominieren, wie in der Hauptkategorie als `MaxNomineesPerUser` konfiguriert ist. Der aktuelle Default bleibt drei.
 - Eine Nominierung muss nicht fuer alle Kategorien abgegeben werden.
 - Clip-Compilations werden nicht als Videodateien in der App gespeichert.
 - Voting und Gewinnerbereiche nutzen externe YouTube-/Twitch-Links oder Embeds.
@@ -29,21 +29,23 @@ Das Dokument beschreibt pro Award-Kategorie drei Unterkategorien nach Viewer-Gro
 
 Im aktuellen Datenmodell passt das am besten zu einzelnen `Category`-Datensaetzen pro Unterkategorie. Der uebergeordnete Award-Bereich, zum Beispiel `Gamer`, bleibt `GroupName`; die konkrete Unterkategorie wird `Name`, zum Beispiel `Hidden Star der Gamer`.
 
-Damit entsteht kein paralleles Kategorienmodell. Admin-, Public- und Voting-Flows koennen weiter mit `CategoryId` arbeiten.
+Damit entsteht kein paralleles Kategorienmodell. Admin- und Voting-Flows arbeiten weiter mit konkreten `CategoryId`s. Die Public-Nominierung wurde davon bewusst entkoppelt: User nominieren auf Hauptkategorie/`GroupName`, das passende Viewer-Tier wird danach ueber Tracker- und Admin-Review bestimmt.
+
+Um die Pflege fuer Admins einfacher zu machen, bleibt die normale Hauptkategorie-Pflege erhalten, waehrend Unterkategorien zentral in einem Season-Modal konfiguriert werden. Ein Award-Bereich bleibt `GroupName`, Unterkategorien bleiben im Ausfuehrungsmodell normale `Category`-Datensaetze, werden aber aus der globalen Definition fuer alle Hauptkategorien synchron gehalten. Viewer-Range, Name, Slug und Reihenfolge werden pro Unterkategorie strukturiert gespeichert; ein separates Standard-Set wird nicht mehr angeboten.
 
 ### Nominierung
 
-Das Feedback wuenscht pro Kategorie bis zu drei Nominierungen als Stream-/Kanal-Links. Namen sind nicht zwingend noetig, weil die Admins aus dem Link den finalen Kandidaten erstellen oder zuordnen koennen.
+Das Feedback wuenscht pro Kategorie mehrere Nominierungen als Stream-/Kanal-Links. Namen sind nicht zwingend noetig, weil die Admins aus dem Link den finalen Kandidaten erstellen oder zuordnen koennen. Das konkrete Link-Limit kommt aus der Admin-Hauptkategorie.
 
 Geplanter Zielzustand:
 
-- Pro Kategorie koennen ein bis drei Links eingereicht werden.
-- Doppelte Links innerhalb derselben Kategorie werden blockiert.
+- Pro Hauptkategorie koennen ein bis zum konfigurierten Limit Links eingereicht werden.
+- Doppelte Links innerhalb derselben Hauptkategorie werden blockiert.
 - Leere Kategorien duerfen uebersprungen werden.
 - Die Nominierungsoberflaeche wird wie ein Wizard aufgebaut: Kategorien links, Inhalt rechts, klare Weiter-Navigation.
 - Clip-Einreichung wird aus dem Nominierungsformular entfernt oder deutlich getrennt, weil laut Feedback Clips in der Nominierungsphase eher Probleme verursachen.
 
-Backendseitig existiert bereits eine passende Grundlage: `CreateNominationRequest` unterstuetzt mehrere `Nominations`, und die API verhindert doppelte Links innerhalb eines Requests. Die groesste Arbeit liegt daher im Public UI und in der Kommunikation der Regeln.
+Backendseitig speichert `Nomination` jetzt `CategoryGroupName` statt eine Tier-Kategorie als primaere Zuordnung. `CategoryId` bleibt als nullable Legacy-Feld erhalten. Twitch-Links werden best-effort ueber TwitchTracker angereichert; Nicht-Twitch-Links bleiben erlaubt und werden im Admin-Review manuell einem Tier zugeordnet.
 
 ### Vorbereitung
 
@@ -52,6 +54,9 @@ Nach der Nominierungsphase prueft das Team die Nominierungen, zaehlt aus und kon
 Geplanter Zielzustand:
 
 - Admins sehen pro Review-Fall genug Signal, um Kandidaten zuzuordnen.
+- Admins sehen Nominierungen gruppiert nach Hauptkategorie und Streamer-Identitaet.
+- Das System zeigt Trackerstatus, durchschnittliche Viewer, Tier-Vorschlag und Tally der eindeutigen User.
+- Beim Uebernehmen entsteht der Kandidat im vorgeschlagenen oder manuell gewaelten Tier.
 - Final ausgewaehlte Nominierte bekommen einen Annahmestatus.
 - Admins koennen pro Kandidat eine externe Clip-Compilation-URL pflegen.
 - Es wird keine Upload-Infrastruktur fuer Videodateien gebaut.
@@ -85,7 +90,8 @@ Diese Regeln sollten nicht still im Public UI verschwinden, sondern als Admin-Gu
 Geplanter Zielzustand:
 
 - Admins koennen final maximal vier Nominierte pro Unterkategorie festlegen.
-- Admins sehen Warnungen, wenn eine Person zu oft nominiert oder als Gewinner markiert wird.
+- Streamer-Identitaet wird zentral ueber Plattform/Login modelliert, damit dieselbe Person ueber Kategorien hinweg erkannt werden kann.
+- Admins sehen Warnungen oder Blocker, wenn eine Person zu oft nominiert oder als Gewinner markiert wird.
 - Die App blockiert riskante finale Veroeffentlichungen oder verlangt eine bewusste Admin-Bestaetigung.
 - Gewinner werden pro Unterkategorie bestimmt; bei Gleichstand oder Sonderfaellen entscheidet das Team manuell.
 
@@ -103,14 +109,14 @@ Folgeplanung:
 
 ### Phase 1: Public Nominierungs- und Voting-UX
 
-Ziel: Der Public Flow entspricht dem Feedback, ohne zuerst das Datenmodell stark umzubauen.
+Ziel: Der Public Flow entspricht dem Feedback: Nominierung auf Hauptkategorie, Voting weiter auf Tier-Kategorie.
 
 Umsetzung:
 
 - Nominierungsmodal zu einem Wizard umbauen.
-- Pro Kategorie bis zu drei Link-Felder anbieten.
-- Kategorien als linke Navigation anzeigen.
-- Kategorien ohne Eingaben erlauben.
+- Pro Hauptkategorie bis zum konfigurierten `MaxNomineesPerUser`-Limit Link-Felder anbieten.
+- Hauptkategorien als linke Navigation anzeigen.
+- Hauptkategorien ohne Eingaben erlauben.
 - Doppelte Links clientseitig validieren und Backend-Fehler sauber anzeigen.
 - Clip-Einreichung aus dem Nominierungsflow entfernen oder als separaten, weniger prominenten Flow belassen.
 - Voting-Wizard um Weiter-Button und fehlende-Stimmen-Hinweis erweitern.
@@ -118,8 +124,8 @@ Umsetzung:
 
 Akzeptanz:
 
-- Eine Kategorie kann mit einem, zwei oder drei Links eingereicht werden.
-- Doppelte Links in derselben Kategorie werden blockiert.
+- Eine Hauptkategorie kann mit einem oder mehreren Links bis zum konfigurierten Limit eingereicht werden.
+- Doppelte Links in derselben Hauptkategorie werden blockiert.
 - Ein leerer Kategorienblock verhindert nicht das Absenden anderer Kategorien.
 - Voting kann gespeichert und in derselben Phase erneut geaendert werden.
 
@@ -184,9 +190,9 @@ Akzeptanz:
 
 ### Beibehalten
 
-- `CategoryId` bleibt die zentrale Einheit fuer Nominierung und Voting.
+- `CategoryId` bleibt die zentrale Einheit fuer Voting, Kandidaten und Gewinner.
 - `GroupName` bleibt die Gruppierung fuer uebergeordnete Award-Bereiche.
-- Die Nominierungs-API bleibt grundsaetzlich erhalten.
+- Die Nominierungs-API bleibt grundsaetzlich erhalten, nimmt aber `CategoryGroupName` als neues Zielfeld; `CategoryId` bleibt Legacy-Fallback.
 - Die Voting-API bleibt grundsaetzlich erhalten.
 - Wiederholtes Vote-Speichern bleibt erlaubt und wird als Bearbeiten behandelt.
 
@@ -198,6 +204,8 @@ Akzeptanz:
   - Plattform
   - optionaler Embed-Status
 - Admin-Review braucht Statusinformationen fuer final ausgewaehlte Nominierte.
+- `Nomination` speichert Tracker-/Review-Metadaten: `ResolvedChannel`, `ResolvedPlatform`, `AvgViewers`, `SuggestedCategoryId`, `StreamerIdentityId`, `TrackerStatus`.
+- `StreamerIdentity` wird als eigene Entity fuer Plattform/Login/Normalisierung eingefuehrt.
 - Gewinnerverwaltung braucht Guards fuer interne Regeln, inklusive "maximal ein Gewinnerplatz" und "Clip-Link fuer Gewinner erforderlich".
 
 ### Nicht bauen

docs/workflow.md

@@ -0,0 +1,124 @@
+# Development Workflow
+
+This document defines the default path from idea to released change.
+
+For branch policy, see [branching.md](branching.md). For release execution, see
+[release-process.md](release-process.md). For task quality gates, see
+[CHECKLISTS.md](CHECKLISTS.md).
+
+## Workflow Overview
+
+```mermaid
+flowchart LR
+    Idea["Idea, bug, or feedback"]
+    Clarify["Clarify scope"]
+    Plan["Plan or ADR"]
+    Implement["Implement"]
+    Validate["Validate"]
+    Review["Review"]
+    Merge["Merge"]
+    Release["Release"]
+    Learn["Update docs/checklists"]
+
+    Idea --> Clarify
+    Clarify --> Plan
+    Plan --> Implement
+    Implement --> Validate
+    Validate --> Review
+    Review --> Merge
+    Merge --> Release
+    Release --> Learn
+```
+
+## 1. Clarify Scope
+
+Before implementation:
+
+- restate the objective in engineering terms;
+- identify affected public, admin, backend, database, or deployment surfaces;
+- confirm acceptance criteria and non-goals;
+- identify security, authorization, migration, data-loss, or live-production
+  risk;
+- ask concise questions when ambiguity affects important behavior.
+
+## 2. Inspect Existing Context
+
+Read the relevant source and docs before editing:
+
+- [PROJECT.md](PROJECT.md) for runtime and product facts;
+- [ARCHITECTURE.md](ARCHITECTURE.md) for boundaries;
+- [CONVENTIONS.md](CONVENTIONS.md) for coding standards;
+- [DECISIONS.md](DECISIONS.md) for durable trade-offs;
+- [../DESIGN.md](../DESIGN.md) for UI work;
+- feature plans such as [workflow-feedback-plan.md](workflow-feedback-plan.md)
+  when the task builds on planned product feedback.
+
+## 3. Plan The Change
+
+Use a lightweight plan for non-trivial changes. Create or update an ADR when
+the change affects:
+
+- architecture style or module boundaries;
+- data ownership or public contracts;
+- authentication, authorization, or security posture;
+- deployment strategy, migrations, or long-term operating cost.
+
+## 4. Implement
+
+Implementation expectations:
+
+- keep changes focused and reviewable;
+- follow existing frontend/backend patterns;
+- split large Vue surfaces into smaller components or composables;
+- keep backend/admin data authoritative for public behavior;
+- avoid unrelated refactors unless needed for the requested change;
+- preserve user changes in a dirty worktree.
+
+## 5. Validate
+
+Default validation:
+
+```bash
+cd frontend
+npm run build
+
+cd ..
+dotnet build Backend/Backend.csproj --configuration Release
+git diff --check
+```
+
+Add targeted validation by risk:
+
+- API checks for backend behavior;
+- authenticated checks for admin/team/permission changes;
+- browser checks for visible UI changes;
+- responsive geometry checks for layout work;
+- database health and migration checks for schema changes;
+- live checks only for release or explicitly live-scoped work.
+
+When frontend and backend are both actively used for local verification, keep
+them running as a pair or shut both down together.
+
+## 6. Review
+
+Review should answer:
+
+- Does the change solve the stated problem?
+- Does it preserve backend/admin truth?
+- Is authorization enforced at the trusted boundary?
+- Are migrations and deployment risk understood?
+- Are docs and validation sufficient for the risk?
+
+## 7. Merge And Release
+
+`main` is the production deployment branch. Pushes to `main` run CI and deploy
+when the workflow conditions match. Follow [release-process.md](release-process.md).
+
+## 8. Learn
+
+After meaningful releases, regressions, or repeated review feedback:
+
+- update docs or checklists;
+- add or update ADRs;
+- add regression coverage when practical;
+- record follow-up work where the repo exposes an operational or test gap.