thepopebot 1.2.76-beta.35 → 1.2.76-beta.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thepopebot",
-  "version": "1.2.76-beta.35",
+  "version": "1.2.76-beta.36",
   "type": "module",
   "description": "Create autonomous AI agents with a two-layer architecture: Next.js Event Handler + Docker Agent.",
   "bin": {

package/templates/agent-job/CLAUDE.md.template

@@ -18,19 +18,22 @@ There are three action types:
 
 ```json
 {
-  "name": "heartbeat",
-  "schedule": "*/30 * * * *",
+  "name": "weekly-report",
+  "schedule": "0 9 * * 1",
   "type": "agent",
-  "job": "Read agent-job/HEARTBEAT.md and complete the tasks described there.",
+  "scope": "agents/reporter",
+  "job": "Generate the weekly report and open a PR.",
+  "user_id": "57e959ab-d288-4623-8cda-829c995b7251",
   "enabled": false
 }
 ```
 
 Optional fields:
-- `"scope"` (e.g. `"agents/my-agent"`) — routes the cron to a scoped agent. Its `SYSTEM.md`, skills directory, and working directory all switch to that subdirectory. See `agents/CLAUDE.md` for the full pattern.
+
+- **`"scope"`** *(recommended)* — e.g. `"agents/my-agent"`. Routes the cron to a **scoped agent** under `agents/<name>/`. Its `SYSTEM.md`, skills directory, and working directory all switch to that subdirectory. Scoping is technically optional (a cron without `scope` runs from the repo root using the default `agent-job/SYSTEM.md`), but in practice you almost always want a scoped agent so the job has a clearly-defined identity, prompt, and skill set. See `agents/CLAUDE.md` for the full pattern.
+- **`"user_id"`** *(optional)* — sets the owner of the agent-job. Used by internal systems like `send-dm` to route the completion message; with no owner, the message goes to all admins. Set for personal crons; leave out for shared/system crons. Find user ids in Admin > Users.
 - `"agent_backend"` (e.g. `"claude-code"`, `"codex-cli"`, `"gemini-cli"`, `"pi"`, `"opencode"`, `"kimi-cli"`) — pick which coding agent runs the job, overriding the default set in Admin > Event Handler > Coding Agents.
 - `"llm_model"` — override the model used within the selected coding agent (provider is implicit in the agent).
-- `"user_id"` — attribute the job to a specific user. The completion DM (after PR merge) routes to that user's inbox. If omitted, the completion broadcasts to every admin subscribed to system messages.
 
 **`command`** — Runs a shell command on the event handler (working directory: project root).
 

package/templates/event-handler/CLAUDE.md.template

@@ -38,17 +38,20 @@ JSON array of webhook trigger definitions. Loaded at server boot by `lib/trigger
 
 ### Action types
 
-Three types — `agent`, `command`, `webhook`. `agent` accepts optional `scope`, `agent_backend`, `llm_model`, `user_id` overrides:
+Three types — `agent`, `command`, `webhook`:
 
 ```json
-{ "type": "agent", "job": "Process: {{body}}", "scope": "agents/triage", "agent_backend": "claude-code", "llm_model": "claude-sonnet-4-5-20250929", "user_id": "<uuid>" }
+{ "type": "agent", "scope": "agents/triage", "job": "Process: {{body}}" }
 { "type": "command", "command": "echo 'webhook received: {{body}}' >> logs/webhook.log" }
 { "type": "webhook", "url": "https://example.com/hook", "method": "POST", "headers": {}, "vars": { "source": "github" } }
 ```
 
-`scope` resolves to a directory under `agents/` (see `agents/CLAUDE.md`). The agent runs with that directory as its working dir, picks up its `SYSTEM.md`, and uses the skills under `agents/<scope>/skills/` falling back to root `skills/`.
+#### Optional fields on `agent` actions
 
-`user_id` attributes the spawned job to a specific user — its completion DM routes to that user's inbox. Omit to broadcast the completion to subscribed admins.
+- **`"scope"`** *(recommended)* — e.g. `"agents/triage"`. Routes the action to a **scoped agent** under `agents/<name>/`. Its `SYSTEM.md`, skills directory, and working directory all switch to that subdirectory. Scoping is technically optional (an action without `scope` runs from the repo root using the default `agent-job/SYSTEM.md`), but in practice you almost always want a scoped agent so each trigger has a clearly-defined identity, prompt, and skill set. See `agents/CLAUDE.md` for the full pattern.
+- **`"user_id"`** *(optional)* — sets the owner of the agent-job. Used by internal systems like `send-dm` to route the completion message; with no owner, the message goes to all admins. Set for per-user integrations; leave out for shared/system triggers. Find user ids in Admin > Users.
+- `"agent_backend"` (e.g. `"claude-code"`, `"codex-cli"`, `"gemini-cli"`, `"pi"`, `"opencode"`, `"kimi-cli"`) — pick which coding agent runs the action, overriding the default set in Admin > Event Handler > Coding Agents.
+- `"llm_model"` — override the model used within the selected coding agent (provider is implicit in the agent).
 
 ### Template tokens (in `job` and `command` strings)