semillero-special-hotel/docs/AI_DEVELOPER_WORKSTATION.md

AI & Developer Workstation Guide

Variable Remuneration, Compensation, and Commissions System - Hoteles Estelar

---

This document outlines the environment configurations (Development vs. Production), active API keys, and recommended AI integration tools (like Model Context Protocol servers) designed to optimize this workspace for AI agents and human developers alike.

---

1. Environment Configurations (.env Blueprints)

The Next.js application separates environment secrets between local active development, development containers, and production servers. All credentials reside in a centralized .env file at the project root.

1.1. Dual-Stack Configuration Layout (.env)

This file configs connection parameters for both production (app-prod) and development (app-dev) containers.

# -----------------------------------------------------------------------------
# Database Setup (Fallback / Local Development)
# -----------------------------------------------------------------------------
DATABASE_URL="postgresql://special_hotel_user:***@pg.gaboggamer.online/special_hotel_dev?schema=public"

# -----------------------------------------------------------------------------
# Production Stack Environment Variables (for Docker Compose app-prod)
# -----------------------------------------------------------------------------
# Connection string pointing to the production PostgreSQL instance
DATABASE_URL_PROD="postgresql://special_hotel_user:***@pg.gaboggamer.online/special_hotel?schema=public"

# Production domain resolved by the Caddy reverse proxy
NEXT_PUBLIC_APP_URL="https://hotels.gaboggamer.online"

# Secret token used to sign NextAuth / custom session JWTs in production
NEXTAUTH_SECRET="0qqPRY4NIbCEFag33Q6EB1ea7dUQR1J6Z8h4NogrgCg="

# Production n8n calculation webhook endpoint
N8N_WEBHOOK_URL="https://n8n.gaboggamer.online/webhook/calculate-commissions"

# Token to authorize and verify n8n webhook payload signatures in production
N8N_WEBHOOK_SECRET="Ecjb2s33tHJppNBDJ/DxXEjHWKow8bNWmsQrk1sQKyQ="

# Internal container networking URL for production app mapping
APP_PROD_INTERNAL_URL="http://special-hotel-prod:3000"

# -----------------------------------------------------------------------------
# Development Stack Environment Variables (for Docker Compose app-dev)
# -----------------------------------------------------------------------------
# Connection string pointing to the development PostgreSQL instance
DATABASE_URL_DEV="postgresql://special_hotel_user:***@pg.gaboggamer.online/special_hotel_dev?schema=public"

# Dedicated connection string for the isolated test/sandbox database
TEST_DATABASE_URL="postgresql://special_hotel_user:***@pg.gaboggamer.online/special_hotel_test?schema=public"

# Local host address for development
NEXT_PUBLIC_APP_URL_DEV="http://localhost:3001"

# JWT session signing key for development
NEXTAUTH_SECRET_DEV="TdD2xx0rZYCGkYxFFB7y9Sm8L+HGyXaXInqB9lYLJsk="

# Sandbox n8n testing webhook endpoint
N8N_TEST_WEBHOOK_URL="https://n8n.gaboggamer.online/webhook-test/calculate-commissions"

# Signature token to authorize development webhook payloads
N8N_WEBHOOK_SECRET_DEV="qUHuPqPjA65psdtwQU7zgp/DVkvd1xXk2WP/vzbnEdc="

# Internal container networking URL for development app mapping
APP_DEV_INTERNAL_URL="http://special-hotel-dev:3000"

---

2. Optimizing the Workspace for the Antigravity Agent (agy)

To make this codebase highly friendly for the Antigravity agent (agy), you can configure the following Model Context Protocol (MCP) servers. Once registered in the agent's active configuration, agy is equipped with specialized tools to inspect database schemas, execute and debug n8n workflows, manage git versions, and run automated browser checks.

2.1. Recommended MCP Servers for agy

A. n8n MCP Server (n8n)

Exposes tools to read, execute, and write workflows directly on the n8n canvas.

• Use Case: Allows agy to trigger calculation runs, inspect failing nodes on the canvas, check webhook logs, and modify workflows dynamically.
• Harness Registration:

  "n8n": {
    "command": "npx",
    "args": ["-y", "n8n-mcp"],
    "env": {
      "N8N_API_KEY": "your_n8n_api_key_here",
      "N8N_URL": "https://n8n.gaboggamer.online"
    }
  }
  

