@atollhq/skill-codex 0.4.27 → 0.4.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.4.27",
+  "version": "0.4.29",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"

package/skill/SKILL.md

@@ -38,12 +38,20 @@ Read only the references required for the current task:
 - Request and response fields, enums, and validation:
   [api-fields.md](references/api-fields.md)
 
-For automation rule V1 actions (including create issue), CI create-only rules,
-event conditions, validation, safe disabling, and example-only CI dry runs, read [Automation Rule Fields](references/api-fields.md#automation-rule-fields).
+For automation rule V1 actions (including create issue and send webhook), explicit project or
+organization scope, CI create-or-webhook rules, event conditions, validation, safe
+disabling, repair, and example-only CI dry runs, read [Automation Rule Fields](references/api-fields.md#automation-rule-fields).
 Use `atoll automation` for rule management, previews, and run history; see
 [CLI operations](references/cli-operations.md#automation-rules).
-Invalid rules execute no actions. Do not enable one before its full definition
-and references pass validation.
+REST rule lists accept `?project_id=<UUID>` for exact project rules or
+`?project_id=none` for organization-wide rules only. Omission lists all rules
+in the organization. See [list filter access and validation](references/api-endpoints.md#automation-rules).
+Rule creates require an explicit `project_id`: use a project UUID for project
+scope or `null` for organization scope. Partial updates preserve the saved
+scope when `project_id` is omitted; include it only when intentionally changing
+scope. An invalid rule executes no actions. Repair an invalid rule with
+separate `disable`, `update` while it is disabled, `test`, and `enable`
+operations. Enable only after the latest saved revision passes the dry run.
 
 Do not load every reference by default. Start with this entrypoint and load a
 topic reference only when the requested operation needs it.

package/skill/references/api-endpoints.md

@@ -719,6 +719,18 @@ receive projectless work. An inaccessible explicit `projectId` is concealed as
 
 ## Automation Rules
 
+**List filter:** `GET /api/orgs/{id}/automation-rules` accepts optional
+`project_id`. A project UUID returns only rules assigned to that exact project;
+it does not include organization-wide rules. Use `project_id=none` for only
+organization-wide rules (`project_id IS NULL`). Omit the parameter to preserve
+the existing list of all rules in the organization. Empty or invalid values
+return `400`. A project UUID requires both organization membership and caller
+read access to that project; cross-organization, inaccessible, or missing
+projects return `404`. Organization-wide and unfiltered requests retain existing
+organization-member access. Results remain newest first and include disabled
+or invalid rules with their validation diagnostics. This REST filter does not
+add CLI flags or public MCP tool parameters.
+
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/automation-rules` | List rules |
@@ -730,7 +742,15 @@ receive projectless work. An inaccessible explicit `projectId` is concealed as
 | POST | `/api/orgs/{id}/automation-rules/{ruleId}/test` | Dry-run test |
 
 V1 definitions validate on create, merged partial updates, dry runs, and runtime.
-A concurrent edit during validation returns `409`; reload before retrying.
+On create, `project_id` must be explicit: use a project UUID for project scope
+or `null` for organization scope. Partial updates preserve the saved scope
+when `project_id` is omitted; include it only when intentionally changing
+scope. A concurrent edit during validation returns `409`; reload before
+retrying. An enabled rule must be
+disabled with a separate exact `{ "enabled": false }` update before changing
+scope or repairing an invalid definition. A disabled invalid rule can be
+repaired while remaining disabled; run `test` on that saved revision before a
+separate `enable` update.
 GET/list preserve invalid rows with optional `validation: { valid, issues }`
 (`issues` contain `path`, `code`, and `message`). Owner/admin callers can disable
 an invalid rule with only `{ "enabled": false }`. Change-condition dry runs
@@ -764,6 +784,7 @@ failed without executing its actions.
 |--------|----------|-------------|
 | GET | `/api/webhooks?orgId=...` | List redacted webhooks (owner/admin) |
 | POST | `/api/webhooks?orgId=...` | Create webhook (owner/admin) |
+| PATCH | `/api/webhooks/{id}` | Update webhook metadata or private auth (owner/admin) |
 | DELETE | `/api/webhooks/{id}` | Delete webhook (owner/admin) |
 | GET | `/api/webhooks/{id}/deliveries` | List safe delivery metadata (owner/admin, last 50) |
 | POST | `/api/webhooks/{id}/redeliver/{deliveryId}` | Redeliver a past payload (owner/admin) |

package/skill/references/api-fields.md

@@ -499,6 +499,11 @@ clear it), `add_assignee` (add a member UUID without removing others), `unassign
 (omit `value`), `set_priority` (integer `0` through `3`), `add_label` and
 `remove_label` (label UUID), `post_comment` (non-empty text, at most 10,000
 characters), and legacy `close_issue` (omit `value`, targets the valid `done` key).
+`send_webhook` accepts only `{ "type": "send_webhook", "webhook_id": "webhook-uuid" }`.
+The destination must be enabled, same-org, and purpose `automation` or `both`.
+Queued transport retries do not re-run the automation action. Activity exposes
+`webhook_delivery_id` plus safe latest-attempt `webhook_delivery` state.
+Manual redelivery uses a new header and payload delivery ID.
 Already satisfied assignments, priorities, statuses, and label relationships
 succeed without duplicate mutation events. Invalid references still fail.
 Unsupported action types or malformed values return `400` and are not saved.
@@ -517,7 +522,7 @@ oversized rendered content fail before creation. Current issue triggers do not
 provide those external fields; use fixed text for issue triggers. The
 `ci.run.completed` trigger supplies them from a signed GitHub completion event.
 CI rules require organization scope (`project_id: null`) and support only
-`create_issue`. CI rules accept only event conditions. Issue triggers reject event conditions.
+`create_issue` and `send_webhook`. CI rules accept only event conditions. Issue triggers reject event conditions.
 Event conditions use `kind: "event"`, `eq` or `neq`, and fields
 `conclusion`, `repository`, `workflow`, `branch` (strings), `has_pr`, or
 `has_linked_issue` (booleans). Use conclusion `failure` and
@@ -553,12 +558,29 @@ Create and partial `PUT` requests reject unknown keys, unsupported versions,
 malformed conditions/actions, and invalid references with `400` and
 `issues: [{ path, code, message }]`. A partial update is merged with the stored
 definition and the complete result is validated. If another edit changes the rule
-during validation, `PUT` returns `409`; reload the rule before retrying. Project-scoped status values
+during validation, `PUT` returns `409`; reload the rule before retrying. An enabled
+rule must be disabled by a separate exact `{ "enabled": false }` request before
+changing `project_id`; combining disable with a scope change is rejected. An
+enabled invalid rule must also be disabled separately before repair. A disabled
+invalid rule accepts a valid repair only while remaining disabled; repair and
+enable must be separate. Project-scoped status values
 must exist in that workflow; project, member, and label references must belong
 to the organization. A request containing only `{ "enabled": false }` can
 disable an invalid rule without changing its definition; owner/admin access
 is still required. Enabling requires a valid definition.
 
+**List filter:** `GET /api/orgs/{id}/automation-rules` accepts optional
+`project_id`. A project UUID returns only rules assigned to that exact project;
+it does not include organization-wide rules. Use `project_id=none` for only
+organization-wide rules (`project_id IS NULL`). Omit the parameter to preserve
+the existing list of all rules in the organization. Empty or invalid values
+return `400`. A project UUID requires both organization membership and caller
+read access to that project; cross-organization, inaccessible, or missing
+projects return `404`. Organization-wide and unfiltered requests retain existing
+organization-member access. Results remain newest first and include disabled
+or invalid rules with their validation diagnostics. This REST filter does not
+add CLI flags or public MCP tool parameters.
+
 GET/list rules can include `validation: { valid, issues: [{ path, code, message }] }`.
 Invalid saved rows remain readable. Runtime validation rejects the whole invalid
 rule before any action; valid actions are not salvaged from a malformed rule.
@@ -688,15 +710,23 @@ reject `position`.
 
 ## Webhook Fields
 
+Bearer secrets must contain only printable ASCII characters. Switching from none to Bearer requires a token and returns HTTP 400 if it is missing.
+
+`PATCH /api/webhooks/{id}` preserves omitted fields. A blank or omitted Bearer
+secret preserves the token; `auth.type: none` clears it. URL/auth changes create
+a new private destination version; pending deliveries retain their pinned version.
+
 ```json
 {
   "url": "https://example.com/webhook",
   "events": ["issue.created", "issue.updated"],
-  "enabled": true
+  "enabled": true,
+  "purpose": "subscription",
+  "auth": { "type": "none" }
 }
 ```
 
-URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. The create response includes a `secret` for HMAC signature verification. Store it immediately; it is shown only once.
+URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. The create response includes a `secret` for HMAC signature verification. Store it immediately; it is shown only once. Use purpose `automation` or `both` with `auth: { "type": "bearer", "secret": "..." }` for automation destinations; responses expose only `auth.type` and `auth.configured`.
 
 List responses include `destination_display` and a deprecated `url` compatibility field containing only the origin plus `/…`. Payload schema version `2` is allowlisted. Delivery requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned `X-Atoll-Signatures`, and `X-Atoll-Delivery-Id`. Delivery history includes `delivery_id`, `status`, `status_code`, `error_code`, `delivered_at`, and `next_retry_at`, never payloads, receiver response bodies, or raw errors.
 

package/skill/references/cli-operations.md

@@ -201,16 +201,21 @@ Use `atoll automation list`, `get <rule-uuid>`, `create --file rule.json`,
 `runs <rule-uuid> --limit 20`, `enable`, `disable`, and `delete --force`.
 Use `delete <rule-uuid> --dry-run` to preview deletion. Use `--json`
 for machine-readable results and `--file -` for standard input. Create defaults
-to disabled when `enabled` is omitted; update preserves omitted fields.
+to disabled when `enabled` is omitted, but the JSON must include an explicit
+`project_id` UUID or `null` for Organization-wide scope; update preserves omitted
+fields.
 List uses the selected organization and applies a project filter only with
 explicit `--project`; it does not inherit the default project.
 
 Rule files use the canonical Automation Rule Fields contract. CI rules require
-`project_id: null`, only `create_issue` actions, and event conditions. Use
+`project_id: null`, only `create_issue` or `send_webhook` actions, and event conditions. Use
 conclusion `failure` and `has_linked_issue: false` for unlinked CI failures.
 The action chooses its target project/status and accepts approved
 `{{repository}}`, `{{workflow}}`, `{{conclusion}}`, `{{run_url}}` substitutions.
 CI `test` sends `{}` by default, uses marked fixed examples, rejects overrides,
 and executes no actions. Inspect the preview before explicitly enabling.
 Rule writes, tests, and run history require owner/admin access; CLI does not bypass it.
-`runs` preserves created issue IDs and interrupted-action evidence.
+`runs` preserves created issue IDs and interrupted-action evidence. For an invalid
+rule, use separate `disable`, `update` while disabled, `test`, and `enable`
+operations. Human `get` output includes invalid state and validation paths;
+`--json` preserves the API response.