deploy

.agent/AGENT_MEMORY.md

@@ -0,0 +1,174 @@
+# AGENT_MEMORY.md — Unified Agent Memory System
+<!-- trigger: always_on -->
+<!-- priority: P0 — Read this BEFORE any other file -->
+
+> **MANDATORY:** Every AI agent (Antigravity, Gemini, Claude, Codex, any terminal script)
+> **MUST** read this file at the **start of every conversation or session** when the `.Agent`
+> folder is present in the workspace. This is the highest-priority initialization step.
+
+---
+
+## 🧠 What is the Agent Memory System?
+
+A locally-running, filesystem-based shared memory layer for all AI agents. It persists:
+- **Tasks** — current work, status, description, and which agent owns it
+- **Checkpoints** — compressed mid-task snapshots so you can resume without context loss
+- **Knowledge** — reusable facts and architecture decisions
+- **Usage** — per-agent token consumption for optimization
+
+All data lives in `.Agent/memory/` as plain JSON. No server. No cloud. No dependencies.
+
+---
+
+## 📋 Step 1: Load Current Context (MANDATORY at session start)
+
+Run this at the beginning of **every** conversation to get your current task context:
+
+```bash
+python .Agent/scripts/memory_engine.py --context --agent <YOUR_AGENT_NAME> --max-tokens 4000
+```
+
+This returns a `<MEMORY_CONTEXT>` block. **Inject it into your first response** so you
+know what task is in progress without the user having to repeat themselves.
+
+**Agent name examples** (use any string — fully dynamic):
+- `antigravity`, `gemini`, `claude`, `codex`, `terminal`, `my_script`, `claude-code`
+
+---
+
+## 📝 Step 2: Register Your Task (when starting or resuming work)
+
+```bash
+# New task
+python .Agent/scripts/memory_engine.py --write \
+  --task "Build auth module" \
+  --agent "antigravity" \
+  --status "in_progress" \
+  --description "Implementing JWT + refresh token flow for the API"
+
+# Resume existing task
+python .Agent/scripts/memory_engine.py --write \
+  --task-id <ID_FROM_CONTEXT> \
+  --task "Build auth module" \
+  --agent "antigravity" \
+  --status "in_progress"
+```
+
+---
+
+## 💾 Step 3: Save Checkpoints (CRITICAL — before context grows large)
+
+Save a checkpoint **proactively** every ~30,000 tokens or at the end of a major step:
+
+```bash
+python .Agent/scripts/memory_engine.py --checkpoint \
+  --task-id <TASK_ID> \
+  --agent "antigravity" \
+  --summary "Completed DB schema design. Next: implement routes." \
+  --content "Schema: users(id, email, hash), tokens(id, user_id, expires_at)..."
+```
+
+The context will be auto-compressed before saving, so it stays small.
+
+---
+
+## ⚡ Step 4: Check & Optimize Token Usage
+
+```bash
+# Check your token usage
+python .Agent/scripts/usage_tracker.py --report
+
+# Get optimization tips
+python .Agent/scripts/usage_tracker.py --tips
+
+# Log what you just used (call this after a long session)
+python .Agent/scripts/usage_tracker.py --log \
+  --agent "antigravity" \
+  --model "gemini-2.5-pro" \
+  --input 15000 \
+  --output 8000 \
+  --task-id <TASK_ID>
+```
+
+---
+
+## 🔍 Step 5: Search Past Memory (when unsure what was done)
+
+```bash
+python .Agent/scripts/memory_engine.py --search "auth module"
+python .Agent/scripts/memory_engine.py --search "database schema"
+```
+
+---
+
+## ✅ Step 6: Complete a Task
+
+```bash
+python .Agent/scripts/memory_engine.py --complete \
+  --task-id <TASK_ID> \
+  --summary "Auth module complete. JWT + refresh + middleware all working."
+```
+
+---
+
+## 🚨 Context Window Emergency Protocol
+
+If you are **near your context limit**, do this immediately:
+
+```bash
+# 1. Auto-compress and checkpoint everything
+python .Agent/scripts/context_optimizer.py --auto-checkpoint \
+  --task-id <TASK_ID> --agent <NAME> --input context_dump.txt --threshold 60000
+
+# 2. Start a fresh conversation
+# 3. At the start of the new conversation, run Step 1 above to reload context
+```
+
+---
+
+## 📊 Live Dashboard
+
+Open the local dashboard in any browser (no server needed):
+```
+d:\Code\.Agent\dashboard\index.html
+```
+
+Or via PowerShell aliases (after running `setup_memory_hook.ps1`):
+```powershell
+agent-status    # Current session + task
+agent-report    # Token usage per agent
+agent-tips      # Optimization recommendations
+agent-watch     # Live watch for changes
+```
+
+---
+
+## 🔌 Cross-Agent Compatibility
+
+| Agent           | How to inject AGENT_MEMORY.md |
+|-----------------|-------------------------------|
+| **Antigravity** | Add to `.gemini/GEMINI.md`: `always_on` trigger |
+| **Gemini CLI**  | Add `@.Agent/AGENT_MEMORY.md` to your prompt |
+| **Claude**      | Add to `CLAUDE.md` or system prompt |
+| **Codex / GPT** | Include in `system_prompt.txt` |
+| **Terminal**    | `python .Agent/scripts/activate.py` on shell start |
+| **Custom**      | `python .Agent/scripts/memory_engine.py --context --agent <name>` |
+
+See **MEMORY_PROTOCOL.md** for the full JSON schema and integration spec.
+
+---
+
+## 📁 File Reference
+
+| File | Purpose |
+|------|---------|
+| `memory/memory-store.json` | Tasks, checkpoints, knowledge (persistent) |
+| `memory/usage-tracker.json` | Per-agent token usage log |
+| `memory/session.json` | Hot session state (fast read) |
+| `scripts/memory_engine.py` | Core read/write/compress/search |
+| `scripts/usage_tracker.py` | Token usage logging and reports |
+| `scripts/context_optimizer.py` | Token budget + auto-compress |
+| `scripts/activate.py` | Session initializer |
+| `scripts/workspace_watcher.py` | Live status watcher |
+| `dashboard/index.html` | Local web dashboard |
+| `setup_memory_hook.ps1` | PowerShell auto-activation installer |

