From 0f8c758d3801574ee9d14e2a5d117b6ced7b4ae7 Mon Sep 17 00:00:00 2001
From: dermotduffy <dermot.duffy@gmail.com>
Date: Sat, 21 Feb 2026 20:39:15 -0800
Subject: [PATCH] chore: Add AI instructions.

---
 .claude/settings.json          |  5 ++++
 .cursor/rules/instructions.mdc |  1 +
 AGENTS.md                      |  1 +
 CLAUDE.md                      |  1 +
 GEMINI.md                      |  1 +
 INSTRUCTIONS.md                | 54 ++++++++++++++++++++++++++++++++++
 6 files changed, 63 insertions(+)
 create mode 100644 .claude/settings.json
 create mode 120000 .cursor/rules/instructions.mdc
 create mode 120000 AGENTS.md
 create mode 120000 CLAUDE.md
 create mode 120000 GEMINI.md
 create mode 100644 INSTRUCTIONS.md

diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 00000000..6bcf1043
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "allow": ["Bash(yarn run *)"]
+  }
+}
diff --git a/.cursor/rules/instructions.mdc b/.cursor/rules/instructions.mdc
new file mode 120000
index 00000000..ee51c546
--- /dev/null
+++ b/.cursor/rules/instructions.mdc
@@ -0,0 +1 @@
+../../INSTRUCTIONS.md
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
new file mode 120000
index 00000000..946b8ea5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1 @@
+INSTRUCTIONS.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 00000000..946b8ea5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+INSTRUCTIONS.md
\ No newline at end of file
diff --git a/GEMINI.md b/GEMINI.md
new file mode 120000
index 00000000..946b8ea5
--- /dev/null
+++ b/GEMINI.md
@@ -0,0 +1 @@
+INSTRUCTIONS.md
\ No newline at end of file
diff --git a/INSTRUCTIONS.md b/INSTRUCTIONS.md
new file mode 100644
index 00000000..1df84392
--- /dev/null
+++ b/INSTRUCTIONS.md
@@ -0,0 +1,54 @@
+# AI Project Instructions: Advanced Camera Card
+
+## Core Tech Stack
+
+- **Language:** TypeScript (Strict Mode)
+- **Package Manager:** Yarn
+- **Test Runner:** Vitest
+- **UI Framework:** LitElement (Lit v3)
+- **Config/Validation:** Zod
+- **Build System:** Rollup
+
+## Development Workflow
+
+- **Install Dependencies:** `yarn install`
+- **Build Project:** `yarn run build`
+- **Run Tests:** `yarn run test`
+- **Run Tests (Coverage):** `yarn run coverage`
+- **Format:** `yarn run format`
+- **Lint:** `yarn run lint`
+- **Prune**: `yarn run prune`
+- **Check doc link validity**: `yarn run docs-check-links`
+
+## Code Style
+
+- Prettier enforces: 89-char line width, single quotes, trailing commas, 2-space indent, semicolons.
+- Commits must follow the **Conventional Commits** format (used by semantic-release).
+
+## Coding Standards & Patterns
+
+- **TypeScript:**
+
+  - Prefer `interface` for object structures; `type` for unions/intersections.
+  - Avoid `any` at all costs (in both source and tests); use `unknown`, proper generics, or `as unknown as T` for unavoidable type coercions. In tests, use `assert` (imported from `vitest`) for type narrowing.
+  - Use `zod` for runtime validation if external data is involved.
+  - `noUnusedParameters` and `noImplicitReturns` are enforced — all parameters must be used and all code paths must return.
+
+- **Testing (Vitest):**
+
+  - Follow the **Arrange-Act-Assert (AAA)** pattern.
+  - Mock external dependencies using `vi.mock()`.
+  - Use `vi.spyOn()` for monitoring method calls without destroying original behavior.
+  - Use `mock<T>()` from `vitest-mock-extended` for type-safe interface/class mocks.
+  - For time-sensitive tests, use `vi.useFakeTimers()` / `vi.setSystemTime()` and restore with `vi.useRealTimers()` in `afterEach`.
+  - Test files must be named `*.test.ts` and reside in a matching file under the `tests/` hierarchy. The source and test file hierarchy must match.
+  - 100% coverage is required for all business logic layers: `camera-manager/`, `card-controller/`, `components-lib/`, `config/`, `conditions/`, `ha/`, `utils/`, `view/`. New web components (`components/*`) are exempt; put as much non-render logic as possible in a matching controller under `components-lib/`.
+  - Reuse shared test factories from `tests/test-utils.ts` (e.g. `createHASS()`, `createCameraConfig()`, `createFrigateEvent()`) rather than building ad-hoc test data inline.
+
+- **Architecture:**
+  - Keep functions small and "pure" where possible.
+  - Favor composition over inheritance.
+  - Readability and simple understandable code is extremely important.
+  - **Separation of concerns:** Web components (`components/`) handle rendering only; business logic belongs in matching controllers under `components-lib/`. Controllers implement Lit's `ReactiveController` pattern where needed.
+  - **Manager pattern:** `CardController` (`card-controller/controller.ts`) orchestrates specialized managers (e.g. `ConfigManager`, `HASSManager`, `ViewManager`). New cross-cutting concerns belong in a new manager.
+  - **Module conventions:** Within each module use `types.ts` for type/schema definitions, `*-manager.ts` for coordinators, `*-controller.ts` for logic controllers, and a `utils/` subdirectory for helpers.