Exporting Your Work

The decision graph lives in a local SQLite database. To share it with others, you export it—as JSON for the web, as DOT for visualizations, or as markdown for pull requests.

Sync — Export for GitHub Pages

The deciduous sync command exports your entire graph as JSON files suitable for static hosting:

deciduous sync
deciduous sync Exported graph to docs/graph-data.json 61 nodes, 70 edges Exported git-history.json (28 commits)

This creates two files in your docs/ directory:

File Contents
docs/graph-data.json All nodes, edges, metadata, and prompts
docs/git-history.json Commit messages, authors, and dates for nodes linked via --commit

The web viewer (docs/index.html) reads these JSON files. Once synced and pushed to GitHub, anyone can browse the decision graph in a browser—no deciduous installation needed.

Deploying to GitHub Pages

After running deciduous sync, deploying is three steps:

Deploying to GitHub Pages
deciduous sync Exported graph to docs/graph-data.json 61 nodes, 70 edges Exported git-history.json (28 commits) git add docs/graph-data.json docs/git-history.json git commit -m "docs: sync decision graph" git push origin main

Then in your GitHub repository settings, go to Pages, select Deploy from branch, and choose the /docs folder. Your graph will be live at https://<user>.github.io/<repo>/.

PR Writeups

The deciduous writeup command generates a markdown summary of a set of nodes, suitable for pasting into a pull request body:

Generating a PR writeup
deciduous writeup -t "Add CI Pipelines" --nodes 57-61 --auto ## Summary **Goal:** Add CI pipelines for snowflex ## Key Decisions ### Use separate workflow files - clearer separation, easier contributor onboarding ## Implementation - Implement unit test CI workflow ## Test Plan - [ ] Verify implementation - [ ] Run test suite ## Decision Graph Reference This PR corresponds to deciduous nodes: 57, 58, 59, 60, 61

The writeup pulls goal titles, decision rationales, action summaries, and outcome statuses directly from the graph. The --auto flag detects a branch-specific PNG and embeds it as an image link.

Key flags for deciduous writeup:

Flag Effect
-t, --title PR title used in the summary header
-n, --nodes Node IDs or ranges to include (e.g., 57-61 or 57,58,60)
-r, --roots Root node IDs—BFS traverses all children
--auto Auto-detect branch-specific PNG for embedding
--png Specify a PNG filename manually
--no-dot Skip the DOT graph section
--no-test-plan Skip the test plan checklist
-o, --output Write to file instead of stdout

Attaching Writeups to the Graph

You can attach the generated writeup back to the graph as a document, creating a permanent record:

Attaching a writeup
deciduous writeup -t "Add CI Pipelines" --nodes 57-61 -o PR-WRITEUP.md deciduous doc attach 57 PR-WRITEUP.md -d "PR writeup for CI pipeline work" Attached document (id: 3) to node #57

Backups

Before any major export or sync operation, it is good practice to create a backup of the database:

deciduous backup
deciduous backup Backup created: .deciduous/backups/deciduous-2024-01-15T14-30-00.db

Backups are timestamped SQLite copies stored in .deciduous/backups/. If anything goes wrong during a sync or export, you can restore from the most recent backup by copying it over the main database.

Never delete the database

The SQLite database at .deciduous/deciduous.db is the source of truth. Always use deciduous backup before risky operations, and never delete the database file directly.