getaura 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "getaura",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Aura helps you and your coding agent follow best practices while you vibe code.",
+  "type": "module",
+  "bin": {
+    "aura": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JohnFazio1/aura.git"
+  },
+  "keywords": [
+    "vibe coding",
+    "claude code",
+    "codex",
+    "cursor",
+    "pi",
+    "best practices",
+    "security",
+    "cli"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p .",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "commander": "^15.0.0",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@getaura/shared": "workspace:*",
+    "@types/node": "^26.6.5",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3",
+    "zod": "^4.6.5"
+  }
+}

package/templates/README.md

@@ -0,0 +1,94 @@
+# Aura templates
+
+Files the Aura CLI copies into a user's repository, usually through a pull request. Each file is plain text with `{{name}}` placeholders that the CLI fills in.
+
+## Placeholder rules
+
+- The CLI replaces a placeholder only when its name is in the list below. Use a regex like `/\{\{([a-z_]+)\}\}/g` and leave any match whose name isn't known untouched.
+- This keeps GitHub Actions expressions such as `${{ github.base_ref }}` and `${{ secrets.AURA_PILOT_KEY }}` intact. Those always have a space after `{{` and contain dots, so they never match, but the known-names rule is what guarantees it.
+- A known placeholder with no value is replaced with an empty string.
+- Values are inserted as-is (no escaping). List values are complete markdown bullet lists.
+- Skills (`skills/`) and guides (`guides/`) contain no placeholders and are copied verbatim.
+
+## Placeholders
+
+| Name | Meaning | Example |
+| --- | --- | --- |
+| `{{product_name}}` | Product name from the brief | `Tidy Invoices` |
+| `{{product_summary}}` | 2–3 sentences from the brief | `Tidy Invoices helps freelancers…` |
+| `{{stack_list}}` | Markdown bullet list of the detected stack | `- Next.js 16 (App Router)` |
+| `{{package_manager}}` | `npm`, `pnpm`, `yarn` or `bun` | `pnpm` |
+| `{{run}}` | Prefix to run a package.json script. Must be `bun run` for Bun (`bun test` runs Bun's own test runner, not the script) | `npm run`, `pnpm`, `yarn`, `bun run` |
+| `{{install_cmd}}` | Clean, lockfile-respecting install | `npm ci`, `pnpm install --frozen-lockfile`, `yarn install --immutable` (Berry) or `yarn install --frozen-lockfile` (v1), `bun install --frozen-lockfile` |
+| `{{commands_list}}` | Markdown bullet list of dev, test, lint and build commands | ``- `pnpm dev`: start the dev server`` |
+| `{{skills_list}}` | Markdown bullet list of installed skills, one line each | ``- `writing-tests`: add tests for every new feature`` |
+| `{{skills_dir}}` | Where skills are installed | `.claude/skills` or `.agents/skills` |
+| `{{node_version}}` | Node.js major version for CI | `22` |
+| `{{env_vars_list}}` | Markdown bullet list of env vars with a short description, never values | ``- `STRIPE_SECRET_KEY`: Stripe API key (server only)`` |
+| `{{date}}` | Date of generation, ISO format | `2026-10-09` |
+| `{{aura_version}}` | Aura CLI version | `0.1.0` |
+| `{{setup_node_cache}}` | `cache` value for actions/setup-node: the package manager for npm, pnpm and yarn; empty for Bun (setup-node can't cache Bun) | `pnpm` |
+| `{{dependabot_ecosystem}}` | Dependabot ecosystem: `bun` for Bun projects, `npm` for npm, pnpm and yarn | `npm` |
+| `{{src_alias_path}}` | Folder the `@/` import alias points to, relative to the project root | `.` or `src` |
+| `{{details}}` | Generated markdown for a PR body (files deleted, packages upgraded, skills installed, changes bundled). Empty string when there's nothing to list | `- Deleted \`lib/old-utils.ts\`` |
+
+## Files
+
+### Skills (`skills/<name>/SKILL.md`)
+
+Agent Skills format: YAML frontmatter with `name` (matches the folder) and `description` (when to use it), then instructions. Installed into `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex, Cursor, Pi).
+
+| Skill | Use |
+| --- | --- |
+| `aura` | Running Aura, reading its JSON, explaining findings, completing task files |
+| `writing-tests` | Vitest unit tests, route handlers, server actions, Playwright |
+| `secure-api-routes` | Auth, ownership checks, zod validation, webhooks, rate limits, `aura-ignore: public` |
+| `database-migrations` | Supabase migrations, row level security, indexes, policy tests |
+| `secrets-and-env` | `process.env`, `NEXT_PUBLIC_` rules, `.env.example`, leaks |
+| `error-handling` | Error, loading, empty and not-found states; safe logging |
+| `docs-and-readme` | Keeping README, `docs/index.md` and `.aura/brief.md` current |
+| `folder-structure` | Target layout for Next.js App Router and Supabase |
+| `pre-launch-checklist` | Checks before going live |
+
+### Agent rules
+
+- `rules/agent-rules.md`: body written into `CLAUDE.md`, `AGENTS.md` or `.cursor/rules/aura.mdc`. The CLI wraps it in `<!-- aura:start -->` / `<!-- aura:end -->` and adds the `.mdc` frontmatter for Cursor. Uses `##` headings so it fits inside an existing file.
+
+### Docs and README
+
+- `docs/index.md`: `docs/index.md` in the user's repo, the first file agents read.
+- `readme/README.md`: `README.md` for the `add-readme` action.
+
+### GitHub (`github/`)
+
+- `github/workflows/ci.yml` → `.github/workflows/ci.yml` (`add-ci`). Lint, test, build, typecheck; skips missing scripts. Sets up pnpm or Bun when their lockfile exists. For pnpm without a `packageManager` field in package.json it installs pnpm 10.
+- `github/workflows/aura.yml` → `.github/workflows/aura.yml` (`add-aura-workflow`). PR scan with sticky comment; fails when the score drops.
+- `github/workflows/aura-weekly.yml` → `.github/workflows/aura-weekly.yml` (`add-aura-workflow`). Monday 13:00 UTC summary issue.
+- `github/dependabot.yml` → `.github/dependabot.yml` (`enable-dependency-updates`).
+
+### Configs (`configs/`)
+
+| File | Destination | Action |
+| --- | --- | --- |
+| `eslint.config.mjs` | `eslint.config.mjs` (needs `eslint` 9+ and `eslint-config-next` 16+) | `add-linting` |
+| `prettierrc.json` | `.prettierrc.json` | `add-linting` |
+| `prettierignore` | `.prettierignore` | `add-linting` |
+| `vitest.config.ts` | `vitest.config.ts` | `setup-testing` |
+| `example.test.ts` | `lib/example.test.ts` or `src/lib/example.test.ts` | `setup-testing` |
+| `husky-pre-commit` | `.husky/pre-commit` (Husky 9; make it executable) | `add-pre-commit` |
+| `security-headers.md` | Not copied. Snippet the CLI or agent merges into `next.config` | `add-security-headers` |
+| `env-example-header.txt` | Top of `.env.example` | `add-env-example` |
+
+### Guides (`guides/<topic>.md`)
+
+Printed by `aura guide <topic>`. Frontmatter: `title`, `summary` (one sentence), `services` (array). Body: numbered steps and a "Check it worked" section.
+
+Topics: `rotate-stripe-key`, `rotate-supabase-key`, `rotate-openai-key`, `rotate-anthropic-key`, `rotate-github-token`, `rotate-aws-key`, `rotate-google-key`, `rotate-vercel-key`, `rotate-resend-key`, `rotate-sendgrid-key`, `rotate-slack-key`, `rotate-database-key`, `rotate-generic-key`, `github-security`, `transfer-ownership`, `install-github-cli`, `add-aura-key-to-github`.
+
+Mapping from secret service ids to guides: `github` → `rotate-github-token`; `database` → `rotate-database-key`; services without their own guide (`twilio`, `aura`, `generic`, anything new) → `rotate-generic-key`; every other service → `rotate-<service>-key`.
+
+### PR bodies (`pr/<action>.md`)
+
+One per PR action id: `add-brief`, `add-agent-rules`, `install-skills`, `token-efficiency`, `add-ci`, `setup-testing`, `add-env-example`, `add-linting`, `add-pre-commit`, `add-readme`, `enable-dependency-updates`, `fix-vulnerable-deps`, `add-security-headers`, `remove-dead-files`, `move-misplaced-files`, `add-aura-workflow`, `foundation`.
+
+Sections: "What this does", "Why it matters", "What to check before merging", then the footer `Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}`. The PR title is set by the CLI. `{{details}}` appears in `install-skills`, `token-efficiency`, `setup-testing`, `add-env-example`, `fix-vulnerable-deps`, `remove-dead-files`, `move-misplaced-files` and `foundation`.

package/templates/configs/env-example-header.txt

@@ -0,0 +1,6 @@
+# Environment variables for this app.
+# Copy this file to .env.local and fill in the values. Never commit .env.local.
+# Each variable has a comment saying what it's for and where to get it.
+# Variables starting with NEXT_PUBLIC_ are visible in the browser: never put secrets in them.
+# When you add a variable, add it here (name and comment, no value) and in Vercel
+# (Project → Settings → Environment Variables).

package/templates/configs/eslint.config.mjs

@@ -0,0 +1,12 @@
+// ESLint flat config for Next.js (eslint-config-next 16 or later, ESLint 9 or later).
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([".next/**", "out/**", "build/**", "coverage/**", "next-env.d.ts"]),
+]);
+
+export default eslintConfig;

