From 4e54b8bd4d4b14ddd9958f6a2d8956b3e589530c Mon Sep 17 00:00:00 2001
From: Dorian <dorian@Dorians-MacBook-Air.local>
Date: Sun, 15 Mar 2026 12:35:17 +0000
Subject: [PATCH] feat: add YAML frontmatter, bitcoin-conventions skill, path
 rules, and Gitea CI

- Added YAML frontmatter to all 8 polish-* skills and sweep skill
  so Claude can auto-invoke them
- New bitcoin-conventions skill with PROUX UX methodology, sats display,
  address validation, Tor preferences, Lightning patterns
- Path-specific rules for containers (security hardening) and frontend
  (Vue/glassmorphism conventions)
- Gitea Actions: nightly security review and weekly dependency audit

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/rules/containers.md                 |  19 ++++
 .claude/rules/frontend.md                   |  16 +++
 .claude/skills/bitcoin-conventions/SKILL.md | 113 ++++++++++++++++++++
 .claude/skills/polish-backend/SKILL.md      |   5 +
 .claude/skills/polish-deploy/SKILL.md       |   5 +
 .claude/skills/polish-errors/SKILL.md       |   5 +
 .claude/skills/polish-forms/SKILL.md        |   5 +
 .claude/skills/polish-loading/SKILL.md      |   5 +
 .claude/skills/polish-security/SKILL.md     |   5 +
 .claude/skills/polish-websocket/SKILL.md    |   5 +
 .claude/skills/polish/SKILL.md              |   5 +
 .claude/skills/sweep/SKILL.md               |   5 +
 .gitea/workflows/nightly-security.yml       |  45 ++++++++
 .gitea/workflows/weekly-dep-audit.yml       |  29 +++++
 14 files changed, 267 insertions(+)
 create mode 100644 .claude/rules/containers.md
 create mode 100644 .claude/rules/frontend.md
 create mode 100644 .claude/skills/bitcoin-conventions/SKILL.md
 create mode 100644 .gitea/workflows/nightly-security.yml
 create mode 100644 .gitea/workflows/weekly-dep-audit.yml

