Replicas

Replicas Documentation Audit

Replicas' docs cover a broad surface (CLI, API, Slack, GitHub, Automations, Environments, Billing) but suffer from concrete contradictions between pages — lifecycle states, undocumented CLI commands, deprecated API fields, missing Slack-app prerequisites, and a connector-tracking gap — that will silently break both human developers and AI agents trying to reason across the docs.

1. CLI reference is missing at least three documented subcommands (claude-auth, codex-auth, init) (critical)

Location: /quickstart and /features/workspaces/repository-configuration vs /features/cli

Problem: Three commands appear in other docs but are absent from the canonical CLI reference at /features/cli:

• Quickstart Step 2 ("Option A: Bring Your Subscription") instructs users to run replicas claude-auth and replicas codex-auth. The CLI reference's Authentication section documents only replicas login — there is no claude-auth or codex-auth anywhere on the page.
• /features/workspaces/repository-configuration documents replicas init and replicas init --yaml for creating config files. The CLI reference enumerates login, list, create, connect, code, and org switch, but not init.

Consequence: A new user copy-pasting from Quickstart hits commands that either don't exist or are undocumented. AI coding agents indexing /features/cli as the source of truth will tell users these commands are invalid; agents indexing Quickstart or repository-configuration will produce flows that the CLI reference doesn't corroborate. The headline "Bring Your Subscription" onboarding path is broken on its second command, and this isn't an isolated oversight — at least three commands documented elsewhere are missing from the canonical reference, suggesting a systemic gap.

The fix: Add claude-auth, codex-auth, and init (with --yaml) to /features/cli under appropriate sections (e.g., a new "Agent Authentication" section and an extension of "Replica Management"), with full flag/behavior documentation. Audit the rest of the docs for any other CLI invocations that don't appear in the reference.

2. Workspace lifecycle states and auto-delete behavior contradict between Overview and API reference (critical)

Location: /features/workspaces/overview vs /features/api

Problem: Two contradictions on the same primitive:

1. Status enum mismatch. /features/workspaces/overview defines three states: Booting, Active, Sleeping. /features/api defines: preparing, active, sleeping. "Booting" vs "preparing" is a different identifier — an API client filtering on status == "booting" will never match.

2. Auto-delete contradiction. Overview states: "Auto-delete: Automatic sandbox deletion is currently disabled." But /features/api documents two lifecycle_policy values that explicitly delete workspaces: delete_when_done ("workspace is deleted when the agent finishes") and delete_after_inactivity ("workspace is deleted after a period of inactivity").

Consequence: Developers reading Overview will believe their workspaces persist indefinitely and won't set up cleanup jobs — then discover via API that workspaces they created with delete_when_done are gone. Agents pattern-matching status strings between the two docs will produce code that silently fails. This is the worst kind of doc bug: each page is internally consistent, so neither sets off alarms in isolation.

