bigpowers 2.76.3 → 2.77.0

package/.pi/prompts/plan-work.md

@@ -44,7 +44,7 @@ If this plan touches an existing module, run `assess-impact` first to understand
 
 2. **Draft steps** — Break implementation into the smallest possible steps where each step leaves the codebase working, has one observable outcome, and can be verified with a single command. Red-flag check: name any rationalization you caught before moving to step 3.
 
-3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics/<id>/THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps.
+3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics/<id>/THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. Each task should also include an `allure:` block to drive test reporting: `severity:` maps risk to Allure severity (`P0→critical`, `P1→high`, `P2→normal`, `P3→minor`), and `categories:` is a list of relevant tags like `"Security Review"`, wave names, or test categories (see REFERENCE.md for the full template).
 
    **Requirement delta tags (e45s29):** When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content:
 
@@ -132,8 +132,21 @@ tasks:
     verify: "npm test -- login-form.test.tsx"
     risk: P1
     status: failing   # flip to passing only after verify exits 0 (e45s06)
+    allure:
+      severity: high              # P0→critical, P1→high, P2→normal, P3→minor
+      categories:
+        - "Auth"
+        - "Security Review"
 ```
 
+**Allure severity mapping:**
+- `P0` → `critical`
+- `P1` → `high`
+- `P2` → `normal`
+- `P3` → `minor`
+
+`categories` is a list of relevant tags — wave names, test categories (e.g. `"unit"`, `"integration"`), or thematic groupings (e.g. `"Security Review"`).
+
 Update `specs/epics/<capsule>/epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes.
 
 ## Plan template

package/.pi/skills/build-epic/SKILL.md

@@ -33,6 +33,7 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 ## Process
 
 1. Read `specs/state.yaml`, `specs/execution-status.yaml`, `specs/release-plan.yaml`, active `specs/epics/eNN-slug/epic.yaml`.
+   - **On story start (step 1):** Write `started_at` ISO 8601 timestamp to `execution-status.yaml` under the story's key in the `stories:` section. The `bp-timing.sh` script already tracks skill-level timings — this is story-level.
 2. **Step 0 — Threat Model:** Run `security-review` against the epic's scope (read from the epic capsule). Output `specs/security/epics/<epic-id>/THREAT_MODEL.md` with surface area, vulnerability categories, risk level, and mitigation guidance.
 3. **Assess Impact (Step 2):** Before writing tasks, run `assess-impact --lightweight` on the proposed change. If the risk score exceeds 7, gate — require a `grill-me` session. Write the impact report to `specs/IMPACT-<epic>-<story>.md`. For net-new code with no existing dependents, skip.
 4. **BCP Tracking (Step 2):** After `plan-work` completes, read the `bcps:` count (Business Complexity Points story size) from the epic capsule and carry it into `state.yaml` as `epic_cycle.story_bcps = N`.
@@ -41,6 +42,15 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 6. Run **only the current step** (resume mode) unless user asked for full auto-run.
 7. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).
 8. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.
