@sibyllinesoft/smith-installer 0.1.1

package/skills/detect-system/SKILL.md

@@ -0,0 +1,69 @@
+---
+description: Detect local system capabilities required for Smith Core installation
+---
+# Detect System
+
+Run:
+
+```bash
+uname -a
+node -v
+docker --version
+docker compose version
+cargo --version
+
+if [ "$(uname -s)" = "Darwin" ]; then
+  command -v gondolin
+  gondolin help >/dev/null
+fi
+```
+
+## What It Does
+
+This skill gathers the minimum environment facts needed before bootstrap.
+
+1. Confirms host OS/kernel information.
+2. Confirms Node.js runtime availability.
+3. Confirms Docker engine and Compose plugin availability.
+4. Confirms Rust toolchain availability.
+5. On macOS, confirms Gondolin is installed for persistent VM sandbox mode.
+6. Establishes whether the machine can run the standard Smith Core flow.
+
+## Prerequisites
+
+- Shell access in the `smith-core` repository.
+- `bash` available.
+
+## Expected Output
+
+Successful environment output includes:
+
+```text
+Linux ...
+v22.x.x
+Docker version ...
+Docker Compose version ...
+cargo 1.xx.x ...
+/usr/bin/gondolin   # macOS only
+```
+
+## Reading Results
+
+- Missing `node` means installer and Node workspaces cannot run.
+- Missing `docker compose` means infrastructure cannot start.
+- Missing `cargo` means Rust services cannot build from source.
+- On macOS, missing `gondolin` means persistent VM sandbox sessions cannot start.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `node: command not found` | Node.js missing | Install Node 22+ |
+| `docker: command not found` | Docker missing | Install Docker engine |
+| `docker compose` unknown command | Compose plugin missing | Install Docker Compose plugin |
+| `cargo: command not found` | Rust toolchain missing | Install Rust via rustup |
+| `gondolin: command not found` (macOS) | Gondolin missing | Install Gondolin and verify `gondolin help` works |
+
+## Notes
+
+This skill is diagnostic only. It does not install packages automatically.

package/skills/generate-certs/SKILL.md

@@ -0,0 +1,54 @@
+---
+description: Generate local mTLS certificates for the Envoy gateway
+---
+# Generate Certs
+
+Run:
+
+```bash
+bash infra/envoy/certs/generate-certs.sh
+```
+
+## What It Does
+
+This skill generates the mTLS certificate chain used by the local Envoy gateway.
+
+1. Creates a self-signed local CA certificate.
+2. Creates a server certificate for `smith-gateway` / `localhost`.
+3. Creates a client certificate for bridge-side mTLS calls.
+4. Writes outputs to `infra/envoy/certs/generated/`.
+
+## Prerequisites
+
+- `openssl` must be available on PATH.
+- The repo must contain `infra/envoy/certs/generate-certs.sh`.
+
+## Expected Output
+
+The script reports generated artifacts and lists files in:
+
+- `infra/envoy/certs/generated/ca.crt`
+- `infra/envoy/certs/generated/ca.key`
+- `infra/envoy/certs/generated/server.crt`
+- `infra/envoy/certs/generated/server.key`
+- `infra/envoy/certs/generated/client.crt`
+- `infra/envoy/certs/generated/client.key`
+
+## Reading Results
+
+- If files already exist, the script exits successfully without rotating certs.
+- Set `SMITH_FORCE_CERTS=1` to regenerate certificates intentionally.
+- These certs are mounted into `envoy` by `docker-compose.yaml`.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `openssl: command not found` | OpenSSL missing | Install OpenSSL via package manager |
+| `Permission denied` writing files | Directory ownership/permissions issue | Fix permissions for `infra/envoy/certs/generated` |
+| Envoy TLS startup error after generation | Corrupted or partial cert set | Re-run with `SMITH_FORCE_CERTS=1` |
+| Client handshake fails | Client cert paths not wired in runtime env | Set `CLIENT_CERT`, `CLIENT_KEY`, `CA_CERT` correctly |
+
+## Notes
+
+For local single-user deployments, generated certs are development trust material and should not be reused across public environments.

