# Proposal

## Why

On the live deployment (`podp`), two queues ended up with the identical CUPS
Description, so both derived the same DNS-SD instance name
(`"<Description> @ <host>"`). Avahi can register only one of them and CUPS 2.4
never resolves the collision (upstream `scheduler/dnssd.c` still has
`/* TODO: Handle collisions with avahi_alternate_service_name */`), so one queue
showed `printer-is-shared=true` but was never advertised. macOS pins the exact
instance name into the queue's `dnssd://` device URI; when the pinned name stops
being announced, the Mac reports the printer **offline**. Because the collision
is deterministic, container restarts never helped and only remove/re-add on the
client fixed it — hours of debugging with no server-side signal pointing at the
cause.

## What Changes

- **`entrypoint.sh`**: after cupsd is up, derive the DNS-SD instance name of
  every shared queue (`Description` if set, otherwise the queue name, plus
  `@ <host>`) and log a prominent, non-fatal warning when two or more queues
  derive the same instance name — naming the affected queues and the fix
  (give each queue a unique Description, or delete the redundant queue).
- **`README.md`**: new Troubleshooting entry "macOS shows the printer offline
  after some time" documenting the symptom, root cause (client-side instance
  name pinning + duplicate-Description collision), verification commands
  (`dns-sd -B`, `lpstat -l -p`, `ipptool`), and the fix including the
  remove/re-add step on macOS.
- **Docs correction**: the `PRINTER_NAME` description in the `entrypoint.sh`
  header and in the README currently claims it is the "advertised (DNS-SD)
  name" — that is only true while no Description is set; the Description
  overrides it. Correct both places, and clarify the matching requirement in
  the `printserver/cups` spec (same claim).

Out of scope: changing how queues are configured (no automatic renaming or
de-duplication), and avoiding the `lpadmin` re-registration churn on restart.

## Capabilities

### New Capabilities

(none)

### Modified Capabilities

- `printserver/cups`: adds a requirement that the container detects DNS-SD
  instance-name collisions between shared queues at startup and reports them in
  the container log, so a queue that silently loses its advertisement is visible
  to the operator instead of surfacing as an "offline" client hours later.

## Impact

- `entrypoint.sh` — one additional startup diagnostic block (log output only;
  no change to queue creation, advertisement, or exit behaviour).
- `README.md` — one new Troubleshooting section; correction of the
  `PRINTER_NAME` wording.
- No changes to `cupsd.conf`, the `Containerfile`, or runtime behaviour seen by
  clients; the fix for an existing collision is still a manual operator action
  (documented in the README).