Document repo install workflow for agents

AGENTS.md

@@ -0,0 +1,80 @@
+# 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.
+- 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 from the repository so the running local service matches the repo:
+   ```sh
+   make upgrade-local
+   ```
+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.
+
+## Install Model
+
+- The service virtualenv lives at `/opt/importarr/venv`.
+- The systemd unit runs `/opt/importarr/venv/bin/importarr` as the `importarr` system user.
+- 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
+
+- 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.

README.md

@@ -113,3 +113,29 @@ Importarr should not drift into host-local scripts. Treat the checked-out reposi
 5. Verify the live service: `make verify-live`.
 
 Do not edit `/usr/local/sbin/importarr-status.py`, `/usr/local/sbin/manual-media-import.py`, or files copied out of the repo as the normal workflow. If an emergency live hotfix is unavoidable, backport it to this repository immediately and run the repo install workflow again.
+
+### Local install lessons learned
+
+- The live systemd service runs as the unprivileged `importarr` user.
+- Do not install the system service with `pip install --editable /srv/opencode-workspace/importarr`; that can fail at startup if the service user cannot read the workspace checkout.
+- The supported local service install is a normal package install from the repo into `/opt/importarr/venv`:
+
+```sh
+sudo -n /opt/importarr/venv/bin/pip install --upgrade /srv/opencode-workspace/importarr
+sudo -n systemctl restart importarr.service
+```
+
+- `deploy/systemd-install.sh`, `make upgrade-local`, and `/opt/importarr/repo-upgrade.sh` already use this supported model.
+- After every implementation task that should affect the live local service, run:
+
+```sh
+make upgrade-local
+make verify-live
+```
+
+- If `make verify-live` fails, check:
+
+```sh
+sudo -n systemctl --no-pager --full status importarr.service
+sudo -n journalctl -u importarr.service -n 120 --no-pager
+```