Johnny.Decimal Documentation

Scaffold, validate, and maintain Johnny.Decimal documentation structure with sensible defaults and per-project customization.

Quick Start

# Scaffold a new structure
uv run scripts/jd_init.py --dry-run   # Preview first
uv run scripts/jd_init.py             # Create docs/ with defaults

# Validate existing structure
uv run scripts/jd_validate.py --dir docs

# Regenerate README index
uv run scripts/jd_index.py --dir docs

See WORKFLOW.md for the full six-phase methodology.

Capabilities

• Scaffolding (jd_init.py) — Create J.D directory tree with README templates; supports --product for monorepo sub-trees and --init-config to generate .jd-config.json
• Validation (jd_validate.py) — Check NN-kebab-case naming, detect orphan files, verify README presence per area; --strict for CI enforcement
• Index generation (jd_index.py) — Generate/update root README with table or tree index; preserves custom content via <!-- JD:INDEX:START/END --> markers
• Migration (Claude-driven) — Classify flat docs into J.D areas using naming heuristics, present a move plan, execute interactively

Default Area Scheme

Gap at 40-80 reserved for per-project customization (e.g., 40-operations).

Config File (.jd-config.json)

Optional per-project override at project root:

{
  "version": 1,
  "root": "docs",
  "areas": { "00": "getting-started", "10": "product", "20": "architecture", "30": "research", "90": "archive" },
  "products": [],
  "ignore": ["adr", "*.pdf"],
  "readme_format": "table"
}

Create with uv run scripts/jd_init.py --init-config. All fields have sensible defaults.

Common Issues

See TROUBLESHOOTING.md for all 10 error scenarios.

References

• WORKFLOW.md — Six-phase methodology (discovery, config, scaffold, validate, index, migrate)
• EXAMPLES.md — Real-world examples for all six operations
• TROUBLESHOOTING.md — Error handling and debugging tips