grails-cli 0.0.0-stage → 0.3.0

package/LICENSE.md

@@ -0,0 +1,250 @@
+# Grails CLI: terms of use
+
+Copyright (c) 2026 Grails Services LLC. All rights reserved.
+
+`grails-cli` (the "Software") is proprietary software. It is not open source.
+
+## What you may do
+
+You may install the Software and run it, free of charge, to work with Grails (https://grails.design): to read your
+own code and send its design tokens and component specs to your own Grails account, from your computer or from your
+CI. Using Grails itself is covered by the Grails Terms of Service (https://grails.design/terms).
+
+## What you may not do
+
+No other right is granted. Without the written permission of Grails Services LLC you may not:
+
+- copy the Software, except as installing it requires;
+- modify it, or make anything derived from it;
+- redistribute, sublicense, sell, rent or host it;
+- use it for anything other than working with Grails.
+
+## No warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL GRAILS SERVICES LLC BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+## Third-party software
+
+The Grails terms above do not apply to the open-source packages that `dist/cli.js` includes. Each is used under its
+own license, reproduced below as that license requires. (`typescript` is not included: it is installed next to the
+Software as a dependency, under its own license.) The CLI also includes the Design Tokens Community Group's JSON
+Schemas for the format and the resolver, version 2025.10, published at https://www.designtokens.org.
+
+### ajv 8.20.0 (MIT)
+
+The MIT License (MIT)
+
+Copyright (c) 2015-2021 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+### ajv-formats 3.0.1 (MIT)
+
+MIT License
+
+Copyright (c) 2020 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+### colorjs.io 0.7.1 (MIT)
+
+MIT License
+
+Copyright (c) 2021 Lea Verou, Chris Lilley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+### fast-deep-equal 3.1.3 (MIT)
+
+MIT License
+
+Copyright (c) 2017 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+### fast-uri 3.1.8 (BSD-3-Clause)
+
+Copyright (c) 2011-2021, Gary Court until https://github.com/garycourt/uri-js/commit/a1acf730b4bba3f1097c9f52e7d9d3aba8cdcaae
+Copyright (c) 2021-present The Fastify team <https://github.com/fastify/fastify#team>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * The names of any contributors may not be used to endorse or promote
+      products derived from this software without specific prior written
+      permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+                                  *   *   *
+
+The complete list of contributors can be found at:
+- https://github.com/garycourt/uri-js/graphs/contributors
+
+### json-schema-traverse 1.0.0 (MIT)
+
+MIT License
+
+Copyright (c) 2017 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+### nanoid 3.3.20 (MIT)
+
+The MIT License (MIT)
+
+Copyright 2017 Andrey Sitnik <andrey@sitnik.ru>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+### picocolors 1.1.1 (ISC)
+
+ISC License
+
+Copyright (c) 2021-2024 Oleksii Raspopov, Kostiantyn Denysov, Anton Verinov
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+### postcss 8.5.28 (MIT)
+
+The MIT License (MIT)
+
+Copyright 2013 Andrey Sitnik <andrey@sitnik.es>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,280 @@
-# Temporary Holding Version
+# grails-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Grails Code Sync from the command line: `grails-cli` reads a component library's code and uploads its design
+tokens and each component's spec to [Grails](https://grails.design), so the vault shows what the code actually
+holds, next to Figma. The product is Grails Code Sync the way the Figma plugin is Grails Sync; this is its
+command line. Full documentation: https://docs.grails.design/cli/overview/
+
+**Requirements:** Node 20 or newer. The package is free to install and use with Grails; see `LICENSE.md`.
+
+```bash
+npm i -D grails-cli          # or run it without installing: npx grails-cli <command>
+
+npx grails-cli scan  /path/to/library              # the manifest of components
+npx grails-cli tokens /path/to/library             # the design tokens Grails would read; sends nothing
+npx grails-cli sync  /path/to/library --dry-run    # what would be uploaded; sends nothing, needs no key
+
+export GRAILS_API_KEY=grails_sk_…                  # see "The key"
+npx grails-cli sync  /path/to/library
+npx grails-cli status
+```
+
+The examples below write `grails-cli`; use `npx grails-cli` if it is not installed globally.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `scan [root] [--out f] [--profile f] [--tier syntax\|typed] [--in-repo]` | The manifest (stdout without `--out`). Refuses to write it inside a git repository unless `--in-repo`. Exits 1 when the scan is incomplete. |
+| `chi [root] [--profile f] [--tier …] [--json]` | The Component Health Index of every component, worst first. |
+| `check-classes [root] [--unknown] [--json]` | Probable Tailwind typos; exits 1 when there is one. |
+| `init [root] [--write] [--force]` | Proposes a `grails.code.json` from the code, with the evidence. |
+| `tokens [root] [--profile f] [--json]` | The design tokens Grails would read (a Tailwind theme, CSS listed in the profile's `css`, token sources in its `tokens`), and every value left out. `--json` is the exact token list a sync uploads. Sends nothing, needs no key. |
+| `tokens baseline [root] --out <dir> [--in-repo] [--profile f]` | The scanner's tokens as DTCG files and a resolver, a first DTCG version for the team to own (see "Moving from the scanner to DTCG"). Writes only where `--out` says, refuses a path inside a git repository unless `--in-repo`, and never touches a folder that has files. Sends nothing, needs no key. |
+| `sync [root] [--dry-run] [--json] [--trigger ci\|local] [--profile f] [--tier …] [--name n] [--platform p]` | **Tokens first, then components, in one step.** Records the tokens in one request, then opens a component sync, sends the components, finalizes, and prints the result and the vault link. See "Exit codes". |
+| `status` | The code sources of the key's project, with the last component sync and the last token sync of each. |
+| `tokens pending [root] [--name n] [--limit 1..1000] [--json]` | The token changes people asked for in Grails, by collection, before → after. Writes nothing (see "Changes asked for in Grails"). |
+| `rules [root] [--set code=figma \| --delete code \| --threshold n] [--json]` | The naming rules of the Code ↔ Figma match (see "Naming rules"). |
+| `skill` | Prints the agent skill the package ships (`templates/skill/grails-cli/SKILL.md`), for a team to save where its coding agent reads skills. Sends nothing, writes nothing. |
+
+### `sync`
+
+**Only from the declared branch.** `grails.code.json` says which branch IS the
+source in Grails: `"branch": "main"` (or `preview`, or whatever merges land on); `init` proposes the branch the
+checkout is on. A real sync:
+- **without a declared branch** is refused before anything is read (exit 2), with that sentence;
+- **on another branch** uploads nothing and exits **0**, so a pull request's job stays green, and says so where a CI
+  shows it: the terminal, the job summary, a `::notice` on the run, and the step outputs `result=skipped-branch` and
+  `exit_code=0` (`GITHUB_OUTPUT`). A detached checkout is judged by `CI_COMMIT_REF_NAME` / `GITHUB_REF_NAME`, so a
+  GitHub pull request run (`<number>/merge`) is "another branch"; a folder that is not a checkout has no branch;
+- **on the declared branch** syncs as below, and writes `result=synced` (or `failed`, with its exit code).
+A dry run is never held back: it stores nothing. The server enforces the version that carries this guard: the two
+storing routes refuse a CLI older than 0.2.0 with 400 `GRAILS_CODE_CLI_OUTDATED` (exit 3).
+
+**Tokens go first.** The token list is read and
+recorded with `POST /v1/code/token-syncs` in one request. Grails builds the DTCG document from it and answers what
+changed against the source's previous snapshot; the same content is stored once. A token step that fails (a
+project Grails cannot read, the server refusing the list) does **not** stop the components: they sync anyway, and
+the run exits with the token step's code. Then the components:
+
+1. **Opens** the sync with every component key the scan found (`declared_keys`). That is how the server tells a
+   component deleted from the code from one that failed to arrive.
+2. **Sends** the components in requests of at most 50 components and 1 MB (the API refuses more than 50, and
+   accepts 2 MB). Grails answers the open with the hash of the spec it already holds for each key; the spec
+   travels **only** for a key that is new or whose hash differs.
+3. **Finalizes** with the scan's own `complete`. Only a complete scan lets the server mark anything deleted, and
+   even then it refuses to delete 5 or more components and more than 20 % of the source in one sync.
+   Since 0.3.0 the finalize also carries **what each component uses** (canonical entities D1): the components of
+   the same source it renders, resolved with the TypeScript checker to their keys, and the tokens its styles
+   reference, as the collection and name of the token list just recorded. Grails keeps them as edges of the
+   project graph. They are sent only when the tokens were read and recorded (or there are none): otherwise Grails
+   keeps the usage it had. A reference no token of the source answers to (a framework default, a source missing
+   from `grails.code.json`) is counted in a warning and not sent.
+
+If a sync fails after it was opened, the CLI closes it as incomplete before raising the error. Otherwise it stays
+open for two hours and the next run of the same source (a CI retry) is answered "another sync is running".
+
+The **source** (what Grails calls this library) is named after the package's own `name`, so it is the same on a
+laptop and in CI; `--name` sets another one, for a monorepo whose packages share nothing else. The platform is
+`react-native` when the package depends on React Native or Expo or any file imports `react-native`, and `web`
+otherwise; `--platform` overrides. The commit and branch come from git when the root is in a checkout (the branch
+from `CI_COMMIT_REF_NAME` or `GITHUB_REF_NAME` when the checkout is detached, as GitLab's is). `--trigger` is `ci`
+when `CI=true` and `local` otherwise.
+
+### `--dry-run`, `--json` and the job summary
+
+- **`--dry-run` with `GRAILS_API_KEY` set** asks Grails what each step would change, through the preview routes
+  (`POST /v1/code/token-syncs:preview`, `POST /v1/code/syncs:preview`), which store nothing: tokens added, changed
+  and removed; components added, changed, reactivated and **those that would be deleted**, with the same floor the
+  real sync applies.
+- **`--dry-run` without the key** counts locally and sends nothing, as it always did.
+- **`--json`** prints one report on stdout (`mode`, `tokens`, `components`, `exit_code`); the human lines go to
+  stderr, so the output can be piped.
+- **In GitHub Actions** (`GITHUB_STEP_SUMMARY` is set) the same report is appended to the job summary: counts,
+  and the changed tokens and would-be-deleted components folded. There is no comment on a pull request.
+
+No state is written to the repository: what Grails holds is the only source of truth, and the comparison is
+always against it.
+
+### Code ↔ Figma
+
+After a real sync records the tokens, `sync` asks Grails how they compare with the Figma ones
+(`GET /v1/code/token-match`) and prints one line: same, differ, conflicts, by value only, only in code, only in
+Figma, and the colour threshold it used (ΔE2000, 1.5 by default). The job summary adds the table, what differs,
+the conflicts (code tokens that disagree about one design token, never resolved) and the **suggested** naming
+rules, which are never applied: naming rules live in Grails, not in this repository.
+
+- A project with no Figma snapshot yet says so instead of calling every token missing.
+- A dry run does not ask: Grails would compare the code tokens it already stores, not the ones on disk.
+- It is a report, not a step of the sync: a failure is said and kept in the report, and the exit code does not change.
+
+### Naming rules
+
+A naming rule tells the match that a word of your code is another word in Figma: `gray` in the code is `neutral`
+in Figma. Rules belong to one source and live in Grails, never in the repository: the CLI,
+the REST API and MCP all edit the same rules.
+
+    grails-cli rules                      # this source's rules and the project's colour threshold
+    grails-cli rules --set gray=neutral   # create, or move its target; the same rule twice is one rule
+    grails-cli rules --delete gray
+    grails-cli rules --threshold 2        # ΔE2000 under which two colours are equal, for the whole project
+
+The source is named as `sync` names it (`--name`, else the package name, else the folder). Listing needs the
+usual key; editing needs a key with the `write:tokens` scope. The job summary of a sync lists the rules applied
+and the ones Grails suggests from tokens with the same value and one different word.
+
+### Changes asked for in Grails
+
+In Grails, an admin or an editor can ask for changes to this repository's tokens: a new value, a new token,
+collection or mode, a removal. **Grails never writes your repository, and neither does this CLI.**
+
+    grails-cli tokens pending               # by collection, before → after, as DTCG values
+    grails-cli tokens pending --json        # the list as Grails answers it, every value exact
+    grails-cli tokens pending --limit 1000  # the read answers 500 by default, at most 1000
+
+Carry each change into your token source, or into the rules that generate it (a Style Dictionary build, a Tokens
+Studio export, your CSS). ⚠️ **A change carried over still shows as pending for now:** marking it applied when a sync
+shows the repository says the same is designed but not live yet (it comes with the token comparison in the sync).
+
+An sRGB colour shows as its hex and a dimension as `24px`; anything else shows as its DTCG JSON, and `--json` has the
+exact components. The source is named as `sync` names it (`--name`, else the package name). It needs the usual key (`write:code`).
+
+### Exit codes
+
+A contract a CI step can branch on. Only 4 is worth retrying. A sync on another branch is 0; its own
+result, `skipped-branch`, is in the step output `result` (see `sync` above), since any other code would turn the step
+red.
+
+| code | meaning | retry? |
+|---|---|---|
+| 0 | done: synced, nothing changed, or a dry run | – |
+| 1 | the component sync ran and ended incomplete (unreadable components, or deletions held back) | no: read the warnings |
+| 2 | misconfigured: a flag, `grails.code.json` (including no declared `branch` on a real sync), no key, or a project Grails cannot read (its own tailwindcss missing, or of a major other than 3 and 4) | no: fix it |
+| 3 | the server refused it: the key, the plan, content it does not accept, or a CLI older than the minimum (400) | no: fix it |
+| 4 | the server could not be reached or failed (network, 5xx, a 429 after one retry) | yes |
+
+### Where the tokens come from
+
+**The team's own DTCG files, when `grails.code.json` names them** (the official way in):
+
+    "dtcg": { "files": ["tokens/**/*.json"], "resolver": "tokens/resolver.json" }
+
+- **One source.** With `dtcg`, these files are the only token source. Nothing is read from Tailwind, CSS or `tokens`,
+  and a run that also lists `css` or `tokens` says so.
+- **Sent as written.** `sync` uploads them as they are (`dtcg: { files, resolver? }` with `client: grails-cli`), and
+  the API reads them with `@grails/dtcg`'s `readDtcg`.
+- **Checked here first**, so a wrong repository sends nothing (exit 2):
+  - the file count (500) and the body size (4 MiB);
+  - a file outside the resolver's folder (a resolver names its files from where it is, so every key is relative to it);
+  - two keys that differ only in case;
+  - JSON that does not parse.
+- **What the API refuses comes back as findings** (422, or 413 for a limit). The run prints each one with the file the
+  person knows and its JSON pointer, and exits 3.
+- **Usage.** Component uses still go with the finalize. Token uses do not: nothing tells which DTCG token a style's
+  `var(--x)` is, and guessing it from the spelling would be a heuristic, so the CLI does not. The run says so.
+
+**Without `dtcg`, the scanner reads** (a convenience for a first sync):
+
+- **A Tailwind 3 theme**, read with the **project's own** `tailwindcss` (`loadConfig` + `resolveConfig`), defaults
+  included. ⚠️ That executes `tailwind.config.*`, as the project's build does. Install the project's dependencies
+  first (`npm ci`): without them the run exits 2, and never reads the theme with a copy of its own.
+- **Tailwind 4**: the `@theme` stylesheet, read with the project's `tailwindcss` (`__unstable__loadDesignSystem`),
+  defaults included; its CSS variables become a collection with a mode per selector (`:root` light, `.dark` dark).
+- **CSS files** listed in `grails.code.json`'s `css`, read with postcss.
+- **TypeScript token objects and enums** listed in `grails.code.json`'s `tokens`.
+
+`calc()` is computed (DTCG has no expressions). Values it cannot express are left out and listed, never guessed.
+
+**Text styles** are tokens too (`typography`, one per style, all five fields): a Tailwind 4 `--text-X` with its
+`--text-X--line-height`, `--letter-spacing` and `--font-weight`; a Tailwind 3 `theme.fontSize` entry (`[size]`,
+`[size, lineHeight]` or `[size, { lineHeight, letterSpacing, fontWeight }]`); or a TypeScript object with a
+`fontSize` and another typography key. Each field says where it comes from: the style's own value, a token it
+inherits (the family of `fontFamily.sans`), a CSS rule that is not a token (`body { font-family }`), or CSS's initial
+value (weight 400, letter spacing 0). An `em` letter spacing is converted against the size and keeps its spelling. A
+family written as a `next/font` variable becomes the font the layout names, marked as a heuristic. A style that
+cannot be formed (no family to inherit, a size that is not a length) is left out and listed.
+
+#### Moving from the scanner to DTCG: `tokens baseline`
+
+    grails-cli tokens baseline --out ../acme-tokens                # outside the repository: nothing else to say
+    grails-cli tokens baseline --out tokens --in-repo              # inside it: only because you asked
+
+The scanner's tokens, written as the DTCG files and the resolver Grails' own export writes (`exportProject` from
+`@grails/dtcg`, through the same conversion the API runs, `fromCodeUpload`). It is the team's first DTCG version
+: review the files, commit them, and declare them in `dtcg`. From then on the team owns its
+generation rules and the scanner stops being the source. The command prints the `dtcg` block to
+add and lists the values left out, which are not in the files: the ones the scanner could not express (the list
+`tokens` prints, with the reason for each) and what the DTCG export could not carry.
+
+- **It writes only where `--out` says.** A folder inside the git repository also needs `--in-repo`, exactly like
+  `scan --out`. A folder that already has files is refused: a baseline never overwrites anything.
+- **It refuses while `dtcg` is set.** Those files are the token source, and a baseline from the scanner would compete
+  with them (exit 2).
+- **A round trip pins it:** what `readDtcg` reads back from the files equals
+  `snapshotProject` of the scanner's upload, a text style included: its five fields and where each comes from.
+
+## The key
+
+`GRAILS_API_KEY` is read from the environment **and from nowhere else**. A flag would land in the shell history,
+in the process list and in a CI log that prints the command line, so the CLI refuses any flag that looks like a
+credential (`--api-key`, `--token`, …) before it reads anything. It goes in one header, is never printed, and is
+scrubbed from everything the CLI prints in case an upstream message echoes it.
+
+Create it in **Team Settings › Integrations › API Keys** with the `write:code` scope. It is a personal key: if its
+owner is demoted to viewer or leaves the team the key is **deleted**, and the API answers it like a key that never
+existed (`GRAILS_AUTH_INVALID_TOKEN`). The CLI says so in those words.
+
+`GRAILS_API_URL` points the CLI at another API (default `https://api.grails.design`; the docs' `…/v1` form is
+accepted). `http://` is accepted only for this machine, and a redirect is never followed, so the key cannot be sent
+to an address nobody chose.
+
+One retry on a network error, and one on a `429` after the `retry_after_seconds` the API gives. The Worker counts
+rate limits but does not block yet, so no real `429` exists today: that retry is the contract's, not a measured
+behaviour. Opening a sync is retried only when the connection was *refused*: if the server may have received it, a
+second open would be answered "another sync is running" and the first would hold the source for two hours.
+
+## What leaves the repository
+
+An allow-list, built field by field (never a copy with fields deleted), enforced again by the
+API and a last time by the database:
+
+- the source: name, platform, package name, and the repository address **without userinfo, query or fragment**
+  (`https://gitlab-ci-token:<token>@gitlab.com/…` and `?private_token=…` are what a CI checkout's remote can look
+  like; an SSH remote becomes its `https://` address, or is dropped);
+- git: the commit sha and the branch;
+- per component: key (`<file>#<export>`), name, file path, export name, the spec hash and **the spec**, the
+  stories summary (files, titles, count, tags), the coverage numbers, `unresolved` as `{ what, line }` and other
+  props as `{ name, kind }`;
+- at finalize, per component: the keys of the components of the same source it renders, and the collection and
+  name of each token its styles reference.
+
+The spec is the component's public API: prop names, their values, types as declared, anatomy names and resolved
+style values. It is what a design system documents. **Not** sent: source code, the CHI (the server computes it),
+`unresolved[].detail` (it quotes a fragment of the code), `otherProps[].tsType`, the scan root, any absolute path.
+`sync --dry-run` prints what would go, in counts and bytes, and sends nothing.
+
+**Tokens:** token names, their declared type, a literal or an alias per mode, and the file each came from, relative
+to the root. Not sent: file contents, comments, absolute paths, or any environment value a Tailwind config reads
+outside its theme. `grails-cli tokens --json` prints exactly what would go.
+
+**With `dtcg`, the files go whole.** The token half sends the DTCG files `dtcg.files` matches, and the resolver, as
+they are written: every `$description`, `$extensions` and `$deprecated` in them goes too. Grails keeps the
+descriptions and the extensions with each token. Their keys are paths relative to the resolver's folder (or to the
+root), never absolute. Only the files the globs match leave; `node_modules` and dot folders are never walked.
+`grails-cli tokens --json` prints the upload exactly.
+
+## The GitHub workflow
+
+`templates/grails-cli-sync.yml` (in this package, and shown in Grails under Team Settings › Integrations) runs
+`npx --yes grails-cli sync --trigger ci` on a push to the branch under `branches:` (`main` by default), which must
+be the one `grails.code.json` declares. Copy it to `.github/workflows/grails-cli-sync.yml`. Its step has
+`id: grails`, so a later step reads `steps.grails.outputs.result`.
+The key reaches it through the step's `env:` from a repository secret named `GRAILS_API_KEY`, and never appears in a
+`run:` line. Do not run it on `pull_request`: a fork's run has no secrets and no business syncing.
+
+A new release of the CLI can change what a push uploads. To choose when that happens, pin a version in the
+workflow: `npx --yes grails-cli@<version> sync --trigger ci`.
+
+## License
+
+Proprietary. You may install and use `grails-cli` to work with Grails; no other right is granted. See `LICENSE.md`.