Add example standards, template and CI format checks

.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'The examples in this repository obey STANDARDS.md in the root directory. Read that file before you add or change an example. It is written in Simplified Technical English (ASD-STE100), and new example documentation must use the same style. The CI pipeline checks the format with .prettierrc and ruff.toml. Run those checks before you commit.'",
+            "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

@@ -2,21 +2,25 @@
 
 Example applications and companion code for Shotstack guides and tutorials.
 
-Clone this repo, or head into the folder for the example you want. Each example has its own README with the API keys and setup steps it needs.
+Clone this repository, or open the directory of the example you want. Each example has its own README. The README gives the API keys and the setup steps for that example.
 
 ## Examples
 
 - [instagram-ai-video](examples/instagram-ai-video) generates a script, voiceover and background image with AI, renders a 1080x1920 video, and publishes it as an Instagram Reel. Companion code for [How to automate Instagram posts with AI video](https://shotstack.io/learn/automate-instagram-posts-with-ai-video/).
 - [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
+
+To make a new example, copy [`examples/_template`](examples/_template). Then read [STANDARDS.md](STANDARDS.md). It gives the rules for API keys, failures, README structure, and the checks to do before you make 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:
+Install the Shotstack CLI and its skill before you use a coding agent, such as Claude Code, on these examples:
 
 ```bash
 npm install -g @shotstack/cli
 npx skills add shotstack/shotstack-cli
 ```
 
-The skill gives the agent the Edit JSON authoring conventions, which are easy to get wrong from instinct. `shotstack validate <file>` then lints a template offline, no API key and no render credits. See the [agent guide](https://shotstack.io/docs/guide/agents/cli/).
+The skill gives the agent the rules to write Edit JSON. These rules are easy to get wrong. The `shotstack validate <file>` command then checks a template on your computer. It does not need an API key, and it does not use render credits. For more data, see the [agent guide](https://shotstack.io/docs/guide/agents/cli/).

STANDARDS.md

@@ -0,0 +1,81 @@
+# Standards for cookbook examples
+
+All the code in this repository is public. Developers copy it into their own projects. These rules make the
+examples consistent and safe to copy.
+
+To make a new example, copy the `examples/_template/` directory.
+
+## Structure
+
+- Put each example in its own directory in `examples/`.
+- Each example must run after a new clone of the repository. Do not add steps that are not in the README of
+  the example.
+- The `name` in `package.json` must be the same as the directory name.
+- If the example has a `package.json`, give the minimum Node version in `engines`. The minimum version for
+  the repository is in `.nvmrc`.
+- If the example has no `package.json`, no tool can check the minimum version. Do not put flags in the README
+  that need a specific version of Node. Use environment variables.
+
+## API keys
+
+- Read the API key from an environment variable.
+- Do not put a key in the code. Do not print a key. Do not commit a key.
+- Add a `.env.example` file. Put example values in it.
+- For a Next.js example, name the file `.env.local.example`. Next.js reads `.env.local`.
+- Add the real environment file to `.gitignore`.
+
+## Format and lint
+
+- The `.prettierrc` file in the root directory controls the format of the JavaScript, TypeScript, JSON, CSS
+  and Markdown files.
+- The `ruff.toml` file controls the format of the Python files.
+- If the example has a `package.json`, add a `format` script.
+- The CI pipeline does `prettier --check` and `ruff check` for each pull request. Do these commands on your
+  computer first.
+
+## Failures
+
+An example can fail for these usual reasons:
+
+- The user did not set the API key.
+- The API rejected the key.
+- The network failed.
+
+For each of these failures, the example must print one line that tells the user what to do. Then the example
+must stop with an exit code that is not zero. Do not let the example print a stack trace.
+
+Most users get the first failure, because they forgot to set the API key. Give the most attention to that
+failure.
+
+## README structure
+
+Use these sections, in this sequence, in each README:
+
+1. What the example does, and a link to the related guide if there is one
+2. Requirements
+3. Setup
+4. How to run the example
+5. What happens when you run it
+
+Write as few statements of fact as possible. Each version number, flag and command in a README is a statement
+that must stay correct.
+
+Write the documentation in Simplified Technical English (ASD-STE100). Many readers of this repository do not
+have English as their first language. Obey these rules:
+
+- Write short sentences. Use a maximum of 20 words in an instruction, and 25 words in a description.
+- Write one instruction in each sentence.
+- Use the active voice. Write "Set the API key", not "The API key must be set".
+- Use the same word for the same thing each time.
+- Do not use idioms, metaphors or humour.
+
+## Before you make a pull request
+
+You must read the code and run it before you make a pull request. Then do these checks:
+
+1. Clone the repository again. Run the example with no API key. Read the message.
+2. Run the example with an incorrect API key. Read the message.
+3. Do each command in your README, in the correct sequence.
+4. Run the formatter and the linter.
+5. If the example is in two languages, compare the two files. If they are different, one of them is
+   incorrect.

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,44 @@
+# Example name
+
+What the example does. Write one or two sentences. Tell the user what they get at the end.
+
+Related guide: [Guide title](https://shotstack.io/learn/...). Remove this line if there is no guide.
+
+## Requirements
+
+- A [Shotstack account](https://dashboard.shotstack.io/register) and an API key
+- Each other tool that the example needs, and its 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. What to do with the result.
+
+---
+
+Remove this line and all the text below it.
+
+Keep the five sections above, in this sequence.
+
+The `STANDARDS.md` file in the root directory gives the rules for all the examples. It tells you how to use
+API keys, how to format the code, and what the example must do when it fails. It also lists the checks to do
+before you make a pull request.
+
+Add a `package.json` file only if the example has dependencies. If you add one, set `engines` and a `format`
+script.