docs: supercharge repository AI-readiness (automated)

.github/instructions/ci-workflows.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: '.github/workflows/*.yml'
+---
+# GitHub Actions Instructions
+
+**When to read:** Editing GitHub Actions workflows.
+
+- When changing validation scope, update the same path set in `validate.yml` `paths` and `validate-patch.yml` `paths-ignore`: the canonical sample catalog, `scripts/**`, `tests/**`, and both npm manifest files.
+- Preserve the `validate-json-schema` and `test` job names in both validation workflows because the patch workflow supplies their stand-in results.
+- Keep the Jest `test` job dependent on `validate-json-schema` in `.github/workflows/validate.yml`.
+- In the translation handoff, preserve the staging step that collects localized files before opening the cross-repository pull request.
+- Reference credentials through GitHub Actions secrets, following `.github/workflows/handover-translations.yml`; never inline credential values.
+- Get explicit approval before changing triggers, required-check behavior, permissions, secrets, or cross-repository handoff destinations.

.github/instructions/content.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: 'sample-queries/**,permissions/**,messages/**,ge-tour/**'
+---
+# Content Catalog Instructions
+
+**When to read:** Editing Graph Explorer or DevX content catalogs.
+
+- In `sample-queries/sample-queries.json`, keep fields in the order documented in `README.md`: `id`, `category`, `method`, `humanName`, `requestUrl`, `docLink`, `headers`, `postBody`, `tip`, then `skipTest` when applicable.
+- A sample with `postBody` must also define `headers`; JSON request bodies are parsed by `tests/validator.js` unless the content type is XML.
+- Keep `skipTest` false for sample queries, as required by `README.md`.
+- Permission display names in `permissions/permissions-descriptions.json` must not have leading or trailing spaces or end with a period.
+- Documentation links are checked with network HEAD requests, so distinguish an unavailable endpoint from a malformed catalog entry.
+- Avoid unrelated catalog reformatting or reordering because these files are published for external consumers.

.github/instructions/tests.instructions.md

@@ -0,0 +1,12 @@
+---
+applyTo: 'tests/**'
+---
+# Test Instructions
+
+**When to read:** Editing validation specifications, validators, or schemas under `tests/`.
+
+- Jest specifications use the `.spec.js` suffix and load canonical catalogs from `sample-queries/sample-queries.json` or `permissions/permissions-descriptions.json`.
+- Keep sample structure rules aligned between `tests/samples.schema.json` and `tests/samples.spec.js`.
+- `tests/samples.spec.js` validates documentation links with network HEAD requests through `tests/validator.js`; distinguish endpoint failures from assertion failures.
+- Run `npm run test` after test or validator changes.
+- Do not weaken GUID, URL, request-body, display-name, or documentation-link checks merely to accept invalid content.

.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Description
+
+Describe the change, its purpose, and any related issue.
+
+## Testing Done
+
+List the validation performed and the results. Explain why testing is not applicable when relevant.
+
+## Checklist
+
+- [ ] The change is scoped to the intended content or configuration.
+- [ ] Applicable tests were added or updated and pass.
+- [ ] Applicable documentation was updated.
+- [ ] Breaking changes and consumer impact are described.
+- [ ] No secrets or sensitive data are included.

.gitignore

@@ -1 +1,12 @@
 node_modules
+
+# Local environment and secret files
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.pfx
+*.p12
+credentials.json
+service-account*.json

AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+## Build & Test
+
+See `CONTRIBUTING.md` for setup, test, and verification commands.
+
+## Environment Constraints
+
+See `CONTRIBUTING.md` for toolchain and runtime requirements.
+
+## Operational Context
+
+Before answering questions or making changes, read:
+
+- `repo-context.md` - Repository structure, content flow, configuration, dependencies, and ownership.
+- `CONTRIBUTING.md` - Setup, validation, contribution workflow, and common pitfalls.
+- `README.md` - Canonical sample-query and permission authoring requirements.
+
+This repository publishes content rather than running an application service. Validation and publication are separate: `.github/workflows/validate.yml` runs schema and Jest checks, while `azure-pipelines/publishSamples.yml` publishes selected content from `master`.
+
+## Safety Guardrails
+
+> **WARNING:** Production publication and cross-repository handoff are destructive or externally visible operations. Always get explicit user approval before:
+> - Running or changing the production publication behavior in `azure-pipelines/publishSamples.yml`.
+> - Running or changing the translation handoff behavior in `.github/workflows/handover-translations.yml`.
+> - Changing protected-branch, required-check, credential, or secret handling.
+
+### Rules
+
+- Never force push, run `git reset --hard`, or rewrite shared branch history.
+- Never deploy or publish content without explicit user approval.
+- Never weaken validation, branch protection, review, or security controls to make a change pass.
+- Keep edits scoped to the requested content area; avoid unrelated reformatting of large JSON catalogs.
+- Treat `permissions/new/` as a separate data model from `permissions/permissions-descriptions.json`.
+
+## Secrets Management
+
+GitHub Actions accesses credentials through repository secrets in `.github/workflows/handover-translations.yml`, including `API_TOKEN_GITHUB`, `ACTION_EMAIL`, and `ACTION_USERNAME`.
+
+### Rules for AI Agents
+
+- Never inline secrets, tokens, passwords, connection strings, certificate material, or secret values.
+- Never commit `.env`, credential, key, certificate, or token files.
+- Preserve the existing `${{ secrets.NAME }}` reference pattern in GitHub Actions.
+- Do not print, retrieve, rotate, or replace repository secrets without explicit user approval.
+
+## PR Workflow
+
+When creating pull requests, read and follow `.github/pull_request_template.md`. Complete the description, testing, and checklist sections. Mark a section N/A when it does not apply rather than removing it.
+
+## Test Selection
+
+Jest 29.3.1 is the test framework declared in `package.json`. Keep `--no-watch` in local targeted commands so the repository test launcher terminates.
+
+- Run one test file by path: `npm run test -- --no-watch --runTestsByPath tests/permissions-descriptions.spec.js`
+- Run one named test in that file: `npm run test -- --no-watch --runTestsByPath tests/permissions-descriptions.spec.js --testNamePattern "^Permissions descriptions consistency TenantGovernance-Invitation[.]ReadWrite[.]All: adminConsentDisplayName should not have trailing spaces$"`
+- For another test, replace the quoted regular expression with its full Jest test name. Include the enclosing `describe` names when they are needed to select exactly one generated test.

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+The repository already documents its content-authoring rules in `README.md`. Use those instructions as the canonical source rather than duplicating them here:
+
+- [Adding Sample Queries](README.md#adding-sample-queries)
+- [Testing of Sample Queries](README.md#testing-of-sample-queries)
+- [Adding Permissions](README.md#adding-permissions)
+
+## Quick Start
+
+1. Complete the prerequisites and fork or clone steps in [Adding Sample Queries](README.md#adding-sample-queries).
+2. Install the npm dependencies. The validation workflow uses `npm install`.
+3. Make the content change using the field, naming, and ordering rules in `README.md`.
+4. Run `npm run test` before opening a pull request.
+
+Permission contributions are limited to contributors with write access. Other contributors can report missing permissions through the repository issue tracker linked from [Adding Permissions](README.md#adding-permissions).
+
+## Returning Developer Fast Path
+
+Pull the latest `master`, install dependencies if `package.json` or `package-lock.json` changed, make the content update, and run `npm run test`. For sample-query changes, also use the branch-specific Graph Explorer URL described in [Testing of Sample Queries](README.md#testing-of-sample-queries).
+
+## Common Pitfalls
+
+- Editing a localized file when the intended change belongs in the unsuffixed canonical JSON file.
+- Treating `permissions/new/` as interchangeable with `permissions/permissions-descriptions.json`; they use different data models.
+- Omitting the sample-query property order, lowercase `humanName` rule, relative request URL, or required documentation link described in `README.md` and checked by validation.
+- Assuming no CI check is required when a change falls outside the paths watched by `validate.yml`; `validate-patch.yml` supplies the required successful status for those pull requests.
+- Forgetting that sample documentation links are checked with network requests, so local test results can depend on endpoint availability.
+
+## Contribution Workflow
+
+1. Create a branch using the initials-and-purpose format documented in `README.md`.
+2. Keep changes scoped to the relevant content area and update canonical and localized files only when the change requires both.
+3. Run the applicable local validation and inspect the changed JSON for accidental formatting or unrelated content changes.
+4. Push the branch and open a pull request against the appropriate protected branch.
+5. Wait for validation and review. The branch policy requires pull requests, one approving review, and strict status checks for `master` and `dev`.
+6. Address review feedback with additional commits. New commits dismiss stale approvals on `master`.
+
+Repository-wide code ownership is assigned to `@microsoftgraph/msgraph-devx-api-write` through `.github/CODEOWNERS`.
+
+## Who to Ask
+
+Use the repository issue tracker for content gaps and questions that should be publicly tracked. For review routing, use the repository-wide CODEOWNERS team. The existing contact list for contribution issues remains in the final paragraph of `README.md`.
+
+## Building
+
+This is a static content repository, so it does not produce a compiled application or a separate build artifact. The Jest validation suite is the build check. The `test` script is defined in `package.json` and launches `scripts/test-initiator.js`.
+
+For a validation run that terminates instead of entering local watch mode, run `npm run test -- --no-watch`. The `--no-watch` behavior is implemented in `scripts/test-initiator.js`. This command was validated in the current checkout with Node.js v24.14.1 and npm 11.11.0; it completed successfully with exit code 0.
+
+In CI mode, set `CI=true` and run `npm run test`. For PowerShell, the validated form is `$env:CI='true'; npm run test`. The CI condition is defined in `scripts/test-initiator.js`, and the repository workflow runs `npm run test` in `.github/workflows/validate.yml`. The PowerShell form completed successfully with exit code 0 in the current checkout.
+
+## Running
+
+There is no local application service to start. Exercise a content change by running the terminating validation command in [Building](#building). For sample-query changes, use the branch-specific Graph Explorer workflow in [Testing of Sample Queries](README.md#testing-of-sample-queries) after local validation passes.

README.md

@@ -5,6 +5,8 @@ Content used by the DevX API to enhance clients and tooling. At the moment it ha
 
 This will also be used by the localization team to add translation files, and by feature teams to modify, add, or update samples.
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, build, test, and usage instructions.
+
 ## Contributing
 ## Adding Sample Queries
 
@@ -161,3 +163,16 @@ Contributions to permissions are limited to contributors with write access. Howe
 In case you see *You are viewing a cached set of samples because of a network connection failure*, check the query parameters and confirm they're correct, then reload the page.
 
 If you run into any issues, reach out to @MaggieKimani1, @irvinesunday or @thewahome.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Repository Context](repo-context.md) | Repository structure, content areas, configuration, dependencies, integrations, and conventions. |
+| [Contributing Guide](CONTRIBUTING.md) | Setup, validation, and contribution workflow. |
+| [Agent Guidance](AGENTS.md) | Repository-wide guidance and safety rules for AI agents. |
+| [Code of Conduct](CODE_OF_CONDUCT.md) | Community standards and conduct resources. |
+| [Pull Request Template](.github/pull_request_template.md) | Required pull request description, testing details, and checklist. |
+| [CI Workflow Instructions](.github/instructions/ci-workflows.instructions.md) | Scoped guidance for GitHub Actions workflow changes. |
+| [Content Catalog Instructions](.github/instructions/content.instructions.md) | Scoped guidance for content catalog changes. |
+| [Test Instructions](.github/instructions/tests.instructions.md) | Scoped guidance for validation and test changes. |