.agent/Backend/API_Versioning.md

@@ -0,0 +1,23 @@
+# API Versioning Strategies
+
+## 1. URL Versioning
+
+Include the version number in the URL (e.g., `/v1/users`). This is the most common and visible strategy.
+
+## 2. Header Versioning
+
+Define the version in a custom header (e.g., `X-API-Version: 1`). This keeps URLs clean and avoids breaking existing links.
+
+## 3. Query Parameter Versioning
+
+Include the version in a query parameter (e.g., `/users?v=1`). This is similar to URL versioning but can be more flexible.
+
+## 4. Media Type Versioning
+
+Define the version in the `Accept` header's media type (e.g., `Accept: application/vnd.myapi.v1+json`). This follows RESTful principles but can be more complex.
+
+## 5. Compatibility
+
+Ensure that your API versioning strategy supports backward compatibility as much as possible to avoid breaking client applications.
+
+Jonas

.agent/Backend/ApiDesign.md

@@ -0,0 +1,21 @@
+# API Design Principles
+
+## Core Standards
+
+1. **Statelessness**: Every request must contain all information needed to fulfill it.
+2. **Versioning**: Use URL versioning (e.g., `/api/v1/...`) to prevent breaking changes.
+3. **Consistency**: Consistent naming (camelCase), status codes, and error formats.
+
+## Resource-Oriented Design
+
+- `GET /items`: List items.
+- `POST /items`: Create item.
+- `GET /items/:id`: Get specific item.
+- `PUT /items/:id`: Replace item.
+- `PATCH /items/:id`: Update item partially.
+- `DELETE /items/:id`: Remove item.
+
+## Documentation
+
+- Self-document using Swagger/OpenAPI or TSON (Type-Safe Object Notation).
+- Include examples for request bodies and response schemas.

.agent/Backend/Authentication_Strategies.md

@@ -0,0 +1,21 @@
+# Authentication Strategies
+
+## 1. JWT (JSON Web Tokens)
+
+Stateless authentication using tokens. Good for scalability, but requires careful management of token expiration and revocation.
+
+## 2. Session-Based
+
+Traditional stateful authentication where the server stores session data and the client holds a session ID in a cookie.
+
+## 3. OAuth2 / OpenID Connect
+
+Standards for delegated authorization and authentication, often used for third-party logins (e.g., Google, GitHub).
+
+## 4. Multi-Factor Authentication (MFA)
+
+Enhance security by requiring more than one form of verification.
+
+## 5. Password Hashing
+
+Always use strong, salted hashing algorithms like Argon2 or BCrypt to store passwords.

.agent/Backend/CachingStrategies.md

@@ -0,0 +1,23 @@
+# Caching Strategies for Backend Performance
+
+## 1. Identifying Cacheable Data
+
+Cache data that is frequently accessed and relatively static, such as configuration settings or product catalogs.
+
+## 2. Cache Levels
+
+Implement caching at multiple levels, including in-memory (e.g., Redis, Memcached) and at the application level.
+
+## 3. Cache Invalidation
+
+Establish clear strategies for invalidating the cache when the underlying data changes to ensure consistency.
+
+## 4. Cache Expiration (TTL)
+
+Set appropriate Time-To-Live (TTL) values for cached data to prevent it from becoming stale.
+
+## 5. Monitoring
+
+Monitor cache hit rates and performance to ensure your caching strategy is effective.
+
+Jonas

.agent/Backend/DatabaseNormalization.md

@@ -0,0 +1,25 @@
+# Database Normalization Principles
+
+## 1. Goal
+
+The primary goal of database normalization is to reduce data redundancy and improve data integrity by organizing data into related tables.
+
+## 2. Normal Forms (1NF, 2NF, 3NF)
+
+Understand and apply the different normal forms to ensure your database design is efficient and robust.
+
+## 3. Benefits
+
+- Reduced data anomalies.
+- Improved data consistency.
+- More efficient data storage and retrieval.
+
+## 4. Trade-offs
+
+In some cases, over-normalization can lead to complex queries and performance issues. Be mindful of the trade-offs.
+
+## 5. Practical Application
+
+Apply normalization principles during the database design phase to create a solid foundation for your application.
+
+Jonas

.agent/Backend/DatabaseOptimization.md

@@ -0,0 +1,19 @@
+# Database Optimization & Schema Design
+
+## Schema Rules
+
+1. **Normalization**: Aim for 3NF to reduce redundancy.
+2. **Indexing**: Index frequently queried columns (IDs, Slugs, Timestamps). Avoid over-indexing.
+3. **Foreign Keys**: Enforce data integrity with proper relational constraints.
+
+## Query Performance
+
+- **Selectivity**: Only SELECT the columns you need. Avoid `SELECT *`.
+- **Joins**: Optimize JOIN operations; avoid N+1 query problems using eager loading.
+- **Pagination**: Use cursor-based pagination for large datasets.
+
+## Migration Standards
+
+- Use a robust migration tool (e.g., Prisma, Knex).
+- Never modify existing migrations; always create a new one.
+- Migration scripts must be reversible (Up/Down).

.agent/Backend/DatabaseScalability.md

