Quickstart

Merfolk keeps the diagram and the conversation around it together. This guide takes you through the complete product workflow in the web app: make a visual reference, share it with the people who know the work, and turn their feedback into the next version.

1. Start with a question

Choose something your team needs to make visible:

• A process that is difficult to explain
• A system or architecture that has changed
• A customer journey or operational workflow
• A decision that needs shared context

Open the Merfolk web app and create a diagram. Give it a title that makes its purpose clear to someone who did not create it.

2. Create the first version

Describe the main steps, services, people, or decisions. You can start with a small diagram and add detail as the team learns more.

For example, a simple system map might begin with:

graph TD
  Browser --> API
  API --> Database

The editor shows the Mermaid source alongside the rendered diagram. Use the preview to check whether the structure is understandable, then let the editor save your changes.

Read Create and edit diagrams for the editor workflow and source-format guidance.

3. Share the visual reference

Open Share to copy the diagram link. Choose the visibility that fits the work before sending it:

• Use public visibility for diagrams that are safe to share broadly.
• Use private visibility for internal architecture, unfinished work, or team material.

See Share diagrams for sharing guidance and Diagram visibility for the access model.

4. Collect feedback on the diagram

Ask reviewers to comment on the part they understand best. Comments can capture questions, missing paths, and follow-up tasks without requiring reviewers to edit the source.

For example:

• “What happens when the API is unavailable?”
• “This step is owned by operations, not engineering.”
• “Add the approval path before the release.”

Read Comments and collaboration to learn how review works.

5. Update the shared picture

An approved editor turns the useful feedback into a new source version. Keep the diagram focused on the question it should answer, then share the updated result again.

This is the Merfolk loop:

1. Create a useful first version.
2. Share it with the people who know the work.
3. Collect feedback where it belongs: on the diagram.
4. Update the source and continue the conversation.

Choose another workflow

The web app is the easiest place to start, but the same diagram workflow can begin wherever your work already happens:

• CLI quickstart — create and update diagrams from a terminal, script, or automation.
• Merfolk for agents — have a coding agent create or update diagrams from working context.
• Web app overview — learn how the workspace, editor, teams, and sharing fit together.