B. Prisma Postgres MCP Server (prisma-postgres)

Exposes tools allowing agy to interact with the database using type-safe schemas.

• Use Case: Allows agy to run schema checks, dry-run validations, and automatically inspect database tables during development.
• Harness Registration:

  "prisma-postgres": {
    "command": "npx",
    "args": ["-y", "@prisma/mcp"],
    "env": {
      "DATABASE_URL": "postgresql://special_hotel_user:***@pg.gaboggamer.online/special_hotel_dev?schema=public"
    }
  }
  

C. PostgreSQL MCP Server (postgres)

Provides raw PostgreSQL connection and querying tools.

• Use Case: Enables agy to query migration status, seed verification, and raw audit log verification directly.
• Harness Registration:

  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://special_hotel_user:***@pg.gaboggamer.online/special_hotel_dev"]
  }
  

D. Git MCP Server (git)

Provides local Git operations tools (clone, commit, diff, log, status).

• Use Case: Allows agy to review local branches, examine diffs of modified code files, and make structured, micro-commits during development.
• Harness Registration:

  "git": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-git", "/home/gabogg/Proyects/semillero-special-hotel"]
  }
  

E. Puppeteer MCP Server (puppeteer)

Exposes browser automation tools (take screenshots, click, type, fill forms).

• Use Case: Allows agy to start a headless browser, render our Next.js pages, and verify layout responsiveness and style details against the style guide without manual developer steps.
• Harness Registration:

  "puppeteer": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
  }
  

---

3. Hermes Agent Integration

Hermes Agent is the primary AI agent used for development on this project alongside Antigravity. It runs locally with full tool access and has been configured with project-specific skills, model routing, and automated testing.

3.1. Model Routing

Hermes uses a two-tier model setup to save cost while keeping heavy tasks powerful:

Mode	Model	Purpose
Main chat	deepseek-chat (fast, cheap)	Normal conversation, file edits, simple queries
Delegation	deepseek-v4-pro (powerful)	Complex debugging, code review, research, multi-step tasks

How it works: When Hermes needs to do something complex, it spawns a subagent via delegate_task. That subagent automatically gets the pro model. Your normal chat stays fast and cheap. Configured in ~/.hermes/config.yaml:

model:
  default: deepseek-chat
  provider: deepseek
delegation:
  model: deepseek-v4-pro
  provider: deepseek

To manually switch models mid-session: /model deepseek-v4-pro or /model deepseek-chat.

3.2. Project-Specific Hermes Skills

Five Hermes skills have been created for this project. They live at ~/.hermes/skills/software-development/ and are loaded on demand with skill_view(name="skill-name").

Skill	Load With	Purpose
hotel-project-map	Any session start	Full structural index: schema models, API routes, pages, deps, key libs
hotel-remuneration-orchestrator	Compensation/commission tasks	3-agent orchestrator (planner → calculator → QA auditor)
hotel-seeding-testing	Before tests or seeding	Exact commands for dev/test DB seed, individual tests, full suite
hotel-rls-verification	RLS / auth work	Role isolation testing scripts, manual verification queries
hotel-n8n-deployment	n8n workflow work	Bootstrap scripts, workflow JSONs, verification test

Recommended loading order for a new session:

hermes -s hotel-project-map,hotel-remuneration-orchestrator

Or inside an existing session:

/skill hotel-project-map
/skill hotel-remuneration-orchestrator

The skills contain exact commands, edge cases, and pitfalls so you (or the agent) don't rediscover them.

3.3. AGENTS.md

The file AGENTS.md at the project root is loaded automatically when Hermes works from this directory (either by launching from here or via a cron job with workdir set). It covers:

• Caveman Mode (Lite): Professional, precise, no filler
• RTK Command Proxying: All shell commands proxied through rtk when available to reduce token consumption
• MCP-specific guidelines: n8n silent execution, Forgejo PR integrity, Prisma schema validation
• Hermes skills reference: The 5 skills above with loading guidance
• Git Worktree Mode: hermes -w for parallel agent sessions without conflicts

3.4. MCP Server Configuration

