Add Copilot custom instructions (#20)

This pull request introduces comprehensive Copilot and language-specific
instructions for Azure Cosmos DB samples, standardizing conventions
across the repository for structure, authentication, code style, and CI
workflows. The changes clarify product naming, enforce folder and file
patterns, and provide detailed guidelines for .NET, Python, Go,
TypeScript, and workflow files to ensure consistency and
maintainability.

**Copilot and repository-wide conventions:**

* Added `.github/copilot-instructions.md` with detailed guidelines for
product naming, folder structure, sample numbering, shared data model,
authentication, package versioning, README conventions, testing/CI, and
anti-patterns.

**Language-specific sample conventions:**

* Added `.github/instructions/dotnet.instructions.md` outlining .NET
sample structure, package management, authentication, and code style
(e.g., use of `.cs` scripts, `#:package`, top-level statements, and
`record` types).
* Added `.github/instructions/python.instructions.md` detailing Python
sample file structure, dependency management, authentication, and code
style (e.g., single `app.py`, `os.environ` for config, dict literals for
data).
* Added `.github/instructions/go.instructions.md` specifying Go sample
structure, module naming, authentication, and code style (e.g., single
`main.go`, `go.mod`, JSON struct tags, error handling helpers).
* Added `.github/instructions/typescript.instructions.md` defining
TypeScript sample structure, dependency management, authentication, and
code style (e.g., `tsx` usage, caret version ranges, ES modules,
`interface` for types).

**CI workflow conventions:**

* Added `.github/instructions/workflows.instructions.md` to standardize
CI workflow structure, validation jobs, per-language build/test rules,
emulator testing, and language-specific build/test instructions.

Author: seesharprun

.github/copilot-instructions.md

@@ -0,0 +1,75 @@
+# Azure Cosmos DB Samples — Copilot Instructions
+
+## Product naming
+
+- Always say **Azure Cosmos DB** — never "Azure Cosmos DB for NoSQL"
+- The NoSQL API is the only API in this repository and is always inferred
+- Do not generate samples for MongoDB, Cassandra, Gremlin, or Table APIs
+
+## Repository structure
+
+- Root folders by language: `dotnet/`, `python/`, `go/`, `typescript/`
+- Sample folders use the pattern `NNN-kebab-case-name/` (regex: `^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$`)
+- Every sample folder **must** contain a `readme.md`
+- Each sample is self-contained and independently runnable
+
+## Numbering standard
+
+Sample numbers are **shared across languages** — the same number means the same concept in every language.
+
+| Range | Category | Description |
+|-------|----------|-------------|
+| `000–099` | Connectivity | Client setup, authentication, emulator |
+| `100–199` | Quickstart | Hello-world style getting-started scenarios |
+| `200–299` | Features | Change feed, bulk, batch, patch, indexing |
+| `300–399` | Patterns | Multi-tenancy, pagination, retry, hierarchical partition keys |
+| `400–499` | Advanced | Vector search, AI integration, semantic cache |
+| `500–599` | Vertical | End-to-end apps (todo, IoT, e-commerce) |
+
+## Shared data model
+
+All samples use the same database, container, and item shape:
+
+- **Database:** `cosmicworks`
+- **Container:** `products`
+- **Partition key:** `/category`
+- **Product shape:** `{ id, category, name, quantity, sale }`
+- **Canonical item:** id `70b63682-b93a-4c77-aad2-65501347265f`, category `gear-surf-surfboards`, name `Yamba Surfboard`, quantity `12`, sale `false`
+
+## Authentication
+
+- **00x range only** (connect samples): passwordless via `DefaultAzureCredential`
+- **All other samples**: key-based via `COSMOS_ENDPOINT` + `COSMOS_KEY` environment variables
+
+## Package versions
+
+Do **not** pin specific package versions. Use floating or major-version ranges:
+
+- .NET: `Version="3.*"` in `Directory.Packages.props` or `#:package Foo@3.*` in script files
+- Python: `azure-cosmos>=4.9` in `requirements.txt`
+- Go: standard `go get` versioning
+- TypeScript: caret ranges (`^`) in `package.json`
+
+## README conventions
+
+- **Title pattern:** `{Operation} with Azure Cosmos DB ({Language})`
+- **Sections:** Prerequisites, Run (with macOS/Linux + Windows PowerShell blocks), What this sample does
+- **Environment variable callout:** use `> [!IMPORTANT]` note
+- **Connect samples (00x):** only read account metadata — no CRUD operations
+- Do not include `.env.example` files — put env var instructions inline in the readme
+
+## Testing and CI
+
+- Samples are validated on **every push to `main`** and on **every pull request**
+- Samples should be runnable against the **Azure Cosmos DB emulator**
+- The CI workflow (`.github/workflows/validate.yml`) runs per-language build jobs independently
+- Structure validation enforces the naming regex and readme presence
+
+## Anti-patterns
+
+- Do not say "for NoSQL" — just "Azure Cosmos DB"
+- Do not add `.env.example` files
+- Do not use `python-dotenv` — use `os.environ` directly
+- Do not pin exact package versions
+- Do not mix CRUD operations into connect samples
+- Do not use `matrix` strategy in CI with single versions (causes version-suffixed check names)

.github/instructions/dotnet.instructions.md

@@ -0,0 +1,34 @@
+---
+applyTo: "dotnet/**"
+---
+
+# .NET sample conventions
+
+## File-based apps
+
+- Use `.cs` script files with `#:package` directives — do **not** create `.csproj` files
+- Run samples with `dotnet run {filename}.cs`
+- Use `#:property` for per-file MSBuild properties when needed
+
+## Package management
+
+- **`Directory.Packages.props`** (central): only packages used by **2+ samples** (e.g., `Microsoft.Azure.Cosmos`, `Newtonsoft.Json`). Use floating major versions (`Version="3.*"`).
+- **`#:package` in the `.cs` file**: packages used by **only one sample** (e.g., `Azure.Identity` is only in `001-connect-passwordless`). Use `#:package Foo@3.*` syntax.
+- When a second sample needs a previously single-use package, promote it to `Directory.Packages.props`.
+
+## Build properties
+
+- `Directory.Build.props` holds shared properties like `UserSecretsId`
+- `.editorconfig` enforces code style — do not remove or override it
+
+## Authentication
+
+- **00x connect samples**: `DefaultAzureCredential` via `Azure.Identity`. Store endpoint in user secrets (`dotnet user-secrets set --file {file}.cs "COSMOS_ENDPOINT" "..."`)
+- **All other samples**: key-based via `COSMOS_ENDPOINT` + `COSMOS_KEY` user secrets
+
+## Code style
+
+- Top-level statements (no `Main` method, no namespace)
+- Use `record` types for the `Product` data model
+- Use `var` where the type is obvious
+- Suffix async calls with `Async` — use `await` directly in top-level code

.github/instructions/go.instructions.md

@@ -0,0 +1,31 @@
+---
+applyTo: "go/**"
+---
+
+# Go sample conventions
+
+## File structure
+
+- Single `main.go` as the entry point
+- `go.mod` with module path `github.com/AzureCosmosDB/samples/go/{sample-name}`
+- Use standard `go get` versioning — do not pin exact versions
+
+## Authentication
+
+- Key-based: `COSMOS_ENDPOINT` + `COSMOS_KEY` environment variables
+- Use `azcosmos.NewKeyCredential(key)` and `azcosmos.NewClientWithKey(endpoint, cred, nil)`
+- Validate env vars at startup with `log.Fatalf(...)` if missing
+
+## Code style
+
+- Use a `Product` struct with JSON tags (`json:"id"`, etc.)
+- Use `json.Marshal` / `json.Unmarshal` for item serialization
+- Handle 409 Conflict errors with an `isConflict()` helper function:
+  ```go
+  func isConflict(err error) bool {
+      var responseErr *azcore.ResponseError
+      return errors.As(err, &responseErr) && responseErr.StatusCode == http.StatusConflict
+  }
+  ```
+- Use `context.Background()` for all Cosmos DB operations
+- Use `log.Fatalf` for fatal errors, `fmt.Printf` for output

.github/instructions/python.instructions.md

@@ -0,0 +1,23 @@
+---
+applyTo: "python/**"
+---
+
+# Python sample conventions
+
+## File structure
+
+- Single `app.py` as the entry point
+- `requirements.txt` for dependencies — use floating versions (e.g., `azure-cosmos>=4.9`)
+- Do **not** use `python-dotenv` — read config with `os.environ` directly
+
+## Authentication
+
+- Key-based: `COSMOS_ENDPOINT` + `COSMOS_KEY` environment variables
+- Validate env vars at startup with `raise ValueError(...)` if missing
+
+## Code style
+
+- Use `dict` literals for item data (no dataclasses or Pydantic models)
+- Use `PartitionKey` from `azure.cosmos` for container creation
+- Use parameterized queries with `@parameter` syntax for SQL queries
+- Print operations and results to stdout for verification

.github/instructions/typescript.instructions.md

@@ -0,0 +1,31 @@
+---
+applyTo: "typescript/**"
+---
+
+# TypeScript sample conventions
+
+## File structure
+
+- `package.json` with dependencies and scripts (`start`, `build`, `test`)
+- `tsconfig.json` with ES2022 target, Node module resolution, strict mode
+- Source `.ts` file as entry point
+- Use `tsx` for direct TypeScript execution (no compile step to run)
+- `.gitignore` for `node_modules/`, `dist/`, `.env`
+
+## Dependencies
+
+- Use caret ranges (`^`) in `package.json` — do not pin exact versions
+- Primary SDK: `@azure/cosmos`
+- Node.js 20+
+
+## Authentication
+
+- Key-based: `COSMOS_ENDPOINT` + `COSMOS_KEY` environment variables
+- Read with `process.env.COSMOS_ENDPOINT` — throw if missing
+- Do **not** use `dotenv` — put env var setup instructions in the readme
+
+## Code style
+
+- Use `interface` for the `Product` type (not `type` alias or `class`)
+- Use `async`/`await` throughout
+- Use ES module syntax (`import`/`export`)

.github/instructions/workflows.instructions.md

@@ -0,0 +1,38 @@
+---
+applyTo: ".github/workflows/**"
+---
+
+# CI workflow conventions
+
+## Workflow structure
+
+- Single workflow file: `validate.yml` — do not split into per-language workflows
+- Trigger on both `push` to `main` AND `pull_request` to `main`
+- Set `permissions: contents: read` at the workflow level
+- Use `concurrency` group with `cancel-in-progress: true`
+
+## Structure validation job
+
+- Scan all language folders: `python`, `javascript`, `typescript`, `java`, `dotnet`, `go`
+- Enforce naming regex: `^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$`
+- Check for `readme.md` using **case-insensitive** find: `find "${sample}" -maxdepth 1 -type f -iname "readme.md"`
+- Do **not** use exact filename match (e.g., `[ -f "README.md" ]`) — this breaks on case variations
+
+## Per-language build jobs
+
+- Each language job runs independently and only scans its own folder
+- Exit cleanly (`exit 0`) if the language folder doesn't exist
+- Do **not** use `matrix` strategy with single versions — hardcode versions in `with:` to avoid version-suffixed check names
+- Use latest major action versions (`actions/checkout@v6`, `actions/setup-node@v6`, etc.)
+
+## Language-specific rules
+
+- **.NET**: handle both `.csproj`/`.sln` projects AND file-based `.cs` apps. Do **not** use `-q` quiet flag on `dotnet build` (it suppresses errors)
+- **Python**: `pip install -r requirements.txt` then `py_compile` or `pytest`
+- **Go**: `go build ./...` and `go test ./...`
+- **JavaScript/TypeScript**: scan both `javascript/` and `typescript/` folders. `npm install` + `npm test --if-present`
+
+## Emulator testing
+
+- Samples should be testable against the Azure Cosmos DB emulator
+- Do not require a live Azure account for CI validation