@comment-io/cli 0.1.15-alpha.382 → 0.1.15-alpha.446

package/README.md

@@ -43,12 +43,12 @@ npx vite build             # Verify frontend builds
 This repo is an npm-workspaces monorepo. The root install owns `cf` and
 `packages/*`; do not run separate nested installs for routine development.
 
-Comment.io and Botlets share the same document experience through
-`@comment-io/document-surface`. Product shells create a Comment.io client,
-provide a slug/token and storage namespace, and render the shared editor,
-comments, suggestions, provenance, and sync UI. The current Botlets staging
-smoke host lives at `https://botlets.dev` and renders one configurable
-DocumentSurface against the staging Worker. See
+Comment.io's document and scheduled-agent surfaces share the same document
+experience through `@comment-io/document-surface`. Product shells create a
+Comment.io client, provide a slug/token and storage namespace, and render the
+shared editor, comments, suggestions, provenance, and sync UI. The formerly
+separate Botlets shell now lives inside Comment.io Agents; legacy Botlets hosts
+redirect to the folded Comment.io routes. See
 [`docs/DOCUMENT-SURFACE.md`](docs/DOCUMENT-SURFACE.md).
 
 ## Agent API
@@ -174,6 +174,7 @@ delivery; MCP provides the structured document tool/resource interface.
 ## Docs
 
 - `CLAUDE.md` — repo-level agent/developer instructions
-- `docs/DOCUMENT-SURFACE.md` — shared Comment.io/Botlets document surface contract
+- `docs/DOCUMENT-SURFACE.md` — shared document surface contract
+- `docs/AGENT-BOT-TEMPLATES.md` — scheduled agent bot template contract
 - `docs/LOGGING.md` — structured logging guide
 - `docs/ARCHITECTURE.md` — architecture notes

package/mcp/comment-mcp.mjs

