kastell 2.2.0 → 2.2.1

package/kastell-plugin/skills/kastell-ops/references/patterns.md

@@ -0,0 +1,145 @@
+# Kastell Patterns
+
+## Do / Don't
+
+| Do                                                                    | Don't                                                              |
+|-----------------------------------------------------------------------|--------------------------------------------------------------------|
+| Put all business logic in `src/core/`                                 | Put logic in `src/commands/` — commands are thin wrappers only    |
+| Use `getAdapter(platform)` from `factory.ts`                          | Import `CoolifyAdapter` / `DokployAdapter` directly in commands   |
+| Use `adapter.port`, `adapter.defaultLogService`, `adapter.platformPorts` | Hardcode port numbers (8000, 3000) in command files            |
+| Use `withProviderErrorHandling` HOF for provider operations           | Write per-command try/catch around provider API calls             |
+| Use `assertValidIp()` before every SSH operation                      | Call `sshExec` without IP validation                              |
+| Use `sanitizedEnv` for subprocess calls                               | Pass raw `process.env` to child processes                         |
+| Use `sanitizeResponseData()` for API error responses                  | Leak raw API error objects to the user                            |
+| Use `createMockAdapter()` from `tests/helpers/mockAdapter.ts`         | Write inline `{ healthCheck: jest.fn() }` objects in tests        |
+| Batch SSH commands (fast config + slow probes) in audit operations    | Call `sshExec` multiple times fetching overlapping data           |
+| Return plain data objects from `src/core/` functions                  | Import `chalk` or `ora` in `src/core/` files                      |
+| Use `jest.resetAllMocks()` with `describe.each`                       | Use `clearAllMocks()` with `describe.each` (causes cross-test bleed) |
+
+## Testing Patterns
+
+### Pattern 1: Mock Adapter Factory
+
+Use `createMockAdapter()` from `tests/helpers/mockAdapter.ts`. Never write inline mock adapter objects.
+
+```typescript
+import { createMockAdapter } from '../../tests/helpers/mockAdapter.js';
+
+// Basic usage — gets correct defaults for the platform
+const adapter = createMockAdapter({ name: 'coolify' });
+// adapter.port === 8000, adapter.defaultLogService === 'coolify'
+
+// Override specific methods
+const adapter = createMockAdapter({
+  name: 'dokploy',
+  overrides: {
+    healthCheck: jest.fn(async () => ({ status: 'not reachable' as const })),
+  },
+});
+
+// In the test — inject via jest.mock or direct parameter
+jest.mock('../../src/adapters/factory.js', () => ({
+  getAdapter: jest.fn(() => adapter),
+  resolvePlatform: jest.fn(() => 'coolify'),
+}));
+```
+
+### Pattern 2: SSH Mock
+
+Mock `sshExec` at the module level. Use `mockResolvedValueOnce` for sequential calls.
+
+```typescript
+import { sshExec } from '../../src/utils/ssh.js';
+jest.mock('../../src/utils/ssh.js');
+const mockSshExec = sshExec as jest.MockedFunction<typeof sshExec>;
+
+// Single call
+mockSshExec.mockResolvedValueOnce({ code: 0, stdout: 'active', stderr: '' });
+
+// Multiple sequential calls (batch grouping pattern)
+mockSshExec
+  .mockResolvedValueOnce({ code: 0, stdout: 'ufw active', stderr: '' })  // fast config
+  .mockResolvedValueOnce({ code: 0, stdout: '{"load": 0.5}', stderr: '' }); // slow probe
+```
+
+### Pattern 3: MCP Handler Test
+
+Import the handler directly and call it with the expected parameters. Assert on `result.content[0].text`.
+
+```typescript
+import { handleServerAudit } from '../serverAudit.js';
+
+// Mock the core dependency
+jest.mock('../../src/core/audit/runner.js');
+import { runAudit } from '../../src/core/audit/runner.js';
+const mockRunAudit = runAudit as jest.MockedFunction<typeof runAudit>;
+
+describe('handleServerAudit', () => {
+  beforeEach(() => jest.resetAllMocks());
+
+  it('returns audit results', async () => {
+    mockRunAudit.mockResolvedValueOnce({ score: 85, checks: [] });
+
+    const result = await handleServerAudit({
+      server: 'test-server',
+      category: 'ssh',
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain('85');
+  });
+
+  it('returns error on failure', async () => {
+    mockRunAudit.mockRejectedValueOnce(new Error('SSH timeout'));
+
+    const result = await handleServerAudit({ server: 'test-server' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('SSH timeout');
+  });
+});
+```
+
+### Pattern 4: Command Test (mock core, not low-level deps)
+
+Test commands by mocking the core module — not `sshExec`, not providers. This verifies delegation.
+
+```typescript
+jest.mock('../../src/core/backup.js');
+import { backupServer } from '../../src/core/backup.js';
+const mockBackupServer = backupServer as jest.MockedFunction<typeof backupServer>;
+
+describe('backup command', () => {
+  beforeEach(() => jest.resetAllMocks());
+
+  it('delegates to backupServer core function', async () => {
+    mockBackupServer.mockResolvedValueOnce({
+      success: true,
+      backupPath: '/home/user/.kastell/backups/myserver',
+    });
+
+    // Execute command action directly (Commander action callback)
+    await backupAction({ server: 'myserver' });
+
+    expect(mockBackupServer).toHaveBeenCalledWith('myserver');
+  });
+});
+```
+
+## Core Function Signature Conventions
+
+Core functions return typed result objects, never throw to the caller:
+
+```typescript
+// Pattern: return { success, data?, error?, hint? }
+export async function exampleCore(server: string): Promise<ExampleResult> {
+  try {
+    const record = getServerRecord(server); // throws if not found
+    assertValidIp(record.ip);               // throws if invalid
+    // ... business logic ...
+    return { success: true, data: result };
+  } catch (err) {
+    return { success: false, error: String(err) };
+  }
+}
+```