diff --git a/.claude/rules/containers.md b/.claude/rules/containers.md
new file mode 100644
index 00000000..b756b8aa
--- /dev/null
+++ b/.claude/rules/containers.md
@@ -0,0 +1,19 @@
+---
+globs:
+  - "**/container/**"
+  - "**/manifest*"
+  - "**/*podman*"
+  - "**/Containerfile"
+  - "**/Dockerfile"
+---
+
+# Container Security Rules (Archipelago)
+
+- `readonly_root: true` always — containers must not write to their root filesystem
+- Drop ALL capabilities, add only what's required (`--cap-drop=ALL --cap-add=...`)
+- Run as non-root user (UID > 1000): `--user 1001:1001`
+- Set `--security-opt=no-new-privileges:true`
+- Pin image versions by SHA256 digest, never use `:latest` tag
+- Mount secrets as read-only files, never pass as environment variables when possible
+- Set memory and CPU limits on all containers
+- Use `--network=none` unless network access is required
diff --git a/.claude/rules/frontend.md b/.claude/rules/frontend.md
new file mode 100644
index 00000000..1f538cf1
--- /dev/null
+++ b/.claude/rules/frontend.md
@@ -0,0 +1,16 @@
+---
+globs:
+  - "**/neode-ui/**"
+  - "**/*.vue"
+---
+
+# Frontend Rules (Archipelago)
+
+- Always use `<script setup lang="ts">` in Vue components
+- Global CSS classes go in `style.css`, never inline Tailwind utilities
+- Use `.glass-button` for ALL buttons — `.gradient-button` is BANNED
+- Use Pinia stores for shared state, never provide/inject for cross-component data
+- Every async view needs: loading state, empty state, and error state
+- Trim all text inputs before submission
+- Disable submit buttons during async operations
+- Use `errorMessage` ref pattern for user-visible errors, not just console.log
diff --git a/.claude/skills/bitcoin-conventions/SKILL.md b/.claude/skills/bitcoin-conventions/SKILL.md
new file mode 100644
index 00000000..695cd9da
--- /dev/null
+++ b/.claude/skills/bitcoin-conventions/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: bitcoin-conventions
+description: Bitcoin development conventions for Archipelago. Covers sats display (integers, never float), address type detection, Tor/onion endpoint preference, Bitcoin RPC error handling, and Lightning patterns. Use when working with Bitcoin amounts, addresses, RPC calls, Lightning channels, or onion services.
+---
+
+# Bitcoin Development Conventions
+
+## Critical Rules
+
+- **NEVER use floating point for Bitcoin amounts.** Sats are always `u64` (Rust) or `BigInt`/integer (TypeScript).
+- **NEVER log private keys, seeds, or mnemonics.** Not even at debug/trace level.
+- **Prefer Tor/onion endpoints** for all Bitcoin network services when available.
+
+## Amount Display
+
+### Rust
+```rust
+// Amount is always in sats as u64
+pub fn format_sats(sats: u64) -> String {
+    if sats >= 100_000_000 {
+        let btc = sats / 100_000_000;
+        let remainder = sats % 100_000_000;
+        if remainder == 0 {
+            format!("{} BTC", btc)
+        } else {
+            format!("{}.{:08} BTC", btc, remainder)
+        }
+    } else {
+        format!("{} sats", sats)
+    }
+}
+```
+
+### TypeScript
+```typescript
+// Never: amount * 0.00000001
+// Always: integer arithmetic or BigInt
+function formatSats(sats: number): string {
+  if (sats >= 100_000_000) {
+    const btc = Math.floor(sats / 100_000_000)
+    const remainder = sats % 100_000_000
+    return remainder === 0 ? `${btc} BTC` : `${btc}.${String(remainder).padStart(8, '0')} BTC`
+  }
+  return `${sats.toLocaleString()} sats`
+}
+```
+
+## Address Types
+
+Detect and display address type:
+- `1...` — P2PKH (Legacy)
+- `3...` — P2SH (SegWit-compatible)
+- `bc1q...` — P2WPKH (Native SegWit)
+- `bc1p...` — P2TR (Taproot)
+
+Always validate addresses before any operation. Use network-appropriate validation (mainnet `bc1`, testnet `tb1`, regtest `bcrt1`).
+
+## Bitcoin RPC Error Handling
+
+```rust
+match rpc_response.error {
+    Some(err) => {
+        // Standard Bitcoin Core RPC error codes
+        match err.code {
+            -1 => /* miscellaneous error */,
+            -5 => /* invalid address or key */,
+            -6 => /* insufficient funds */,
+            -25 => /* transaction verification failed */,
+            -26 => /* transaction rejected by policy */,
+            -27 => /* transaction already in chain */,
+            -28 => /* client still warming up */,
+            _ => /* unknown error */,
+        }
+    }
+    None => { /* success */ }
+}
+```
+
+Always set explicit timeouts on RPC calls (10s default, 30s for heavy operations like `rescanblockchain`).
+
+## Tor/Onion Preferences
+
+When configuring Bitcoin services:
+1. Check for Tor SOCKS proxy (default: `127.0.0.1:9050`)
+2. If available, route Bitcoin P2P and RPC through Tor
+3. Prefer `.onion` endpoints for block explorers, electrum servers
+4. Set `proxy=127.0.0.1:9050` in `bitcoin.conf`
+5. Set `onlynet=onion` for maximum privacy (if full Tor mode)
+
+## Lightning (LND/CLN) Patterns
+
+### BOLT11 Invoice handling
+- Always validate invoice before displaying to user
+- Show: amount, description, expiry, destination pubkey
+- Never auto-pay without user confirmation
+
+### Channel States
+Display human-readable channel state:
+- `PENDING_OPEN` → "Opening..."
+- `OPEN` → "Active"
+- `PENDING_CLOSE` / `FORCE_CLOSING` → "Closing..."
+- `CLOSED` → "Closed"
+
+### Macaroon handling
+- Never log macaroon contents
+- Store with restrictive permissions (0600)
+- Use read-only macaroon for queries, admin macaroon only for mutations
+
+## Container Images for Bitcoin Services
+
+- **Always pin by SHA256 digest**, never by tag alone
+- Example: `docker.io/lnzap/lnd@sha256:abc123...` not `lnzap/lnd:latest`
+- Verify image signatures when available (cosign/notary)
diff --git a/.claude/skills/polish-backend/SKILL.md b/.claude/skills/polish-backend/SKILL.md
index 625e2c05..327f4202 100644
--- a/.claude/skills/polish-backend/SKILL.md
+++ b/.claude/skills/polish-backend/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: polish-backend
+description: Fix Rust backend quality issues in Archipelago. Eliminates panics/unwraps, adds timeouts, implements connection pooling, fixes clippy warnings. Use when user says "polish backend", "fix unwraps", "backend quality", or "eliminate panics".
+---
+
 # Skill: Polish Backend Quality
 
 Fix Rust backend quality issues: eliminate panics, add timeouts, implement connection pooling, fix clippy warnings. The backend must never crash in production.
