headlamp

# AGENTS.md
version: 1
default_agent: "@dev-agent"

> **Consulted files (agent must populate before committing):**
> - `/backend/pkg/k8cache/cacheInvalidation.go`
> - `/backend/pkg/kubeconfig/contextStore.go`
>
> **README.md files:**
> - `/README.md` - Main project README
> - `/frontend/README.md` - Frontend-specific README
> - `/backend/README.md` - Backend quickstart guide
> - `/app/README.md` - Desktop app README
> - `/e2e-tests/README.md` - End-to-end testing README
> - `/load-tests/README.md` - Load testing guide
> - `/plugins/README.md` - Plugins overview
> - `/plugins/headlamp-plugin/README.md` - Plugin development tools
> - `/plugins/pluginctl/README.md` - Plugin control utility
> - `/backend/pkg/telemetry/README.md` - Telemetry module
> - `/docker-extension/README.md` - Docker extension
> - `/charts/headlamp/README.md` - Helm chart
> - `/backstage-test/README.md` - Backstage integration test
> - `/tools/i18n/README.md` - Internationalization tools
> - `/eslint-config/README.md` - ESLint configuration
> - `/frontend/src/i18n/README.md` - Frontend i18n
> - `/app/e2e-tests/README.md` - Desktop app e2e tests
> - Plugin examples: `/plugins/examples/*/README.md` (multiple examples)
>
> **Documentation files:**
> - `/docs/development/index.md` - Main development guide with build/run commands
> - `/docs/development/frontend.md` - Frontend development guide
> - `/docs/development/backend.md` - Backend development guide with testing commands
> - `/docs/development/app.md` - Desktop app development guide
> - `/docs/development/testing.md` - Load testing guide
> - `/docs/development/architecture.md` - Architecture documentation
> - `/docs/development/plugins/index.md` - Plugin system overview
> - `/docs/development/plugins/building.md` - Plugin building guide
> - `/docs/development/plugins/getting-started.md` - Plugin getting started
> - `/docs/development/plugins/publishing.md` - Plugin publishing guide
> - `/docs/development/i18n/index.md` - Internationalization guide
> - `/docs/development/release-guide.md` - Release process
> - `/docs/installation/index.mdx` - Installation instructions
> - `/docs/installation/in-cluster/index.md` - In-cluster deployment
> - `/docs/installation/desktop/index.mdx` - Desktop installation
> - `/docs/contributing.md` - Contribution guidelines
> - `/docs/faq.md` - Frequently asked questions
> - `/docs/platforms.md` - Tested platforms list
>
> **Build/Config files:**
> - `/package.json` - Root package with all npm scripts and Node.js version (>=20.11.1)
> - `/backend/go.mod` - Go version (1.25.9)
> - `/CONTRIBUTING.md` - Contributing guidelines
> - `/OWNERS` - Code reviewers and approvers

---

### Agent persona and scope
- **@dev-agent** — pragmatic, conservative, test-first, risk-averse.
- **Scope:** propose, validate, and prepare code/docs patches; run local build/test commands; create PR drafts.
- **Not allowed:** push images/releases, modify CI or infra, or merge without human approval.

---

### Explicit non-goals
should NOT unless explicitly requested or strictly necessary for the change
- Propose refactors without a clear bug, performance, or maintenance justification
- Change public APIs without explicit request
- Reformat unrelated code
- Rename files or symbols for stylistic reasons
- Introduce new dependencies unless required to fix a bug or implement a requested feature and an existing dependency can not be used

---

### Tech stack and environment
- **Languages:** TypeScript (frontend), Go (backend).
- **Runtimes/tools:**
  - Node.js >=20.11.1 (specified in `/package.json` engines field)
  - npm >=10.0.0 (specified in `/package.json` engines field)
  - Go 1.25.9 (specified in `/backend/go.mod`)
- **Reproduce locally:** Use commands from `/package.json` scripts section and documentation files listed above.

---

