Every release mirrors @viztor/dsh-tinyfish to GitHub Packages — a second source if npmjs.org is unreachable, and what populates the repository sidebar. Only the scoped name mirrors: GitHub links packages to repositories by owner scope. Unlike npmjs, GitHub Packages requires authentication even for public packages: an unauthenticated request 404s without saying whether the package exists. With a token carrying read:packages:

# project-local .npmrc is better than global for a token
@viztor:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=ghp_xxx

then npm install @viztor/dsh-tinyfish resolves from the mirror. Unless npmjs is down, prefer it: no token, no extra configuration.

Everything lives in one row, dsh-tinyfish. The row is validated, so an out-of-range value is rejected with a message rather than silently clamped.

Turning one off reports unavailable rather than missing — the harness tells those apart, and only the second means "the install is broken". But unavailable is not a silent fall-through: if searchProvider/fetchProvider still names TinyFish, the call fails. Point that tool at another provider to use one.

- id: dsh-tinyfish
  config:
    search: true
    fetch: false # TinyFish stays registered but unavailable for fetch; point fetchProvider elsewhere to use another fetch

Manifest metadata, not configuration

The manifest also carries dsh.compatibility: the Node and DSH ranges stated explicitly, plus a per-release verdict — compatible, incompatible, or unknown — for the DSH versions a catalog checks.

DSH itself never reads it. No harness code reads dsh.compatibility, and the dshReleases map appears nowhere in the harness, so these fields cannot change how the plugin loads, registers, or behaves. DSH's own compatibility machinery is a separate thing: the loader checks peerDependencies, and exemptions live in the profile's compatibility.json. These fields exist so a listing can state what has actually been verified, and the verdicts here are honest rather than aspirational: 0.2.0-rc.2 is what every build and test in this repository runs against, 0.2.0-rc.1 is admitted by the peer range but never exercised, and 0.1.7-rc.2 sits below that floor.

Filters and fetch options live in the patch file

filters and fetchOptions are nested objects, and the settings form addresses one flat key per field — so search and fetch tuning stays operator-level:

- id: dsh-tinyfish
  config:
    channel: monid
    filters:
      domainType: research_paper
      language: zh
      includeDomains: arxiv.org,openreview.net
      pubYearMin: 2023
    fetchOptions:
      ttl: 0 # force a live fetch instead of accepting a cached page
      excludeSelectors: nav, .cookie-banner

Both sections always resolve: an unset one is an empty group that adds nothing to the request, and an unusable member degrades to unset rather than travelling upstream. Three upstream caveats pass through as documented behaviour instead of being enforced:

• recencyMinutes and afterDate are mutually exclusive in TinyFish's API; a row setting both sends both.
• excludeSelectors cannot apply to direct PDF/CSV downloads, which answer selector_unsupported while it is set.
• Upstream cross-checks each date bound against domainType: recencyMinutes and afterDate are refused for research_paper, pubYearMin exists only for it, and either wrong pairing rejects the whole search while set.

Where a credential comes from

Resolved per call — a rotated key takes effect on the next search, no restart. First match wins:

1. the apiKey literal in the row (a secret in config; prefer 2–3)
2. the credentials service — apiKeyEnv (direct) or monidKeyEnv (monid), saved from the settings UI
3. the launch environment (exported before DSH started)
4. the live environment — the configured ref name first (apiKeyEnv / monidKeyEnv, which may name a variable of your own), then MONID_API_KEY / MONID_MCP_TOKEN / TINYFISH_API_KEY (either Monid variable covers the monid channel)
5. the channel's CLI store (monid keys add / tinyfish auth login)

A failing service falls through to the next source rather than failing the search.

Where an endpoint comes from

Row, then environment, then built-in default — so staging can retarget without a patch:

• A 404 is a result, not an error. A per-URL fetch failure comes back carrying its status, because that is resource state the model needs.
• publishedAt is honest. TinyFish reports human dates ("Apr 30, 2026", "1 year ago"). What parses becomes ISO-8601; what doesn't is dropped, never invented. A date-only value with no zone reads as UTC, so the same page reports the same day everywhere; a value carrying a clock time is parsed as given.
• Empty searches retry. The upstream answers a valid query with nothing about one run in three — a blank result is retried until the attempt budget (attempts, total tries) runs out before it is believed.
• A blocked run is terminal. If a Monid workspace control stops a run, the error says why and links to top up. Never retried.
• Off means unavailable, not gone. A switched-off kind stays registered and declines. If the profile still pins that tool to Tinyfish, the call fails loudly instead of silently rerouting — point the tool at another provider to use one. With nothing pinned, a withdrawn Tinyfish simply yields: auto-select picks whoever is left, and switching one kind off is how you resolve an "ambiguous provider" standoff down to a single candidate.
• Unavailable has three causes and one message. The seam only sees a boolean, so "switched off", "no credential", and "bad base URL" all read the same downstream. The card can tell them apart — check the switches and the key badges there, and the endpoint overrides in the row or the environment.
• purpose is one sentence for every request. The seam's requests carry no goal slot — {query} for search, {url} for fetch — so a per-call goal is impossible without a harness change. The configured sentence rides every search and fetch verbatim: a standing bias, not a per-task instruction.

TinyFish's agent and browser surfaces are not exposed: metered, wallet-billed, and not a search or a fetch. Use the tinyfish CLI directly when a page genuinely needs a real browser.

The toolchain is Vite+: vp pack builds with tsdown, vp test runs Vitest, vp lint / vp fmt are Oxlint and Oxfmt, type-aware. Lint and format live in vite.config.ts — Vite+ ignores standalone configs.

pnpm install
pnpm test               # hermetic — no network, no credential
pnpm run check          # format + lint + types
pnpm run release:gate   # build, then the full gate incl. the package checks
pnpm run test:live      # the real APIs, still $0, needs credentials

Requires DSH ^0.2.0-rc.1 (0.2.0-rc.1 and later, below 0.3.0) and Node 24+. Full process and invariants: AGENTS.md. Contributing: CONTRIBUTING.md.