getaura 0.0.0-stage → 0.1.1

package/templates/guides/transfer-ownership.md

@@ -0,0 +1,55 @@
+---
+title: Move accounts to company ownership
+summary: Move your code, hosting, database, payments and domain into accounts the company controls, not one person's personal login.
+services: [github, vercel, supabase, stripe, domain]
+---
+
+# Move accounts to company ownership
+
+If your app lives in one person's personal accounts, the business depends on that person's login. If they leave, lose access or get locked out, you can lose the app, the customer data or the payments. Move each account to a company-owned organization or team.
+
+## Before you start
+
+1. Create a company email address for accounts, for example `admin@yourcompany.com`, ideally a shared inbox that more than one person can read.
+2. Set up a shared password manager (1Password, Bitwarden or similar) for the company. Store every login and recovery code there.
+3. Turn on two-factor authentication everywhere, using an authenticator app or passkeys. Save recovery codes in the password manager.
+
+## GitHub repository → organization
+
+1. Create a free organization: profile picture → **Your organizations → New organization**. Add at least one other owner.
+2. In the repository, open **Settings → General**, scroll to **Danger Zone**, click **Transfer ownership**, and choose the organization.
+3. GitHub redirects the old URL. Update the remote on your machine if you like: `git remote set-url origin <new URL>`.
+4. Reconnect the repository in Vercel if deploys stop (Project → **Settings → Git**).
+
+## Vercel project → team
+
+1. Create a team in Vercel if you don't have one (account menu → **Create Team**). Team plans may cost money; check the pricing first.
+2. Open the project → **Settings → General**, scroll down to **Transfer Project**, and pick the team.
+3. Check that environment variables, domains and the Git connection came across, then redeploy.
+
+## Supabase project → organization
+
+1. Create an organization owned by the company email (https://supabase.com/dashboard → **New organization**), and invite at least one other owner.
+2. Open the project → **Project Settings → General**, find **Transfer project**, and pick the organization. The plan and billing move with it; check the target organization's plan first.
+
+## Stripe account owner
+
+1. Invite the company email: **Settings → Team and security → Team → New member**, role **Administrator**.
+2. Once they accept, the current owner opens the same page, clicks **⋯** next to the new member, and chooses **Transfer ownership** (if you don't see it, contact Stripe support).
+3. Check the bank account and business details under **Settings → Business** belong to the company.
+
+## Domain name
+
+1. Sign in to the registrar where the domain was bought (Namecheap, Cloudflare, GoDaddy, Squarespace and others).
+2. Either change the account's email and login to the company email, or use the registrar's "move" or "change account" option to move the domain into a company account.
+3. Turn on auto-renew and registrar lock, and make sure the payment card won't expire soon.
+
+## Record it
+
+Run `aura inventory` and record the owner of each service, so everyone knows who controls what.
+
+## Check it worked
+
+- Each service shows the company organization, team or email as owner.
+- At least two people can sign in to each account (through the password manager).
+- `aura inventory --json` lists an owner for every service.

package/templates/pr/add-agent-rules.md

@@ -0,0 +1,16 @@
+## What this does
+
+Adds a project rules section to the file your coding agent reads at the start of every session (`CLAUDE.md` for Claude Code, `AGENTS.md` for Codex and Pi, `.cursor/rules/aura.mdc` for Cursor). It covers your stack, the commands to run, and the rules every change should follow. Aura only manages the part between its `aura:start` and `aura:end` markers; anything else in the file is left as it was.
+
+## Why it matters
+
+Without rules, agents guess. With them, they write tests, check who is signed in on every route, protect every database table and keep secrets out of the code, without you having to ask each time.
+
+## What to check before merging
+
+- [ ] The product summary, stack and commands are correct.
+- [ ] If you already had rules in this file, they're still there.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/add-aura-workflow.md

@@ -0,0 +1,18 @@
+## What this does
+
+Adds two GitHub Actions workflows:
+- `aura.yml` scans every pull request, posts the Aura score and what changed as a comment, and fails the check if the score drops more than allowed.
+- `aura-weekly.yml` opens a GitHub issue every Monday with a plain-language summary of the week's changes and the score trend.
+
+## Why it matters
+
+You see the effect of every change on your app's security and quality before you merge it, in plain language, even when your coding agent made the change.
+
+## What to check before merging
+
+- [ ] Add your Aura pilot key as a repository secret named `AURA_PILOT_KEY` for plain-language explanations (`aura guide add-aura-key-to-github`). The workflow works without it, with shorter comments.
+- [ ] The **Aura score** check on this pull request runs and posts a comment.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/add-brief.md

@@ -0,0 +1,17 @@
+## What this does
+
+Adds `.aura/brief.md`, a short description of {{product_name}}: what it does, who it's for, what it charges for and what data it handles. It was drafted from your answers during `aura init`.
+
+## Why it matters
+
+Coding agents make better decisions when they know what the product is for. The brief is linked from your agent rules, so every session starts with the same understanding, and agents are told to ask you before doing work that contradicts it.
+
+## What to check before merging
+
+- [ ] Read the brief. Does it describe the product accurately?
+- [ ] Fix anything wrong or missing directly in this pull request (edit the file on GitHub), then merge.
+- [ ] Nothing secret is in it. It's committed to the repository.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/add-ci.md

@@ -0,0 +1,16 @@
+## What this does
+
+Adds a GitHub Actions workflow (`.github/workflows/ci.yml`) that runs on every pull request and every push to `main`. It installs dependencies and runs lint, tests, the production build and type checking. Any step whose script doesn't exist yet is skipped.
+
+## Why it matters
+
+Every change gets checked automatically before it's merged, so mistakes are caught in the pull request instead of by your users. Once it's running, you can require it to pass before merging (see `aura guide github-security`).
+
+## What to check before merging
+
+- [ ] The **CI** check on this pull request passes. If the build fails because environment variables are missing, add them under **Settings → Secrets and variables → Actions** and map them in the build step, or ask your coding agent to.
+- [ ] If an existing problem (a lint error, a failing test) makes it fail, fix that in a separate pull request or ask your coding agent to.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/add-env-example.md

@@ -0,0 +1,18 @@
+## What this does
+
+Adds `.env.example`, a list of every environment variable the app uses, with a short comment for each and no real values. It also makes sure `.env.local` and other files with real values are ignored by git.
+
+{{details}}
+
+## Why it matters
+
+Anyone setting up the project (a new teammate, a new computer, a coding agent) can see which settings are needed without guessing, and nobody has to share a file with real secrets to get started.
+
+## What to check before merging
+
+- [ ] The file contains no real keys or passwords. Only names and comments.
+- [ ] The comments are accurate. Add any variable that's missing.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/add-linting.md

@@ -0,0 +1,16 @@
+## What this does
+
+Adds ESLint with the official Next.js rules, Prettier for consistent formatting, and `lint` and `format` scripts.
+
+## Why it matters
+
+Linting catches common bugs (like misused React hooks) automatically. Consistent formatting keeps changes small and easy to review, so it's clear what actually changed.
+
+## What to check before merging
+
+- [ ] The **CI** check passes. If lint reports existing problems, merge this anyway and ask your coding agent to fix them in a follow-up.
+- [ ] Don't run the formatter across the whole project in this pull request; it would hide real changes in a huge diff.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/add-pre-commit.md

@@ -0,0 +1,16 @@
+## What this does
+
+Adds a pre-commit hook with Husky. Before each commit, it checks the staged changes for secrets (API keys, tokens, passwords) with `aura check-staged` and runs lint if the project has a lint script. A commit with a secret in it is stopped.
+
+## Why it matters
+
+Once a secret is pushed to GitHub, you have to rotate it. Catching it before the commit means it never leaves your computer.
+
+## What to check before merging
+
+- [ ] After merging, run the install command from the README once so the hook is set up on your machine.
+- [ ] Make a small commit to confirm it runs. It takes a few seconds.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/add-readme.md

@@ -0,0 +1,16 @@
+## What this does
+
+Adds a `README.md` describing {{product_name}}: what it does, how to set it up and run it, the environment variables it needs, the commands, how it's deployed and how the project is organized.
+
+## Why it matters
+
+The README is the first thing a teammate, contractor, investor or coding agent reads. A good one saves hours of explaining and guessing.
+
+## What to check before merging
+
+- [ ] The "What it does" section describes the product well. Edit it in this pull request if not.
+- [ ] The setup steps match how you run the project.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/add-security-headers.md

@@ -0,0 +1,16 @@
+## What this does
+
+Adds standard security headers to every response, through `headers()` in `next.config`: force HTTPS, block other sites from showing your app in a frame, stop browsers guessing file types, limit what's shared when users click links to other sites, and turn off camera, microphone and location access.
+
+## Why it matters
+
+These headers block several common attacks, such as clickjacking (tricking users into clicking something hidden), with no change to how your app works. A Content Security Policy is left out on purpose because it often breaks apps; it's a good follow-up.
+
+## What to check before merging
+
+- [ ] Open the preview deployment and click through the app. Everything works as before.
+- [ ] If your app is meant to be embedded in another website, or uses the camera, microphone or location, tell your coding agent so it can adjust the headers.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/enable-dependency-updates.md

@@ -0,0 +1,16 @@
+## What this does
+
+Adds `.github/dependabot.yml`. Dependabot opens a weekly pull request that groups minor and patch updates for your packages, and a monthly one for GitHub Actions. It waits a few days after a new release before suggesting it.
+
+## Why it matters
+
+Old packages collect known security problems. Small, regular updates checked by CI are much easier and safer than a big upgrade once a year.
+
+## What to check before merging
+
+- [ ] After merging, expect a few Dependabot pull requests. Merge them when the **CI** check passes.
+- [ ] Also turn on Dependabot alerts and security updates (see `aura guide github-security`).
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/fix-vulnerable-deps.md

@@ -0,0 +1,19 @@
+## What this does
+
+Updates packages that have publicly known security vulnerabilities to the nearest fixed version.
+
+{{details}}
+
+## Why it matters
+
+Attackers scan for apps that use packages with known vulnerabilities. Updating closes those holes.
+
+## What to check before merging
+
+- [ ] The **CI** check passes.
+- [ ] Open the preview deployment and try the main flows (sign in, the core feature, payment). Version updates can occasionally change behaviour.
+- [ ] Packages marked as major upgrades are the most likely to need code changes. If one breaks something, ask your coding agent to fix it on this branch.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/foundation.md

@@ -0,0 +1,19 @@
+## What this does
+
+Sets up the basics every app should have, in one pull request.
+
+{{details}}
+
+## Why it matters
+
+These are the foundations that keep an app safe and maintainable as it grows: your coding agent knows the rules, checks run on every change, and secrets stay out of the code. Doing them together now is much easier than adding them one by one later.
+
+## What to check before merging
+
+- [ ] Read the product brief (`.aura/brief.md`) and fix anything that's wrong.
+- [ ] The **CI** check on this pull request passes. If it fails because of an existing problem, ask your coding agent to fix it on this branch.
+- [ ] After merging, run the install command from the README once so the pre-commit hook is set up on your machine.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/install-skills.md

@@ -0,0 +1,18 @@
+## What this does
+
+Installs skills: short instruction files your coding agent loads only when a task needs them. They go in `{{skills_dir}}/`.
+
+{{details}}
+
+## Why it matters
+
+Skills give your agent detailed, up-to-date instructions for the things that most often go wrong in apps built quickly (security, database rules, tests, secrets), without filling every session with instructions it doesn't need.
+
+## What to check before merging
+
+- [ ] Skim the list of skills. Remove any you don't want by deleting its folder in this pull request.
+- [ ] If you already had a skill with the same name, check the changes to it in this pull request.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/move-misplaced-files.md

@@ -0,0 +1,18 @@
+## What this does
+
+Moves a few files to the place the project's folder layout says they belong, and updates every import that pointed to them. No code inside the files changes.
+
+{{details}}
+
+## Why it matters
+
+A predictable layout means you and your coding agent find things quickly, and new code goes in the right place.
+
+## What to check before merging
+
+- [ ] The **CI** check passes (it confirms every import still works).
+- [ ] No page URLs changed. Pages under `app/` are never moved by this action.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/remove-dead-files.md

@@ -0,0 +1,18 @@
+## What this does
+
+Deletes files that nothing in the project imports or uses.
+
+{{details}}
+
+## Why it matters
+
+Unused files confuse you and your coding agent: agents read them, copy patterns from them and sometimes edit them instead of the real code. Removing them makes the project smaller and easier to work on.
+
+## What to check before merging
+
+- [ ] Check the list. If you recognize a file you still need (for example something used by a script or an external tool), tell your coding agent or restore it in this pull request.
+- [ ] The **CI** check passes and the preview deployment works.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/setup-testing.md

@@ -0,0 +1,19 @@
+## What this does
+
+Adds Vitest, a fast test runner, with a config file, a `test` script in `package.json` and one small example test.
+
+{{details}}
+
+## Why it matters
+
+Tests check that your app still works after every change, so you and your coding agent can change things with confidence. Your agent rules ask agents to add tests for every new feature; this gives them a place to put them.
+
+## What to check before merging
+
+- [ ] The **CI** check passes, which runs the example test.
+- [ ] Run the test script locally if you like (see the README). The example test passes.
+- [ ] Replace the example test with real ones over time. Your coding agent can start with `aura fix write-critical-tests --agent`.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/token-efficiency.md

@@ -0,0 +1,18 @@
+## What this does
+
+Adds `docs/index.md`, a short map of the project: key documents, where code lives, architecture notes and integrations. Your agent rules tell agents to read it first.
+
+{{details}}
+
+## Why it matters
+
+Agents spend a lot of time (and tokens, which cost money) searching the codebase. A short index lets them open only the files they need, so they work faster, cheaper and with fewer mistakes. Agents add to it as they learn more about the project.
+
+## What to check before merging
+
+- [ ] The "Where things live" section matches your project. Fix anything that's off.
+- [ ] Nothing secret is in it.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/readme/README.md

@@ -0,0 +1,73 @@
+# {{product_name}}
+
+{{product_summary}}
+
+## What it does
+
+<!-- Describe the main things a user can do, in plain language. See .aura/brief.md for the full brief. -->
+
+## Built with
+
+{{stack_list}}
+
+## Getting started
+
+### Prerequisites
+
+- Node.js {{node_version}} or later
+- {{package_manager}}
+- Accounts with access to the project's services (see Environment variables)
+
+### Set up
+
+1. Install dependencies:
+   ```bash
+   {{install_cmd}}
+   ```
+2. Copy the example environment file and fill in the values:
+   ```bash
+   cp .env.example .env.local
+   ```
+   If the project is linked to Vercel, `vercel env pull .env.local` downloads the development values instead.
+3. Start the development server:
+   ```bash
+   {{run}} dev
+   ```
+4. Open http://localhost:3000.
+
+## Environment variables
+
+Every variable is listed in `.env.example` with a short description. Never commit `.env.local` or real values.
+
+{{env_vars_list}}
+
+Variables starting with `NEXT_PUBLIC_` are visible in the browser, so they must never hold secrets.
+
+## Commands
+
+{{commands_list}}
+
+## Deployment
+
+- **App**: hosted on Vercel. Pushing to `main` deploys to production; every pull request gets a preview deployment. Set environment variables in Vercel under Project → Settings → Environment Variables, then redeploy.
+- **Database**: schema changes are migrations in `supabase/migrations/`. Apply them to production with `npx supabase db push` (after `npx supabase link`) before or alongside the deploy that needs them.
+
+## Project structure
+
+```
+app/                 Routes and pages
+components/          UI components
+lib/                 Business logic, integrations, Supabase clients
+supabase/migrations/ Database migrations
+docs/                Project docs
+public/              Static files
+```
+
+## Docs
+
+- [Docs index](docs/index.md): where things live, architecture notes, integrations
+- [Product brief](.aura/brief.md): what we're building and for whom
+
+---
+
+Built with [Aura](https://github.com/JohnFazio1/aura).

package/templates/rules/agent-rules.md

@@ -0,0 +1,43 @@
+## About {{product_name}}
+
+{{product_summary}}
+
+The product brief in `.aura/brief.md` is the source of truth for what we're building and for whom. Read it before planning a feature. If a request contradicts it, ask before continuing.
+
+## Stack
+
+{{stack_list}}
+
+Package manager: {{package_manager}}. Use it for every install and script; don't add another lockfile.
+
+## Commands
+
+{{commands_list}}
+
+## Rules
+
+These apply to every change.
+
+1. **Tests**: every new feature and bug fix gets tests. Run the test suite before saying you're done, and never delete or skip a failing test to make it pass.
+2. **Auth on every route**: every route handler and server action checks the signed-in user on the server and checks they're allowed to touch that record. Validate input with zod.
+3. **Row level security on every table**: every new table enables RLS with explicit policies, in a migration in `supabase/migrations/`. Never edit an applied migration.
+4. **No hardcoded secrets**: read secrets from `process.env` in server code only. Never put a secret in a `NEXT_PUBLIC_` variable. When you add a variable, add it to `.env.example` (name and comment, no value).
+5. **Folder layout**: put new code where the folder-structure skill says. Search for an existing helper before writing a new one.
+6. **Small, focused changes**: one concern per change. Don't refactor unrelated code or move many files at once.
+7. **Docs**: update README.md and `docs/index.md` when behaviour, setup or env vars change.
+8. **Errors**: handle failures with plain user-facing messages; never show stack traces or raw errors to users.
+9. **Check your work**: run `aura scan` before finishing a big change and fix anything new it reports. Never disable or work around an Aura check without the user's agreement.
+10. **Plain language**: the user may be non-technical. Explain what you did and why in plain words, and say clearly when they need to do something themselves (dashboards, keys, payments).
+
+## Working efficiently
+
+- Read `docs/index.md` first. It says where things live, so you don't have to search the whole repo.
+- Open only the files you need for the task. Don't read lockfiles, build output (`.next/`, `dist/`) or `node_modules/`.
+- Load a skill only when the task needs it.
+- When you learn something about the codebase that would have saved time, add one line to `docs/index.md`.
+
+## Skills
+
+Skills live in `{{skills_dir}}/`. Load the relevant one before starting that kind of work.
+
+{{skills_list}}

package/templates/skills/aura/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: aura
+description: Use when the user asks about their Aura score, what to fix next, or to fix the most serious issue, before a release, or after a big change. Runs the Aura CLI to scan the repo, explain findings in plain language and fix them through pull requests.
+---
+
+# Aura
+
+Aura is a CLI that scores this repo on security, agent setup, foundations and structure (0–100), then recommends and makes fixes through pull requests. The user is often a non-technical founder. Your job is to run Aura, explain what it found in plain language and help fix it.
+
+Run `aura <command>`. If `aura` is not on the PATH, run `npx getaura <command>` instead.
+
+## When to use it
+
+- "Check my Aura score", "how healthy is my code", "is this safe to launch"
+- "What should I fix next?" or "fix the most serious issue"
+- Before a release, and after a big change (new feature, new integration, large refactor)
+
+## Commands
+
+Always use the non-interactive flags below so nothing waits for input.
+
+| Goal | Command |
+| --- | --- |
+| Score and findings | `aura scan --json` (add `--fast` for a quick check without type checking, linting and dead-code analysis) |
+| Recommended next steps | `aura next --json` |
+| Apply a template change as a PR | `aura apply <action> --yes` |
+| Let Aura's agent fix something | `aura fix <finding id or action> --yes` |
+| Get a task file for you to complete | `aura fix <finding id or action> --agent` |
+| Step-by-step guide for the user | `aura guide <topic>` (list topics with `aura guide --list`) |
+| Services, env vars and owners | `aura inventory --json` |
+| Score trend | `aura history` |
+
+## Reading the JSON
+
+`aura scan --json` returns:
+- `score` (0–100) and `cappedBy` when a critical finding capped the score.
+- `categories[]`: `category`, `score`.
+- `checks[]`: `checkId`, `title`, `status`, `summary` and `findings[]`.
+- Each finding: `id`, `severity` (critical, high, medium, low, info), `title`, `detail`, `why`, optional `explanation`, `locations[]` (`file`, `line`) and optional `actionId`.
+
+`aura next --json` returns steps in priority order. Each step has `actionId`, `title`, `delivery` (`pr`, `agent-fix`, `guide`, `checklist`), `why`, `impact` (estimated points gained), `effort` and the exact `command` to run.
+
+## Explaining findings to the user
+
+- Use plain language. Say what could happen to the business or its users, not just the technical term.
+- Start with the most serious finding. Group the rest; don't dump the whole list.
+- Never print, quote or repeat a secret value, even partly. Refer to it by file and line.
+- Keep two things separate: what Aura found, and what you think. Say "Aura found…" and "I think…".
+- End with one clear recommendation and the command or action for it.
+
+## Fixing things
+
+1. Pick the step: the first item from `aura next --json`, or the finding the user named.
+2. Follow its `delivery`:
+   - `pr`: run the step's command (`aura apply <action> --yes`). Tell the user a PR was opened and what to check.
+   - `agent-fix`: run `aura fix <id> --agent`, then complete the task file yourself (see below), or run `aura fix <id> --yes` if the user prefers Aura's agent.
+   - `guide`: run `aura guide <topic>` and walk the user through it. These steps happen in vendor dashboards, so the user does them.
+   - `checklist`: run `aura inventory` and help the user answer the questions.
+3. After any change, run `aura scan --json` again and tell the user the new score.
+
+## Task files
+
+When `.aura/tasks/<id>.md` exists, it is your brief. Follow it exactly:
+
+1. Create a branch: `git checkout -b aura/<id>`.
+2. Make the change the task describes. Keep it small and focused on that task.
+3. Run the tests, lint and typecheck. Fix anything you broke.
+4. Commit, push and open a PR with `gh pr create`. Write the PR body in plain language: what changed, why it matters, and what the user should check before merging.
+5. Run `aura scan` to confirm the finding is gone.
+
+## Rules
+
+- Never disable, weaken or game a check to raise the score. This includes adding `aura-ignore` comments, editing `.aura/config.json` ignores or deleting tests, unless the user explicitly agrees after you explain the trade-off.
+- Never commit `.aura/report.md`, `.aura/scan.json`, `.aura/history.json` or `.aura/tasks/`. They stay local because they can describe security weaknesses.
+- If a finding is a leaked secret, tell the user straight away and run `aura guide rotate-<service>-key`. Removing the secret from the code is not enough; it must be rotated.
+- If you think a finding is wrong, say so and explain why. Don't silently skip it.