Cleanup Spec Files

AGENTS.md

@@ -0,0 +1,21 @@
+# Bike Tracking Agent Guide
+
+Bike Tracking is a local-first commuter app that records rides and computes savings using a .NET Minimal API, F# domain logic, and a React TypeScript frontend.
+
+## Always Applies
+- Work inside the DevContainer only.
+- Run the app with `dotnet run --project src/BikeTracking.AppHost`.
+- Use TDD with mandatory failing-test proof before implementation.
+- E2E tests are required for every PR.
+- Run the post-change verification matrix before merge.
+
+## Instruction Packs
+- [Architecture Principles](docs/agent/architecture-principles.md)
+- [Domain And Error Handling](docs/agent/domain-and-error-handling.md)
+- [Testing And Quality Gates](docs/agent/testing-and-quality-gates.md)
+- [Frontend And UX](docs/agent/frontend-and-ux.md)
+- [Data Events And Projections](docs/agent/data-events-and-projections.md)
+- [Delivery And Git Workflow](docs/agent/delivery-and-git-workflow.md)
+- [Runtime And Observability](docs/agent/runtime-and-observability.md)
+- [Stack And Environment](docs/agent/stack-and-environment.md)
+- [Flagged For Deletion](docs/agent/flagged-for-deletion.md)

docs/agent/architecture-principles.md

@@ -0,0 +1,18 @@
+# Architecture Principles
+
+## Scope
+Rules that shape all backend and cross-layer architecture decisions.
+
+## Required
+- Keep domain and application logic isolated from infrastructure through ports and adapters.
+- Define ports in inner layers as technology-agnostic interfaces.
+- Implement adapters in infrastructure only; adapters are replaceable.
+- Introduce anti-corruption layers for third-party APIs and SDKs.
+- Prevent leakage of external transport or SDK types into domain/application models.
+- Separate orchestration, business rules, and I/O concerns.
+- Prefer small composable services; do not create god services.
+
+## Design Checks
+- Does this change introduce or modify a boundary contract?
+- Are third-party types translated at boundaries?
+- Is each class or module focused on one responsibility?

docs/agent/data-events-and-projections.md

@@ -0,0 +1,17 @@
+# Data Events And Projections
+
+## Scope
+Event sourcing, CQRS, persistence, and migration-test coupling rules.
+
+## Required
+- Persist domain actions as immutable append-only events.
+- Separate write behavior (commands/events) from read behavior (projections).
+- Keep event and API contracts explicit and versioned.
+- Maintain projection builders independently from command handlers.
+- For each migration, add or update automated tests that cover the change.
+- Prevent schema and contract drift through compatibility checks.
+
+## Design Checks
+- Is the event contract backward compatible?
+- Is projection behavior validated by tests?
+- Is migration impact covered by automated tests?

docs/agent/delivery-and-git-workflow.md

@@ -0,0 +1,17 @@
+# Delivery And Git Workflow
+
+## Scope
+Branching, PR, CI, and feature-flag governance.
+
+## Required
+- Follow trunk-based development with short-lived feature branches.
+- Open PRs for all changes; do not push directly to main.
+- Link each PR to a GitHub issue.
+- Keep branches current with main before merge.
+- Use feature flags for in-progress work merged to main.
+- Limit active feature flags and remove them after rollout.
+- Preserve owner-controlled final merge authority.
+
+## CI Expectations
+- Validation checks must pass before merge.
+- Include build, formatting/linting, unit/integration checks, and E2E.

docs/agent/domain-and-error-handling.md

@@ -0,0 +1,17 @@
+# Domain And Error Handling
+
+## Scope
+Rules for domain modeling and expected-flow error handling.
+
+## Required
+- Model core business logic as pure functions when feasible.
+- Keep impure effects (time, I/O, external calls) at application boundaries.
+- Use immutable domain state and explicit transformation steps.
+- Prefer F# discriminated unions and active patterns for domain modeling.
+- Represent expected business, validation, and conflict outcomes with explicit Result-style return values.
+- Reserve exceptions for unexpected failures only.
+
+## Design Checks
+- Can this behavior be tested without infrastructure?
+- Are expected failures represented as data, not thrown exceptions?
+- Are side effects isolated to adapters or handlers?

docs/agent/flagged-for-deletion.md

@@ -0,0 +1,17 @@
+# Flagged For Deletion Or Demotion
+
+## Redundant
+- Principle rationale text repeated across multiple sections without adding enforceable rules.
+- Repeated reminders to reference React documentation in several places.
+- Duplicate C# API language requirement bullets with overlapping content.
+- Long amendment changelog embedded in the active constitution guidance body.
+
+## Too Vague To Enforce
+- "Prioritize experimentation and learning" without required output artifacts.
+- "Simple and intuitive UX" without measurable acceptance criteria.
+- "Avoid feature creep" without scope-control checks.
+
+## Overly Obvious
+- "No broken builds."
+- "Run tests before merge."
+- "Use meaningful commit messages."

