diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..7d939e1
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,26 @@
+# Copilot Instructions
+
+## System Requirements
+
+This project targets **retro systems** (Windows 3.11, Windows 98, FreeDOS).
+The UI must work in period-appropriate browsers:
+
+- **No JavaScript** — all interactivity must be server-side.
+- **No CSS** — use HTML attributes (`border`, `cellpadding`, `cellspacing`) for layout.
+- **Use table-based layouts** to arrange elements side by side.
+- Keep HTML simple: plain `<form>`, `<table>`, `<input>`, `<a>` elements only.
+
+## Testing
+
+- **All new functionality must have unit tests.**
+- Service-layer tests go in `src/test/java/.../service/GitServiceTest.java` and use
+  real JGit repositories created in `@TempDir` directories.
+- Controller tests go in `src/test/java/.../controller/RepoControllerTest.java` and
+  use `@WebMvcTest` with `@MockitoBean` for the service layer.
+- Run `./gradlew test` to verify all tests pass before considering a change complete.
+
+## Tech Stack
+
+- Java 25, Spring Boot 4.0, Thymeleaf, Gradle
+- JGit for all Git operations (no shelling out to `git`)
+- Lombok for boilerplate reduction (`@Getter`, `@Setter`, `@RequiredArgsConstructor`)