package/kastell-plugin/skills/kastell-ops/references/pitfalls.md

@@ -0,0 +1,136 @@
+# Kastell Pitfalls
+
+Known traps, symptoms, and fixes. Severity: HIGH (blocks correct behavior), MEDIUM (causes test/maintenance pain), LOW (minor inconsistency).
+
+---
+
+## 1. Adapter Bypass (HIGH)
+
+**Symptom:** `if (server.platform === 'coolify') { port = 8000 } else { port = 3000 }` in `src/commands/`
+
+**Root cause:** Command accesses platform properties directly instead of using the adapter.
+
+**Fix:** Use `getAdapter(platform)` from `factory.ts` and read `adapter.port`, `adapter.defaultLogService`, `adapter.platformPorts`.
+
+```typescript
+// WRONG
+const port = server.platform === 'coolify' ? 8000 : 3000;
+
+// CORRECT
+import { getAdapter } from '../../src/adapters/factory.js';
+const adapter = getAdapter(server.platform);
+const port = adapter.port;
+```
+
+---
+
+## 2. Business Logic in Commands (HIGH)
+
+**Symptom:** Complex calculations, API calls, try/catch blocks, or SSH calls in `src/commands/*.ts`.
+
+**Root cause:** Logic was not extracted to `src/core/`.
+
+**Fix:** Extract all logic to a new `src/core/<name>.ts` function. Command only calls core and displays the result.
+
+---
+
+## 3. UI in Core (HIGH)
+
+**Symptom:** `chalk.green(...)`, `ora('...').start()`, or `console.log()` in `src/core/*.ts`.
+
+**Root cause:** Core function was handling display instead of returning data.
+
+**Fix:** Core functions return plain data objects. The command layer (or MCP handler) handles display using chalk/ora.
+
+---
+
+## 4. Direct Adapter Import (MEDIUM)
+
+**Symptom:** `import { CoolifyAdapter } from '../../src/adapters/coolify.js'` in a command or core file.
+
+**Root cause:** Bypasses the factory cache and breaks the abstraction boundary.
+
+**Fix:** Always use `getAdapter(platform)` from `src/adapters/factory.ts`.
+
+---
+
+## 5. Inline Adapter Mocks in Tests (MEDIUM)
+
+**Symptom:** `const adapter = { healthCheck: jest.fn(), port: 8000, ... }` scattered across test files.
+
+**Root cause:** Not using the centralized mock factory.
+
+**Fix:** Use `createMockAdapter()` from `tests/helpers/mockAdapter.ts`. When the `PlatformAdapter` interface gains new methods, only `mockAdapter.ts` needs updating.
+
+---
+
+## 6. SSH Batch Grouping (MEDIUM)
+
+**Symptom:** Audit or health commands call `sshExec` 4-6 times sequentially, each fetching partially overlapping data.
+
+**Root cause:** Each check independently fetches data instead of using shared batched results.
+
+**Fix:** Batch fast config commands together (single SSH call), batch slow probe commands together. Use head limits appropriate to the data volume (e.g., `head -50` for audit log checks).
+
+---
+
+## 7. Jest requireActual Crash (MEDIUM)
+
+**Symptom:** Tests crash on Node v24+ with an error related to `jest.requireActual`.
+
+**Root cause:** `jest.requireActual` behavior changed in Node v24.
+
+**Fix:** Use inline `jest.fn()` mocks instead of `jest.requireActual`. For module-level mocks, use `jest.mock()` with a factory function.
+
+---
+
+## 8. Module-Level Side Effects (MEDIUM)
+
+**Symptom:** Test imports a module that registers listeners or modifies globals at load time, causing unexpected behavior when other tests run.
+
+**Root cause:** Module has top-level side effects (e.g., `process.on('SIGINT', ...)` at module scope).
+
+**Fix:** Mock the module in ALL test files that import it, not just the direct test file. Side effects occur at import time.
+
+---
+
+## 9. Hardcoded Port Numbers (LOW)
+
+**Symptom:** `8000` or `3000` literals appear in `src/commands/` or `src/core/` files.
+
+**Root cause:** Port copied from constants instead of read from adapter.
+
+**Fix:** Use `adapter.port` for platform HTTP port, `adapter.platformPorts` for firewall protection list.
+
+---
+
+## 10. PROVIDER_REGISTRY Mismatch (LOW)
+
+**Symptom:** New provider works via direct code path but fails CLI validation, completion, or `--provider` flag parsing.
+
+**Root cause:** Provider added to `src/providers/` but not added to `PROVIDER_REGISTRY` in `src/constants.ts`.
+
+**Fix:** Always add to `PROVIDER_REGISTRY` first — it is the single source of truth for provider enumeration, validation, and display.
+
+---
+
+## 11. SSH Timeout Too Short (LOW)
+
+**Symptom:** Long-running commands (lock, audit, update) fail silently or with cryptic timeout errors.
+
+**Root cause:** Default SSH timeout (30s) is insufficient for operations like platform update (~3 minutes).
+
+**Fix:** Use 180s timeout for slow operations:
+```typescript
+await sshExec(ip, command, { timeout: 180_000 });
+```
+
+---
+
+## 12. describe.each + clearAllMocks (LOW)
+
+**Symptom:** Tests pass individually but fail when the full suite runs. Mock call counts are wrong in later tests.
+
+**Root cause:** `jest.clearAllMocks()` clears call history but does not reset mock implementations. `describe.each` reuses the same mock instance across parameterized runs.
+
+**Fix:** Use `jest.resetAllMocks()` in `beforeEach` when using `describe.each`. This resets both call history and implementations.