+   - **On story complete (step 8):** Write `completed_at` ISO 8601 timestamp to `execution-status.yaml` under the same story key. Format:
+
+     ```yaml
+     stories:
+       e01s01:
+         status: done
+         started_at: "2026-07-12T16:00:00-03:00"
+         completed_at: "2026-07-12T18:45:00-03:00"
+     ```
 9. **Traceability refresh:** Before step 8 (release-branch), run `bash scripts/trace-stories.sh` to regenerate `specs/traceability-matrix.json`, `specs/TRACEABILITY_LATEST.md`, and the `specs/codebase-wiki/` OKF bundle. Surface dark/orphan/stale findings for the just-built epic in your verify summary. If `scripts/trace-stories.sh` is missing or fails, note "trace skipped" and continue — trace failure must be visible, not silent (blocking is gate-trace's job, e38s06).
 
 9b. **OKF wiki refresh (e39s08):** Before step 8, run maintain-wiki INGEST to refresh the OKF wiki bundle:

package/.pi/skills/generate-allure-report/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: generate-allure-report
+model: sonnet
+description: "Generate Allure-ready reports from bigpowers YAML metadata. Reads execution-status.yaml, release-plan.yaml, epic capsules, task YAMLs, cycle-times.yaml, and bug registry to produce allure-results/junit-results.xml, categories.json, and executor.json. Use when preparing progress dashboards, integrating with Allure TestOps, or generating CI reports."
+---
+
+# Generate Allure Report
+
+Generate Allure TestOps-compatible reports from bigpowers project metadata. Produces JUnit XML for story-level test results, custom categories for filtering, and executor metadata — all in the `allure-results/` directory.
+
+## Quick Start
+
+```bash
+bash scripts/generate-allure-report.sh
+```
+
+## What It Produces
+
+Three files in `allure-results/`:
+
+| File | Description |
+|------|-------------|
+| `junit-results.xml` | One `<testcase>` per story with `<properties>` for risk, security, WSJF, tier, wave, and status. Incomplete stories get a `<failure>` element. |
+| `categories.json` | Custom Allure categories for filtering by epic, risk level (P0), and security reviews. |
+| `executor.json` | Build metadata — name, type, version from release-plan.yaml, build order. |
+
+## Data Sources
+
+See [REFERENCE.md](REFERENCE.md)
+
+## Verify
+
+```bash
+test -f allure-results/junit-results.xml && test -f allure-results/categories.json && test -f allure-results/executor.json
+```
+
+## Handoff
+
+- next_skill: null (terminal skill — no downstream workflow step)
+
+---
+
+# generate-allure-report — Reference
+
+## Data Sources
+
+The script reads five YAML sources from the project:
+
+| Source | Path | Fields Used |
+|--------|------|-------------|
+| Execution status | `specs/execution-status.yaml` | `epics`, `stories`, `development_status` |
+| Release plan | `specs/release-plan.yaml` | `release.version`, `release.status`, `bugs` summary |
+| Epic capsules | `specs/epics/**/epic.yaml` + `-tasks.yaml` | Epic metadata, task pass/fail counts |
+| Cycle times | `specs/metrics/cycle-times.yaml` | Story-level `cycle_minutes`, `bcp_per_hour`, `source` |
+| Bug registry | `specs/bugs/registry.yaml` | Bug counts by status and severity |
+
+## Script Body
+
+`scripts/generate-allure-report.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || ROOT="$(dirname "${BASH_SOURCE[0]}")/.."
+
+mkdir -p "$ROOT/allure-results"
+
+$PYTHON - "$ROOT" <<'PY'
+import json
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+root = Path(sys.argv[1])
+out = root / "allure-results"
+
+# 1. Read execution-status.yaml
+exec_status_file = root / "specs" / "execution-status.yaml"
+release_plan_file = root / "specs" / "release-plan.yaml"
+cycle_times_file = root / "specs" / "metrics" / "cycle-times.yaml"
+bugs_registry_file = root / "specs" / "bugs" / "registry.yaml"
+
+sys.path.insert(0, str(root / "scripts" / "lib"))
+from simple_yaml import parse_simple_yaml
+
+exec_status = parse_simple_yaml(exec_status_file.read_text()) if exec_status_file.exists() else {}
+release_plan = parse_simple_yaml(release_plan_file.read_text()) if release_plan_file.exists() else {}
+cycle_times = parse_simple_yaml(cycle_times_file.read_text()) if cycle_times_file.exists() else {"stories": []}
+bugs_registry = parse_simple_yaml(bugs_registry_file.read_text()) if bugs_registry_file.exists() else {"bugs": []}
+
+# Build cycle-times lookup
+ct_lookup = {}
+for ct in cycle_times.get("stories", []):
+    if isinstance(ct, dict):
+        ct_lookup[ct.get("id", "")] = ct
+
+# 2. Build JUnit XML
+stories = exec_status.get("stories", {})
+
+# Counts for testsuite attributes
+total_stories = len(stories)
+incomplete = sum(1 for s in stories.values() if isinstance(s, dict) and s.get("status") != "done")
+
+testsuite = ET.Element("testsuite", {
+    "name": "bigpowers-epic-progress",
+    "tests": str(total_stories),
+    "failures": str(incomplete),
+    "errors": "0",
+    "skipped": "0",
+})
+
+for story_id in sorted(stories.keys()):
+    story = stories[story_id]
+    if not isinstance(story, dict):
+        continue
+
+    epic_id = story.get("epic", "unknown")
+    title = story.get("title", story_id)
+    bcps = story.get("bcps", 0)
+    status = story.get("status", "backlog")
+    risk_max = story.get("risk_max", "none")
+    security_max = story.get("security_max", "none")
+
+    # Enrich with cycle-times data
+    ct_data = ct_lookup.get(story_id, {})
+    cycle_minutes = ct_data.get("cycle_minutes", 0)
+    bcp_per_hour = ct_data.get("bcp_per_hour", 0)
+
+    # Time: cycle_minutes * 60 for seconds in Allure display
+    time_seconds = cycle_minutes * 60.0 if cycle_minutes else 0.0
+
+    testcase = ET.SubElement(testsuite, "testcase", {
+        "classname": epic_id,
+        "name": f"{story_id}: {title}",
+        "time": str(round(time_seconds, 3)),
+    })
+
+    props = ET.SubElement(testcase, "properties")
+    ET.SubElement(props, "property", {"name": "risk", "value": risk_max})
+    ET.SubElement(props, "property", {"name": "security", "value": security_max})
+    ET.SubElement(props, "property", {"name": "bcps", "value": str(bcps)})
+    ET.SubElement(props, "property", {"name": "status", "value": status})
+    ET.SubElement(props, "property", {"name": "bcp_per_hour", "value": str(bcp_per_hour)})
+    ET.SubElement(props, "property", {"name": "lead_time_minutes", "value": str(cycle_minutes)})
+
+    if status != "done":
+        ET.SubElement(testcase, "failure", {
+            "message": f"Story {story_id} is {status} [risk={risk_max}, security={security_max}]",
+            "type": "StoryIncomplete"
+        })
+
+tree = ET.ElementTree(testsuite)
+ET.indent(tree, space="  ")
+tree.write(str(out / "junit-results.xml"), encoding="utf-8", xml_declaration=True)
+
+# 3. Build categories.json
+epics = exec_status.get("epics", {})
+categories = []
+
+for epic_id in sorted(epics.keys()):
+    epic = epics[epic_id]
+    if isinstance(epic, dict) and epic.get("status") != "done":
+        categories.append({
+            "name": f"Epic: {epic.get('title', epic_id)}",
+            "matchedStatuses": ["failed"],
+            "messageRegex": f".*{epic_id}:.*"
+        })
+
+categories.append({
+    "name": "P0 Risk",
+    "matchedStatuses": ["failed"],
+    "messageRegex": ".*risk.*P0.*"
+})
+categories.append({
+    "name": "Security Review",
+    "matchedStatuses": ["failed"],
+    "messageRegex": ".*security.*(?:medium|high).*"
+})
+
+# Add bug-based categories
+bug_list = bugs_registry.get("bugs", [])
+bug_count = len(bug_list) if isinstance(bug_list, list) else 0
+open_bugs = sum(1 for b in bug_list if isinstance(b, dict) and b.get("status") not in ("fixed", "closed", None))
+if open_bugs > 0:
+    categories.append({
+        "name": "Open Bugs",
+        "matchedStatuses": ["failed"],
+        "messageRegex": ".*Bug.*"
+    })
+
+(out / "categories.json").write_text(json.dumps(categories, indent=2))
+
+# 4. Build executor.json
+rl = release_plan.get("release", {}) if isinstance(release_plan.get("release"), dict) else {}
+executor = {
+    "name": "bigpowers",
+    "type": "bigpowers",
+    "buildName": rl.get("version", "unknown") if isinstance(rl, dict) else "unknown",
+    "buildOrder": len(exec_status.get("development_status", {})),
+}
+(out / "executor.json").write_text(json.dumps(executor, indent=2))
+
+# Summary
+epic_count = len([e for e in epics.values() if isinstance(e, dict) and e.get("status") == "done"])
+total_epics = len(epics)
+print(f"generate-allure-report: {total_stories} stories, {epic_count}/{total_epics} epics done, {bug_count} bugs")
+print(f"  -> {out}/junit-results.xml")
+print(f"  -> {out}/categories.json")
+print(f"  -> {out}/executor.json")
+PY
+```
+
+## JUnit XML Schema
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<testsuite name="bigpowers-epic-progress" tests="N" failures="F" errors="0" skipped="0">
+  <testcase classname="e01" name="e01s01: Security slopcheck tags" time="0.75">
+    <properties>
+      <property name="risk" value="none"/>
+      <property name="security" value="none"/>
+      <property name="bcps" value="1"/>
+      <property name="status" value="done"/>
+      <property name="bcp_per_hour" value="1.3"/>
+      <property name="lead_time_minutes" value="45"/>
+    </properties>
+  </testcase>
+  <testcase classname="e01" name="e01s99: Some incomplete story" time="0.0">
+    <properties>...</properties>
+    <failure message="Story e01s99 is backlog [risk=P0, security=high]" type="StoryIncomplete"/>
+  </testcase>
+</testsuite>
+```
+
+## Categories JSON Schema
+
+```json
+[
+  {
+    "name": "Epic: Quality Core - Skill Hardening",
+    "matchedStatuses": ["failed"],
+    "messageRegex": ".*e45:.*"
+  },
+  {
+    "name": "P0 Risk",
+    "matchedStatuses": ["failed"],
+    "messageRegex": ".*risk.*P0.*"
+  },
+  {
+    "name": "Security Review",
+    "matchedStatuses": ["failed"],
+    "messageRegex": ".*security.*(?:medium|high).*"
+  }
+]
+```
+
+## Executor JSON Schema
+
+```json
+{
+  "name": "bigpowers",
+  "type": "bigpowers",
+  "buildName": "2.76.2",
+  "buildOrder": 400
+}
+```
+
+## Example Usage
+
+```bash
+# Generate reports
+bash scripts/generate-allure-report.sh
+
+# Verify output
+test -f allure-results/junit-results.xml && echo "JUnit OK"
+test -f allure-results/categories.json && echo "Categories OK"
+test -f allure-results/executor.json && echo "Executor OK"
+
+# Serve with Allure
+allure serve allure-results/
+
+# Or open the Allure TestOps UI
+allure open allure-results/
+```

package/.pi/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
+```