package/templates/configs/example.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+
+// A small example to show the shape of a test. Replace it with tests for your own code,
+// for example by importing a function from "@/lib/..." instead of defining one here.
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+describe("slugify", () => {
+  it("turns a title into a URL-friendly slug", () => {
+    expect(slugify("Hello, World!")).toBe("hello-world");
+  });
+
+  it("returns an empty string for text with no letters or numbers", () => {
+    expect(slugify("  !!  ")).toBe("");
+  });
+});

package/templates/configs/husky-pre-commit

@@ -0,0 +1,16 @@
+# Aura pre-commit hook: blocks commits that contain secrets, then runs lint.
+
+# 1. Secret check on staged changes.
+if [ -x node_modules/.bin/aura ] || command -v aura >/dev/null 2>&1; then
+  npx --no-install aura check-staged || {
+    echo "Aura found a secret in your staged changes. Remove it and read it from an environment variable instead."
+    exit 1
+  }
+else
+  echo "Aura is not installed, so the secret check was skipped. Run {{install_cmd}} to install it."
+fi
+
+# 2. Lint, only if package.json has a lint script.
+if node -e "process.exit(require('./package.json').scripts?.lint ? 0 : 1)" 2>/dev/null; then
+  {{run}} lint || exit 1
+fi

package/templates/configs/prettierignore

