docs: lead onboarding with "Use this template"

Quickstart, monorepo-layout, deployment, 404, landing hero, root README,
AGENTS, and the bootstrap compose.env.tftpl comment now point users at
GitHub's "Use this template" button instead of fork-style clone language.
This is a template repository; forks create lineage we don't want.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: agjs

AGENTS.md

@@ -7,7 +7,7 @@ Single repository: `apps/api`, `apps/ui`, `apps/docs`, `infra/compose`, `infra/b
 ```bash
 bun run regen           # cross-app generators (ACL, OpenAPI, lint-meta, docs JSON)
 bun run check           # drift checks before push
-bun run rename:project  # one-shot fork rebrand (boringstack → your project)
+bun run rename:project  # one-shot rebrand after Use this template (boringstack → your project)
 ./setup.sh --up         # boot local dev stack
 ./scripts/audit-repo-settings.sh # diff GitHub repo settings vs .github/desired-repo-settings.json
 ```

README.md

@@ -21,7 +21,7 @@
 </p>
 
 <p align="center">
-  <strong>Production-ready from the first fork.</strong><br />
+  <strong>Production-ready from the first template clone.</strong><br />
   One monorepo for the full stack.
 </p>
 

apps/docs/src/components/landing/HeroSection.tsx

@@ -17,11 +17,10 @@ export function HeroSection() {
           className="mt-[0.55rem] max-w-[38rem] text-balance text-[2.45rem] leading-[1.08] tracking-[-0.02em] text-[var(--bs-text)] min-[421px]:text-[2.65rem] min-[641px]:text-[3.25rem] lg:text-[3.75rem]"
           id="bs-hero-title"
         >
-          Production-ready from the first fork.
+          Production-ready from the first template clone.
         </h1>
         <p className="mt-[1.25rem] max-w-[34rem] text-pretty text-base leading-[1.55] text-[var(--bs-muted-strong)] min-[641px]:mt-[1.15rem] min-[641px]:text-[1.05rem]">
-          GitHub templates for the full stack. Fork the org, boot with compose/dev.sh, deploy
-          on Compose.
+          A GitHub template repository for the full stack. Click <b>Use this template</b>, boot with compose/dev.sh, deploy on Compose.
         </p>
 
         <div aria-label="Primary actions" className="mt-9 grid w-full max-w-full gap-3 min-[641px]:mt-[2.1rem] min-[641px]:w-[min(100%,30rem)] min-[641px]:gap-[0.65rem]">

apps/docs/src/content/docs/404.mdx

@@ -34,7 +34,7 @@ import DocCallout from "../../components/DocCallout";
 
 ## Popular starting points
 
-- **[Quickstart](/quickstart/)**: fork the templates, boot Compose, sign in.
+- **[Quickstart](/quickstart/)**: use the template, boot Compose, sign in.
 - **[Why BoringStack](/architecture/why-boringstack/)**: the thesis, the fit check, and what's in the box.
 - **[Stack at a glance](/architecture/stack/)**: runtime, libraries, and tools, one place.
 - **[Commands cheatsheet](/reference/commands/)**: every command you'll run on a normal day.

apps/docs/src/content/docs/architecture/monorepo-layout.mdx

@@ -13,13 +13,13 @@ import FaqItem from "../../../components/FaqItem.tsx";
 <PageIntro
   eyebrow="Repository contract"
   actions={[
-    { label: "Quickstart", href: "/quickstart/#step-1-clone-the-monorepo" },
+    { label: "Quickstart", href: "/quickstart/#step-1-use-this-template" },
     { label: "Separation of concerns", href: "/architecture/separation-of-concerns/" },
   ]}
   facts={[
     { value: "apps/", label: "api · ui · docs" },
     { value: "infra/", label: "compose · bootstrap" },
-    { value: "1", label: "git clone" },
+    { value: "1", label: "template clone" },
   ]}
 >
   BoringStack ships as a single monorepo. API, UI, docs site, and Compose infra
@@ -32,7 +32,7 @@ The runtime is composed from `apps/api`, `apps/ui`, and `infra/compose`. Optiona
 <DocFileTree
   root="boringstack/"
   title="Monorepo layout"
-  caption="one clone, explicit join points"
+  caption="one template clone, explicit join points"
   nodes={[
     { name: "apps/api/", detail: "Bun + Elysia + Drizzle API" },
     { name: "apps/ui/", detail: "Vite + React SPA" },
@@ -86,10 +86,12 @@ Each app keeps its own `package.json`, lockfile, and lint config. CI workflows l
   ]}
 />
 
-<Aside type="note" title="Forking">
-  Fork the whole monorepo on GitHub. API, UI, docs, Compose, and bootstrap
-  infrastructure stay together in one tree. On a VPS, clone the monorepo and
-  run Compose from `infra/compose/compose`.
+<Aside type="note" title="Use this template">
+  The monorepo is a GitHub template. Click **Use this template** on
+  [`boringstack-xyz/boringstack`](https://github.com/boringstack-xyz/boringstack)
+  to create a fresh repo under your org — API, UI, docs, Compose, and bootstrap
+  infrastructure all in one tree, no fork relationship. On a VPS, clone your repo
+  and run Compose from `infra/compose/compose`.
 </Aside>
 
 ## What lives where

apps/docs/src/content/docs/quickstart.mdx

@@ -1,6 +1,6 @@
 ---
 title: Quickstart
-description: "Clone the BoringStack monorepo, run setup.sh, sign in at localhost:3001."
+description: "Use the BoringStack template on GitHub, clone your new repo, run setup.sh, sign in at localhost:3001."
 ---
 
 import CommandRun from "../../components/docs-kit/CommandRun";
@@ -18,13 +18,13 @@ import FaqItem from "../../components/FaqItem.tsx";
     { label: "What's running", href: "#whats-running" },
   ]}
   facts={[
-    { value: "1", label: "git clone" },
+    { value: "1", label: "click Use this template" },
     { value: "Docker", label: "only prerequisite" },
     { value: "0", label: "local Node or Bun installs" },
   ]}
 >
-  Clone the [BoringStack monorepo](https://github.com/boringstack-xyz/boringstack),
-  run `./setup.sh --up`, and Compose starts Postgres, Valkey, api-dev (migrations +
+  Click **Use this template** on the [BoringStack monorepo](https://github.com/boringstack-xyz/boringstack),
+  clone your new repo, run `./setup.sh --up`, and Compose starts Postgres, Valkey, api-dev (migrations +
   OpenAPI), and ui-dev (Vite on :3001 with generated client). Optional overlays:
   Mailpit, Bull Board, observability, GlitchTip.
 </PageIntro>
@@ -46,8 +46,8 @@ import FaqItem from "../../components/FaqItem.tsx";
   items={[
     {
       label: "01",
-      title: "Clone the monorepo",
-      body: "One repo contains apps/api, apps/ui, infra/compose, and apps/docs.",
+      title: "Use this template",
+      body: "Click \"Use this template\" on GitHub, then clone the new repo created under your org.",
     },
     {
       label: "02",
@@ -75,14 +75,18 @@ You now have Postgres, Valkey, the API, and the UI running locally with hot relo
 - About 4 GB of free RAM.
 - No local Node or Bun needed for the default path; everything runs in containers.
 
-## Step 1. Clone the monorepo
+## Step 1. Use this template
+
+The BoringStack monorepo is a [GitHub template repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template). On the [`boringstack-xyz/boringstack`](https://github.com/boringstack-xyz/boringstack) page, click **Use this template → Create a new repository** to make a fresh copy under your org with full ownership and no fork relationship.
+
+Then clone the repo you just created:
 
 ```bash
