[magnus919]

Summary

Existing deployments can run canonical GroktoCrawl while retaining names such as groktocrawl-x-candidate-candidate-agent-1. The candidate runbook still describes this as a separate X experiment, which makes those names misleading after the architecture's adoption in PR #665 and v1.0.0.

Clarify the retained topology, trace Compose/MCP/portal/HAProxy naming contracts, link canonical image provenance, and distinguish an application update from an operator-led topology migration. Add the same warning to the mainline migration runbook. Compose values remain unchanged.

Related Issue

Requested directly by Magnus after verifying canonical source running under retained X deployment names. Related adoption context: #665. No additional issue created.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that changes existing behavior)
• 📚 Documentation (README, AGENTS.md, CONTRIBUTING.md, or other docs)
• 🔧 Refactor (code change that neither fixes a bug nor adds a feature)
• 🧪 Test (adding or updating tests)
• ⚡ CI/DevOps (CI pipeline, Docker, dependency updates)

Test Plan

• Integration tests pass: not run; documentation-only change, no deployment or runtime configuration changes.
• New tests added for the change: not applicable; existing Compose contract tests cover the unchanged configuration.
• Manual verification done: traced project name and candidate-agent service in compose.experimental-candidate.yml, portal/MCP URLs, compose.capture-https.yml and deploy/capture-https.cfg. Checked canonical adoption/release provenance.
• python3 scripts/check-docs-surface.py passed.
• python3 -m pytest tests/unit/test_mainline_migration_compose.py -o addopts='' -q --noconftest: 6 passed.
• git diff --check passed.

Checklist

• My code follows the project's coding conventions: documentation only.
• I have updated the relevant documentation: both deployment runbooks; README, AGENTS.md and CONTRIBUTING.md public behavior is unchanged.
• I have added tests that prove my fix is effective or my feature works: no new behavior; existing six configuration contract tests and documentation surface check pass.
• New API endpoints have a corresponding CLI subcommand: not applicable, no endpoints.
• If adding a new async endpoint, it accepts a webhook field and fires on completion/failure: not applicable.

Notes for Reviewers

The same naming convention is present in maintained compatibility templates, but the observed production launch uses an explicit -p argument and private generated Compose inputs outside Git. No checked-in generator for those private files was found. Standard docker-compose.yml already has no X naming defaults. Template edits alone cannot rename that live deployment. The identifiers remain connected resource and routing contracts. A cosmetic rename can select different volumes/networks or break MCP/proxy routing; any future rename needs a separately rehearsed data/route migration and rollback plan. Historical experiment ADRs and fixtures remain historical evidence.

This PR changes no project names, service names, networks, volumes, images, ports, runtime routing, dependencies, or live deployment. No production tests or container operations were performed. Draft status avoids invoking the repository's paid AI review job; no manual scan/build/review runs requested.

Prepared by Codex (AI agent on behalf of Magnus Hedemark).

Scope limit: this draft documents naming/provenance and migration prerequisites; it does not complete a runtime naming migration. A follow-up design must choose retained candidate service topology with new names versus migration to the existing standard topology, explicitly preserving data/network/route mappings.