Skip to content

docs phase 2: creating-workers section + landing copy nit#1664

Open
anthonyiscoding wants to merge 46 commits into
mainfrom
docs/phase-2
Open

docs phase 2: creating-workers section + landing copy nit#1664
anthonyiscoding wants to merge 46 commits into
mainfrom
docs/phase-2

Conversation

@anthonyiscoding
Copy link
Copy Markdown
Contributor

@anthonyiscoding anthonyiscoding commented May 20, 2026

Summary

Docs restructure (the main thrust)

  • New 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).
  • Reworked 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.
  • Landing page: "The Solution" consolidated with quadratic-to-zero framing.
  • Renamed SDK binding iiiworker across docs; added HTTP-invokable functions, trigger metadata, built-in functions index, how-to stubs, cross-links.
  • custom.css polish (tabular-nums in code, tighter line-height/padding).

Code (merged in from main)

45 commits, 179 files, +13.6k/−3.9k (uv.lock churn included).


Original scope (early branch)

  • New 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-iii for the mental model and to the three existing pages in the section.
  • Adds the overview to the Creating Workers nav group in docs.json.
  • Tightens index.mdx landing copy: folds "Quadratic to Zero" into "The Solution" so the page leads with the headline framing before introducing the three primitives.

Summary by CodeRabbit

  • Documentation
    • Major rework of Creating Workers, Workers, Triggers, and Functions content; added an overview/navigation landing.
    • Added comprehensive Channels docs and model; new how‑to stubs for cron scheduling and trigger conditions.
    • Clarified that request/response schemas are metadata-only; added HTTP-invokable function guidance and failure semantics.
    • Expanded invocation, registry, console, deployment, and multi-language examples for clarity.
  • Style
    • Tweaked code-block typography and accordion theming for visual consistency.

Review Change Stack

anthonyiscoding and others added 2 commits May 20, 2026 10:26
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]>
@vercel
Copy link
Copy Markdown
Contributor

vercel Bot commented May 20, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
iii-website Ready Ready Preview, Comment May 22, 2026 8:06pm

Request Review

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 20, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 70696830-3b88-4a85-b32c-8943f7120ed6

📥 Commits

Reviewing files that changed from the base of the PR and between 02ff113 and b4926c7.

📒 Files selected for processing (2)
  • docs/install.mdx
  • docs/install.mdx.skill.md
✅ Files skipped from review due to trivial changes (1)
  • docs/install.mdx

📝 Walkthrough

Walkthrough

Adds 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.

Changes

Worker Authoring Documentation

Layer / File(s) Summary
Worker section index and fundamentals
docs/creating-workers/index.mdx, docs/creating-workers/index.mdx.skill.md
New landing page for "Creating Workers" explaining that workers provide capabilities by registering Triggers and Functions, with navigation cards linking to sub-sections.
Function registration and HTTP-invokable functions
docs/creating-workers/functions.mdx, docs/creating-workers/functions.mdx.skill.md
Function authoring guide rewritten: register semantics, explicit note that attached request/response schemas are metadata-only (no runtime validation), updated multi-language examples and schema field names, new "HTTP-invokable functions" section documenting HttpInvocationConfig, auth via engine-resolved env vars, and non-2xx/network failure semantics; updated return/error stack-trace notes and unregister examples.
Trigger type creation and metadata
docs/creating-workers/triggers.mdx, docs/creating-workers/triggers.mdx.skill.md
Comprehensive trigger authoring: distinguishes type definition from consumer binding; adds binding examples, per-binding metadata storage and discovery visibility, expanded trigger-type declaration with TriggerHandler callbacks, mini-http example, schema-attachment guidance (informational only), and updated unregister/dispatch behavior.
Worker lifecycle: connections, registry, and shutdown
docs/creating-workers/workers.mdx, docs/creating-workers/workers.mdx.skill.md
Connection examples updated to pass workerName/WorkerMetadata via InitOptions, new "Inspecting the live registry" section with engine::*::list examples, reworked disconnect guidance (in-flight handling and subscribe-to-changes), revised manifest explanation, and a new "Shutting down a worker" section with multi-language examples.

Consumer-Facing Invocation and API Documentation

Layer / File(s) Summary
Channels documentation with worker-scoped APIs
docs/creating-workers/channels.mdx, docs/creating-workers/channels.mdx.skill.md
New Channels page describing channel model, payload-size guidance (~16MB practical threshold), create/write/read APIs, and cross-function ref handoff with Node/Python/Rust examples.
Function invocation patterns and common functions
docs/using-iii/functions.mdx, docs/using-iii/functions.mdx.skill.md
Reorganized "Invoking functions" section with direct SDK/CLI examples (worker.trigger and iii trigger), synchronous-by-default note, repositioned Common functions catalog, and Node/Ts registration example now validates III_URL.
Trigger consumption and binding guidance
docs/using-iii/triggers.mdx, docs/using-iii/triggers.mdx.skill.md
Updated call/register examples to validate III_URL, added Python trigger_async note, expanded TriggerAction docs with links, and replaced bind/gate/unregister sections with multi-language tabbed examples including condition_function_id gating and unregister() handles.
Worker starting and stopping reference
docs/using-iii/workers.mdx, docs/using-iii/workers.mdx.skill.md
Adds "Managing workers" subsections (listing, starting/stopping, updating, removing), updates examples/notes to reference worker.trigger, and reorganizes versioning/lockfile guidance.

