@comment-io/cli 0.1.18-alpha.523 → 0.1.18-alpha.527

package/mcp/comment-mcp.mjs

@@ -27229,7 +27229,7 @@ function apiReference(baseUrl, slug, token, sid) {
     `\`\`\``,
     ``,
     `#### Compact read shape`,
-    `Per-doc agent reads use the compact thread shape by default. The \`shape\` selector is retired; omit it. Use \`Authorization: Bearer ...\`; agent doc routes reject \`?token=\` query auth so pagination URLs never carry secrets. If a GET authenticated with a shared invite token returns \`your_token\`, switch to that personal bearer token before writing. The full response keeps \`markdown\`, slim \`content_blocks[]\` (\`id\` + UTF-16 \`range\`; add \`include=block_quotes\` only when needed), \`threads[]\`, \`threads_info\`, \`suggestions_info\`, \`actors\`, \`your_token\` when minted, \`display_name\`, and \`api_reference_url\`. Add \`include=authorship\` to include authorship ranges.`,
+    `Per-doc agent reads use the compact thread shape by default. The \`shape\` selector is retired; omit it. Use \`Authorization: Bearer ...\`; agent doc routes reject \`?token=\` query auth so pagination URLs never carry secrets. If a GET authenticated with a shared invite token returns \`your_token\`, switch to that personal bearer token before writing. The full response keeps \`markdown\`, slim \`content_blocks[]\` (\`id\` + UTF-16 \`range\`; add \`include=block_quotes\` only when needed), \`threads[]\`, \`threads_info\`, \`suggestions_info\`, \`actors\`, \`link_access\`, \`your_token\` when minted, \`display_name\`, and \`api_reference_url\`. Add \`include=authorship\` to include authorship ranges.`,
     `\`threads[]\` replaces legacy \`blocks[]\`. Each thread has a stable \`thr_...\` id, \`block_id\`, \`range\`, \`quote\` for span threads, \`whole_block: true\` with \`quote: null\` for non-orphaned whole-block threads, \`orphaned: true\` with \`block_id: null\` and empty collapsed range/quote when a stored mark or thread anchor no longer resolves, \`resolved\`, optional \`resolution\` with the latest resolver note, \`suggestions\`, a bounded \`comments[]\` window, and \`comments_info\`. Pending suggestions on orphaned threads report \`stale\`. \`threads_info.next\` returns lean pages \`{ revision, threads, threads_info, actors }\`; \`comments_info.next\` returns \`{ revision, thread_id, comments, comments_info, actors }\`. Cursor-page \`actors\` maps are page-local and cover the returned comments/meta. Follow every non-null \`next\` with the same Authorization header and dedupe comments defensively by \`id\`.`,
     `Thread pages accept post-capture filters: \`mentions=me\` returns threads whose stored mention metadata references the requesting credential actor, \`since_revision=N\` returns threads with a captured comment, resolve/unresolve, or suggestion-status write newer than N, \`resolved=false\` returns unresolved threads, and \`suggestions=pending|stale|open\` returns threads with matching suggestion state. Filtered \`threads_info.total\` counts matching threads; \`threads_info.doc_total\` appears when the unfiltered document thread count differs. Pagination URLs preserve the filters.`,
     `The compact thread page is byte-budgeted, not count-capped. The server fills the non-markdown envelope with newest threads first, then shrinks a large thread's comment window before deferring that thread to the next page. Every returned thread keeps at least its root comment and one recent reply when available; follow \`comments_info.next\` for omitted middle comments.`,
@@ -27237,7 +27237,7 @@ function apiReference(baseUrl, slug, token, sid) {
     ``,
     `#### Legacy field map`,
     `Older internal notes may mention \`blocks[]\`, \`content_blocks[].block_id\`, or \`api_docs\`. The live agent shape is \`threads[]\`, durable \`content_blocks[].id\` (\`bid_...\`), and \`quickstart\` plus \`api_reference_url\`. Block text from \`content_blocks[].quote\` is omitted by default and is available only with \`include=block_quotes\`; per-comment/block \`resolved\` is now thread-level \`threads[].resolved\`; bounded comment windows use \`threads[].comments[]\` with \`comments_info\`.`,
-    `Auth rule: send \`Authorization: Bearer {token}\` for agent REST requests. Do not put credentials in \`?token=\` on agent doc routes; they return \`AUTH_HEADER_REQUIRED\`. Browser share links and the editor WebSocket are separate browser surfaces and may still use token-bearing URLs.`,
+    `Auth rule: send \`Authorization: Bearer {token}\` for agent REST requests. Do not put credentials in \`?token=\` on agent doc routes; they return \`AUTH_HEADER_REQUIRED\`. Browser share links are separate browser surfaces; the normal shareable link is tokenless and governed by \`link_access\`.`,
     `Write rule: keep using string-matched \`quote\`, \`old_string\`, \`after\`, and \`before\`. For block targets, prefer durable \`bid_...\` ids from \`content_blocks[].id\`; \`blk_...\` ids are a compatibility alias only. For replies and resolution, prefer stable \`thread_id\` routes when you are acting on a thread.`,
     ``,
     `#### Offset units`,
@@ -27596,14 +27596,19 @@ function apiReference(baseUrl, slug, token, sid) {
     ``,
     `### Short links (cmnt.md)`,
     `\`\`\`bash`,
-    `# Create a short link (auto code, or name= for vanity / @you/name handle-scoped):`,
+    `# See General access for tokenless share links:`,
+    `curl -s "${api}/link-access" -H "Authorization: Bearer ${token}"`,
+    `# Changing General access requires an owner browser/session, not a document bearer token.`,
+    `# Create or reuse the tokenless shareable short link:`,
+    `curl -s -X POST "${api}/share-link" -H "Authorization: Bearer ${token}"`,
+    `# Create a token-backed named/capability 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.`,
+    `\`POST /share-link\` returns a tokenless \`https://cmnt.md/<code>\` that redirects to \`/d/:slug\`; access comes from \`link_access\` (\`restricted\`, or \`anyone\` as viewer/commenter/editor). \`POST /links\` is for explicit named/capability links: it embeds a scoped token server-side and returns no token secret. For token-backed links, \`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 OKF markdown, \`.json\` returns doc JSON, and a browser gets the editor. Per-link click analytics live in the \`shortlink.resolved\` structured log stream. Editor role or above; updating \`link_access\` is owner-only.`,
     ``,
     `## Full endpoint reference`,
     ``,
@@ -27638,6 +27643,9 @@ function apiReference(baseUrl, slug, token, sid) {
     `| 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 |`,
+    `| GET | /docs/:slug/link-access | editor+ | Read General access policy for tokenless share links |`,
+    `| PATCH | /docs/:slug/link-access | owner | Set Restricted vs Anyone with link and viewer/commenter/editor role |`,
+    `| POST | /docs/:slug/share-link | editor+ | Create/reuse the tokenless shareable cmnt.md link governed by link_access |`,
     `| 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) |`,
@@ -27701,7 +27709,7 @@ function apiReference(baseUrl, slug, token, sid) {
     `- The editor does not support raw HTML. HTML tags and comments (e.g. \`<!-- ... -->\`, \`<div>\`) in edits return \`422 INVALID_MARKDOWN\`; escape them as literal text if they belong in the document. Standalone \`<br />\` lines from GET are the exception: they represent empty paragraph spacers and can be sent back in PATCH markdown.`,
     ``,
     `## Additional notes`,
-    `- **When sharing a document link with a user, always use the exact \`share_url\` value from the API response.** Links without its embedded browser token will not work.`,
+    `- For human-facing shares, prefer the UI's Copy shareable link or \`POST /docs/:slug/share-link\`; do not paste bearer tokens or raw \`?token=\` URLs unless you intentionally want a token-backed capability link.`,
     `- For large replacements, GET the markdown programmatically \u2014 don't copy-paste through shell (Unicode issues).`
   ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comment-io/cli",
-  "version": "0.1.18-alpha.523",
+  "version": "0.1.18-alpha.527",
   "description": "Comment.io CLI and local notification daemon",
   "private": false,
   "type": "module",
@@ -41,6 +41,6 @@
     "node": ">=20"
   },
   "commentio": {
-    "sourceSha": "9938ad4c88786dc3159fad98ac1743c7b0495866"
+    "sourceSha": "e9dd014129822c33b097f6e7b36a2b152acc5afa"
   }
 }