package/skills/generate-pairing-code/SKILL.md

@@ -0,0 +1,87 @@
+---
+description: Generate a pairing code for DM authentication with the chat bridge
+---
+# Generate Pairing Code
+
+Run these read-only inspection commands to understand the current state:
+
+```bash
+# Check DM policy
+grep '^CHAT_BRIDGE_DM_POLICY=' .env 2>/dev/null || echo "CHAT_BRIDGE_DM_POLICY=pairing (default)"
+
+# Check if admin token is set
+grep -q '^CHAT_BRIDGE_ADMIN_TOKEN=.' .env 2>/dev/null && echo "ADMIN_TOKEN_SET" || echo "NO_ADMIN_TOKEN"
+
+# Check webhook port
+grep '^CHAT_BRIDGE_WEBHOOK_PORT=' .env 2>/dev/null || echo "CHAT_BRIDGE_WEBHOOK_PORT=8092 (default)"
+
+# Check if daemon is running
+pgrep -f smith-chat-daemon && echo "DAEMON_RUNNING" || echo "DAEMON_NOT_RUNNING"
+```
+
+## What It Does
+
+This skill generates a short-lived pairing code that a user sends as a DM to the bot on their chat platform. The daemon validates the code and pairs the sender's chat identity with an agent, authorizing future DM conversations.
+
+Pairing codes are 6 alphanumeric characters, uppercase, and expire after 5 minutes (`CHAT_BRIDGE_PAIRING_CODE_TTL`, default 300 seconds).
+
+## Prerequisites
+
+- **DM policy must be `pairing`** (the default). If `CHAT_BRIDGE_DM_POLICY` is set to `open` or `allowlist`, pairing codes are not needed — inform the user and skip.
+- **Daemon must be running.** If not, tell the user to run the `start-chat-bridge` skill first.
+- **Admin token must be set.** If `CHAT_BRIDGE_ADMIN_TOKEN` is empty or missing, generate one:
+
+```bash
+grep -q '^CHAT_BRIDGE_ADMIN_TOKEN=.' .env || echo "CHAT_BRIDGE_ADMIN_TOKEN=$(openssl rand -hex 32)" >> .env
+```
+
+Note: if you set the admin token after the daemon started, the daemon must be restarted to pick up the new value.
+
+## Mutation Command
+
+Generate a pairing code:
+
+```bash
+curl -s -X POST "http://localhost:${CHAT_BRIDGE_WEBHOOK_PORT:-8092}/admin/pairing-codes" \
+  -H "Authorization: Bearer ${CHAT_BRIDGE_ADMIN_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"agent_id\": \"${AGENT_ID:-smith-default}\"}"
+```
+
+The response contains the pairing code:
+
+```json
+{
+  "code": "A1B2C3",
+  "agent_id": "smith-default",
+  "expires_in_secs": 300
+}
+```
+
+## User Instructions
+
+After generating the code, tell the user:
+
+> Send this 6-character code as a DM to the bot on your chat platform to pair. The code expires in 5 minutes. Once paired, you can chat with the agent directly via DM.
+
+## Expected Output
+
+- A JSON response with `code`, `agent_id`, and `expires_in_secs`.
+- The user can then DM the code to the bot to complete pairing.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `DAEMON_NOT_RUNNING` | Daemon not started | Run `start-chat-bridge` skill first |
+| `NO_ADMIN_TOKEN` | Admin token not configured | Generate one and add to `.env`, restart daemon |
+| `401 Unauthorized` | Token mismatch | Ensure `.env` token matches what daemon loaded (restart daemon after changes) |
+| `connection refused` on curl | Daemon not listening on expected port | Check `CHAT_BRIDGE_WEBHOOK_PORT` and daemon logs |
+| Code not accepted by bot | Code expired (>5 min) or already redeemed | Generate a new code |
+| `pairing` not required | DM policy is `open` or `allowlist` | No action needed; DMs are already authorized |
+
+## Notes
+
+- Each code can only be redeemed once.
+- Active pairings expire after `CHAT_BRIDGE_PAIRING_TTL` seconds (default 86400 = 24 hours).
+- To change the DM policy, set `CHAT_BRIDGE_DM_POLICY` in `.env` to `pairing`, `allowlist`, or `open` and restart the daemon.

