Integrate DX docs into existing docs/ tree and CI skills

- AGENTS.md becomes a thin router into docs/ and .agents/skills
- Move local-service-dev facts to docs/cli/local-development.md (indexed)
- Fold pre-ci/codegen/check-ci-gates into get-started + CI contracts doc
- Reconcile pnpm pre-ci (full parity) with cli-pre-submit-ci minimal-derived default
- Remove orphan docs/LOCAL_DEV.md

Author: dmerand

.agents/skills/_shared/shopify-cli-ci-repo-contracts.md

@@ -25,6 +25,12 @@ For normal PR CI work, start with `.github/workflows/tests-pr.yml`.
 - Generated outputs are often part of the required change set when a workflow step verifies cleanliness after regeneration.
 - `dev.yml` is a useful local workflow entrypoint, but workflow YAML is the source of truth for what CI actually enforces.
 
+## Local pre-submit tooling
+
+- `pnpm pre-ci` runs the local subset of PR gates at full CI parity (type-check, lint, build, knip, codegen freshness, unit tests). It is heavier than routine work needs; prefer the minimal diff-derived set below, and reach for `pre-ci` when the user wants full confidence before a high-risk push.
+- Codegen freshness is single-sourced in `package.json`: `pnpm codegen` regenerates all generated files; `pnpm codegen:check:graphql` / `:oclif` regenerate and assert a clean tree. The workflow's `graphql-schema` and `oclif-checks` jobs call these scripts, so local and CI cannot drift.
+- `bin/ci-gates.js` is the source of truth mapping each `tests-pr.yml` job to a `pre-ci` command or a `ci-only` reason. `pnpm check-ci-gates` (CI job `CI gate manifest`) fails if a workflow job is unclassified or if the Node/pnpm versions in `dev.yml` and `tests-pr.yml` disagree.
+
 ## Gotchas
 
 - Do not guess from a check name alone when the workflow or job definition is available.

.agents/skills/cli-pre-submit-ci/SKILL.md

@@ -35,7 +35,7 @@ If the diff clearly maps to a narrow family, keep the investigation narrow.
 |---|---|
 | docs/config/wiring only, with no obvious workflow-enforced generator family | **stop there unless contradicted**: run lightweight sanity checks only (`git diff --check`, validate changed symlink targets, validate local markdown links if relevant); do not full-read large workflow/script files |
 | user is at PR time (`submit`, `open`, `update`, `restack`) | advisory mode: suggest minimal checks, staging needs, and likely CI risk; ask before running anything substantial |
-| user asks what to run before push | recommend the minimal high-signal checks implied by the workflow |
+| user asks what to run before push | recommend the minimal high-signal checks implied by the workflow; mention `pnpm pre-ci` as the full-parity option for a high-risk push |
 | user asks what to commit or stage | reproduce the relevant generator/check path, then inspect git status and diffs |
 | user explicitly asks to run checks | run the minimal derived set, not the whole world |
 
@@ -75,7 +75,7 @@ After any generator, freshness check, or lightweight sanity pass:
 
 ## Gotchas
 
-- At PR time, do **not** automatically run the full workflow-equivalent validation set unless the user asks.
+- At PR time, do **not** automatically run the full workflow-equivalent validation set unless the user asks. `pnpm pre-ci` is that full set — offer it for high-risk pushes, but default to the minimal derived checks.
 - `dev.yml` is a useful local entrypoint, but workflow YAML is the source of truth for what CI enforces.
 - Broad generated diffs are not automatically wrong; distinguish required churn from suspicious churn.
 - Do not stop at “run this command.” Explain what likely needs staging.

AGENTS.md

@@ -3,44 +3,19 @@ See @.cursor/rules/docs.mdc for Shopify CLI architecture and conventions.
 
 # Working in Shopify CLI
 
-Guidance for contributors and coding agents to get a change green in CI with the fewest round-trips. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for changesets/versioning and [`docs/LOCAL_DEV.md`](./docs/LOCAL_DEV.md) for running the CLI locally.
+Entry point for contributors and coding agents. Canonical docs live under [`docs/`](./docs/README.md) and agent skills under [`.agents/skills/`](./.agents/skills); this file routes to them rather than restating them.
 
-## Before you push: `pnpm pre-ci`
+## Before you push
 
-Run the local subset of the PR pipeline before pushing:
+- Derive the minimal checks for your diff with the [`cli-pre-submit-ci`](./.agents/skills/cli-pre-submit-ci/SKILL.md) skill. For full local CI parity (slower), run `pnpm pre-ci`.
+- After changing commands, flags, or GraphQL queries, run `pnpm codegen` and commit the regenerated files.
+- `pnpm check-ci-gates` keeps the local gate list ([`bin/ci-gates.js`](./bin/ci-gates.js)) and pinned tool versions in sync with the workflow.
 
-```bash
-pnpm pre-ci      # or: dev pre-ci
-```
+## Key docs
 