docs/agent/frontend-and-ux.md

@@ -0,0 +1,16 @@
+# Frontend And UX
+
+## Scope
+React and UX requirements that affect frontend implementation.
+
+## Required
+- Use React (latest stable) with TypeScript and Vite.
+- Keep client-side validation aligned with server-side constraints.
+- Meet WCAG 2.1 AA accessibility expectations.
+- Build mobile-first responsive UI.
+- Keep design tokens centralized for consistent theming.
+- Validate implementation details against official React docs: https://react.dev/
+
+## Authentication Direction
+- Current implementation baseline: local PIN and session token flow.
+- Future-phase architecture: OAuth/MSAL path may be introduced later.

docs/agent/runtime-and-observability.md

@@ -0,0 +1,15 @@
+# Runtime And Observability
+
+## Scope
+Runtime quality targets and telemetry requirements.
+
+## Required
+- Target API p95 latency below 500ms under normal load.
+- Emit structured logs, metrics, and traces.
+- Use Aspire OpenTelemetry wiring for service telemetry.
+- Keep Aspire Dashboard usage to local diagnostics only.
+- For cloud scenarios, use Application Insights as the observability backend.
+
+## Deployment Posture
+- Local-first deployment is the default operating model.
+- Cloud deployment is a supported profile for future or scaled scenarios.

docs/agent/stack-and-environment.md

@@ -0,0 +1,21 @@
+# Stack And Environment
+
+## Scope
+Tooling and stack constraints that apply across tasks.
+
+## Required
+- Develop inside the DevContainer.
+- Backend stack: .NET 10 Minimal API with C# and F# domain layer.
+- Frontend stack: React + TypeScript + Vite.
+- Local-first data profile uses SQLite by default.
+- Keep package dependencies maintained with regular update reviews.
+
+## Canonical Commands
+- Start full local stack:
+  - `dotnet run --project src/BikeTracking.AppHost`
+- Backend tests:
+  - `dotnet test BikeTracking.slnx`
+- Frontend checks:
+  - `cd src/BikeTracking.Frontend && npm run lint && npm run build && npm run test:unit`
+- E2E tests:
+  - `cd src/BikeTracking.Frontend && npm run test:e2e`

docs/agent/testing-and-quality-gates.md

@@ -0,0 +1,31 @@
+# Testing And Quality Gates
+
+## Scope
+Mandatory test and validation requirements before implementation and merge.
+
+## TDD Workflow
+1. Write tests that define expected behavior before implementation.
+2. Execute tests and prove they fail for behavioral reasons.
+3. Obtain explicit confirmation of failing-test evidence before coding.
+4. Implement the minimum change to satisfy failing tests.
+5. Re-run tests after meaningful changes.
+6. Refactor only while tests remain green.
+
+## Red-Proof Policy
+- Failing-test proof is mandatory before implementation.
+- A committed red checkpoint is optional.
+
+## Required Verification Matrix
+- Frontend-only changes:
+  - `cd src/BikeTracking.Frontend`
+  - `npm run lint`
+  - `npm run build`
+  - `npm run test:unit`
+- Backend or domain changes:
+  - `dotnet test`
+- Cross-layer or authentication changes:
+  - Run all impacted commands above
+  - `cd src/BikeTracking.Frontend && npm run test:e2e`
+
+## PR Gate
+- E2E tests are required for every PR.

specs/001-create-a-per-user/spec.md

@@ -2,9 +2,11 @@
 
 **Feature Branch**: `001-create-a-per-user`  
 **Created**: 2026-03-30  
-**Status**: Draft  
+**Status**: Superseded by `009-create-a-per-user`  
 **Input**: User description: "Create a per user settings page. Allow entry of average car mpg, a yearly goal, location picker for lat and long, oil change price, and mileage rate (in cents)."
 
+> This folder is retained for historical traceability. Use `specs/009-create-a-per-user/` as the canonical implementation-ready spec set for this feature.
+
 ## User Scenarios & Testing *(mandatory)*
 
 <!--

specs/001-project-scaffold/checklists/requirements.md

@@ -47,7 +47,7 @@
 - "simple hello screen" is clearly understood via acceptance scenarios
 - "callable endpoint" defined as health check or sample data
 - "build with dotnet build" is unambiguous
-- Frontend framework (TypeScript/Vue) is reasonable default based on existing project
+- Frontend framework (TypeScript/React) is aligned with existing project
 
 **Requirements are testable**: ✓ Examples:
 - FR-005: "buildable with `dotnet build`" → clear pass/fail