@@ -0,0 +1,18 @@
+# Build output and dependencies
+.next/
+out/
+build/
+dist/
+coverage/
+node_modules/
+
+# Lockfiles and generated files
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+bun.lock
+next-env.d.ts
+
+# Supabase local state and Aura's local files
+supabase/.temp/
+.aura/

package/templates/configs/prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "printWidth": 100
+}

package/templates/configs/security-headers.md

@@ -0,0 +1,41 @@
+# Security headers for next.config
+
+These headers tell browsers to block common attacks: loading your site over plain HTTP, embedding it in another site to trick users into clicking (clickjacking), guessing file types, and leaking full URLs to other sites.
+
+Add `headers()` to the existing config in `next.config.ts` (or `next.config.mjs`). If the config already has a `headers()` function, add the entry below to the array it returns instead of creating a second one.
+
+```ts
+import type { NextConfig } from "next";
+
+const securityHeaders = [
+  // Always use HTTPS for two years. Vercel serves HTTPS by default.
+  { key: "Strict-Transport-Security", value: "max-age=63072000" },
+  // Don't let browsers guess file types.
+  { key: "X-Content-Type-Options", value: "nosniff" },
+  // Don't allow other sites to show this app in a frame.
+  { key: "X-Frame-Options", value: "DENY" },
+  // Send only the origin, not the full URL, to other sites.
+  { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+  // Turn off browser features the app doesn't use.
+  { key: "Permissions-Policy", value: "camera=(), microphone=(), geolocation=()" },
+];
+
+const nextConfig: NextConfig = {
+  // ...keep your existing options here
+  async headers() {
+    return [{ source: "/:path*", headers: securityHeaders }];
+  },
+};
+
+export default nextConfig;
+```
+
+## Before merging
+
+- If the app is meant to be embedded in another site (an iframe widget), remove the `X-Frame-Options` line.
+- If the app uses the camera, microphone or location, change that feature's value to `(self)`, for example `camera=(self)`.
+- Once every subdomain of your domain uses HTTPS, you can add `; includeSubDomains` to the `Strict-Transport-Security` value.
+
+## Content Security Policy
+
+A Content Security Policy (CSP) is left out on purpose. A strict CSP is the strongest protection against injected scripts, but it often breaks apps that load analytics, payment widgets, fonts or inline scripts. Add it as a separate follow-up, start with `Content-Security-Policy-Report-Only` to see what would break, and test on a preview deployment before enforcing it.