@@ -0,0 +1,22 @@
+# Database Scalability: Sharding & Replication
+
+## 1. Read Replication
+
+- Direct read queries to "read-only" replicas to scale out read heavy workloads.
+- The master node handles all writes.
+
+## 2. Horizontal Sharding
+
+- Splitting data across multiple database instances based on a shard key (e.g., `user_id`, `region`).
+
+## 3. Data Consistency
+
+- Understand the trade-offs between strictly consistent systems and eventually consistent systems.
+
+## 4. Failover & High Availability
+
+- Configure automatic failover to a standby node if the master node goes down.
+
+## 5. Partitioning
+
+- Use database-level partitioning to split large tables into smaller, more manageable pieces within a single instance.

.agent/Backend/DenoRuntime.md

@@ -0,0 +1,21 @@
+# Deno Runtime vs Node.js
+
+## 1. Security by Default
+
+- No file, network, or environment access unless explicitly enabled via flags (e.g., `--allow-net`).
+
+## 2. TypeScript Support
+
+- Deno has built-in TypeScript support; no separate compiler or config needed.
+
+## 3. Standard Library
+
+- Comprehensive, audited standard library following Go's model.
+
+## 4. ES Modules Only
+
+- No `require()`; all modules must be imported via URLs or file paths.
+
+## 5. Built-in Utilities
+
+- Includes a test runner, linter, and formatter out of the box.

.agent/Backend/Microservices_Communication.md

@@ -0,0 +1,21 @@
+# Microservices Communication
+
+## 1. Synchronous vs Asynchronous
+
+Understand when to use REST/gRPC (synchronous) versus Message Queues/Pub-Sub (asynchronous).
+
+## 2. API Gateways
+
+Use an API gateway to centralize authentication, rate limiting, and request routing.
+
+## 3. Service Discovery
+
+Implement a mechanism for services to find each other dynamically (e.g., Consul, Kubernetes DNS).
+
+## 4. Resiliency
+
+Use patterns like circuit breakers and retries to handle transient failures between services.
+
+## 5. Message Serialization
+
+Choose efficient serialization formats like Protocol Buffers (protobuf) for inter-service communication.

.agent/Backend/Nodejs_Cluster.md

@@ -0,0 +1,21 @@
+# Node.js Cluster Module & Multi-threading
+
+## 1. Scaling to Multiple Cores
+
+- Since Node.js is single-threaded, use the `cluster` module to spawn worker processes that share the same server port.
+
+## 2. Master & Worker Processes
+
+- The Master process manages workers and distributes incoming connections.
+
+## 3. IPC (Inter-Process Communication)
+
+- Use `process.send()` and `on('message')` to communicate between master and worker processes.
+
+## 4. Zero-Downtime Reloads
+
+- Restart workers one by one when releasing new code to ensure the server stays active.
+
+## 5. PM2 Process Manager
+
+- In most production environments, prefer an external manager like **PM2** which handles clustering and automatic restarts out of the box.

.agent/Backend/ORM_BestPractices.md

@@ -0,0 +1,21 @@
+# ORM Best Practices (Prisma/Drizzle)
+
+## 1. Type Safety
+
+- Leverage auto-generated types from your schema to ensure end-to-end type safety.
+
+## 2. Efficient Joins
+
+- Use `include` or `select` (Prisma) or explicit joins (Drizzle) to fetch exactly what you need. Avoid over-fetching.
+
+## 3. Batching & Transaction
+
+- Use `$transaction` to ensure atomic operations (either all succeed or all fail).
+
+## 4. Middleware/Hooks
+
+- Use ORM-level middleware for cross-cutting concerns like logging or soft deletes (marking as deleted instead of removing).
+
+## 5. Connection Pooling
+
+- Use tools like `accelerate` (Prisma) or standard pg-pool to manage database connections in serverless environments.

.agent/Backend/PubSub_Architecture.md

@@ -0,0 +1,21 @@
+# Pub-Sub Architecture & Message Queues
+
+## 1. Decoupling Services
+
+- Use Publisher-Subscriber patterns to allow services to communicate without knowing about each other.
+
+## 2. Message Brokers
+
+- Use Redis (BullMQ), RabbitMQ, or Amazon SQS for reliable message delivery.
+
+## 3. Idempotency
+
+- Ensure that message consumers can handle the same message multiple times without unintended side effects.
+
+## 4. Retries & Dead Letter Queues (DLQ)
+
+- Automatically retry failed tasks. Move persistently failing tasks to a DLQ for manual inspection.
+
+## 5. Event-Driven Workflows
+
+- Trigger long-running tasks (e.g., report generation, bulk email) asynchronously via the queue.

.agent/Backend/ServerActions.md

@@ -0,0 +1,14 @@
+# Backend & Server Actions
+
+## Server Actions (`lib/actions`)
+
+1. **Async Synchronization**: Use `Promise.all` for parallel tasks and proper `await` for sequential ones.
+2. **Validation**: Validate all inputs using `Zod` before processing.
+3. **Error Handling**: Use try-catch blocks and return structured error objects.
+4. **Security**: Ensure user session/permission check at the start of every action.
+
+## API Integration
+
+- Keep server-side logic strictly in `lib/actions`.
+- Avoid leaking database schemas to the client; use DTOs (Data Transfer Objects).
+- Implement rate limiting and input sanitization.

.agent/Backend/WebSockets.md

@@ -0,0 +1,13 @@
+# WebSockets & Real-time Communication
+
+## Logic Standards
+
+1. **Connection Management**: Implement robust auto-reconnect logic with exponential backoff.
+2. **Event Naming**: Use a clear `namespace:action` format (e.g., `billing:invoice_updated`).
+3. **Security**: Authenticate the socket connection using JWT or session tokens during the handshake.
+
+## Performance
+
+- **Throttling**: Limit the rate of outgoing messages for high-frequency data (e.g., mouse positions, typing).
+- **Binary Format**: Use `Protocol Buffers` or `MsgPack` for large binary data to reduce payload size.
+- **Heartbeats**: Send regular ping/pong messages to keep the connection alive and detect dead links.

.agent/Design/Animations.md

