@@ -15,7 +15,8 @@
     "ghcr.io/devcontainers/features/copilot-cli:1": {
       "version": "prerelease"
     },
-    "ghcr.io/devcontainers/features/github-cli:1": {}
+    "ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
   },
 
   "customizations": {
 
@@ -0,0 +1,22 @@
+# Copilot instructions for docs.github.com
+
+This repository powers the GitHub Docs site (docs.github.com). It contains both the Next.js application code (TypeScript) and the documentation content (Markdown).
+
+## Instruction files
+
+Read the relevant instruction files in `.github/instructions/` before making changes:
+
+* **`all.instructions.md`** — General project guidelines, PR conventions, and how to access docs.github.com content programmatically. Applies to all files.
+* **`code.instructions.md`** — TypeScript/JavaScript coding standards, test commands (per-suite with environment variables), and validation steps. Read this before any code change.
+* **`content.instructions.md`** — Markdown content conventions, Liquid variable usage, reusables, and linking with `[AUTOTITLE]`. Read this before any content change.
+* **`style-guide-summary.instructions.md`** — Condensed docs style guide covering voice, headers, lists, alerts, and formatting. Read this before any content change.
+
+## Key rules
+
+* All new code must be TypeScript (not JavaScript).
+* Use `@/` absolute imports (e.g., `import getRedirect from '@/redirects/lib/get-redirect'`).
+* Do not run `npm test` without a path argument — always target a specific suite.
+* Run `npm run build` before running tests.
+* Do not commit to `main`. Create a branch and open a draft PR.
+* Use Liquid variables for product names — never hardcode them. Check `data/variables/`.
+* Use `[AUTOTITLE](/path/to/article)` for internal links — never hardcode article titles.
@@ -24,13 +24,53 @@ For code reviews, follow guidelines, tests, and validate instructions. For creat
 
 We use `vitest` to write unit tests. Tests live in their own files in the `tests` subdirectory of a source (src) directory, e.g. `src/search/tests/api-ai-search.ts`. For integration tests, we can use the mock server in `src/tests/mocks/start-mock-server.ts` to mock external requests. For UI rendering tests, we use `playwright` and write tests in `src/fixtures/tests/playwright-rendering.spec.ts`
 
-- `npm run test`: For all unit tests
-  - You can pass specific paths, e.g. `npm run test -- src/search/tests/ai-search-proxy`
-  - You can add `--silent=false` to include `console.log` debugging.
-- `npm run build && npm run playwright-test -- playwright-rendering`: You need to build for changes outside of the test to be picked up. We use playwright for all rendering and end-to-end tests
+**Important: Do NOT run `npm test` without a path argument.** Tests must be run per-suite because different suites require different environment variables. Running all tests at once will produce many false failures.
+
+**Important: Run `npm run build` before running tests.** Many test suites depend on Next.js build artifacts. Without a build, tests may fail with `Could not find a production build` or other confusing errors.
+
+### Running tests by suite
+
+Always target the specific suite for the code you changed:
+
+```shell
+npm test -- src/<suite-name>/tests/
+```
+
+For example: `npm test -- src/search/tests/` or `npm test -- src/versions/tests/`
+
+You can also target a single file: `npm test -- src/search/tests/ai-search-proxy.ts`
+
+Add `--silent=false` to include `console.log` debugging output.
+
+### Suites that require environment variables
+
+Some test suites depend on fixture content or external services. These suites have dedicated npm scripts in `package.json` that set the required environment variables automatically:
+
+```shell
+npm run test:article-api
+npm run test:changelogs
+npm run test:fixtures
+npm run test:landings
+npm run test:languages    # requires Elasticsearch running
+npm run test:search       # requires Elasticsearch running
+```
+
+For the `content-linter` suite, you can optionally scope linting to changed files by setting `DIFF_FILES` (space-separated list) or `DIFF_FILE` (path to a text file containing a space-separated list of changed files). Without these, the linter runs against all content:
+
+```shell
+DIFF_FILES="content/foo.md content/bar.md" npm test -- src/content-linter/tests/
+```
+
+All other suites (e.g., `versions`, `redirects`, `rest`, `frame`, `content-render`, `graphql`, etc.) can be run without special environment variables.
+
+### Playwright (rendering and end-to-end tests)
+
+- `npm run build && npm run playwright-test -- playwright-rendering`: You need to build for changes outside of the test to be picked up. We use playwright for all rendering and end-to-end tests.
   - You can add `--ui` to keep open `localhost:4000` which can be viewed in a simple browser for debugging UI state.
+
+### Development server
+
 - `npm run dev` to start the development server on `localhost:4000`.
-- `ROOT=src/fixtures/fixtures TRANSLATIONS_FIXTURE_ROOT=src/fixtures/fixtures/translations vitest src/fixtures/tests` for tests that involve fixtures.
 
 ## Validate