docs(factory): issue labels and cross-repository dispatch (#31)

[kjgbot]

Closes #31.

What this adds

A new, navigable and searchable Factory docs page — Issue labels and repository routing (web/content/docs/factory/issue-routing.mdx) — plus cross-links from the Introduction, Configuration, and Safety scope pages, a nav entry, and a nav/search regression test.

The page covers, for Factory v0.1.34:

• Readiness vs. routing vs. execution shape — safety.requireLabel opts an issue in and is not a repository route; repos.byLabel selects repositories; execution-shape labels choose how routes become agents.
• Execution-shape labels (case-insensitive): agent:single, agent:team, agent:workflow, with the exact agent fan-out for each.
• Inferred team scope — two or more mapped repository labels imply team when no explicit shape label is present.
• Routes come from configuration, not prose — issue-body links and repo mentions do not add routes.
• Cloud + Factory factory.config.json example using cloneRoot, plus a clonePaths variant, and the collision-safe factory-repo routing label.
• Daemon working directory vs. per-agent checkout distinction.
• triage.maxImplementers (1–6, default 2) and the effective team route cap min(triage.maxImplementers, 4), including the refusal-on-overflow behavior.
• Copyable launch examples — factory dispatch <number|mounted-path> --dry-run, factory dispatch <number|mounted-path>, factory start --mode live — and the note that factory dispatch does not accept an issue URL.
• Canonical source links pinned to the v0.1.34 tag.

Reviewer verification (ar-31-review-agentrelay-com)

Independent of the implementer's checks, I verified:

• Tests: vitest run → 22 passed (incl. the new web/lib/test/product-docs.test.ts).
• Types: tsc --noEmit → clean.
• Build: next build --webpack → exit 0, 386 pages generated; /docs/factory/issue-routing and its /markdown mirror render.
• Navigation/search: the page is registered in factorySection nav and is picked up by getProductSearchIndex (headings + body), so it is reachable and searchable.
• Behavioral accuracy: all documented claims were checked against the canonical Factory source (src/triage/heuristic.ts, src/config/schema.ts, src/orchestrator/factory.ts, .agentworkforce/features/manifest.yaml) and confirmed — including case-insensitive label matching, the single/team/workflow fan-out, inferred team scope, min(maxImplementers, 4) cap with refusal on overflow, and the dispatch URL limitation. Terminology matches the manifest entries triage-team-scope and triage-shape-labels.
• Links: the v0.1.34 git tag exists and all four referenced source files resolve at that tag.

Docs correctly pin to v0.1.34 — consistent with the existing factorySection.version and sibling factory docs — even though the local factory checkout has since advanced.

Merge policy

Opened for human review and approval. Do not auto-merge — a human should review and merge.

🤖 Generated with Claude Code

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[kjgbot]

Review: APPROVED — ar-31-review-agentrelay-com

Reviewed commit ad49aae against issue #31's required content and acceptance criteria; every item is satisfied. Independent verification: vitest run 22/22 pass, tsc --noEmit clean, next build exit 0 (page + markdown mirror render), nav/search wiring correct, and all documented behaviors confirmed against the canonical Factory v0.1.34 source (heuristic/schema/orchestrator/manifest). The v0.1.34 doc links resolve to a real tag.

No changes requested. Per merge policy this PR is left open for human review and merge — not auto-merged.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e325b2da-dd2d-4db5-94e8-8c8a2bfeec42

📥 Commits

Reviewing files that changed from the base of the PR and between 89a062a and 103e66d.

📒 Files selected for processing (6)

• web/content/docs/factory/configuration.mdx
• web/content/docs/factory/introduction.mdx
• web/content/docs/factory/issue-routing.mdx
• web/content/docs/factory/safety-scope.mdx
• web/lib/product-docs-nav.ts
• web/lib/test/product-docs.test.ts

---

📝 Walkthrough

Walkthrough

Added a Factory issue-label and repository-routing documentation page covering routing semantics, execution shapes, limits, checkout behavior, and dispatch commands. Linked it from related Factory docs, added it to navigation, and tested navigation/search indexing.

Changes

Factory issue routing

Layer / File(s)	Summary
Issue routing behavior documentation web/content/docs/factory/issue-routing.mdx	Documents readiness, repository, and execution-shape labels; multi-repository routing; limits; checkout behavior; dispatch commands; and canonical Factory references.
Documentation links and search coverage web/content/docs/factory/configuration.mdx, web/content/docs/factory/introduction.mdx, web/content/docs/factory/safety-scope.mdx, web/lib/product-docs-nav.ts, web/lib/test/product-docs.test.ts	Adds cross-links, exposes the new page in Factory navigation, and verifies its search-index entry and content.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• AgentWorkforce/agentrelay.com#30: Introduced the Factory documentation navigation and slug-based routing infrastructure used by this page.

Suggested reviewers: khaliqgant

Poem

I’m a rabbit with labels, hopping in line,
Routing each issue to the checkout just fine.
Single or team, workflow too,
Docs now show what Factory can do.
Cross-repo paths and dispatchers take flight—
Thump! The new guide is wired up right.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the new Factory docs about issue labels and cross-repository dispatch.
Description check	✅ Passed	The description matches the docs page, nav, and test additions described in the changeset.
Linked Issues check	✅ Passed	The docs and supporting changes cover the required labels, routing rules, examples, limits, and navigation for #31.
Out of Scope Changes check	✅ Passed	The changes stay within Factory documentation, navigation, and test coverage, with no unrelated additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch factory/31-agentworkforce-agentrelay-com-3735faf2

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Preview deployed!

Environment	URL
Web	https://5eca5008-agentrelay-web.agent-workforce.workers.dev

This is a Cloudflare Workers preview version of this PR's build.

[khaliqgant]

The example shouldn't have "workspaceId": "your-workspace-id", as this is optional and might confuse users who think it is mandatory

[kjgbot]

Addressed — thanks for the catch.

Finding: the factory.config.json example in issue-routing.mdx included "workspaceId": "your-workspace-id" alongside required fields, which reads as mandatory even though it's optional (Factory resolves the active workspace automatically; see workspaceId: z.string().optional() in src/config/schema.ts).

Fix (commit 103e66d): removed workspaceId from the example JSON and added a sentence clarifying it's omitted because it's optional, with guidance to add it only to pin a non-active workspace — consistent with the existing wording in quickstart.mdx.

Validation: vitest run → 22/22 passed, tsc --noEmit → clean, next build --webpack → exit 0 (386 pages incl. /docs/factory/issue-routing). Pushed to the PR head branch; CI (CodeRabbit, Deploy Preview) is green on 103e66d, and the PR is mergeable/clean against main.