# Project specification

Status: agreed product direction, 2026-09-08. This document defines implementation goals; the [prototype guide](prototype-status.md) records existing behavior. Where they conflict, this specification governs new development, while the prototype contract remains a compatibility reference.

## 1. Problem

Agents can generate explanations, but the resulting artifacts often contain overflowing text, overlapping elements, labels covering arrows, connectors crossing nodes, or excessively wide layouts. Requiring repeated revisions after inspecting the result shifts layout work back to the agent and user.

The goal of show-me-mcp is for the agent to choose the content and display form, while the MCP automatically handles layout problems and delivers a checked result with as little repeated manual adjustment as possible.

## 2. Responsibilities

| Participant | Responsibility |
| --- | --- |
| Agent | Understand the question, choose a form, organize content with expression elements, and specify relationships and emphasis |
| MCP | Validate input, measure, lay out content, detect defects, repair them automatically, and verify the final artifact |
| Client / Pi plugin | Supply display-environment information, present artifacts as agreed, and avoid unverified layout changes |

Expression choices remain with the agent. The MCP can provide use cases and composition examples, but must not infer business facts, change relationships, or silently select another display form.

Simple content can be displayed directly. When content is submitted to the MCP, the tool owns display quality for that form; merely replying “too wide, fix it yourself” is insufficient.

## 3. Five display forms

| Form | Suitable content | Optimization focus |
| --- | --- | --- |
| Pseudocode | Algorithms, logic, important branches | Indentation, branch ownership, wrapping, readable steps |
| Text tree | Calls, components, files, ownership structures | Hierarchy, connectors, English and Chinese display widths, long labels |
| Mermaid | Interactions, control flow, data flow | Diagram type, syntax, node dimensions, label avoidance, connector routing |
| diff | Before-and-after changes | Necessary context, addition/deletion markers, line alignment, ownership of changes |
| HTML | UI, complex layouts, dense relationships, interaction | Layout components, text measurement, responsiveness, relationship presentation |

These are display forms, not five unrelated business models. Expression elements are references for organizing meaning; not every form must become graph nodes.

Extension scope is deliberately limited: HTML retains the seam for user expression and component libraries. Mermaid, pseudocode, text trees, and diff are built-in capabilities and do not accept user libraries, components, or custom Adapters. Each uses its own native input structure.

Mermaid versus PNG is not the project's core choice. PNG and SVG are artifact formats for display or export; changing a file format does not itself repair layout.

## 4. Semantic invariants

Automatic repair must preserve entity and step identity, relation endpoints and direction/type, group membership, explicit reading order, branch conditions and outcomes, diff addition/deletion semantics, and author-specified emphasis.

Do not silently delete, truncate, or hide content; invent connections; or reorder business steps to make a diagram look better. Wrapping text, expanding containers, adjusting spacing, moving labels, and rerouting connectors are renderer-owned layout operations.

If abbreviation, pagination, or splitting changes the reading experience, it requires an explicit policy and traceable relationships across pages. Automatic splitting policy is not yet settled and must not be assumed to be authorized.

## 5. Quality assurance flow

```text
Content and selected form
  → Validate expression structure
  → Measure and lay out for the display environment
  → Detect defects
  → Repair automatically and recheck
  → Verify the actual display artifact
  → Deliver the result and quality evidence
```

The normal workflow completes inside the MCP without requiring the agent to repeatedly change coordinates, text lengths, or connector paths.

Repair loops must have finite budgets and termination conditions. Specific limits are determined through implementation and acceptance examples. Within the declared quality boundary, only artifacts that pass their checks can be marked as passed.

When an input exceeds supported capabilities, return explicit limitations, unresolved defects, and attempted strategies. A preview may be retained if clearly marked as not passed, but must not be presented as accepted output. An agent changing forms to improve expression is normal; an agent being forced to repair layout should not be the routine workflow.

## 6. Responsibility for the final display

Syntax checks, successful SVG generation, or a valid PNG header do not establish display quality.

If a client lays out Mermaid again, quality claims cover only the renderer versions and display environments actually verified. Tests of one renderer cannot establish behavior in every client. Where client layout cannot be controlled or checked, state the verification scope. Controlled artifacts and plugin integration are subject to further design.

The goal is reliable delivery, not a promise that every input complexity, font, and client will always work without adjustment.

## 7. Expression references

See [expression elements](expression-elements.md) for elements and recipes. Each element must explain its meaning, use cases, and composition patterns. The agent declares semantics; the MCP owns coordinates, font sizes, spacing, and connector routing.

HTML expression elements are extensible: users can add domain elements, recipes, and their own component libraries. Built-in and user libraries follow the same extension contract; the core layout and quality engine must not hard-code a particular user library's catalog. The other four forms use built-in expression references and native structures. Semantic definitions, form-specific display adaptation, and core quality assurance should be designed separately; see [extensibility](extensibility.md).

User components must still participate in measurement, avoidance, and final artifact checks. Extensibility does not permit bypassing quality guarantees. Adding an expression library that satisfies the existing adaptation contract should not require changes to the core engine.

## 8. Current scope and evolution

Existing templates, primitives, SVG/PNG, Mermaid, and regression tests remain as the prototype baseline. The [HTML quality slice](quality-slice.md) and [four built-in forms](native-forms.md) are implemented. Support scopes and acceptance conclusions are independent for each form; general guarantees for arbitrary graphs and all clients are not complete.

The legacy width diagnostics, 120-column threshold, and nested-Stack-to-PNG fallback are transitional behavior, not proof that the product goal has been achieved. Expand implementation using failure examples and repair evidence from the [acceptance criteria](acceptance.md).

The GitHub repository is public. Licensing, package publication, and a standalone Pi plugin remain separate deliverables; initializing Git or publishing a repository does not establish those release states.