---
name: web-capture
description: "Shared capture-route module for reference/inspiration site URLs: client decision between AIOSON capture (web:save + web:extract) and harness web tools, token-lean reading discipline, fallbacks, and local-reference-only policy."
agents: [briefing-refiner, benchmark, site-forge, sheldon, product, dev]
task_types: [design, research, benchmarking, site-cloning, visual-identity]
load_tier: trigger
triggers: [reference site, inspiration site, site URL, web:save, web:extract, site capture, clone site, site effects, motion reference, extract.md, researchs site, CSS extraction, keyframes reference, visual reference]
---

# Web capture — full-fidelity reference sites

> Load this module on demand when the current task is about to ingest a **reference/inspiration site URL** whose design, effects, motion, or structure matter (identity extraction, benchmark references, site cloning, visual research). Do not load it for plain content reading — harness web tools are fine for text.

Consumers: briefing-refiner (visual route), benchmark (reference research and clones), site-forge (extraction source), and any agent doing visual web research. One module, one behavior — never restate these rules inside agent kernels; point here.

## Why two routes exist

Harness web tools (WebFetch and equivalents) convert pages to markdown and drop CSS/JS — fast and zero-setup, but lossy for design evidence. The AIOSON route mirrors the real sources deterministically and distills them into a token-lean extract. Both are legitimate; which one runs is the **client's decision**.

## The client decision

When a capture-worthy URL enters the task, offer the choice once — do not silently pick:

1. **AIOSON capture (recommended for visual scope)** — deterministic local mirror + distilled extract; quality independent of the harness.
2. **Harness web tools** — direct fetch by the model; faster for a quick look, lossy for CSS/JS/motion.

Resolution order:

- An explicit operator instruction (this session, project rules, or operator memory) applies silently — do not re-ask.
- Under Autopilot with no stated preference, apply option 1 for visual scope and record it as a reviewable routine decision.
- Otherwise ask, in one short line, and proceed.

The route is recorded in `researchs/{slug}/summary.md` (`captured_via: aioson | harness | external-mirror`) so the operator can compare fidelity and token cost between routes in practice. On the AIOSON route the CLI stamps `captured_via: aioson` deterministically (`web:extract` self-heals missing stamps, marking external-mirror captures); only the harness route needs the agent to record `captured_via: harness` itself.

## AIOSON route — commands

```bash
aioson web:save . --url=<url> --slug=<ref-slug>     # mirrors HTML + CSS + JS + fonts/images/media to researchs/<ref-slug>/site/
aioson web:extract . --slug=<ref-slug>              # distills researchs/<ref-slug>/extract.md
```

`web:save` rewrites references to local relative paths, writes `manifest.json` (provenance, counts, failures), seeds `summary.md` when absent, and enforces budgets (150 files / 40MB default; `--max-files`, `--max-bytes`). Individual asset failures are recorded, not fatal.

`extract.md` carries fonts and @font-face files, color palette by frequency, keyframes with bodies, transitions/animations, breakpoints, effect signals (parallax, gradients, backdrop-filter, scroll-snap, reduced-motion), detected JS libraries (gsap, ScrollTrigger, Swiper, three.js, lenis, ...), JS API usage, and section topology.

## Reading discipline (token economy)

- Read `extract.md` first — it is the evidence surface.
- For a targeted follow-up, use `aioson web:extract . --slug=<ref-slug> --query=<text>` (bounded snippets with context).
- **Never bulk-read saved HTML/CSS/JS bundles into context.** Open a raw file only when a query result proves insufficient, and only that file.

## Fallbacks and limits

- JS-rendered SPAs save a thin HTML shell (source CSS/JS still come through); note the limitation instead of retrying.
- Bot protection blocking `web:save`: mirror with an external tool (SaveWebZip, HTTrack, `wget --mirror`) into the same `researchs/<ref-slug>/site/` layout and continue — `web:extract` works on any conforming directory (`--dir=<path>` when outside `researchs/`).

## Usage policy

Saved originals are **local reference only**: never redistributed, never shipped in prototypes or builds, never named as the inspiration in delivered artifacts. Translate observed principles into an original result.