# AGENTS.md — working on opendrive (opendrive.fun)

Read this before changing anything. Details live in `README.md`.

## Stack

- **Frontend:** React 19 + Vite 6 + TypeScript + Tailwind CSS 4. Multi-page build: `index`, `home`, `login`,
  `signup`, `legal`, `app` (`*.html` at the repo root, code in `src/`, static assets and locales in `public/`).
  The frontend is **always React** — do not port it to another framework.
- **API:** PHP 8.5 (≥ 8.1 supported) + MySQL/MariaDB, front controller `api/index.php`, config in `api/lib/config.php`,
  dependencies via Composer (`api/composer.json`, lock committed, `api/vendor/` ignored).
- **i18n:** 28 locales in `public/i18n/locales/`; English is the source.

## Branch model

- `develop` — main development branch. Every push/merge to `develop` **auto-deploys to https://dev.opendrive.fun**
  (`.github/workflows/dev-deploy.yml`). Work on feature branches and open PRs into `develop`.
- Merge-only exception: the dev deploy job skips push commits containing `[merge-only]`. Keep this marker in the final squash commit title, pass normal CI and verify the deploy job was skipped. Never dispatch a deploy for merge-only work.
- `main` — **production** (https://opendrive.fun). Deployed automatically by `.github/workflows/prod-deploy.yml` on every push to `main` except pushes that only touch `**/*.md` or `docs/**`
  (manual workflow_dispatch also works, input `confirm=DEPLOY-PRODUCTION`). Runs queue and never overlap; merge to `main` once per release so only one production deploy is in flight. Production deployment is permitted: finalized work → `develop` → `main` → incremental production deploy → verify (owner policy 2026-11-17, `/etc/grupo-open/PRODUCTION-DEPLOY-POLICY.md`).

## Build and test locally

```bash
npm ci                     # frontend deps (lockfile)
(cd api && composer install)
npm run build              # Vite build -> dist/
npm run check              # typecheck + unit tests + locale + data checks
npm run lint:php           # php -l on all first-party PHP
npm run test:php           # PHP unit tests
npm run check:workflows    # workflow policy (self-hosted runners, pinned actions, secrets only in deploy workflows)
node scripts/ci/secret-scan.mjs dist
npm run test:integration   # real PHP + disposable local MariaDB (see README "Local setup")
npm run test:e2e           # browser walkthroughs against the built site
```

`npm run dev` serves the frontend on 127.0.0.1:5173 and proxies `/api` to a local PHP server (README "Local setup").

## Configuration and migrations

- API configuration: process environment > `api/config.local.php` (never committed) > safe defaults. See
  `env.example` and `api/config.local.php.example`. Required on servers: `APP_PUBLIC_ORIGIN`, `DB_*`, and
  `STORAGE_DIR` (private documents, **outside** the web root).
- Schema changes are migrations in `api/migrations/NNNN_name.php`; apply with `php api/cli/migrate.php`
  (idempotent; `--seed-demo` only for local/dev, refused when `APP_ENV=production`). Migrations should only add
  tables/columns so the previous release keeps working.

## Deploy flow

1. Merge to `develop` → `Dev deploy` workflow on self-hosted runners (`[self-hosted, deploy]`): `npm ci`,
   `npm run build`, `composer install --no-dev` in `api/`, tar `dist/` + `api/` + `public/` (the API reads `public/*.json`), stream it over SSH to
   `opendrive-deploy-dev@51.77.85.58`.
2. The server's forced command `/usr/local/libexec/opendrive-receive` unpacks into `/opt/opendrive-dev/releases/<sha>`,
   links `api/config.local.php` and `uploads/` from `/opt/opendrive-dev/shared/`, writes `dist/opendrive-release.txt`,
   then runs `opendrive-migrate <sha>`: when the new release has pending migrations it writes a verified backup to
   `/var/backups/opendrive/opendrive_<env>-pre-<sha12>-<UTC>.sql.gz` and applies them as the env's PHP user
   (log: `/var/log/opendrive/migrate-<env>.log`). A failed backup or migration keeps the previous release live.
   Only then it flips `current` atomically, reloads `opendrive-php@dev` and restarts the env's sync/media workers.
3. The workflow verifies `https://dev.opendrive.fun/opendrive-release.txt` equals the pushed SHA.
4. One deployment per environment: runs queue (never cancelled mid-deploy) and a run whose commit is no longer the
   branch head skips its deploy, so back-to-back merges (e.g. `release/*` PRs to `main`) cannot roll prod back.

The receiver, migration helper, their sudoers drop-in and the worker units are versioned in `deploy/server/`;
install or check drift with `scripts/deploy/install-server.sh [--check] [--workers dev|prod|all|none]`.

Production is the same pipeline with `prod` in every name, triggered by pushes to `main` (see Branch model).
Web server: nginx on the host. Its OpenDrive config is versioned in `deploy/nginx/` (see `deploy/nginx/README.md`); change it there and
install with `scripts/deploy/install-nginx.sh` (`--check` reports drift). `.htaccess` files only matter for Apache/local setups.
Both deploy workflows finish with `scripts/smoke/post-deploy.mjs` (release SHA, assets, `/api/health`, `/healthz`, public API).

## Rules

- **No secrets in git** — no passwords, keys, tokens, `.env*`, `config.local.php` or credential files in commits,
  logs, screenshots or PR text. Deploy keys live only in GitHub secrets; server config only on the server.
- **No scheduled backups** (owner's choice) — do not add backup jobs or snapshot timers. The only dumps are the
  automatic pre-migration backups the deploy receiver takes (owner policy: backups before migrations).
- **Frontend always React.**
- Self-hosted runners only; actions pinned to commit SHAs; only the deploy workflows may use secrets.
- Production deployment is permitted: finalized work → `develop` → `main` → incremental production deploy → verify (owner policy 2026-11-17, `/etc/grupo-open/PRODUCTION-DEPLOY-POLICY.md`).

## UI rules (Miguel, strict)

The UI must be minimal, intuitive and super easy to use. Avoid text; when it can't be avoided, keep it very brief, using common words (book, rent, list, show, hide, pay, trips, messages, profile, search) and no technical terms. Make features easy to find, actions easy to understand and results easy to verify. Use clearly labelled controls, familiar icons, relevant visuals and accurate status indicators. Remove unnecessary text, clutter, confusing elements and redundant information without losing clarity. Always put visuals before text: use images, official logos, icons and brand assets (for example car makes, payment methods and sign-in providers) and diagrams wherever they communicate better. All screens and states must be responsive, consistent, functional and production-ready on desktop and mobile. Keep the design system where it is sound. Fix invisible text, low contrast, broken QR rendering, overflow, clipping, confusing states and unusable mobile controls.

In review, audit every page on desktop (1280px) and mobile (390px) for these points: text overflow, contrast, tap targets of at least 44px, text that could be an icon, and copy that is too long. Fix what you find before you merge.

### Full mandatory UI rules (verbatim from /workspace/UI-RULES.md)

#### UI rules (Miguel, 22 Oct 2026, mandatory for every app and every prompt)

UI should be minimal, minimalistic, intuitive and super easy to use. Avoid using text, and when unavoidable, keep it very brief and clear, use minimal common wording like "buy", "sell", "list", "delist", "show", "hide", "mint", "progress", "token", "index", "protocol", "trade", "wallet", "connect", etc, and avoid technical terms. Make features easy to find, actions easy to understand, and results easy to verify. Use clearly labeled controls, familiar icons, relevant visuals, and accurate status indicators. Remove unnecessary text, clutter, confusing elements, and redundant information without sacrificing clarity or usability.

Ensure all affected screens and states are responsive, consistent, functional, and production-ready on desktop and mobile.

Preserve the established design system where sound. Correct invisible text, low contrast, broken QR rendering, overflow, clipping, confusing states, and unusable mobile controls without introducing unrelated redesign.

Always prioritize visuals over text. Use images, especially those featuring official logos, icons, branding, or other authoritative visual assets, and diagrams wherever they can communicate the information more clearly and effectively than text alone.

## Backlog

The feature queue is `docs/BACKLOG.md`. Its P1 items are the top-priority next features and come first in every Grow
cycle until they are merged into develop.

## Deployment operating rule (Miguel, 18 Nov 2026)

"A requested application fix includes implementation, immediate development publication, focused validation, production deployment, and verification of the live result. Repair deployment infrastructure as part of the task. Do not stop at development or request renewed approval for routine releases already covered by the user’s authorization. Use sequential integration and minimal tests covering the complete release impact. Never mark a production fix complete without production evidence."

"Fixed in dev" is intermediate; a production fix is done only when the live revision matches the release and the changed workflow works on the public URL (mobile and desktop). Repair a missing publisher, runner, credential reference or host key as part of the task (repeatable provisioning; host keys verified from an authenticated source and pinned, never by asking Miguel, never by disabling verification). Explicit per-request `[merge-only]` / `[no deploy]` markers, auth, secrets, health checks and pre-migration backups stay. Canonical: `/etc/grupo-open/PRODUCTION-DEPLOY-POLICY.md` (`open-group-ai/openbot-master` `policies/`).
