TL-M0-09 · Scaffold apps/docs

Why: Starlight is where the engineering docs go after cutover (D23). Until then it only has to build.

ID TL-M0-09 · Level L0 · Run order row 9

Goal

apps/docs is a Starlight site and workspace member named docs that builds and runs.

Before

TL-M0-08 is Done.

Run

1 · Create the site from the Starlight template, without installing and without git

pnpm create astro@latest apps/docs --template starlight --no-install --no-git --skip-houston --yes

2 · Make it a workspace member named docs

pnpm --dir apps/docs pkg set name=docs
rm -f apps/docs/pnpm-workspace.yaml apps/docs/pnpm-lock.yaml
pnpm --dir apps/docs pkg delete packageManager

3 · Install from the root. pnpm stops on esbuild's install script; approve it, because Astro's bundler needs its native binary

pnpm install
pnpm approve-builds esbuild

4 · Format the template with Biome, build it, and look at it. Open http://localhost:4321, then press Ctrl+C

pnpm format
pnpm --filter docs build
pnpm --filter docs dev

5 · Commit

git add -A
git commit -m "build(docs): scaffold the Starlight docs app"

Expect

• Block 1: Astro reports the project created in apps/docs.
• Block 3: pnpm install ends with “ERR_PNPM_IGNORED_BUILDS” and “Ignored build scripts: esbuild@…”. approve-builds then runs “esbuild postinstall … Done”. If the list names any package other than esbuild, stop and paste it.
• Block 4: format fixes some files; the build ends with “[build] Complete!”; the browser shows the Starlight welcome page.
• Block 5: the commit line.

Check

cat pnpm-workspace.yaml
cat apps/docs/package.json | head -5

allowBuilds lists esbuild: true and lefthook: true. The docs package is named docs.

If it fails

“Template starlight could not be found”: the network blocked GitHub, where the templates live. Paste the output.

Undo

rm -rf apps/docs
git checkout -- pnpm-workspace.yaml pnpm-lock.yaml
pnpm install

Runs

Done 2026-10-05 (zuki)