@@ -60,7 +60,7 @@
 - SC-007: "90% of developers successfully" → quantified percentage
 
 **Success criteria are technology-agnostic**: ✓ Criteria focus on user-facing outcomes:
-- "displays hello screen within 5 seconds" (not "Vue component renders in 100ms")
+- "displays hello screen within 5 seconds" (not "specific framework render timing")
 - "responds within 2 seconds" (not "ASP.NET Core response time")
 - No framework or language specifics in criteria
 

specs/001-project-scaffold/plan.md

@@ -13,7 +13,7 @@ Create a well-structured, multi-project .NET solution that demonstrates modern d
 **Primary Dependencies**:
   - .NET Aspire (service orchestration)
   - ASP.NET Core (API framework)
-  - Vue + TypeScript + Vite (frontend framework)
+    - React 19 + TypeScript + Vite (frontend framework)
   - F# (domain logic layer)
 
 **Storage**: N/A (no database in this phase - out of scope)  
@@ -52,12 +52,11 @@ src/
 │   └── Properties/
 │       └── launchSettings.json       # Launch profiles
 │
-├── BikeTracking.Frontend/           # Vue + TypeScript + Vite SPA
+├── BikeTracking.Frontend/           # React + TypeScript + Vite SPA
 │   ├── src/
 │   │   ├── index.html               # Hello screen entry point
-│   │   ├── main.ts                  # App initialization
-│   │   ├── my-app.ts                # Main component
-│   │   └── my-app.html              # Template
+│   │   ├── main.tsx                 # App initialization
+│   │   └── App.tsx                  # Main component
 │   ├── package.json                 # Dependencies
 │   ├── vite.config.ts               # Vite configuration
 │   └── tsconfig.json                # TypeScript configuration
@@ -115,10 +114,10 @@ This structure provides:
 - Better for small services and verification endpoints
 - Aligns with Aspire best practices
 
-### 3. Vue + Vite for Frontend
-**Decision**: Continue with existing Vue + Vite + TypeScript setup
+### 3. React + Vite for Frontend
+**Decision**: Use React + Vite + TypeScript setup
 **Rationale**:
-- Already configured in existing project
+- Aligned with current repository frontend standards
 - Modern development experience with hot reload
 - Type safety with TypeScript
 - Good ecosystem and community support
@@ -215,7 +214,7 @@ All items from spec.md Success Criteria must be met:
 | 5 Projects | Clear separation: API, Frontend, Domain, Defaults, Orchestration. Simpler structure (3 projects) inadequate for demonstrating multi-tier architecture |
 | F# Project | Type-driven domain modeling. Direct C# insufficient for showcasing functional patterns |
 | Aspire Usage | Enterprise-grade orchestration. Manual configuration inadequate for complex multi-service setup |
-| Vue Frontend | Modern SPA framework required. Plain HTML insufficient for demonstrating hot reload and component patterns |
+| React Frontend | Modern SPA framework required. Plain HTML insufficient for demonstrating hot reload and component patterns |
 
 ## File Locations & Artifacts
 
@@ -225,7 +224,7 @@ All items from spec.md Success Criteria must be met:
 | Global Config | `global.json` | Enforce .NET 10+ |
 | README | `README.md` | Setup, running, structure documentation |
 | API Program | `src/BikeTracking.Api/Program.cs` | Minimal API endpoints |
-| Frontend Entry | `src/BikeTracking.Frontend/src/main.ts` | App initialization |
-| Hello Screen | `src/BikeTracking.Frontend/src/my-app.html` | Hello screen template |
+| Frontend Entry | `src/BikeTracking.Frontend/src/main.tsx` | App initialization |
+| Hello Screen | `src/BikeTracking.Frontend/src/App.tsx` | Hello screen component |
 | AppHost | `src/BikeTracking.AppHost/AppHost.cs` | Service orchestration |
 | Service Defaults | `src/BikeTracking.ServiceDefaults/Extensions.cs` | Shared configuration |

specs/001-project-scaffold/spec.md

@@ -87,7 +87,7 @@ As a DevOps engineer reviewing the project, I want to confirm that the project u
 
 - **FR-001**: Solution MUST use multi-project structure with separate concerns: API, Frontend, Domain, AppHost, and Service Defaults
 - **FR-002**: API project MUST be a runnable .NET service that can start independently 
-- **FR-003**: Frontend project MUST be a TypeScript/Vue-based application with development server capability
+- **FR-003**: Frontend project MUST be a TypeScript/React-based application with development server capability
 - **FR-004**: AppHost project MUST orchestrate and configure all services for local development using .NET Aspire
 - **FR-005**: Solution MUST be buildable with `dotnet build` command without errors
 - **FR-006**: Solution MUST have a solution file (.slnx) that includes all projects
