clokio-mcp 0.18.0 → 0.18.2

package/README.md

@@ -140,10 +140,14 @@ that employee:
 - A document the employee cannot see answers **`404`**, the same as one that
   does not exist (the API never confirms an id to someone not allowed to know it).
 - A visible document they may not change answers **`403`**.
-- The employee's role gates each call: `docs.view` for reads, `docs.create`
-  for content writes, `docs.manage` for delete and sharing. Per document,
-  roles are `view` < `comment` < `edit` < `admin`; each tool's description
-  names what it needs.
+- Two separate gates, both named in each tool's description:
+  - the employee's **role** must hold the section permission: `docs.view`
+    for reads, `docs.create` for creating, editing, moving, archiving,
+    comments, version restores and uploads, `docs.manage` for delete, members,
+    teams and share links (and for standalone documents). A `403`
+    `Forbidden: Insufficient permissions` means this gate refused;
+  - the **document role**, `view` < `comment` < `edit` < `admin`. A `403`
+    with any other message means that role is too low.
 
 | Tool | Endpoint |
 |------|----------|
@@ -168,25 +172,33 @@ that employee:
 | `clokio_list_doc_versions` / `clokio_get_doc_version` / `clokio_restore_doc_version` | `GET .../versions`, `GET .../versions/{versionId}`, `POST .../versions/{versionId}/restore` |
 | `clokio_list_doc_attachments` / `clokio_upload_doc_attachment` / `clokio_download_doc_attachment` | `GET` / `POST /docs/{id}/attachments`, `GET .../attachments/download?path=` |
 
-Working with content:
+Working with documents:
 
+- **Every docs tool answers `{data}` or `{data, meta}`**, like the task tools:
+  the record or rows in `data`; paging, counts, your role and permissions in
+  `meta`. `clokio_get_doc` puts the record and its body together in `data`.
+- **Listing covers every scope by default.** `project_id` narrows it: a
+  project id, `"none"` for standalone documents only, or `"all"` (default).
 - **Read as Markdown, write as Markdown.** `clokio_get_doc` returns Markdown by
-  default (`format: "html"` or `"json"` for the others), and the create/update
-  tools take Markdown by default (`content_format: "html"` or `"json"`). HTML
-  read back is not writable as-is; HTML you write must stay inside a strict
-  12-tag grammar (no headings, no attributes except `img[src]` and `a[href]`).
+  default (`format: "html"` or `"json"` for the others) without the title;
+  pass `include_title: true` to start the body with it as a heading. The
+  create/update tools take Markdown by default (`content_format: "html"` or
+  `"json"`); HTML you write must stay within Clokio's restricted grammar (a
+  `422` names any unsupported tag).
 - **Content writes are optimistic.** `clokio_update_doc_content` REPLACES the
   whole body and requires `base_version` - the `content_version` you last read.
   A `409` means someone else edited in between: re-read, reconcile, write
   again with the new version. Never retry with the same `base_version`.
-- **Uploading does not change the text.** `clokio_upload_doc_attachment`
-  returns a `url`; place it in the body yourself (an `image` or
-  `fileAttachment` node in Tiptap JSON).
+- **Public share links expire after 30 days** unless you pass `expires_at` or
+  `never_expires: true`.
+- **Attachments** list `name`, `size`, `mime` and `uploaded_at`; download by
+  `path`. Uploading does not change the text: place the returned `url` in the
+  body yourself (an `image` or `fileAttachment` node in Tiptap JSON).
 - **Members are named by `employee_code`** (e.g. `"00080"`), like everywhere
   else in this server; the internal `employee_id` is accepted as an
   alternative. Teams are named by `team_id`, from
   `clokio_list_doc_shareable_teams`. A member's `email` is shown only when the
-  key has `employees:pii`.
+  key has `employees:pii`; profile pictures only with `include_avatars: true`.
 
 ## Security
 

package/dist/tools/docs.js

@@ -7,44 +7,51 @@ import { registerTool } from './helpers.js';
  * The Docs module, on the Public API (/api/v1/docs...) with CLOKIO_API_KEY.
  *
  * Documents are permissioned per PERSON, so every docs request acts as one
- * employee - the key's EFFECTIVE actor (backend ActsAsAuthority, owner
- * decision 2026-10-11):
- *   - the key's "acts as" employee, when it has one;
- *   - otherwise the person who CREATED the key, but only when the key lists
- *     docs:read / docs:write EXPLICITLY. The wildcard "*" does not grant docs
- *     scopes to a key with no acts-as employee, so an ordinary full-access
- *     integration key never opens its creator's private documents.
- * Every refusal of that kind is a uniform 403 decided before any document is
- * looked up. The key then sees exactly what that employee sees: a document
- * they cannot see is a 404 (never a 403 - the API will not confirm that an id
- * exists), and a visible document they may not change is a 403. Nothing here
- * re-checks permissions; the API's answer is surfaced verbatim.
+ * employee - the key's EFFECTIVE actor (backend ActsAsAuthority): its
+ * "acts as" employee, else the key's creator, the latter only when the key
+ * lists docs:read / docs:write EXPLICITLY ("*" is not enough for a key with
+ * no actor). The API decides everything else: an invisible document is 404,
+ * a visible one the actor may not change is 403.
  *
- * Three permission layers decide every call, and the descriptions name them:
- *   - the KEY SCOPE: docs:read (GET routes) or docs:write (everything else);
- *   - the SECTION permission of the acting employee's role: docs.view
- *     (reads), docs.create (content writes), docs.manage (delete, sharing);
- *   - the per-document ROLE: view < comment < edit < admin.
+ * TOKEN BUDGET. tools/list is paid by every session, so the access rules are
+ * spelled out ONCE, on clokio_list_docs, and every other description points
+ * there ("Docs access: see clokio_list_docs"). Each description says only
+ * what the model needs to call the tool correctly: what it does, the doc
+ * role it needs, and any trap (base_version, the 30-day share link default).
+ *
+ * RESPONSE SHAPE. The API answers with named keys (`docs`, `doc`, `comment`,
+ * `comments`, ...). These tools reshape that into the envelope the task tools
+ * return - `{data}` or `{data, meta}` - so a model reads every Clokio tool the
+ * same way: the record or rows in `data`, paging / permissions / counts in
+ * `meta`. See shape*() below.
+ */
+/**
+ * Per-tool access tag: the SECTION permission the acting employee's role
+ * must hold (the backend's sectionGate() per route), on top of the doc role
+ * each description names ("needs edit", "needs admin"). The full rule lives
+ * once, on clokio_list_docs. Verified against
+ * app/Http/Controllers/EmployeeApi/Doc*.php (sectionGate calls).
  */