-git clone https://github.com/boringstack-xyz/boringstack.git
-cd boringstack
+git clone https://github.com/<your-org>/<your-repo>.git
+cd <your-repo>
 ```
 
-Fork the monorepo on GitHub if you want your own copy under your org. API, UI, docs, Compose, and bootstrap infrastructure all live in this one tree.
+API, UI, docs, Compose, and bootstrap infrastructure all live in this one tree. Run `bun run rename:project` from the root any time to rebrand the BoringStack identifiers across the codebase.
 
 <DocFileTree
   root="boringstack/"

apps/docs/src/content/docs/topics/deployment.mdx

@@ -1,6 +1,6 @@
 ---
 title: Deployment
-description: Boring deployment. Single-host VPS, Docker, one monorepo fork, GHCR images, one prod profile. HTTPS via ACME, perimeter locked by Cloudflare.
+description: Boring deployment. Single-host VPS, Docker, one repo created from the GitHub template, GHCR images, one prod profile. HTTPS via ACME, perimeter locked by Cloudflare.
 ---
 
 import { Aside } from "@astrojs/starlight/components";
@@ -23,8 +23,9 @@ import FaqItem from "../../../components/FaqItem.tsx";
   ]}
 >
   BoringStack runs on a VPS you control: Docker Compose, GHCR images, Traefik
-  TLS, and Cloudflare at the edge. Fork the monorepo, fill compose/.env, then
-  boot the production profile manually or let OpenTofu do first provisioning.
+  TLS, and Cloudflare at the edge. Use the GitHub template to create your repo,
+  fill compose/.env, then boot the production profile manually or let OpenTofu
+  do first provisioning.
 </PageIntro>
 
 ## The mental model
@@ -81,15 +82,15 @@ Push to `main` with changes under `apps/api` or `apps/ui`. Path-filtered release
 
 ## First-time wiring
 
-Three things need configuring before the first deploy. The release workflows handle everything else from your monorepo fork URL.
+Three things need configuring before the first deploy. The release workflows handle everything else from your repo URL.
 
 ### 1. Publish images to GHCR
 
-The API and UI release workflows run on push to `main` when their app paths change. They use `${{ github.event.repository.name }}` plus an app suffix, so a fork named `acme-stack` publishes `ghcr.io/<your-owner>/acme-stack-api:latest` and `ghcr.io/<your-owner>/acme-stack-ui:latest` automatically. The default `GITHUB_TOKEN` has `packages: write` via the workflow grant, so the first push from a freshly-forked repo works without secret setup.
+The API and UI release workflows run on push to `main` when their app paths change. They use `${{ github.event.repository.name }}` plus an app suffix, so a repo named `acme-stack` publishes `ghcr.io/<your-owner>/acme-stack-api:latest` and `ghcr.io/<your-owner>/acme-stack-ui:latest` automatically. The default `GITHUB_TOKEN` has `packages: write` via the workflow grant, so the first push from a fresh template clone works without secret setup.
 
 After the first publish, **make the GHCR package public** so the VPS can pull without credentials:
 
-1. Go to the fork's Packages tab and open both containers: `<repo>-api` and `<repo>-ui`.
+1. Go to your repo's Packages tab and open both containers: `<repo>-api` and `<repo>-ui`.
 2. Package settings → Change visibility → Public.
 
 Without this, downstream consumers (your VPS) need a pull credential.
@@ -122,7 +123,7 @@ The module derives `IMAGE_OWNER`, `API_IMAGE_NAME=<repo>-api`, and `UI_IMAGE_NAM
 
 Use this once, after Quickstart and before the first production boot:
 