package/kastell-plugin/skills/kastell-ops/scripts/check_coverage.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# check_coverage.sh — Compare audit check count vs test count.
+# Usage: bash check_coverage.sh [project-root]
+#
+# Counts audit checks defined in src/core/audit/checks/ and matching tests.
+# Requires: node
+
+set -euo pipefail
+
+PROJECT_ROOT="${1:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+node -e "
+const fs = require('fs');
+const path = require('path');
+
+const root = process.argv[1];
+const checksDir = path.join(root, 'src', 'core', 'audit', 'checks');
+
+if (!fs.existsSync(checksDir)) {
+  console.error('Error: ' + checksDir + ' not found');
+  process.exit(1);
+}
+
+// Read all .ts files in checks dir (excluding index.ts)
+const checkFiles = fs.readdirSync(checksDir)
+  .filter(f => f.endsWith('.ts') && f !== 'index.ts');
+
+let totalChecks = 0;
+const uniqueIds = new Set();
+const perFile = [];
+
+for (const file of checkFiles) {
+  const content = fs.readFileSync(path.join(checksDir, file), 'utf8');
+  const ids = [...content.matchAll(/id:\s*['\"]([^'\"]+)['\"]/g)].map(m => m[1]);
+  totalChecks += ids.length;
+  ids.forEach(id => uniqueIds.add(id));
+  perFile.push({ name: file.replace('.ts', ''), checks: ids.length });
+}
+
+// Count categories from index.ts
+let categories = 0;
+const indexPath = path.join(checksDir, 'index.ts');
+if (fs.existsSync(indexPath)) {
+  const indexContent = fs.readFileSync(indexPath, 'utf8');
+  categories = (indexContent.match(/sectionName/g) || []).length;
+}
+
+// Find audit test files recursively
+function findTests(dir) {
+  let count = 0;
+  if (!fs.existsSync(dir)) return 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) count += findTests(full);
+    else if (entry.name.endsWith('.test.ts') && entry.name.includes('audit') ||
+             full.includes('audit') && entry.name.endsWith('.test.ts')) {
+      count++;
+    }
+  }
+  return count;
+}
+const testCount = findTests(path.join(root, 'src'));
+
+// Pre-index all test file contents once (avoids N+1 file reads)
+const testIndex = new Set();
+function indexTests(dir) {
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) indexTests(full);
+      else if (entry.name.endsWith('.test.ts')) {
+        const content = fs.readFileSync(full, 'utf8');
+        // Extract referenced module names from imports and test descriptions
+        for (const match of content.matchAll(/['\"]([^'\"]*audit[^'\"]*)['\"]|from\s+['\"]([^'\"]+)['\"]/g)) {
+          const ref = match[1] || match[2] || '';
+          ref.split('/').forEach(part => testIndex.add(part.replace('.js', '').replace('.ts', '')));
+        }
+      }
+    }
+  } catch {}
+}
+indexTests(path.join(root, 'src'));
+function hasTestFor(name) { return testIndex.has(name); }
+
+console.log('=== Audit Check Coverage ===');
+console.log('Project: ' + root);
+console.log('');
+console.log('Check source files: ' + checkFiles.length);
+console.log('Categories:         ' + categories);
+console.log('Checks defined:     ' + totalChecks);
+console.log('Unique check IDs:   ' + uniqueIds.size);
+console.log('Audit test files:   ' + testCount);
+console.log('');
+console.log('Per-file breakdown:');
+
+perFile.sort((a, b) => a.name.localeCompare(b.name));
+for (const f of perFile) {
+  const tested = hasTestFor(f.name) ? '✓' : '✗';
+  console.log('  ' + tested + ' ' + f.name.padEnd(20) + ' ' + String(f.checks).padStart(3) + ' checks');
+}
+" "$PROJECT_ROOT"

