ts-standby: AGENTS.md should teach programmatic endpoint discoverability

[DaveHanns]

Problem

The ts-standby template's AGENTS.md (and the equivalent for any Standby template) teaches the mechanical setup — usesStandbyMode: true in actor.json, HTTP server binding to process.env.ACTOR_STANDBY_PORT — but does not teach endpoint discoverability.

Agents that follow the template commonly bind their primary handler on a verb-shaped path (/metadata, /api, ...) and use / for a plain-text help message. Result: the Actor works when a human types the correct URL, but is invisible to programmatic clients hitting /.

Suggested change

Add a Do-list bullet (or a small Discoverability section) to ts-standby/AGENTS.md:

- **Make your Standby endpoint programmatically discoverable.** One of:
  1. Bind your primary handler on `/` — the Standby URL you hand out IS the endpoint.
  2. Serve an OpenAPI spec at `/openapi.json` (see `webServerSchema` in `actor.json`).
  3. If `/` is reserved for something else, return machine-readable JSON at `/`:
     ```js
     res.json({ endpoints: [{ path: '/metadata', method: 'GET', params: { url: 'string' } }] });
     ```
  Do NOT return plain-text help ("Actor is ready. Use GET /metadata?url=...") at `/` — that
  makes the Actor reachable by humans only.

Related

• Sibling issue in apify/agent-skills — same teaching in the public skill.
• Sibling issue in apify/apify-docs — same teaching in the Standby reference page.
• Platform-side (apify/actor-standby-controller Update crew AI template with a link to blog post: How to built an AI Agent (once published) #340): auto-serve webServerSchema at /openapi.json on the Standby URL.

Impact

Medium. Templates are the anchoring artifact for agent-authored Standby Actors — if the template AGENTS.md teaches discoverability, the anti-pattern goes away at the source.

---

Surfaced during an evaluation of Apify surfaces for agent-driven Actor development.