The MCP servers configured for Hermes are stored in .agents/mcp_config.json. These are the same MCP servers from Section 2 but registered for Hermes. Currently configured:

• n8n → n8n-mcp package, pointed at n8n.gaboggamer.online
• Prisma → @prisma/mcp for type-safe DB introspection
• PostgreSQL → direct server-postgres for raw queries
• Git → mcp-git pointed at the project directory
• Puppeteer → @modelcontextprotocol/server-puppeteer for browser automation
• Forgejo → forgejo-mcp for PR and issue management on git.gaboggamer.online

3.5. Automatic Test Runner (Cron)

A Hermes cron job runs the full test suite every 6 hours:

• Job ID: dd941135c090
• Name: hotel-test-runner
• Schedule: Every 6 hours
• Workdir: /home/gabogg/Proyects/semillero-special-hotel (loads AGENTS.md)
• Skills loaded: hotel-seeding-testing, hotel-project-map
• Action: Seed test DB → rtk npm run test:all → report pass/fail

Check status:

hermes cron list

The cron job delivers results to the same conversation. If all tests pass, it summarises. If any fail, it gives error details.

3.6. .hermes/ Directory

The project contains a .hermes/ directory:

• .hermes/plans/ — stores Hermes plan files (used with the plan skill for executable markdown plans)

3.7. Quick Reference for Common Tasks

Task	Command
Seed dev DB	rtk npm run db:seed
Seed test DB	rtk npm run db:seed-test
Run all tests	rtk npm run test:all
Run RLS tests	rtk node prisma/test-rls.js
Run auth+RLS tests	rtk node prisma/test-auth-rls.js
Run UI tests	rtk npm run test:ui
Run n8n tests	rtk node prisma/test-n8n-real.js
Bootstrap n8n workflows	rtk node scripts/n8n-bootstrap.js
Load Hermes project map	/skill hotel-project-map in session
Load orchestrator	/skill hotel-remuneration-orchestrator
Load seeding/testing skill	/skill hotel-seeding-testing
Switch to pro model	/model deepseek-v4-pro
Start Hermes with skills	hermes -s hotel-project-map from project dir
Create a plan	Create .hermes/plans/<name>.md with actionable steps

---

4. Testing Procedures & Webhook Testing Flow

Testing must occur in complete isolation from production data. We achieve this by splitting execution paths using dedicated test hooks in both Next.js and n8n.

4.1. Testing Scripts Command List

Run these commands from the repository root using pnpm (or npm / yarn):

• Run Row-Level Security Tests:

  pnpm run test:rls
  

  Tests tenant read boundaries across admin, gerente, and colaborador roles, and verifies that update/delete actions on audit_logs are blocked.
• Run Auth & API RLS Integration Tests:

  pnpm run test:auth-rls
  

  Runs a Next.js instance on test port 3009 and asserts cookies, authorization blocks, and API-level data filtration.
• Run UI End-to-End Tests:

  pnpm run test:ui
  

  Compiles Next.js and runs automated Puppeteer scripts (test-phase3-ui.js, test-phase4-ui.js, test-phase5-ui.js) to verify pages, styles, translations, and modals.
• Run n8n Webhook Integration Tests:

  pnpm run test:n8n
  

  Fires sales validation and settlement calculation jobs directly at the n8n webhook test endpoint.
• Run All Tests:

  pnpm run test
  

4.2. n8n Testing Webhook Routing

All calculations triggered by test suites route to n8n via /webhook-test path segments:

1. Trigger: Test suite invokes n8n via POST ${process.env.N8N_TEST_WEBHOOK_URL}/calculate-commissions.
2. n8n Path Branching:
   • Within the n8n canvas, an IF node checks: {{ $json.headers["x-nginx-original-uri"] || $json.path }} contains webhook-test.
   • True: The n8n workspace connects to the database utilizing TEST_DATABASE_URL credentials. It pulls test sales/goals data and pushes calculations back to the Next.js dev API.
   • False: Connects to the main DATABASE_URL for production processing.

4.3. Manual Integration Setup

To sync and seed the testing database structure:

1. Spin up both databases.
2. Run database schema migrations on the test database:

   pnpm run db:seed-test
   

3. Run the development server or test suites.