@descix/cli 2.0.2 → 2.0.4

package/README.md

@@ -183,48 +183,6 @@ build variables the server returns injected into its environment:
 }
 ```
 
-## Airdrop Admin Operations (WS-ADMIN-B1)
-
-Admin-only commands for triggering airdrop migration batch runs. Per CEO-D-MANUAL-TRIGGER-NO-CRON (2026-04-20), Cloud Scheduler cron was dropped from Round B in favor of operator-invoked manual triggers via this CLI.
-
-**Access:** requires platform-admin membership (enforced server-side via `isPlatformAdmin(user)`).
-
-### `descix airdrop execute-queue`
-
-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).
-
-**Examples:**
-
-```bash
-# Dry run against DEV — safe to run repeatedly; no PK, no tx, no state mutation
-descix airdrop execute-queue --env dev --dry-run
-
-# Dry run scoped to one community
-descix airdrop execute-queue --env dev --dry-run --community smile
-
-# 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
-
-# Live execution reading the signer PK from a file
-descix airdrop execute-queue --env dev --apply --community smile --signer-pk-file ./signer.key
-```
-
-**Testing:**
-
-```bash
-cd DeSciX_Core/descix-cli && npm test
-```
-
 ## Documentation
 
 For full documentation, please refer to the [DeSciX SDK Documentation](./SERVICE_README_sdk.md).

package/agent-assets/guides/microservice-pattern.md

@@ -116,7 +116,9 @@ descix kb corpus sync -c <community> -a <app>
 
 **What registration is, and is not.** It publishes your `manifest.json` — the command list —
 and vectorizes the README you pass with `-r`, so `tell_me_how` can discover your tools.
-`scripts/register.js` writes that manifest and logs the commands it published. There is no
+`scripts/register.js` writes that manifest and logs the commands it published. It targets a RUNNING
+service: it first calls the service's own `/api` unsigned and registers only if the mesh guard
+answers 401, so start the service (`npm run dev`), then run `npm run register`. There is no
 separate developer-facing vectorize step — `descix microservice vectorize` exists but is an
 admin-only utility (for re-vectorizing without re-registering), not part of the normal flow.
 It is a DISCOVERY step.

package/bin/descix.js

@@ -28,7 +28,6 @@ import * as authCommands from '../lib/commands/auth.js';
 import * as configCommands from '../lib/commands/config.js';
 import * as buyCommands from '../lib/commands/buy.js';
 import * as creditsCommands from '../lib/commands/credits.js';
-import * as airdropCommands from '../lib/commands/airdrop.js';
 import { MICROSERVICE_AUTH_MODEL } from '../lib/commands/microservice-auth-model.js';
 import { runInit } from '../lib/commands/init.js';
 // "May I prompt?" has ONE OWNER. No command in this file derives it.
@@ -430,32 +429,6 @@ creditsCommand
     }
   });
 
-// ============ Airdrop Commands (WS-ADMIN-B1 manual-trigger) ============
-// Per CEO-D-MANUAL-TRIGGER-NO-CRON (2026-04-20), airdrop batch execution is operator-triggered
-// via this CLI command group rather than Cloud Scheduler cron. Server-side access is gated on
-// platform-admin membership (`isPlatformAdmin(user)`); the server emits an on_chain_log row
-// with `caller.operator_email` for audit.
-
-const airdropCommand = program
-  .command('airdrop')
-  .description('Admin airdrop migration operations (WS-ADMIN-B1)');
-
-airdropCommand
-  .command('execute-queue')
-  .description('Manually trigger airdrop_execute_queue on the target env (admin-only)')
-  .option('--community <slug>', 'Community slug for per-community batch scoping (REQUIRED for --apply)')
-  .option('--dry-run', 'Read-only preview: encode calldata, estimate gas, validate net-zero invariant. No PK, no tx, no state mutation.')
-  .option('--apply', 'Live execution: requires --signer-pk-file or interactive prompt-password. Mutually exclusive with --dry-run.')
-  .option('--signer-pk-file <path>', 'Path to file containing admin signer PK (0x + 64 hex). Required for --apply unless prompted interactively.')
-  .option('--batch-size <n>', 'Cap on users processed this run (server caps at AIRDROP_MAX_RUN_USERS)')
-  .action(async (options) => {
-    try {
-      await airdropCommands.executeQueue(options);
-    } catch (error) {
-      fail(error);
-    }
-  });
-
 // ============ Sync Commands: REMOVED ============
 // `sync assets`, `sync site` and `sync kb` are all gone, so the `sync` GROUP is gone with
 // them: a registered verb with no working children is dead weight. Every retired verb is
@@ -2374,7 +2347,11 @@ siteCommand
 
       console.log(chalk.cyan(`\n  Site Upload: ${appId} → GCS\n`));
       console.log(chalk.gray(`  Source: ${sourceLabel}`));
-      console.log(chalk.gray(`  Target: ${communityId}/${appId}`));
+      // The write prefix is server-owned and FLAT ({env}/{appId}/site/ — community_id is
+      // derived server-side from Products/{app_id} and a caller-supplied one is ignored).
+      // Printing a locally-guessed community here once read as a changed write target and
+      // held up a prod upload (FRAQTL wall, 2026-10-12) — say only what this client knows.
+      console.log(chalk.gray(`  Target: {env}/${appId}/site/ (flat; community resolved server-side)`));
       if (options.preview) console.log(chalk.yellow(`  Mode: PREVIEW`));
       if (gitStatus.isGitRepo) {
         console.log(chalk.gray(`  Git: ${gitStatus.branch} @ ${gitStatus.shortHash}`));

package/lib/agent-files.js

@@ -12,6 +12,7 @@ import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { readIdentity, isIdentityNamed } from './workspace-identity.js';
 import { mcpServerEntry } from './invocation.js';
+import { CLI_VERSION } from './cli-version.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -71,7 +72,7 @@ async function loadContext(workspaceRoot) {
   // Friendly name: capitalize app_id or use as-is
   const appName = appId.charAt(0).toUpperCase() + appId.slice(1);
 
-  return { appId, communityId, apiUrl: originLine, appName, originSource };
+  return { appId, communityId, apiUrl: originLine, appName, originSource, cliVersion: CLI_VERSION };
 }
 
 /**
@@ -82,7 +83,9 @@ function render(template, vars) {
     .replace(/\{\{appId\}\}/g, vars.appId)
     .replace(/\{\{communityId\}\}/g, vars.communityId)
     .replace(/\{\{apiUrl\}\}/g, vars.apiUrl)
-    .replace(/\{\{appName\}\}/g, vars.appName);
+    .replace(/\{\{appName\}\}/g, vars.appName)
+    .replace(/\{\{originSource\}\}/g, vars.originSource)
+    .replace(/\{\{cliVersion\}\}/g, vars.cliVersion);
 }
 
 /**

package/lib/app-scaffold.js

@@ -0,0 +1,68 @@
+/**
+ * THE ONE OWNER of the files `descix app init` stamps into an app repo beyond the workspace and
+ * the agent instruction files (proposal 2026-10-09-standard-app-repo-form, items 3 and 5):
+ *
+ *   .descix/manifests/site.json   the deployable site set (`descix site upload` reads it)
+ *   .claude-plugin/plugin.json    the Claude plugin stub
+ *   site/index.html               the front-page template (templates/scaffolds/frontpage/)
+ *
+ * ONLY-IF-ABSENT: a file that exists is never read-modified, never overwritten, never reported as
+ * written. The agent files (CLAUDE.md …) stay with lib/agent-files.js; this module does not write
+ * them.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const FRONTPAGE_TEMPLATE = path.join(
+  path.dirname(fileURLToPath(import.meta.url)), '..', 'templates', 'scaffolds', 'frontpage', 'index.html',
+);
+
+const escapeHtml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+async function writeIfAbsent(file, content) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  try {
+    await fs.writeFile(file, content, { encoding: 'utf8', flag: 'wx' });
+    return true;
+  } catch (err) {
+    if (err.code === 'EEXIST') return false;
+    throw err;
+  }
+}
+
+/**
+ * @param {string} appPath the app repo root
+ * @param {{appId: string, communityId: string}} identity
+ * @returns {Promise<string[]>} repo-relative paths actually created
+ */
+export async function scaffoldAppRepo(appPath, { appId, communityId }) {
+  if (!appId || !communityId) {
+    throw new Error('scaffoldAppRepo: appId and communityId are required (no default would be true).');
+  }
+  const siteManifest = {
+    _purpose: `Deployable site set for the ${appId} app; sources are uploaded by descix site upload.`,
+    sources: [{ path: 'site' }],
+    buildCommand: null,
+  };
+  const plugin = {
+    name: appId,
+    description: `${appId}, an app of the ${communityId} community on DeSciX.`,
+    version: '0.1.0',
+    author: { name: communityId },
+  };
+  const frontpage = (await fs.readFile(FRONTPAGE_TEMPLATE, 'utf8'))
+    .replace(/\{\{APP_ID\}\}/g, escapeHtml(appId))
+    .replace(/\{\{COMMUNITY_ID\}\}/g, escapeHtml(communityId));
+
+  const files = [
+    ['.descix/manifests/site.json', JSON.stringify(siteManifest, null, 2) + '\n'],
+    ['.claude-plugin/plugin.json', JSON.stringify(plugin, null, 2) + '\n'],
+    ['site/index.html', frontpage],
+  ];
+  const created = [];
+  for (const [rel, content] of files) {
+    if (await writeIfAbsent(path.join(appPath, rel), content)) created.push(rel);
+  }
+  return created;
+}

package/lib/commands/appInit.js

@@ -15,6 +15,7 @@ import path from 'path';
 import { WorkspaceConfig, assertNoParentWorkspace } from '../workspace-config.js';
 import { refreshCommunityIdentity, printIdentityReceipt } from './communityIdentity.js';
 import { generateAgentFiles } from '../agent-files.js';
+import { scaffoldAppRepo } from '../app-scaffold.js';
 
 /**
  * @param {Object} apiClient an authenticated DeSciXApiClient
@@ -130,6 +131,7 @@ export async function runAppInit(apiClient, options) {
     await fs.writeFile(descPath, `# ${appId}\n\nApplication description goes here.\n`);
   }
   console.log(chalk.gray(`  Created: site/, microservice/, assets/`));
