@pitcher/cli-scripts 2.17.1 → 2.18.0

package/README.md

@@ -522,10 +522,13 @@ p dsr create --instance-id 01... --sharebox-file-ids 01A,01B --account-id 01...
   --auth-strategy specified_domains --allowed-domains acme.com --valid-until 2026-09-01T00:00:00Z \
   --landing-template-id 01... --landing-context '{"rep":"Sam"}'
 # bind/unbind a landing template on an existing share
-p dsr bind-landing --id 01... --landing-template-id 01...
-p dsr bind-landing --id 01... --landing-template-id none
+p dsr bind-landing --id 01... --instance-id 01... --landing-template-id 01...
+p dsr bind-landing --id 01... --instance-id 01... --landing-template-id none
 # refuse to reuse an existing share instead of silently returning it
 p dsr create --canvas-id 01... --if-exists error
+# send the download preference explicitly — either direction
+p dsr create --canvas-id 01... --allow-download
+p dsr create --canvas-id 01... --no-allow-download
 # change an existing share — only the flags you pass are sent
 p dsr update --id 01... --valid-until 2026-12-01T00:00:00Z
 p dsr update --id 01... --auth-strategy specified_domains --allowed-domains acme.com
@@ -538,8 +541,29 @@ p dsr delete --id 01...
 p dsr scaffold --out share.json
 ```
 
+### The `--config-file` spec
+
+`p dsr scaffold` prints the starter. The spec has three blocks — `source`, `security`, `landing` — and the CLI sends `source` and `security` **spread verbatim into the create POST body**, so their keys are the wire (snake_case) names, not flag names. `landing` is not part of that body: it becomes a follow-up PUT to `/{id}/landing-page` after the share exists.
+
+The `source` block picks what is shared:
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| `canvas_id` | ULID string | Share an **existing** canvas. Exactly one of `canvas_id` / `sharebox_items`. |
+| `sharebox_items` | `[{ file_id, page_index? }]` | Build a **new** ShareBox canvas from these files and share that. `file_id` is a ULID; an integer `page_index` shares that single page of the file instead of the whole file (`--sharebox-file-ids` can only send whole files, so a per-page share needs the spec). Exactly one of `canvas_id` / `sharebox_items`. |
+| `canvas_name` | string | Name of the ShareBox-built canvas. Server default is `ShareBox <timestamp>`. |
+| `account_id` | ULID string | Account attached to the ShareBox-built canvas. **Required** when the instance is configured to require an account on canvas creation. |
+| `template_id` | ULID string | Canvas template the ShareBox-built canvas is built from. Omitted, the server looks for the instance's `share`-tagged template. |
+| `instance_id` | ULID string | The instance to create in. `--instance-id` overrides it when both are given, and it is also what the landing-page PUT is scoped to. |
+
+`canvas_name`, `account_id`, `template_id` and `security.tags` name or shape the canvas the server **mints**, so they only mean anything for a `sharebox_items` source — with `canvas_id` the canvas already exists and there is nothing to name. `tags` is the one the CLI enforces: a non-empty `tags` alongside `canvas_id` is rejected rather than sent to be dropped. The scaffold's empty `tags: []` is accepted, since it asks for nothing.
+
+`security` holds the access settings (`auth_strategy`, `allowed_emails`, `allowed_domains`, `valid_until`, `allow_forward`, `allow_download`, `tags`) and every key in it is spread into the POST body **exactly as written**. The CLI checks three of them and no more: `auth_strategy` against the allowed values, the `allowed_emails`/`allowed_domains` that strategy requires, and `tags` (above). The rest — `allow_download` included — it forwards untouched and makes no claim about, so read the created share back if you need to confirm a value took. Sending the block as written also matters against an already-shared canvas — see the `--if-exists` note above. `landing` holds `landing_page_template_id` (discover ids with `p dsr-landing list`) and `landing_page_context`; left at the scaffold's `null` / `{}` no landing page is bound at all. Binding one — from the spec or from `--landing-template-id` — needs an instance: `--instance-id` or `source.instance_id`. Without it the CLI skips the bind and returns the share with a warning naming the flag.
+
 `update` PATCHes `/core/api/protected/shared-links/{id}`, which distinguishes an **absent** key from an **explicit null** — so omitting `--valid-until` leaves the stored expiry exactly as it is, and `--clear valid-until` is what resets it. `--clear` is repeatable and accepts `valid-until`, `allowed-emails`, `allowed-domains` (the CLI sends `null` for the first and `[]` for the lists, matching what each field's server schema accepts). An empty `--allowed-emails`/`--allowed-domains` is rejected on both `create` and `update`, because `""` from an unset shell variable would otherwise be sent as `[]` and wipe the stored list. `--clear` is a separate flag rather than an in-value sentinel such as `--valid-until ""` because an empty string is something a script can produce by accident from an unset variable, and `none` is already a real `--auth-strategy` value. `tags` and `--allow-download` are **create-time only** — the PATCH surface does not accept them, and `--clear` says so rather than dropping them silently.
 
+`--allow-download` has a `--no-allow-download` twin, so **both** directions are sendable (PIT-7521). Without it commander could only ever produce `true` or nothing: passing the flag said “allow”, and there was no way to say “do not allow” — the OFF state could not be expressed at all, only left out. Declaration order is load-bearing: the positive flag of each pair is declared first, because commander takes a boolean's default from whichever it sees first. ⚠️ The value records the sharer's **intent** and drives the viewer's UI; it is not a server-side download block — the file URL is already in the payload the browser receives.
+
 **Clearing an allow-list is refused while a strategy that needs it is in force**, because an empty allow-list denies every recipient rather than admitting them — the clear would brick the link, not open it. `specified_emails`/`verified_emails` need `allowed-emails`; `specified_domains`/`verified_domains` need `allowed-domains`. The check covers a strategy passed in the same call **and** the one already stored on the share (read from the public `GET /core/api/shared-links/{id}/config`, since the PATCH surface has no GET). If that read fails the update still goes through, with a warning saying the check did not run. Two ways out:
 
 ```bash
