git:20260810.2c49e20 to git:20260811.08891f1

37 added, 79 removed. Audit A to A.

---

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.

+ description: Use this optional Narova companion for broad, creative internet sourcing when the built-in stock adapters do not produce a suitable photo, video, audio file, font, 2D asset, 3D asset, texture, HDRI, map, scientific visual, or cultural object. Use it when the user requests exhaustive provider exploration, browser-sourced media, or an LLM-led search across changing websites. Work with the available web search, HTTP, or interactive browser capability; do not require a browser. Keep discovery flexible, inspect the selected item and rights, and return downloaded bytes through Narova's core asset lifecycle.

---

# 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.

+ Use this skill as Narova's flexible discovery layer. Do not install another CLI

+ or implement stable provider APIs here. Narova core owns all repeatable search,

+ download, normalization, hashing, provenance, verification, and credits.

## 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:

+ 1. Run `narova assets providers`. Prefer a ready core adapter matching the

+ required media kind. Missing optional credentials must not block other

+ providers.

+ 2. Search core with `narova assets search`, inspect candidates, and acquire only

+ the chosen item with `narova assets acquire`.

+ 3. If the results are creatively weak, read

+ [references/providers.md](references/providers.md) and choose a small number

+ of relevant loose providers.

+ 4. Use the least complex capability currently available:

+ - use web search/open or direct HTTP for readable public pages and files;

+ - use an interactive browser for JavaScript search, item inspection, or an

+ explicit download action;

+ - without web access, work only from user-supplied pages/files or return a

+ sourcing plan. Never pretend that an unvisited provider was checked.

+ 5. Inspect the exact item page, file, dimensions or duration, creator, and

+ item-level license. A homepage or thumbnail is discovery evidence only.

+ 6. Finish through `narova assets download` for an official direct URL or

+ `narova assets import` for bytes already downloaded by a browser or user.

+ Record the provider, item ID, source page, and only rights actually shown.

+ 7. Run `narova assets verify` and review `narova assets credits` before using

+ the asset.

- ```bash

- npm run test:stock-extensions

- ```

+ Keep search separate from acquisition so creative selection stays deliberate.

+ Never search during a build, bypass site controls, infer a license from a

+ provider-wide reputation, or claim a loose provider is mechanically supported.

- 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:

+ ## Core boundary

- ```bash

- npm run test:stock-live:extensions

- ```

+ The built-in CLI includes Wikimedia Commons, Openverse, NASA, Internet Archive,

+ Iconify, Poly Haven, The Met, Cleveland Museum of Art, Library of Congress,

+ Pexels, Pixabay, and Freesound. Pexels, Pixabay, and Freesound become ready only

+ when their optional environment key is present.

- 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.

+ Everything in the provider reference is LLM-led discovery. Some sources work

+ with ordinary search or HTTP; others require a browser. Their changing flows

+ remain intentionally outside core until a stable adapter can pass real search,

+ download, registry, and verification tests.