-It runs, in CI-parity order: `type-check`, `lint`, `build`, `knip`, the graphql and OCLIF/docs codegen freshness checks, and unit tests — and prints which CI-only gates it skips (e2e, type-diff, breaking-change detection) and why. It mirrors CI's full targets, so green locally implies green in CI; it is slower than the affected-only `dev check`.
-
-The gate list lives in [`bin/ci-gates.js`](./bin/ci-gates.js) and is kept in sync with `.github/workflows/tests-pr.yml` by `pnpm check-ci-gates` (enforced by the `CI gate manifest` CI job). When you add or change a CI gate, update that manifest.
-
-## After changing commands, flags, or GraphQL queries: `pnpm codegen`
-
-Generated files are gated in CI (`Check OCLIF manifests & readme & docs`, `Check graphql-codegen has been run`). Regenerate and commit them:
-
-```bash
-pnpm codegen                 # regenerate everything
-pnpm codegen:check:oclif     # regenerate + verify the tree is clean (as CI does)
-pnpm codegen:check:graphql
-```
-
-## Linting
-
-Use the repo's lint command, not `eslint` directly:
-
-```bash
-pnpm lint        # nx-driven; matches the CI "Lint" job
-pnpm lint:fix    # auto-fix
-```
-
-Invoking `eslint <file>` directly can report problems CI does not enforce (and CI lints project sources, not root `bin/` scripts). Repo-specific lint conventions are implemented in [`packages/eslint-plugin-cli/rules/`](./packages/eslint-plugin-cli/rules) (for example, `no-vi-manual-mock-clear` — Vitest resets mocks automatically, so do not clear them by hand). Check there when a rule is unfamiliar rather than guessing.
-
-## Tests
-
-```bash
-pnpm test                              # full vitest run (single env; CI runs a node/OS matrix)
-pnpm vitest run path/to/file.test.ts   # a single file
-```
+- [Get started / setup and scripts](./docs/cli/get-started.md)
+- [Local development against services](./docs/cli/local-development.md)
+- [ESLint rules](./docs/cli/eslint-rules.md)
+- [Testing strategy](./docs/cli/testing-strategy.md)
+- [Cross-OS compatibility](./docs/cli/cross-os-compatibility.md)
+- [Changesets and versioning](./CONTRIBUTING.md)

docs/LOCAL_DEV.md

@@ -11,6 +11,7 @@ The Shopify CLI is a tool for merchants, partners, and developers to interact wi
 The list below contains valuable resources for people interested in contributing to the CLI project in this repository.
 
 * [Get started](./cli/get-started.md)
+* [Local development against services](./cli/local-development.md)
 * [Architecture](./cli/architecture.md)
 * [Conventions](./cli/conventions.md)
 * [Performance](./cli/performance.md)

docs/README.md

@@ -72,5 +72,10 @@ Besides the scripts for building and running the CLIs, there are others that mig
 - `pnpm lint:fix`: Runs ESLint and Prettier checks for all the packages and fixes the fixable issues.
 - `pnpm type-check`: Type-checks all the packagesusing the Typescript `tsc` tool.
 - `pnpm clean`: Removes the `dist` directory from all the packages.
+- `pnpm pre-ci`: Runs the local subset of PR CI gates (type-check, lint, build, knip, codegen freshness, unit tests) at full parity with CI. Slower, for a high-risk push; for routine PRs derive the minimal checks for your diff (see the `cli-pre-submit-ci` agent skill).
+- `pnpm codegen`: Regenerates all generated files (GraphQL types, OCLIF manifests, README, docs). Run after changing commands, flags, or queries, and commit the result.
+- `pnpm check-ci-gates`: Verifies the local CI-gate manifest stays in sync with the GitHub Actions workflow.
+
+Prefer these scripts over invoking `eslint`/`prettier`/`tsc` directly: CI runs them through Nx over package sources, not over root `bin/` scripts.
 
 All the packages in the repository contain the above scripts so they can be executed too for an individual package.

docs/cli/get-started.md

@@ -0,0 +1,18 @@
+# Local development against services
+
+Most contributions run against production Shopify services. When developing against a local services stack, the CLI changes behavior based on the service environment.
+
+## Service environment
+
+- `SHOPIFY_SERVICE_ENV=local`
+- `SHOPIFY_CLI_NEVER_USE_PARTNERS_API=1`
+
+In local mode the CLI maps a store's `{store}.my.shop.dev` host to `admin.shop.dev/store/{store}` — see `packages/cli-kit/src/public/node/context/fqdn.ts`.
+
+## Running the CLI
+
+See [Get started](./get-started.md) for building and running the CLI (`pnpm shopify <command>`) and the available scripts.
+
+## Before opening a PR
+
+Derive the minimal pre-submit checks for your diff (see the `cli-pre-submit-ci` agent skill), or run `pnpm pre-ci` for full local CI parity. After changing commands, flags, or GraphQL queries, run `pnpm codegen` and commit the regenerated files.