@@ -128,7 +128,7 @@ As a DevOps engineer reviewing the project, I want to confirm that the project u
 - **API endpoint**: API includes at least one working endpoint (e.g., health check, sample data endpoint) for verification
 - **No database**: Specification explicitly excludes database schema or ORM setup; data layer is out of scope
 - **Monorepo structure**: Project uses a single git repository with multiple projects organized in `/src/` folder
-- **Frontend framework**: Frontend uses modern JavaScript/TypeScript tooling (Vue with Vite based on existing package.json)
+- **Frontend framework**: Frontend uses modern JavaScript/TypeScript tooling (React with Vite)
 - **Service orchestration**: .NET Aspire is used for local development orchestration (not production deployment)
 
 ## Scope Boundaries

specs/001-project-scaffold/tasks.md

@@ -110,20 +110,20 @@ description: "Tasks for Project Structure and Scaffolding"
 
 ### Implementation for US2
 
-- [ ] T028 [US2] Create hello screen markup in `src/BikeTracking.Frontend/src/my-app.html` with:
+- [ ] T028 [US2] Create hello screen component in `src/BikeTracking.Frontend/src/App.tsx` with:
   - Basic HTML structure
   - "Hello, Bike Tracking!" heading
   - Description paragraph
   - Basic styling (inline or minimal CSS)
 
-- [ ] T029 [US2] Verify `src/BikeTracking.Frontend/vite.config.ts` enables hot reload with `@vitejs/plugin-vue`
+- [ ] T029 [US2] Verify `src/BikeTracking.Frontend/vite.config.ts` enables hot reload with `@vitejs/plugin-react`
 
 - [ ] T030 [US2] Update `src/BikeTracking.Frontend/package.json` to include:
   - Script: `dev` → `vite` (dev server)
   - Script: `build` → `vite build` (production build)
   - Script: `preview` → `vite preview` (preview production build)
 
-- [ ] T031 [US2] Verify `src/BikeTracking.Frontend/src/main.ts` correctly initializes Vue app and loads `my-app.html`
+- [ ] T031 [US2] Verify `src/BikeTracking.Frontend/src/main.tsx` correctly initializes the React app and loads `App.tsx`
 
 - [ ] T032 [US2] Setup environment configuration for frontend:
   - Create `.env.local` template with API endpoint
@@ -143,7 +143,7 @@ description: "Tasks for Project Structure and Scaffolding"
   - Readable font and spacing
   - Simple color scheme
 
-- [ ] T035 [P] [US2] Test hot reload: start dev server, modify `my-app.html`, verify page updates without manual refresh
+- [ ] T035 [P] [US2] Test hot reload: start dev server, modify `App.tsx`, verify page updates without manual refresh
 
 - [ ] T036 [US2] Update `README.md` Troubleshooting section with Frontend-specific issues:
   - "npm install fails" → check Node version
@@ -249,7 +249,7 @@ description: "Tasks for Project Structure and Scaffolding"
   - How to add new features
   - How to add new services
 
-- [ ] T052 [P] [US4] Document TypeScript/Vue patterns in Frontend:
+- [ ] T052 [P] [US4] Document TypeScript/React patterns in Frontend:
   - Component structure
   - Type safety approach
   - Hot reload during development
@@ -377,7 +377,7 @@ This delivers:
 | `README.md` | Setup documentation | Create → Build throughout |
 | `src/BikeTracking.Api/Program.cs` | API endpoints | Scaffold (T037) |
 | `src/BikeTracking.Api/appsettings.json` | API config | Configure (T038) |
-| `src/BikeTracking.Frontend/src/my-app.html` | Hello screen | Create (T028) |
+| `src/BikeTracking.Frontend/src/App.tsx` | Hello screen | Create (T028) |
 | `src/BikeTracking.Frontend/vite.config.ts` | Frontend build | Verify (T029) |
 | `src/BikeTracking.AppHost/AppHost.cs` | Service orchestration | Configure (T009-T012) |
 | `src/BikeTracking.ServiceDefaults/Extensions.cs` | Shared config | Setup (T006-T008) |

specs/002-user-signup-pin/spec.md

@@ -2,7 +2,7 @@
 
 **Feature Branch**: `001-user-signup-pin`  
 **Created**: 2026-03-13  
-**Status**: Draft  
+**Status**: Complete  
 **Input**: User description: "Create and identify the user. Create a minimal signup screen (name and pin) with the validation, api, events and database structure to store that. Each user will get a new database id. We are focusing on the local flow now, in the future we will add Azure hosting and OAuth authentication. The pin will be the authorization approach and needs to be encrypted."
 
 ## Clarifications