From 6f902b78c007fe55d09a7578d7945be9a5cd4529 Mon Sep 17 00:00:00 2001
From: Bastien Wirtz <bastien.wirtz@gmail.com>
Date: Sat, 27 Sep 2025 14:42:31 +0200
Subject: [PATCH] doc: add agent instructions file.

---
 .gitignore      |  6 +++-
 AGENTS.md       | 84 +++++++++++++++++++++++++++++++++++++++++++++++++
 CONTRIBUTING.md | 12 ++++++-
 3 files changed, 100 insertions(+), 2 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/.gitignore b/.gitignore
index ee51c88..6eb9005 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,4 +23,8 @@ yarn-error.log*
 # App configuration
 config.yml
 
-.drone.yml
\ No newline at end of file
+.drone.yml
+
+# Specific Agent file
+CLAUDE.md
+GEMINI.md
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..29d7dfb
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,84 @@
+# AGENTS Instructions
+
+This file provides guidance to AI Agents when working with code in this repository.
+
+## Development Commands
+
+```bash
+pnpm install      # Install dependencies (PNPM enforced via packageManager)
+pnpm dev          # Start development server on http://localhost:3000
+pnpm mock         # Start mock API server for testing service integrations
+pnpm build        # Build for production
+pnpm preview      # Preview production build
+pnpm lint         # Run ESLint with auto-fix
+```
+
+## Architecture Overview
+
+Homer is a static Vue.js 3 PWA dashboard that loads configuration from YAML files. The architecture is service-oriented with dynamic component loading.
+
+### Core Application Structure
+
+- **Entry Point**: `src/main.js` mounts the Vue app
+- **Root Component**: `src/App.vue` handles layout, configuration loading, and routing
+- **Configuration System**: YAML-based with runtime merging of defaults (`src/assets/defaults.yml`) and user config (`/assets/config.yml`)
+- **Service Components**: 53 specialized integrations in `src/components/services/` that extend a Generic component pattern
+
+### Service Integration Pattern
+
+All service components follow this architecture:
+
+- Extend `Generic.vue` using Vue slots (`<template #indicator>`, `<template #content>`, `<template #icon>`)
+- Use the `service.js` mixin (`src/mixins/service.js`) for common API functionality
+- Use a custom `fetch` method provided by the service mixin to seamlessly support proxy configuration, custom headers, and credentials.
+
+### Configuration & Routing
+
+- **Multi-page Support**: Hash-based routing without Vue Router
+- **Dynamic Config Loading**: External URLs supported via `config.remote_config`
+- **Theme System**: CSS layers architecture with three built-in themes in `src/assets/themes/`
+- **Asset Management**: Static files served from `/assets/` with runtime configuration merging
+
+### Build System Details
+
+- **Vite 7**: Modern build tool with Vue plugin
+- **PWA**: Auto-updating service worker via `vite-plugin-pwa`
+- **SCSS**: Bulma framework with modular component styling
+- **Docker**: Multi-stage build (Node.js → Alpine + Lighttpd)
+
+### Mock Data Creation Pattern
+
+When creating mock data for service components testing:
+
+**Structure**: `dummy-data/[component-name]/[api-path]/[endpoint]`
+
+**Steps**:
+
+1. **Analyze component**: Read the Vue component file to identify API calls (look for `this.fetch()` calls)
+2. **Check existing mock**: If mock directory exists, read existing files to check for missing fields
+3. **Create/update structure**: `mkdir -p dummy-data/[lowercase-component-name]/` and mirror API endpoint paths
+4. **Create/update JSON files**: Write realistic mock responses matching the expected data structure
+5. **Verify fields**: Ensure all fields used in the component's computed properties and templates are included
+6. **Update existing mocks**: If mock files exist but are missing fields, add the missing fields without removing existing data
+
+**Key Points**:
+
+- Component directory name should be lowercase version of component name (e.g., `AdGuardHome.vue` → `adguardhome/`)
+- Directory structure mirrors API endpoints exactly
+- Files contain JSON responses (no file extension needed)
+- Mock server serves from `dummy-data/` via `pnpm mock` command
+- Each component gets isolated directory to prevent API path conflicts
+- When updating existing mocks, preserve existing data and only add missing fields required by the component
+- Always read existing mock files first to understand current structure before making changes
+
+**Example**: For `AdGuardHome.vue`:
+- API calls: `/control/status`, `/control/stats`
+- Mock files: `dummy-data/adguardhome/control/status`, `dummy-data/adguardhome/control/stats`
+
+### Development Notes
+
+- Use `pnpm mock` to test service integrations with dummy data
+- Configuration changes require restart in development mode
+- New service components should follow the Generic component slot pattern
+- Themes use CSS custom properties for dynamic color switching
+- The app has no backend dependencies and generates static files only
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4dc7b49..3955115 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,7 +7,7 @@ First off, thank you for considering contributing to Homer!
 ### Project philosophy
 
 Homer is meant to be a light and very simple dashboard that keeps all your useful utilities at hand. The few features implemented in Homer focus on
-UX and usability. If you are looking for a full featured dashboard, there are tons of great stuff out there like https://heimdall.site/, https://github.com/rmountjoy92/DashMachine or https://organizr.app/.
+UX and usability. If you are looking for a full featured dashboard, there are tons of great stuff out there like https://gethomepage.dev/, https://heimdall.site/, https://github.com/rmountjoy92/DashMachine or https://organizr.app/.
 
 - Configuration is stored in a simple config file, avoiding the need for a backend/database while making it possible to use versioning or [config template](https://docs.ansible.com/ansible/latest/user_guide/playbooks_templating.html).
 - Only modern browsers are supported, feel free to use any JS features without any polyfill as soon as the latest version of the major browsers supports them.
@@ -33,6 +33,16 @@ For all contributions, please respect the following guidelines:
 If you want to add a feature, it's often best to talk about it before starting to work on it and submitting a pull request. It's not mandatory at all, but
 feel free to open an issue to present your idea.
 
+### Working with AI Agents
+
+This repository include an [`AGENTS.md`](https://github.com/bastienwirtz/homer/blob/main/AGENTS.md) instruction file for agents. It use an [open format](https://agents.md/), which most agent should natively use for context. However, for specific agent like Claude Code or Gemini, you will have to specifically ask it to read the file or create symlink:  
+
+```sh
+ln -s AGENTS.md CLAUDE.md
+ln -s AGENTS.md GEMINI.md
+```
+
+
 ### How to submit a contribution
 
 The general process to submit a contribution is as follow: