stage-11-agentics/c11/c11-markdown

c11 Markdown Panels

Use this skill to display markdown files in a c11 markdown panel — a first-class panel type that lives alongside terminal and browser panels in the same workspace, driven from the same c11 CLI. The binary is c11.

Rich rendering (headings, code blocks, tables, lists, Mermaid) with live file watching — the panel auto-updates when the file changes on disk.

Corpus Navigation

• Press ⌘K in a Markdown panel to search Markdown file names and headings in the containing Git repository. If the file is outside a Git repository, c11 searches its containing directory.
• Open the panel outline and select Referenced by to see links to the current document and current section. Selecting a result navigates within the same panel and adds to its history.
• The index skips .git, node_modules, DerivedData, build, dist, and .build; indexing is bounded, incremental and local to the open panel.
• C11-123 references show a title/status card only when the indexed repository has a matching local .lattice board entry. The lookup is read-only; unmatched IDs stay plain text.

Agent command:

~bash c11 markdown backlinks --panel <id|ref> --json ~

It returns bounded references for the selected Markdown panel's current file without changing panel or workspace selection.

Core Workflow

1. Write your plan or notes to a .md file.
2. Open it in a markdown panel.
3. The panel auto-updates when the file changes on disk.

Place docs by anchor, never by focus. An agent opening a doc for itself passes --panel "$C11_PANEL_ID" (or --area <ref>). The first doc splits beside that panel and later ones join the markdown area already beside it; a cross-workspace --workspace open adds a panel to an existing area instead of splitting.

# Open beside your own panel
c11 markdown open plan.md --panel "$C11_PANEL_ID"
 
# Absolute path
c11 markdown open /path/to/PLAN.md
 
# Target a specific workspace
c11 markdown open design.md --workspace workspace:2

When to Use

• Displaying an agent plan or task list alongside the terminal
• Showing documentation, changelogs, or READMEs while working
• Reviewing notes that update in real-time (e.g., a plan file being written by another process)

Producing artifacts the operator will return to

When you are creating more than one markdown artifact across a session — a map, a proposal, an audit, a status report — present them as one navigable document, not multiple disconnected areas. The hyperengineer is already running many agents in many workspaces; your session should not become another navigation problem for them to solve when they come back from lunch.

Two patterns, in priority order:

Default: one consolidated file with sections

Write to a single /tmp/<task>-trail.md and append as the work progresses. The operator scrolls one document instead of switching panels; the most current section sits on top so it is what they see first when they return.

# At the start of a multi-artifact piece of work, open the trail file once
c11 new-area --type markdown --file /tmp/voice-trail.md
# → OK panel:35 area:9 workspace:1
 
# Then write to that file as the work evolves — live-reload renders it.
# When new sections supersede earlier ones, put the new section at the top
# so the operator's first read is current truth, not stale context.

This is the right default unless the operator explicitly asks for separate files.

When you need multiple distinct files: panels of the same area

If the artifacts genuinely need to be separate files (different audiences, different lifetimes, downstream tooling reads them as units), add the second and subsequent ones as panels of the existing markdown area, not as new areas:

# Capture the area ref from the first open
c11 new-area --type markdown --file /tmp/voice-map.md
# → OK panel:35 area:9 workspace:1
 
# Add subsequent files as panels of area:9 — NOT new areas
c11 new-panel --type markdown --file /tmp/voice-wave-1.md --area area:9
c11 new-panel --type markdown --file /tmp/voice-audit.md --area area:9

The operator sees one markdown area; the artifacts navigate as panels of that area. This is materially different from three c11 new-area calls, which produce three sibling areas the operator has to context-switch between.

Always: title + description per panel

Whether it is one consolidated file or an area holding several panels, set c11 set-title and c11 set-description on every markdown panel immediately after opening it. The operator should know what they are looking at without opening it. See the top-level c11 skill's "Title and description" section for the conventions.

Close stale artifacts at session-end

If an early-session map document is superseded by a final audit, close the early panel (c11 close-panel --panel <ref>) so the operator's primary view shows the current truth. Leaving five panels open across a session because they were once useful is unkind to the next look.

Live File Watching

The panel automatically re-renders when the file changes on disk. This works with:

• Direct writes (echo "..." >> plan.md)
• Editor saves (vim, nano, VS Code)
• Atomic file replacement (write to temp, rename over original)
• Agent-generated plan files that are updated progressively

If the file is deleted, the panel shows a "file unavailable" state. During atomic replace, the panel attempts automatic reconnection within its short retry window. If the file returns later, close and reopen the panel.

Agent Integration

Opening a plan file

Write your plan to a file, then open it:

cat > plan.md << 'EOF'
# Task Plan
 