+  for (const f of await scaffoldAppRepo(appPath, { appId, communityId })) console.log(chalk.green(`  ✓ ${f}`));
 
   // 3. The default KB — CREATE leg only (see the adopt block above: map never creates).
   let kbResult = null;

package/lib/commands/config.js

@@ -34,10 +34,24 @@ export async function show() {
       console.log(chalk.yellow(`   ⚠ This workspace pins ${normalizeOrigin(pinned)} (${environmentNameFor(pinned)}), but ${effective.source} overrides it for this shell.`));
     }
 
-    // v3 single-app: the one app this workspace holds
-    const appId = workspaceConfig.env?.app?.appId;
-    if (appId) {
-      console.log(chalk.white(`   App:           ${appId}`));
+    // v3 single-app: the one app this workspace holds. Every fact a verb can set is shown here,
+    // so the verb's effect is verifiable without hand-reading workspace.json (field, 2026-10-10:
+    // neither the adopted kbId nor env.gateway.port was printed by anything).
+    const app = workspaceConfig.env?.app;
+    if (app?.appId) {
+      console.log(chalk.white(`   App:           ${app.appId}`));
+      if (app.kbId) {
+        console.log(chalk.white(`   KB:            ${app.kbId}`));
+      }
+      if (app.site?.static) {
+        console.log(chalk.white(`   Site:          static ${app.site.static}`));
+      } else if (app.site?.port) {
+        console.log(chalk.white(`   Site:          dev server on port ${app.site.port} (${app.site.protocol || 'https'})`));
+      }
+    }
+    const gatewayPort = workspaceConfig.env?.gateway?.port;
+    if (gatewayPort) {
+      console.log(chalk.white(`   Gateway port:  ${gatewayPort}`));
     }
 
     console.log('');

package/lib/commands/retired-verbs.js

@@ -24,6 +24,11 @@ const kbSyncRefusal = (invocation) =>
   `\`${CANONICAL_KB_CREATE}\`.`;
 const KB_SYNC_DESCRIPTION = `REMOVED — use \`${CANONICAL_KB_SYNC}\``;
 
+const AIRDROP_QUEUE_REFUSAL = (invocation) =>
+  `❌ \`${invocation}\` has been REMOVED: the pending_migrations queue it previewed (lane B) no longer ` +
+  `exists, and neither does the server command behind it.\n\n` +
+  `Distributions run through the offers rail on daita-sam (act plan + the role holder's own wallet signs).`;
+
 /**
  * Every retired verb. `invocation` is what a user types; `parent` is the id of the commander
  * parent it hangs off (a root passed to registerAllRetiredVerbs, or an earlier row); `refusal`
@@ -52,6 +57,12 @@ export const RETIRED_VERBS = Object.freeze([
     refusal: () =>
       '"descix microservice register-delegate" has been removed: there is no per-app microservice ' +
       'delegate key.\n' + MICROSERVICE_AUTH_MODEL },
+  // Lane B (the pending_migrations queue) is struck (CEO word Unkamon 1530eb6, daita-sam#4).
+  { id: 'airdrop', parent: 'program', name: 'airdrop', invocation: 'descix airdrop',
+    description: 'removed — see error text', refusal: (invocation) => AIRDROP_QUEUE_REFUSAL(invocation) },
+  { id: 'airdrop.execute-queue', parent: 'airdrop', name: 'execute-queue',
+    invocation: 'descix airdrop execute-queue', description: 'removed — see error text',
+    refusal: (invocation) => AIRDROP_QUEUE_REFUSAL(invocation) },
 ]);
 
 /** Implementations deleted with the KB sync surfaces. No exported symbol survives without a caller. */

package/lib/verb-invokes.generated.json

@@ -2,9 +2,6 @@
   "admin-login": [
     "admin_bootstrap_login"
   ],
-  "airdrop execute-queue": [
-    "airdrop_execute_queue"
-  ],
   "app delete": [
     "delete_app"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",

package/templates/agent-claude.md

@@ -1,3 +1,9 @@
+## DeSciX lane
+LANE: app          ENV: {{apiUrl}} (origin source: {{originSource}}; this repo's own .descix/workspace.json env.apiUrl and wallet — `descix whoami` must agree, never an environment variable)
+SDK: ONLY the published packages, as an external developer, invoked as `npx -y -p @descix/cli@{{cliVersion}} descix …` (an `npx` call without `-p @descix/cli` resolves the wrong package); never platform source
+HANDBOOK: 1 `descix tell-me-how "<question>"`  2 the docs shipped inside the published packages (@descix/cli agent-assets/, @descix/app-sdk README.md)  3 the app-developer runbook, live at https://descix.net/prod/daita-docs/site/app-sdk/app-developer-runbook.html
+PLATFORM WALL: when the handbook does not answer — stop, write the question with evidence (command, output, the CLI's origin banner line) and hand it to Sam to open a platform session. Never open platform source to answer it.
+
 # DeSciX App Development
 
 <!-- BOOTSTRAP MODE: This file was auto-generated by DeSciX.

package/templates/scaffolds/README.md

@@ -39,6 +39,10 @@ A complete Express microservice with:
 descix microservice init
 ```
 
+### Front page (`frontpage/`)
+
+The shared front-page template (`index.html`: head styles, `<nav class="nav">`, `<header class="hero" id="top">`, `<section class="sec" id="…">` blocks, `<footer>`). It is stamped by `descix app init` as `site/index.html`, ONLY if that file is absent, with `{{APP_ID}}` / `{{COMMUNITY_ID}}` filled by `lib/app-scaffold.js`. It is not a `site init` scaffold type. Each repo owns its own divergence after the stamp; no repo reads this template across repositories.
+
 ## Usage
 
 Run scaffold commands from your app directory (auto-detects context):

package/templates/scaffolds/frontpage/index.html

@@ -0,0 +1,124 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>{{APP_ID}} — a {{COMMUNITY_ID}} app on DeSciX</title>
+<meta name="description" content="{{APP_ID}}, an app of the {{COMMUNITY_ID}} community on DeSciX. Replace this description with what the app is for.">
+<style>
+:root{
+  --bg:#0b0f14; --bg2:#10161e; --panel:#151d27; --line:#233040; --line2:#2f3f52;
+  --ink:#e9eef3; --ink2:#b3bfcc; --mute:#7f8ea0;
+  --cyan:#5fcbe6; --cyan2:#3aa9c6; --cyan-ink:#06202a;
+  --serif:Georgia,"Times New Roman",serif;
+  --sans:"Helvetica Neue",Arial,sans-serif;
+  --mono:ui-monospace,SFMono-Regular,Menlo,monospace;
+  color-scheme:dark;
+}
+*{box-sizing:border-box}
+[hidden]{display:none!important}
+body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans);font-size:17px;line-height:1.55;-webkit-font-smoothing:antialiased}
+a{color:var(--cyan);text-decoration:none}
+a:hover{text-decoration:underline}
+a:focus-visible,button:focus-visible{outline:2px solid var(--cyan);outline-offset:2px}
+img{max-width:100%;display:block}
+h1,h2,h3{font-family:var(--serif);font-weight:500;line-height:1.08;margin:0;text-wrap:balance;letter-spacing:-.01em}
+h2{font-size:clamp(30px,4.2vw,46px)}
+h3{font-size:22px}
+p{margin:0}
+.wrap{max-width:1120px;margin:0 auto;padding-inline:20px}
+.eyebrow{font-family:var(--mono);font-size:12px;letter-spacing:.12em;text-transform:uppercase;color:var(--cyan)}
+.sec{padding-block:88px;border-top:1px solid var(--line)}
+.sec-head{display:grid;gap:14px;max-width:760px;margin-bottom:44px}
+.lede{font-size:19px;color:var(--ink2);max-width:62ch}
+.btn{display:inline-flex;align-items:center;gap:10px;padding:14px 22px;border-radius:4px;font-family:var(--sans);font-weight:600;font-size:16px;border:1px solid transparent;cursor:pointer;text-decoration:none!important}
+.btn-primary{background:var(--cyan);color:var(--cyan-ink)}
+.btn-primary:hover{background:#7ad6ec}
+.btn-ghost{background:transparent;color:var(--ink);border-color:var(--line2)}
+.btn-ghost:hover{border-color:var(--cyan);color:var(--cyan)}
+code{font-family:var(--mono);font-size:.92em;color:var(--cyan);background:rgba(95,203,230,.08);padding:2px 6px;border-radius:3px}
+
+/* nav */
+.nav{position:sticky;top:env(safe-area-inset-top,0px);z-index:20;background:rgba(11,15,20,.86);backdrop-filter:blur(10px);border-bottom:1px solid var(--line)}
+.nav .wrap{display:flex;align-items:center;justify-content:space-between;gap:20px;height:64px}
+.brand{display:flex;align-items:baseline;gap:10px;color:var(--ink);text-decoration:none!important}
+.brand b{font-family:var(--serif);font-weight:600;font-size:20px;letter-spacing:.01em}
+.brand span{font-family:var(--mono);font-size:11px;letter-spacing:.14em;text-transform:uppercase;color:var(--mute)}
+.navlinks{display:flex;gap:26px;font-size:15px}
+.navlinks a{color:var(--ink2)}
+.navlinks a:hover{color:var(--cyan);text-decoration:none}
+@media (max-width:820px){.navlinks{display:none}}
+
+/* hero */
+.hero{position:relative;overflow:hidden;border-bottom:1px solid var(--line)}
+.hero .wrap{position:relative;padding-block:96px 84px;display:grid;gap:26px}
+.hero h1{font-size:clamp(40px,6.4vw,78px);font-weight:300;max-width:12ch}
+.hero h1 em{font-style:italic;font-weight:500;color:var(--cyan)}
+.hero .lede{font-size:20px;max-width:56ch}
+.cta-row{display:flex;flex-wrap:wrap;gap:12px;margin-top:6px}
+
+/* skeleton cards */
+.cards{display:grid;grid-template-columns:repeat(3,1fr);gap:18px}
+.card{border:1px solid var(--line);border-radius:6px;background:var(--bg2);padding:24px 22px;display:grid;gap:10px;align-content:start}
+.card p{font-size:15px;color:var(--ink2)}
+@media (max-width:820px){.cards{grid-template-columns:1fr}}
+
+/* footer */
+footer{border-top:1px solid var(--line);padding-block:44px 60px;color:var(--mute);font-size:14px}
+footer .wrap{display:grid;gap:22px}
+footer .row{display:flex;flex-wrap:wrap;gap:8px 24px}
+footer .row a{color:var(--ink2)}
+footer .legal{max-width:80ch;font-size:13px}
+</style>
+</head>
+<body>
+
+<nav class="nav"><div class="wrap">
+  <a class="brand" href="#top"><b>{{APP_ID}}</b><span>{{COMMUNITY_ID}}</span></a>
+  <div class="navlinks">
+    <a href="#about">About</a><a href="#next">Next steps</a>
+  </div>
+</div></nav>
+
+<header class="hero" id="top">
+  <div class="wrap">
+    <p class="eyebrow">A {{COMMUNITY_ID}} app on DeSciX</p>
+    <h1>{{APP_ID}}, <em>in one sentence.</em></h1>
+    <p class="lede">This is the scaffold front page <code>descix app init</code> stamped for {{APP_ID}}. It is yours: replace this paragraph with what the app does and who it is for.</p>
+    <div class="cta-row">
+      <a class="btn btn-primary" href="#about">Learn more</a>
+      <a class="btn btn-ghost" href="#next">Make this page yours</a>
+    </div>
+  </div>
+</header>
+
+<section class="sec" id="about"><div class="wrap">
+  <div class="sec-head">
+    <p class="eyebrow">About</p>
+    <h2>What {{APP_ID}} is for.</h2>
+  </div>
+  <p class="lede">Placeholder copy from the scaffold. Say what {{APP_ID}} offers to the {{COMMUNITY_ID}} community, in the app's own words.</p>
+</div></section>
+
+<section class="sec" id="next"><div class="wrap">
+  <div class="sec-head">
+    <p class="eyebrow">Next steps</p>
+    <h2>Make this page yours.</h2>
+  </div>
+  <div class="cards">
+    <div class="card"><h3>Edit it</h3><p>This file is <code>site/index.html</code> in your repository. Nothing regenerates it; your edits are kept.</p></div>
+    <div class="card"><h3>Upload it</h3><p>Deploy the site set with <code>descix site upload</code>.</p></div>
+    <div class="card"><h3>Ask the handbook</h3><p>Run <code>descix tell-me-how</code> for every capability the CLI offers.</p></div>
+  </div>
+</div></section>
+
+<footer><div class="wrap">
+  <div class="brand"><b>{{APP_ID}}</b><span>{{COMMUNITY_ID}}</span></div>
+  <div class="row">
+    <a href="#about">About</a><a href="#next">Next steps</a>
+  </div>
+  <p class="legal">{{APP_ID}} is an app of the {{COMMUNITY_ID}} community on DeSciX. Replace this line with your own legal text.</p>
+</div></footer>
+
+</body>
+</html>

package/templates/scaffolds/microservice/package.json

@@ -11,7 +11,7 @@
     "gen-jwt-secret": "node -e 'console.log(require(\"crypto\").randomBytes(32).toString(\"hex\"))'"
   },
   "dependencies": {
-    "@descix/cloud-core": "^1.2.0",
+    "@descix/cloud-core": "^2.0.0",
     "@descix/platform-api": "^2.0.0",
     "@google-cloud/secret-manager": "^5.0.1",
     "@google-cloud/storage": "^7.7.0",

package/templates/scaffolds/microservice/scripts/register.js

@@ -23,6 +23,11 @@
  * (audience = CORE_API_URL). On Cloud Run that works with no setup. Under local developer ADC,
  * ID-token minting is unsupported without impersonation and this reports a named failure — it
  * does not fall back to anything.
+ *
+ * REGISTRATION TARGETS A RUNNING SERVICE. Before it registers, the bootstrap calls this service's
+ * own /api UNSIGNED and registers only if the mesh guard answers 401 (the mesh startup self-test).
+ * The origin it calls is derived from utils.PORT — the same config value app.js binds — so start
+ * the service (npm run dev) first, in the same checkout, then run this script.
  */
 
 import fs from 'fs';
@@ -51,12 +56,17 @@ async function register() {
         // Used ONLY to name the derived domain in a message. The platform, not this script,
         // owns the derivation.
         siteDomain: utils.SITE_DOMAIN,
+        // The running service's own listener, from the config owner app.js binds (utils.PORT).
+        meshSelfUrl: `http://127.0.0.1:${utils.PORT}`,
     });
 
     const result = await bootstrap.register();
 
     if (result.status !== 'ok') {
         console.error(`[Register] ${manifest.service.name}: registration ${result.status} — ${result.error || result.reason}`);
+        if (String(result.error || result.reason).includes('mesh self-test FAILED')) {
+            console.error('[Register] REMEDY: start the service (npm run dev), then re-run npm run register');
+        }
         process.exit(1);
     }
     console.log(`[Register] SUCCESS: ${manifest.service.name} registered via register_service`);

package/lib/commands/airdrop.js

@@ -1,266 +0,0 @@
-/**
- * Airdrop Commands
- *
- * Admin-facing CLI commands for WS-ADMIN-B1 airdrop migration operations.
- * Per CEO-D-MANUAL-TRIGGER-NO-CRON (2026-04-20), Cloud Scheduler cron was dropped
- * from Round B in favor of operator-invoked manual triggers via this CLI.
- *
- * Per CEO-D-B1-FIX-DESIGN-LOCK (2026-04-28), the CLI signature is:
- *   descix airdrop execute-queue --community <slug> [--dry-run | --signer-pk-file <path> --apply]
- *
- *   --community <slug>      REQUIRED for --apply mode (per-community batch scoping). Optional
- *                           in --dry-run mode (returns aggregate-across-communities preview).
- *   --dry-run               Read-only preview path. No PK prompt. No tx. No state mutation.
- *   --apply                 Live execution path. Requires --signer-pk-file or interactive
- *                           prompt-password. Mutually exclusive with --dry-run.
- *   --signer-pk-file <path> File containing the admin's per-invocation signer PK (0x + 64 hex,
- *                           one line). Inline --signer-pk and env vars REJECTED on security
- *                           grounds (process listing leak).
- *
- * Access: requires admin session (platform-admin group membership enforced server-side
- * in `airdrop_execute_queue` via `isPlatformAdmin(user)`). CLI-side, we require an
- * authenticated session (`requireAuth`). The server rejects non-admin users.
- *
- * Safety: the `BATCH_UPDATE_BALANCES_BROADCAST_ENABLED` flag gates the actual on-chain
- * broadcast in Powch. While that flag is false, `airdrop_execute_queue --apply` will assemble
- * batches but Powch returns `stopped_at_broadcast_boundary` — useful for verifying queue
- * assembly without spending MATIC.
- */
-
-import fs from 'fs';
-// "May I prompt?" has ONE OWNER. This site holds no TTY check of its own.
-import { requireInteractive } from '../interactive.js';
-import readline from 'readline';
-import chalk from 'chalk';
-import { DeSciXApiClient } from '../api-client.js';
-import { requireAuth } from '../auth-guard.js';
-
-const PK_REGEX = /^0x[a-fA-F0-9]{64}$/;
-
-/**
- * Read a signer PK from a file. Validates 0x + 64-hex format. Trims trailing whitespace
- * and a trailing newline only — does NOT mutate any other formatting.
- *
- * @param {string} path - Filesystem path to the PK file.
- * @returns {string} Validated PK in `0x` + 64 hex form.
- * @throws {Error} If the file is missing or contents are malformed.
- */
-export function readSignerPkFromFile(path) {
-    let raw;
-    try {
-        raw = fs.readFileSync(path, 'utf8');
-    } catch (e) {
-        throw new Error(`--signer-pk-file: cannot read ${path}: ${e.message}`);
-    }
-    const trimmed = raw.trim();
-    if (!PK_REGEX.test(trimmed)) {
-        // CRITICAL: do not echo the contents (even partial) into the error message.
-        throw new Error(`--signer-pk-file: contents do not match expected 0x + 64 hex format`);
-    }
-    return trimmed;
-}
-
-/**
- * Interactive password prompt (no echo). Reads a line of stdin with terminal echo disabled
- * so the typed PK never appears on screen. Validates 0x + 64-hex format.
- *
- * @returns {Promise<string>} Validated PK in `0x` + 64 hex form.
- */
-export async function promptSignerPkInteractive({ stdin = process.stdin, stdout = process.stdout } = {}) {
-    // Gate FIRST: a non-TTY here previously hung forever holding a secret prompt open. This site
-    // keeps its own readline because it must disable terminal echo so the PK is never displayed;
-    // the DECISION of whether prompting is allowed is still the owner's alone.
-    requireInteractive({
-        what: 'descix airdrop',
-        question: 'signer private key',
-        nonInteractiveForm: ['descix airdrop --signer-pk-file <path>   # reads the key from a file, never echoed']
-    });
-    return await new Promise((resolve, reject) => {
-        const rl = readline.createInterface({ input: stdin, output: stdout, terminal: true });
-        // Disable echo so the PK isn't visible while typing.
-        const originalWrite = stdout.write.bind(stdout);
-        stdout.write = (str, ...rest) => {
-            // Suppress only the echoed characters during the prompt; allow our prompt to render.
-            if (typeof str === 'string' && str.length === 1) return true;
-            return originalWrite(str, ...rest);
-        };
-        stdout.write('Enter signer PK (0x + 64 hex, will not be echoed): ');
-        rl.question('', (answer) => {
-            stdout.write = originalWrite;
-            stdout.write('\n');
-            rl.close();
-            const trimmed = (answer || '').trim();
-            if (!PK_REGEX.test(trimmed)) {
-                reject(new Error('prompt-password: input does not match expected 0x + 64 hex format'));
-                return;
-            }
-            resolve(trimmed);
-        });
-    });
-}
-
-/**
- * Execute the airdrop migration batch queue on the target environment.
- *
- * @param {Object} options
- * @param {string} [options.community] - Community slug for per-community batch scoping.
- *   REQUIRED for --apply mode; optional for --dry-run mode (omitted = aggregate preview).
- * @param {boolean} [options.dryRun] - If true, read-only preview path. Mutually exclusive with --apply.
- * @param {boolean} [options.apply] - If true, live execution path. Requires --signer-pk-file or
- *   interactive prompt-password. Mutually exclusive with --dry-run.
- * @param {string} [options.signerPkFile] - Path to file containing the admin's signer PK.
- * @param {number} [options.batchSize] - Optional cap on number of users processed this run.
- * @param {Object} [options.apiClient] - Optional injected API client (for tests).
- * @param {Function} [options.promptFn] - Optional injected interactive PK prompt (for tests).
- */
-export async function executeQueue(options) {
-    const apiClient = options.apiClient || new DeSciXApiClient();
-    await requireAuth(apiClient);
-
-    // Mode resolution: --dry-run and --apply are mutually exclusive. Default is dry-run when
-    // no --apply is provided (read-only is the safer default per CEO-D-B1-FIX-DESIGN-LOCK §4.A).
-    if (options.dryRun && options.apply) {
-        throw new Error('--dry-run and --apply are mutually exclusive (CEO-D-B1-FIX-DESIGN-LOCK Decision 1).');
-    }
-    const isDryRun = options.dryRun === true || (!options.apply && options.dryRun !== false);
-    const isApply = options.apply === true;
-
-    if (isApply && !options.community) {
-        throw new Error('--community <slug> is required for --apply mode (per-community batch scoping per CEO-D-B1-FIX-DESIGN-LOCK Decision 3).');
-    }
-
-    // Resolve signer PK for --apply mode: --signer-pk-file (default) or interactive prompt fallback.
-    let signerPkHex = null;
-    if (isApply) {
-        if (options.signerPkFile) {
-            signerPkHex = readSignerPkFromFile(options.signerPkFile);
-        } else {
-            const promptFn = options.promptFn || promptSignerPkInteractive;
-            signerPkHex = await promptFn();
-        }
-    }
-
-    const params = {};
-    if (options.community) params.community = options.community;
-    params.mode = isApply ? 'apply' : 'dry-run';
-    if (signerPkHex) params.signer_pk_hex = signerPkHex;
-    if (options.batchSize !== undefined && options.batchSize !== null) {
-        const bs = Number(options.batchSize);
-        if (!Number.isFinite(bs) || bs <= 0) {
-            throw new Error(`--batch-size must be a positive integer, got: ${options.batchSize}`);
-        }
-        params.batch_size = bs;
-    }
-    // Legacy boolean dry_run parameter (preserved for backwards-compat with existing scripts).
-    if (isDryRun && !options.community) {
-        params.dry_run = true;
-    }
-
-    const envLabel = process.env.DESCIX_API_URL || '(workspace default)';
-    const mode = isApply ? chalk.green('APPLY') : chalk.yellow('DRY-RUN');
-    console.log(chalk.cyan(`\nairdrop execute-queue [${mode}] target=${envLabel}`));
-    if (options.community) {
-        console.log(chalk.gray(`  community:        ${options.community}`));
-    }
-    if (params.batch_size) {
-        console.log(chalk.gray(`  batch_size:       ${params.batch_size}`));
-    }
-    if (signerPkHex) {
-        // Just confirm a PK is loaded; never echo any portion of it.
-        console.log(chalk.gray(`  signer_pk:        loaded (0x${signerPkHex.slice(2,6)}…${signerPkHex.slice(-4)})`));
-    }
-    console.log('');
-
-    let response;
-    try {
-        response = await apiClient.invoke('airdrop_execute_queue', params);
-    } catch (error) {
-        // Auth/permission errors surface as HTTP-level failures with readable messages.
-        // CRITICAL: ensure no echo of params.signer_pk_hex into any error message we print.
-        const safeMsg = String(error.message || '').replace(/0x[a-fA-F0-9]{64}/g, '0x[REDACTED]');
-        console.error(chalk.red(`\nairdrop_execute_queue failed: ${safeMsg}\n`));
-        if (/platform-admin|service-account/i.test(error.message)) {
-            console.error(chalk.gray('  This command requires a platform-admin account.'));
-            console.error(chalk.gray('  Verify your membership in the DESCIX_ADMIN_GROUP Google Group.\n'));
-        }
-        throw error;
-    } finally {
-        // Belt-and-suspenders: clear local PK var after the single use. We deliberately
-        // do NOT mutate `params.signer_pk_hex` here because the api-client/axios layer may
-        // still be serializing the body, and modern axios keeps no reference after the
-        // request resolves anyway. The local var nulling is the meaningful action.
-        signerPkHex = null;
-    }
-
-    const result = response?.message || response;
-    if (!result || typeof result !== 'object') {
-        throw new Error('airdrop_execute_queue returned no result');
-    }
-
-    if (isDryRun && result.mode === 'dry-run') {
-        // Render the §4.F dry-run summary table.
-        console.log(chalk.bold('Dry-Run Summary:'));
-        console.log(`  community:                ${chalk.cyan(result.community || '(all)')}`);
-        if (result.token_symbol) console.log(`  token_symbol:             ${result.token_symbol}`);
-        if (result.token_contract_address) console.log(`  token_contract:           ${result.token_contract_address}`);
-        if (result.abi_source) console.log(`  abi_source:               ${result.abi_source.doc_id} (v${result.abi_source.version || '?'})`);
-        console.log(`  transfers_total:          ${chalk.yellow(result.transfers_total)}`);
-        console.log(`  batches_total:            ${result.batches_total}`);
-        console.log(`  debit_total:              ${result.debit_total}`);
-        console.log(`  credit_total:             ${result.credit_total}`);
-        const nz = result.net_zero_assertion || {};
-        const nzLabel = nz.passes ? chalk.green('PASS') : chalk.red('FAIL');
-        console.log(`  net_zero_assertion:       ${nzLabel} (Σ=${nz.sum})`);
-        const pbc = result.pre_batch_checks || {};
-        console.log(`  pre_batch_checks:         ${pbc.passes ? chalk.green('PASS') : chalk.red('FAIL — --apply would refuse')}`);
-        for (const r of (pbc.refusals || [])) {
-            console.log(chalk.red(`    ${r.kind} ${r.wallet} (${r.community_id}) holds ${r.held}, needs ${r.required} base units — rows ${(r.pending_ids || []).join(', ')}`));
-        }
-        console.log(`  unique_source_wallets:    ${result.unique_source_wallets}`);
-        console.log(`  unique_master_wallets:    ${result.unique_master_wallets}`);
-        console.log(`  prospective_batch_id:     ${result.prospective_batch_id}`);
-        if (result.gas_estimate) {
-            console.log(`  gas_estimate:             ${result.gas_estimate.units || '?'} units @ ${result.gas_estimate.gas_price_gwei || '?'} gwei`);
-            if (result.gas_estimate.matic_cost_estimate) {
-                console.log(`  estimated_cost:           ~${result.gas_estimate.matic_cost_estimate} MATIC`);
-            }
-        }
-        console.log('');
-        console.log(chalk.gray('No PK supplied. No tx submitted. No DB rows mutated.'));
-        console.log(chalk.gray('Re-run with --apply --signer-pk-file <path> to commit.'));
-        console.log('');
-        return result;
-    }
-
-    console.log(chalk.bold('Result:'));
-    console.log(`  batches_executed: ${chalk.yellow(result.batches_executed ?? 0)}`);
-    console.log(`  total_users:      ${chalk.yellow(result.total_users ?? 0)}`);
-    console.log(`  dry_run:          ${result.dry_run ? chalk.yellow('true') : chalk.gray('false')}`);
-
-    const perCommunity = result.per_community || {};
-    const communityKeys = Object.keys(perCommunity);
-    if (communityKeys.length) {
-        console.log(`  per_community:`);
-        for (const cid of communityKeys) {
-            console.log(`    ${cid}: ${perCommunity[cid]}`);
-        }
-    } else {
-        console.log(`  per_community:    ${chalk.gray('{}')}`);
-    }
-
-    if (result.caller) {
-        const who = result.caller.operator_email || result.caller.service_account || '(unknown)';
-        console.log(chalk.gray(`  caller:           ${who}`));
-    }
-
-    console.log('');
-    if (isApply) {
-        console.log(chalk.gray('Apply complete. See on_chain_log for the trigger audit row.'));
-    } else {
-        console.log(chalk.gray('Dry-run complete. No broadcast attempted. No on_chain_log broadcast row written.'));
-    }
-    console.log('');
-    return result;
-}
-
-export default { executeQueue, readSignerPkFromFile, promptSignerPkInteractive };