@sibyllinesoft/smith-installer 0.1.1

package/skills/setup-chat-bridge/SKILL.md

@@ -0,0 +1,289 @@
+---
+description: Configure chat platform bridges by selecting platforms, collecting credentials, and writing bridge config
+---
+# Setup Chat Bridge
+
+Run these read-only inspection commands to understand the current state:
+
+```bash
+# Check if config already exists
+cat config/chat-bridge.toml 2>/dev/null || echo "NO_CONFIG"
+
+# Check which gateway secrets are already set in .env
+grep -E '^(DISCORD_BOT_TOKEN|TELEGRAM_BOT_TOKEN|SLACK_BOT_TOKEN|SLACK_APP_TOKEN|TEAMS_TENANT_ID|WHATSAPP_ACCESS_TOKEN|MATRIX_ACCESS_TOKEN|SIGNAL_RECIPIENT|MATTERMOST_TOKEN|GOOGLE_CHAT_WEBHOOK_URL)=' .env 2>/dev/null | sed 's/=.*/=<set>/'
+```
+
+## What It Does
+
+This skill interactively configures one or more chat platform bridges by:
+
+1. Asking the user which platforms they want to connect.
+2. Walking them through creating bot credentials on each platform.
+3. Writing `config/chat-bridge.toml` with the correct adapter stanzas.
+4. Setting the required env vars in `.env`.
+
+## Interactive Flow
+
+Ask the user which platform(s) they want to configure. For each selected platform, walk through the setup guide below, collect the credentials, then write config and env vars.
+
+## Platform Setup Guides
+
+### Discord
+
+1. Go to https://discord.com/developers/applications
+2. Click **New Application**, give it a name, click **Create**.
+3. Go to **Bot** in the left sidebar, click **Reset Token**, copy the token.
+4. Under **Privileged Gateway Intents**, enable **Message Content Intent**.
+5. Go to **OAuth2 > URL Generator**, select scopes `bot` + `applications.commands`, permissions `Send Messages` + `Read Message History`.
+6. Open the generated URL to invite the bot to your server.
+
+**Credentials needed:** Bot Token, Application ID (from General Information page)
+
+**TOML stanza:**
+
+```toml
+[[adapters]]
+type = "discord"
+bot_token = "<DISCORD_BOT_TOKEN>"
+application_id = "<APPLICATION_ID>"
+```
+
+**Env vars:** `DISCORD_BOT_TOKEN`
+
+### Telegram
+
+1. Open https://t.me/BotFather in Telegram.
+2. Send `/newbot`, follow prompts to choose a name and username.
+3. Copy the bot token BotFather gives you.
+
+**Credentials needed:** Bot Token
+
+**TOML stanza:**
+
+```toml
+[[adapters]]
+type = "telegram"
+bot_token = "<TELEGRAM_BOT_TOKEN>"
+```
+
+**Env vars:** `TELEGRAM_BOT_TOKEN`
+
+### Slack
+
+1. Go to https://api.slack.com/apps and click **Create New App > From scratch**.
+2. Under **Socket Mode**, enable it and generate an App-Level Token (begins with `xapp-`).
+3. Under **OAuth & Permissions**, add bot scopes: `chat:write`, `channels:history`, `groups:history`, `im:history`, `mpim:history`.
+4. Install the app to your workspace and copy the Bot User OAuth Token (begins with `xoxb-`).
+5. Under **Event Subscriptions**, enable events and subscribe to `message.channels`, `message.groups`, `message.im`, `message.mpim`.
+
+**Credentials needed:** App Token (`xapp-...`), Bot Token (`xoxb-...`)
+
+**TOML stanza:**
+
+```toml
+[[adapters]]
+type = "slack"
+bot_token = "<SLACK_BOT_TOKEN>"
+app_token = "<SLACK_APP_TOKEN>"
+```
+
+**Env vars:** `SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN`
+
+### Microsoft Teams
+
+1. Go to https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps
+2. Click **New registration**, name it, select **Accounts in this organizational directory only**.
+3. Under **Certificates & secrets**, create a new client secret and copy it.
+4. Note the **Application (client) ID** and **Directory (tenant) ID** from the Overview page.
+5. Under **API permissions**, add `ChannelMessage.Read.All`, `ChannelMessage.Send`, `Team.ReadBasic.All` (application permissions), then grant admin consent.
+6. Get the Team ID and Channel ID from Teams (right-click channel > Get link to channel).
+
+**Credentials needed:** Tenant ID, Client ID, Client Secret, Team ID, Channel ID
+
+**TOML stanza:**
+
+```toml
+[[adapters]]
+type = "teams"
+tenant_id = "<TEAMS_TENANT_ID>"
+client_id = "<TEAMS_CLIENT_ID>"
+client_secret = "<TEAMS_CLIENT_SECRET>"
+team_id = "<TEAM_ID>"
+channel_id = "<CHANNEL_ID>"
+```
+
+**Env vars:** `TEAMS_TENANT_ID`, `TEAMS_CLIENT_ID`, `TEAMS_CLIENT_SECRET`
+
+### Mattermost
+
+1. In your Mattermost instance, go to **Integrations > Bot Accounts > Add Bot Account**.
+2. Copy the access token.
+3. Note the Team ID and Channel ID from the channel URL or API.
+
+**Credentials needed:** Base URL (your Mattermost server), Access Token, Team ID, Channel ID
+
+**TOML stanza:**
+
+```toml
+[[adapters]]
+type = "mattermost"
+base_url = "<MATTERMOST_URL>"
+access_token = "<MATTERMOST_TOKEN>"
+team_id = "<TEAM_ID>"
+channel_id = "<CHANNEL_ID>"
+```
+
+**Env vars:** `MATTERMOST_TOKEN`
+
+### WhatsApp
+
+1. Go to https://developers.facebook.com/apps and create a new **Business** app.
+2. Add the **WhatsApp** product.
+3. Under **WhatsApp > API Setup**, copy the temporary Access Token, Phone Number ID, and Business Account ID.
+4. For production, create a System User token with `whatsapp_business_messaging` permission.
+
+**Credentials needed:** Access Token, Phone Number ID, Business Account ID
+
+**TOML stanza:**
+
+```toml
+[[adapters]]
+type = "whatsapp"
+access_token = "<WHATSAPP_ACCESS_TOKEN>"
+phone_number_id = "<PHONE_NUMBER_ID>"
+business_account_id = "<BUSINESS_ACCOUNT_ID>"
+```
+
+**Env vars:** `WHATSAPP_ACCESS_TOKEN`
+
+### Matrix
+
+1. On your Matrix homeserver, create a bot user or use an existing account.
+2. Generate an access token via `curl -XPOST 'https://<homeserver>/_matrix/client/r0/login' -d '{"type":"m.login.password","user":"<username>","password":"<password>"}'`.
+3. Note the homeserver URL, access token, and full user ID (`@user:server`).
+
+**Credentials needed:** Homeserver URL, Access Token, User ID
+
+**TOML stanza:**
+
+```toml
+[[adapters]]
+type = "matrix"
+homeserver_url = "<MATRIX_HOMESERVER>"
+access_token = "<MATRIX_ACCESS_TOKEN>"
+user_id = "<USER_ID>"
+```
+
+**Env vars:** `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN`
+
+### Signal
+
+1. Install `signal-cli` and register or link a phone number.
+2. Run `signal-cli` in daemon/JSON-RPC mode: `signal-cli -u +<NUMBER> daemon --json-rpc`.
+3. The default signal-cli URL is `http://127.0.0.1:8080`.
+
+**Credentials needed:** Phone Number, signal-cli URL (if non-default)
+
+**TOML stanza:**
+
+```toml
+[[adapters]]
+type = "signal"
+phone_number = "<PHONE_NUMBER>"
+signal_cli_url = "http://127.0.0.1:8080"
+```
+
+**Env vars:** `SIGNAL_RECIPIENT`
+
+### Google Chat
+
+1. Go to https://console.cloud.google.com, create or select a project.
+2. Enable the **Google Chat API**.
+3. Create a **Service Account**, download the JSON key file.
+4. In **Google Chat API > Configuration**, configure the bot and note the Space ID.
+
+**Credentials needed:** Path to service account JSON file, Space ID
+
+**TOML stanza:**
+
+```toml
+[[adapters]]
+type = "google_chat"
+service_account_json = "<PATH_TO_SERVICE_ACCOUNT_JSON>"
+space_id = "<SPACE_ID>"
+```
+
+**Env vars:** `GOOGLE_CHAT_WEBHOOK_URL`
+
+### iMessage (via BlueBubbles)
+
+1. Install and run BlueBubbles server on a Mac: https://bluebubbles.app
+2. Note the server URL and server password from BlueBubbles settings.
+
+**Credentials needed:** Server URL, Server Password
+
+**TOML stanza:**
+
+```toml
+[[adapters]]
+type = "imessage"
+server_url = "<BLUEBUBBLES_SERVER_URL>"
+server_password = "<SERVER_PASSWORD>"
+```
+
+**Env vars:** None (config-only)
+
+## Mutation Commands
+
+After collecting credentials from the user, write the config and env vars:
+
+### Write config/chat-bridge.toml
+
+Assemble the file from the selected platform stanzas. Example for Discord + Telegram:
+
+```toml
+[[adapters]]
+type = "discord"
+bot_token = "MTIz..."
+application_id = "1234567890"
+
+[[adapters]]
+type = "telegram"
+bot_token = "7654321:AAH..."
+```
+
+### Set env vars in .env
+
+Use the idempotent pattern (same as `configure-agentd`):
+
+```bash
+grep -q '^CHAT_BRIDGE_CONFIG=' .env || echo 'CHAT_BRIDGE_CONFIG=config/chat-bridge.toml' >> .env
+
+# Generate a random admin token if not already set
+grep -q '^CHAT_BRIDGE_ADMIN_TOKEN=.' .env || echo "CHAT_BRIDGE_ADMIN_TOKEN=$(openssl rand -hex 32)" >> .env
+
+# Per-platform env vars (set for each configured platform)
+grep -q '^DISCORD_BOT_TOKEN=' .env && sed -i 's|^DISCORD_BOT_TOKEN=.*|DISCORD_BOT_TOKEN=<collected-value>|' .env || echo 'DISCORD_BOT_TOKEN=<collected-value>' >> .env
+```
+
+Repeat the `grep -q ... && sed -i ... || echo ...` pattern for each platform-specific env var.
+
+## Prerequisites
+
+- `.env` exists (run `configure-agentd` first if missing).
+- `config/` directory exists.
+
+## Expected Output
+
+- `config/chat-bridge.toml` written with selected adapter stanzas.
+- Platform credentials set in `.env`.
+- `CHAT_BRIDGE_CONFIG` and `CHAT_BRIDGE_ADMIN_TOKEN` set in `.env`.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `.env` does not exist | `configure-agentd` not run | Run `configure-agentd` skill first |
+| `config/` directory missing | Not at repository root | `cd` to smith-core root |
+| Invalid bot token at runtime | Token was revoked or mistyped | Re-run this skill to update credentials |
+| TOML parse error on daemon start | Malformed config | Check quoting in `config/chat-bridge.toml` |

