chore: add example standards, template and CI format checks

Author: dazzatronus

.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Examples in this repo follow STANDARDS.md at the root — read it before adding or changing one. Formatting and linting are enforced in CI by .prettierrc and ruff.toml; run them before committing.'",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

.github/workflows/check.yml

@@ -0,0 +1,25 @@
+name: check
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+jobs:
+  format-and-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+
+      - run: npx prettier@3 --check .
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      # Passes trivially until an example ships Python.
+      - run: pip install ruff==0.16.1 && ruff check .

README.md

@@ -10,6 +10,10 @@ Clone this repo, or head into the folder for the example you want. Each example
 - [rapidreels](examples/rapidreels) creates faceless short-form videos using generative AI. [View demo](https://shotstack.io/demos/social-media-video-maker/).
 - [reelestate](examples/reelestate) turns static real estate images into fully edited video slideshows. [View demo](https://shotstack.io/demos/real-estate-video-listing-maker/).
 
+## Contributing
+
+New example? Copy [`examples/_template`](examples/_template) and read [STANDARDS.md](STANDARDS.md) — it covers credential handling, failure behaviour, README shape, and what to check before opening a pull request.
+
 ## Editing with an AI agent
 
 If you are working on these examples with Claude Code or another coding agent, install the Shotstack CLI and its skill first:

STANDARDS.md

@@ -0,0 +1,55 @@
+# Standards for cookbook examples
+
+Everything here is published code that strangers copy into their own projects. These rules keep the examples
+consistent and safe to copy. New examples start by copying `examples/_template/`.
+
+## Structure
+
+- One example per directory under `examples/`. Self-contained: it runs from a fresh clone with no steps
+  beyond the ones in its own README.
+- The `name` in `package.json` matches the directory name.
+- Declare a Node floor in `engines` wherever an example has a `package.json`. The repo floor is `.nvmrc`.
+- An example with no `package.json` has no machine-checkable floor, so its README must not document flags
+  that depend on a specific runtime version. Use plain environment variables instead.
+
+## Credentials
+
+- Read keys from the environment. Never hard-code one, never print one, never commit one.
+- Ship a `.env.example` with placeholder values. Next.js examples use `.env.local.example`, because that is
+  the file Next loads.
+- Gitignore the real env file.
+
+## Formatting and linting
+
+- `.prettierrc` at the root governs JavaScript, TypeScript, JSON, CSS and Markdown. `ruff.toml` governs
+  Python.
+- Every example with a `package.json` exposes `npm run format`.
+- CI runs `prettier --check` and `ruff check` on every pull request. Run both locally first.
+
+## Failure behaviour
+
+Expected failures — no API key set, a rejected key, a network error — print one line the reader can act on
+and exit non-zero. A stack trace on any of those paths is a bug. The missing-key path is the most common
+first-run experience an example has, so it deserves the most care.
+
+## README shape
+
+The same order in every example, so a reader can skim any of them:
+
+1. What it does, in a sentence or two, with a link to the companion guide where one exists
+2. Requirements
+3. Setup
+4. Run
+5. What happens when you do
+
+Prefer fewer claims to more. Every version number, flag and command in a README is a promise somebody has to
+keep true.
+
+## Before you open a pull request
+
+Whoever opens the pull request has read and run the code in it. Before asking for review:
+
+- Run the example from a fresh clone with no credentials set, then with a wrong key, and read what it prints.
+- Copy every command out of your README and run it, in the order written.
+- Run the formatter and the linter.
+- Where the same flow ships in two languages, diff them. A disagreement means one of the two is wrong.

examples/_template/.env.example

@@ -0,0 +1 @@
+SHOTSTACK_API_KEY=your_api_key

examples/_template/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.env

examples/_template/README.md

@@ -0,0 +1,40 @@
+# Example name
+
+What it does, in a sentence or two. Say what a reader gets at the end of it.
+
+Companion code for [Guide title](https://shotstack.io/learn/...) — delete this line if there is no guide.
+
+## Requirements
+
+- A [Shotstack account](https://dashboard.shotstack.io/register) and your API key
+- Anything else the example needs, with the minimum version
+
+## Setup
+
+```bash
+git clone https://github.com/shotstack/shotstack-cookbook.git
+cd shotstack-cookbook/examples/<name>
+```
+
+```bash
+export SHOTSTACK_API_KEY="your_api_key"
+```
+
+## Run
+
+```bash
+<the command>
+```
+
+## What happens
+
+What the example prints, how long it takes, and what to do with the result.
+
+---
+
+Delete this line and everything below it.
+
+Keep the five sections above, in this order. `STANDARDS.md` at the repo root has the rules that apply to
+every example — credential handling, failure behaviour, formatting, and what to check before opening a pull
+request. Add a `package.json` only if the example has dependencies; if it does, set `engines` and a `format`
+script.