grails-cli 0.0.0-stage → 0.4.0

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "grails-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Grails Code Sync from the command line: reads a component library's code and uploads its design tokens and component specs to Grails.",
+  "license": "UNLICENSED",
+  "homepage": "https://docs.grails.design/cli/overview/",
+  "keywords": [
+    "grails",
+    "design-system",
+    "design-tokens",
+    "dtcg",
+    "components",
+    "figma",
+    "react",
+    "tailwind",
+    "cli",
+    "code-sync"
+  ],
+  "packageManager": "pnpm@10.32.1",
+  "type": "module",
+  "bin": {
+    "grails-cli": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "typescript": "5.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.27.7"
+  }
+}

package/templates/grails-cli-sync.yml

@@ -0,0 +1,56 @@
+# Grails Code Sync: on every push to the branch your team syncs from (a merge into it), read this repository's
+# design tokens and components and upload them to Grails, so the vault shows what the code actually holds.
+#
+# SETUP
+#   1. In Grails, create an API key with the write:code scope: Team Settings > Integrations > API Keys.
+#   2. Save it as a repository secret named GRAILS_API_KEY: Settings > Secrets and variables > Actions.
+#   3. Say in grails.code.json which branch syncs ("branch": "main", or "preview", …): `npx grails-cli init`
+#      proposes it. Put the SAME branch under `branches:` below.
+#   4. Commit this file as .github/workflows/grails-cli-sync.yml.
+#
+# THE KEY stays in the step's `env:`. It is never written into a `run:` line, never echoed, and never passed as
+# an argument: the CLI reads it from the environment and refuses it as a flag. Do not change that, and do not run
+# this on `pull_request`, where a fork's run has no secrets and no business syncing.
+#
+# WHAT LEAVES THE REPOSITORY: design tokens (names, types, values), component names, file paths, and each
+# component's spec (props, anatomy names, resolved style values). Never source code. `npx grails-cli tokens
+# --json` prints the exact token list. `sync --dry-run` stores nothing: with the key it asks Grails what would
+# change, without it it counts locally.
+#
+# EXIT CODES: 0 done · 1 the sync ended incomplete · 2 misconfigured (grails.code.json declares no branch, too) · 3
+# refused by the server (a CLI older than the minimum, too) · 4 the server could not be reached or failed. Only 4 is
+# worth retrying.
+#
+# THE BRANCH: the CLI uploads only from the branch grails.code.json declares. Run anywhere else it uploads nothing,
+# exits 0 so the job stays green, and says so: a notice on the run, the job summary, and the step output
+# `steps.grails.outputs.result` = `skipped-branch` (otherwise `synced`, `preview`, `offline` or `failed`).
+#
+# THE VERSION: `npx --yes grails-cli` fetches the latest release from npm on every run. To choose when a new release
+# reaches your pushes, pin a version (`grails-cli@<version>`) so a new release cannot change a push you did not look at.
+name: Grails Code Sync
+
+on:
+  push:
+    # The branch grails.code.json declares. Keep the two equal.
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      # Needed when the library uses Tailwind (its tokens are read with the project's OWN tailwindcss; without the
+      # dependencies installed the run exits 2), and better in any case: with them the scanner reads the types the
+      # way the project does (the "typed" run). Use your package manager's command.
+      # - run: npm ci
+      - name: Sync the design tokens and the components to Grails
+        id: grails
+        env:
+          GRAILS_API_KEY: ${{ secrets.GRAILS_API_KEY }}
+        run: npx --yes grails-cli sync --trigger ci