Navigation and Styling

Layer / File(s) Summary
Documentation navigation restructuring
docs/docs.json
Adds creating-workers/index, reorders Creating Workers pages, and updates Understanding iii group to include only index/engine/channels entries.
Accordion and code-block styling
docs/custom.css
Adjusts code block typography/padding and adds accordion theming to align Mintlify accordion presentation with table styling.
Landing page messaging update
docs/index.mdx, docs/index.mdx.skill.md
Rephrases "The Solution" to emphasize "iii reduces quadratic effort to zero" and rewraps the three-primitives description.

How-to Guide Stubs

Layer / File(s) Summary
Cron scheduling and trigger conditions how-to stubs
docs/how-to/schedule-cron-task.mdx, docs/how-to/schedule-cron-task.mdx.skill.md, docs/how-to/use-trigger-conditions.mdx, docs/how-to/use-trigger-conditions.mdx.skill.md
Adds two how-to skeleton pages with TODOs: scheduling cron tasks with iii-cron, and gating triggers with condition functions (condition_function_id).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • iii-hq/iii#1651 — Overlaps on trigger type model and registerTriggerType/registerTrigger flow.
  • iii-hq/iii#1242 — Related to HTTP-invokable functions and HttpInvocationConfig documentation.
  • iii-hq/iii#1346 — Related to function schema field naming and metadata semantics.

Suggested reviewers

  • mfpiccolo
  • sergiofilhowz

"🐰 I scribble docs with a hop and hop,
Functions, triggers — I never stop.
HTTP doors and schemas show,
Worker names that let things flow,
Docs stitched up from top to top!"

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and specifically summarizes the main documentation restructuring: a new creating-workers section and a landing page copy refinement.
Description check ✅ Passed The description is comprehensive, organized into clear sections (Summary, Original scope), and details the major documentation restructuring, code merges, scope metrics, and related PR information.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/phase-2

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

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.


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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 20, 2026

skill-check — docs

285 verified, 0 skipped.

Layer Result
structure
vale
ai

Three for three. Nicely done.

@mintlify
Copy link
Copy Markdown

mintlify Bot commented May 20, 2026

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
iii 🟢 Ready View Preview May 20, 2026, 3:49 PM

💡 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]>
@anthonyiscoding anthonyiscoding changed the title docs: creating-workers overview + landing copy pass docs: creating-workers overview + landing copy nit May 20, 2026
@anthonyiscoding anthonyiscoding changed the title docs: creating-workers overview + landing copy nit docs: creating-workers section + landing copy nit May 20, 2026
@anthonyiscoding anthonyiscoding changed the title docs: creating-workers section + landing copy nit docs phase 2: creating-workers section + landing copy nit May 20, 2026
anthonyiscoding and others added 3 commits May 20, 2026 13:12
…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]>
anthonyiscoding and others added 2 commits May 20, 2026 14:48
…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]>
@anthonyiscoding
Copy link
Copy Markdown
Contributor Author

#1677 is related but there shouldn't be any conflicts besides docs.json, easy to resolve

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between 8491071 and 4e62745.

📒 Files selected for processing (35)
  • .skill-check.yaml
  • docs/creating-workers/channels.mdx
  • docs/creating-workers/channels.mdx.skill.md
  • docs/creating-workers/functions.mdx
  • docs/creating-workers/functions.mdx.skill.md
  • docs/creating-workers/triggers.mdx
  • docs/creating-workers/triggers.mdx.skill.md
  • docs/creating-workers/workers.mdx
  • docs/creating-workers/workers.mdx.skill.md
  • docs/custom.css
  • docs/docs.json
  • docs/understanding-iii/channels.mdx
  • docs/understanding-iii/channels.mdx.skill.md
  • docs/understanding-iii/functions.mdx
  • docs/understanding-iii/functions.mdx.skill.md
  • docs/understanding-iii/index.mdx
  • docs/understanding-iii/index.mdx.skill.md
  • docs/understanding-iii/triggers.mdx
  • docs/understanding-iii/triggers.mdx.skill.md
  • docs/understanding-iii/workers.mdx
  • docs/understanding-iii/workers.mdx.skill.md
  • docs/using-iii/channels.mdx
  • docs/using-iii/channels.mdx.skill.md
  • docs/using-iii/console.mdx
  • docs/using-iii/console.mdx.skill.md
  • docs/using-iii/deployment.mdx
  • docs/using-iii/deployment.mdx.skill.md
  • docs/using-iii/engine.mdx
  • docs/using-iii/engine.mdx.skill.md
  • docs/using-iii/functions.mdx
  • docs/using-iii/functions.mdx.skill.md
  • docs/using-iii/triggers.mdx
  • docs/using-iii/triggers.mdx.skill.md
  • docs/using-iii/workers.mdx
  • docs/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

Comment thread docs/creating-workers/functions.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]>
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