fix: auto-download URL-sourced documents on view/crop with notice and progress

[yuanwen-tian]

Why

QA follow-up on the v1.0.2 "[STG-PROD][ADE][ADE-CLI] doc preview doesn't load after parsing with document URL" ticket: the --download flag added in #169's follow-up fixed the preview, but only opt-in — a plain ade view <id> on a URL-sourced parse still reported pages_embedded: 0, and a user who didn't know the flag saw an empty preview. Decision: the download becomes the default, said out loud rather than silent.

What changes

• ade view auto-fetches: a URL-sourced item with no attached copy downloads on first view — a stderr notice explains why and names the opt-out, and the body streams behind the shared progress line (percent + elapsed rewriting in place on a tty, one line per 10% piped, silent under --json):

  note: job item 01fd4532c57f9b28 was parsed from a URL and no local copy is attached — downloading it so page imagery can render (skip with --no-download)
  downloading document.pdf 45% · 1s
  Viewer for job item 01fd4532c57f9b28 (parse) -> ~/.ade/jobs/…/view.html (built)
    download: fetched document.pdf (662 bytes) into job item 01fd4532c57f9b28
  

• Failure degrades, never breaks: pre-signed URLs expire, so a failed auto-fetch logs the error (downloaded: false + download_error in the payload) and the viewer still builds with the honest empty-preview note — a view that worked yesterday never starts exiting non-zero. Explicit --download keeps the strict contract: failed fetch and non-URL items stay errors.

• --no-download suppresses the fetch on both commands; previews then stay empty with the existing remediation note (reworded as a retry action, since the flag no longer needs discovering).

• ade crop gets the same flow: detect → notice → fetch before rendering. A failed fetch is the crop's failure (no empty-imagery fallback exists), exactly as the no-copy state already was.

• Contract restated in attach.py: a URL fetch is never silent — either asked for at parse time (--keep-copy) or announced before it starts. README, --keep-copy/view/crop help text, payload reference, and remediation hints updated to match.

Verification

• 701 tests pass (new coverage: auto-fetch success/failure/skip for view, stderr notice + progress assertions, crop auto-fetch success/failure, --download strictness on both commands); ruff and ty check src clean; help reference regenerated.
• Verified end-to-end against a seeded store with a throttled localhost server under a real pty: notice renders, progress ticks 0→100%, previews embed in the same run, second run fetches nothing.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Makes URL-sourced documents download automatically when first viewed or cropped, with notices, progress, opt-out behavior, and graceful view failures.

Changes:

• Adds shared announced download and progress handling.
• Integrates automatic fetching into view and crop.
• Updates tests, help, and user documentation.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/ade_cli/attach.py	Adds shared download notice and progress reporting.
src/ade_cli/view.py	Enables automatic fetching with graceful failure handling.
src/ade_cli/crop.py	Enables automatic fetching before cropping.
src/ade_cli/parse.py	Updates --keep-copy guidance.
src/ade_cli/help.py	Updates view payload and artifact documentation.
tests/test_view.py	Covers view download modes and failures.
tests/test_crop.py	Covers crop download modes and failures.
tests/test_serve.py	Prevents unrelated server tests from auto-fetching.
README.md	Documents automatic download behavior.
docs/reference/help.json	Regenerates command help reference.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.