diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..1279bc4
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,97 @@
+# GitHub Copilot / AI agent instructions
+
+Purpose: help an AI coding agent be immediately productive in this repository.
+
+- Big picture
+  - Static site built with MkDocs + Material theme. Sources live in `markdown/`; generated site is written to `public/` ([mkdocs.yml](mkdocs.yml)).
+  - Theme customizations and build hooks are in `overrides/` (Python hooks + theme assets).
+  - A parallel Gemini site lives in `gmi/` (different format, separate publishing flow).
+  - Cloudflare Pages / Workers integration: see `wrangler.jsonc` (publishes assets from `public/`).
+
+- Key workflows (concrete commands)
+  - Install dependencies (preferred): `pipenv install` (or `pip install -r requirements.txt`). See [Pipfile](Pipfile) and [requirements.txt](requirements.txt).
+  - Local preview: `mkdocs serve --watch overrides --watch-theme --livereload` or `pipenv run dev` (see `Pipfile` scripts and [mkdocs.yml](mkdocs.yml)).
+  - Build site: `pipenv run build` or `pipenv run build -f mkdocs.readthedocs.yml` (build targets in `Pipfile` and `build.sh`). `build.sh` copies favicon into `public/` after build.
+  - Cloudflare deploy (manual): `npm run deploy` -> `wrangler deploy` (see `package.json` and [wrangler.jsonc](wrangler.jsonc)). CI deploy logic uses `npx wrangler pages publish` in `bin/deploy.sh` when running under CI.
+  - CI: deployments happen via GitLab CI; do not rely on a repository-local Docker CI image.
+
+- Project-specific conventions & patterns
+  - Content separation: author-managed Markdown in `markdown/` is canonical. Do not edit `public/` — it is generated.
+  - Theme overrides and custom assets live in `overrides/`; changes there affect build behavior and the site theme.
+  - The build copies `assets/images/favicon.png` to `public/favicon.ico` after building (see `build.sh` and `bin/build.sh`). Keep favicon at that path.
+  - Python environment targets Python 3.13 (see `Pipfile`). The repo commonly uses `pipenv` and a `.venv` pattern in local scripts (`bin/localdev.sh`).
+  - CI: deployments happen via GitLab CI and `bin/deploy.sh` (see `wrangler.jsonc` for Cloudflare Pages configuration).
+
+- Integration points & external dependencies
+  - Cloudflare Pages / Workers via `wrangler`/`wrangler.jsonc` (assets directory: `./public`).
+  - CI builds run on GitLab. Avoid referencing the `docker/` folder — it may be moved to a separate repo.
+  - `npm` is used only for `wrangler` dev/deploy and Docker convenience scripts (`package.json`).
+
+- Helpful files to inspect
+  - Repository README: [README.md](README.md)
+  - MkDocs config: [mkdocs.yml](mkdocs.yml)
+  - Build scripts: [build.sh](build.sh) and [bin/build.sh](bin/build.sh)
+  - CI/deploy: [bin/deploy.sh](bin/deploy.sh) and [wrangler.jsonc](wrangler.jsonc)
+  - Python deps: [Pipfile](Pipfile) and [requirements.txt](requirements.txt)
+  -
+
+- What NOT to do
+  - Do not edit generated files under `public/` directly — change sources in `markdown/` or `overrides/`.
+  - Avoid changing `site_dir` or `assets` layout without verifying `wrangler.jsonc` and `bin/deploy.sh` updates.
+
+- If you need clarification
+  - Ask the maintainer which mirror/CI (GitLab primary) you want to target before modifying CI configs.
+
+- Next steps
+  - If you want, I can expand the CI section with example GitLab job snippets or add examples for contributing patches.
+
+- Commit attribution
+  - Adopt the `Assisted-by` commit trailer for AI-assisted changes to comply with attribution policies.
+  - Required trailer format (commit footer):
+
+```
+Assisted-by: <Model Name> via <Tool Name>
+```
+
+  - Example:
+
+```
+Assisted-by: GLM 4.6 via Claude Code
+```
+
+  - Repository also requires Linux DCO sign-off for patches. Ensure commits include `Signed-off-by:` lines in the footer alongside `Assisted-by:` when applicable.
+
+If any section is unclear or you want deeper examples (e.g., contributing workflow, CI job templates), tell me which area to expand.
+
+- Example: GitLab CI snippet
+  - Minimal job that builds the site and publishes to Cloudflare Pages using `wrangler`.
+
+```yaml
+stages:
+  - build
+  - deploy
+
+build_site:
+  stage: build
+  image: node:20-bullseye
+  script:
+    - pip install pipenv
+    - pipenv install --deploy --ignore-pipfile
+    - pipenv run build
+  artifacts:
+    paths:
+      - public/
+
+publish_pages:
+  stage: deploy
+  image: node:20-bullseye
+  dependencies:
+    - build_site
+  script:
+    - npm install -g wrangler
+    - npx wrangler pages publish public --project-name "$CF_PAGES_PROJECT_NAME" --branch "$CI_COMMIT_BRANCH"
+  only:
+    - main
+```
+
+  - Notes: set `CF_PAGES_PROJECT_NAME` in CI variables; the repo's `bin/deploy.sh` also contains an example `npx wrangler pages publish` invocation used by CI.