package/templates/skill/grails-cli/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: grails-cli
+description: Use when working with the Grails CLI (`grails-cli`) in a component library's repository. That covers setting up `grails.code.json`, syncing components and design tokens to Grails from a terminal or from CI, writing DTCG token files that Grails accepts, starting a first DTCG version from the scanner's tokens, listing the token changes people asked for in Grails, and fixing a sync that failed. Triggers on grails-cli, grails.code.json, Grails Code Sync, GRAILS_API_KEY, DTCG upload, design tokens to Grails, tokens pending, tokens baseline.
+---
+
+# The Grails CLI
+
+Grails (grails.design) keeps a design system's Figma files and its code side by side. This CLI reads your
+component library's repository (its components and its design tokens) and syncs them to a Grails project.
+
+**It never changes your code.** It writes only the files you explicitly ask it to: `init --write` writes
+`grails.code.json`, `scan --out <file>` writes the manifest, and `tokens baseline --out <dir>` writes the scanner's
+tokens as DTCG files (both refuse a path inside the repository unless you pass `--in-repo`). When people in Grails ask
+for a token change, the CLI lists the change, and you or your build make it in your own source.
+
+## Install
+
+`npm i -D grails-cli` in the repository (Node 20 or newer), or run any command without installing it as
+`npx grails-cli <command>`. The commands below are written `grails-cli`. The GitHub workflow template the package
+ships (`templates/grails-cli-sync.yml`) runs `npx --yes grails-cli sync`: pin a version in it (`grails-cli@<version>`)
+to choose when a new release reaches your pushes.
+
+## Commands
+
+| command | what it does | sends anything? |
+|---|---|---|
+| `grails-cli init [root] [--write]` | proposes a `grails.code.json` from the code, with the evidence for each decision | no |
+| `grails-cli scan [root] [--out <file>]` | writes the component manifest Grails would receive | no |
+| `grails-cli tokens [root] [--json]` | the design tokens a sync would upload (with `dtcg`: the files, or the exact upload with `--json`) | no |
+| `grails-cli tokens baseline [root] --out <dir> [--in-repo]` | writes the scanner's tokens as DTCG files and a resolver, a first version to own | no |
+| `grails-cli sync [root] [--dry-run] [--json]` | uploads the tokens, then the components | yes (with `--dry-run`: asks what would change, stores nothing) |
+| `grails-cli tokens pending [root] [--collection <name>] [--request <id>] [--json]` | the token changes people asked for in Grails: type, before → after, and the id; the filters narrow it | reads only |
+| `grails-cli tokens discard <change-id> \| --all [--collection <name>] \| --request <id> --reason "<why>" [--dry-run]` | closes one change, or a set in one step, that your team will not carry, with the reason | yes (Grails keeps the changes, closed); `--dry-run` changes nothing |
+| `grails-cli rules [root] [--set code=figma]` | the naming rules that match code tokens to Figma ones | edits need `write:tokens` |
+| `grails-cli connect [--prompt]` | keeps the API key in the operating system's keychain (checked against Grails first) so no command needs `GRAILS_API_KEY`; reads the clipboard and clears it, or with `--prompt` asks in a hidden prompt | reads only (one authenticated read to validate the key) |
+| `grails-cli disconnect` | removes the key `connect` stored (the key itself is not revoked) | no |
+| `grails-cli update [root]` | asks the npm registry now for the latest `grails-cli` and prints the command that updates it for the project's package manager; it does not run it | asks the npm registry only |
+| `grails-cli status` | the project's code sources, their last syncs, and how many changes asked for in Grails wait for each | reads only |
+| `grails-cli chi [root]` | the Component Health Index of every component | no |
+| `grails-cli check-classes [root]` | Tailwind classes that are probably misspelt | no |
+| `grails-cli skill` | prints this file | no |
+
+**The API key** is read from `GRAILS_API_KEY` in the environment (CI, and anyone who prefers it) and, when that is not
+set, from the operating system's keychain, where `grails-cli connect` put it; and from nowhere else. Never pass it as a
+flag or an argument, and never print the environment. To create one, go to Team Settings › Integrations › API Keys in
+Grails and give it the `write:code` scope. `GRAILS_API_URL` points the CLI at another API; the keychain keeps one key
+per API, by its host.
+
+**An agent does not run `connect` for the person.** `connect` takes the key from the person's clipboard or from a hidden
+prompt on their terminal; a key an agent was handed in a chat is already in a transcript, so it does not go to
+`connect --prompt` either. When there is no key, tell the person to run `grails-cli connect` in their own terminal (or to set
+`GRAILS_API_KEY`), and carry on with the commands that need none (`init`, `scan`, `tokens`, `sync --dry-run`).
+
+**Updates.** Once a day the CLI asks the npm registry for the latest version and, while it is behind, every run ends with
+one line on stderr naming the two versions and the update command. That line is not an error and does not change the
+exit code. `GRAILS_CLI_NO_UPDATE_CHECK=1` turns it off. `grails-cli update` prints the command and never runs it: update
+the version only when the person asks.
+
+## `grails.code.json`
+
+```json
+{
+  "branch": "main",
+  "components": ["src/components/**/*.tsx"],
+  "exclude": ["**/*.stories.tsx"],
+  "dtcg": { "files": ["tokens/**/*.json"], "resolver": "tokens/resolver.json" }
+}
+```
+
+- **`branch`** is required for a real sync. It names the branch that IS this source in Grails: the one merges land
+  on. Run anywhere else, the sync uploads nothing and exits 0.
+- **`components`** and **`exclude`** are globs, relative to the root.
+- **`dtcg`** names your DTCG files. **When it is set, it is the only token source**: the scanner reads no token from
+  Tailwind or CSS, and `css` and `tokens` are ignored with a warning.
+  - `files` are globs of `.json` files.
+  - `resolver` is optional, and is a DTCG resolver document. Its `$ref`s name the files relative to its own folder,
+    so every file must sit in or below that folder.
+  - `cssVariables` is optional: how your CSS names the tokens, so Grails can tell which token a `var(--x)` is. It holds
+    the `prefix` of your build, the `exceptions` to the naming, and `ignore`, patterns for custom properties that are
+    not your tokens. See "Telling Grails which token a `var(--x)` is".
+- **`css`** (CSS files whose custom properties are tokens) and **`tokens`** (TypeScript token objects) are for the
+  scanner, when there is no `dtcg`.
+
+## Tokens: two ways in
+
+1. **DTCG files (the recommended way).** Generate them with your tool of choice: a Style Dictionary build,
+   Tokens Studio's DTCG export, Specify, your own script. Declare them in `dtcg`, and `sync` uploads them as they are.
+   Grails reads them and answers with precise findings when it cannot.
+2. **The scanner (a convenience).** With no `dtcg`, the CLI reads a Tailwind 3 or 4 theme, the CSS custom properties
+   of the files in `css`, and the token objects in `tokens`. It is good for a first sync. Anything it does not
+   support should be exported to DTCG rather than worked around. To move to DTCG, run `tokens baseline --out <dir>`,
+   review the files, commit them and declare them in `dtcg`. From then on the files are yours and the scanner stops
+   being the source. The command lists the values the scanner left out (they are not in the files), refuses to run while
+   `dtcg` is set, and never writes into a folder that has files.
+
+With DTCG, a sync records which components each component renders, and which tokens it uses **only through a `var(--x)`
+that `cssVariables` ties to a token** (next section). Every `var(--x)` it cannot tie is listed, so you can fix it.
+
+## Telling Grails which token a `var(--x)` is
+
+*This section is written for a coding agent that is asked to set it up. Follow the steps in order, and never guess a
+name.*
+
+Your components write `var(--color-brand-500)`; your DTCG files say `color.brand.500`. With `dtcg` declared, the scanner
+reads no token, so the only thing that ties the two is how your build names a token's custom property. Grails assumes
+**Style Dictionary's default**, the `css` transform group (`name/kebab`):
+
+- the token's path segments, joined with `-`, lower case, behind two dashes: `color.brand.500` is `--color-brand-500`;
+- with the build's `prefix` first: `prefix: "ds"` makes it `--ds-color-brand-500`;
+- camelCase is split (`fontSize` → `font-size`, `h1Bold` → `h1-bold`), but **a digit stays with its letters** (`2xl`
+  stays `2xl`, `body2` stays `body2`);
+- anything that is not a letter or a digit is a separator (`Brand Primary`, `brand_primary` and `brand-primary` all give
+  `brand-primary`);
+- the name is **case-sensitive**: `var(--Color-Brand-500)` is no token, because the build writes lower case.
+
+Where a name does not follow that, you write an **exception**: the custom property and the token it is. A custom
+property that is **not your token at all** (a library's, the framework's) goes in **`ignore`**, as a pattern.
+
+```json
+{
+  "dtcg": {
+    "files": ["tokens/**/*.json"],
+    "resolver": "tokens/resolver.json",
+    "cssVariables": {
+      "prefix": "ds",
+      "exceptions": { "--brand": "color.brand.500", "--surface": "color.semantic.surface" },
+      "ignore": ["--radix-*", "--tw-*"]
+    }
+  }
+}
+```
+
+All three keys are optional. An exception's value is the token's dotted path in the files (the first segment is its
+collection). **An exception wins over the convention**, and one that names a path the files do not have is reported.
+
+**`ignore` is a list of patterns**: a name as `var()` writes it, two dashes first, with `*` for the part that varies
+(`*` is the only wildcard, and at most 200 patterns). A name an `ignore` pattern covers is not resolved, not counted,
+not listed and never sent, **even when the convention would have found a token of that name**; an exception for the same
+name wins over `ignore`. A pattern that covers nothing the components use is not an error: `--json` lists it in
+`css_variables.ignore_unused`, and the terminal line says how many were ignored (`· 14 ignored`), never which.
+
+**The steps:**
+
+1. **Look at how the repository builds its CSS from the DTCG files.** Find the Style Dictionary configuration
+   (`config.json`, `style-dictionary.config.*`, `sd.config.*`, or a script that calls it) and read, for the CSS platform,
+   its `prefix`, its `transformGroup` and its `transforms`. Then open the CSS it generates and look at a few real names:
+   a name in the output beats a reading of the configuration.
+   - `transformGroup: "css"` (or `name/kebab` in `transforms`), and no custom `name` transform: the convention applies.
+   - `name/camel`, `name/snake`, `name/constant`, `name/pascal` or a custom `name` transform: the names do not follow
+     the convention, and each one a component uses needs an exception.
+2. **Set the prefix**: `"cssVariables": { "prefix": "<the build's prefix>" }`, and leave it out when the build has none.
+3. **Run `grails-cli sync --dry-run`.** It needs no key and sends nothing (with a key it also asks Grails what
+   would change). `--json` adds a `css_variables` object with the same list. The line `css variables` counts the custom
+   properties your components use and how many resolve to a token.
+4. **Read the unresolved list** (the `!` lines under it), and decide each one:
+   - `var(--x) is no token of the DTCG files`: find where `--x` comes from, and choose by who owns it.
+     - **It is your token under another name**: generated from a DTCG token, or an alias of a generated one
+       (`--x: var(--ds-color-brand-500)`). Add it to **`exceptions`** with that token's path. An exception says what a
+       name IS.
+     - **It is not your token, and never will be**: a library's, the framework's, one the page sets at run time. Add a
+       pattern that covers the family to **`ignore`**, so the list holds only what a person still has to decide.
+       Examples that are common: Radix sets sizes for its popovers and menus
+       (`--radix-dropdown-menu-content-available-height`, `--radix-select-trigger-width`: pattern `--radix-*`);
+       Tailwind's own internals, which a component reads when it writes a ring or a shadow by hand
+       (`--tw-ring-color`, `--tw-ring-offset-color`: pattern `--tw-*`); a value the page sets from JavaScript (`--vh`,
+       `--scroll-y`). A custom property one component declares for itself (`--card-padding`) is also not a token: ignore
+       it, by name or by a prefix that component's team already uses.
+     - **You cannot tell which of the two it is**: do not ignore it and do not guess an exception. Leave it listed and
+       ask the person.
+   - `var(--x) is the name of N tokens`: two tokens spell the same CSS name (`brandPrimary` and `brand-primary`).
+     Read the generated CSS to see which one the build keeps (the last declaration wins), and add that one to
+     `exceptions`. Better, rename one of them in the DTCG files.
+   - `dtcg.cssVariables.exceptions: --x names color.y, which is not a token of the DTCG files`: the exception is
+     mistyped, or the token was renamed or removed. Fix its path (`grails-cli tokens --json` prints the files) or
+     delete the exception.
+   - `whose name has a "/"`: a level of that token's name contains a `/`, which a usage upload cannot spell. Rename the
+     level in the DTCG files.
+5. **Run step 3 again** until every remaining `!` line is one you decided to leave for the person. Then tell them what
+   you added to `exceptions` and to `ignore` and what you left, with the reason for each.
+6. **Prune** with `grails-cli sync --dry-run --json`: `css_variables.ignore_unused` lists the patterns that ignored
+   nothing (no component uses a name they cover, or an exception already names every such name). Delete those.
+
+**Keep `ignore` narrow.** A pattern beats the naming convention, so `--*-bg` would hide a real token that happens to end
+in `-bg`: the token would no longer be tied to the components that use it, and the line would not say so. Cover a family
+by its owner's prefix (`--radix-*`), not by a shape (`--*-width`). If a name the pattern covers IS a token, add an
+exception for it: that is the way to keep one inside a broad pattern.
+
+**What this reads, and what it does not.** The scanner reads a `var(--x)` a component can use in three places:
+
+- **the `style` of any element** in the component, every property (`margin`, `border`, `boxShadow`, …) and not only
+  colour, padding and size; also the props libraries use for styles (`contentContainerStyle`, `css`, `sx`), a constant or
+  style sheet the style refers to, and every branch of a condition or lookup;
+- **the stylesheet the component's file imports** (`.css`, CSS modules, `.scss`, `.less`), for every component that file
+  holds. A custom property a rule *declares* in `:root`, a theme selector or `@theme` is a definition, not a use, so a
+  tokens sheet imported by a layout does not make the layout "use" every token. `@import` inside a stylesheet is not
+  followed;
+- **Tailwind classes** in `className` and in `cn`, `clsx`, `classnames`, `cx`, `twMerge` and `cva` calls, variants
+  included: `bg-[var(--x)]` in either version, `bg-(--x)` in Tailwind 4, `bg-[--x]` in Tailwind 3. (Tailwind 4
+  compiles `bg-[--x]` to a literal `--x`, not a `var()`, so it is not read there.)
+
+It does **not** read a name a template assembles at run time (`` `var(--space-${n})` ``), a class helper it does not know
+(`tv()`), CSS-in-JS template literals (styled-components, Emotion's `css` tag), a component a file defines but does not
+export, or a property set from JavaScript. So a custom property missing from the list may still be used. A reference
+that is not a `var()` (a Tailwind theme class such as `bg-primary`, a TypeScript token object) is counted in a line ("N
+token reference(s)… are not linked") but not tied to a token. A run never fails for any of this.
+
+**Do not** edit the token files or the CSS to make a line disappear: an exception, or a pattern in `ignore`, is the
+team's statement of what a name is, or that it is not theirs.
+
+## Writing DTCG that Grails accepts
+
+Grails reads the **DTCG format 2025.10** (designtokens.org) and validates every document against its schema.
+
+- **A token's path is its dotted name, and the first segment is its collection.** `color.brand.500` belongs to the
+  collection `color`. A token directly at the root (one segment) is refused.
+- **Types.** All 13 DTCG types are accepted: `color` (`{ "colorSpace", "components" }`), `dimension`
+  (`{ "value", "unit" }`), `number`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `strokeStyle`, `border`,
+  `transition`, `shadow` (one or a list, `inset` allowed), `gradient` and `typography`. A group's `$type` applies to
+  the tokens inside it.
+- **Aliases** are `{path}` references, at most 64 deep, with no cycles. A JSON Pointer `$ref` inside a value is
+  refused: use `{path}`.
+- **Modes.**
+  - With no resolver, each collection has one mode, `default`.
+  - With a resolver, its sets give every mode the same value, and a modifier's contexts become the collection's modes.
+  - Two or more modifiers give one mode per combination, named with `·` (`light·brand-a`), at most 50.
+  - A resolver's `$ref` names only a file of the same upload (or `#/sets/x`, `#/modifiers/x`). Nothing is fetched.
+- **Limits.**
+  - At most 500 files and 4 MiB in one upload.
+  - At most 20,000 values, 500 collections, 20 modifiers, 50 contexts per modifier, and groups 32 levels deep.
+  - The CLI checks the file count and the size before sending anything.
+- **Refused outright:**
+  - Tokens Studio's legacy format (`$themes`, `$metadata`, or `value` / `type` without `$`): export as DTCG (W3C).
+  - A `boolean` or object `$value` with no `$type`.
+
+**What DTCG cannot express.** The token stays valid DTCG, with a `$value` any tool can read, and the extra goes in
+`$extensions` under a `design.grails.*` key:
+
+- **Typography.** Use `design.grails.typography.extraProps`: `textCase`, `textDecoration`, `fontStyle`,
+  `paragraphSpacing`, `paragraphIndent`, `listSpacing`, `leadingTrim`.
+- **Booleans, copy strings, blurs and layout grids.** Use no `$type`, a readable string `$value` (`"true"`,
+  `"blur(4px)"`, `"12 columns, 24px gutter"`), and the real value in
+  `design.grails.value: { "type": "boolean" | "string" | "blur" | "grid", "value": … }`.
+- **A colour built from a colour and an opacity token.** Keep the applied colour in `$value`, and name the parts in
+  `design.grails.composed: { "color": "{path}" or a DTCG colour, "opacity": "{path}" }`. The opacity token is read
+  as it is: a Figma opacity is 0–100, so divide by 100.
+
+**What Grails does with them.**
+- It reads a token with `design.grails.value` as that type and that value. The extension wins over `$value`, so a
+  `$value` like `"{brand}"` there is text, not a reference.
+- It validates the forms above. A malformed one (a boolean whose value is `"yes"`, a `textCase` of `"shout"`) refuses
+  the sync with `extension_invalid` and the pointer. A `{path}` inside them that names no token is `alias_unknown`.
+- What it does not know (a key a form does not have, a value type it has never seen) is kept as written, with the
+  warning `extension_not_interpreted`, so a document a newer tool wrote loses nothing.
+
+When a sync is refused, each finding names the file, the JSON pointer inside it and a code (`schema_invalid`,
+`token_at_root`, `legacy_format`, `alias_unknown`, `alias_cycle`, `extension_invalid`, …). Fix the source and sync
+again.
+
+## Changes asked for in Grails
+
+Admins and editors can ask for token changes in Grails: a new value, a new token, collection or mode, or a removal.
+**Grails never writes your repository, and neither does the CLI.** Closing the loop takes three steps, and the last one
+is automatic:
+
+1. `grails-cli tokens pending` lists the changes by collection: each with its **type**, `before → after` as DTCG, and
+   its **id**. The `before` is the value your repository holds now, resolved (an alias in your code shows as the colour
+   it resolves to). `--json` has every value exact.
+2. Carry each change into your token source, or into the rules that generate it, and merge it as any other change.
+3. The next `grails-cli sync` (in CI, on the declared branch) **marks the change applied** once your repository holds
+   its value, and prints how many. Grails compares the resolved value of the token in that mode, with the tolerance the
+   Diff uses for colours and sizes, so an alias that resolves to the asked value counts. A token you removed closes
+   its change; a created token, collection or mode closes when it exists.
+
+To see what the next sync would do **before** it runs, use `grails-cli sync --dry-run` (with the key): it prints how many
+changes it would mark applied, close because their token is gone, or leave open, with their ids, and stores nothing.
+`grails-cli status` shows how many changes wait for each source.
+
+**If the repository holds another value, the change is not closed.** Grails keeps proposing its value, checks again on
+every sync, and records what your code holds: running `tokens pending` again after a sync shows the real "before".
+
+**A change your team will not carry is closed with a reason, not ignored:**
+
+```sh
+grails-cli tokens discard <change-id> --reason "Handled in the design-tokens repo"
+```
+
+- The id is the one `tokens pending` prints beside the change. Never invent one.
+- `--reason` is required: 1 to 1000 characters on one line. Say why, in words a designer reads: Grails keeps it with the
+  change, with who discarded it (the owner of the API key) and that it came from code.
+- Discarding a collection takes its modes and tokens with it. One value of a token being created cannot be discarded
+  alone: discard the token.
+- Exit 3 means Grails has no open change with that id for this source, or it was already applied or discarded. Do not
+  retry; list again with `tokens pending`.
+- Do it only when the team decided not to carry the change. If it only has not been carried yet, leave it: the sync
+  closes it when it arrives.
+
+**Many at once.** Exactly one of three picks the changes (the reason is required, as above):
+
+```sh
+grails-cli tokens discard --all --dry-run                              # look first: nothing is changed
+grails-cli tokens discard --all --reason "Handled in the tokens repo"  # everything waiting for this repository
+grails-cli tokens discard --all --collection color --reason "…"        # one collection's
+grails-cli tokens discard --request <request-id> --reason "…"          # one change request's
+```
+
+- `--dry-run` lists the changes that would be discarded (id, token, before → after) and changes nothing. Run it first
+  and read the list: there is no `--yes`, and a discard cannot be undone from the CLI.
+- The set is closed all together or not at all, and at most 1000 at once. Past that the CLI says so and discards
+  nothing: narrow it with `--collection` or `--request`.
+- `tokens pending --collection <name>` and `--request <id>` list exactly what the same words would discard. The request
+  id is printed under the heading of `tokens pending`.
+- `--collection` goes with `--all` only. Naming a change id and `--all` together is refused.
+- The answer says how many were discarded; `--json` has the ids. Exit 3 means a request or source Grails does not hold
+  (nothing was discarded) or a set over the cap.
+
+## In CI
+
+The package ships `templates/grails-cli-sync.yml`, a GitHub Actions workflow that runs `npx --yes grails-cli sync --trigger ci`
+on a push to the declared branch.
+
+- Store the key as the repository secret `GRAILS_API_KEY`. It reaches the step only through `env:`, never inside a
+  `run:` line.
+- Do not run it on `pull_request`.
+- The run writes a job summary, and the step output `result` is `synced`, `preview`, `offline`, `skipped-branch` or
+  `failed`.
+
+**Exit codes:**
+
+| code | meaning |
+|---|---|
+| 0 | done (synced, unchanged, or a dry run) |
+| 1 | the sync ended incomplete |
+| 2 | misconfigured: a flag, `grails.code.json` (no `branch`, a DTCG file that is not JSON or matches nothing), or the key |
+| 3 | refused by the server: the key, the plan, or the content (DTCG findings included) |
+| 4 | the server could not be reached or failed |
+
+Only 4 is worth retrying.