@doclift/workflows-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CapSens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# Doclift workflows — MCP server
+
+An MCP server over the workflow authoring API, so that an agent can build,
+inspect and reproduce a Doclift workflow without a browser.
+
+## What it does not do
+
+**It holds no catalogue.** What a caller may write — the section kinds, the
+condition operators, the faces the renderer carries, the ceilings this
+organization is held to — is answered live by `workflow_capabilities`, which
+reads them from the model and from the organization's own columns. Nothing here
+is a copy, on purpose: a copy is a copy that will be wrong, and an agent that
+trusted it would write values the API refuses without understanding why.
+
+What *is* written down here is the part the API cannot express: the order
+operations have to happen in, and the failures that answer 200.
+
+## Running it
+
+```bash
+npm install
+npm run build
+
+DOCLIFT_API_KEY=<the key you send in X-Api-Key> \
+DOCLIFT_API_URL=https://app.doclift.io \
+  node dist/index.js
+```
+
+| Variable | Required | Default |
+|---|---|---|
+| `DOCLIFT_API_KEY` | yes | — |
+| `DOCLIFT_API_URL` | no | `https://app.doclift.io` |
+
+The key must belong to an organization the workflow editor is open to, and it
+carries the same rights it carries on the REST API — no more.
+
+### As a client would declare it
+
+```json
+{
+  "mcpServers": {
+    "doclift-workflows": {
+      "command": "node",
+      "args": ["/path/to/mcp/dist/index.js"],
+      "env": { "DOCLIFT_API_KEY": "…", "DOCLIFT_API_URL": "…" }
+    }
+  }
+}
+```
+
+## Calling it from a terminal
+
+`bin/mcp-call.mjs` speaks to the server over the same stdio transport a real
+client uses. It exists so the server can be exercised the way an agent meets it
+— the tool list, the schemas, the descriptions, the guides, the error text.
+
+```bash
+node bin/mcp-call.mjs tools                             # every tool, with its schema
+node bin/mcp-call.mjs resources                         # the guides
+node bin/mcp-call.mjs read doclift://guides/how-to-build
+node bin/mcp-call.mjs call workflow_capabilities '{}'
+node bin/mcp-call.mjs call workflow_create '{"title":"Bulletin","description":"…"}'
+```
+
+A call prints `OK` or `REFUSED` before its payload: a tool that refused is not a
+tool that answered, and flattening the two would hide the thing these runs look
+for.
+
+## The tools
+
+| Group | Tools |
+|---|---|
+| Catalogue | `workflow_capabilities` |
+| Workflows | `workflow_list`, `workflow_get`, `workflow_create`, `workflow_update`, `workflow_delete` |
+| Checking | `workflow_validate`, `workflow_payload_contract` |
+| Publication | `workflow_publish`, `workflow_unpublish` |
+| Whole document | `workflow_document_get`, `workflow_document_put` |
+| Theme | `theme_get`, `theme_update` |
+| Tree | `section_tree`, `section_get`, `section_create`, `section_update`, `section_move`, `section_duplicate`, `section_delete` |
+| Backdrops | `section_background_set`, `section_background_remove` |
+| Variables | `variable_list`, `variable_create`, `variable_update`, `variable_delete` |
+| Datasets | `dataset_list`, `dataset_create`, `dataset_update`, `dataset_delete` |
+| Pictures | `image_upload`, `image_list` |
+| Generation | `workflow_render` |
+| Self-check | `workflow_selfcheck` |
+
+## The guides
+
+Five resources, read with `resources/read`:
+
+- `doclift://guides/how-to-build` — the order, and the three silent failures
+- `doclift://guides/conditions` — which key each operator takes
+- `doclift://guides/repetitions` — section repetition against row repetition
+- `doclift://guides/before-you-finish` — what can be checked, and the one thing that cannot
+- `doclift://guides/anomalies` — what blocks publication and what only warns
+
+## Three things worth knowing before the first build
+
+**A human in the builder wins.** While somebody holds the editing lock on a
+workflow, every write through this server is refused with 409. Reads are
+unaffected, and `workflow_get` reports `being_edited` so the refusal is never a
+surprise.
+
+**Three failures answer 200.** Content sanitising, placement key spelling, and
+declaring inline what the theme already says. `workflow_validate` is the only
+tool that sees the first coming; the other two are described where they can be
+made.
+
+**A green run is not a finished job.** `workflow_selfcheck` reads the workflow
+back and answers a checklist from its actual state — tokens the interpolator
+will never read, pictures the engine cannot fetch, variables declared and never
+used, and whether a PDF exists that is newer than the last edit. It also names
+the one line it can never tick: that the document is the one that was asked for.
+Only reading the PDF answers that.

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+export interface ClientOptions {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly timeoutMs?: number;
+}
+export interface ApiSuccess<T> {
+    readonly ok: true;
+    readonly status: number;
+    readonly body: T;
+}
+export interface ApiFailure {
+    readonly ok: false;
+    readonly status: number;
+    /** Every message the API returned, already flattened out of `error`/`errors`. */
+    readonly messages: readonly string[];
+}
+export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
+export declare class ApiClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    constructor({ baseUrl, apiKey, timeoutMs }: ClientOptions);
+    get<T>(path: string, query?: Record<string, string | number | undefined>): Promise<ApiResult<T>>;
+    post<T>(path: string, body?: unknown): Promise<ApiResult<T>>;
+    patch<T>(path: string, body?: unknown): Promise<ApiResult<T>>;
+    put<T>(path: string, body?: unknown): Promise<ApiResult<T>>;
+    delete<T>(path: string): Promise<ApiResult<T>>;
+    private withQuery;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,92 @@
+// The one door onto the Doclift API.
+//
+// Every tool goes through `request`, which is also the only place that knows how
+// the API words a refusal. A tool that read `response.status` itself would be a
+// second reading of the same contract, and the two would part company the first
+// time a status changed.
+const DEFAULT_TIMEOUT_MS = 30_000;
+export class ApiClient {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    constructor({ baseUrl, apiKey, timeoutMs }) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.apiKey = apiKey;
+        this.timeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async get(path, query) {
+        return this.request('GET', this.withQuery(path, query));
+    }
+    async post(path, body) {
+        return this.request('POST', path, body);
+    }
+    async patch(path, body) {
+        return this.request('PATCH', path, body);
+    }
+    async put(path, body) {
+        return this.request('PUT', path, body);
+    }
+    async delete(path) {
+        return this.request('DELETE', path);
+    }
+    withQuery(path, query) {
+        if (!query)
+            return path;
+        const pairs = Object.entries(query).filter(([, value]) => value !== undefined && value !== '');
+        if (pairs.length === 0)
+            return path;
+        const search = new URLSearchParams(pairs.map(([key, value]) => [key, String(value)]));
+        return `${path}?${search.toString()}`;
+    }
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    'X-Api-Key': this.apiKey,
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: controller.signal,
+            });
+            // 204 carries nothing, and JSON.parse('') throws — which used to surface as
+            // "Unexpected end of JSON input" on a delete that had in fact succeeded.
+            const text = await response.text();
+            const parsed = text.length === 0 ? null : safeParse(text);
+            if (response.ok) {
+                return { ok: true, status: response.status, body: parsed };
+            }
+            return { ok: false, status: response.status, messages: messagesOf(parsed, response.status) };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return { ok: false, status: 0, messages: [`The API could not be reached: ${reason}`] };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+const safeParse = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { error: text };
+    }
+};
+// The API says `error` for one message and `errors` for a list. Both shapes reach
+// a caller as a list, so no tool has to ask which one it got.
+const messagesOf = (parsed, status) => {
+    if (parsed && typeof parsed === 'object') {
+        const payload = parsed;
+        if (Array.isArray(payload.errors))
+            return payload.errors.map(String);
+        if (typeof payload.error === 'string')
+            return [payload.error];
+    }
+    return [`The API answered ${status} without saying why.`];
+};

package/dist/guidance.d.ts

@@ -0,0 +1,5 @@
+export declare const HOW_TO_BUILD: string;
+export declare const CONDITIONS: string;
+export declare const REPETITIONS: string;
+export declare const ANOMALIES: string;
+export declare const BEFORE_YOU_FINISH: string;

package/dist/guidance.js

@@ -0,0 +1,219 @@
+// What an agent cannot read off the API.
+//
+// Everything that is a *catalogue* — the kinds, the operators, the faces, the
+// limits — is served by `GET /api/v1/workflows/capabilities` and must never be
+// written down here: a second copy is a copy that will be wrong. What lives in
+// this file is the part that is not data: the order to do things in, and the
+// three mistakes that produce no error at all.
+export const HOW_TO_BUILD = `
+# Building a workflow through this server
+
+## Read before you write
+
+Call \`workflow_capabilities\` first, once per session. It answers with the
+catalogues **for this organization** — the allowed kinds, the operators split by
+the shape of value they take, the faces the renderer is provisioned with, and
+the limits your account is actually held to. Nothing in this server hardcodes
+them, and neither should you.
+
+## The order that works
+
+1. \`workflow_create\` — title and description; the page setup can follow.
+2. \`variable_create\` — every variable **before** any content that cites one.
+   A citation is a string, not a foreign key: writing content first succeeds and
+   leaves you a broken reference to find later.
+3. \`theme_update\` — the document's own face, size, ink and leading.
+4. \`section_create\` — the tree, top down. A group can carry its children in the
+   same call.
+5. \`workflow_validate\` — before publishing, and after any large edit.
+6. \`workflow_publish\` — refused while a blocking anomaly stands.
+7. \`workflow_render\`, then **fetch the URL it answers with and read the PDF**.
+8. \`workflow_selfcheck\` — the last step, always. It reads the workflow back and
+   answers what is still wrong: tokens the interpolator will never look at,
+   pictures the engine cannot fetch, variables nothing cites, and whether the
+   PDF you read predates your last edit. Do not report a workflow as finished
+   before its \`outstanding\` count is zero.
+
+## Anomalies are not write errors
+
+A write refuses what is wrong with **the node**: a group carrying content, a
+fourth level, a repetition inside a repetition. It does not refuse what is wrong
+with **the document** — a broken reference, a nested table-row loop, a comparison
+on a collection. Those are anomalies: they answer 200, they surface in
+\`workflow_validate\`, and they refuse publication.
+
+So a section can be saved in a state that will never publish, on purpose: work
+in progress is allowed. Run \`workflow_validate\` after building, not only before
+publishing.
+
+## The three mistakes that produce no error
+
+**1. An attribute that is not on the list is removed without a word.** The save
+answers 200, and the mark is gone. \`workflow_validate\` is the only way to see it
+coming: it reports what sanitising *would* strip from content you have not
+written yet.
+
+**2. A placement key spelled differently is dropped.** The label survives its
+first save and then renders as nothing. The exact key names are in
+\`capabilities.placement\`; there is no near-miss tolerance.
+
+**2 bis. A variable token is recognised by its CLASS, not by its tag.** Write
+the whole thing, exactly as \`capabilities.content.tokens\` gives it:
+
+\`\`\`html
+<variable class="editor-text-variable non-editable-content editor-parsed">investor_name</variable>
+\`\`\`
+
+The name is the **inner text**; only an *image* token reads \`data-src\`. A
+\`<variable>\` without \`editor-parsed\` survives sanitising, satisfies the
+integrity check, and prints the name of the variable instead of its value.
+\`workflow_validate\` reports those as \`inert_tokens\`.
+
+**2 quinquies. A CSS property is dropped from inside a \`style\` that survives.**
+The attribute is on the allow list, its contents are filtered against a list of
+their own. \`text-transform\` goes, \`style\` stays, and nothing about the element
+looks different — measured, and it is what turns small-caps labels back into
+sentence case. \`workflow_validate\` reports these as
+\`removed_css_declarations\`. When a property you need is not carried, write the
+result rather than the instruction: put the capitals in the text.
+
+**2 quater. A block element written inside a \`<p>\` is moved out of it.** The
+parser cuts the paragraph in three and drops the block between the halves — a
+callout written as \`<p>text <div>…</div> more</p>\` comes back as three
+siblings. Nothing is removed, so even the before/after comparison reads clean.
+\`workflow_validate\` reports these as \`ejected_from_paragraph\`. Write a block
+as a sibling of your paragraphs, never inside one.
+
+**2 ter. A picture cited by an external URL prints an empty frame.** The engine
+makes no network request at render time, so every picture has to go through
+\`image_upload\` and be cited by the URL it answers with. \`workflow_validate\`
+reports the others under \`unreachable_images\`.
+
+**3. Declaring inline what the theme already says freezes the document.** It
+looks identical today and stops following the theme forever. Set the theme, then
+write only what departs from it. This is the mistake that costs the most and
+shows the least.
+
+A fourth, of the same family: **a theme declaration that will not parse is
+dropped, not refused.** \`font_size\` is a string carrying its unit (\`"11pt"\`,
+never \`11\`) and \`line_height\` is unitless. Read the theme back after writing
+it; what is missing is what was thrown away.
+
+## Reproducing an existing document
+
+Ask for the face by the name the renderer carries, not by the name on the
+original. \`capabilities.authoring.fonts\` gives, for each family, what it stands
+in for and whether the substitution is **metric** — identical advance widths, so
+the line breaks and the page count are the ones the original had — or
+**approximate**, in which case the text will reflow and the page count is not
+guaranteed.
+
+\`capabilities.authoring.fidelity_meanings\` defines the three words. In
+particular \`none\` means the family stands in for nothing because it is an
+original face — it is always available, and it is not a warning.
+
+Then: \`workflow_render\` produces a real PDF from a dataset, which is the only
+honest way to check a reproduction.
+`.trim();
+export const CONDITIONS = `
+# Conditions
+
+A condition is flat — a \`match\` and a list of rules, with no nesting:
+
+\`\`\`json
+{"match": "all", "rules": [{"variable": "residence", "operator": "eq", "value": "France"}]}
+\`\`\`
+
+\`match\` is \`all\` or \`any\`. **Any other value is read as \`all\`**, silently.
+
+The key a rule carries depends on the operator, and \`capabilities.condition.operators\`
+says which: single-value operators take \`value\`, membership operators take
+\`values\` (a list), and \`blank\`/\`present\` take neither. Sending \`value\` with
+\`present\` is not a syntax error, it is an operator that ignores it.
+
+**On a variable of type \`collection\`, only \`present\` and \`blank\` mean anything.**
+Any other operator reaches the normaliser, which reads an array as its string
+form and matches nothing an author would ever write. It is a blocking anomaly,
+not a runtime surprise.
+
+A rule naming a variable that no longer exists is **kept**, not cascaded away, so
+that it can be reported as broken rather than disappear. Deleting a variable
+therefore breaks nothing at write time and everything at render time.
+`.trim();
+export const REPETITIONS = `
+# The two repetitions, which are not the same thing
+
+**Section repetition — \`repeat_over\`.** The whole node is printed once per row
+of the named collection. Nesting one inside another is refused: two nested
+repetitions would print the cartesian product of two collections. The refusal is
+checked in both directions — ancestors and descendants — because the tree is
+saved one node at a time.
+
+**Table row repetition — \`data-loop\`.** You draw **one** \`<tr>\` and mark it
+\`data-loop="collection_name"\`; the document carries as many as the payload does.
+It runs *before* interpolation. A collection that is absent, empty or malformed
+removes **the row** and leaves the table standing: a table with a header and no
+body says "no movement", a missing table says nothing.
+
+Inside a repeated row, \`collection.field\` expands to \`collection.i.field\`.
+Citing \`collection.field\` **outside** the loop that carries it is a blocking
+anomaly.
+
+Two nested \`data-loop\` rows are a blocking anomaly too.
+`.trim();
+export const ANOMALIES = `
+# What blocks publication, and what only warns
+
+\`workflow_validate\` returns anomalies, each with a type, whether it blocks, and
+the node it points at. \`capabilities.anomalies\` is the authoritative list of
+which types block — do not infer it from the name.
+
+The distinction is deliberate. \`empty_membership\` — an \`in\` with an empty list —
+does **not** block: an empty rule sitting in an \`any\` next to a complete sister
+decides nothing, and refusing to publish a workflow that works would be wrong.
+\`missing_background\` does not block either: an image section without its backdrop
+is work in progress, not an error.
+`.trim();
+export const BEFORE_YOU_FINISH = `
+# Before you say it is done
+
+A document that saved cleanly, validated cleanly and generated successfully can
+still be wrong in a way nothing reported. Three of this API's failures answer
+200, and a fourth — the one that costs the most — is not a failure of the API at
+all: it is having built something that is not what was asked for.
+
+\`workflow_selfcheck\` answers this list from the workflow's actual state. It is
+not a reminder; it reads the database and tells you which lines are already
+satisfied.
+
+## What it can check for you
+
+1. **Nothing blocks publication.** Anomalies, with the node each points at.
+2. **No token is inert.** A \`<variable>\` written with the right tag and the
+   wrong class prints the name of the variable. It survives saving, satisfies
+   the integrity check, and is invisible everywhere else.
+3. **No picture is unreachable.** The engine makes no network request, and a
+   token that no longer names a stored image is removed at render time.
+4. **No variable was declared and never used.** The mirror of a broken
+   reference: it usually means a token was written with a typo, and the typo
+   became a second, dead name.
+5. **A PDF exists, and it is newer than your last edit.** If you rendered before
+   your last change, what you looked at is not what you have.
+
+## What it cannot check, and you must
+
+**That the document is the one that was asked for.** No tool can compare your
+result to an intention it never saw. Download the PDF, read it, and compare it
+line by line with the request — the wording, the order of the sections, the
+values in place of the tokens, the page count.
+
+\`workflow_render\` answers with a URL. Fetch it. Reading the bytes is the only
+step of this whole procedure that no tool will do for you, and it is the one
+that catches everything the others cannot.
+
+## The honest ending
+
+If something could not be reproduced, say so and say why. A reproduction that is
+90% right and presented as complete costs more than one that names its own gap:
+the reader stops looking.
+`.trim();

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// The Doclift workflow authoring server, spoken over stdio.
+//
+// It is a thin skin on the public API and holds no catalogue of its own: what a
+// caller may write is answered by `workflow_capabilities`, live and scoped to the
+// organization the key belongs to. The only knowledge that lives here is the
+// knowledge the API cannot express — the order to do things in, and the failures
+// that succeed.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { ApiClient } from './client.js';
+import { registerTools } from './tools/index.js';
+import { ANOMALIES, BEFORE_YOU_FINISH, CONDITIONS, HOW_TO_BUILD, REPETITIONS } from './guidance.js';
+const DEFAULT_BASE_URL = 'https://app.doclift.io';
+const readConfig = () => {
+    const apiKey = process.env['DOCLIFT_API_KEY'];
+    if (!apiKey) {
+        process.stderr.write('DOCLIFT_API_KEY is not set. It is the same key the REST API takes in X-Api-Key.\n');
+        process.exit(1);
+    }
+    return { baseUrl: process.env['DOCLIFT_API_URL'] ?? DEFAULT_BASE_URL, apiKey };
+};
+const GUIDES = [
+    {
+        name: 'how-to-build',
+        title: 'Building a workflow',
+        description: 'The order operations have to happen in, and the three mistakes that raise no error.',
+        text: HOW_TO_BUILD,
+    },
+    {
+        name: 'conditions',
+        title: 'Conditions',
+        description: 'How a rule is shaped, which key each operator takes, and what a collection allows.',
+        text: CONDITIONS,
+    },
+    {
+        name: 'repetitions',
+        title: 'The two repetitions',
+        description: 'Section repetition and table-row repetition, and why they must not be confused.',
+        text: REPETITIONS,
+    },
+    {
+        name: 'before-you-finish',
+        title: 'Before you say it is done',
+        description: 'What the workflow can be checked for, and the one thing only you can check.',
+        text: BEFORE_YOU_FINISH,
+    },
+    {
+        name: 'anomalies',
+        title: 'Anomalies',
+        description: 'What blocks publication, what only warns, and why the line is drawn where it is.',
+        text: ANOMALIES,
+    },
+];
+const main = async () => {
+    const { baseUrl, apiKey } = readConfig();
+    const server = new McpServer({ name: 'doclift-workflows', version: '0.1.0' }, {
+        instructions: 'Authoring of Doclift workflows: conditional PDF documents assembled from a tree of sections. ' +
+            'Call `workflow_capabilities` before writing anything — it carries the catalogues and the ' +
+            'limits for this organization, and nothing in this server duplicates them. Read the ' +
+            '`how-to-build` resource before a first build: three of this API\'s failure modes answer 200 ' +
+            'and lose what you sent. Finish with `workflow_selfcheck` — it reads the workflow back and ' +
+            'names what is still wrong. A workflow that saved, validated and generated can still be ' +
+            'broken in ways only it reports.',
+    });
+    registerTools(server, new ApiClient({ baseUrl, apiKey }));
+    for (const guide of GUIDES) {
+        server.registerResource(guide.name, `doclift://guides/${guide.name}`, { title: guide.title, description: guide.description, mimeType: 'text/markdown' }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: 'text/markdown', text: guide.text }] }));
+    }
+    registerPrompts(server);
+    await server.connect(new StdioServerTransport());
+};
+// Two procedures rather than two descriptions. Both start by reading the
+// catalogue and both end at `workflow_validate`, because the order is the part
+// that cannot be inferred from a tool list.
+const registerPrompts = (server) => {
+    const message = (text) => ({
+        messages: [{ role: 'user', content: { type: 'text', text } }],
+    });
+    server.registerPrompt('reproduce_document', {
+        title: 'Reproduce an existing document',
+        description: 'The procedure for turning a document you have in front of you into a workflow.',
+        argsSchema: {
+            source: z.string().describe('What the original is: its sections, its typography, its variable parts.'),
+        },
+    }, ({ source }) => message([
+        `Reproduce this document as a Doclift workflow:\n\n${source}\n`,
+        'Work in this order, and do not skip a step:',
+        '',
+        '1. `workflow_capabilities`, and read the `authoring` block. It says what the editor can',
+        '   actually produce, which is narrower than what survives sanitising.',
+        '2. Match every face of the original against `authoring.fonts`. Ask for the family the',
+        '   renderer carries, not the name on the original — and note the `fidelity`: `metric`',
+        '   means the line breaks and the page count are preserved, `approximate` means the text',
+        '   will reflow and you should say so rather than promise an identical result.',
+        '3. `workflow_create`, then set the page: orientation and the four margins.',
+        '4. `theme_update` with the document\'s own face, size, ink and leading — BEFORE any',
+        '   content. Everything that stays silent then follows it.',
+        '5. `variable_create` for every part that changes between two copies of the original.',
+        '6. `section_create`, top down. Write inline styling ONLY where a passage departs from',
+        '   the theme. Styling every paragraph with the theme\'s own values looks identical today',
+        '   and freezes the document forever.',
+        '7. `workflow_validate`, passing the content you are about to write, until it comes back',
+        '   clean. Then publish, then `workflow_render` with a dataset, fetch the URL it answers',
+        '   with, and read the PDF against the original.',
+        '8. `workflow_selfcheck` last, always. Do not report this as finished while its',
+        '   `outstanding` count is above zero.',
+        '',
+        'A document has a look as well as a text, and reproducing only the text is how a',
+        'reproduction reads as a draft. Carry over its ink — accent colours, tinted callouts,',
+        'grey labels — with `style` on the element, and its typographic treatment: a heading',
+        'set in small capitals, a coloured rule down the left of a section title, a band behind',
+        'it. A callout is a single block CONTAINING its text, never a bordered box above it.',
+        'The self-check hands you the palette your document declares: if the original had an',
+        'accent and yours comes back in greys, you have left something out.',
+        '',
+        'Report what you could not reproduce and why, rather than approximating in silence.',
+    ].join('\n')));
+    server.registerPrompt('audit_workflow', {
+        title: 'Audit a workflow',
+        description: 'Read a workflow you did not build and report what is wrong with it.',
+        argsSchema: { id: z.string().describe('The workflow identifier.') },
+    }, ({ id }) => message([
+        `Audit workflow ${id}.`,
+        '',
+        '1. `workflow_capabilities` for the catalogue and the ceilings.',
+        `2. \`workflow_document_get\` with id ${id} — the whole thing in one read.`,
+        `3. \`workflow_validate\` with id ${id} — the anomalies, and which of them block.`,
+        `4. \`workflow_selfcheck\` with id ${id} — what is wrong with the workflow as stored, which`,
+        '   is where an audit finds what its author never saw.',
+        '',
+        'Then report, in this order: what blocks publication; what is merely advisory and why it',
+        'was judged not to block; every reference naming a variable that no longer exists; every',
+        'passage that declares inline what the theme already says, which is invisible today and',
+        'stops following the theme forever; and anything that would print differently from what',
+        'its author appears to have intended.',
+    ].join('\n')));
+};
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+    process.exit(1);
+});

package/dist/tools/capabilities.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../client.js';
+export declare const registerCapabilities: (server: McpServer, api: ApiClient, base: string) => void;

package/dist/tools/capabilities.js

@@ -0,0 +1,13 @@
+import { respond } from './shared.js';
+export const registerCapabilities = (server, api, base) => {
+    // ---------------------------------------------------------------- catalogue
+    server.registerTool('workflow_capabilities', {
+        title: 'Read what may be written',
+        description: 'The authoring catalogue for this organization: section kinds and what each may carry, page ' +
+            'breaks and layouts, condition operators split by the shape of value they take, placement keys ' +
+            'by kind, the faces the renderer is provisioned with, the tags and attributes that survive ' +
+            'sanitising, the anomaly types and which of them block publication, and the limits this account ' +
+            'is held to. Call this first, once. Nothing here is a constant you may assume.',
+        annotations: { readOnlyHint: true },
+    }, async () => respond(await api.get(`${base}/capabilities`)));
+};

package/dist/tools/checks.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../client.js';
+export declare const registerChecks: (server: McpServer, api: ApiClient, base: string) => void;