amadan

carlos / platform Public

plan: approved copy record for nearest-region (copy review, Paul 2026-10-03)

121 strings, approved unchanged in the copy review, then two rulings Paul
made on 2026-10-03 that override the approved text:

- C25: `carlos canary remove` becomes `carlos canary rm`. Nothing else in
  the string changes.
- C24: the text is exactly `IP Geolocation by DB-IP`, DB-IP's required
  attribution wording. The entry carries a `link` of https://db-ip.com
  and a `note`, because the console page must render it as a link.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
claude 6afa7dbf2e672c122fe18cc8cb75bcec2289ecbb parent e2b5d8f
1 file changed, +613 −0
  • docs/superpowers/plans/2026-10-02-nearest-region-copy.json +613 −0
diff --git a/docs/superpowers/plans/2026-10-02-nearest-region-copy.json b/docs/superpowers/plans/2026-10-02-nearest-region-copy.json
new file mode 100644
index 000000000..19c76ea5e
--- /dev/null
+++ b/docs/superpowers/plans/2026-10-02-nearest-region-copy.json
@@ -0,0 +1,613 @@
+{
+ "approved_by": "Paul",
+ "approved_on": "2026-10-03",
+ "entries": [
+ {
+ "id": "C1",
+ "file": "internal/console/regioncopy.go",
+ "text": "Region"
+ },
+ {
+ "id": "C2",
+ "file": "internal/console/regioncopy.go",
+ "text": "Where this app's instances run. We picked the region nearest to you. Choose another if most of your users are somewhere else."
+ },
+ {
+ "id": "C3",
+ "file": "internal/console/regioncopy.go",
+ "text": "%s (nearest to you)"
+ },
+ {
+ "id": "C5",
+ "file": "internal/console/regioncopy.go",
+ "text": "That region can't take new apps right now. Choose another."
+ },
+ {
+ "id": "C7",
+ "file": "internal/console/regioncopy.go",
+ "text": "New instances start in %s, this app's region."
+ },
+ {
+ "id": "C8",
+ "file": "internal/console/regioncopy.go",
+ "text": "New instances can't start in %s, this app's region, right now. Pass a region to place one elsewhere."
+ },
+ {
+ "id": "C21",
+ "file": "internal/console/regioncopy.go",
+ "text": "created app %s in %s"
+ },
+ {
+ "id": "C24",
+ "file": "internal/console/regioncopy.go",
+ "text": "IP Geolocation by DB-IP",
+ "link": "https://db-ip.com",
+ "note": "Paul's 2026-10-03 ruling: the text is DB-IP's required attribution wording, and the console page must render it as a link to the url in link."
+ },
+ {
+ "id": "R-absent",
+ "file": "internal/console/regionmsgs.go",
+ "text": "no box runs there now"
+ },
+ {
+ "id": "R-not-hosting",
+ "file": "internal/console/regionmsgs.go",
+ "text": "boxes there can't start instances"
+ },
+ {
+ "id": "R-no-secrets-key",
+ "file": "internal/console/regionmsgs.go",
+ "text": "boxes there can't open this deployment's secrets"
+ },
+ {
+ "id": "R-not-eligible",
+ "file": "internal/console/regionmsgs.go",
+ "text": "boxes there don't take ordinary instances"
+ },
+ {
+ "id": "C16",
+ "file": "internal/console/regionmsgs.go",
+ "text": "this app's region %s can't take new instances right now (%s). Pass a region to place this instance elsewhere. Regions that can: %s."
+ },
+ {
+ "id": "C17",
+ "file": "internal/console/regionmsgs.go",
+ "text": "this app's region %s is not one its instances may use. Allowed: %s. Pass a region to choose one."
+ },
+ {
+ "id": "C18",
+ "file": "internal/console/regionmsgs.go",
+ "text": "region %s is not one this platform runs in. Choose from: %s."
+ },
+ {
+ "id": "C19",
+ "file": "internal/console/regionmsgs.go",
+ "text": "region %s can't take new apps right now. Choose from: %s."
+ },
+ {
+ "id": "C16b",
+ "file": "internal/console/regionmsgs.go",
+ "text": "this app's region %s can't take new instances right now (%s), and no other region this app may use can either. Try again later."
+ },
+ {
+ "id": "C17b",
+ "file": "internal/console/regionmsgs.go",
+ "text": "this app's region %s is not one its instances may use, and no region they may use can take new instances right now. Try again later."
+ },
+ {
+ "id": "C18b",
+ "file": "internal/console/regionmsgs.go",
+ "text": "region %s is not one this platform runs in. Run the command without --region."
+ },
+ {
+ "id": "C19b",
+ "file": "internal/console/regionmsgs.go",
+ "text": "region %s can't take new apps right now. Run the command without --region."
+ },
+ {
+ "id": "C20",
+ "file": "internal/console/regionmsgs.go",
+ "text": "could not read this app's region. Try again."
+ },
+ {
+ "id": "C26",
+ "file": "internal/console/regionmsgs.go",
+ "text": "this app's region %s is also one of this instance's replica placements. Pass a region for the instance, or drop %s from replicas."
+ },
+ {
+ "id": "C27",
+ "file": "internal/console/regionmsgs.go",
+ "text": "could not read this app's instance policy, so there is no region suggestion. Try again."
+ },
+ {
+ "id": "C28",
+ "file": "internal/console/regionmsgs.go",
+ "text": "could not confirm that this app's region %s can take new instances. Try again, or pass a region."
+ },
+ {
+ "id": "C29",
+ "file": "internal/console/regionmsgs.go",
+ "text": "possible placement discrepancy: %s of %s has no region, but %s's region is %s. It may be a deliberate home override; review it."
+ },
+ {
+ "id": "C31",
+ "file": "internal/console/regionmsgs.go",
+ "text": "region %s can't run instances right now: its boxes don't hold this deployment's secrets key, so an instance there would start without its config or secrets. Choose another region."
+ },
+ {
+ "id": "O1",
+ "file": "internal/console/regionconfig.go",
+ "text": "console: CONSOLE_APP_REGIONS=on but CONSOLE_HOME_REGION is unset, so app regions stay off until the home is named"
+ },
+ {
+ "id": "O2",
+ "file": "internal/console/regionconfig.go",
+ "text": "console: CARLOS_SECRETS_PUBKEY is unset, so no region outside the home can be chosen automatically"
+ },
+ {
+ "id": "O3",
+ "file": "cmd/console/main.go",
+ "text": "console: CONSOLE_GEOIP_DB %s is unusable, so the IP step of region guesses is off: %v"
+ },
+ {
+ "id": "O4",
+ "file": "cmd/console/main.go",
+ "text": "console: GeoIP database loaded from %s"
+ },
+ {
+ "id": "O5",
+ "file": "internal/geo/mmdb.go",
+ "text": "geo: a GeoIP lookup failed and was treated as a miss"
+ },
+ {
+ "id": "O6",
+ "file": "internal/console/regioncandidates.go",
+ "text": "console: boxes for region %q disagree on their AWS region %v; using %s"
+ },
+ {
+ "id": "O7",
+ "file": "internal/console/regioncandidates.go",
+ "text": "console: region %q has no point in the shipped AWS region table (AWS region %q), so region guesses leave it out"
+ },
+ {
+ "id": "O8",
+ "file": "internal/console/server.go",
+ "text": "console: app region %s/%s: %s (%s)"
+ },
+ {
+ "id": "O9",
+ "file": "internal/console/regiondrift.go",
+ "text": "console: placement discrepancy check %s/%s: only the first %d records were checked"
+ },
+ {
+ "id": "O10",
+ "file": "internal/host/edgesfile.go",
+ "text": "agent: CARLOS_SECRETS_KEY does not parse, so no secrets_key_fp is published: %v"
+ },
+ {
+ "id": "O11",
+ "file": "internal/console/apiinstances.go",
+ "text": "console: api instances create %s/%s: read app region: %v"
+ },
+ {
+ "id": "O12",
+ "file": "internal/console/apiinstances.go",
+ "text": "console: api instances create %s/%s: read edges: %v"
+ },
+ {
+ "id": "O13",
+ "file": "internal/console/regioncandidates.go",
+ "text": "console: region policy %s/%s: read manifest: %v"
+ },
+ {
+ "id": "O14",
+ "file": "internal/console/regioncandidates.go",
+ "text": "console: region policy %s/%s: open registry: %v"
+ },
+ {
+ "id": "O15",
+ "file": "internal/console/regioncandidates.go",
+ "text": "console: region policy %s/%s: placement: %v"
+ },
+ {
+ "id": "O16",
+ "file": "internal/console/apicli.go",
+ "text": "console: claim %s/%s: read back region: %v"
+ },
+ {
+ "id": "O17",
+ "file": "apimode.go",
+ "text": "regions: unreadable response: %w"
+ },
+ {
+ "id": "O18",
+ "file": "internal/console/regiondrift.go",
+ "text": "console: placement discrepancy check %s/%s: %v"
+ },
+ {
+ "id": "O19",
+ "file": "internal/console/regiondrift.go",
+ "text": "console: placement discrepancy check: %v"
+ },
+ {
+ "id": "O20",
+ "file": "apimode.go",
+ "text": "instance: unreadable response: %w"
+ },
+ {
+ "id": "C9",
+ "file": "region_copy.go",
+ "text": "Region: %s (from your timezone). Use --region to choose another."
+ },
+ {
+ "id": "C10",
+ "file": "region_copy.go",
+ "text": "Region: %s (from your network location). Use --region to choose another."
+ },
+ {
+ "id": "C11",
+ "file": "region_copy.go",
+ "text": "Region: %s (the platform default). Use --region to choose another."
+ },
+ {
+ "id": "C12",
+ "file": "region_copy.go",
+ "text": "Region: %s."
+ },
+ {
+ "id": "C13a",
+ "file": "region_copy.go",
+ "text": "This console does not record an app region yet, so --region was not applied."
+ },
+ {
+ "id": "C13b",
+ "file": "region_copy.go",
+ "text": "This console is not assigning app regions yet, so --region was not applied. This app's instances start in %s."
+ },
+ {
+ "id": "C14",
+ "file": "region_copy.go",
+ "text": "channel %s, %s"
+ },
+ {
+ "id": "C15",
+ "file": "region_copy.go",
+ "text": "%s already runs in %s. --region only applies when deploy creates an app. To place one instance elsewhere, use carlos instances create --region."
+ },
+ {
+ "id": "C15b",
+ "file": "region_copy.go",
+ "text": "could not read %s's region (%v), so deploy stopped before shipping anything. Try again, or run without --region."
+ },
+ {
+ "id": "C15c",
+ "file": "region_copy.go",
+ "text": "the console could not read %s's region, so deploy stopped before shipping anything. Try again, or run without --region."
+ },
+ {
+ "id": "C25",
+ "file": "region_copy.go",
+ "text": "canary %s already runs in %s. --region applies only when canary creates the host. Run carlos canary rm first to start it somewhere else."
+ },
+ {
+ "id": "C30",
+ "file": "region_copy.go",
+ "text": "%s runs on your fleet %s, which decides where every instance runs, so --region does not apply. Run the command without --region."
+ },
+ {
+ "id": "C30b",
+ "file": "region_copy.go",
+ "text": "this console can't say where %s's instances run, so --region can't be checked. Update the console, or run the command without --region."
+ },
+ {
+ "id": "C30c",
+ "file": "region_copy.go",
+ "text": "could not confirm where canary %s runs, so nothing was changed. Try again, or run the command without --region."
+ },
+ {
+ "id": "C22a",
+ "file": "region_copy.go",
+ "text": "region this app's instances start in (default: the region nearest you)"
+ },
+ {
+ "id": "C22b",
+ "file": "region_copy.go",
+ "text": "region for the app this deploy creates (default: the region nearest you)"
+ },
+ {
+ "id": "C22c",
+ "file": "region_copy.go",
+ "text": "region for the canary instance (default: the app's region)"
+ },
+ {
+ "id": "C22d",
+ "file": "region_copy.go",
+ "text": "region for this instance (default: the app's region, subject to the manifest's allow-list)"
+ },
+ {
+ "id": "U1",
+ "file": "apps.go",
+ "text": " [--region <code>]"
+ },
+ {
+ "id": "U2",
+ "file": "deploy.go",
+ "text": " [--region <code>]"
+ },
+ {
+ "id": "U3",
+ "file": "canary.go",
+ "text": "[--region <code>]"
+ },
+ {
+ "id": "S1",
+ "file": "scripts/update-tzgeo.sh",
+ "text": "usage: update-tzgeo.sh <tzdata version, e.g. 2026b>"
+ },
+ {
+ "id": "S2",
+ "file": "scripts/update-tzgeo.sh",
+ "text": "gpg not found: signature NOT checked"
+ },
+ {
+ "id": "S3",
+ "file": "scripts/update-tzgeo.sh",
+ "text": "internal/geo/data refreshed to tzdata $v"
+ },
+ {
+ "id": "G1",
+ "file": "scripts/region-service-gate.sh",
+ "text": "usage: region-service-gate.sh <probe-host> <expected-version> [<edge-eip> ...]"
+ },
+ {
+ "id": "G2",
+ "file": "scripts/region-service-gate.sh",
+ "text": "ok $label: $status $version"
+ },
+ {
+ "id": "G3",
+ "file": "scripts/region-service-gate.sh",
+ "text": "FAIL $label: request failed"
+ },
+ {
+ "id": "G4",
+ "file": "scripts/region-service-gate.sh",
+ "text": "FAIL $label: status $status"
+ },
+ {
+ "id": "G5",
+ "file": "scripts/region-service-gate.sh",
+ "text": "FAIL $label: X-Carlos-Version '$version', want '$want'"
+ },
+ {
+ "id": "G6",
+ "file": "scripts/region-service-gate.sh",
+ "text": "FAIL $label: connected to $ip, not $eip"
+ },
+ {
+ "id": "C23-us-east-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "US East · N. Virginia"
+ },
+ {
+ "id": "C23-us-east-2",
+ "file": "internal/geo/awsregions.go",
+ "text": "US East · Ohio"
+ },
+ {
+ "id": "C23-us-west-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "US West · N. California"
+ },
+ {
+ "id": "C23-us-west-2",
+ "file": "internal/geo/awsregions.go",
+ "text": "US West · Oregon"
+ },
+ {
+ "id": "C23-ca-central-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Canada · Montréal"
+ },
+ {
+ "id": "C23-ca-west-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Canada · Calgary"
+ },
+ {
+ "id": "C23-mx-central-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Mexico · Querétaro"
+ },
+ {
+ "id": "C23-sa-east-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Brazil · São Paulo"
+ },
+ {
+ "id": "C23-eu-west-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Ireland · Dublin"
+ },
+ {
+ "id": "C23-eu-west-2",
+ "file": "internal/geo/awsregions.go",
+ "text": "UK · London"
+ },
+ {
+ "id": "C23-eu-west-3",
+ "file": "internal/geo/awsregions.go",
+ "text": "France · Paris"
+ },
+ {
+ "id": "C23-eu-central-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Germany · Frankfurt"
+ },
+ {
+ "id": "C23-eu-central-2",
+ "file": "internal/geo/awsregions.go",
+ "text": "Switzerland · Zurich"
+ },
+ {
+ "id": "C23-eu-south-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Italy · Milan"
+ },
+ {
+ "id": "C23-eu-south-2",
+ "file": "internal/geo/awsregions.go",
+ "text": "Spain · Aragón"
+ },
+ {
+ "id": "C23-eu-north-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Sweden · Stockholm"
+ },
+ {
+ "id": "C23-il-central-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Israel · Tel Aviv"
+ },
+ {
+ "id": "C23-me-south-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Bahrain"
+ },
+ {
+ "id": "C23-me-central-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "UAE"
+ },
+ {
+ "id": "C23-af-south-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "South Africa · Cape Town"
+ },
+ {
+ "id": "C23-ap-south-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "India · Mumbai"
+ },
+ {
+ "id": "C23-ap-south-2",
+ "file": "internal/geo/awsregions.go",
+ "text": "India · Hyderabad"
+ },
+ {
+ "id": "C23-ap-east-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Hong Kong"
+ },
+ {
+ "id": "C23-ap-east-2",
+ "file": "internal/geo/awsregions.go",
+ "text": "Taiwan · Taipei"
+ },
+ {
+ "id": "C23-ap-southeast-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Singapore"
+ },
+ {
+ "id": "C23-ap-southeast-2",
+ "file": "internal/geo/awsregions.go",
+ "text": "Australia · Sydney"
+ },
+ {
+ "id": "C23-ap-southeast-3",
+ "file": "internal/geo/awsregions.go",
+ "text": "Indonesia · Jakarta"
+ },
+ {
+ "id": "C23-ap-southeast-4",
+ "file": "internal/geo/awsregions.go",
+ "text": "Australia · Melbourne"
+ },
+ {
+ "id": "C23-ap-southeast-5",
+ "file": "internal/geo/awsregions.go",
+ "text": "Malaysia"
+ },
+ {
+ "id": "C23-ap-southeast-6",
+ "file": "internal/geo/awsregions.go",
+ "text": "New Zealand · Auckland"
+ },
+ {
+ "id": "C23-ap-southeast-7",
+ "file": "internal/geo/awsregions.go",
+ "text": "Thailand · Bangkok"
+ },
+ {
+ "id": "C23-ap-northeast-1",
+ "file": "internal/geo/awsregions.go",
+ "text": "Japan · Tokyo"
+ },
+ {
+ "id": "C23-ap-northeast-2",
+ "file": "internal/geo/awsregions.go",
+ "text": "South Korea · Seoul"
+ },
+ {
+ "id": "C23-ap-northeast-3",
+ "file": "internal/geo/awsregions.go",
+ "text": "Japan · Osaka"
+ },
+ {
+ "id": "D1",
+ "file": "docs/site/cli.md",
+ "text": "`--region <code>` sets the region the app's instances start in. Without it,\nthe console picks the region nearest you from your timezone, and the command\nprints one line saying which and why:\n\n```\ncarlos apps create --app hello --region uk\n```"
+ },
+ {
+ "id": "D2",
+ "file": "docs/site/cli.md",
+ "text": "When `carlos deploy` creates your first app, it sends your timezone so the\nconsole can pick the region nearest you, and prints the choice. `--region\n<code>` chooses instead. On an app that already exists, `--region` must\nmatch the app's region, or deploy stops before shipping anything."
+ },
+ {
+ "id": "D3",
+ "file": "docs/site/cli.md",
+ "text": "`--region <code>` places a new canary in that region (default: the app's\nregion). It is refused for an existing canary in another region, and for an\napp that runs on one of your fleets."
+ },
+ {
+ "id": "D4",
+ "file": "docs/site/cli.md",
+ "text": "Without `--region`, a new instance starts in the app's region."
+ },
+ {
+ "id": "D5",
+ "file": "README.md",
+ "text": "- `CONSOLE_APP_REGIONS`: `on` lets new apps be given a region other than the\n home. It needs `CONSOLE_HOME_REGION` set too. With the home unnamed, the\n console logs once and leaves app regions off. Default off. Automatic\n placement outside the home also needs `CARLOS_SECRETS_PUBKEY`, so the\n console can check that a box holds the deployment's secrets key.\n- `CONSOLE_GEOIP_DB`: the path to an operator-supplied MaxMind-format `.mmdb`.\n DB-IP Lite is recommended, and it requires the attribution the new-app page\n shows. Unset or unusable turns the IP step of the region guess off, and the\n console starts either way. Replace the file by atomic rename, then restart."
+ },
+ {
+ "id": "D6",
+ "file": "README.md",
+ "text": "**App regions rollback floor.** Once any app holds a region other than the\nhome, do not roll the console binary below the first release that\nunderstands app regions: an older console places a no-region create at the\nhome. That release's version is named here, in its release notes, and in the\nconsole roll recipe in carloku-infrastructure; check all three name the same\nversion before turning `CONSOLE_APP_REGIONS` on. If a rollback below the\nfloor happens anyway, write down when it started and ended: on its next\nstart the console logs \"possible placement discrepancy\" lines, and the\ninterval tells you which to review. Turning the switch off is the feature's\nown rollback: it stops new non-home regions and keeps existing ones in force."
+ },
+ {
+ "id": "D7",
+ "file": "README.md",
+ "text": "**Turning app regions on.** In order:\n\n1. Stage the deployment's `CARLOS_SECRETS_KEY` on every box in every region\n that should take placed instances, and set `CARLOS_SECRETS_PUBKEY` on the\n console. A box without the key runs placed instances with no config, no\n secrets and no store.\n2. Roll the box release that publishes `serves_shared_pool`,\n `accepts_inbound` and `secrets_key_fp`. Check every region's\n `control/edges/*.json` carries them, and that each `secrets_key_fp` equals\n the console's.\n3. Roll the console with the switch off.\n4. On dev, turn the switch on. Create an app and an instance, read their\n region, and run the service gate below for every region.\n5. On production, with the switch still off, create one probe instance per\n eligible region with an explicit `--region`, deploy a known build, and run\n `scripts/region-service-gate.sh <probe-host> <build> <every other edge EIP>`\n for each. Every region must pass. Delete the probes.\n6. Turn the switch on. Re-run step 5 after any period with the switch off,\n and whenever a new region becomes eligible."
+ },
+ {
+ "id": "D8",
+ "file": "README.md",
+ "text": " Keep it geographically consistent with the region's place name in the\n console's region picker (for example \"EU · Ireland\" beside\n \"Ireland · Dublin\"); it may stay coarser."
+ },
+ {
+ "id": "D9",
+ "file": "README.md",
+ "text": "A manifest's `regions` allow-list compares the home as `\"\"`, so listing the\nhome's code does not admit the home."
+ },
+ {
+ "id": "D10",
+ "file": "README.md",
+ "text": "- Refresh the embedded timezone tables when a new IANA tzdata release is out:\n `scripts/update-tzgeo.sh <version>`, then `go test ./internal/geo`."
+ },
+ {
+ "id": "F1",
+ "file": "internal/geo/testdata/README",
+ "text": "The .mmdb files and GeoIP2-Country-Test.json are MaxMind's published test\ndata from github.com/maxmind/MaxMind-DB, dual licensed MIT or Apache-2.0\n(LICENSE-MIT, LICENSE-APACHE beside this file). All were fetched at commit\n276926d23b4109ca5452709bfb5931c338afb34c. They contain test records only, not real geolocation data."
+ }
+ ]
+}