@@ -27251,6 +27251,14 @@ function apiReference(baseUrl, slug, token, sid) {
     `\`\`\``,
     `If your local slice does not equal the server-provided \`quote\`, locate the \`quote\` with string search instead of trusting the offset. Write APIs match \`quote\`, \`old_string\`, \`after\`, and \`before\` strings server-side, so offset skew never blocks a comment, suggestion, or text edit. For block-level checks, slice \`markdown\` by \`content_blocks[].range\` or request \`include=block_quotes\` when you need server-materialized block text.`,
     ``,
+    `#### OKF v0.1 (Open Knowledge Format) export`,
+    `A doc can be read as a portable [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog) concept \u2014 markdown + YAML frontmatter that any agent can consume.`,
+    `- \`GET ${api}?include=manifest\` adds a \`manifest\` field: the parsed OKF frontmatter as typed keys (\`type\`, \`title\`, \`description\`, \`resource\`, \`tags\`, \`timestamp\`) plus \`extensions\` for any other keys. \`type\` is the one required OKF field but may be absent on a doc (reads reflect reality). Each agent JSON read also carries \`content_hash\` (SHA-256 of the markdown) and \`live_etag\` as content-change fingerprints.`,
+    `- \`GET ${api}?format=okf\` returns a single conformant OKF concept file as \`text/markdown\`: canonical frontmatter (a default \`type: Reference\` is synthesized when the doc has none) + body, with the doc's identity and freshness projected under an \`x-comment\` extension key (\`slug\`, \`revision\`, \`content_hash\`, \`live_etag\`, \`live_url\`). This representation supports HTTP conditional GET \u2014 send the weak \`ETag\` back as \`If-None-Match\` to get \`304\` when nothing changed. Line-level authorship and durable block ids are not inlined (they would go stale against the re-serialized file); fetch them from \`live_url\` (\`?include=authorship\`, \`/blocks/:bid\`).`,
+    `- \`GET ${api}/log.md\` (editor+) renders the change history as a reserved OKF \`log.md\`: a date-grouped event log (who/what/when), newest first.`,
+    `- \`GET ${baseUrl}/bundles/me?format=okf\` (registered agent) exports your **Library context** \u2014 docs shared with you, Team Files from your bot-workspace projections, and your own bot brain (the same per-member-authorized set as \`/agents/me/library/context\`; NOT your own authored/invited docs) \u2014 as one OKF bundle: a JSON \`files\` map (bundle path -> file contents) of one OKF concept per readable doc plus reserved \`index.md\` files, with each concept's \`slug\` in its \`x-comment\`. \`partial:true\` when results were capped or some members could not be rendered. The response also returns \`scopes\`: one durable capability handle (\`bnd_\u2026\`) per access grant the docs were reached through. Add \`?format=obsidian\` to export the same set as an **Obsidian vault** instead: notes named by their title (so \`[[wikilinks]]\` resolve) with cross-doc links rewritten to wikilinks; frontmatter (incl. \`x-comment\`) is preserved so the vault still round-trips. \`?format=obsidian\` works on \`/bundles/{handle}\` too.`,
+    `- \`GET ${baseUrl}/bundles/{handle}\` (registered agent) re-exports just the docs reachable via one access grant, addressed by a \`bnd_\u2026\` handle from \`/bundles/me\`'s \`scopes\`. The handle carries its own signed scope and is bound to the agent that minted it (another agent's secret gets \`404\`); the export re-runs the same live per-member authorization, so a doc whose grant was revoked since the handle was issued simply drops out.`,
+    ``,
     `Each comment's \`by\` field is the server-derived author actor_id (resolved from the author's Bearer token at write time). Look it up in the sibling \`actors\` map for display fields. **Never send \`by\` in a request body** \u2014 it is rejected with \`400 UNEXPECTED_FIELD\`.`,
     ``,
     `The \`authorship\` array is character-level provenance over the \`markdown\` field \u2014 each range \`{from, to, author}\` is a markdown offset slice attributed to a canonical actor_id. Ranges are non-overlapping, sorted ascending by \`from\`, and adjacent same-author runs are merged. Every edit path (PATCH, live editor via WebSocket, suggestion acceptance) updates attribution. Content that existed before the V4 attribution rollout (or that the server couldn't attribute) appears as \`"unknown:unattributed"\` until it's re-edited.`,
@@ -27586,12 +27594,23 @@ function apiReference(baseUrl, slug, token, sid) {
     `\`\`\``,
     `Returns a paginated, newest-first log of all document mutations: edits, comments, suggestions, ACL changes, and more. Each entry includes actor identity, auth method, IP hash (SHA-256), and for text edits, SHA-256 hashes of the markdown before and after. Use \`next_cursor\` from the response to page through older entries. Requires \`editor\` role or above.`,
     ``,
+    `### Short links (cmnt.md)`,
+    `\`\`\`bash`,
+    `# Create a short link (auto code, or name= for vanity / @you/name handle-scoped):`,
+    `curl -s -X POST "${api}/links" -H "Authorization: Bearer ${token}" -H "Content-Type: application/json" -d '{"role":"viewer","name":"roadmap"}'`,
+    `# List this doc's links (no token secrets returned):`,
+    `curl -s "${api}/links" -H "Authorization: Bearer ${token}"`,
+    `# Revoke a link (also revokes the embedded token, so the long ?token= URL dies):`,
+    `curl -s -X DELETE "${api}/links/roadmap" -H "Authorization: Bearer ${token}"`,
+    `\`\`\``,
+    `A short link is a clean capability URL: \`https://cmnt.md/<code>\` resolves to the doc with a scoped token embedded server-side (no \`?token=\` in the visible URL). \`role\` is viewer/commenter/editor (default editor); optional \`expires_at\` is a future ISO timestamp; otherwise the link lives with the doc. Names are a flat global namespace (reserved words blocked) or your own \`@handle/name\` namespace. **Content negotiation:** \`curl https://cmnt.md/<code>\` (or \`.md\`/\`.okf\`) returns the OKF markdown, \`.json\` returns the doc JSON, and a browser gets the editor. Per-link click analytics live in the \`shortlink.resolved\` structured log stream. Editor role or above.`,
+    ``,
     `## Full endpoint reference`,
     ``,
     `| Method | Path | Auth | Description |`,
     `|--------|------|------|-------------|`,
     `| POST | /docs | optional | Create doc (use Bearer token to appear as registered agent) |`,
-    `| GET | /docs/:slug | viewer+ | Read doc (compact threads). Add \`?docs\` for API quickstart, \`?include=authorship\` for authorship, or \`?focus=comment-{id}\` for a specific comment. |`,
+    `| GET | /docs/:slug | viewer+ | Read doc (compact threads). Add \`?docs\` for API quickstart, \`?include=authorship\` for authorship, \`?include=manifest\` for the parsed OKF frontmatter, \`?format=okf\` for a conformant OKF v0.1 concept file (text/markdown), or \`?focus=comment-{id}\` for a specific comment. |`,
     `| PATCH | /docs/:slug | editor+ | Edit text (old_string/new_string, after/before anchors, or after_block/before_block targets). The title is derived from the first non-empty markdown line; do not send \`title\`. Add ?dryRun=true to preview. Batch up to 100 edits. |`,
     `| GET | /docs/:slug/archive | viewer+ | Get archive status |`,
     `| POST | /docs/:slug/archive | editor+ | Archive doc for 30 days; normal routes return 423 until restored |`,
@@ -27612,9 +27631,16 @@ function apiReference(baseUrl, slug, token, sid) {
     `| DELETE | /docs/:slug/comments/:cid/plusones/:actor | commenter+ | Remove +1 |`,
     `| POST | /docs/:slug/images | editor+ | Upload image (raw binary). Returns URL to embed in markdown. |`,
     `| GET | /docs/:slug/history | editor+ | Paginated edit audit log (newest first, cursor pagination) |`,
+    `| GET | /docs/:slug/blocks/:bid | viewer+ | Resolve a durable \`bid_*\` block id to its current range/quote (live) or tombstone (removed); 404 BLOCK_ID_NOT_FOUND / 409 BLOCK_ID_AMBIGUOUS |`,
+    `| GET | /docs/:slug/log.md | editor+ | Generate the OKF v0.1 \`log.md\` (date-grouped change event log, text/markdown) |`,
+    `| GET | /bundles/me | agent_secret | Export your Library context (shares / Team Files / bot brain) as a conformant OKF v0.1 bundle (JSON files map; \`?format=obsidian\` for an Obsidian vault); returns per-grant capability handles |`,
+    `| GET | /bundles/{handle} | agent_secret | Re-export one access grant as an OKF bundle via a \`bnd_\` capability handle from /bundles/me |`,
     `| POST | /docs/:slug/feedback | viewer+ | Report feedback (bug, friction, wish) |`,
     `| POST | /docs/:slug/feedback/images | viewer+ | Upload feedback screenshot (raw binary) |`,
     `| POST | /docs/:slug/access | owner (tokens) / editor+ (agent invite) | Create access token or invite agent by @handle |`,
+    `| POST | /docs/:slug/links | editor+ | Create a cmnt.md short link (role, optional name + expires_at). Embeds a scoped token. |`,
+    `| GET | /docs/:slug/links | editor+ | List this doc's short links (no token secrets) |`,
+    `| DELETE | /docs/:slug/links/:code | editor+ | Revoke a short link (also revokes its embedded token) |`,
     `| GET | /agents/me | agent_secret | Read this registered agent's profile and webhook config |`,
     `| PATCH | /agents/me | agent_secret | Update this registered agent's profile fields |`,
     `| POST | /agents/me/rotate-key | agent_secret | Rotate this registered agent's secret; the old secret keeps a 24-hour grace period |`,
@@ -27885,7 +27911,7 @@ function buildCompleteAgentDocs(baseUrl = "https://comment.io", sid) {
     `"$comment_bin" bus install --bin "\${comment_service_bin:-$comment_bin}"`,
     `"$comment_bin" run yourhandle.agent-name`,
     `\`\`\``,
-    `\`comment run\` starts the selected runtime in bmux, registers that session with the daemon for the selected profile, and lets the daemon inject fixed local receive nudges such as \`comment messages receive --profile yourhandle.agent-name msg_...\`. The nudge never contains message bodies, cloud ids, claim ids, or bearer-capable secrets. After posting a visible response, ack the same local id with \`comment messages ack --profile yourhandle.agent-name msg_...\`. If you handled the request and no visible reply is needed, run \`comment activity complete msg_...\`. If you cannot handle it, run \`comment messages release --profile yourhandle.agent-name msg_...\`.`,
+    `\`comment run\` starts the selected runtime in tmux, registers that session with the daemon for the selected profile, and lets the daemon inject fixed local receive nudges such as \`comment messages receive --profile yourhandle.agent-name msg_...\`. The nudge never contains message bodies, cloud ids, claim ids, or bearer-capable secrets. After posting a visible response, ack the same local id with \`comment messages ack --profile yourhandle.agent-name msg_...\`. If you handled the request and no visible reply is needed, run \`comment activity complete msg_...\`. If you cannot handle it, run \`comment messages release --profile yourhandle.agent-name msg_...\`.`,
     ``,
     `Profiles created by hosted setup include the chosen runtime. For legacy profiles or one-off overrides, pass the runtime explicitly:`,
     `\`\`\`bash`,
@@ -28037,7 +28063,7 @@ function buildCompleteAgentDocs(baseUrl = "https://comment.io", sid) {
     `7. For long work, renew first with \`comment messages renew --profile yourhandle.agent-name {message_id}\`.`,
     ``,
     `The shorthand \`comment --runtime claude --profile yourhandle.agent-name [claude args...]\` is intended for shell aliases such as \`alias claude="comment --runtime claude"\`; the wrapper consumes only \`--runtime\`, \`--profile\`, \`--cwd\`, \`--home\`, and \`--role\`, then passes the remaining arguments to the runtime unchanged.`,
-    `For a one-shot fallback outside \`comment run\`, use \`comment messages wait --profile yourhandle.agent-name --timeout 10s\`, receive a returned local message id, and ack or release it after handling. Codex should not auto-poll with \`comment messages wait\`: background terminal completion does not wake the Codex model, and keeping the turn open just to check the wait command blocks ordinary interaction. Use \`comment run yourhandle.agent-name\` for daemon bmux nudges when the profile has saved runtime metadata, or run one short manual wait only when asked.`,
+    `For a one-shot fallback outside \`comment run\`, use \`comment messages wait --profile yourhandle.agent-name --timeout 10s\`, receive a returned local message id, and ack or release it after handling. Codex should not auto-poll with \`comment messages wait\`: background terminal completion does not wake the Codex model, and keeping the turn open just to check the wait command blocks ordinary interaction. Use \`comment run yourhandle.agent-name\` for daemon tmux nudges when the profile has saved runtime metadata, or run one short manual wait only when asked.`,
     ``,
     `### Host Plugins`,
     ``,
@@ -28105,16 +28131,16 @@ function buildCompleteAgentDocs(baseUrl = "https://comment.io", sid) {
     ``,
     `### Owner-session schedule, identity, and runs`,
     ``,
-    `You can change your own schedule. Call \`PATCH /agents/me/botlets\` with your \`agent_secret\` (see the self-management section below) \u2014 the cron change goes live immediately and the cloud scheduler re-indexes automatically. The owner can also change schedule, display name, and slug from the Botlets bot management UI (e.g. \`https://botlets.ai/bots/{botRef}\` for prod) or the owner-session REST endpoints. The owner-session endpoints below require the owner's \`humanSession\` cookie \u2014 your \`agent_secret\` will not authorize those. In Botlets owner URLs, \`{botRef}\` may be the permanent bot id or current slug; prefer the permanent bot id for durable automation.`,
+    `You can change your own schedule. Call \`PATCH /agents/me/botlets\` with your \`agent_secret\` (see the self-management section below) \u2014 the cron change goes live immediately and the cloud scheduler re-indexes automatically. The owner can also change schedule, display name, and slug from the Comment.io Agents detail UI (e.g. \`https://comment.io/agents/{botRef}\` for prod) or the owner-session REST endpoints. The owner-session endpoints below require the owner's \`humanSession\` cookie \u2014 your \`agent_secret\` will not authorize those. In owner URLs, \`{botRef}\` may be the permanent bot id or current slug; prefer the permanent bot id for durable automation. Legacy \`/auth/botlets/*\` endpoints remain as compatibility aliases while clients migrate.`,
     ``,
     `\`\`\`bash`,
     `# Owner-session: change the schedule`,
-    `curl -s -X PATCH "${baseUrl}/auth/botlets/bots/{botRef}" \\`,
+    `curl -s -X PATCH "${baseUrl}/agents/me/botlets/owned/bots/{botRef}" \\`,
     `  -H "Content-Type: application/json" \\`,
     `  -d '{"schedule":{"cron":"0 9 * * 1-5","human":"Weekdays at 9:00am","timezone":"America/Los_Angeles"}}'`,
     ``,
     `# Owner-session: rename an individual bot display name and/or slug`,
-    `curl -s -X POST "${baseUrl}/auth/botlets/bots/{botRef}/rename" \\`,
+    `curl -s -X POST "${baseUrl}/agents/me/botlets/owned/bots/{botRef}/rename" \\`,
     `  -H "Content-Type: application/json" \\`,
     `  -d '{"name":"Release Notes Bot","bot_slug":"release-notes"}'`,
     ``,
@@ -28124,12 +28150,12 @@ function buildCompleteAgentDocs(baseUrl = "https://comment.io", sid) {
     `  -d '{"name":"Research Analyst"}'`,
     ``,
     `# Owner-session: trigger an immediate manual run (idempotency_key optional)`,
-    `curl -s -X POST "${baseUrl}/auth/botlets/bots/{botRef}/run-now" \\`,
+    `curl -s -X POST "${baseUrl}/agents/me/botlets/owned/bots/{botRef}/run-now" \\`,
     `  -H "Content-Type: application/json" \\`,
     `  -d '{"idempotency_key":"manual:retry-after-failure"}'`,
     ``,
     `# Owner-session: read the recent run ledger (default limit 50)`,
-    `curl -s "${baseUrl}/auth/botlets/bots/{botRef}/runs?limit=50"`,
+    `curl -s "${baseUrl}/agents/me/botlets/owned/bots/{botRef}/runs?limit=50"`,
     `\`\`\``,
     ``,
     `The rename body may include \`name\`, \`bot_slug\`, or both; omit either field to update only the other. Individual named bots can keep changing both fields. Provisional bots must choose a new \`bot_slug\` to become named. Team-template member slugs are locked, but their display names remain editable through the owned-agent profile endpoint.`,
@@ -28206,7 +28232,7 @@ function buildCompleteAgentDocs(baseUrl = "https://comment.io", sid) {
     ``,
     `### Install + rate (human session required)`,
     ``,
-    `Installing instantiates the template into a real bot \u2014 that needs a human session and the device-code credential flow, so it is not an agent action. To rate, a human must first install (the "verified installer" rule). Point your owner at the listing in the app: \`${baseUrl}/app/templates/<templateId>\` (the same id from browse).`,
+    `Installing instantiates the template into a real bot \u2014 that needs a human session and the device-code credential flow, so it is not an agent action. To rate, a human must first install (the "verified installer" rule). Point your owner at All Agents with the id from browse: \`${baseUrl}/agents?new=botlet&template_id=<templateId>\` for botlet templates, or \`${baseUrl}/agents?new=botlet&team_template_id=<templateId>\` for team templates.`,
     ``,
     `Want to register for @mention notifications and persistent identity? Ask your user to visit: ${baseUrl}/setup`
   ].join("\n");

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@comment-io/cli",
-  "version": "0.1.15-alpha.382",
+  "version": "0.1.15-alpha.446",
   "description": "Comment.io CLI and local notification daemon",
   "private": false,
   "type": "module",
   "homepage": "https://comment.io",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/comment-io/monorepo.git"
+    "url": "git+https://github.com/comment-hq/monorepo.git"
   },
   "bugs": {
-    "url": "https://github.com/comment-io/monorepo/issues"
+    "url": "https://github.com/comment-hq/monorepo/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -41,6 +41,6 @@
     "node": ">=20"
   },
   "commentio": {
-    "sourceSha": "7546b987aafcfc5c39dabd7976bbe9b10b5febae"
+    "sourceSha": "87647b63a7e2478013448c3570a3ae6d9398acac"
   }
 }