@descix/cli 1.0.4 → 1.0.6

package/README.md

@@ -15,11 +15,12 @@ npm install -g @descix/cli
     descix login
     ```
 
-2.  **Setup your workspace**:
+2.  **Initialize your workspace**:
     ```bash
-    descix setup
+    descix init
     ```
-    This will guide you through connecting your Google Drive and setting up your local environment.
+    This writes `.descix/workspace.json` for the current project. Pass `-c <community_id> -a <app_id>`
+    to pre-fill the app context, or `--from-invite <token>` to resolve an invite token.
 
     **Choosing an environment**:
     The `--dev` flag has been REMOVED. Its absence silently meant production, so the most common
@@ -58,40 +59,129 @@ Best for platform admins or agencies managing multiple communities.
 ## Core Commands
 
 - `descix login`: Authenticate with the platform.
-- `descix setup`: Initialize or repair your workspace configuration.
 - `descix status`: View your current environment status and workspace mode.
-- `descix init`: Create `.descix/workspace.json` for the current project.
-- `descix app create`: Show instructions; use `--quick -c <community> -a <name>` for template-only app creation, or use PWA / `descix-admin app create`.
-- `descix sync`: Sync content to the platform (Site, Assets).
-- `descix kb`: Manage Knowledge Base content (Pull -> Chunk -> Sync).
+- `descix init`: Initialize workspace for DeSciX app development (Git-aware) — writes `.descix/workspace.json`.
+- `descix app init`: Create (when it does not exist yet) and initialize an app — the one path to an app. See [Creating an App](#creating-an-app).
+- `descix site init` / `descix site upload`: Scaffold an app's site, then build and deploy it. See [Deploying a Site](#deploying-a-site).
+- `descix app sync-assets`: Sync local assets (`system_instructions.md`, `app_description.md`, `icon.png`) to the platform.
+- `descix drive pull` / `descix drive push`: Drive content authoring — pull from Drive to local markdown, push staging back to Drive.
+- `descix kb`: Manage Knowledge Bases (`list`, `create`, `delete`, and `corpus sync`).
 
 ## Knowledge Base Management (Git Mode)
 
-For apps managed via CLI (Git Mode), use the following commands to process your Knowledge Base locally:
+The CLI exposes exactly ONE knowledge-base sync surface: `descix kb corpus sync`, driven by a
+git-tracked corpus manifest. The older four-step local pipeline has been REMOVED — its invocations
+now exit non-zero and name this replacement.
 
-1.  **Pull**: Fetch source documents from Drive.
+1.  **Create** the knowledge base (once per KB):
     ```bash
-    descix kb pull
+    descix kb create -c <community_id> -a <app_id> -k <kb_name>
     ```
-2.  **Chunk**: Process documents into chunks locally.
+2.  **Author** a corpus manifest at `.descix/manifests/<kb_name>.json` describing the sources to sync.
+3.  **Sync** the corpus to the platform (Pinecone):
     ```bash
