gipity 1.0.413 → 1.0.416

package/dist/api.js

@@ -211,6 +211,51 @@ export async function download(path, retried = false) {
     }
     return Buffer.from(await res.arrayBuffer());
 }
+/** Download raw bytes plus the response headers - for binary endpoints whose
+ *  metadata rides headers (e.g. `GET /projects/:guid/export`, where
+ *  `X-Gip-Skipped` and the Content-Disposition filename matter to the caller).
+ *  Non-2xx responses are parsed as standard JSON errors. */
+export async function downloadWithHeaders(path, retried = false) {
+    const url = `${baseUrl()}${path}`;
+    const res = await fetch(url, {
+        headers: { ...clientHeaders(), 'Authorization': `Bearer ${await bearerToken()}` },
+    });
+    if (await shouldRetryAfter401(res.status, retried)) {
+        return downloadWithHeaders(path, true);
+    }
+    if (!res.ok) {
+        const json = await res.json().catch(() => ({ error: { code: 'UNKNOWN', message: res.statusText } }));
+        const err = json.error || { code: 'UNKNOWN', message: res.statusText };
+        throw new ApiError(res.status, err.code, with401Hint(res.status, err.message), json.data);
+    }
+    return { buffer: Buffer.from(await res.arrayBuffer()), headers: res.headers };
+}
+/** POST raw bytes (e.g. a .gip bundle) and parse the JSON response, returning
+ *  the HTTP status alongside it so callers can tell a clean 201 from a 207
+ *  partial success. The timeout scales with the body size (same policy as the
+ *  presigned PUT path) so a large-but-progressing upload isn't cut off. */
+export async function postBinary(path, body, contentType = 'application/zip', retried = false) {
+    const url = `${baseUrl()}${path}`;
+    const headers = {
+        ...clientHeaders(),
+        'Authorization': `Bearer ${await bearerToken()}`,
+        'Content-Type': contentType,
+    };
+    const res = await fetchWithTimeout(url, {
+        method: 'POST',
+        headers,
+        body: new Uint8Array(body),
+    }, putTimeoutMs(body.length), `POST ${path}`);
+    if (await shouldRetryAfter401(res.status, retried)) {
+        return postBinary(path, body, contentType, true);
+    }
+    if (!res.ok) {
+        const json = await res.json().catch(() => ({ error: { code: 'UNKNOWN', message: res.statusText } }));
+        const err = json.error || { code: 'UNKNOWN', message: res.statusText };
+        throw new ApiError(res.status, err.code, with401Hint(res.status, err.message), json.data);
+    }
+    return { status: res.status, json: await res.json() };
+}
 /** Download a response as a Node.js Readable stream */
 export async function downloadStream(path, retried = false) {
     const { Readable } = await import('stream');

package/dist/client-context.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
-function cliVersion() {
+export function cliVersion() {
     try {
         const dir = dirname(fileURLToPath(import.meta.url));
         const pkg = JSON.parse(readFileSync(resolve(dir, '../package.json'), 'utf-8'));

package/dist/commands/chat.js

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import { get, post, put, del } from '../api.js';
-import { resolveProjectContext, saveConfig } from '../config.js';
+import { resolveProjectContext, requireConfig, saveConfig } from '../config.js';
 import { sync } from '../sync.js';
 import { error as clrError, muted, success } from '../colors.js';
 import { run, printList, printResult } from '../helpers/index.js';
@@ -98,13 +98,19 @@ chatCommand
     });
 }));
 chatCommand
-    .command('rename <guid> <title...>')
-    .description('Rename a chat')
+    .command('rename <title...>')
+    .description('Rename a chat (the current chat by default; changes the tab title only)')
+    .option('--guid <guid>', 'Chat guid to rename (defaults to the current chat)')
     .option('--json', 'Output as JSON')
-    .action((guid, titleParts, opts) => run('Rename', async () => {
+    .action((titleParts, opts) => run('Rename', async () => {
     const title = titleParts.join(' ');
+    const guid = opts.guid || requireConfig().conversationGuid;
+    if (!guid) {
+        console.error(clrError('No current chat. Start a chat first, or pass --guid <guid>.'));
+        process.exit(1);
+    }
     await put(`/conversations/${guid}`, { title });
-    printResult(success(`Renamed ${guid} → "${title}".`), opts, { guid, title });
+    printResult(success(`Renamed chat → "${title}".`), opts, { guid, title });
 }));
 chatCommand
     .command('archive <guid>')

package/dist/commands/github.js

@@ -0,0 +1,80 @@
+/**
+ * `gipity github <connect|status|repos|disconnect>` - manage the GitHub
+ * connection that powers `gipity load github:owner/repo`.
+ *
+ * Connect uses the GitHub App install flow: the URL is GitHub's own repo
+ * picker, so the user chooses exactly which repositories Gipity can read.
+ * Re-running connect doubles as the "grant more repositories" flow.
+ */
+import { Command } from 'commander';
+import { get, post } from '../api.js';
+import { brand, bold, muted } from '../colors.js';
+import { run, printList, printResult } from '../helpers/index.js';
+export const githubCommand = new Command('github')
+    .description('Connect GitHub for repo imports')
+    .addHelpText('after', '\nConnect once, then import any shared repo with `gipity load github:owner/repo`.');
+githubCommand
+    .command('connect')
+    .description('Connect your GitHub account - prints a link; GitHub lets you pick which repositories to share')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Connect', async () => {
+    const res = await get('/services/github/authorize');
+    if (opts.json) {
+        console.log(JSON.stringify({ url: res.url }));
+        return;
+    }
+    console.log('Open this link in your browser to connect GitHub - GitHub lets you pick which repositories to share:\n');
+    console.log(brand(res.url));
+    console.log(muted('\nWhen done, run `gipity github status` to confirm.'));
+    console.log(muted('Re-run `gipity github connect` any time to grant more repositories.'));
+}));
+githubCommand
+    .command('status', { isDefault: true })
+    .description('Show whether GitHub is connected')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Status', async () => {
+    const res = await get('/services/github/status');
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    const s = res.data;
+    if (!s.connected) {
+        console.log('GitHub: not connected. Run `gipity github connect` to set it up.');
+        return;
+    }
+    console.log(`GitHub: ${bold('connected')}`);
+    if (s.email)
+        console.log(`  Account:   ${s.email}`);
+    if (s.connectedAt)
+        console.log(`  Connected: ${new Date(s.connectedAt).toLocaleDateString()}`);
+    console.log(muted('\nList reachable repositories with `gipity github repos`.'));
+    console.log(muted('Import one with `gipity load github:owner/repo`.'));
+}));
+githubCommand
+    .command('repos')
+    .description('List the repositories your GitHub connection can reach')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Repos', async () => {
+    const res = await get('/services/github/repos').catch((err) => {
+        if (err?.code === 'NOT_CONNECTED') {
+            throw new Error('GitHub is not connected - run `gipity github connect` first.');
+        }
+        throw err;
+    });
+    const width = res.data.length ? Math.max(...res.data.map(r => r.full_name.length)) : 0;
+    printList(res.data, opts, 'No repositories shared yet - run `gipity github connect` to grant some.', r => {
+        const vis = r.private ? 'private' : 'public ';
+        const desc = r.description ? `  ${muted(r.description)}` : '';
+        return `${r.full_name.padEnd(width)}  ${muted(vis)}  ${r.default_branch}${desc}`;
+    });
+}));
+githubCommand
+    .command('disconnect')
+    .description('Disconnect GitHub (imports via github: sources will stop working)')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Disconnect', async () => {
+    await post('/services/github/disconnect');
+    printResult('GitHub disconnected.', opts, { disconnected: true });
+}));
+//# sourceMappingURL=github.js.map

package/dist/commands/load.js

