diff --git a/marlin_demo.md b/marlin_demo.md
new file mode 100644
index 0000000..55b4329
--- /dev/null
+++ b/marlin_demo.md
@@ -0,0 +1,165 @@
+# Marlin Demo
+
+Here’s a little “complex‐demo” you can spin up to exercise tags, attributes, FTS queries, `--exec` hooks, backups & restores. Just copy–paste each block into your terminal:
+
+---
+
+### 0 Create the demo folder and some files
+
+```bash
+rm -rf ~/marlin_demo_complex
+mkdir -p ~/marlin_demo_complex/{Projects/{Alpha,Beta,Gamma},Logs,Reports,Scripts,Media/Photos}
+
+# Projects
+cat <<EOF > ~/marlin_demo_complex/Projects/Alpha/draft1.md
+# Alpha draft 1
+
+- [ ] TODO: outline architecture
+- [ ] TODO: write tests
+EOF
+
+cat <<EOF > ~/marlin_demo_complex/Projects/Alpha/draft2.md
+# Alpha draft 2
+
+- [x] TODO: outline architecture
+- [ ] TODO: implement feature X
+EOF
+
+cat <<EOF > ~/marlin_demo_complex/Projects/Beta/notes.md
+Beta meeting notes:
+
+- decided on roadmap
+- ACTION: follow up with design team
+EOF
+
+cat <<EOF > ~/marlin_demo_complex/Projects/Beta/final.md
+# Beta Final
+
+All tasks complete. Ready to ship!
+EOF
+
+cat <<EOF > ~/marlin_demo_complex/Projects/Gamma/TODO.txt
+Gamma tasks:
+
+TODO: refactor module Y
+EOF
+
+# Logs
+echo "2025-05-15 12:00:00 INFO Starting app"   > ~/marlin_demo_complex/Logs/app.log
+echo "2025-05-15 12:01:00 ERROR Oops, crash"     >> ~/marlin_demo_complex/Logs/app.log
+echo "2025-05-15 00:00:00 INFO System check OK" > ~/marlin_demo_complex/Logs/system.log
+
+# Reports
+printf "Q1 financials\n" > ~/marlin_demo_complex/Reports/Q1_report.pdf
+
+# Scripts
+cat <<'EOF' > ~/marlin_demo_complex/Scripts/deploy.sh
+#!/usr/bin/env bash
+echo "Deploying version $1..."
+EOF
+chmod +x ~/marlin_demo_complex/Scripts/deploy.sh
+
+# Media
+echo "JPEGDATA" > ~/marlin_demo_complex/Media/Photos/event.jpg
+```
+
+---
+
+### 1 Initialize & index
+
+```bash
+marlin init
+marlin scan ~/marlin_demo_complex
+```
+
+---
+
+### 2 Attach hierarchical tags
+
+```bash
+# Tag all project markdown as “project/md”
+marlin tag "~/marlin_demo_complex/Projects/**/*.md" project/md
+
+# Tag your logs
+marlin tag "~/marlin_demo_complex/Logs/**/*.log" logs/app
+
+# Tag everything under Projects/Beta as “project/beta”
+marlin tag "~/marlin_demo_complex/Projects/Beta/**/*" project/beta
+```
+
+---
+
+### 3 Set custom attributes
+
+```bash
+# Mark only the “final.md” as complete
+marlin attr set "~/marlin_demo_complex/Projects/Beta/final.md" status complete
+
+# Mark PDF as reviewed
+marlin attr set "~/marlin_demo_complex/Reports/*.pdf" reviewed yes
+```
+
+---
+
+### 4 Play with search
+
+```bash
+# Find all TODOs (in any file)
+marlin search TODO
+
+# All markdown under your “project/md” tag
+marlin search tag:project/md
+
+# All files tagged “logs/app” containing ERROR
+marlin search "tag:logs/app AND ERROR"
+
+# Only your completed Beta deliverable
+marlin search "attr:status=complete"
+
+# Only reviewed PDFs
+marlin search "attr:reviewed=yes AND pdf"
+
+# Open every reviewed report
+marlin search "attr:reviewed=yes" --exec 'xdg-open {}'
+```
+
+---
+
+### 5 Try JSON output & verbose mode
+
+```bash
+marlin --format=json attr ls ~/marlin_demo_complex/Projects/Beta/final.md
+marlin --verbose scan ~/marlin_demo_complex
+```
+
+---
+
+### 6 Snapshot & restore
+
+```bash
+# Snapshot
+snap=$(marlin backup | awk '{print $NF}')
+
+# Delete your DB to simulate data loss
+rm ~/.local/share/marlin/index.db
+
+# Bring it back
+marlin restore "$snap"
+
+# Confirm you still see “TODO”
+marlin search TODO
+```
+
+---
+
+That gives you:
+
+* **wide folder structures** (Projects, Logs, Reports, Scripts, Media)
+* **hierarchical tags** you can mix and match
+* **key-value attributes** to flag state & review
+* **FTS5 queries** with AND/OR/NOT
+* **`--exec` hooks** to trigger external commands
+* **JSON output** for programmatic gluing
+* **backups & restores** to guard your data
+
+Have fun playing around!