[ENG-3568] Document login for the agents that will run it

[mariojgt]

Follow-up to #150. The command shipped; the instructions for using it did not.

login was one line inside a paragraph about credentials — not enough for an assistant to use it correctly, and this package is installed by AI coding tools far more often than by hand.

The failure this heads off

An agent that sees a missing or rejected credential will reach for the obvious fix: delete .patchstackrc.json and run scan again. That provisions a second site. The original is orphaned — its widget tag already live on the deployed page, its history attached to a record nothing points at any more.

AGENT-INSTALL.md now says so directly, in the place that instinct occurs.

What the section covers

When it applies — credential gone or rejected: file deleted, never committed, cloned without it, container recycled, ingest 401ing.

What the agent must do — surface the link and code verbatim, leave the command running, report the outcome.

What it cannot do alone — approval requires the user's signed-in account. This is deliberately human-in-the-loop: starting a flow proves nothing about who started it, so an owner approving in the browser is the authorisation. An agent must not ask for credentials to do it itself.

Two things it would otherwise get wrong

• Don't kill and retry — each run issues a new code and invalidates the one already on screen.
• Approving rotates: CI secrets, hosting env vars, preview environments and other checkouts all need the new value. The CLI now prints this before approval as well as after, so whoever is deciding sees it in time.

A table of cases where it won't work at all — unclaimed site (409), CI (refuses), no siteUuid, expired code — each with the correct next step.

Verification

1220 tests pass, typecheck clean. Docs and CLI copy only — no behaviour change.

Ref ENG-3568

🤖 Generated with Claude Code

[coderbuds]

Adds detailed login recovery documentation and CLI flow for credential restoration.

🎯 Quality: 94% Elite · 📦 Size: Small

📈 This month: Your 58th PR — above team average · Averaging Excellent

_{See how your team is trending →}

[mariojgt]

/review