gipity 1.0.414 → 1.0.416

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/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/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')

package/dist/commands/text.js

@@ -140,7 +140,7 @@ const analyzeCommand = new Command('analyze')
 // Parent namespace. One capability today (analyze); namespaced for a lean
 // top-level surface and room for future text operations.
 export const textCommand = new Command('text')
-    .description('Analyze text')
+    .description('Deterministic text analysis (counts, substrings) - no LLM needed')
     .addHelpText('after', `\nDeterministic char/word counts, frequency, and occurrences (${brand('text analyze')}). Local, no network.`)
     .addCommand(analyzeCommand);
 textCommand.action(() => {

package/dist/index.js

@@ -127,25 +127,55 @@ const program = new Command();
 // global value-option precedes it (e.g. `gipity --api-base X workflow create
 // --from Y`). enablePositionalOptions draws the boundary at the first command.
 program.enablePositionalOptions();
-// ── Command groups (logical ordering within each) ──────────────────────
-const commonGroup = [skillCommand, projectCommand, addCommand, removeCommand, saveCommand, loadCommand, deployCommand];
-const connectGroup = [claudeCommand, setupCommand, relayCommand];
-const projectGroup = [domainCommand, statusCommand, initCommand];
-const filesGroup = [fileCommand, storageCommand, syncCommand, pushCommand, uploadCommand];
-const appBuildingGroup = [testCommand, fnCommand, serviceCommand, secretsCommand, notifyCommand, paymentsCommand, githubCommand, jobCommand, dbCommand, logsCommand, workflowCommand, realtimeCommand, rbacCommand, auditCommand, recordsCommand];
-const utilitiesGroup = [pageCommand, sandboxCommand, generateCommand, emailCommand, gmailCommand, locationCommand, textCommand];
-const agentGroup = [chatCommand, memoryCommand, agentCommand, approvalCommand, bugCommand];
-const setupGroup = [loginCommand, logoutCommand, tokenCommand, creditsCommand, doctorCommand, updateCommand, uninstallCommand];
+// ── Command groups (lifecycle order; logical ordering within each) ─────
+// Section names deliberately match the vocabulary of the generated CLAUDE.md
+// primer and the skill docs ("build loop: add → edit → deploy → page
+// inspect"), so an agent's first `--help` reads in the same terms as the rest
+// of its context. Humans get the same win: sections follow the order you
+// actually use them - orient, build, wire the backend, then everything else.
+const startGroup = [statusCommand, initCommand, skillCommand, projectCommand];
+const buildGroup = [addCommand, removeCommand, saveCommand, loadCommand, deployCommand, pageCommand, testCommand];
+const backendGroup = [dbCommand, fnCommand, secretsCommand, logsCommand, jobCommand, workflowCommand];
+const servicesGroup = [serviceCommand, generateCommand, notifyCommand, paymentsCommand, realtimeCommand, recordsCommand, rbacCommand, auditCommand, domainCommand, tokenCommand];
+const filesGroup = [syncCommand, fileCommand, pushCommand, uploadCommand, storageCommand];
+const gipGroup = [chatCommand, memoryCommand, agentCommand, approvalCommand, gmailCommand];
+const utilitiesGroup = [sandboxCommand, emailCommand, locationCommand, textCommand, bugCommand];
+const connectGroup = [loginCommand, logoutCommand, claudeCommand, setupCommand, relayCommand, githubCommand, creditsCommand, doctorCommand, updateCommand, uninstallCommand];
 const HELP_SECTIONS = [
-    { title: 'Common', cmds: commonGroup },
-    { title: 'Connect', cmds: connectGroup },
-    { title: 'Project', cmds: projectGroup },
+    { title: 'Start here', cmds: startGroup },
+    { title: 'App build & ship', cmds: buildGroup },
+    { title: 'App backend', cmds: backendGroup },
+    { title: 'App services', cmds: servicesGroup },
     { title: 'Files', cmds: filesGroup },
-    { title: 'App building', cmds: appBuildingGroup },
+    { title: 'Gip (cloud agent)', cmds: gipGroup },
     { title: 'Utilities', cmds: utilitiesGroup },
-    { title: 'Agent', cmds: agentGroup },
-    { title: 'Setup', cmds: setupGroup },
+    { title: 'Connect & setup', cmds: connectGroup },
 ];
+// Per-command deep-docs cross-links, rendered as a "Docs:" epilog on each
+// command's --help AND carried in the `help --json` manifest. This is the
+// bridge agents actually need - from "found the command" to "know the API
+// pattern" - without duplicating skill content in help text (skills stay the
+// single source of truth; this maps names only). Keys must be real skill
+// names (`gipity skill list`).
+const SKILL_DOCS = {
+    save: 'app-import',
+    load: 'app-import',
+    github: 'app-import',
+    deploy: 'deploy',
+    page: 'app-debugging',
+    test: 'app-testing',
+    db: 'app-database',
+    fn: 'app-development',
+    service: 'service-call',
+    notify: 'app-notify',
+    payments: 'app-payments',
+    realtime: 'app-realtime',
+    job: 'jobs',
+    sandbox: 'sandbox-tools',
+    gmail: 'google-services',
+    email: 'email',
+    location: 'location',
+};
 program
     .name('gipity')
     .description(`${brand(bold('Gipity CLI'))} ${dim('-')} ${GIPITY_TAGLINE.replace(/\.$/, '')}\n\n  ${dim('Hosting, databases, deploys, workflows, code execution, and monitoring - one place, agent-tuned. Pair with Claude Code or use standalone.')}`)
@@ -207,14 +237,72 @@ program.configureHelp({
             lines.push('');
         }
         lines.push(dim(`Run "${cmd.name()} <command> --help" for details on a specific command.`));
+        lines.push(dim(`Deep docs: "${cmd.name()} skill list". Machine-readable manifest: "${cmd.name()} help --json".`));
         lines.push('');
         return lines.join('\n');
     },
 });
 for (const cmd of HELP_SECTIONS.flatMap(s => s.cmds)) {
     configureHelp(cmd);
+    // "Docs:" epilog bridging this command's --help to its skill doc.
+    const skill = SKILL_DOCS[cmd.name()];
+    if (skill)
+        cmd.addHelpText('after', `Docs: gipity skill read ${skill}\n`);
     program.addCommand(cmd);
 }
+// ── `gipity help [command]` + `help --json` machine-readable manifest ───
+// The JSON manifest is generated from the SAME commander registry that
+// renders human help, so it cannot drift: name, args, options, subcommands,
+// group, and the skill cross-link per command. Meant for agents and tooling
+// that want the full surface in one parseable shot instead of N --help calls.
+program.helpCommand(false); // replace the builtin so we can add --json
+function manifestCommand(c) {
+    return {
+        name: c.name(),
+        aliases: c.aliases().slice(),
+        description: c.description(),
+        usage: `gipity ${fullCommandPath(c)} ${c.usage()}`.trim(),
+        args: c.registeredArguments.map(a => ({
+            name: a.name(),
+            required: a.required,
+            description: a.description || '',
+        })),
+        options: c.options.filter(o => !o.hidden).map(o => ({ flags: o.flags, description: o.description })),
+        subcommands: c.commands.filter(sc => !sc._hidden).map(manifestCommand),
+        skill: SKILL_DOCS[c.name()] ?? null,
+    };
+}
+function fullCommandPath(c) {
+    const parts = [];
+    for (let cur = c; cur && cur.parent; cur = cur.parent)
+        parts.unshift(cur.name());
+    return parts.join(' ');
+}
+program.addCommand(new Command('help')
+    .description('Show help; --json emits the full command manifest for agents/tools')
+    .argument('[command]', 'Show help for this command')
+    .option('--json', 'Output every command (args, options, subcommands, docs links) as JSON')
+    .action((name, opts) => {
+    if (opts.json) {
+        const manifest = {
+            name: 'gipity',
+            version: pkg.version,
+            docs: 'Run `gipity skill list` for deep task docs; each command may carry a `skill` cross-link.',
+            sections: HELP_SECTIONS.map(s => ({
+                title: s.title,
+                commands: s.cmds.map(manifestCommand),
+            })),
+        };
+        console.log(JSON.stringify(manifest, null, 2));
+        return;
+    }
+    if (name) {
+        const target = program.commands.find(c => c.name() === name || c.aliases().includes(name));
+        if (target)
+            target.help();
+    }
+    program.help();
+}));
 // ── Malformed invocation → print the command's help inline, error LAST ──
 // When an agent guesses the wrong shape (excess args, unknown command/option,
 // missing arg), don't make it run `--help` as a second trip: render that exact

package/dist/knowledge.js

@@ -107,6 +107,7 @@ mkdir -p ~/GipityProjects/<slug> && cd ~/GipityProjects/<slug> && gipity init <s
 ## CLI quick reference
 
 Key commands: \`gipity add <template|kit>\`, \`gipity deploy dev\`, \`gipity sandbox run\`, \`gipity page inspect <url>\`, \`gipity page screenshot <url>\`, \`gipity db query "SQL"\`, \`gipity fn call <name>\`, \`gipity logs fn <name>\`, \`gipity secrets set <NAME> <value> [--account]\` (store an API key/token encrypted; read in functions via \`secrets.get('NAME')\` — never hardcode keys), \`gipity email send --to <addr> --subject <s> --body <b>\` (sends as \`gipity@gipity.ai\`; omit \`--to\` to self-send), \`gipity skill read <name>\`.
+Rename for findability: \`gipity project rename <name>\` renames the current project's display name (the slug and deployed URLs never change); \`gipity chat rename <title>\` renames the current chat's tab title. Both are the display label users scan to switch between tabs — retitle a chat when the conversation clearly shifts to a new topic (sparingly, not every turn), and keep every project/chat title SHORT: 2-4 words, ≤40 characters, no trailing punctuation (e.g. "Stripe checkout", "Tetris game").
 Pull an existing remote project local (given its URL/slug): \`mkdir -p ~/GipityProjects/<slug> && cd ~/GipityProjects/<slug> && gipity init <slug>\` (adopts the matching project and syncs files down - this is the "clone").
 Move whole apps in/out: \`gipity save\` (export this project as a portable \`.gip\` bundle), \`gipity load <file.gip | github:owner/repo>\` (import as a NEW project; \`--inspect\` to preview), \`gipity github connect\` (1-2 click GitHub access for imports). Porting a Vercel/Replit/Lovable app? Load the \`app-import\` skill first.
 For deterministic text questions (letter/word counts, substring occurrences, nth word/char, anagrams), use \`gipity text analyze "<text>"\` - local and instant, no sandbox or LLM needed.

package/dist/relay/onboarding.js

@@ -12,12 +12,12 @@
  * All the non-interactive primitives live in `setup.ts` (`pairDevice`,
  * `startDaemon`, `installAutostart`); this module is only the prompts + copy.
  */
-import { hostname } from 'os';
+import { readFileSync } from 'node:fs';
 import { prompt, confirm } from '../utils.js';
 import { bold, brand, dim, success, error as clrError, muted } from '../colors.js';
 import * as state from './state.js';
 import { UnsupportedPlatformError } from './installers.js';
-import { pairDevice, startDaemon, installAutostart } from './setup.js';
+import { pairDevice, startDaemon, installAutostart, friendlyDeviceName } from './setup.js';
 /** Spawn a fresh `gipity relay run` detached from this process. Fire-and-forget.
  *  Re-exported from the shared `setup` core so existing importers (`claude.ts`)
  *  keep their import path. */
@@ -27,6 +27,21 @@ export const ensureDaemonRunning = startDaemon;
  * ended up enabled (or was already), `false` if the user declined or a step
  * failed. Non-interactive flows (e.g. `gipity claude -p`) must not call this.
  */
+/** True inside Windows Subsystem for Linux (either env marker or kernel
+ *  string). Used to explain autostart failures accurately - WSL ships without
+ *  a systemd user session unless the user opts in via /etc/wsl.conf. */
+function isWsl() {
+    if (process.platform !== 'linux')
+        return false;
+    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP)
+        return true;
+    try {
+        return /microsoft/i.test(readFileSync('/proc/version', 'utf-8'));
+    }
+    catch {
+        return false;
+    }
+}
 export async function runRelaySetup(opts) {
     const alreadyAnswered = state.getRelayEnabled() !== undefined;
     // `gipity claude` first-run: honor the user's prior choice and don't re-ask.
@@ -35,6 +50,36 @@ export async function runRelaySetup(opts) {
             ensureDaemonRunning();
         return state.isRelayEnabled();
     }
+    // We only ever REGISTER an unregistered machine. If this computer already has
+    // a device, re-running setup must not silently create a second one — nor
+    // quietly reuse the old name after asking for a new one (the original bug:
+    // you'd type a new name and it would still show the old one). Surface the
+    // existing registration plainly and point at revoke as the way to start over.
+    const existingDevice = state.getDevice();
+    if (existingDevice) {
+        // Keep setup's promise: leave the relay enabled and running.
+        state.setRelayEnabled(true);
+        if (!state.isPaused())
+            ensureDaemonRunning();
+        if (opts.mode === 'run-now') {
+            console.log(`  ${bold('This computer is already set up as a relay')}`);
+            console.log('');
+            console.log(`  ${success('Registered as')} ${bold(existingDevice.name)} ${muted(`(${existingDevice.guid})`)}`);
+            if (state.isPaused()) {
+                console.log(`  ${dim('The relay is paused — resume it with')} ${brand('gipity relay resume')}${dim('.')}`);
+            }
+            else {
+                console.log(`  ${dim('The relay is running. Open')} ${brand('gipity.ai')}${dim(' and type `/claude` to drive Claude Code here.')}`);
+            }
+            console.log('');
+            console.log(`  ${dim('To register this computer again — for example under a different name —')}`);
+            console.log(`  ${dim('unregister it first, then re-run setup:')}`);
+            console.log(`      ${brand('gipity relay revoke')}   ${dim('# unpairs this computer and removes the login service')}`);
+            console.log(`      ${brand('gipity setup')}          ${dim('# register it again (asks for a new name)')}`);
+            console.log('');
+        }
+        return true;
+    }
     // Header. `gipity setup` frames it as the deliberate action it is; the
     // `gipity claude` first-run frames it as an optional add-on it's offering.
     if (opts.mode === 'run-now') {
@@ -59,8 +104,8 @@ export async function runRelaySetup(opts) {
         console.log('');
         return false;
     }
-    // Device name - show hostname as the default; Enter accepts.
-    const defaultName = hostname() || 'my-pc';
+    // Device name - show a friendly default (owner + device kind); Enter accepts.
+    const defaultName = friendlyDeviceName();
     const rawName = await prompt(`  Device name [${bold(defaultName)}]: `);
     const name = (rawName || defaultName).trim();
     if (!name || name.length > 100) {
@@ -94,7 +139,18 @@ export async function runRelaySetup(opts) {
         try {
             const res = installAutostart();
             if (!res.ok) {
-                console.log(`  ${muted('Autostart install returned non-zero - you can run')} ${brand('gipity relay install')} ${muted('later.')}`);
+                if (isWsl()) {
+                    // WSL: `systemctl --user` fails unless systemd is enabled in
+                    // /etc/wsl.conf, so name the actual cause + the fix instead of a
+                    // generic non-zero. The relay itself is unaffected (it's already
+                    // running this session, and `gipity claude` restarts it).
+                    console.log(`  ${muted('Auto-start needs systemd, which this WSL distro has off. The relay still runs -')}`);
+                    console.log(`  ${muted('it started just now and `gipity claude` restarts it. For boot-time auto-start:')}`);
+                    console.log(`  ${muted('add [boot] systemd=true to /etc/wsl.conf, restart WSL, then run')} ${brand('gipity relay install')}${muted('.')}`);
+                }
+                else {
+                    console.log(`  ${muted('Autostart install returned non-zero - you can run')} ${brand('gipity relay install')} ${muted('later.')}`);
+                }
             }
             else {
                 console.log(`  ${success('Auto-start installed.')} ${dim(res.summary)}`);

package/dist/relay/setup.js

@@ -11,7 +11,7 @@
  * and no `process.exit` in this module: callers own all UX.
  */
 import { spawnCommand, spawnSyncCommand } from '../platform.js';
-import { hostname, platform as osPlatform } from 'os';
+import { hostname, userInfo, platform as osPlatform } from 'os';
 import { resolve, dirname } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
 import { post } from '../api.js';
@@ -24,6 +24,33 @@ export function mapPlatform(p) {
         return p;
     return 'linux';
 }
+/**
+ * A friendly default device name for the web CLI — e.g. "Steve's Mac",
+ * "Steve's Windows PC". Prefers the OS login name + device kind, which reads
+ * better and is more recognizable than a raw hostname like "SignalOrangeXps".
+ * Falls back to the hostname, then a generic label. The user can override at
+ * the prompt, and the server de-dupes collisions ("Steve's Mac-2").
+ */
+export function friendlyDeviceName() {
+    const kind = osPlatform() === 'darwin' ? 'Mac' :
+        osPlatform() === 'win32' ? 'Windows PC' :
+            'Linux PC';
+    let user = '';
+    try {
+        user = (userInfo().username || '').trim();
+    }
+    catch {
+        // userInfo() throws when there's no matching passwd entry (some containers).
+    }
+    // Generic/service accounts carry no signal — the hostname is more useful there.
+    const generic = new Set(['root', 'user', 'admin', 'ubuntu', 'ec2-user', 'administrator', 'pi']);
+    if (user && !generic.has(user.toLowerCase())) {
+        const owner = user.charAt(0).toUpperCase() + user.slice(1);
+        return `${owner}'s ${kind}`;
+    }
+    const host = (hostname() || '').trim();
+    return host || `My ${kind}`;
+}
 /** Absolute path to the currently-running `gipity` CLI. Embedded in service
  *  units so launchd/systemd/Task Scheduler re-launch the same binary even if
  *  PATH changes. */
@@ -59,7 +86,7 @@ export async function pairDevice(opts = {}) {
         }
         state.clearDevice();
     }
-    const name = (opts.name?.trim() || hostname() || 'my-pc').trim();
+    const name = (opts.name?.trim() || friendlyDeviceName()).trim();
     if (!name || name.length > 100) {
         throw new Error('Device name must be 1–100 non-whitespace characters.');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.414",
+  "version": "1.0.416",
   "description": "The full-stack platform tuned for AI agents. Database, storage, auth, functions, deploy, and drop-in kits - all agent-tuned. Pair with Claude Code or use standalone.",
   "bin": {
     "gipity": "dist/updater/shim.js",