-    descix kb chunk
-    ```
-3.  **Sync**: Push chunks to the platform (Pinecone).
-    ```bash
-    descix kb sync
-    ```
-4.  **Build**: Run the full pipeline (Pull -> Chunk -> Sync).
-    ```bash
-    descix kb build
+    descix kb corpus sync -a <app_id> [-k <kb_name>]
     ```
+    It walks the git blobs at the manifest's ref, so only changed files are re-vectorized. Useful
+    flags: `--dry-run` (report drift, write nothing), `--show-walk` (print the resolved ref and the
+    files it would walk), `--ref <ref>` (override the git ref for all manifest sources).
+
+To fetch source documents from Google Drive into local markdown, use `descix drive pull`.
+
+## Creating an App
+
+`descix app init` is the one path to an app. It creates the app on the platform when it does not
+exist yet, then registers and scaffolds it locally — one command, not two.
+
+```bash
+descix app init -a <name> -c <community>
+```
+
+Pass `-c` to create a new app in that community. **Omit `-c` to initialize an app that already
+exists** — the CLI resolves the app from the Products registry and only does the local half.
+
+The command is idempotent, so re-running it on a half-made app finishes the job.
+
+**Options:**
+
+- `-a, --app <app_id>` (required): the app ID. With `-c`, this is the app NAME to create.
+- `-c, --community <id>`: the community to create the app in. It must already be materialized in
+  this environment. Required only for creation.
+- `-s, --short <short_name>`: the short id segment (no hyphens). The `app_id` is composed
+  **server-side** as `{community}-{short}`; defaults to `--app`.
+- `--overwrite`: when creating, overwrite an existing app record intentionally.
+- `--kb <name>`: knowledge base name (default: `General`).
+- `-p, --path <dir>`: local app directory (default: auto-detected, else the current directory).
+
+**What it does, in order:**
+
+1.  **Creates the app** (only when `-c` is given and the app does not exist): the server composes
+    the unique `app_id` and writes `Products/{app_id}` and `Community/{community}/Apps/{app_id}`.
+    Every app is guaranteed a default knowledge base at creation.
+2.  **Registers it in `.descix/workspace.json`** if it is not already mapped.
+3.  **Scaffolds the app folder**: creates `site/`, `microservice/` and `assets/`, and writes
+    `assets/system_instructions.md` and `assets/app_description.md` when they do not exist.
+4.  **Creates the knowledge base record** for Git-mode sync.
+
+It fails loud rather than guessing: initializing an app that does not exist without `-c` names the
+`-c` invocation that would create it; a `-c` that disagrees with the app's real community is
+refused; and `-p` against an already-mapped app names `descix app set-localpath` instead.
 
-## Provisioning
+**Next step** — author a corpus manifest at `.descix/manifests/<kb_name>.json`, then
+`descix kb corpus sync -a <app_id>`.
 
-**Communities and apps are created in the PWA** (Workspace Config / Device Setup / App Manager) or via **Admin CLI** (`descix-admin community create`, `descix-admin app create`) for platform admins. The user CLI does not create communities or full app structures; use `descix init` to write `.descix/workspace.json` and PWA or Admin CLI to create entities.
+Creating a **community** is a separate, admin-only operation: `descix community create` requires
+platform-admin membership and deploys a real ERC-20 token contract to live Polygon. App developers
+work inside a community that already exists.
 
-1.  Create your App in the PWA (Workspace Builder).
-2.  Run `descix setup` to hydrate your local folder structure.
+## Deploying a Site
+
+An app's site is scaffolded, then uploaded. `descix site upload` is the deploy verb — there is no
+`descix site deploy`.
+
+```bash
+descix site init      # scaffold site/ (optional — upload works on any site directory)
+descix site upload --env dev
+```
+
+### `descix site init`
+
+Copies the site scaffold — `index.html`, `app.js`, `styles.css`, `DeSciXAppSDK.js`, `README.md` —
+into the app's `site/` directory. The app must already be mapped in `.descix/workspace.json`.
+
+- `-f, --force`: overwrite an existing `site/` folder.
+- `-c, --community <id>` / `-a, --app <id>`: auto-detected from context when omitted.
+
+It scaffolds site content only; it writes no manifest. Skip it entirely if you already have a site.
+
+### `descix site upload`
+
+Builds (when a manifest declares a build) and uploads the site to GCS, then updates the app's
+metadata. Files are uploaded straight to GCS with short-lived **signed URLs** issued by
+`get_site_deploy_token`; `confirm_site_deploy` then records the deploy and returns the site URL.
+
+- `-p, --path <localPath>`: directory to deploy (default `./site`). **Ignored when a site manifest
+  exists.**
+- `--preview`: deploy to the preview path.
+- `--full`: force a full upload, ignoring the unchanged-file delta.
+- `--dry-run`: show what would be deployed.
+- `--no-cache`: set `Cache-Control: no-cache`.
+- `-c, --community <id>` / `-a, --app <id>`: auto-detected from context when omitted.
+
+**Site deploys target a cloud environment.** An upload that resolves to a local backend without
+this invocation naming its target is refused — pass `--env <dev|demo|prod>`.
+
+**Manifest-driven builds.** When `{app_root}/.descix/manifests/site.json` exists it takes over from
+`-p`. Author it yourself; nothing generates it for you. It declares the sources to walk and,
+optionally, a `buildCommand`, which runs in the app root with the environment-specific `VITE_*`
+build variables the server returns injected into its environment:
+
+```json
+{
+  "sources": [{ "path": "site/dist", "include": ["**/*"] }],
+  "buildCommand": "npm run build --prefix site"
+}
+```
 
 ## Airdrop Admin Operations (WS-ADMIN-B1)
 
@@ -103,25 +193,31 @@ Admin-only commands for triggering airdrop migration batch runs. Per CEO-D-MANUA
 
 Manually trigger the server-side `airdrop_execute_queue` command on the target environment. Assembles `pending_migrations` rows into per-community batches and (when `BATCH_UPDATE_BALANCES_BROADCAST_ENABLED=true`) broadcasts to the Powch HD wallet. When the broadcast flag is off (default for DEV), batches are assembled but the downstream Powch handler returns `stopped_at_broadcast_boundary` — useful for verifying queue shape without spending MATIC.
 
+**Read-only is the default.** Without `--apply`, the command runs as a dry run.
+
 **Options:**
 
+- `--dry-run`: Read-only preview — encode calldata, estimate gas, validate the net-zero invariant. No PK, no transaction, no state mutation. Mutually exclusive with `--apply`.
+- `--apply`: Live execution. Requires `--signer-pk-file` or the interactive prompt, and requires `--community`.
+- `--community <slug>`: Community slug for per-community batch scoping. **Required for `--apply`**; optional in dry-run mode, where omitting it returns an aggregate preview across communities.
+- `--signer-pk-file <path>`: Path to a file containing the admin signer PK (`0x` + 64 hex). Used for `--apply`; when omitted, the PK is requested at an interactive no-echo prompt. Inline PK flags and environment variables are rejected on security grounds (process-listing leak).
 - `--batch-size <n>`: Cap on users processed this run (server caps at `AIRDROP_MAX_RUN_USERS`; a larger `--batch-size` is clamped).
-- `--dry-run`: Assemble batches but skip the broadcast call entirely. Emits an `on_chain_log` row with `status: dry_run` for audit.
 
 **Examples:**
 
 ```bash