diff --git a/.claude/skills/polish-deploy/SKILL.md b/.claude/skills/polish-deploy/SKILL.md
index 447226c5..896ba4bb 100644
--- a/.claude/skills/polish-deploy/SKILL.md
+++ b/.claude/skills/polish-deploy/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: polish-deploy
+description: Harden Archipelago deployment pipeline with rollback capability, pre-deploy checks, post-deploy health verification, and deployment locking. Use when user says "polish deploy", "harden deployment", "add rollback", or "deploy safety".
+---
+
 # Skill: Polish Deployment Pipeline
 
 Harden deploy-to-target.sh with rollback capability, pre-deploy checks, post-deploy health verification, and deployment locking.
diff --git a/.claude/skills/polish-errors/SKILL.md b/.claude/skills/polish-errors/SKILL.md
index 775990ba..85ac5a81 100644
--- a/.claude/skills/polish-errors/SKILL.md
+++ b/.claude/skills/polish-errors/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: polish-errors
+description: Fix silent error handling across Archipelago codebase. Replaces empty catch blocks, adds user-visible error feedback for all async operations. Use when user says "polish errors", "fix error handling", "silent catches", or "error feedback".
+---
+
 # Skill: Polish Error Handling
 
 Fix silent error handling patterns across the entire codebase. Every async operation must have visible, actionable error feedback for the user.
diff --git a/.claude/skills/polish-forms/SKILL.md b/.claude/skills/polish-forms/SKILL.md
index 91095c6a..c11a64e5 100644
--- a/.claude/skills/polish-forms/SKILL.md
+++ b/.claude/skills/polish-forms/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: polish-forms
+description: Improve form validation across Archipelago UI with real-time feedback, input sanitization, disabled states during submission, and consistent error messaging. Use when user says "polish forms", "form validation", "input validation", or "fix forms".
+---
+
 # Skill: Polish Form Validation
 
 Improve all form inputs to have real-time validation feedback, proper trimming, disabled states during submission, and consistent error messaging.
diff --git a/.claude/skills/polish-loading/SKILL.md b/.claude/skills/polish-loading/SKILL.md
index 9158862c..04db16c8 100644
--- a/.claude/skills/polish-loading/SKILL.md
+++ b/.claude/skills/polish-loading/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: polish-loading
+description: Add skeleton loaders, loading indicators, timeout warnings, and empty states to all Archipelago async views. Use when user says "polish loading", "add skeletons", "loading states", "empty states", or "blank screen fix".
+---
+
 # Skill: Polish Loading States
 
 Add skeleton loaders, loading indicators, timeout warnings, and empty states to all async views. No view should ever show a blank screen.
diff --git a/.claude/skills/polish-security/SKILL.md b/.claude/skills/polish-security/SKILL.md
index b709e701..b7a4c4ff 100644
--- a/.claude/skills/polish-security/SKILL.md
+++ b/.claude/skills/polish-security/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: polish-security
+description: Security hardening for Archipelago systemd services, nginx headers, secrets management, and rate limiting. Use when user says "polish security", "harden services", "security headers", "rate limiting", or "secrets management".
+---
+
 # Skill: Polish Security
 
 Security hardening pass for systemd, nginx, secrets management, and rate limiting.
