meridian-cli

Compile a YAML design-map spec into a self-contained, interactive HTML artifact (Cytoscape + Tailwind + Dagre).

meridian-cli is the canonical home for the Meridian deep-design workflow:

• CLI that turns *.meridian.yaml specs into navigable HTML design maps with compound nodes, descriptive edges, layer filters, search, and selectable user journeys.
• Skills (./skills/) — deep-design, issue-planner, builder — designed to be symlinked or snapshotted into per-project .cursor/skills/meridian/.

intent
  │
  ▼
[deep-design jam]        free-form conversation, severity-proportional pushback
  │                      (no code, no files in the codebase)
  ▼
<feature>.meridian.yaml  written by the agent in main chat
  │
  ▼  meridian compile
<feature>-design-map.html   self-contained interactive artifact

---

Install

Requires Python 3.12+ and uv.

Editable / development install (recommended for now)

From the meridian-cli repo root:

uv tool install --editable .

meridian is now on your PATH globally. Re-run after pulling changes (uv handles the editable link).

One-off run without installing

uv run --from . meridian compile path/to/spec.meridian.yaml

---

Usage

# scaffold a starter spec
meridian init docs/design/my-feature.meridian.yaml --feature "My Feature"

# validate cross-references (unique ids, parent/edge/journey resolution)
meridian validate docs/design/my-feature.meridian.yaml

# compile to HTML (auto-validates first)
meridian compile docs/design/my-feature.meridian.yaml \
  --out docs/design/my-feature-design-map.html \
  --open

# rebuild on every save
meridian compile docs/design/my-feature.meridian.yaml --watch

# live preview server with hot-reload (no HTML written to disk)
meridian preview docs/design/my-feature.meridian.yaml
# default: http://127.0.0.1:7823, opens in your browser
# saves to the YAML auto-recompile in-memory and reload all open tabs via SSE
# validation errors render as a styled error page that auto-recovers on fix
# flags: --port 8000 --host 0.0.0.0 --no-open

# emit JSON Schema (for VS Code YAML extension `yaml.schemas` mapping)
meridian schema --out spec.schema.json

The compiled HTML loads Cytoscape, Dagre, and Tailwind from CDN — open it directly with file:// or via any static file server.

---

Spec format

See skills/deep-design/spec_authoring_guide.md for the full guide. Minimal example:

meta:
  feature: "Hello World"
  intent: "Trivial example."

groups:
  - { id: g_route, label: "main.py", sub_label: "routes", layer: route }

nodes:
  - id: route_hello
    label: "hello()"
    layer: route
    parent: g_route
    file: "app/main.py"
    sig: "hello() -> str"
    behaviour:
      - "Returns 'world'"

  - id: util_format
    label: "format_msg()"
    layer: utility
    file: "app/util.py"

edges:
  - { from: route_hello, to: util_format, label: "calls" }

journeys:
  - id: hello_world
    label: "Say hello"
    steps:
      - { node: route_hello, note: "GET /hello" }
      - { node: util_format, note: "format the message" }

The full-fidelity reference is examples/rapid-fire.meridian.yaml (29 nodes, 38 edges, 7 journeys) along with its compiled output examples/rapid-fire.html.

---

Per-project skills consumption

./skills/ is the canonical home for the Meridian skill set. Each repo that wants to use Meridian should pull these into its own .cursor/skills/meridian/. Two options:

Symlink (recommended for active development)

# from inside your project
ln -s /path/to/meridian-cli/skills .cursor/skills/meridian

The skills update automatically as meridian-cli evolves.

Snapshot copy

cp -r /path/to/meridian-cli/skills/* /path/to/repo/.cursor/skills/meridian/

Re-run whenever the canonical skills change.

The skills assume meridian is on PATH; install per the section above before using them.

---

Project layout

meridian-cli/
  pyproject.toml              # uv project + console script `meridian`
  src/meridian/
    cli.py                    # Typer entrypoint
    spec/
      models.py               # Pydantic models for the spec
      loader.py               # YAML -> Spec
      validator.py            # cross-reference validation
    render/
      compiler.py             # Spec -> render context (JSON-encoded)
      template.py             # Jinja2 wrapper
      templates/
        artifact.html.j2      # the interactive HTML shell
  examples/
    rapid-fire.meridian.yaml  # canonical reference spec
    rapid-fire.html           # compiled output (regenerate via `meridian compile`)
  skills/
    deep-design/
      SKILL.md
      spec_authoring_guide.md
      sample_spec.yaml        # mirror of examples/rapid-fire.meridian.yaml
    builder/SKILL.md
    issue-planner/SKILL.md
    references/{glossary.md, testing-guidelines.md}
  tests/
    test_loader.py
    test_validator.py
    test_compiler.py
    fixtures/minimal.meridian.yaml

---

Future

Direction the CLI is intentionally pointed in (not implemented yet — out of scope for the initial release):

• Spec $ref / multi-file includes — split a large spec across files; loader merges before validation/render. Useful for system-level maps spanning multiple services where each service owns its slice of the spec.
• Depth-level granularity — every node carries an optional depth: N field (already in the schema today, currently inert). Once wired:
  • meridian compile --depth N will prune the rendered graph to nodes at that depth or shallower, producing a focused static artifact.
  • The HTML viewer will gain a depth slider that hides/shows nodes (and their edges) client-side without recompiling.
  • Same spec then serves as a CTO-level architecture overview at depth: 1 and a function-level implementation map at depth: 4+.
• Diff / change-mode rendering between two spec versions, highlighting added/removed/changed nodes and edges.
• Auto-derived "callers" view in the side drawer (the data is already in EDGES; render polish away).
• PyPI release so uv tool install meridian-cli works without the editable path.

---

Development

uv sync
uv run pytest -v          # 18 tests (loader, validator, compiler/template)
uv run meridian compile examples/rapid-fire.meridian.yaml

Run the version check from any cwd after install:

meridian version