package/skills/start-agentd/SKILL.md

@@ -0,0 +1,55 @@
+---
+description: Start agentd with committed baseline config and verify process health
+---
+# Start Agentd
+
+Run:
+
+```bash
+cargo run --manifest-path agent/agentd/Cargo.toml --features grpc --bin agentd -- run \
+  --config ${AGENTD_CONFIG:-agent/agentd/config/agentd.toml} \
+  --capability-digest ${AGENTD_CAPABILITY_DIGEST:-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef}
+```
+
+## What It Does
+
+This skill launches `agentd` directly from source using the valid CLI shape.
+
+1. Runs the explicit `agentd` bin target (multi-bin workspace-safe).
+2. Enables gRPC feature for Envoy JSON transcoding compatibility.
+3. Uses committed `agentd` config instead of insecure fallback parsing.
+4. Supplies required `--capability-digest` argument.
+
+## Prerequisites
+
+- `agentd` build completed successfully.
+- Required infrastructure services available if runtime depends on them.
+
+## Expected Output
+
+- Process starts without immediate panic.
+- Startup logs indicate daemon initialization and gRPC listener startup.
+
+## Reading Results
+
+- Keep process attached while testing bridge/gateway flows.
+- If process exits, inspect final error lines for missing config or dependency issues.
+- On macOS, ensure `.env` includes `SMITH_EXECUTOR_VM_POOL_ENABLED=true` and
+  `SMITH_EXECUTOR_VM_METHOD=gondolin` to use the Gondolin sandbox path.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `could not determine which binary to run` | Missing `--bin agentd` | Use full command shown above |
+| `Failed to load config` | Wrong/missing config path | Set `AGENTD_CONFIG` to a valid agentd TOML |
+| `Refusing all-zero capability digest` | Placeholder digest left at zero | Set real `AGENTD_CAPABILITY_DIGEST`, or opt in with `SMITH_ALLOW_ZERO_CAPABILITY_DIGEST=1` for local-only testing |
+| `--capability-digest` required | Missing mandatory flag | Provide 64-char hex digest (env or inline) |
+| Port already in use | Conflicting process | Stop conflicting process or change `AGENTD_GRPC_LISTEN` |
+| Cannot connect to NATS/DB | Stack not running or wrong URL | Start stack and fix endpoint vars |
+| TLS-related errors | Missing cert files for strict modes | Generate certs and verify mounts/env |
+
+## Notes
+
+Use a separate terminal session so logs remain visible during installer verification.  
+For development-only fallback behavior, run the same command with `SMITH_EXECUTOR_ALLOW_INSECURE_FALLBACK=1 SMITH_ALLOW_ZERO_CAPABILITY_DIGEST=1`.

package/skills/start-chat-bridge/SKILL.md

@@ -0,0 +1,109 @@
+---
+description: Start the chat bridge daemon and platform gateway processes
+---
+# Start Chat Bridge
+
+Run these read-only inspection commands to understand the current state:
+
+```bash
+# Verify config exists
+test -f "${CHAT_BRIDGE_CONFIG:-config/chat-bridge.toml}" && echo "CONFIG_OK" || echo "NO_CONFIG"
+
+# Check which platforms are configured
+grep '^type = ' "${CHAT_BRIDGE_CONFIG:-config/chat-bridge.toml}" 2>/dev/null
+
+# Check if daemon/gateways are already running
+pgrep -f smith-chat-daemon && echo "DAEMON_RUNNING" || echo "DAEMON_NOT_RUNNING"
+pgrep -af 'smith-.*-gateway' 2>/dev/null || echo "NO_GATEWAYS_RUNNING"
+```
+
+## What It Does
+
+This skill starts the chat bridge daemon and the correct gateway binary for each configured platform adapter. The daemon handles inbound message routing, session management, and the admin/webhook API. Each gateway connects to its platform (Discord WebSocket, Telegram polling, etc.) and publishes messages to NATS for the daemon to consume.
+
+## Start Sequence
+
+### 1. Start the daemon
+
+```bash
+cargo run -p smith-chat --features webhooks --bin smith-chat-daemon
+```
+
+The daemon reads `CHAT_BRIDGE_CONFIG` (defaults to `config/chat-bridge.toml`) and starts the webhook server on `CHAT_BRIDGE_WEBHOOK_PORT` (defaults to 8092).
+
+Start this in a separate terminal or background it with log redirection:
+
+```bash
+cargo run -p smith-chat --features webhooks --bin smith-chat-daemon 2>&1 | tee logs/chat-daemon.log &
+```
+
+### 2. Start gateway(s) for each configured platform
+
+Parse the `type = ` values from the config and start the matching gateway binary:
+
+| Config `type =` | Binary name | Required env vars |
+|-----------------|-------------|-------------------|
+| `discord` | `smith-discord-gateway` | `DISCORD_BOT_TOKEN` |
+| `telegram` | `smith-telegram-gateway` | `TELEGRAM_BOT_TOKEN` |
+| `slack` | `smith-slack-gateway` | `SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN` |
+| `teams` | `smith-teams-gateway` | `TEAMS_TENANT_ID`, `TEAMS_CLIENT_ID`, `TEAMS_CLIENT_SECRET` |
+| `mattermost` | `smith-mattermost-gateway` | `MATTERMOST_TOKEN` |
+| `whatsapp` | `smith-whatsapp-gateway` | `WHATSAPP_ACCESS_TOKEN` |
+| `matrix` | `smith-matrix-gateway` | `MATRIX_ACCESS_TOKEN` |
+| `signal` | `smith-signal-gateway` | `SIGNAL_RECIPIENT` |
+| `google_chat` | `smith-google-chat-gateway` | `GOOGLE_CHAT_WEBHOOK_URL` |
+| `imessage` | `smith-imessage-gateway` | (config-only) |
+
+Start each gateway with:
+
+```bash
+cargo run -p smith-chat --bin <binary-name>
+```
+
+For example, for Discord:
+
+```bash
+cargo run -p smith-chat --bin smith-discord-gateway 2>&1 | tee logs/discord-gateway.log &
+```
+
+Each gateway should run in its own terminal or backgrounded process.
+
+## Prerequisites
+
+- `config/chat-bridge.toml` exists and has at least one `[[adapters]]` stanza (run `setup-chat-bridge` first).
+- Platform credentials set in `.env` for each configured adapter.
+- Docker stack running (NATS and Redis required by daemon).
+- Rust workspace built (`cargo build -p smith-chat`).
+
+## Expected Output
+
+- Daemon logs: `Starting chat bridge daemon` and `Starting webhook ingestion server`.
+- Gateway logs: platform-specific ready message (e.g., `Discord bot is READY`).
+- Processes visible via `pgrep -f smith-chat-daemon` and `pgrep -f gateway`.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `NO_CONFIG` | Config file missing | Run `setup-chat-bridge` skill first |
+| `failed to read chat bridge config` | Wrong `CHAT_BRIDGE_CONFIG` path | Check `.env` value matches actual file location |
+| `failed to connect to NATS` | NATS not running | `docker compose up -d nats` |
+| `failed to connect to redis` | Redis not running | `docker compose up -d redis` |
+| Gateway missing env var | Credential not set in `.env` | Run `setup-chat-bridge` to set credentials |
+| Port 8092 already in use | Another daemon instance running | Kill existing process or change `CHAT_BRIDGE_WEBHOOK_PORT` |
+| `could not determine which binary to run` | Missing `--bin` flag | Use full `--bin <name>` as shown above |
+
+## Notes
+
+Use separate terminal sessions so logs remain visible. For convenience, create a `logs/` directory first:
+
+```bash
+mkdir -p logs
+```
+
+To stop all chat bridge processes:
+
+```bash
+pkill -f smith-chat-daemon
+pkill -f 'smith-.*-gateway'
+```