### Repo map
- **`frontend/`** — UI code (TypeScript/React); see `/frontend/README.md` and `/docs/development/frontend.md` for build/run/test commands.
- **`backend/`** — Go server and API; see `/backend/README.md` and `/docs/development/backend.md` for server commands.
- **`docs/`** — all developer and user docs; reference specific files under `docs/` for workflows.
- **`plugins/`** — plugin system and examples; see `/plugins/README.md` and `/docs/development/plugins/`.
- **`app/`** — desktop application (Electron); see `/app/README.md` and `/docs/development/app.md` for build/run/test commands.
- **CI & infra:** `.github/workflows/`, Dockerfiles (`/Dockerfile`, `/Dockerfile.plugins`), Kubernetes manifests (`kubernetes-headlamp*.yaml`), Helm charts (`/charts/`) — treat as manual-review-only.

---

### Primary entry points (exact commands from repository)

#### Build commands (from `/package.json` and `/docs/development/index.md`):
- **Build everything:** `npm run build` (builds backend and frontend - from `/package.json`)
- **Build frontend only:** `npm run frontend:build` (from `/package.json`, documented in `/docs/development/frontend.md`)
- **Build backend only:** `npm run backend:build` (from `/package.json`, documented in `/docs/development/backend.md`)
- **Build desktop app:** `npm run app:build` (from `/package.json`)

#### Run commands (from `/package.json` and `/docs/development/index.md`):
- **Run both backend and frontend:** `npm start` (from `/package.json`, documented in `/docs/development/index.md`)
- **Run backend only:** `npm run backend:start` (from `/package.json`, documented in `/docs/development/backend.md`)
- **Run frontend only:** `npm run frontend:start` (from `/package.json`, documented in `/docs/development/frontend.md`)
- **Run desktop app:** `npm run app:start` (from `/package.json`)

#### Test commands (from `/package.json` and `/docs/development/backend.md`):
- **Run all tests:** `npm test` (from `/package.json`)
- **Backend tests:** `npm run backend:test` (from `/package.json`, documented in `/docs/development/backend.md`)
- **Backend coverage:** `npm run backend:coverage` (from `/package.json`, documented in `/docs/development/backend.md`)
- **Backend coverage HTML:** `npm run backend:coverage:html` (from `/package.json`, documented in `/docs/development/backend.md`)
- **Frontend tests:** `npm run frontend:test` (from `/package.json`)
- **App unit tests:** `npm run app:test:unit` (from `/package.json`)
- **App e2e tests:** `npm run app:test:e2e` (from `/package.json`)

#### Lint commands (from `/package.json` and `/docs/development/backend.md`):
- **Lint all:** `npm run lint` (from `/package.json`)
- **Lint backend:** `npm run backend:lint` (from `/package.json`, documented in `/docs/development/backend.md`)
- **Lint backend (fix):** `npm run backend:lint:fix` (from `/package.json`, documented in `/docs/development/backend.md`)
- **Lint frontend:** `npm run frontend:lint` (from `/package.json`)
- **Lint frontend (fix):** `npm run frontend:lint:fix` (from `/package.json`)
- **Lint app:** `npm run app:lint` (from `/package.json`, documented in `/docs/development/app.md`)
- **Lint app (fix):** `npm run app:lint:fix` (from `/package.json`, documented in `/docs/development/app.md`)

#### Format commands (from `/package.json` and `/docs/development/backend.md`):
- **Format backend:** `npm run backend:format` (from `/package.json`, documented in `/docs/development/backend.md`)
- **Format and lint frontend:** `npm run frontend:lint:fix` (from `/package.json`)
- **Format app:** `npm run app:format` (from `/package.json`, documented in `/docs/development/app.md`)

#### Documentation generation (from `/package.json` and `/docs/development/frontend.md`):
- **Generate API docs:** `npm run docs` (from `/package.json`, documented in `/docs/development/frontend.md`)

#### Storybook (from `/package.json` and `/docs/development/frontend.md`):
- **Run Storybook:** `npm run frontend:storybook` (from `/package.json`, documented in `/docs/development/frontend.md`)
- **Build Storybook:** `npm run frontend:build:storybook` (from `/package.json`)

---

### Allowed commands and CI interactions
- **Permitted to suggest/run locally:**
  - All npm scripts from `/package.json`
  - Go commands: `go build`, `go test`, `go fmt` (documented in `/docs/development/backend.md`)
  - Node/npm commands: `npm install`, `npm run build`, `npm run test`, `npm start`
