setup-git-repo 1.0.0

package/template/codecov.yml

@@ -0,0 +1,50 @@
+# Codecov configuration for the packages tested by .github/workflows/tests.yml.
+#
+# Statuses are informational: they annotate a pull request without ever blocking
+# it. Test Analytics — the failed-test comment and the flake dashboard — is the
+# part meant to be acted on.
+
+codecov:
+  # Publish and deploy workflows run on the default branch only, so a pull
+  # request often has no CI for Codecov to wait on before reporting.
+  require_ci_to_pass: false
+
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 1%
+        informational: true
+    patch:
+      default:
+        informational: true
+
+# One flag per package. `carryforward` means a package that skipped a run (its
+# paths were untouched) keeps its last known coverage instead of reading as a
+# drop to zero.
+#
+# Flags are created on first upload, so this block only needs entries when a
+# flag's paths differ from the default. Add one per package as the repo grows:
+#
+#   individual_flags:
+#     - name: my-package
+#       paths:
+#         - packages/my-package/
+flag_management:
+  default_rules:
+    carryforward: true
+
+comment:
+  layout: "header, diff, flags, files"
+  # Don't post on pull requests that changed nothing Codecov measures.
+  require_changes: true
+
+ignore:
+  - "**/test/**"
+  - "**/tests/**"
+  - "**/__tests__/**"
+  - "**/examples/**"
+  - "**/docs/**"
+  - "**/dist/**"
+  - "**/build/**"

package/template/docs/BADGES.md