package/skills/start-stack/SKILL.md

@@ -0,0 +1,56 @@
+---
+description: Start the Smith Core infrastructure stack with Docker Compose
+---
+# Start Stack
+
+Run:
+
+```bash
+bash infra/envoy/certs/generate-certs.sh
+docker compose up -d
+docker compose ps
+```
+
+## What It Does
+
+This skill launches the local infrastructure dependencies.
+
+1. Ensures local Envoy mTLS certs exist before container startup.
+2. Starts NATS, Postgres, Redis, ClickHouse, Grafana, OPA, Envoy, and MCP services.
+3. Ensures background containers are running.
+4. Gives a service-level health snapshot via `docker compose ps`.
+5. Establishes prerequisites for bridge and service processes.
+
+## Prerequisites
+
+- Docker and Compose available.
+- Ports required by the stack are free.
+
+## Expected Output
+
+- Cert generation exits successfully (or reports existing certs).
+- `docker compose up -d` exits successfully.
+- `docker compose ps` shows core services as `running` or `healthy`.
+
+## Reading Results
+
+Focus on these critical services:
+
+- `smith-nats`
+- `smith-postgres`
+- `smith-envoy`
+- `smith-mcp-index`
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Container exits immediately | Bad env/config | Inspect `docker compose logs <service>` |
+| Envoy fails with cert path errors | Certs not generated/mounted | Run `bash infra/envoy/certs/generate-certs.sh` and retry |
+| Port bind error | Port already in use | Free the port or remap in compose |
+| Image pull/build failure | Network or registry failure | Retry after network recovery |
+| Healthcheck stuck | Dependency not ready | Check dependent service logs |
+
+## Notes
+
+Use `docker compose down` to stop the stack.

