scaffolder | features | documentation | DISCOVERY

project:     scaffolder
feature:     documentation
doc-type:    DISCOVERY
status:      draft
version:     0.1
updated:     2026-03-22
depends-on:  scaffolder | ARCHITECTURE,
             scaffolder | features | plane-integration | DISCOVERY

What this is

Raw discovery from session 2026-03-22. Covers the full exploration of PM tools, doc hosting, private repo strategy, and framework selection. Not a SPEC. Read this to understand why decisions landed where they did.

The problem being solved

Two problems discovered in the same session:

Plane’s MCP surface cannot support the doc store pattern — see plane-integration DISCOVERY. A replacement doc system is needed.
The operator needs a human-readable, browser-accessible view of all project documentation. Docs on disk are AI-readable but not human-navigable as a whole.
The PM tool itself turned out to be the wrong tool for both execution AND docs. A replacement PM tool was needed alongside a doc hosting solution.

PM tool exploration

Plane — dropped

MCP too restricted for doc use. See plane-integration DISCOVERY. Execution layer (work items, cycles, modules) was valid in isolation but the missing list/update/search on pages made it unworkable for the AI workflow pattern.

Linear — selected

MCP surface is materially better:

Official hosted MCP at https://mcp.linear.app/mcp
Read and write: issues, projects, cycles, milestones, initiatives, project updates, comments
OAuth 2.1 authentication — no API key management
Expanded Feb 2026: initiatives, project milestones, project updates all added with explicit Claude support noted in changelog
Free tier: unlimited users, 250 active issues, full API access

Linear Documents exist but are flat per-project — no nesting, no cross-project hierarchy. Not suitable for the doc store pattern. Linear is the right PM tool. Docs live elsewhere.

Features → Linear projects mapping

Each project folder = one Linear project. Features map to Linear projects (not modules as originally discussed with Plane — Linear’s model is project-centric). Cycles for sprints. Milestones for releases. Issues + sub-issues for tasks.

Doc hosting exploration

Requirements

Hierarchical navigation mirroring local docs/ folder structure
Auto-generated sidebar — no manual config per new page or project
Private — operator-only access
Deployed to custom subdomain (projects.purlshq.com)
Markdown-native — Joker writes files, site renders on push
Extensible — custom components possible for future expansion
Zero or near-zero cost
Minimal maintenance for a solo op

Options explored

Plane Wiki — dropped. MCP restrictions (see above). Wiki nesting on Pro, Pages nesting on Business only.

VitePress — clean, minimal, fast. Manual sidebar config required. No breadcrumbs. No right-side page nav by default. Would need config updates every time new pages/projects are added.

Starlight (Astro) — auto-generates sidebar from folder structure. Breadcrumbs, right-side page nav, search, light/dark toggle all built in. React-adjacent (Astro) ecosystem for future extensibility. Selected. See decisions/starlight-over-alternatives.md

MkDocs Material — also auto-generates nav from folders, beautiful default theme, very low maintenance. Lost on extensibility — Python ecosystem limits custom component work.

Docusaurus — React-based, mature. Heavier, more config, designed for open source product docs. Overkill for private internal project docs.

Sphinx, Hugo — not suited. Sphinx is API-doc focused. Hugo requires manual theme selection with no obvious winner for this use case.

All options confirmed as natively supported by Cloudflare Pages: developers.cloudflare.com/pages/framework-guides/

Private repo pattern

Source of truth remains on disk. Website is a rendered human view.

One private GitHub repo: purlshq/projects
Mirrors D:\scaffolder-engine\projects\ exactly — one folder per project
Cloudflare Pages deploys to projects.purlshq.com
Cloudflare Access locks the subdomain — operator email only, free tier
Every git push triggers auto-deploy — Joker writes files, site updates
Monorepo support confirmed: Cloudflare Pages supports up to 5 separate deployed sites from one repo (future: per-project subdomains if needed)

AI workflow unchanged

Joker reads and writes files via filesystem MCP. The website is purely a human interface. Joker does not need the website to read docs — it reads files directly. The “Joker access” problem is already solved.

Doc type system defined this session

Full standard defined — formal version at: _system/standards/doc-types.md

Tier structure:

T1 Project: DISCOVERY, SPEC, ARCHITECTURE, SCHEMA (optional), DECISION, INDEX
T2 Feature: DISCOVERY, SPEC, TASKS, TESTING, SCHEMA, ARCHITECTURE (optional), DECISION
T3 Sub-feature: Joker decides at discovery

Page header standard (every page):

project:      [name]
feature:      [name]        ← omit at T1
sub-feature:  [name]        ← omit if not T3
doc-type:     [TYPE]
status:       stub | draft | accepted | superseded
version:      0.1
updated:      YYYY-MM-DD
depends-on:   [page title], [page title]

DECISION pages use ADR format: context, options, decision, rationale, consequences.

The “cannot reorganize” guarantee: Joker creates every page as a stub before content is written. Structure is fixed before Harley starts.

Naming convention (pipe-separated hierarchy): scaffolder | features | documentation | decisions | starlight-over-alternatives

What comes next

Harley builds Starlight site as a scaffolder sub-project
Create private repo purlshq/projects on GitHub
Configure Cloudflare Pages → projects.purlshq.com
Set up Cloudflare Access on that subdomain
Wire Linear MCP into Harley (claude mcp add —transport http linear-server https://mcp.linear.app/mcp)
Produce docs/features/documentation/SPEC.md
Update scaffolder SKILL.md to reflect new doc type system
Re-scope v0.11.0 — Plane epic becomes Linear + documentation build

DISCOVERY — raw session capture. Do not modify. Produce SPEC separately.