package/kastell-plugin/skills/kastell-ops/scripts/fleet_report.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# fleet_report.sh — Generate a fleet-wide server score table.
+# Usage: kastell fleet --json | bash fleet_report.sh
+#    OR: bash fleet_report.sh < fleet-output.json
+#    OR: bash fleet_report.sh fleet-output.json
+#
+# Requires: node
+
+set -euo pipefail
+
+if [[ -n "${1:-}" && -f "$1" ]]; then
+  INPUT=$(cat "$1")
+elif [[ ! -t 0 ]]; then
+  INPUT=$(cat)
+else
+  echo "Usage: kastell fleet --json | bash fleet_report.sh" >&2
+  exit 1
+fi
+
+node -e "
+const data = JSON.parse(process.argv[1]);
+const servers = data.servers || data.fleet || data || [];
+
+if (!Array.isArray(servers) || servers.length === 0) {
+  console.log('No servers found in fleet data.');
+  process.exit(0);
+}
+
+// Header
+const cols = { name: 20, ip: 16, provider: 12, mode: 8, score: 6, health: 10 };
+const pad = (s, n) => String(s || '-').slice(0, n).padEnd(n);
+const sep = '-'.repeat(Object.values(cols).reduce((a, b) => a + b + 3, 0));
+
+console.log('=== Kastell Fleet Report ===');
+console.log('Servers: ' + servers.length);
+console.log('');
+console.log(
+  pad('Name', cols.name) + ' | ' +
+  pad('IP', cols.ip) + ' | ' +
+  pad('Provider', cols.provider) + ' | ' +
+  pad('Mode', cols.mode) + ' | ' +
+  pad('Score', cols.score) + ' | ' +
+  pad('Health', cols.health)
+);
+console.log(sep);
+
+// Sort by score (lowest first = needs attention)
+const sorted = [...servers].sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
+
+for (const s of sorted) {
+  const score = s.score ?? s.auditScore ?? '-';
+  const health = s.health ?? s.status ?? '-';
+  const icon = health === 'ONLINE' ? '●' : health === 'DEGRADED' ? '◐' : '○';
+  console.log(
+    pad(s.name, cols.name) + ' | ' +
+    pad(s.ip, cols.ip) + ' | ' +
+    pad(s.provider, cols.provider) + ' | ' +
+    pad(s.mode, cols.mode) + ' | ' +
+    pad(score, cols.score) + ' | ' +
+    icon + ' ' + pad(health, cols.health - 2)
+  );
+}
+
+// Summary
+const scores = sorted.map(s => s.score ?? s.auditScore).filter(s => typeof s === 'number');
+if (scores.length > 0) {
+  const avg = Math.round(scores.reduce((a, b) => a + b, 0) / scores.length);
+  const min = Math.min(...scores);
+  const max = Math.max(...scores);
+  console.log('');
+  console.log('Avg: ' + avg + ' | Min: ' + min + ' | Max: ' + max);
+}
+" "$INPUT"

