# GitHub Copilot & Contributor Instructions

Purpose: guidance for using GitHub Copilot (and for humans) when working on this repo.

**Repo overview**
- `theme/`: WordPress theme source (PHP, theme assets, includes). Edit here for theme behavior, templates, and assets.
- `pages/`: PHP page templates used by WordPress (e.g., `about.php`, `contact.php`). These are page-level templates or example pages.
- `theme/assets/`: CSS/JS/SVG used by the theme. `assets/css/main.css` and `assets/js/main.js` are the main files.
- `theme/inc/`: PHP helpers and feature modules (enqueueing, AJAX handlers, setup, theme defaults, generator, settings).
- `parts/`: small HTML snippets (header/footer) included by templates.
- `patterns/` and `templates/`: reusable patterns and template HTML files.

**Goals when editing**
- Keep changes small and focused per PR.
- Preserve WordPress conventions (use `wp_enqueue_script`/`wp_enqueue_style`, action/filter hooks, and template hierarchy).
- Avoid breaking backward compatibility for theme consumers unless explicitly required.

**Local development (recommended quick steps)**
- Testing is handled by the repository owner; do not run WordPress locally unless explicitly requested.

Manual checks you can run locally before submitting changes:
- PHP syntax: `php -l path/to/file.php`
- Theme header: ensure `style.css` at `theme/style.css` contains valid theme metadata.

**Editing the theme**
- Primary entry points: `theme/functions.php`, `theme/index.php`, `theme/assets/`, and `theme/inc/*`.
- Add / modify reusable sections in `parts/header.html` and `parts/footer.html`.
- For new templates: follow WP template naming (e.g., `page-{$slug}.php`) or create a template with a `/* Template Name: ... */` comment.
- Use `theme/inc/enqueue.php` (or existing helpers) to add scripts/styles — keep asset handles unique and versioned.

**Pages folder usage**
- `pages/*.php` contains standalone page templates or examples. When adding a new page template, document how it should be attached in WP admin (page template comment or theme settings).

**Testing & validation**
- Run `php -l` on changed PHP files before committing.
- For CSS/HTML, use browser devtools and the W3C validator for critical pages.
- If adding JS, test in Safari and Chrome on macOS (this repo is tested on macOS by default).

**Code style & safety**
- Follow existing code patterns in `theme/`.
- Escape outputs (use `esc_html()`, `esc_attr()`, `wp_kses_post()` where appropriate) for user-facing output.
- Nonces: use `wp_nonce_field()`/`check_admin_referer()` for forms/AJAX in `theme/inc/ajax.php`.

**Commit and PR guidance**
- Keep commits focused: one feature/bugfix per PR.
- Provide a clear PR description: what changed, why, and how to test locally.
- Run `php -l` and a quick manual smoke-test before opening PR.

**Using GitHub Copilot effectively for this repo**
- Provide context in prompts: mention exact file path(s) and constraints (WordPress version targets, PHP version, browser compatibility).
- Good prompt pattern:
  - Short summary of intent.
  - Files or functions to change (provide paths).
  - Constraints (e.g., "must use wp_enqueue_script", "no breaking changes to header markup").
  - How to test the change.

Example Good Prompt:
"Refactor theme/inc/enqueue.php to register and enqueue a new frontend script `theme-main` from `theme/assets/js/main.js`. Use `wp_enqueue_script` with dependency `jquery` and version based on file `filemtime`. Make sure it loads in the footer. Show the exact code to add and where."

Example Bad Prompt:
"Make the theme faster." (too vague — include file, objective, and measurable change)

**When to ask for human review**
- Changes to security-sensitive code (nonce handling, AJAX endpoints).
- Template structure changes that may break theme consumers.
- Large refactors that affect multiple parts of the theme.

**Owner / Maintainers**
- If unsure, open a draft PR and assign it to the repository owner for review.

---
If you want, I can also:
- Add a quick `Makefile` or NPM scripts for common checks (PHP lint, CSS/JS lint).
- Add a sample `wp-env` configuration for one-command local setup.