Docs: rewrite quickstart as a step-by-step tutorial - #1452
Conversation
Replace the thin "scaffold and read the README" page with a self-contained tutorial that walks through scaffolding, starting workers, calling functions across languages, and understanding the code.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughReplaces the prior quickstart with an end-to-end cross-language walkthrough: scaffold a template, start the iii engine with Changes
Sequence Diagram(s)sequenceDiagram
participant Dev as Developer (CLI / Browser)
participant CLI as iii CLI
participant Engine as iii Engine
participant WorkerA as math-worker (Python)
participant WorkerB as caller-worker (TypeScript)
Dev->>CLI: scaffold template
Dev->>Engine: start with `config.yaml`
CLI->>Engine: register worker manifests (`iii worker add`)
Engine->>WorkerA: open connection / register `math::add`
Engine->>WorkerB: open connection / register `math::add_two_numbers`
Dev->>CLI: trigger `math::add_two_numbers`
CLI->>Engine: send trigger
Engine->>WorkerB: invoke `math::add_two_numbers`
WorkerB->>Engine: trigger `math::add` (cross-language)
Engine->>WorkerA: invoke `math::add`
WorkerA-->>Engine: return result
Engine-->>WorkerB: deliver result
WorkerB-->>Engine: return composed result
Engine-->>Dev: return JSON payload / Console shows result
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
docs/quickstart.mdx (1)
164-166: Tighten the cross-language explanation sentence for readabilityThis is a run-on sentence and reads awkwardly. Splitting it improves clarity without changing meaning.
Suggested doc patch
-`registerWorker` connects to the engine the same way the Python worker does. The `iii.trigger()` call inside the handler invokes -`math::add` on the Python worker through the engine the TypeScript worker doesn't need to know where the `math::add` function -is running, its language, or anything else. +`registerWorker` connects to the engine the same way the Python worker does. The `iii.trigger()` call inside the handler invokes +`math::add` on the Python worker through the engine. The TypeScript worker doesn't need to know where `math::add` is running, +which language it uses, or any transport details.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/quickstart.mdx` around lines 164 - 166, The sentence describing cross-language invocation is a run-on and should be split for clarity: reword the paragraph around registerWorker so it states that registerWorker connects to the engine similarly to the Python worker, and then in a separate sentence explain that the iii.trigger() call inside the handler invokes math::add on the Python worker through the engine, so the TypeScript worker does not need to know where math::add is running or its language. Reference registerWorker, iii.trigger(), and math::add when updating the two shorter sentences.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/quickstart.mdx`:
- Around line 88-93: The JSON example in the fenced json block containing `"c":
5, // ...` is invalid; update the example used by the `json` code fence (the
snippet with `"c": 5`) to be valid JSON by removing the `// ...` comment and the
trailing comma — e.g., change the block to a proper object `{ "c": 5 }` so
copy/paste and validators accept it.
- Around line 99-100: The sentence in Step 6 ("Now open a fourth terminal...")
conflicts with Step 5 which already uses the fourth terminal; update the wording
in docs/quickstart.mdx to refer to the correct terminal number (change "fourth"
to "fifth" in the Step 6 sentence) or alternatively renumber the earlier step so
terminal counts are sequential; locate the sentence text "Now open a fourth
terminal in the `quickstart` directory and call the TypeScript worker." and make
the terminal numbering consistent with Step 5.
- Around line 33-40: Add a "You should see" terminal output block immediately
after the Step 2 command `iii --config config.yaml` showing a short startup log
(modeled on Steps 3/4) that includes something like "Engine started" and
"WebSocket listening on ws://localhost:49134" so users can verify the engine
booted successfully, then retain the existing note to keep the terminal open.
---
Nitpick comments:
In `@docs/quickstart.mdx`:
- Around line 164-166: The sentence describing cross-language invocation is a
run-on and should be split for clarity: reword the paragraph around
registerWorker so it states that registerWorker connects to the engine similarly
to the Python worker, and then in a separate sentence explain that the
iii.trigger() call inside the handler invokes math::add on the Python worker
through the engine, so the TypeScript worker does not need to know where
math::add is running or its language. Reference registerWorker, iii.trigger(),
and math::add when updating the two shorter sentences.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/quickstart.mdx (1)
33-40:⚠️ Potential issue | 🟠 MajorAdd an engine startup “You should see” output block in Step 2.
Line 39 gives the endpoint, but users still need a concrete terminal-output check (like Steps 3/4) to verify engine boot success.
Suggested patch
## 2. Start the engine ```bash iii --config config.yaml-The engine is now listening on
ws://localhost:49134. Keep this terminal open.
+You should see output that includes the WebSocket endpoint, for example:
+
+text +Engine started +WebSocket listening on ws://localhost:49134 +
+
+Keep this terminal open.</details> As per coding guidelines: “Ensure the quickstart is a self-contained, step-by-step tutorial … start the engine … and instruct users to keep that terminal open (include the documented default WS URL/port).” <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/quickstart.mdxaround lines 33 - 40, Add a "You should see"
terminal-output example immediately after the Step 2 command block (theiii --config config.yamlblock) showing a successful engine start that includes the
documented WebSocket endpoint (e.g., lines like "Engine started" and "WebSocket
listening on ws://localhost:49134"); replace the current single-sentence note
with this output example followed by "Keep this terminal open." to give users a
concrete check that the engine booted.</details> </blockquote></details> </blockquote></details> <details> <summary>🧹 Nitpick comments (1)</summary><blockquote> <details> <summary>docs/quickstart.mdx (1)</summary><blockquote> `147-149`: **Tighten this run-on sentence for readability.** Lines 147-149 currently merge multiple clauses and are harder to scan in a tutorial context. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/quickstart.mdxaround lines 147 - 149, The paragraph is a run-on and
hard to scan; split and tighten it by breaking into two sentences: describe that
registerWorker connects to the engine like the Python worker, and then state
that the iii.trigger() call inside the handler invokes math::add on the Python
worker via the engine—clarify that the TypeScript worker does not need to know
where math::add runs or its language.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@docs/quickstart.mdx:
- Around line 151-169: Add the missing TypeScript worker manifest for the
caller-worker to the "How it works" section so both worker manifests are shown:
create an iii.worker.yaml for the caller-worker with name: caller-worker,
runtime.language: typescript, runtime.package_manager: npm, runtime.entry:
src/worker.ts, and scripts.install/start entries (install: "npm install", start:
"npm run dev") and place it alongside the existing Python manifest so the
quickstart shows both workers' name/runtime/scripts.
Duplicate comments:
In@docs/quickstart.mdx:
- Around line 33-40: Add a "You should see" terminal-output example immediately
after the Step 2 command block (theiii --config config.yamlblock) showing a
successful engine start that includes the documented WebSocket endpoint (e.g.,
lines like "Engine started" and "WebSocket listening on ws://localhost:49134");
replace the current single-sentence note with this output example followed by
"Keep this terminal open." to give users a concrete check that the engine
booted.
Nitpick comments:
In@docs/quickstart.mdx:
- Around line 147-149: The paragraph is a run-on and hard to scan; split and
tighten it by breaking into two sentences: describe that registerWorker connects
to the engine like the Python worker, and then state that the iii.trigger() call
inside the handler invokes math::add on the Python worker via the engine—clarify
that the TypeScript worker does not need to know where math::add runs or its
language.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Repository UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `e4f0b5a1-36d7-4c72-bbb3-dc4e29413068` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 3f63963bf4a3e8188003b3887d48a2ccb3ccfb5c and 97ff5c6528f401f7588383dd9196025c1389afc8. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `docs/quickstart.mdx` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs/quickstart.mdx (1)
155-173:⚠️ Potential issue | 🟠 MajorAdd the TypeScript worker manifest.
Lines 157-160 state "Each worker has an
iii.worker.yaml" but only the Python manifest is shown. Add the TypeScript worker manifest (workers/caller-worker/iii.worker.yaml) to complete the documentation.📄 Proposed addition
`name` identifies the worker. `runtime` tells the engine the language and entrypoint. `scripts` define how to install dependencies and start the worker. + +Here is the TypeScript worker's manifest: + +```yaml +name: caller-worker +runtime: + language: typescript + package_manager: npm + entry: src/worker.ts +scripts: + install: "npm install" + start: "npm run dev" +```As per coding guidelines: "Quickstart should be a self-contained, step-by-step walkthrough that ... includes 'How it works' sections with inline snippets for both the Python and TypeScript worker, plus a 'Worker manifest' section explaining iii.worker.yaml fields (what name/runtime/scripts do)."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/quickstart.mdx` around lines 155 - 173, Add a second YAML manifest example for the TypeScript worker alongside the existing Python manifest: include an `iii.worker.yaml` for `caller-worker` showing runtime.language: typescript, runtime.package_manager: npm, runtime.entry: src/worker.ts and scripts.install: "npm install" and scripts.start: "npm run dev" in a fenced YAML code block so readers can copy the `caller-worker` manifest for their TypeScript worker.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/index.mdx`:
- Line 59: Replace the unhyphenated compound modifier "iii powered" with the
hyphenated form "iii-powered" in the sentence containing "The best way to
understand iii is to try it. [Install iii](/install) and then follow the
[Quickstart](/quickstart) to create your first iii powered project." — update
the phrase "iii powered project" to "iii-powered project" so the compound
adjective correctly modifies "project".
In `@docs/quickstart.mdx`:
- Line 6: Replace the placeholder ellipsis in the opening line "In this tutorial
you will setup a simple iii project that ..." with a complete summary sentence
describing what the tutorial covers, e.g., setting up a new iii project,
installing dependencies, scaffolding a basic app, running the development
server, and building a simple page or component; update the sentence in
docs/quickstart.mdx so it reads as a single clear introductory summary rather
than ending with "...".
---
Duplicate comments:
In `@docs/quickstart.mdx`:
- Around line 155-173: Add a second YAML manifest example for the TypeScript
worker alongside the existing Python manifest: include an `iii.worker.yaml` for
`caller-worker` showing runtime.language: typescript, runtime.package_manager:
npm, runtime.entry: src/worker.ts and scripts.install: "npm install" and
scripts.start: "npm run dev" in a fenced YAML code block so readers can copy the
`caller-worker` manifest for their TypeScript worker.
🪄 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: 12765583-3323-49ae-b21c-4f1eb132e64b
📒 Files selected for processing (4)
docs/docs.jsondocs/index.mdxdocs/install.mdxdocs/quickstart.mdx
✅ Files skipped from review due to trivial changes (2)
- docs/docs.json
- docs/install.mdx
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs/quickstart.mdx (1)
33-40:⚠️ Potential issue | 🟠 MajorAdd a “You should see” startup output for Step 2.
Step 2 still lacks a concrete engine log snippet, so users can’t immediately verify success like they can in later steps. Please add a short expected output block after
iii --config config.yaml.As per coding guidelines: “Provide exact commands and expected outputs for each step … so the reader can verify progress immediately.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/quickstart.mdx` around lines 33 - 40, Add a short "You should see" startup output block immediately after the `iii --config config.yaml` command showing the expected engine log (for example a single-line like: "INFO Listening on ws://localhost:49134" or similar) so readers can verify the engine started; insert this snippet directly after the command and before the sentence "The engine is now listening on `ws://localhost:49134`", ensuring the output mirrors the wording used elsewhere in the doc.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/quickstart.mdx`:
- Line 6: The opening sentence uses the noun "setup" incorrectly; change the
phrase "you will setup a simple iii project" to "you will set up a simple iii
project" in the docs/quickstart.mdx opening sentence (replace the "setup" token
with the verb form "set up").
- Around line 151-153: Split the run-on sentence into two sentences: after
"through the engine." end the first sentence, then start a new sentence
clarifying that the TypeScript worker (the handler using registerWorker and
calling iii.trigger()) does not need to know where math::add is running, its
language, or any other details; ensure you reference registerWorker,
iii.trigger(), and math::add in the revised text for clarity.
---
Duplicate comments:
In `@docs/quickstart.mdx`:
- Around line 33-40: Add a short "You should see" startup output block
immediately after the `iii --config config.yaml` command showing the expected
engine log (for example a single-line like: "INFO Listening on
ws://localhost:49134" or similar) so readers can verify the engine started;
insert this snippet directly after the command and before the sentence "The
engine is now listening on `ws://localhost:49134`", ensuring the output mirrors
the wording used elsewhere in the doc.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
There was a problem hiding this comment.
♻️ Duplicate comments (3)
docs/quickstart.mdx (3)
151-153:⚠️ Potential issue | 🟡 MinorSplit the run-on sentence in the TypeScript explanation.
Add a sentence break after “through the engine.” to keep this tutorial step easy to parse.
📝 Suggested edit
-`registerWorker` connects to the engine the same way the Python worker does. The `iii.trigger()` call inside the handler invokes -`math::add` on the Python worker through the engine the TypeScript worker doesn't need to know where the `math::add` function +`registerWorker` connects to the engine the same way the Python worker does. The `iii.trigger()` call inside the handler invokes +`math::add` on the Python worker through the engine. The TypeScript worker doesn't need to know where the `math::add` function is running, its language, or anything else.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/quickstart.mdx` around lines 151 - 153, The sentence in docs/quickstart.mdx explaining registerWorker and iii.trigger() is a run-on and hard to parse; split it into two sentences by ending the first sentence after "through the engine." so the text reads that `registerWorker` connects to the engine the same way the Python worker does, and then start a new sentence explaining that the `iii.trigger()` call inside the handler invokes `math::add` on the Python worker and that the TypeScript worker doesn't need to know where `math::add` is running or its language.
35-40:⚠️ Potential issue | 🟠 MajorAdd a “You should see” startup snippet in Step 2.
Step 2 should include expected engine startup output so readers can verify success before proceeding.
🧪 Suggested edit
```bash iii --config config.yaml-The engine is now listening on
ws://localhost:49134. Keep this terminal open.
+You should see output that includes the WebSocket endpoint, for example:
+
+text +Engine started +WebSocket listening on ws://localhost:49134 +
+
+Keep this terminal open.</details> As per coding guidelines: “Use clear, numbered sections and multiple terminal commands in separate steps … with expected output snippets.” <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/quickstart.mdxaround lines 35 - 40, Add an expected-output
verification snippet immediately after the existing command block "bash iii --config config.yaml" in Step 2: insert a short "You should see" paragraph
followed by a small example output showing the engine startup and WebSocket
endpoint (e.g., lines like "Engine started" and "WebSocket listening on
ws://localhost:49134") and then restore the "Keep this terminal open." sentence;
ensure the example output is presented as plain output text so readers can
compare their terminal to confirm success.</details> --- `6-6`: _⚠️ Potential issue_ | _🟡 Minor_ **Use the verb form “set up” in the intro sentence.** Please change “will setup” to “will set up” for grammatical correctness. <details> <summary>✏️ Suggested edit</summary> ```diff -In this tutorial you will setup a simple iii project and run two services (which we call workers) that are inherently composable. +In this tutorial you will set up a simple iii project and run two services (which we call workers) that are inherently composable. ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/quickstart.mdx` at line 6, The intro sentence contains the incorrect verb form "will setup"; update the text that reads "In this tutorial you will setup a simple iii project and run two services (which we call workers) that are inherently composable." to use the correct verb phrase "will set up" so it becomes "In this tutorial you will set up a simple iii project..." — locate the sentence by searching for "will setup" in the quickstart content and replace it with "will set up". ``` </details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In@docs/quickstart.mdx:
- Around line 151-153: The sentence in docs/quickstart.mdx explaining
registerWorker and iii.trigger() is a run-on and hard to parse; split it into
two sentences by ending the first sentence after "through the engine." so the
text reads thatregisterWorkerconnects to the engine the same way the Python
worker does, and then start a new sentence explaining that theiii.trigger()
call inside the handler invokesmath::addon the Python worker and that the
TypeScript worker doesn't need to know wheremath::addis running or its
language.- Around line 35-40: Add an expected-output verification snippet immediately
after the existing command block "bash iii --config config.yaml" in Step
2: insert a short "You should see" paragraph followed by a small example output
showing the engine startup and WebSocket endpoint (e.g., lines like "Engine
started" and "WebSocket listening on ws://localhost:49134") and then restore the
"Keep this terminal open." sentence; ensure the example output is presented as
plain output text so readers can compare their terminal to confirm success.- Line 6: The intro sentence contains the incorrect verb form "will setup";
update the text that reads "In this tutorial you will setup a simple iii project
and run two services (which we call workers) that are inherently composable." to
use the correct verb phrase "will set up" so it becomes "In this tutorial you
will set up a simple iii project..." — locate the sentence by searching for
"will setup" in the quickstart content and replace it with "will set up".</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Repository UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `29598f3e-1244-4585-9d49-08cf6e58a3e7` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between ee2b43ef1ac8e0ade824f8862e072f92279dab07 and 6ee1d041e27427c01ebbd996f4b1d5010e20a4fa. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `docs/quickstart.mdx` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
3 participants
Replace the thin "scaffold and read the README" page with a self-contained tutorial that walks through scaffolding, starting workers, calling functions across languages, and understanding the code.
Summary by CodeRabbit