package/kastell-plugin/skills/kastell-ops/scripts/parse_audit.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# parse_audit.sh — Parse kastell audit JSON into 5 security domain summaries.
+# Usage: kastell audit --server <name> --json | bash parse_audit.sh
+#    OR: bash parse_audit.sh < audit-output.json
+#    OR: bash parse_audit.sh audit-output.json
+#
+# Requires: node (uses inline JS for JSON parsing — no jq dependency)
+
+set -euo pipefail
+
+# Read JSON from file arg, stdin, or pipe
+if [[ -n "${1:-}" && -f "$1" ]]; then
+  INPUT=$(cat "$1")
+elif [[ ! -t 0 ]]; then
+  INPUT=$(cat)
+else
+  echo "Usage: kastell audit --server <name> --json | bash parse_audit.sh" >&2
+  echo "   OR: bash parse_audit.sh <audit-json-file>" >&2
+  exit 1
+fi
+
+node -e "
+const data = JSON.parse(process.argv[1]);
+const checks = data.checks || data.results || [];
+
+// 5 security domain mapping
+const DOMAINS = {
+  'Perimeter':       ['Network', 'Firewall', 'DNS Security'],
+  'Authentication':  ['SSH', 'Auth', 'Crypto', 'Accounts'],
+  'Runtime':         ['Docker', 'Services', 'Boot', 'Scheduling'],
+  'Internals':       ['Filesystem', 'Logging', 'Kernel', 'Memory'],
+  'Compliance':      ['Updates', 'File Integrity', 'Malware', 'MAC', 'Secrets',
+                      'Cloud Metadata', 'Supply Chain', 'Backup Hygiene',
+                      'Resource Limits', 'Incident Readiness', 'Banners', 'Time',
+                      'TLS', 'HTTP Security Headers'],
+};
+
+// Map categories to domains
+const catToDomain = {};
+for (const [domain, cats] of Object.entries(DOMAINS)) {
+  for (const cat of cats) catToDomain[cat.toLowerCase()] = domain;
+}
+
+// Bucket checks
+const buckets = {};
+for (const d of Object.keys(DOMAINS)) buckets[d] = { passed: 0, failed: 0, critical: [] };
+
+for (const c of checks) {
+  const cat = (c.category || '').toLowerCase();
+  let domain = 'Compliance'; // default
+  for (const [key, val] of Object.entries(catToDomain)) {
+    if (cat.includes(key)) { domain = val; break; }
+  }
+  if (c.passed) buckets[domain].passed++;
+  else {
+    buckets[domain].failed++;
+    if (c.severity === 'critical') buckets[domain].critical.push(c.id || c.name);
+  }
+}
+
+// Output
+const score = data.score ?? data.overallScore ?? 'N/A';
+console.log('=== Kastell Audit Domain Summary ===');
+console.log('Overall Score: ' + score + '/100');
+console.log('');
+
+for (const [domain, b] of Object.entries(buckets)) {
+  const total = b.passed + b.failed;
+  const pct = total > 0 ? Math.round(b.passed / total * 100) : 0;
+  const bar = '█'.repeat(Math.round(pct / 5)) + '░'.repeat(20 - Math.round(pct / 5));
+  console.log(domain + ': ' + b.passed + '/' + total + ' (' + pct + '%) ' + bar);
+  if (b.critical.length > 0) {
+    console.log('  Critical: ' + b.critical.slice(0, 3).join(', '));
+  }
+}
+" "$INPUT"

