@bitpub/cli 2.0.1 → 2.0.3

package/bin/bitpub.js

@@ -39,6 +39,7 @@ require('../src/commands/delete')(program);
 
 // ── Setup (rare, agent-invoked) ─────────────────────────────────────────────
 require('../src/commands/setup')(program);
+require('../src/commands/group')(program);
 require('../src/commands/alias')(program);
 require('../src/commands/seed')(program);
 require('../src/commands/browser')(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitpub/cli",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "BitPub CLI — local-first shared memory for AI agents. Six daily verbs (save/load/list/find/sync/delete), zero-config private namespace, encrypted client-side.",
   "bin": {
     "bitpub": "./bin/bitpub.js"

package/src/api.js

@@ -2,74 +2,106 @@
 
 const axios = require('axios');
 
+const { groupEntryFor } = require('./config');
+
 /**
- * Create an API client bound to a specific config.
- * All methods throw on non-2xx responses (axios default behavior).
- */
-/**
- * Pick the right API key for a given HCU.
- * Private namespaces use the personal api_key provisioned by `bitpub init`.
- * Group/public namespaces use group_key set by `bitpub auth login`, falling
- * back to api_key so single-key setups keep working.
+ * Resolve the backend (`url` + `key`) to use for a given HCU.
+ *
+ *   private:<owner>/...   → primary api_url + api_key from config
+ *   group:<slug>/...      → matching entry in config.groups[]
+ *                           (falls back to legacy top-level group_key/domain
+ *                           for the single-domain enterprise install)
+ *   public/...            → primary api_url + api_key
+ *   bare patterns         → same as primary (used for sync of mixed scopes)
+ *
+ * Throws if the HCU points at a group the caller isn't a member of —
+ * surfacing this at request time means the user gets a clear message
+ * ("Not a member of bitpub://group:foo") instead of an opaque 401.
  */
-function keyForHcu(config, hcu) {
-  if (typeof hcu === 'string' && hcu.startsWith('bitpub://private:')) {
-    return config.api_key;
+function resolveBackend(config, hcu) {
+  const baseUrl = (config.api_url || 'http://localhost:8080').replace(/\/$/, '');
+  const fallback = { url: baseUrl, key: config.api_key, source: 'primary' };
+
+  if (typeof hcu !== 'string') return fallback;
+
+  // Extract the group slug if this is a group-scoped HCU.
+  const m = hcu.match(/^bitpub:\/\/group:([^/]+)/);
+  if (!m) return fallback;
+
+  const slug = m[1];
+
+  // New flow: look in config.groups[] for a matching entry.
+  const entry = groupEntryFor(config, slug);
+  if (entry && entry.key) {
+    return {
+      url: (entry.api_url || baseUrl).replace(/\/$/, ''),
+      key: entry.key,
+      source: 'group',
+      slug,
+    };
+  }
+
+  // Legacy single-domain enterprise flow: pre-v2 deploys had a top-level
+  // group_key + domain. The lazy migration in config.js mirrors these
+  // into config.groups[], so this branch should rarely fire after the
+  // first read — kept for completeness.
+  if (config.group_key && config.domain && config.domain === slug) {
+    return { url: baseUrl, key: config.group_key, source: 'legacy-group', slug };
   }
-  return config.group_key || config.api_key;
+
+  // No matching key. Two reasonable behaviors:
+  //   - fall through to primary (will get a 403 from the server)
+  //   - throw here with a clearer message
+  // We pick the second so the user gets actionable feedback.
+  const err = new Error(
+    `Not a member of bitpub://group:${slug}/. Ask the group owner for an invite link, then run: bitpub join <link>`
+  );
+  err.code = 'NOT_A_MEMBER';
+  throw err;
 }
 
+/**
+ * Create an API client bound to a specific config.
+ *
+ * Each method resolves the backend (url + key) from the HCU it's about
+ * to operate on. Group-scoped HCUs route through `config.groups[]` to
+ * the host backend with the per-group key; private/public HCUs use the
+ * top-level `api_url` + `api_key`.
+ *
+ * All methods throw on non-2xx responses (axios default behavior, wrapped
+ * by the response interceptor so errors carry the server-side message).
+ */
 function createApiClient(config) {
-  const baseURL = (config.api_url || 'http://localhost:8080').replace(/\/$/, '');
-
-  const http = axios.create({
-    baseURL,
-    timeout: 30_000,
-  });
-
-  // Surface server-side error messages cleanly, preserving response for callers
-  http.interceptors.response.use(
-    res => res,
-    err => {
-      const msg = err.response?.data?.error || err.message;
-      const status = err.response?.status;
-      const wrapped = new Error(status ? `[${status}] ${msg}` : msg);
-      wrapped.status = status;
-      wrapped.response = err.response;
-      return Promise.reject(wrapped);
-    }
-  );
+  function http(backend) {
+    const inst = axios.create({
+      baseURL: backend.url,
+      timeout: 30_000,
+      headers: { 'x-api-key': backend.key },
+    });
+    inst.interceptors.response.use(
+      (res) => res,
+      (err) => {
+        const msg = err.response?.data?.error || err.message;
+        const status = err.response?.status;
+        const wrapped = new Error(status ? `[${status}] ${msg}` : msg);
+        wrapped.status = status;
+        wrapped.response = err.response;
+        return Promise.reject(wrapped);
+      }
+    );
+    return inst;
+  }
 
   return {
-    /**
-     * Pull context slices from the remote ledger.
-     * @param {string} hcu
-     * @param {number} [limit]
-     * @param {object} [opts]
-     * @param {boolean} [opts.includeDeleted]  surface tombstoned slices
-     * @param {boolean} [opts.mine]            filter to slices written by this key
-     * @returns {Promise<Array>} array of slice DTOs
-     */
     async pull(hcu, limit = 50, opts = {}) {
+      const backend = resolveBackend(config, hcu);
       const params = { hcu, limit };
       if (opts.includeDeleted) params.include_deleted = 'true';
       if (opts.mine) params.mine = 'true';
-      const res = await http.get('/v1/context/pull', {
-        params,
-        headers: { 'x-api-key': keyForHcu(config, hcu) },
-      });
+      const res = await http(backend).get('/v1/context/pull', { params });
       return res.data;
     },
 
-    /**
-     * Push a context slice to the remote ledger.
-     * @param {object} body  Full ContextSlice payload
-     * @param {object} [opts]
-     * @param {boolean} [opts.append]    append instead of overwrite
-     * @param {number}  [opts.expectVersion]  reject with 409 on version mismatch
-     * @param {boolean} [opts.force]     un-tombstone a deleted slice with new content
-     * @returns {Promise<{success: boolean, slice: object}>}
-     */
     async push(body, opts = {}) {
       // Back-compat: older callers passed (body, append, expectVersion) as
       // positional args. Detect that shape and translate to the opts object.
@@ -81,79 +113,42 @@ function createApiClient(config) {
       if (append) params.append = 'true';
       if (force) params.force = 'true';
       if (expectVersion != null) params.expect_version = String(expectVersion);
-      const res = await http.post('/v1/context/push', body, {
-        params,
-        headers: { 'x-api-key': keyForHcu(config, body?.hcu) },
-      });
+      const backend = resolveBackend(config, body?.hcu);
+      const res = await http(backend).post('/v1/context/push', body, { params });
       return res.data;
     },
 
-    /**
-     * List immediate children of an HCU path.
-     * @param {string} hcu
-     * @param {object} [opts]
-     * @param {boolean} [opts.includeDeleted]  return tombstone provenance
-     * @returns {Promise<{children: string[] | Array<{hcu: string, deleted_at: string|null, deleted_by: string|null}>}>}
-     */
     async list(hcu, opts = {}) {
+      const backend = resolveBackend(config, hcu);
       const params = { hcu };
       if (opts.includeDeleted) params.include_deleted = 'true';
-      const res = await http.get('/v1/context/list', {
-        params,
-        headers: { 'x-api-key': keyForHcu(config, hcu) },
-      });
+      const res = await http(backend).get('/v1/context/list', { params });
       return res.data;
     },
 
-    /**
-     * Soft-delete an exact context slice. Bumps version (active(N) →
-     * deleted(N+1)). The server preserves the row's payload so a no-content
-     * restore can undelete it. Re-dropping an already-tombstoned slice is
-     * idempotent.
-     */
     async drop(hcu, opts = {}) {
+      const backend = resolveBackend(config, hcu);
       const params = { hcu };
       if (opts.expectVersion != null) params.expect_version = String(opts.expectVersion);
-      const res = await http.delete('/v1/context/drop', {
-        params,
-        headers: { 'x-api-key': keyForHcu(config, hcu) },
-      });
+      const res = await http(backend).delete('/v1/context/drop', { params });
       return res.data;
     },
 
-    /**
-     * Restore a tombstoned slice in place using the server's preserved
-     * payload. Bumps version (deleted(N) → active(N+1)). Returns 409 if
-     * the slice is already active; 404 if it never existed.
-     */
     async restore(hcu, opts = {}) {
+      const backend = resolveBackend(config, hcu);
       const params = { hcu };
       if (opts.expectVersion != null) params.expect_version = String(opts.expectVersion);
-      const res = await http.post('/v1/context/restore', null, {
-        params,
-        headers: { 'x-api-key': keyForHcu(config, hcu) },
-      });
+      const res = await http(backend).post('/v1/context/restore', null, { params });
       return res.data;
     },
 
-    /**
-     * Open an SSE heartbeat stream and invoke onSync(evt) for each sync event.
-     * Each `evt` is a `{ hcu, deleted? }` object — the optional `deleted: true`
-     * hint tells callers the slice was tombstoned (so they can evict from
-     * any local cache without a refetch).
-     *
-     * For backward compatibility with any caller that expected just an HCU
-     * string, the `evt` argument is documented as the new shape and callers
-     * should detect `evt.deleted` to short-circuit refetch.
-     *
-     * Returns a cleanup function that closes the connection.
-     */
     watch(hcuPattern, onSync, onError) {
       const EventSource = require('eventsource');
-      const url = `${baseURL}/v1/context/heartbeat?hcu_pattern=${encodeURIComponent(hcuPattern)}`;
+      const backend = resolveBackend(config, hcuPattern);
+      const url = `${backend.url}/v1/context/heartbeat?hcu_pattern=${encodeURIComponent(hcuPattern)}`;
 
       const es = new EventSource(url, {
-        headers: { 'x-api-key': keyForHcu(config, hcuPattern) },
+        headers: { 'x-api-key': backend.key },
       });
 
       es.addEventListener('sync', (event) => {
@@ -174,4 +169,4 @@ function createApiClient(config) {
   };
 }
 
-module.exports = { createApiClient };
+module.exports = { createApiClient, resolveBackend };

package/src/commands/group.js

@@ -0,0 +1,333 @@
+'use strict';
+
+/**
+ * `bitpub group` — manage groups (shared namespaces).
+ *
+ *   bitpub group create "Acme Engineering"   create a group, print invite link
+ *   bitpub group list                        show groups I'm in
+ *   bitpub group invite <slug>               rotate the share link (or --show to peek)
+ *   bitpub group leave <slug>                leave a group
+ *
+ * Plus the top-level shortcut for the joiner persona — see `bitpub join`,
+ * which is registered as its own top-level command in this file.
+ *
+ * Encryption: group content is plaintext on whatever server hosts the
+ * group (only `private:` slices are client-side encrypted). This is by
+ * design — full-text search, ltree queries, and BYOC audit all need the
+ * server to be able to read group content.
+ */
+
+const axios = require('axios');
+const {
+  readConfig,
+  requireConfig,
+  upsertGroupEntry,
+  removeGroupEntry,
+  groupEntryFor,
+  DEFAULT_CLOUD_URL,
+} = require('../config');
+
+function trimSlash(s) {
+  return String(s || '').replace(/\/+$/, '');
+}
+
+function primaryApiUrl(config) {
+  return trimSlash(config.api_url || DEFAULT_CLOUD_URL);
+}
+
+/**
+ * Parse a join input that may be either a raw invite token or a full
+ * invite URL (e.g. https://bitpub.io/j/9k3lp2-...). Returns:
+ *   { token, baseUrl|null }
+ * where baseUrl is the backend the invite lives on (so cross-backend
+ * joins talk to the right host without any local config tweak).
+ */
+function parseJoinInput(input) {
+  if (!input || typeof input !== 'string') {
+    throw new Error('join: token or invite URL is required');
+  }
+  const trimmed = input.trim();
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    const u = new URL(trimmed);
+    const parts = u.pathname.split('/').filter(Boolean);
+    // Accept both /join/<token> (canonical) and the legacy /j/<token> form
+    // so older invite links keep working during the rename.
+    if ((parts[0] !== 'join' && parts[0] !== 'j') || !parts[1]) {
+      throw new Error(`join: not a recognized invite URL: ${trimmed}`);
+    }
+    return { token: parts[1], baseUrl: `${u.protocol}//${u.host}` };
+  }
+  return { token: trimmed, baseUrl: null };
+}
+
+async function httpJson(method, url, { headers, body } = {}) {
+  try {
+    const res = await axios.request({
+      method,
+      url,
+      timeout: 30_000,
+      headers: { 'content-type': 'application/json', ...(headers || {}) },
+      data: body,
+    });
+    return res.data;
+  } catch (err) {
+    const status = err.response?.status;
+    const msg = err.response?.data?.error || err.message;
+    const wrapped = new Error(status ? `[${status}] ${msg}` : msg);
+    wrapped.status = status;
+    throw wrapped;
+  }
+}
+
+// ── group create ───────────────────────────────────────────────────────────
+
+async function createGroup(display) {
+  const config = requireConfig();
+  if (!config.api_key) {
+    throw new Error('Group creation requires a personal identity. Run `bitpub setup` first.');
+  }
+  const baseUrl = primaryApiUrl(config);
+
+  const data = await httpJson('POST', `${baseUrl}/v1/groups`, {
+    headers: { 'x-api-key': config.api_key },
+    body: { display },
+  });
+
+  // Creators are auto-added to memberships server-side. Mirror the entry
+  // locally so subsequent `bitpub save bitpub://group:.../...` calls hit
+  // the right backend with the same personal key (creator stays on
+  // their own key; the per-group-key mint happens at *accept* time, not
+  // create time, since the creator already has a key on this backend).
+  upsertGroupEntry({
+    slug: data.slug,
+    display: data.display,
+    api_url: baseUrl,
+    key: config.api_key,
+    owner: config.owner || null,
+    role: 'owner',
+    joined_at: new Date().toISOString(),
+  });
+
+  return { ...data, invite_url: data.invite_url, base_url: baseUrl };
+}
+
+// ── group list ─────────────────────────────────────────────────────────────
+
+async function listGroupsLocal() {
+  const config = readConfig() || {};
+  return Array.isArray(config.groups) ? config.groups : [];
+}
+
+// ── group invite (rotate / show) ───────────────────────────────────────────
+
+async function rotateInvite(slug, { show } = {}) {
+  const config = requireConfig();
+  const entry = groupEntryFor(config, slug);
+  if (!entry) {
+    throw new Error(`Not a member of group "${slug}". Run \`bitpub group list\` to see your groups.`);
+  }
+  if (show) {
+    throw new Error('--show is not yet implemented (server does not expose the current token to non-creators by design). Use `bitpub group invite <slug>` to rotate and get a fresh URL.');
+  }
+  const baseUrl = trimSlash(entry.api_url) || primaryApiUrl(config);
+  const data = await httpJson('POST', `${baseUrl}/v1/groups/${encodeURIComponent(slug)}/invites`, {
+    headers: { 'x-api-key': entry.key },
+  });
+  return data;
+}
+
+// ── group leave ────────────────────────────────────────────────────────────
+
+async function leaveGroup(slug) {
+  const config = requireConfig();
+  const entry = groupEntryFor(config, slug);
+  if (!entry) {
+    // Already not in this group locally. Treat as a no-op (idempotent).
+    return { slug, left: false, reason: 'not-in-local-config' };
+  }
+  const baseUrl = trimSlash(entry.api_url) || primaryApiUrl(config);
+  try {
+    await httpJson('DELETE', `${baseUrl}/v1/groups/${encodeURIComponent(slug)}/members/me`, {
+      headers: { 'x-api-key': entry.key },
+    });
+  } catch (err) {
+    // 404 = server already considers us gone; proceed to clean up locally.
+    if (err.status !== 404) throw err;
+  }
+  removeGroupEntry(slug);
+  return { slug, left: true };
+}
+
+// ── bitpub join <token-or-url> ─────────────────────────────────────────────
+//
+// The recipient-side verb. Public, doesn't require a pre-existing identity
+// on the host backend — the invite token is the capability. After accept,
+// stores a new entry in config.groups[] with the fresh per-group key
+// minted by the backend.
+
+async function joinFromInvite(input) {
+  const { token, baseUrl: baseFromUrl } = parseJoinInput(input);
+  const config = readConfig() || {};
+  const baseUrl = baseFromUrl
+    ? trimSlash(baseFromUrl)
+    : primaryApiUrl(config);
+
+  // Optionally include the existing personal key — this lets same-backend
+  // joins inherit the existing owner_id so the user looks like one person
+  // across all their groups on that backend.
+  const headers = {};
+  if (config.api_key && (!baseFromUrl || trimSlash(baseFromUrl) === primaryApiUrl(config))) {
+    headers['x-api-key'] = config.api_key;
+  }
+
+  const data = await httpJson('POST', `${baseUrl}/v1/groups/invites/${encodeURIComponent(token)}/accept`, {
+    headers,
+  });
+
+  upsertGroupEntry({
+    slug: data.group.slug,
+    display: data.group.display,
+    api_url: baseUrl,
+    key: data.api_key,
+    owner: data.owner_id,
+    role: 'member',
+    joined_at: new Date().toISOString(),
+  });
+
+  return { ...data, base_url: baseUrl };
+}
+
+// ── command registration ──────────────────────────────────────────────────
+
+module.exports = function registerGroup(program) {
+  const group = program
+    .command('group')
+    .description('Create, manage, and leave shared groups');
+
+  group
+    .command('create <name...>')
+    .description('Create a new group; prints a shareable invite link')
+    .action(async (nameParts) => {
+      const display = nameParts.join(' ').trim();
+      if (!display) {
+        console.error('Usage: bitpub group create "Acme Engineering"');
+        process.exit(1);
+      }
+      try {
+        const out = await createGroup(display);
+        console.log(`\n✓ Created group: ${out.display}`);
+        console.log(`  Slug      : ${out.slug}`);
+        console.log(`  Hosted on : ${out.hosted_on}`);
+        console.log(`  Address   : bitpub://group:${out.slug}/`);
+        console.log(`\n  Share this link with teammates:`);
+        console.log(`    ${out.invite_url}`);
+        console.log(`\n  Anyone who clicks it lands on a friendly install + join page —`);
+        console.log(`  technical or not, they're ready to collaborate in a minute.`);
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  group
+    .command('list')
+    .description('Show the groups you are a member of (local view)')
+    .action(async () => {
+      try {
+        const entries = await listGroupsLocal();
+        if (entries.length === 0) {
+          console.log('You are not in any groups yet.');
+          console.log('\n  Create one:  bitpub group create "My Team"');
+          console.log('  Join one:    bitpub join <invite-link>');
+          return;
+        }
+        for (const e of entries) {
+          const label = e.display || e.slug;
+          const tag = e.legacy ? '  [legacy]' : '';
+          console.log(`  ${label}${tag}`);
+          console.log(`    slug    : ${e.slug}`);
+          console.log(`    address : bitpub://group:${e.slug}/`);
+          console.log(`    backend : ${e.api_url || '(default)'}`);
+          if (e.role) console.log(`    role    : ${e.role}`);
+        }
+      } catch (err) {
+        console.error(`✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  group
+    .command('invite <slug>')
+    .description('Rotate the shareable invite link for a group')
+    .option('--show', '[not yet implemented] Show the current link without rotating it')
+    .action(async (slug, opts) => {
+      try {
+        const out = await rotateInvite(slug, opts);
+        console.log(`\n✓ Rotated invite for ${out.display || out.slug}`);
+        console.log(`\n  New share link:`);
+        console.log(`    ${out.invite_url}`);
+        console.log(`\n  Old links (if any) are now invalid.`);
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  group
+    .command('leave <slug>')
+    .description('Leave a group (revokes your per-group key on the host)')
+    .action(async (slug) => {
+      try {
+        const out = await leaveGroup(slug);
+        if (out.left) console.log(`✓ Left group: ${slug}`);
+        else console.log(`(Not in group "${slug}" locally — nothing to do.)`);
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // ── group join — longhand alias of top-level `bitpub join` ─────────────
+  group
+    .command('join <tokenOrUrl>')
+    .description('Accept an invite (longhand for `bitpub join`)')
+    .action(async (tokenOrUrl) => {
+      try {
+        const out = await joinFromInvite(tokenOrUrl);
+        console.log(`\n✓ Joined group: ${out.group.display}`);
+        console.log(`  Address : bitpub://group:${out.group.slug}/`);
+        console.log(`  Backend : ${out.base_url}`);
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // ── top-level `bitpub join` — the joiner one-liner ─────────────────────
+  program
+    .command('join <tokenOrUrl>')
+    .description('Accept a group invite link (or token) and start collaborating')
+    .action(async (tokenOrUrl) => {
+      try {
+        const out = await joinFromInvite(tokenOrUrl);
+        console.log(`\n✓ Joined group: ${out.group.display}`);
+        console.log(`  Address : bitpub://group:${out.group.slug}/`);
+        console.log(`  Backend : ${out.base_url}`);
+        console.log(`\nTry it:`);
+        console.log(`  bitpub save bitpub://group:${out.group.slug}/hello "first message"`);
+        console.log(`  bitpub list bitpub://group:${out.group.slug}/`);
+      } catch (err) {
+        console.error(`\n✗ ${err.message}`);
+        process.exit(1);
+      }
+    });
+};
+
+module.exports._internals = {
+  parseJoinInput,
+  createGroup,
+  joinFromInvite,
+  rotateInvite,
+  leaveGroup,
+};

package/src/commands/init.js

@@ -15,6 +15,7 @@ const {
   ensureIdentity,
   ensureWorkspace,
   ensureSkill,
+  runFirstRunWelcome,
 } = require('./setup');
 const { DEFAULT_CLOUD_URL } = require('../config');
 
@@ -27,6 +28,7 @@ module.exports = function registerInit(program) {
     .option('--no-workspace', 'Skip creating a .bitpub/workspace.json in the current folder')
     .option('--workspace-label <string>', 'Override the workspace label (defaults to folder name)')
     .option('--force', 'Overwrite an existing identity (the old key is unrecoverable)')
+    .option('--no-welcome', 'Skip the post-install welcome (save first memory + open browser)')
     .option('--import-from <path>', 'Import an existing TollBit config')
     .option('--no-import', 'Skip auto-import')
     .action(async (opts) => {
@@ -41,6 +43,9 @@ module.exports = function registerInit(program) {
           ensureWorkspace({ owner: config.owner, label: opts.workspaceLabel });
         }
         await ensureSkill({});
+        if (config && !opts.localOnly && opts.welcome !== false) {
+          await runFirstRunWelcome(config);
+        }
       } catch (err) {
         console.error(`\n✗ ${err.message}`);
         process.exit(1);

package/src/commands/setup.js

@@ -23,6 +23,7 @@
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
+const { spawn } = require('child_process');
 const axios = require('axios');
 const {
   readConfig,
@@ -169,6 +170,65 @@ async function ensureSkill({ quiet = false } = {}) {
   }
 }
 
+/**
+ * First-run welcome: save the Welcome slice and (if interactive) open the
+ * browser to view it. Shared by `bitpub setup` and the deprecated
+ * `bitpub init` so any install path lands the user in the same place.
+ *
+ * Idempotent through welcome.js's `welcome_saved_at` config flag. The
+ * browser tab only opens on a *fresh* save (so re-running setup doesn't
+ * pop new tabs forever); when the slice already exists we just print a
+ * pointer to `bitpub browser`.
+ *
+ * Auto-open is gated:
+ *   - `BITPUB_SKIP_WELCOME=1`  → skip
+ *   - non-TTY stdout (CI, headless agents w/o pty) → skip with a pointer
+ *   - otherwise → spawn `bitpub welcome --serve` detached so the server
+ *     outlives this process and the user gets their shell back.
+ */
+async function runFirstRunWelcome(config) {
+  const { saveWelcomeSlice } = require('./welcome');
+
+  let result;
+  try {
+    result = await saveWelcomeSlice(config, {});
+  } catch (err) {
+    console.error(`\n(welcome: could not save first memory — ${err.message})`);
+    return;
+  }
+
+  // Re-run on an already-welcomed machine — quietly skip the browser
+  // open so a `bitpub setup` re-invocation isn't disruptive.
+  if (!result.saved) return;
+
+  console.log(`\n✓ Saved your first memory → ${result.address}  (v${result.version})`);
+
+  const skipReason = welcomeSkipReason();
+  if (skipReason) {
+    console.log(`  (skipping auto browser open: ${skipReason})`);
+    console.log('  Run `bitpub welcome --serve` to open it when you\'re ready.');
+    return;
+  }
+
+  try {
+    const child = spawn(process.execPath, [process.argv[1], 'welcome', '--serve'], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    console.log('  Opening your browser at http://localhost:4141 …');
+  } catch (err) {
+    console.error(`  (could not auto-open browser: ${err.message})`);
+    console.error('  Run `bitpub welcome --serve` manually.');
+  }
+}
+
+function welcomeSkipReason() {
+  if (process.env.BITPUB_SKIP_WELCOME === '1') return 'BITPUB_SKIP_WELCOME=1';
+  if (!process.stdout.isTTY) return 'non-interactive shell';
+  return null;
+}
+
 module.exports = function registerSetup(program) {
   const setup = program
     .command('setup')
@@ -178,6 +238,7 @@ module.exports = function registerSetup(program) {
     .option('--no-anchor', 'Skip anchoring this folder as a project')
     .option('--label <string>', 'Override the project label (defaults to folder name)')
     .option('--force', 'Overwrite an existing identity (the old key is unrecoverable after this)')
+    .option('--no-welcome', 'Skip the post-install welcome (save first memory + open browser)')
     .option('--import-from <path>', 'Import an existing TollBit config (defaults to ~/.tollbit/config.json if present)')
     .option('--no-import', 'Skip auto-import even if a legacy ~/.tollbit/ config is present')
     .action(async (opts) => {
@@ -191,6 +252,15 @@ module.exports = function registerSetup(program) {
           ensureWorkspace({ owner: config.owner, label: opts.label });
         }
         await ensureSkill({});
+
+        // Welcome flow: save a first memory + open the browser. Idempotent
+        // and gated — re-running `bitpub setup` doesn't keep popping tabs.
+        // Skipped in --local-only (no cloud identity to write to) and when
+        // the user opted out via --no-welcome or BITPUB_SKIP_WELCOME=1.
+        if (config && !opts.localOnly && opts.welcome !== false) {
+          await runFirstRunWelcome(config);
+        }
+
         console.log('\nTry it:');
         console.log('  bitpub save notes "first slice"');
         console.log('  bitpub list                       # see what\'s in this project');
@@ -201,23 +271,36 @@ module.exports = function registerSetup(program) {
     });
 
   // ── setup team … ────────────────────────────────────────────────────
-  // Joins (or rejoins) a team namespace. Today: requires --key + --domain
-  // from a team admin. Future: --invite <token> in lieu of those, once
-  // server-side invite generation lands.
+  // Legacy: join a tenant by pre-shared key + domain. Kept working for
+  // existing enterprise / BYOC deployments. New users use `bitpub join
+  // <invite-link>` instead — that flow mints a fresh per-user key
+  // instead of sharing one.
   setup
     .command('team')
-    .description('Join a team namespace (key + domain from your team admin)')
-    .requiredOption('--key <string>', 'Team API key provided by your team admin')
-    .requiredOption('--domain <string>', 'Your organization domain (e.g. acme.com)')
+    .description('[legacy] Join a group by shared key + domain — prefer `bitpub join <invite-link>`')
+    .requiredOption('--key <string>', 'Group API key provided by your group admin')
+    .requiredOption('--domain <string>', 'Group domain (e.g. acme.com) — used as the group slug')
     .option('--url <string>', 'Backend URL (defaults to current api_url or https://bitpub.io)')
     .option('--verify', 'Ping the backend to verify the key before saving')
     .action(async ({ key, domain, url, verify }) => {
       const existing = readConfig() || {};
       const apiUrl = url || existing.api_url || DEFAULT_CLOUD_URL;
 
+      // Build a temporary config the API client will see, with this group
+      // already mirrored into config.groups[] so the verify-pull picks the
+      // right per-group key+url.
+      const probeConfig = {
+        ...existing,
+        api_url: apiUrl,
+        groups: [
+          ...(Array.isArray(existing.groups) ? existing.groups : []).filter((g) => g.slug !== domain),
+          { slug: domain, display: domain, api_url: apiUrl, key, legacy: true },
+        ],
+      };
+
       if (verify) {
         try {
-          const api = createApiClient({ group_key: key, api_url: apiUrl });
+          const api = createApiClient(probeConfig);
           await api.pull(`bitpub://group:${domain}/**`, 1);
           console.log('✓ Key verified against backend');
         } catch (err) {
@@ -226,14 +309,25 @@ module.exports = function registerSetup(program) {
         }
       }
 
-      writeConfig({ ...existing, group_key: key, domain, api_url: apiUrl });
+      // Persist into the new groups[] shape as well as the legacy top-level
+      // fields. Keeping the top-level fields around for one release means
+      // any external script that reads config.group_key keeps working; the
+      // next release can drop them.
+      writeConfig({
+        ...existing,
+        group_key: key,
+        domain,
+        api_url: apiUrl,
+        groups: probeConfig.groups,
+      });
       initCache();
 
-      console.log(`✓ Joined team ${domain}`);
+      console.log(`✓ Joined group ${domain}`);
       console.log(`  Backend : ${apiUrl}`);
       if (existing.owner) {
         console.log(`  Private : agent_${existing.owner} (preserved)`);
       }
+      console.error('warning: `bitpub setup team` is the legacy flow. New invites use `bitpub join <link>` instead.');
       console.log('\nNext: bitpub sync "bitpub://group:' + domain + '/**"');
     });
 
@@ -310,3 +404,4 @@ function maybeImportLegacyConfig({ quiet = false } = {}) {
 module.exports.ensureIdentity = ensureIdentity;
 module.exports.ensureWorkspace = ensureWorkspace;
 module.exports.ensureSkill = ensureSkill;
+module.exports.runFirstRunWelcome = runFirstRunWelcome;

package/src/commands/welcome.js

@@ -80,8 +80,8 @@ function buildWelcomeContent(config) {
     'Generate a link teammates can click to join your group namespace and',
     'read shared context. No GitHub invites, no repo access, no PRs.',
     '',
-    '> *One-click sharing coming soon. Today: `bitpub auth login --domain',
-    '> yourcompany.com` joins an existing team namespace.*',
+    '> *One-click sharing coming soon. Today: `bitpub setup team --key K',
+    '> --domain yourcompany.com` joins an existing team namespace.*',
     '',
     '### 3. See what you can build',
     '',
@@ -89,7 +89,7 @@ function buildWelcomeContent(config) {
     'can put here — research notes, prompts, drafts, agent configs, job',
     'queues. Multiple agents can read and write the same slices.',
     '',
-    '> Read the [Cookbook](https://github.com/tollbit/shared-memory-protocol/blob/main/COOKBOOK.md)',
+    '> Read the [Cookbook](https://github.com/tollbit/bitpub/blob/main/COOKBOOK.md)',
     '> for real patterns teams have built on top of these primitives.',
     '',
     '---',

package/src/config.js

@@ -21,11 +21,51 @@ function ensureDir() {
 }
 
 function readConfig() {
+  let parsed;
   try {
-    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+    parsed = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
   } catch {
     return null;
   }
+  return _migrateLegacyGroupFieldsInPlace(parsed);
+}
+
+/**
+ * Lazy one-shot migration of the pre-v2 top-level `group_key` + `domain`
+ * fields into a single entry in the new `groups` array. We keep the
+ * top-level fields for one release as a safety net so any caller that
+ * still reads them keeps working — they'll be dropped in a follow-up.
+ *
+ * Idempotent: if a matching entry already exists in `groups`, we do
+ * nothing. Only persists back to disk when an actual change was made.
+ */
+function _migrateLegacyGroupFieldsInPlace(config) {
+  if (!config || typeof config !== 'object') return config;
+  if (!Array.isArray(config.groups)) config.groups = [];
+
+  const hasLegacyTopLevel = config.group_key && config.domain;
+  if (!hasLegacyTopLevel) return config;
+
+  const alreadyMigrated = config.groups.some((g) => g && g.slug === config.domain);
+  if (alreadyMigrated) return config;
+
+  config.groups.push({
+    slug: config.domain,
+    display: config.domain,
+    api_url: config.api_url,
+    key: config.group_key,
+    owner: config.owner || null,
+    joined_at: new Date().toISOString(),
+    legacy: true,
+  });
+
+  try {
+    ensureDir();
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+  } catch {
+    // Non-fatal: in-memory copy is still correct for this process.
+  }
+  return config;
 }
 
 function writeConfig(config) {
@@ -35,16 +75,55 @@ function writeConfig(config) {
 
 /**
  * Identity is valid if api_url is present and at least one of these is true:
- *   - private identity: api_key + owner  (provisioned by `bitpub init`)
- *   - group identity:   group_key + domain  (set by `bitpub auth login`)
- *   - legacy single-key: api_key + domain  (old config shape, still supported)
+ *   - private identity:  api_key + owner    (provisioned by `bitpub setup`)
+ *   - group membership:  any entry in groups[]  (added by `bitpub join`)
+ *   - legacy group key:  group_key + domain  (pre-v2 top-level fields)
+ *   - legacy single-key: api_key + domain    (oldest single-tenant shape)
  */
 function isConfigured(config) {
   if (!config || !config.api_url) return false;
   const hasPrivate = Boolean(config.api_key && config.owner);
-  const hasGroup   = Boolean(config.group_key && config.domain);
-  const hasLegacy  = Boolean(config.api_key && config.domain);
-  return hasPrivate || hasGroup || hasLegacy;
+  const hasGroup   = Array.isArray(config.groups) && config.groups.length > 0;
+  const hasLegacyG = Boolean(config.group_key && config.domain);
+  const hasLegacyS = Boolean(config.api_key && config.domain);
+  return hasPrivate || hasGroup || hasLegacyG || hasLegacyS;
+}
+
+/**
+ * Look up the local config entry for a given group slug. Returns null if
+ * the user isn't a member. Used by the API client to route writes to the
+ * correct backend with the correct per-group key.
+ */
+function groupEntryFor(config, slug) {
+  if (!config || !Array.isArray(config.groups)) return null;
+  return config.groups.find((g) => g && g.slug === slug) || null;
+}
+
+/**
+ * Add (or replace) a group entry in the config. Idempotent — re-joining
+ * an existing group overwrites the prior entry (which is what happens
+ * server-side too: accept-invite mints a fresh key, the old one is left
+ * orphaned but still works).
+ */
+function upsertGroupEntry(entry) {
+  if (!entry || !entry.slug) throw new Error('upsertGroupEntry: slug is required');
+  const config = readConfig() || {};
+  if (!Array.isArray(config.groups)) config.groups = [];
+  const idx = config.groups.findIndex((g) => g && g.slug === entry.slug);
+  if (idx === -1) config.groups.push(entry);
+  else config.groups[idx] = { ...config.groups[idx], ...entry };
+  writeConfig(config);
+  return config;
+}
+
+function removeGroupEntry(slug) {
+  const config = readConfig() || {};
+  if (!Array.isArray(config.groups)) return false;
+  const idx = config.groups.findIndex((g) => g && g.slug === slug);
+  if (idx === -1) return false;
+  config.groups.splice(idx, 1);
+  writeConfig(config);
+  return true;
 }
 
 /**
@@ -79,6 +158,9 @@ module.exports = {
   requireConfig,
   isConfigured,
   authorIdFor,
+  groupEntryFor,
+  upsertGroupEntry,
+  removeGroupEntry,
   BITPUB_DIR,
   CONFIG_FILE,
   DEFAULT_CLOUD_URL,