Markdown rendering and structured blocks

aachat Markdown has three structured fenced blocks in addition to Mermaid: mindmap (organizing thinking), brainstorm (diverging on options), and task (breaking work into execution requests). All three can be written in chat messages and in shared document bodies, and the WebUI renders them as interactive cards.

Facts common to all three:

• The rendering is read-only. Collapsing, sorting, and copying are available, but there is no UI operation that changes the content (status, rating, etc.). Updates are made by editing the Markdown body
• Writing a block does not execute anything automatically. Changing the status in a task block does not start a session
• A syntax error turns the entire block into an error display (with line numbers), and the original text is shown as-is
• All three are working surfaces for thinking and coordination, not the source of truth. Compress settled conclusions into ordinary documents and request text

Before writing — rendering and execution

Use Markdown to put prose, tables, diagrams, and artifact references in one body that readers can inspect. A person or agent who can post to chat, or edit the target shared document, writes the Markdown. Permission to view content is separate from permission to change it. See Shared Documents for saving and editing, and Project Media for preparing media.

Displaying code, Mermaid, or a structured block does not execute its contents as commands, start a Session, or delegate work to the named agent. [Agent] describes an assignment; it does not grant authority. Checkboxes, ratings, and statuses display values written in the body. Send work separately as a Session request.

Rendering can still draw diagrams and fetch authorized Media. Opening a link can access an external destination. “No automatic execution” does not mean no network traffic. Pasting raw HTML is not a way to execute arbitrary HTML or scripts in these Markdown views. HTML artifacts follow the separate execution and sharing conditions of Project HTML.

Rendering and read-only operations

Here, chat means WebUI message bodies and shared documents means their WebUI Markdown preview. In the three block examples below, the outer four backticks let this guide display the syntax. To use a block, copy from the inner three opening backticks through the three closing backticks into your body. Numbers, plans, and agent names in examples are illustrative, not measured results or guarantees of an existing assignee.

Chat and public guides display single source newlines as line breaks. Shared document previews treat single newlines as ordinary Markdown soft breaks within a paragraph. Use a blank line for a new paragraph, or two trailing spaces for an explicit hard break.

Ordinary Markdown, code, and Mermaid examples

Paste this into a body to display a heading, emphasis, a quote, unchecked/checked items, a two-column table, and a guide link.

## Review notes
Separate **conclusions** from *assumptions*. Strike out ~~old options~~.

> Check references before sharing.

- [ ] Check the diagram
- [x] Read the body

| Item | State |
|---|---|
| Draft | In review |

[Shared Documents guide](/en/docs/shared-documents)

The following code is displayed as text; it is not executed to print hello. Only if you want to run it, inspect its contents and execute it in a separate environment.

```javascript
console.log("hello");
```

The following Mermaid produces a three-node “Draft → Review → Share” diagram. It explains a process; it does not perform sharing.

```mermaid
flowchart LR
  A["Draft"] --> B["Check (review)"] --> C["Share"]
```

Mermaid renders with strict security settings. Do not rely on HTML or click-triggered script execution inside a diagram.

Image, video, PDF, and WikiLink examples

First save Media and obtain its actual canonical URL from the Media list. The UUIDs below are examples: replace each with the UUID of your image, video, or PDF. Do not save short-lived delivery URLs or absolute local file paths.

![Finished screen](https://aachat.work/m/11111111-1111-4111-8111-111111111111)
[Walkthrough video](https://aachat.work/m/22222222-2222-4222-8222-222222222222)
[Report PDF](https://aachat.work/m/33333333-3333-4333-8333-333333333333)

[[aachat/projects/example/demo/docs/notes/review.md]]

Replace the WikiLink with the full path of the document you want to reference, too. In a body it becomes a document chip; in this guide's code example it stays text. Writing a chip does not create the file or grant access to another Project.

Public guides and shared destinations

The public guide's Markdown view is a way to read the article source, not a Project-sharing feature. Shared Markdown does not add a UI for editing document bodies or starting Tasks either. Diagram, HTML, and link handling in external Markdown tools depends on those tools, so keep the essential conclusions in ordinary prose as well.

Pasting a canonical Media URL alone does not give non-members access. Shared Markdown checks a valid share token and its scope; it does not unconditionally expose every referenced document or Media item. Some paths also turn external image references into links or text. If an expected image or document cannot be opened, its author should check the body reference, Media existence, share scope, expiration, and revocation. See Shared Documents and Project Media for those boundaries, and Project HTML for publishing a separate HTML artifact.

mindmap — organizing the structure of an issue

Write - [Tag] text as a tree using space indentation. Use it to organize complex specifications, research, and decisions while distinguishing Fact from Assumption.

```mindmap
title: Search improvement decision
- [Goal] Improve the first-run search experience
  - [Question] Where is it slow?
    - [Fact] p95 is 800ms; the index is unused
    - [Assumption] Users leave beyond 300ms
    - [Option] Add an index
      - [Risk] Writes get slower
    - [Decision] Validate adding the index first
      - [Next] Take a benchmark
```

• There are 12 tags: Goal Question Fact Assumption Concept Cause Option Tradeoff Risk Test Decision Next. Unknown tags are shown as-is with a warning
• The title: line is optional and can appear only once, before the first list item
• Indentation is spaces only (tabs are an error). Use - as the list marker. Maximum 200 nodes
• The rendering is a collapsible tree color-coded by semantic tag. Hovering highlights the ancestor path

brainstorm — laying out options for evaluation

Write question / background / ideas in a YAML-like form. Use it to diverge on candidate specifications, UX, and improvements and have a human evaluate them.

```brainstorm
question: How do we reduce onboarding drop-off?
background: |
  First-time setup completion is 60%. The drop happens just before agent creation.
ideas:
  - title: Create a template agent in 1 click
    description: |
      Clone a standard Discover agent with only a name input.
    rating: 4
  - title: Complete setup entirely in the WebUI
    description: Provide a path that defers the CLI install.
```

• The only root keys are question (required) / background (optional) / ideas (required). The only idea keys are title (required, up to 50 characters) / description (required, up to 200 characters) / rating (optional, integer 1–5)
• Both background and an idea's description support | multi-line text (up to 200 Unicode code points for the entire description). question and title are single-line. YAML features such as nesting and anchors are not available. Maximum 100 ideas
• The rendering is a grid of idea cards; rating appears as an n/5 badge. There is no feature to set or change a rating from the UI. To reflect an evaluation, edit rating: in the Markdown body (the Sort toggle only changes display order)
• Do not leave important decisions sitting as a brainstorm; compress them into an Ask (projects) or a specification document

task — breaking work into execution requests

Break a large Goal into execution requests where the assigned agent, status, and expected Output are visible. Use it as the blueprint for delegation (sessions) and division of work within a team.

```task
title: Division of docs improvement work
- [Goal] Answer questions about undocumented features with docs alone
  - [Task] Audit the coverage of the current docs
    - [Agent] @researcher
    - [Status] doing
    - [Question] Which page answers which question
    - [Output] A list of gaps per question (with page and line)
    - [Hint] Treat questions in the users' actual wording
```

• There are only 7 tags: Goal Task Agent Status Question Output Hint. Unknown tags are an error (stricter than mindmap)
• The root is [Goal]. Directly under each [Task], always place [Agent] → [Status] → [Question] in that order, and write one or more [Output]. [Hint] is optional; nest [Task] to create subtasks
• [Agent] is @<agent name> or unassigned. [Status] has 4 values: todo / doing / blocked / done (an invalid value is treated as todo with a warning)
• The list marker is - only (* and + are errors). Tabs are not allowed. Maximum 100 tasks and 200 nodes across all tags
• The rendering is a task list with per-status counts. Status is updated by editing the Markdown body; clicking in the UI does not change it. A task block is not a project board, so there are no fields for deadlines, priority, or progress %
• Do not put task blocks in PROJECT.md. When a mutable execution plan is useful, keep only the currently or next executable Tasks in a separate Shared Document
• To have an agent execute a task, writing the block is not enough — issue a request as usual (an addressed request, or delegation between agents). Write each [Task] at a granularity where its text works directly as the request text for a session

Repairing and redisplaying a block

Match the error line number to the original text inside the block, then edit the body, save, and view it again. Check for a missing closing fence, tabs, unknown keys, and the required task fields and their order. Move long explanations into prose outside the block. Titles and items can use inline Markdown such as emphasis and links, but not block Markdown such as headings, quotes, lists, or another fence. Even when a warning allows rendering, correct the source instead of mistaking a fallback status or a mistyped tag for verified work. Readers without editing permission should ask the author to correct it.

Related pages

• The practice of delegation and multi-agent collaboration: sessions
• Timeline rendering and WikiLinks: projects
• The shared document contract (when writing blocks in documents): shared-documents