fix(cli): name the entity an environment in every string the os environments family prints (#12429)

ADR-0006's v5.0 rename `project` -> `environment` has no aliases, and AGENTS.md
states "Project now only means the npm/monorepo sense". #10967 (PR #11227)
renamed the COMMAND across these same five files; the ENTITY NOUN inside the
strings oclif prints was left behind, so `os environments switch <id>` answered
`Active project: ...`.

25 user-visible string literals swap to the post-rename noun:
5 `static override description`, 7 flag/arg descriptions, 9 success-path console
lines, 3 `examples` arg placeholders (`<project-id>` -> `<environment-id>`) and
the `switch` id-not-found error.

No behaviour, flag/argument names, exit codes or `--format json`/`yaml` payloads
change. `client.projects.*`, the `res.project`/`res.projects` response fields,
the locals bound from them and the docblock comments are deliberately untouched:
they are API surface in other packages, not CLI wording.


Claude-Session: https://claude.ai/code/session_01UjujZN219uFzBhSYfMykCd

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-litant

.changeset/cli-environments-entity-noun.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): the `os environments` family calls the entity an environment, not a project, in every string it prints (#12153)
+
+Per ADR-0006 the v5.0 rename `project` → `environment` has no aliases, and AGENTS.md
+states "Project now only means the npm/monorepo sense". #10967 (PR #11227) renamed the
+**command** (`os projects …` → `os environments …`) across these same five files; the
+**entity noun** inside the strings oclif prints was left behind. A user ran
+`os environments switch <id>` and the tool answered `✓ Active project: …`.
+
+25 user-visible string literals in `packages/cli/src/commands/environments/` are swapped
+to the post-rename noun. No behaviour, no flag or argument names, no exit codes, and no
+`--format json` / `--format yaml` payloads change — those are produced by
+`formatOutput(res, …)` straight from the control-plane response and are untouched.
+
+| where | count | printed by |
+| --- | --- | --- |
+| `static override description` | 5 | `os environments --help` |
+| flag / arg `description` | 7 | each command's own `--help` |
+| success-path console output | 9 | `list` · `bind` · `create` · `show` · `switch` |
+| `examples` arg placeholder (`<project-id>` → `<environment-id>`) | 3 | `os environments bind --help` |
+| the `switch` id-not-found error | 1 | `os environments switch` on a bad id |
+
+The five `static override description` strings now read as
+`content/docs/deployment/cli.mdx`'s command table has described them since the rename
+("List environments visible to the current session", "Provision a new environment", …),
+so the shipped `--help` and the shipped docs agree for the first time.
+
+What is deliberately NOT renamed, because it is API surface in other packages rather than
+CLI wording, and each needs its own decision: `client.projects.*` (the `@objectstack/client`
+SDK method names), the `res.project` / `res.projects` response fields, the locals bound
+directly from them, and the docblock comments in these files.

packages/cli/src/commands/environments/bind.ts

@@ -21,17 +21,17 @@ import { formatOutput } from '../../utils/output-formatter.js';
  * reflects the latest source.
  */
 export default class EnvironmentsBind extends Command {
-  static override description = 'Bind a local objectstack artifact to an existing project';
+  static override description = 'Bind a local objectstack artifact to an existing environment';
 
   static override examples = [
-    '$ os environments bind <project-id> --artifact ./dist/objectstack.json',
-    '$ os environments bind <project-id> --artifact ./dist/objectstack.json --build',
-    '$ os environments bind <project-id> --reseed',
+    '$ os environments bind <environment-id> --artifact ./dist/objectstack.json',
+    '$ os environments bind <environment-id> --artifact ./dist/objectstack.json --build',
+    '$ os environments bind <environment-id> --reseed',
   ];
 
   static override args = {
     environmentId: Args.string({
-      description: 'Target project id (UUID)',
+      description: 'Target environment id (UUID)',
       required: true,
     }),
   };
@@ -111,7 +111,7 @@ export default class EnvironmentsBind extends Command {
       delete existingMeta.artifactBindError;
       existingMeta.artifact_path = artifactAbs;
 
-      printKV('Project', args.environmentId, '🎯');
+      printKV('Environment', args.environmentId, '🎯');
       printKV('Artifact', artifactAbs, '📦');
 
       const res = await client.projects.update(args.environmentId, {
@@ -139,9 +139,9 @@ export default class EnvironmentsBind extends Command {
       } else if (flags.format === 'yaml') {
         await formatOutput(res, 'yaml');
       } else {
-        console.log(`\n✓ Project bound to artifact`);
+        console.log(`\n✓ Environment bound to artifact`);
         console.log(`  ${args.environmentId} → ${artifactAbs}`);
-        console.log(`  The next request to this project will load the new bundle.`);
+        console.log(`  The next request to this environment will load the new bundle.`);
         console.log('');
       }
     } catch (error: any) {

packages/cli/src/commands/environments/create.ts

@@ -15,7 +15,7 @@ import { readAuthConfig, writeAuthConfig } from '../../utils/auth-config.js';
  * (unless `--no-activate` is passed).
  */
 export default class EnvironmentsCreate extends Command {
-  static override description = 'Provision a new project';
+  static override description = 'Provision a new environment';
 
   static override examples = [
     '$ os environments create --org 00000000-0000-0000-0000-000000000000 --name Staging',
@@ -39,11 +39,11 @@ export default class EnvironmentsCreate extends Command {
     // the App Marketplace instead (`os package install`, `sys_package` with
     // `is_starter = true`).
     artifact: Flags.string({
-      description: 'Path to a locally-compiled objectstack.json artifact to bind into this project',
+      description: 'Path to a locally-compiled objectstack.json artifact to bind into this environment',
     }),
-    'clone-from': Flags.string({ description: 'Clone schema from an existing project id' }),
+    'clone-from': Flags.string({ description: 'Clone schema from an existing environment id' }),
     activate: Flags.boolean({
-      description: 'Activate the new project for subsequent CLI calls',
+      description: 'Activate the new environment for subsequent CLI calls',
       default: true,
       allowNo: true,
     }),
@@ -111,9 +111,9 @@ export default class EnvironmentsCreate extends Command {
         await formatOutput(res, 'yaml');
       } else {
         const p = res?.project ?? {};
-        console.log(`\n✓ Project created: ${p.display_name ?? p.id} (${p.id})`);
+        console.log(`\n✓ Environment created: ${p.display_name ?? p.id} (${p.id})`);
         if (flags.activate) {
-          console.log(`  active project set to ${p.id}`);
+          console.log(`  active environment set to ${p.id}`);
         }
         console.log('');
       }

packages/cli/src/commands/environments/list.ts

@@ -13,7 +13,7 @@ import { formatOutput } from '../../utils/output-formatter.js';
  * consistent DX.
  */
 export default class EnvironmentsList extends Command {
-  static override description = 'List projects visible to the current session';
+  static override description = 'List environments visible to the current session';
 
   static override examples = [
     '$ os environments list',
@@ -25,7 +25,7 @@ export default class EnvironmentsList extends Command {
     url: Flags.string({ char: 'u', description: 'Server URL', env: 'OS_CLOUD_URL' }),
     token: Flags.string({ char: 't', description: 'Authentication token', env: 'OS_TOKEN' }),
     org: Flags.string({ description: 'Filter by organization id' }),
-    status: Flags.string({ description: 'Filter by project status (active|provisioning|failed|…)' }),
+    status: Flags.string({ description: 'Filter by environment status (active|provisioning|failed|…)' }),
     format: Flags.string({
       char: 'f',
       description: 'Output format',
@@ -57,9 +57,9 @@ export default class EnvironmentsList extends Command {
       } else if (flags.format === 'yaml') {
         await formatOutput(res, 'yaml');
       } else {
-        console.log(`\nProjects (${projects.length}):\n`);
+        console.log(`\nEnvironments (${projects.length}):\n`);
         if (projects.length === 0) {
-          console.log('  (no projects)');
+          console.log('  (no environments)');
         } else {
           for (const p of projects) {
             const active = p.id === activeId ? ' ★' : '';

packages/cli/src/commands/environments/show.ts

@@ -12,15 +12,15 @@ import { formatOutput } from '../../utils/output-formatter.js';
  * membership row (same shape as `client.projects.get(id)`).
  */
 export default class EnvironmentsShow extends Command {
-  static override description = 'Show detailed information for a project';
+  static override description = 'Show detailed information for an environment';
 
   static override examples = [
     '$ os environments show 00000000-0000-0000-0000-000000000001',
     '$ os environments show proj-123 --format json',
   ];
 
   static override args = {
-    id: Args.string({ description: 'Project id', required: true }),
+    id: Args.string({ description: 'Environment id', required: true }),
   };
 
   static override flags = {
@@ -49,7 +49,7 @@ export default class EnvironmentsShow extends Command {
         await formatOutput(res, 'yaml');
       } else {
         const p = res?.project ?? {};
-        console.log(`\nProject: ${p.display_name ?? p.id}`);
+        console.log(`\nEnvironment: ${p.display_name ?? p.id}`);
         console.log('─'.repeat(60));
         console.log(`  id:             ${p.id}`);
         console.log(`  organization:   ${p.organization_id ?? '—'}`);

packages/cli/src/commands/environments/switch.ts

@@ -15,15 +15,15 @@ import { readAuthConfig, writeAuthConfig } from '../../utils/auth-config.js';
  * project.
  */
 export default class EnvironmentsSwitch extends Command {
-  static override description = 'Activate a project for subsequent CLI calls';
+  static override description = 'Activate an environment for subsequent CLI calls';
 
   static override examples = [
     '$ os environments switch 00000000-0000-0000-0000-000000000001',
     '$ os environments switch proj-123 --no-remote',
   ];
 
   static override args = {
-    id: Args.string({ description: 'Project id to activate', required: true }),
+    id: Args.string({ description: 'Environment id to activate', required: true }),
   };
 
   static override flags = {
@@ -47,7 +47,7 @@ export default class EnvironmentsSwitch extends Command {
       const lookup = await client.projects.get(args.id);
       const project = lookup?.project;
       if (!project?.id) {
-        throw new Error(`Project ${args.id} not found`);
+        throw new Error(`Environment ${args.id} not found`);
       }
 
       if (flags.remote) {
@@ -59,7 +59,7 @@ export default class EnvironmentsSwitch extends Command {
       cfg.lastUsedAt = new Date().toISOString();
       await writeAuthConfig(cfg);
 
-      console.log(`\n✓ Active project: ${project.display_name ?? project.id}`);
+      console.log(`\n✓ Active environment: ${project.display_name ?? project.id}`);
       console.log(`  id: ${project.id}`);
       if (!flags.remote) {
         console.log('  (local only — server session unchanged)');