The fix: Pick one canonical status enum (the API's preparing|active|sleeping is more accurate to the system) and update Overview. Rewrite the Auto-delete line to: "Auto-delete: disabled by default, but workspaces created via API with lifecycle_policy: delete_when_done or delete_after_inactivity will be deleted per that policy. See API lifecycle policies."

3. Slack setup page omits the message.channels subscription that Automations declares mandatory (significant)

Location: /features/slack vs /features/automations

Problem: /features/automations carries an explicit prerequisite: "Slack triggers require your organization to have Slack connected in Organization Settings. The Slack app must be subscribed to message.channels events in the app configuration." The canonical Slack setup page at /features/slack walks through connecting Slack ("Go to Integrations settings → Click Connect Slack and authorize for your workspace → Invite @Replicas to the channels") but never mentions message.channels or any event-subscription configuration.

Consequence: A user setting up Slack from /features/slack will follow the documented steps end-to-end and end up with a Slack app that lacks the message.channels subscription. Mentions in channels may work via other event paths, but Slack-trigger automations will fail silently with no diagnostic, because the prerequisite is documented on a different page that Slack-only users have no reason to read. AI agents asked to write "how do I wire Slack to Replicas" from the Slack page will produce incomplete instructions.

The fix: Add the message.channels requirement to /features/slack's Setup section as a prerequisite step, with a link to the Automations page for context on why. Better still, surface it before "Connect Slack" so the OAuth scopes / app config can be fixed up front rather than after a failure.

4. /admin/credentials doesn't document the connectors the Audit Log claims are tracked (significant)

Location: /admin/credentials vs /admin/audit-log

Problem: The Audit Log's "What's tracked" table lists, under Connectors: "GitHub, Sentry, Linear, Slack, Doppler, Infisical, Anthropic, OpenAI, Claude, Codex, Bedrock" — all linked to /admin/credentials as the configuration page. But /admin/credentials only documents Coding Agents (Claude Code via OAuth/Anthropic key/Bedrock; Codex via OpenAI OAuth). There is no enumeration of Doppler, Infisical, standalone Anthropic, or standalone OpenAI credential paths on the credentials page itself.

Consequence: A user told (by Audit Log, by Billing, or by another doc) that Doppler/Infisical/Anthropic/OpenAI credentials live under /admin/credentials arrives at the page and finds no instructions for those connectors. They have to guess whether the connector exists, look elsewhere, or contact support. AI agents reading the Audit Log to understand what credential surfaces exist will hallucinate setup instructions because the canonical reference doesn't describe them.

The fix: Expand /admin/credentials with sections for each connector category the Audit Log lists — at minimum Doppler, Infisical, and a clear distinction between the Anthropic/OpenAI/Claude/Codex/Bedrock authentication options. If some of these are configured on a different page (e.g., a Secrets or Integrations page), make /admin/credentials cross-link to it explicitly.

5. Plan availability for Automations and the public API contradict each other (significant)

Location: /features/automations, /features/api, /admin/billing

Problem: Three pages disagree on what Hobby-tier orgs can actually do programmatically:

• /admin/billing says: "the public API is Developer and above."
• /features/api says: "API keys are available on the Developer plan and above."
• /features/automations says: "Automations are available on every plan." and shows Hobby with a cap of 2 automations.
• The same Automations page also says: "Automations and the public API are the only sanctioned channels for programmatic use of Replicas. Driving the dashboard, Slack, Linear, GitHub, or CLI from scripts is prohibited."

Consequence: A Hobby user is in a no-win position for any programmatic workflow. The public API is gated to Developer+, so they cannot manage automations programmatically. Driving the dashboard, Slack, Linear, GitHub, or CLI from scripts is prohibited under ToS. The only programmatic surface left to them is firing a custom-webhook URL one-way. "Available on every plan" is technically true but means a Hobby user has literally no sanctioned programmatic path beyond a one-shot webhook fire — yet none of the three pages spells this out. AI agents recommending Replicas to a Hobby-tier user will produce integration plans that violate ToS or assume API access that doesn't exist.

The fix: Add a row or footnote to the Automations "Plan availability" table noting that on Hobby, Automations can only be configured/managed via the dashboard and only the custom-webhook trigger provides a (one-way) programmatic surface. On the Hobby plan row in /admin/billing, explicitly mark "Public API: ✗". Surface the ToS-prohibited-scripting note on the billing page so the gap is impossible to miss.

6. Deprecated API fields rendered as ordinary alternatives in the API reference (significant)

Location: /api-reference/replica/create-replica vs /changelog

Problem: The May 4, 2026 changelog entry states explicitly: "The legacy fields are marked deprecated; please migrate to environment_id when convenient." But on /api-reference/replica/create-replica, repository_set_id and repository_ids are listed in the request-body table as plain Optional fields with no deprecated: true flag, no badge, no warning callout — they appear as peers of environment_id. The OpenAPI description says "Required unless repository_set_id or repository_ids is provided for backwards compatibility" — the phrase "backwards compatibility" is the only signal the field is legacy, and it's buried.

Consequence: Developers and agents reading the reference page in isolation (the normal flow) will pick repository_set_id because it looks like a more direct selector, building new integrations on a deprecated path. When the field is eventually removed, those integrations break.

The fix: Add deprecated: true to both fields in the OpenAPI source so the rendered table shows a deprecation badge. Add a callout at the top of the create-replica page: "repository_set_id and repository_ids are deprecated as of May 4, 2026. Use environment_id. See changelog."

7. The Members/Team/Members-and-roles page has three different labels across the docs (significant)

Location: /admin/team, /quickstart, /admin/audit-log

Problem: The same dashboard area is referred to by three different names across docs:

• /admin/team titles itself "Team" and uses the link text "Team settings".
• /quickstart calls it "Members settings".
• /admin/audit-log calls it "Members and roles" with a link to /admin/team.

Consequence: Search (Ctrl-F, in-product help, agent retrieval) for "Members settings" misses the canonical page. Users following Quickstart click "Members settings" and land on a page titled "Team", which looks like a wrong link. Agents trying to cross-reference "who is invited to this org" against the audit-log entry under "Members and roles" can't reliably stitch the two together. This is exactly the kind of inconsistency that breaks programmatic doc indexing and llms.txt-style retrieval.

The fix: Pick one label — "Team" (matching the page title and the URL /admin/team) — and use it everywhere. Update Quickstart to say "Team settings" and the Audit Log table to say "Team" rather than "Members and roles".

8. Repository-cap math reads as a contradiction (minor)

Location: /admin/billing

Problem: The Repository cap section states: "Repository cap is enforced inclusive of repository set membership; a repo in two repository sets consumes three slots toward the cap." One repo in two sets totaling three slots is non-obvious arithmetic — readers can't tell if it's a typo (1 repo + 2 sets = 3? or 1 + 1 + 1?) and the docs provide no example.

Consequence: A Developer-tier user with a 10-repo cap can't accurately predict whether their planned configuration fits. They either over-provision (upgrade unnecessarily) or under-provision and hit a cap mid-rollout. AI agents asked "will this fit on Developer" will give wrong answers because the formula is not stated.

The fix: Replicas should publish the canonical formula and a worked example next to this sentence — the docs as written do not contain enough information for a reader (or auditor) to derive the rule with confidence, so any worked example here would be an inferred guess rather than a documented contract. Replace the prose with an explicit formula and at least one worked example written by someone who knows how the cap is actually enforced.

What they do well

• The Automations page documents the custom-webhook trigger thoroughly, including the explicit security guidance ("the URL itself is the secret") and clear 202 Accepted semantics.
• Plan-tier limits are presented in a single comparison table on /features/automations rather than scattered.
• The changelog is dated and specific (e.g., the May 4, 2026 backwards-compatibility note explicitly names the affected fields).

Top 3 recommendations

1. Reconcile lifecycle vocabulary across /features/workspaces/overview and /features/api — pick one status enum, and rewrite the auto-delete line to acknowledge API-driven deletion policies.
2. Bring the CLI reference into agreement with the rest of the docs — add claude-auth, codex-auth, and init to /features/cli, and audit for any other commands referenced elsewhere but undocumented there.
3. Close the cross-page reference gaps — add the message.channels Slack-app prerequisite to /features/slack, expand /admin/credentials to enumerate the Doppler/Infisical/Anthropic/OpenAI connectors that the Audit Log claims are tracked there, and mark repository_set_id / repository_ids deprecated in the API reference.