@@ -0,0 +1,14 @@
+# Animation Principles & Motion
+
+## Core Rules
+
+1. **Purpose-Driven**: Every animation must serve a purpose (e.g., feedback, hierarchy, entry).
+2. **Smooth Transitions**: Standard durations: `200ms` for small transitions, `400-600ms` for larger layout shifts.
+3. **Easing**: Use `cubic-bezier(0.4, 0, 0.2, 1)` for natural motion. Avoid linear timing.
+4. **Staggering**: Stagger entry of list items to create a flow effect.
+
+## Library Standards
+
+- **Framer Motion**: Default for complex UI transitions.
+- **GSAP**: Use for high-performance timeline-based animations.
+- **CSS Transitions**: Preferred for simple hover and focus states.

.agent/Design/ColorPalettes.md

@@ -0,0 +1,21 @@
+# Color Palettes for Modern UI
+
+## 1. Sourcing Inspiration
+
+Draw inspiration for your color palettes from nature, art, and successful designs.
+
+## 2. Creating a Palette
+
+Create a cohesive color palette with a primary color, secondary colors, and accent colors.
+
+## 3. Contrast and Accessibility
+
+Ensure your color palette provides sufficient contrast for readability and accessibility.
+
+## 4. Consistency
+
+Use your color palette consistently throughout your application to create a sense of unity.
+
+## 5. Testing
+
+Test your color palette with real users to ensure it's visually appealing and easy to use.

.agent/Design/ColorTheory.md

@@ -0,0 +1,25 @@
+# Color Theory for Premium UI
+
+## 1. Visual Hierarchy
+
+- Use bold, varied colors for primary actions and soft, neutral colors for background elements.
+- **60-30-10 Rule**: 60% dominant (neutral), 30% secondary, 10% accent (bright/vibrant).
+
+## 2. HSL over HEX
+
+- Prefer HSL (Hue, Saturation, Lightness) for easier adjustments and programmatic color generation.
+- **Consistent Tonal Variations**: Build a palette based on different lightness levels of a few core hues.
+
+## 3. Contrast & Accessibility (WCAG)
+
+- Ensure a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text.
+- Use tools like Lighthouse to verify accessibility.
+
+## 4. Semantic Colors
+
+- Define standardized names: `primary`, `secondary`, `success`, `warning`, `danger`, `info`.
+
+## 5. Dark Mode Strategies
+
+- Use deep grays/navy instead of pure black (`#000000`) for backgrounds to reduce eye strain.
+- Invert lightness while maintaining hue and saturation for icons and accents.

.agent/Design/DesignSystem.md

@@ -0,0 +1,18 @@
+# Design System & Aesthetics
+
+## Visual Identity
+
+- **Glassmorphism**: Use subtle backgrounds with `backdrop-filter: blur()`, thin borders, and low-opacity fills.
+- **Color Palette**: Curated HSL colors. Avoid generic primary colors. Use deep bolds and soft pastels.
+- **Typography**: Primary: `Inter` or `Outfit`. Secondary: `Roboto Mono` for data.
+
+## UI Components
+
+- **Buttons**: Smooth transitions, hover scaling (1.02x), and active state indentation.
+- **Inputs**: Clear focus rings, animated labels, and inline validation.
+- **Micro-animations**: Use GSAP or Framer Motion for subtle entry/exit effects.
+
+## Layout
+
+- Grid/Flexbox for responsiveness.
+- Consistent spacing (8px base unit).

.agent/Design/Glassmorphism.md

@@ -0,0 +1,21 @@
+# Glassmorphism & Modern UI Style
+
+## Visual Standards
+
+1. **Backgrounds**: Transparent, high-blur (10-20px) layers with a white or tinted overlay (10-20% opacity).
+2. **Borders**: Thin (0.5-1px), semi-transparent borders to define edges.
+3. **Lighting**: Subtle inner shadows or gradients to simulate 3D depth and light source.
+4. **Saturation**: Boost the background saturation behind blurred elements for a premium feel.
+
+## Implementation (CSS)
+
+```css
+.glass-container {
+  background: rgba(255, 255, 255, 0.1);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  border-radius: 16px;
+  box-shadow: 0 4px 30px rgba(0, 0, 0, 0.1);
+}
+```

.agent/Design/Glassmorphism_Advanced.md

@@ -0,0 +1,21 @@
+# Advanced Glassmorphism Techniques
+
+## 1. Layered Blurs
+
+- Use multiple stacked containers with varying `backdrop-filter: blur()` and boarder opacities to simulate depth.
+
+## 2. Noise & Texture
+
+- Add a subtle noise texture (`svg` or `png`) as a low-opacity background layer to give the glass a material feel.
+
+## 3. Dynamic Refraction
+
+- Use subtle gradients that move with the mouse cursor to simulate light refraction on a glass surface.
+
+## 4. Inner Glow (Inner Shadow)
+
+- Use `box-shadow: inset ...` to highlight edges and make the glass element "pop" from its background.
+
+## 5. Saturation Boost
+
+- Use `backdrop-filter: blur(12px) saturate(180%)` to make the colors behind the glass look more vibrant and expensive.

.agent/Design/Layout_Grid.md

@@ -0,0 +1,21 @@
+# Layout Grids in UI Design
+
+## 1. Importance
+
+Layout grids provide a framework for organizing content and creating a consistent visual hierarchy.
+
+## 2. Common Grid Systems
+
+Common grid systems include the 12-column grid and the modular grid.
+
+## 3. Responsive Design
+
+Use responsive grids that adapt to different screen sizes and orientations.
+
+## 4. Consistency
+
+Use a consistent grid system throughout your application to create a sense of order.
+
+## 5. Breaking the Grid
+
+Don't be afraid to occasionally break the grid for visual interest or to highlight important content.

.agent/Design/Layout_Pillars.md