-# Dry run against DEV — safe to run repeatedly; no broadcast, no MATIC
+# Dry run against DEV — safe to run repeatedly; no PK, no tx, no state mutation
 descix airdrop execute-queue --env dev --dry-run
 
-# Execute a capped real run (10 users max this invocation)
-descix airdrop execute-queue --env dev --batch-size 10
+# Dry run scoped to one community
+descix airdrop execute-queue --env dev --dry-run --community smile
 
-# Execute a full queue run (still gated by BATCH_UPDATE_BALANCES_BROADCAST_ENABLED)
-descix airdrop execute-queue --env dev
-```
+# Live execution, capped at 10 users this invocation (prompts for the signer PK)
+descix airdrop execute-queue --env dev --apply --community smile --batch-size 10
 
-**Audit trail:** every invocation (dry-run or real) writes one `on_chain_log` row with `op.kind = "airdrop_execute_queue_trigger"` and `caller.operator_email = <invoking admin email>`.
+# Live execution reading the signer PK from a file
+descix airdrop execute-queue --env dev --apply --community smile --signer-pk-file ./signer.key
+```
 
 **Testing:**
 
@@ -131,4 +227,4 @@ cd DeSciX_Core/descix-cli && npm test
 
 ## Documentation
 
-For full documentation, please refer to the [DeSciX SDK Documentation](../../SERVICE_README_sdk.md).
+For full documentation, please refer to the [DeSciX SDK Documentation](./SERVICE_README_sdk.md).

package/agent-assets/reference/local-dev.md

@@ -143,10 +143,6 @@ KB querying will surface. If you fix something there, the fix reaches readers of
 nobody asking the KB — so do not assume KB coverage for a surface that has none. This is a known
 boundary, not a defect.
 
-`descix kb chunk`, `descix kb sync` and `descix update kb` still run but are **superseded
-duplicates** — each names `kb corpus sync` as its replacement in its own `--help` and is slated
-for removal. Do not put them in new instructions.
-
 #### What you put in a KB changes what comes out of it
 
 Retrieval is **vocabulary-dominated**, and when it goes wrong it does so silently. Measured against

package/bin/descix.js

@@ -11,8 +11,9 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { DeSciXApiClient } from '../lib/api-client.js';
 import { requireAuth } from '../lib/auth-guard.js';
