insta 0.0.68 → 0.0.70

package/dist/config.js

@@ -1,13 +1,21 @@
 // CLI config: global (~/.insta/config.json: api url + tokens) and per-project (./.insta/project.json).
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { ensureGitignore } from './gitignore.js';
+import { die } from './util.js';
 import { DEFAULT_ENV, ENVS, envForApiUrl, envFromEnvVar, normalizeUrl } from './env.js';
 const GLOBAL_DIR = join(homedir(), '.insta');
 const GLOBAL_FILE = join(GLOBAL_DIR, 'config.json');
 const PROJECT_DIR = '.insta';
 const PROJECT_FILE = 'project.json';
+// Machine-local, gitignored: which project this machine linked here, and on which control plane.
+// It is NOT in project.json because that file is the team's committed binding — a URL chosen by one
+// machine (a staging switch, a local box, a transient INSTA_API_URL) would make every teammate's
+// CLI treat the shared link as foreign. It records the project id too, because project.json is
+// committed and this file is not: a pull or checkout can replace the project underneath it.
+const LINK_PLANE_FILE = 'link-plane.json';
 // The cloud API default. Uses the instacloud.com brand domain (matches the agents.instacloud.com
 // onboarding), NOT the legacy beta-api.insta.insforge.dev host — same backend, branded domain.
 // Only affects fresh installs: a persisted apiUrl (from a prior login) or INSTA_API_URL wins below.
@@ -85,11 +93,46 @@ export async function writeGlobal(c) {
     await mkdir(GLOBAL_DIR, { recursive: true });
     await writeFile(GLOBAL_FILE, JSON.stringify(c, null, 2));
 }