package/skills/install-agentd/SKILL.md

@@ -0,0 +1,46 @@
+---
+description: Build and validate the agentd workspace from source
+---
+# Install Agentd
+
+Run:
+
+```bash
+cargo build --manifest-path agent/agentd/Cargo.toml --features grpc --bin agentd
+```
+
+## What It Does
+
+This skill prepares the `agentd` binary from source.
+
+1. Compiles `agent/agentd` and internal crates.
+2. Ensures gRPC support is included (`--features grpc`).
+3. Produces a runnable `agentd` binary for Envoy transcoding flows.
+4. Validates crate path wiring in the extracted repo.
+
+## Prerequisites
+
+- Rust toolchain installed.
+- Cargo dependency resolution functional.
+
+## Expected Output
+
+`cargo build --manifest-path agent/agentd/Cargo.toml --features grpc --bin agentd` finishes successfully.
+
+## Reading Results
+
+- Compile errors indicate source/API drift in `agentd` components.
+- Successful build enables `cargo run --manifest-path agent/agentd/Cargo.toml --features grpc --bin agentd -- run ...`.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Dependency fetch failures | Network issue | Retry when registry/network is available |
+| Compile errors | Code mismatch | Fix code and re-run build |
+| Toolchain mismatch | Old Rust version | Update to current stable toolchain |
+| Linker errors | Missing system build deps | Install compiler/linker prerequisites |
+
+## Notes
+
+This is source-build based; no separate package installer is required.

package/skills/install-runtime/SKILL.md

@@ -0,0 +1,49 @@
+---
+description: Validate container runtime availability for Smith Core services
+---
+# Install Runtime
+
+Run:
+
+```bash
+docker --version
+docker compose version
+```
+
+## What It Does
+
+This skill validates runtime prerequisites for the infrastructure stack.
+
+1. Confirms Docker engine availability.
+2. Confirms Compose plugin availability.
+3. Blocks bootstrap early if runtime prerequisites are missing.
+4. Keeps installer behavior deterministic.
+
+## Prerequisites
+
+- Docker installed on host.
+- Active user has permission to run Docker commands.
+
+## Expected Output
+
+Both commands return version information without errors.
+
+## Reading Results
+
+- If both commands succeed, proceed to stack startup.
+- If either command fails, runtime must be installed/configured first.
+- On macOS, also ensure `gondolin` is installed before enabling persistent VM sessions.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `docker: command not found` | Docker not installed | Install Docker |
+| `permission denied` on daemon socket | User not authorized | Add user to Docker group or use sudo |
+| `docker compose` missing | Compose plugin not installed | Install Docker Compose plugin |
+| Daemon not running | Docker service stopped | Start Docker daemon |
+| `gondolin` missing on macOS | Gondolin not installed | Install Gondolin and confirm `gondolin help` succeeds |
+
+## Notes
+
+Installer does not perform OS-level package installation in this repo version.

package/skills/preflight/SKILL.md

