docs(automation): `job` and `email_template` are authorable, referenced, and have no how-to page

[os-elon]

Part of #10206

The gap

Both kinds are first-class: members of MetadataTypeSchema, bound to schemas in BUILTIN_METADATA_TYPE_SCHEMAS, and authorable as defineStack({ jobs, emailTemplates }).

job — references/system/job.mdx (182 lines) is the only page. automation/index.mdx mentions it in exactly one bullet ("Scheduled jobs run on setInterval or cron via the job service, alongside schedule-type flows") and gives it no Card and no page. The stack describe string is 'Background / Scheduled Jobs (run by IJobService on cron/interval/once schedules)'.

email_template — references/system/email-template.mdx (95 lines) publishes the shape. kernel/runtime-services/email-service.mdx documents services.email and sendTemplate({ template, locale }) — i.e. how to send. Nothing documents how to author a template, how locale resolves, or how a flow's notify node reaches one. Grep for emailTemplates across the hand-written docs returns zero hits.

File surface

• content/docs/automation/jobs.mdx — new
• content/docs/automation/email-templates.mdx — new
• content/docs/automation/index.mdx — edit ("The building blocks" bullet + a Card each)
• content/docs/automation/meta.json — two added entries

⛔ Nothing outside content/docs/automation/. In particular do not edit kernel/runtime-services/email-service.mdx — cross-link it instead; that file is the service contract and belongs to a different surface.

PM ruling on placement

Both pages go in automation/. job clearly belongs beside flows and hooks. email_template is System Protocol by schema module, but its reader arrives from an automation need ("my flow should email someone"), and automation/ is where that reader is. If while writing you find a concrete reason this misleads, say so in the report and place it anyway — do not re-shelve on your own.

What to write

jobs.mdx

Read JobSchema (packages/spec/src/system/job.zod.ts) and the IJobService contract, and write from them:

• what a job is and how it differs from a schedule-type flow — this distinction is the reason the page exists, so lead with it and make it decidable, not descriptive;
• the schedule forms the schema actually accepts (cron / interval / once) with real examples;
• how the handler is bound and what runs it;
• cluster semantics — kernel/cluster.mdx already says something about which node fires a scheduled job; cross-link rather than restate, and verify what it says still holds;
• failure, retry and observability, to whatever depth the schema and service actually support. If a facet is not supported, say nothing rather than implying it.

email-templates.mdx

Read EmailTemplateDefinitionSchema (packages/spec/src/system/email-template.zod.ts):

• authoring a template: name, subject, body, and whatever templating/interpolation the schema declares;
• locale resolution — how sendTemplate({ template, locale }) picks a variant, and how that interacts with the translation kind if it does;
• reaching one from a flow notify node and from services.email;
• ⚠️ spec/system 通知模板语汇在 C3 后成为零消费方孤儿:EmailTemplate/SMSTemplate/PushNotification/InAppNotification(Schema) 待 enforce-or-remove 处置 #4616 note for your own reading: the canonical schema is EmailTemplateDefinitionSchema, not the legacy EmailTemplateSchema, which was demoted and then removed. Consumers historically wired the wrong one. Make sure every example you write is valid against the canonical schema.

⛔ Non-goals

• Do not touch packages/spec/**. If a schema property looks dead or contradicts the service, report it — that is a domain:spec finding, not something to document around.
• Do not document capabilities the runtime does not implement. An undocumented gap is a smaller problem than a documented fiction.

Gates (derived at dispatch time via node scripts/pm/dispatch-gates.mjs, not recalled)

check:doc-anchors, check:docs-audit-scope, check:docs-redirects, check:published-readme-links, check:role-word, check:cross-package-test-inputs, and the spec liveness set (check:empty-state, check:liveness, check:strictness-ledger, check:variant-docs). Re-derive against your actual diff.

Acceptance

• A developer who needs a nightly job, or an outbound templated email, lands on a page from the Automation sidebar and can author one without opening packages/spec.
• Every code sample validates against the real schema.
• Named gates green.

[os-elon]

Claim: PM loop round 1 (epic #10206)
Session: session_01GawRwpD44VwBDVy3hs77AX
Branch: claude/issue-10211-jobs-email-templates
Worktree: objectstack-issue-10211
Domain: domain:devx
File surface: content/docs/automation/jobs.mdx (new), content/docs/automation/email-templates.mdx (new), content/docs/automation/index.mdx, content/docs/automation/meta.json (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — no path-derived mandate (node scripts/pm/dispatch-gates.mjs --tier over the surface → "the surface hits none of the 1 declared glob(s)"), tier is this seat's call. Default judgment tier: both pages must be written from JobSchema / EmailTemplateDefinitionSchema and the IJobService / IEmailService contracts, and the card's chief risk is documenting a facet the runtime does not implement.
Clause-②: no — documentation only.
Serial constraints cleared: content/docs/automation/** — no in-flight claim, no open PR. Two-member family fold (jobs + email templates) justified on the five gates: same shape (authorable kind with a generated reference and no how-to), same directory and one meta.json, both adjudicated under the epic, each independently checkable as its own page, and the exclusion list is stated on the card (kernel/runtime-services/email-service.mdx is the service contract and is NOT in this fold — cross-link only). Sibling epic cards #10209 / #10210 in this batch touch the root nav and content/docs/ui/**; disjoint.

---

Generated by Claude Code

[os-elon]

{
 "issue": 10211,
 "status": "done",
 "branch": "claude/issue-10211-jobs-email-templates",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10273",
 "premise_still_valid": true,
 "summary": "Issue body read in full and NOT truncated (ends at the Acceptance section). All four PM premises verified true against origin/main: job.mdx 182 lines and email-template.mdx 95 lines exactly; automation/index.mdx had one jobs bullet, no Card, no page; `emailTemplates` returned zero hits across all of content/docs (generated pages included, not just hand-written); and EmailTemplateDefinitionSchema is the live schema (the legacy EmailTemplateSchema survives only in comments and retirement pins). Added content/docs/automation/jobs.mdx and email-templates.mdx, two Cards plus two rewritten bullets in index.mdx, and two meta.json entries. The PM's mechanism assumption about the jobs.mdx lead was RIGHT as framing and WRONG on its axis, and the page says so: a `schedule`-type flow owns no timer at all — ScheduleTrigger registers it as a job (name prefixed `flow-schedule:`) against the SAME IJobService, so schedule forms, adapter and cluster leader election are identical for both, and cluster behaviour cannot be the deciding axis. kernel/cluster.mdx section 1's 'a schedule-triggered Flow fires once on every node' is a motivating bug class, not current state; section 5.1 IS current (verified at cron-job-adapter.ts:227, lock.acquire per job per fire) and is what the page cross-links. The real decision axes are what runs, who may change it after deploy (job is allowRuntimeCreate:false / allowOrgOverride:false because `handler` names a compiled-bundle function key), the identity of the run's writes, and run-history destination. DELIBERATELY NOT DOCUMENTED, runtime does not implement them: (1) clusterScope / leaderStrategy auto-wiring — the schema accepts the annotations and no runtime consumes them (cluster.mdx 5.1 marks it Phase 4), so the page documents only the lock that works; (2) a jobs admin HTTP API — none exists, the client's only `jobs` routes are data-import jobs, so observability is documented as sys_job / sys_job_run records plus IJobService.getExecutions; (3) variables[].type coercion — declared but the renderer never coerces by it, so it is documented as an authoring hint while only `required` is described as enforced (MISSING_VARIABLES). On the adjudicated placement: no reason to re-shelve found, and positive supporting evidence instead — the notify node's `template` key IS the localizable content path and resolves (name, recipient locale) per recipient, so the reader really does arrive at email_template from an automation need. One file outside the declared surface: .claude/workflows/docs-accuracy-audit.js, two lines, generated by scripts/docs-audit/check-audit-scope.mjs --write; check:docs-audit-scope is on this card's own gate list and fails for any new hand-written page until that derived list is regenerated (the workflow runs in a node:vm with no filesystem and cannot enumerate content/docs itself). Named in the PR body. Draft PR carries skip-changeset (publishes nothing); label written as the UNION with the bot's size/m and read back as [size/m, skip-changeset].",
 "tests": "Gate union re-derived with `node scripts/pm/dispatch-gates.mjs` (no paths passed) against the actual diff, then re-run at final commit 98b5b91f3 with a clean tree — ALL GREEN, each line below quoting the gate's own verdict, exit codes captured before any pipe. check:doc-anchors 'check-doc-anchors: 254 internal #fragment link(s) across 401 source file(s) all resolve to a real heading'. check:docs-audit-scope 'docs-accuracy-audit scope is in sync with content/docs/: 182 hand-written doc(s)'. check:docs-redirects 'OK (apps/docs/redirects.mjs: 92 entries...)'. check:published-readme-links '152 outbound link(s) across 60 published markdown file(s)'. check:role-word 'OK, no new occurrences of the reserved word' (scanned 218 files). check:doc-authoring 'doc authoring guard: 382 files clean — no bare metadata literals'. check:cross-package-test-inputs 'OK: 12 package(s) read outside themselves, all declared'. spec check:empty-state 'all classified'; check:liveness 'state-counts.md is current'; check:strictness-ledger '61 file(s) across 5 triaged director(ies)'; check:variant-docs '18 discriminated union(s) — 8 governed, 10 exempt'. RE-DERIVATION ADDED FOUR FAMILIES THE DISPATCH LIST DID NOT NAME, all pulled in by the .claude/ file and all run green: check:doc-authoring, check:doc-formula-expressions ('22 record-scoped formula example(s) across 408 files / 1424 TS blocks judged clean'), check:pm-governed-merges ('81 assertions'), check:skill-frame-sync ('4 copies of the decision frame are structurally isomorphic'). check:doc-formula-expressions first failed ERR_MODULE_NOT_FOUND on @objectstack/formula/dist — the fresh-worktree unbuilt-closure trap, not a defect; fixed by building the closure (`pnpm --workspace-concurrency=2 --filter '@objectstack/lint^...' --filter '@objectstack/spec' build`, VERDICT command-exit 0) and re-running green. SAMPLE VALIDATION: all three TypeScript samples carry `os:check`, so check:skill-examples type-checks them against the BUILT @objectstack/spec — '212 prose examples type-check against @objectstack/spec', and the blocks were confirmed actually extracted rather than silently skipped (log names content/docs/automation/jobs.mdx:14, email-templates.mdx:20 and :108 with their generated .ts filenames). The gate itself refuses a dist missing or older than src, so that green is against a fresh build, not a cached one. ABLATION: no rebuild was required on either leg because the mutation is in the .mdx the gate reads directly and the spec dist was unchanged (freshness asserted by the gate). Predicted direction was RED. Mutation confirmed ON DISK by anchor count before reading any result: canonical anchor 1 -> 0, injected `cron:` 0 -> 1. Replacing `schedule:` with the legacy `cron:` alias in the defineJob sample produced VERDICT command-exit 1 with 'error TS2353: Object literal may only specify known properties, and cron does not exist in type { name: string; schedule: ... }' attributed to docs__automation_jobs__1.ts — i.e. my own block, so the green is not vacuous. RESTORE LEG: git checkout of the committed file, proved on disk (canonical 1, mutant 0, git status clean), re-run green at '212 prose examples type-check'. IMPORTANT PROCESS NOTE: the FIRST mutation attempt was a `perl -0pi` NO-OP — zero match, exit 0, file untouched — and would have read as a passing ablation had the anchor count not been checked; it was redone with a literal-string replace that asserts exactly one anchor match. Heavy work serialized through scripts/pm/os-verify-lock.sh (waits of 269s and 294s behind the issue-10210 agent, spent in-turn, never a background watcher). Not run locally and left to CI: the rest of the ~115-family farm, per the local-scope rule. Worktree removed without --force; no governed-surface files (apps/docs/AGENTS.md / CLAUDE.md) were ever generated — verified the commit holds exactly 5 paths and the branch diff touches no AGENTS.md/CLAUDE.md.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #10266: [finding, domain:spec] JobHandler's docblock in packages/spec/src/contracts/job-service.ts still says degraded consumption is 'not yet wired: the shipped adapters currently discard the resolved value' — stale; cron, interval and db adapters all map it and sys_job_run.status / sys_job.last_status carry it in enforced selects. The docs page documents the measured behaviour, not the docblock's claim.",
 "filed as #10267: examples/app-showcase/src/system/emails/index.ts declares locale:'en', which the exact-then-en-US ladder can never resolve for a call naming en-US (including per-recipient notify delivery); it also bypasses defineEmailTemplateDefinition so nothing validates it at authoring time. No label — left for triage."
 ]
}

---

Generated by Claude Code