@stacksjs/defaults 0.72.103 → 0.73.0

package/ai/skills/stacks-wizard/scripts/template.sh

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+#
+# A wizard walks a human through a manual procedure, step by step.
+# Generated by the stacks-wizard skill.
+#
+# Library adapted from Matt Pocock's `wizard` skill (MIT),
+# https://github.com/mattpocock/skills
+#
+# Everything above the "STAGES" marker is the wizard library: do not hand-edit
+# it. Author the per-step stages below the marker.
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────────
+# Wizard library: delightful, consistent UX, identical across every wizard.
+# ──────────────────────────────────────────────────────────────────────────
+
+if [[ -t 1 ]] && command -v tput >/dev/null 2>&1 && [[ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]]; then
+  BOLD=$(tput bold); DIM=$(tput dim); RESET=$(tput sgr0)
+  BLUE=$(tput setaf 4); GREEN=$(tput setaf 2); YELLOW=$(tput setaf 3); RED=$(tput setaf 1)
+else
+  BOLD=""; DIM=""; RESET=""; BLUE=""; GREEN=""; YELLOW=""; RED=""
+fi
+
+# Author sets this at the top of the stages section.
+TOTAL_STAGES=0
+
+_STAGE_INDEX=0
+ENV_FILE="${ENV_FILE:-.env}"
+WRITTEN_ENV=()    # KEYs written to ENV_FILE this run
+WRITTEN_SECRET=() # secret NAMEs set this run
+SKIPPED=()        # things we couldn't do (e.g. gh missing)
+
+# _clear wipes the terminal so only the current step is on screen. No-op when
+# output isn't a terminal, so piped logs stay readable.
+_clear() {
+  [[ -t 1 ]] || return 0
+  if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi
+}
+
+# banner "Title" shows the opening frame: what this wizard does.
+banner() {
+  _clear
+  printf '\n%s%s  %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET"
+  printf '%s  %s stages%s\n\n' "$DIM" "$TOTAL_STAGES" "$RESET"
+  printf '%s  You drive the browser; this wizard tells you exactly what to do and\n' "$DIM"
+  printf '  captures the values you copy back. Stop any time with Ctrl-C and re-run\n'
+  printf '  later, since it remembers values already saved.%s\n' "$RESET"
+  pause "Ready to start?"
+}
+
+# stage "Name" clears the screen, then announces a stage and shows progress.
+# Clearing keeps only the current step on screen.
+stage() {
+  _clear
+  _STAGE_INDEX=$((_STAGE_INDEX + 1))
+  printf '\n%s%s▸ Stage %s/%s · %s%s\n' \
+    "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET"
+}
+
+# say "..." prints a plain instruction line.
+say()  { printf '  %s\n' "$1"; }
+# step "..." is a numbered-feeling action the human takes in the browser.
+step() { printf '  %s•%s %s\n' "$BLUE" "$RESET" "$1"; }
+note() { printf '  %s%s%s\n' "$DIM" "$1" "$RESET"; }
+warn() { printf '  %s⚠ %s%s\n' "$YELLOW" "$1" "$RESET"; }
+
+# open_url URL opens it in the human's browser, cross-platform incl. WSL.
+open_url() {
+  local url="$1"
+  printf '  %s↗ opening%s %s\n' "$GREEN" "$RESET" "$url"
+  { if   command -v wslview     >/dev/null 2>&1; then wslview "$url"
+    elif command -v explorer.exe >/dev/null 2>&1; then explorer.exe "$url"
+    elif command -v xdg-open    >/dev/null 2>&1; then xdg-open "$url"
+    elif command -v open        >/dev/null 2>&1; then open "$url"
+    else warn "couldn't open a browser; visit it manually: $url"; fi
+  } >/dev/null 2>&1 || warn "couldn't open a browser, so visit it manually: $url"
+}
+
+# pause "msg" waits for the human to confirm they've done the manual part.
+pause() {
+  printf '  %s%s%s ' "$DIM" "${1:-Press Enter to continue}" "$RESET"
+  read -r _ || true
+}
+
+# confirm "question" is a y/N gate; returns success on yes.
+confirm() {
+  local reply=""
+  printf '  %s? %s [y/N] ' "$YELLOW" "$1"
+  read -r reply || true
+  [[ "$reply" =~ ^[Yy] ]]
+}
+
+# _existing KEY: current value of KEY in ENV_FILE, if any.
+_existing() {
+  [[ -f "$ENV_FILE" ]] || return 1
+  local line; line=$(grep -E "^${1}=" "$ENV_FILE" | tail -n1) || return 1
+  printf '%s' "${line#*=}"
+}
+
+# ask KEY "Prompt" reads a value into $KEY. Offers the existing .env value as
+# a default on re-runs (Enter keeps it). Visible input (non-secret).
+ask() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -r input || true
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# ask_secret KEY "Prompt" is like ask, but input is hidden.
+ask_secret() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -rs input || true
+  printf '\n'
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# write_env KEY VALUE upserts KEY=VALUE into ENV_FILE (creates it; replaces
+# any existing line). Idempotent.
+write_env() {
+  local key="$1" value="$2" tmp
+  touch "$ENV_FILE"
+  tmp=$(mktemp)
+  grep -vE "^${key}=" "$ENV_FILE" > "$tmp" || true
+  printf '%s=%s\n' "$key" "$value" >> "$tmp"
+  mv "$tmp" "$ENV_FILE"
+  WRITTEN_ENV+=("$key")
+  printf '  %s✓ wrote%s %s → %s\n' "$GREEN" "$RESET" "$key" "$ENV_FILE"
+}
+
+# set_secret NAME VALUE sets a GitHub Actions repo secret via gh. Falls back
+# to a warning (and records it) if gh is unavailable or unauthenticated.
+set_secret() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if printf '%s' "$value" | gh secret set "$name" >/dev/null 2>&1; then
+      WRITTEN_SECRET+=("$name")
+      printf '  %s✓ set%s GitHub secret %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub secret $name (set it manually: gh secret set $name)")
+  warn "skipped GitHub secret $name: gh not ready; set it later"
+}
+
+# set_var NAME VALUE sets a GitHub Actions repo variable (non-secret).
+set_var() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if gh variable set "$name" --body "$value" >/dev/null 2>&1; then
+      printf '  %s✓ set%s GitHub variable %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub variable $name")
+  warn "skipped GitHub variable $name, gh not ready; set it later"
+}
+
+# finish clears, then shows a closing summary of everything configured.
+finish() {
+  _clear
+  printf '\n%s%s  ✓ Setup complete%s\n' "$BOLD" "$GREEN" "$RESET"
+  (( ${#WRITTEN_ENV[@]} ))    && note "wrote ${#WRITTEN_ENV[@]} value(s) to $ENV_FILE: ${WRITTEN_ENV[*]}"
+  (( ${#WRITTEN_SECRET[@]} )) && note "set ${#WRITTEN_SECRET[@]} GitHub secret(s): ${WRITTEN_SECRET[*]}"
+  if (( ${#SKIPPED[@]} )); then
+    printf '\n'; warn "still to do by hand:"
+    for s in "${SKIPPED[@]}"; do note "  - $s"; done
+  fi
+  printf '\n'
+}
+
+# ──────────────────────────────────────────────────────────────────────────
+# STAGES: author this section. One stage() per step the human takes.
+# Replace the example below. Set TOTAL_STAGES to match the stages you write.
+# ──────────────────────────────────────────────────────────────────────────
+
+TOTAL_STAGES=1
+
+banner "AWS credentials for buddy deploy"
+
+# -- Example stage: replace with the real steps ---------------------------
+stage "AWS: access keys"
+say "We'll capture an AWS access key pair so 'buddy deploy' can reach your account."
+open_url "https://console.aws.amazon.com/iam/home#/security_credentials"
+step "Open Access keys, then Create access key, and pick 'Command Line Interface'."
+ask AWS_ACCESS_KEY_ID "Paste the access key ID:"
+step "Copy the secret access key before you close the dialog. It is shown once."
+ask_secret AWS_SECRET_ACCESS_KEY "Paste the secret access key:"
+write_env AWS_ACCESS_KEY_ID "$AWS_ACCESS_KEY_ID"
+write_env AWS_SECRET_ACCESS_KEY "$AWS_SECRET_ACCESS_KEY"
+set_secret AWS_SECRET_ACCESS_KEY "$AWS_SECRET_ACCESS_KEY"   # CI needs this one
+note "Encrypt the file when every stage is done: ./buddy env:encrypt"
+# -------------------------------------------------------------------------
+
+finish

package/ai/skills/stacks-writing-for-agents/MECHANICS.md

@@ -0,0 +1,125 @@
+# Skill mechanics in Stacks
+
+The skill-specific branch of [SKILL.md](SKILL.md): what changes when the
+document is a `SKILL.md`. Everything else about writing it is the universal
+reference next door.
+
+## Where a skill lives
+
+`@stacksjs/skills` resolves a skill name against two sources, in order:
+
+1. `app/Skills/<name>/SKILL.md` - the project's own skills
+2. `storage/framework/defaults/ai/skills/<name>/SKILL.md` - the bundled ones
+
+First hit wins, which is the same app-overrides-defaults model as
+`app/Actions/` and `app/Models/`. To shadow a bundled skill, create a directory
+with **the same name** under `app/Skills/`. To add a new one, pick a name no
+bundled skill uses.
+
+`buddy setup:ai <agent>` materializes the merged set into whatever directory the
+agent reads (`.claude/skills` for Claude Code), symlinking by default so an
+upgrade keeps them in sync, or copying with `--copy` when you want to edit them
+per project. The generated directories are gitignored. Only `AGENTS.md` is
+committed, because which agent you use is a personal choice.
+
+Nothing writes into `storage/framework/defaults/ai/skills`. A project skill goes
+in `app/Skills/`. Edit the bundled directory only when you are working on the
+framework itself.
+
+## Frontmatter
+
+```yaml
+---
+name: stacks-cache
+description: Use when implementing caching in Stacks - memory cache, Redis cache, cache-aside (getOrSet), TTL management, or cache stats. Covers @stacksjs/cache and config/cache.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+```
+
+`validateSkill()` in `@stacksjs/skills` enforces four rules, and
+`storage/framework/core/skills/tests/skills.test.ts` runs it over every bundled
+skill, so a broken one fails the suite:
+
+- `name` is required, 1 to 64 characters, lowercase letters, numbers and hyphens
+  only.
+- `name` must equal the directory name.
+- `description` is required and at most 1024 characters.
+
+Two more rules the validator does not catch but the parsers do:
+
+- **Keep `: ` out of the description.** The frontmatter parser splits each line
+  on its first colon and takes the rest verbatim, and a bare `: ` inside an
+  unquoted YAML scalar is invalid YAML besides. Use a hyphen or a comma.
+- **Keep the em-dash out of everything.** The project-wide rule in `AGENTS.md`
+  applies to skills as much as to UI copy. Older bundled skills still carry them
+  in their descriptions, which is drift, not licence.
+
+Optional fields `SkillMetadata` understands, beyond the five above:
+`disable-model-invocation`, `user-invocable`, `argument-hint`, `context: fork`,
+`agent`, `model`, `effort`, and a free-form `metadata` map.
+
+## Supporting files
+
+`getSkill()` reports three well-known subdirectories beside `SKILL.md`:
+
+- `scripts/` - runnable helpers the skill invokes (`stacks-browse` and
+  `stacks-wizard` both ship one)
+- `references/` - disclosed reference the body points at
+- `assets/` - templates, images, fixtures
+
+A sibling `.md` file with no directory works too, and is the lightest form of
+progressive disclosure: `stacks-technical-diagrams` keeps 36 of them.
+
+## Invocation
+
+Two choices, trading the two loads:
+
+- A **model-invoked** skill keeps its `description`, so the agent can fire it on
+  its own and other skills can reach it. The description is the skill's top-level
+  context pointer, forced to stay loaded at all times: permanent context load in
+  exchange for discoverability. A model-invoked skill whose content is all
+  reference is also the one home for shared reference, because another skill can
+  invoke it. Mechanics: omit `disable-model-invocation` and write a model-facing
+  description carrying the trigger branches. This is the default for the bundled
+  set, and the right choice for every subsystem reference.
+- A **user-invoked** skill strips the description from the agent's reach: only
+  the human typing its name can invoke it, and no other skill can. Zero context
+  load, but it spends cognitive load, because you are the index that must
+  remember it exists. Mechanics: set `disable-model-invocation: true`, and the
+  `description` becomes human-facing, a one-line summary with the trigger list
+  stripped. `stacks-flow` and `stacks-handoff` are the two bundled examples.
+
+Pick model-invocation only when the agent must reach the skill on its own, or
+another skill must. If it only ever fires by hand, make it user-invoked and pay
+no context load.
+
+Shared reference that two user-invoked skills both need can live in neither:
+with no descriptions, neither can fire the other. Push it to a plain file
+outside the skill system, or to a model-invoked reference skill both can reach.
+
+## Splitting by invocation
+
+The invocation cut, as opposed to the sequence cut in [SKILL.md](SKILL.md):
+split off a model-invoked skill when you have a distinct leading word that
+should trigger it on its own (a trigger word you actually type), or when another
+skill must reach it. `stacks-grilling` exists as its own skill for exactly that
+reason: `stacks-office-hours`, `stacks-plan-review` and `stacks-redesign` all
+call it. You pay context load for the new always-loaded description, so that
+independent reach has to be worth it.
+
+## Router skills
+
+When user-invoked skills multiply past what you can remember, that piled-up
+cognitive load is cured by a **router skill**: one user-invoked skill that names
+the others and when to reach for each, so the human has one skill to remember
+instead of many. `stacks-flow` is it. A router can only hint, never fire:
+user-invoked skills have no description, so nothing but the human can reach them.
+
+## Registering a project skill
+
+Nothing to register. `listSkills()` reads the directories, so a new
+`app/Skills/<name>/SKILL.md` is live the moment it exists. Re-run
+`buddy setup:ai <agent>` to link it into your agent's directory, and add a row to
+the feature-to-skill table in `AGENTS.md` so a human can find it too.

package/ai/skills/stacks-writing-for-agents/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: stacks-writing-for-agents
+description: Use when writing or editing any document an agent reads - a SKILL.md under app/Skills or storage/framework/defaults/ai/skills, the project AGENTS.md, or a reference file a skill points at. Covers context pointers, the information hierarchy, completion criteria, leading words, pruning, and the skill mechanics behind app/Skills and buddy setup:ai.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Writing for agents
+
+Reference for every document an agent consumes in a Stacks project: a skill, the
+project `AGENTS.md`, a doc reached by a pointer. The packaging differs, the
+writing does not. The same levers make each one predictable, because the agent
+takes the same *process* every run rather than producing the same output.
+
+Stacks ships 100+ skills and expects projects to add their own under
+`app/Skills/`, so this is the skill that keeps that set from turning to sludge.
+The Stacks-specific mechanics (frontmatter, invocation, the override model,
+what `buddy setup:ai` does with the result) are in
+[MECHANICS.md](MECHANICS.md). Everything below is universal.
+
+Credit: the model in this skill is adapted from Matt Pocock's `writing-for-agents`
+skill (MIT), <https://github.com/mattpocock/skills>.
+
+## Context pointers
+
+A **context pointer** is a reference held in the agent's context that names some
+out-of-context material and encodes the condition for reaching it. A skill's
+`description` is one. A line in `AGENTS.md` naming a doc is the same object. The
+pointer's *wording*, not its target, decides when the agent reaches the material
+and how reliably. A must-have target behind a weakly worded pointer is a variance
+bug: sharpen the wording first, and inline the material only if sharpening fails.
+
+A pointer does two jobs: state what the material is, and list the **branches**
+that should trigger reaching it (a branch is a distinct case the document
+handles, so different runs take different paths through it). Every word of an
+always-loaded pointer costs on every turn, so it earns harder pruning than the
+body:
+
+- **Front-load the leading word.** The pointer is where it does its triggering work.
+- **One trigger per branch.** Synonyms that rename a single branch are one branch
+  written twice. Collapse them, keep only genuinely distinct branches.
+- **Cut identity the body already carries.** `stacks-queue`'s description does not
+  need to explain what a queue is.
+
+The bundled skills follow one shape, and yours should too: `Use when <situation>
+- <branch>, <branch>, <branch>. Covers <package> and <config file>.` The
+trailing `Covers` clause is doing pointer work, not decoration: it is how an
+agent holding a package name (`@stacksjs/cache`) or a path (`config/queue.ts`)
+finds the skill that owns it.
+
+## The two loads
+
+Every document and pointer you add spends one of two budgets:
+
+- **Context load** is the cost of always-loaded material on the agent's window:
+  an `AGENTS.md` line, a skill description, anything sitting in context every
+  turn, spending tokens and attention whether or not it fires.
+- **Cognitive load** is the cost on the human: which documents exist and when to
+  reach for each. The human is the index. Not a cost to minimise, it is the
+  price of human agency. Spend it where human judgement matters, remove it where
+  it does not.
+
+Material reached only through a pointer escapes context load at the price of the
+pointer's own line. Material with no pointer at all rides entirely on cognitive
+load.
+
+## Information hierarchy
+
+A document is built from two content types: **steps** (the ordered actions the
+agent performs) and **reference** (definitions, rules, facts consulted on
+demand). The two mix freely: all steps (`stacks-new-feature`), all reference
+(`stacks-orm`), or both (`stacks-investigate`). The core decision is where each
+piece sits on the **information hierarchy**, a ladder ranked by how immediately
+the agent needs the material:
+
+1. **In-file step** is the primary tier: what the agent does, in order.
+2. **In-file reference** is consulted on demand. Often a legitimately flat
+   peer-set (every rule of a review on one rung), which is a fine arrangement,
+   not a smell.
+3. **Disclosed reference** is pushed into a separate file, reached by a context
+   pointer, loaded only when the pointer fires. Spans a sibling file in the same
+   skill directory through fully external reference any document can point at.
+
+Push too little down and the top bloats. Push too much and you hide material the
+agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder so the top stays legible.
+Not primarily a token optimisation: it is how the hierarchy is protected.
+Branching is the cleanest disclosure test: inline what every branch needs, push
+behind a pointer what only some branches reach. `stacks-technical-diagrams`
+keeps 36 reference files beside one `SKILL.md` for exactly this reason.
+
+**Co-location** is the within-file companion. Where the ladder decides *how far
+down* a piece sits, co-location decides *what sits beside it* once there. Keep a
+concept's definition, rules and caveats under one heading rather than scattered,
+so reading one part brings its neighbours with it. The test: the document should
+read like documentation written for the agent.
+
+**Sprawl** is the failure mode: a document simply too long, even when every line
+is live and unique. Attention thins across the excess, and every extra line is
+one more to keep relevant. The cure is the ladder.
+
+## Steps and completion criteria
+
+Every step ends on a **completion criterion**, the condition that tells the agent
+the work is done. Two properties make it a lever:
+
+- **Clarity.** Can the agent tell done from not-done? A vague bound
+  ("understanding reached") invites **premature completion**: ending the step
+  before it is genuinely done, attention slipping to *being done*. The visible
+  steps still ahead supply the pull, the criterion's clarity is the resistance.
+  Defend in order: sharpen the bound first (local and cheap), and only if it is
+  irreducibly fuzzy *and* you observe the rush, hide the later steps by splitting
+  the sequence. Hiding only works across a real context boundary (a hand-off or a
+  subagent dispatch). An inline call leaves the later steps in context and clears
+  nothing.
+- **Demand.** How much the criterion requires. "Every changed model accounted
+  for" forces thorough work where "produce a change list" does not. Demand drives
+  **legwork**, the digging the agent does within the work, latent in the wording
+  rather than written as its own step. It is not step-bound: "every rule applied"
+  binds a body of flat reference just as "every step done" binds a sequence,
+  which is how an all-reference document still carries an exhaustiveness bar.
+
+The strongest criteria are both checkable and exhaustive. `stacks-investigate`
+Phase 1 is the model to copy: one command, already run once, output shown.
+
+## When to split
+
+Splitting one document into two spends one of the two loads, so split only when
+the cut earns it:
+
+- **By sequence.** Split a run of steps where the post-completion steps tempt the
+  agent to rush the one in front of it. Keeping them out of view drives more
+  legwork on the current task. Beware the reverse: merging sequences exposes each
+  step's later steps to what follows, inviting premature completion.
+- **By invocation.** Skill-specific, see [MECHANICS.md](MECHANICS.md).
+
+## Leading words
+
+A **leading word** is a compact concept already living in the model's
+pretraining that the agent thinks with while running the document (*lesson*,
+*fog of war*, *tracer bullet*, *seam*). Repeated as a token, never as a
+sentence, it accumulates a distributed definition and anchors a whole region of
+behaviour in the fewest tokens by recruiting priors the model already holds.
+Coining your own works if you define it clearly, but a made-up word recruits no
+priors: you pay in definition tokens what a pretrained word gives free. Reach
+for an existing word first.
+
+It anchors twice. In the body, *execution*: the agent reaches for the same
+behaviour every time the word appears. In a pointer, *invocation*: when the same
+word lives in your prompts, your docs and your codebase, the agent links that
+shared language to the material and reaches it more reliably. This is why the
+Stacks skills insist on `trait`, `driver`, `action`, `seam` and `tracer bullet`
+rather than paraphrasing them.
+
+Hunt for opportunities to refactor with leading words. A triad spelled out at
+three sites, a pointer spending a sentence to gesture at one idea. Each is a
+passage begging to collapse into a single token:
+
+- "fast, deterministic, low-overhead" becomes *tight* (a *tight* loop).
+- "a loop you believe in" becomes *red*, turning a fuzzy gate into a binary
+  observable state (the loop goes *red* on the bug, or it does not).
+
+**Negation** is the failure mode beside this lever. Steering by prohibition drags
+the forbidden behaviour into context and makes it *more* available, not less.
+*Do not think of an elephant*, and the elephant is all there is. Prompt the
+**positive**: state the target behaviour ("use signals and composables in stx
+templates") so the banned one is never spoken. A prohibition earns its place only
+as a hard guardrail you cannot phrase positively, and even then, pair it with the
+positive target so attention lands on what to do.
+
+## Pruning
+
+- Keep each meaning in a **single source of truth**: one authoritative place, so
+  changing the behaviour is a one-place edit. **Duplication** costs maintenance
+  and tokens, and inflates a meaning's prominence on the ladder past its real
+  rank. It is the accidental inverse of a leading word, which repeats a token on
+  purpose, never the meaning.
+- The **environment** is a source of truth too, and in a Stacks project it is a
+  rich one: `buddy list`, `buddy <command> --help`, `config/*.ts`, the
+  `storage/framework/*-auto-imports.json` manifests, the generated
+  `storage/framework/types/*.d.ts`. A document that restates it is a **cache**: a
+  copy of a lookup, earning its load only when the lookup is expensive. Cache
+  what the agent cannot find by looking (the unwritten convention, the reason
+  behind a choice, the gotcha no config confesses) and leave the one-command
+  lookups to the environment, where they cannot go stale. Every bundled skill's
+  `## Gotchas` section is this rule applied.
+- Check every line for **relevance**: does it still bear on what the document
+  does? A line loses relevance by never bearing on the task, or by going stale as
+  the code it describes changes. Without a pruning discipline the default fate is
+  **sediment**: stale layers that settle because adding feels safe and removing
+  feels risky.
+- Hunt **no-ops** sentence by sentence: an instruction the model already obeys by
+  default pays load to say nothing. The test (does it change behaviour versus the
+  default?) is model-relative, not reader-relative. Two people disagreeing about
+  a no-op disagree about the default, and settle it by running the document, not
+  by debate. When a sentence fails, delete the whole sentence rather than trim
+  words from it. The test also grades leading words: a word too weak to beat the
+  default (*be thorough*, when the agent is already thorough-ish) is a no-op, and
+  the fix is a stronger word (*relentless*), not a different technique.
+
+## Before you finish
+
+- Every line changes behaviour versus the default.
+- Every meaning lives in exactly one place.
+- The description names distinct branches, front-loads the trigger, and carries
+  the `Covers` clause.
+- Nothing in the body restates what `buddy <command> --help` or a config file
+  already says.
+- No em-dash anywhere in the file (the project-wide rule in `AGENTS.md`).
+- `bunx --bun pickier .` is clean if you touched code alongside it.
+
+## Downstream
+
+> Reach for `stacks-retro` after a session to find which documents actually
+> failed, and `stacks-flow` when the problem is that nobody remembers a skill
+> exists.

package/app/Actions/Auth/GenerateTwoFactorSecretAction.ts

@@ -2,10 +2,11 @@ import { Action } from '@stacksjs/actions'
 import { generateTwoFactorSetup, stashPendingTwoFactorSecret } from '@stacksjs/auth'
 import { config } from '@stacksjs/config'
 import { response } from '@stacksjs/router'
+import { toSvg } from 'ts-qr-codes'
 
 export default new Action({
   name: 'GenerateTwoFactorSecretAction',
-  description: 'Generate a new TOTP secret + otpauth URI for the authenticated user to scan',
+  description: 'Generate a new TOTP secret, otpauth URI and scannable QR code for the authenticated user',
   method: 'POST',
   async handle(request: RequestInstance) {
     const user = await request.user()
@@ -21,6 +22,15 @@ export default new Action({
     // two-factor.ts's doc comment for why.
     await stashPendingTwoFactorSecret(user.id as number, secret)
 
-    return response.json({ secret, uri })
+    // Rendered here rather than left to the client. Every authenticator flow
+    // needs the URI as a QR code, and a caller that has to find its own
+    // encoder either ships one to the browser or, more often, falls back to
+    // asking the user to type a 32-character secret by hand.
+    //
+    // SVG so it stays sharp at any size and can be inlined into a page or an
+    // email; the URI is still returned for clients that render their own.
+    const qr = toSvg(uri, { size: 240, title: 'Two-factor authentication setup' })
+
+    return response.json({ secret, uri, qr })
   },
 })

package/app/Actions/Commerce/Shipping/{DriverDestroyAction.ts → CourierDestroyAction.ts}

@@ -4,19 +4,19 @@ import { response } from '@stacksjs/router'
 import { commerceIdentifier, commerceNotFound } from '../commerce-action'
 
 export default new Action({
-  name: 'Driver Destroy',
-  description: 'Driver Destroy ORM Action',
+  name: 'Courier Destroy',
+  description: 'Courier Destroy ORM Action',
   method: 'DELETE',
   async handle(request: RequestInstance) {
-    const identifier = commerceIdentifier(request, 'Driver')
+    const identifier = commerceIdentifier(request, 'Courier')
     if (identifier.error)
       return identifier.error
     const { id } = identifier
 
-    const deleted = await shippings.drivers.destroy(id)
+    const deleted = await shippings.couriers.destroy(id)
     if (!deleted)
-      return commerceNotFound('Driver', id)
+      return commerceNotFound('Courier', id)
 
-    return response.json({ message: 'Driver deleted successfully' })
+    return response.json({ message: 'Courier deleted successfully' })
   },
 })

package/app/Actions/Commerce/Shipping/{DriverIndexAction.ts → CourierIndexAction.ts}

@@ -5,11 +5,11 @@ import { shippings } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
 
 export default new Action({
-  name: 'Driver Index',
-  description: 'Driver Index ORM Action',
+  name: 'Courier Index',
+  description: 'Courier Index ORM Action',
   method: 'GET',
   async handle() {
-    const results = await shippings.drivers.fetchAll()
+    const results = await shippings.couriers.fetchAll()
 
     return response.json(results)
   },