@@ -0,0 +1,27 @@
+# Holy Grail Layout & Modern Grids
+
+## 1. The Holy Grail Layout
+
+- Header, Main Content (with sidebars), and Footer.
+- Use CSS Grid for the most robust implementation.
+
+## 2. Flexbox for Micro-Layouts
+
+- Perfect for navbars, card headers, and button groups.
+
+## 3. Subgrid & Nested Grids
+
+- Use `grid-template-columns: subgrid` to align nested elements with the parent grid.
+
+## 4. Aspect Ratio Control
+
+- Use `aspect-ratio` property to reserve space for images and videos, preventing Layout Shift (CLS).
+
+## 5. Container Queries
+
+- Favor `@container` over `@media` for components that need to respond to their parent container's size rather than the viewport.
+
+## 6. Sticky & Overlay Elements
+
+- Use `position: sticky` for persistent navs and sidebars.
+- Implementation of glassmorphism on sticky headers for a premium floating feel.

.agent/Design/MicroAnimations.md

@@ -0,0 +1,21 @@
+# Micro-Animations in UI Design
+
+## 1. Purpose
+
+Micro-animations are small, subtle animations that provide feedback and enhance the user experience.
+
+## 2. Feedback
+
+Use micro-animations to provide feedback when a user interacts with an element, such as a button click or form submission.
+
+## 3. Guiding the User
+
+Use micro-animations to guide the user's attention to important parts of the interface.
+
+## 4. Transitions
+
+Use smooth transitions to make the interface feel more fluid and natural.
+
+## 5. Overusing
+
+Avoid overusing micro-animations, as they can become distracting and even frustrating for users.

.agent/Design/Typography_Advanced.md

@@ -0,0 +1,25 @@
+# Advanced Typography Standards
+
+## 1. Typographic Scale
+
+- Use a consistent ratio (e.g., 1.25 Modular Scale) to define sizes for `h1` through `h6`.
+- Root size: `16px` (1rem).
+
+## 2. Line Heights & Spacing
+
+- Body text: `1.5` to `1.6` for optimal readability.
+- Headings: `1.1` to `1.3` for a compact, authoritative look.
+- Letter spacing: `-0.01em` to `-0.02em` for headings to increase "tightness."
+
+## 3. Font Loading & Performance
+
+- Use `font-display: swap` to prevent FOUT (Flash of Unstyled Text).
+- Prefer variable fonts to reduce bundle size if multiple weights are needed.
+
+## 4. Optical Sizing
+
+- Enable `font-optical-sizing: auto` when available for better legibility at small sizes.
+
+## 5. System Fonts Fallback
+
+- Always include a reliable system font stack as a fallback (e.g., `-apple-system, BlinkMacSystemFont, "Segoe UI", ...`).

.agent/Design/Typography_Scales.md

@@ -0,0 +1,21 @@
+# Typography Scales in UI Design
+
+## 1. Definition
+
+A typography scale is a set of predefined font sizes used consistently throughout a design.
+
+## 2. Creating a Scale
+
+Create a typography scale with sizes for headings, body text, and captions.
+
+## 3. Consistency
+
+Use your typography scale consistently throughout your application to create a sense of hierarchy and rhythm.
+
+## 4. Legibility
+
+Ensure your typography scale provides sufficient legibility for all users.
+
+## 5. Testing
+
+Test your typography scale with real users to ensure it's easy to read and provides clear visual hierarchy.

.agent/DevOps/CiCd.md

@@ -0,0 +1,20 @@
+# DevOps & CI/CD Pipelines
+
+## Core Principles
+
+1. **Automate Everything**: From testing to deployments.
+2. **Shift Left**: Catch bugs as early as possible (Git hooks).
+3. **Immutable Infrastructure**: Changes should be applied through code, not manual tweaks.
+
+## GitHub Actions Standards
+
+- **Pull Request**: Trigger lint, typecheck, and unit tests.
+- **Merge to Main**: Trigger build and staging deployment.
+- **Tag/Release**: Trigger production deployment.
+- **Fail Fast**: Cancel previous runs if a new commit is pushed.
+
+## Secret Management
+
+- Never commit secrets to the repository.
+- Use GitHub Secrets or AWS Secrets Manager.
+- Use `.env.template` for developer onboarding.

.agent/DevOps/ContinuousDeployment.md

@@ -0,0 +1,25 @@
+# Continuous Deployment (CD)
+
+## 1. Definition
+
+Continuous Deployment is the practice of automatically deploying code changes to production after they have passed a suite of automated tests.
+
+## 2. Benefits
+
+- Faster delivery of new features and fixes.
+- Reduced risk of human error during deployment.
+- Improved collaboration and communication.
+
+## 3. Automation
+
+Automate your entire deployment process, from building and testing to deploying and monitoring.
+
+## 4. Rollback
+
+Establish a mechanism for automatically rolling back a deployment if it fails.
+
+## 5. Monitoring
+
+Continuously monitor your production environment for potential issues after a deployment.
+
+Jonas

.agent/DevOps/DockerBestPractices.md

@@ -0,0 +1,21 @@
+# Docker Best Practices for Production
+
+## 1. Use Small Base Images
+
+- Prefer `alpine` or `distroless` images to reduce attack surface and build time.
+
+## 2. Multi-Stage Builds
+
+- Separate your build environment from your runtime environment to keep final images small.
+
+## 3. Don't Run as Root
+
+- Use the `USER` instruction to run your application as a non-privileged user.
+
+## 4. Use .dockerignore
+
+- Exclude `node_modules`, logs, and local configuration files from the build context.
+
+## 5. Layer Caching
+
+- Order your Dockerfile instructions from least-to-most frequently changed to optimize build caching.

.agent/DevOps/IaC.md