@@ -0,0 +1,86 @@
+---
+description: Collect preflight state for installer decision making
+---
+# Preflight
+
+Run:
+
+```bash
+mkdir -p var/installer
+ENV_SOURCE=".env"
+if [ ! -f "$ENV_SOURCE" ]; then
+  ENV_SOURCE=".env.example"
+fi
+
+read_env_value() {
+  local key="$1"
+  if [ ! -f "$ENV_SOURCE" ]; then
+    echo ""
+    return
+  fi
+  awk -F= -v k="$key" '$1 == k {sub(/^[ \t]+/, "", $2); print $2; exit}' "$ENV_SOURCE"
+}
+
+POSTGRES_PASSWORD="$(read_env_value POSTGRES_PASSWORD)"
+MCP_INDEX_API_TOKEN="$(read_env_value MCP_INDEX_API_TOKEN)"
+CLOUDFLARE_TUNNEL_TOKEN="$(read_env_value CLOUDFLARE_TUNNEL_TOKEN)"
+TAILSCALE_AUTHKEY="$(read_env_value TAILSCALE_AUTHKEY)"
+
+cat > var/installer/preflight.json <<JSON
+{
+  "env_source": "'${ENV_SOURCE}'",
+  "node": "'$(node -v 2>/dev/null || echo missing)'",
+  "docker": "'$(docker --version 2>/dev/null || echo missing)'",
+  "compose": "'$(docker compose version 2>/dev/null || echo missing)'",
+  "cargo": "'$(cargo --version 2>/dev/null || echo missing)'",
+  "postgres_password_default": "'$( [ "${POSTGRES_PASSWORD}" = "smith-dev" ] && echo yes || echo no )'",
+  "mcp_index_token_set": "'$( [ -n "${MCP_INDEX_API_TOKEN}" ] && echo yes || echo no )'",
+  "cloudflare_tunnel_hint": "'$( [ -n "${CLOUDFLARE_TUNNEL_TOKEN}" ] && echo yes || echo no )'",
+  "tailscale_hint": "'$( [ -n "${TAILSCALE_AUTHKEY}" ] && echo yes || echo no )'"
+}
+JSON
+cat var/installer/preflight.json
+```
+
+## What It Does
+
+This skill creates a lightweight local preflight snapshot for the installer agent.
+
+1. Creates `var/installer/` if needed.
+2. Captures key runtime version information.
+3. Writes a JSON state file the agent can reference.
+4. Avoids repeated probing throughout the install session.
+
+## Prerequisites
+
+- Repository write access.
+- Basic shell utilities.
+
+## Expected Output
+
+A JSON document exists at `var/installer/preflight.json` and includes:
+
+- `env_source`
+- `node`
+- `docker`
+- `compose`
+- `cargo`
+- `postgres_password_default`
+- `mcp_index_token_set`
+- `cloudflare_tunnel_hint`
+- `tailscale_hint`
+
+## Reading Results
+
+- Any `missing` value is a hard blocker for full bootstrap.
+- If all values are present, continue with stack startup/build steps.
+- If password defaults or missing private-network hints are detected, continue but emit loud warnings.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Cannot create `var/installer` | Permission issue | Fix directory permissions |
+| Empty JSON values | Command substitution failed | Re-run with full shell output |
+| `cat: ... no such file` | Preflight command not run | Re-run preflight block |
+| Missing tunnel hints | VPN/tunnel env not configured yet | Continue with warning and recommend Cloudflare Tunnel or Tailscale |

package/skills/setup-activitywatch/SKILL.md

@@ -0,0 +1,44 @@
+---
+description: Configure optional ActivityWatch integration guidance for local installs
+---
+# Setup ActivityWatch
+
+Run:
+
+```bash
+echo "ActivityWatch integration is optional in smith-core"
+```
+
+## What It Does
+
+This skill captures optional guidance for ActivityWatch-related tooling.
+
+1. Marks ActivityWatch as non-blocking for core installation.
+2. Prevents installer flow from failing on optional telemetry extras.
+3. Documents that ActivityWatch setup should be explicit and user-driven.
+4. Keeps bootstrap focused on required services.
+
+## Prerequisites
+
+- None; this step can be skipped safely.
+
+## Expected Output
+
+A clear statement that ActivityWatch is optional and skipped by default.
+
+## Reading Results
+
+- If user requires ActivityWatch, configure it separately and then integrate endpoints.
+- If not required, continue directly to build/start/verify steps.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| User expects ActivityWatch by default | Legacy installer assumptions | Clarify it is optional |
+| Missing ActivityWatch MCP server | Not provisioned in repo stack | Add external server configuration |
+| Agent tries to depend on ActivityWatch metrics | Over-eager automation | Keep optional path disabled unless requested |
+
+## Notes
+
+Core Smith Core install success does not depend on ActivityWatch.