List Available Diagram Templates

Discover the diagram templates diagrams_template can instantiate, without reading any template contents.

Lists the built-in skeleton kinds (each supports 'puml' and 'mermaid') plus the custom-template candidate names found as *.json entries directly under PROJECT_ROOT/.diagrams-templates. A candidate name is an identifier to pass as custom_template to diagrams_template with template='custom'; the definition, the selected dialect, and the emitted source are validated there, not here. Discovery reads directory entries only — file contents are never read, so a malformed JSON file can still appear as a candidate — and it never writes or creates a missing template directory.

The scan is bounded: at most 1000 directory entries are examined (MAX_TEMPLATE_SCAN_ENTRIES), counting non-template entries too, plus one lookahead to detect the cap. There is no pagination, no full directory total, and no global subset ordering promised when capped: custom_count describes only the returned candidates, and the returned names are sorted only within the capped subset, which depends on filesystem iteration order.

Args: (none): Call with {} — discovery takes no arguments.

Returns: JSON with schema: { "built_in": [ // one entry per built-in kind, in documented order { "template": "class" | "sequence" | "c4_context", "formats": ["puml", "mermaid"] } ], "custom": [ // candidate names, sorted within the scanned subset { "template": "custom", "custom_template": string, "relative_path": string } ], "custom_count": number, // length of "custom": returned candidates only, not a full total when capped "entries_scanned": number, // directory entries examined, including non-template entries "scan_limit": number, // 1000 "truncated": boolean, // true when the entry cap was reached "scan_warning": string | null,// human-readable warning when truncated, otherwise null "written": false // always false; discovery never writes }

Each custom relative_path identifies the project-relative file '.diagrams-templates/.json'. Pass the custom_template identifier, not this path, to diagrams_template.

Examples:

• Use when: "What templates are available?" -> call with {}

• Use when: "Do we have a team skeleton?" -> call with {}, then look for its name in "custom"

• Use when: "Which built-in starter should I use?" -> call with {}, then pass one of the built_in names to diagrams_template

• Don't use when: You want the skeleton source itself (use diagrams_template with a name from this listing)

• Don't use when: You want generated content from code (use diagrams_generate or diagrams_generate_sequence)

Error Handling:

• Unknown argument fields are rejected: discovery accepts only {}

• A missing .diagrams-templates directory is not an error: "custom" is empty with truncated=false and scan_warning=null

• Subdirectories, symlink files/directories, invalid identifiers, and extensions other than .json are excluded, not errors

• A .diagrams-templates path that is not a regular directory is rejected without exposing absolute paths

• Expected filesystem access failures return CustomTemplateError without absolute paths

• Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets