plotwork 0.1.0__py3-none-any.whl

plotwork/_generated.py

@@ -0,0 +1,2201 @@
+# Generated by scripts/gen-python.mjs from spec/openapi.json. Do not edit by hand: run `pnpm gen:python`.
+"""Every schema of the Plotwork API as a ``TypedDict``, and every ``/v1`` operation as a typed method."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any, Dict, List, Literal, NoReturn, Optional, TypedDict, Union, cast
+
+from ._request import Transport
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, Unpack
+elif TYPE_CHECKING:
+    from typing_extensions import NotRequired, Unpack
+
+
+class ApprovalHold(TypedDict):
+    """Present when the organisation's "Publishing needs approval" or "Public sharing needs approval" held this. It is data, not an error: the diagram is stored, and only its publisher and the approvers can see it until an approver approves."""
+
+    state: Literal["pending"]
+    #: The request, as the Approvals queue lists it.
+    requestId: str
+    #: `publish` (a new diagram), `change` (a new version of one the library shows) or `share` (a public link).
+    kind: Literal["publish", "change", "share"]
+    #: When the daily sweep ends the request if nobody decides it, in milliseconds since the epoch: thirty days after it was made.
+    expiresAt: int
+    #: One sentence to tell the person: held for approval by the organisation, and what happens next.
+    message: str
+    #: The warning code a tool answer carries for it: W601.
+    code: str
+
+
+class CheckPatternInputPatternTemplates(TypedDict):
+    neutral: NotRequired[str]
+    aws: NotRequired[str]
+    azure: NotRequired[str]
+    gcp: NotRequired[str]
+
+
+class CheckPatternInputPatternSlotsItem(TypedDict):
+    id: str
+    default: str
+    meaning: str
+
+
+class CheckPatternInputPatternNotes(TypedDict):
+    keep: NotRequired[str]
+    rename: NotRequired[str]
+    split: NotRequired[str]
+
+
+# The pattern file. Every field is described at https://docs.plotwork.dev/schemas/plotwork.pattern.json; get_pattern with file true gives one to start from.
+CheckPatternInputPattern = TypedDict(
+    "CheckPatternInputPattern",
+    {
+        "$schema": "NotRequired[str]",
+        "name": "str",
+        "title": "str",
+        "summary": "str",
+        "whenToUse": "NotRequired[str]",
+        "tags": "NotRequired[List[str]]",
+        "templates": "CheckPatternInputPatternTemplates",
+        "slots": "NotRequired[List[CheckPatternInputPatternSlotsItem]]",
+        "notes": "NotRequired[CheckPatternInputPatternNotes]",
+    },
+)
+
+
+class CheckPatternInput(TypedDict):
+    """A pattern file to check before it is published or imported."""
+
+    #: The pattern file. Every field is described at https://docs.plotwork.dev/schemas/plotwork.pattern.json; get_pattern with file true gives one to start from.
+    pattern: CheckPatternInputPattern
+
+
+class CheckPatternResponseProblemsItem(TypedDict):
+    #: Where the problem is: name, title, templates.aws, slots.0.default, and so on; json for a file that is not JSON.
+    field: str
+    message: str
+    #: How to fix it.
+    hint: str
+
+
+class CheckPatternResponse(TypedDict):
+    """Whether a pattern file would be saved, its problems with fixes, and the source each flavour draws."""
+
+    #: True when the file passes every check a save runs, so publish_pattern or the portal's import would take it.
+    valid: bool
+    #: The id it would have, org:<name>; null when the name is not valid.
+    id: Optional[str]
+    #: The kind of diagram every flavour draws; null when not valid.
+    kind: Optional[str]
+    #: The flavours the file gives.
+    flavours: List[Literal["neutral", "aws", "azure", "gcp"]]
+    #: Every problem at once, each with its field and a fix. Empty when valid.
+    problems: List[CheckPatternResponseProblemsItem]
+    #: Each flavour filled with the slot defaults, keyed by flavour: send one to draw_diagram to see it and its warnings. Empty when not valid.
+    sources: Dict[str, str]
+    #: The next step in one sentence.
+    next: str
+
+
+class CompareDiagramsInput(TypedDict):
+    """Two versions of a diagram to compare."""
+
+    #: The old diagram: source, the text of a Plotwork SVG that carries its source, or a cdn.plotwork.dev link.
+    before: str
+    #: The new diagram, in any of the same three forms.
+    after: str
+    #: Also return a Markdown block ready to paste as a pull request comment.
+    markdown: NotRequired[bool]
+
+
+CompareDiagramsResponseBefore = TypedDict(
+    "CompareDiagramsResponseBefore",
+    {
+        "from": "Literal[\"source\", \"svg\", \"url\"]",
+        # False when no source could be read from it; message says why.
+        "read": "bool",
+        # A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+        "kind": "Optional[str]",
+        "valid": "bool",
+        "message": "Optional[str]",
+    },
+)
+
+
+CompareDiagramsResponseAfter = TypedDict(
+    "CompareDiagramsResponseAfter",
+    {
+        "from": "Literal[\"source\", \"svg\", \"url\"]",
+        # False when no source could be read from it; message says why.
+        "read": "bool",
+        # A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+        "kind": "Optional[str]",
+        "valid": "bool",
+        "message": "Optional[str]",
+    },
+)
+
+
+class CompareDiagramsResponseCounts(TypedDict):
+    added: int
+    removed: int
+    renamed: int
+    moved: int
+    changed: int
+
+
+class CompareDiagramsResponseChangesItem(TypedDict):
+    change: Literal["added", "removed", "renamed", "moved", "changed"]
+    subject: Literal["header", "node", "group", "edge", "row", "series", "line"]
+    #: The id, the label in quotes, or for an edge its ends.
+    name: str
+    #: The line in after, or in before for a removal.
+    line: Optional[int]
+    detail: str
+
+
+class CompareDiagramsResponse(TypedDict):
+    """What changed between two versions of a diagram."""
+
+    same: bool
+    before: CompareDiagramsResponseBefore
+    after: CompareDiagramsResponseAfter
+    counts: CompareDiagramsResponseCounts
+    changes: List[CompareDiagramsResponseChangesItem]
+    #: True when more changes were found than are listed; counts covers all of them.
+    truncated: bool
+    #: The changes in plain words, for a pull request review.
+    summary: str
+    markdown: Optional[str]
+    next: str
+
+
+class ConvertMermaidInput(TypedDict):
+    """Mermaid source and what to return with the converted Plotwork source."""
+
+    #: One Mermaid diagram: a flowchart or graph, sequenceDiagram, erDiagram, gitGraph, gantt, classDiagram, stateDiagram, timeline, journey, mindmap, treemap-beta or treemap, pie, quadrantChart, C4Context or C4Container or C4Component or C4Dynamic or C4Deployment, sankey-beta or sankey, xychart-beta or xychart, treeView-beta or treeView, requirementDiagram, block-beta or block, packet or packet-beta, kanban, radar-beta or radar, usecase-beta or usecase, venn-beta or venn, ishikawa-beta or ishikawa, wardley-beta, architecture-beta, or zenuml. Front matter and %%{init}%% directives are allowed and are dropped. Send the text inside a mermaid fence, without the fence.
+    source: str
+    #: false (the default): a line that cannot be read stops the conversion, so nothing is converted with a line missing. true: such a line is skipped with a warning and the rest is converted.
+    lenient: NotRequired[bool]
+    #: Also draw the converted diagram, in the color schemes schemes names.
+    render: NotRequired[bool]
+    #: light, dark, or both (the default): the light picture and the dark one a dark page needs.
+    schemes: NotRequired[Literal["light", "dark", "both"]]
+    #: summary (the default), or full: the whole outline, and the source embedded in each SVG.
+    detail: NotRequired[Literal["summary", "full"]]
+    #: auto (the default): over MCP the SVG text stays out of the answer (picturesOmitted). always returns it. never draws nothing, cheapest. Checks run either way. The HTTP API treats auto as always.
+    svg: NotRequired[Literal["auto", "always", "never"]]
+    #: Write the source into each SVG so read_diagram can give it back. Set it when you save the SVG in a repository or publish it to edit later; anyone with the file or link can then read the source.
+    embedSource: NotRequired[bool]
+    #: The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json
+    settings: NotRequired[Dict[str, Any]]
+
+
+class ConvertMermaidResponseStats(TypedDict):
+    #: Flow nodes written.
+    nodes: int
+    #: Flow edges written.
+    edges: int
+    #: Flow groups written.
+    groups: int
+    #: Sequence participants written.
+    actors: int
+    #: Sequence messages written.
+    messages: int
+    #: Schema tables written.
+    tables: int
+    #: Schema columns written.
+    columns: int
+    #: Schema relations written.
+    relations: int
+    #: Warnings about constructs that were dropped: styling, links, activations, and so on.
+    dropped: int
+    #: Ids that were not valid Plotwork ids and were renamed.
+    renamed: int
+
+
+class ConvertMermaidResponseValidationObjectSizeObject(TypedDict):
+    """Natural size of the laid-out diagram."""
+
+    #: Width in px.
+    width: int
+    #: Height in px.
+    height: int
+
+
+class ConvertMermaidResponseValidationObject(TypedDict):
+    """The Plotwork validator run on `source`; null when nothing was converted."""
+
+    #: True when the converted source has no Plotwork errors. It always is when `ok` is true.
+    valid: bool
+    #: Plotwork errors in the converted source. Lines and columns point into `source`, not into the Mermaid.
+    errors: List[Diagnostic]
+    #: Plotwork quality warnings, including icon and group-type suggestions with the exact icon= to write. Lines and columns point into `source`, not into the Mermaid.
+    warnings: List[Diagnostic]
+    #: One-line description of the converted diagram, usable as alt text.
+    summary: Optional[str]
+    #: Natural size of the laid-out diagram.
+    size: Optional[ConvertMermaidResponseValidationObjectSizeObject]
+
+
+class ConvertMermaidResponseQuality(TypedDict):
+    """How clean the converted diagram looks and up to three changes that would help (see draw_diagram); absent when it is not valid."""
+
+    #: 0 to 100; 100 is a picture with nothing to fix. The same diagram always gets the same score.
+    score: int
+    #: clean is 85 or more, fair 60 or more, cluttered below.
+    grade: Literal["clean", "fair", "cluttered"]
+    #: What the score is made from: crossings, lineOverBox, labelOverlaps, smallestTextPx (in an 880px column), aspectRatio, emptySpace (0 to 1), longestLine (px), detour (1 is straight), the counts of boxes, lines, labels, series, and slices, and any measure the kind adds.
+    measures: Dict[str, float]
+    #: Up to three changes, the one worth most first, each naming the statement or option to edit.
+    hints: List[str]
+    #: The grade, the score, and the first hint in one line.
+    line: str
+
+
+class ConvertMermaidResponseRendersItem(TypedDict):
+    #: The color scheme this picture is drawn in.
+    scheme: Literal["light", "dark"]
+    #: Self-contained SVG markup with an accessible title and description.
+    svg: str
+    size: Size
+
+
+class ConvertMermaidResponsePicturesOmitted(TypedDict):
+    """Present only when pictures were left out because the answer would have been too big for an AI client to read in one piece."""
+
+    #: The color schemes whose pictures were left out.
+    schemes: List[Literal["light", "dark"]]
+    #: How many characters the pictures left out came to.
+    characters: int
+    #: The most characters one answer may hold before the pictures are left out.
+    limit: int
+    #: Why they were left out, and what to do.
+    why: str
+
+
+class ConvertMermaidResponse(TypedDict):
+    """The result of converting one Mermaid diagram to Plotwork."""
+
+    #: True when `source` is valid Plotwork source. False means nothing was converted and `source` is empty: read `diagnostics`.
+    ok: bool
+    #: The Plotwork kind the diagram became, or null when it could not be converted.
+    kind: Optional[str]
+    #: The Mermaid diagram type read from the first line, such as flowchart or sequenceDiagram; null when none was found.
+    mermaidType: Optional[str]
+    #: The Plotwork source, or an empty string when nothing could be converted.
+    source: str
+    #: Everything dropped, changed, or wrong, with a hint that says what to do. Codes start with M. Lines and columns point into the Mermaid you sent. M1xx codes are errors that stop the conversion; M2xx codes are warnings and the conversion went on.
+    diagnostics: List[Diagnostic]
+    stats: ConvertMermaidResponseStats
+    #: The Plotwork validator run on `source`; null when nothing was converted.
+    validation: Optional[ConvertMermaidResponseValidationObject]
+    #: How clean the converted diagram looks and up to three changes that would help (see draw_diagram); absent when it is not valid.
+    quality: NotRequired[ConvertMermaidResponseQuality]
+    #: The converted diagram as plain text, to check it says what the Mermaid said; empty when nothing was converted.
+    outline: List[str]
+    #: True when the summary level cut the outline short. Call again with detail "full" to read all of it.
+    outlineTruncated: bool
+    #: One picture per requested color scheme, light first; empty unless `render` was true and the conversion is valid, when svg is never, and when every picture was left out (see picturesOmitted).
+    renders: List[ConvertMermaidResponseRendersItem]
+    #: Present only when pictures were left out because the answer would have been too big for an AI client to read in one piece.
+    picturesOmitted: NotRequired[ConvertMermaidResponsePicturesOmitted]
+    #: A link that shows a valid diagram in a browser; give it to the person who wants to look. It holds the drawing itself: the source is in the part after #, never sent to a server, so nothing is saved on Plotwork and it appears in no Diagrams list; anyone with the link can read it. Absent when too long; next says so.
+    viewUrl: NotRequired[str]
+    #: The viewUrl with &download=png: opening it in a browser saves the diagram as a PNG for Slack, email, or a wiki. The PNG is drawn in the person's browser, not on a server, so it is a link to open, not an image address to embed. Absent when too long.
+    pngUrl: NotRequired[str]
+    #: The viewUrl with &download=svg: a person opens it to download the SVG. Not a file address for curl; use saveCommand. Absent when too long.
+    svgUrl: NotRequired[str]
+    #: Run in a shell to save the SVG into the repository: the CLI decodes the link locally, fetches nothing, and embeds the source. Set --out to the path; add --scheme dark for dark. Absent when too long.
+    saveCommand: NotRequired[str]
+    #: The next step in one sentence.
+    next: str
+
+
+class DiagnosticFix(TypedDict):
+    """The one certain fix, to apply as it is. Present only when exactly one fix is certain."""
+
+    #: What the fix does, in a few words, for a button.
+    label: str
+    #: The edits, all against the source the diagnostic was found in.
+    edits: List[FixEdit]
+
+
+class Diagnostic(TypedDict):
+    """A located, actionable problem found in diagram source."""
+
+    #: Stable code to branch on; E-codes are errors, W-codes are warnings.
+    code: Literal["E100", "E101", "E110", "E111", "E120", "E121", "E123", "E124", "E125", "E130", "E131", "E132", "E133", "E134", "E135", "E136", "E137", "E138", "E139", "E140", "W200", "W201", "W202", "W203", "W204", "W205", "W206", "W207", "W208", "W209", "W500", "W600", "W601", "W700", "W701", "W702", "W703", "W704", "W705", "W706", "W707", "W708", "W709", "W710", "M100", "M101", "M102", "M103", "M104", "M110", "M200", "M201", "M202", "M203", "M204", "M205", "M206", "M207", "M208", "M209", "M210", "M211", "M212", "M213", "M214", "M215", "M216", "M217", "M218", "E300", "E301", "E302", "E303", "E304", "W300", "W301", "W302", "W303", "M120", "M220", "M221", "M222", "E340", "E341", "E342", "E343", "E344", "E345", "W320", "W321", "W322", "W323", "M240", "M241", "M242", "E360", "E361", "E362", "E363", "E364", "E365", "E366", "E367", "W330", "W331", "W332", "W333", "W334", "M250", "M251", "E400", "E401", "E402", "E403", "W350", "W351", "W352", "W353", "M270", "M271", "E420", "E421", "E422", "E423", "E424", "W360", "W361", "W362", "W363", "W364", "M180", "M280", "M281", "M282", "E320", "E321", "E322", "E323", "E324", "E325", "E326", "E327", "E328", "E329", "E330", "W310", "W311", "W312", "W313", "W314", "M130", "M131", "M132", "M230", "M231", "M232", "M233", "M234", "M235", "M236", "M237", "M238", "E380", "E381", "E382", "E383", "W340", "W341", "W342", "W343", "M260", "I100", "I101", "I102", "I103", "I104", "I105", "I200", "I201", "I202", "I203", "I204", "I206", "I207", "R100", "R101", "R200", "R201", "R202", "R203", "R204", "R205", "R206", "R207", "S100", "S200", "S101", "S102", "S103", "S104", "S201", "S202", "S203", "S204", "S205"]
+    #: Errors stop rendering; warnings never do.
+    severity: Literal["error", "warning"]
+    #: What is wrong, in one sentence.
+    message: str
+    #: 1-based line in the submitted source.
+    line: int
+    #: 1-based column in that line.
+    column: int
+    #: Number of characters the problem covers.
+    length: int
+    #: A concrete suggestion for fixing it, or null.
+    hint: Optional[str]
+    #: The one certain fix, to apply as it is. Present only when exactly one fix is certain.
+    fix: NotRequired[DiagnosticFix]
+
+
+class DiagramSeriesObject(TypedDict):
+    """Its place in a series (the parts of one split import), or null when it is in none."""
+
+    #: The series id the parts were published with.
+    id: str
+    #: Its place in the series, from 1; 0 is the whole import combined into one diagram.
+    index: int
+    #: How many parts the publisher said the series has, or null.
+    total: Optional[int]
+
+
+class DiagramSourceInput(TypedDict):
+    """Request body carrying diagram source."""
+
+    #: Diagram source; the first line is the header, such as flow "Title" (draw_diagram lists every kind).
+    source: str
+    #: The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json
+    settings: NotRequired[Dict[str, Any]]
+
+
+class DrawDiagramInput(TypedDict):
+    """Diagram source and what to return: the color schemes to draw and how much detail."""
+
+    #: Diagram source. The first line is the header: flow "Title", sequence "Title", schema "Title", git "Title", gantt "Title", class "Title", state "Title", timeline "Title", journey "Title", mindmap "Title", treemap "Title", pie "Title", quadrant "Title", layers "Title", c4 "Title", matrix "Title", sankey "Title", xychart "Title", tree "Title", swimlane "Title", requirement "Title", block "Title", packet "Title", kanban "Title", radar "Title", usecase "Title", venn "Title", fishbone "Title", or wardley "Title".
+    source: str
+    #: light, dark, or both (the default): the light picture and the dark one a dark page needs.
+    schemes: NotRequired[Literal["light", "dark", "both"]]
+    #: Colour theme for this drawing, over the header's theme=.
+    theme: NotRequired[Literal["plotwork", "slate", "ocean", "forest", "sunset", "mono", "contrast"]]
+    #: summary (the default), or full: the whole outline, and the source embedded in each SVG.
+    detail: NotRequired[Literal["summary", "full"]]
+    #: auto (the default): over MCP the SVG text stays out of the answer (picturesOmitted). always returns it. never draws nothing, cheapest. Checks run either way. The HTTP API treats auto as always.
+    svg: NotRequired[Literal["auto", "always", "never"]]
+    #: Write the source into each SVG so read_diagram can give it back. Set it when you save the SVG in a repository or publish it to edit later; anyone with the file or link can then read the source.
+    embedSource: NotRequired[bool]
+    #: The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json
+    settings: NotRequired[Dict[str, Any]]
+
+
+class DrawDiagramResponseSizeObject(TypedDict):
+    """Natural size of the laid-out diagram; null when invalid."""
+
+    #: Width in px.
+    width: int
+    #: Height in px.
+    height: int
+
+
+class DrawDiagramResponseQuality(TypedDict):
+    """How clean the picture looks (score, grade, measures) and up to three changes that would help; read it instead of looking. Absent when invalid."""
+
+    #: 0 to 100; 100 is a picture with nothing to fix. The same diagram always gets the same score.
+    score: int
+    #: clean is 85 or more, fair 60 or more, cluttered below.
+    grade: Literal["clean", "fair", "cluttered"]
+    #: What the score is made from: crossings, lineOverBox, labelOverlaps, smallestTextPx (in an 880px column), aspectRatio, emptySpace (0 to 1), longestLine (px), detour (1 is straight), the counts of boxes, lines, labels, series, and slices, and any measure the kind adds.
+    measures: Dict[str, float]
+    #: Up to three changes, the one worth most first, each naming the statement or option to edit.
+    hints: List[str]
+    #: The grade, the score, and the first hint in one line.
+    line: str
+
+
+class DrawDiagramResponseRendersItem(TypedDict):
+    #: The color scheme this picture is drawn in.
+    scheme: Literal["light", "dark"]
+    #: Self-contained SVG markup with an accessible title and description.
+    svg: str
+    size: Size
+
+
+class DrawDiagramResponsePicturesOmitted(TypedDict):
+    """Present only when pictures were left out because the answer would have been too big for an AI client to read in one piece."""
+
+    #: The color schemes whose pictures were left out.
+    schemes: List[Literal["light", "dark"]]
+    #: How many characters the pictures left out came to.
+    characters: int
+    #: The most characters one answer may hold before the pictures are left out.
+    limit: int
+    #: Why they were left out, and what to do.
+    why: str
+
+
+class DrawDiagramResponse(TypedDict):
+    """The result of checking, describing, and drawing a diagram in one call."""
+
+    #: True when the source has no errors. When false, nothing was drawn: fix the errors and call again.
+    valid: bool
+    #: The diagram kind, or null when the header could not be read.
+    kind: Optional[str]
+    #: Every error found in one pass, each with line, column, and a hint. Empty when valid.
+    errors: List[Diagnostic]
+    #: Quality warnings for a valid diagram: too dense, too wide, text cut, unconnected nodes, and suggestions for an icon or a group type. Empty when invalid.
+    warnings: List[Diagnostic]
+    #: One-line description of the diagram, usable as alt text; null when invalid.
+    summary: Optional[str]
+    #: The diagram as plain text in reading order, to check it says what you meant; empty when invalid.
+    outline: List[str]
+    #: True when the summary level cut the outline short. Call again with detail "full" to read all of it.
+    outlineTruncated: bool
+    #: Natural size of the laid-out diagram; null when invalid.
+    size: Optional[DrawDiagramResponseSizeObject]
+    #: How clean the picture looks (score, grade, measures) and up to three changes that would help; read it instead of looking. Absent when invalid.
+    quality: NotRequired[DrawDiagramResponseQuality]
+    #: Information notes, such as an icon alias drawn as the real icon; absent when there is none.
+    notices: NotRequired[List[Note]]
+    #: One picture per requested color scheme, light first; empty when invalid, when svg is never, and when every picture was left out (see picturesOmitted).
+    renders: List[DrawDiagramResponseRendersItem]
+    #: Present only when pictures were left out because the answer would have been too big for an AI client to read in one piece.
+    picturesOmitted: NotRequired[DrawDiagramResponsePicturesOmitted]
+    #: A link that shows a valid diagram in a browser; give it to the person who wants to look. It holds the drawing itself: the source is in the part after #, never sent to a server, so nothing is saved on Plotwork and it appears in no Diagrams list; anyone with the link can read it. Absent when too long; next says so.
+    viewUrl: NotRequired[str]
+    #: The viewUrl with &download=png: opening it in a browser saves the diagram as a PNG for Slack, email, or a wiki. The PNG is drawn in the person's browser, not on a server, so it is a link to open, not an image address to embed. Absent when too long.
+    pngUrl: NotRequired[str]
+    #: The viewUrl with &download=svg: a person opens it to download the SVG. Not a file address for curl; use saveCommand. Absent when too long.
+    svgUrl: NotRequired[str]
+    #: Run in a shell to save the SVG into the repository: the CLI decodes the link locally, fetches nothing, and embeds the source. Set --out to the path; add --scheme dark for dark. Absent when too long.
+    saveCommand: NotRequired[str]
+    #: The next step in one sentence.
+    next: str
+
+
+class DrawFromPatternInput(TypedDict):
+    """A pattern id, the flavour and slot values to use, and what to return."""
+
+    #: The pattern id, as find_pattern returns it, such as three-tier-network.
+    id: str
+    #: neutral (generic glyphs, no vendor names; the default), or aws, azure, or gcp for that provider's icons. Not every pattern comes in every flavour; the answer lists the ones it has.
+    provider: NotRequired[Literal["neutral", "aws", "azure", "gcp"]]
+    #: Slot values keyed by slot id, such as {"office": "Branch office"}: plain text of up to 60 characters, no quotes or line breaks. Omit a slot to keep its default. get_pattern lists the slots and what they mean.
+    slots: NotRequired[Dict[str, str]]
+    #: light, dark, or both (the default): the light picture and the dark one a dark page needs.
+    schemes: NotRequired[Literal["light", "dark", "both"]]
+    #: summary (the default), or full: the whole outline, and the source embedded in each SVG.
+    detail: NotRequired[Literal["summary", "full"]]
+    #: auto (the default): over MCP the SVG text stays out of the answer (picturesOmitted). always returns it. never draws nothing, cheapest. Checks run either way. The HTTP API treats auto as always.
+    svg: NotRequired[Literal["auto", "always", "never"]]
+    #: Write the source into each SVG so read_diagram can give it back. Set it when you save the SVG in a repository or publish it to edit later; anyone with the file or link can then read the source.
+    embedSource: NotRequired[bool]
+    #: The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json
+    settings: NotRequired[Dict[str, Any]]
+
+
+class DrawFromPatternResponseSlotsItem(TypedDict):
+    #: The slot id; the key to use in slots.
+    id: str
+    #: The text the slot has in the source: the value sent, or the default.
+    value: str
+    #: The default text.
+    default: str
+    #: What belongs in this slot.
+    meaning: str
+    #: True when the slot kept its default.
+    isDefault: bool
+
+
+class DrawFromPatternResponseNotesObject(TypedDict):
+    """How to adapt the pattern: what to keep, what to rename, and when to split."""
+
+    #: What to leave exactly as it is.
+    keep: str
+    #: What to rename or replace, and how.
+    rename: str
+    #: When the diagram has grown too big, and where to cut it.
+    split: str
+
+
+class DrawFromPatternResponseProblemsItem(TypedDict):
+    code: Literal["unknown-pattern", "unknown-flavour", "unknown-slot", "bad-slot-value", "bad-source"]
+    message: str
+    #: How to fix it.
+    hint: str
+
+
+class DrawFromPatternResponseSizeObject(TypedDict):
+    """Natural size of the laid-out diagram; null when invalid."""
+
+    #: Width in px.
+    width: int
+    #: Height in px.
+    height: int
+
+
+class DrawFromPatternResponseQuality(TypedDict):
+    """How clean the picture looks (score, grade, measures) and up to three changes that would help; read it instead of looking. Absent when invalid."""
+
+    #: 0 to 100; 100 is a picture with nothing to fix. The same diagram always gets the same score.
+    score: int
+    #: clean is 85 or more, fair 60 or more, cluttered below.
+    grade: Literal["clean", "fair", "cluttered"]
+    #: What the score is made from: crossings, lineOverBox, labelOverlaps, smallestTextPx (in an 880px column), aspectRatio, emptySpace (0 to 1), longestLine (px), detour (1 is straight), the counts of boxes, lines, labels, series, and slices, and any measure the kind adds.
+    measures: Dict[str, float]
+    #: Up to three changes, the one worth most first, each naming the statement or option to edit.
+    hints: List[str]
+    #: The grade, the score, and the first hint in one line.
+    line: str
+
+
+class DrawFromPatternResponseRendersItem(TypedDict):
+    #: The color scheme this picture is drawn in.
+    scheme: Literal["light", "dark"]
+    #: Self-contained SVG markup with an accessible title and description.
+    svg: str
+    size: Size
+
+
+class DrawFromPatternResponsePicturesOmitted(TypedDict):
+    """Present only when pictures were left out because the answer would have been too big for an AI client to read in one piece."""
+
+    #: The color schemes whose pictures were left out.
+    schemes: List[Literal["light", "dark"]]
+    #: How many characters the pictures left out came to.
+    characters: int
+    #: The most characters one answer may hold before the pictures are left out.
+    limit: int
+    #: Why they were left out, and what to do.
+    why: str
+
+
+class DrawFromPatternResponse(TypedDict):
+    """A pattern filled, checked, and drawn in one call."""
+
+    #: True when the pattern and flavour exist and the slot values are usable. When false, problems says why and nothing else is filled.
+    found: bool
+    #: The pattern id that was asked for.
+    id: str
+    title: Optional[str]
+    #: One sentence: what the pattern shows.
+    patternSummary: Optional[str]
+    whenToUse: Optional[str]
+    #: A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+    kind: Optional[str]
+    #: The flavour that was filled.
+    flavour: Literal["neutral", "aws", "azure", "gcp", None]
+    #: Every flavour this pattern comes in; empty when the pattern was not found.
+    flavours: List[Literal["neutral", "aws", "azure", "gcp"]]
+    #: Plotwork source, valid and ready to use; null when not found.
+    source: Optional[str]
+    #: Every slot the source uses, with the value it has.
+    slots: List[DrawFromPatternResponseSlotsItem]
+    #: How to adapt the pattern: what to keep, what to rename, and when to split.
+    notes: Optional[DrawFromPatternResponseNotesObject]
+    #: Mistakes in the id, the flavour, or the slot values, each with a fix. Empty when found.
+    problems: List[DrawFromPatternResponseProblemsItem]
+    #: True when the source has no errors. When false, nothing was drawn: fix the errors and call again.
+    valid: bool
+    #: Every error found in one pass, each with line, column, and a hint. Empty when valid.
+    errors: List[Diagnostic]
+    #: Quality warnings for a valid diagram: too dense, too wide, text cut, unconnected nodes, and suggestions for an icon or a group type. Empty when invalid.
+    warnings: List[Diagnostic]
+    #: One-line description of the diagram, usable as alt text; null when invalid.
+    summary: Optional[str]
+    #: The diagram as plain text in reading order, to check it says what you meant; empty when invalid.
+    outline: List[str]
+    #: True when the summary level cut the outline short. Call again with detail "full" to read all of it.
+    outlineTruncated: bool
+    #: Natural size of the laid-out diagram; null when invalid.
+    size: Optional[DrawFromPatternResponseSizeObject]
+    #: How clean the picture looks (score, grade, measures) and up to three changes that would help; read it instead of looking. Absent when invalid.
+    quality: NotRequired[DrawFromPatternResponseQuality]
+    #: Information notes, such as an icon alias drawn as the real icon; absent when there is none.
+    notices: NotRequired[List[Note]]
+    #: One picture per requested color scheme, light first; empty when invalid, when svg is never, and when every picture was left out (see picturesOmitted).
+    renders: List[DrawFromPatternResponseRendersItem]
+    #: Present only when pictures were left out because the answer would have been too big for an AI client to read in one piece.
+    picturesOmitted: NotRequired[DrawFromPatternResponsePicturesOmitted]
+    #: A link that shows a valid diagram in a browser; give it to the person who wants to look. It holds the drawing itself: the source is in the part after #, never sent to a server, so nothing is saved on Plotwork and it appears in no Diagrams list; anyone with the link can read it. Absent when too long; next says so.
+    viewUrl: NotRequired[str]
+    #: The viewUrl with &download=png: opening it in a browser saves the diagram as a PNG for Slack, email, or a wiki. The PNG is drawn in the person's browser, not on a server, so it is a link to open, not an image address to embed. Absent when too long.
+    pngUrl: NotRequired[str]
+    #: The viewUrl with &download=svg: a person opens it to download the SVG. Not a file address for curl; use saveCommand. Absent when too long.
+    svgUrl: NotRequired[str]
+    #: Run in a shell to save the SVG into the repository: the CLI decodes the link locally, fetches nothing, and embeds the source. Set --out to the path; add --scheme dark for dark. Absent when too long.
+    saveCommand: NotRequired[str]
+    #: The next step in one sentence.
+    next: str
+
+
+EditDiagramInputOperationsItem = TypedDict(
+    "EditDiagramInputOperationsItem",
+    {
+        "op": "Literal[\"rename\", \"set\", \"add_node\", \"remove\", \"add_edge\", \"remove_edge\", \"move\", \"replace_text\"]",
+        # Id, label, table.column, or "header".
+        "target": "NotRequired[str]",
+        # rename: the new name. Edges: the end.
+        "to": "NotRequired[str]",
+        # Edges: the start.
+        "from": "NotRequired[str]",
+        "option": "NotRequired[str]",
+        # set: null removes the option.
+        "value": "NotRequired[Optional[str]]",
+        "id": "NotRequired[str]",
+        # add_edge on sankey: the amount.
+        "label": "NotRequired[str]",
+        # add_node: node type, or statement word (c4 person, tree dir).
+        "type": "NotRequired[str]",
+        "options": "NotRequired[Dict[str, str]]",
+        # add_node: the whole line, for a kind with no plain node statement.
+        "statement": "NotRequired[str]",
+        # A block; null is the top level.
+        "into": "NotRequired[Optional[str]]",
+        "after": "NotRequired[str]",
+        "arrow": "NotRequired[Literal[\"<-->\", \"-->\", \"<->\", \"..>\", \"->\", \"--\"]]",
+        "find": "NotRequired[str]",
+        "replace": "NotRequired[str]",
+        "all": "NotRequired[bool]",
+    },
+)
+
+
+class EditDiagramInput(TypedDict):
+    """Diagram source and the edits to make to it."""
+
+    #: Diagram source; the first line is the header, such as flow "Title" (draw_diagram lists every kind).
+    source: str
+    #: Applied in order.
+    operations: List[EditDiagramInputOperationsItem]
+    #: never (the default) draws nothing; auto or always draws like draw_diagram.
+    svg: NotRequired[Literal["auto", "always", "never"]]
+    #: light, dark, or both (the default): the light picture and the dark one a dark page needs.
+    schemes: NotRequired[Literal["light", "dark", "both"]]
+    #: The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json
+    settings: NotRequired[Dict[str, Any]]
+
+
+class EditDiagramResponseResultsItem(TypedDict):
+    op: Literal["rename", "set", "add_node", "remove", "add_edge", "remove_edge", "move", "replace_text"]
+    applied: bool
+    #: Lines of the new source this operation wrote, or the lines it removed from.
+    lines: List[int]
+    message: str
+    hint: Optional[str]
+
+
+class EditDiagramResponseRendersItem(TypedDict):
+    scheme: Literal["light", "dark"]
+    svg: str
+    size: Size
+
+
+class EditDiagramResponsePicturesOmitted(TypedDict):
+    """Present only when pictures were left out because the answer would have been too big for an AI client to read in one piece."""
+
+    #: The color schemes whose pictures were left out.
+    schemes: List[Literal["light", "dark"]]
+    #: How many characters the pictures left out came to.
+    characters: int
+    #: The most characters one answer may hold before the pictures are left out.
+    limit: int
+    #: Why they were left out, and what to do.
+    why: str
+
+
+class EditDiagramResponse(TypedDict):
+    """The edited source, a result for each operation, and the check of the result."""
+
+    #: The edited source. Lines no operation touched are byte for byte as they were, comments included.
+    source: str
+    changed: bool
+    #: One entry for each operation, in order.
+    results: List[EditDiagramResponseResultsItem]
+    valid: bool
+    #: A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+    kind: Optional[str]
+    errors: List[Diagnostic]
+    #: Quality warnings; only when the result is drawn.
+    warnings: List[Diagnostic]
+    summary: Optional[str]
+    outline: List[str]
+    outlineTruncated: bool
+    size: Optional[Size]
+    renders: List[EditDiagramResponseRendersItem]
+    #: Present only when pictures were left out because the answer would have been too big for an AI client to read in one piece.
+    picturesOmitted: NotRequired[EditDiagramResponsePicturesOmitted]
+    #: A link that shows a valid diagram in a browser; give it to the person who wants to look. It holds the drawing itself: the source is in the part after #, never sent to a server, so nothing is saved on Plotwork and it appears in no Diagrams list; anyone with the link can read it. Absent when too long; next says so.
+    viewUrl: NotRequired[str]
+    #: The viewUrl with &download=svg: a person opens it to download the SVG. Not a file address for curl; use saveCommand. Absent when too long.
+    svgUrl: NotRequired[str]
+    #: Run in a shell to save the SVG into the repository: the CLI decodes the link locally, fetches nothing, and embeds the source. Set --out to the path; add --scheme dark for dark. Absent when too long.
+    saveCommand: NotRequired[str]
+    next: str
+
+
+class ErrorResponse(TypedDict):
+    """Standard error envelope used by every failing response."""
+
+    #: Always true, so clients can branch without reading the status.
+    error: Literal[True]
+    #: Stable snake_case key such as validation.failed or diagram.invalid.
+    errorCode: str
+    #: Safe, human-readable summary.
+    message: str
+    #: Validation issues or diagnostics, JSON-safe.
+    details: NotRequired[Any]
+    #: Trace id for correlating with logs.
+    requestId: NotRequired[str]
+
+
+class FindPatternInput(TypedDict):
+    """Words that describe the architecture wanted, and optional filters."""
+
+    #: The architecture wanted, in plain words, such as "three tier network".
+    query: str
+    #: Only patterns that come in this flavour: neutral, aws, azure, or gcp.
+    provider: NotRequired[Literal["neutral", "aws", "azure", "gcp"]]
+    #: Tags every result must have, such as "load balancer". Up to 5.
+    tags: NotRequired[List[str]]
+    #: Only patterns of this diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley.
+    kind: NotRequired[Literal["flow", "sequence", "schema", "git", "gantt", "class", "state", "timeline", "journey", "mindmap", "treemap", "pie", "quadrant", "layers", "c4", "matrix", "sankey", "xychart", "tree", "swimlane", "requirement", "block", "packet", "kanban", "radar", "usecase", "venn", "fishbone", "wardley"]]
+    #: Most results to return, up to 5.
+    limit: NotRequired[int]
+
+
+class FindPatternResponseMatchesItem(TypedDict):
+    #: The pattern id, as find_pattern returns it, such as three-tier-network.
+    id: str
+    title: str
+    #: One sentence: what the diagram shows.
+    summary: str
+    #: A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+    kind: str
+    tags: List[str]
+    #: The flavours the pattern comes in.
+    providers: List[Literal["neutral", "aws", "azure", "gcp"]]
+    #: How well it matches; only the order of the results is meaningful.
+    score: float
+    #: Present on a pattern of your organisation's own, which it approved and which comes first. Absent on the built-in patterns.
+    origin: NotRequired[Literal["organisation"]]
+    #: Present, with origin, on a pattern of your organisation: the words to show beside it.
+    label: NotRequired[Literal["Your organisation's pattern"]]
+
+
+class FindPatternResponse(TypedDict):
+    """Patterns that match a request, best first, with summaries and no source."""
+
+    #: The query that was searched.
+    query: str
+    #: Up to the limit, best match first. Empty when nothing fits.
+    matches: List[FindPatternResponseMatchesItem]
+    #: The next step in one sentence.
+    next: str
+
+
+class FixEdit(TypedDict):
+    """Replace `length` characters from `line`:`column` with `text`."""
+
+    #: 1-based line the edit starts on.
+    line: int
+    #: 1-based column it starts at.
+    column: int
+    #: Characters to replace from there, a line break counting one.
+    length: int
+    #: What replaces them; empty deletes.
+    text: str
+
+
+class GetPatternInput(TypedDict):
+    """A pattern id, the flavour to draw, and the slot values to use."""
+
+    #: The pattern id, as find_pattern returns it, such as three-tier-network.
+    id: str
+    #: neutral (generic glyphs, no vendor names; the default), or aws, azure, or gcp for that provider's icons. Not every pattern comes in every flavour; the answer lists the ones it has.
+    provider: NotRequired[Literal["neutral", "aws", "azure", "gcp"]]
+    #: Slot values keyed by slot id, such as {"office": "Branch office"}: plain text of up to 60 characters, no quotes or line breaks. Omit a slot to keep its default. get_pattern lists the slots and what they mean.
+    slots: NotRequired[Dict[str, str]]
+    #: true also returns the whole pattern as a pattern file, to edit, check_pattern and publish_pattern.
+    file: NotRequired[bool]
+
+
+class GetPatternResponseSlotsItem(TypedDict):
+    #: The slot id; the key to use in slots.
+    id: str
+    #: The text the slot has in the source: the value sent, or the default.
+    value: str
+    #: The default text.
+    default: str
+    #: What belongs in this slot.
+    meaning: str
+    #: True when the slot kept its default.
+    isDefault: bool
+
+
+class GetPatternResponseNotesObject(TypedDict):
+    """How to adapt the pattern: what to keep, what to rename, and when to split."""
+
+    #: What to leave exactly as it is.
+    keep: str
+    #: What to rename or replace, and how.
+    rename: str
+    #: When the diagram has grown too big, and where to cut it.
+    split: str
+
+
+class GetPatternResponseProblemsItem(TypedDict):
+    code: Literal["unknown-pattern", "unknown-flavour", "unknown-slot", "bad-slot-value", "bad-source"]
+    message: str
+    #: How to fix it.
+    hint: str
+
+
+class GetPatternResponseTreeItem(TypedDict):
+    #: How deep the item sits: 0 for the top level.
+    depth: int
+    kind: Literal["group", "overlay", "node", "actor", "table"]
+    #: The id written in the source.
+    id: str
+    label: str
+    #: The group type, node type, or actor type; null for a table or an untyped group.
+    type: Optional[str]
+
+
+class GetPatternResponseFileObjectTemplates(TypedDict):
+    neutral: NotRequired[str]
+    aws: NotRequired[str]
+    azure: NotRequired[str]
+    gcp: NotRequired[str]
+
+
+class GetPatternResponseFileObjectSlotsItem(TypedDict):
+    id: str
+    default: str
+    meaning: str
+
+
+class GetPatternResponseFileObjectNotes(TypedDict):
+    keep: NotRequired[str]
+    rename: NotRequired[str]
+    split: NotRequired[str]
+
+
+# The whole pattern as a pattern file, when file was true and the pattern was found.
+GetPatternResponseFileObject = TypedDict(
+    "GetPatternResponseFileObject",
+    {
+        "$schema": "NotRequired[str]",
+        "name": "str",
+        "title": "str",
+        "summary": "str",
+        "whenToUse": "NotRequired[str]",
+        "tags": "NotRequired[List[str]]",
+        "templates": "GetPatternResponseFileObjectTemplates",
+        "slots": "NotRequired[List[GetPatternResponseFileObjectSlotsItem]]",
+        "notes": "NotRequired[GetPatternResponseFileObjectNotes]",
+    },
+)
+
+
+class GetPatternResponse(TypedDict):
+    """A pattern filled for one flavour, with its slots and advice."""
+
+    #: True when the pattern and flavour exist and the slot values are usable. When false, problems says why and nothing else is filled.
+    found: bool
+    #: The pattern id that was asked for.
+    id: str
+    title: Optional[str]
+    #: One sentence: what the pattern shows.
+    patternSummary: Optional[str]
+    whenToUse: Optional[str]
+    #: A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+    kind: Optional[str]
+    #: The flavour that was filled.
+    flavour: Literal["neutral", "aws", "azure", "gcp", None]
+    #: Every flavour this pattern comes in; empty when the pattern was not found.
+    flavours: List[Literal["neutral", "aws", "azure", "gcp"]]
+    #: Plotwork source, valid and ready to use; null when not found.
+    source: Optional[str]
+    #: Every slot the source uses, with the value it has.
+    slots: List[GetPatternResponseSlotsItem]
+    #: How to adapt the pattern: what to keep, what to rename, and when to split.
+    notes: Optional[GetPatternResponseNotesObject]
+    #: Mistakes in the id, the flavour, or the slot values, each with a fix. Empty when found.
+    problems: List[GetPatternResponseProblemsItem]
+    #: The groups, overlays, and nodes as drawn, depth first, so you can see what to rename.
+    tree: List[GetPatternResponseTreeItem]
+    #: The text description of the diagram.
+    outline: List[str]
+    #: The whole pattern as a pattern file, when file was true and the pattern was found.
+    file: NotRequired[Optional[GetPatternResponseFileObject]]
+    #: The next step in one sentence.
+    next: str
+
+
+class HostedDiagram(TypedDict):
+    #: The handle for managing the diagram (delete). It is not in the link.
+    id: str
+    #: The public address of the SVG. Anyone with the link can see it; the token in it cannot be guessed.
+    url: str
+    #: The label given at publish, or null.
+    name: Optional[str]
+    #: The folder it is filed in, such as `Payments/Checkout`, or null for the top level.
+    folder: Optional[str]
+    #: The color scheme it was drawn in: light, dark, or auto.
+    scheme: Literal["light", "dark", "auto"]
+    #: Size of the stored SVG in bytes.
+    bytes: int
+    #: When it was first published, in milliseconds since the epoch.
+    createdAt: int
+    #: When it was last published, in milliseconds since the epoch. Publishing the same diagram again moves it.
+    publishedAt: int
+    #: When it will be deleted, in milliseconds since the epoch, or null when the plan keeps diagrams until you delete them.
+    expiresAt: Optional[int]
+    #: True while the diagram is locked: it cannot be deleted, renamed or moved until you unlock it. A lock does not stop it expiring on a plan that expires diagrams.
+    locked: bool
+    #: When it was locked, in milliseconds since the epoch, or null when it is not locked.
+    lockedAt: Optional[int]
+    series: DiagramSeries
+
+
+class IconSearchResponse(TypedDict):
+    """Matching bundled icon names."""
+
+    #: The query that was searched.
+    query: str
+    #: Matching icon references as set:name, best match first.
+    items: List[str]
+
+
+class ImportSourceInputFilesItem(TypedDict):
+    #: The file path, such as infra/network.tf; diagnostics name it.
+    path: str
+    #: The file content, as text.
+    text: str
+
+
+class ImportSourceInputOptions(TypedDict):
+    #: The picture of a format drawn several ways.
+    view: NotRequired[Literal["endpoints", "map", "sequence", "git", "timeline", "context", "container", "component"]]
+    #: openapi sequence: the operation.
+    operationId: NotRequired[str]
+    #: csv, json: the chart; auto picks.
+    chart: NotRequired[Literal["auto", "xychart", "pie", "sankey", "treemap", "matrix"]]
+    #: Tables to draw, by name or prefix*.
+    tables: NotRequired[List[str]]
+    #: openapi: path prefixes to read.
+    paths: NotRequired[List[str]]
+    #: openapi: tags to read.
+    tags: NotRequired[List[str]]
+    #: Variables files to apply.
+    varFiles: NotRequired[List[str]]
+    #: How things are framed; module is the default.
+    groupBy: NotRequired[Literal["module", "network", "file", "owner"]]
+    #: The root, stack, template, or draw.io page of several to draw.
+    root: NotRequired[str]
+    #: off: no icons, as settings with icons off.
+    icons: NotRequired[Literal["auto", "off"]]
+
+
+class ImportSourceInput(TypedDict):
+    """A file of another format to turn into Plotwork source."""
+
+    #: What the text is; get_diagram_syntax with topic import-formats describes each.
+    format: Literal["sql", "prisma", "drizzle", "openapi", "graphql", "protobuf", "terraform", "terraform-plan", "bicep", "arm", "pulumi", "cloudformation", "cdk", "serverless", "compose", "dockerfile", "kubernetes", "helm", "kustomize", "nginx", "backstage", "structurizr", "asyncapi", "github-actions", "gitlab-ci", "azure-pipelines", "dbt", "workspaces", "drawio", "csv", "json", "tree", "git-log"]
+    #: The file content, as text. Send text or files, not both.
+    text: NotRequired[str]
+    #: The files of a folder, for a format that spans files; the others read the first.
+    files: NotRequired[List[ImportSourceInputFilesItem]]
+    #: The diagram title; taken from the file when left out.
+    title: NotRequired[str]
+    #: Page of parts, 24 a page.
+    partsPage: NotRequired[int]
+    #: Too big for one picture: parts, whole, or both.
+    large: NotRequired[Literal["parts", "whole", "both"]]
+    options: NotRequired[ImportSourceInputOptions]
+
+
+class ImportSourceResponseStats(TypedDict):
+    #: Boxes, tables, rows, slices, places, entries, or commits written.
+    items: int
+    #: Arrows, relations, messages, flows, or merges written.
+    links: int
+    #: Frames, sections, or folders written.
+    groups: int
+    #: Things in the file left out by a cap or because the picture has no place for them; each is in diagnostics.
+    dropped: int
+
+
+class ImportSourceResponseCoverageObject(TypedDict):
+    """How much of the file the picture shows; null when nothing was imported. When complete is false, the picture is not the whole file: say so."""
+
+    #: What was counted, such as resources, services, tables, or endpoints.
+    noun: str
+    #: Everything of that kind in the file.
+    total: int
+    #: Drawn as a box, frame, table, row, or entry of its own.
+    drawn: int
+    #: Not drawn on their own but counted on the box they belong to, such as "3 role assignments".
+    summarised: int
+    #: Not in the picture at all; the diagnostics say which and why.
+    omitted: int
+    #: True when nothing was omitted.
+    complete: bool
+    #: The coverage in one sentence, such as "Drawn 12 of 85 resources; 60 are counted on the boxes they belong to and 13 are left out."
+    line: str
+
+
+class ImportSourceResponseValidationObjectSizeObject(TypedDict):
+    """Natural size of the laid-out diagram."""
+
+    #: Width in px.
+    width: int
+    #: Height in px.
+    height: int
+
+
+class ImportSourceResponseValidationObject(TypedDict):
+    """The Plotwork validator run on `source`; null when nothing was imported."""
+
+    #: True when the source has no Plotwork errors. It always is when `ok` is true.
+    valid: bool
+    #: Plotwork errors. Lines and columns point into `source`.
+    errors: List[Diagnostic]
+    #: Plotwork quality warnings, with the exact fix in each hint. Lines and columns point into `source`.
+    warnings: List[Diagnostic]
+    #: One-line description of the diagram, usable as alt text.
+    summary: Optional[str]
+    #: Natural size of the laid-out diagram.
+    size: Optional[ImportSourceResponseValidationObjectSizeObject]
+
+
+class ImportSourceResponsePartsItem(TypedDict):
+    #: Its place among all the parts, from 1.
+    index: int
+    #: What this diagram shows, such as one resource group or one tag of an API.
+    title: str
+    #: The kind of diagram.
+    kind: str
+    #: The Plotwork source of this diagram; draw it with draw_diagram.
+    source: str
+    #: The boxes, rows, or entries it draws.
+    items: int
+    #: True when the source has no Plotwork errors.
+    valid: bool
+    #: Plotwork quality warnings of this diagram. Lines and columns point into its source.
+    warnings: List[Diagnostic]
+
+
+class ImportSourceResponseSeriesObject(TypedDict):
+    """For a split import, publish_diagram's series for every part, with the part's index. Null for one diagram."""
+
+    id: str
+    total: int
+
+
+class ImportSourceResponseCombinedObject(TypedDict):
+    """A split import as one diagram, every arrow kept; publish at series index 0."""
+
+    title: str
+    source: str
+
+
+class ImportSourceResponse(TypedDict):
+    """The result of turning a file of another format into Plotwork source."""
+
+    #: True when `source` is valid Plotwork source. False means nothing was imported and `source` is empty: read `diagnostics`.
+    ok: bool
+    #: The kind of diagram the file became, or null when nothing was imported.
+    kind: Optional[str]
+    #: The format the text was read as.
+    format: str
+    #: The Plotwork source, or an empty string when nothing could be imported.
+    source: str
+    #: Everything left out, changed, or wrong, with a hint. Codes start with I and point into the text you sent: I1xx errors stopped the import, I2xx warnings did not.
+    diagnostics: List[Diagnostic]
+    stats: ImportSourceResponseStats
+    #: How much of the file the picture shows; null when nothing was imported. When complete is false, the picture is not the whole file: say so.
+    coverage: Optional[ImportSourceResponseCoverageObject]
+    #: The Plotwork validator run on `source`; null when nothing was imported.
+    validation: Optional[ImportSourceResponseValidationObject]
+    #: When the file is too big for one readable picture, the diagrams it was split into, in order, at most 24 a page; `source` is the first diagram of all. Show or draw each of them. Empty when the import is one diagram.
+    parts: List[ImportSourceResponsePartsItem]
+    #: How many diagrams the import was split into in all; 0 when it is one diagram.
+    partsTotal: int
+    #: The page of parts this answer holds, from 1.
+    partsPage: int
+    #: How many pages of parts there are; call again with partsPage for the next one.
+    partsPages: int
+    #: For a split import, publish_diagram's series for every part, with the part's index. Null for one diagram.
+    series: Optional[ImportSourceResponseSeriesObject]
+    #: A split import as one diagram, every arrow kept; publish at series index 0.
+    combined: Optional[ImportSourceResponseCombinedObject]
+    #: The diagram as plain text, to check it says what the file says; empty when nothing was imported.
+    outline: List[str]
+    #: True when the outline was cut short at its summary length.
+    outlineTruncated: bool
+    #: A link that shows a valid diagram in a browser; give it to the person who wants to look. It holds the drawing itself: the source is in the part after #, never sent to a server, so nothing is saved on Plotwork and it appears in no Diagrams list; anyone with the link can read it. Absent when too long; next says so.
+    viewUrl: NotRequired[str]
+    #: The viewUrl with &download=png: opening it in a browser saves the diagram as a PNG for Slack, email, or a wiki. The PNG is drawn in the person's browser, not on a server, so it is a link to open, not an image address to embed. Absent when too long.
+    pngUrl: NotRequired[str]
+    #: The viewUrl with &download=svg: a person opens it to download the SVG. Not a file address for curl; use saveCommand. Absent when too long.
+    svgUrl: NotRequired[str]
+    #: Run in a shell to save the SVG into the repository: the CLI decodes the link locally, fetches nothing, and embeds the source. Set --out to the path; add --scheme dark for dark. Absent when too long.
+    saveCommand: NotRequired[str]
+    #: The next step in one sentence.
+    next: str
+
+
+class MapIconsInput(TypedDict):
+    """Names to find icons for, and an optional provider to look in first."""
+
+    #: Services, products, or ideas to find icons for, written as the user wrote them ("S3", "Postgres", "load balancer"). Up to 40 names of up to 80 characters.
+    names: List[str]
+    #: The cloud the architecture runs on. A name is looked up there first, so "queue" finds aws:sqs for aws. Omit it when the names are not tied to one provider.
+    provider: NotRequired[Literal["aws", "gcp", "azure", "alibaba", "oci", "ibm", "cloudflare", "digitalocean", "vercel"]]
+
+
+class MapIconsResponseResultsItem(TypedDict):
+    #: The name exactly as it was sent.
+    name: str
+    #: True when icon holds the one icon to use. False when the name could mean more than one: choose from candidates, or ask the user.
+    resolved: bool
+    #: The icon to write as icon=, such as aws:lambda; null when resolved is false.
+    icon: Optional[str]
+    #: exact: the name is the icon or product name. strong: the name clearly points at this icon and no other provider competes. ambiguous: several icons fit, or the match is by idea only.
+    confidence: Literal["exact", "strong", "ambiguous"]
+    #: Up to 3 other icons that also fit a resolved name, best first. Empty when none.
+    alternatives: List[str]
+    #: When resolved is false, the icons that fit, best first (up to 4). Empty when resolved.
+    candidates: List[str]
+
+
+class MapIconsResponseGapsItem(TypedDict):
+    #: The name that matched no icon.
+    name: str
+    #: A neutral icon to use instead, or leave icon= out so the node type draws its own.
+    fallback: str
+    #: Why there is no match, and what to try.
+    reason: str
+
+
+class MapIconsResponse(TypedDict):
+    """An icon, or candidates, for each name sent, and the names that found no icon."""
+
+    #: The provider hint that was used, or null.
+    provider: Literal["aws", "gcp", "azure", "alibaba", "oci", "ibm", "cloudflare", "digitalocean", "vercel", None]
+    #: One entry per name that matched something, in the order sent.
+    results: List[MapIconsResponseResultsItem]
+    #: Names that matched nothing, in the order sent.
+    gaps: List[MapIconsResponseGapsItem]
+    #: How many names have one icon to use.
+    resolvedCount: int
+    #: How many names need a choice from candidates.
+    ambiguousCount: int
+    #: How many names matched nothing.
+    gapCount: int
+
+
+class Note(TypedDict):
+    """An information note with its place in the source."""
+
+    #: A stable code, such as I122 for an icon alias.
+    code: str
+    #: A note never stops a drawing and is not a warning.
+    severity: Literal["info"]
+    message: str
+    line: int
+    column: int
+    length: int
+    #: The text to write instead.
+    hint: Optional[str]
+
+
+class OrganisationDiagramPublishedKeyObject(TypedDict):
+    """The key behind a connection or an organisation key. Null for a person, and once the key no longer exists."""
+
+    #: The key's id, as Keys and CI lists it. Never the key itself.
+    id: str
+    #: The key's name, or null once the key is revoked.
+    name: Optional[str]
+
+
+class OrganisationDiagram(TypedDict):
+    #: The handle for the diagram in the routes below.
+    id: str
+    #: The label given at publish, or null.
+    name: Optional[str]
+    #: The folder it is filed in, such as `Payments/Checkout`, or null for the top level.
+    folder: Optional[str]
+    #: The color scheme it was drawn in: light, dark, or auto.
+    scheme: Literal["light", "dark", "auto"]
+    #: Size of the stored SVG in bytes.
+    bytes: int
+    #: The person it belongs to: the member who published it, or the person who connected the agent that did. Null when that account has left or an organisation key published it.
+    createdBy: Optional[str]
+    #: How it was published: `person` (signed in, or with a key the person made), `connection` (an agent connected to the organisation, whose person is `createdBy`), or `key` (an organisation key from Keys and CI). Null for a diagram published before this was recorded.
+    publishedVia: Literal["person", "connection", "key", None]
+    #: The key behind a connection or an organisation key. Null for a person, and once the key no longer exists.
+    publishedKey: Optional[OrganisationDiagramPublishedKeyObject]
+    #: The client name the agent gave when it connected, such as `Claude Code`, for a connection only.
+    publishedClient: Optional[str]
+    #: When it was first published, in milliseconds since the epoch.
+    createdAt: int
+    #: When it was last published, in milliseconds since the epoch. Publishing the same diagram again moves it.
+    publishedAt: int
+    #: When it will be deleted, in milliseconds since the epoch, or null when the owner's plan keeps diagrams until they are deleted.
+    expiresAt: Optional[int]
+    #: A page in the portal that shows the diagram to a signed-in member. It is not a link anyone can open: an organisation's diagrams have no public address.
+    viewUrl: str
+    #: True while the owner has the diagram locked: nobody can delete, rename or move it, its publisher and the owner included, until the owner unlocks it. A lock does not stop it expiring on a plan that expires diagrams.
+    locked: bool
+    #: When the owner locked it, in milliseconds since the epoch, or null when it is not locked.
+    lockedAt: Optional[int]
+    #: Present, and true, when the owner has restricted this diagram's folder and the caller is allowed in it, so the portal can show it as locked. Absent otherwise. A diagram in a folder the caller may not use is not listed at all.
+    restricted: NotRequired[Literal[True]]
+    #: Present, and true, when the folder rule over this diagram keeps its diagrams inside: the svg route refuses `?download=1` and the copy route refuses a copy (403 `orgs.folder_restricted`). Absent otherwise.
+    keepInside: NotRequired[Literal[True]]
+    share: OrganisationDiagramShare
+    #: "Keep": true when an owner or admin keeps it from the library retention. The plan's own retention still applies.
+    kept: bool
+    #: When the retention deletes it, in milliseconds since the epoch: the nearer of the plan's expiry and "Delete library diagrams not updated for". Null when nothing will, and always null under a legal hold.
+    deletesAt: Optional[int]
+    classification: Classification
+    #: True while it is held for approval ("Publishing needs approval"): only its publisher and the approvers see it.
+    pending: bool
+    #: True while a new version of it waits for approval. The library shows this version until then.
+    changePending: bool
+    series: DiagramSeries
+
+
+class OrganisationDiagramShareObject(TypedDict):
+    """Its public link while the organisation shares it, or null. Only a diagram someone chose to share has one."""
+
+    #: The public address, `{CDN_URL}/l/<token>.svg`. Anyone with it can see the picture, without its source. It keeps showing the latest version when the diagram is edited, and never changes.
+    url: str
+    #: When the diagram was first shared, in milliseconds since the epoch.
+    sharedAt: int
+
+
+class OutlineResponse(TypedDict):
+    """A plain-text description of a diagram, usable as alt text."""
+
+    #: A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+    kind: str
+    #: One-line description.
+    summary: str
+    #: Lines in reading order: participants, steps, tables, and connections.
+    outline: List[str]
+
+
+class PlanDocumentInput(TypedDict):
+    """A document to read for the sections a picture would help."""
+
+    #: The whole document: Markdown, plain text pasted from Confluence, Notion, or Google Docs, or HTML. Up to 10000000 characters.
+    document: str
+    #: Most sections to suggest a picture for, up to 12. The strongest are kept, in document order. The default is 8.
+    maxSuggestions: NotRequired[int]
+
+
+class PlanDocumentResponseSuggestionsItem(TypedDict):
+    #: The heading of the section, as written.
+    heading: str
+    #: The 1-based line of the heading in the document that was sent.
+    line: int
+    #: A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+    kind: str
+    #: The style the starter uses: compare, score, raci, or risk for a matrix, files or org for a tree; null for the kind's only style.
+    style: Optional[str]
+    #: One sentence: what in the section points to this kind.
+    why: str
+    #: high: the text names this kind of picture or its shape fits it exactly. medium: it leans toward it. low: a fallback worth considering.
+    confidence: Literal["high", "medium", "low"]
+    #: A short Plotwork source of this kind that parses without errors: built from the names and numbers in the text where it could find them, otherwise a small example to edit. Replace every placeholder before you draw it.
+    starter: str
+    #: True when the starter uses names or numbers from the text; false when it is the kind's small example.
+    tailored: bool
+
+
+class PlanDocumentResponseCaps(TypedDict):
+    #: True when a cap left something out; messages says what.
+    hit: bool
+    messages: List[str]
+    maxSections: int
+    maxSuggestions: int
+
+
+class PlanDocumentResponse(TypedDict):
+    """The sections of a document a picture would help, each with a kind, a reason, and a starter."""
+
+    #: One sentence: how many sections were read and how many would gain a picture.
+    summary: str
+    #: How the document was read: Markdown headings, HTML h1 to h6, or plain text with heading-like lines.
+    format: Literal["markdown", "html", "text"]
+    #: Sections read, up to the cap.
+    sectionsRead: int
+    #: In document order. Sections that read well as text, or already have a diagram, are not listed.
+    suggestions: List[PlanDocumentResponseSuggestionsItem]
+    caps: PlanDocumentResponseCaps
+    #: The next step in one sentence.
+    next: str
+
+
+class PublishDiagramBody(TypedDict):
+    #: Diagram source; the first line is the header, such as flow "Title" (draw_diagram lists every kind).
+    source: str
+    #: The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json
+    settings: NotRequired[Dict[str, Any]]
+    #: The color scheme to draw it in: light, dark, or auto (one picture that follows the viewer's light or dark setting). Light when left out.
+    scheme: NotRequired[Literal["light", "dark", "auto"]]
+    #: The old name of scheme, still taken from callers that send it: light, dark, or auto. Send scheme instead; refused when both are sent and differ.
+    theme: NotRequired[Literal["light", "dark", "auto"]]
+    #: Whether the stored SVG carries the diagram source in its metadata, so the picture can be edited later: read_diagram gives the source back from the link. The source is part of the picture, which anyone who has the link can read (for a diagram in an organisation, every member who can open it). Left out, a personal diagram carries the source, and a diagram that lands in an organisation follows its keepEditable setting (on unless the owner turned it off). Send false to leave the source out, such as for a public link whose labels name internal systems. The same diagram published with and without it is two pictures with two links.
+    embedSource: NotRequired[bool]
+    #: A label for the diagram in your list and in the Markdown snippet. Optional.
+    name: NotRequired[str]
+    #: The folder to file the diagram in. Left out, a new diagram goes to the top level and a diagram that is already hosted stays where it is. A path files a new diagram there, or moves the one that is already hosted and keeps its link. null puts it at the top level.
+    folder: NotRequired[Optional[str]]
+    #: Point a stable link with this name at the diagram, so one address always shows the latest version. The first publish with a name makes the stable link (the answer's stableLink.url) and every later publish with the same name moves it to the new diagram; the address never changes. How many stable links an account keeps depends on its plan. An alias asks for a personal link, so an organisation that requires its library refuses it (orgs.publish_required). Optional.
+    alias: NotRequired[str]
+    #: An organisation's slug or id: the diagram goes to that organisation's private library, and the answer has private true and a viewUrl in place of a public link. The account must be a member who may publish there. Left out, the diagram goes to your own library, unless an organisation you belong to publishes its members' diagrams to its library.
+    organization: NotRequired[str]
+    #: True asks for a public link in your own library even though an organisation you belong to publishes its members' diagrams to its library by default. An organisation that requires its library refuses it (403 orgs.publish_required). Not with organization.
+    personal: NotRequired[bool]
+    #: The classification label of a diagram that lands in an organisation's library: public, internal or confidential. Left out, a new diagram takes its folder's default or the organisation's (internal unless an owner or admin chose another). Below that default, and lowering an existing diagram's label, is for an owner or admin. Ignored for a personal diagram.
+    classification: NotRequired[Classification]
+    series: NotRequired[SeriesInput]
+
+
+class PublishOrganization(TypedDict):
+    """The organisation whose private library holds the diagram."""
+
+    id: str
+    slug: str
+    name: str
+
+
+class PublishedDiagram(HostedDiagram):
+    #: True when this call stored a new diagram; false when the same diagram was already hosted and its link was kept.
+    created: bool
+    stableLink: NotRequired[StableLink]
+
+
+class PublishedOrganisationDiagram(OrganisationDiagram):
+    #: True when this call stored a new diagram; false when the same diagram was already in the library and was kept.
+    created: bool
+    #: True when the stored picture carries the diagram source: the call sent embedSource true, or left it out while the organisation's keepEditable is on.
+    sourceEmbedded: bool
+    approval: NotRequired[ApprovalHold]
+
+
+class ReadDiagramInput(TypedDict):
+    """The text of a Plotwork SVG, or the link of a hosted one."""
+
+    #: The text of a Plotwork SVG: the content of an .svg file in the repository. Send this or url, not both.
+    svg: NotRequired[str]
+    #: The link of a hosted Plotwork picture, https://cdn.plotwork.dev/d/<22 characters>.svg. Only Plotwork's own picture hosts are fetched. Send this or svg, not both.
+    url: NotRequired[str]
+
+
+class ReadDiagramResponseValidationObject(TypedDict):
+    """The check of the source, or null when there is none. It parses the source; draw_diagram also lays it out and returns warnings."""
+
+    #: True when the source has no errors.
+    valid: bool
+    #: Every error, each with line, column, and a hint; empty when valid.
+    errors: List[Diagnostic]
+    #: One-line description of the diagram, or null when invalid.
+    summary: Optional[str]
+
+
+class ReadDiagramResponsePictureObjectSizeObject(TypedDict):
+    """Its size in px, or null."""
+
+    #: Width in px.
+    width: int
+    #: Height in px.
+    height: int
+
+
+class ReadDiagramResponsePictureObject(TypedDict):
+    """What the picture says about itself, or null when the text is not an SVG."""
+
+    #: The diagram title, or null.
+    title: Optional[str]
+    #: The one-line summary the picture carries, or null.
+    summary: Optional[str]
+    #: The color scheme it was drawn in, or null.
+    scheme: Optional[str]
+    #: Its size in px, or null.
+    size: Optional[ReadDiagramResponsePictureObjectSizeObject]
+    #: The plain-language outline the picture carries, one entry for each line. Empty when the source was read: the source says more.
+    outline: List[str]
+    #: The text painted on the picture, each distinct label once, in painted order. Empty when the source was read.
+    labels: List[str]
+
+
+# The source of a Plotwork SVG, or why there is none and what to do.
+ReadDiagramResponse = TypedDict(
+    "ReadDiagramResponse",
+    {
+        # read: the source was found. no-source: the picture carries none. damaged: it carries one that cannot be read back. not-a-picture: the text is not an SVG. refused: the link is not one this tool fetches. unreachable: the link could not be fetched.
+        "status": "Literal[\"read\", \"no-source\", \"damaged\", \"not-a-picture\", \"refused\", \"unreachable\"]",
+        # True when source is set.
+        "hasSource": "bool",
+        # The exact source the picture was drawn from, ready to edit and send to draw_diagram; null when there is none.
+        "source": "Optional[str]",
+        # The diagram kind of the source, or null.
+        "kind": "Optional[str]",
+        # The id of the stored diagram when the picture was published (data-plotwork-id), or null.
+        "id": "Optional[str]",
+        # Where the picture came from: the text that was sent, or the link that was fetched.
+        "from": "Literal[\"text\", \"url\"]",
+        # The check of the source, or null when there is none. It parses the source; draw_diagram also lays it out and returns warnings.
+        "validation": "Optional[ReadDiagramResponseValidationObject]",
+        # What the picture says about itself, or null when the text is not an SVG.
+        "picture": "Optional[ReadDiagramResponsePictureObject]",
+        # What happened, in one sentence.
+        "message": "str",
+        # The next step in one sentence.
+        "next": "str",
+    },
+)
+
+
+class RenderInput(TypedDict):
+    """Diagram source and rendering options."""
+
+    #: Diagram source; the first line is the header, such as flow "Title" (draw_diagram lists every kind).
+    source: str
+    #: Color scheme to paint with: light, dark, or auto for one picture that follows the reader's light or dark setting.
+    scheme: NotRequired[Literal["light", "dark", "auto"]]
+    #: Colour theme for this drawing, over the header's theme=.
+    theme: NotRequired[Literal["plotwork", "slate", "ocean", "forest", "sunset", "mono", "contrast"]]
+    #: Prefix for element ids; set it when inlining several diagrams into one page.
+    idPrefix: NotRequired[str]
+    #: Write the source into the SVG metadata so read_diagram can give it back. Set it true when you save the SVG into a repository; anyone with the file can then read the source. Default false.
+    embedSource: NotRequired[bool]
+    #: The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json
+    settings: NotRequired[Dict[str, Any]]
+
+
+class RenderResponse(TypedDict):
+    """A rendered diagram."""
+
+    #: Self-contained SVG markup with an accessible title and description.
+    svg: str
+    #: The color scheme used.
+    scheme: Literal["light", "dark", "auto"]
+    size: Size
+    warnings: List[Diagnostic]
+
+
+class RoutedPublish(PublishedOrganisationDiagram):
+    #: The diagram is in an organisation's private library and has no public link.
+    private: Literal[True]
+    organization: PublishOrganization
+    #: Present when the organisation's Publishing setting chose its library for a publish that named no organisation: organisation-default (its members publish there unless they ask for a personal link) or organisation-required (they always do).
+    routedBy: NotRequired[Literal["organisation-default", "organisation-required"]]
+
+
+class SeriesInput(TypedDict):
+    """Publish the diagram as one part of a series: the parts of one big import, such as an overview and one diagram per group, each published with the same id and its place, the overview first. The portal shows a series as tabs of one diagram and can open it on one board. A part published at a place another diagram of the series holds takes the place. Left out, a diagram's series is left as it is. Optional."""
+
+    #: The series id, the same for every part: letters, digits, - and _, up to 64 characters. It names nothing outside your library or the organisation's.
+    id: str
+    #: The part's place in the series, from 1 (the overview); 0 is the whole import combined into one diagram, at most one a series.
+    index: int
+    #: How many parts the series has. Optional.
+    total: NotRequired[int]
+
+
+class Size(TypedDict):
+    """Natural size of a rendered diagram in px."""
+
+    #: Width in px.
+    width: int
+    #: Height in px.
+    height: int
+
+
+class StableLink(TypedDict):
+    """Present only when the publish named an alias: the stable link, now pointing at this diagram."""
+
+    #: The handle for managing the stable link (delete). It is not in its address.
+    id: str
+    #: The name you gave it. Only you see it.
+    alias: str
+    #: The public address, on the CDN host. It shows the diagram the stable link points at now (cached for up to 60 seconds) and never changes. Anyone with it can see the picture.
+    url: str
+    #: The diagram it shows now, or null when that diagram was deleted or expired; the address then answers 404 until you point the link at a diagram again.
+    diagramId: Optional[str]
+    #: When it was made, in milliseconds since the epoch.
+    createdAt: int
+    #: When it was last pointed at a diagram, in milliseconds since the epoch.
+    updatedAt: int
+
+
+class SuggestDiagramInput(TypedDict):
+    """A request in plain words and optional data to draw from."""
+
+    #: What the picture is for, in plain words, such as "permission matrix for these endpoints and roles" or "how a refund moves between support and billing".
+    request: str
+    #: Optional text to draw from: a pasted table, a list, numbers by period, or notes. Names and numbers in it are used in the starters.
+    data: NotRequired[str]
+
+
+class SuggestDiagramResponseSuggestionsItem(TypedDict):
+    #: A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+    kind: str
+    #: The style the starter uses: compare, score, raci, or risk for a matrix, files or org for a tree; null for the kind's only style.
+    style: Optional[str]
+    #: One sentence: why this kind fits.
+    why: str
+    #: high: the text names this kind of picture or its shape fits it exactly. medium: it leans toward it. low: a fallback worth considering.
+    confidence: Literal["high", "medium", "low"]
+    #: A short Plotwork source of this kind that parses without errors: built from the names and numbers in the text where it could find them, otherwise a small example to edit. Replace every placeholder before you draw it.
+    starter: str
+    #: True when the starter uses names or numbers from the text; false when it is the kind's small example.
+    tailored: bool
+    #: The few statements of this kind to write, as syntax. get_diagram_syntax with this kind has them all.
+    statements: List[str]
+
+
+class SuggestDiagramResponse(TypedDict):
+    """The diagram kinds that fit a request, best first, each with a starter source."""
+
+    #: The request that was read.
+    request: str
+    #: Up to 3, best first, one for each kind and style.
+    suggestions: List[SuggestDiagramResponseSuggestionsItem]
+    #: Present when the data is, or the request names, a file import_source reads (sql, openapi, compose, terraform, and so on): call import_source with this format and the file's text instead of editing a starter.
+    importFormat: NotRequired[str]
+    #: The next step in one sentence.
+    next: str
+
+
+class SyncMarkdownInput(TypedDict):
+    """A Markdown document and how to turn its diagram fences into pictures."""
+
+    #: The whole Markdown document, exactly as it is on disk, with its line endings. Up to 10000000 characters.
+    markdown: str
+    #: Where the document lives, relative to the repository root, with forward slashes, for example docs/guide.md. Picture links and file paths are worked out from it.
+    documentPath: str
+    #: The directory for the SVG files, relative to the repository root. The default is assets/diagrams next to the document.
+    assetsDir: NotRequired[str]
+    #: Text put in front of every picture file name, for documents that share one assets directory. By default a titled diagram is named from its title and an untitled one from the document name.
+    prefix: NotRequired[str]
+    #: When true, every ```mermaid fence that can be converted is replaced by a ```diagram fence first, then drawn. Fences that cannot be converted are left exactly as they were and reported.
+    convertMermaid: NotRequired[bool]
+    #: sync (the default) returns the rewritten document and the files to write. check changes nothing: it only reports whether a picture is stale or a fence would convert.
+    mode: NotRequired[Literal["sync", "check"]]
+    #: inline (the default) returns each SVG file with its content. none returns each with path, bytes, sha256, and viewUrl instead, so the answer stays small.
+    files: NotRequired[Literal["inline", "none"]]
+    #: Which page of files to return, from 1; pictures are paged in document order, a light and a dark file together.
+    page: NotRequired[int]
+    #: Pictures per page, at most 30. Setting page or pageSize turns paging on.
+    pageSize: NotRequired[int]
+    #: The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json
+    settings: NotRequired[Dict[str, Any]]
+
+
+class SyncMarkdownResponseFilesItem(TypedDict):
+    #: Where to write the file, relative to the repository root.
+    path: str
+    #: The file contents; absent when files is none.
+    content: NotRequired[str]
+    #: How content is encoded. Always utf8: the files are SVG text.
+    encoding: Literal["utf8"]
+    #: Only when files is none: the size of the file in bytes.
+    bytes: NotRequired[int]
+    #: Only when files is none: the SHA-256 of the content, in hex, to check a file fetched later.
+    sha256: NotRequired[str]
+    #: Only when files is none: a link that shows this diagram in a browser.
+    viewUrl: NotRequired[str]
+
+
+class SyncMarkdownResponseReportItem(TypedDict):
+    #: The picture id, which names the SVG files; null for a fence that has none (a mermaid fence that was not converted).
+    id: Optional[str]
+    #: diagram for a fence that was already Plotwork, mermaid for one that came from Mermaid.
+    source: Literal["diagram", "mermaid"]
+    #: The diagram kind, or null when it could not be read.
+    kind: Optional[str]
+    #: The 1-based line of the opening fence in the document that was sent.
+    line: int
+    #: synced: the picture was written or refreshed. converted: a mermaid fence became a diagram fence and was drawn. unchanged: the picture was already current. skipped: a cap stopped it, see message. failed: it has errors, the fence is left as it was.
+    status: Literal["synced", "converted", "unchanged", "skipped", "failed"]
+    #: Errors and warnings, with line numbers counted in the document that was sent. For a converted fence they point at the Mermaid lines.
+    diagnostics: List[Diagnostic]
+    #: A plain sentence when something needs saying, such as why a fence was skipped; otherwise null.
+    message: Optional[str]
+
+
+class SyncMarkdownResponseSummary(TypedDict):
+    #: Fences handled: synced, converted, unchanged, skipped, and failed together.
+    diagrams: int
+    synced: int
+    converted: int
+    unchanged: int
+    skipped: int
+    failed: int
+    #: Mermaid fences left alone because convertMermaid was false.
+    mermaidIgnored: int
+    #: Files to write.
+    files: int
+    #: Bytes in the returned document and files together.
+    outputBytes: int
+
+
+class SyncMarkdownResponseCaps(TypedDict):
+    #: True when a cap stopped some of the work. Nothing is cut silently: see messages.
+    hit: bool
+    #: One plain sentence per cap that was hit, saying what was skipped and what to do.
+    messages: List[str]
+    #: Most fences handled in one call.
+    maxDiagrams: int
+    #: Most bytes in the returned document and files together.
+    maxOutputBytes: int
+
+
+class SyncMarkdownResponsePages(TypedDict):
+    """Present when page or pageSize was sent: which pictures files holds, and the next page."""
+
+    page: int
+    pageSize: int
+    #: Pages in all.
+    pages: int
+    #: Pictures in all, each one file or a light and a dark one.
+    pictures: int
+    #: The page to ask for next, or null on the last one.
+    nextPage: Optional[int]
+
+
+class SyncMarkdownResponse(TypedDict):
+    """The result of turning a document's diagram fences into pictures."""
+
+    #: The mode that ran.
+    mode: Literal["sync", "check"]
+    #: The document to write back: every diagram fence wrapped in its collapsed source section, with the picture block and text description under it, and everything else unchanged. In check mode this is the document that was sent.
+    markdown: str
+    #: True when the document or a file differs from what was sent. In check mode this says the pictures are stale or a fence would convert.
+    changed: bool
+    #: The SVG files to write for each picture that was refreshed (one, or light and dark with schemes light-and-dark), with paths relative to the repository root. Empty in check mode. A picture that was already current has no files.
+    files: List[SyncMarkdownResponseFilesItem]
+    #: One entry per fence handled, in document order.
+    report: List[SyncMarkdownResponseReportItem]
+    summary: SyncMarkdownResponseSummary
+    caps: SyncMarkdownResponseCaps
+    #: Present when page or pageSize was sent: which pictures files holds, and the next page.
+    pages: NotRequired[SyncMarkdownResponsePages]
+    #: The next step in one sentence.
+    next: str
+
+
+class SyntaxResponseKindDetailsItemStatementsItem(TypedDict):
+    #: The statement with its parts named, such as: task <id> "Name" days=<n>.
+    syntax: str
+    #: What the statement does, and what it needs.
+    meaning: str
+    #: One line that parses.
+    example: str
+
+
+class SyntaxResponseKindDetailsItemLimitsItem(TypedDict):
+    #: What is counted, such as tasks.
+    name: str
+    #: More than this in one diagram draws a quality warning.
+    value: int
+    #: Why the limit exists and what to do past it.
+    meaning: str
+
+
+class SyntaxResponseKindDetailsItem(TypedDict):
+    #: A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+    kind: str
+    #: The header line, such as flow "Title".
+    header: str
+    #: What the kind's diagrams are called in a sentence, such as flow or database schema.
+    noun: str
+    #: One sentence: what the kind draws.
+    summary: str
+    #: The statements the kind adds to the header. Empty for a kind whose language the shared tables of this reference already describe.
+    statements: NotRequired[List[SyntaxResponseKindDetailsItemStatementsItem]]
+    #: The quality thresholds the kind adds. Empty for a kind whose limits are in the limits table of this reference.
+    limits: NotRequired[List[SyntaxResponseKindDetailsItemLimitsItem]]
+    #: Only in the overview, where statements and limits are left out: what a call with this kind returns that the overview does not, and how to ask for it.
+    more: NotRequired[str]
+
+
+class SyntaxResponseNodeTypesItem(TypedDict):
+    type: Literal["person", "agent", "client", "service", "gateway", "function", "database", "cache", "queue", "storage", "identity", "secret", "external", "step", "decision", "terminal"]
+    #: How the node is drawn.
+    shape: Literal["card", "pill"]
+    #: True when the card is filled and outlined in its tone, as for decisions.
+    isTinted: bool
+    #: Color family used when tone= is not set.
+    defaultTone: Literal["neutral", "blue", "violet", "aqua", "orange", "green", "amber", "red"]
+    #: Icon used when icon= is not set, or null for none.
+    defaultIcon: Optional[str]
+    #: True when the outline is dashed, as for external systems.
+    isDashed: bool
+    #: True when a sequence diagram actor may use this type.
+    usableAsActor: bool
+
+
+class SyntaxResponseArrowsItem(TypedDict):
+    #: The arrow as written in source.
+    token: str
+    #: How the line is drawn.
+    line: Literal["solid", "dashed", "dotted"]
+    #: Which ends carry an arrowhead.
+    heads: Literal["end", "both", "none"]
+    #: What the arrow says, so the right one is chosen.
+    meaning: str
+
+
+class SyntaxResponseIconProvidersItem(TypedDict):
+    #: Icon set prefix, as in aws:lambda.
+    set: Literal["aws", "gcp", "azure", "alibaba", "oci", "ibm", "cloudflare", "digitalocean", "vercel"]
+    #: The provider the set stands for.
+    title: str
+    #: Icons in the set: the provider itself (set:cloud) and its products.
+    iconCount: int
+    #: One icon of the set that is bundled, for example aws:lambda.
+    example: str
+
+
+class SyntaxResponseOverlay(TypedDict):
+    """A dashed frame around members that may sit in different groups; it owns none of them."""
+
+    #: Options an overlay statement takes after its name, as in: overlay id "Name" members=a,b type=scale-group
+    options: List[str]
+    #: How an overlay is always drawn.
+    frame: Literal["solid", "dashed", "dotted"]
+    #: What an overlay is for, so it is used where a group would be wrong.
+    meaning: str
+
+
+class SyntaxResponseGroupExample(TypedDict):
+    """A complete architecture diagram: typed groups nested by provider, a provider icon on every node, stack marks, and a dotted edge. Copy and edit it."""
+
+    #: A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+    kind: str
+    title: str
+    #: A complete diagram that is checked by the build; copy and edit it.
+    source: str
+
+
+class SyntaxResponseGroupTypesItem(TypedDict):
+    #: Value for type= on a group.
+    type: Literal["cloud", "account", "region", "zone", "network", "subnet", "public-subnet", "private-subnet", "management-subnet", "isolated-subnet", "resource-group", "cluster", "scale-group", "service-plan", "web-tier", "app-tier", "data-tier", "storage-account", "messaging", "edge", "security", "identity-boundary", "trust-boundary", "observability", "ci-cd", "environment", "cloud-boundary", "on-premises", "client-side", "external-systems"]
+    #: What the frame is called in the text description.
+    title: str
+    #: What the author means by this type, so the right one is chosen.
+    meaning: str
+    #: Color family the frame and tab get when tone= is not set.
+    tone: Literal["neutral", "blue", "violet", "aqua", "orange", "green", "amber", "red"]
+    #: How the outline is drawn.
+    frame: Literal["solid", "dashed", "dotted"]
+    #: Icon in the corner tab when the group has no provider.
+    icon: str
+    #: Icon in the corner tab for each provider whose icon differs from the generic one, keyed by provider set.
+    providerIcons: Dict[str, str]
+
+
+class SyntaxResponseGroup(TypedDict):
+    """How a flow group looks and what it accepts; its corner tab shows its icon and name."""
+
+    #: Options a group statement takes after its name, as in: group id "Name" type=region provider=aws {
+    options: List[str]
+    #: Color family of a group with no type when tone= is not set.
+    defaultTone: Literal["neutral", "blue", "violet", "aqua", "orange", "green", "amber", "red"]
+    #: A complete architecture diagram: typed groups nested by provider, a provider icon on every node, stack marks, and a dotted edge. Copy and edit it.
+    example: SyntaxResponseGroupExample
+    #: Every group type. A type gives the group a default icon, tone, frame style, and a shade that deepens with nesting; icon= and tone= override them.
+    types: List[SyntaxResponseGroupTypesItem]
+
+
+class SyntaxResponseFlowLookItem(TypedDict):
+    #: The option or statement as written, such as spacing or align.
+    key: str
+    #: header: on the flow header line. line: on an edge. statement: a line of its own.
+    scope: Literal["header", "line", "statement"]
+    #: What it takes.
+    values: str
+    #: What it does.
+    meaning: str
+    #: One line that parses.
+    example: str
+
+
+class SyntaxResponseLineOptionsItem(TypedDict):
+    #: The option as written, such as animate or step.
+    key: str
+    #: header: on the flow or sequence header line. line: on an edge or a message.
+    scope: Literal["header", "line"]
+    #: What the option takes.
+    values: str
+    #: What it does, and the cases where it is refused.
+    meaning: str
+    #: One line that parses.
+    example: str
+
+
+class SyntaxResponseLabelIconsItem(TypedDict):
+    #: An edge label that gets an icon automatically, matched whole and ignoring case.
+    label: str
+    #: The icon the label gets.
+    icon: str
+
+
+class SyntaxResponseVerbIconsItem(TypedDict):
+    #: The icon drawn in the label.
+    icon: str
+    #: Phrases that draw it: the whole label, or its first words followed by what is acted on ("reads orders").
+    words: List[str]
+
+
+class SyntaxResponseAutoIcons(TypedDict):
+    """Items with no icon= get the icon their label names for certain (a brand, a cloud product, a common role). icon=none keeps one item plain; icons=off on the header keeps them all plain."""
+
+    #: The header option: icons.
+    key: str
+    #: What it takes.
+    values: str
+    #: What it does, and how one item opts out.
+    meaning: str
+    #: One header line that parses.
+    example: str
+
+
+class SyntaxResponseRoleIconsItem(TypedDict):
+    #: The icon drawn.
+    icon: str
+    #: Whole words of a label of three words or fewer that draw it.
+    words: List[str]
+
+
+class SyntaxResponseStatusIconsItem(TypedDict):
+    #: Value for icon=, such as status:success.
+    ref: str
+    #: Color the icon is always drawn in, whatever tone its owner has.
+    tone: Literal["neutral", "blue", "violet", "aqua", "orange", "green", "amber", "red"]
+    #: What the icon says, so the right one is chosen.
+    meaning: str
+
+
+class SyntaxResponseLimits(TypedDict):
+    """Bounds and quality thresholds."""
+
+    maxSourceLength: int
+    #: Quality lint: more nodes than this warns, for a diagram with no groups.
+    maxFlowNodes: int
+    #: Each group of a flow diagram raises the node limit by this many.
+    nodesPerGroup: int
+    #: The node limit never rises above this, whatever the groups.
+    maxFlowNodesCeiling: int
+    maxSchemaTables: int
+    maxSequenceActors: int
+    #: More numbered steps than this in one diagram warns (W200).
+    maxNumberedSteps: int
+    #: Most technology marks a node carries in stack=.
+    maxStackMarks: int
+    #: Column width in px that diagrams are checked against.
+    targetWidth: int
+
+
+class SyntaxResponseEditing(TypedDict):
+    """How to edit an existing Plotwork SVG: read it back with read_diagram, change the source, draw it, and save or publish it again."""
+
+    #: In order: how to change a diagram that already exists as a Plotwork SVG, a hosted link or a file in the repository.
+    steps: List[str]
+    #: When to set embedSource true on draw_diagram or render_diagram, that publish_diagram embeds the source unless it is false, and what it means for who can read the source.
+    embedSource: str
+
+
+class SyntaxResponseDiagnosticCodesItem(TypedDict):
+    #: Identifier of the code.
+    name: str
+    #: The code to branch on, such as E120.
+    code: str
+    severity: Literal["error", "warning"]
+
+
+class SyntaxResponseExamplesItem(TypedDict):
+    #: A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today. Later versions add kinds, so expect others.
+    kind: str
+    title: str
+    #: A complete diagram that is checked by the build; copy and edit it.
+    source: str
+
+
+class SyntaxResponseImportFormatsItem(TypedDict):
+    #: The format, as import_source takes it.
+    format: str
+    #: What it reads.
+    reads: str
+    #: The diagram it draws.
+    draws: str
+    #: The options it takes.
+    options: str
+
+
+class SyntaxResponse(TypedDict):
+    """The diagram language for one scope: the overview, or one kind in full."""
+
+    #: What this answer is: overview, a topic (import-formats, icon-words), or the kind it describes in full (flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane, requirement, block, packet, kanban, radar, usecase, venn, fishbone, or wardley today; later versions add kinds, so expect others).
+    answer: str
+    #: In plain words: what this answer holds and how to get the rest.
+    howToGetAKind: str
+    #: Header keywords: the first line names the kind.
+    kinds: List[str]
+    #: The overview lists every kind in the order of kinds, with its header, noun, and summary, and a pointer in more. A kind answer holds that kind alone, in full.
+    kindDetails: List[SyntaxResponseKindDetailsItem]
+    nodeTypes: NotRequired[List[SyntaxResponseNodeTypesItem]]
+    tones: NotRequired[List[Literal["neutral", "blue", "violet", "aqua", "orange", "green", "amber", "red"]]]
+    #: Values for direction= on a flow header.
+    directions: NotRequired[List[Literal["auto", "right", "down", "left", "up"]]]
+    arrows: NotRequired[List[SyntaxResponseArrowsItem]]
+    #: Frames a sequence diagram can wrap around messages.
+    blockTypes: NotRequired[List[Literal["alt", "opt", "loop", "par"]]]
+    #: Flags a schema column row may carry.
+    columnFlags: NotRequired[List[Literal["pk", "fk", "unique", "nullable"]]]
+    #: The color schemes a picture is drawn in, chosen where it is drawn (a tool's scheme argument), not in the source.
+    schemes: NotRequired[List[Literal["light", "dark"]]]
+    #: Colour themes: theme=<name> on the header of any kind, such as flow "Title" theme=ocean. plotwork is the default; contrast reaches WCAG AAA. Each holds light and dark, and tones keep their meaning. An organisation's brand, on the hosted service, wins over it.
+    themes: NotRequired[List[Literal["plotwork", "slate", "ocean", "forest", "sunset", "mono", "contrast"]]]
+    iconSets: NotRequired[List[Literal["lucide", "simple", "status", "aws", "gcp", "azure", "alibaba", "oci", "ibm", "cloudflare", "digitalocean", "vercel", "k8s"]]]
+    #: Number of bundled icons; use search_icons to find names.
+    iconCount: NotRequired[int]
+    #: Cloud and platform providers, each an icon set holding the provider (set:cloud) and its products.
+    iconProviders: NotRequired[List[SyntaxResponseIconProvidersItem]]
+    #: A dashed frame around members that may sit in different groups; it owns none of them.
+    overlay: NotRequired[SyntaxResponseOverlay]
+    #: How a flow group looks and what it accepts; its corner tab shows its icon and name.
+    group: NotRequired[SyntaxResponseGroup]
+    #: Options that shape a flow diagram: spacing=, edges= and fit= on the header, main=on on an edge, and the align statement.
+    flowLook: NotRequired[List[SyntaxResponseFlowLookItem]]
+    #: Options that animate a line (animate=on makes dashes travel toward the arrowhead) or number the steps of a flow or sequence (numbered=on, start=, and step= on a line). All are off by default.
+    lineOptions: NotRequired[List[SyntaxResponseLineOptionsItem]]
+    #: Edge labels that name an outcome and get its status icon automatically (a tick for yes, a cross for no, a clock for expired); one per icon in a kind answer, every one in topic icon-words. icon=none on the edge removes it.
+    labelIcons: NotRequired[List[SyntaxResponseLabelIconsItem]]
+    #: The icons a flow edge label draws when it names a relationship with a verb. icon= on the edge wins, icon=none removes it, and icons=off on the header turns them all off.
+    verbIcons: NotRequired[List[SyntaxResponseVerbIconsItem]]
+    #: How to make a flow diagram look finished: verbs on arrows, role= on lines that mean something, typed groups, product names.
+    style: NotRequired[List[str]]
+    #: Items with no icon= get the icon their label names for certain (a brand, a cloud product, a common role). icon=none keeps one item plain; icons=off on the header keeps them all plain.
+    autoIcons: NotRequired[SyntaxResponseAutoIcons]
+    #: The plain icons for common roles, drawn on flow and sequence service and external items, C4 elements, layers blocks, mind map topics, and swimlane lanes. The last role word of the label wins.
+    roleIcons: NotRequired[List[SyntaxResponseRoleIconsItem]]
+    #: Colored status and outcome icons: a green check, a red X, and so on.
+    statusIcons: NotRequired[List[SyntaxResponseStatusIconsItem]]
+    #: Bounds and quality thresholds.
+    limits: NotRequired[SyntaxResponseLimits]
+    #: How to edit an existing Plotwork SVG: read it back with read_diagram, change the source, draw it, and save or publish it again.
+    editing: NotRequired[SyntaxResponseEditing]
+    diagnosticCodes: NotRequired[List[SyntaxResponseDiagnosticCodesItem]]
+    #: Tested examples: the overview holds the ones for the kinds the shared tables describe in full, a kind answer holds its own.
+    examples: List[SyntaxResponseExamplesItem]
+    #: Only for topic import-formats: every format import_source reads, a line each.
+    importFormats: NotRequired[List[SyntaxResponseImportFormatsItem]]
+
+
+class ValidateResponseSizeObject(TypedDict):
+    """Natural rendered size, or null when invalid."""
+
+    #: Width in px.
+    width: int
+    #: Height in px.
+    height: int
+
+
+class ValidateResponseQuality(TypedDict):
+    """How clean the laid-out diagram looks, with up to three changes; absent when invalid."""
+
+    #: 0 to 100; 100 is a picture with nothing to fix. The same diagram always gets the same score.
+    score: int
+    #: clean is 85 or more, fair 60 or more, cluttered below.
+    grade: Literal["clean", "fair", "cluttered"]
+    #: What the score is made from: crossings, lineOverBox, labelOverlaps, smallestTextPx (in an 880px column), aspectRatio, emptySpace (0 to 1), longestLine (px), detour (1 is straight), the counts of boxes, lines, labels, series, and slices, and any measure the kind adds.
+    measures: Dict[str, float]
+    #: Up to three changes, the one worth most first, each naming the statement or option to edit.
+    hints: List[str]
+    #: The grade, the score, and the first hint in one line.
+    line: str
+
+
+class ValidateResponse(TypedDict):
+    """Result of checking diagram source."""
+
+    #: True when there are no errors; warnings do not make a diagram invalid.
+    valid: bool
+    #: The diagram kind, or null when the header could not be read.
+    kind: Optional[str]
+    #: Every error found in one pass, so they can be fixed together.
+    errors: List[Diagnostic]
+    #: Quality warnings for a valid diagram, such as too dense or too wide.
+    warnings: List[Diagnostic]
+    #: One-line description of the diagram, or null when invalid.
+    summary: Optional[str]
+    #: Natural rendered size, or null when invalid.
+    size: Optional[ValidateResponseSizeObject]
+    #: How clean the laid-out diagram looks, with up to three changes; absent when invalid.
+    quality: NotRequired[ValidateResponseQuality]
+    #: Information notes, such as an icon alias resolved to a real icon; absent when there is none.
+    notices: NotRequired[List[Note]]
+
+
+# A diagram's classification label: `public`, `internal` (the default, and what a diagram published before labels reads as) or `confidential`. Confidential is never shared publicly; under "Share only diagrams labelled Public" only public is.
+Classification = Literal["public", "internal", "confidential"]
+
+
+# Its place in a series (the parts of one split import), or null when it is in none.
+DiagramSeries = Optional[DiagramSeriesObject]
+
+
+# Its public link while the organisation shares it, or null. Only a diagram someone chose to share has one.
+OrganisationDiagramShare = Optional[OrganisationDiagramShareObject]
+
+
+PublishAnswer = Union[PublishedDiagram, RoutedPublish]
+
+
+class DiagramsOperations:
+    """The ``diagrams`` operations."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def compare(self, **body: Unpack[CompareDiagramsInput]) -> CompareDiagramsResponse:
+        """Say what changed between two versions of a diagram. ``POST /v1/diagrams/compare``"""
+        return cast("CompareDiagramsResponse", self._transport.request("POST", "/v1/diagrams/compare", idempotent=True, body=body))
+
+    def convert_mermaid(self, **body: Unpack[ConvertMermaidInput]) -> ConvertMermaidResponse:
+        """Convert one Mermaid diagram. ``POST /v1/diagrams/convert-mermaid``"""
+        return cast("ConvertMermaidResponse", self._transport.request("POST", "/v1/diagrams/convert-mermaid", idempotent=True, body=body))
+
+    def draw(self, **body: Unpack[DrawDiagramInput]) -> DrawDiagramResponse:
+        """Check, describe, and draw a diagram. ``POST /v1/diagrams/draw``"""
+        return cast("DrawDiagramResponse", self._transport.request("POST", "/v1/diagrams/draw", idempotent=True, body=body))
+
+    def edit(self, **body: Unpack[EditDiagramInput]) -> EditDiagramResponse:
+        """Change diagram source with small typed operations. ``POST /v1/diagrams/edit``"""
+        return cast("EditDiagramResponse", self._transport.request("POST", "/v1/diagrams/edit", idempotent=True, body=body))
+
+    def outline(self, **body: Unpack[DiagramSourceInput]) -> OutlineResponse:
+        """Describe diagram source as text. ``POST /v1/diagrams/outline``"""
+        return cast("OutlineResponse", self._transport.request("POST", "/v1/diagrams/outline", idempotent=True, body=body))
+
+    def publish(self, **body: Unpack[PublishDiagramBody]) -> PublishAnswer:
+        """Publish a diagram and get a link. ``POST /v1/diagrams/publish``"""
+        return cast("PublishAnswer", self._transport.request("POST", "/v1/diagrams/publish", idempotent=False, body=body))
+
+    def read(self, **body: Unpack[ReadDiagramInput]) -> ReadDiagramResponse:
+        """Read the source back out of a Plotwork SVG. ``POST /v1/diagrams/read``"""
+        return cast("ReadDiagramResponse", self._transport.request("POST", "/v1/diagrams/read", idempotent=True, body=body))
+
+    def render(self, **body: Unpack[RenderInput]) -> RenderResponse:
+        """Render diagram source to SVG. ``POST /v1/diagrams/render``"""
+        return cast("RenderResponse", self._transport.request("POST", "/v1/diagrams/render", idempotent=True, body=body))
+
+    def suggest(self, **body: Unpack[SuggestDiagramInput]) -> SuggestDiagramResponse:
+        """Choose the kind of diagram for a request. ``POST /v1/diagrams/suggest``"""
+        return cast("SuggestDiagramResponse", self._transport.request("POST", "/v1/diagrams/suggest", idempotent=True, body=body))
+
+    def validate(self, **body: Unpack[DiagramSourceInput]) -> ValidateResponse:
+        """Check diagram source. ``POST /v1/diagrams/validate``"""
+        return cast("ValidateResponse", self._transport.request("POST", "/v1/diagrams/validate", idempotent=True, body=body))
+
+
+class IconsOperations:
+    """The ``icons`` operations."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def search(self, *, q: str, limit: Optional[int] = None) -> IconSearchResponse:
+        """Find bundled icon names. ``GET /v1/icons``"""
+        return cast("IconSearchResponse", self._transport.request("GET", "/v1/icons", idempotent=True, query={"q": q, "limit": limit}))
+
+    def map(self, **body: Unpack[MapIconsInput]) -> MapIconsResponse:
+        """Choose icons for many names at once. ``POST /v1/icons/map``"""
+        return cast("MapIconsResponse", self._transport.request("POST", "/v1/icons/map", idempotent=True, body=body))
+
+
+class MarkdownOperations:
+    """The ``markdown`` operations."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def plan(self, **body: Unpack[PlanDocumentInput]) -> PlanDocumentResponse:
+        """Find the sections of a document a picture would help. ``POST /v1/markdown/plan``"""
+        return cast("PlanDocumentResponse", self._transport.request("POST", "/v1/markdown/plan", idempotent=True, body=body))
+
+    def sync(self, **body: Unpack[SyncMarkdownInput]) -> SyncMarkdownResponse:
+        """Turn a document's diagram fences into pictures. ``POST /v1/markdown/sync``"""
+        return cast("SyncMarkdownResponse", self._transport.request("POST", "/v1/markdown/sync", idempotent=True, body=body))
+
+
+class PatternsOperations:
+    """The ``patterns`` operations."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def check(self, **body: Unpack[CheckPatternInput]) -> CheckPatternResponse:
+        """Check a pattern file. ``POST /v1/patterns/check``"""
+        return cast("CheckPatternResponse", self._transport.request("POST", "/v1/patterns/check", idempotent=True, body=body))
+
+    def draw(self, **body: Unpack[DrawFromPatternInput]) -> DrawFromPatternResponse:
+        """Fill a pattern and draw it. ``POST /v1/patterns/draw``"""
+        return cast("DrawFromPatternResponse", self._transport.request("POST", "/v1/patterns/draw", idempotent=True, body=body))
+
+    def find(self, **body: Unpack[FindPatternInput]) -> FindPatternResponse:
+        """Find a ready-made architecture diagram. ``POST /v1/patterns/find``"""
+        return cast("FindPatternResponse", self._transport.request("POST", "/v1/patterns/find", idempotent=True, body=body))
+
+    def get(self, **body: Unpack[GetPatternInput]) -> GetPatternResponse:
+        """Read a pattern filled for a flavour. ``POST /v1/patterns/get``"""
+        return cast("GetPatternResponse", self._transport.request("POST", "/v1/patterns/get", idempotent=True, body=body))
+
+
+class Operations:
+    """Every ``/v1`` operation, as groups of methods that each send one request through the transport."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+        self.diagrams = DiagramsOperations(transport)
+        self.icons = IconsOperations(transport)
+        self.markdown = MarkdownOperations(transport)
+        self.patterns = PatternsOperations(transport)
+
+    def import_source(self, **body: Unpack[ImportSourceInput]) -> ImportSourceResponse:
+        """Turn a file of another format into a diagram. ``POST /v1/import``"""
+        return cast("ImportSourceResponse", self._transport.request("POST", "/v1/import", idempotent=True, body=body))
+
+    def vocabulary(self, *, kind: Optional[Literal["flow", "sequence", "schema", "git", "gantt", "class", "state", "timeline", "journey", "mindmap", "treemap", "pie", "quadrant", "layers", "c4", "matrix", "sankey", "xychart", "tree", "swimlane", "requirement", "block", "packet", "kanban", "radar", "usecase", "venn", "fishbone", "wardley"]] = None, topic: Optional[Literal["import-formats", "icon-words"]] = None) -> SyntaxResponse:
+        """Get the diagram language reference. ``GET /v1/vocabulary``"""
+        return cast("SyntaxResponse", self._transport.request("GET", "/v1/vocabulary", idempotent=True, query={"kind": kind, "topic": topic}))
+
+
+#: The operations' addresses, for a test or a tool that lists them.
+OPERATION_PATHS = (
+    "POST /v1/diagrams/compare",
+    "POST /v1/diagrams/convert-mermaid",
+    "POST /v1/diagrams/draw",
+    "POST /v1/diagrams/edit",
+    "POST /v1/diagrams/outline",
+    "POST /v1/diagrams/publish",
+    "POST /v1/diagrams/read",
+    "POST /v1/diagrams/render",
+    "POST /v1/diagrams/suggest",
+    "POST /v1/diagrams/validate",
+    "GET /v1/icons",
+    "POST /v1/icons/map",
+    "POST /v1/import",
+    "POST /v1/markdown/plan",
+    "POST /v1/markdown/sync",
+    "POST /v1/patterns/check",
+    "POST /v1/patterns/draw",
+    "POST /v1/patterns/find",
+    "POST /v1/patterns/get",
+    "GET /v1/vocabulary",
+)