Documentation: Structured, modular Onboarding Guide for new users & operators

[smota]

Hi everyone,

### What I'm trying to solve
OpenRig is an incredible tool for coordinating AI coding agents, but the initial learning curve for a new operator after running rig setup can feel steep.

Currently, docs/reference/getting-started.md carries a lot of weight - combining first-run mechanics, low-level platform edge-cases (WSL2 networking, Node ABI checks), and kernel handoffs in a single 1,000+ line document. For a newcomer asking:

• "What is the actual mental model between a harness, a seat, a pod, and a rig?"

• "Where does OpenRig store files, and what does each file/setting do?"

• "How do I onboard my existing git repository into OpenRig without dirtying my git tree?"

• "How do I run and drive my first rig (starter or workshop) day-to-day?"

  ...finding the answers requires piecing together information across several deep reference pages and scripts.

### Proposed Solution & Information Architecture
To make onboarding intuitive, progressive, and operator-friendly, I explored organizing new-user documentation into a dedicated subfolder under docs/reference/onboarding/, anchored by a visual navigation index:

docs/reference/onboarding/
|- index.md                              # Master navigation hub & dual-track roadmap (Fast vs Deep path)
|- 01-core-concepts.md                   # Architectural taxonomy (Daemon, Rig, Pod, Seat, Harness, Context)
|- 02-configuration-and-storage.md       # Map of $OPENRIG_HOME, provider hooks, and in-repo files
|- 03-onboarding-your-first-project.md   # Git hygiene (.git/info/exclude), cataloging & project intent
|- 04-operating-your-first-rig.md        # starter vs workshop, rig up --plan, rig ps, task dispatch & queue
|- 05-daily-workflows-and-craft.md       # The SDLC loop, postures (human-led vs delegated), seams & proof
|- 06-troubleshooting-and-diagnostics.md # 4-step triage ladder & common friction remedies

Key principles of this structure:

1. Separation of Concerns: Leaves deep reference and platform-specific troubleshooting intact while providing a progressive disclosure on-ramp for beginners.
2. Package & Guard Compliance: Sits under docs/reference/, so it packages cleanly via scripts/build-package.sh, materializes to $OPENRIG_HOME/reference/, and passes scripts/check-docs-guard.mjs.
3. Operator-First Mindset: Assumes installation is working and focuses purely on enabling the user to become productive with rigs and projects quickly.

### Prototype / Reference Implementation
I have implemented a complete working draft of this documentation suite on my fork:

• Branch / Folder: https://github.com/smota/openrig/tree/main/docs/reference/onboarding https://github.com/smota/openrig/tree/main/docs/reference/onboarding
• Commit: 3f4ee57 smota@3f4ee57d

### Questions & Next Steps

• Does this modular onboarding structure align with your vision for OpenRig's documentation and new-user experience?
• Would you be open to a PR based on this scope?
• If this direction resonates, I would be glad to refine the content based on your feedback and explore further contributions (e.g. interactive guides, visual diagrams, or CLI onboarding hints).

Would love to hear your thoughts and suggestions!

[mvschwarz]

Thanks, @smota, for naming the questions newcomers actually ask and for building a full draft rather than only suggesting one. We'll read your draft and reply here on both questions: whether the structure fits, and whether a PR on this scope does.

[mvschwarz]

Following up on both questions, @smota.

Your WSL2 finding. The WSL2 note in your draft is useful: with WSL2 mirrored networking and the firewall on, a probe of an unused loopback port hung instead of being refused, and starting the daemon then failed. That matches our code: when there's no saved daemon state, rig daemon start probes the port first and stops if that probe times out. We haven't reproduced it on WSL. We'd welcome one small PR for it, separate from the onboarding guide: a short, factual note with the versions and the result you observed. To write it, could you share your Windows and WSL versions, which of the workarounds in your draft you ran and what happened, and whether you tried NAT mode or another loopback address?

The onboarding guide. Yes to a better path for newcomers, but not as a second full guide alongside our references. Your chapters 02 and 03 repeat material those references already keep: the $OPENRIG_HOME folder layout, how a project selects its skills from the managed skill catalog, project.yaml and rig context work-install, in docs/reference/instance-layout.md and docs/reference/project-workspace.md. A second copy would have to be kept true at every release, so we won't take the full guide into this repository, though it's welcome in yours. What we'd welcome instead is one short newcomer index that links to the existing pages. Where you find a gap in one of those pages, fixing it there is welcome too. So is moving the platform details out of the main flow of getting-started.md: you're right that it's long and mixes the first run with edge cases.

Either PR may need a rebase on our own docs edits, and neither comes with a promise of a merge or a date.

[smota]

@mvschwarz thanks for the quick review and analysis

WSL2
I will rewrite the reference note to be short and factual to submit a quick PR.

ONBOARDING GUIDE
If I read right (in other comments as well), it seems there is a major rewrite of the docs for an upcoming release, is it right? If the case - I'm happy to keep an eye and work from there once this is done.

[mvschwarz]

Thanks, @smota. Your WSL2 note is welcome, and #1061 is our proposed fix for the first-start failure you found, so your note can link to it. With #1061, a first rig daemon start no longer stops when its probe of the unused port goes unanswered, as happened in your setup. We've tested it on Linux, not on WSL2. Its description credits you, and it's open and in review.

On the docs: no, there's no major rewrite coming. We bring the docs up to date with each release, as we just did for 0.6.8. So the newcomer index we described in our last reply can be written against the current docs whenever you're ready.

[mvschwarz]

An update, @smota: #1061, our fix for the first-start failure you found with WSL2 mirrored networking, is merged to main. A first rig daemon start no longer stops when its probe of the unused port goes unanswered. We've tested it on Linux, not on WSL2. It will ship in the next release. Thanks again for the finding.

[mvschwarz]

An update, @smota: OpenRig 0.6.10 is out on npm (release notes: https://github.com/mvschwarz/openrig/releases/tag/v0.6.10). It includes #1061, our fix for the first-start failure you found with WSL2 mirrored networking. A first rig daemon start after a timed-out probe now goes ahead when the port is free, and it's refused only when the port is really held, with the refusal naming --port. So far we've tested it only on Linux, not on WSL2. To upgrade, run npm install -g @openrig/cli, then restart the daemon with rig daemon stop and rig daemon start. Thanks again for the finding.