@@ -0,0 +1,271 @@
+# Badges: what each one needs and how to set it up
+
+Every badge in the README falls into one of three groups:
+
+| Group | Setup | Badges |
+| --- | --- | --- |
+| **Zero setup** — works the moment the repo is public | none | Stars, Commit Activity, Last Commit, License, PRs Welcome, Deploy to Cloudflare, DeepWiki, tech-stack chips |
+| **Needs a workflow or service connected** | one repo secret or one app install | Tests status, Coverage, npm version, npm downloads |
+| **Needs an account and an id you paste in** | an external account | DOI, Discord, UptimeRobot, YouTube, Docs, API |
+
+`setup-git-repo` drops the badge lines for group 3 unless you pass the id, so the
+README never ships a badge pointing at `{{DOI}}`. Add them back later by copying
+the snippet from this file.
+
+Almost everything is [Shields.io](https://shields.io), whose URL shape is
+`https://img.shields.io/<type>/<args>.svg?<options>`. Common options: `label=`,
+`color=`/`colorB=`, `logo=` (any [Simple Icons](https://simpleicons.org) slug),
+`logoColor=`, `style=` (`flat`, `flat-square`, `for-the-badge`).
+
+---
+
+## Zero setup
+
+### GitHub Stars
+
+```html
+<a href="https://github.com/OWNER/REPO/stargazers"><img src="https://img.shields.io/github/stars/OWNER/REPO" alt="GitHub Stars" /></a>
+```
+
+Nothing to configure. Works on public repos only — Shields has no token for
+your private repo and renders `invalid` or `repo not found`.
+
+### Commit Activity
+
+```html
+<img src="https://img.shields.io/github/commit-activity/m/OWNER/REPO" alt="Commit Activity" />
+```
+
+`m` is commits per month; `w` and `y` also work. Add `/BRANCH` to scope it:
+`commit-activity/m/OWNER/REPO/main`.
+
+### Last Commit
+
+```html
+<img src="https://img.shields.io/github/last-commit/OWNER/REPO.svg" alt="Last Commit" />
+```
+
+Defaults to the default branch. `?display_timestamp=committer` switches from
+author date to commit date, which is what you usually mean after a rebase.
+
+### License
+
+```html
+<img src="https://img.shields.io/github/license/OWNER/REPO" alt="License" />
+```
+
+Reads GitHub's detected license, which comes from a recognized `LICENSE` file.
+A `LICENSE.md` with a custom or modified text is often detected as `Other` —
+if that bothers you, use a static badge instead:
+`https://img.shields.io/badge/license-MIT-green.svg`.
+
+### PRs Welcome
+
+A static badge; it links to GitHub's "creating a pull request" docs. Point it at
+your own `CONTRIBUTING.md` once you have one.
+
+### Deploy to Cloudflare Workers
+
+```html
+<a href="https://deploy.workers.cloudflare.com/?url=https://github.com/OWNER/REPO"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare Workers" /></a>
+```
+
+The button image is hosted by Cloudflare; no account needed to *show* it. For the
+click-through to actually work, the repo must be deployable: a `wrangler.jsonc`
+(or `wrangler.toml`) at the root, or a `workers/` directory Cloudflare can find.
+This template's Worker config lives in `apps/test-reports/`, so either move it,
+add a root config, or point the button at a subdirectory URL.
+
+### Ask DeepWiki
+
+```html
+<a href="https://deepwiki.com/OWNER/REPO"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" /></a>
+```
+
+DeepWiki indexes public repos automatically. The first visit to the link
+triggers indexing if the repo has not been seen; the badge image itself is
+static, so it renders even before indexing finishes.
+
+### Tech-stack chips
+
+Pure decoration — static Shields badges with a brand color and a Simple Icons
+slug:
+
+```html
+<img src="https://img.shields.io/badge/Turborepo-EF4444?logo=turborepo&logoColor=white" alt="Turborepo" />
+```
+
+Format is `badge/<label>-<hex color>?logo=<slug>`. A slug that isn't in Simple
+Icons renders the label with no icon and no error, so check
+[simpleicons.org](https://simpleicons.org) before assuming a typo elsewhere. A
+literal `-` in the label must be written `--`, and a space `_`.
+
+---
+
+## Needs a workflow or service connected
+
+### Workflow status (Tests)
+
+```html
+<a href="https://github.com/OWNER/REPO/actions/workflows/tests.yml"><img src="https://github.com/OWNER/REPO/actions/workflows/tests.yml/badge.svg?branch=main" alt="Tests" /></a>
+```
+
+Served by GitHub, not Shields. Three things to get right:
+
+- The path segment is the workflow **file name**, not the `name:` inside it.
+  `tests.yml` here; renaming the file breaks the badge silently (it renders
+  "no status").
+- `?branch=` is worth setting. Without it the badge shows the most recent run on
+  *any* branch, so a red feature branch turns your README red.
+- The badge shows `no status` until the workflow has run at least once on that
+  branch. Push to the branch or use "Run workflow" from the Actions tab.
+
+One badge per workflow file: add `npm-publish.yml` or `deploy-test-reports.yml`
+the same way if you want them visible.
+
+### Coverage (Codecov)
+
+```html
+<a href="https://codecov.io/gh/OWNER/REPO"><img src="https://codecov.io/gh/OWNER/REPO/graph/badge.svg" alt="Coverage" /></a>
+```
+
+Setup:
+
+1. Sign in at [codecov.io](https://codecov.io) with GitHub and add the repo.
+2. Copy the **repository upload token** and save it as the `CODECOV_TOKEN`
+   repository secret (Settings → Secrets and variables → Actions → New secret).
+   Public repos on GitHub Actions can often upload tokenless, but rate limits
+   make that unreliable in CI — set the secret.
+3. Push. `tests.yml` uploads `coverage/lcov.info` per package.
+
+Getting the token from Codecov's UI: repo page → Settings → General → Repository
+Upload Token. If the badge stays `unknown`, the upload never arrived — check the
+"Upload coverage to Codecov" step's log, not the badge.
+
+Private repos need the token in the badge URL too; Codecov's repo Settings →
+Badges page shows the exact markdown with the graph token included.
+
+`codecov.yml` in this template sets `carryforward: true` per flag, so a package
+that didn't run in a given PR keeps its last coverage instead of reading as a
+drop to 0%.
+
+### npm version and downloads
+
+```html
+<a href="https://www.npmjs.com/package/PACKAGE"><img src="https://img.shields.io/npm/v/PACKAGE.svg" alt="npm version" /></a>
+<a href="https://www.npmjs.com/package/PACKAGE"><img src="https://img.shields.io/npm/dm/PACKAGE.svg" alt="NPM Monthly Downloads" /></a>
+```
+
+`PACKAGE` is the name in that package's `package.json`, not the repo name. Both
+badges render `invalid` until the package's **first** publish — `npm-publish.yml`
+does that on the first push to the default branch. Scoped packages work with the
+scope included and URL-encoded slash: `npm/v/%40scope%2Fname`.
+
+`dm` is downloads/month; `dw` weekly, `dt` total. In a monorepo, pick the package
+users actually install — or show several, one badge each.
+
+---
+
+## Needs an account and an id you paste in
+
+### DOI (Zenodo)
+
+```html
+<a href="https://doi.org/10.5281/zenodo.NNNNNNN"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.NNNNNNN.svg" alt="DOI" /></a>
+```
+
+A DOI makes the repo citable in academic work. Setup:
+
+1. Sign in to [zenodo.org](https://zenodo.org) with GitHub.
+2. Zenodo → GitHub → flip the repo's switch **on**. This installs a webhook; it
+   only affects releases created *after* the switch.
+3. Create a GitHub Release (a tag alone is not enough — it must be a Release).
+   Zenodo archives the tarball and mints a DOI within a few minutes.
+4. Zenodo shows two DOIs. Use the **concept DOI** ("all versions"), not the
+   version-specific one, so the badge keeps pointing at the newest release.
+
+Pass it to the CLI without the `https://doi.org/` prefix: `--doi 10.5281/zenodo.NNNNNNN`.
+
+### Discord
+
+```html
+<a href="https://discord.gg/INVITE"><img src="https://img.shields.io/discord/SERVER_ID.svg?label=Chat&logo=Discord&colorB=7289da&style=flat" alt="Join Discord" /></a>
+```
+
+Two different values, and mixing them up is the usual failure:
+
+- **Server id** goes in the Shields path (it renders the online count). Get it
+  with Discord → User Settings → Advanced → Developer Mode on, then right-click
+  the server → Copy Server ID.
+- **Invite code** goes in the `href`. Create a *never-expiring* invite —
+  a default invite expires in 7 days and the badge quietly links to a dead page.
+
+The server also needs the **Widget** enabled (Server Settings → Widget → Enable
+Server Widget); without it Shields cannot read the member count and the badge
+reads `invalid`.
+
+### UptimeRobot
+
+```html
+<a href="https://stats.uptimerobot.com/PAGE_ID"><img src="https://img.shields.io/badge/Uptime-Status-brightgreen?logo=uptimerobot&logoColor=white" alt="Uptime Status" /></a>
+```
+
+As written this is a **static** badge — it always says "Status" and links to your
+public status page. Setup: [uptimerobot.com](https://uptimerobot.com) → add a
+monitor for your URL → Status Pages → create one → copy the id out of its URL.
+
+For a badge that reports the *real* number, use a monitor-specific API key
+(Monitor → Settings → API key, the `m` key) with Shields' UptimeRobot endpoints:
+
+```html
+<img src="https://img.shields.io/uptimerobot/ratio/7/MONITOR_API_KEY" alt="Uptime 7d" />
+<img src="https://img.shields.io/uptimerobot/status/MONITOR_API_KEY" alt="Up or down" />
+```
+
+That key is read-only for one monitor, which is why it is safe in a README —
+never paste your account-wide API key there.
+
+### Docs / API / YouTube links
+
+```html
+<a href="https://your.docs"><img src="https://img.shields.io/badge/Docs-blue?logo=ReadTheDocs&logoColor=white" alt="Documentation" /></a>
+<a href="https://your.api/docs"><img src="https://img.shields.io/badge/API-blue?logo=fastapi&logoColor=white" alt="API" /></a>
+<a href="https://youtu.be/VIDEO_ID"><img height="20px" src="https://img.shields.io/badge/YouTube-red?style=for-the-badge&logo=youtube&logoColor=white" alt="YouTube" /></a>
+```
+
+Static badges whose only "setup" is having somewhere to point them. They exist
+to make the top of the README a navigation bar rather than a status board — the
+logo does the work, so keep the label to one word.
+
+Note the YouTube badge is `style=for-the-badge` while its neighbors are flat.
+That is deliberate in the original layout but it renders taller; the `height`
+attribute pulls it back in line. Drop `style=for-the-badge` if you would rather
+they match.
+
+---
+
+## Layout
+
+The block is plain HTML inside `<p align="center">`, not markdown, because
+markdown image syntax cannot center or set a height. Consequences:
+
+- Keep each `<a>` on one line. A newline inside the tag is fine for HTML but
+  makes the block much harder to reorder later.
+- `<br />` between rows is what creates the grouping — GitHub collapses
+  whitespace, so blank lines do nothing.
+- GitHub's markdown renderer strips `style` attributes. Sizing has to come from
+  the `height` attribute or from Shields' own `style=` parameter.
+
+Group by meaning: identity and links on row one, health and freshness on row two,
+community on row three, stack chips last.
+
+## Verifying
+
+Badges are cached by GitHub's image proxy (camo), so a fixed badge can keep
+looking broken for a while. To check the real state, open the badge's `src` URL
+directly in a browser — that bypasses camo. Shields renders its own errors into
+the image (`invalid`, `not found`, `inaccessible`), so the image itself tells you
+which half of the URL is wrong.
+
+To force GitHub to refetch: `curl -X PURGE <the camo URL>` on the rendered image
+address, or simply wait — camo's TTL is minutes, not hours.

package/template/docs/SECRETS.md

@@ -0,0 +1,77 @@
+# Secrets and settings CI depends on
+
+Repository secrets live at **Settings → Secrets and variables → Actions → New
+repository secret**. Names are case-sensitive and must match exactly.
+
+| Secret | Used by | Required? | Where it comes from |
+| --- | --- | --- | --- |
+| `CODECOV_TOKEN` | `tests.yml` | For coverage and Test Analytics | codecov.io → your repo → Settings → General → Repository Upload Token |
+| `NPM_TOKEN` | `npm-publish.yml` | Only if you are not using trusted publishing | npmjs.com → Access Tokens → Generate → **Granular**, write access to the packages |
+| `CLOUDFLARE_API_TOKEN` | `deploy-test-reports.yml` | For the report deploy | dash.cloudflare.com → My Profile → API Tokens → "Edit Cloudflare Workers" template |
+| `CLOUDFLARE_ACCOUNT_ID` | `deploy-test-reports.yml` | For the report deploy | Cloudflare dashboard → Workers & Pages → the id in the right sidebar (or the URL) |
+| `GIT_TOKEN` | both auto-merge workflows | For auto-merge | github.com → Settings → Developer settings → Personal access tokens |
+
+`GITHUB_TOKEN` is provided automatically — never create a secret with that name;
+GitHub rejects it.
+
+## Which workflows you can run without any secrets
+
+`tests.yml` still runs the suites without `CODECOV_TOKEN`; only the two upload
+steps fail, and both are `fail_ci_if_error: false`, so the job stays green while
+you set the token up. Everything else needs its secret to do anything at all.
+
+## GIT_TOKEN scopes
+
+A fine-grained personal access token, scoped to this repository, with:
+
+- **Contents**: Read and write
+- **Pull requests**: Read and write
+
+A classic token needs `repo` (and `workflow` if the merged PRs ever touch
+`.github/workflows`).
+
+**Why not `GITHUB_TOKEN`?** Merges made with `GITHUB_TOKEN` do not trigger
+further workflows — an [intentional loop guard][loop]. With it, a PR merged by
+the auto-merge workflow would never fire `npm-publish.yml` or
+`deploy-test-reports.yml` on the default branch. A PAT is a real user, so its
+pushes trigger workflows normally.
+
+The tradeoff: that token carries whatever access its owner has. Prefer a
+fine-grained token limited to this one repository, and set an expiry you will
+actually notice.
+
+[loop]: https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow
+
+## npm: trusted publishing instead of a token
+
+Preferred, because there is nothing to rotate. Per package, on npmjs.com:
+
+1. Go to `npmjs.com/package/<name>/access`.
+2. Under **Trusted publisher**, add: GitHub Actions, this `owner/repo`, workflow
+   file `npm-publish.yml`.
+3. Leave `NPM_TOKEN` **unset** in the repo. The workflow detects the absence and
+   authenticates via OIDC — that is what `permissions: id-token: write` is for.
+
+A package's *first* publish cannot use trusted publishing (there is no package
+page yet to configure). Publish once by hand — `npm publish --access public` —
+then set the trusted publisher and let CI take over.
+
+## Repository settings, not secrets
+
+| Setting | Where | Needed for |
+| --- | --- | --- |
+| Allow auto-merge | Settings → General → Pull Requests | `gh pr merge --auto` in both auto-merge workflows |
+| Branch protection with ≥1 required check | Settings → Branches | Makes `--auto` actually wait for CI instead of merging immediately |
+| Read and write permissions for Actions | Settings → Actions → General → Workflow permissions | The version-bump commit in `npm-publish.yml` |
+| Allow GitHub Actions to create and approve pull requests | Settings → Actions → General | `gh pr create` in `auto-merge-and-create-prs.yml` |
+
+## Rotation
+
+- `NPM_TOKEN`: granular tokens expire after **90 days maximum**. The workflow's
+  preflight step turns an expired token into a clear error instead of a
+  late `E404`, but it still stops the release. Trusted publishing avoids this
+  entirely.
+- `GIT_TOKEN`: set an expiry and a calendar reminder. An expired PAT makes the
+  auto-merge workflows fail with `gh: Bad credentials`.
+- `CLOUDFLARE_API_TOKEN`: does not expire unless you set a TTL, but scope it to
+  Workers Scripts:Edit on one account rather than using a global API key.

package/template/docs/WORKFLOWS.md

@@ -0,0 +1,205 @@
+# The workflows
+
+Five files in `.github/workflows`, plus one helper script. Each is described
+here by what it does, what it needs, and how it fails — the failure modes are
+the part that costs hours if you meet them cold.
+
+| Workflow | Trigger | Needs |
+| --- | --- | --- |
+| `tests.yml` | PR, push to default branch | `CODECOV_TOKEN` |
+| `npm-publish.yml` | push to default branch | `NPM_TOKEN` *or* trusted publishing |
+| `deploy-test-reports.yml` | push to default branch | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` |
+| `auto-merge-claude.yml` | PR opened/updated | `GIT_TOKEN`, "Allow auto-merge" |
+| `auto-merge-and-create-prs.yml` | every 12h, manual | `GIT_TOKEN` |
+
+---
+
+## tests.yml
+
+Discovers every workspace package with a `test:ci` script, runs each as its own
+matrix job, and uploads results to Codecov Test Analytics and coverage to
+Codecov.
+
+**Why the matrix is discovered rather than listed.** A hand-maintained matrix
+goes stale the first time someone adds a package and forgets to edit the
+workflow — the package silently has no CI. A `discover` job emits the list as
+JSON; the `test` job consumes it through `fromJSON`. GitHub cannot compute a
+matrix inside the job that uses it, which is why it is two jobs.
+
+**What your package must produce.** Relative to the package directory:
+
+```
+junit.xml            test results — what Test Analytics ingests
+coverage/lcov.info   coverage — uploaded when the runner can produce it
+```
+
+For Vitest:
+
+```json
+"test:ci": "vitest run --reporter=junit --outputFile=junit.xml --coverage"
+```
+
+**Details that matter:**
+
+- `fail-fast: false` — one package's red suite must not cancel the other jobs
+  before they upload. Their results are the ones you need to compare against.
+- `if: ${{ !cancelled() }}` on both upload steps, not `if: success()`. Without
+  it, the upload is skipped on exactly the runs whose results matter most.
+- `bun install --ignore-scripts` — postinstall hooks in a workspace tend to want
+  env vars CI does not have (database URLs, Tauri toolchains, doc generators),
+  and none of them affect tests.
+- Tests run through `bunx turbo run test:ci --filter=...` rather than `cd` +
+  `bun test`, so a package that imports a sibling through its built `dist` gets
+  that sibling built first.
+
+**Failure modes:**
+
+| Symptom | Cause → fix |
+| --- | --- |
+| A package you added never appears as a job | It has no `test:ci` script, or it lives outside `packages/`, `apps/` |
+| `Error: Unable to process file command 'output'` in `discover` | A package name contains a newline or the JSON exceeded the 1MB output cap |
+| Codecov shows the run but no coverage | The runner wrote no `lcov.info` — `--coverage` missing, or a provider that writes nothing on your Node version |
+| Coverage drops to 0% for an untouched package | `carryforward` is off for that flag in `codecov.yml` |
+
+## npm-publish.yml
+
+Publishes every non-private workspace package **whose content changed**, then
+commits the version bumps back.
+
+**The rule it exists to enforce:** nobody has to remember a version number. Each
+package is packed with `npm pack --dry-run --json` and its integrity hash
+compared against `npm view <pkg>@<version> dist.integrity`. npm tarballs are
+reproducible (mtimes are normalized), so identical hashes mean nothing to
+release; a different hash means bump the patch and publish.
+
+**Credentials — two supported paths:**
+
+1. **Trusted publishing (OIDC), preferred.** No secret at all. npm ≥ 11.5.1
+   trades the job's `id-token` for a short-lived publish token. Each package
+   must name this repo + workflow as its trusted publisher at
+   `npmjs.com/package/<name>/access`. Nothing to rotate.
+2. **`NPM_TOKEN` secret.** A granular access token with write access. These
+   expire after at most 90 days; classic automation tokens no longer work for
+   direct publishing.
+
+Setting the secret picks (2); leaving it unset picks (1).
+
+**Why the credential is checked in its own step, before anything is built.** npm
+answers an *unauthorized* PUT with `E404 ... could not be found or you do not
+have permission to access it` — which reads like a missing package, not a
+permissions problem. Without the preflight you pay a full build for every
+package before the first one hits it, and each failed attempt still signs a
+provenance statement into the public sigstore transparency log.
+
+**Details that matter:**
+
+- `set +e` in the publish loop. GitHub runs `run:` steps with `bash -e -o
+  pipefail`, so *not* writing `set -e` does not disable errexit — the first
+  failing package would kill the step and leave every later package unevaluated.
+  Outcomes travel through `$rc`; the step still exits non-zero at the end.
+- Exit 43 means "npm rejected the credential". The loop stops attempting further
+  packages: they would all fail the same way, after another build and another
+  provenance signature each.
+- `workspace:*` dependencies are rewritten to real semver ranges before packing.
+  npm keeps the literal protocol in the tarball, and consumers cannot resolve it.
+  Only the `version` field of that edit is committed back.
+- A local version *behind* the registry is synced forward first, otherwise the
+  publish fails with "Cannot implicitly apply the latest tag".
+- `E409 cannot publish over previously staged version` is retried at the next
+  free version, up to five times. `latest` lags versions an interrupted publish
+  reserved; `.github/scripts/next-free-version.mjs` reads the full version list
+  *and* the release timeline, which is where those numbers appear.
+- The final step rewrites only the `version` field back into each
+  `package.json`, by regex rather than by re-serializing the parsed object, so
+  the file keeps its own formatting. It matches `"version"\s*:\s*"..."` rather
+  than a literal `"version": "x"`, and fails the step if the replace found
+  nothing — a package.json written without the space after the colon would
+  otherwise silently lose the bump while the log claimed to keep it.
+- The bump commit ends in `[skip ci]` so it does not retrigger the workflow.
+- A no-op `husky` is put on PATH. Some published dependencies ship
+  `prepare: "husky install"`; when npm reconciles bun's linked `node_modules` it
+  runs that hook and dies with exit 127 — and `--ignore-scripts` does **not**
+  suppress it for bun-linked packages.
+
+**Failure modes:**
+
+| Symptom | Cause → fix |
+| --- | --- |
+| `E404` on publish for a package that exists | The credential cannot write to it. Read the error annotation the workflow emits |
+| `EUNSUPPORTEDPROTOCOL workspace:*` | An `npm` command ran without `--no-workspaces` against bun's symlinks |
+| `vite: not found` during build | Someone replaced `bun install` with `npm install`; npm cannot install a bun workspace |
+| Versions bump on every run | The build is not reproducible — a timestamp or absolute path is landing in `dist` |
+| Nothing publishes, no errors | Every package is `private: true`, or content genuinely did not change |
+
+## deploy-test-reports.yml
+
+Runs the whole suite with Vitest's HTML reporter and deploys the result to
+Cloudflare Workers, so the report has a permanent URL.
+
+**The two non-obvious parts:**
+
+- `continue-on-error: true` on the test step. A red suite must still publish its
+  report — that report is how you see what went red.
+- The "Ensure a report exists to deploy" step. What a red suite must *not* do is
+  leave `dist` missing: `wrangler deploy` treats an absent `assets.directory` as
+  a hard error, so the run would end on a config error instead of on the test
+  signal. A placeholder page is written instead.
+
+**The reporter gotcha.** Vitest's HTML reporter ignores `outputFile` and writes
+`<outputDir>/index.html` plus a UI bundle, where `outputDir` is a *reporter
+option* defaulting to `.vitest`. A reporter named on the command line
+(`--reporter=html`) is constructed without options and silently keeps that
+default — so the deploy finds nothing. `vitest.config.ts` declares the reporter
+and its destination together, keyed off `VITEST_HTML_REPORT_DIR`; `test:report`
+sets it.
+
+## auto-merge-claude.yml
+
+Enables auto-merge on PRs opened by trusted agents and maintainers.
+
+`gh pr merge --auto` is the safe path: GitHub holds the merge until branch
+protection is satisfied. It works **only** when both are true:
+
+- "Allow auto-merge" is on in Settings → General → Pull Requests, and
+- the base branch has protection with at least one **required** status check.
+
+Without both, GitHub rejects `--auto` and the fallback merges immediately —
+without waiting for CI. That is why the actor allowlist in the `if:` matters,
+and why you should turn on branch protection before turning on this workflow.
+
+It uses `GIT_TOKEN` (a PAT) rather than `GITHUB_TOKEN` deliberately: merges made
+with `GITHUB_TOKEN` do not trigger further workflows, so the publish and deploy
+runs on the default branch would never fire.
+
+Branches named `production`, `prod`, `staging` or `develop` are merged without
+`--delete-branch`.
+
+## auto-merge-and-create-prs.yml
+
+A twice-daily sweep that merges PRs already clean/approved/green, and opens a PR
+for any pushed branch that never got one. Both halves are idempotent, so a
+delayed or duplicated run is harmless — and scheduled workflows **are** delayed,
+sometimes by hours, during periods of high Actions load. Never rely on the exact
+minute.
+
+A *merged* PR counts when checking whether a branch already has one: reopening a
+PR for a branch whose work already landed creates an empty, permanently open PR.
+
+The second step deliberately skips `actions/checkout` — it only needs refs, so
+it fetches them into an empty workspace rather than paying for a full checkout.
+
+---
+
+## Adapting these to another repo
+
+- **Different package manager.** Replace `oven-sh/setup-bun@v2` with
+  `actions/setup-node@v4` and the `bun install --ignore-scripts` /
+  `bunx turbo` lines with `npm ci --ignore-scripts` / `npx turbo`. The publish
+  loop's `--no-workspaces` flags exist for bun's symlinks and are harmless
+  otherwise.
+- **Not a monorepo.** `tests.yml`'s discovery finds nothing; either add a
+  `packages/` layout, or replace the matrix with a single job that runs
+  `npm run test:ci` at the root.
+- **`main` instead of `master`.** Every `branches:` filter in this template is
+  written by `setup-git-repo` from your repo's actual default branch. If you
+  rename the branch later, grep the workflows for the old name.

package/template/gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+build/
+.next/
+.turbo/
+coverage/
+junit.xml
+*.tsbuildinfo
+.env
+.env.local
+.DS_Store

package/template/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{REPO}}",
+  "version": "0.0.0",
+  "private": true,
+  "description": "{{DESCRIPTION}}",
+  "type": "module",
+  "packageManager": "bun@1.3.11",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/{{OWNER}}/{{REPO}}"
+  },
+  "workspaces": [
+    "packages/*",
+    "apps/*"
+  ],
+  "scripts": {
+    "build": "turbo run build",
+    "dev": "turbo run dev",
+    "lint": "turbo run lint",
+    "typecheck": "turbo run typecheck",
+    "test": "turbo run test",
+    "test:ci": "turbo run test:ci",
+    "test:report": "VITEST_HTML_REPORT_DIR=apps/test-reports/dist vitest run",
+    "test:watch": "turbo run test:watch",
+    "coverage": "turbo run coverage",
+    "clean": "turbo run clean && rm -rf .turbo node_modules"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.0",
+    "turbo": "^2.10.12",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/template/packages/README.md

@@ -0,0 +1 @@
+Placeholder — publishable libraries live here, one directory per package.