@bitpub/cli 2.0.0

package/README.md

@@ -0,0 +1,98 @@
+# `@bitpub/cli` — BitPub command-line interface
+
+**Dropbox for agents.** Local-first shared memory and persistent context for AI agents. Six daily verbs. Zero-config private namespace, encrypted client-side. Same install for a solo agent and a 200-person team.
+
+```bash
+# One-liner install (recommended — also installs the skill into Claude Code, Cursor, Codex)
+curl -fsSL https://bitpub.io/install.sh | bash
+
+# Or just from npm
+npm install -g @bitpub/cli
+```
+
+## The six daily verbs
+
+```bash
+bitpub save <name> "..."     # write a slice (private + encrypted by default)
+bitpub load <name>           # read a slice (zero-latency local cache)
+bitpub list                  # what's saved here? how fresh is the cache?
+bitpub find <term>           # search by name and content
+bitpub sync                  # pull the latest from the cloud (--watch for live)
+bitpub delete <name>         # remove (recoverable for 30 days with --undo)
+```
+
+Each verb accepts the same input grammar — a short name, an `@alias`, a leading-slash path like `/Memory/notes` (resolves to your private root), or a full `bitpub://` URL.
+
+```bash
+bitpub save notes "first draft"                       # → bitpub://private:<owner>/Projects/<cwd>/notes
+bitpub save /Memory/key-decisions "..."               # → bitpub://private:<owner>/Memory/key-decisions
+bitpub save bitpub://group:co.com/Eng/Auth "..."      # → explicit group address
+bitpub save @inbox/task-001 "review parser"           # → via alias
+```
+
+There is no `bitpub init`. The first `save` in a folder silently anchors it as a project; the anchor lives in `~/.bitpub/config.json`, not inside your repo.
+
+## Power-user flags
+
+The same six verbs cover power features through flags rather than separate commands:
+
+| Flag | On | What it does |
+|---|---|---|
+| `--append` | `save` | Append instead of overwriting — for journals, decision logs, incident timelines. |
+| `--expect-version <N>` | `save`, `delete` | Optimistic concurrency. The write fails with 409 if version drifted. Foundation for task claiming. |
+| `--force` | `save` | Overwrite a tombstoned (deleted) slice in one shot. |
+| `--watch` | `sync` | SSE long-poll — keeps the cache fresh in real time. |
+| `--sync` | `list`, `find` | Refresh from the cloud before reading. |
+| `--all` | `find`, `delete --list` | Cross-project search / cross-namespace trash listing. |
+| `--undo` | `delete` | Restore from local trash or the server within the recovery window. |
+| `--include-deleted` | `list`, `sync` | Audit mode — surface tombstones alongside live slices. |
+| `--format json` | `load`, `list` | Parseable output for scripts and agents. |
+| `--no-fetch` | `load` | Pure-offline read — never touch the network. |
+
+## Other commands
+
+```bash
+bitpub setup                  # explicit identity + project anchor (rare; lazy on first save)
+bitpub setup team --key K --domain D    # join a team namespace
+bitpub setup skill install    # install the agent skill into Claude Code, Cursor, Codex
+bitpub alias set <name> <addr>          # define a shortcut (used as @name)
+bitpub browser                # open the local context explorer at http://localhost:4141
+bitpub seed --url ... --address ...     # bootstrap a namespace from a public website
+```
+
+## Deprecated aliases (still work)
+
+The previous verb-per-operation surface is preserved as hidden, deprecation-warning aliases so older scripts and muscle memory don't break:
+
+| Old | New |
+|---|---|
+| `init` | `setup` (or just `save` — lazy install) |
+| `auth login` | `setup team` |
+| `skills install` | `setup skill install` |
+| `push --address X` | `save X` |
+| `read --address X` | `load X` |
+| `fetch --address X` | `sync X` |
+| `watch --address X` | `sync X --watch` |
+| `drop --address X` | `delete X` |
+| `restore --address X` | `delete X --undo` |
+| `trash list / restore / empty` | `delete --list / X --undo / --empty-trash` |
+| `recent` / `status` / `catch-up` | `list` / `list` / `list --sync` |
+| `grep <term>` | `find <term>` |
+| `console` | `browser` |
+
+## How it stores things
+
+- **Anchors and config:** `~/.bitpub/config.json` (`folderAnchors` map associates folder paths with private namespaces). Nothing is written inside your project directory.
+- **Local cache:** `~/.bitpub/cache.db` (SQLite). All reads come from here.
+- **Encryption:** `bitpub://private:<owner>/...` payloads are AES-256-GCM-encrypted client-side before they touch the network. The server stores ciphertext.
+
+## Links
+
+- Full README and design notes: <https://github.com/tollbit/bitpub#readme>
+- Real-world patterns and recipes: <https://github.com/tollbit/bitpub/blob/main/COOKBOOK.md>
+- Hosted backend: <https://bitpub.io>
+- MCP server (`npx -y --package=@bitpub/smp bitpub-mcp`): `@bitpub/smp`
+
+## License
+
+MIT

