scaffolder | features | documentation | decisions | folder-restructure-to-purlshq-dev

project:     scaffolder
feature:     documentation
doc-type:    DECISION
status:      accepted
version:     0.1
updated:     2026-03-22
depends-on:  scaffolder | features | documentation | DISCOVERY

Context

The scaffolder engine lives at D:\scaffolder-engine\ — a top-level folder on the D:\ drive. The documentation feature introduces a second repo (projects-purlshq-com) that is tightly coupled to the engine. Additionally, automated backups need a natural home.

The D:\ drive is not dedicated to development — it contains other unrelated content. With multiple repos at the drive root, there is no visible relationship between them. For an operator with medication-related brain fog, discovering the connection between two sibling folders months later is a real failure mode.

A structural solution is needed: something that makes the relationship between repos self-evident from the folder structure alone, keeps the drive root clean, and provides a home for backups and future tooling.

Options considered

Option 1 — Leave repos at drive root. D:\scaffolder-engine\ and D:\projects-purlshq-com\ side by side. Relationship is implied, not explicit. Drive root gets cluttered as more repos are added. Backups have no natural home. Lowest effort but worst discoverability.

Option 2 — Nest doc site inside the engine repo. Put projects-purlshq-com inside D:\scaffolder-engine\ as a nested repo (gitignored by the parent). Relationship is physically visible. No path changes for the engine. Downside: repos inside repos is unconventional and confusing when using git tooling. Also doesn’t solve the backup location problem or general drive root clutter.

Option 3 — Common parent folder D:\purlshq-dev\. Move the engine under D:\purlshq-dev\scaffolder-engine\. Place the doc site at D:\purlshq-dev\projects-purlshq-com\. Backups at D:\purlshq-dev\backups\. Everything development-related lives under one roof. The relationship is obvious from the folder structure. The drive root stays clean. One-time migration cost: every absolute path reference needs updating.

Decision

Option 3 — Common parent folder D:\purlshq-dev\.

Rationale

The primary driver is discoverability under brain fog conditions. A common parent folder makes the relationship between repos self-evident — you open D:\purlshq-dev\ and see everything that belongs together. No guessing, no remembering, no documentation required to find things.

The nested-repo approach (Option 2) solves the relationship problem but introduces git tooling confusion and doesn’t provide a home for backups or future repos. The flat drive-root approach (Option 1) solves nothing.

The migration cost is real — absolute paths in CLAUDE.md, shell aliases, WSL mount references, CHAT-REFERENCE.md, PROJECT-INSTRUCTIONS.md, hooks, and global config all need updating. But this is a one-time cost that Harley can execute from a task list, and every path reference becomes more descriptive after the change (/mnt/d/purlshq-dev/scaffolder-engine/ is immediately meaningful; /mnt/d/scaffolder-engine/ is not).

The -dev suffix distinguishes this from any future non-development purlshq folder (e.g., marketing assets, brand files).

Consequences

D:\scaffolder-engine\ moves to D:\purlshq-dev\scaffolder-engine\
All absolute path references must be updated (CLAUDE.md, aliases, WSL paths, hooks, global config, CHAT-REFERENCE.md, PROJECT-INSTRUCTIONS.md)
D:\purlshq-dev\projects-purlshq-com\ becomes the doc site repo location
D:\purlshq-dev\backups\ becomes the backup target
Future repos and tooling go under D:\purlshq-dev\
The engine’s .gitignore no longer needs to account for sibling repos or non-engine folders — simpler rules
WSL path becomes /mnt/d/purlshq-dev/scaffolder-engine/

DECISION — accepted. Do not modify.