@@ -0,0 +1,221 @@
+/**
+ * `gipity load <source>` - create a brand-new project from a .gip bundle or
+ * a GitHub repository.
+ *
+ * The counterpart of `gipity save`. Load ALWAYS creates a new project (the
+ * server retries slug collisions); it never merges into an existing one. Use
+ * `--inspect` to peek inside a source - metadata, contents, deploy phases,
+ * and each function's permission surface - without creating anything.
+ *
+ * Sources:
+ * - a local .gip file (from `gipity save`) - uploaded as raw zip bytes
+ * - `github:owner/repo[/sub/path][@ref]` or a github.com URL - resolved
+ *   server-side through the user's GitHub connection (`gipity github connect`);
+ *   the CLI sends a JSON `{source}` body, no repo bytes travel through the
+ *   client. Both transports feed the same import pipeline and response shapes.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Command } from 'commander';
+import { get, post, postBinary, getAccountSlug } from '../api.js';
+import { success, muted, warning, bold, info, brand } from '../colors.js';
+import { run } from '../helpers/index.js';
+import { withSpinner } from '../progress.js';
+import { formatBytes } from '../adopt-cwd.js';
+import { getProjectsRoot } from '../relay/paths.js';
+import { finalizeLocalProject } from '../project-setup.js';
+/** Server transport cap for a .gip upload - checked locally first so a too-big
+ *  bundle fails in milliseconds instead of after a full upload. */
+const MAX_BUNDLE_BYTES = 200 * 1024 * 1024;
+/** A source the server resolves via the user's GitHub connection: the
+ *  `github:owner/repo[/sub/path][@ref]` shorthand or a github.com URL. */
+function isGithubSource(source) {
+    return /^github:/i.test(source) || /^https?:\/\/(www\.)?github\.com\//i.test(source);
+}
+/** Append the recovery path when a GitHub-source call fails because the repo
+ *  isn't reachable through the user's connection (not connected, or connected
+ *  but this repo wasn't granted). The server's message names the problem; the
+ *  hint names the fix. Re-throws always. */
+function rethrowWithConnectHint(err) {
+    const e = err;
+    const msg = e?.message ?? '';
+    if (e?.code === 'NOT_CONNECTED' || /not covered by your GitHub connection|connect github/i.test(msg)) {
+        e.message = `${msg}\nRun \`gipity github connect\` to connect GitHub - re-run it any time to grant more repositories.`;
+    }
+    throw err;
+}
+function readBundle(source) {
+    const resolved = path.resolve(source.startsWith('~') ? os.homedir() + source.slice(1) : source);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Bundle not found: ${resolved}`);
+    }
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        throw new Error(`${resolved} is a directory - pass a .gip file (create one with \`gipity save\`) or a github: source.`);
+    }
+    if (stat.size > MAX_BUNDLE_BYTES) {
+        throw new Error(`Bundle is ${formatBytes(stat.size)} - over the ${formatBytes(MAX_BUNDLE_BYTES)} upload cap. Move large assets to Gipity Storage and re-save.`);
+    }
+    return { resolved, buffer: fs.readFileSync(resolved) };
+}
+/** Manifest permission surface, one line per function - what an importing user
+ *  needs to see before trusting a bundle. */
+function printManifest(m) {
+    if (!m.found) {
+        console.log(muted('No gipity.yaml in the source - static app (files deploy only).'));
+        return;
+    }
+    if (!m.valid) {
+        console.log(warning(`gipity.yaml is present but invalid: ${m.error ?? 'unparseable'}`));
+        return;
+    }
+    console.log(`Deploy phases: ${m.phases.map(p => `${p.name} (${p.type})`).join(', ') || 'none'}`);
+    console.log(`Database:      ${m.hasDatabase ? 'yes' : 'no'}`);
+    if (m.functions.length) {
+        console.log('');
+        console.log(bold('Functions and permissions:'));
+        const width = Math.max(...m.functions.map(f => f.name.length));
+        for (const f of m.functions) {
+            const parts = [`auth=${f.auth ?? 'public'}`];
+            if (f.tables?.length)
+                parts.push(`tables=${f.tables.join(',')}`);
+            if (f.fetch_domains?.length)
+                parts.push(`fetch=${f.fetch_domains.join(',')}`);
+            if (f.services?.length)
+                parts.push(`services=${f.services.join(',')}`);
+            console.log(`  ${f.name.padEnd(width)}  ${muted(parts.join('  '))}`);
+        }
+    }
+}
+function printInspect(d, source) {
+    if (d.meta) {
+        console.log(bold(d.meta.name));
+        if (d.meta.description)
+            console.log(muted(d.meta.description));
+        console.log(`Source:    project ${d.meta.source_project}, exported ${d.meta.exported_at}`);
+    }
+    else {
+        console.log(bold(isGithubSource(source) ? source : path.basename(source)));
+        console.log(muted('No Gipity bundle metadata - imports as a plain file tree.'));
+    }
+    console.log(`Contents:  ${d.fileCount} file(s), ${formatBytes(d.totalBytes)}`);
+    console.log(`Top level: ${d.topLevel.join(', ') || '(empty)'}`);
+    console.log('');
+    printManifest(d.manifest);
+    console.log('');
+    console.log(muted('Load it with `gipity load ' + source + '` - always creates a NEW project.'));
+}
+export const loadCommand = new Command('load')
+    .description('Create a new app from a .gip bundle or a GitHub repo')
+    .argument('<source>', 'A .gip file (from `gipity save`), github:owner/repo[/sub/path][@ref], or a github.com URL')
+    .option('--name <name>', 'Name for the new project (default: the source\'s saved name)')
+    .option('--inspect', 'Peek inside the source - contents, deploy phases, function permissions - without creating anything')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', '\nLoad always creates a NEW project - it never merges into an existing one.'
+    + '\nGitHub sources need a one-time `gipity github connect` (re-run it to grant more repos).')
+    .action((source, opts) => run('Load', async () => {
+    const github = isGithubSource(source);
+    if (!github && /^https?:\/\//i.test(source)) {
+        throw new Error('Only GitHub URLs are supported for now - pass github:owner/repo, a github.com URL, or a local .gip file.');
+    }
+    // Local .gip bundles upload raw zip bytes; GitHub sources send a tiny JSON
+    // body and the server pulls the tree through the user's connection.
+    let sourceLabel;
+    let doInspect;
+    let doImport;
+    if (github) {
+        sourceLabel = source;
+        doInspect = () => post('/projects/inspect', { source }).catch(rethrowWithConnectHint);
+        doImport = async () => {
+            const body = { source };
+            if (opts.name)
+                body.name = opts.name;
+            const res = await post('/projects/import', body).catch(rethrowWithConnectHint);
+            // The JSON helper hides the 201-vs-207 status; `failed` carries the
+            // same signal (the server only sets it on a partial write).
+            return { data: res.data, partial: !!res.data.failed?.length };
+        };
+    }
+    else {
+        const { resolved, buffer } = readBundle(source);
+        sourceLabel = path.basename(resolved);
+        doInspect = async () => (await postBinary('/projects/inspect', buffer)).json;
+        doImport = async () => {
+            const qs = new URLSearchParams();
+            if (opts.name)
+                qs.set('name', opts.name);
+            const { status, json } = await postBinary(`/projects/import${qs.size ? `?${qs}` : ''}`, buffer);
+            return { data: json.data, partial: status === 207 };
+        };
+    }
+    if (opts.inspect) {
+        const res = opts.json
+            ? await doInspect()
+            : await withSpinner('Inspecting…', doInspect, { done: null });
+        if (opts.json) {
+            console.log(JSON.stringify(res.data));
+            return;
+        }
+        printInspect(res.data, source);
+        return;
+    }
+    const { data, partial } = opts.json
+        ? await doImport()
+        : await withSpinner('Importing…', doImport, { done: null });
+    const project = data.project;
+    // Materialize a local dir and link it, exactly like `gipity project create`:
+    // `.gipity.json` is written directly inside the new dir, then a soft sync
+    // pulls the imported files down.
+    const dir = path.join(getProjectsRoot(), project.slug);
+    fs.mkdirSync(dir, { recursive: true });
+    const accountSlug = await getAccountSlug();
+    // Resolve the first assigned agent (if any) - not fatal if missing.
+    let agentGuid = '';
+    try {
+        const agents = await get(`/projects/${project.short_guid}/agents`);
+        if (agents.data.length > 0)
+            agentGuid = agents.data[0].short_guid;
+    }
+    catch {
+        // offline or no agents - non-fatal
+    }
+    const { applied } = await finalizeLocalProject({
+        dir,
+        projectGuid: project.short_guid,
+        projectSlug: project.slug,
+        projectName: project.name,
+        accountSlug,
+        agentGuid,
+        sync: 'soft',
+        interactive: false,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify({
+            created: project.slug,
+            name: project.name,
+            guid: project.short_guid,
+            dir,
+            written: data.written,
+            failed: data.failed,
+            partial,
+            applied,
+        }));
+        return;
+    }
+    console.log(success(`Created "${project.name}" (${project.slug}) from ${sourceLabel}`));
+    console.log(`Wrote ${data.written} file(s) to the new project.`);
+    console.log(`Initialized ${info(dir)}`);
+    if (applied > 0)
+        console.log(`Pulled ${applied} file(s) to local.`);
+    if (partial || data.failed?.length) {
+        console.log('');
+        console.warn(warning(`Partial import - ${data.failed?.length ?? 0} file(s) could not be written:`));
+        for (const f of data.failed ?? [])
+            console.warn(warning(`  ! ${f.path}: ${f.error}`));
+        console.warn(warning('The project was still created and linked; the files above are missing from it.'));
+    }
+    console.log('');
+    console.log(`${muted('Next:')} cd ${dir} && ${brand('gipity deploy dev')}`);
+}));
+//# sourceMappingURL=load.js.map

