docs: describe role-based placement instead of a fixed VM count (#15194)

[mrveiss]

Refs #15194

Single-issue rationale: this is the documentation half of #15194. The ADR, the architecture documents, the code comments and the placement tests are in a sibling PR on issue-15194-adr-architecture. The guard against reintroduction lands after both, because on base it would fail against whichever half hasn't merged yet.

Thinking Path

AutoBot has no fixed VM count. It runs in Docker, on one VM, or with its roles scaled out across as many machines as the operator chooses (owner-confirmed on #15194). Across docs/, the agent definitions and the infrastructure docs, a six-VM topology was stated as the architecture. In security documents that turns a machine count into an assumed blast radius ("bypass across 6 VMs", "deploy keys to all 6 VMs"), so they're swept first.

What Changed

• Security (first commit): six docs/security/ documents and the access-control rollout runbook now state blast radius by role, not by a machine count.
• Everything else (second commit):
  • docs/ areas: operations, planning, developer, guides, monitoring, api, troubleshooting, user-guide, glossary, roadmap and system-state.
  • .claude/agents/, two chat prompt resources, and docs under autobot-infrastructure/shared/ and autobot-slm-backend/.
• Wherever "VM1" to "VM6" served as role names, they're now the role names.
• Dated records of one install (the October 2025 security rollout plans and status reports, completion reports, one changelog entry) keep their counts, labelled as that install's layout rather than rewritten.
• Internal addresses: real fleet IPs found along the way are redacted to the existing <role-ip> placeholder.
• Untouched on purpose: docs/adr/, docs/architecture/, docs/archives/, and links into them. That's the sibling PR's scope, or history.

Verification

• The pre-commit doc checks (cross-links, docs location) passed at commit.
• No code or behaviour changed. The one hook edit is detect-secrets moving an existing baseline entry's line number.
• Places where a count lives in code, so a doc rewrite would have created a doc/code mismatch, are left for a follow-up issue:
  • verify-ssh-security.sh checks for at least 6 known hosts.
  • The npu-worker-vm2 identifier in npu_workers.yaml.
  • The vm1-frontend to vm5-browser names in the logging scripts.

Model Used

Claude Opus 5 (coordinator) with a Claude Sonnet 5 subagent for the sweep.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 598988e4-7638-44a7-b1e2-473d63646330

---

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]

Notice: 29 open PRs — past the runaway threshold (25)

There is no PR queue limit, and this is not a request to defer this PR. Work proceeds one issue at a time without a cap on open PRs; review capacity is the constraint.

This notice only means the count is high enough to be worth a glance for a runaway — something opening PRs in a loop, or a merge pipeline that has stalled so nothing is draining.

Currently open:

• fix(mcp): rename autobot-backend/mcp/ off the name it shadows (#16449) #16454 fix(mcp): rename autobot-backend/mcp/ off the name it shadows (chore(mcp): autobot-backend/mcp/ shadows the real mcp PyPI SDK, making it unreachable by name #16449)
• feat(secrets): wire in SecretAuditLog, consolidate SecretVault into SecretsManager (#16429) #16453 feat(secrets): wire in SecretAuditLog, consolidate SecretVault into SecretsManager (frontend(secrets): SecretVault, ShareSecretDialog and SecretAuditLog components are unwired #16429)
• docs(adr): supersede ADR-001's fixed VM count with role-separation placement (#15194) #16452 docs(adr): supersede ADR-001's fixed VM count with role-separation placement (docs: a fixed 6-VM topology is documented as the architecture — AutoBot scales from one VM or Docker to whatever is needed, and ADR-001 enshrines the wrong invariant #15194)
• fix(tooling): scope protect-files.sh's secrets/ rule to real credential storage (#16446) #16448 fix(tooling): scope protect-files.sh's secrets/ rule to real credential storage (fix(tooling): protect-files.sh's secrets/ rule blocks legitimate frontend source, zero real targets #16446)
• feat(secrets): bridge connector credential templates to ConnectorCredentialStore (#16428) #16444 feat(secrets): bridge connector credential templates to ConnectorCredentialStore (secrets: connector credential templates must write where knowledge connectors read #16428)
• security(secrets): admin-gate infrastructure hosts, fix vault-backed template names (#16426, #16427) #16442 security(secrets): admin-gate infrastructure hosts, fix vault-backed template names (security(secrets): any logged-in user can list and delete infrastructure hosts through /api/infrastructure/hosts #16426, bug(secrets): the OpenAI and Anthropic quick-add templates save names the vault mirror never recognizes, so the key never reaches the runtime #16427)
• refactor(slm): derive the role list's names, units, health and ports from the role manifests (#16025) #16441 refactor(slm): derive the role list's names, units, health and ports from the role manifests (SLM role shape has two sources of truth: role_registry.DEFAULT_ROLES vs autobot-infrastructure/*/manifest.yml #16025)
• fix(infra): map detect-environment.sh onto files that exist, and drop CONFIGURATION_GUIDE.md's dead env vars (#15143, #15151) #16440 fix(infra): map detect-environment.sh onto files that exist, and drop CONFIGURATION_GUIDE.md's dead env vars (bug(scripts): detect-environment.sh selects three .env files that do not exist #15143, bug(config): AUTOBOT_PLAYWRIGHT_HOST and AUTOBOT_PLAYWRIGHT_API_PORT are documented but read by nothing #15151)
• chore(ci): merge train 2026-09-12-b, stacked test vehicle, do not merge (#15937) #16438 chore(ci): merge train 2026-09-12-b, stacked test vehicle, do not merge (Enable the merge queue — no PR merges against a stale base #15937)
• fix(frontend): point artifact-cells/CodeCell.vue at the shared --codecell-syntax-* tokens (#14853) #16437 fix(frontend): point artifact-cells/CodeCell.vue at the shared --codecell-syntax-* tokens (style(frontend): the two CodeCells now tokenise their syntax palette differently #14853)
• fix(knowledge): wire real grounding:stats counters, replacing the hardcoded claim_sources split (#14981) #16434 fix(knowledge): wire real grounding:stats counters, replacing the hardcoded claim_sources split (bug(knowledge): kb-stats reports a hardcoded claim_sources split — 65/22/13 on an empty KB with zero claims extracted #14981)
• security(auth): fail closed when the password-epoch check cannot reach Redis (#16411) #16433 security(auth): fail closed when the password-epoch check cannot reach Redis (security(backend-auth): password-epoch revocation check fails open when Redis errors (backend equivalent of #16387) #16411)
• chore(slm-frontend): retire getApiUrl(), route its display-only callers through getSlmApiBase() (#15761) #16432 chore(slm-frontend): retire getApiUrl(), route its display-only callers through getSlmApiBase() (tech-debt(slm-frontend): getApiUrl() survived the #13140 migration and still diverges from getSlmApiBase() in DEV #15761)
• chore(frontend): retire useApi.ts, the deprecated useApiWithState composable family (#15025) #16424 chore(frontend): retire useApi.ts, the deprecated useApiWithState composable family (tech-debt(frontend): useApi.ts still exports the deprecated useApiWithState with zero importers — the #7600 migration stopped short of the shim #15025)
• chore(ci): merge train 2026-09-12-a2, test vehicle, do not merge (#15937) #16423 chore(ci): merge train 2026-09-12-a2, test vehicle, do not merge (Enable the merge queue — no PR merges against a stale base #15937)
• test(voice): judge first audio by chunks released, not a wall-clock race (#16407) #16420 test(voice): judge first audio by chunks released, not a wall-clock race (test(voice): voice_latency_test's streaming-vs-blocking TTFB race looks flaky under CI load (found triaging #16367) #16407)
• fix(security): require sign-in on seven ungated routers, and admin where they change shared state or reach outside (#16375) #16418 fix(security): require sign-in on seven ungated routers, and admin where they change shared state or reach outside (security(api): 44 config-registered routers declare no auth gate, triaged by exposure (found by widening the router-auth guard, #16368) #16375)
• feat(preflight): run every reproducible required check through the workflow's own command (#15933) #16416 feat(preflight): run every reproducible required check through the workflow's own command (Local preflight must cover the 10 required checks #15933)
• fix(guards): fold shell continuations in the hooksPath guard via one shared helper (#15961) #16414 fix(guards): fold shell continuations in the hooksPath guard via one shared helper (core.hooksPath override silently disables every hook in a worktree #15961)
• fix(security): deny an SLM token when its revocation check cannot run, HS256 and RS256 (#16387, #16412) #16413 fix(security): deny an SLM token when its revocation check cannot run, HS256 and RS256 (security(slm-auth): token revocation checks fail open when Redis errors, so a revoked token is accepted #16387, security(slm-auth): RS256 authority-token revocation check fails open when Redis errors #16412)
• fix(security): generate the vault root key from 32 random bytes, not alphanumeric characters (#16405) #16410 fix(security): generate the vault root key from 32 random bytes, not alphanumeric characters (security(secrets): the vault root key is base64 of 32 alphanumeric chars (~190 bits), not 32 random bytes #16405)
• chore(docker): retire the four agent Dockerfiles whose modules no longer exist; agents run in-process (#16361) #16409 chore(docker): retire the four agent Dockerfiles whose modules no longer exist; agents run in-process (chore(docker): four agent Dockerfiles under autobot-infrastructure/autobot-backend/docker/ are built by nothing: wire in or retire #16361)
• chore(deps): carry dependabot's npm security bumps onto Dev_new_gui (hono 4.13.7 and transitive; supersedes #16171) #16408 chore(deps): carry dependabot's npm security bumps onto Dev_new_gui (hono 4.13.7 and transitive; supersedes chore(deps): bump the npm_and_yarn group across 6 directories with 7 updates #16171)
• fix(tests): stop gating a disk-bound model load on a CPU work budget, and prove it stays offline and import-free (#15055, #15235) #16404 fix(tests): stop gating a disk-bound model load on a CPU work budget, and prove it stays offline and import-free (test(perf): startup benchmarks assert absolute wall-clock budgets and fail on runner load — passed and failed on the same code minutes apart #15055, test(perf): three calibrated budgets are drifting or disk-bound — the startup margin is 1.4x, not the 1.9x its note records #15235)
• fix(ci): keep the drift-checked SLM agent mirror out of the duplication scan (#16401) #16402 fix(ci): keep the drift-checked SLM agent mirror out of the duplication scan (ci(duplication-guard): the SLM scope counts the drift-checked agent mirror, so every agent change fails the absolute pin #16401)
• fix(ci): bring CI's pytest environment up to its declared floors, and gate on them (#16264) #16391 fix(ci): bring CI's pytest environment up to its declared floors, and gate on them (ci: the pytest environment sits below two declared floors, and the floor banner tells CI readers the opposite #16264)
• fix(security): the dev proxy stops granting admin without a login, and the session check endpoint is tested (#16382, #16385) #16390 fix(security): the dev proxy stops granting admin without a login, and the session check endpoint is tested (SLM Vite dev-server proxy injects X-Internal-API-Key on /autobot-api with no session check #16382, SLM backend: add direct test coverage for GET /api/auth/me #16385)
• fix(security): the SLM proxy checks the caller's SLM session before it adds the backend key (#16374) #16386 fix(security): the SLM proxy checks the caller's SLM session before it adds the backend key (security(slm): the SLM nginx /autobot-api/ proxy adds the internal API key for every caller, so anyone reaching the SLM host is a backend admin #16374)
• fix(ci): retire the CodeQL suite file nothing loads, and record the real guard behind alert #1030 (#16283, #16302) #16377 fix(ci): retire the CodeQL suite file nothing loads, and record the real guard behind alert feat: Voice conversation mode — Hands-free with VAD (Tier 2) #1030 (ci(security): codeql.yml is disabled, so the reviewed codeql-config.yml exclusions apply to nothing #16283, ci(security): codeql-config.yml's file-scoped query-filters exclude nothing, under either setup #16302)

If the queue is draining normally, ignore this. Otherwise:

1. Check whether CI is dispatching at all — see the ci-dispatch-watchdog status on these PRs
2. Merge the ones whose CI has finished and review has passed: gh pr merge <number> --squash --delete-branch
3. Look for a loop opening near-identical PRs

Warn-only runaway detector — .github/workflows/pr-queue-gate.yml. It never blocks a merge.

[mrveiss]

Review at cfa9c2593: APPROVE.

Verified the branch's real diff against its true merge-base with main (0abe0d47a, one commit behind current main tip — the branch is genuinely fresh, not stale). gh pr diff --name-only matches git diff --name-only against that merge-base: 68 files, 887+/802-.

Sampled ~250 of the ~1060 changed content lines across the largest files (SECURITY_FRAMEWORK.md, IMPLEMENTATION_COMPLETE.md, the production-validation reports, the SSH-hardening README, the deployment/redis/NPU docs): every hunk I checked is on-topic for #15194 — either (a) role-based language replacing a fixed "6-VM"/"5-VM" architecture claim, or (b) a hardcoded internal IP (172.16.168.2x) replaced with a role placeholder (<frontend-ip>, <database-ip>, etc.). No off-topic content found in the sample.

Historical/dated reports (ANA_backend-critical-issues-architectural-2025-10-05.md, ARCHITECTURE_COMPLIANCE_IMPLEMENTATION_REPORT.md, IMPLEMENTATION_COMPLETE.md) get a short disclaimer note added at the top rather than an exhaustive rewrite of body prose — a few "6 VM" mentions remain in body text below the disclaimer in a couple of files (IMPLEMENTATION_COMPLETE.md lines 33/251, the 20250911 production-validation reports, BACKEND_ROOT_CAUSE_IMPLEMENTATION_PLAN.md). Consistent with the disclaimer-not-rewrite pattern already used elsewhere in this same PR for historical documents — not a defect, just noting it's a deliberate scope boundary rather than an exhaustive sweep.

No blocking issues.