Document pre-submit workflow and local dev (AGENTS.md + docs/LOCAL_DEV.md)

.claude/CLAUDE.md

@@ -0,0 +1 @@
+../AGENTS.md

AGENTS.md

@@ -0,0 +1,46 @@
+See @.cursor/rules/base.mdc for your desired behavior.
+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.
+
+## Before you push: `pnpm pre-ci`
+
+Run the local subset of the PR pipeline before pushing:
+
+```bash
+pnpm pre-ci      # or: dev pre-ci
+```
+
+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
+```

docs/LOCAL_DEV.md

@@ -0,0 +1,41 @@
+# Local development
+
+How to set up and run Shopify CLI from a checkout. For the pre-submit workflow and lint/codegen guidance, see [`../AGENTS.md`](../AGENTS.md).
+
+## Setup
+
+```bash
+dev up      # installs the pinned Node + pnpm, dependencies, GraphQL schemas, and Playwright
+```
+
+`dev up` pins the same Node and pnpm versions CI uses (`dev.yml` ↔ `tests-pr.yml`, enforced by `pnpm check-ci-gates`), so your local runtime matches CI.
+
+## Running the CLI
+
+```bash
+pnpm shopify <command>      # builds the cli, then runs it (e.g. pnpm shopify app dev)
+dev shopify <command>       # same, via the dev command
+```
+
+`pnpm shopify` rebuilds the `cli` package first, so it reflects your latest changes.
+
+## Local service environment
+
+When developing against local services rather than production:
+
+```bash
+SHOPIFY_SERVICE_ENV=local
+SHOPIFY_CLI_NEVER_USE_PARTNERS_API=1
+```
+
+- **Admin URLs**: in local mode the CLI maps `{store}.my.shop.dev` to `admin.shop.dev/store/{store}` — see `packages/cli-kit/src/public/node/context/fqdn.ts`.
+
+## Theme check
+
+The `theme check` command wraps [`@shopify/theme-check-node`](https://github.com/Shopify/theme-tools). Entry point: `packages/theme/src/cli/commands/theme/check.ts`.
+
+## Before opening a PR
+
+- Run `pnpm pre-ci` (see [`../AGENTS.md`](../AGENTS.md)).
+- After changing commands, flags, or GraphQL queries, run `pnpm codegen` and commit the regenerated files.
+- For changesets and bump types, see [`../CONTRIBUTING.md`](../CONTRIBUTING.md).