Explain With Canvas

Explain With Canvas

Use Agent Canvas as a visual explanation surface, not as a decorative diagram. The goal is to leave the user with a canvas that shows what exists, where it lives, how it connects, and what to inspect next.

Safety First

• Treat the target repository as read-only unless the user explicitly asks for code changes.
• Prefer agent-canvas scan-repo or scripts/safe-repo-scan.mjs for discovery. These commands read files and write only to an explicit output path.
• If the target repo is actively being edited by other agents, store Agent Canvas state outside that repo with --workspace /safe/path/.agent-canvas/external/<project>.
• Check git status --short before and after scanning when the user asks to avoid disturbing a repo.
• Do not run install, build, format, migration, or test commands in the target repo during an explanation pass unless the user asks for them.

Quick Workflow

1. Check canvas access:

   agent-canvas doctor
   

2. Scan the target repo read-only:

   agent-canvas scan-repo /path/to/repo --out /tmp/repo-agent-canvas-scan.json --pretty
   

3. If a live Agent Canvas is available, generate the canvas:

   agent-canvas explain /path/to/repo --workspace /path/to/workspace/.agent-canvas
   

4. If no live canvas is available, prepare operations without posting them:

   agent-canvas explain /path/to/repo --workspace /path/to/workspace/.agent-canvas --dry-run
   

5. Inspect the generated canvas and refine with MCP tools:

   • Add focused nodes for unclear flows.
   • Re-layout sections if nodes overlap.
   • Add provenance to new nodes using metadata.agentCanvas.files.
   • Avoid focusing every created node unless the user asks to follow the generation.

Canvas Structure

Create or update stable sections:

• Project overview: purpose, runtime, manifests, commands, current git state.
• Architecture map: major modules and responsibilities.
• Flows: route, screen, API, data, event, or user journeys.
• Source map: top directories, file types, important files.
• Questions: uncertainties, missing context, suggested next probes.

For UI apps, add optional sections when useful:

• Screens and routes.
• Components and design system.
• Data/state flow.
• Build/deploy surface.

Node Rules

• Use deterministic node IDs based on repo name and topic so reruns update existing nodes.
• Keep summaries short enough to scan. Link detail through provenance, not giant pasted files.
• Use document nodes for synthesized explanations.
• Use website nodes only for actual generated previews or captured app screens.
• Use sections for spatial grouping, not as fake decorative frames.
• Use layout/tidy tools after creating multiple nodes.

Provenance

Every explanation node should identify where its claim came from. Prefer this metadata shape:

{
  "agentCanvas": {
    "generatedBy": "explain-with-canvas",
    "repoRoot": "/path/to/repo",
    "gitHead": "abc1234",
    "files": ["src/app.ts", "package.json"],
    "readOnly": true
  }
}

When the agent is uncertain, say so in the node. A useful visual map is allowed to have open questions; it should not pretend guessed architecture is fact.

References

• Read references/codebase-canvas-patterns.md when deciding what kind of canvas to create for a repo.
• Use scripts/safe-repo-scan.mjs when agent-canvas scan-repo is not on PATH but this skill is available from the source package.