## Steps
1. Analyze the codebase
2. Implement the feature
3. Write tests
4. Verify the build
EOF
 
c11 markdown open plan.md

Updating a plan in real-time

The panel live-reloads, so simply overwrite the file as work progresses:

# The markdown panel updates automatically when the file changes
echo "## Step 1: Complete" >> plan.md

Recommended AGENTS.md instruction

Add this to your project's AGENTS.md to instruct coding agents to use the markdown viewer:

## Plan Display
 
When creating a plan or task list, write it to a `.md` file and open it in c11:
 
    c11 markdown open plan.md
 
The panel renders markdown with rich formatting and auto-updates when the file changes.

Routing

# Open in the caller's workspace (default — uses C11_WORKSPACE_ID)
c11 markdown open plan.md
 
# Open in a specific workspace
c11 markdown open plan.md --workspace workspace:2
 
# Navigate an existing Markdown panel in place (a terminal --panel is a placement anchor)
c11 markdown open plan.md --panel panel:5
 
# Add it as a panel in a specific area, no split
c11 markdown open plan.md --area area:3
 
# Open in a specific window
c11 markdown open plan.md --window window:1

Without --panel, an optional #fragment selects a heading in the new panel. With a stable --panel target, c11 markdown open <path>#<fragment> --panel panel:8 navigates that existing Markdown panel in place. This does not change the visible workspace or focus. The panel validates the target and records back/forward history.

Deep-Dive References

Rendering Support

The markdown panel renders:

• Headings (h1-h6) with dividers on h1/h2
• Fenced code blocks with monospaced font
• Inline code with highlighted background
• Tables with alternating row colors
• Ordered and unordered lists (nested)
• Blockquotes with left border
• Bold, italic, strikethrough
• Links (clickable)
• Horizontal rules
• Images (inline)

The offline WKWebView renderer bundles Mermaid, syntax highlighting, math, footnotes, task lists and callouts. No external Mermaid CLI is required.

Text scale (50–300% in 10% steps), theme (system, light, dark), typeface (theme, serif, sans, mono) and the outline choice belong to each panel and survive session restore. The last setting changed becomes the default for new panels. Invalid saved values fall back independently to their defaults. ⌘= / ⌘− / ⌘0 change text scale through c11's focused-panel shortcuts. ⌘F opens the focused Markdown panel's in-page find popover; Return and ⇧Return move between matches. ⇧⌘O toggles the page-rendered outline through the customizable shortcut registry. The outline docks when the effective width fits, otherwise it overlays the page; click a heading to jump without closing it, type to filter, and press Escape to clear the filter before closing it. System theme follows c11's effective appearance, which follows the OS when c11 appearance is set to System. Typing in page controls keeps the web view as first responder only when C11-359's panel focus policy allows it.

Document links navigate in the same panel by default. The toolbar's default link-destination toggle switches ordinary relative links to a new markdown panel; Cmd-click uses the opposite destination. Same-document anchors always stay in the current panel, including Cmd-click, and participate in panel history. Use ⌘[ / ⌘] or the toolbar arrows to move through that panel's history. A broken anchor offers the closest headings. Hovering a relative link briefly previews the target section after native path validation. Automatic document, palette and backlink navigation stays inside the source document's repository (or its directory when it has no repository).

Agent Reading Controls

These commands target an explicit markdown panel. They do not select its workspace or change c11's in-app focus. Discover the markdown.agent_cli feature, version 1, through c11 capabilities before relying on the socket methods. Use a stable panel:<n> reference or UUID; bare panel indices are rejected because they are scoped to the selected or caller workspace.

c11 markdown scroll --panel panel:8 --heading "Installation"
c11 markdown visible --panel panel:8 --json
c11 markdown visible --panel panel:8 --json --watch
c11 markdown theme --panel panel:8 --list
c11 markdown theme --panel panel:8 --set dark
c11 markdown typeface --panel panel:8 --list
c11 markdown typeface --panel panel:8 --set mono
c11 markdown font --panel panel:8 --scale 1.2
c11 markdown open-external --panel panel:8
c11 markdown open /path/to/guide.md#installation --panel panel:8
c11 markdown history --panel panel:8 --json
c11 markdown links --panel panel:8 --broken --json

visible reports the current heading path, visible source-line range, reading progress, theme, typeface, text scale, pane size, find state and bounded text selection. scroll, visible, and visible --watch create a hidden reader when needed and wait up to eight seconds for its first rendered state. A not_ready or timeout response means the reader did not become ready in that window; selecting the workspace is not an agent recovery path, so report the error instead. A scroll against a hidden panel takes effect in its reader; the gold flash appears when the panel is next shown.