Johnny Decimal File Organization

This skill helps you work with the Johnny Decimal (JD) file system located at ~/Documents (or $XDG_DOCUMENTS_DIR).

Quick Reference

The system has 10 areas:

Structure Format

XX-XX Area Name/           # Area (decade range)
└── XX Category Name/      # Category (two digits)
    └── XX.YY Subcategory/ # Subcategory (ID)

Example path:

~/Documents/20-29 Finances/21 Banks/21.10 Example Bank/

Key Principles

1. One place for everything - Each item has exactly one correct location
2. Person-first for personal records - A spouse's health records go in 12 Spouse, not 50 Health
3. Purpose determines area - A bill goes in 27 Bills, not with the service provider
4. JDex is the brain - Notes and decisions live in 00.00 JDex for System

Finding Where Things Go

Before filing, consult:

• Flowchart: 00-09 System/00 System/00.00 JDex for System/flowchart.md
• Full structure: 00-09 System/00 System/00.00 JDex for System/overview.md

Or use your judgment with the filing hierarchy:

1. Is it about a specific person? → 10-19 Personal under their folder
2. Is it about yourself specifically? → 11 Self
3. Otherwise, match by purpose → Areas 20-99

Notes System

Notes about JD items live as markdown files in the JDex:

00-09 System/00 System/00.00 JDex for System/
├── overview.md      # System structure documentation
├── flowchart.md     # Filing decision tree
├── 31.14.md         # Notes about current home
├── 21.10.md         # Notes about a bank account
└── ...

Use jd-note to add timestamped entries to these files.

Naming Conventions

Folders:

• Areas: XX-XX Name (e.g., 20-29 Finances)
• Categories: XX Name (e.g., 21 Banks)
• Subcategories: XX.YY Name (e.g., 21.10 Example Bank)

Files:

• Date-prefixed for transient items: 2024-12-27_statement.pdf
• Descriptive for permanent items: policy_declaration.pdf
• Statements: statements/YYYY/MM.pdf or cc_MM.pdf for credit cards

Available Scripts

These scripts help with common operations:

Also available: jd <query> for navigation (in ~/bin/).

Interactive Features

When run by a human (not an agent), these commands have interactive modes:

• jd-note (no args) - Hierarchical browse (Area → Category → ID), then opens editor
• jd-note <ID> (without text) - Opens editor to write a note
• jd-read (no args) - Hierarchical browse (Area → Category → ID), then displays notes
• jd-read --edit (no args) - Hierarchical browse, then opens editor
• jd-read <ID> --edit - Opens the note file for editing

All properly handle TTY redirection for compatibility with any editor.

Agent Usage (--porcelain)

All scripts support a --porcelain flag for machine-readable output:

jd-list 21 --porcelain                # Full paths, no colors
jd-mkdir 21 "Name" --porcelain        # Outputs created path
jd-move file.pdf 21.10 --porcelain    # Outputs destination path
jd-note 21.10 "text" --porcelain      # Adds note (text required)
jd-read 21.10 --porcelain             # Outputs note file path
jd-validate file.pdf --porcelain      # Machine-readable validation

When using these scripts as an agent:

• Always use --porcelain for reliable parsing
• Paths are absolute and suitable for further operations
• Errors go to stderr with exit code 1
• jd-note requires text argument in agent mode (no editor)
• jd-read --edit is not available in agent mode (requires TTY)
• All scripts auto-detect agent mode when stdout/stdin are not TTYs

Safety Rules

• Scripts will refuse to overwrite existing files
• Scripts validate paths before operations
• Always confirm destructive operations with the user
• When uncertain about filing location, ask rather than guess

When to Explore

If you need current structure details not covered here, read:

1. overview.md in the JDex for full category breakdown
2. flowchart.md in the JDex for filing decisions
3. Use jd-list to see what exists in a location