docs: polish bundle — muted-foreground token, getting-started, Neon URL (closes #47)

.env.example

@@ -1,4 +1,8 @@
 # Neon serverless Postgres connection string.
-# Get one at: https://neon.tech → New Project → Connection Details → copy the pooled URL.
+# Get one at https://neon.tech → New Project → Connection Details.
+# This template uses Neon's HTTP driver (drizzle-orm/neon-http), so the pooled
+# vs. direct endpoint doesn't matter — either connection string works. (The
+# -pooler endpoint is for the WebSocket `Pool` driver, which this template
+# doesn't use.)
 # Format: postgresql://user:password@host/dbname?sslmode=require
 DATABASE_URL=

app/styles/app.css

@@ -1 +1,8 @@
 @import "tailwindcss";
+
+@theme {
+  /* Muted/secondary text — backs the `text-muted-foreground` utility used by
+     the starter routes. Tailwind v4 emits nothing for an undefined color
+     utility, so this token must exist for that class to render. */
+  --color-muted-foreground: oklch(0.556 0 0);
+}

changelog.d/47-polish-bundle.fixed.md

@@ -0,0 +1,3 @@
+- `[propagate]` Defined the `--color-muted-foreground` theme token in `app/styles/app.css` so the `text-muted-foreground` utility used by the starter routes actually renders (Tailwind v4 emits nothing for an undefined color utility).
+- `[propagate]` Aligned the scaffold-generated README with the scaffold's "Next steps" output — one command order, and the `DATABASE_URL` step is now in both.
+- `[propagate]` Clarified Neon connection-string guidance in `.env.example` and `docs/agents/environment.md`: with the `neon-http` driver the pooled vs. direct endpoint doesn't matter (the `-pooler` endpoint is for the WebSocket `Pool` driver).

docs/agents/environment.md

@@ -47,19 +47,18 @@ This project uses [Neon](https://neon.tech) — a serverless Postgres provider w
 
 1. Go to [neon.tech](https://neon.tech) and sign in (GitHub login works).
 2. Click **New Project** → choose a region close to you → **Create Project**.
-3. On the project dashboard, click **Connection Details**.
-4. Select the **Pooled connection** tab and copy the connection string.
-5. Create `.env` at the project root and paste it in:
+3. On the project dashboard, click **Connection Details** and copy the connection string. Either the **Pooled** or **Direct** endpoint works — this template uses Neon's HTTP driver (`drizzle-orm/neon-http`), so the `-pooler` distinction (which matters for the WebSocket `Pool` driver) doesn't apply here.
+4. Create `.env` at the project root and paste it in:
 
 ```bash
 DATABASE_URL=postgresql://user:password@host/dbname?sslmode=require
 ```
 
-6. Run `pnpm db:migrate` to apply the initial schema.
+5. Run `pnpm db:migrate` to apply the initial schema.
 
 ### CI (GitHub Actions)
 
 1. Go to your GitHub repo → **Settings** → **Secrets and variables** → **Actions**.
 2. Click **New repository secret**.
-3. Name: `CI_E2E_DATABASE_URL`, Value: the same pooled connection string from above.
+3. Name: `CI_E2E_DATABASE_URL`, Value: the same connection string from above.
 4. The CI workflow at `.github/workflows/ci.yml` reads `secrets.CI_E2E_DATABASE_URL` and injects it as `DATABASE_URL` for the E2E job. E2E steps are skipped when the secret is absent.

docs/agents/styling.md

@@ -22,6 +22,11 @@ This is the only global stylesheet. Keep it minimal:
 }
 ```
 
+The starter routes use the `text-muted-foreground` utility for secondary text;
+its backing `--color-muted-foreground` token is defined in `app/styles/app.css`.
+Tailwind v4 emits nothing for an undefined color utility, so the token must
+exist for the class to render.
+
 ## Rules
 
 - Use Tailwind utility classes exclusively in JSX.

scripts/scaffold.mjs

@@ -193,11 +193,12 @@ ${projectDescription}
 
 \`\`\`bash
 pnpm install
-cp .env.example .env
-pnpm test:e2e:install
+cp .env.example .env   # then fill in DATABASE_URL — see docs/agents/environment.md
 pnpm dev
 \`\`\`
 
+Running E2E tests? Install browsers first with \`pnpm test:e2e:install\`.
+
 ## For Agents
 
 Read [\`AGENTS.md\`](./AGENTS.md) before making any changes.
@@ -336,7 +337,7 @@ console.log(`
 ✅ Done! Your project "${projectName}" is ready.
 
 Next steps:
-  1. cp .env.example .env  (and fill in DATABASE_URL — see docs/agents/environment.md)
-  2. pnpm install
+  1. pnpm install
+  2. cp .env.example .env  (then fill in DATABASE_URL — see docs/agents/environment.md)
   3. pnpm dev
 `);