Adding obsidian docs with initial notes

docs/agent.md.md

@@ -0,0 +1,253 @@
+# **agent.md — Game Reference Platform Agent Specification**
+
+## **Purpose**
+
+This agent defines the architecture, responsibilities, and operational expectations for the **Game Reference**, a Blazor‑based website to host:
+
+- **Build calculators**
+    
+- **Learning documentation**
+    
+- **Game data reference libraries**
+    
+
+The web app is designed for **modularity**, **data portability**, and **long‑term maintainability**, with a roadmap toward **self‑hosted offline builds**.
+
+---
+
+## **High‑Level Responsibilities**
+
+- **Data ingestion**: Regularly update game data sets from external sources (official APIs, community wikis, manual imports).
+    
+- **Data persistence**: Store all game data, user builds, and metadata in PostgreSQL.
+    
+- **Web delivery**: Serve interactive Blazor WebAssembly or Server pages for calculators and documentation.
+    
+- **Automation**: Validate functionality through NUnit unit tests and Selenium UI automation.
+    
+- **Containerization**: Package each game site as a Docker image for deployment or local use.
+    
+- **Offline mode**: Allow users to download the site and run it with their own local PostgreSQL instance.
+    
+
+---
+
+## **System Architecture**
+
+### **Platform Overview**
+
+- **Frontend**: Blazor WebAssembly or Blazor Server (project‑specific choice)
+    
+- **Backend**: ASP.NET Core minimal APIs or controllers
+    
+- **Database**: PostgreSQL (hosted or local)
+    
+- **Containerization**: Docker Compose for multi‑service orchestration
+    
+- **Testing**: NUnit + Selenium (C#)
+    
+- **CI/CD**: GitHub Actions or Azure DevOps (future)
+    
+
+---
+
+
+    
+
+### **Data Update Strategy**
+
+Data ingestion may occur via:
+
+- **Manual imports**
+    
+- **Official game APIs**
+    
+- **Community‑maintained datasets**
+    
+
+The agent must support:
+
+- Scheduled updates
+    
+- Versioning of game data
+    
+- Rollback capability
+    
+- Validation before ingestion
+    
+
+---
+
+## **Docker Architecture**
+
+### **Container Layout**
+
+Each game site includes:
+
+- `blazor-app` container
+    
+- `postgres` container (optional for production, required for offline mode)
+    
+- `data-import` container (optional automation)
+    
+
+### **Local Development**
+
+Users can run:
+
+```
+docker compose up --build
+```
+
+This launches:
+
+- Blazor site
+    
+- Local PostgreSQL
+    
+- Optional admin tools (pgAdmin)
+    
+
+---
+
+## **Testing Strategy**
+
+### **NUnit Unit Tests**
+
+Unit tests cover:
+
+- Data models
+    
+- Calculation logic
+    
+- API endpoints
+    
+- Data ingestion validation
+    
+
+Tests live in:
+
+```
+/tests/GameSlop.Tests.Unit
+```
+
+### **Selenium UI Automation**
+
+A separate C# Selenium project validates:
+
+- Page load behavior
+    
+- Calculator functionality
+    
+- Navigation flow
+    
+- Form inputs
+    
+- Error handling
+    
+
+Tests live in:
+
+```
+/tests/GameSlop.Tests.UI
+```
+
+Automation runs against:
+
+- Local Docker environment
+    
+- Staging environment
+    
+- Production (read‑only tests)
+    
+
+---
+
+## **Offline Mode (Long‑Term Goal)**
+
+Users will be able to:
+
+1. Download a packaged version of a game site.
+    
+2. Run it locally via Docker.
+    
+3. Use a local PostgreSQL instance.
+    
+4. Save builds offline.
+    
+5. Import/export builds as JSON.
+    
+
+This requires:
+
+- Self‑contained Docker Compose bundles
+    
+- Local EF migrations
+    
+
+---
+
+## **Agent Responsibilities**
+
+### **Build Calculators**
+
+The agent must:
+
+- Load game data dynamically
+    
+- Apply calculation logic (damage, stats, modifiers)
+    
+- Support multiple build variants
+    
+- Allow saving/loading builds from PostgreSQL
+    
+
+### **Documentation Engine**
+
+The agent must:
+
+- Render markdown or rich text
+    
+- Support versioned documentation
+    
+
+### **Data Sync**
+
+The agent must:
+
+- Detect outdated data
+    
+- Fetch new data
+    
+- Validate and sanitize
+    
+- Apply migrations if needed
+    
+
+### **Observability**
+
+The agent should log:
+
+- Data ingestion events
+    
+- User build saves
+    
+- Errors and exceptions
+    
+- Performance metrics
+    
+
+
+---
+
+## **Contributor Guidelines**
+
+- Follow C# coding standards
+    
+- Use EF migrations for schema changes
+    
+- Write NUnit tests for all logic
+    
+- Add Selenium tests for UI changes
+    
+- Document new features in `/docs`