-- [ ] BoringStack monorepo forked under your org/user.
+- [ ] Repo created from the BoringStack template (**Use this template** on [`boringstack-xyz/boringstack`](https://github.com/boringstack-xyz/boringstack)) under your org/user.
 - [ ] First API and UI images published to GHCR (push to `main`, then watch each Actions tab).
 - [ ] GHCR packages set to **Public**, or the VPS has a pull credential.
 - [ ] `compose/.env` has `IMAGE_OWNER` and any renamed `API_IMAGE_NAME` / `UI_IMAGE_NAME`.
@@ -132,7 +133,7 @@ Use this once, after Quickstart and before the first production boot:
 - [ ] [Firewall & TLS](/runbooks/firewall-and-tls/) verified: Cloudflare can reach the origin, direct requests cannot.
 - [ ] [Backups](/runbooks/backups/) configured and at least one restore drill run.
 - [ ] [Cloudflare Email setup](/runbooks/cloudflare-email-setup/) completed if Cloudflare is your outbound mail provider.
-- [ ] Optional OpenTofu path: `terraform.tfvars` has fork URLs, real `domain`, and production secrets.
+- [ ] Optional OpenTofu path: `terraform.tfvars` has your repo URL, real `domain`, and production secrets.
 
 ## First-time deploy
 
@@ -141,7 +142,7 @@ The preferred path is [Provisioning with OpenTofu](/topics/provisioning-with-tof
 Manual path if you'd rather:
 
 1. Provision a Ubuntu VPS with Docker installed.
-2. Clone your monorepo fork onto the VPS.
+2. Clone the repo you created from the template onto the VPS.
 3. Write `compose/.env` with `PUBLIC_UI_HOST`, `ACME_EMAIL`, `IMAGE_OWNER`, and the rest from `.env.example`.
 4. `STACK=prod ./scripts/compose-up.sh pull && STACK=prod ./scripts/compose-up.sh up -d`.
 5. Run the [Firewall & TLS runbook](/runbooks/firewall-and-tls/) to verify Cloudflare-only ingress.

infra/bootstrap/modules/bootstrap/templates/compose.env.tftpl

@@ -8,8 +8,8 @@ STACK=${stack}
 PUBLIC_UI_HOST=${public_ui_host}
 ACME_EMAIL=${acme_email}
 
-# GHCR coordinates derived from monorepo_repo by tofu. A fork + rename flow
-# needs no manual image-name override here.
+# GHCR coordinates derived from monorepo_repo by tofu. A "Use this template" +
+# rename flow needs no manual image-name override here.
 IMAGE_OWNER=${image_owner}
 API_IMAGE_NAME=${api_image_name}
 UI_IMAGE_NAME=${ui_image_name}