Skip to content

docs: correct env claims, the Postman full tier, and Quick Start model examples#262

Merged
jsugg merged 1 commit into
mainfrom
docs/env-claims-and-quickstart
Jul 15, 2026
Merged

docs: correct env claims, the Postman full tier, and Quick Start model examples#262
jsugg merged 1 commit into
mainfrom
docs/env-claims-and-quickstart

Conversation

@jsugg

@jsugg jsugg commented Jul 15, 2026

Copy link
Copy Markdown
Owner

Three documented facts that were not facts. Each verified against source or the
live API, not assumed.

RATE_LIMIT_REDIS_TOPOLOGY

The doc asserted the Render deployment "keeps RATE_LIMIT_REDIS_TOPOLOGY=external".
The variable is not set on the service at all (confirmed against the live
API). The behaviour is right — external is the code default
(config/rateLimitStore.js:51,61) — but stating it as configuration sends
anyone auditing the dashboard hunting for a variable that was never there.

Fixed in the repository rather than by setting the variable on the service: the
deployment already behaves as documented, so there is nothing to change in
production, only something to stop mis-stating.

SCRAPER_REQUEST_TIMEOUT_MS

The documented 10000 default is correct (config/index.js:110). The service
runs 90000, and the doc never mentioned it. The deviation is deliberate —
hosted vision models routinely exceed 10s per image, and the free-tier instance
is slower still — so it is recorded with its reason, rather than looking like
drift to whoever finds it next.

The Postman full tier

Described as "Full deterministic harness for main and production". Wrong
on both counts:

  • npm run postman:full appears in exactly one workflow,
    local-provider-integration.yml, whose triggers are workflow_dispatch, a
    weekly schedule, and paths-filtered push/PR to main. There is no
    production trigger.
  • CI does run on production pushes, but hardcodes NEWMAN_MODE: smoke with
    no branch conditional. production gets smoke, never full.

The sibling tiers are written as trigger policy (smoke = "required on pull
requests", live = "Manual or scheduled"), so this bullet read as trigger
policy too — and promised production coverage that does not exist. It now
separates capability from execution policy.

Quick Start model=replicate

Not a style nit. Providers register only when their env keys are set, and an
unregistered model throws Unknown model400 UNKNOWN_MODEL /
unsupported_value (descriptionController.js:215-221). An install configured
for any provider other than Replicate — an OpenAI-only setup, say — got a 400
following Quick Start verbatim, with nothing in the surrounding text to explain
why.

The examples now use <configured-model> and say the value must name a
provider configured in .env.

Verification

docs:validate 8 files / 0 violations · docs:lint 0 errors · no
model=replicate remains in the README.

…l examples

Three documented facts that were not facts.

RATE_LIMIT_REDIS_TOPOLOGY: the doc asserted the Render deployment "keeps
RATE_LIMIT_REDIS_TOPOLOGY=external". The variable is not set on the service at
all. The behaviour it describes is right — external is the code default — but
stating it as configuration sends anyone auditing the dashboard looking for a
variable that was never there.

SCRAPER_REQUEST_TIMEOUT_MS: the documented 10000 default matches the code; the
service runs 90000 and the doc never said so. Hosted vision models routinely
take longer than 10s per image, so the deviation is deliberate and now recorded
with its reason, rather than looking like drift to the next reader.

postman:full was described as the harness "for main and production". It is
neither: the tier appears in exactly one workflow (Local Provider Integration),
whose triggers are manual dispatch, a weekly schedule, and paths-filtered
push/PR to main — there is no production trigger. CI does run on production
pushes, but hardcodes NEWMAN_MODE: smoke with no branch conditional, so
production gets smoke and never full. The sibling tiers are all written as
trigger policy, so this bullet read as trigger policy too, and promised
production coverage that does not exist. It now separates capability from
execution policy.

Quick Start hardcoded model=replicate. Providers register only when their keys
are set, and an unregistered model throws Unknown model -> 400 UNKNOWN_MODEL
(descriptionController.js:215-221), so an install configured for any other
provider got a 400 following the README verbatim. The examples now name a
placeholder and say the value must be a provider configured in .env.
@jsugg
jsugg merged commit 5d98563 into main Jul 15, 2026
19 checks passed
@jsugg
jsugg deleted the docs/env-claims-and-quickstart branch July 15, 2026 08:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant