borgmcp 3.6.3 → 3.8.0

package/src/docs-sections.ts

@@ -3,29 +3,24 @@
  *
  * `borg_docs` (index.ts) returns these sections so an agent can route a "how
  * does borgmcp work / setup / concept / tool" question to the right
- * repository-local document, then WebFetch the URL for the content. Pure data +
+ * public documentation page, then WebFetch the URL for the content. Pure data +
  * a lazy keyword match — NO server-side fetch, NO RAG/embeddings.
  *
- * This is a local-only client: every URL points at the public source repository
- * (its README + `docs/`), never a hosted product site.
- *
- * `page` is the repository-local file each section maps to (anti-drift anchor).
+ * Most topics route to borgmcp.ai; repository-resident operator detail routes
+ * to the public source repository.
  */
 
-export const DOCS_BASE_URL = "https://github.com/Byte-Ventures/borg-mcp-client";
-
-const README_URL = `${DOCS_BASE_URL}#readme`;
-const LOCAL_SERVER_URL = `${DOCS_BASE_URL}/blob/main/docs/LOCAL_SERVER.md`;
-const SEAT_LIFECYCLE_URL = `${DOCS_BASE_URL}/blob/main/docs/SEAT_LIFECYCLE.md`;
+const SITE_URL = "https://borgmcp.ai";
+const REPOSITORY_URL = "https://github.com/Byte-Ventures/borg-mcp-client";
+const LOCAL_SERVER_URL = `${REPOSITORY_URL}/blob/main/docs/LOCAL_SERVER.md`;
+const SEAT_LIFECYCLE_URL = `${REPOSITORY_URL}/blob/main/docs/SEAT_LIFECYCLE.md`;
 
 export interface DocsSection {
   /** logical topic key */
   slug: string;
   title: string;
-  /** repository-local document URL the agent should WebFetch */
+  /** public documentation URL the agent should WebFetch */
   url: string;
-  /** the repository file this section maps to (anti-drift anchor) */
-  page: string;
   summary: string;
   /** extra match terms for the topic lookup */
   keywords: string[];
@@ -35,82 +30,79 @@ export const DOCS_SECTIONS: DocsSection[] = [
   {
     slug: "overview",
     title: "Overview",
-    url: README_URL,
-    page: "README.md",
+    url: `${SITE_URL}/docs/`,
     summary: "What Borg MCP is + the cube / drone / role / log mental model.",
     keywords: ["overview", "what is", "intro", "mental model", "how it works", "start"],
   },
   {
     slug: "concepts",
     title: "Core concepts",
-    url: README_URL,
-    page: "README.md",
+    url: `${SITE_URL}/docs/concepts/`,
     summary: "Cubes, drones, roles, the activity log + signals, claims, decisions.",
     keywords: ["cube", "drone", "role", "log", "signal", "claim", "decision", "coordinate", "coordination"],
   },
   {
     slug: "install",
     title: "Install client",
-    url: README_URL,
-    page: "README.md",
+    url: `${SITE_URL}/get-started/`,
     summary: "Install the published Borg MCP client and verify the borg CLI.",
     keywords: ["install", "installation", "npm", "client", "borgmcp", "borg help", "claude code", "codex", "opencode"],
   },
   {
     slug: "run-server",
     title: "Run server",
-    url: LOCAL_SERVER_URL,
-    page: "docs/LOCAL_SERVER.md",
-    summary: "Run a self-hosted borgmcp-server: setup, start, endpoint, network configuration.",
-    keywords: ["server", "self-hosted", "borgmcp-server", "borg-mcp-server", "setup", "start", "listen port", "7091", "local server", "--lan", "tls"],
+    url: `${SITE_URL}/docs/run-server/`,
+    summary: "Run a self-hosted borgmcp-server: setup, start, private-LAN and TLS configuration.",
+    keywords: ["server", "self-hosted", "borgmcp-server", "borg-mcp-server", "setup", "start", "local server", "--lan", "tls"],
   },
   {
     slug: "enroll",
     title: "Enroll",
     url: LOCAL_SERVER_URL,
-    page: "docs/LOCAL_SERVER.md",
     summary: "Connect a client to a self-hosted server: invitations, assimilate --host --enroll, credentials.",
-    keywords: ["enroll", "enrollment", "invitation", "invite", "assimilate", "--host", "credential", "credentials", "owner", "join server"],
+    keywords: ["enroll", "enrollment", "invitation", "invite", "assimilate", "--host", "credential", "credentials", "owner", "join server", "add agent", "teammate"],
   },
   {
     slug: "seat-lifecycle",
     title: "Seat lifecycle and recovery",
     url: SEAT_LIFECYCLE_URL,
-    page: "docs/SEAT_LIFECYCLE.md",
     summary: "Saved-seat states, re-attach and reset recovery, duplicate-session guards, and deterministic multi-seat selection.",
     keywords: ["seat", "lifecycle", "reattach", "re-attach", "reset-local-connection", "evicted", "revoked", "superseded", "inbox monitor", "multiple seats", "silent deafness"],
   },
   {
     slug: "self-hosting",
     title: "Self-hosting operations",
-    url: LOCAL_SERVER_URL,
-    page: "docs/LOCAL_SERVER.md",
+    url: `${SITE_URL}/docs/self-hosting/`,
     summary: "Operate a self-hosted server: data directory, credential rotation and grants, capacity, backup, upgrades.",
-    keywords: ["self-hosting", "operations", "operate", "backup", "restore", "upgrade", "rotate", "revoke", "grant", "capacity", "data directory", "license"],
+    keywords: ["self-hosting", "operations", "operate", "backup", "restore", "upgrade", "rotate", "revoke", "grant", "capacity", "data directory", "dashboard", "monitoring", "observability"],
   },
   {
     slug: "cli",
     title: "CLI commands",
-    url: README_URL,
-    page: "README.md",
-    summary: "Client launch, sync, cleanup, worktree maintenance, and launch-all reference.",
-    keywords: ["cli", "command", "sync", "cleanup", "worktree", "launch", "launch-all", "terminal", "maintenance", "prune"],
+    url: `${SITE_URL}/docs/cli/`,
+    summary: "Client launch, cleanup, worktree maintenance, and launch-all reference.",
+    keywords: ["cli", "command", "cleanup", "worktree", "launch", "launch-all", "terminal", "maintenance", "prune"],
   },
   {
     slug: "tools",
     title: "Tool reference",
-    url: README_URL,
-    page: "README.md",
+    url: `${SITE_URL}/docs/tools/`,
     summary: "Every borg_* tool — name, description, params.",
     keywords: ["tool", "tools", "api", "reference", "param", "borg_"],
   },
   {
     slug: "faq",
     title: "FAQ",
-    url: README_URL,
-    page: "README.md",
-    summary: "Common questions — agents, coordination, worktrees, docs maturity, security.",
-    keywords: ["faq", "question", "agent", "claude", "codex", "opencode", "coordination", "worktree", "security", "reporting", "second agent"],
+    url: `${SITE_URL}/docs/faq/`,
+    summary: "Common questions — agents, coordination, worktrees, local setup, security, cost and licensing.",
+    keywords: ["faq", "question", "agent", "claude", "codex", "opencode", "coordination", "worktree", "security", "reporting", "second agent", "pricing", "cost", "free"],
+  },
+  {
+    slug: "license",
+    title: "License",
+    url: `${SITE_URL}/docs/license/`,
+    summary: "Licenses for the client, shared contracts, and self-hosted server.",
+    keywords: ["license", "licensing", "apache", "fsl", "source available"],
   },
 ];
 

package/src/regen-format.ts

@@ -554,11 +554,9 @@ export function formatRegenMarkdown(
     ? [
         '## Getting started',
         '',
-        'Welcome to your first cube. Here\'s how to get going:',
-        '',
-        '1. Post your first activity: `borg_log message="Starting work on <your task>"`',
-        '2. Invite another agent session: open a new terminal and run `borg assimilate --worktree <name>`',
-        '3. Check who\'s here: `borg_roster`',
+        '**You (this agent):** post `borg_log message="<task>"`; check `borg_roster`.',
+        '**Your user:** in a new terminal in the repository, add a teammate: `borg assimilate <role>`; optional `--worktree <name>` names its worktree.',
+        'For "what do I do next?", use `borg_docs`.',
         '',
         '---',
         '',

package/src/roster-render.ts

@@ -19,7 +19,7 @@ import { formatDroneAddressToken } from 'borgmcp-shared/drone-address';
 import { escapeSyncDisplay } from './sync-roles-render.js';
 
 export const RUNTIME_METADATA_ADVISORY =
-  'Agent CLI, reported model, and working repository are advisory. They do not determine authority, role, health, activity, wake behavior, or routing.';
+  "Agent CLI and reported model are advisory; they do not determine authority, role, health, activity, wake behavior, or routing. Working repository is the drone's home assignment for implementation work: route repository-specific implementation work to the drone homed in that repository, and drones do not take implementation work outside their home repository. These fields carry no server-side authority, and the server does not enforce repository homing.";
 
 export interface RosterDrone {
   id?: string;

package/src/tool-manifest.ts

@@ -4,9 +4,11 @@
  * The single canonical list of borg_* MCP tool definitions. The runtime and
  * documentation consumers use the same pure-data list.
  *
- * PURE DATA — no imports, no side effects — so documentation builds do not pull
- * in the client's MCP runtime dependencies.
+ * CONTRACT-BACKED DATA — imports only published scalar contract constants, with
+ * no client runtime side effects.
  */
+import { DECISION_TEXT_MAX_BYTES } from 'borgmcp-shared/protocol';
+
 export interface ToolManifestEntry {
   name: string;
   description: string;
@@ -128,7 +130,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_docs',
           description:
-            'Look up the Borg MCP documentation. Call this when the user asks how borgmcp works, or any feature / usage / setup / concept / tool question. Returns the docs index — each section\'s repository documentation URL + a one-line summary. Pass `topic` (e.g. "worktree", "roles", "codex") to get the best-matching section(s) instead of the full index. Then WebFetch the returned URL to read the page — borg_docs returns the index only, it does not fetch the page for you.',
+            'Look up the Borg MCP documentation. Call this when the user asks how borgmcp works, or any feature / usage / setup / concept / tool question. Returns the docs index — each section\'s documentation URL + a one-line summary. Pass `topic` (e.g. "worktree", "roles", "codex") to get the best-matching section(s) instead of the full index. Then WebFetch the returned URL to read the page — borg_docs returns the index only, it does not fetch the page for you.',
           inputSchema: {
             type: 'object',
             properties: {
@@ -262,11 +264,11 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
               },
               decision: {
                 type: 'string',
-                description: 'The ratified decision text. Max 2000 chars.',
+                description: `The ratified decision text. Max ${DECISION_TEXT_MAX_BYTES} UTF-8 bytes (bytes, not characters).`,
               },
               rationale: {
                 type: 'string',
-                description: 'Optional why. Max 2000 chars.',
+                description: `Optional why. Max ${DECISION_TEXT_MAX_BYTES} UTF-8 bytes (bytes, not characters).`,
               },
             },
           },
@@ -519,7 +521,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_list-drones',
           description:
-            'List every drone in a cube when this local client has a live read, write, or manage grant. Returns id, label, role_id, agent_kind, last_seen, advisory reported model, working repository, and wake_path_alert_class. Role labels affect workflow only and grant no server permission.',
+            'List every drone in a cube when this local client has a live read, write, or manage grant. Returns id, label, role_id, agent_kind, last_seen, advisory reported model, working repository home assignment for implementation work, and wake_path_alert_class. Route repository-specific implementation work to the drone homed in that repository; drones do not take implementation work outside their home repository. Repository homing and role labels grant no server permission, and the server does not enforce repository homing.',
           inputSchema: {
             type: 'object',
             properties: {