Tier 3: worked local-vs-hosted comparison across examples and the site - #121
Open
giordano-lucas wants to merge 2 commits into
Open
Tier 3: worked local-vs-hosted comparison across examples and the site#121giordano-lucas wants to merge 2 commits into
giordano-lucas wants to merge 2 commits into
Conversation
Rounds out the funnel with the content layer. - examples/hosted: the same job three ways — local capture, hosted over HTTP, hosted over MCP — with a comparison table and two dependency-free scripts. `discover.py` searches the public marketplace and needs no credentials; `run_hosted.py` executes one function and needs an API key. - Every existing example README gains a footer pointing at the hosted route, phrased around maintenance rather than claiming a hosted equivalent exists. None of those six sites are in the marketplace today, so the footers link to a search and to building one, which stays true either way. - A /docs/cloud page covering when to use which, the pre-capture lookup, how to turn it off, CLI search, and the MCP endpoint. - A "Run it, or don't." section on the home page, plus a card and a short section in the docs index and a callout in agent mode. The comparison is deliberately even. Overselling the hosted side to an audience that just installed an MIT CLI would read as a bait-and-switch, so both columns list what the other does better — offline, code review, and network-local execution stay firmly in the local column. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Follows the search endpoint gaining `base_url`. `discover.py` now scopes with it instead of over-fetching and filtering by domain locally, and the docs drop the "the endpoint ranks rather than filters" caveat, which no longer holds. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
giordano-lucas
force-pushed
the
promote/cloud-tier3-examples-docs
branch
from
August 20, 2026 11:48
8ad3dcb to
892f642
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stack: 3 of 3. Based on #120, which is based on #119. Review in order; this PR's diff is against #120.
What
The content layer — the part that has to earn the click rather than just place a link.
examples/hosted/— the same job done three ways (local capture, hosted over HTTP, hosted over MCP) with a comparison table and two dependency-free, standard-library scripts:discover.pysearches the public marketplace and needs no credentials at all — verified live againstnfl.com(5 hits),instagram post comments(semantic), andjobs.ashbyhq.com(correctly 0).run_hosted.pyexecutes one hosted function withNOTTE_API_KEY. All error paths smoke-tested; the unauthorized path correctly returnsHTTP 401 {"error":"Unauthorized"}.Example README footers on all six existing examples.
/docs/cloud— when to use which, the pre-capture lookup, how to disable it, CLI search, MCP setup.Home page — a "Run it, or don't." section, plus a docs-index card and an agent-mode callout.
Two honesty calls worth flagging
The footers don't claim a hosted equivalent exists. I checked every example's domain against the live marketplace:
jobs.apple.com,uber.com,autoscout24.com,mintlify.com,ikea.com, andjobs.ashbyhq.comall return zero functions today. My original plan was "Hosted equivalent: " footers, which would have sent readers to empty result pages — the worst possible first impression. They're now phrased around maintenance, with a search command and a build link, both of which stay true whether or not coverage lands later.The comparison is deliberately even. Both columns list what the other does better; offline, code review, and network-local execution stay firmly in the local column. Overselling the hosted side to an audience that just installed an MIT CLI reads as a bait-and-switch, and that costs more than it wins.
One inferred detail — please confirm
POST /api/functions/{id}/runis verified to exist and to require Bearer auth (401 without), but I could not verify its request body shape — it's authenticated, and the preview MCP server's marketplace is empty sospecreturned nothing.run_hosted.pysends{"variables": {...}}, inferred from the MCPruntool contract ({function_id, variables}) with the id in the path. Worth a 30-second check by someone with a key. Everything else in these PRs is verified against the live API.Verification
types:check,lint, andbuildall pass;/docs/cloudrenders and is in the sitemap.raecard heading was hardcoded to#1f1f1fand disappeared against the dark card — nowvar(--color-ink).ruff checkclean onexamples/hosted/.🤖 Generated with Claude Code