@@ -0,0 +1,13 @@
+# Infrastructure as Code (IaC)
+
+## Standards
+
+1. **Declarative**: Use Terraform or AWS CloudFormation to describe your infrastructure.
+2. **Version Control**: Infrastructure code must reside in the same repo as the application.
+3. **Modularity**: Create reusable modules for VPCs, S3 buckets, and RDS instances.
+
+## Cloud Strategy
+
+- **AWS/Google Cloud**: Scale based on traffic.
+- **Edge Computing**: Use Cloudflare Workers for caching and security at the edge.
+- **Serverless**: Prefer serverless functions for cost efficiency on low-traffic modules.

.agent/DevOps/InfrastructureAsCode.md

@@ -0,0 +1,25 @@
+# Infrastructure as Code (IaC)
+
+## 1. Definition
+
+IaC is the process of managing and provisioning your infrastructure using machine-readable definition files, rather than manual configuration.
+
+## 2. Benefits
+
+- Increased efficiency and speed.
+- Improved consistency and reliability.
+- Better collaboration and version control.
+
+## 3. Tooling
+
+Use tools like Terraform, Ansible, or CloudFormation to define and manage your infrastructure as code.
+
+## 4. Version Control
+
+Store your IaC files in a version control system like Git to track changes and collaborate with others.
+
+## 5. Testing
+
+Test your IaC code to ensure it correctly provisions your infrastructure as expected.
+
+Jonas

.agent/DevOps/Kubernetes.md

@@ -0,0 +1,23 @@
+# Kubernetes Orchestration Basics
+
+## 1. Pods & Services
+
+- Understand that Pods are logically grouped containers.
+- Use Services to provide a stable IP/DNS name for a group of Pods.
+
+## 2. Deployments & Rollouts
+
+- Use Deployments to manage stateless applications.
+- Implement Rolling Updates to replace old pods with new ones without downtime.
+
+## 3. ConfigMaps & Secrets
+
+- Store configuration and sensitive data externally from the pod image.
+
+## 4. Ingress Controllers
+
+- Use Ingress (like Nginx) to route external HTTP/S traffic to internal services.
+
+## 5. Autoscaling (HPA)
+
+- Automatically scale the number of pods based on CPU or memory usage.

.agent/DevOps/Logging_Monitoring.md

@@ -0,0 +1,22 @@
+# Logging & Monitoring: Prometheus & Grafana
+
+## 1. Structured Logging
+
+- Log in JSON format to make it easy for log collectors (like Fluentd, ELK) to parse and index.
+
+## 2. Redaction of PII
+
+- Automatically strip sensitive info (email, phone, credit card) from logs.
+
+## 3. Correlation IDs
+
+- Append a unique Request-ID to every log message in a single request flow to trace it across services.
+
+## 4. Key Metrics
+
+- Track the "Four Golden Signals": Latency, Traffic, Errors, and Saturation.
+
+## 5. Dashboards and Alerts
+
+- Use Grafana to visualize metrics.
+- Set up alerts for high error rates or unusual latency spikes.

.agent/DevOps/MonitoringPerformance.md

@@ -0,0 +1,23 @@
+# Monitoring Performance in Production
+
+## 1. Key Performance Indicators (KPIs)
+
+Identify the key performance indicators for your application, such as response time, error rate, and throughput.
+
+## 2. Real-Time Monitoring
+
+Monitor your application in real-time to detect performance issues as they happen.
+
+## 3. Alerting and Notification
+
+Set up alerts for when KPIs exceed predefined thresholds.
+
+## 4. Performance Analysis
+
+Analyze your performance data to identify trends and potential optimizations.
+
+## 5. Capacity Planning
+
+Use your performance data to plan for future growth and ensure your infrastructure can handle it.
+
+Jonas

.agent/DevOps/Monitoring_Alerting.md

@@ -0,0 +1,21 @@
+# Monitoring and Alerting
+
+## 1. Purpose
+
+Monitoring provides visibility into the health and performance of your application, while alerting notifies you of critical issues in real-time.
+
+## 2. Key Metrics to Monitor
+
+Monitor vital signs like CPU usage, memory consumption, request latency, and error rates.
+
+## 3. Setting Up Alerts
+
+Define threshold-based alerts for critical metrics and configure notifications through channels like email, Slack, or PagerDuty.
+
+## 4. Log Aggregation
+
+Centralize logs from all your services into a single searchable location (e.g., ELK stack, Datadog, or CloudWatch Logs).
+
+## 5. Automated Response
+
+Consider implementing automated responses to certain alerts, such as auto-scaling resources or restarting services.

.agent/Engineering/API_First_Development.md

@@ -0,0 +1,23 @@
+# API-First Development
+
+## 1. Principle
+
+Design the API first, before any implementation. This ensures the API meets the needs of its consumers and provides a stable contract.
+
+## 2. Benefits
+
+- Improved developer experience for API consumers.
+- Reduced development time through parallel frontend and backend development.
+- Higher quality and better-designed APIs.
+
+## 3. Tooling
+
+Use tools like Swagger or Stoplight to design and document your APIs using the OpenAPI Specification.
+
+## 4. Collaborative Design
+
+Involve stakeholders and API consumers in the design process to ensure the API meets their needs.
+
+## 5. Implementation
+
+Once the API is designed, implement the backend and frontend in parallel, using the API contract as a guide.

.agent/Engineering/BigO_Notation.md

@@ -0,0 +1,25 @@
+# Big O Notation & Algorithmic Complexity
+
+## 1. O(1) - Constant Time
+
+- Execution time is independent of the input size (e.g., accessing an array element by index).
+
+## 2. O(log n) - Logarithmic Time
+
+- Execution time grows logarithmically with input size (e.g., Binary Search).
+
+## 3. O(n) - Linear Time
+
+- Execution time grows linearly with input size (e.g., iterating through a list).
+
+## 4. O(n log n) - Linearithmic Time
+
+- Common in efficient sorting algorithms like Merge Sort and Quick Sort.
+
+## 5. O(n²) - Quadratic Time
+
+- Execution time is proportional to the square of input size (e.g., nested loops).
+
+## 6. O(2ⁿ) - Exponential Time
+
+- Execution time doubles with each addition to the input (e.g., recursive Fibonacci).