- **Require human approval:**
  - Pushing container images (references in `/docs/development/index.md`)
  - Publishing releases (process documented in `/docs/development/release-guide.md`)
  - Modifying `.github/workflows/*`
  - Changing `Dockerfile` or `/Dockerfile.plugins`
  - Altering Kubernetes manifests (`kubernetes-headlamp*.yaml`)
  - Modifying Helm charts in `/charts/`
- **Reporting CI results:** GitHub Actions workflows in `.github/workflows/` - summarize failing steps, include logs, recommend fixes with local reproduction commands.

---

### Change rules and safety constraints
- **Manual-review-only:**
  - `.github/workflows/*` - CI workflows
  - `Dockerfile`, `Dockerfile.plugins` - container definitions
  - `charts/` - Helm charts
  - `kubernetes-*.yaml` - Kubernetes manifests
  - `SECURITY.md`, `SECURITY_CONTACTS` - security policy files
  - `OWNERS`, `OWNERS_ALIASES` - maintainer lists (documented in `/OWNERS`)
  - `LICENSE`, `NOTICE` - license files
  - `code-of-conduct.md` - code of conduct
- **Pre-change checks:**
  - Run `npm run lint` (from `/package.json`)
  - Run `npm test` (from `/package.json`)
  - Run `npm run backend:test` for backend changes (from `/package.json`)
  - Run `npm run frontend:test` for frontend changes (from `/package.json`)
  - Run `npm run backend:format` for backend code formatting (from `/package.json`)
  - Run `npm run frontend:lint:fix` for frontend code formatting (from `/package.json`)
  - Run TypeScript compiler: `npm run frontend:tsc` (from `/package.json`) or `npm run app:tsc` (from `/package.json`)
  - Run e2e tests for UI changes: `npm run app:test:e2e` (from `/package.json`)
- **Dependency updates:**
  - Run full test suite: `npm test`
  - Tag maintainers from `/OWNERS` (headlamp-maintainers, headlamp-reviewers)
  - Do not bump major versions without approval
- **Licenses/copyright:**
  - Do not alter `/LICENSE` or `/NOTICE` files
  - Do not modify copyright headers

---

### Best practices and coding guidelines
- **Reduce solution size:**
  - Make minimal, surgical changes - modify as few lines as possible to achieve the goal
  - Prefer focused, single-purpose changes over large refactors
  - Break down complex changes into smaller, reviewable increments
  - Remove unnecessary code, dependencies, or complexity when fixing issues
- **Testing best practices:**
  - Avoid using mocks in tests if possible - prefer testing with real implementations
  - Use integration tests over unit tests when it improves test reliability
  - Only mock external dependencies (APIs, databases, file systems) when necessary
  - Write tests that validate actual behavior, not implementation details
- **Consider best practices for the type of change:**
  - **Bug fixes:** Add regression tests, verify the fix doesn't break existing functionality
  - **New features:** Follow existing patterns, add comprehensive tests, update documentation
  - **Refactoring:** Ensure behavior remains unchanged, validate with existing tests
  - **Performance:** Add benchmarks, measure before and after, document improvements
  - **Security:** Follow secure coding practices, validate inputs, avoid common vulnerabilities
  - **Documentation:** Keep it concise, accurate, and consistent with code examples
- **Frontend-specific guidelines:**
  - **Screenshots:** Always include screenshots for UI changes in PRs to show visual impact
  - **React components:** Add Storybook stories with error and loading states for new components (use `npm run frontend:storybook`)
  - **Formatting:** Run `npm run frontend:lint:fix` to format code before committing
  - **End-to-end tests:** For significant UI changes, consider adding or updating e2e tests (`npm run app:test:e2e`)

---

### Examples and templates

#### Example 1: Small frontend code fix
- **Files to change:** `frontend/src/components/Example.tsx` (example path)
- **Rationale:** Fix null-check to avoid runtime error
- **Commands to validate:**
  1. `npm run frontend:install` (from `/package.json`)
  2. `npm run frontend:lint:fix` (from `/package.json`) - format code
  3. `npm run frontend:lint` (from `/package.json`)
  4. `npm run frontend:test` (from `/package.json`)
  5. `npm run frontend:tsc` (from `/package.json`)
  6. `npm run app:test:e2e` (from `/package.json`) - if UI changes
