docs phase 2: creating-workers section + landing copy nit#1664
docs phase 2: creating-workers section + landing copy nit#1664anthonyiscoding wants to merge 46 commits into
Conversation
Introduces the section by stating its premise: every new capability in iii is added by writing a Worker, never by extending the Engine. Cross-links to /understanding-iii for the mental model and to the three sibling pages (Workers, Functions, Triggers) for the actual authoring guides. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Folds the "Quadratic to Zero" section into "The Solution" so the landing page leads with the headline framing (zero quadratic cost, two-or-two-hundred is the same) before introducing the three primitives. Removes the intermediate paragraph about up/downstream friction and the worker-join detail, which read as supporting prose rather than the core message. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughAdds a Creating Workers index and substantially rewrites authoring docs: Functions (including HTTP-invokable functions and schema metadata notes), Triggers (publisher-side types, bindings, metadata), Workers (lifecycle, registry, shutdown), Channels, plus many consumer-facing examples, navigation, styling, and how‑to stubs. ChangesWorker Authoring Documentation
Consumer-Facing Invocation and API Documentation
Navigation and Styling
How-to Guide Stubs
Estimated code review effort 🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint skipped: no ESLint configuration detected in root package.json. To enable, add Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
skill-check — docs285 verified, 0 skipped.
Three for three. Nicely done. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
- functions.mdx, triggers.mdx: restore the "Review against real SDK/CLI surface" TODOs that PR #1651 removed. - workers.mdx: restore the iii.worker.yaml-reference and ephemeral- worker-shutdown TODOs; refresh the SDK reference Note, add the workerName option to Connecting-to-the-engine snippets, expand the Worker lifecycle and invocation_stopped handling with per-language examples, restructure registry inspection into Read-a-snapshot / Subscribe tables, and tighten the manifest paragraph. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
- Move the "What a worker contributes" bullets up next to the SDK reference Note so callers see the contribution surface immediately. - Promote registry inspection into the Worker lifecycle group and add a per-language Accordion example that lists workers, functions, triggers, and trigger types. - Split Handling Worker disconnects into "In flight requests" and "Subscribe to changes" subsections with Accordion examples. - Add a "Shutting down a worker" section with per-language SIGTERM examples, framed as the natural fit for one-shot / ephemeral workers. Re-rendered workers.mdx.skill.md to match. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
…ages - Rename the SDK handle variable from `iii` to `worker` across in-scope docs (creating-workers, using-iii, sdk-reference, etc.) so example code reads naturally now that "worker" is the SDK's noun. Skipped versioned archives (0-10-0/, 0-11-0/, changelog/), URLs (iii.dev), filenames (iii.lock, iii.worker.yaml), OTel metric names (iii.invocations.total, ...), and module imports. - Link `http`, `cron`, queue messages, and `state` to their respective workers on workers.iii.dev in creating-workers/triggers.mdx and the parallel mentions in using-iii/triggers.mdx. - Split the "see Using iii / Triggers" + "see Understanding iii / Triggers" pointer paragraph into two `<Note>` callouts so each reference reads as its own aside. - Fix a broken inline-fenced Tabs block under "Unregister a trigger type" so each language example renders on its own line; switch Python to the handle pattern (TriggerTypeRef.unregister) to match the surrounding prose. - Style accordions to share the table border treatment (borders match --iii-rule, no radius). Trigger/header keeps the inline-code panel background; the expanded body uses the regular page bg, so the collapsed and expanded states each look like the right thing. - Replace `## Run an ephemeral worker` with `## Shutting down a worker` in creating-workers/workers.mdx; describe `shutdown` semantics in terms already introduced in "Handling Worker disconnects", show the per-language signal-handler patterns, and fold the ephemeral-worker guidance into a `<Note>` so it's clearly the same code path. Re-rendered the affected `.skill.md` artifacts to match. Co-Authored-By: Claude Opus 4.7 <[email protected]>
Rewrites the trigger-type publisher section against the real SDK surface: - Frames the section as publisher (vs consumer) explicitly so the role flip from the previous section is obvious. - Calls out the registerTrigger naming collision between the consumer bind (worker.registerTrigger) and the publisher handler callback (TriggerHandler.registerTrigger) as a Warning. - Describes the TriggerTypeRef handle's three uses (registerFunction, registerTrigger, unregister) and notes Rust's unregister asymmetry. - Reframes the example as a mini iii-http built from scratch, with a bindings routing table that the Dispatch section now references back by name. Consistent worker variable naming across all three tabs. - Regenerates the matching .skill.md artifact.
- using-iii/triggers: add cross-ref Note at "Register a trigger" pointing worker authors to creating-workers/triggers#bind-a- function-to-an-existing-trigger-type. - using-iii/functions: add a "Common functions" section indexing the engine::* introspection / lifecycle functions and the standard workers (state, stream, queue, pubsub, observability) with links out to each worker's docs. - how-to/schedule-cron-task, how-to/use-trigger-conditions: stub pages with frontmatter + TODO bodies for future how-to authoring. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Split the section into Components-of-a-Trigger-Type and an Example walkthrough of a mini iii-http. Reframe `TriggerHandler` as "interface you implement" and the `TriggerTypeRef` as the handle `registerTriggerType` returns. Strip the Warning callout and the TriggerTypeRef convenience-method tables that were marked Node/Python only — they'll come back once the surface is stable. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
…example Reorganize the intro into "register on existing types" vs "publish new types" with separate Notes; expand the `TriggerHandler` callback descriptions; add an "Example: A mini iii-http from scratch" walkthrough showing a publisher worker maintaining its own bindings map. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Replace two ` — ` clauses (schemas-are-metadata, unregister-timing) with a colon and parentheses respectively. No semantic change. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
- creating-workers/functions: rename request_schema/response_schema to request_format/response_format (Node + Python); replace the Rust schema snippet with the actual JsonSchema-derive pattern (manual builders don't exist). - using-iii/triggers, creating-workers/functions: drop `?` from Rust register_function (returns FunctionRef, not Result). - using-iii/deployment: remove the 9464/Prometheus row — the Prometheus exporter was removed from the engine in 0.12. - Node samples now fail loudly when III_URL is unset (`if (!url) throw new Error(...)`) instead of silently passing `string | undefined` to registerWorker. - using-iii/workers: add `-y` to `iii worker stop|remove|clear` so the documented forms work in non-interactive shells, with TODOs to drop `-y` once those commands are made non-interactive. - creating-workers/triggers, creating-workers/functions: fix broken anchor #engine-built-ins-engine → #engine-functions-engine. All Node + Python snippets re-tested against a live engine; the four Rust snippets compile against the in-repo iii-sdk via `cargo check`. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Vale [Terminology.EmDash] flagged two em dashes in the asyncio-twin Note. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
|
#1677 is related but there shouldn't be any conflicts besides |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/understanding-iii/index.mdx.skill.md (1)
233-233: TODO reminder: Confirm restricted string prefix policy.The TODO comment indicates uncertainty about whether restricted string prefixes for function IDs are still enforced. Please verify this with the engine implementation and either document the restriction or remove the TODO.
Do you want me to search the codebase for restricted prefix enforcement?
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/understanding-iii/index.mdx.skill.md` at line 233, The TODO about "restricted string prefixes" means we need to confirm whether the engine still enforces restricted prefixes for function IDs; search the engine implementation for any validation or constants that mention "restricted", "prefix", "function ID", or methods like validateFunctionId/normalizeFunctionId, confirm the current behavior, then either (a) update the docs at the TODO to document the exact restriction and link to the enforcing code symbol(s), or (b) if no enforcement exists, remove the TODO and the statement about restricted prefixes; include the exact code symbol names you found (e.g., validateFunctionId, FunctionIdPrefixConstants) in the doc change.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/creating-workers/functions.mdx`:
- Around line 84-88: Update the Note paragraph in
docs/creating-workers/functions.mdx to fix the parallel structure: locate the
sentence that begins "the engine does not enforce a specific schema, reject
payloads, nor handler return values..." and change it to use matching
auxiliaries—for example, "the engine does not enforce a specific schema, nor
does it reject payloads or handler return values that don't match the schemas."
Ensure you modify the Note block content accordingly.
---
Nitpick comments:
In `@docs/understanding-iii/index.mdx.skill.md`:
- Line 233: The TODO about "restricted string prefixes" means we need to confirm
whether the engine still enforces restricted prefixes for function IDs; search
the engine implementation for any validation or constants that mention
"restricted", "prefix", "function ID", or methods like
validateFunctionId/normalizeFunctionId, confirm the current behavior, then
either (a) update the docs at the TODO to document the exact restriction and
link to the enforcing code symbol(s), or (b) if no enforcement exists, remove
the TODO and the statement about restricted prefixes; include the exact code
symbol names you found (e.g., validateFunctionId, FunctionIdPrefixConstants) in
the doc change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 77667ac6-0859-4058-8a3c-324cf4cd1da6
📒 Files selected for processing (35)
.skill-check.yamldocs/creating-workers/channels.mdxdocs/creating-workers/channels.mdx.skill.mddocs/creating-workers/functions.mdxdocs/creating-workers/functions.mdx.skill.mddocs/creating-workers/triggers.mdxdocs/creating-workers/triggers.mdx.skill.mddocs/creating-workers/workers.mdxdocs/creating-workers/workers.mdx.skill.mddocs/custom.cssdocs/docs.jsondocs/understanding-iii/channels.mdxdocs/understanding-iii/channels.mdx.skill.mddocs/understanding-iii/functions.mdxdocs/understanding-iii/functions.mdx.skill.mddocs/understanding-iii/index.mdxdocs/understanding-iii/index.mdx.skill.mddocs/understanding-iii/triggers.mdxdocs/understanding-iii/triggers.mdx.skill.mddocs/understanding-iii/workers.mdxdocs/understanding-iii/workers.mdx.skill.mddocs/using-iii/channels.mdxdocs/using-iii/channels.mdx.skill.mddocs/using-iii/console.mdxdocs/using-iii/console.mdx.skill.mddocs/using-iii/deployment.mdxdocs/using-iii/deployment.mdx.skill.mddocs/using-iii/engine.mdxdocs/using-iii/engine.mdx.skill.mddocs/using-iii/functions.mdxdocs/using-iii/functions.mdx.skill.mddocs/using-iii/triggers.mdxdocs/using-iii/triggers.mdx.skill.mddocs/using-iii/workers.mdxdocs/using-iii/workers.mdx.skill.md
💤 Files with no reviewable changes (10)
- docs/using-iii/deployment.mdx
- docs/understanding-iii/functions.mdx
- docs/understanding-iii/triggers.mdx.skill.md
- docs/understanding-iii/workers.mdx.skill.md
- docs/understanding-iii/workers.mdx
- docs/understanding-iii/triggers.mdx
- docs/using-iii/channels.mdx.skill.md
- docs/understanding-iii/functions.mdx.skill.md
- docs/using-iii/deployment.mdx.skill.md
- docs/using-iii/channels.mdx
✅ Files skipped from review due to trivial changes (9)
- docs/understanding-iii/channels.mdx.skill.md
- .skill-check.yaml
- docs/creating-workers/channels.mdx
- docs/using-iii/functions.mdx.skill.md
- docs/using-iii/console.mdx
- docs/creating-workers/channels.mdx.skill.md
- docs/docs.json
- docs/using-iii/functions.mdx
- docs/using-iii/triggers.mdx
- Drop "built-in" framing from the http trigger type in creating-workers/triggers.mdx; attribute the type to iii-http instead, consistent with the no built-in/external worker distinction. - Replace the commented-out VS Code extension capability list in install.mdx with a single neutral sentence and a TODO to move the capability description to an extension overview page when the section is re-enabled. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Summary
Docs restructure (the main thrust)
creating-workers/section with an overview page; moved channels in, restored review TODOs, refactored worker lifecycle/shutdown, added "Scaffold a new worker", and reworked the triggers page (intro, Components, Declaring a Trigger Type, mini-http example).using-iii/pages: workers grouped under "Managing workers", channels regrouped under "Using channels" with a new payload-size section, triggers got code samples + em-dash cleanup, console copy polish.understanding-iii/overview now merges workers/triggers/functions; channels copy polished.iii→workeracross docs; added HTTP-invokable functions, trigger metadata, built-in functions index, how-to stubs, cross-links.custom.csspolish (tabular-nums in code, tighter line-height/padding).Code (merged in from main)
feat(iii-worker): bundle worker install pipeline (feat(iii-worker): add bundle worker install pipeline #1674)feat(engine)!: rework discovery builtins; drop hand-written SDK discovery types (feat(engine)!: rework discovery builtins; drop hand-written SDK discovery types #1675)refactor(sdk)!: drop unused telemetry exports across all SDKs (refactor(sdk)!: drop unused telemetry exports across all SDKs #1676)feat(workflows): scripts for discovering and publishing worker skills (feat(workflows): add scripts for discovering and publishing worker skills #1667)docs(http): agent skills bundle for iii-http worker (docs(http): add agent skills bundle for iii-http worker #1668)45 commits, 179 files, +13.6k/−3.9k (uv.lock churn included).
Original scope (early branch)
creating-workers/index.mdx: section overview that states the premise ("every new capability is added by writing a Worker, never by extending the Engine") and cross-links to/understanding-iiifor the mental model and to the three existing pages in the section.docs.json.index.mdxlanding copy: folds "Quadratic to Zero" into "The Solution" so the page leads with the headline framing before introducing the three primitives.Summary by CodeRabbit