narova-stock-extensions git:20260810.2c49e20A

Immutable. This exact content never changes and is served at /api/v1/blob/3b6860966346a01d.

---
name: narova-stock-extensions
description: Use this optional Narova companion when a video needs stock photos, stock video, sound effects, cultural media, free 2D illustrations/icons, free 3D models, textures, HDRIs, or a provider beyond Narova's essential Wikimedia, Openverse, NASA, Internet Archive, Iconify, and Poly Haven adapters. It adds deterministic Met, Cleveland Museum, Library of Congress, Pexels, Pixabay, and Freesound adapters, while preserving a flexible browser/LLM route for long-tail public sources. Use it when the user requests stock extensions, broad provider exploration, browser-sourced media, or exhaustive creative-asset sourcing. Do not require optional API keys and do not treat a search result as proof of downloadable bytes or rights.
---

# Narova Stock Extensions

This skill extends Narova's essential stock pack. It does not replace Narova's
asset registry: all downloads return through core for atomic publication,
hashing, provenance, rights, verification, and credits.

## Start

Use the repository script directly, or install the small launcher:

```bash
bash skills/narova-stock-extensions/tool/setup.sh
narova-stock providers
```

The launcher delegates essential providers to `narova` and handles extension
provider API translation itself. Missing `PEXELS_API_KEY`, `PIXABAY_API_KEY`, or
`FREESOUND_API_KEY` disables only that provider.

`narova-stock providers` lists three explicit modes:

- `essential-api`: deterministic no-key core adapters.
- `extension-api`: deterministic no-key or optional-key companion adapters.
- `llm-browser`: loose discovery sources that require current browser/LLM
  inspection and are shown as `explore`, never as verified or ready.

## Workflow

1. Read [references/providers.md](references/providers.md) when choosing a
   provider, using 2D/3D sources, or leaving the deterministic list. Run
   `narova-stock providers` to enumerate every API and loose provider.
2. Run `narova-stock providers`. Prefer a ready deterministic provider that
   fits the scene and media kind.
3. Search, inspect the normalized candidates, then acquire the selected ID:

   ```bash
   narova-stock search "our lady" --provider met --kind image --limit 5 --json
   narova-stock acquire 764091 --provider met --kind image \
     --output assets/met-artwork.jpg --project .
   ```

4. Run `narova assets verify` and review `narova assets credits`.
5. If deterministic results are creatively weak, use the browser workflow in
   the provider reference. Search public pages, inspect the real item/license,
   and finish with `narova assets download` or `narova assets import`.

Search and acquisition must stay separate so an agent can make a creative
choice. Never search during a build. Never claim a provider works merely because
its search endpoint returned metadata: automated support requires a real byte
download and registry verification in the live suite.

## Provider boundaries

- Essential/core: Wikimedia, Openverse, NASA, Internet Archive, Iconify (free
  2D SVG), and Poly Haven (free CC0 3D models).
- No-key extensions: The Met, Cleveland Museum of Art, and Library of Congress.
- Optional-key extensions: Pexels, Pixabay, and Freesound.
- Browser/LLM extensions: the larger discovery catalogue in the provider
  reference and `tool/browser-providers.js`, including free illustration, 3D,
  music, SFX, museum, map, and science sources. Treat each as an
  `llm-browser` provider, not undocumented fallback prose.

The browser path is deliberately loose for creative discovery but strict at the
boundary: record the exact item page, do not bypass site controls, do not invent
a license, and import/download through Narova before using the asset.

## Testing

Unit tests are deterministic:

```bash
npm run test:stock-extensions
```

The explicit live test performs real searches and downloads for essential and
no-key extension providers. Credentialed providers run only when their key is
present and otherwise report a skip:

```bash
npm run test:stock-live:extensions
```

Browser/LLM providers are intentionally not a deterministic matrix. Validate a
representative with the current `agent-browser` core skill: submit a real query,
open a result item, inspect its current license, download real bytes, import the
file through `narova assets import`, and pass `narova assets verify`. Opening a
homepage or seeing search thumbnails is not a passing browser test.