@vodmal/vdx-cli 0.13.1 → 0.15.0

package/README.md

@@ -26,7 +26,7 @@ ephemeral environment.
 
 **First command after install: `vdx doctor`** — it inspects your environment
 (Node version, `vdx` on PATH, git, mise, npm auth, container runtime, Claude
-Code plugin) and points to remedies for everything that's missing or
+Code plugin; in a project — git hooks and the commit author) and points to remedies for everything that's missing or
 sub-optimal.
 
 ## Use
@@ -48,7 +48,7 @@ vdx publish <patch|minor|major> [--dry-run] [--force]
 vdx doctor [--format=ansi|markdown|json]
 
 # Start your agent in a project per your profile (~/.vdx-environment.yaml or $VDX_ENVIRONMENT)
-vdx ai [project-path] [--new] [--restart] [--detach] [--dry-run]   # default: cwd
+vdx ai[@host] [project-path] [--new] [--restart] [--detach] [--dry-run]   # default: cwd; @host: over ssh, in tmux there
 
 # Print the installed version
 vdx --version
@@ -73,11 +73,20 @@ vdx publish minor   # bump → npm publish (OTP prompt) → git commit + tag (no
 # 4. Start the agent here, continuing its last conversation (--new: a new one);
 #    re-run to attach, --restart to apply a changed profile
 vdx ai
+
+# 5. The same on another machine (an ssh host with vdx), attaching from here
+vdx ai@m3
 ```
 
 `vdx ai` reads a personal profile, never a bundled one: `$VDX_ENVIRONMENT`, else
 `~/.vdx-environment.yaml`, else a plain `claude`/`codex` with no flags. Format:
 [docs/specs/environment-format.md](../docs/specs/environment-format.md).
+The session's `{project}` is `[vdx] name` from the project's `mise.toml`, else the
+first file in the profile's `session.project_names` that has one, else the repo
+name. `vdx ai@<host>` runs the same command on `<host>` over ssh — that machine's vdx,
+profile and tmux, the path taken under its home directory; `--detach` only
+starts it. The machine's own label (`$VDX_HOST`) runs here. Where git knows no
+commit author, `vdx ai` proposes one (Enter writes it into `.git/config`).
 
 By default the bundled `rubric/vdx-rubric.yaml` is used (a mirror of canonical
 [vdx-rubric-vodmal](https://github.com/VoDmAl/vdx-rubric-vodmal) at the time of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/rubric/vdx-rubric.yaml

@@ -11,7 +11,7 @@ schema_version: "0.2"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "0.4.0"
+  version: "0.6.0"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"

package/src/ai.ts

@@ -4,7 +4,9 @@ import * as path from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
 import YAML from 'js-yaml';
 import { evalPredicate } from './evaluator.ts';
-import { autoDetectStack, type Ctx } from './facts.ts';
+import { autoDetectStack, readStructured, resolveConfigPath, type Ctx } from './facts.ts';
+import { loadManifest } from './manifest.ts';
+import { type Author, effectiveAuthor, isGitRepo, rankAuthors, scanPool, writeAuthor } from './author.ts';
 import type { Predicate } from './rubric.ts';
 
 /**
@@ -46,9 +48,23 @@ export interface AgentProfile {
 
 export type Multiplexer = 'tmux' | 'none';
 
+/** A place a project's short name may come from: a structured file and a dot path into it. */
+export interface NameSource {
+  /** `{repo}` is the repository name; `~` the home directory; relative to the profile's directory. */
+  file: string;
+  jsonpath: string;
+}
+
 export interface SessionProfile {
   multiplexer?: Multiplexer;
   name?: string;
+  /** Tried after `[vdx] name` in the project's mise.toml; the first non-empty string wins. */
+  project_names?: NameSource[];
+}
+
+export interface GitProfile {
+  /** Directories whose repos are the neighbours an author is proposed from; default — the project's parent. */
+  author_pool?: string[];
 }
 
 export interface Environment {
@@ -56,6 +72,7 @@ export interface Environment {
   metadata?: Record<string, unknown>;
   agent?: AgentProfile;
   session?: SessionProfile;
+  git?: GitProfile;
 }
 
 export const ENVIRONMENT_ENV_VAR = 'VDX_ENVIRONMENT';
@@ -137,6 +154,27 @@ export function parseEnvironment(text: string, source: string): Environment {
     if (session.name !== undefined && typeof session.name !== 'string') {
       fail('session.name', 'must be a string');
     }
+    if (session.project_names !== undefined) {
+      if (!Array.isArray(session.project_names)) fail('session.project_names', 'must be a list');
+      session.project_names.forEach((src, i) => {
+        const at = `session.project_names[${i}]`;
+        if (typeof src !== 'object' || src === null) fail(at, 'must be a mapping');
+        if (typeof src.file !== 'string' || src.file === '') fail(`${at}.file`, 'must be a non-empty string');
+        const unknown = src.file.match(/\{(?!repo\})\w+\}/);
+        if (unknown) fail(`${at}.file`, `has an unknown placeholder ${unknown[0]} (only {repo})`);
+        if (typeof src.jsonpath !== 'string' || src.jsonpath === '') {
+          fail(`${at}.jsonpath`, 'must be a non-empty string (a dot path, e.g. names.0)');
+        }
+      });
+    }
+  }
+
+  const gitDoc = envDoc.git;
+  if (gitDoc !== undefined) {
+    if (typeof gitDoc !== 'object' || gitDoc === null) fail('git', 'must be a mapping');
+    if (gitDoc.author_pool !== undefined && !isStringList(gitDoc.author_pool)) {
+      fail('git.author_pool', 'must be a list of directories');
+    }
   }
   return envDoc;
 }
@@ -172,6 +210,8 @@ export function renderSessionName(template: string, vars: Record<string, string>
 export interface LaunchPlan {
   projectRoot: string;
   project: string;
+  /** Where `project` came from: mise.toml, a profile source, or the repository name. */
+  projectSource: string;
   host: string;
   profilePath: string | null;
   command: string;
@@ -190,6 +230,7 @@ export function planLaunch(input: {
   agent: AgentProfile;
   projectRoot: string;
   project: string;
+  projectSource?: string;
   host: string;
 }): LaunchPlan {
   const { environment, agent, projectRoot } = input;
@@ -206,6 +247,7 @@ export function planLaunch(input: {
   return {
     projectRoot,
     project: input.project,
+    projectSource: input.projectSource ?? 'repository name',
     host: input.host,
     profilePath: input.profilePath,
     command: agent.command,
@@ -384,6 +426,40 @@ export function projectIdentity(projectRoot: string): string {
   return path.basename(projectRoot);
 }
 
+export interface ProjectName {
+  name: string;
+  source: string;
+}
+
+/**
+ * `{project}`: `[vdx] name` in the project's mise.toml, else the first profile
+ * source holding a non-empty string, else the repository name. A source that is
+ * missing or unreadable is skipped — a name is a label, not a reason to fail.
+ */
+export function resolveProjectName(input: {
+  projectRoot: string;
+  repo: string;
+  sources: NameSource[];
+  home: string;
+  profileDir: string;
+}): ProjectName {
+  const own = loadManifest(input.projectRoot)?.name;
+  if (typeof own === 'string' && own.trim()) return { name: own.trim(), source: 'mise.toml [vdx] name' };
+  for (const src of input.sources) {
+    const file = path.resolve(
+      input.profileDir,
+      src.file.replace(/^~(?=$|\/)/, input.home).replace(/\{repo\}/g, input.repo),
+    );
+    // Readers take paths relative to a project root; from "/" an absolute path stays itself.
+    const value = resolveConfigPath(readStructured({ projectRoot: '/', stack: '', cache: new Map() }, file), src.jsonpath);
+    if (typeof value === 'string' && value.trim()) {
+      const shown = file.startsWith(input.home + path.sep) ? `~${file.slice(input.home.length)}` : file;
+      return { name: value.trim(), source: `${shown} ${src.jsonpath}` };
+    }
+  }
+  return { name: input.repo, source: 'repository name' };
+}
+
 /** `{host}`: `$VDX_HOST` when set (a machine label such as `lft`), else the short hostname. */
 export function hostLabel(env: NodeJS.ProcessEnv = process.env): string {
   const label = env[HOST_ENV_VAR]?.trim();
@@ -522,12 +598,37 @@ export interface AiDeps {
   processes: () => ProcInfo[];
   sleep: (ms: number) => void;
   confirmTimeoutMs: number;
+  /** One line from the person at the terminal, or null when there is none. */
+  ask: (prompt: string) => string | null;
 }
 
 export function sleepSync(ms: number): void {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
+/** Read one line from the terminal, synchronously: the prompt runs before tmux takes it. */
+export function askLine(prompt: string): string | null {
+  process.stderr.write(prompt);
+  const buf = Buffer.alloc(256);
+  let text = '';
+  for (;;) {
+    let n: number;
+    try {
+      n = fs.readSync(0, buf, 0, buf.length, null);
+    } catch (e: any) {
+      if (e?.code === 'EAGAIN') {
+        sleepSync(50);
+        continue;
+      }
+      return null;
+    }
+    if (n === 0) return text === '' ? null : text.trim();
+    text += buf.toString('utf8', 0, n);
+    const nl = text.indexOf('\n');
+    if (nl >= 0) return text.slice(0, nl).trim();
+  }
+}
+
 export function defaultDeps(): AiDeps {
   return {
     env: process.env,
@@ -541,6 +642,7 @@ export function defaultDeps(): AiDeps {
     processes: listProcesses,
     sleep: sleepSync,
     confirmTimeoutMs: 30_000,
+    ask: askLine,
   };
 }
 
@@ -559,6 +661,7 @@ export const NOTHING_TO_RESUME_MS = 30_000;
 export function renderPlan(plan: LaunchPlan, multiplexer: Multiplexer, running: AgentPane[]): string {
   const lines = [
     `vdx ai — ${plan.projectRoot}`,
+    `  name:     ${plan.project} (${plan.projectSource})`,
     `  profile:  ${plan.profilePath ?? `none — built-in default (${FALLBACK_AGENTS.join(' or ')}, no flags, no tmux)`}`,
     `  agent:    ${commandLine(plan.command, plan.args)}`,
     `  resume:   ${plan.resumeArgs.length ? plan.resumeArgs.join(' ') : '—'}`,
@@ -693,6 +796,116 @@ function finish(ok: boolean, session: string, paneId: string, opts: AiOptions, d
   return ok ? EXIT_OK : EXIT_LAUNCH_FAILED;
 }
 
+/** `vdx ai@<host>`: an ssh destination such as `m3` — never an option to ssh. */
+export const REMOTE_HOST_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** A path under the local home as a shell word under the remote home; any other path as is. */
+export function remotePathWord(abs: string, home: string): string {
+  const rel = path.relative(home, abs);
+  if (rel === '') return '"$HOME"';
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return shellQuote(abs);
+  return `"$HOME"/${shellQuote(rel)}`;
+}
+
+/**
+ * The ssh argv for `vdx ai@<host>`: the same `vdx ai` on the host, in its own
+ * tmux there. The path goes first: an older vdx hands the token after a flag it
+ * does not know to that flag. A different vdx version there is named, not fatal.
+ */
+export function remoteAiArgs(input: {
+  host: string;
+  projectPath: string;
+  home: string;
+  version: string;
+  opts: AiOptions;
+  tty: boolean;
+}): string[] {
+  const { host, opts, version } = input;
+  const flags = [
+    opts.fresh && '--new',
+    opts.restart && '--restart',
+    opts.detach && '--detach',
+    opts.dryRun && '--dry-run',
+  ].filter((f): f is string => Boolean(f));
+  const v = shellQuote(version);
+  const script =
+    `v=$(vdx --version 2>/dev/null) || v='older than 0.13.1'; ` +
+    `[ "$v" = ${v} ] || echo "note: vdx on ${host} is $v, here "${v} >&2; ` +
+    `exec vdx ai ${[remotePathWord(input.projectPath, input.home), ...flags].join(' ')}`;
+  return [input.tty ? '-t' : '-T', host, script];
+}
+
+/** Where neighbour repos live: the profile's `git.author_pool`, else the project's parent directory. */
+export function authorPoolDirs(environment: Environment, projectRoot: string, home: string, profileDir: string): string[] {
+  const listed = environment.git?.author_pool;
+  if (!listed?.length) return [path.dirname(projectRoot)];
+  return listed.map((d) => path.resolve(profileDir, d.replace(/^~(?=$|\/)/, home)));
+}
+
+/**
+ * A repo without its own author makes git refuse to commit (`user.useConfigOnly`).
+ * At a terminal vdx proposes the likely author and Enter takes the first;
+ * without one it says so and goes on — a scripted start must not stop here.
+ * A running agent needs no restart: git reads the author at each commit.
+ */
+export function ensureAuthor(projectRoot: string, poolDirs: string[], deps: AiDeps, dryRun: boolean): void {
+  if (!isGitRepo(projectRoot)) return;
+  const current = effectiveAuthor(projectRoot);
+  if (current) {
+    if (dryRun) deps.out(`  author:   ${current.email} (${current.scope})\n`);
+    return;
+  }
+  const top = rankAuthors(projectRoot, scanPool(poolDirs)).slice(0, 3);
+  const q = shellQuote(projectRoot);
+  const command = (a: Author) =>
+    `git -C ${q} config --local user.name ${shellQuote(a.name)} && git -C ${q} config --local user.email ${shellQuote(a.email)}`;
+  if (dryRun) {
+    const proposal = top.length ? `; would propose ${top.map((c) => c.email).join(', ')}` : '';
+    deps.out(`  author:   none — git refuses to commit here${proposal}\n`);
+    return;
+  }
+  deps.log(`⚠ ${path.basename(projectRoot)}: no commit author of its own — git will refuse to commit here`);
+  if (!deps.interactive || top.length === 0) {
+    deps.log(`  set it: ${top[0] ? command(top[0]) : `git -C ${q} config --local user.email <address>`}`);
+    return;
+  }
+  top.forEach((c, i) => deps.log(`  ${i + 1}) ${c.name} <${c.email}>${c.why.length ? `   ${c.why.join('; ')}` : ''}`));
+  deps.log('  s) skip');
+  for (let tries = 0; tries < 2; tries++) {
+    const answer = deps.ask('Author [1]: ');
+    if (answer === null) return;
+    const a = answer.trim();
+    if (/^[sn]$/i.test(a)) {
+      deps.log('  skipped');
+      return;
+    }
+    const pick: Author | undefined =
+      a === '' ? top[0] : /^\d+$/.test(a) ? top[Number(a) - 1] : a.includes('@') ? { name: top[0]!.name, email: a } : undefined;
+    if (pick) {
+      if (writeAuthor(projectRoot, pick)) deps.log(`✓ ${pick.name} <${pick.email}> → .git/config`);
+      else deps.log(`✗ could not write .git/config — ${command(pick)}`);
+      return;
+    }
+    deps.log(`  1–${top.length}, an address, or s`);
+  }
+}
+
+export function runAiRemote(opts: AiOptions, host: string, deps: AiDeps, version: string): number {
+  const projectPath = resolveProjectRoot(opts.path) ?? path.resolve(opts.path);
+  const tty = deps.interactive && !opts.detach && !opts.dryRun;
+  const args = remoteAiArgs({ host, projectPath, home: deps.home, version, opts, tty });
+  deps.log(`→ ${host}: vdx ai ${shellQuote(projectPath)}`);
+  const res = spawnSync('ssh', args, { stdio: 'inherit' });
+  if ((res.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') {
+    deps.log('vdx ai: `ssh` not found on PATH');
+    return 127;
+  }
+  if (opts.detach && res.status === EXIT_OK) {
+    deps.log(`attach from here: vdx ai@${host} ${shellQuote(projectPath)}`);
+  }
+  return res.status ?? 1;
+}
+
 export function runAi(opts: AiOptions, deps: AiDeps): number {
   const { log, tmux } = deps;
 
@@ -722,6 +935,15 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     return EXIT_USAGE;
   }
 
+  const profileDir = profilePath ? path.dirname(profilePath) : deps.home;
+  const named = resolveProjectName({
+    projectRoot,
+    repo: projectIdentity(projectRoot),
+    sources: environment.session?.project_names ?? [],
+    home: deps.home,
+    profileDir,
+  });
+
   let plan: LaunchPlan;
   try {
     plan = planLaunch({
@@ -729,7 +951,8 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
       profilePath,
       agent,
       projectRoot,
-      project: projectIdentity(projectRoot),
+      project: named.name,
+      projectSource: named.source,
       host: hostLabel(deps.env),
     });
   } catch (e: any) {
@@ -750,10 +973,13 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
       ? findAgentPanes(tmux.panes(), deps.processes(), projectRoot, plan.command)
       : [];
 
+  const poolDirs = authorPoolDirs(environment, projectRoot, deps.home, profileDir);
   if (opts.dryRun) {
     deps.out(renderPlan(plan, multiplexer, running));
+    ensureAuthor(projectRoot, poolDirs, deps, true);
     return EXIT_OK;
   }
+  ensureAuthor(projectRoot, poolDirs, deps, false);
 
   if (multiplexer === 'none') {
     if (opts.restart) {

package/src/author.ts

@@ -0,0 +1,192 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Who commits in a repo. The rule this serves: every repo carries its own
+ * author in `.git/config`, and git refuses where there is none
+ * (`user.useConfigOnly`). When a repo has none, vdx proposes one — the
+ * addresses some repo in the pool already carries, ranked by this repo's
+ * history, repos in the same remote group, and repos with a similar name.
+ */
+
+export interface Author {
+  name: string;
+  email: string;
+}
+
+export interface PoolRepo {
+  dir: string;
+  author: Author | null;
+  host: string;
+  group: string;
+  tokens: Set<string>;
+}
+
+export interface AuthorCandidate extends Author {
+  score: number;
+  why: string[];
+}
+
+function git(dir: string, args: string[]): string | null {
+  try {
+    return execFileSync('git', ['--no-optional-locks', '-C', dir, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function isGitRepo(dir: string): boolean {
+  return git(dir, ['rev-parse', '--git-dir']) !== null;
+}
+
+/** The address git would commit with here, and the scope it comes from; null when git knows none. */
+export function effectiveAuthor(dir: string): { email: string; scope: string } | null {
+  const out = git(dir, ['config', '--show-scope', '--get', 'user.email']);
+  if (!out) return null;
+  const [scope, email] = out.split('\t');
+  return email ? { email, scope: scope ?? '' } : null;
+}
+
+/** `git@host:group/repo.git`, `ssh://git@host:7999/group/repo.git` → host and group ("" when none). */
+export function remoteParts(url: string): { host: string; group: string; path: string } {
+  const m = url.match(/^(?:[a-z+]+:\/\/)?(?:[^@/]+@)?([^/:]+)(?::\d+)?[:/](.*?)(?:\.git)?\/?$/);
+  if (!m) return { host: '', group: '', path: '' };
+  const p = m[2]!;
+  return { host: m[1]!, group: p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '', path: p };
+}
+
+/** Words that say nothing about whose repo it is. */
+const GENERIC = new Set([
+  'git', 'com', 'org', 'name', 'www', 'ssh', 'http', 'https', 'the', 'app', 'mcp',
+  'github', 'gitlab', 'dev', 'net', 'vorobyev', 'vodmal', 'dmitry',
+]);
+
+export function nameTokens(dir: string, remotePath: string): Set<string> {
+  return new Set(
+    `${path.basename(dir)} ${remotePath}`
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((t) => t.length > 2 && !GENERIC.has(t)),
+  );
+}
+
+function describe(dir: string): PoolRepo {
+  const cfg = git(dir, ['config', '--local', '--get-regexp', '^(user\\.(name|email)|remote\\.origin\\.url)$']) ?? '';
+  const val = (key: string) =>
+    cfg.split('\n').find((l) => l.toLowerCase().startsWith(`${key} `))?.slice(key.length + 1).trim() ?? '';
+  const email = val('user.email');
+  const remote = remoteParts(val('remote.origin.url'));
+  return {
+    dir,
+    author: email ? { name: val('user.name'), email: email.toLowerCase() } : null,
+    host: remote.host,
+    group: remote.group,
+    tokens: nameTokens(dir, remote.path),
+  };
+}
+
+/** Git repos one level under each directory; the directories themselves are not repos. */
+export function scanPool(dirs: string[]): PoolRepo[] {
+  const seen = new Set<string>();
+  const out: PoolRepo[] = [];
+  for (const d of dirs) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const dir = path.join(d, e.name);
+      if (!e.isDirectory() || seen.has(dir) || !fs.existsSync(path.join(dir, '.git'))) continue;
+      seen.add(dir);
+      out.push(describe(dir));
+    }
+  }
+  return out;
+}
+
+/**
+ * Weights measured 2026-09-30 against the owner's 38 repos with their own
+ * author, each guessed from the others: the right address came first in 31,
+ * among the first three in 37.
+ */
+const W_HISTORY = 1.0;
+const W_GROUP = 0.3;
+const W_HOST = 0.1;
+const W_TOKEN = 0.4;
+
+/** The pool's addresses, best first. Only addresses some pool repo carries are proposed. */
+export function rankAuthors(dir: string, pool: PoolRepo[]): AuthorCandidate[] {
+  const self = describe(dir);
+  const others = pool.filter((p) => p.author && path.resolve(p.dir) !== path.resolve(dir));
+  const names = new Map<string, Map<string, number>>();
+  for (const p of others) {
+    const byName = names.get(p.author!.email) ?? new Map<string, number>();
+    if (p.author!.name) byName.set(p.author!.name, (byName.get(p.author!.name) ?? 0) + 1);
+    names.set(p.author!.email, byName);
+  }
+  if (names.size === 0) return [];
+
+  const score = new Map<string, number>();
+  const why = new Map<string, string[]>();
+  const add = (email: string, s: number, reason?: string) => {
+    score.set(email, (score.get(email) ?? 0) + s);
+    if (reason) why.set(email, [...(why.get(email) ?? []), reason]);
+  };
+
+  // Counted by git: a per-commit log of a large repo overflows the output buffer.
+  const history = new Map<string, number>();
+  for (const line of (git(dir, ['shortlog', '-se', '--all']) ?? '').split('\n')) {
+    const m = line.match(/^\s*(\d+)\s+.*<([^>]*)>\s*$/);
+    const e = m?.[2]?.toLowerCase();
+    if (e && names.has(e)) history.set(e, (history.get(e) ?? 0) + Number(m![1]));
+  }
+  const total = [...history.values()].reduce((a, b) => a + b, 0);
+  for (const [e, n] of history) add(e, (W_HISTORY * n) / total, `history ${n}`);
+
+  const group = new Map<string, number>();
+  const similar = new Map<string, string[]>();
+  for (const p of others) {
+    const e = p.author!.email;
+    if (self.host && p.host === self.host) {
+      const same = Boolean(self.group) && p.group === self.group;
+      add(e, same ? W_GROUP : W_HOST);
+      if (same) group.set(e, (group.get(e) ?? 0) + 1);
+    }
+    const overlap = [...self.tokens].filter((t) => p.tokens.has(t)).length;
+    if (overlap > 0) {
+      add(e, W_TOKEN * overlap);
+      similar.set(e, [...(similar.get(e) ?? []), path.basename(p.dir)]);
+    }
+  }
+  for (const [e, n] of group) add(e, 0, `same group ${self.host}/${self.group}: ${n}`);
+  for (const [e, list] of similar) add(e, 0, `similar: ${list.slice(0, 3).join(', ')}`);
+
+  const ranked = [...score.entries()].sort((a, b) => b[1] - a[1]);
+  // Addresses with no signal still belong in the menu, after the rest, by how many repos carry them.
+  const repos = (e: string) => [...(names.get(e)?.values() ?? [])].reduce((a, b) => a + b, 0);
+  const unsignalled = [...names.keys()].filter((e) => !score.has(e)).sort((a, b) => repos(b) - repos(a));
+  for (const e of unsignalled) {
+    ranked.push([e, 0]);
+    why.set(e, [`in ${repos(e)} repos`]);
+  }
+
+  const fallbackName = [...names.values()].flatMap((m) => [...m.entries()]).sort((a, b) => b[1] - a[1])[0]?.[0] ?? '';
+  return ranked
+    .map(([email, s]) => {
+      const byName = [...(names.get(email)?.entries() ?? [])].sort((a, b) => b[1] - a[1]);
+      return { email, name: byName[0]?.[0] ?? fallbackName, score: s, why: why.get(email) ?? [] };
+    });
+}
+
+export function writeAuthor(dir: string, author: Author): boolean {
+  return (
+    git(dir, ['config', '--local', 'user.name', author.name]) !== null &&
+    git(dir, ['config', '--local', 'user.email', author.email]) !== null
+  );
+}

package/src/doctor.ts

@@ -3,6 +3,8 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
+import { effectiveAuthor, isGitRepo, rankAuthors, scanPool } from './author.ts';
+import { authorPoolDirs, loadEnvironment, resolveEnvironmentPath, shellQuote, type Environment } from './ai.ts';
 
 export type CheckStatus = 'ok' | 'warning' | 'missing';
 
@@ -503,6 +505,40 @@ function checkGitHooks(ctx: DoctorCtx): CheckResult | null {
   };
 }
 
+/**
+ * The project's commit author. With `user.useConfigOnly` git refuses to commit
+ * in a repo that has none; the remedy names the likely one, as `vdx ai` does.
+ */
+export function checkGitAuthor(ctx: DoctorCtx): CheckResult | null {
+  const root = ctx.projectRoot;
+  if (root === null || !isGitRepo(root)) return null;
+  const id = 'git-author';
+  const label = 'git author';
+  const current = effectiveAuthor(root);
+  if (current) return { id, label, status: 'ok', message: `${current.email} (${current.scope})` };
+
+  let environment: Environment = {};
+  const profilePath = resolveEnvironmentPath();
+  try {
+    if (profilePath) environment = loadEnvironment(profilePath);
+  } catch {
+    /* a broken profile is vdx ai's report; the parent directory still gives neighbours */
+  }
+  const home = os.homedir();
+  const dirs = authorPoolDirs(environment, root, home, profilePath ? path.dirname(profilePath) : home);
+  const top = rankAuthors(root, scanPool(dirs))[0];
+  const q = shellQuote(root);
+  return {
+    id,
+    label,
+    status: 'warning',
+    message: `no author of its own — git refuses to commit here${top ? `; likely ${top.email}` : ''}`,
+    remedy: top
+      ? `git -C ${q} config --local user.name ${shellQuote(top.name)} && git -C ${q} config --local user.email ${shellQuote(top.email)}`
+      : `git -C ${q} config --local user.email <address>`,
+  };
+}
+
 const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkVdxVersion,
   checkVdx,
@@ -514,6 +550,7 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkNpmAuth,
   checkContainerRuntime,
   checkGitHooks,
+  checkGitAuthor,
 ];
 
 export function resolveDoctorCtx(cwd: string = process.cwd()): DoctorCtx {

package/src/index.ts

@@ -29,7 +29,7 @@ import {
   type PublishOptions,
 } from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
-import { runAi, defaultDeps } from './ai.ts';
+import { runAi, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
 
 const DEFAULT_RUBRIC = resolveDefaultRubric();
 
@@ -41,7 +41,7 @@ function usage(): never {
   vdx init    [project_path]  [--stack <id>] [--baseline <ref>] [--dry-run] [--force]                     (default: cwd)
   vdx publish <patch|minor|major> [--dry-run] [--force]
   vdx doctor  [--format=ansi|markdown|json] [--json]
-  vdx ai      [project_path]  [--new] [--restart] [--detach] [--dry-run]                                    (default: cwd)
+  vdx ai[@host] [project_path] [--new] [--restart] [--detach] [--dry-run]         (default: cwd; @host: over ssh, in tmux there)
   vdx --version
 `,
   );
@@ -278,9 +278,19 @@ function cmdAi(opts: ParsedArgs): void {
   bool('resume');
   const detach = bool('detach');
   const dryRun = bool('dry-run');
-  process.exit(
-    runAi({ path: positionals[0] ?? '.', restart, fresh, detach, dryRun }, defaultDeps()),
-  );
+  const options = { path: positionals[0] ?? '.', restart, fresh, detach, dryRun };
+  // `ai@m3`: the same command on another machine. Its own label runs here.
+  const host = opts.cmd.startsWith('ai@') ? opts.cmd.slice(3) : null;
+  if (host !== null) {
+    if (!REMOTE_HOST_RE.test(host)) {
+      process.stderr.write(`vdx ai@host: "${host}" is not a host name (an ssh destination such as m3)\n`);
+      process.exit(2);
+    }
+    if (host.toLowerCase() !== hostLabel().toLowerCase()) {
+      process.exit(runAiRemote(options, host, defaultDeps(), readCliVersion()));
+    }
+  }
+  process.exit(runAi(options, defaultDeps()));
 }
 
 const parsed = parseArgs(process.argv);
@@ -289,7 +299,7 @@ else if (parsed.cmd === 'audit') cmdAudit(parsed);
 else if (parsed.cmd === 'init') cmdInit(parsed);
 else if (parsed.cmd === 'publish') cmdPublish(parsed);
 else if (parsed.cmd === 'doctor') cmdDoctor(parsed);
-else if (parsed.cmd === 'ai') cmdAi(parsed);
+else if (parsed.cmd === 'ai' || parsed.cmd.startsWith('ai@')) cmdAi(parsed);
 else if ((LIFECYCLE_VERBS as readonly string[]).includes(parsed.cmd))
   cmdRun(parsed.cmd as LifecycleVerb);
 else usage();

package/src/init.ts

@@ -12,7 +12,7 @@ import {
 export const STANDARD_VERBS = ['up', 'down', 'build', 'test', 'check', 'fix'] as const;
 export type Verb = (typeof STANDARD_VERBS)[number];
 
-export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v0.4.0';
+export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v0.6.0';
 
 const VERB_ALIASES: Record<Verb, string[]> = {
   up: ['docker:up', 'docker-up', 'docker:up:detached', 'start', 'dev', 'serve'],

package/src/manifest.ts

@@ -5,6 +5,8 @@ import YAML from 'js-yaml';
 
 export interface VdxManifest {
   schema_version?: string;
+  /** Short name people use for the project (a session name, a sidebar); defaults to the repository name. */
+  name?: string;
   baseline?: string;
   stack?: string;
   primary_language?: string;