docs: reorganize Homeboy documentation

[chubes4]

Summary

• Rewrite the README as a short visitor-facing front door
• Add docs/start-here.md and top-level workflow/concept/reference/internals/operations indexes
• Move docs into clearer taxonomy buckets while preserving command docs as the CLI reference surface
• Update moved-doc links plus code/test references to the new paths

Verification

• Markdown link check: missing=0 checked=130
• cargo test --test architecture_core_agnostic_test architecture_docs_source_paths_exist
• cargo run --quiet -- docs list
• git diff --check

AI assistance

• AI assistance: Yes
• Tool(s): gpt-5.5 via OpenCode
• Used for: Auditing the docs structure, drafting the new visitor-oriented taxonomy, moving documentation into the new structure, updating links/references, and running verification.

[homeboy-ci]

Homeboy Results — homeboy

Lint

✅ lint — passed

ℹ️ Full options: homeboy docs commands/lint
ℹ️ Save lint baseline: homeboy lint homeboy --baseline
Deep dive: homeboy lint homeboy --changed-since b2638fb

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-homeboy-lint-homeboy-Linux contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-homeboy-lint-homeboy-Linux contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/homeboy/actions/runs/28335915380

Test

⚠️ test — baseline red

ℹ️ No tests ran — the runner failed before producing results. See raw_output.stderr_tail / raw_output.stdout_tail for the underlying error (bootstrap failure, missing deps, DB connection, etc.).
ℹ️ To run specific tests: homeboy test homeboy -- --filter=TestName
ℹ️ Auto-fix lint issues: homeboy refactor homeboy --from lint --write
ℹ️ Collect coverage: homeboy test homeboy --coverage
ℹ️ Analyze failures: homeboy test homeboy --analyze
ℹ️ Pass args to test runner: homeboy test -- [args]
ℹ️ Full options: homeboy docs commands/test
Deep dive: homeboy test homeboy --changed-since b2638fb

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-homeboy-test-homeboy-Linux contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-homeboy-test-homeboy-Linux contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/homeboy/actions/runs/28335915380

Audit

✅ audit — passed

• core_boundary_leak:core-agnostic-source — 70 finding(s)
• structural — 57 finding(s)
• intra-method-duplication — 47 finding(s)
• field_patterns — 35 finding(s)
• dead_code — 19 finding(s)
• near-duplication — 17 finding(s)
• test_quality — 13 finding(s)
• duplication — 10 finding(s)
• remote_execution_preflight — 9 finding(s)
• thin_command_adapter — 8 finding(s)
• Total: 310 finding(s)

Deep dive: homeboy audit homeboy --changed-since b2638fb

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-homeboy-audit-homeboy-Linux contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-homeboy-audit-homeboy-Linux contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/homeboy/actions/runs/28335915380

Tooling versions

• Homeboy CLI: homeboy 0.269.1+4c0e18d5b697+67464bd69
• Extension: rust from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: 7d9b168e
• Action: unknown@unknown

[chubes4]

Second pass pushed in 00c6043b3 docs: expand core workflow guides.

What changed:

• Expanded review-a-branch, capture-evidence, use-runners, and release-a-component from sketches into task guides with when-to-use sections, command sequences, expected artifacts, and failure/proof guidance.
• Added docs/workflows/reproduce-ci.md for declared CI profiles, command-native jobs, differential gates, and autofix dry-runs.
• Strengthened docs/start-here.md, docs/concepts/index.md, and docs/reference/index.md to steer readers by task instead of command name.

Verification rerun:

• Markdown link check: missing=0 checked=131
• cargo run --quiet -- docs list
• cargo test --test architecture_core_agnostic_test architecture_docs_source_paths_exist
• git diff --check

Note: Rust commands still emit existing warnings unrelated to this docs work.

[chubes4]

Third pass pushed in 3933b0dbd docs: document agent task loops.

What changed:

• Added docs/workflows/run-agent-task-loops.md as a task guide for durable agent-task loops, controller specs, bounded execution, external events, human-ready handoffs, retries/request-changes, and durable evidence.
• Linked the loop guide from README, docs/index.md, docs/start-here.md, and docs/workflows/index.md.
• Clarified when to use one-shot agent-task cook versus named loops versus lower-level controllers.

Verification rerun:

• Markdown link check: missing=0 checked=132
• cargo run --quiet -- docs list includes workflows/run-agent-task-loops
• cargo test --test architecture_core_agnostic_test architecture_docs_source_paths_exist
• git diff --check

Note: Rust commands still emit existing warnings unrelated to this docs work.

[chubes4]

Generalized setup/orchestration pass pushed in 67464bd69 docs: add setup and orchestration guides.

What changed:

• Added docs/workflows/set-up-lab-runners.md for runner onboarding, preferred selection, env vs secret env, lab-offload readiness, binary refresh, and proof-capable execution.
• Added docs/workflows/set-up-extensions.md for extension installation, component wiring, runner parity, and core/extension contract boundaries.
• Added docs/concepts/headless-agent-orchestration.md to explain why Homeboy is useful for agents: durable ids, JSON evidence, run artifacts, controller state, and comparable parallel work.
• Added docs/workflows/manage-local-environments.md for rigs, stacks, and task worktrees.
• Added docs/workflows/deploy-and-operate-fleets.md for project status, deploy preview/apply, fleet checks, and operator evidence.
• Linked the new material from README, start-here, concepts, docs index, and workflows index.

Verification rerun:

• Markdown link check: missing=0 checked=137
• cargo run --quiet -- docs list includes the new topics
• cargo test --test architecture_core_agnostic_test architecture_docs_source_paths_exist
• git diff --check

Note: Rust commands still emit existing warnings unrelated to this docs work.