30790-vm/GEMINI.md

Here’s a drop-in gemini.md for the LAMP golden machine. Put it in the project root (i.e., WORKSPACE_ROOT, which is also the Apache DocumentRoot). It speaks directly to Gemini CLI and sets guardrails for edits + chat output.

# Gemini — Working Instructions (Flatlogic LAMP VM)

You are **Gemini CLI** running inside a **Flatlogic Dev VM** on the **LAMP golden image**.
Your job is to **edit files in-place** under the current working directory and keep the app running and browsable.

---

## Where you are (facts)

- **CWD / Project root:** this folder (the Flatlogic `WORKSPACE_ROOT`).  
  - It is also the **Apache DocumentRoot**.  
  - `index.php` lives here and is served as `/`.
- **Stack:** Apache 2.4+ and PHP 8.x (classic LAMP). No framework by default.
- **Network:** The VM exposes HTTP(S) via a **Cloudflare Tunnel**. Locally it’s served on `http://localhost:80`.
- **Privileges:** You are a regular user. Do **not** attempt system package changes or service reconfiguration.
- **VCS:** A Git repo may be present. You can modify tracked files; commits/pushes are triggered by platform commands (not by you directly).

---

## What to do (capabilities & constraints)

- **Edit files directly** in this folder tree. Prefer small, safe changes.
- **Stay within the project root.** Do not write outside this directory.
- **Do not change Apache/system configs** or assume root access.
- **Keep the app immediately browsable.** After changes, `/` must still load without PHP errors.
- **No database is guaranteed.** If you need persistence, propose **file-based** storage first. If MySQL is explicitly requested later, ask for credentials.
- **Composer/frameworks:** Avoid adding unless asked. Stick to vanilla PHP unless requirements say otherwise.

---

## How Flatlogic Chat sees you

- Your **stdout/stderr is streamed** to a human via Flatlogic Cloud.
- Keep output **concise and actionable**:
  1. Start with a one-line **Plan**.
  2. Perform changes (write files).
  3. Print a **Summary** of what changed.
  4. End with **Next** (a yes/no or options).
- If an operation fails, print a short **Error** line and what you’ll try next.

**Output template (guideline):**

Plan: <1–2 short bullets>

Changed:

• :
• :

Notes:

Next:

> You generally do **not** need to print full file contents. When useful, show **small excerpts only**.

---

## File editing rules (PHP)

- **index.php must keep working.** If you introduce new includes, ensure relative paths exist.
- **Security:** never echo raw user input; use `htmlspecialchars` for HTML contexts.
- **Health endpoint:** ensure `/healthz` returns `ok` with HTTP 200 (lightweight, no PHP warnings).
  - Implement as `healthz.php` or route via `index.php`—your choice, but keep it simple.
- **Configuration:** if you create config, use a single `config.php` loaded by `index.php`.
- **Error handling:** avoid `display_errors` changes. Use defensive checks and small try/catch blocks.

---

## Testing after changes

- Print a quick checklist the human can run:
  - “Open `/`—should show …”
  - “Open `/healthz`—should return ‘ok’”
  - Mention any new endpoints you add.

---

## Git & deploy (how your work is shipped)

- The platform will run `git pull`, `git commit_push`, and `server.restart` when appropriate.
- **You don’t run git here.** Just make sure your changes are saved to disk.

**Commit message convention** (for your summaries so humans can reuse):
- `feat: ...` user-visible features
- `fix: ...` bug fix
- `chore: ...` small housekeeping
- `docs: ...` text-only updates

---

## Do not do

- Don’t install system packages or restart Apache yourself.
- Don’t write outside the project root.
- Don’t introduce heavy dependencies without asking.
- Don’t leak secrets or create random credentials.

---

## Small starter tasks you can do safely

1) **Add a health check**
- Create `healthz.php` with plain `ok`.
- Optionally link from `index.php` footer for quick access.

2) **Improve the landing page**
- In `index.php`, add a minimal header/footer, and a quick environment box:
  - PHP version, current time, and a link to `/healthz`.

3) **Basic contact form (no DB)**
- Add `contact.php` with a POST form and server-side validation.
- On submit, write a sanitized line to `data/contact.log` (create folder if missing).

(Only perform these if asked; otherwise wait for explicit prompts.)

---

## Example: Health check (what good output looks like)

Plan: add /healthz endpoint and link it from index.php

Changed:

• healthz.php: returns 'ok' with HTTP 200
• index.php: footer link to /healthz

Notes:

• Tested locally via PHP include; endpoint is static and safe.

Next: Proceed to add a minimal env box on the homepage?

---

## Telemetry note

- Your token usage and latencies are measured. Keep prompts/responses compact.
- Prefer **editing files** over dumping large code blocks into chat.

---

**That’s it.** Operate inside this folder, keep `/` working, and narrate succinctly in Flatlogic Chat.