package/skills/verify/SKILL.md

@@ -0,0 +1,53 @@
+---
+description: Verify the full Smith Core bootstrap state after install steps
+---
+# Verify
+
+Run:
+
+```bash
+cargo check --workspace
+cargo check --manifest-path agent/agentd/Cargo.toml --features grpc --bin agentd
+npm run build --workspaces --if-present
+docker compose ps
+```
+
+## What It Does
+
+This skill validates that core components are buildable and infrastructure is running.
+
+1. Checks Rust root workspace.
+2. Checks `agentd` workspace.
+3. Builds Node workspaces.
+4. Confirms Docker services are active.
+
+## Prerequisites
+
+- Dependencies installed.
+- Docker stack started.
+
+## Expected Output
+
+- All check/build commands exit with status 0.
+- `docker compose ps` shows core services up.
+
+## Reading Results
+
+Installation is considered healthy when:
+
+- Rust checks pass.
+- Node workspace build passes.
+- Core services (`nats`, `postgres`, `envoy`, `mcp-index`) are running.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Rust check failures | Code/toolchain mismatch | Fix compile issues and rerun |
+| npm build failures | TS/dependency issue | Resolve workspace build errors |
+| Containers not running | Compose/startup failure | Inspect compose logs and restart |
+| Intermittent health failures | Service startup race | Wait and re-run verification |
+
+## Notes
+
+This is the final gate for local release-readiness confidence.