docs(workers): fix startup commands and broken README images - #642
Conversation
Quickstart sections referenced iii start (not a real subcommand, the engine boots via bare iii / iii --config) and the old mkdir/touch/iii -c bootstrap instead of iii project init.
The two README images pointed at hashed iii.dev/blog/_astro assets that now 404 (registry and GitHub both rendered broken images). Commit the screenshots under harness/docs/images and reference them via raw.githubusercontent.com, same pattern as console/screenshot.png.
rohitg00
added
the
no-ticket
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
skill-check — worker0 verified, 50 skipped (no docs/).
Four for four. Nicely done. |
📝 WalkthroughWalkthroughDocumentation now describes worker startup on the next engine boot, updates console, harness, and storage quickstarts, changes local configuration commands, and replaces harness screenshot references and image assets. ChangesDocumentation refresh
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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: 1
🤖 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 `@console/README.md`:
- Around line 107-119: The quickstart commands start the engine before
installing workers, despite worker installation taking effect on the next engine
start. In console/README.md lines 107-119, move “iii worker add console” before
the first “iii” command or add an engine restart afterward; apply the same
ordering correction in harness/README.md lines 44-58 for “worker add harness
console”.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 86eb6bd7-cb73-47b6-98c3-cb9f35939b0b
📒 Files selected for processing (20)
bridge/README.mdbrowser/README.mdconsole/README.mdcontext-manager/README.mdcron/README.mddocs/sops/binary-worker.mdgithub/README.mdharness/README.mdharness/docs/images/configure-a-provider.webpharness/docs/images/console-traces.webphttp/README.mdiii-directory/README.mdprovider-anthropic/README.mdpubsub/README.mdqueue/README.mdsession-manager/README.mdstate/README.mdstorage/README.mdweb/README.mdworker-readme.md
| This fetches the prebuilt binary, writes a `console:` block into `~/.iii/config.yaml`, and the engine launches the worker the next time it boots. | ||
|
|
||
| ## Quickstart | ||
|
|
||
| ```bash | ||
| iii start # engine on ws://127.0.0.1:49134 | ||
| console --http-port 3113 # UI + /ws proxy on :3113 | ||
| curl -fsSL https://install.iii.dev/iii/main/install.sh | sh | ||
| iii project init iii-app && cd iii-app | ||
| iii # engine on ws://127.0.0.1:49134 | ||
| ``` | ||
|
|
||
| ```bash | ||
| # New terminal, same folder | ||
| iii worker add console # UI + /ws proxy on :3113 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== repository files =="
git ls-files | sed -n '1,120p'
echo "== README occurrences =="
for f in console/README.md harness/README.md; do
if [ -f "$f" ]; then
echo "--- $f lines 1-180 ---"
nl -ba "$f" | sed -n '1,180p'
else
echo "missing $f"
fi
done
echo "== search worker add / next-boot wording =="
rg -n "worker add|next boot|next-boot|boot|console|worker" console harness README.md . --glob '!node_modules' --glob '!dist' --glob '!build' 2>/dev/null | sed -n '1,240p'Repository: iii-hq/workers
Length of output: 4718
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate README files =="
find . -type f \( -name 'README.md' -o -path '*/README.md' \) | grep -E '(^|/)console/README\.md$|(^|/)harness/README\.md$|(^|/)README\.md$' | sed -n '1,80p'
echo "== console README relevant lines =="
if [ -f console/README.md ]; then
awk 'BEGIN{n=1} n>=1 && n<=140 {printf "%3d\t%s\n", NR, $0; n++}' console/README.md
else
echo "missing console/README.md"
fi
echo "== harness README relevant lines =="
if [ -f harness/README.md ]; then
awk 'BEGIN{n=1} n>=1 && n<=90 {printf "%3d\t%s\n", NR, $0; n++}' harness/README.md
else
echo "missing harness/README.md"
fi
echo "== search worker add / next-boot wording =="
rg -n "worker add|next boot|next-boot|boot|console|worker" . \
--glob '!node_modules' --glob '!dist' --glob '!build' --glob '!target' \
2>/dev/null | sed -n '1,260p'Repository: iii-hq/workers
Length of output: 50372
🌐 Web query:
iii worker add worker boot next boot config config.yaml
💡 Result:
The command iii worker add is used to install and register a worker in your project [1][2]. When you run this command, the worker is added to your project's config.yaml file, and it starts automatically [1][3]. Regarding the behavior of boot configuration: 1. Initial Seeding: When a worker is added, its configuration can be provided as a config: block in config.yaml [4][5]. This block acts as a first-boot seed, read by the worker once if it registers a configuration schema [5]. 2. Lifecycle: Once the worker has registered its schema, its settings are managed by the configuration worker (stored in files under./config/) [5]. On the next boot after the initial seed is consumed, the engine removes the config: block from config.yaml, leaving a comment in its place, and thereafter treats the configuration worker as the source of truth [4][5]. 3. Exceptions: If a worker does not register a configuration schema, it will continue to read its config: block directly from config.yaml on every boot [5]. The configuration worker itself is also an exception; its config: block remains in config.yaml and is read on every boot [5]. You do not generally need to manually manage the boot sequence in config.yaml; the engine handles the transition from the bootstrap seed to the persistent configuration store automatically [4][6]. If you need to force a re-download or re-initialization of a worker, you can use iii worker reinstall [1][2].
Citations:
- 1: https://iii.dev/docs/next/using-iii/workers
- 2: https://iii.dev/docs/0-20-0/using-iii/workers
- 3: https://iii.dev/docs/next/using-iii/workers-registry
- 4: https://iii.dev/docs/next/using-iii/engine
- 5: https://iii.dev/docs/next/using-iii/configuration
- 6: https://iii.dev/docs/0-11-0/how-to/managing-container-workers
🌐 Web query:
site:iii.dev "worker add" "next boot"
💡 Result:
In the context of the iii engine, "next boot" refers to when certain configuration changes take effect [1]. Most configuration settings for workers apply immediately upon being changed through the configuration worker [1]. However, some specific settings are designated as "restart-tier" [1]. When these restart-tier settings are modified, the change is recorded and logged by the engine, but it does not take effect until the next engine start (the next boot) [1]. Additionally, the config: block found under a worker entry in the config.yaml file acts as a first-boot seed [1][2]. This configuration is read exactly once, during the worker's first boot after it registers its schema [1][2]. Once the engine consumes this block at that first boot, it removes the block from config.yaml and manages the worker's settings subsequently via the configuration worker and per-worker files in the ./config/ directory [1][2].
Citations:
🌐 Web query:
site:github.com/iii-hq "iii worker add" "next time" "next boot"
💡 Result:
When you run the command iii worker add, the iii engine fetches the specified worker binary and writes a configuration block into your ~/.iii/config.yaml file [1][2][3][4][5]. This action prepares the worker to be initialized, and the engine will automatically start it during the next iii start or system boot [1][2][3][4][5]. In summary, the add command performs the registration and configuration step, while the actual process lifecycle is managed by the engine on subsequent launches [1][3][5]. If you need to seed specific configuration values for a worker during this initial process, many workers allow you to pass a --config flag to provide a YAML file for the first-boot setup [4][5][6].
Citations:
- 1: https://github.com/iii-hq/workers/blob/main/cron/README.md
- 2: https://github.com/iii-hq/workers/blob/main/worktree/README.md
- 3: https://github.com/iii-hq/workers/tree/main/iii-directory
- 4: https://github.com/iii-hq/workers/tree/main/session-manager
- 5: https://github.com/iii-hq/workers/tree/main/storage
- 6: https://github.com/iii-hq/workers/tree/main/rbac-proxy
Align worker installation with the engine start order.
console/README.md says adding a worker prepares it for the next engine start, but the console quickstart starts the engine before running iii worker add console. Move console installation before the first iii, or add a restart after it; the same ordering applies to harness/README.md where worker add harness console runs after iii.
📍 Affects 2 files
console/README.md#L107-L119(this comment)harness/README.md#L44-L58
🤖 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 `@console/README.md` around lines 107 - 119, The quickstart commands start the
engine before installing workers, despite worker installation taking effect on
the next engine start. In console/README.md lines 107-119, move “iii worker add
console” before the first “iii” command or add an engine restart afterward;
apply the same ordering correction in harness/README.md lines 44-58 for “worker
add harness console”.
1 participant
What
Two documentation fixes for content the registry serves verbatim on workers.iii.dev.
Startup commands. The harness and console Quickstarts told users to bootstrap with
mkdir iii-app && touch config.yaml && iii -c config.yaml(harness) oriii start(console). Neither is the current flow:iii startis not a subcommand of the CLI, and manual config bootstrap was replaced byiii project init. Both Quickstarts now read:The same fictional
iii startsentence ("the engine starts the worker on the nextiii start") was templated into 14 more worker READMEs,worker-readme.md, anddocs/sops/binary-worker.md; all now say the engine starts the worker the next time it boots.Broken harness README images. Both screenshots pointed at hashed
iii.dev/blog/_astro/*.webpassets that return 404, so the registry and GitHub rendered broken images. The screenshots are now committed underharness/docs/images/and referenced via raw.githubusercontent.com, the same patternconsole/screenshot.pngalready uses.Verification
iii --helpliststrigger, console, cloud, worker, project, update; nostart.iii project init --helpconfirms the init flow.git grep "iii start" -- '*.md'returns nothing outside test fixtures.Summary by CodeRabbit