# Repository Conventions

## 1. Naming

- Existing script filenames stay unchanged for documentation compatibility.
- New scripts should use clear, stable names and should not be renamed later without a migration plan.

## 2. Placement

- Place scripts by platform + domain:
  - `scripts/m365/...`
  - `scripts/windows/...`
  - `scripts/macos/...`
  - `scripts/content/...`
- Place build/deploy automation in `automation/...`.

## 3. Script Header (minimum)

Use these fields at the top of each script where possible:

- Purpose/Synopsis
- Requirements (modules, permissions, OS)
- Input parameters
- Output (file/console)
- Example usage

## 4. Secrets and Variables

- Do not hardcode secrets.
- Use variables, prompts, or a secure vault mechanism.

## 5. Output and Logging

- Default output goes to `output/` unless operational requirements dictate otherwise.
- Use predictable filenames for exports.

## 6. Change Policy

- For file moves: update README and relevant guides.
- For any future filename changes: add a temporary compatibility layer (wrapper/alias) and define a deprecation window.