.agent/Engineering/CI_CD_Philosophy.md

@@ -0,0 +1,21 @@
+# CI/CD Philosophy
+
+## 1. Automation
+
+Automate every aspect of the software delivery process, from testing to deployment.
+
+## 2. Small, Frequent Updates
+
+Ship smaller changes more frequently to reduce risk and get faster feedback.
+
+## 3. Continuous Feedback
+
+Incorporate automated tests and quality checks at every step to catch issues early.
+
+## 4. Reproducibility
+
+Ensure that every build and deployment is reproducible, with clear versioning and configuration management.
+
+## 5. Deployment Pipelines
+
+Define clear pipelines for moving code from development to production, with appropriate manual approvals if necessary.

.agent/Engineering/CleanCode.md

@@ -0,0 +1,20 @@
+# Clean Code Standards
+
+## Core Principles
+
+1. **Readable > Clever**: Code should be self-documenting.
+2. **DRY (Don't Repeat Yourself)**: Abstract logic into reusable hooks or utilities.
+3. **KISS (Keep It Simple, Stupid)**: Avoid over-engineering.
+4. **Single Responsibility**: Each function/component should do ONE thing well.
+
+## Naming Conventions
+
+- **Files**: `PascalCase` for components, `camelCase` for hooks/utils.
+- **Variables**: Descriptive `camelCase`.
+- **Booleans**: Prefix with `is`, `has`, `should`.
+
+## Formatting
+
+- Use Prettier/ESLint configs.
+- Limit line length to 80-100 characters.
+- Consistent indentation (2 spaces).

.agent/Engineering/CodeReviewGuidelines.md

@@ -0,0 +1,28 @@
+# Code Review Guidelines
+
+## 1. Purpose
+
+Code reviews are a collaborative process intended to improve code quality, share knowledge, and ensure consistency.
+
+## 2. Review Checklist
+
+- **Functionality**: Does the code do what it's supposed to do?
+- **Readability**: Is the code easy to understand and maintain?
+- **Performance**: Are there any potential performance issues?
+- **Security**: Are there any security vulnerabilities?
+- **Testing**: Is the code properly tested?
+
+## 3. Best Practices
+
+- Keep reviews small and focused.
+- Provide constructive feedback.
+- Be respectful and professional.
+- Use tools to automate parts of the review process.
+
+## 4. Code Ownership
+
+Everyone on the team is responsible for the quality of the codebase.
+
+## 5. Continuous Improvement
+
+Use code reviews as an opportunity to learn and improve your coding skills.

.agent/Engineering/Concurrency_Patterns.md

@@ -0,0 +1,27 @@
+# Concurrency Patterns & Async Flow
+
+## 1. Single Threaded Event Loop
+
+- Understand how the Node.js/Browser event loop handles asynchronous operations using the task and microtask queues.
+
+## 2. Promises & Async/Await
+
+- Use for multi-step asynchronous processes.
+- Handle multiple promises with `Promise.all` (parallel), `Promise.allSettled` (robust), and `Promise.race` (timeout).
+
+## 3. Web Workers
+
+- Use to run CPU-intensive tasks in a background thread to prevent blocking the UI/main thread.
+
+## 4. Generators & Iterators
+
+- Use for custom iteration behavior and lazy data streams.
+
+## 5. Streams (Node.js)
+
+- Use for processing large datasets chunk by chunk rather than loading everything into memory.
+- `Readable`, `Writable`, and `Transform` streams.
+
+## 6. Sagas & Side Effect Management
+
+- In large applications, use structured side effect management (e.g., Redux-Saga or custom event-based handlers).

.agent/Engineering/Constants.md

@@ -0,0 +1,23 @@
+# Single Source of Truth: Constants & Configuration
+
+## Rules
+
+1. **Centralization**: All non-changeable text, magic numbers, and config must reside in `constants/` or `.env`.
+2. **PascalCase for Constants**: Use `UPPER_SNAKE_CASE` for global constants.
+3. **No Hardcoded Strings**: Even UI labels should be pulled from a constants file or i18n store.
+
+## Implementation
+
+```typescript
+// constants/billing.ts
+export const INVOICE_STATUS = {
+  PAID: 'paid',
+  PENDING: 'pending',
+  OVERDUE: 'overdue',
+} as const;
+
+export const TAX_RATES = {
+  GST: 0.18,
+  VAT: 0.05,
+} as const;
+```

.agent/Engineering/DRY_KISS_YAGNI.md

@@ -0,0 +1,16 @@
+# DRY, KISS, and YAGNI
+
+## DRY (Don't Repeat Yourself)
+
+- Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.
+- Avoid copy-pasting code; use functions, hooks, or shared components.
+
+## KISS (Keep It Simple, Stupid)
+
+- Most systems work best if they are kept simple rather than made complicated.
+- Avoid over-engineering and unnecessary abstractions.
+
+## YAGNI (You Ain't Gonna Need It)
+
+- Always implement things when you actually need them, never when you just foresee that you need them.
+- Avoid "just-in-case" coding features that add complexity without immediate value.

.agent/Engineering/DataStructures.md

@@ -0,0 +1,27 @@
+# Essential Data Structures
+
+## 1. Arrays & Linked Lists
+
+- O(1) access for arrays, O(n) for linked lists.
+- O(1) insertion at the head for linked lists.
+
+## 2. Stacks & Queues
+
+- **Stack**: LIFO (Last-In-First-Out).
+- **Queue**: FIFO (First-In-First-Out).
+
+## 3. Hash Tables (Maps/Objects)
+
+- Provides average O(1) lookup, insertion, and deletion.
+
+## 4. Trees (Binary Search Trees)
+
+- Allow for O(log n) searching and sorted traversal.
+
+## 5. Graphs
+
+- Represent relationships between objects. Used for social networks, maps, and dependency tracking.
+
+## 6. Heaps
+
+- Specialized tree-based data structure used for priority queues.

.agent/Engineering/Debugging.md

@@ -0,0 +1,21 @@
+# Debugging Techniques for Complex Systems
+
+## 1. Rubber Duck Debugging
+
+- Explain your code and logic to a surrogate (a literal rubber duck or a colleague) to find logical flaws.
+
+## 2. Binary Search Debugging
+
+- Comment out halves of your code to isolate the specific section causing the error.
+
+## 3. Logpoints over Breakpoints
+
+- In production or complex async environments, use conditional logpoints to trace state without pausing execution.
+
+## 4. Time Travel Debugging
+
+- Use tools like Redux DevTools or specialized IDE features to step backwards through state changes.
+
+## 5. Network & Performance Profiling
+
+- Use browser DevTools to identify slow API calls, memory leaks, and unnecessary layout shifts.

.agent/Engineering/DependencyInjection.md

@@ -0,0 +1,17 @@
+# Dependency Injection & Inversion of Control
+
+## IoC (Inversion of Control)
+
+- Design principle in which a software component's dependencies are provided by an external framework or container, rather than the component managing them itself.
+
+## Dependency Injection (DI)
+
+- Pattern that implements IoC by injecting dependencies into a class's constructor, properties, or methods.
+- **Constructor Injection**: Preferred method for mandatory dependencies.
+- **Setter Injection**: Used for optional dependencies.
+
+## Advantages
+
+- **Decoupling**: Components are less tethered to specific implementations.
+- **Testability**: Dependencies can be easily mocked or stubbed.
+- **Maintainability**: Swapping implementations requires minimal code changes.

.agent/Engineering/DesignPatterns_Behavioral.md

@@ -0,0 +1,41 @@
+# Behavioral Design Patterns
+
+## Chain of Responsibility
+
+- Lets you pass requests along a chain of handlers. Upon receiving a request, each handler decides either to process the request or to pass it to the next handler in the chain.
+
+## Command
+
+- Turns a request into a stand-alone object that contains all information about the request. This transformation lets you pass requests as a method arguments, delay or queue a request’s execution, and support undoable operations.
+
+## Iterator
+
+- Lets you traverse elements of a collection without exposing its underlying representation (list, stack, tree, etc.).
+
+## Mediator
+
+- Lets you reduce chaotic dependencies between classes. The pattern restricts direct communications between the classes and forces them to collaborate only via a mediator object.
+
+## Memento
+
+- Lets you save and restore the previous state of an object without revealing the details of its implementation.
+
+## Observer
+
+- Lets you define a subscription mechanism to notify multiple objects about any events that happen to the object they’re observing.
+
+## State
+
+- Lets an object alter its behavior when its internal state changes. It appears as if the object changed its class.
+
+## Strategy
+
+- Lets you define a family of algorithms, put each of them into a separate class, and make their objects interchangeable.
+
+## Template Method
+
+- Defines the skeleton of an algorithm in the superclass but lets subclasses override specific steps of the algorithm without changing its structure.
+
+## Visitor
+
+- Lets you separate algorithms from the objects on which they operate.

.agent/Engineering/DesignPatterns_Creational.md

@@ -0,0 +1,24 @@
+# Creational Design Patterns
+
+## Singleton
+
+- Ensures a class has only one instance and provides a global point of access to it.
+- Use for database connections or shared configuration managers.
+
+## Factory Method
+
+- Defines an interface for creating an object, but lets subclasses decide which class to instantiate.
+- Useful for dynamic instantiation based on runtime conditions.
+
+## Abstract Factory
+
+- Provides an interface for creating families of related or dependent objects without specifying their concrete classes.
+
+## Builder
+
+- Separates the construction of a complex object from its representation.
+- Excellent for objects with many optional parameters.
+
+## Prototype
+
+- Specifies the kinds of objects to create using a prototypical instance, and creates new objects by copying this prototype.

.agent/Engineering/DesignPatterns_Structural.md

@@ -0,0 +1,30 @@
+# Structural Design Patterns
+
+## Adapter
+
+- Allows objects with incompatible interfaces to collaborate.
+- Acts as a wrapper between two objects.
+
+## Bridge
+
+- Lets you split a large class or a set of closely related classes into two separate hierarchies—abstraction and implementation—which can be developed independently.
+
+## Composite
+
+- Lets you compose objects into tree structures and then work with these structures as if they were individual objects.
+
+## Decorator
+
+- Lets you attach new behaviors to objects by placing these objects inside special wrapper objects that contain the behaviors.
+
+## Facade
+
+- Provides a simplified interface to a library, a framework, or any other complex set of classes.
+
+## Flyweight
+
+- Lets you fit more objects into the available amount of RAM by sharing common parts of state between multiple objects instead of keeping all of the data in each object.
+
+## Proxy
+
+- Provides a substitute or placeholder for another object. A proxy controls access to the original object, allowing you to perform something either before or after the request gets through to the original object.

.agent/Engineering/E2ETesting.md

@@ -0,0 +1,21 @@
+# End-to-End (E2E) Testing Guidelines
+
+## 1. Scope
+
+E2E tests simulate real user scenarios from start to finish, exercising the entire application stack.
+
+## 2. Tooling
+
+Use Playwright or Cypress for reliable, cross-browser E2E testing.
+
+## 3. Key Workflows
+
+Focus on critical paths such as login, user registration, and checkout processes.
+
+## 4. Environment
+
+Run E2E tests against a production-like environment (Staging) before deploying to production.
+
+## 5. Maintenance
+
+E2E tests can be fragile. Design them to be as robust as possible, but be prepared to update them as the UI evolves.