Skip to content

Correct the Automations docs against the jobs and templates code (docs audit) - #963

Merged
selfcontained merged 1 commit into
mainfrom
docs-audit-automations-2026-08-15
Aug 16, 2026
Merged

Correct the Automations docs against the jobs and templates code (docs audit)#963
selfcontained merged 1 commit into
mainfrom
docs-audit-automations-2026-08-15

Conversation

@selfcontained

Copy link
Copy Markdown
Owner

Nightly docs audit. Deep-dive of the docs-pane Automations section — the next_focus carried over from #960, and the first time this section has been audited against the code.

Audited

docs-sections/automations.tsx against automations-form-fields.tsx, jobs-add-dialog.tsx, jobs-settings-tab.tsx, jobs-detail-pane.tsx, jobs-history-tab.tsx, jobs-overview.tsx, jobs/service.ts, jobs/store.ts, templates/service.ts, notifications/job-notifier.ts, and JOB_TOOLS in shared/mcp/server.ts. Cross-checked docs/17-jobs.md, skills/jobs/SKILL.md, skills/templates/SKILL.md.

Clean as a set in both directions: the template create/edit field list, the job create dialog + Advanced list, the 53-entry job agent tool list, the seven run statuses, the three trigger-source labels, and the self-improve guidance text.

Wrong claims fixed

  • Jobs do not send notifications. JobNotifier is wired into the run-state callback, but its channel lists come from job.notify — a column nothing writes (absent from createJob's INSERT, from JobConfigUpdate, from the route Zod schemas, and from MCP create_job/update_job). Per-job Slack has never fired. What does notify is the ordinary per-agent path, which job agents are not excluded from.
  • The run timeout does not stop at running. The monitor checks now - startedAt >= timeoutMs for every active status, so the 30 min default kills a run parked on job_needs_input ~23.5 h before the 24 h wait-for-input timeout it advertises.
  • Nothing "resumes" a needs_input run from the UI — there is no answer box; the human replies in the agent's terminal.
  • Template launches all go through one dialog. The detail pane was described as filling arguments inline and the palette as an Enter-twice confirm; both open the same launch dialog (Add template launch agent type override #523).
  • Template agentType lists omitted cursor/terminal; field tables omitted model, allowMedia, selfImprove.
  • docs/17-jobs.md described an answer box and an MCP log stream that do not exist, and a two-tab Automations sidebar that now has three.

Filled in by omission

When a run is recorded crashed; the Configure tab's immediate-write Enabled switch and Remove job; the Jobs overview's 7-day stats, charts, and Recent Activity; the last-five-job_log-lines-per-task limit in History; the hidden backing template; the webhook endpoint and its rate limit. Also drops a review-tools bullet that duplicated the one above it.

Tip

Adds an ambient job-webhooks tip — the webhook trigger is buried in a job's Configure tab and nothing surfaced it. since: 0.22.0, confirmed by git merge-base --is-ancestor aca12314 <release>.

Deferred to next run

next_focus is the Media & Sharing section (tab set vs MediaSidebarTab, pin types vs dispatch_pin/dispatch_pins, upload paths, retention claims). Backlog gained two product decisions this audit surfaced but did not fix: job notify has no write path at all, and job callable is fully inert while two UI surfaces and the MCP tool description still promise palette/API behavior.

Deep-dive of the docs-pane Automations section (in-app docs), plus the
same claims in docs/17-jobs.md and the jobs/templates skills.

Wrong claims fixed:
- Jobs were said to add "notifications". JobNotifier is wired up, but its
  channel lists come from job.notify, which nothing writes — it is absent
  from createJob's INSERT, JobConfigUpdate, the route schemas, and the MCP
  tools. Per-job Slack has never fired. What does notify is the ordinary
  per-agent path, which job agents are not excluded from.
- The run timeout was described as covering started/running only. The
  monitor checks it against the run start time for every active status, so
  the 30 min default kills a run parked on job_needs_input long before the
  24 h wait-for-input timeout.
- needs_input was said to end when "someone resumes it". There is no answer
  box in the Jobs pane; the human replies in the agent's terminal.
- Template launches were described as filling arguments inline (detail pane)
  and as an Enter-twice confirm (palette). All three paths open the same
  launch dialog.
- Template agentType lists omitted cursor/terminal; field tables omitted
  model, allowMedia, and selfImprove.
- 17-jobs.md described an answer box and an MCP log stream that do not
  exist, and a two-tab sidebar that now has three.

Filled in by omission: when a run is recorded as crashed, the Configure
tab's immediate-write Enabled switch and Remove job, the Jobs overview's
7-day stats and Recent Activity, the last-five-job_log-lines-per-task
limit in History, the hidden backing template, and the webhook endpoint.

Also drops a duplicated review-tools bullet and adds an ambient tip for
job webhook triggers, which nothing surfaced before.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@selfcontained
selfcontained merged commit db5eb58 into main Aug 16, 2026
1 check passed
@selfcontained
selfcontained deleted the docs-audit-automations-2026-08-15 branch August 16, 2026 04:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant