syndes 0.2.0 → 0.3.0

package/README.md

@@ -77,12 +77,31 @@ other people also use.
 
 ## Sharing an account
 
+`syndes install` asks. Or set it up later:
+
 ```bash
 syndes team join git@github.com:you/usage.git   # a private repo you both push to
 syndes team join ~/Dropbox/usage --folder       # or no server at all
-syndes team name "Ada"
 ```
 
+**Adding someone is one line.** `syndes team invite` — or the Invite button on
+the Team page — prints a command you send them:
+
+```
+npm install -g syndes && syndes join syndes1_eyJ2Ijox…
+```
+
+That installs SynDes, works out why git cannot reach the repo, offers to sign
+them in, joins them and starts publishing. The invite carries an address, never
+a credential: who may join is the repository's collaborator list, and only that.
+
+| | |
+| --- | --- |
+| `syndes team invite` | a line to send someone |
+| `syndes team status` | who used how much |
+| `syndes team remove <name>` | take a machine out of the pool |
+| `syndes team doctor` | what is stopping git reaching the repo |
+
 Each machine writes only its own folder and reads everyone's, so there is nothing
 to merge and nothing to run. Open the dashboard and the **Team** page is live
 while you watch it.
@@ -90,6 +109,11 @@ while you watch it.
 What leaves your machine: daily counts, tokens, and the hours you worked. What
 never does: your prompts, your file paths, your commands — at any setting.
 
+**A pool is one room.** Everyone in it sees everyone else — names, hours and
+volumes — and can read the raw files on GitHub without SynDes. Add only people
+who should all see each other. Removing someone takes them out of the view;
+git keeps the old commits, so it is not an erasure.
+
 This is cooperative measurement, not enforcement. It sees Claude Code on machines
 where SynDes is installed, and anyone can stop publishing. Note that consumer
 plans are licensed to one person; per-person logins are both the supported path

package/bin/cli.mjs

@@ -42,7 +42,9 @@ import { openUrl } from '../src/open.mjs';
 import { pendingCount } from '../runtime/spool.mjs';
 import { detectAll, adapterFor, ADAPTERS } from '../adapters/index.mjs';
 import { pollTails, resetCursors } from '../collect/tail.mjs';
-import { joinPool, leave as leavePool, syncOnce, readPool, isEnabled, teamConfig, loadState, poolRoot } from '../sync/index.mjs';
+import { joinPool, leave as leavePool, syncOnce, readPool, isEnabled, teamConfig, loadState, poolRoot, inviteCode, removeDevice, poolName } from '../sync/index.mjs';
+import { decode as decodeInvite, commandFor } from '../sync/invite.mjs';
+import { diagnose as preflight, repair as repairAuth, ghInstallHint } from '../src/preflight.mjs';
 import { identity, setName, initialsOf } from '../runtime/identity.mjs';
 import { team as teamView } from '../analytics/team.mjs';
 
@@ -52,7 +54,7 @@ const COMMANDS = {
   install: cmdInstall, uninstall: cmdUninstall, doctor: cmdDoctor,
   status: cmdStatus, report: cmdReport, dashboard: cmdDashboard, ui: cmdDashboard,
   lock: cmdLock, verify: cmdVerify, sessions: cmdSessions,
-  sources: cmdSources, watch: cmdWatch, team: cmdTeam,
+  sources: cmdSources, watch: cmdWatch, team: cmdTeam, join: cmdJoin,
   projects: cmdProjects, practices: cmdPractices, habits: cmdPractices, coach: cmdCoach,
   ledger: cmdLedger, export: cmdExport, rebuild: cmdRebuild, drain: cmdDrain,
   archive: cmdArchive, prune: cmdPrune, config: cmdConfig,
@@ -592,6 +594,130 @@ async function cmdWatch(args) {
   process.on('SIGINT', () => { clearInterval(timer); write(); process.exit(0); });
 }
 
+/**
+ * `syndes join <invite>` — everything a newcomer has to do, in one command.
+ *
+ * The person receiving an invite has not read any of this and should not have
+ * to. So this installs if it is not installed, works out why git cannot reach
+ * the repository, offers to fix that, joins, and publishes — reporting each
+ * step rather than failing with one line about credentials.
+ */
+async function cmdJoin(args) {
+  const raw = args.find((arg) => !arg.startsWith('--'));
+  if (!raw) throw new Error('usage: syndes join <invite-code>   (the line whoever invited you sent)');
+
+  const invite = decodeInvite(raw);
+  if (!invite) {
+    throw new Error('that does not look like an invite — paste the whole line you were sent, or use: syndes team join <repo-url>');
+  }
+
+  banner();
+  write(`  Joining ${bold(invite.pool ?? 'the pool')}${invite.from ? grey(`, invited by ${invite.from}`) : ''}`);
+  write(grey(`  ${invite.repo}`));
+  write();
+
+  if (!isInstalledHere()) {
+    const step = spinner('Setting up SynDes on this machine');
+    await beat();
+    await install({});
+    step.succeed(displayPath(installDir));
+  } else {
+    write(`  ${grey(DOT)} ${grey('already installed')}`);
+  }
+
+  if (!(await ensureReachable(invite.repo, args))) return;
+
+  let who = args.find((arg) => arg.startsWith('--name='))?.split('=').slice(1).join('=');
+  if (!who && process.stdin.isTTY) {
+    write();
+    who = (await ask(`  Your name, as the others will see it [${identity().name}]: `)).trim();
+  }
+  if (who) setName(who);
+
+  write();
+  const step = spinner('Joining the pool');
+  await beat();
+  try {
+    joinPool({ transport: invite.transport, repo: invite.repo });
+  } catch (error) {
+    step.fail(error.message);
+    process.exitCode = 1;
+    return;
+  }
+  step.succeed(poolName());
+
+  const share = spinner('Publishing this machine');
+  await beat();
+  const state = syncOnce();
+  if (state.ok) share.succeed(`${state.published} day(s) shared as ${identity().name}`);
+  else share.fail(state.error ?? 'could not publish');
+
+  const others = readPool().filter((peer) => !peer.isMe);
+  write();
+  write(`  ${OK} you are in${others.length ? grey(` · also here: ${others.map((peer) => peer.name).join(', ')}`) : ''}`);
+  write(grey(`  ${cyan('syndes dashboard')} then open Team`));
+  write();
+}
+
+function isInstalledHere() {
+  try {
+    return (adapterFor('claude-code').status?.().wired ?? 0) > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check git can reach the repository, and fix it if we can.
+ *
+ * The confusing case this exists for: accepting a collaborator invite in a
+ * browser authorises the ACCOUNT, while git on this machine still cannot prove
+ * who it is — and GitHub answers that with "not found" rather than "not you".
+ */
+async function ensureReachable(repo, args = []) {
+  const step = spinner('Checking access to the repository');
+  await beat();
+  let report = preflight(repo);
+
+  if (report.ok) {
+    // Only claim an account when a reach check actually ran and passed with it.
+    // A folder pool, or a local path, never touches GitHub — saying "as <user>"
+    // there would credit an authentication that was not tested.
+    const tested = report.checks.some((check) => check.name === 'repository' && check.ok);
+    step.succeed(tested && report.gh.account ? `as ${report.gh.account}` : tested ? 'reachable' : 'no sign-in needed');
+    return true;
+  }
+  step.fail(report.blocking.detail);
+
+  if (report.gh.installed && process.stdin.isTTY && !args.includes('--no-fix')) {
+    write();
+    write(grey('  This is usually a sign-in, not a missing repository.'));
+    if (await confirm('  Sign in to GitHub now?', true)) {
+      write();
+      const fixed = repairAuth({ interactive: true });
+      write();
+      if (fixed.ran.length) write(grey(`  ran: ${fixed.ran.join(', ')}`));
+      const retry = spinner('Checking access again');
+      await beat();
+      report = preflight(repo);
+      if (report.ok) {
+        retry.succeed(report.gh.account ? `as ${report.gh.account}` : 'reachable');
+        return true;
+      }
+
+      retry.fail(report.blocking.detail);
+    }
+  }
+
+  write();
+  write(`  ${cyan('→')} ${report.blocking.fix}`);
+  if (!report.gh.installed) write(`  ${cyan('→')} the GitHub CLI makes this one command: ${ghInstallHint()}`);
+  write(grey('  then run this again — nothing is lost, recording has already started'));
+  write();
+  process.exitCode = 1;
+  return false;
+}
+
 /**
  * `syndes team …` — the shared-account pool.
  *
@@ -659,6 +785,63 @@ async function cmdTeam(args) {
     return;
   }
 
+  if (verb === 'invite') {
+    if (!isEnabled()) throw new Error('sharing is off — syndes team join <repo> first');
+    const code = inviteCode();
+    write();
+    write(`  ${bold('Send this line')} ${grey('· they paste it into a terminal, and that is all')}`);
+    write();
+    write(`  ${cyan(commandFor(code))}`);
+    write();
+    write(grey('  It installs SynDes, checks their GitHub access, offers to fix it,'));
+    write(grey('  and joins them to this pool.'));
+    write();
+    write(grey(`  ${WARN} first add them as a collaborator on ${teamConfig().repo}`));
+    write(grey('  The invite is not a key — access is the repository\'s collaborator list.'));
+    write(grey('  Everyone in the pool can see everyone else in it.'));
+    write();
+    return;
+  }
+
+  if (verb === 'remove') {
+    const target = rest.filter((arg) => !arg.startsWith('--')).join(' ');
+    if (!target) throw new Error('usage: syndes team remove <name>');
+    if (!isEnabled()) throw new Error('sharing is off');
+
+    const peers = readPool();
+    const match = peers.find((p) => p.deviceId === target || p.name?.toLowerCase() === target.toLowerCase());
+    if (!match) throw new Error(`no machine called "${target}" — ${peers.map((p) => p.name).join(', ')}`);
+
+    write();
+    write(`  ${WARN} removing ${bold(match.name)} takes their ${match.rollups.size} published day(s) out of the pool`);
+    write(grey('  Their own ledger is untouched. Past totals will change for everyone.'));
+    write(grey('  Git keeps the old commits, so this removes them from view, not from history.'));
+    write(grey(`  To stop them adding more, remove their GitHub access as well.`));
+    write();
+    if (process.stdin.isTTY && !rest.includes('--yes') && !(await confirm(`  Remove ${match.name}?`))) return write('cancelled');
+
+    const step = spinner(`Removing ${match.name}`);
+    await beat();
+    const result = removeDevice(match.deviceId);
+    if (!result.removed) { step.fail(result.error); process.exitCode = 1; return; }
+    if (result.pushed) step.succeed('removed and pushed');
+    else step.fail(`removed locally, but the push failed: ${result.error ?? 'unknown'}`);
+    return;
+  }
+
+  if (verb === 'doctor') {
+    const report = preflight(teamConfig().repo ?? null);
+    write();
+    for (const check of report.checks) {
+      const mark = check.ok === true ? OK : check.ok === false ? FAIL : grey(DOT);
+      write(`  ${mark} ${check.name.padEnd(12)} ${check.ok === false ? check.detail : grey(check.detail)}`);
+      if (check.fix) write(`     ${cyan('→')} ${check.fix}`);
+    }
+    write();
+    if (!report.ok) process.exitCode = 1;
+    return;
+  }
+
   if (verb === 'sync') {
     if (!isEnabled()) return write(grey('sharing is off — syndes team join <repo>'));
     const spin = spinner('Exchanging with the pool');
@@ -706,6 +889,8 @@ async function cmdTeam(args) {
   write();
   write(`  ${grey('overlap')} ${percent(data.grid.overlapRate)} ${grey(`of working hours had more than one of you in them`)}`);
   write();
+  write(grey(`  ${cyan('syndes team invite')} to add someone  ${DOT}  ${cyan('syndes team remove <name>')}  ${DOT}  ${cyan('syndes team doctor')}`));
+  write();
 }
 
 /** `syndes lock [open|system|pin]` */
@@ -801,7 +986,9 @@ function usage_() {
     [cyan('export --format=csv'), 'all of it, back out'],
     [cyan('sources'), 'which coding agents SynDes can see'],
     [cyan('watch [--once]'), 'follow agents that have no hook API'],
-    [cyan('team [join|status]'), 'share one account and see the split'],
+    [cyan('join <invite>'), 'accept an invite — installs and sets everything up'],
+    [cyan('team invite'), 'a line to send someone so they can join'],
+    [cyan('team [status|remove]'), 'share one account and see the split'],
     [cyan('lock [mode]'), 'how the dashboard unlocks: open, system or pin'],
     [cyan('doctor [--full]'), 'what is wired and what actually works'],
     [cyan('off [30m] / on'), 'pause and resume tracking'],

package/dashboard/api/team.mjs

@@ -15,7 +15,9 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { join } from 'node:path';
 import { team } from '../../analytics/team.mjs';
-import { joinPool, leave, publish, isEnabled, teamConfig } from '../../sync/index.mjs';
+import { joinPool, leave, publish, isEnabled, teamConfig, inviteCode, removeDevice, poolName } from '../../sync/index.mjs';
+import { commandFor } from '../../sync/invite.mjs';
+import { diagnose as preflight } from '../../src/preflight.mjs';
 import { setName } from '../../runtime/identity.mjs';
 import { rawConfig, saveConfig, setPath, resetCache } from '../../runtime/config.mjs';
 import { packageRoot } from '../../runtime/paths.mjs';
@@ -97,6 +99,32 @@ export async function teamAction({ body }) {
       return { data: { ok: true, pollSeconds: seconds } };
     }
 
+    if (action === 'invite') {
+      const code = inviteCode();
+      return {
+        data: {
+          ok: true,
+          code,
+          command: commandFor(code),
+          pool: poolName(),
+          repo: teamConfig().repo,
+        },
+      };
+    }
+
+    if (action === 'remove') {
+      // Removing someone is the one write outside our own shelf, so it is
+      // deliberately a separate action from anything the sync loop performs.
+      const result = removeDevice(String(body.deviceId ?? body.name ?? ''));
+      if (!result.removed) return { status: 400, data: { error: result.error ?? 'could not remove' } };
+      await syncNow();
+      return { data: { ok: true, name: result.name, pushed: result.pushed, error: result.error } };
+    }
+
+    if (action === 'check') {
+      return { data: preflight(teamConfig().repo ?? null) };
+    }
+
     if (action === 'sync') {
       const state = await syncNow();
       return { data: { ok: true, sync: state } };

package/dashboard/web/api.js

@@ -72,6 +72,8 @@ export const api = {
 
   team: (range) => get(`/api/team?range=${encodeURIComponent(range)}`),
   teamAction: (action, payload = {}) => post('/api/team', { action, ...payload }),
+  teamInvite: () => post('/api/team', { action: 'invite' }),
+  teamRemove: (deviceId) => post('/api/team', { action: 'remove', deviceId }),
   // Not fetched through request(): an event stream is a live connection, not a
   // response with a body, so the view owns it and closes it itself.
   teamStreamUrl: (range) => `/api/team/stream?range=${encodeURIComponent(range)}`,

package/dashboard/web/app.css

@@ -540,6 +540,24 @@ a { color: inherit; text-decoration: none; }
 .field::placeholder { color: var(--ink-3); }
 .field:focus-visible { outline: 2px solid var(--lime); outline-offset: 2px; }
 
+/* The invite line. Monospace and selectable — somebody will always copy it by
+   hand rather than trust the button, and a wrapped command must still be one
+   correct command when it is pasted. */
+.invite {
+  display: block;
+  font-family: var(--mono);
+  font-size: 11px;
+  line-height: 1.6;
+  color: var(--lime);
+  background: var(--surface-3);
+  border-radius: var(--r-chip);
+  padding: var(--s3) var(--s4);
+  word-break: break-all;
+  user-select: all;
+  max-height: 140px;
+  overflow-y: auto;
+}
+
 /* ── Responsive ───────────────────────────────────────────────────────── */
 
 @media (max-width: 1240px) {

package/dashboard/web/ui.js

@@ -344,6 +344,7 @@ export function modal({
   title,
   note = null,
   input = null,       // { placeholder, type, inputmode, maxlength, validate }
+  body = null,        // extra nodes, rendered above the field
   confirmLabel = 'Confirm',
   cancelLabel = 'Cancel',
   danger = false,
@@ -376,6 +377,7 @@ export function modal({
     const panel = h('div.modal', { role: 'dialog', 'aria-modal': 'true', 'aria-label': title }, [
       h('div.modal__title', { text: title }),
       note ? h('div.modal__note', { text: note }) : null,
+      ...[].concat(body ?? []).filter(Boolean),
       field,
       field ? error : null,
       h('div.modal__actions', {}, [

package/dashboard/web/views/team.js

@@ -222,18 +222,26 @@ function peopleCard(data, outlet, range) {
     String(peer.totals.sessions),
     duration(peer.totals.activeMs),
     peer.score === null ? DASH : String(peer.score),
+    peer.isMe
+      ? h('span', { style: 'color:var(--ink-3)', text: DASH })
+      : h('button.btn.btn--ghost.btn--sm', {
+          text: 'Remove',
+          title: `Remove ${peer.name} from the pool`,
+          onclick: () => remove(peer, outlet, range),
+        }),
   ]);
 
   const actions = h('div', { style: 'display:flex;gap:8px' }, [
+    h('button.btn.btn--lime', { text: 'Invite', onclick: () => invite() }),
     h('button.btn.btn--ghost', { text: 'Rename', onclick: () => rename(data, outlet, range) }),
     h('button.btn.btn--ghost', { text: 'Sync now', onclick: () => syncNow(outlet, range) }),
   ]);
 
   return card('People', [
     table(
-      ['Person', 'Share', 'Tokens', 'Sessions', 'Active', 'Score'],
+      ['Person', 'Share', 'Tokens', 'Sessions', 'Active', 'Score', ''],
       rows,
-      { align: ['left', 'left', 'right', 'right', 'right', 'right'] },
+      { align: ['left', 'left', 'right', 'right', 'right', 'right', 'right'] },
     ),
     h('span.card__note', {
       text: 'A stale shelf has not synced in six hours — that is a machine that stopped reporting, not a quiet day.',
@@ -247,6 +255,92 @@ function peopleCard(data, outlet, range) {
 
 // ── Actions ─────────────────────────────────────────────────────────────────
 
+/**
+ * Invite someone.
+ *
+ * The output is one line they paste into a terminal — not a URL and a list of
+ * steps. Everything they would otherwise have to be told (install it, sign in
+ * to GitHub, paste the repo, pick a name) is what `syndes join` then does for
+ * them, so the thing being copied here is the whole onboarding.
+ *
+ * The two facts that are easy to get wrong are stated in the dialog rather than
+ * left for someone to discover: the invite is not a key, and a pool is one room
+ * where everybody can see everybody.
+ */
+async function invite() {
+  let details;
+  try {
+    details = await api.teamInvite();
+  } catch (error) {
+    await modal({ title: 'Could not make an invite', note: error.body?.error ?? error.message, confirmLabel: 'Close', cancelLabel: 'Dismiss' });
+    return;
+  }
+
+  const box = h('code.invite', { text: details.command });
+  const copy = h('button.btn.btn--lime', { type: 'button', text: 'Copy the line' });
+  copy.addEventListener('click', async () => {
+    try {
+      await navigator.clipboard.writeText(details.command);
+      copy.textContent = 'Copied';
+    } catch {
+      // Clipboard access can be refused; selecting the text still works.
+      copy.textContent = 'Select it and copy';
+    }
+    setTimeout(() => { copy.textContent = 'Copy the line'; }, 2200);
+  });
+
+  await modal({
+    title: `Invite someone to ${details.pool}`,
+    note: 'Send them this line. It installs SynDes, checks their GitHub access, offers to fix it, and joins them.',
+    body: [
+      box,
+      h('div', { style: 'display:flex;justify-content:center' }, [copy]),
+      h('div.modal__note', { style: 'text-align:left;margin-top:4px' }, [
+        h('div', { text: `1. Add them as a collaborator on ${details.repo}` }),
+        h('div', { text: '2. They accept the invite on GitHub' }),
+        h('div', { text: '3. They paste the line above' }),
+      ]),
+      h('div.modal__note', { style: 'text-align:left;color:var(--orange)' }, [
+        h('div', { text: 'Everyone in a pool can see everyone else in it — names, hours and volumes.' }),
+        h('div', { text: 'The line is not a key. Access is the repository\'s collaborator list, and only that.' }),
+      ]),
+    ],
+    confirmLabel: 'Done',
+    cancelLabel: 'Close',
+  });
+}
+
+async function remove(peer, outlet, range) {
+  const ok = await modal({
+    title: `Remove ${peer.name}?`,
+    note: `This takes their published days out of the pool for everyone, so past totals will change. Their own ledger is untouched.`,
+    body: [
+      h('div.modal__note', { style: 'text-align:left' }, [
+        h('div', { text: 'Git keeps the old commits, so this removes them from view, not from history.' }),
+        h('div', { text: 'To stop them publishing more, remove their access to the repository as well.' }),
+      ]),
+    ],
+    confirmLabel: `Remove ${peer.name}`,
+    cancelLabel: 'Keep them',
+    danger: true,
+  });
+  if (!ok) return;
+
+  try {
+    const result = await api.teamRemove(peer.deviceId);
+    if (!result.pushed) {
+      await modal({
+        title: 'Removed here, but not pushed',
+        note: result.error ?? 'The change is local until a push succeeds. Try Sync now.',
+        confirmLabel: 'Close', cancelLabel: 'Dismiss',
+      });
+    }
+  } catch (error) {
+    await modal({ title: 'Could not remove', note: error.body?.error ?? error.message, confirmLabel: 'Close', cancelLabel: 'Dismiss' });
+  }
+  await refresh(outlet, range);
+}
+
 async function rename(data, outlet, range) {
   const name = await modal({
     title: 'What should this machine be called?',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syndes",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SynDes — a tamper-evident ledger of everything you do in Claude Code, an efficiency score built from it, and a local dashboard that shows you how you actually work. Splits one shared account between the people on it. macOS, Windows and Linux. Zero dependencies.",
   "keywords": [
     "syndes",

package/src/preflight.mjs

@@ -0,0 +1,174 @@
+/**
+ * Can this machine actually reach the pool — and if not, what fixes it.
+ *
+ * Joining a shared repository fails for a handful of dull reasons that all
+ * surface as the same unhelpful git error, and one of them is genuinely
+ * confusing: accepting a collaborator invite in a browser grants the ACCOUNT
+ * access, while git on the machine still has no idea who you are. GitHub then
+ * returns 404 rather than admit a private repository exists, so the honest
+ * message "you are not signed in" arrives disguised as "no such repo".
+ *
+ * So every check here answers three things: what was tested, what happened, and
+ * the exact next command. A check that cannot answer returns `null` rather than
+ * guessing — same rule the platform probes follow.
+ *
+ * Nothing is installed without being asked. Software installs itself on a
+ * developer's machine only when they say so; the most this does unattended is
+ * teach git to use credentials the user already has.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { which, isMac, isWindows, platformName } from '../runtime/platform.mjs';
+import { debug } from '../runtime/log.mjs';
+
+const TIMEOUT_MS = 20_000;
+
+function run(binary, args, { timeout = TIMEOUT_MS, quiet = true } = {}) {
+  try {
+    const out = execFileSync(binary, args, {
+      encoding: 'utf8',
+      timeout,
+      stdio: quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+      windowsHide: true,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: 'echo' },
+    });
+    return { ok: true, out: (out ?? '').trim(), error: null };
+  } catch (error) {
+    const stderr = String(error.stderr ?? '').trim();
+    return { ok: false, out: '', error: (stderr || error.message).split('\n').slice(-2).join(' ').slice(0, 240) };
+  }
+}
+
+/** How this platform installs the GitHub CLI. */
+export function ghInstallHint() {
+  if (isMac) return which('brew') ? 'brew install gh' : 'see https://cli.github.com (or: brew install gh)';
+  if (isWindows) return 'winget install --id GitHub.cli';
+  return 'see https://cli.github.com — most distros package it as `gh`';
+}
+
+export function gitInstallHint() {
+  if (isMac) return 'xcode-select --install';
+  if (isWindows) return 'winget install --id Git.Git';
+  return 'your package manager, e.g. apt install git';
+}
+
+/** @returns {{installed: boolean, authed: boolean, account: string|null, gitConfigured: boolean}} */
+export function ghState() {
+  const gh = which('gh');
+  if (!gh) return { installed: false, authed: false, account: null, gitConfigured: false };
+
+  const status = run(gh, ['auth', 'status']);
+  const account = /Logged in to \S+ account (\S+)/.exec(`${status.out}\n${status.error ?? ''}`)?.[1] ?? null;
+
+  // `gh auth setup-git` writes a credential helper entry; without it a gh login
+  // authenticates the gh command and nothing else, which is the trap.
+  const helper = run(which('git') ?? 'git', ['config', '--get-regexp', 'credential.*helper']);
+  return {
+    installed: true,
+    authed: Boolean(account),
+    account,
+    gitConfigured: /gh auth git-credential|gh\b/.test(helper.out),
+  };
+}
+
+/**
+ * Everything that must be true before a join can work.
+ *
+ * @param {string|null} repo  the remote to test, or null to skip the reach check
+ * @returns {{ok: boolean, checks: object[], blocking: object|null}}
+ */
+export function diagnose(repo = null) {
+  const checks = [];
+  const git = which('git');
+
+  checks.push(git
+    ? { name: 'git', ok: true, detail: git }
+    : { name: 'git', ok: false, detail: `not installed on this ${platformName}`, fix: gitInstallHint() });
+
+  const gh = ghState();
+  checks.push(gh.installed
+    ? { name: 'gh', ok: true, detail: gh.authed ? `signed in as ${gh.account}` : 'installed, not signed in' }
+    : { name: 'gh', ok: null, detail: 'not installed — optional, but it is the easiest way to authenticate', fix: ghInstallHint() });
+
+  if (git && repo && !repo.startsWith('/') && !repo.startsWith('~')) {
+    const reach = run(git, ['ls-remote', '--heads', repo]);
+    if (reach.ok) {
+      checks.push({ name: 'repository', ok: true, detail: 'reachable, and git can authenticate' });
+    } else {
+      checks.push({
+        name: 'repository',
+        ok: false,
+        detail: explain(reach.error, gh),
+        fix: remedy(gh, repo),
+        raw: reach.error,
+      });
+    }
+  }
+
+  const blocking = checks.find((check) => check.ok === false) ?? null;
+  return { ok: !blocking, checks, blocking, gh };
+}
+
+/**
+ * Turn git's message into the actual problem.
+ *
+ * "Repository not found" on a private repo almost never means the repo is
+ * missing — it means GitHub will not confirm it exists to someone it cannot
+ * identify. Repeating git's wording would send the user to check the URL, which
+ * is the one thing that is usually right.
+ */
+function explain(error, gh) {
+  const text = String(error ?? '');
+  if (/could not read Username|Authentication failed|terminal prompts disabled/i.test(text)) {
+    return gh.authed
+      ? `git has no credentials for this remote, though gh is signed in as ${gh.account}`
+      : 'git has no credentials for this remote';
+  }
+  if (/not found|does not exist/i.test(text)) {
+    return gh.authed
+      ? `not visible to ${gh.account} — either the invite is not accepted, or git is not using that account`
+      : 'private repositories are invisible until git can prove who you are';
+  }
+  if (/Permission denied \(publickey\)/i.test(text)) return 'no SSH key on this machine that GitHub recognises';
+  if (/Could not resolve host|network/i.test(text)) return 'cannot reach the network';
+  return text.slice(0, 160);
+}
+
+function remedy(gh, repo) {
+  const ssh = repo.startsWith('git@') || repo.startsWith('ssh://');
+  if (ssh) return 'add an SSH key to your GitHub account, or use the https:// url instead';
+  if (!gh.installed) return `${ghInstallHint()}, then: gh auth login && gh auth setup-git`;
+  if (!gh.authed) return 'gh auth login';
+  if (!gh.gitConfigured) return 'gh auth setup-git';
+  return 'check the collaborator invite has been accepted for this account';
+}
+
+/**
+ * Fix what can be fixed without installing anything.
+ *
+ * `gh auth login` is interactive by design — it opens a browser and asks the
+ * person to confirm — so it is only attempted when there is a terminal to run
+ * it in, and it inherits stdio so the user sees and answers it themselves.
+ *
+ * @returns {{ran: string[], ok: boolean}}
+ */
+export function repair({ interactive = Boolean(process.stdin.isTTY) } = {}) {
+  const gh = ghState();
+  const ran = [];
+  if (!gh.installed) return { ran, ok: false };
+
+  const binary = which('gh');
+  if (!gh.authed) {
+    if (!interactive) return { ran, ok: false };
+    ran.push('gh auth login');
+    const result = run(binary, ['auth', 'login'], { quiet: false, timeout: 300_000 });
+    if (!result.ok) return { ran, ok: false };
+  }
+
+  if (!ghState().gitConfigured) {
+    ran.push('gh auth setup-git');
+    const result = run(binary, ['auth', 'setup-git']);
+    if (!result.ok) { debug('gh auth setup-git failed', result.error); return { ran, ok: false }; }
+  }
+  return { ran, ok: ghState().authed };
+}

package/sync/index.mjs

@@ -25,9 +25,11 @@ import { identity } from '../runtime/identity.mjs';
 import { loadRollup, coveredDays } from '../analytics/rollup.mjs';
 import { localDay, shiftDay } from '../analytics/ranges.mjs';
 import { sanitise, manifestFor } from './share.mjs';
+import { encode as encodeInvite } from './invite.mjs';
 import {
-  transportFor, listDevices, readJsonFile, writeJsonFile, removeFile,
+  transportFor, listDevices, readJsonFile, writeJsonFile, removeFile, git,
 } from './transport.mjs';
+import { rmSync } from 'node:fs';
 import { writeFileSync, renameSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { debug } from '../runtime/log.mjs';
@@ -192,6 +194,83 @@ export function readPool({ root = poolRoot(), days = null } = {}) {
   return peers;
 }
 
+/**
+ * An invite for this pool, for the owner to send.
+ *
+ * Carries the repository address and a label — never a credential. Who may join
+ * is decided by the repository's collaborator list, which is the only place that
+ * decision can be revoked from.
+ */
+export function inviteCode({ from = null } = {}) {
+  const team = teamConfig();
+  if (!team.enabled || !team.repo) throw new Error('sharing is off — join or create a pool first');
+  return encodeInvite({
+    repo: team.repo,
+    transport: team.transport ?? 'git',
+    pool: poolName(),
+    from: from ?? identity().name,
+  });
+}
+
+/** A readable label for the pool, taken from the repository name. */
+export function poolName() {
+  const repo = teamConfig().repo ?? '';
+  const last = repo.replace(/\.git$/, '').split(/[/\\:]/).filter(Boolean).pop();
+  return last || 'pool';
+}
+
+/**
+ * Remove someone's shelf from the pool.
+ *
+ * This is the ONE operation that deliberately writes outside our own directory,
+ * and it is an explicit administrative act rather than part of any sync. Git
+ * permissions are per-repository, so anyone with write access could already do
+ * this by hand; having a command for it means it is done correctly — the folder
+ * removed, the change pushed — instead of half-done.
+ *
+ * It removes them from view, not from history. Earlier commits still hold the
+ * data and anyone who pulled before still has a copy. The caller is expected to
+ * have said so before calling this.
+ *
+ * @returns {{removed: boolean, name: string|null, pushed: boolean, error: string|null}}
+ */
+export function removeDevice(target, { push = true } = {}) {
+  const root = poolRoot();
+  const me = identity();
+
+  const peers = readPool({ root });
+  const match = peers.find((peer) => peer.deviceId === target)
+    ?? peers.find((peer) => peer.name?.toLowerCase() === String(target).toLowerCase());
+
+  if (!match) return { removed: false, name: null, pushed: false, error: `no machine called "${target}" in the pool` };
+  if (match.deviceId === me.deviceId) {
+    // Deleting your own shelf while still publishing would simply re-create it
+    // on the next sync, which looks like the command silently failed.
+    return { removed: false, name: match.name, pushed: false, error: 'that is this machine — use `syndes team leave` instead' };
+  }
+
+  const shelf = teamDeviceDir(root, match.deviceId);
+  const relative = `devices/${match.deviceId}`;
+
+  if ((teamConfig().transport ?? 'git') !== 'git') {
+    try { rmSync(shelf, { recursive: true, force: true }); } catch (error) { return { removed: false, name: match.name, pushed: false, error: error.message }; }
+    return { removed: true, name: match.name, pushed: true, error: null };
+  }
+
+  const removed = git(root, ['rm', '-r', '--quiet', '--', relative]);
+  if (!removed.ok) return { removed: false, name: match.name, pushed: false, error: removed.error };
+
+  const committed = git(root, ['commit', '-m', `syndes: remove ${match.name} from the pool`, '--', relative]);
+  if (!committed.ok) return { removed: true, name: match.name, pushed: false, error: committed.error };
+
+  if (!push) return { removed: true, name: match.name, pushed: false, error: null };
+
+  const transport = transportFor('git');
+  transport.pull(root);
+  const pushed = git(root, ['push', 'origin', 'HEAD'], 25_000);
+  return { removed: true, name: match.name, pushed: pushed.ok, error: pushed.ok ? null : pushed.error };
+}
+
 // ── One cycle ───────────────────────────────────────────────────────────────
 
 /**

package/sync/invite.mjs

@@ -0,0 +1,70 @@
+/**
+ * Invites: one string that carries everything a new machine needs to join.
+ *
+ * The alternative is a paragraph of instructions — "install this, then run that,
+ * paste this URL, use your own GitHub" — which is where onboarding goes to die.
+ * An invite collapses it into a line the inviter copies and the joiner pastes.
+ *
+ * ── An invite is NOT a credential ──────────────────────────────────────────
+ * It carries a repository address and a label, nothing else. Access is decided
+ * entirely by whether GitHub lets that person in, which the repository owner
+ * controls with collaborator permissions and can revoke. Encoding a token here
+ * would mean the inviter's own credentials travelling through a chat app, which
+ * is exactly the practice this tool should not be teaching. So the invite is
+ * base64 for tidiness, not for secrecy, and it is safe to say so out loud.
+ */
+
+const PREFIX = 'syndes1_';
+const VERSION = 1;
+
+/**
+ * @param {{repo: string, transport: 'git'|'folder', pool?: string, from?: string}} details
+ * @returns {string}
+ */
+export function encode({ repo, transport = 'git', pool = null, from = null }) {
+  if (!repo) throw new Error('an invite needs a repository');
+  const body = { v: VERSION, r: repo, t: transport };
+  if (pool) body.p = pool.slice(0, 60);
+  if (from) body.f = from.slice(0, 40);
+  return PREFIX + Buffer.from(JSON.stringify(body), 'utf8').toString('base64url');
+}
+
+/**
+ * Decode, tolerating what people actually paste — surrounding quotes, a stray
+ * backtick from a chat app, the whole command line rather than just the code.
+ *
+ * @returns {{repo, transport, pool, from}|null} null when it is not an invite
+ */
+export function decode(input) {
+  if (typeof input !== 'string') return null;
+
+  let text = input.trim().replace(/^[`'"]+|[`'"]+$/g, '');
+  const found = /syndes1_[A-Za-z0-9_-]+/.exec(text);
+  if (found) text = found[0];
+  if (!text.startsWith(PREFIX)) return null;
+
+  try {
+    const body = JSON.parse(Buffer.from(text.slice(PREFIX.length), 'base64url').toString('utf8'));
+    if (body.v !== VERSION || typeof body.r !== 'string' || !body.r) return null;
+    return {
+      repo: body.r,
+      transport: body.t === 'folder' ? 'folder' : 'git',
+      pool: typeof body.p === 'string' ? body.p : null,
+      from: typeof body.f === 'string' ? body.f : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The line an inviter sends. Two steps, because the install must be global. */
+export function commandFor(code) {
+  return `npm install -g syndes && syndes join ${code}`;
+}
+
+/** True for anything that looks like an invite, so `join` can accept a raw URL too. */
+export function looksLikeInvite(input) {
+  return typeof input === 'string' && input.includes(PREFIX);
+}
+
+export { PREFIX };