package/dist/commands/project.js

@@ -36,6 +36,31 @@ export const projectCommand = new Command('project')
         return `${p.slug}${active}${def}`;
     });
 }));
+projectCommand
+    .command('rename <name...>')
+    .description('Rename the current project (display name only; slug and URLs unchanged)')
+    .option('--project <target>', 'Project name, slug, or guid to rename (defaults to the current project)')
+    .option('--json', 'Output as JSON')
+    .action((nameParts, opts) => run('Rename', async () => {
+    const name = nameParts.join(' ');
+    const config = requireConfig();
+    let guid = config.projectGuid;
+    if (opts.project) {
+        const res = await get('/projects?limit=1000');
+        const match = res.data.find(p => p.slug === opts.project || p.name === opts.project || p.short_guid === opts.project);
+        if (!match) {
+            console.error(clrError(`Project "${opts.project}" not found.`));
+            process.exit(1);
+        }
+        guid = match.short_guid;
+    }
+    if (!guid) {
+        console.error(clrError('No current project. Link one first, or pass --project <name>.'));
+        process.exit(1);
+    }
+    await put(`/projects/${guid}`, { name });
+    printResult(success(`Renamed project → "${name}".`), opts, { guid, name });
+}));
 projectCommand
     .command('create <name>')
     .description('Create a project')
@@ -132,20 +157,6 @@ projectCommand
     await del(`/projects/${match.short_guid}`);
     printResult(`Deleted "${match.name}".`, opts, { deleted: match.slug });
 }));
-projectCommand
-    .command('rename <name> <new-name>')
-    .description('Rename a project')
-    .option('--json', 'Output as JSON')
-    .action((name, newName, opts) => run('Rename', async () => {
-    const res = await get('/projects?limit=1000');
-    const match = res.data.find(p => p.slug === name || p.name === name || p.short_guid === name);
-    if (!match) {
-        console.error(clrError(`Project "${name}" not found.`));
-        process.exit(1);
-    }
-    await put(`/projects/${match.short_guid}`, { name: newName });
-    printResult(`Renamed "${match.name}" → "${newName}".`, opts, { renamed: match.slug, from: match.name, to: newName });
-}));
 projectCommand
     .command('info')
     .description('Show current project')

package/dist/commands/records.js

@@ -9,7 +9,7 @@ import { confirm } from '../utils.js';
 // Records API is the only records surface that exists server-side; there is no
 // /projects/<guid>/records mirror.)
 export const recordsCommand = new Command('records')
-    .description('Manage records');
+    .description('Manage records-kit data (registry-driven CRUD)');
 recordsCommand
     .command('list')
     .description('List record tables')

package/dist/commands/relay.js

@@ -225,6 +225,35 @@ relayCommand
     state.setPaused(false);
     console.log(success('Resumed.'));
 });
+// ─── gipity relay diagnostics [on|off] ─────────────────────────────────
+relayCommand
+    .command('diagnostics [state]')
+    .description('View or set sharing of anonymous host/version diagnostics (on|off)')
+    .action((arg) => {
+    if (arg === undefined) {
+        const stored = state.getDiagnosticsConsent();
+        const effective = state.diagnosticsConsented();
+        const label = stored === undefined ? 'on (default, not yet chosen)' : stored ? 'on' : 'off';
+        console.log(`Diagnostics sharing: ${effective ? success(label) : muted(label)}`);
+        if (effective !== (stored !== false)) {
+            console.log(muted('  (overridden off by GIPITY_NO_DIAGNOSTICS / DO_NOT_TRACK)'));
+        }
+        console.log(muted('  Non-PII only: CPU/GPU/memory/disk specs, OS + tool versions. No file paths, hostname, or username.'));
+        console.log(muted('  Set with `gipity relay diagnostics on` / `gipity relay diagnostics off`.'));
+        return;
+    }
+    const on = /^(on|true|yes|1|enable)$/i.test(arg);
+    const off = /^(off|false|no|0|disable)$/i.test(arg);
+    if (!on && !off) {
+        console.log(clrError("Expected 'on' or 'off'."));
+        process.exitCode = 1;
+        return;
+    }
+    state.setDiagnosticsConsent(on);
+    console.log(on
+        ? `${success('Diagnostics sharing on.')} ${muted('Reported on the next daily heartbeat.')}`
+        : `${success('Diagnostics sharing off.')} ${muted('No host/version data will be sent.')}`);
+});
 // ─── gipity relay rename <name> ────────────────────────────────────────
 relayCommand
     .command('rename <new-name>')

package/dist/commands/save.js

