# Importarr Agent Instructions

Importarr is owned as a Linux-ops-managed service repository. Treat this checkout as the source of truth for application code, deployment files, and local service installs.

## Repository Source Of Truth

- Work from `/srv/opencode-workspace/importarr` for Importarr code and deploy changes.
- The live service is installed on `dgsserver1` from a repo checkout at `/opt/importarr/repo`; gmk1 installs are not the public Importarr service.
- Do not edit host-local legacy scripts as the normal workflow:
  - `/usr/local/sbin/importarr-status.py`
  - `/usr/local/sbin/manual-media-import.py`
- If an emergency hotfix is made outside the repo, backport it here immediately and reinstall from the repo.

## Seamless Feature Workflow

When asked to implement an Importarr feature, fix, UI change, deployment change, or operational behavior change:

1. Inspect `git status --short --branch` before editing.
2. Implement the smallest correct repo change.
3. Run the narrowest useful verification, normally:
   ```sh
   .venv/bin/pytest -q
   ```
   If shell deploy scripts changed, also run:
   ```sh
   sh -n deploy/systemd-install.sh && sh -n deploy/repo-upgrade.sh
   ```
4. Inspect `git diff` and ensure no secrets, raw `.env`, tokens, databases, or private material are included.
5. Commit and push completed Importarr changes by default unless the user explicitly asks not to publish or verification is blocked.
6. Install/restart on `dgsserver1` from the repository so the public service matches the repo:
    ```sh
    ssh -p 2222 opencode@dgsserver1 'sudo -n sh /opt/importarr/repo-upgrade.sh'
    ```
7. Verify the live service:
   ```sh
   make verify-live
   ```
8. If the live install fails, inspect `systemctl status importarr.service` and `journalctl -u importarr.service`; fix the repo, commit/push the fix, reinstall, and verify again.

## Gitea Issue Completion Workflow

When the user points an agent at an Importarr Gitea issue and asks to solve it, the expected end-to-end flow is mandatory unless the user explicitly says not to deploy:

1. Read the issue first, including comments and acceptance criteria.
2. Implement the smallest correct repo change on a dedicated issue branch when appropriate.
3. Run the narrowest useful tests/checks.
4. Commit and push the completed change to `main` or merge/push the issue branch as instructed.
5. Update the Gitea issue with what changed and the verification that ran, then close it when solved.
6. Update the `dgsserver1` install from the pushed repo state:
   ```sh
   ssh -p 2222 opencode@dgsserver1 'sudo -n sh /opt/importarr/repo-upgrade.sh'
   ```
7. Restart/verify the `dgsserver1` service from the repo-managed install and confirm the public URL:
   ```sh
   ssh -p 2222 opencode@dgsserver1 'sudo -n systemctl status importarr.service --no-pager -l'
   curl -fsS https://importarr.delphas.dk/health
   ```

If the worker timer is intentionally paused, do not re-enable it unless the issue explicitly includes worker scheduling or the user approves.

## Install Model

- The service virtualenv lives at `/opt/importarr/venv` on `dgsserver1`.
- The status UI systemd unit runs `/opt/importarr/venv/bin/importarr-status` from the packaged repo install.
- The manual worker systemd unit runs `/opt/importarr/venv/bin/manual-media-import` from the packaged repo install.
- The package is installed from the repository into the venv using normal wheel/package install, not editable install.
- Do **not** use editable install for the system service: the unprivileged `importarr` user may not be able to read `/srv/opencode-workspace/importarr`, causing `ModuleNotFoundError` at startup.
- `/opt/importarr/repo-upgrade.sh` is the pull-and-reinstall helper for machines that should follow pushed `main`.

## Local Commands

```sh
make test
make install-systemd
make upgrade-local
make repo-upgrade
make verify-live
```

`make repo-upgrade` is for pulling already-pushed changes with `git pull --ff-only`. It refuses to run with uncommitted repo changes.

## Runtime Defaults On This Host

- Public URL: `https://importarr.delphas.dk/`
- dgsserver1 local URL: `http://127.0.0.1:8095/`
- Health: `http://127.0.0.1:8095/health`
- Status: `http://127.0.0.1:8095/api/status`
- Systemd service: `importarr.service`
- Env file: `/etc/importarr/importarr.env`
- SQLite state: `/var/lib/importarr/importarr.db`

## Secret Handling

- Prefer `*_FILE` settings for secrets, for example:
  - `IMPORTARR_SAB_API_KEY_FILE`
  - `IMPORTARR_AUTH_TOKEN_FILE`
  - `IMPORTARR_RADARR_API_KEY_FILE`
  - `IMPORTARR_SONARR_API_KEY_FILE`
- Never commit real env files, API keys, tokens, private keys, service databases, or backup data.
- Template files may list variable names with placeholder values or commented examples only.

## Linux Ops Follow-Through

For changes that materially alter the live service setup, ports, routes, monitoring, backup coverage, or host ownership, also follow the linux-ops documentation/systems-overview update rules. Do not mix unrelated pre-existing uncommitted changes from `linux-ops-docs` or `systems-overview` into Importarr commits.