bigpowers 2.83.4 → 2.84.0

package/.codex/skills/grill-me/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: grill-me
+model: sonnet
+description: "Interactive assumption-surfacing Q&A that stress-tests a plan through relentless questioning until every decision is resolved. Use when user wants to challenge a plan, validate decisions from conversation/context, or mentions \"grill me\". For doc-grounded variant, use grill-with-docs."
+---
+
+# Grill Me
+
+> **Use this vs grill-with-docs:** `grill-me` surfaces assumptions from the conversation and context alone — no documentation fetching. Use `grill-with-docs` (the doc-grounded variant) when the plan relies on a specific library or external API and every challenge must cite a real doc URL.
+
+Two modes. Default is **Design**. Switch to **Docs** by saying "grill me with docs" or when the plan relies on a specific library or external API.
+
+> **HARD GATE** — Do NOT accept a design until every hard decision has been stress-tested. "Seems right" is not a decision. Grilling must identify and resolve tensions before build begins.
+
+## Design mode (default)
+
+Interview relentlessly about every aspect of this plan until reaching shared understanding. Walk each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask one question at a time.
+
+If a question can be answered by exploring the codebase, explore it instead.
+
+## Docs mode
+
+Ground every challenge in real documentation — no assumption about a library's behavior goes unchecked. See [REFERENCE.md](REFERENCE.md) for the full process.
+
+Short form:
+1. List every external library, third-party API, and framework behavior relied upon.
+2. Fetch the actual docs for each (`WebFetch` the official API reference).
+3. Challenge each plan assumption against the real docs: correct method signature? right version? deprecated?
+4. Report confirmed ✓, corrected ✗ (with the real behavior), and uncertain → `spike-prototype`.
+5. Update the plan for each confirmed discrepancy.
+
+---
+
+# Docs Mode — Full Process
+
+Triggered by "grill me with docs" or when a plan depends on a specific library or external API.
+
+**Why this matters:** AI agents hallucinate API methods, argument orders, and behaviors. Every assumption about an external dependency must be validated against the actual docs before code is written.
+
+## Step 1 — Identify the dependencies
+
+From the plan or conversation, list:
+- Every external library being used
+- Every third-party API being called
+- Every framework behavior being relied upon
+
+Ask: "Which of these are you most confident about? Which are you less sure of?"
+
+## Step 2 — Fetch the relevant docs
+
+For each dependency, fetch the actual documentation:
+
+```
+WebFetch the official docs for [library/API]
+```
+
+Prioritize:
+- The API reference for the specific method being used
+- The changelog for the version in use (breaking changes)
+- Migration guides if upgrading from a previous version
+- Known gotchas / FAQ sections
+
+## Step 3 — Challenge each assumption
+
+For every assumption in the plan, find the corresponding doc section and ask:
+
+- "Does the real API actually work this way? Show me the doc."
+- "Is this method available in the version you're using?"
+- "Does this argument order match the actual signature?"
+- "Are there rate limits, quotas, or timeout behaviors that affect this design?"
+- "Is this marked as deprecated in the current version?"
+
+Ask one question at a time. For each challenge, cite the specific URL and section.
+
+## Step 4 — Surface hallucinations
+
+When an assumption doesn't match the docs:
+
+> "Your plan uses `library.doThing(a, b)` but the [docs](https://example.com/api-reference) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime."
+
+Document each discrepancy clearly.
+
+## Step 5 — Update the plan
+
+For each confirmed discrepancy, recommend a concrete fix:
+- Correct method signature
+- Correct argument order
+- Alternative approach that matches what the library actually supports
+- Whether a spike (`spike-prototype`) is needed to validate a remaining uncertainty
+
+## Step 6 — Sign off
+
+When all major assumptions have been validated against docs, report:
+- Which assumptions were confirmed ✓
+- Which were corrected ✗ + what the correct approach is
+- Which remain uncertain → recommend `spike-prototype`