- **Additional requirements:**
  - Include screenshots of any UI changes in the PR
  - If adding/modifying React components, add Storybook stories with error and loading states

#### Example 2: Backend code fix
- **Files to change:** `backend/pkg/example/handler.go` (example path)
- **Rationale:** Fix error handling in API endpoint
- **Commands to validate:**
  1. `npm run backend:build` (from `/package.json`, documented in `/docs/development/backend.md`)
  2. `npm run backend:lint` (from `/package.json`, documented in `/docs/development/backend.md`)
  3. `npm run backend:test` (from `/package.json`, documented in `/docs/development/backend.md`)
  4. `npm run backend:format` (from `/package.json`, documented in `/docs/development/backend.md`)

#### Example 3: Desktop app code fix
- **Files to change:** `app/electron/example.ts` (example path)
- **Rationale:** Fix window management issue in Electron app
- **Commands to validate:**
  1. `npm run app:install` (from `/package.json`)
  2. `npm run app:lint:fix` (from `/package.json`, documented in `/docs/development/app.md`)
  3. `npm run app:format` (from `/package.json`, documented in `/docs/development/app.md`)
  4. `npm run app:lint` (from `/package.json`, documented in `/docs/development/app.md`)
  5. `npm run app:tsc` (from `/package.json`, documented in `/docs/development/app.md`)
  6. `npm run app:test` (from `/package.json`, documented in `/docs/development/app.md`)

#### Example 4: Documentation update
- **Files to change:** `docs/development/index.md` (from consulted files list)
- **Rationale:** Clarify local dev startup steps to match current npm scripts
- **Commands to validate:**
  - Run the documented commands exactly as written and confirm they succeed
  - For doc-only changes, testing commands is sufficient; no build needed

#### Example 5: Plugin development
- **Files to change:** Plugin code in `/plugins/examples/` directory
- **Rationale:** Add new plugin example
- **Commands to validate:**
  1. `cd plugins/headlamp-plugin && npm install` (from `/package.json`)
  2. Follow plugin testing commands in `/docs/development/plugins/building.md`

---

### PR review and authoring policy

Reference sources:
- `/.github/copilot-instructions.md` for Copilot PR review rules.
- `/docs/contributing.md` for commit message and PR description guidance.
- `/.github/pull_request_template.md` for PR body structure.

#### Commit message format (from `/docs/contributing.md`):
- **Format:** `<area>: <description of changes>`
- **Examples:**
  - `frontend: HomeButton: Fix so it navigates to home`
  - `backend: config: Add enable-dynamic-clusters flag`
- **Guidelines:**
  - Use atomic commits - keep each commit focused on a single change
  - Keep commit titles under 72 characters (soft requirement)
  - Commit messages should explain the intention and _why_ something is done
  - Commit titles should be meaningful and describe _what_ the commit does
  - Use `git rebase` to squash and order commits for easy review
  - Do not write "Fixes #NN" issue number in the commit message

#### PR description template (from `/.github/pull_request_template.md`):
- **Summary:** Brief description of what the change does
- **Related Issue:** Link via `Fixes #ISSUE_NUMBER` if applicable
- **Changes:** List of added/updated/fixed components
- **Steps to Test:** Numbered steps to verify the changes
- **Screenshots:** Include for UI changes
- **Notes for the Reviewer:** Any relevant context or areas to focus on

#### PR authoring guidelines (from `/docs/contributing.md`):
- Run tests: `npm run frontend:test`, `npm run backend:test`
- Run linters: `npm run frontend:lint`, `npm run backend:lint`
- Summarize changes and explain _why_ they are needed
- Provide steps to test the changes
- Link to related issue via `Fixes #ISSUE_NUMBER`

---

### Agent output checklist (must pass before creating patch/PR)
- **Summary:** one-line intent and short rationale
- **Sources:** list consulted README/docs file paths with specific line numbers
- **Files changed:** explicit file list with rationale for each
- **Diff/patch:** minimal unified diff showing only necessary changes
- **Tests:**
  - List tests added/updated
  - Exact commands to run them (from `/package.json`)
  - Test results showing pass status
