jd-docs

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
uv run scripts/jd_init.py --diataxis  # Include Diataxis areas (41-44)

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

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

# Day-2: Add a new area
uv run scripts/jd_add_area.py --prefix 40 --name operations --dry-run

# Day-2: Classify unorganized files
uv run scripts/jd_classify.py docs/*.md
uv run scripts/jd_classify.py docs/*.md --diataxis  # With quadrant info

# Day-2: Move a file to an area
uv run scripts/jd_add.py docs/roadmap.md 00 --dry-run

See WORKFLOW.md for the full methodology.

Capabilities

• Scaffolding (jd_init.py) — Create J.D directory tree with README templates; supports --product for monorepo sub-trees, --init-config to generate .jd-config.json, and --diataxis to include Diataxis quadrant areas (41-44)
• 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

Day-2 Operations

• Add area (jd_add_area.py) — Create a new J.D area with prefix, name, README stub, config update, and auto re-index
• Classify (jd_classify.py) — Classify files into areas using keyword heuristics with confidence scoring (high/medium/low); --diataxis adds Diataxis quadrant column, --diataxis-move routes files to quadrant areas (41-44)
• Add/move file (jd_add.py) — Move a file to an area with auto-normalized kebab-case naming and cross-reference detection

Default Area Scheme

| Prefix | Name | Purpose | |--------|------|---------| | 00- | getting-started | Onboarding, setup, quick start, MVP | | 10- | product | Specs, features, roadmap, design, branding | | 20- | architecture | Tech decisions, system design, integration | | 30- | research | Spikes, investigations, reference material | | 90- | archive | Historical/deprecated docs |

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

With --diataxis, areas 41-44 are added for Diataxis quadrants:

| 41- | tutorials | Tutorials — step-by-step lessons (Diataxis) | | 42- | how-to | How-to guides — practical tasks (Diataxis) | | 43- | reference | Reference — technical descriptions (Diataxis) | | 44- | explanation | Explanation — conceptual discussions (Diataxis) |

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

| Issue | Fix | |-------|-----| | uv not found | curl -LsSf https://astral.sh/uv/install.sh \| sh or run with python3 scripts/jd_init.py | | Orphan files in validation | Move to area dir, or add to "ignore" in .jd-config.json | | Index appended at wrong position | Move <!-- JD:INDEX:START/END --> markers to desired location after first run | | Low confidence on all files | Expand keywords in config or use Claude-driven classification |

See TROUBLESHOOTING.md for all error scenarios.

References

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