package/.codex/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: grill-with-docs
+model: opus
+description: "Doc-grounded variant of grill-me — stress-tests plan assumptions by fetching and citing real library or API documentation. Every challenge must cite a real URL. Use when the plan depends on a specific library or external API."
+---
+
+# Grill With Docs
+
+> **Use this vs grill-me:** `grill-with-docs` is the doc-grounded variant of `grill-me`. Use it when the plan relies on external libraries or APIs and every challenge must be grounded in and cite a real documentation URL. Use `grill-me` for context-only assumption surfacing without fetching docs.
+
+> **HARD GATE** — Every challenge must cite a real documentation URL. No hallucinated APIs.
+
+## Process
+
+1. Read the plan or design under test (`specs/release-plan.yaml + epic shards`, INTERFACE-OPTIONS.md, etc.).
+2. List assumptions that depend on external libraries or APIs.
+3. For each assumption: fetch or quote official docs; challenge with "docs say X, plan says Y."
+4. Resolve or update the plan inline; unresolved items block `plan-work`.
+
+## Docs mode rules
+
+- Cite URL + quoted snippet (method name, parameter, version).
+- If docs contradict the plan, plan loses until updated.
+- Prefer official docs over blog posts.
+
+## Verify
+
+→ verify: `grep -c 'https\?://' skills/grill-with-docs/SKILL.md | awk '{if($1>=2) print "OK"; else print "NEEDS DOCS"}'`
+
+See [REFERENCE.md](REFERENCE.md) for question templates.
+
+
+<!-- story: e03s01 -->
+
+---
+
+# Grill With Docs — Question templates
+
+- "Docs at [URL] show signature `foo(bar?: Baz)`. Your plan calls `foo(bar, baz)` — which is correct?"
+- "The changelog at [URL] deprecates X in v3. Your plan still uses X — migrate or pin version?"
+- "Error handling in [URL] throws `NetworkError`. Your plan catches `Error` only — is that sufficient?"