package/templates/configs/vitest.config.ts

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { configDefaults, defineConfig } from "vitest/config";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      // Matches the "@/*" path in tsconfig.json.
+      "@": path.resolve(root, "{{src_alias_path}}"),
+    },
+  },
+  test: {
+    environment: "node",
+    // Playwright end-to-end tests run separately.
+    exclude: [...configDefaults.exclude, "e2e/**", "tests/e2e/**", ".next/**"],
+  },
+});

package/templates/docs/index.md

@@ -0,0 +1,55 @@
+# {{product_name}} docs
+
+Start here. This page points to everything else so you only open the files you need. Keep it short: links and one-line facts. Update it in the same change as the code.
+
+## Key documents
+
+- [Product brief](../.aura/brief.md): what we're building, for whom, and what's out of scope. The source of truth.
+- [README](../README.md): setup, commands, environment variables, deployment.
+- Agent rules: `CLAUDE.md` or `AGENTS.md` at the repo root.
+
+## Stack
+
+{{stack_list}}
+
+## Where things live
+
+<!-- One line per area. Example: "Billing logic: lib/billing.ts. Stripe webhook: app/api/stripe/webhook/route.ts." -->
+
+- Routes and pages: `app/`
+- Components: `components/` (`ui/` for generic, one folder per feature)
+- Business logic and integrations: `lib/`
+- Supabase clients: `lib/supabase/`
+- Database migrations: `supabase/migrations/`
+- Tests: next to the code (`*.test.ts`) and `e2e/`
+
+## Architecture notes
+
+<!-- Fill in as the project grows. Keep each note to a few lines. -->
+
+### Data model
+
+_Main tables and how they relate._
+
+### Auth and permissions
+
+_How users sign in, roles, and which tables are shared between users._
+
+### Key flows
+
+_The few flows that matter most (sign up, core action, payment) and the files involved._
+
+## Integrations
+
+<!-- One line per service: what it's used for, env vars, where the code is. -->
+
+| Service | Used for | Env vars | Code |
+| --- | --- | --- | --- |
+| Supabase | Database and auth | see `.env.example` | `lib/supabase/` |
+| Vercel | Hosting | set in the Vercel dashboard | n/a |
+
+## Gotchas
+
+<!-- Non-obvious things that cost time. One line each. -->
+
+_Last generated by Aura on {{date}}._

package/templates/github/dependabot.yml

@@ -0,0 +1,25 @@
+# Dependabot keeps dependencies up to date with small pull requests.
+# Security updates are separate: turn them on under
+# Settings → Advanced Security → Dependabot security updates.
+version: 2
+updates:
+  - package-ecosystem: "{{dependabot_ecosystem}}"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    # Wait a few days before proposing a brand-new release, so a compromised
+    # or broken version is usually caught before it reaches you.
+    cooldown:
+      default-days: 3
+    groups:
+      minor-and-patch:
+        update-types: ["minor", "patch"]
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      github-actions:
+        patterns: ["*"]

