feat(docs): top level docs for repository structure and sops#255
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR restructures worker documentation by migrating from scattered legacy references to a centralized docs/sops/ and docs/architecture/ hierarchy, introducing comprehensive SOPs for adding workers and releasing versions, and expanding session-manager support in CI/CD automation. ChangesDocumentation Architecture and Workflow Updates
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 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 |
Contributor
skill-check — worker0 verified, 17 skipped (no docs/).
Four for four. Nicely done. |
ytallo
approved these changes
Jun 12, 2026
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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/architecture/iii-worker-yaml.md`:
- Around line 24-27: Update the "targets" documentation to explicitly state that
any custom `targets` list must include the Linux boot artifact triple
`x86_64-unknown-linux-gnu` (the release path always boots that artifact), and
add a short warning that omitting it will allow publish to build but will fail
at boot; reference the existing default matrix in `_rust-binary.yml` for
examples and show a minimal example `targets:` snippet that preserves the
required triple.
- Around line 31-35: Update docs so it's clear that the interface_smoke field
controls both the interface boot smoke and the release workflow's registry
publish gating: document that setting interface_smoke: false disables the
interface boot smoke AND causes the release job gating condition
(needs.setup.outputs.interface_smoke != 'false') to skip the registry publish
while build jobs still run; amend docs/architecture/testing-and-ci.md to include
this behavior and ensure wording matches docs/architecture/iii-worker-yaml.md
where interface_smoke is described.
🪄 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
Run ID: 3ef0475a-68c7-495a-b28f-7917caa6ad00
📒 Files selected for processing (28)
.github/scripts/validate_worker.py.github/workflows/create-tag.yml.github/workflows/release.ymlREADME.mdcoder/src/config.rscoder/src/functions/mod.rscoder/tests/integration.rscoder/tests/manifest.rsdocs/README.mddocs/architecture/README.mddocs/architecture/deploy-modes.mddocs/architecture/iii-worker-yaml.mddocs/architecture/per-worker-architecture.mddocs/architecture/skills-and-permissions.mddocs/architecture/testing-and-ci.mddocs/architecture/worker-model.mddocs/sops/README.mddocs/sops/binary-worker.mddocs/sops/new-worker.mddocs/sops/release.mdemail/README.mdiii-lsp/README.mdstorage/README.mdstorage/src/config.rsstorage/tests/integration.rstodo-worker-python/README.mdtodo-worker/README.mdworker-readme.md
Comment on lines
+24
to
+27
| When `targets` is omitted, all nine default triples are built: macOS | ||
| x86_64/aarch64, Windows x86_64/i686/aarch64, Linux x86_64 gnu/musl, | ||
| aarch64 gnu, and armv7 gnueabihf (the matrix lives in | ||
| [`_rust-binary.yml`](../../.github/workflows/_rust-binary.yml)). |
There was a problem hiding this comment.
Call out the required Linux boot target.
The targets list reads like an arbitrary subset, but the release path always boots the x86_64-unknown-linux-gnu artifact. If a manifest omits that triple, publish will build successfully but fail at boot time. Please document that custom targets must keep the Linux gnu target.
🛠️ Suggested doc tweak
-When `targets` is omitted, all nine default triples are built: macOS
-x86_64/aarch64, Windows x86_64/i686/aarch64, Linux x86_64 gnu/musl,
-aarch64 gnu, and armv7 gnueabihf (the matrix lives in
-[`_rust-binary.yml`](../../.github/workflows/_rust-binary.yml)).
+When `targets` is omitted, all nine default triples are built: macOS
+x86_64/aarch64, Windows x86_64/i686/aarch64, Linux x86_64 gnu/musl,
+aarch64 gnu, and armv7 gnueabihf (the matrix lives in
+[`_rust-binary.yml`](../../.github/workflows/_rust-binary.yml)).
+
+If you override `targets`, keep `x86_64-unknown-linux-gnu` in the list;
+publish boots that artifact.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| When `targets` is omitted, all nine default triples are built: macOS | |
| x86_64/aarch64, Windows x86_64/i686/aarch64, Linux x86_64 gnu/musl, | |
| aarch64 gnu, and armv7 gnueabihf (the matrix lives in | |
| [`_rust-binary.yml`](../../.github/workflows/_rust-binary.yml)). | |
| When `targets` is omitted, all nine default triples are built: macOS | |
| x86_64/aarch64, Windows x86_64/i686/aarch64, Linux x86_64 gnu/musl, | |
| aarch64 gnu, and armv7 gnueabihf (the matrix lives in | |
| [`_rust-binary.yml`](../../.github/workflows/_rust-binary.yml)). | |
| If you override `targets`, keep `x86_64-unknown-linux-gnu` in the list; | |
| publish boots that artifact. |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~26-~26: The official name of this software platform is spelled with a capital “H”.
Context: ...nd armv7 gnueabihf (the matrix lives in _rust-binary.yml). ## Opt-o...
(GITHUB)
🤖 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/architecture/iii-worker-yaml.md` around lines 24 - 27, Update the
"targets" documentation to explicitly state that any custom `targets` list must
include the Linux boot artifact triple `x86_64-unknown-linux-gnu` (the release
path always boots that artifact), and add a short warning that omitting it will
allow publish to build but will fail at boot; reference the existing default
matrix in `_rust-binary.yml` for examples and show a minimal example `targets:`
snippet that preserves the required triple.
Comment on lines
+31
to
+35
| | Field | Purpose | Consumer | | ||
| |---|---|---| | ||
| | `interface_smoke: false` | Skip interface boot smoke + registry publish | `ci.yml`, `release.yml` | | ||
| | `runtime` / `scripts.start` | Local boot definition; presence routes publish boot to `iii-add` for non-binary/bundle deploys | `manifest_version.py deploy-mode`, `iii worker add` | | ||
| | `scripts.install` | Build command for local install | `iii worker add` (local source) | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n "interface_smoke" .github/workflows .github/scriptsRepository: iii-hq/workers
Length of output: 1359
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show release.yml semantics around the interface_smoke gate
sed -n '1,260p' .github/workflows/release.yml | nl -ba | sed -n '1,260p'
# Show ci.yml semantics around the interface_smoke gate
sed -n '150,260p' .github/workflows/ci.yml | nl -ba | sed -n '1,260p'
# Find and show documentation text about interface_smoke (e.g., testing-and-ci.md)
rg -n "interface_smoke" docs -S || true
rg -n "interface_smoke" . -S --glob '!**/node_modules/**' --glob '!**/dist/**' | head -n 50Repository: iii-hq/workers
Length of output: 101
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show relevant parts of release.yml (with line numbers via cat -n)
cat -n .github/workflows/release.yml | sed -n '1,260p'
# Show relevant parts of ci.yml
cat -n .github/workflows/ci.yml | sed -n '150,260p'
# Locate docs and show the surrounding interface_smoke text
rg -n "interface_smoke" docs -S || true
docfile="$(rg -l "interface_smoke" docs -S | head -n 1 || true)"
if [ -n "$docfile" ]; then
echo "=== $docfile ==="
cat -n "$docfile" | sed -n '1,260p'
fi
# Also print the specific comment blocks near the earlier matches in workflows
rg -n "A worker may declare `interface_smoke: false`|opts out of interface boot smoke|interface_smoke != 'false'|needs.setup.outputs.interface_smoke != 'false'" .github/workflows -SRepository: iii-hq/workers
Length of output: 24968
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the exact table row in the file under review
echo "=== docs/architecture/iii-worker-yaml.md (around interface_smoke) ==="
cat -n docs/architecture/iii-worker-yaml.md | sed -n '1,120p'
# Show testing-and-ci.md section that defines interface_smoke opt-out semantics
echo "=== docs/architecture/testing-and-ci.md (interface_smoke section) ==="
cat -n docs/architecture/testing-and-ci.md | sed -n '1,140p'
# Show any other doc references for cross-check
echo "=== Other docs mentioning interface_smoke ==="
rg -n "interface_smoke" docs/architecture -SRepository: iii-hq/workers
Length of output: 7704
Clarify interface_smoke: false scope across CI vs release docs.
interface_smoke: false skips the interface boot smoke and gates the release workflow’s registry publish job (needs.setup.outputs.interface_smoke != 'false'), while build jobs still run. docs/architecture/testing-and-ci.md should mention this (so it doesn’t read like a CI-only smoke opt-out), keeping it consistent with docs/architecture/iii-worker-yaml.md.
🤖 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/architecture/iii-worker-yaml.md` around lines 31 - 35, Update docs so
it's clear that the interface_smoke field controls both the interface boot smoke
and the release workflow's registry publish gating: document that setting
interface_smoke: false disables the interface boot smoke AND causes the release
job gating condition (needs.setup.outputs.interface_smoke != 'false') to skip
the registry publish while build jobs still run; amend
docs/architecture/testing-and-ci.md to include this behavior and ensure wording
matches docs/architecture/iii-worker-yaml.md where interface_smoke is described.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduce a top-level
docs/tree for worker onboarding and shared architecture, and repoint existing references to it.docs/sops/— procedures:new-worker.md(cross-cutting checklist),binary-worker.md(moved from repo root; sections 1–12 unchanged),release.md(cut, troubleshoot, verify)docs/architecture/— shared reference: worker model,iii.worker.yaml, deploy modes, CI/testing, skills/permissions, per-worker architecture docsdocs/README.md— navigation index (“I want to…” → doc)Root
README.md,worker-readme.md, and worker READMEs now link intodocs/instead of the oldbinary-worker.md/AGENTS-NEW-WORKER.mdpaths.Notable details
binary-worker.mdmove is verbatim apart from link rewrites and a one-line header pointer; code comments citing§5/§7/§9/§11still land on the same sections.new-worker.md§6 documents the full release wiring surface (create-tag options, release tag patterns,ALLOWED_WORKERS,BOOTSTRAP_WORKERS) and flags known drift (emailships skills but isn’t inALLOWED_WORKERS).harness/src/skills.rs::BOOTSTRAP_NAMES(file gone after TS harness rewrite);BOOTSTRAP_WORKERSinvalidate_worker.pyis the source of truth.session-managerrelease wiring — added tocreate-tag.ymloptions andrelease.ymltag patterns (small CI/CD fix bundled with the docs work).Test plan
docs/and touched READMEs resolvebinary-worker.mdorAGENTS-NEW-WORKER.mdpytest .github/scripts/tests/passesdocs/not picked up by worker discovery (iii.worker.yamlabsent)Summary by CodeRabbit
Documentation
Chores