package/.codex/skills/guard-git/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: guard-git
+model: haiku
+description: "Block dangerous git commands (push, force push, reset --hard, clean, branch -D, checkout/restore .) and enforce Conventional Commits & Branch Protection before an AI agent runs them. Installs hook scripts for Claude Code, Cursor, Cursor CLI, and Gemini CLI; documents Google Antigravity Terminal deny lists. Use when the user wants git safety hooks, to block git push or destructive git in agents, or to mirror the same policy across AI coding tools."
+---
+
+# Guard Git
+> **HARD GATE** — **HARD GATE** — Before committing, verify: branch is not main/master, author is correct, git user is configured. Bad commits are hard to fix.
+
+
+Installs a shared hook that blocks destructive git operations and enforces workflow discipline. **Requires `jq` on the agent's PATH** when the hook runs.
+
+## What gets blocked/enforced
+
+- **Safety**: `git push --force`, `git reset --hard`, `git clean -f`, `git branch -D`, `git checkout .`, `git restore .`.
+- **Discipline**: Blocks direct commits or pushes to protected branches (`main`, `master`) unless `GIT_BIGPOWERS_LAND=1` (set only by `scripts/land-branch.sh`).
+- **Allows**: `git push origin <feature-branch>` for backup/CI; solo land push to `main` only inside `land-branch.sh`.
+- **Standardization**: Enforces [Conventional Commits](https://www.conventionalcommits.org/) for all `git commit` commands.
+- **Secrets**: Blocks commits containing common secret patterns (`sk-`, `ghp_`, `AKIA`, `xoxb-`, `-----BEGIN` private keys) — see [REFERENCE.md](REFERENCE.md).
+
+## Quick start
+
+1. **Scope**: ask project-only vs global (paths differ per product).
+2. **Write the hook bundle** from [REFERENCE.md](REFERENCE.md) into the client's hooks directory.
+3. **Run `chmod +x`** on `pre-tool-use.sh`.
+4. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys.
+5. **Verify** with the tests in [REFERENCE.md](REFERENCE.md).
+
+| Client | Mechanism | Config |
+|--------|-----------|--------|
+| Claude Code | `PreToolUse` (Bash) | `.claude/settings.json` or `~/.claude/settings.json` |
+| Cursor / Cursor CLI | `beforeShellExecution` | `.cursor/hooks.json` or `~/.cursor/hooks.json` |
+| Gemini CLI | `BeforeTool` + `run_shell_command` | `.gemini/settings.json` or `~/.gemini/settings.json` |
+| Google Antigravity | Built-in Terminal **Deny list** | Settings UI (no shell hook) |
+
+**Modes (env on the hook command):** `GIT_GUARDRAILS_MODE` is `claude` (default) or `cursor` → stderr + exit `2` on block. Set `gemini` for Gemini CLI → JSON `decision` on stdout.
+
+## Customization
+
+To add or remove patterns or protected branches, edit `pre-tool-use.sh`.
+
+## Advanced
+
+Full JSON examples, merge rules, Antigravity deny-list entries, and test commands: [REFERENCE.md](REFERENCE.md).
+
+
+
+<!-- story: e01s03 -->
+
+---
+
+# Git guardrails — reference
+
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–14 | Navigation |
+| 16–24 | Secret patterns |
+| 26–44 | Copy layout |
+| 46–72 | Claude Code |
+| 74–92 | Cursor and Cursor CLI |
+| 94–120 | Gemini CLI |
+| 122–135 | Google Antigravity |
+| 137–178 | Verify (local tests) |
+
+## Secret patterns (audit + pre-commit)
+
+Agents must not commit files containing:
+
+- `sk-` (OpenAI API keys)
+- `ghp_` / `gho_` (GitHub tokens)
+- `AKIA` (AWS access key id)
+- `xoxb-` (Slack bot tokens)
+- `-----BEGIN` private keys
+
+Use `audit-code` supply-chain checklist before commit. Consider `git-secrets` or custom pre-commit hook in target projects.
+
+## Copy layout
+
+The main script is `pre-tool-use.sh`.
+
+```text
+<hooks-dir>/pre-tool-use.sh
+```
+
+Example project locations:
+
+- Claude: `.claude/hooks/`
+- Cursor: `.cursor/hooks/`
+- Gemini: `.gemini/hooks/`
+
+Use the same layout for user-level hooks (`~/.claude/hooks`, `~/.cursor/hooks`, `~/.gemini/hooks`).
+
+---
+
+## Claude Code
+
+Hook command does **not** need `GIT_GUARDRAILS_MODE` (defaults to `claude`).
+
+**Project** (`.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre-tool-use.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Cursor and Cursor CLI
+
+Use `beforeShellExecution`. Set `GIT_GUARDRAILS_MODE=cursor`.
+
+**Project** (`.cursor/hooks.json`):
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "GIT_GUARDRAILS_MODE=cursor .cursor/hooks/pre-tool-use.sh",
+        "matcher": "git"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Gemini CLI
+
+Use `BeforeTool` with matcher `run_shell_command`. Set **`GIT_GUARDRAILS_MODE=gemini`**.
+
+**Project** (`.gemini/settings.json`):
+
+```json
+{
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "run_shell_command",
+        "hooks": [
+          {
+            "name": "git-guardrails",
+            "type": "command",
+            "command": "GIT_GUARDRAILS_MODE=gemini \"$GEMINI_PROJECT_DIR\"/.gemini/hooks/pre-tool-use.sh",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Google Antigravity
+
+Add **Deny list** entries in **Antigravity → Settings → Terminal**:
+
+- `git push --force`
+- `git push origin main`
+- `git push origin master`
+- `git reset --hard`
+- `git clean`
+- `git branch -D`
+- `git checkout .`
+- `git restore .`
+
+---
+
+## Verify (local tests)
+
+**1. Block push to main without land mode (Claude mode):**
+```bash
+echo '{"tool_input":{"command":"git push origin main"}}' | ./pre-tool-use.sh
+# Expected: exit 2, protected branch message
+```
+
+**2. Allow push to main with GIT_BIGPOWERS_LAND=1:**
+```bash
+GIT_BIGPOWERS_LAND=1 echo '{"tool_input":{"command":"git push origin main"}}' | ./pre-tool-use.sh
+# Expected: exit 0 (when on main)
+```
+
+**3. Allow push to feature branch:**
+```bash
+echo '{"tool_input":{"command":"git push -u origin feat/my-task"}}' | ./pre-tool-use.sh
+# Expected: exit 0
+```
+
+**4. Conventional Commits (Gemini mode):**
+```bash
+echo '{"tool_input":{"command":"git commit -m \"bad message\""}}' | GIT_GUARDRAILS_MODE=gemini ./pre-tool-use.sh
+# Expected: exit 0, {"decision":"deny", "reason":"..."}
+```
+
+**5. Protected Branch commit (Cursor mode):**
+```bash
+# Run on 'main' branch
+echo '{"command":"git commit -m \"feat: valid message\""}' | GIT_GUARDRAILS_MODE=cursor ./pre-tool-use.sh
+# Expected: exit 2, "Direct commits to protected branch 'main' are forbidden"
+```
+
+**6. Land script exists:**
+```bash
+test -x scripts/land-branch.sh && echo OK
+```
+
+**7. Allow (Gemini mode):**
+```bash
+echo '{"tool_input":{"command":"git status"}}' | GIT_GUARDRAILS_MODE=gemini ./pre-tool-use.sh
+# Expected: exit 0, {"decision":"allow"}
+```

package/.codex/skills/harden-vps/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: harden-vps
+model: haiku
+description: "Harden a production Linux VPS for BigBase across three layers — BigBase app (systemd hardening, monitoring alerts, backup automation), Ubuntu OS (UFW firewall, fail2ban SSH, unattended-upgrades, SSH hardening), and Contabo VPS (health checks, daily backups, monthly snapshots). Use when the user wants to secure a production server, harden a VPS, audit server security, or mentions production hardening, VPS security, or harden the server."
+---
+
+# Harden VPS
+
+Three-layer production hardening for BigBase on Contabo VPS. Each layer independently verifiable. Apply OS first (firewall blocks attacks immediately), then BigBase (alerts + backups), then Contabo (snapshots). See [REFERENCE.md](REFERENCE.md) for full script bodies, systemd unit template, and gotchas.
+
+## Quick start
+
+SSH as root into the VPS. Find credentials in the Contabo Customer Control Panel.
+
+> **HARD GATE** — Run `ufw status` first. No firewall = layer 1 takes priority over everything.
+
+## Layer 1 — Ubuntu OS
+
+```bash
+# UFW
+ufw default deny incoming && ufw default allow outgoing
+ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp && ufw enable
+# → verify: ufw status | grep -q active
+
+# fail2ban
+apt install -y fail2ban
+# Configure /etc/fail2ban/jail.local: sshd, maxretry=3, bantime=3600, findtime=600
+systemctl restart fail2ban
+# → verify: fail2ban-client status sshd
+
+# unattended-upgrades
+apt install -y unattended-upgrades && dpkg-reconfigure -plow unattended-upgrades
+# → verify: systemctl is-active unattended-upgrades | grep -q active
+
+# SSH: PermitRootLogin no, PasswordAuthentication no, PubkeyAuthentication yes
+# → verify: sshd -T | grep -E 'permitrootlogin no|passwordauthentication no'
+
+# Deploy healthcheck.sh → /opt/bigbase/scripts/healthcheck.sh
+# Crontab: */5 * * * * /opt/bigbase/scripts/healthcheck.sh
+```
+
+## Layer 2 — BigBase application
+
+```bash
+# systemd: User=bigbase, NoNewPrivileges=yes, ProtectSystem=full,
+#   ProtectKernelTunables=yes, ProtectKernelModules=yes,
+#   ProtectControlGroups=yes, RestrictAddressFamilies=AF_INET AF_INET6,
+#   RestrictRealtime=yes, PrivateTmp=yes, LimitNOFILE=65536
+# → verify: systemctl show bigbase -p NoNewPrivileges -p ProtectSystem -p User
+
+# Alerts (BigBase requires auth; insert via SQLite)
+sqlite3 /opt/bigbase/data/bigbase.db "
+INSERT INTO monitoring_alerts (id,name,metric,threshold,operator,enabled,duration_seconds)
+VALUES ('a1','Disk >80%','disk_used_percent',80,'gt',1,300);
+INSERT INTO monitoring_alerts (id,name,metric,threshold,operator,enabled,duration_seconds)
+VALUES ('a2','CPU >90%','cpu_percent',90,'gt',1,60);
+INSERT INTO monitoring_alerts (id,name,metric,threshold,operator,enabled,duration_seconds)
+VALUES ('a3','RAM >85%','mem_used_percent',85,'gt',1,120);
+"
+systemctl restart bigbase
+
+# Backup crontab (root):
+# 0 2 * * * cp /opt/bigbase/data/bigbase.db /backup/bigbase-$(date +\%Y\%m\%d).db
+# 0 3 * * * find /backup/ -name "bigbase-*.db" -mtime +90 -delete
+```
+
+## Layer 3 — Contabo VPS
+
+```bash
+# cntb CLI
+curl -sL "$(curl -sL https://api.github.com/repos/contabo/cntb/releases/latest \
+  | grep browser_download_url.*linux_amd64.tar.gz | head -1 | cut -d'"' -f4)" \
+  | tar xz -C /usr/local/bin
+
+# Snapshot script → /opt/bigbase/scripts/contabo-snapshot.sh (reads from /opt/bigbase/.env)
+# Credentials as env vars in /opt/bigbase/.env (deployed by GitHub Actions):
+#   CONTABO_CLIENT_ID, CONTABO_CLIENT_SECRET, CONTABO_API_USER, CONTABO_API_PASSWORD
+# Crontab: 0 4 1 * * /opt/bigbase/scripts/contabo-snapshot.sh
+
+# > HARD GATE — Snapshot cron silently fails until env vars are set in .env.
+# Credentials source: Contabo Customer Panel → API Details.
+# Local dev: add to .envrc. Production: GitHub Secrets → deploy → /opt/bigbase/.env
+```
+
+## CRITICAL GOTCHAS
+
+1. **Shell escaping in Orca terminals:** `$VAR`, `$(…)`, and `%` get eaten by the local shell. Always use base64: `echo '<base64>' | base64 -d > script.sh`
+2. **Crontab `%`:** cron interprets `%` as newline. Escape as `\%` in `$(date +\%Y\%m\%d)`
+3. **fail2ban exit 255:** means a jail references a missing log file. Remove the broken jail, restart.
+4. **BigBase alerts need auth:** POST to `/api/monitoring/alerts` requires Bearer token. Workaround: insert directly into SQLite, then restart BigBase.
+
+## Verify all 8 gates
+
+```bash
+ufw status|grep -q active||echo FAIL:ufw
+fail2ban-client status sshd>/dev/null 2>&1||echo FAIL:fail2ban
+systemctl is-active unattended-upgrades|grep -q active||echo FAIL:unattended
+sshd -T|grep -q 'permitrootlogin no'||echo FAIL:sshd
+systemctl show bigbase -p NoNewPrivileges|grep -q yes||echo FAIL:systemd
+systemctl is-active bigbase|grep -q active||echo FAIL:bigbase
+sqlite3 /opt/bigbase/data/bigbase.db "SELECT count(*) FROM monitoring_alerts"|grep -q 3||echo FAIL:alerts
+crontab -l|grep -q healthcheck&&crontab -l|grep -q bigbase.db&&crontab -l|grep -q contabo-snapshot||echo FAIL:crontab
+echo ALL 8 GATES PASSED
+```
+
+→ verify: run the 8-gate one-liner on the VPS.
+
+---
+
+# Harden VPS — Reference
+
+## Health check script
+
+Deploy to `/opt/bigbase/scripts/healthcheck.sh`:
+
+```bash
+#!/bin/bash
+LOG=/var/log/bigbase/health.log
+mkdir -p /var/log/bigbase
+DISK=$(df / | awk 'NR==2 {print $5}' | tr -d '%')
+RAM=$(free | awk '/Mem:/ {printf "%.0f", $3/$2*100}')
+NOW=$(date -Iseconds)
+[ "$DISK" -gt 85 ] && echo "$NOW ALERT: Disk ${DISK}%" >> "$LOG"
+[ "$RAM" -gt 90 ]   && echo "$NOW ALERT: RAM ${RAM}%" >> "$LOG"
+systemctl is-active --quiet bigbase || { echo "$NOW ALERT: BigBase DOWN" >> "$LOG"; systemctl restart bigbase; }
+[ -f /var/run/reboot-required ] && echo "$NOW WARN: kernel reboot pending" >> "$LOG"
+```
+
+Make executable: `chmod +x /opt/bigbase/scripts/healthcheck.sh`
+
+## BigBase systemd unit
+
+Full hardened unit at `/etc/systemd/system/bigbase.service`:
+
+```ini
+[Unit]
+Description=BigBase BaaS Platform
+Documentation=https://github.com/danielvm-git/bigbase
+After=network.target caddy.service
+Wants=caddy.service
+
+[Service]
+Type=simple
+User=bigbase
+Group=bigbase
+WorkingDirectory=/opt/bigbase
+ExecStart=/opt/bigbase/bin/bigbase serve \
+    --port 8080 \
+    --db /opt/bigbase/data/bigbase.db \
+    --sites-domain <your-domain.example.com>
+EnvironmentFile=-/opt/bigbase/.env
+Environment=BIGBASE_HOME=/opt/bigbase
+Environment=HOME=/opt/bigbase
+Environment=NPM_CONFIG_CACHE=/opt/bigbase/.npm
+Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+Restart=always
+RestartSec=5
+StartLimitIntervalSec=60
+StartLimitBurst=3
+TimeoutStopSec=30
+KillSignal=SIGTERM
+NoNewPrivileges=yes
+PrivateTmp=yes
+ProtectSystem=full
+ProtectHome=yes
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectControlGroups=yes
+RestrictAddressFamilies=AF_INET AF_INET6
+RestrictRealtime=yes
+ReadWritePaths=/opt/bigbase/data
+ReadWritePaths=/opt/bigbase/backups
+ReadWritePaths=/opt/bigbase/secrets
+ReadWritePaths=/opt/bigbase/.npm
+ReadWritePaths=/opt/bigbase/logs
+LimitNOFILE=65536
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## fail2ban jail.local
+
+```ini
+[sshd]
+enabled = true
+port = ssh
+filter = sshd
+logpath = /var/log/auth.log
+maxretry = 3
+bantime = 3600
+findtime = 600
+```
+
+Note: BigBase auth jail deferred — BigBase logs to journald, not a file. To enable, use `backend = systemd` with a journald filter.
+
+## contabo-snapshot.sh
+
+Deploy to `/opt/bigbase/scripts/contabo-snapshot.sh`. Reads credentials from `/opt/bigbase/.env` (same file used by BigBase systemd unit):
+
+```bash
+#!/bin/bash
+set -e
+LOG=/var/log/bigbase/snapshot.log
+ENVFILE=/opt/bigbase/.env
+INSTANCE_ID=<your-contabo-instance-id>
+
+[ -f "$ENVFILE" ] || { echo "$(date -Iseconds) ERROR: $ENVFILE missing" >> "$LOG"; exit 1; }
+set -a; source "$ENVFILE"; set +a
+
+[ -z "$CONTABO_CLIENT_ID" ] && { echo "$(date -Iseconds) ERROR: CONTABO_CLIENT_ID not set" >> "$LOG"; exit 1; }
+
+TOKEN=$(curl -s -d "client_id=$CONTABO_CLIENT_ID" \
+  -d "client_secret=$CONTABO_CLIENT_SECRET" \
+  --data-urlencode "username=$CONTABO_API_USER" \
+  --data-urlencode "password=$CONTABO_API_PASSWORD" \
+  -d 'grant_type=password' \
+  'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' \
+  | jq -r '.access_token')
+
+[ -z "$TOKEN" ] || [ "$TOKEN" = "null" ] && { echo "$(date -Iseconds) ERROR: auth failed" >> "$LOG"; exit 1; }
+
+curl -s -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "x-request-id: $(uuidgen 2>/dev/null || echo $RANDOM)" \
+  "https://api.contabo.com/v1/compute/instances/${INSTANCE_ID}/snapshots" \
+  | tee -a "$LOG"
+
+echo >> "$LOG"
+echo "$(date -Iseconds) Snapshot requested for $INSTANCE_ID" >> "$LOG"
+```
+
+## Contabo credentials
+
+Add to `/opt/bigbase/.env` (same file used by BigBase systemd unit, deployed by GitHub Actions):
+
+```
+CONTABO_CLIENT_ID=
+CONTABO_CLIENT_SECRET=
+CONTABO_API_USER=
+CONTABO_API_PASSWORD=
+```
+
+Source: Contabo Customer Control Panel → API Details. ClientId and ClientSecret are generated there. API User is your email. API Password is set separately in the panel.
+
+**Pipeline:** GitHub Secrets → deploy workflow → `/opt/bigbase/.env` on VPS. For local dev (`cntb get instances`), add to `.envrc`.
+
+## Contabo instance info template
+
+Fill in your instance details from the Contabo Customer Control Panel:
+
+```
+IP:           <your-instance-ip>
+IPv6:         <your-instance-ipv6>
+Region:       <your-region>
+OS:           <your-os-version>
+Disk:         <your-disk-size>
+Default user: root
+Customer ID:  <your-customer-id>
+```
+
+## BigBase monitoring alert SQL
+
+```sql
+INSERT INTO monitoring_alerts (id, name, metric, threshold, operator, enabled, duration_seconds)
+VALUES ('alert-001', 'VPS Disk above 80%', 'disk_used_percent', 80, 'gt', 1, 300);
+
+INSERT INTO monitoring_alerts (id, name, metric, threshold, operator, enabled, duration_seconds)
+VALUES ('alert-002', 'VPS CPU above 90%', 'cpu_percent', 90, 'gt', 1, 60);
+
+INSERT INTO monitoring_alerts (id, name, metric, threshold, operator, enabled, duration_seconds)
+VALUES ('alert-003', 'VPS RAM above 85%', 'mem_used_percent', 85, 'gt', 1, 120);
+```
+
+Alerts are loaded at BigBase startup. Restart with `systemctl restart bigbase` after inserting.
+
+## Base64 encoding workaround
+
+When sending scripts through Orca terminal `--text`, the local bash shell interprets `$`, `(`, and `%`. Encode locally and decode remotely:
+
+```bash
+# Local
+cat script.sh | base64
+
+# Remote terminal
+echo '<base64-output>' | base64 -d > script.sh
+```