package/kastell-plugin/skills/kastell-research/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: kastell-research
+description: Read-only Kastell codebase exploration. Use when tracing a bug across files, mapping callsites before refactoring, or exploring unfamiliar subsystems. Runs in isolated context with Explore agent.
+context: fork
+agent: Explore
+allowed-tools: Read, Grep, Glob
+effort: medium
+memory: project
+---
+
+# Kastell Research
+
+## Purpose
+
+Explore the Kastell codebase using read-only tools (Read, Grep, Glob). Runs in a forked Explore agent with Kastell architecture knowledge inlined.
+
+## When to Use
+
+- **Bug investigation:** Trace a bug from CLI command through core logic to adapters/providers. Start at the command file, follow imports to core, check utils and adapters.
+- **Feature mapping:** Map all callsites of a function, trace the import chain, understand how subsystems connect before making changes.
+- **Architecture question:** Understand how audit categories work, how the adapter dispatch flows, or how lock hardening steps are structured.
+
+## Live Codebase
+
+**Commands:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/commands').filter(x=>x.endsWith('.ts')).map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('commands dir not found'))"`
+**Provider registry:**
+!`node -e "import('fs').then(f=>{const c=f.readFileSync('src/constants.ts','utf8');const m=c.match(/PROVIDER_REGISTRY[\s\S]{0,200}/);console.log(m?m[0].split('\n').slice(0,4).join('\n'):'not found')}).catch(()=>console.log('constants.ts not found'))"`
+
+## Architecture Map
+
+```
+src/
+  commands/     # 31 thin CLI wrappers (parse args + delegate only)
+  core/         # Business logic (ALL computation here)
+    audit/      # 30 audit categories, 457+ checks
+    lock/       # 24-step server hardening
+  providers/    # Cloud API: hetzner, digitalocean, vultr, linode
+  adapters/     # Platform abstraction: coolify, dokploy
+    factory.ts  # getAdapter(platform) — entry point
+  mcp/
+    server.ts   # 13 tool registrations
+    tools/      # Handler files
+  utils/        # ssh, config, cloudInit, modeGuard
+  types/        # ServerMode, ServerRecord, Platform
+  constants.ts  # PROVIDER_REGISTRY
+```
+
+## Layer Flow
+
+Commands (parse args) --> Core (business logic) --> Providers (cloud API) / Adapters (platform ops). MCP tools also delegate to Core.
+
+## Research Workflows
+
+**Bug investigation:**
+1. Find the command file (`src/commands/<name>.ts`)
+2. Follow the core import (`src/core/<name>.ts`)
+3. Check adapter/provider calls
+4. Check utils (ssh, config)
+
+**Feature mapping:**
+1. Grep for the function name
+2. Follow import chain
+3. Map all callsites
+4. Check test coverage in `__tests__/`
+
+**Architecture question:**
+1. Read the Architecture Map above
+2. Read `kastell-plugin/skills/kastell-ops/SKILL.md` for full detail (adapter contract, provider registry, layer rules)
+3. Trace specific files
+
+## Debug by Symptom
+
+Common failure patterns and where to look first:
+
+| Symptom | Start Here | Then Check |
+|---------|-----------|------------|
+| SSH auth failure | `src/utils/ssh.ts` → `sshExec()` | `assertValidIp()`, server config `~/.kastell/servers.json`, banner parsing |
+| Provider API error | `src/providers/<name>.ts` | `withProviderErrorHandling()` in `src/utils/retry.ts`, API token config |
+| Audit check false positive | `src/core/audit/checks/<category>.ts` | SSH command output parsing, regex pattern, `sshExec` mock in test |
+| Fix rejected (SAFE tier) | `src/core/fix.ts` → `resolveTier()` | `FORBIDDEN_PATTERNS`, shell redirect/pipe in fixCommand string |
+| MCP tool error | `src/mcp/tools/<name>.ts` | Handler → core delegation, Zod schema validation, `result.content` format |
+| Lock step failure | `src/core/lock.ts` | Step's SSH command, `sshExec` stderr, cloud-init completion |
+| Config not found | `src/utils/config.ts` | `~/.kastell/` dir existence, `servers.json` format, migration from `~/.quicklify/` |
+
+**Known pitfalls:** See `kastell-plugin/skills/kastell-ops/references/pitfalls.md`
+
+## ARGUMENTS
+
+$ARGUMENTS