# Expression elements and recipes

Status: agreed first-batch expression references. These are semantic terms, not a newly implemented input schema, and need not map one-to-one to existing diagram primitives.

This catalog provides expression references and a starting point for the default HTML library. HTML users may supply their own elements, recipes, and component mappings under the [extension contract](extensibility.md). Mermaid, pseudocode, text trees, and diff use built-in native structures only, with no external expression libraries.

## Element catalog

| Element | Meaning and use cases | Composition example |
| --- | --- | --- |
| Entity / step | A system, role, operation, or capability | Client and server; send request and handle response |
| Group | Ownership, containment, stage, or responsibility | Group authentication and request handling under the server |
| Relation | A call, dependency, data flow, or feedback | Client calls server; failure feeds back to a retry step |
| Branch | An explicit condition and its outcome | Finish on success; retry on failure while below the limit |
| Note | An explanation, constraint, risk, or conclusion | At most 3 retries; the note is not a request recipient |
| Comparison / change | A before-and-after difference or alternative | The old flow fails immediately; the new flow adds bounded retries |
| Emphasis | A focus, critical path, or important object | Emphasize the retry limit without treating it as a new state |

Grouping creates no relationship; spatial order creates no causality; emphasis creates no business state. The agent must declare semantics explicitly.

## Recipe: explain failure and retry

```text
Steps: send request → handle request
Branch: success / failure
Feedback: failure below the retry limit → send again
Note: at most 3 retries
Emphasis: retry limit
```

Use pseudocode to explain logic, Mermaid to explain interactions, or diff to explain the change that introduced retries. One recipe does not mandate a single form. The tool must retain conditions and limits rather than omit them to simplify the diagram.

## Recipe: explain module responsibilities

```text
Groups: client / server
Entities: page, request entry point, permission check
Relations: page calls entry point; entry point depends on permission check
Note: permission failure prevents further processing
```

Use a text tree when explaining ownership alone and Mermaid when explaining calls. A text tree should not disguise a call relationship as directory containment.

## Recipe: explain a change

```text
Comparison: before / after
Steps: save → return result
Change: check whether content has changed before saving
Emphasis: return the cache immediately when unchanged
```

Use diff for small changes, retaining enough original steps to identify the context. Choose HTML when several interactive states are needed. Automatic wrapping must not change diff markers or the meaning of original lines.

## Relationship to the prototype

Existing Card, Group, Relation, and Note primitives can represent some of these elements; Stack specifies reading order and layout constraints. Cross-form interfaces for branches, comparison, and emphasis are not yet finalized. Do not mistake this catalog for the current MCP tool parameter schema.