@@ -0,0 +1,90 @@
+/**
+ * `gipity save [output]` - export the linked project as a portable .gip bundle.
+ *
+ * A .gip is a zip of the project's file tree plus a reserved
+ * `_gip/manifest.json` metadata entry. It pairs with `gipity load`, which
+ * creates a brand-new project from a bundle. Code-only: secrets, custom
+ * domains, chats, and database rows are never in a .gip.
+ */
+import fs from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+import { Command } from 'commander';
+import { downloadWithHeaders } from '../api.js';
+import { requireConfig } from '../config.js';
+import { success, muted, warning } from '../colors.js';
+import { run } from '../helpers/index.js';
+import { withSpinner } from '../progress.js';
+import { formatBytes } from '../adopt-cwd.js';
+/** Count archive entries by reading the zip end-of-central-directory record -
+ *  cheap (no inflation, no dependency) and good enough for a summary line.
+ *  Returns null when the record can't be found or the count is zip64-saturated,
+ *  in which case the line is simply omitted. */
+export function zipEntryCount(buf) {
+    const EOCD_SIG = 0x06054b50;
+    const MIN_EOCD = 22; // fixed EOCD size with an empty comment
+    if (buf.length < MIN_EOCD)
+        return null;
+    // The EOCD sits at the end, preceded only by an optional comment (<= 64KB).
+    const floor = Math.max(0, buf.length - MIN_EOCD - 0xffff);
+    for (let i = buf.length - MIN_EOCD; i >= floor; i--) {
+        if (buf.readUInt32LE(i) === EOCD_SIG) {
+            const n = buf.readUInt16LE(i + 10); // total central-directory records
+            return n === 0xffff ? null : n;
+        }
+    }
+    return null;
+}
+/** Pull the server's suggested filename out of Content-Disposition
+ *  (`attachment; filename="<slug>.gip"`). The server slug is fresher than the
+ *  locally cached one if the project was renamed. */
+function dispositionFilename(headers) {
+    const m = /filename="([^"]+)"/.exec(headers.get('content-disposition') ?? '');
+    return m ? m[1] : null;
+}
+export const saveCommand = new Command('save')
+    .description('Save this app as a portable .gip bundle')
+    .argument('[output]', 'Output .gip path, or a directory to write <slug>.gip into (default: ./<slug>.gip)')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', '\nRestore anywhere with `gipity load <file>.gip` - it always creates a NEW project.')
+    .action((output, opts) => run('Save', async () => {
+    const config = requireConfig();
+    const doExport = () => downloadWithHeaders(`/projects/${config.projectGuid}/export`);
+    const { buffer, headers } = opts.json
+        ? await doExport()
+        : await withSpinner('Exporting…', doExport, { done: null });
+    const filename = dispositionFilename(headers) ?? `${config.projectSlug}.gip`;
+    let dest = path.resolve(output ?? filename);
+    if (output && fs.existsSync(dest) && fs.statSync(dest).isDirectory()) {
+        dest = path.join(dest, filename);
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, buffer);
+    const sha256 = createHash('sha256').update(buffer).digest('hex');
+    const skipped = Number(headers.get('x-gip-skipped') ?? 0);
+    const entries = zipEntryCount(buffer);
+    if (opts.json) {
+        console.log(JSON.stringify({
+            path: dest,
+            bytes: buffer.length,
+            sha256,
+            ...(entries !== null ? { entries } : {}),
+            skipped,
+        }));
+        return;
+    }
+    console.log(success(`Saved ${path.basename(dest)}`));
+    console.log(`  Path:     ${dest}`);
+    console.log(`  Size:     ${formatBytes(buffer.length)}`);
+    if (entries !== null)
+        console.log(`  Entries:  ${entries} (including the bundle manifest)`);
+    console.log(`  SHA-256:  ${sha256}`);
+    if (skipped > 0) {
+        console.log('');
+        console.warn(warning(`${skipped} file(s) were skipped (unreadable or over 100 MB) - this bundle is partial.`));
+        console.warn(warning('Large assets belong in Gipity Storage, not in a code bundle.'));
+    }
+    console.log('');
+    console.log(muted('Restore anywhere with `gipity load ' + path.basename(dest) + '` (creates a new project).'));
+}));
+//# sourceMappingURL=save.js.map

package/dist/commands/service.js

@@ -20,7 +20,7 @@ const SERVICES = [
     { name: 'location/geocode', method: 'POST', desc: 'Reverse geocode ({ lat, lon })' },
 ];
 export const serviceCommand = new Command('service')
-    .description('Call an app service')
+    .description('Call an app service (llm, tts, image, transcribe, ...)')
     .addHelpText('after', '\nCall a Gipity app service: LLM, image, music, TTS, and more.');
 serviceCommand
     .command('list')

package/dist/commands/setup.js

@@ -20,7 +20,7 @@ export const setupCommand = new Command('setup')
     .description('Set up this computer as a relay (no project, no launch)')
     .action(async () => {
     try {
-        console.log('');
+        // Leading blank comes from the central output frame (installOutputFrame).
         console.log(`  ${bold('Gipity setup')} ${muted('- get this computer ready as a relay')}`);
         console.log('');
         // ── Step 1: Auth ──────────────────────────────────────────────────

package/dist/commands/skill.js

@@ -17,7 +17,7 @@ function readInstalledKitReadme(name) {
     return existsSync(readme) ? readFileSync(readme, 'utf-8') : null;
 }
 export const skillCommand = new Command('skill')
-    .description('Read platform docs');
+    .description('Task docs - read the matching skill before building');
 skillCommand
     .command('list')
     .description('List skills')