-/** Appended to every docs tool description: who the call acts as. */
-const ACTS_AS = "Acts as the key's acts-as employee, else its creator (only if the key lists docs scopes explicitly).";
-const docId = z.number().int().positive().describe('The document id');
+const VIEW = 'Needs docs.view; see clokio_list_docs.';
+const CREATE = 'Needs docs.create; see clokio_list_docs.';
+const MANAGE = 'Needs docs.manage; see clokio_list_docs.';
+const docId = z.number().int().positive().describe('Document id');
 const CONTENT_FORMATS = ['markdown', 'html', 'json'];
 const contentArg = z
     .union([z.string(), z.record(z.string(), z.unknown())])
-    .describe('The document body. Markdown by default (headings, lists, tables, links, bold, italic, code; raw HTML ' +
-    'and images inside Markdown are dropped by the server). With content_format "html", a strict 12-tag ' +
-    'grammar: p br strong em u s ul ol li blockquote img a - no headings, no attributes except img[src] and ' +
-    'a[href], no nested lists; anything else is refused with 422 naming the tag. With content_format ' +
-    '"json", a Tiptap document {"type":"doc","content":[...]} (object or JSON string).');
-const contentFormatArg = z
-    .enum(CONTENT_FORMATS)
+    .describe('Body. Markdown by default; html = Clokio\'s restricted HTML (a 422 names any unsupported tag); ' +
+    'json = Tiptap {"type":"doc","content":[...]}');
+const contentFormatArg = z.enum(CONTENT_FORMATS).optional().describe('markdown (default), html or json');
+const readFormatArg = z.enum(CONTENT_FORMATS).optional().describe('markdown (default), html or json');
+const includeTitleArg = z
+    .boolean()
     .optional()
-    .describe('How to read `content`: markdown (default), html or json (Tiptap)');
-const readFormatArg = z
-    .enum(CONTENT_FORMATS)
+    .describe('Markdown only: start the body with the title as a heading (default false)');
+const scopeArg = z
+    .union([z.number().int().positive(), z.literal('all'), z.literal('none')])
     .optional()