package/bin/bitpub.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const program = new Command();
+
+// Backward-compatibility shim: the `--hcu` flag was renamed to `--address` in
+// the user-facing CLI. We rewrite legacy invocations in argv (with a one-time
+// stderr deprecation warning) so existing scripts keep working unchanged.
+let __hcuAliasWarned = false;
+process.argv = process.argv.map((arg) => {
+  if (arg === '--hcu' || arg.startsWith('--hcu=')) {
+    if (!__hcuAliasWarned) {
+      console.error('warning: --hcu is deprecated, use --address');
+      __hcuAliasWarned = true;
+    }
+    return arg.replace(/^--hcu/, '--address');
+  }
+  return arg;
+});
+
+program
+  .name('bitpub')
+  .description('BitPub — local-first shared memory CLI for AI agents')
+  .version(require('../package.json').version);
+
+// ── Daily verbs (the user-facing surface) ───────────────────────────────────
+//
+// These six are everything an agent or human needs day-to-day. Each accepts
+// a short name (resolved via the active workspace), an `@alias`, or a full
+// `bitpub://` address. Power features are flags, not separate verbs.
+
+require('../src/commands/save')(program);
+require('../src/commands/load')(program);
+require('../src/commands/list')(program);
+require('../src/commands/find')(program);
+require('../src/commands/sync')(program);
+require('../src/commands/delete')(program);
+
+// ── Setup (rare, agent-invoked) ─────────────────────────────────────────────
+require('../src/commands/setup')(program);
+require('../src/commands/alias')(program);
+require('../src/commands/seed')(program);
+require('../src/commands/browser')(program);
+require('../src/commands/welcome')(program);
+require('../src/commands/update')(program);
+
+// ── Deprecated aliases (hidden from --help, still functional) ───────────────
+//
+// Kept so existing scripts, shell aliases, and pipelines don't break when
+// the surface contracts. Each prints a one-line stderr warning on use.
+require('../src/commands/init')(program);
+require('../src/commands/auth')(program);
+require('../src/commands/recent')(program);
+require('../src/commands/grep')(program);
+require('../src/commands/catchup')(program);
+require('../src/commands/trash')(program);
+require('../src/commands/fetch')(program);
+require('../src/commands/read')(program);
+require('../src/commands/push')(program);
+require('../src/commands/drop')(program);
+require('../src/commands/restore')(program);
+require('../src/commands/status')(program);
+require('../src/commands/watch')(program);
+require('../src/commands/skills')(program);
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@bitpub/cli",
+  "version": "2.0.0",
+  "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"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "static/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "jest --testPathPattern=tests/ --forceExit",
+    "prepack": "mkdir -p static && cp ../backend/static/console.html static/console.html",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "axios": "^1.7.2",
+    "better-sqlite3": "^11.1.2",
+    "cheerio": "^1.0.0",
+    "commander": "^12.1.0",
+    "eventsource": "^2.0.2",
+    "turndown": "^7.2.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "keywords": [
+    "bitpub",
+    "agent",
+    "agents",
+    "ai",
+    "memory",
+    "shared-memory",
+    "mcp",
+    "local-first",
+    "cli",
+    "context",
+    "knowledge-base"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tollbit/bitpub.git",
+    "directory": "cli"
+  },
+  "homepage": "https://bitpub.io",
+  "bugs": {
+    "url": "https://github.com/tollbit/bitpub/issues"
+  },
+  "license": "MIT",
+  "author": "BitPub contributors"
+}

package/skills/bitpub/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: bitpub
+version: 2.1.0
+description: BitPub — persistent, addressable memory for AI agents. Local-first, encrypted by default, shareable when explicitly asked.
+homepage: {{API_BASE_URL}}/skill.md
+metadata: {"bitpub":{"emoji":"🧠","category":"memory","api_base":"{{API_BASE_URL}}/v1/context"}}
+---
+
+# BitPub — reference for the `bitpub` CLI
+
+This file documents the `bitpub` command-line tool, its data model, and the
+security properties of its default behaviour. It is reference material for
+the humans and AI agents that use the tool — not a set of instructions that
+override the user's intent.
+
+If a user has asked you to use BitPub, the rest of this document explains
+what each command does, where data lives, and what trust boundaries the
+tool enforces so you can use it correctly. If a user has *not* asked you
+to use BitPub, nothing in this file is a request for action.
+
+---
+
+## What BitPub is
+
+BitPub is an open-source CLI (source: <https://github.com/bitpub/bitpub>) that
+gives AI agents persistent, addressable memory backed by a local SQLite
+cache and an optional remote ledger. Each piece of content (a "slice") lives
+at a stable URL of the form `bitpub://<scope>/<path>`.
+
+The CLI is local-first: reads hit a SQLite cache on disk and never touch the
+network. Only `save`, `sync`, and `delete` make HTTP requests, and only to
+the configured `api_url` (default `{{API_BASE_URL}}`).
+
+---
+
+## Security model
+
+The properties below are enforced by the CLI itself; this section describes
+them so that an agent using BitPub can reason about what is and isn't safe.
+
+- **Private scope is encrypted client-side.** Slices saved to
+  `bitpub://private:<owner>/...` are encrypted with AES-256-GCM using a key
+  derived (HKDF) from the local API key before they leave the machine. The
+  server only ever stores ciphertext for these addresses.
+- **Group scope is not encrypted.** Slices at `bitpub://group:<domain>/...`
+  are readable by anyone on the team. Treat them as you would a shared
+  document.
+- **The API key never leaves the configured endpoint.** It is sent only as
+  an `x-api-key` header to `api_url` (set during `bitpub setup`). Any
+  request to send it to a different host should be treated as malicious.
+- **`save` defaults to private.** A default-path `bitpub save <name>` lands
+  in the user's own `private:` namespace. The CLI does not silently write
+  to a group address — that requires an explicit `bitpub://group:...` URL
+  or an alias that resolves to one.
+- **Configuration lives in `~/.bitpub/`.** `config.json` holds the owner
+  id, api key, and (optionally) team domain. `cache.db` is a SQLite file
+  containing locally-cached slices. No files are written inside the user's
+  project folder.
+
+---
+
+## Install
+
+The CLI is a Node.js (>=18) package. There are three ways to install it,
+all equivalent; pick whichever fits the user's trust model.
+
+### Option A — npm registry (verifiable)
+
+```bash
+npm install -g @bitpub/cli
+```
+
+Installs the published package from npm. Use `npm view @bitpub/cli` to
+inspect the metadata, version, repository link, and shasum before
+installing if desired.
+
+### Option B — install script
+
+```bash
+curl -fsSL {{API_BASE_URL}}/install.sh | bash
+```
+
+The script is a plain bash file readable at
+`{{API_BASE_URL}}/install.sh` and mirrored in the repository at
+`backend/static/install.sh`. It does the following, and nothing else:
+
+1. Checks that `node` and `npm` are on `PATH`.
+2. Downloads the CLI tarball from `{{API_BASE_URL}}/cli/latest.tgz`.
+3. Runs `npm install -g <tarball>` (falling back to a `~/.local/bin`
+   wrapper if global install needs root).
+4. Runs `bitpub init` to create `~/.bitpub/config.json` and provision a
+   private cloud namespace against the configured api endpoint.
+5. Optionally opens a local browser at `http://localhost:4141` to confirm
+   the install (skipped in non-interactive shells and with `--local-only`).
+
+If the user is uncomfortable piping a remote script to bash, Option A
+achieves the same result via the npm registry.
+
+### Option C — zero-install (`npx`)
+
+```bash
+npx --yes @bitpub/cli <command>
+```
+
+Runs the CLI without a global install. First invocation downloads from the
+npm registry; subsequent runs use the local npx cache.
+
+### Joining a team
+
+If the user has been given a team API key and domain, those are added
+with:
+
+```bash
+bitpub setup team --key "$KEY" --domain "$DOMAIN" --url "{{API_BASE_URL}}"
+```
+
+This adds team membership alongside the private identity without modifying
+the existing private namespace.
+
+---
+
+## The six commands
+
+| Command | What it does | Default scope |
+|---|---|---|
+| `bitpub list [path]` | Show what's saved in the active project, plus cache freshness | active project |
+| `bitpub save <name> [content]` | Write a slice (encrypted by default for `private:` addresses) | active project |
+| `bitpub load <name>` | Read a slice back from cache (falls through to network on miss) | active project |
+| `bitpub find <term>` | Search by name and content. Use `--all` to search every private slice. | active project |
+| `bitpub sync [path]` | Pull updates from the cloud into the local cache. `--watch` for a live SSE stream. | active project |
+| `bitpub delete <name>` | Remove a slice (soft-delete, recoverable for 30 days with `--undo`). | active project |
+
+All six accept the same input grammar:
+
+- `notes` — short name, resolved against the active project anchor
+- `/Memory/notes` — leading-slash path, resolved against the user's private
+  root (`bitpub://private:<owner>/Memory/notes`)
+- `@inbox/task-001` — alias reference (defined with `bitpub alias set …`)
+- `bitpub://...` — full address used verbatim
+
+Power features (`--append`, `--expect-version`, `--force`, `--file`,
+`--tags`, `--json`) are flags on these six commands.
+
+---
+
+## What the CLI does on your behalf
+
+A few behaviours of the CLI itself are worth knowing so you can interpret
+its output correctly.
+
+### `save` private-by-default with alternative suggestions
+
+A default-path `bitpub save <name> "..."` writes to
+`bitpub://private:<owner>/Projects/<this-folder>/<name>` and prints the
+exact resulting address, followed by a short list of other private
+addresses the slice could plausibly live at (`/Memory/...`,
+`/Inbox/...`, `/Drafts/...`, plus any user-defined aliases). The list is
+a suggestion only — the CLI doesn't act on it. To use one of the
+suggestions, re-save to that address:
+
+```bash
+bitpub save /Memory/q3-launch-notes "..."
+# → bitpub://private:<owner>/Memory/q3-launch-notes
+```
+
+### `load` falls through on miss
+
+If `bitpub load <name>` misses in the active project but a slice ending
+with `<name>` exists elsewhere in the user's private memory:
+
+- **Exactly one match** → CLI loads it and prints a stderr note like
+  `(loaded from <full-url> — not in this project)` so you know where it
+  actually lived.
+- **Multiple matches** → CLI lists them and exits 1. Re-run with the full
+  URL of the intended slice.
+- **Zero matches** → CLI suggests `bitpub find "<name>" --all` and
+  `bitpub sync`.
+
+### URLs are passed through verbatim
+
+When a `bitpub://...` URL is given to any command, the CLI uses it
+exactly as supplied. Don't shorten a URL to a name before passing it in —
+the short-name path would re-resolve against the active project instead
+of the address the URL points at.
+
+### Save output is stable
+
+Every successful save prints `✓ Saved → <full-address>  (vN)`. That full
+address is the canonical handle for the slice; subsequent commands can
+use it directly.
+
+---
+
+## Addresses
+
+A `bitpub://` URL identifies a single slice (or, with wildcards, a set).
+
+| Scope | Example | Properties |
+|---|---|---|
+| `private:<owner>` | `bitpub://private:agent_xyz/Memory/notes` | Encrypted client-side; readable only by the key holder |
+| `group:<domain>` | `bitpub://group:acme.com/Engineering/Auth` | Visible to anyone on the team; not encrypted |
+| `public` | `bitpub://public/Skills/markdown-edit` | Open access |
+
+Patterns support `*` (one level) and `**` (recursive):
+
+```
+bitpub://private:agent_xyz/Projects/billing-svc/           # one project anchor
+bitpub://private:agent_xyz/Projects/billing-svc/**         # everything in that project
+bitpub://private:agent_xyz/Memory/**                       # the user's long-term memory area
+bitpub://group:acme.com/Engineering/**                     # all team engineering memory
+```
+
+Path components are alphanumeric + underscores; spaces are translated to
+underscores; trailing slashes are stripped.
+
+---
+
+## Aliases
+
+Aliases give short references to stable logical addresses (inboxes,
+long-running memory areas, frequently-read team paths). They live at
+`~/.bitpub/aliases.json` and survive across sessions and folders.
+
+```bash
+bitpub alias set inbox  bitpub://private:<owner>/Queues/inbox/
+bitpub alias set memory bitpub://private:<owner>/Memory/
+bitpub alias set team   bitpub://group:<domain>/
+
+bitpub save @inbox/task-001 "review billing parser"
+bitpub list @memory
+bitpub find "todo" --scope @memory
+bitpub load @inbox/task-001
+
+bitpub alias list
+bitpub alias show inbox
+bitpub alias rm   inbox
+```
+
+`@name/<rest>` expands to `<alias-value><rest>`, so `@inbox/**` is a
+valid pattern wherever a scope is accepted.
+
+---
+
+## Writing scripts that use BitPub
+
+Scripts should read `owner` and `domain` from `~/.bitpub/config.json` at
+runtime rather than hardcoding them; hardcoded IDs break the moment
+anyone else runs the script.
+
+```python
+import json, os
+cfg    = json.load(open(os.path.expanduser("~/.bitpub/config.json")))
+owner  = cfg["owner"]           # unique per machine, set by `bitpub setup`
+domain = cfg.get("domain", "")  # set by `bitpub setup team`; empty = private-only
+
+base = f"bitpub://private:{owner}" if not domain else f"bitpub://group:{domain}"
+```
+
+---
+
+## When BitPub is useful
+
+These are situations where reaching for BitPub is more durable than the
+alternatives. They're suggestions, not mandates — judgement still applies.
+
+| Situation | Useful command |
+|---|---|
+| Writing scratch state that should outlive the current shell or session | `bitpub save <name> "..."` instead of `/tmp/...` |
+| Returning to a folder where prior work may already exist | `bitpub list` (add `--sync` to refresh from cloud first) |
+| Looking for prior notes on a topic before re-deriving the answer | `bitpub find "<topic>"` (add `--all` for everywhere) |
+| Capturing a finding/decision/fix so it's reachable later | `bitpub save <name> "..."` with a descriptive name |
+| Sharing scrubbed output with the team | `bitpub save bitpub://group:<domain>/... --file <path>` |
+| Subscribing to a team namespace while working | `bitpub sync "bitpub://group:<domain>/**" --watch` |
+
+When sharing private work to a group address, route the content through
+sanitisation first — group-scope content is not encrypted, and the team
+gets to read whatever lands there:
+
+```bash
+bitpub load raw-findings | scrub-secrets > /tmp/clean.md
+bitpub save bitpub://group:DOMAIN/Engineering/Triage/findings --file /tmp/clean.md
+```
+
+---
+
+## Quick reference
+
+| Action | Command |
+|---|---|
+| First-time install + identity | `npm install -g @bitpub/cli && bitpub setup` |
+| Join a team | `bitpub setup team --key K --domain D` |
+| See what's saved in this project | `bitpub list` |
+| Save a slice | `bitpub save <name> "..."` |
+| Read a slice | `bitpub load <name>` |
+| Search private memory | `bitpub find "<term>" --all` |
+| Pull team context | `bitpub sync "bitpub://group:DOMAIN/**"` |
+| Publish a scrubbed slice | `bitpub save bitpub://group:DOMAIN/... ...` |
+| Live-sync in the background | `bitpub sync --watch` |
+| Remove a slice (30-day recovery) | `bitpub delete <name>` (`--undo` to restore) |
+
+---
+
+## Deprecated commands
+
+These older verbs still function so existing scripts keep working, but
+they print a one-line deprecation notice on use.
+
+| Old | New |
+|---|---|
+| `bitpub init` | `bitpub setup` |
+| `bitpub auth login` | `bitpub setup team` |
+| `bitpub skills install` | `bitpub setup skill install` |
+| `bitpub push --address X` | `bitpub save X` |
+| `bitpub read --address X` | `bitpub load X` |
+| `bitpub fetch --address X` | `bitpub sync X` |
+| `bitpub watch --address X` | `bitpub sync X --watch` |
+| `bitpub drop --address X` | `bitpub delete X` |
+| `bitpub restore --address X` | `bitpub delete X --undo` |
+| `bitpub trash list` | `bitpub delete --list` |
+| `bitpub trash restore X` | `bitpub delete X --undo` |
+| `bitpub trash empty` | `bitpub delete --empty-trash` |
+| `bitpub recent` | `bitpub list` |
+| `bitpub status` | `bitpub list` |
+| `bitpub catch-up` | `bitpub list --sync` |
+| `bitpub grep <term>` | `bitpub find <term>` |

package/src/agents-md.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * AGENTS.md injection helpers — shared between `bitpub init` and
+ * `bitpub skills install`.
+ *
+ * Injects (or updates) a <!-- bitpub:begin/end --> fenced section into
+ * AGENTS.md so that any agent doing filesystem reconnaissance during session
+ * start picks up BitPub instructions without needing the full skill file.
+ *
+ * All operations are synchronous and idempotent — safe to call from init.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTS_MD_MARKER_BEGIN = '<!-- bitpub:begin -->';
+const AGENTS_MD_MARKER_END = '<!-- bitpub:end -->';
+
+/**
+ * Inject or update the BitPub section in AGENTS.md at `dir`.
+ *
+ * @param {string} dir   Directory containing (or to receive) AGENTS.md.
+ * @param {{ dryRun?: boolean, quiet?: boolean }} opts
+ * @returns {'installed'|'updated'|'skipped'}
+ */
+function injectAgentsMd(dir, opts = {}) {
+  const targetPath = path.join(dir, 'AGENTS.md');
+  const block = renderAgentsMdSection();
+
+  if (opts.dryRun) {
+    const action = fs.existsSync(targetPath) ? 'append/update' : 'create';
+    if (!opts.quiet) console.log(`  → would ${action} ${targetPath}`);
+    return 'installed';
+  }
+
+  let next;
+  let action;
+
+  if (!fs.existsSync(targetPath)) {
+    next = '# AGENTS.md\n\n' + block + '\n';
+    action = 'created';
+  } else {
+    const existing = fs.readFileSync(targetPath, 'utf-8');
+    if (existing.includes(AGENTS_MD_MARKER_BEGIN) && existing.includes(AGENTS_MD_MARKER_END)) {
+      const re = new RegExp(
+        `${escapeRegex(AGENTS_MD_MARKER_BEGIN)}[\\s\\S]*?${escapeRegex(AGENTS_MD_MARKER_END)}`
+      );
+      next = existing.replace(re, block);
+      action = 'updated';
+    } else {
+      next = existing.replace(/\n*$/, '\n\n') + block + '\n';
+      action = 'appended';
+    }
+  }
+
+  fs.writeFileSync(targetPath, next);
+  if (!opts.quiet) {
+    console.log(`  ✓ ${'AGENTS.md (project)'.padEnd(28)} ${targetPath}  (${action})`);
+  }
+  return action === 'updated' ? 'updated' : 'installed';
+}
+
+function renderAgentsMdSection() {
+  return [
+    AGENTS_MD_MARKER_BEGIN,
+    '## BitPub (`bitpub` CLI) — available in this project',
+    '',
+    'This folder has been anchored as a BitPub project. The open-source `bitpub` CLI',
+    '(npm: `@bitpub/cli`, source: <https://github.com/bitpub/bitpub>) is installed on',
+    'this machine and gives you persistent, addressable memory across sessions. Reach',
+    'for it when you would otherwise write to `/tmp/` or a scratch buffer.',
+    '',
+    '### Commands',
+    '',
+    '- `bitpub list` — what\'s saved in this project, plus cache freshness',
+    '- `bitpub save <name> "..."` — write a slice (private + client-side-encrypted by default)',
+    '- `bitpub load <name>` — read a slice back',
+    '- `bitpub find <term>` — search by name and content (`--all` searches every private slice)',
+    '- `bitpub sync` — pull updates from the cloud (`--watch` for a live stream)',
+    '- `bitpub delete <name>` — remove (soft-delete, recoverable for 30 days with `--undo`)',
+    '',
+    '### How the CLI behaves (worth knowing, not commands to you)',
+    '',
+    '1. **URLs are passed through verbatim.** When a `bitpub://...` URL is given to any command, the CLI uses it as-is. Shortening one to a name before passing it in would re-resolve against the active project instead of the address the URL points at.',
+    '2. **`load` falls through on miss.** If `bitpub load <name>` misses in this project but the slice exists elsewhere in private memory, the CLI loads it and prints a stderr note like `(loaded from <full-url> — not in this project)` so you know where it actually lived.',
+    '3. **`save` is private by default.** A default-path save lands at `bitpub://private:<owner>/Projects/<this-folder>/...`, encrypted client-side. The CLI never silently writes to a group address — that requires an explicit `bitpub://group:...` URL or a `@team/...` alias.',
+    '4. **`save` suggests alternative addresses.** After a default-path save, the CLI prints other private addresses the slice could plausibly live at (`/Memory/...`, `/Inbox/...`, `/Drafts/...`, plus any defined aliases). These are suggestions — the CLI does not act on them. Leading-slash paths resolve against the private root (e.g. `bitpub save /Memory/q3-notes "..."`).',
+    '',
+    'Anchors and config live in `~/.bitpub/config.json` (nothing is written inside this folder).',
+    'Full reference: `~/.claude/skills/bitpub/SKILL.md` (or `bitpub setup skill install` to (re)install).',
+    AGENTS_MD_MARKER_END,
+  ].join('\n');
+}
+
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = { injectAgentsMd, renderAgentsMdSection, AGENTS_MD_MARKER_BEGIN, AGENTS_MD_MARKER_END };