scaffolder | features | documentation | decisions | repo-naming-projects-purlshq-com

project:     scaffolder
feature:     documentation
doc-type:    DECISION
status:      accepted
version:     0.1
updated:     2026-03-22
depends-on:  scaffolder | features | documentation | DISCOVERY,
             scaffolder | features | documentation | decisions | folder-restructure-to-purlshq-dev

Context

The documentation feature requires a private GitHub repo to host the Starlight doc site. The repo deploys to projects.purlshq.com via Cloudflare Pages. A name is needed for both the GitHub repo and the local folder.

The local folder sits inside D:\purlshq-dev\ alongside other repos. The operator has medication-related brain fog — the name must be immediately self-explanatory with no interpretation required.

An earlier assumption (from the DISCOVERY) was that the repo would be called purlshq/projects and mirror the projects folder. That assumption was dropped when it became clear that docs should not be duplicated into a separate repo — and that a folder called projects inside a parent that also contains projects/ in the engine tree would be confusing.

Options considered

purlshq/project-docs — Descriptive and clear. Differentiates from the projects/ folder. But doesn’t tell you where it deploys or what domain it serves.

purlshq/projects-site — Matches the domain (projects.purlshq.com) loosely. Clear that it’s a website. Doesn’t precisely map to the domain.

purlshq/docs — Short and simple. Inside purlshq-dev/ it reads naturally. But too generic — “docs” could be anything.

purlshq/projects-purlshq-com — The domain name itself, with dashes replacing dots. The folder name IS the URL. Zero ambiguity about what it is, where it deploys, or what domain it serves. Three months from now, the operator sees the folder name and knows the URL without opening anything.

Decision

purlshq/projects-purlshq-com — repo name and local folder name both use the domain-as-name convention with dashes replacing dots.

Rationale

Self-documentation is the deciding factor. The operator should never have to remember or look up the relationship between a folder and a domain. projects-purlshq-com maps directly to projects.purlshq.com with a trivial mental substitution (dashes → dots).

This convention scales: if a future project gets its own subdomain (e.g., scaffolder.purlshq.com), the repo would naturally be purlshq/scaffolder-purlshq-com. The pattern is immediately learnable.

Dots in folder names were rejected — they can cause issues with certain tools and feel unnatural in file paths. Dashes are universally safe.

The other options are all reasonable names, but none of them tell you the domain on sight. For an operator with brain fog, “tells you the domain on sight” beats “is a reasonable name.”

Consequences

GitHub repo: purlshq/projects-purlshq-com
Local folder: D:\purlshq-dev\projects-purlshq-com\
WSL path: /mnt/d/purlshq-dev/projects-purlshq-com/
Domain-as-name becomes a convention for future site repos
The earlier assumption of purlshq/projects from the DISCOVERY is superseded — DISCOVERY remains unmodified as the historical record
The starlight-over-alternatives decision’s consequences section references purlshq/projects — this is now understood as superseded by this decision (the original decision is not modified)

DECISION — accepted. Do not modify.