STLPWebsite/STARTHERE.md

🚀 Gemini Agent Task: Grav CMS + Dolibarr Prospect Integration (v1.0)

You are an autonomous software development agent operating inside the Gemini CLI environment. Your task is to deliver a clean, containerized integration between Grav CMS and Dolibarr, enabling email capture on the website and automatic creation of prospect records in Dolibarr.

This is a v1.0 implementation. Keep it simple, modular, and extensible. Do not install anything on the host system.

---

🧱 Environment Constraints

• ✅ All operations must occur inside Docker containers.
• ❌ Do not use apt, yum, brew, or any host-level package manager.
• ✅ Use docker-compose to orchestrate services.
• ✅ Use named volumes and health checks.
• ✅ Log all actions to logs/integration.log.

---

🌐 Project Context

• Website: StartingLineProductions.com
• CMS: Grav (PHP-based, flat-file)
• CRM: Dolibarr (self-hosted via Cloudron)
• Goal: Capture email addresses via a form on the Grav site and push them into Dolibarr as new prospects.

---

🧩 Functional Requirements

• Create a form in Grav that collects:

  • Email (required)
  • First name (optional)
  • Consent checkbox (required for GDPR)

• On submission:

  • Validate input
  • Send data to Dolibarr via REST API (/thirdparties)
  • Create a new prospect with status “Draft” or “To Qualify”
  • Log success/failure with timestamp

---

🔐 Dolibarr API Integration

• Authenticate using API token (stored in containerized config file)
• Required fields:
  • email
  • name (fallback to “Unknown”)
  • status = 1 (prospect)

---

🛠️ Deliverables

• docker-compose.yml with Grav and Dolibarr services
• user/plugins/prospectform/ Grav plugin or override
• README.md with setup and usage instructions
• integration.log with sample entries
• config.yaml with API token placeholder
• form.html.twig for frontend form

---

✅ Do vs. ❌ Don’t

✅ Do	❌ Don’t
✅ Use containerized Grav and Dolibarr images	❌ Install PHP or Grav on the host
✅ Use documented Dolibarr API endpoints	❌ Modify Dolibarr core or database directly
✅ Log errors and retry up to 3 times	❌ Silently fail or discard submissions
✅ Keep code modular and extensible	❌ Hardcode credentials or logic

---

🧭 Agent Behavior

• Confirm understanding before starting
• Ask for clarification if API access fails or endpoint is ambiguous
• Propose fallback options if Dolibarr is unreachable
• Document any assumptions in README.md

---

📦 Future Enhancements (v1.1+)

• Add CAPTCHA or spam protection
• Sync additional fields (phone, company, etc.)
• Enable double opt-in email confirmation
• Add dashboard widget in Dolibarr for new signups

---

Begin with the Grav form and Dolibarr API integration. Keep it lean, reliable, and containerized.