diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 48f8b66d..212f4591 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,36 +1 @@
-<!--
-✏️ PROJECT-SPECIFIC INSTRUCTIONS
-📝 Customize this file for your project needs
--->
-
-# Project Copilot Instructions
-
-> For instructions see [copilot-upstream.md](./copilot-upstream.md)
-
-## Project Configuration
-
-**Do not modify `.github/copilot-upstream.md`, which is managed and updated upstream.  Instead edit this file for project-specific instructions.**
-
-Use these technologies:
-- Next.js 14 with TypeScript
-- PostgreSQL for database
-- Node.js >= 18.0.0
-- OpenAPI for API design
-
-Follow these conventions:
-- API endpoints: kebab-case
-- React components: PascalCase
-- Database: Always use parameterized queries
-
-Project-specific rules:
-- Python: 4 spaces (override BC Gov standard)
-- APIs: Additional validation for public endpoints
-- Branches: feature/JIRA-123-description
-
-Never:
-- Create duplicate files
-- Remove existing documentation
-- Override error handling
-- Bypass security checks
-- Generate non-compliant code
-- Modify or remove the UPSTREAM MANAGED header at the top of `.github/copilot-upstream.md`
+Follow the repository's [AGENTS.md](../AGENTS.md).
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..f8edc5ce
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,17 @@
+# AGENTS.md
+
+Repository facts for automated coding assistants. Teams may edit or remove this file.
+
+## Layout
+- `api/` (Express, Mongoose), `frontend/` (Vite, React), `crawler/` (GitHub crawl of `bcgovpubcode.yml`), `database/` (MongoDB image), `schema/` (JSON Schema)
+- Helm chart: `charts/pubcode` (`charts/pubcode/values.yaml`)
+- Workflows: `.github/workflows/` (PR: `pr-open.yml`, `pr-close.yml`, `pr-validate.yml`; merge: `merge.yml`; crawler and schema jobs: `scheduled.yml`; reusable: `.deploy.yml`, `.tests.yml`)
+
+## Build, test, deploy
+- Local stack: `docker compose up` (MongoDB, API on port 3005, Caddy frontend on port 3002). Caddy serves `frontend/dist`, so run `cd frontend && npm ci && npm run build` first. API: `cd api && npm ci && npm run dev`. Crawler: `cd crawler && npm ci && npm run dev`
+- Frontend (`cd frontend`, Node 24): `npm run dev` (Vite port 3001 in `frontend/vite.config.js`), `npm run build`, `npm run lint`. E2E: `npx cypress run --config baseUrl=http://localhost:3001` with `npm run dev` up. `frontend/cypress.config.js` sets `baseUrl` to `http://localhost:5173`. CI (`.github/workflows/.tests.yml`) overrides `baseUrl` to the deployed route
+- Images `api`, `database`, and `frontend` are built in GitHub Actions by `bcgov/actions/builder` (`pr-open.yml`). OpenShift Helm deploys run from GitHub Actions (`pr-open.yml` for pull requests; `merge.yml` deploys test, then prod), not a workstation
+
+## Shared actions
+- Shared actions are not in this repo. Use `bcgov/actions/*` and `bcgov/actions-openshift/*` as provided; don't copy or fork them.
+- Never pin `@main`. Pin bcgov shared actions to a published release SHA with a `# vX.Y.Z` comment.