@@ -551,7 +575,7 @@ p dsr update --id 01... --allowed-emails new@acme.com
 
 `create` returns the share as `{ id, type, file, canvas, instance, organization, status, url, short_url }` — **`url` is the full link; there is no `full_url` field.**
 
-Creating, updating and deleting need a share-capable key (`canvas.share` on the link's own instance when `enable_granular_permissions` is on); **binding a landing page currently needs an editor key** (PIT-7525 will open it to reps for their own DSRs) — a denied bind returns the link with a warning. Discover landing template IDs via `p dsr-landing list`.
+Creating, updating and deleting need a share-capable key (`canvas.share` on the link's own instance when `enable_granular_permissions` is on); **binding a landing page** needs `--instance-id`, and an admin or editor key to bind any share in the org — a member key can bind only the shares that member created (PIT-7525). On `create`, a denied bind returns the link with a warning. Discover landing template IDs via `p dsr-landing list`.
 
 ## To run the `ld` command:
 

package/dist/src/commands/dsr.js

@@ -19,9 +19,20 @@ function resolveTemplateId(raw) {
         return null;
     return raw;
 }
+// The landing-page PUT is guarded by next-core's `withAtLeastInstanceAdmin`, which resolves the
+// instance from the URL path, then the request body, then the `instance_id` query param. This route
+// has no instance in its path and the body the CLI sends carries only the landing fields, so the
+// query param is the ONLY source there is: without it the server answers 400 "Instance ID is
+// required" before it ever looks at the share. Catching it here names the missing flag instead of
+// handing back that opaque server error.
+const LANDING_INSTANCE_REQUIRED = '--instance-id is required to bind a landing page: the landing-page endpoint resolves the instance from that query param and refuses the call without it';
+// `instanceId` is REQUIRED, not optional-with-a-ternary: both call sites now refuse an empty one
+// before they get here (`runDsrBindLanding` throws, `runDsrCreate` returns the share with a warning),
+// so a params-less PUT is unreachable — and it was never anything but the guaranteed 400 above.
+// Typing it away is what stops a future caller from quietly reintroducing that call.
 async function bindLandingRequest(client, id, body, instanceId) {
     const url = `${ENDPOINT}/${encodeURIComponent(id)}/landing-page`;
-    const res = await client.put(url, body, instanceId ? { params: { instance_id: instanceId } } : undefined);
+    const res = await client.put(url, body, { params: { instance_id: instanceId } });
     return res.data;
 }
 export async function runDsrBindLanding(opts, deps = {}) {
@@ -31,6 +42,8 @@ export async function runDsrBindLanding(opts, deps = {}) {
         const templateId = resolveTemplateId(opts.landingTemplateId);
         if (templateId === undefined)
             throw createCliError('VALIDATION', '--landing-template-id is required (use "none" to unbind)');
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', LANDING_INSTANCE_REQUIRED);
         const body = { landing_page_template_id: templateId };
         if (opts.landingContext !== undefined)
             body.landing_page_context = parseJsonObject(opts.landingContext, 'landing-context');
@@ -108,6 +121,25 @@ function assertCreateBody(body, instanceId) {
         throw createCliError('VALIDATION', 'pass exactly one source: --canvas-id or --sharebox-file-ids');
     if (hasSharebox && !instanceId && body.instance_id === undefined)
         throw createCliError('VALIDATION', '--instance-id is required for --sharebox-file-ids');
+    const tags = body.tags;
+    // SHAPE first: a hand-written spec can put anything under `security.tags`. The server would refuse a
+    // malformed value too (its ZodError catch answers `400 Invalid request data`), so this is not closing
+    // a hole — it fails before any request, with a message that names the field. This guard already owns
+    // the key, so it owns the shape too — and shape means the ELEMENTS as well: the server field is
+    // `z.array(z.string())`, so `tags: [1]` clears `Array.isArray` and still has to be refused. An EMPTY
+    // array passes both checks, by design.
+    if (tags !== undefined && (!Array.isArray(tags) || tags.some((t) => typeof t !== 'string')))
+        throw createCliError('VALIDATION', 'tags must be an array of strings');
+    // SOURCE second: `tags` is read by exactly one branch of the server route — the ShareBox branch,
+    // where it names the canvas the server MINTS from sharebox_items. With an existing canvas there is
+    // nothing to name: the POST schema still accepts the key and then drops it on the floor, so the
+    // tags vanish with no error at all. Refuse the combination instead of shipping a silent no-op.
+    // An EMPTY array is NOT a request to tag anything: `dsr scaffold` emits `tags: []` in its starter
+    // security block, so rejecting that would break every untouched `--config-file` create.
+    if (hasCanvas && Array.isArray(tags) && tags.length > 0)
+        throw createCliError('VALIDATION', 'tags apply only to a ShareBox-built canvas — they name the canvas the server creates from ' +
+            '--sharebox-file-ids, and with --canvas-id the server ignores them. Drop the tags, or share the ' +
+            'files with --sharebox-file-ids.');
     const strat = body.auth_strategy;
     if (strat !== undefined) {
         if (!AUTH_STRATEGIES.includes(strat))
@@ -223,6 +255,16 @@ export async function runDsrCreate(opts, deps = {}) {
         const shareId = share?.id;
         if (!shareId)
             return ok({ ...share, landing: null }, ['landing not attached: no share id in create response']);
+        // Same missing-instance failure as `dsr bind-landing`, reached from the other call site. It stays
+        // a WARNING rather than a hard failure because the share itself was created successfully and is
+        // the caller's primary output — dropping it would strand a live link with nothing referencing it.
+        // What changes is that the PUT is not attempted at all (it cannot succeed) and the warning names
+        // the flag plus the exact follow-up command, instead of echoing an opaque 400 from the server.
+        if (!effectiveInstanceId)
+            return ok({ ...share, landing: null }, [
+                `landing not attached: ${LANDING_INSTANCE_REQUIRED}. The share itself was created — bind the ` +
+                    `landing page with \`p dsr bind-landing --id ${shareId} --landing-template-id <template-id> --instance-id <instance-id>\``,
+            ]);
         try {
             const landing = await bindLandingRequest(client, shareId, landingBody, effectiveInstanceId);
             return ok({ ...share, landing });
@@ -418,7 +460,7 @@ export function createDsrCommand() {
     });
     withAuthFlags(cmd.command('create'))
         .description('create + share a DSR (canvas share link) and return the link (id, url, short_url, canvas)')
-        .option('--instance-id <id>', 'Instance ID (required for --sharebox-file-ids)')
+        .option('--instance-id <id>', 'Instance ID (required for --sharebox-file-ids, and to bind a landing page)')
         .option('--canvas-id <id>', 'Existing canvas to share (one source required)')
         .option('--sharebox-file-ids <csv>', 'Build a canvas from these file IDs (one source required)', parseTags)
         .option('--canvas-name <name>', 'Name for the ShareBox-built canvas')
@@ -431,7 +473,8 @@ export function createDsrCommand() {
         .option('--allow-forward', 'Allow recipients to forward')
         .option('--no-allow-forward', 'Disallow forwarding')
         .option('--allow-download', 'Allow download')
-        .option('--tags <csv>', 'Tags', parseTags)
+        .option('--no-allow-download', 'Disallow download')
+        .option('--tags <csv>', 'Tags for the ShareBox-built canvas (rejected with --canvas-id, which ignores them)', parseTags)
         .option('--landing-template-id <id>', 'Landing template to bind (optional)')
         .option('--landing-context <json>', 'Landing personalization merge fields (JSON object)')
         .option('--config-file <path>', 'Full {source,security,landing} spec JSON (mutually exclusive with the flags above)')
@@ -449,15 +492,16 @@ export function createDsrCommand() {
         .option('--id <id>', 'Shared link ID (required)')
         .option('--landing-template-id <id>', "Landing template ID, or 'none' to unbind (required)")
         .option('--landing-context <json>', 'Personalization merge fields (JSON object)')
-        .option('--instance-id <id>', 'Instance ID (optional)')
+        .option('--instance-id <id>', 'Instance ID (required — the endpoint resolves the instance from it)')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runDsrBindLanding({ ...options, quiet: globals.quiet }), globals);
     });
-    // --allow-forward is declared BEFORE --no-allow-forward on purpose: commander takes a
-    // boolean's default from whichever of the pair it sees first, so the reverse order would
-    // make `allowForward` default to `true` and every update would ship allow_forward: true,
-    // clobbering a rep's opt-out. `create` above relies on the same ordering.
+    // Every --x is declared BEFORE its --no-x on purpose: commander takes a boolean's default
+    // from whichever of the pair it sees first, so the reverse order would make the option
+    // default to `true` and every call would ship it. For allow_forward that clobbers a rep's
+    // opt-out; for allow_download it would turn an unpassed flag into an active grant.
+    // `create` above relies on the same ordering for BOTH pairs.
     withAuthFlags(cmd.command('update'))
         .description('update an existing share: only the flags you pass are sent; --clear removes a value')
         .option('--id <id>', 'Shared link ID (required)')

package/dist/src/core/http.d.ts

@@ -24,7 +24,8 @@ export declare function clickhouseClientFor(opts: CommonOpts, deps?: {
 /**
  * Build a human-readable message from a server error body. Handles DRF shapes:
  * a `detail`/`error` string, `non_field_errors`, and field-level error arrays
- * (e.g. `{ version: ["already exists"] }`). Falls back to the raw body so the
+ * (e.g. `{ version: ["already exists"] }`), plus next-core's
+ * `{ error, details }` validation shape. Falls back to the raw body so the
  * full server response is visible in logs instead of a bare status line.
  */
 export declare function extractApiMessage(data: unknown, fallback: string): string;

package/dist/src/core/http.js

@@ -35,10 +35,158 @@ export function clickhouseClientFor(opts, deps = {}) {
         },
     });
 }
+/** Max number of `details` entries folded into a message before it is summarised. */
+const MAX_DETAIL_PARTS = 3;
+/** Max characters of joined `details` text, before the `(+N more)` marker is appended. */
+const MAX_DETAIL_CHARS = 200;
+/** How deep to walk a nested `details` value before falling back to JSON. */
+const MAX_DETAIL_DEPTH = 3;
+/**
+ * DRF envelope keys: the two places a serializer puts a message that names no field.
+ * next-core's `upstreamErrorMessage()` (`app/api/utils/upstream-error.ts`) reads `detail`
+ * first and sorts `non_field_errors` ahead of everything else, so a summary derived from a
+ * relayed upstream body is usually one of these two verbatim. Every other key IS a field
+ * name, and naming the field is the whole point of folding `details` in — so only a line
+ * from one of these keys may be dropped for merely repeating the summary.
+ */
+const ENVELOPE_KEYS = new Set(['detail', 'non_field_errors']);
+/**
+ * `JSON.stringify` throws on a circular structure and on a BigInt. This runs inside the
+ * error formatter, so a throw here would lose the API error entirely and print a raw
+ * stack instead — every failure has to collapse to a string.
+ */
+function safeDetailJson(val) {
+    try {
+        const text = JSON.stringify(val, (_key, entry) => (typeof entry === 'bigint' ? String(entry) : entry));
+        return text ?? '[unserializable]';
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * Whether an array entry already identifies itself in the output. A zod issue carries
+ * its own `path`, and an entry that renders as a single scalar (`{ title: ['Required'] }`)
+ * reads better bare; anything else gets an `[i]` so entries do not blur together.
+ */
+function labelsItself(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return true;
+    return typeof entry.message === 'string';
+}
+/**
+ * Flatten one `details` value into human-readable, path-prefixed lines.
+ *
+ * next-core emits several shapes for the same field: zod issues
+ * (`[{ path, message }]`, from `_4xx('Invalid request data', 400, { details: error.errors })`),
+ * a `zod.flatten()` object, a relayed upstream body (`{ details: error.response.data }`),
+ * a plain object (`{ details: { id } }`) and a bare string. All of them collapse to
+ * `path: message` lines here.
+ *
+ * The walk is total: every recursive branch sits below the depth guard, and the guard's
+ * own fallback cannot throw.
+ *
+ * `envelope` marks the lines that descend from a top-level `ENVELOPE_KEYS` key; it is what
+ * lets `renderDetails` drop a relay echo without dropping a labelled field error.
+ */
+function detailParts(val, prefix = '', depth = 0, envelope = false) {
+    if (val == null)
+        return [];
+    const part = (value) => value ? [{ text: prefix ? `${prefix}: ${value}` : value, value, envelope }] : [];
+    if (typeof val === 'string')
+        return part(val.trim());
+    if (typeof val === 'number' || typeof val === 'boolean')
+        return part(String(val));
+    if (typeof val !== 'object')
+        return [];
+    // zod issue shape: `{ path: ['canvas_id'], message: 'Invalid ULID format for canvas_id' }`.
+    // A leaf, so it is answered above the depth guard.
+    if (!Array.isArray(val)) {
+        const obj = val;
+        if (typeof obj.message === 'string' && obj.message.trim()) {
+            const path = Array.isArray(obj.path) ? obj.path.join('.') : '';
+            const scope = [prefix, path].filter(Boolean).join('.');
+            const value = obj.message.trim();
+            return [{ text: scope ? `${scope}: ${value}` : value, value, envelope }];
+        }
+    }
+    if (depth >= MAX_DETAIL_DEPTH)
+        return part(safeDetailJson(val));
+    if (Array.isArray(val)) {
+        return val.flatMap((entry, i) => detailParts(entry, labelsItself(entry) ? prefix : `${prefix}[${i}]`, depth + 1, envelope));
+    }
+    const obj = val;
+    return Object.entries(obj).flatMap(([key, entry]) => 
+    // Only a key at the root of `details` can be the envelope — `{ canvas: { detail: … } }`
+    // is a field named `canvas`, not a DRF envelope.
+    detailParts(entry, prefix ? `${prefix}.${key}` : key, depth + 1, envelope || (!prefix && ENVELOPE_KEYS.has(key))));
+}
+/** Cut `text` to `max` code points — never splitting a surrogate pair — and mark the cut. */
+function truncateDetails(text, max) {
+    const points = [...text];
+    if (points.length <= max)
+        return text;
+    return `${points.slice(0, max - 1).join('').trimEnd()}\u2026`;
+}
+/**
+ * Flatten a `details` value into one capped, de-duplicated line.
+ *
+ * When `summary` is given, two kinds of echo are suppressed, and only these two:
+ *   - a whole rendered line equal to the summary (`_400Validation` in next-core answers a
+ *     failed parse with `"<path>: <message>"`, which is exactly how the same issue renders
+ *     here), and
+ *   - a line from a DRF envelope key (`ENVELOPE_KEYS`) whose message equals the summary —
+ *     the relay path, where `next-core .../shared-links/route.ts` builds its summary with
+ *     `upstreamErrorMessage(body)` and then relays that same body as `details`, so the most
+ *     common `p dsr` 400 would otherwise print `Not found. | detail: Not found.`
+ *
+ * A *field* entry is never dropped for matching the summary, however: in
+ * `{ error: 'This field is required.', details: { canvas: [...], expires_at: [...] } }` the
+ * field path is the only thing telling the user which field, and dropping `canvas` there
+ * left the message actively misleading (PR #5570 review).
+ *
+ * Output is capped so a large validation payload cannot become a wall of text. The
+ * `(+N more)` marker is appended after the cap, so it is never cut into a wrong count.
+ */
+function renderDetails(details, summary) {
+    const seen = new Set();
+    const parts = [];
+    let dropped = 0;
+    for (const { text, value, envelope } of detailParts(details)) {
+        if (summary !== undefined && (text === summary || (envelope && value === summary)))
+            continue;
+        if (seen.has(text))
+            continue;
+        seen.add(text);
+        if (parts.length < MAX_DETAIL_PARTS)
+            parts.push(text);
+        else
+            dropped += 1;
+    }
+    if (!parts.length)
+        return '';
+    let text = truncateDetails(parts.join('; '), MAX_DETAIL_CHARS);
+    if (dropped > 0)
+        text += ` (+${dropped} more)`;
+    return text;
+}
+/**
+ * Fold an error body's `details` into the top-level summary so the user sees both
+ * halves on one line — next-core answers a failed schema parse with a generic
+ * `"Invalid request data"` and puts the only actionable text (the field and why it
+ * was rejected) in `details`, which used to be dropped entirely (PIT-7521).
+ */
+function withDetails(summary, details) {
+    if (details === undefined)
+        return summary;
+    const text = renderDetails(details, summary);
+    return text ? `${summary} | ${text}` : summary;
+}
 /**
  * Build a human-readable message from a server error body. Handles DRF shapes:
  * a `detail`/`error` string, `non_field_errors`, and field-level error arrays
- * (e.g. `{ version: ["already exists"] }`). Falls back to the raw body so the
+ * (e.g. `{ version: ["already exists"] }`), plus next-core's
+ * `{ error, details }` validation shape. Falls back to the raw body so the
  * full server response is visible in logs instead of a bare status line.
  */
 export function extractApiMessage(data, fallback) {
@@ -50,11 +198,22 @@ export function extractApiMessage(data, fallback) {
         return String(data);
     const obj = data;
     if (typeof obj.detail === 'string' && obj.detail)
-        return obj.detail;
+        return withDetails(obj.detail, obj.details);
     if (typeof obj.error === 'string' && obj.error)
-        return obj.error;
+        return withDetails(obj.error, obj.details);
     const parts = [];
     for (const [key, val] of Object.entries(obj)) {
+        // A body carrying `details` but no string `detail`/`error` summary lands here. next-core
+        // cannot produce that shape (`_4xx` always emits `{ error: message, ...data }`), but Django
+        // or another upstream can — and the generic rendering below would `join('; ')` structured
+        // entries into `details: [object Object]`, so walk it the same way `withDetails` does.
+        if (key === 'details') {
+            const rendered = renderDetails(val);
+            if (rendered) {
+                parts.push(rendered);
+                continue;
+            }
+        }
         const text = Array.isArray(val) ? val.join('; ') : typeof val === 'string' ? val : JSON.stringify(val);
         parts.push(key === 'non_field_errors' ? text : `${key}: ${text}`);
     }

package/dist/src/mcp/prompts/dsr.js

@@ -20,6 +20,8 @@ export const dsrPrompts = [
                 '',
                 '## DSR sharing guidance',
                 '- **Source is exactly one of** a canvas (`canvasId`) OR files (`shareboxFileIds`).',
+                '- **`tags` are ShareBox-only.** They name the canvas the server builds from `shareboxFileIds`, so non-empty ' +
+                    '`tags` together with `canvasId` is rejected rather than silently ignored.',
                 `- **Pick the gating (\`authStrategy\`) by audience.** For ${audience}: internal/quick demo → \`none\` ` +
                     '(open link); a known individual → `specified_emails` (+ `allowedEmails`); a company → ' +
                     '`specified_domains` (+ `allowedDomains`); the server default is `any_email`. Add `validUntil` ' +
@@ -27,6 +29,8 @@ export const dsrPrompts = [
                 '- **Branding the pre-auth page is a SEPARATE step:** this recipe only **binds** an existing ' +
                     'landing template (`landingTemplateId`, discover via `pitcher_dsr_landing_list`; pass ' +
                     '`landingContext` merge fields **as a JSON object serialized to a string**, not as an object). ' +
+                    '**A landing bind needs `instanceId`** — the endpoint resolves the instance from it, so without it the bind ' +
+                    'is skipped and the share comes back with a warning. ' +
                     'If no suitable template exists and the user wants a ' +
                     'branded landing, author one FIRST with the **`seed_dsr_landing`** recipe, then bind its id here. ' +
                     'Do NOT hand-write landing HTML in this recipe.',

package/dist/src/mcp/tools/dsr.js

@@ -7,9 +7,9 @@ export const dsrTools = [
     {
         name: 'pitcher_dsr_create',
         title: 'Create and share a DSR',
-        description: 'Create a Digital Sales Room (a canvas share link) and get a clickable link back. Source is a canvas (canvasId) OR files (shareboxFileIds) - exactly one. Optional email/domain gating and a bound landing-page template. Returns the share: id, url (the full link), short_url, and a nested canvas object - there is no full_url field. This endpoint is a GET-OR-CREATE: with individual fields, sharing an already-shared canvas returns the existing link and only updates the fields you pass, so use pitcher_dsr_update to change or remove a value on an existing share. A configFile spec sends its whole security block (nulls and empty lists included), so for an already-shared canvas it refuses by default (ifExists "error"). A failed landing bind does not fail the call: it returns the link with a warning.',
+        description: 'Create a Digital Sales Room (a canvas share link) and get a clickable link back. Source is a canvas (canvasId) OR files (shareboxFileIds) - exactly one. Optional email/domain gating and a bound landing-page template. Returns the share: id, url (the full link), short_url, and a nested canvas object - there is no full_url field. This endpoint is a GET-OR-CREATE: with individual fields, sharing an already-shared canvas returns the existing link and only updates the fields you pass, so use pitcher_dsr_update to change or remove a value on an existing share. A configFile spec sends its whole security block (nulls and empty lists included), so for an already-shared canvas it refuses by default (ifExists "error"). A failed landing bind does not fail the call: it returns the link with a warning - and binding a landing page needs instanceId, without which the bind is skipped with that warning. tags are a ShareBox-only field (they name the canvas the server builds from shareboxFileIds), so non-empty tags together with canvasId are REJECTED rather than silently dropped by the server.',
         inputShape: {
-            instanceId: z.string().optional().describe('Instance ID (required for the shareboxFileIds source)'),
+            instanceId: z.string().optional().describe('Instance ID (required for the shareboxFileIds source, and to bind a landing page)'),
             canvasId: z.string().optional().describe('Canvas to share (exactly one of canvasId / shareboxFileIds)'),
             shareboxFileIds: z.array(z.string()).optional().describe('File IDs to build a share from (exactly one of canvasId / shareboxFileIds)'),
             canvasName: z.string().optional().describe('Name for the ShareBox-built canvas'),
@@ -20,9 +20,18 @@ export const dsrTools = [
             allowedDomains: z.array(z.string()).optional().describe('Required for specified_domains / verified_domains. An EMPTY array is rejected'),
             validUntil: z.string().optional().describe('Expiry, ISO datetime'),
             allowForward: z.boolean().optional(),
-            allowDownload: z.boolean().optional(),
-            tags: z.array(z.string()).optional(),
-            landingTemplateId: z.string().optional().describe('Bind a landing-page template (discover via pitcher_dsr_landing_list)'),
+            allowDownload: z
+                .boolean()
+                .optional()
+                .describe('Let recipients download the shared files. Create-time only (pitcher_dsr_update does not accept it). Sent to the server exactly as given for either source - unlike tags, the CLI applies no source-specific guard to it, so read the created share back if you need to confirm the value took'),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe('Tags for the ShareBox-built canvas. ShareBox source ONLY - a non-empty array together with canvasId is rejected, because the server reads tags only when it builds the canvas itself and would otherwise ignore them. An empty array is accepted (it asks for nothing)'),
+            landingTemplateId: z
+                .string()
+                .optional()
+                .describe('Bind a landing-page template (discover via pitcher_dsr_landing_list). Needs instanceId: without it the bind is skipped and the share comes back with a warning'),
             landingContext: z.string().optional().describe('Landing-page merge fields, a JSON object as a string'),
             configFile: z.string().optional().describe('Path on the MCP server host to a full {source,security,landing} spec JSON; mutually exclusive with the individual flags'),
             ifExists: z
@@ -37,12 +46,14 @@ export const dsrTools = [
     {
         name: 'pitcher_dsr_bind_landing',
         title: 'Bind a DSR landing page',
-        description: 'Attach, re-brand, or unbind a landing-page template on an existing DSR share. Use landingTemplateId "none" to unbind. Requires an editor-level key (hard-fails AUTH otherwise).',
+        description: 'Attach, re-brand, or unbind a landing-page template on an existing DSR share. Use landingTemplateId "none" to unbind. instanceId is REQUIRED: the endpoint resolves the instance from that query param and refuses the call without it. An admin or editor key can bind any share in the org; a member key only shares that member created (hard-fails AUTH otherwise).',
         inputShape: {
             id: z.string().describe('Shared-link ID'),
             landingTemplateId: z.string().describe('Landing template ID, or "none" to unbind'),
             landingContext: z.string().optional().describe('Landing-page merge fields, a JSON object as a string'),
-            instanceId: z.string().optional(),
+            instanceId: z
+                .string()
+                .describe('Instance ID. The endpoint resolves the instance from this query param and rejects the call without it'),
         },
         run: runDsrBindLanding,
         readOnly: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.17.1",
+  "version": "2.18.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",