diff --git a/.claude/skills/polish-websocket/SKILL.md b/.claude/skills/polish-websocket/SKILL.md
index 969b3d8c..424b7b7b 100644
--- a/.claude/skills/polish-websocket/SKILL.md
+++ b/.claude/skills/polish-websocket/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: polish-websocket
+description: Improve Archipelago WebSocket reliability, reconnection UX, heartbeat monitoring, session timeout detection, and connection status indicators. Use when user says "polish websocket", "fix reconnection", "websocket reliability", or "connection status".
+---
+
 # Skill: Polish WebSocket & Real-Time
 
 Improve WebSocket reliability, reconnection UX, heartbeat, session timeout detection, and connection status indicators.
diff --git a/.claude/skills/polish/SKILL.md b/.claude/skills/polish/SKILL.md
index 902a61a6..2102075c 100644
--- a/.claude/skills/polish/SKILL.md
+++ b/.claude/skills/polish/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: polish
+description: Production polish orchestrator for Archipelago. Coordinates all polish sub-skills by reading plan.md and executing the current week's tasks. Use when user says "polish", "production polish", "overnight polish", or "run the polish plan".
+---
+
 # Skill: Production Polish (Overnight Orchestrator)
 
 Main entry point for the Archipelago production polish plan. Reads `plan.md` at the project root, determines the current week based on today's date, and executes the tasks for that week.
diff --git a/.claude/skills/sweep/SKILL.md b/.claude/skills/sweep/SKILL.md
index d8f800a8..17873a1e 100644
--- a/.claude/skills/sweep/SKILL.md
+++ b/.claude/skills/sweep/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: sweep
+description: Full automated quality sweep across Archipelago codebase. Checks TypeScript errors, silent catches, console.log, any types, backend unwraps, hardcoded creds, and server health. Use when user says "sweep", "quality check", "run sweep", or "check violations".
+---
+
 # Skill: Quality Sweep
 
 Full automated quality sweep across the entire codebase. Detects regressions, violations, and quality issues. This is the overnight watchdog.
diff --git a/.gitea/workflows/nightly-security.yml b/.gitea/workflows/nightly-security.yml
new file mode 100644
index 00000000..9f3b4e37
--- /dev/null
+++ b/.gitea/workflows/nightly-security.yml
@@ -0,0 +1,45 @@
+name: Nightly Security Review
+on:
+  schedule:
+    - cron: '47 1 * * *'
+  workflow_dispatch:
+
+jobs:
+  security-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Run security review on recent changes
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          CHANGED=$(git diff --name-only HEAD~1..HEAD 2>/dev/null || echo "")
+          if [ -z "$CHANGED" ]; then
+            echo "No recent changes to review"
+            exit 0
+          fi
+
+          claude --print "Run a security review focused on these recently changed files:
+          $CHANGED
+
+          Check for:
+          - Constant-time comparison violations in crypto code
+          - Private key material in logs or error messages
+          - Floating-point Bitcoin amounts (must be integer sats)
+          - eval() or unsafe blocks without SAFETY comments
+          - Hardcoded credentials or secrets
+          - Missing input validation at API boundaries
+
+          Output a structured report with severity levels.
+          If any CRITICAL issues found, exit with code 1." > security-report.txt 2>&1
+
+          cat security-report.txt
+
+          if grep -qi "critical" security-report.txt; then
+            echo "::error::Critical security issues found — review security-report.txt"
+            exit 1
+          fi
diff --git a/.gitea/workflows/weekly-dep-audit.yml b/.gitea/workflows/weekly-dep-audit.yml
new file mode 100644
index 00000000..4d1def41
--- /dev/null
+++ b/.gitea/workflows/weekly-dep-audit.yml
@@ -0,0 +1,29 @@
+name: Weekly Dependency Audit
+on:
+  schedule:
+    - cron: '13 2 * * 0'
+  workflow_dispatch:
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Rust dependency audit
+        run: |
+          cargo install cargo-audit 2>/dev/null || true
+          echo "=== Cargo Audit ==="
+          cargo audit 2>&1 | tee cargo-audit.txt || true
+
+          echo ""
+          echo "=== Version Pinning Check ==="
+          grep -n '"\*"' Cargo.toml || echo "No wildcard versions found"
+
+      - name: Check for critical vulnerabilities
+        run: |
+          if grep -qi "RUSTSEC.*critical\|vulnerability found" cargo-audit.txt 2>/dev/null; then
+            echo "::error::Critical Rust dependency vulnerabilities found"
+            exit 1
+          fi
+          echo "No critical vulnerabilities detected"