Attaching Documents to Nodes
Issues, screenshots, specs, diagrams—attach them directly to the nodes they belong to.
A decision graph node says what was decided and why. But sometimes the full context lives in an external document: a GitHub issue body, an architecture diagram, a screenshot of a failing test. Document attachments let you bind those artifacts directly to graph nodes so they travel with the decision.
Attaching the Issue
Before starting implementation on issue #93, Claude saves the issue body to a file and attaches it to the goal node. This way, anyone recovering context later can read the original issue without leaving the decision graph.
Description: GitHub issue #93: Add CI pipelines
The file is copied into .deciduous/documents/ with a content-hash filename. The original file can be deleted—deciduous keeps its own copy. If you attach the same file twice, it deduplicates automatically.
Browsing Attached Documents
List all documents in the graph, or filter to a specific node:
Get full details on any document:
AI-Generated Descriptions
For images, PDFs, or documents where a manual description would be tedious, use --ai-describe at attach time or --ai to describe after the fact:
Managing Documents
The full document management toolkit:
| Command | What It Does |
|---|---|
doc attach <node> <file> |
Attach a file to a node (copies to .deciduous/documents/) |
doc list [node] |
List all documents, optionally filtered to one node |
doc show <id> |
Full details on a document |
doc describe <id> "text" |
Set or update the description manually |
doc describe <id> --ai |
Generate a description using AI |
doc open <id> |
Open the document in your default application |
doc detach <id> |
Soft-delete the attachment (recoverable) |
doc gc |
Garbage collect orphaned files from disk |
The doc detach command is a soft delete—it removes the association between the document and the node, but the file stays on disk until you run doc gc. This gives you a safety net if you detach something by mistake.
What to Attach
Documents work with any file type: markdown, images, PDFs, text files, spreadsheets. Attach whatever provides context that the node title and edges cannot capture on their own.
The best time to attach a document is at the start of a work session, before it might change. For GitHub issues, save the body to a file and attach it—the issue might get edited later, but the attached copy preserves the version that drove the original decision. For screenshots of failing tests, architecture diagrams, or spec documents, the same principle applies: capture the state that informed the decision.
In the next section, we'll continue the issue #93 session and watch Claude implement the CI workflow, logging actions and outcomes as it goes.