-import { WorkspaceConfig } from '../lib/workspace-config.js';
+import { WorkspaceConfig, unmappedAppMessage } from '../lib/workspace-config.js';
 import { CLI_VERSION } from '../lib/cli-version.js';
+import { recordInvocationOrigin } from '../lib/origin.js';
 // Chat session pointer + the ONE rule for when a dead pointer may be self-healed.
 import {
   getSessionInteractionId,
@@ -107,12 +108,24 @@ const ENV_URL_MAP = Object.fromEntries(
   Object.entries(WorkspaceConfig.ENV_MAP).map(([k, v]) => [k, v.url])
 );
 
+// The fold into DESCIX_API_URL is what makes every consumer see ONE variable — and it is also
+// what used to DESTROY the answer to "who chose this origin", so the origin owner printed a
+// static disjunction ("DESCIX_API_URL (or --api-url / --env)") for all three cases. The fold
+// stays; the provenance is now RECORDED alongside it, in the same breath, so the owner can name
+// the actual source. Recording it here rather than deriving it in the owner keeps one owner of
+// the fact: the only code that knows a flag was passed is the code that read the flag.
 program.hook('preAction', (thisCommand) => {
-  const opts = thisCommand.opts();
+  // Read from the ROOT program, not from the action command. `--env` and `--api-url` are
+  // declared ONCE, globally, and Commander binds them to the root — an identically-named option
+  // redeclared on a subcommand is shadowed and silently never populated (measured on 1.0.4:
+  // `descix config init --env dev` reached its action with `{}` and rejected its own advertised
+  // flag). One declaration, read from where Commander actually puts it.
+  const opts = program.opts();
 
   // --api-url takes highest priority
   if (opts.apiUrl) {
     process.env.DESCIX_API_URL = opts.apiUrl;
+    recordInvocationOrigin(opts.apiUrl, 'flagApiUrl');
     return;
   }
 
@@ -120,12 +133,23 @@ program.hook('preAction', (thisCommand) => {
   if (opts.env) {
     const envName = opts.env.toLowerCase();
     if (!(envName in ENV_URL_MAP)) {
-      console.error(chalk.red(`Unknown environment: ${opts.env}. Use: dev, demo, prod`));
+      // THE REFUSAL CARRIES THE CUSTOM-ENVIRONMENT PATH. This validator runs BEFORE any command
+      // action, so it is now the only thing a developer typing `--env staging` ever sees — the
+      // richer text inside `config init` that names `config set-env` for exactly this case can
+      // no longer be reached through the flag. A refusal that names only the three built-in
+      // names would strand every self-hosted or port-forwarded gateway with no next step, which
+      // is the same dead end as a remedy string for a command that does not run.
+      console.error(chalk.red(
+        `Unknown environment: ${opts.env}. Known environments: ${Object.keys(ENV_URL_MAP).join(', ')}.\n\n` +
+        'For a self-hosted or port-forwarded gateway, name it with its origin instead:\n' +
+        `  descix config set-env ${envName} --url https://...`
+      ));
       process.exit(1);
     }
     // Every named environment resolves to a URL (including dev → cloud DEV).
     // A local backend is a URL you name, not an environment.
     process.env.DESCIX_API_URL = ENV_URL_MAP[envName];
+    recordInvocationOrigin(ENV_URL_MAP[envName], 'flagEnv');
   }
 });
 
@@ -2483,8 +2507,7 @@ siteCommand
       
       const appConfig = workspaceConfig.getAppByAppId(ctx.appId);
       if (!appConfig) {
-        console.error(chalk.red('\n❌ App not found in workspace.json.'));
-        console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+        console.error(chalk.red(`\n❌ ${unmappedAppMessage(ctx.appId)}\n`));
         process.exit(1);
       }
 
@@ -2494,9 +2517,10 @@ siteCommand
       console.log(chalk.cyan('\n📁 Adding site scaffold...\n'));
       
       const { copyScaffold } = await import('../lib/core/Hydrator.js');
-      const stats = await copyScaffold('site', appPath, { 
-        verbose: true, 
-        force: options.force 
+      const stats = await copyScaffold('site', appPath, {
+        verbose: true,
+        force: options.force,
+        substitute: { appId: ctx.appId, communityId: ctx.communityId }
       });
       
       console.log(chalk.green(`\n✅ Site scaffold added (${stats.copied} files)\n`));
@@ -2850,8 +2874,7 @@ siteCommand
       if (!port) {
         const appConfig = workspaceConfig.getAppByAppId(appId);
         if (!appConfig) {
-          console.error(chalk.red('\n❌ App not found in workspace.json.'));
-          console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+          console.error(chalk.red(`\n❌ ${unmappedAppMessage(appId)}\n`));
           process.exit(1);
         }
         // Read site.port from the live env entry (not from the constructed copy)
@@ -3092,8 +3115,7 @@ microserviceCommand
       
       const appConfig = workspaceConfig.getAppByAppId(ctx.appId);
       if (!appConfig) {
-        console.error(chalk.red('\n❌ App not found in workspace.json.'));
-        console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+        console.error(chalk.red(`\n❌ ${unmappedAppMessage(ctx.appId)}\n`));
         process.exit(1);
       }
 
@@ -3125,7 +3147,8 @@ microserviceCommand
       const { copyScaffold } = await import('../lib/core/Hydrator.js');
       const stats = await copyScaffold('microservice', appPath, {
         verbose: true,
-        force: options.force
+        force: options.force,
+        substitute: { appId: ctx.appId, communityId: ctx.communityId }
       });
 
       // Configuration Injection
@@ -3134,15 +3157,16 @@ microserviceCommand
       const manifestPath = path.join(microserviceDir, 'manifest.json');
       const overridesPath = path.join(microserviceDir, 'dev-overrides.json');
 
-      // 1. Inject Context + Port into defaults-config.json
+      // 1. Inject Port into defaults-config.json.
+      // IDENTITY IS NOT SET HERE. copyScaffold resolves {{APP_ID}}/{{COMMUNITY_ID}} during the
+      // copy, so re-deriving them here would be a second derivation of one fact. The port is a
+      // workspace-derived RUNTIME value with no scaffold token, so it stays.
       try {
         const defaultsContent = await fs.readFile(defaultsPath, 'utf-8');
         const defaults = JSON.parse(defaultsContent);
-        defaults.community_id = ctx.communityId;
-        defaults.app_id = ctx.appId;
         defaults.LOCAL_PORT = microservicePort;
         await fs.writeFile(defaultsPath, JSON.stringify(defaults, null, 2));
-        console.log(chalk.gray(`  ✓ Injected context + port into defaults-config.json`));
+        console.log(chalk.gray(`  ✓ Injected port into defaults-config.json`));
       } catch (err) {
         console.warn(chalk.yellow(`  ⚠ Could not update defaults-config.json: ${err.message}`));
       }
@@ -3164,20 +3188,19 @@ microserviceCommand
         console.warn(chalk.yellow(`  ⚠ Could not claim package.json: ${err.message}`));
       }
 
-      // 2. Inject Context + Port into manifest.json
+      // 2. Inject Port into manifest.json.
+      // IDENTITY IS NOT SET HERE. copyScaffold resolved {{APP_ID}}/{{COMMUNITY_ID}} during the
+      // copy, so setting app_id/community_id/name again would be a second derivation of one fact —
+      // the exact mirror-drift shape that let a scaffold ship `community_id: 'descix'` while this
+      // block quietly wrote the right value into a different file.
+      // No domain is injected. A service does not declare its own domain — the platform derives
+      // it ({app_id}.{SITE_DOMAIN}) at registration, and refuses a manifest that declares one.
       try {
         const manifestContent = await fs.readFile(manifestPath, 'utf-8');
         const manifest = JSON.parse(manifestContent);
-        manifest.service.app_id = ctx.appId;
-        manifest.service.community_id = ctx.communityId;
-        manifest.service.name = ctx.appId;
-        // No domain is injected. A service does not declare its own domain — the platform derives
-        // it ({app_id}.{SITE_DOMAIN}) at registration, and refuses a manifest that declares one.
-        // The literal this replaced was `${ctx.appId}.descix.net`: the PROD host, scaffolded into
-        // every service regardless of the env it would be registered against.
         manifest.service.debugPort = microservicePort;
         await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
-        console.log(chalk.gray(`  ✓ Injected context + port into manifest.json`));
+        console.log(chalk.gray(`  ✓ Injected port into manifest.json`));
       } catch (err) {
         console.warn(chalk.yellow(`  ⚠ Could not update manifest.json: ${err.message}`));
       }
@@ -4334,15 +4357,24 @@ configCommand
 
 configCommand
   .command('init')
-  .description('Initialize configuration for an environment (requires --env)')
+  .description('Pin this workspace to an environment (requires the global --env dev|demo|prod)')
   // `--dev` DELETED, not deprecated: its absence meant PRODUCTION, so the most common
   // invocation (`descix config init`) wrote a prod origin nobody named. There is no default.
-  .option('--env <name>', 'Environment to initialize: dev, demo or prod')
+  //
+  // `--env` IS NOT REDECLARED HERE, and that is the fix, not an omission. It was declared both
+  // globally (program.option, above) and on this subcommand; Commander 14 binds `--env dev` to
+  // the ROOT program, so this action received `{}` and threw "requires an environment" — the
+  // command REJECTED THE FLAG ITS OWN --help ADVERTISED. Measured on published 1.0.4, and worse
+  // than a missing command: the CLI printed `descix config init --env dev` as the remedy for an
+  // unconfigured origin (origin.js DEFAULT_ORIGIN_SOURCE) and that exact copy-pasted string
+  // exited 1. Two declarations of one flag is the mirror-drift class; one owner is the cure.
   .option('--url <url>', 'Explicit origin (for a self-hosted or port-forwarded gateway)')
   .option('-g, --global', 'Save to global config (~/.descixrc)')
+  .addHelpText('after', '\nEnvironment comes from the global flag:\n' +
+    '  descix config init --env dev|demo|prod\n')
   .action(async (options) => {
     try {
-      await configCommands.init(options.env, options);
+      await configCommands.init(program.opts().env, options);
     } catch (error) {
       fail(error);
     }

package/lib/api-client.js

@@ -66,6 +66,15 @@ export class DeSciXApiClient {
       this.baseUrl = String(this.baseUrl).trim().replace(/\/+$/, '');
       originSource = EXPLICIT_ORIGIN_SOURCE;
     }
+    // KEPT ON THE CLIENT, not just printed and dropped. `status` and `doctor` have to SHOW the
+    // resolved origin and its source in their own report bodies; when this was a local variable
+    // the only way for them to state an origin was to derive one themselves, and both did —
+    // from GlobalConfig.api_url, which is legitimately null. That produced three different
+    // answers for one state seconds apart (status "production (null)", doctor "API URL: null",
+    // app list the real origin). A consumer can only ferry the owner's answer if the owner's
+    // answer is still reachable.
+    this.originSource = originSource;
+
     // I1 (A', rev 2): ALWAYS, not default-only. Silence was the defect; PROD was not.
     reportEnvironment({ origin: this.baseUrl, source: originSource });
 

package/lib/commands/auth.js

@@ -275,6 +275,7 @@ export async function loginDevice(options = {}) {
     diag(chalk.gray(`   ${walletPath}\n`));
     
     // Sync auto-purchase apps
+    let entitlementsSynced = true;
     spinner.start('Syncing app entitlements...');
     try {
       apiClient.setCredentials({
@@ -293,10 +294,25 @@ export async function loginDevice(options = {}) {
         spinner.succeed(chalk.gray('App entitlements up to date'));
       }
     } catch (error) {
+      entitlementsSynced = false;
       spinner.warn(chalk.yellow('Could not sync app entitlements'));
       diag(chalk.gray(`   ${error.message}\n`));
     }
-    
+
+    // DO NOT CLAIM SUCCESS ON A PARTIAL LOGIN, AND DO NOT EXIT 0.
+    // Credentials are saved either way, so this is genuinely partial rather than a failed login —
+    // but entitlements are what grant app access, so "you can now use all DeSciX CLI commands" is
+    // false when the sync failed. A script branching on the exit code is the caller least able to
+    // read the yellow warning above, which is why the code is the sharper half of this fix.
+    if (!entitlementsSynced) {
+      diag(chalk.yellow(
+        'Logged in, but app entitlements did NOT sync. Credentials are saved; commands needing an ' +
+        'entitlement may fail until you re-run `descix login`.\n'
+      ));
+      process.exitCode = 1;
+      return;
+    }
+
     diag(chalk.white('You can now use all DeSciX CLI commands!\n'));
 
   } catch (error) {

package/lib/commands/config.js

@@ -101,13 +101,29 @@ export async function init(env, options = {}) {
     // Write through the CANONICAL writer. This function used to assign the LEGACY top-level
     // `workspaceConfig.apiUrl`, while `config set-env` writes `env.apiUrl` — two writers of one
     // fact, writing two different keys, one of which `getApiUrl()` only consults as a fallback.
-    const workspaceConfig = await WorkspaceConfig.load();
+    //
+    // `tryLoad`, NOT `load`, AND IT CREATES ONE WHEN THERE IS NONE. This is what closes the
+    // PROD WINDOW at the start of every onboarding (measured on published 1.0.4): in a fresh
+    // directory `config init --env dev` threw "Workspace not configured", `config set-env dev`
+    // threw the same, and so there was NO WORKING WAY TO PIN THE ENVIRONMENT BEFORE the first
+    // command ran — every one of them silently targeted PROD while printing a remedy that could
+    // not be executed. Pinning the environment must not require a workspace to already exist:
+    // choosing the origin is the FIRST thing a developer does, not something they may only do
+    // after they have already talked to the wrong one.
+    const existing = await WorkspaceConfig.tryLoad();
+    const workspaceConfig = existing
+      || new WorkspaceConfig({ version: '2.1', type: 'workspace', env: {} }, process.cwd());
+    const created = !existing;
     const result = await workspaceConfig.setEnvironment(normalized, options.url || null);
 
     console.log(chalk.green('\n✅ Configuration initialized!\n'));
     console.log(chalk.white(`   Environment: ${result.environment}`));
     console.log(chalk.white(`   API URL:     ${result.apiUrl}`));
-    console.log(chalk.gray(`   Saved to:    ${result.configPath}\n`));
+    console.log(chalk.gray(`   Saved to:    ${result.configPath}`));
+    if (created) {
+      console.log(chalk.gray('   (new workspace created here — this directory is now the workspace root)'));
+    }
+    console.log('');
 
   } catch (error) {
     console.error(chalk.red('Error initializing config:', error.message));
@@ -124,7 +140,32 @@ export async function init(env, options = {}) {
  */
 export async function setEnv(envName, options = {}) {
   try {
-    const workspaceConfig = await WorkspaceConfig.load();
+    // ONE SURFACE PER CAPABILITY. `config init` and `config set-env` both write through the same
+    // canonical writer (setEnvironment) — that shared owner is correct — but they must not both
+    // accept the SAME input, or there are two commands for one act and the CLI's own remedy
+    // string can name the loser. `config init` is canonical for the three KNOWN environments:
+    // the origin owner prints `descix config init --env dev` as the remedy, so that command must
+    // be the one that does it. `set-env` keeps the capability `init` genuinely does not have —
+    // a CUSTOM environment name with an explicit --url — and REFUSES the known names outright,
+    // naming its replacement. A refusal, not a warning: a warning would leave two working paths.
+    const knownName = WorkspaceConfig.ENV_MAP[String(envName).toLowerCase()];
+    if (knownName) {
+      throw new Error(
+        `"${envName}" is a known environment — use the canonical command:\n` +
+        `  descix config init --env ${String(envName).toLowerCase()}\n\n` +
+        'descix config set-env is for a CUSTOM environment name with an explicit origin, e.g.\n' +
+        '  descix config set-env staging --url https://staging.example.com'
+      );
+    }
+
+    // Same tryLoad-or-create as `config init`, for the same reason: `config init`'s own error
+    // text sends a developer HERE for the self-hosted / port-forwarded case, so this command has
+    // to work where that developer actually is. If it still required a pre-existing workspace,
+    // init's remedy would point at a command that refuses — the identical closed loop, moved one
+    // hop along. A remedy string is only true if the command it names runs.
+    const existing = await WorkspaceConfig.tryLoad();
+    const workspaceConfig = existing
+      || new WorkspaceConfig({ version: '2.1', type: 'workspace', env: {} }, process.cwd());
 
     const result = await workspaceConfig.setEnvironment(envName, options.url || null);