Migrating from grove names

Scion used to call its per-workspace grouping construct a “grove.” That name is being retired in favor of “project” across the CLI, on-disk layout, hub/broker wire protocol, environment variables, container labels, and the hub API. This page is the durable, running list of what changed and how to migrate, organized by area. Each row below is added as the corresponding change merges; a section with no rows yet means nothing in that area has changed yet.

Pods and containers created by scion releases before this rename, and hub/broker pairs on mixed versions, are not supported. If you see stale behavior after upgrading, restart the affected agents and make sure hub and broker are on the same release.

CLI

Removed	Replacement / action
`--project <gcp-id>` on `scion project service-accounts add` and `scion hub secret migrate`	`--gcp-project <gcp-id>`. `--project`/`-g` on these commands now selects the scion project, like everywhere else.
`--grove` (global and on `broker provide/withdraw`, `hub env `, `hub secret `, `hub token create/list`, `notifications *`)	`--project` / `-g`
`scion grove …`	`scion project …` (the `group` alias is unaffected)
`scion hub groves …` / `scion hub grove …`	`scion hub projects …` / `scion hub project …`
`scion config cd-grove`	`scion config cd-project`
`grove:<name>` template-scope prefix and `--template-scope grove`	`project:<name>`; `--template-scope project`
`scion config get/set grove_id`, `hub.grove_id`, `hub.groveId`	`scion config get/set project_id`, `hub.project_id`, `hub.projectId`
`grove_id` field in `scion project list --format json`	`project_id`
`groveId`, `groveName`, `groveType`, `grove`, `groves`, `grovePath` keys in CLI JSON output (including `scion list --format json`)	`projectId`, `name` (`projectName` on broker project entries), `projectType`, `project`, `projects`, `projectPath`

Hub environment variable

Removed	Replacement / action
env `SCION_HUB_GROVE_ID` (now ignored, with a warning)	`SCION_HUB_PROJECT_ID`

On-disk

Removed	Replacement / action
`.scion/grove-id` file	migrated automatically to `.scion/project-id`. If the file is committed, commit the rename.
`grove-id`/`grove-name`/`grove-slug` keys in `.scion` marker files; `hub.grove_id` in `settings.yaml`	migrated automatically to `project-id`/`project-name`/`project-slug` and `hub.project_id`. A project-level `hub.grove_id` now takes precedence over a global `hub.project_id`, as project settings normally do. On value conflicts the project-named key wins, and a `.grove-migration.bak` backup is written.
`~/.scion/groves/`, `~/.scion/grove-configs/`	moved automatically to `~/.scion/projects/` and `~/.scion/project-configs/`, with symlinks left at the old paths. If both exist, scion warns and uses the project-named directory. Directories on another filesystem or owned by another user must be moved by hand (scion prints the command).

Wire / env / labels

Removed	Replacement / action
listing agents whose pods/containers carry only `scion.grove*` labels (created before the rename)	restart those agents
env `SCION_GROVE_ID`, `SCION_GROVE`, `SCION_GROVE_PATH` inside agent containers (now ignored, with a warning)	`SCION_PROJECT_ID`, `SCION_PROJECT`, `SCION_PROJECT_PATH`. Restart running agents. Update harness scripts that read the old names.
container/pod labels `scion.grove`, `scion.grove_id`; annotation `scion.grove_path`	`scion.project`, `scion.project_id`, `scion.project_path`. Update external tooling that filters on the old labels. Restart any agent created before the grove→project rename before upgrading. Its container carries only `scion.grove*` labels and is otherwise treated as unlabelled, so a same-named agent lookup in any project can match it.
grove-named fields and the `groveId` query parameter on the hub-to-broker HTTP API (agent create/start/message/response, broker info, workspace upload) and the `/api/v1/workspace/grove-upload` broker route	the project-named equivalents (`projectId`, `projectPath`, `projectSlug`, `projects`, `projectName`) and `/api/v1/workspace/project-upload`; upgrade hub and brokers together, mixed versions are unsupported
`groves`/`groveId` fields in the hub↔broker heartbeat payload and the runtime-broker websocket control protocol (`ConnectMessage`, `StreamOpenMessage`)	`projects`/`projectId`. Upgrade hub and brokers together; mixed versions are unsupported.

Hub API

Removed	Replacement / action
broker error code `global_grove_disabled`	`global_project_disabled`
REST routes `/api/v1/groves[/…]`	`/api/v1/projects[/…]`
request fields `groveId`, `grove_id` on project register	`id`
request field / query param `groveId` on templates and notifications	`projectId`
hub accepted and stored unrecognized `scope` values on template create/clone, notification subscription-template create, and harness-config create/clone (e.g. the removed `grove` scope, or any other unrecognized value)	rejected with 400 (echoing the rejected value); use `global`, `project` or `user` for templates and harness configs, `project` or `agent` for subscription templates
harness-config update (`PUT /api/v1/harness-configs/{id}`) accepted `scope`, `scopeId`, `ownerId`, `storagePath`, `storageUri` and `storageBucket` from the request body	update keeps the stored record’s scope, scope ID, owner and storage location, matching template updates
pre-existing stored `scope='grove'` rows in `templates`, `harness_configs` and `subscription_templates`	normalized to `scope='project'` automatically on hub boot; no action needed
`groveId` (and `groveName`/`grove` on project records) in hub API responses for notifications, subscriptions, subscription templates, schedules, scheduled events, access tokens, messages, project providers, project sync state and agent session metrics	`projectId` (`name`/`slug` where applicable).
`groveId` in hub event payloads; metric attribute `scope="grove"`	`projectId`; `scope="project"` (update dashboards and alerts)
response fields `groveId`, `groveName`, `grove`, `groves`; `source: "grove"` on resolved secrets; token response `groveId`	`projectId`, `name`, `slug`, `projects`; `source: "project"`
legacy `groveId` key decoded into the hubclient request types (create agent, subscription, subscription template, template, clone template, token)	`projectId`; these types no longer map `groveId` to `ProjectID` when decoded from JSON

Extras / telemetry

Removed	Replacement / action
telemetry attributes `scion.grove`, `scion.grove.id`, `scion.grove_id` as identity keys	`scion.project`, `scion.project.id`, `scion.project_id`. The old names are still stripped from user-supplied attributes.
a2a-bridge `groves:` config key, `SCION_GROVE_ID`, `/groves/…` routes; fs-watcher `--grove`	`projects:`, `SCION_PROJECT_ID`, `/projects/…`; `--project`. The bridge ignores `groves:` silently, so a config that uses only `groves:` starts with zero projects. Rename the key before upgrading.
broker-inbound and chat-integration topics `scion.grove.*`	`scion.project.*` (Telegram v1 route imports are converted automatically)

Finish

Removed	Replacement / action