docs(agents): create comprehensive agent guidelines document

- Document project overview and target audience - Detail all 4 physical areas with specifications - Define equipment categories for major machines and hand tools - Explain taxonomy system and usage - Provide page templates for machines, areas, and hand tools - Document navigation structure and organization - Add content guidelines and tone requirements - Include git workflow with conventional commit examples - Add Docker environment commands and file locations - Define work priorities and quality checklist - Create reference document for future agents 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush <crush@charm.land>
2026-01-13 16:38:49 -05:00
parent efa5c703e6
commit 42ce121c4c
1 changed files with 506 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,506 @@
 # Starting Line Productions LLC - Agent Guidelines
 This document provides comprehensive guidelines for AI agents working on the Starting Line Productions LLC website.
 ## Project Overview
 **Business:** Starting Line Productions LLC
 **Type:** Prototyping job shop renting resources/spaces by the hour
 **Location:** Pflugerville, Texas
 **Target Audience:** High-paying clients ($100+/hour)
 **Platform:** Grav CMS 1.7.49.5 (Docker: linuxserver/grav:1.7.49)
 ## Physical Areas
 The facility is organized into **4 main areas**. Each area has dedicated equipment and tools.
 ### 1. EE Garage
 **Location:** Main garage
 **Size:** 400 sq ft
 **Capacity:** 4-6 people
 **Purpose:** Electronics prototyping and testing
 **Equipment Categories:**
 - Test equipment (oscilloscopes, function generators, power supplies)
 - Soldering stations
 - Hot plate and reflow oven
 - Pick and place machine
 - Hand tools for electronics
 - Measuring tools
 **Content Location:** `/config/www/user/pages/05.areas/01.ee-garage/`
 ### 2. Dirty Fabrication
 **Location:** Backyard (primary), Garage & Shed (tools)
 **Total Size:** 1,500 sq ft
 **Capacity:** 8-10 people
 **Purpose:** Metal fabrication, machining, welding
 **Sub-Locations:**
 - **Backyard (800 sq ft):** CNC Mill, CNC Router, MIG/TIG welders, Plasma cutter
 - **Garage Section (400 sq ft):** CNC Lathe, Surface Grinder, Manual Lathe, Manual Mill, Bandsaw, Drill Press
 - **Shed Section (300 sq ft):** Hand tools, cutting tools, consumables, safety equipment
 **Content Location:** `/config/www/user/pages/05.areas/02.dirty-fabrication/`
 ### 3. Clean Fabrication
 **Location:** Upstairs dedicated room
 **Size:** 300 sq ft
 **Capacity:** 2-4 people
 **Purpose:** Precision assembly, clean electronics work, controlled environment
 **Content Location:** `/config/www/user/pages/05.areas/03.clean-fabrication/` (to be created)
 ### 4. Kitchen
 **Location:** Dedicated kitchen
 **Size:** 250 sq ft
 **Capacity:** 2-4 people
 **Purpose:** Commercial kitchen rental for food preparation and cooking projects
 **Content Location:** `/config/www/user/pages/05.areas/04.kitchen/` (to be created)
 ## Equipment Categories
 Major machines have **dedicated individual pages**. General hand tools and equipment are documented in **category pages** by area.
 ### Major Machines (Individual Pages Required)
 Each major machine needs its own detailed page at: `/equipment/{category}/{machine-name}/`
 **CNC Machines:**
 - CNC Mill (3-Axis) - ✅ Created
 - CNC Router
 - CNC Lathe
 **3D Printing:**
 - FDM Printer (Large)
 - SLA Printer
 **Laser Cutting:**
 - Laser Cutter
 **Electronics:**
 - Pick & Place Machine
 - Reflow Oven
 - Hot Plate
 **Soldering:**
 - Soldering Stations (multiple stations documented together)
 ### Hand Tools & General Equipment
 Hand tools are documented by **area** and **category**. Each area should have a comprehensive hand tools page.
 **Organization Structure:**
 ```
 /equipment/measuring/01.hand-tools/    - Dirty Fabrication hand tools
 /equipment/electronics/01.hand-tools/  - EE Garage hand tools
 /equipment/measuring/02.hand-tools/  - Clean Fabrication hand tools
 ```
 **Categories to Document:**
 - Cutting Tools (saws, snips, cutters)
 - Wrenches & Sockets
 - Pliers & Gripping Tools
 - Measuring Tools (calipers, micrometers, gauges)
 - Hammers & Striking Tools
 - Clamping & Holding
 - Power Tools (cordless)
 - Abrasives & Finishing
 ## Taxonomy System
 The site uses Grav's taxonomy system for flexible categorization.
 **Taxonomy Configuration:** `/config/www/user/config/taxonomies.yaml`
 ### Equipment Categories (Type of Equipment)
 ```
 category:
  cnc: CNC Machines
  3d-printing: 3D Printing
  laser-cutting: Laser Cutting
  electronics: Electronics
  welding: Welding & Fabrication
  soldering: Soldering Stations
  measuring: Measuring Tools
  cutting: Cutting Tools
  grinding: Grinding Tools
  drilling: Drilling Tools
 ```
 ### Physical Areas (Location)
 ```
 area:
  ee-garage: EE Garage
  dirty-fabrication: Dirty Fabrication
  clean-fabrication: Clean Fabrication
  kitchen: Kitchen
  backyard: Backyard
  garage: Garage
  shed: Shed
  upstairs: Upstairs Room
 ```
 ### Equipment Status
 ```
 status:
  available: Available
  maintenance: Under Maintenance
  training-required: Training Required
 ```
 ## Page Structure & Templates
 ### Major Machine Page Template
 Each major machine page should include:
 **Front Matter:**
 ```yaml
 ---
 title: Machine Name
 menu: Short Menu Name
 taxonomy:
    category: [category-name]
    area: [area-name]
 hourly_rate: XX
 daily_rate: XXX
 ---
 ```
 **Content Sections:**
 1. Machine Title & Tagline
 2. Equipment Specifications (table)
 3. Capabilities (table)
 4. Materials We Machine
 5. Machining Services
 6. Pricing
 7. Design & File Requirements
 8. Training Requirements
 9. Sample Projects
 10. Booking Information
 11. Safety Requirements
 12. Location & Access
 13. FAQ
 **Example:** `/config/www/user/pages/04.equipment/01.cnc/01.cnc-mill/default.md`
 ### Area Page Template
 Each area page should include:
 **Front Matter:**
 ```yaml
 ---
 title: Area Name
 menu: Menu Name
 taxonomy:
    area: [area-name]
 ---
 ```
 **Content Sections:**
 1. Area Title & Tagline
 2. Area Overview (table with size, capacity, location)
 3. Equipment & Tools (links to categories)
 4. Location Breakdown (if multiple sub-locations)
 5. Equipment Categories (with links)
 6. Capabilities by Location
 7. Safety Features
 8. Access & Booking
 9. Rules & Guidelines
 10. Nearby Areas
 11. Equipment Quick Reference (inventory table)
 **Examples:**
 - `/config/www/user/pages/05.areas/01.ee-garage/default.md`
 - `/config/www/user/pages/05.areas/02.dirty-fabrication/default.md`
 ### Hand Tools Page Template
 Hand tools pages by area should include:
 **Front Matter:**
 ```yaml
 ---
 title: Hand Tools & General Equipment
 menu: Hand Tools
 taxonomy:
    area: [area-name]
 ---
 ```
 **Content Sections:**
 1. Page Title
 2. Tool Categories (with subsection links)
 3. Detailed Category Sections (with tables)
 4. Tool Locations (where tools are stored)
 5. Tool Usage Guidelines
 6. Safety
 7. Tool Inventory (table with quantity, location, notes)
 8. Missing/Needs Attention
 9. Suggestions & Feedback
 10. Related Equipment
 **Example:** `/config/www/user/pages/04.equipment/07.measuring/01.hand-tools/default.md`
 ## Navigation Structure
 ### Main Pages
 - `/` - Home
 - `/resources` - Resources & Pricing
 - `/contact` - Contact Us
 - `/equipment` - Equipment & Areas (landing)
 - `/areas` - Areas by Location (landing)
 ### Equipment Pages
 - `/equipment/cnc` - CNC Machines category
 - `/equipment/3d-printing` - 3D Printing category
 - `/equipment/laser-cutting` - Laser Cutting category
 - `/equipment/electronics` - Electronics category
 - `/equipment/welding` - Welding category
 - `/equipment/soldering` - Soldering Stations category
 - `/equipment/measuring` - Measuring Tools category
 ### Area Pages
 - `/areas/ee-garage` - EE Garage area details
 - `/areas/dirty-fabrication` - Dirty Fabrication area details
 - `/areas/clean-fabrication` - Clean Fabrication area details
 - `/areas/kitchen` - Kitchen area details
 ## Content Guidelines
 ### Naming Conventions
 **Page Directories:**
 - Equipment categories: `04.equipment/01.{category-name}/`
 - Individual machines: `04.equipment/01.{category-name}/01.{machine-name}/`
 - Areas: `05.areas/01.{area-name}/`
 - Hand tools: `04.equipment/07.measuring/01.{area}-hand-tools/`
 **File Names:**
 - Use lowercase with hyphens
 - Example: `cnc-mill`, `dirty-fabrication`, `hand-tools`
 ### Formatting
 **Tables:** Use Markdown tables for specifications, pricing, and inventory
 **Links:** Use `=> [Link Text](/path)` format for internal navigation
 **Sections:** Use H2 (##) for major sections, H3 (###) for subsections
 **Callouts:** Use `!! text` for important callouts
 ### Tone & Style
 **Audience:** High-paying clients ($100+/hour)
 **Tone:** Professional yet approachable
 **Voice:** Expert, helpful, premium service
 **Keywords:** Precision, professional, premium, excellence, quality
 **Writing Guidelines:**
 - Use active voice ("We provide", "Our equipment offers")
 - Be specific with specifications
 - Include safety information prominently
 - Emphasize quality and professionalism
 - Provide practical booking information
 ## Git Workflow
 ### Conventional Commits
 Use conventional commit format:
 ```
 {type}({scope}): {description}
 {optional body}
 💘 Generated with Crush
 Assisted-by: GLM-4.7 via Crush <crush@charm.land>
 ```
 **Types:**
 - `feat` - New feature or page
 - `fix` - Bug fix or correction
 - `docs` - Documentation only changes
 - `style` - Formatting, code style
 - `refactor` - Code refactoring
 - `chore` - Maintenance, dependencies, config
 **Scopes:**
 - `config` - Configuration files
 - `equipment` - Equipment pages and categories
 - `areas` - Area pages
 - `theme` - Theme and styling
 - `content` - General content changes
 - `docker` - Docker configuration
 ### Commit Frequency
 **Atomic Commits:** Each commit should be focused on a single, self-contained change
 **Examples of atomic commits:**
 - Add single machine page
 - Update taxonomy configuration
 - Fix broken link
 - Add single hand tools category
 - Update pricing table
 **Push Frequency:** Push after every 2-3 commits to ensure work is backed up
 ### Commit Message Examples
 Good:
 ```
 feat(equipment): add CNC Router detailed page
 - Complete specifications table
 - Include pricing and training requirements
 - Add booking information and safety protocols
 - Link from CNC category page
 💘 Generated with Crush
 ```
 Bad:
 ```
 added some pages and fixed some stuff
 ```
 ## Docker & Environment
 ### Container Management
 **Image:** `linuxserver/grav:1.7.49`
 **Version:** Must match server (1.7.49.5-ls234)
 **Port:** 5001 (mapped from host)
 **Volume:** `/config` mapped from host
 **Commands:**
 ```bash
 # Start container
 docker compose up -d
 # Stop container
 docker compose down
 # Restart container
 docker restart stlp-grav
 # View logs
 docker logs stlp-grav
 # Clear cache
 docker exec stlp-grav rm -rf /config/www/user/cache/*
 # Execute command in container
 docker exec stlp-grav <command>
 ```
 ### File Locations
 **Local Development:** `/home/charles/Projects/STLPWebsite/config/www/`
 **Container Path:** `/config/www/`
 **Pages:** `/config/www/user/pages/`
 **Config:** `/config/www/user/config/`
 **Theme:** `/config/www/user/themes/quark/`
 ### Testing After Changes
 1. Clear cache: `docker exec stlp-grav rm -rf /config/www/user/cache/*`
 2. Check container: `docker ps | grep stlp-grav`
 3. Test in browser: http://localhost:5001
 4. Commit changes
 5. Push to remote
 ## Work Priorities
 ### High Priority (Complete First)
 1. ✅ CNC Mill detailed page
 2. ✅ EE Garage area page
 3. ✅ Dirty Fabrication area page
 4. ✅ Hand tools documentation template
 5. Clean Fabrication area page
 6. Kitchen area page
 7. Areas index page
 ### Medium Priority
 8. Remaining CNC machine pages (Router, Lathe)
 9. 3D Printing category and pages
 10. Electronics category and pages
 11. Welding category and pages
 12. Soldering category and pages
 ### Low Priority (As Needed)
 13. Clean Fabrication hand tools page
 14. Kitchen equipment page
 15. Laser Cutting category and page
 16. Additional detailed machine pages
 ## Quality Checklist
 Before committing, verify:
 ### Content Quality
 - [ ] Page follows template structure
 - [ ] All specifications are complete
 - [ ] Pricing is accurate and consistent
 - [ ] Safety information is included
 - [ ] Booking information is clear
 - [ ] Links are correct and working
 - [ ] Tone is professional and premium
 ### Technical Quality
 - [ ] YAML front matter is valid
 - [ ] Taxonomy tags are correct
 - [ ] File follows naming conventions
 - [ ] Markdown formatting is correct
 - [ ] No broken internal links
 ### Git Quality
 - [ ] Commit is atomic (single purpose)
 - [ ] Commit message follows conventional format
 - [ ] Commit message describes what and why
 - [ ] No uncommitted config/log files included
 ## Support Resources
 ### Project Files
 - Docker Compose: `/docker-compose.yml`
 - Taxonomy Config: `/config/www/user/config/taxonomies.yaml`
 - Site Config: `/config/www/user/config/site.yaml`
 - System Config: `/config/www/user/config/system.yaml`
 ### Theme Files
 - Custom CSS: `/config/www/user/themes/quark/css/custom.css`
 - Logo: `/config/www/user/themes/quark/images/logo.svg`
 - Logo Template: `/config/www/user/themes/quark/templates/partials/logo.html.twig`
 ### Reference Pages
 - CNC Mill template: `/config/www/user/pages/04.equipment/01.cnc/01.cnc-mill/default.md`
 - EE Garage template: `/config/www/user/pages/05.areas/01.ee-garage/default.md`
 - Dirty Fabrication template: `/config/www/user/pages/05.areas/02.dirty-fabrication/default.md`
 - Hand Tools template: `/config/www/user/pages/04.equipment/07.measuring/01.hand-tools/default.md`
 ## Notes
 ### Business Rules
 - All equipment is rented by the hour
 - Daily rates available for extended use
 - Memberships offer discounts and priority access
 - Training required for major equipment
 - Safety orientation required for all users
 - Professional, premium service expected
 ### Design Principles
 - Clean, modern, professional appearance
 - Easy navigation by type or location
 - Comprehensive documentation for all equipment
 - Clear pricing and booking information
 - Safety emphasized throughout
 ### Future Enhancements
 - Online booking system
 - Equipment availability calendar
 - Member portal
 - Equipment reservation system
 - Real-time availability status