158 lines
6.8 KiB
Markdown
158 lines
6.8 KiB
Markdown
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.
|
||
|
||
```markdown
|
||
# 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`.
|
||
- **Database:** Local MariaDB/MySQL is available on `127.0.0.1:3306`. App credentials are stored in `db/config.php` (loaded by the app). Use PDO (MySQL) for all persistence.
|
||
- **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.
|
||
- **Use the database for persistence.** Do not store app data in JSON/flat files. Always use MariaDB/MySQL via PDO with prepared statements. Credentials are provided in `db/config.php`.
|
||
- **Composer/frameworks:** Avoid adding unless asked. Stick to vanilla PHP unless requirements say otherwise.
|
||
|
||
---
|
||
## Database usage policy
|
||
|
||
- Connectivity: include `db/config.php` and use the provided `db()` PDO helper (or create one if missing) for all queries.
|
||
- Prepared statements only: use `PDO::prepare` and `bindParam/ bindValue`; never concatenate user input into SQL.
|
||
- DDL (schema changes):
|
||
- Write idempotent SQL (e.g., `CREATE TABLE IF NOT EXISTS`, check for column existence before `ALTER`).
|
||
- Prefer placing DDL in `db/migrations/*.sql` (one task per file) with clear comments. If adding a lightweight migrator script, keep it simple and safe.
|
||
- Prohibited: destructive operations like `DROP DATABASE`, `DROP TABLE`, mass `TRUNCATE`, or irreversible schema changes without explicit instruction.
|
||
|
||
---
|
||
|
||
## Safety & Boundaries
|
||
|
||
- Scope: operate strictly inside `WORKSPACE_ROOT` (this directory). Never use absolute paths or `..` in any path or command.
|
||
- Dotfiles: never read, write, rename, or delete any hidden files or folders (`**/.*`), including `.htaccess`, `.git/**`, `.gemini/**`, `.env*`, `.vscode/**`, `.idea/**`, `.github/**`, `.DS_Store`.
|
||
- System/service folders: do not modify `.git/**`, `.gemini/**`, `node_modules/**`, `vendor/**`, `tmp/**`, `storage/**`.
|
||
- Write operations: only targeted, minimal edits to application code. Do not perform mass refactors, bulk renames, file moves, or deletions without explicit instruction.
|
||
- Shell commands: allowed only for safe, read-only inspection within this directory (e.g., `ls`, `cat`, `head`, `grep`, `sed -n`, `php -v`).
|
||
- Forbidden: `rm`, `mv`, `cp -r`, `chmod`, `chown`, `ln`, `find -delete`, `xargs rm`, in-place edits (`sed -i`, `perl -pi`, `awk -i inplace`), redirects/append (`>`, `>>`, `tee -a`), archive extractors writing to disk, network downloads to files (`curl|wget > file`), any `git` commands, process control, `sudo`.
|
||
- All command paths must be relative to the current directory and must not reference `..` or absolute paths.
|
||
- If a requested change violates these rules (touches dotfiles/service folders or escapes the workspace), refuse and ask for confirmation/alternative.
|
||
|
||
Examples
|
||
- Allowed: `cat includes/helpers.php`, `rg -n "function enroll" ./`, `sed -n '1,120p' courses.php`.
|
||
- Forbidden: `rm -rf .*`, `mv .htaccess .htaccess.bak`, `cp -r ../* ./`, `git init`, `curl URL > file.php`, `chmod -R 777 .`.
|
||
|
||
---
|
||
|
||
## 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:
|
||
|
||
* <path>: <very short description>
|
||
* <path>: <very short description>
|
||
|
||
Notes:
|
||
|
||
* <any caveat or test instruction>
|
||
|
||
Next: <question or options>
|
||
|
||
```
|
||
|
||
> 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.
|
||
- **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 …”
|
||
- 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) **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`.
|
||
|
||
2) **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.)
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## 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.
|
||
```
|