-    .describe('Body format to return: markdown (default, best for reading), html, or json (Tiptap tree)');
+    .describe('Project id, "none" (standalone docs only) or "all" (default)');
+const archivedArg = z.enum(['exclude', 'include', 'only']).optional().describe('Default exclude');
 /**
  * Map (content, content_format) onto the ONE content field the API accepts.
  * Sending two content fields is a 422, so exactly one key is produced.
@@ -80,116 +87,168 @@ function contentBody(content, format = 'markdown') {
     }
     return format === 'html' ? { content_html: content } : { content_markdown: content };
 }
-/** The Docs tools (/api/v1/docs, CLOKIO_API_KEY with an acts-as employee). */
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** `{data, meta}`, with meta left out when it would be empty. */
+export function envelope(data, meta) {
+    const m = meta ? Object.fromEntries(Object.entries(meta).filter(([, v]) => v !== undefined)) : {};
+    return Object.keys(m).length ? { data, meta: m } : { data };
+}
+/** Lift `key` out of the API's data object into `data`; every other key becomes meta. */
+export function liftKey(raw, key) {
+    if (!isObj(raw) || !(key in raw))
+        return envelope(raw);
+    const { [key]: data, ...rest } = raw;
+    // A nested meta (the list endpoints put paging in data.meta) is flattened
+    // into the same meta object rather than nested a second time.
+    const { meta: nested, ...others } = rest;
+    return envelope(data, { ...(isObj(nested) ? nested : {}), ...others });
+}
+/**
+ * A document read (live or a version): the record and its body together in
+ * `data` (the body sits BESIDE the record in the API, which is easy to miss),
+ * the reader's permissions and breadcrumbs in `meta`.
+ */
+export function shapeDocRead(raw, recordKey) {
+    if (!isObj(raw) || !isObj(raw[recordKey]))
+        return envelope(raw);
+    const { [recordKey]: record, ...rest } = raw;
+    const data = { ...record };
+    const meta = {};
+    for (const [k, v] of Object.entries(rest)) {
+        if (k === 'content' || k === 'content_html' || k === 'content_markdown')
+            data[k] = v;
+        else
+            meta[k] = v;
+    }
+    return envelope(data, meta);
+}
+/**
+ * Drop every profile_pic key, at any depth, unless avatars were asked for. A
+ * signed avatar URL is a few hundred characters per person and tells a model
+ * nothing.
+ */
+export function stripAvatars(rows, keep = false) {
+    if (keep)
+        return rows;
+    const strip = (v) => {
+        if (Array.isArray(v))
+            return v.map(strip);
+        if (!isObj(v))
+            return v;
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            if (k === 'profile_pic')
+                continue;
+            out[k] = strip(val);
+        }
+        return out;
+    };
+    return strip(rows);
+}
+/** Attachment rows with name / size / mime / uploaded_at first, null when the API omits one. */
+export function shapeAttachments(raw) {
+    const rows = isObj(raw) && Array.isArray(raw.attachments) ? raw.attachments : Array.isArray(raw) ? raw : null;
+    if (!rows)
+        return envelope(raw);
+    return envelope(rows.map((r) => {
+        if (!isObj(r))
+            return r;
+        const { name, size, mime, uploaded_at, ...rest } = r;
+        return { name: name ?? null, size: size ?? null, mime: mime ?? null, uploaded_at: uploaded_at ?? null, ...rest };
+    }));
+}
+// ---------------------------------------------------------------------- tools
 export function registerDocTools(server, config) {
     // ---------------------------------------------------------------- reading
     registerTool(server, config, {
         name: 'clokio_list_docs',
-        description: 'List documents the key\'s employee can view, as flat rows (id, title, icon, project_id, parent_id, ' +
-            'visibility, is_archived, content_version, effective_role, ...) plus meta {page, per_page, total, has_more, ' +
-            'truncated}. NOTE the default scope: omitting project_id returns STANDALONE docs only (those in no ' +
-            'project); pass project_id "all" for every scope. effective_role (view/comment/edit/admin) is YOUR role ' +
-            'on that row; edit or admin means content writes will be accepted. Needs section docs.view. Scope docs:read. ' +
-            ACTS_AS +
-            ' WHO: every docs tool acts as ONE employee - the key\'s "acts as" employee, or, for a key without one, the ' +
-            'person who created the key, and only when docs:read / docs:write are listed on the key explicitly (the ' +
-            'wildcard "*" is not enough). Otherwise every docs tool answers 403; set an acts-as employee or add the ' +
-            'docs scopes explicitly in Settings > API keys.',
+        description: 'List documents you can view (all scopes by default; project_id narrows). Rows include effective_role ' +
+            '(view/comment/edit/admin): edit or admin means you may write content. ' +
+            'DOCS ACCESS (applies to every clokio_*doc* tool): each call acts as the API key\'s "acts as" employee, ' +
+            'or, if the key has none, as the key\'s creator - only when the key lists docs:read / docs:write ' +
+            'explicitly ("*" is not enough). Otherwise every docs tool returns 403: set an acts-as employee or add ' +
+            'the docs scopes in Settings > API keys. Reads need scope docs:read, everything else docs:write. You see ' +
+            'exactly what that employee sees; a doc they cannot see is 404. ' +
+            'Two separate gates: the employee\'s ROLE must hold the section permission each tool names (docs.view ' +
+            'reads; docs.create writes, comments, uploads; docs.manage delete and sharing) - a 403 "Forbidden: ' +
+            'Insufficient permissions" means it does not; and the DOC role (view<comment<edit<admin, "needs edit" ' +
+            'etc.) - a 403 with another message means that is too low. Needs docs.view.',
         schema: {
-            project_id: z
-                .union([z.number().int().positive(), z.literal('all')])
-                .optional()
-                .describe('A project id, or "all". Omitted = standalone docs only'),
+            project_id: scopeArg,
             parent_id: z
                 .union([z.number().int().positive(), z.literal('root')])
                 .optional()
-                .describe('A doc id to list its children (project_id is then ignored), or "root" for top-level docs only'),
-            q: z.string().max(120).optional().describe('Case-insensitive title substring'),
-            archived: z
-                .enum(['exclude', 'include', 'only'])
-                .optional()
-                .describe('Archived docs: exclude (default), include, or only'),
+                .describe('A doc id to list its children, or "root" for top-level docs only'),
+            q: z.string().max(120).optional().describe('Title substring'),
+            archived: archivedArg,
             page: z.number().int().min(1).optional(),
-            per_page: z.number().int().min(1).max(100).optional().describe('1-100, default 50'),
+            per_page: z.number().int().min(1).max(100).optional().describe('Default 50'),
         },
-        handler: (args, cfg) => request(cfg, '/docs', {
+        handler: async (args, cfg) => liftKey(await request(cfg, '/docs', {
             query: {
-                project_id: args.project_id,
+                project_id: args.project_id ?? 'all',
                 parent_id: args.parent_id,
                 q: args.q,
                 archived: args.archived,
                 page: args.page,
                 per_page: args.per_page,
             },
-        }),
+        }), 'docs'),
     });
     registerTool(server, config, {
         name: 'clokio_get_doc_tree',
-        description: 'The visible documents as a nested tree (data.tree, each node with `children`), paged over the top level, ' +
-            'plus meta. A doc whose parent you cannot see appears at the top level. Same scope rule as ' +
-            'clokio_list_docs: omitting project_id means standalone docs only; "all" means every scope. Needs ' +
-            'section docs.view. Scope docs:read. ' + ACTS_AS,
+        description: `Documents you can view as a nested tree (children), paged over the top level. ${VIEW}`,
         schema: {
-            project_id: z
-                .union([z.number().int().positive(), z.literal('all')])
-                .optional()
-                .describe('A project id, or "all". Omitted = standalone docs only'),
-            archived: z.enum(['exclude', 'include', 'only']).optional(),
+            project_id: scopeArg,
+            archived: archivedArg,
             page: z.number().int().min(1).optional(),
-            per_page: z.number().int().min(1).max(100).optional().describe('Top-level nodes per page, 1-100'),
+            per_page: z.number().int().min(1).max(100).optional(),
         },
-        handler: (args, cfg) => request(cfg, '/docs', {
+        handler: async (args, cfg) => liftKey(await request(cfg, '/docs', {
             query: {
                 tree: 1,
-                project_id: args.project_id,
+                project_id: args.project_id ?? 'all',
                 archived: args.archived,
                 page: args.page,
                 per_page: args.per_page,
             },
-        }),
+        }), 'tree'),
     });
     registerTool(server, config, {
         name: 'clokio_search_docs',
-        description: 'Search the titles AND body text of documents you can view, newest edit first. Each row has the listing ' +
-            'shape plus `snippet` (~160 chars around the first match). Archived docs are left out. Needs section ' +
-            'docs.view. Scope docs:read. ' + ACTS_AS,
+        description: `Search titles and body text (not archived), newest first; each row has a snippet. ${VIEW}`,
         schema: {
-            q: z.string().min(2).max(120).describe('2-120 characters; % and _ match literally'),
-            project_id: z.number().int().positive().optional().describe('Limit to one project'),
-            limit: z.number().int().min(1).max(50).optional().describe('1-50, default 20'),
+            q: z.string().min(2).max(120),
+            project_id: z.number().int().positive().optional(),
+            limit: z.number().int().min(1).max(50).optional().describe('Default 20'),
         },
-        handler: (args, cfg) => request(cfg, '/docs/search', {
-            query: { q: args.q, project_id: args.project_id, limit: args.limit },
-        }),
+        handler: async (args, cfg) => liftKey(await request(cfg, '/docs/search', { query: { q: args.q, project_id: args.project_id, limit: args.limit } }), 'docs'),
     });
     registerTool(server, config, {
         name: 'clokio_get_doc',
-        description: 'Read one document: data.doc (metadata incl. content_version), breadcrumbs, effective_role, can_comment, ' +
-            'can_edit, can_manage, and the body BESIDE the record as content_markdown / content_html / content (json). ' +
-            'Keep doc.content_version: clokio_update_doc_content needs it as base_version. HTML read back is NOT ' +
-            'writable as-is (it carries dir/style attributes and possibly headings) - to edit, write Markdown. ' +
-            'Archived docs are readable. 404 = no such doc OR one you cannot see. Needs section docs.view. Scope docs:read. ' + ACTS_AS,
-        schema: { id: docId, format: readFormatArg },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}`, { query: { format: args.format ?? 'markdown' } }),
+        description: 'Read a document: data = the record plus its body; meta = your role and breadcrumbs. Keep ' +
+            `data.content_version for clokio_update_doc_content. ${VIEW}`,
+        schema: { id: docId, format: readFormatArg, include_title: includeTitleArg },
+        handler: async (args, cfg) => shapeDocRead(await request(cfg, `/docs/${seg(args.id)}`, {
+            query: { format: args.format ?? 'markdown', include_title: args.include_title ? 1 : undefined },
+        }), 'doc'),
     });
     // ---------------------------------------------------------------- writing
     registerTool(server, config, {
         name: 'clokio_create_doc',
-        description: 'Create a document. Where it lands: parent_id = a sub-page (inherits the parent\'s project; needs edit on ' +
-            'the parent); project_id = inside that project (needs the right to create tasks there); neither = a ' +
-            'standalone org-level doc (org admins / docs.manage only, else 403). Content is Markdown by default. ' +
-            'Returns data.doc with content_version 0 - the base_version for the first content write. You become the ' +
-            'doc\'s admin. Needs section docs.create. Scope docs:write. ' + ACTS_AS,
+        description: 'Create a document. parent_id = sub-page (needs edit on the parent); project_id = in that project; ' +
+            'neither = standalone (needs docs.manage). Starts at content_version 0. ' +
+            CREATE,
         mutates: true,
         schema: {
             title: z.string().min(1).max(255),
-            icon: z.string().max(10).optional().describe('A single emoji'),
+            icon: z.string().max(10).optional().describe('One emoji'),
             project_id: z.number().int().positive().optional(),
-            parent_id: z.number().int().positive().optional().describe('Create as a sub-page of this doc'),
+            parent_id: z.number().int().positive().optional(),
             content: contentArg.optional(),
             content_format: contentFormatArg,
         },
-        handler: (args, cfg) => {
+        handler: async (args, cfg) => {
             const body = {
                 title: args.title,
                 icon: args.icon,
@@ -200,101 +259,84 @@ export function registerDocTools(server, config) {
             const blank = typeof args.content === 'string' && args.content.trim() === '';
             if (!blank)
                 Object.assign(body, contentBody(args.content, args.content_format));
-            return request(cfg, '/docs', { method: 'POST', body });
+            return liftKey(await request(cfg, '/docs', { method: 'POST', body }), 'doc');
         },
     });
     registerTool(server, config, {
         name: 'clokio_update_doc_content',
-        description: 'REPLACE a document\'s whole body (not a patch, not an append). base_version is REQUIRED: the ' +
-            'content_version you last read (clokio_get_doc, or a previous write\'s response). A 409 means someone ' +
-            'else changed the doc since: do NOT retry with the same base_version - re-read with clokio_get_doc, ' +
-            'reconcile, and write again with the new version (the 409 names current_version and edited_by). ' +
-            'Markdown by default; an empty string clears the doc. Returns {content_version, last_edited_at}. ' +
-            'Needs section docs.create and edit on the doc (a read-only share is 403). Scope docs:write. ' + ACTS_AS,
+        description: 'REPLACE the whole body (needs edit). base_version = the content_version you last read. On 409 do not ' +
+            'retry the same base_version: re-read, reconcile, write with the new version. Empty content clears. ' +
+            CREATE,
         mutates: true,
         schema: {
             id: docId,
             content: contentArg,
             content_format: contentFormatArg,
-            base_version: z.number().int().min(0).describe('The content_version you last read'),
+            base_version: z.number().int().min(0),
         },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/content`, {
+        handler: async (args, cfg) => envelope(await request(cfg, `/docs/${seg(args.id)}/content`, {
             method: 'PUT',
             body: { ...contentBody(args.content, args.content_format), base_version: args.base_version },
-        }),
+        })),
     });
     registerTool(server, config, {
         name: 'clokio_update_doc_meta',
-        description: 'Change a document\'s metadata - send only what changes. title, icon (null clears), full_width (page ' +
-            'layout) and sort_order need edit on the doc; visibility (private/project/organization), ' +
-            'inherit_permissions and is_archived need admin on the doc (a call mixing both needs admin). To change ' +
-            'parent or project use clokio_move_doc. Returns data.doc and `changed` (fields that actually changed). ' +
-            'Needs section docs.create. Scope docs:write. ' + ACTS_AS,
+        description: 'Change metadata; send only what changes. title/icon/full_width/sort_order need edit; visibility, ' +
+            'inherit_permissions, is_archived need admin. Use clokio_move_doc for parent/project. ' +
+            CREATE,
         mutates: true,
         schema: {
             id: docId,
             title: z.string().min(1).max(255).optional(),
-            icon: z.string().max(10).nullable().optional().describe('An emoji, or null to clear'),
+            icon: z.string().max(10).nullable().optional().describe('null clears'),
             full_width: z.boolean().optional(),
             sort_order: z.number().int().min(0).optional(),
             visibility: z.enum(['private', 'project', 'organization']).optional(),
             inherit_permissions: z.boolean().optional(),
             is_archived: z.boolean().optional(),
         },
-        handler: (args, cfg) => {
+        handler: async (args, cfg) => {
             const { id, ...fields } = args;
             const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
             if (Object.keys(body).length === 0) {
                 throw new ClokioApiError(0, 'Nothing to change: pass at least one field.');
             }
-            return request(cfg, `/docs/${seg(id)}`, { method: 'PATCH', body });
+            return liftKey(await request(cfg, `/docs/${seg(id)}`, { method: 'PATCH', body }), 'doc');
         },
     });
     registerTool(server, config, {
         name: 'clokio_move_doc',
-        description: 'Move a document (with its sub-pages) in the tree or between projects. BOTH parent_id and project_id ' +
-            'must be given, null meaning top level / standalone, so a forgotten project_id never reads as "move to ' +
-            'standalone". With a parent_id the parent\'s project wins. Moving into its own sub-tree is 422; into a ' +
-            'project needs the right to create tasks there; into standalone needs docs.manage. Needs section ' +
-            'docs.create and admin on the doc. Scope docs:write. ' + ACTS_AS,
+        description: 'Move a document and its sub-pages (needs admin). Send both parent_id and project_id; null = top ' +
+            `level / standalone. With a parent, the parent's project wins. ${CREATE}`,
         mutates: true,
         schema: {
             id: docId,
-            parent_id: z.number().int().positive().nullable().describe('New parent doc id, or null for top level'),
-            project_id: z
-                .number()
-                .int()
-                .positive()
-                .nullable()
-                .describe('Target project id, or null for standalone (ignored when parent_id is set)'),
-            sort_order: z.number().int().min(0).optional().describe('Position among the new siblings'),
+            parent_id: z.number().int().positive().nullable(),
+            project_id: z.number().int().positive().nullable(),
+            sort_order: z.number().int().min(0).optional(),
         },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/move`, {
+        handler: async (args, cfg) => liftKey(await request(cfg, `/docs/${seg(args.id)}/move`, {
             method: 'POST',
             body: { parent_id: args.parent_id, project_id: args.project_id, sort_order: args.sort_order },
-        }),
+        }), 'doc'),
     });
     registerTool(server, config, {
         name: 'clokio_archive_doc',
-        description: 'Archive a document (hidden from the default listing; still readable by id). Reversible with ' +
-            'clokio_restore_doc. Needs section docs.create and admin on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Archive a document (needs admin; reversible with clokio_restore_doc). ${CREATE}`,
         mutates: true,
         schema: { id: docId },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/archive`, { method: 'POST' }),
+        handler: async (args, cfg) => liftKey(await request(cfg, `/docs/${seg(args.id)}/archive`, { method: 'POST' }), 'doc'),
     });
     registerTool(server, config, {
         name: 'clokio_restore_doc',
-        description: 'Un-archive a document. (A DELETED doc cannot be restored through the API.) Needs section docs.create ' +
-            'and admin on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Un-archive a document (needs admin). ${CREATE}`,
         mutates: true,
         schema: { id: docId },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/restore`, { method: 'POST' }),
+        handler: async (args, cfg) => liftKey(await request(cfg, `/docs/${seg(args.id)}/restore`, { method: 'POST' }), 'doc'),
     });
     registerTool(server, config, {
         name: 'clokio_delete_doc',
-        description: 'DELETE a document. A pre-delete version snapshot is kept for administrators, but the doc cannot be ' +
-            'restored through the API - prefer clokio_archive_doc unless deletion is explicitly wanted. Needs ' +
-            'section docs.manage and admin on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `DELETE a document (needs admin; not restorable via the API - prefer archive). ${MANAGE}`,
         mutates: 'destructive',
         schema: { id: docId },
         handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}`, { method: 'DELETE' }),
@@ -302,36 +344,49 @@ export function registerDocTools(server, config) {
     // -------------------------------------------------------------- templates
     registerTool(server, config, {
         name: 'clokio_list_doc_templates',
-        description: 'List the document templates ({key, name, icon, description}) and can_create_standalone (whether you may ' +
-            'create a doc outside any project). Needs section docs.view. Scope docs:read. ' + ACTS_AS,
+        description: `List document templates (key, name, description). ${VIEW}`,
         schema: {},
-        handler: (_args, cfg) => request(cfg, '/docs/templates'),
+        handler: async (_args, cfg) => liftKey(await request(cfg, '/docs/templates'), 'templates'),
     });
     registerTool(server, config, {
         name: 'clokio_create_doc_from_template',
-        description: 'Create a top-level document from a template (key from clokio_list_doc_templates; unknown is 404). With ' +
-            'project_id it lands in that project (needs the right to create tasks there); without, it is standalone ' +
-            '(needs docs.manage). Returns data.doc. Needs section docs.create. Scope docs:write. ' + ACTS_AS,
+        description: `Create a top-level document from a template key. No project_id = standalone (needs docs.manage). ${CREATE}`,
         mutates: true,
         schema: {
-            template: z.string().min(1).max(60).describe('The template key'),
-            title: z.string().max(255).optional().describe('Defaults to the template name'),
+            template: z.string().min(1).max(60),
+            title: z.string().max(255).optional(),
             project_id: z.number().int().positive().optional(),
         },
-        handler: (args, cfg) => request(cfg, '/docs/from-template', {
+        handler: async (args, cfg) => liftKey(await request(cfg, '/docs/from-template', {
             method: 'POST',
             body: { template: args.template, title: args.title, project_id: args.project_id },
-        }),
+        }), 'doc'),
     });
     // ---------------------------------------------------------------- sharing
     registerTool(server, config, {
         name: 'clokio_list_doc_members',
-        description: 'Who a document is shared with: members (direct person grants: employee_code, employee_id, name, role; ' +
-            'email only when the key has employees:pii), teams (team grants: team_id, name, role), inherited (people ' +
-            'reaching it through a parent - change those on the parent), visibility, inherit_permissions and the ' +
-            'live share_link if any. Needs section docs.view and admin on the doc. Scope docs:read. ' + ACTS_AS,
+        description: 'Who a document is shared with (needs admin): data = members, teams, inherited (change those on the ' +
+            `parent); meta = visibility, inherit_permissions, share_link. ${VIEW}`,
+        schema: {
+            id: docId,
+            include_avatars: z.boolean().optional().describe('Include profile pictures (default false)'),
+        },
+        handler: async (args, cfg) => {
+            const raw = await request(cfg, `/docs/${seg(args.id)}/members`, {
+                query: { include_avatars: args.include_avatars ? 1 : undefined },
+            });
+            if (!isObj(raw))
+                return envelope(raw);
+            const { members, teams, inherited, ...meta } = raw;
+            const keep = args.include_avatars === true;
+            return envelope({ members: stripAvatars(members, keep), teams, inherited: stripAvatars(inherited, keep) }, meta);
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_list_doc_shareable_teams',
+        description: `Teams this document can be shared with (needs admin); use id as team_id. ${VIEW}`,
         schema: { id: docId },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/members`),
+        handler: async (args, cfg) => liftKey(await request(cfg, `/docs/${seg(args.id)}/shareable-teams`), 'teams'),
     });
     const memberRole = z.enum(['view', 'comment', 'edit', 'admin']);
     // A person is named by employee_code (preferred - the way every other tool
@@ -341,13 +396,8 @@ export function registerDocTools(server, config) {
             .string()
             .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code must be 1-50 chars of letters, digits, _ or -')
             .optional()
-            .describe('The person\'s employee_code, zero-padded (e.g. "00080"). Preferred. Resolve names with clokio_list_employees'),
-        employee_id: z
-            .number()
-            .int()
-            .positive()
-            .optional()
-            .describe('Alternative to employee_code: Clokio\'s INTERNAL employee id (as clokio_list_doc_members reports it)'),
+            .describe('Zero-padded, e.g. "00080" (preferred)'),
+        employee_id: z.number().int().positive().optional().describe('Internal id, instead of employee_code'),
     };
     /** Exactly one of employee_code / employee_id, as the API requires. */
     function person(args) {
@@ -360,45 +410,37 @@ export function registerDocTools(server, config) {
     }
     registerTool(server, config, {
         name: 'clokio_add_doc_member',
-        description: 'Share a document with a person, or change their direct role if already shared. Name them by ' +
-            'employee_code (preferred) or employee_id. role: view, comment, edit or admin. The person must be an ' +
-            'active member of your organisation (422 otherwise) and is notified on a first grant. Needs section ' +
-            'docs.manage and admin on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Share a document with a person or change their role (needs admin; they are notified once). ${MANAGE}`,
         mutates: true,
         schema: { id: docId, ...personArgs, role: memberRole },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/members`, {
+        handler: async (args, cfg) => envelope(await request(cfg, `/docs/${seg(args.id)}/members`, {
             method: 'POST',
             body: { ...person(args), role: args.role },
-        }),
+        })),
     });
     registerTool(server, config, {
         name: 'clokio_update_doc_member',
-        description: 'Change an existing direct grant\'s role. Name the person by employee_code (preferred) or employee_id. ' +
-            '404 if the person has no direct grant; demoting the last admin is 422. Needs section docs.manage and ' +
-            'admin on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Change a person's direct role (needs admin; demoting the last admin is 422). ${MANAGE}`,
         mutates: true,
         schema: { id: docId, ...personArgs, role: memberRole },
-        handler: (args, cfg) => {
+        handler: async (args, cfg) => {
             const who = person(args);
             // An id has its own path route; a code rides in the body of the
             // collection route (PATCH /docs/{id}/members).
-            return 'employee_id' in who
-                ? request(cfg, `/docs/${seg(args.id)}/members/${seg(who.employee_id)}`, {
+            return envelope('employee_id' in who
+                ? await request(cfg, `/docs/${seg(args.id)}/members/${seg(who.employee_id)}`, {
                     method: 'PATCH',
                     body: { role: args.role },
                 })
-                : request(cfg, `/docs/${seg(args.id)}/members`, {
+                : await request(cfg, `/docs/${seg(args.id)}/members`, {
                     method: 'PATCH',
                     body: { ...who, role: args.role },
-                });
+                }));
         },
     });
     registerTool(server, config, {
         name: 'clokio_remove_doc_member',
-        description: 'Remove a person\'s direct grant. Name them by employee_code (preferred; may name someone who has since ' +
-            'left, to revoke their grant) or employee_id. Removing the ' +
-            'last admin is 422; inherited access must be removed on the parent. Needs section docs.manage and admin ' +
-            'on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Remove a person's direct grant (needs admin; a code may name someone who has left). ${MANAGE}`,
         mutates: 'destructive',
         schema: { id: docId, ...personArgs },
         handler: (args, cfg) => {
@@ -414,71 +456,58 @@ export function registerDocTools(server, config) {
                 });
         },
     });
-    registerTool(server, config, {
-        name: 'clokio_list_doc_shareable_teams',
-        description: 'The organisation\'s teams this document can be shared with ({id, name, color, members_count}) - use the ' +
-            'id as team_id in ' +
-            'clokio_add_doc_team. Needs section docs.view and admin on the doc. Scope docs:read. ' + ACTS_AS,
-        schema: { id: docId },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/shareable-teams`),
-    });
-    const teamRole = z.enum(['view', 'comment', 'edit']).describe('Teams cannot be admins');
-    const teamId = z
-        .number()
-        .int()
-        .positive()
-        .describe('The team id (from clokio_list_doc_shareable_teams, or teams[].team_id in clokio_list_doc_members)');
+    const teamRole = z.enum(['view', 'comment', 'edit']);
+    const teamId = z.number().int().positive().describe('From clokio_list_doc_shareable_teams');
     registerTool(server, config, {
         name: 'clokio_add_doc_team',
-        description: 'Share a document with a team (role view, comment or edit). The team must be in your organisation. ' +
-            'Find team ids with clokio_list_doc_shareable_teams; current team grants are in clokio_list_doc_members. Needs section docs.manage and admin on the ' +
-            'doc. Scope docs:write. ' + ACTS_AS,
+        description: `Share a document with a team (needs admin; teams cannot be admins). ${MANAGE}`,
         mutates: true,
         schema: { id: docId, team_id: teamId, role: teamRole },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/teams`, {
+        handler: async (args, cfg) => envelope(await request(cfg, `/docs/${seg(args.id)}/teams`, {
             method: 'POST',
             body: { team_id: args.team_id, role: args.role },
-        }),
+        })),
     });
     registerTool(server, config, {
         name: 'clokio_update_doc_team',
-        description: 'Change a team grant\'s role (404 if the team has no grant). Needs section docs.manage and admin on the ' +
-            'doc. Scope docs:write. ' + ACTS_AS,
+        description: `Change a team's role on a document (needs admin). ${MANAGE}`,
         mutates: true,
         schema: { id: docId, team_id: teamId, role: teamRole },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/teams/${seg(args.team_id)}`, {
+        handler: async (args, cfg) => envelope(await request(cfg, `/docs/${seg(args.id)}/teams/${seg(args.team_id)}`, {
             method: 'PATCH',
             body: { role: args.role },
-        }),
+        })),
     });
     registerTool(server, config, {
         name: 'clokio_remove_doc_team',
-        description: 'Remove a team\'s grant on a document. Needs section docs.manage and admin on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Remove a team's grant (needs admin). ${MANAGE}`,
         mutates: 'destructive',
         schema: { id: docId, team_id: teamId },
         handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/teams/${seg(args.team_id)}`, { method: 'DELETE' }),
     });
     registerTool(server, config, {
         name: 'clokio_create_doc_share_link',
-        description: 'Create a PUBLIC link to a document (anyone with the URL can read it), or REPLACE the existing one - the ' +
-            'old URL stops working. Returns {share_token, share_url, expires_at}. Needs section docs.manage and ' +
-            'admin on the doc. Scope docs:write. ' + ACTS_AS,
+        description: 'Create or REPLACE the public read link (needs admin; the old URL stops working). Expires in 30 days ' +
+            `unless expires_at or never_expires is given. ${MANAGE}`,
         mutates: true,
         schema: {
             id: docId,
-            expires_at: z
-                .string()
-                .optional()
-                .describe('Optional expiry, a date/time in the future (e.g. 2026-12-31 or an ISO 8601 timestamp)'),
+            expires_at: z.string().optional().describe('Future date or ISO 8601 timestamp'),
+            never_expires: z.boolean().optional().describe('No expiry (overrides the 30-day default)'),
+        },
+        handler: async (args, cfg) => {
+            if (args.never_expires && args.expires_at) {
+                throw new ClokioApiError(0, 'Pass expires_at or never_expires, not both.');
+            }
+            return envelope(await request(cfg, `/docs/${seg(args.id)}/share-link`, {
+                method: 'POST',
+                body: { expires_at: args.expires_at, never_expires: args.never_expires },
+            }));
         },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/share-link`, {
-            method: 'POST',
-            body: { expires_at: args.expires_at },
-        }),
     });
     registerTool(server, config, {
         name: 'clokio_revoke_doc_share_link',
-        description: 'Revoke a document\'s public link. Needs section docs.manage and admin on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Revoke the public link (needs admin). ${MANAGE}`,
         mutates: 'destructive',
         schema: { id: docId },
         handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/share-link`, { method: 'DELETE' }),
@@ -486,124 +515,101 @@ export function registerDocTools(server, config) {
     // --------------------------------------------------------------- comments
     registerTool(server, config, {
         name: 'clokio_list_doc_comments',
-        description: 'A document\'s comment threads, newest first (max 100), replies nested under `replies`, plus counts ' +
-            '{unresolved, resolved, total}. Needs section docs.view and view on the doc. Scope docs:read. ' + ACTS_AS,
+        description: `Comment threads, newest first, replies nested; meta has counts. ${VIEW}`,
         schema: {
             id: docId,
-            filter: z
-                .enum(['unresolved', 'resolved', 'all'])
-                .optional()
-                .describe('Which threads: unresolved (default), resolved or all'),
-            block_id: z.string().max(40).optional().describe('Only threads anchored to this block'),
+            filter: z.enum(['unresolved', 'resolved', 'all']).optional().describe('Default unresolved'),
+            block_id: z.string().max(40).optional(),
         },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/comments`, {
+        handler: async (args, cfg) => liftKey(stripAvatars(await request(cfg, `/docs/${seg(args.id)}/comments`, {
             query: { filter: args.filter, block_id: args.block_id },
-        }),
+        })), 'comments'),
     });
     registerTool(server, config, {
         name: 'clokio_add_doc_comment',
-        description: 'Comment on a document, or reply to a thread (parent_id = a thread on THIS doc; a reply to a reply is ' +
-            '422). The body accepts Markdown (converted to HTML) or HTML. @Full Name mentions of active colleagues ' +
-            'notify them. Needs section docs.create and comment on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Comment, or reply to a thread with parent_id (needs comment). Markdown or HTML; @Full Name notifies. ${CREATE}`,
         mutates: true,
         schema: {
             id: docId,
-            body: z.string().min(1).max(20000).describe('Markdown or HTML'),
-            parent_id: z.number().int().positive().optional().describe('Reply to this thread'),
-            block_id: z.string().max(40).optional().describe('Anchor the comment to a block of the doc'),
+            body: z.string().min(1).max(20000),
+            parent_id: z.number().int().positive().optional(),
+            block_id: z.string().max(40).optional(),
         },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/comments`, {
+        handler: async (args, cfg) => liftKey(stripAvatars(await request(cfg, `/docs/${seg(args.id)}/comments`, {
             method: 'POST',
             body: { body: markdownToHtml(args.body), parent_id: args.parent_id, block_id: args.block_id },
-        }),
+        })), 'comment'),
     });
     registerTool(server, config, {
         name: 'clokio_resolve_doc_comment',
-        description: 'Resolve a comment thread (a thread, not a reply - a reply is 422). Needs section docs.create and ' +
-            'comment on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Resolve a comment thread (needs comment). ${CREATE}`,
         mutates: true,
         schema: { id: docId, comment_id: z.number().int().positive() },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/comments/${seg(args.comment_id)}/resolve`, { method: 'POST' }),
+        handler: async (args, cfg) => liftKey(stripAvatars(await request(cfg, `/docs/${seg(args.id)}/comments/${seg(args.comment_id)}/resolve`, { method: 'POST' })), 'comment'),
     });
     registerTool(server, config, {
         name: 'clokio_reopen_doc_comment',
-        description: 'Reopen a resolved comment thread. Needs section docs.create and comment on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Reopen a resolved comment thread (needs comment). ${CREATE}`,
         mutates: true,
         schema: { id: docId, comment_id: z.number().int().positive() },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/comments/${seg(args.comment_id)}/reopen`, { method: 'POST' }),
+        handler: async (args, cfg) => liftKey(stripAvatars(await request(cfg, `/docs/${seg(args.id)}/comments/${seg(args.comment_id)}/reopen`, { method: 'POST' })), 'comment'),
     });
     // --------------------------------------------------------------- versions
     registerTool(server, config, {
         name: 'clokio_list_doc_versions',
-        description: 'A document\'s version history, newest first (max 50): {id, version, reason, created_at, creator}. reason ' +
-            'is manual_save, auto_save, restore, pre_delete or conflict_backup. Pass the `id` (not the `version` ' +
-            'number) to the other version tools. Needs section docs.view and view on the doc. Scope docs:read. ' + ACTS_AS,
+        description: `Version history, newest first. Pass a row's id (not its version number) to the other version tools. ${VIEW}`,
         schema: { id: docId },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/versions`),
+        handler: async (args, cfg) => liftKey(await request(cfg, `/docs/${seg(args.id)}/versions`), 'versions'),
     });
     registerTool(server, config, {
         name: 'clokio_get_doc_version',
-        description: 'Read one snapshot from a document\'s history, in markdown (default), html or json. version_id is the ' +
-            '`id` from clokio_list_doc_versions. Needs section docs.view and view on the doc. Scope docs:read. ' + ACTS_AS,
-        schema: { id: docId, version_id: z.number().int().positive(), format: readFormatArg },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/versions/${seg(args.version_id)}`, {
-            query: { format: args.format ?? 'markdown' },
-        }),
+        description: `Read one version snapshot. ${VIEW}`,
+        schema: {
+            id: docId,
+            version_id: z.number().int().positive(),
+            format: readFormatArg,
+            include_title: includeTitleArg,
+        },
+        handler: async (args, cfg) => shapeDocRead(await request(cfg, `/docs/${seg(args.id)}/versions/${seg(args.version_id)}`, {
+            query: { format: args.format ?? 'markdown', include_title: args.include_title ? 1 : undefined },
+        }), 'version'),
     });
     registerTool(server, config, {
         name: 'clokio_restore_doc_version',
-        description: 'Copy a snapshot back over the document\'s content (recorded as a new `restore` version). Returns ' +
-            '{content_version, version}: content_version MOVES, so use the returned value as base_version for the ' +
-            'next content write. Needs section docs.create and edit on the doc. Scope docs:write. ' + ACTS_AS,
+        description: `Restore a snapshot over the content (needs edit). content_version moves: use the returned one. ${CREATE}`,
         mutates: true,
         schema: { id: docId, version_id: z.number().int().positive() },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/versions/${seg(args.version_id)}/restore`, { method: 'POST' }),
+        handler: async (args, cfg) => envelope(await request(cfg, `/docs/${seg(args.id)}/versions/${seg(args.version_id)}/restore`, { method: 'POST' })),
     });
     // ------------------------------------------------------------ attachments
     registerTool(server, config, {
         name: 'clokio_list_doc_attachments',
-        description: 'Files uploaded to a document (max 200): {kind: media|file, name, path, url}. Read from storage, so a ' +
-            'file removed from the text is still listed. Download with clokio_download_doc_attachment using `path` ' +
-            '(the `url` values need a browser session). Needs section docs.view and view on the doc. Scope docs:read. ' + ACTS_AS,
+        description: `Files uploaded to a document: name, size, mime, uploaded_at, path (for download). ${VIEW}`,
         schema: { id: docId },
-        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/attachments`),
+        handler: async (args, cfg) => shapeAttachments(await request(cfg, `/docs/${seg(args.id)}/attachments`)),
     });
     registerTool(server, config, {
         name: 'clokio_upload_doc_attachment',
-        description: 'Upload a LOCAL FILE to a document. kind "file" (default): anything up to 100 MB except executable and ' +
-            'markup types (php, js, sh, exe, svg, html, xml...). kind "media": jpg/jpeg/png/gif/webp/heic/heif ' +
-            '(HEIC becomes JPEG)/mp4/webm/mov, up to 50 MB. Returns {kind, url, path, name, size, mime}. Uploading ' +
-            'does NOT change the text: to show it, write content (content_format json) with an `image` node ' +
-            '(src = url) for media or a `fileAttachment` node (url, name, size, mime) for a file. Needs section ' +
-            'docs.create and edit on the doc. Scope docs:write. ' + ACTS_AS,
+        description: 'Upload a LOCAL file (needs edit). kind file (default, 100 MB) or media (images/video, 50 MB). Does not ' +
+            `change the text: reference the returned url in the body yourself. ${CREATE}`,
         mutates: true,
         schema: {
             id: docId,
-            file_path: z.string().describe('Path to a file on THIS machine'),
-            kind: z.enum(['file', 'media']).optional().describe('file (default) or media'),
+            file_path: z.string().describe('Path on THIS machine'),
+            kind: z.enum(['file', 'media']).optional(),
         },
-        handler: (args, cfg) => requestUpload(cfg, `/docs/${seg(args.id)}/attachments`, args.file_path, { kind: args.kind ?? 'file' }),
+        handler: async (args, cfg) => envelope(await requestUpload(cfg, `/docs/${seg(args.id)}/attachments`, args.file_path, { kind: args.kind ?? 'file' })),
     });
     registerTool(server, config, {
         name: 'clokio_download_doc_attachment',
-        description: 'Download one document attachment by its storage `path` (from clokio_list_doc_attachments). With ' +
-            'save_path, writes the file to disk (creating folders, refusing to overwrite unless overwrite: true) and ' +
-            'returns {saved_to, sha256, mime_type, file_size}. Without it, returns the content in the most usable ' +
-            'form: text as text, a PDF as extracted text plus page count, a ZIP as its entry list, an image as an ' +
-            'image you can see, anything else as a type-and-size description. Large text/PDF is truncated (use ' +
-            'save_path for the whole file). Needs section docs.view and view on the doc. Scope docs:read. ' + ACTS_AS,
+        description: 'Download an attachment by its path. save_path writes it to disk; otherwise text, PDF text, ZIP entries ' +
+            `or an image come back inline. ${VIEW}`,
         schema: {
             id: docId,
-            path: z.string().min(1).max(1024).describe('The attachment `path` from clokio_list_doc_attachments'),
-            file_name: z
-                .string()
-                .optional()
-                .describe('The attachment `name` from the listing. Drives type detection (text/PDF/zip/image)'),
-            save_path: z
-                .string()
-                .optional()
-                .describe('Write the file here instead of returning its content; parent folders are created'),
-            overwrite: z.boolean().optional().describe('Allow save_path to replace an existing file (default false)'),
+            path: z.string().min(1).max(1024).describe('`path` from clokio_list_doc_attachments'),
+            file_name: z.string().optional().describe('`name` from the listing (type detection)'),
+            save_path: z.string().optional(),
+            overwrite: z.boolean().optional().describe('Replace an existing save_path file'),
         },
         handler: (args, cfg) => downloadDocAttachment(cfg, args.id, args.path, {
             fileName: args.file_name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clokio-mcp",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Model Context Protocol (MCP) server for Clokio - manage tasks, projects, clients, employees, attendance and documents from Claude and any MCP client.",
   "type": "module",
   "bin": {