package/templates/github/workflows/aura-weekly.yml

@@ -0,0 +1,55 @@
+# Weekly Aura summary: every Monday, opens a GitHub issue with a plain-language
+# summary of the week's merged pull requests and commits, plus the score trend.
+# You can also run it by hand from the Actions tab.
+# Note: GitHub pauses scheduled workflows after 60 days without any repo activity.
+# If summaries stop arriving, re-enable this workflow in the Actions tab.
+name: Aura weekly summary
+
+on:
+  schedule:
+    - cron: "0 13 * * 1" # Mondays at 13:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: read
+
+jobs:
+  summary:
+    name: Weekly summary
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Choose pnpm version
+        id: pnpm
+        if: hashFiles('pnpm-lock.yaml') != ''
+        run: node -e "const p=require('./package.json');console.log('version='+(p.packageManager?'':'10'))" >> "$GITHUB_OUTPUT"
+
+      - name: Set up pnpm
+        if: hashFiles('pnpm-lock.yaml') != ''
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ steps.pnpm.outputs.version }}
+
+      - name: Set up Bun
+        if: hashFiles('bun.lock', 'bun.lockb') != ''
+        uses: oven-sh/setup-bun@v2
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '{{node_version}}'
+          cache: '{{setup_node_cache}}'
+
+      - name: Install dependencies
+        run: {{install_cmd}}
+
+      - name: Post weekly summary
+        env:
+          AURA_KEY: ${{ secrets.AURA_PILOT_KEY }}
+          GH_TOKEN: ${{ github.token }}
+        run: npx --yes getaura@{{aura_version}} summary --days 7 --post

package/templates/github/workflows/aura.yml

@@ -0,0 +1,90 @@
+# Aura score: scans every pull request, compares it with the base branch and
+# posts the result as a comment. The check fails when the score drops more than
+# the allowed amount (ciMaxDrop in .aura/config.json, default 0; loosen it with
+# `aura config ciMaxDrop 3`). Aura's version is pinned so scores only change when
+# your code does; upgrade it deliberately by re-running `aura apply add-aura-workflow`.
+# Needs the AURA_PILOT_KEY repository secret for plain-language explanations
+# (run `aura guide add-aura-key-to-github`). It still scores without it.
+name: Aura score
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: aura-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  aura:
+    name: Aura score
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Choose pnpm version
+        id: pnpm
+        if: hashFiles('pnpm-lock.yaml') != ''
+        run: node -e "const p=require('./package.json');console.log('version='+(p.packageManager?'':'10'))" >> "$GITHUB_OUTPUT"
+
+      - name: Set up pnpm
+        if: hashFiles('pnpm-lock.yaml') != ''
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ steps.pnpm.outputs.version }}
+
+      - name: Set up Bun
+        if: hashFiles('bun.lock', 'bun.lockb') != ''
+        uses: oven-sh/setup-bun@v2
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '{{node_version}}'
+          cache: '{{setup_node_cache}}'
+
+      - name: Install dependencies
+        run: {{install_cmd}}
+
+      - name: Run Aura scan (pull request)
+        id: scan
+        if: github.event_name == 'pull_request'
+        continue-on-error: true
+        env:
+          AURA_KEY: ${{ secrets.AURA_PILOT_KEY }}
+          BASE_REF: ${{ github.base_ref }}
+        run: npx --yes getaura@{{aura_version}} scan --ci --base "origin/$BASE_REF" --comment-file aura-comment.md
+
+      - name: Post Aura comment
+        # Runs even when the scan failed. Skipped for forks and Dependabot,
+        # whose pull requests can't write comments.
+        if: >-
+          always()
+          && github.event_name == 'pull_request'
+          && github.event.pull_request.head.repo.full_name == github.repository
+          && github.actor != 'dependabot[bot]'
+          && hashFiles('aura-comment.md') != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: gh pr comment "$PR_NUMBER" --body-file aura-comment.md --edit-last --create-if-none
+
+      - name: Fail if the score dropped
+        if: github.event_name == 'pull_request' && steps.scan.outcome == 'failure'
+        run: |
+          echo "The Aura score dropped more than allowed, or the scan failed. See the comment on the pull request."
+          exit 1
+
+      - name: Run Aura scan (main)
+        if: github.event_name == 'push'
+        env:
+          AURA_KEY: ${{ secrets.AURA_PILOT_KEY }}
+        run: npx --yes getaura@{{aura_version}} scan --ci

package/templates/github/workflows/ci.yml

@@ -0,0 +1,86 @@
+# Runs lint, tests, build and type checking on every pull request and on main.
+# Steps whose script doesn't exist in package.json are skipped, not failed.
+# If the build needs environment variables, add them under
+# Settings → Secrets and variables → Actions and map them in the build step's env.
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: Lint, test, build
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Choose pnpm version
+        id: pnpm
+        if: hashFiles('pnpm-lock.yaml') != ''
+        # Uses the packageManager field in package.json when present, otherwise pnpm 10.
+        run: node -e "const p=require('./package.json');console.log('version='+(p.packageManager?'':'10'))" >> "$GITHUB_OUTPUT"
+
+      - name: Set up pnpm
+        if: hashFiles('pnpm-lock.yaml') != ''
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ steps.pnpm.outputs.version }}
+
+      - name: Set up Bun
+        if: hashFiles('bun.lock', 'bun.lockb') != ''
+        uses: oven-sh/setup-bun@v2
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '{{node_version}}'
+          cache: '{{setup_node_cache}}'
+
+      - name: Install dependencies
+        run: {{install_cmd}}
+
+      - name: Lint
+        run: |
+          if node -e "process.exit(require('./package.json').scripts?.lint ? 0 : 1)"; then
+            {{run}} lint
+          else
+            echo "No lint script in package.json, skipping."
+          fi
+
+      - name: Test
+        run: |
+          if node -e "process.exit(require('./package.json').scripts?.test ? 0 : 1)"; then
+            {{run}} test
+          else
+            echo "No test script in package.json, skipping."
+          fi
+
+      - name: Build
+        run: |
+          if node -e "process.exit(require('./package.json').scripts?.build ? 0 : 1)"; then
+            {{run}} build
+          else
+            echo "No build script in package.json, skipping."
+          fi
+        env:
+          NEXT_TELEMETRY_DISABLED: 1
+
+      # Runs after the build so Next.js has generated next-env.d.ts and route types.
+      - name: Typecheck
+        run: |
+          if node -e "process.exit(require('./package.json').scripts?.typecheck ? 0 : 1)"; then
+            {{run}} typecheck
+          elif [ -f tsconfig.json ]; then
+            npx --no-install tsc --noEmit
+          else
+            echo "No tsconfig.json, skipping."
+          fi

package/templates/guides/add-aura-key-to-github.md

@@ -0,0 +1,34 @@
+---
+title: Add your Aura key to GitHub
+summary: Store your Aura pilot key as a GitHub Actions secret so pull request checks include plain-language explanations.
+services: [github, aura]
+---
+
+# Add your Aura key to GitHub
+
+The Aura workflow scores every pull request. With your pilot key stored as a repository secret, its comments also include plain-language explanations. The key is stored encrypted and never shown in logs.
+
+## Option 1: in the browser
+
+1. Open your repository on GitHub → **Settings → Secrets and variables → Actions**.
+2. Click **New repository secret**.
+3. Name: `AURA_PILOT_KEY`
+4. Secret: paste your Aura pilot key (it starts with `aura_`).
+5. Click **Add secret**.
+
+## Option 2: in the terminal
+
+From your project folder, run:
+
+```bash
+gh secret set AURA_PILOT_KEY
+```
+
+Paste the key when asked and press Enter. Don't put the key in the command itself, so it doesn't end up in your terminal history.
+
+## Check it worked
+
+- **Settings → Secrets and variables → Actions** lists `AURA_PILOT_KEY` (the value stays hidden), or `gh secret list` shows it.
+- Open or update a pull request. The **Aura score** comment includes explanations.
+
+Pull requests from Dependabot and from forks can't read repository secrets or post comments. The Aura check still runs on them, without a comment. That's expected.