- **Local validation:**
  - Exact commands to reproduce build/test results
  - Output showing successful execution
  - For frontend: verify in browser at `localhost:3000` (from `/docs/development/frontend.md`)
  - For backend: verify server starts successfully (from `/docs/development/backend.md`)
- **CI expectations:**
  - Which workflows in `.github/workflows/` should pass
  - Expected test coverage (documented in `/docs/development/backend.md` lines 60-67)
- **Reviewers:**
  - Suggested reviewers from `/OWNERS`: headlamp-maintainers, headlamp-reviewers
  - Tag specific maintainers for specialized areas if needed

---

### Appendix

#### All consulted README.md files:
1. `/README.md` - Main project README with overview, features, quickstart
2. `/frontend/README.md` - Frontend module pointer to docs
3. `/backend/README.md` - Backend quickstart with build/run commands
4. `/app/README.md` - Desktop app information
5. `/e2e-tests/README.md` - End-to-end testing guide
6. `/load-tests/README.md` - Load testing with KWOK
7. `/plugins/README.md` - Plugins overview
8. `/plugins/headlamp-plugin/README.md` - Plugin development tools
9. `/plugins/headlamp-plugin/template/README.md` - Plugin template
10. `/plugins/pluginctl/README.md` - Plugin control utility
11. `/backend/pkg/telemetry/README.md` - Telemetry module
12. `/docker-extension/README.md` - Docker extension
13. `/charts/headlamp/README.md` - Helm chart documentation
14. `/backstage-test/README.md` - Backstage integration
15. `/tools/i18n/README.md` - Internationalization tools
16. `/eslint-config/README.md` - ESLint configuration
17. `/frontend/src/i18n/README.md` - Frontend i18n
18. `/app/e2e-tests/README.md` - Desktop app e2e tests
19. Plugin examples in `/plugins/examples/` (activity, app-menus, change-logo, cluster-chooser, custom-theme, customizing-map, details-view, dynamic-clusters, headlamp-events, pod-counter, projects, resource-charts, sidebar, tables, ui-panels)

#### Key documentation files:
1. `/docs/development/index.md` - Primary development guide (lines 1-310)
2. `/docs/development/frontend.md` - Frontend dev guide (lines 1-82)
3. `/docs/development/backend.md` - Backend dev guide (lines 1-69)
4. `/docs/development/app.md` - Desktop app dev guide
5. `/docs/development/testing.md` - Testing guide (lines 1-83)
6. `/docs/development/architecture.md` - System architecture
7. `/docs/development/plugins/index.md` - Plugin system
8. `/docs/development/plugins/building.md` - Building plugins
9. `/docs/development/plugins/getting-started.md` - Plugin quickstart
10. `/docs/development/plugins/publishing.md` - Publishing plugins
11. `/docs/development/plugins/common-patterns.md` - Plugin patterns
12. `/docs/development/i18n/index.md` - Internationalization
13. `/docs/development/release-guide.md` - Release process
14. `/docs/contributing.md` - Contribution guidelines
15. `/docs/faq.md` - FAQ
16. `/docs/platforms.md` - Tested platforms

#### Versioning guidance:
- Follow semantic versioning (documented in `/docs/development/release-guide.md`)
- App version defined in `/app/package.json`
- Docker image version from git tags
- Request maintainer approval for version bumps and releases
- Release process documented in `/docs/development/release-guide.md`

---

## Final instructions for the agent (implementation complete)
1. ✅ **Searched the repository** for all `README.md` files and files under `docs/` - listed their relative paths in "Consulted files" section above
2. ✅ **Extracted exact commands and versions** from package.json, go.mod, and documentation - replaced all placeholders with exact text and file path citations
3. ✅ **Commands are ready for validation** - all commands listed can be run locally following the exact syntax provided
4. ✅ **File is ready for commit** - consulted-files list is complete and all placeholders have been replaced with exact commands and paths from the repository

**Version Information:**
- Node.js: >=20.11.1 (from `/package.json`)
- npm: >=10.0.0 (from `/package.json`)
- Go: 1.25.9 (from `/backend/go.mod`)

**Key Command Sources:**
- Build/test commands: `/package.json`
- Development workflow: `/docs/development/index.md`
- Backend specifics: `/docs/development/backend.md`
- Frontend specifics: `/docs/development/frontend.md`