# CLAUDE.md — genieacs-ha

## Overview
Home Assistant custom integration for managing TR-069 CPE devices (routers, ONTs, gateways) through a GenieACS instance. Connects to the GenieACS NBI REST API (port 7557) to surface device status, WAN IP, uptime, and firmware info.

## Tech Stack
- Python (Home Assistant custom component)
- HACS (default store, since 2026-05-21)
- pytest for testing
- Codecov for coverage
- GitHub Actions CI

## Development
```bash
pip install -r requirements-test.txt
pytest tests/
```

Install from the HACS default store (no custom repository needed) or copy `custom_components/genieacs/` into HA config directory.

## Architecture
- `custom_components/genieacs/` — HA integration code (config flow, sensors, binary sensors)
- `tests/` — test suite
- `hacs.json` — HACS metadata
- `docs/` — documentation and images

## Key Rules
- Requires a running GenieACS instance with NBI accessible (default port 7557)
- Minimum Home Assistant version: 2024.1
- Device is considered online if it reported within the last 5 minutes
- Never hardcode ACS URLs or credentials; configured via HA config flow
- Part of the broader GenieACS ecosystem (container, MCP, ansible, sim)

*Generated by [LynxPrompt](https://lynxprompt.geiser.cloud) CLI*

<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6cd5cc61 -->
## Beads Issue Tracker

This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.

### Quick Reference

```bash
bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work
```

### Rules

- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Run `bd prime` for detailed command reference and session close protocol
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files

**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.

## Agent Context Profiles

The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.

- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.

## Session Completion

This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.

1. **File issues for remaining work** - Create beads for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **Handle git/sync by active profile**:
   ```bash
   # Conservative/minimal/default: report status and proposed commands; wait for approval.
   git status

   # Team-maintainer opt-in only, unless current instructions forbid it:
   git pull --rebase
   git push
   git status
   ```
5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step

**Critical rules:**
- Explicit user or orchestrator instructions override this Beads block.
- Do not commit or push without clear authority from the active profile or the current user request.
- If a required sync or push is blocked, stop and report the exact command and error.
<!-- END BEADS INTEGRATION -->

## Where the tracker syncs

This repo is public, so its tracker syncs only to the private remote named by `sync.remote` in `.beads/config.yaml`. The block above says sync uses "your git remote". Here that never means this GitHub repo. Don't add it as a Dolt remote and don't push `refs/dolt/*` to it.