create-ironclaws 1.0.3 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ironclaws",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Create an IronClaws AI agent platform in seconds",
   "type": "module",
   "bin": {

package/template/CLAUDE.md

@@ -1,66 +1,123 @@
-# NanoClaw — Ardoq IT Ops Agent Platform
+# IronClaws — AI Agent Platform
 
-Internal deployment of NanoClaw. Hosts the Ardoq IT agent fleet over Slack.
+This is an IronClaws deployment. It runs a fleet of AI agents over Slack.
 
 ## Architecture
 
-Single Node.js host process. Each registered agent gets its own Docker container (isolated filesystem + memory) spawned on demand. Agents communicate back via IPC files. All agents share one Docker image: `argus-claude:latest`.
+Single Node.js host process. Each agent gets its own Docker container — isolated filesystem, memory, and credentials. The host handles Slack routing, scheduling, and security. Agents do the actual work.
+
+```
+Slack
+  │
+  ▼
+IronClaws host (src/index.ts)
+  │  reads .env, agents.yaml, agent-credentials.yaml
+  │
+  ├── Message router ──► spawns Docker container per agent
+  ├── Task scheduler ──► spawns containers on schedule
+  └── IPC watcher    ──► reads results from containers
+          │
+          ▼
+    Docker container (argus-claude:latest)
+      ├── Claude Code (the AI)
+      ├── agent-runner (IPC bridge)
+      ├── Python tools (container/tools/)
+      └── Skills (container/skills/)
+```
 
 ## Key Files
 
 | File | Purpose |
 |------|---------|
 | `src/index.ts` | Main loop: message routing, agent invocation, state |
-| `src/channels/slack.ts` | Slack channel integration (Socket Mode) |
+| `src/channels/slack.ts` | Slack Socket Mode integration |
 | `src/container-runner.ts` | Spawns containers with correct mounts and env vars |
 | `src/ipc.ts` | IPC file watcher — agents write here to send messages / schedule tasks |
 | `src/task-scheduler.ts` | Cron-based task scheduling |
 | `src/db.ts` | SQLite: messages, groups, sessions, tasks |
-| `src/config.ts` | Trigger patterns, paths, env var loading |
-| `src/sender-allowlist.ts` | Per-channel sender filtering |
+| `agents.yaml` | Declarative agent registry — single source of truth for the fleet |
+| `agent-credentials.yaml` | Per-agent access control: which env vars, tools, and skills each agent gets |
 | `groups/{name}/CLAUDE.md` | Per-agent identity and instructions |
-| `container/Dockerfile.argus` | Agent container image definition |
+| `container/Dockerfile.argus` | Agent container image |
 | `container/tools/` | Python tools available inside containers |
-| `container/skills/` | Shared skills available to all agents |
+| `container/skills/` | Shared skills (SKILL.md files) available to agents |
 
-## Agent Fleet
+## Your Agent Fleet
 
 | Agent | Folder | Channel | Purpose |
 |-------|--------|---------|---------|
-| Argus Alert | `argus-alert` | Alert channel | Monitors alerts, investigates incidents, raises fix PRs |
-| Argus Deps | `argus-deps` | Deps channel | Manages Dependabot alerts, bumps packages |
-| Byte | `byte` | IT standup | Team standup agent, team memory |
-| Byte IT Internal | `byte-it-internal` | IT internal | Silent reader, writes to Byte's MEMORY.md |
-| Ticket Creator | `ticket-creator` | Ticket channel | Creates Jira tickets from Slack conversation |
-| Jira Worker | `jira-worker` | Worker channel | Picks up IAI tickets, implements, raises PRs |
-| Global Claw | `global-claw` | DM (Sewnet only) | Meta-agent: manages all other agents |
+| Forge | `forge` | Your channel | Built-in guide — helps you add new agents and troubleshoot |
+
+Add more agents by creating a `groups/{name}/CLAUDE.md`, adding an entry to `agents.yaml`, and setting the channel ID in `.env`.
+
+## Adding an Agent
+
+**1. Create the agent instructions:**
+```bash
+mkdir -p groups/my-agent
+# Write groups/my-agent/CLAUDE.md — the agent's identity, what it does, how to respond
+```
+
+**2. Register in `agents.yaml`:**
+```yaml
+  - folder: my-agent
+    name: "My Agent"
+    trigger: "@Argus"
+    channel_env: MY_AGENT_CHANNEL_ID
+    requires_trigger: false
+    onecli_secrets: [litellm]
+    onecli_id: <python3 -c "import uuid; print(uuid.uuid4())">
+```
+
+**3. Set the channel ID in `.env`:**
+```
+MY_AGENT_CHANNEL_ID=C...
+```
+
+**4. Restart IronClaws** — agents auto-register on startup. No script needed.
 
 ## Container Image
 
-All agents use `argus-claude:latest`. Built with:
+All agents share one image: `argus-claude:latest`. Build it with:
 ```bash
-cd container && ./build-argus.sh
+cd container && ./build.sh && ./build-argus.sh
 ```
 
-Set `CONTAINER_IMAGE=argus-claude:latest` in `.env`.
+## Tools
+
+Located in `container/tools/` — baked into the image at build time. There are no default tools. You add the tools your agents need.
 
-## Tools Available Inside Containers
+Drop a Python script into `container/tools/`, rebuild the image, then grant access in `agent-credentials.yaml`:
+```yaml
+agents:
+  my-agent:
+    tools: [my_tool.py]
+    config: [MY_SERVICE_URL]
+```
 
-Located in `container/tools/` — baked into the image:
-- `elastic_query.py` — Kibana/Elastic log querying
-- `jira_tool.py` — Jira CRUD (get, search, create, update, comment, assign)
-- `gdrive_tool.py` — Google Drive transcript reading
-- `slack_history_tool.py` — Slack channel history fetching
+See `container/tools/README.md` for design principles and auth patterns.
 
 ## Skills Available Inside Containers
 
-Located in `container/skills/` — loaded at runtime:
-- `agent-browser` — web browsing
-- `capabilities` — list available skills
-- `slack-formatting` — Slack mrkdwn formatting reference
+Located in `container/skills/` — mounted at runtime, no rebuild needed.
+
+- `slack-formatting` — Slack mrkdwn formatting rules (loaded by all agents)
+- `capabilities` — lets agents list available tools
 - `status` — system health check
-- `agent-status` — dashboard of all agents
-- `edit-agent` — collaborative CLAUDE.md editing
+- `agent-browser` — web browsing capability
+- `agent-status` — dashboard of all running agents
+- `edit-agent` — collaborative CLAUDE.md editing from Slack
+
+## Credentials and Security
+
+The `agent-credentials.yaml` file controls what each agent can access:
+- `config:` — env vars from `.env` forwarded to the container
+- `tools:` — Python scripts mounted at `/workspace/extra/tools/`
+- `skills:` — SKILL.md files made available
+
+Dangerous skills (`edit-agent`, `agent-browser`, `agent-status`) are not in the default set — agents must explicitly opt in. See `agent-credentials.yaml`.
+
+Service API credentials (Jira, Slack, etc.) are never in containers. The OneCLI proxy intercepts HTTPS traffic and injects `Authorization` headers server-side. See `docs/how-it-works.md` → Secrets Management.
 
 ## Runtime Config
 
@@ -68,37 +125,34 @@ Key env vars (set in `.env`):
 ```
 SLACK_BOT_TOKEN      Slack bot token (xoxb-...)
 SLACK_APP_TOKEN      Slack app-level token (xapp-...)
-GITHUB_TOKEN         GitHub PAT for raising PRs
-GITHUB_APP_ID        GitHub App ID (for token generation)
-ELASTIC_BASE_URL     Kibana base URL
-ELASTIC_API_KEY      Kibana API key
-JIRA_BASE_URL        https://ardoqcom.atlassian.net
-JIRA_EMAIL           Jira account email
-JIRA_API_TOKEN       Jira API token
-JIRA_PROJECT_KEY     IAI
+ANTHROPIC_BASE_URL   LiteLLM gateway URL
+ANTHROPIC_AUTH_TOKEN LiteLLM auth token
 CONTAINER_IMAGE      argus-claude:latest
 ```
 
+See `.env.example` for the full list with descriptions.
+
 ## Security
 
-- Mount allowlist: `~/.config/nanoclaw/mount-allowlist.json` — controls what host paths containers can access
-- Sender allowlist: `~/.config/nanoclaw/sender-allowlist.json` — per-channel sender filtering, outside project root (tamper-proof)
-- Global Claw DM is restricted to Sewnet only (U04S2VA1CU8) at allowlist level
-- `github-app.pem` is gitignored — never commit
+- Mount allowlist: `~/.config/nanoclaw/mount-allowlist.json` — controls what host paths containers can access. Outside the project directory so containers can't read or modify it.
+- Sender allowlist: `~/.config/nanoclaw/sender-allowlist.json` — per-channel sender filtering. Also outside the project directory.
+- `*.pem` files are gitignored — never commit private keys
 
 ## Running
 
 ```bash
-npm run dev          # Development (hot reload)
-npm run build        # Compile TypeScript
-npm start            # Production
+docker compose up -d   # Start OneCLI credential proxy
+npm run dev            # Start IronClaws (development, hot reload)
+npm run build && npm start  # Production
 ```
 
 ## First-Time Setup
 
 1. Copy `.env.example` to `.env` and fill in all values
-2. Run `./setup-agents.sh` to register all agents in the SQLite database
-3. Update `~/.config/nanoclaw/sender-allowlist.json` with channel IDs
-4. Update `~/.config/nanoclaw/mount-allowlist.json` for Global Claw repo access
-5. Build the container: `cd container && ./build-argus.sh`
-6. Start: `npm run dev`
+2. Start OneCLI: `docker compose up -d`
+3. Build the container image: `cd container && ./build.sh && ./build-argus.sh`
+4. Start IronClaws: `npm run dev`
+5. Agents auto-register on startup — no script needed
+6. Say hello in the configured Slack channel
+
+For credential registration (Jira, Elastic, etc.): `bash scripts/setup-onecli-secrets.sh`

package/template/container/Dockerfile.argus

@@ -1,6 +1,6 @@
-# Argus Claude Agent Container
-# Extends the NanoClaw agent image with Python, Poetry, gh CLI, and moon
-# so Claude's Bash tool can run poetry lock, gh pr create, moon lint, etc.
+# IronClaws Agent Container
+# Extends the base NanoClaw image with Python and the gh CLI.
+# This is intentionally minimal — add your own dependencies as needed.
 #
 # Build the base image first:  ./container/build.sh
 # Then build this image:       ./container/build-argus.sh
@@ -9,24 +9,26 @@ FROM nanoclaw-agent:latest
 
 USER root
 
-# Python 3 + pip (requests needed by elastic_query.py)
+# Python 3 + pip — required to run tools from container/tools/
+# requests: foundational HTTP library; most tools will need it
 RUN apt-get update && apt-get install -y python3 python3-pip && rm -rf /var/lib/apt/lists/*
-RUN pip3 install requests tenacity youtube-transcript-api markdownify --break-system-packages
+RUN pip3 install requests --break-system-packages
 
-# Poetry
-RUN pip3 install poetry --break-system-packages
-
-# gh CLI
+# gh CLI — for agents that work with GitHub (PR creation, issue management, etc.)
 RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
     | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg 2>/dev/null && \
     echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] \
     https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null && \
     apt-get update && apt-get install -y gh && rm -rf /var/lib/apt/lists/*
 
-# moon task runner
-RUN npm install -g @moonrepo/cli
+# ── Add your own dependencies here ────────────────────────────────────────────
+# Examples:
+#   RUN pip3 install tenacity pyjwt pyyaml --break-system-packages
+#   RUN pip3 install poetry --break-system-packages
+#   RUN npm install -g @moonrepo/cli
 
-# Argus tools — baked into the image, no repo mount needed
+# Tools — baked into the image at build time
+# Add Python scripts to container/tools/ and rebuild to make them available
 COPY tools/ /workspace/extra/tools/
 RUN chown -R node:node /workspace/extra/tools && chmod -R 755 /workspace/extra/tools
 

package/template/container/skills/slack-formatting/SKILL.md

@@ -42,25 +42,25 @@ Tables don't render. Use these patterns instead:
 
 **Field list (best for structured data):**
 ```
-*Voucher:* AP-818
-*Vendor:* Metosin Oy
-*Amount:* 325,994.74 NOK
-*Posted:* 2025-08-31
+*Ticket:* PROJ-042
+*Assignee:* eng@yourcompany.com
+*Priority:* High
+*Due:* 2026-06-30
 ```
 
 **Compact inline (best for short summaries):**
 ```
-AP-818 • Metosin Oy • 325,994.74 NOK • 2025-08-31
+PROJ-042 • Deploy pipeline fix • High • Due 2026-06-30
 ```
 
 **Key-value in code block (best for exact copy-paste, e.g. email drafts):**
 ````
 ```
-Voucher:    AP-818
-Vendor:     Metosin Oy
-Amount:     325,994.74 NOK
-Move from:  6784 – Konsulentkostnader Utvikling
-Move to:    [INSERT ACCOUNT]
+Ticket:     PROJ-042
+Summary:    Deploy pipeline fix
+Priority:   High
+Assignee:   eng@yourcompany.com
+Due date:   2026-06-30
 ```
 ````
 
@@ -94,13 +94,12 @@ _Footer — instructions or next steps_
 ```
 :red_circle: *1 violation found — action required*
 
-*Voucher:* AP-818
-*Vendor:* Metosin Oy (Finland)
-*Amount:* 325,994.74 NOK
-*Posted:* 2025-08-31
-*Issue:* Vendor invoice posted to 6784 — must be reclassified by Amesto
+*Item:* PROJ-042
+*Assigned to:* eng@yourcompany.com
+*Found:* 2026-06-15
+*Issue:* Missing required field — needs manual review before proceeding
 
-> Christian — fill in `[INSERT ACCOUNT]` and send the correction email below.
+> Team Lead — please review and confirm the correct value.
 ```
 
 ---
@@ -108,11 +107,11 @@ _Footer — instructions or next steps_
 ## Status summaries
 
 ```
-:white_check_mark: *Expense check complete — May 2026*
+:white_check_mark: *Check complete — June 2026*
 
-• Reports checked: 14 | Expenses: 67
-• :red_circle: 2 red violations | :large_yellow_circle: 7 yellow flags
-• Notifications: 0 (DM sending not yet enabled)
+• Items reviewed: 14 | Findings: 3
+• :red_circle: 1 critical | :large_yellow_circle: 2 warnings
+• :large_green_circle: 11 clean
 ```
 
 ---
@@ -122,25 +121,26 @@ _Footer — instructions or next steps_
 Always use a triple-backtick code block. This makes it copy-paste ready and visually distinct:
 
 ````
-Here's the correction email for Christian to review and send:
+Here's the draft for your review:
 
 ```
-To: [Amesto contact]
-Cc: finance@ardoq.com, Christian Dotterweich <christian.dotterweich@ardoq.com>
-Subject: Correction request — voucher AP-818 — move from 6784 to [INSERT ACCOUNT]
+To: recipient@theircompany.com
+Cc: team@yourcompany.com
+Subject: Action required — PROJ-042
 
-Hi [Amesto contact],
+Hi [Name],
 
-Please reclassify the following vendor invoice ...
+Please review the following item and confirm the correction below.
 
-Voucher:    AP-818
-Vendor:     Metosin Oy
-Amount:     325,994.74 NOK
-Move from:  6784 – Konsulentkostnader Utvikling
-Move to:    [INSERT ACCOUNT]
+Item:       PROJ-042
+Details:    [description]
+Action:     [what needs to happen]
+Deadline:   [date]
+
+Please confirm once resolved.
 
 Thanks,
-Christian Dotterweich
+[Your Name]
 ```
 ````
 
@@ -151,10 +151,10 @@ Christian Dotterweich
 Use `send_message` for long-running tasks so people know you're working:
 
 ```
-:hourglass_flowing_sand: Fetching transactions from Xledger...
+:hourglass_flowing_sand: Fetching data from the API...
 ```
 ```
-:mag: Found 3 entries on account 6784 — running classification...
+:mag: Found 3 items — running checks...
 ```
 
 ---
@@ -162,12 +162,11 @@ Use `send_message` for long-running tasks so people know you're working:
 ## Escalations and warnings
 
 ```
-:rotating_light: *Annual true-up required — December close*
+:rotating_light: *Review required before proceeding*
 
-The December close report cannot be marked complete until the annual true-up is logged.
+This task cannot complete automatically. Human judgment needed.
 
-Reply with:
-`annual true-up done 2025: <summary including adjustment amount>`
+Please reply with your decision or `skip` to defer.
 ```
 
 ---
@@ -175,13 +174,13 @@ Reply with:
 ## Confirmations and success
 
 ```
-:white_check_mark: *Done* — session flagged as resolved in state/flagged_6784.json
+:white_check_mark: *Done* — state updated in flagged_items.json
 ```
 
 ```
-:white_check_mark: *Reconciliation complete — 6784 — 2025-08*
+:white_check_mark: *Check complete — PROJ — June 2026*
 
-:red_circle: 1 violation | :large_green_circle: 1 compliant | no volume flag
+:red_circle: 1 violation | :large_green_circle: 3 compliant
 ```
 
 ---
@@ -192,9 +191,9 @@ Use `•` for bullets. Never `1.` numbered lists (they don't render as lists in
 
 ```
 What was checked:
-• Account 6784 — Konsulentkostnader Utvikling
-• Period: 2025-08 (August)
-• Source: Xledger GraphQL API
+• Data source: API
+• Period: 2026-06 (June)
+• Items reviewed: 14
 ```
 
 ---
@@ -202,9 +201,9 @@ What was checked:
 ## Mentions and links
 
 ```
-<@U04S2VA1CU8>                          # Mention a specific user
-<#C0B36KNFDHV|finance-close-ops>        # Link a channel
-<https://expensify.com/report?id=123|View report>   # Named link
+<@USERID>                                    # Mention a specific user
+<#CHANNELID|channel-name>                    # Link a channel
+<https://app.yourservice.com/item/123|View>  # Named link
 ```
 
 ---

package/template/container/tools/README.md

@@ -0,0 +1,33 @@
+# Tools
+
+Add Python scripts here that your agents need. Each script becomes available
+inside containers at `/workspace/extra/tools/<script-name>`.
+
+## How to add a tool
+
+1. Drop your Python script here: `container/tools/my_tool.py`
+2. Rebuild the container image: `cd container && ./build-argus.sh`
+3. Grant access to specific agents in `agent-credentials.yaml`:
+   ```yaml
+   agents:
+     my-agent:
+       tools: [my_tool.py]
+   ```
+
+## Design principles
+
+- One purpose per tool. A Jira tool does Jira things. A database tool does database things.
+- Output JSON to stdout. Errors to stderr. Exit non-zero on failure.
+- Auth: don't put credentials in tools. Use the OneCLI proxy (`HTTPS_PROXY` is set
+  automatically in every container — outbound requests get Authorization headers
+  injected by the proxy for any service you've configured in OneCLI).
+- If a service embeds credentials in request bodies (not headers), pass them via
+  env vars listed in `agent-credentials.yaml` → `config:`.
+
+## What's available inside containers
+
+- Python 3 with `requests` — for HTTP calls
+- `gh` CLI — for GitHub operations (PR creation, issue management)
+- All skills from `container/skills/`
+
+Add dependencies to `container/Dockerfile.argus` and rebuild.

package/template/docs/how-it-works.md

@@ -113,7 +113,7 @@ This is the most important system to understand. The design goal: **no long-live
 
 ### The Four Credential Categories
 
-#### A. Service API Keys (Elastic, Jira, Confluence, Slack, Intercom, Ardoq)
+#### A. Service API Keys (Jira, Slack, Elastic, Confluence, and any other services you configure)
 These never enter containers at all. The OneCLI proxy intercepts HTTPS requests and injects the `Authorization` header server-side. The container makes a request to `jira.atlassian.com`, OneCLI intercepts, adds `Authorization: Basic <token>`, forwards it. The container only ever sees the base URL.
 
 ```
@@ -136,10 +136,10 @@ Same pattern as GitHub. The host holds the OAuth refresh token. Before spawning,
 
 **Where to read:** `src/google-token.ts`, `container-runner.ts:470–478`
 
-#### D. Expensify Credentials (the exception)
-Expensify embeds credentials in the **JSON request body** (not in HTTP headers). OneCLI can only inject headers, so it can't handle Expensify. These two env vars (`EXPENSIFY_PARTNER_USER_ID`, `EXPENSIFY_PARTNER_USER_SECRET`) must be passed directly to the container. This is explicitly documented as a known trade-off, and only the `expense-policy-checker` agent gets them.
+#### D. Services that embed credentials in request bodies (the exception)
+Some APIs embed credentials in JSON request bodies rather than HTTP headers (e.g. certain payment or partner APIs). OneCLI can only inject headers — it cannot inject body parameters. For these, the credentials must be passed as env vars directly to the container. This is explicitly documented as a known trade-off, and only the agents that specifically need them should receive them (principle of least privilege).
 
-**Where to read:** `agent-credentials.yaml` (comment on expense-policy-checker block)
+**Where to read:** `agent-credentials.yaml` — add these under `config:` for the relevant agent
 
 ### Per-Agent Selective Credentials
 
@@ -148,7 +148,7 @@ Each agent only gets the credentials it actually needs. This is configured in tw
 **`agent-credentials.yaml`** — controls which env vars from the host's `.env` are forwarded:
 ```yaml
 agents:
-  argus-alert:
+  my-agent:
     config:
       - GITHUB_TOKEN        # gets a fresh token injected
       - ELASTIC_BASE_URL    # just a URL, not a secret
@@ -156,7 +156,7 @@ agents:
 
 **`agents.yaml`** — controls which OneCLI credential sets are linked (for service auth via proxy):
 ```yaml
-- folder: byte-it-internal
+- folder: my-agent
   onecli_secrets: [slack, litellm]   # can call Slack API + Claude API
 ```
 
@@ -187,7 +187,7 @@ When OneCLI intercepts a request:
 3. If yes: injects the `Authorization: Bearer <secret>` header
 4. If no credential: proxies the request unchanged (or blocks if configured to do so)
 
-The `access_token` in the proxy URL is the per-agent token stored in OneCLI's PostgreSQL database. It's regenerated each time `setup-agents.sh` is run.
+The `access_token` in the proxy URL is the per-agent token stored in OneCLI's PostgreSQL database. It's generated when the agent is first registered (automatically on startup).
 
 ### Git Authentication Fix
 
@@ -201,7 +201,7 @@ GIT_CONFIG_VALUE_0=Authorization: Basic <base64(x:token)>
 - `src/container-runner.ts:482–499` — where `applyContainerConfig()` is called
 - `node_modules/@onecli-sh/sdk/lib/index.js` — what it actually injects
 - `agents.yaml` — `onecli_id` and `onecli_secrets` per agent
-- `setup-agents.sh:101–124` — how agents are registered in OneCLI's DB
+- `src/index.ts` — `autoRegisterAgentsFromYaml()` — how agents are registered on startup
 
 ---
 
@@ -227,12 +227,12 @@ The `REJECT` (not `DROP`) matters: with `DROP`, a blocked connection hangs for m
 The iptables rules only allow port 10255 (OneCLI proxy). Since `HTTPS_PROXY` is set in the container, ALL HTTPS calls go through port 10255 automatically. So:
 - Direct `api.anthropic.com:443` connections → REJECTED (but these go through proxy anyway)
 - Claude API calls → port 10255 → OneCLI → forwarded with credentials → OK
-- Expensify calls → port 10255 → OneCLI → forwarded without modification (body unchanged) → OK
+- Calls to any service with no credential → port 10255 → OneCLI → forwarded unchanged → service decides auth
 - Any unauthorized service → port 10255 → OneCLI → no credential → 401 or blocked
 
 ### Cleanup
 
-Rules are tagged with the container name (`--comment "nanoclaw-argus-deps-123"`). When the container exits, all its rules are deleted. On NanoClaw startup, stale rules from any previous run are cleaned up automatically.
+Rules are tagged with the container name (`--comment "nanoclaw-my-agent-123"`). When the container exits, all its rules are deleted. On startup, stale rules from any previous run are cleaned up automatically.
 
 **Where to read:**
 - `src/network-policy.ts` — `applyContainerIptables()`, `cleanupContainerIptables()`
@@ -255,7 +255,7 @@ Each group has its own IPC directory at `data/ipc/{agentFolder}/`. Agents can on
 Each container only gets the skills and tools listed in `agent-credentials.yaml`. See [Section 7](#7-tools-and-skills).
 
 ### Worktrees
-When an agent needs to modify code (e.g. argus-deps raising a PR), it doesn't work on your live checkout. NanoClaw creates a git worktree — a separate clone of the repo — at `data/worktrees/{agentFolder}/repo/`. This is mounted read-write into the container while the actual repo stays untouched.
+When an agent needs to modify code (e.g. an agent raising a PR), it doesn't work on your live checkout. NanoClaw creates a git worktree — a separate clone of the repo — at `data/worktrees/{agentFolder}/repo/`. This is mounted read-write into the container while the actual repo stays untouched.
 
 **Where to read:**
 - `src/worktree.ts` — worktree creation/management
@@ -279,15 +279,15 @@ common:
   tools: []                                          # no tools by default
 
 agents:
-  argus-alert:
+  alert-agent:
     skills: []                        # adds nothing extra
-    tools: [elastic_query.py, jira_tool.py]  # but gets these tools
-  global-claw:
+    tools: [my_tool.py]              # gets this tool
+  meta-agent:
     skills: [agent-browser, agent-status, edit-agent]  # dangerous skills
-    tools: [elastic_query.py, jira_tool.py, ...]       # all tools
+    tools: [my_tool.py, other_tool.py]                 # all tools
 ```
 
-**Dangerous skills** (`edit-agent`, `agent-browser`, `agent-status`) are NOT in the common layer. Only `global-claw` has them by explicit opt-in.
+**Dangerous skills** (`edit-agent`, `agent-browser`, `agent-status`) are NOT in the common layer. Only agents that explicitly list them in `agent-credentials.yaml` get them — typically just your main/meta agent.
 
 ### How It's Enforced
 
@@ -395,12 +395,12 @@ If `wakeAgent: false`, the task ends without calling Claude — useful for tasks
 ## 10. Agent Registration
 
 ### Automatic Registration on Startup
-NanoClaw reads `agents.yaml` on every startup and auto-registers any agent whose channel ID env var is set in `.env` but isn't in the DB yet. This means a fresh install only requires filling in `.env` and starting NanoClaw — no manual script needed.
+IronClaws reads `agents.yaml` on every startup and auto-registers any agent whose channel ID env var is set in `.env` but isn't in the DB yet. A fresh install only requires filling in `.env` and starting IronClaws — no manual script needed.
 
 The `autoRegisterAgentsFromYaml()` function in `src/index.ts` handles this. It also runs `scripts/setup-onecli-secrets.sh` automatically when credentials change (detected via hash of relevant env vars).
 
 ### Dynamic Registration (Main Group)
-The `global-claw` agent (the meta-agent) can register new agents at runtime using the `register_group` MCP tool. Only the main group can do this — NanoClaw enforces this at the IPC processing level.
+The main agent (`is_main: true` in `agents.yaml`) can register new agents at runtime using the `register_group` MCP tool. Only the main group can do this — IronClaws enforces this at the IPC processing level.
 
 ### What Registration Does
 
@@ -492,5 +492,5 @@ If you want to go deeper on a specific area:
 | Network security | `src/network-policy.ts` |
 | How agents talk back | `src/ipc.ts` + `container/agent-runner/src/ipc-mcp-stdio.ts` |
 | Scheduling | `src/task-scheduler.ts` |
-| What OneCLI does | `setup-agents.sh` + `node_modules/@onecli-sh/sdk/lib/index.js` |
+| What OneCLI does | `docker-compose.yml` + `node_modules/@onecli-sh/sdk/lib/index.js` |
 | Security model end-to-end | This doc → `src/mount-security.ts` → `src/network-policy.ts` |

package/template/groups/forge/CLAUDE.md

@@ -63,7 +63,7 @@ Tone, format, constraints.
 ```yaml
   my-agent:
     skills: []
-    tools: [jira_tool.py]   # tools from container/tools/
+    tools: [my_tool.py]     # tools from container/tools/
     config:
       - SOME_API_URL
 ```
@@ -72,16 +72,20 @@ Tone, format, constraints.
 
 Agents never see raw API keys. OneCLI (the HTTPS proxy) intercepts outbound requests and injects Authorization headers. `onecli_secrets` in `agents.yaml` controls which credentials flow to which agent. Run `bash scripts/setup-onecli-secrets.sh` to register new credentials — this runs automatically on startup when credentials change.
 
-### Available tools
+### Tools
 
-| Tool | What it does |
-|------|-------------|
-| `jira_tool.py` | Jira CRUD — get, search, create, update, comment |
-| `elastic_query.py` | Query Kibana/Elasticsearch |
-| `slack_history_tool.py` | Read Slack channel history |
-| `gdrive_tool.py` | Read Google Drive files |
+There are no default tools — tools are specific to each deployment. To add one:
 
-Add tools to an agent via `agent-credentials.yaml` → `tools:`.
+1. Write a Python script and drop it in `container/tools/my_tool.py`
+2. Rebuild the image: `cd container && ./build-argus.sh`
+3. Grant it to the agent in `agent-credentials.yaml`:
+   ```yaml
+   agents:
+     my-agent:
+       tools: [my_tool.py]
+   ```
+
+**Tool design:** output JSON to stdout, errors to stderr, exit non-zero on failure. Auth goes through the OneCLI proxy — don't put credentials in tools. See `container/tools/README.md`.
 
 ---