+/** The home directory is never a project root. `~/.insta/` is this CLI's GLOBAL config directory,
+ *  so a project.json there is not a project link: honouring one made every directory under the home
+ *  dir inherit it, and `insta project link` run anywhere below home silently overwrote it. */
+function isHomeDir(dir) {
+    return canonicalDir(dir) === canonicalDir(homedir());
+}
+/** A directory's filesystem identity rather than its spelling: the native real path, which resolves
+ *  symlinks and returns the on-disk case on case-insensitive filesystems (macOS, Windows). Comparing
+ *  spellings let a symlinked or differently-cased path to home through the home check. A path that
+ *  doesn't exist has no identity to resolve, so it falls back to its resolved spelling. */
+function canonicalDir(dir) {
+    try {
+        return realpathSync.native(resolve(dir));
+    }
+    catch {
+        return resolve(dir);
+    }
+}
+export const HOME_LINK_REFUSAL = 'refusing to link the home directory — ~/.insta is the insta CLI\'s global config, not a project. Run this inside a project directory';
+/** Where a link written from `cwd` lands: the existing project root, or `cwd` itself. */
+async function linkTarget(cwd) {
+    return (await findProjectRoot(cwd)) ?? resolve(cwd);
+}
+/** True when a link written from `cwd` would land in the home directory, which never holds one.
+ *  Lets a caller refuse BEFORE it does anything else with side effects. */
+export async function isHomeLinkTarget(cwd = process.cwd()) {
+    return isHomeDir(await linkTarget(cwd));
+}
 /** Git-style ancestor lookup: the nearest directory at-or-above `cwd` containing
- *  .insta/project.json — so "link once" works from any subdirectory of the project. */
+ *  .insta/project.json — so "link once" works from any subdirectory of the project. The search
+ *  stops at the home directory (see isHomeDir): neither home nor anything above it is a project
+ *  root for a directory inside home. */
 export async function findProjectRoot(cwd = process.cwd()) {
     let dir = resolve(cwd);
     for (;;) {
+        // Stop AT the home directory rather than skipping it: a link above home is not a project for
+        // home or anything below it, and climbing past home let `insta project link` run in ~ resolve
+        // to, and overwrite, an ancestor's link after the home-directory check had passed.
+        if (isHomeDir(dir))
+            return null;
         try {
             await readFile(join(dir, PROJECT_DIR, PROJECT_FILE), 'utf8');
             return dir;
@@ -101,32 +144,157 @@ export async function findProjectRoot(cwd = process.cwd()) {
         dir = parent;
     }
 }
-export async function readProject(cwd = process.cwd()) {
+/** The link that applies to `cwd`, and whether it was made against a DIFFERENT control plane. A
+ *  project id means nothing on another control plane (cloud, staging and every insta-oss box each
+ *  have their own), and the CLI used to reuse a link against whatever API it was pointed at. */
+export async function resolveProjectLink(cwd = process.cwd()) {
     // Linkless targeting (CI / one-offs / agents): INSTA_PROJECT_ID resolves the project with no
     // link file, and beats one when both exist — an explicit parameter outranks ambient state.
     if (process.env.INSTA_PROJECT_ID) {
         return {
-            projectId: process.env.INSTA_PROJECT_ID,
-            orgId: process.env.INSTA_ORG_ID ?? '',
-            branch: process.env.INSTA_BRANCH ?? 'main',
+            link: {
+                projectId: process.env.INSTA_PROJECT_ID,
+                orgId: process.env.INSTA_ORG_ID ?? '',
+                branch: process.env.INSTA_BRANCH ?? 'main',
+            },
         };
     }
     const root = await findProjectRoot(cwd);
     if (!root)
         return null;
+    let link;
+    try {
+        link = JSON.parse(await readFile(join(root, PROJECT_DIR, PROJECT_FILE), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    // No sidecar — a link from before this existed, or a teammate who just cloned — resolves as it
+    // always did: there is nothing to say which control plane it belongs to.
+    const record = await readLinkPlane(root);
+    if (record) {
+        const current = safeUrl((await readGlobal()).apiUrl);
+        const base = {
+            file: join(root, PROJECT_DIR, PROJECT_FILE), projectId: String(link.projectId),
+            linkedProjectId: record.projectId, linkedApiUrl: record.apiUrl, currentApiUrl: current,
+        };
+        // The record vouches for the project it was written for, and only that one. A record for
+        // another project says nothing about this one: trusting it would send this project to the
+        // control plane of the project it replaced, or refuse it for a reason that is not true. Fail
+        // closed with the real reason instead.
+        if (record.projectId !== base.projectId)
+            return { link, foreign: { reason: 'changed', ...base } };
+        if (normalizeUrl(record.apiUrl) !== normalizeUrl(current))
+            return { link, foreign: { reason: 'plane', ...base } };
+    }
+    return { link };
+}
+/** The link for this control plane, or null. A foreign link is NOT returned (it names a project
+ *  that does not exist here); callers that must act on a project use requireProject, which stops
+ *  with guidance instead of treating a foreign link as "unlinked". */
+export async function readProject(cwd = process.cwd()) {
+    const r = await resolveProjectLink(cwd);
+    if (!r)
+        return null;
+    if (r.foreign) {
+        if (!warnedForeignLinks.has(r.foreign.file)) {
+            warnedForeignLinks.add(r.foreign.file);
+            process.stderr.write(`note: ${foreignLinkMessage(r.foreign)}\n`);
+        }
+        return null;
+    }
+    return r.link;
+}
+const warnedForeignLinks = new Set();
+export function foreignLinkMessage(f) {
+    // Every field can come from a file (a committed project.json, a copied or hand-edited record),
+    // so all of it is stripped of control characters before it reaches a terminal.
+    const file = safeText(f.file);
+    const id = safeText(f.projectId);
+    const linked = safeUrl(f.linkedApiUrl);
+    const current = safeUrl(f.currentApiUrl);
+    if (f.reason === 'changed') {
+        return `${file} now links project ${id}, but this machine linked project ${safeText(f.linkedProjectId)} there, on ${linked}. `
+            + `The link changed since (a pull or checkout), so its control plane is unknown. `
+            + `Confirm it for ${current} with \`insta project link ${id}\`.`;
+    }
+    return `${file} links project ${id} on ${linked}, but the CLI is pointed at ${current}. `
+        + `Link this directory for ${current} with \`insta project link <id>\`, or point the CLI back at ${linked}.`;
+}
+async function readLinkPlane(root) {
     try {
-        return JSON.parse(await readFile(join(root, PROJECT_DIR, PROJECT_FILE), 'utf8'));
+        const raw = JSON.parse(await readFile(join(root, PROJECT_DIR, LINK_PLANE_FILE), 'utf8'));
+        // Validated, not cast: a malformed record is ignored rather than crashing every command. A
+        // record with no project id cannot say which project it vouches for, so it is ignored too.
+        if (!raw || typeof raw.projectId !== 'string' || !raw.projectId || typeof raw.apiUrl !== 'string' || !raw.apiUrl)
+            return null;
+        // Untrusted input (it may have been copied or edited), so sanitized before it is compared or printed.
+        return { projectId: raw.projectId, apiUrl: safeUrl(raw.apiUrl) };
     }
     catch {
         return null;
     }
 }
+/** Text safe to echo to a terminal: C0 and C1 control characters and DEL removed — ESC and the
+ *  single-byte C1 introducers (U+009B CSI among them) alike, so no escape sequence survives. */
+function safeText(text) {
+    return String(text).replace(/[\u0000-\u001f\u007f-\u009f]/g, '');
+}
+/** A control-plane URL safe to persist and to print: control characters removed, surrounding
+ *  whitespace trimmed, and any userinfo (INSTA_API_URL may carry credentials) removed.
+ *
+ *  Userinfo is removed with the same WHATWG parser fetch uses, not with a pattern. That parser is
+ *  lenient in ways a pattern keeps missing: it accepts leading whitespace, `\` for `/`, and a
+ *  missing `//` on special schemes, and each of those defeated an anchored pattern while fetch
+ *  would still have sent the credentials. A value the parser rejects is never requested, but it can
+ *  still be stored or printed, so everything up to its last `@` is dropped. The same goes for a
+ *  value that parses under any other scheme: `user:token@host` parses as scheme `user:` with the
+ *  credentials in its path, where clearing username and password removes nothing. */
+export function safeUrl(url) {
+    const text = safeText(url).trim();
+    const pastLastAt = () => (text.includes('@') ? text.slice(text.lastIndexOf('@') + 1) : text);
+    let parsed;
+    try {
+        parsed = new URL(text);
+    }
+    catch {
+        return pastLastAt();
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return pastLastAt();
+    if (!parsed.username && !parsed.password)
+        return text;
+    parsed.username = '';
+    parsed.password = '';
+    return parsed.href;
+}
 /** Writes to the existing project root when inside a linked project (branch switches from a
- *  subdirectory must not mint a nested link); a fresh `link` in an unlinked tree writes to cwd. */
+ *  subdirectory must not mint a nested link); a fresh `link` in an unlinked tree writes to cwd.
+ *  Records the control plane in the machine-local sidecar beside it. Never writes into the home
+ *  directory: `~/.insta/` is the global config, not a project. */
 export async function writeProject(c, cwd = process.cwd()) {
-    const target = (await findProjectRoot(cwd)) ?? cwd;
+    const target = await linkTarget(cwd);
+    if (isHomeDir(target))
+        die(HOME_LINK_REFUSAL);
+    const { apiUrl } = await readGlobal();
     await mkdir(join(target, PROJECT_DIR), { recursive: true });
     ensureGitignore(target, ['.insta/agent-session.json'], '# Local agent credentials');
+    ensureGitignore(target, [`.insta/${LINK_PLANE_FILE}`], '# Local: the control plane this machine linked against');
     await writeFile(join(target, PROJECT_DIR, PROJECT_FILE), JSON.stringify(c, null, 2));
+    // Owner-only, like agent-session.json: it can name a private self-hosted box. writeFile's mode
+    // applies only when it creates the file, so an existing record is chmod-ed too.
+    const record = join(target, PROJECT_DIR, LINK_PLANE_FILE);
+    await writeFile(record, JSON.stringify({ projectId: c.projectId, apiUrl: safeUrl(apiUrl) }, null, 2), { mode: 0o600 });
+    await chmod(record, 0o600);
+}
+/** Save a link that auto-resolution chose. Unlike an explicit `insta project link`, the command it
+ *  was resolved for must still run: in the home directory the choice is used for this command and
+ *  simply not remembered, rather than showing the picker and then failing the command. Returns
+ *  whether the link was saved. */
+export async function persistAutoLink(c, cwd = process.cwd()) {
+    if (await isHomeLinkTarget(cwd))
+        return false;
+    await writeProject(c, cwd);
+    return true;
 }
 //# sourceMappingURL=config.js.map

package/dist/deploy-archive.js

@@ -0,0 +1,145 @@
+import { handleApproval } from './util.js';
+export function archiveBuildSpec(hasDockerfile) {
+    return hasDockerfile ? { type: 'dockerfile' } : { type: 'nixpacks' };
+}
+const defaultUpload = async (url, body) => {
+    const res = await fetch(url, { method: 'PUT', body });
+    if (!res.ok)
+        throw new Error(`uploading the archive failed: HTTP ${res.status}`);
+};
+const statusPath = (projectId, sha256) => `/projects/${projectId}/build-uploads/${sha256}`;
+// Put an archive where the build gateway can fetch it, and answer what the deploy body needs.
+// Returns null when an approval is pending — the caller stops, the user approves and re-runs.
+//
+// The status read comes FIRST and that ordering is the whole recovery story: it is ungated, the
+// packer is deterministic and the upload id is derived from the content, so a re-run after an
+// approval finds the object already there, skips the gated mint it no longer needs, and submits a
+// byte-identical deploy body. That is why no resumable state is written to disk.
+export async function uploadArchive(api, projectId, packed, branch, opts, upload = defaultUpload) {
+    const ref = { archiveSha256: packed.sha256, build: archiveBuildSpec(packed.hasDockerfile) };
+    // The id the platform derives storage from is this digest, so an object that is already there is
+    // BYTE-IDENTICAL to the one in hand and the ref describes it truthfully. Keying on the tar digest
+    // instead bought cross-runtime dedup and paid for it with a lie: a Bun re-run of a Node upload
+    // matched the id, skipped the upload, and sent Bun's digest for Node's bytes, which the worker
+    // then rejected on every attempt until the object expired.
+    const first = await api.rawRequest('GET', statusPath(projectId, packed.sha256));
+    if (first.body?.state === 'valid')
+        return ref;
+    const minted = await api.rawRequest('POST', `/projects/${projectId}/build-uploads`, {
+        branch,
+        group: opts.group,
+        sha256: packed.sha256,
+        size: packed.archive.length,
+    });
+    if (handleApproval(minted, opts.json))
+        return null;
+    // The mint's whole product is this URL. An absent one would be PUT to as the string
+    // "undefined" and the failure would surface two steps later as a missing object.
+    const uploadUrl = minted.body?.uploadUrl;
+    if (typeof uploadUrl !== 'string' || !uploadUrl)
+        throw new Error('the platform minted an upload with no URL — re-run the deploy');
+    await upload(uploadUrl, packed.archive);
+    // Never let the deploy call be the thing that discovers a failed upload: its grant is spent in
+    // the governance preHandler, so a retry would need a NEW approval.
+    const after = await api.rawRequest('GET', statusPath(projectId, packed.sha256));
+    if (after.body?.state !== 'valid') {
+        throw new Error('the archive upload did not land — re-run the deploy to try again');
+    }
+    return ref;
+}
+// How often to ask, and how long to keep asking. The platform submits the build and returns; the
+// WAIT is ours, one short request at a time, because a deploy is answered synchronously and the
+// ALB in front of the platform cuts an idle request at 60s while an image build runs minutes.
+const POLL_MS = 3000;
+const DEPLOY_DEADLINE_MS = 30 * 60 * 1000;
+// One status read is a small GET; anything longer than this is a stalled endpoint, not a slow one.
+const POLL_REQUEST_TIMEOUT_MS = 20_000;
+const isAbort = (e) => e instanceof Error && (e.name === 'TimeoutError' || e.name === 'AbortError');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// ONE gated call, then a poll. The platform enqueues the build+deploy as an operation and answers
+// 202 at once, because a request has to finish inside the ALB's 60s and an image build runs
+// minutes; the wait is ours, one short GET at a time. Two gates on the lane with the mint, the
+// same as the flyctl lane. Returns null when an approval is pending.
+//
+// The operation is idempotent on (target, archive, build kind), so a re-run after approving finds
+// the one it already started rather than building again: same image, same result, no second
+// approval for a build that already happened.
+export async function deployArchive(api, projectId, ref, branch, opts, now = Date.now, wait = sleep, log = () => { }) {
+    const started = await api.rawRequest('POST', `/projects/${projectId}/archive-deploys`, {
+        branch,
+        group: opts.group,
+        archive: ref,
+        port: opts.port ? Number(opts.port) : undefined,
+        websocket: typeof opts.websocket === 'boolean' ? opts.websocket : undefined,
+        replaceSource: opts.replaceSource === true ? true : undefined,
+    });
+    // An approval is a 202 too, told apart by its status word; anything else here is our operation.
+    if (handleApproval(started, opts.json))
+        return null;
+    const operationId = started.body?.operationId;
+    if (typeof operationId !== 'string' || !operationId)
+        throw new Error('the platform accepted the deploy but returned no operation id — re-run the deploy');
+    if (started.body?.resumed === true)
+        log('resuming the deploy this archive already started');
+    const deadline = now() + DEPLOY_DEADLINE_MS;
+    const overdue = () => new Error(`the deploy did not finish within ${Math.round(DEPLOY_DEADLINE_MS / 60000)} minutes — check \`insta status\` or re-run`);
+    let last = '';
+    for (;;) {
+        // The deadline bounds the wall clock, not the number of answers: it is checked before each poll,
+        // and each poll is itself bounded by what remains, so a stalled endpoint cannot hold the CLI
+        // past it, and an answer that would arrive after it is not waited for.
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            throw overdue();
+        const res = await api.rawRequest('GET', `/projects/${projectId}/archive-deploys/${encodeURIComponent(operationId)}`, undefined, {
+            signal: AbortSignal.timeout(Math.min(remaining, POLL_REQUEST_TIMEOUT_MS)),
+        }).catch((e) => {
+            if (!isAbort(e))
+                throw e;
+            throw remaining <= POLL_REQUEST_TIMEOUT_MS ? overdue() : new Error(`the platform did not answer a status poll within ${POLL_REQUEST_TIMEOUT_MS / 1000}s — check \`insta status\` or re-run`);
+        });
+        const state = res.body?.state;
+        // A failed operation is an ANSWER, not a transport error: the poll worked, and the sentence
+        // it carries (usually the gateway's own, e.g. "no Dockerfile at ./api") is the one to show.
+        if (state === 'failed') {
+            // `||` would let a non-string through and the CLI would print "[object Object]" for the one
+            // sentence that explains the failure. Only a non-empty string is a message.
+            const error = res.body?.error;
+            return { failed: typeof error === 'string' && error ? error : 'the deploy failed' };
+        }
+        if (state === 'live') {
+            const image = res.body?.imageRef;
+            const url = res.body?.url;
+            if (typeof image !== 'string' || !image || typeof url !== 'string' || !url) {
+                throw new Error('the deploy finished but the platform returned no image or URL for it — check `insta status`');
+            }
+            // Optional strings, validated as such. String() would have coerced a protocol error into a
+            // plausible-looking branch or group and reported a target the deploy never named. An omitted
+            // field falls back to what was requested; a field of the wrong type is a broken contract.
+            const optionalString = (field, v) => {
+                if (v === undefined || v === null)
+                    return undefined;
+                if (typeof v !== 'string')
+                    throw new Error(`the platform returned a non-string ${field} for the deploy — upgrade with \`insta upgrade\``);
+                return v;
+            };
+            return {
+                image, url,
+                branch: optionalString('branch', res.body.branch) ?? branch,
+                group: optionalString('group', res.body.group) ?? opts.group ?? '',
+                machineId: optionalString('machineId', res.body.machineId),
+            };
+        }
+        // Only the platform's own in-flight states keep the loop going. An absent or unknown state
+        // would otherwise spend the whole deadline looking like a slow build.
+        if (state !== 'queued' && state !== 'building' && state !== 'deploying') {
+            throw new Error(`the platform reported an unknown deploy state (${JSON.stringify(state)}) — upgrade with \`insta upgrade\``);
+        }
+        if (state !== last) {
+            log(state === 'deploying' ? 'image built, deploying it' : `${state}…`);
+            last = state;
+        }
+        await wait(POLL_MS);
+    }
+}
+//# sourceMappingURL=deploy-archive.js.map

package/dist/env.js

@@ -2,12 +2,12 @@ export const ENVS = {
     prod: {
         api: 'https://api.instacloud.com',
         mcp: 'https://mcp.instacloud.com/mcp',
-        skills: 'InsForge/insta-skills',
+        skills: 'InsForge/instacloud-skills',
     },
     staging: {
         api: 'https://api.staging.instacloud.com',
         mcp: 'https://mcp.staging.instacloud.com/mcp',
-        skills: 'InsForge/insta-skills#devel',
+        skills: 'InsForge/instacloud-skills#devel',
     },
 };
 export const DEFAULT_ENV = 'prod';

package/dist/index.js

@@ -149,7 +149,7 @@ svc.command('add [type] [name]').description('Provision a service on demand (ass
     .option('--port <n>', 'compute only: port the image listens on (default 8080)')
     .option('--always-on', 'compute only: create as always-on — never scales to zero (the default for new compute services; all plans; billing is actual usage either way)')
     .option('--no-always-on', 'compute only: create as scale-to-zero — idle machines suspend and wake on the next request')
-    .option('--volume <gi>', 'compute only: attach a persistent /data volume of this many whole Gi (also attachable later: `insta compute volume <name> --size <gi>`; any plan may attach at the default 10 (the free cap, on every plan); larger sizes are paid and plan-capped). Volume services keep 1 machine and stop (cold wake) instead of suspend when idle')
+    .option('--volume <gi>', 'compute only: attach a persistent /data volume of this many whole Gi (also attachable later: `insta compute volume <name> --size <gi>`). Any plan may attach up to its own plan cap (10Gi free, 50Gi paid by default; the bare `insta compute volume <name>` read prints it as plan max); a size above the free cap is paid. Volume services keep 1 machine and stop (cold wake) instead of suspend when idle')
     .option('--json')
     .action(guard(async (type, name, o) => {
     const a = await resolveServiceArgs(type, name, serviceArgsDeps(o.json), o);
@@ -208,13 +208,13 @@ sec.command('sources').description('List service credential sources available fo
 sec.command('tree').description('Show secrets as project → branch → service → secrets').option('--json')
     .action(guard((o) => secretsCmd.secretsTree(o)));
 // ---- build (pre-push verification — local, offline, deploys nothing) ----
-program.command('build [dir]').description('Verify a source directory would build before deploying: detection plan + the Dockerfile (yours, or the one nixpacks would generate for the GitHub lane — `insta deploy <dir>` needs your own) + static checks. Local and offline — no login needed, nothing pushed. Exit 1 when the verdict is failed')
+program.command('build [dir]').description('Verify a source directory would build before deploying: detection plan + the Dockerfile (yours, or the one nixpacks would generate server-side) + static checks. Local and offline — no login needed, nothing pushed. Exit 1 when the verdict is failed')
     .option('--explain', 'include the Dockerfile content in the output')
     .option('--port <p>', 'port the app listens on (else the Dockerfile EXPOSE)')
     .option('--json')
     .action(guard((dir, o) => build(dir, o)));
 // ---- deploy ----
-program.command('deploy [dir]').description('Deploy a source directory (built remotely on Fly) or a prebuilt --image to a branch compute group')
+program.command('deploy [dir]').description('Deploy a source directory (built remotely; on insta-compute a Dockerfile is optional and nixpacks detects the runtime) or a prebuilt --image to a branch compute group')
     .option('--image <url>', 'prebuilt container image to deploy (instead of a source dir)').option('--branch <b>').option('--group <g>').option('--port <p>')
     .option('--websocket', 'run a WebSocket app (larger guest + connection-based concurrency)')
     .option('--replace-source', 'the service deploys from a connected GitHub repo: switch it to this image and remove the repo connection (admin); without it such a deploy is refused')
@@ -270,7 +270,7 @@ compute.command('watch-paths [service]').description("Show or change which paths
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => githubCmd.computeWatchPaths(service, o)));
 compute.command('disconnect-repo [service]').description('Disconnect the GitHub repository from a compute service. The service keeps running its current image; pushes no longer deploy it, and its build history stays')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => githubCmd.computeDisconnectRepo(service, o)));
-compute.command('volume [service]').description("Show, attach, grow, or delete a compute service's persistent /data volume. No flag: print size, mount path, and the plan cap (any plan). --size on a volumeless service ATTACHES one (any plan at the default 10Gi, the free cap; larger is paid and plan-capped; the disk mounts at /data on the next deploy); on a volume-bearing one it grows (paid plans; grow-only — a provisioned disk cannot shrink). --delete DESTROYS the disk and ALL its data immediately (no detach, no undo; billing stops now, and suspend fast-wake + scale-out return). Billing is actual data stored — the size is a cap, not a price")
+compute.command('volume [service]').description("Show, attach, grow, or delete a compute service's persistent /data volume. No flag: print size, mount path, and the plan cap (any plan). --size on a volumeless service ATTACHES one (any plan up to its own plan cap — 10Gi free, 50Gi paid by default — which is also what a disk with no size named is born at; a size above the free cap is paid; the disk mounts at /data on the next deploy); on a volume-bearing one it grows (paid plans; grow-only — a provisioned disk cannot shrink). --delete DESTROYS the disk and ALL its data immediately (no detach, no undo; billing stops now, and suspend fast-wake + scale-out return). Billing is actual data stored — the size is a cap, not a price")
     .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
     .option('--delete', 'destroy the volume and ALL its data (irreversible; download anything you need first)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeVolume(service, o)));