القائمة
Reference for deploying to the Raspberry Pi
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Review code changes against the HelmLog-specific data licensing policy (docs/data-licensing.md) — embargoes, protest firewall, biometrics consent, gambling exclusion, fleet-benchmark thresholds, coach access expiry. The model recovers general PII / cross-tenant / audit-logging concerns by default; this skill encodes only the HelmLog-specific items that are not recoverable from general engineering judgment. TRIGGER when modifying code that handles user data, PII, co-op/federation data sharing, export endpoints, deletion/anonymization, or audit logging. Key files — storage.py, export.py, peer_api.py, peer_client.py, federation.py, transcribe.py, audio.py, web.py (data endpoints). DO NOT trigger for UI-only changes, instrument decoding, polar analysis, config, docs, or CSS/JS/templates.
Run pre-PR verification checks before creating a pull request. TRIGGER when implementation is complete and the user is ready to create or push a PR — e.g., "create a PR", "ready for review", "push this up", or running /pr-checklist. DO NOT trigger mid-implementation, during TDD cycles, when exploring code, or when the user is still writing features.
HelmLog-specific test patterns and the pre-existing-error allowlist for ruff/mypy. The Red-Green-Refactor cycle and lint commands are already mandated in CLAUDE.md — this skill encodes only the patterns and known-pre-existing-errors list that aren't recoverable from existing tests at a glance. TRIGGER when writing or modifying Python source code in src/helmlog/. DO NOT trigger for documentation, config, templates, CSS/JS, skill definitions, or changes that don't affect runtime behavior.
Run a focused per-race debrief and attach the summary as a moment on the session. TRIGGER when the user says "debrief race N", "debrief that race", "/debrief", "post-race analysis", or asks for analysis of a single specific race. DO NOT trigger for season-wide reviews (that's a manual run of scripts/analysis/full_analysis.py), broad questions about boat performance, or non-race sessions.
Detect OCS (over-the-line at gun, returned to clear) races against the live DB and apply the 'ocs' tag to any newly identified ones. TRIGGER when the user asks "check for OCS", "did we OCS", "tag OCS races", "/ocs-check", or after a race day to find any starts that should be marked OCS. Auto-trigger when running /debrief on a race that hasn't been OCS-checked yet.
Codebase comprehension and complexity tracking — module map, data flow, recent changes, and complexity hotspots. Run with no arguments for a full snapshot or with a date/commit/tag for a delta briefing. TRIGGER when the user asks for a system overview, wants to understand the architecture, asks "what changed while I was away", or needs to orient before a large task. DO NOT trigger for specific code questions, bug fixes, or implementation tasks — those are better served by reading the relevant module directly.
| name | deploy-pi |
| description | Reference for deploying to the Raspberry Pi |
| disable-model-invocation | true |
Deploys are driven from the Deploy admin page — /admin/deployment
(nav → "Deploy") — not by hand on the Pi. The Pi runs an evergreen
auto-deployer that polls the tracked branch (~every 300 s) and deploys when it
changes.
main → stage → live: use the PROMOTION PIPELINE on the same page
(the main → stage / stage → live links) — promotions run via GitHub
Actions, not manual git. The main → stage gate needs a RELEASES.md entry
(see /release-notes); stage → live has no gate.So "deploy #N to corvopi-live" = set Track branch to the merged branch (usually
main) on the Deploy page; switching branches is a config change there, not an
ssh session.
ssh <pi-user>@<pi-host>
cd ~/helmlog
./scripts/deploy.sh
The script: pulls the tracked branch, syncs Python deps, re-applies Tailscale
Funnel routes, updates PUBLIC_URL in .env, restarts helmlog, prints status.
ssh <pi-user>@<pi-host>
cd ~/helmlog
./scripts/setup.sh && sudo systemctl daemon-reload && sudo systemctl restart helmlog
The service runs as a dedicated helmlog system account (not the login user):
User=helmlog, UV_CACHE_DIR=/var/cache/helmlog, --no-synchelmlog:helmlog; rest of project tree is read-onlychmod 600 <pi-user>:<pi-user>; systemd reads as root before dropping privileges<pi-user> has scoped access via /etc/sudoers.d/helmlog-allowed127.0.0.1:3000 — exposed publicly via Tailscale Funnel at /signalk/127.0.0.1:8086 only127.0.0.1:3001 only0.0.0.0:3002GF_AUTH_ANONYMOUS_ENABLED=false via systemd)@signalk/sk-simple-token-security; admin password in ~/.signalk-admin-pass.txt# Check status
sudo systemctl status helmlog
# View logs
sudo journalctl -u helmlog -f
# Restart
sudo systemctl restart helmlog
# Rollback to previous commit
git log --oneline -5
git checkout <previous-commit>
./scripts/deploy.sh
| Symptom | Fix |
|---|---|
| Service won't start | Check journalctl -u helmlog -n 50 for errors |
uv not found | Ensure UV_CACHE_DIR is set in systemd unit |
ModuleNotFoundError for a dep in pyproject.toml | Run uv sync — the venv is stale. The service uses --no-sync and trusts the venv. Never use uv pip install as a workaround |
Permission denied on data/ | Run sudo chown -R helmlog:helmlog data/ |
| Signal K unreachable | Check systemctl status signalk-server |
| Web UI 502 | Service crashed — sudo systemctl restart helmlog |