Check any site's /.well-known/poppy.json against Poppy 1.0 in one command: PASS or FAIL for every rule, a 0–100 score, and the exact fix for each failure.
npx github:NHTanvir/pollen check https://example.comNo install and no account: npx runs Pollen straight from this repository. Swap in your own domain.
Pollen is the linter and doctor for Poppy adoption. It reads your discovery file the way a Personal Agent does, follows every redirect, checks the OAuth metadata your sign-in depends on, and tells you what to change. It is deterministic and makes no LLM calls: the same site always gets the same report.
A fictional shop.example with three common mistakes. The network is simulated for the example, but every line is Pollen's real output, and the test suite regenerates it to keep this README honest.
$ npx github:NHTanvir/pollen check shop.example
pollen 0.1.0 · Poppy 1.0 discovery check
target https://shop.example/.well-known/poppy.json
Transport
PASS transport.https Served over HTTPS, redirects included §3
PASS transport.status Responds with HTTP 200 §3
PASS transport.final-url Final URL is exactly /.well-known/poppy.json, with no query §3
Document
PASS document.json Is a valid JSON object §3.1
PASS version.present protocol_version is present and a string §3.1
PASS version.format protocol_version is major.minor §3.1
PASS version.compatible protocol_version is compatible with 1.0 §3.4
PASS organization.present organization is present and an object §3.1
PASS organization.name organization.name is a non-empty string §3.1
PASS organization.domain organization.domain is a bare host name §3.1
PASS organization.domain-host organization.domain matches the host that served it §3
SKIP organization.logo, versions.supported (not applicable)
Channels
PASS channels.present Lists at least one channel: agent, apis, or web §3.1
PASS agent.protocols agent.protocols entries have type, HTTPS endpoint, and description §8.1
PASS agent.known-type agent.protocols has a "poppy" or "ucp" entry §8.1
PASS apis.entries apis entries have type, HTTPS url, and description §7
WARN apis.types apis types are "openapi" or "mcp" §7
✗ apis[0].type: "OpenAPI" isn't an API type this version defines, so Personal Agents skip it
fix: Use lowercase "openapi".
https://personalagentprotocol.org/docs/1.0/spec#apis
PASS web.fields web fields have the right types §6
FAIL web.disabled web.disabled has no browser endpoint and another channel §6
✗ web.browser_session_endpoint: must not be set when web.disabled is true
fix: Remove browser_session_endpoint, or set web.disabled to false.
https://personalagentprotocol.org/docs/1.0/spec#web-browsing
SKIP agent.ucp, agent.access, tasks.endpoint (not applicable)
Sign-in
PASS auth.fields auth.issuer is HTTPS and auth.disabled is a boolean §3.1
PASS auth.scopes auth.scopes maps scope names to descriptions §4.7
SKIP auth.scope-hints, auth.disabled-conflicts (not applicable)
Extensions
SKIP extensions.shape, extensions.names, extensions.versions, operations.browser-join, mediated.fields, mediated.transitional (not applicable)
OAuth metadata
PASS oauth.resource-metadata Protected resource metadata is valid JSON, or a clean 404 §3.2
PASS oauth.resource Protected resource metadata names this domain §3.2
PASS oauth.issuer auth.issuer agrees with the authorization servers listed §3.2
PASS oauth.server-metadata Issuer publishes metadata with a matching issuer §3.2
FAIL oauth.protected-resources Issuer lists this domain in protected_resources §3.2
✗ https://auth.shop.example/.well-known/oauth-authorization-server → protected_resources: doesn't list https://shop.example, so the issuer doesn't confirm it serves this domain and Personal Agents won't trust the link
fix: Add "https://shop.example" to protected_resources, with no path or trailing slash.
https://personalagentprotocol.org/docs/1.0/spec#oauth-server
PASS oauth.endpoints Issuer metadata has the endpoints and grants Poppy needs §3.2
PASS oauth.scopes-supported Scopes in poppy.json are listed in scopes_supported §3.2
PASS oauth.sign-in-grant Issuer offers a way to sign in, or auth.disabled says it doesn't §3.2
SKIP oauth.mediated-grant (not applicable)
Score 45/100 25 passed · 2 errors · 1 warning · 14 skipped
FAIL Fix the 2 errors above before Poppy 1.0 Personal Agents can use this document.
Poppy, the Personal Agent Protocol, is an open standard for how personal AI agents work with businesses on a user's behalf. A business publishes one JSON file, /.well-known/poppy.json, that names it, lists the ways an agent can reach it (APIs such as OpenAPI and MCP, its website, its own company agent), and points to the OAuth sign-in where users grant scoped access.
Sierra and Meta announced it on October 6, 2026, and version 1.0 shipped in November 2026. Meta, OpenAI, Shopify, Stripe and Walmart are among its design partners. According to Sierra's 1.0 announcement, every Shopify store now publishes a Poppy file automatically, and Meta's Muse agent looks for Poppy first on every site it visits.
Read the specification, the introduction, or the source repository. The protocol is licensed Apache-2.0; Pollen is a separate, independent MIT-licensed tool.
- Built on the published 1.0 spec, not a draft. All 42 rules cite the section they enforce, and docs/SPEC-NOTES.md records where each requirement comes from.
- Checks the whole discovery chain. HTTPS on every redirect, the exact well-known path,
organization.domainagainst the host that served the file, and the issuer link through RFC 9728 protected resource metadata and RFC 8414 server metadata. A file can be valid JSON and still be unusable; Pollen tells you why. - Knows which version it's reading. A 0.4 document isn't failed for missing 1.0-only fields. Pollen reports the version as the problem, which is what matters to a 1.0 agent.
- Fixes, not just failures. Every problem names the JSON path, says what's wrong, and gives the change to make.
- Made for CI.
--jsonoutput, meaningful exit codes, and a GitHub Action that fails the build when your deployedpoppy.jsonbreaks. - Small and dependable. TypeScript on Node 18+, zero runtime dependencies, 300+ tests, and an offline
pollen demo.
npx github:NHTanvir/pollen check example.com # a domain
npx github:NHTanvir/pollen check https://example.com # a URL, with or without the path
npx github:NHTanvir/pollen check ./public/.well-known/poppy.json # a local file, before you deployA local file gets every document rule. The transport and OAuth rules need a live URL, so check the deployed domain too.
| Option | What it does |
|---|---|
--json |
Print the report as JSON, for CI and scripts |
--failures-only |
Show only the rules that failed |
--skip-oauth |
Don't fetch the OAuth metadata (live URLs only) |
--timeout <ms> |
Per-request timeout, default 10000 |
--no-color |
Plain output. NO_COLOR is respected too |
Exit codes: 0 passed, 1 failed (at least one error), 2 usage error.
npx github:NHTanvir/pollen check example.com --json | jq '{score, ok, errors: .summary.errors}'Each result has a stable id, its status (pass, fail or skip), severity, spec section and spec_url, and a list of problems, each with a path, message and fix.
$ npx github:NHTanvir/pollen init
pollen init: a starter poppy.json for Personal Agent Protocol 1.0.
Company name: Orbit Air
Domain that will serve poppy.json, such as example.com: orbit.example
Sign-in. Personal Agents sign Users in through your OAuth issuer (Direct Sign-In).
OAuth issuer URL, where Users sign in (blank if you don't offer sign-in yet): https://auth.orbit.example
Interfaces. Leave a question blank to skip that interface.
May Personal Agents browse your website? [Y/n]: y
Browser session endpoint, if you support browser join:
Company agent conversation endpoint (Poppy protocol): https://api.orbit.example/poppy/conversations
What can your agent help with? [Anything about Orbit Air]: Trips, seats, and bags
OpenAPI description URL: https://api.orbit.example/openapi.json
What is the API for? [Orbit Air API]:
MCP server URL:
Wrote poppy.json (pollen score 100/100).
It writes a document that passes every rule, then prints next steps: where to serve it and, if you offer sign-in, the OAuth metadata to publish. Use --out public/.well-known/poppy.json to write it straight into your site, and --force to overwrite.
npx github:NHTanvir/pollen demoRuns Pollen against the bundled example documents, with no network: 5 that pass, and 15 that each break exactly one rule, then prints one full report.
Listed on the GitHub Marketplace as Pollen poppy.json Validator. Fail the build when your deployed poppy.json breaks:
name: poppy.json
on:
push:
schedule:
- cron: "0 6 * * *" # also catch changes made outside this repository
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: NHTanvir/pollen@v0.1.0
with:
target: example.com| Input | Default | What it does |
|---|---|---|
target |
(required) | Domain, URL, or path to a poppy.json in your repository (add actions/checkout first) |
skip-oauth |
false |
Don't fetch the OAuth metadata |
timeout |
10000 |
Per-request timeout in milliseconds |
The report goes to the job log and the job summary. The exit-code output is 0, 1 or 2, as above.
Every rule either passes, fails, or is skipped because it doesn't apply, such as the OAuth rules for a company with no sign-in. The score starts at 100. Each failed error costs 25 points and each failed warning costs 5, down to 0. A missing or unreadable document scores 0.
Any failed error means FAIL and exit code 1, whatever the score. Errors are spec requirements (MUST): a Personal Agent may refuse the document. Warnings are things agents ignore or skip, so a feature silently doesn't work.
All 42 rules, with the spec section each one enforces
| Rule | Checks | Severity | Spec |
|---|---|---|---|
| Transport | |||
transport.https |
Served over HTTPS, redirects included | error | §3 |
transport.status |
Responds with HTTP 200 | error | §3 |
transport.final-url |
Final URL is exactly /.well-known/poppy.json, with no query | error | §3 |
| Document | |||
document.json |
Is a valid JSON object | error | §3.1 |
version.present |
protocol_version is present and a string | error | §3.1 |
version.format |
protocol_version is major.minor | error | §3.1 |
version.compatible |
protocol_version is compatible with 1.0 | error | §3.4 |
organization.present |
organization is present and an object | error | §3.1 |
organization.name |
organization.name is a non-empty string | error | §3.1 |
organization.domain |
organization.domain is a bare host name | error | §3.1 |
organization.domain-host |
organization.domain matches the host that served it | error | §3 |
organization.logo |
organization.logo_uri is an HTTPS URL | error | §3.1 |
versions.supported |
supported_versions maps other versions to HTTPS URLs on this host | error | §3.4 |
| Channels | |||
channels.present |
Lists at least one channel: agent, apis, or web | error | §3.1 |
agent.protocols |
agent.protocols entries have type, HTTPS endpoint, and description | error | §8.1 |
agent.known-type |
agent.protocols has a "poppy" or "ucp" entry | warning | §8.1 |
agent.ucp |
ucp entries point at the UCP profile and list the "ucp" extension | error | UCP 5 |
agent.access |
access hints are "session" or "signed_in" | warning | §3.2 |
apis.entries |
apis entries have type, HTTPS url, and description | error | §7 |
apis.types |
apis types are "openapi" or "mcp" | warning | §7 |
web.fields |
web fields have the right types | error | §6 |
web.disabled |
web.disabled has no browser endpoint and another channel | error | §6 |
tasks.endpoint |
tasks.endpoint is an HTTPS URL | error | §9 |
| Sign-in | |||
auth.fields |
auth.issuer is HTTPS and auth.disabled is a boolean | error | §3.1 |
auth.scopes |
auth.scopes maps scope names to descriptions | error | §4.7 |
auth.scope-hints |
auth.scope_hints have changes and personal_data | error | §4.7 |
auth.disabled-conflicts |
auth.disabled doesn't advertise sign-in anywhere else | error | §3.2 |
| Extensions | |||
extensions.shape |
extensions are lists of entries with a version | error | §3.3 |
extensions.names |
extension names are defined or start with a domain | warning | §3.3 |
extensions.versions |
defined extensions include their 1.0 version | warning | Extensions index |
operations.browser-join |
an operations endpoint comes with web.browser_session_endpoint | error | Operations 2 |
mediated.fields |
mediated-sign-in v1 lists fields and scopes | error | Mediated Sign-In 2 |
mediated.transitional |
Doesn't depend on Mediated Sign-In, which is being removed | warning | Roadmap |
| OAuth metadata | |||
oauth.resource-metadata |
Protected resource metadata is valid JSON, or a clean 404 | error | §3.2 |
oauth.resource |
Protected resource metadata names this domain | error | §3.2 |
oauth.issuer |
auth.issuer agrees with the authorization servers listed | error | §3.2 |
oauth.server-metadata |
Issuer publishes metadata with a matching issuer | error | §3.2 |
oauth.protected-resources |
Issuer lists this domain in protected_resources | error | §3.2 |
oauth.endpoints |
Issuer metadata has the endpoints and grants Poppy needs | error | §3.2 |
oauth.scopes-supported |
Scopes in poppy.json are listed in scopes_supported | warning | §3.2 |
oauth.sign-in-grant |
Issuer offers a way to sign in, or auth.disabled says it doesn't | warning | §3.2 |
oauth.mediated-grant |
Issuer supports the Mediated Sign-In grant it advertises | error | Mediated Sign-In 2 |
Run npx github:NHTanvir/pollen check yourdomain.com. Pollen fetches https://yourdomain.com/.well-known/poppy.json the way a Personal Agent does, checks it against all 42 rules of Poppy 1.0, and prints PASS or FAIL for each rule, a 0–100 score, and a fix for every failure.
At https://{your-domain}/.well-known/poppy.json, served over HTTPS. In Next.js, Vite or Astro, that means public/.well-known/poppy.json. Some hosts and static site generators skip folders that start with a dot, so check that the URL actually returns the file. Pollen's transport.status rule catches it if it doesn't.
{
"protocol_version": "1.0",
"organization": { "name": "Example Company", "domain": "example.com" },
"web": {}
}protocol_version and organization are required, plus at least one channel: web, apis or agent. An empty web object lets Personal Agents browse your site as signed-out visitors. Run pollen init to build a fuller one.
Shopify publishes a Poppy file for every store. When we checked several Shopify stores on November 17, 2026, their files declared protocol_version 0.4. Before 1.0, versions are only compatible with the exact same minor version (spec 3.4), so an agent that implements only 1.0 must not use a 0.4 file. Shopify generates the file, so the update has to come from Shopify.
The changelog lists every change. One that breaks 0.4 documents: each agent.protocols entry now needs a description saying what the agent can help with. Pollen checks pre-1.0 documents for the version problem only, so a 0.4 file isn't buried in 1.0 errors.
No. Every check is a deterministic rule written from the spec, with no LLM calls, so the same site always gets the same report. It only makes the HTTP requests a Personal Agent would make during discovery.
The official company kit gives implementers JSON Schemas, a validator for them, and a coding-agent skill. Pollen checks a deployed site end to end: it fetches the file over the network, follows redirects, applies the cross-field and OAuth rules, scores the result, and suggests fixes. For more Poppy tools, see awesome-poppy.
No. Pollen is an independent open-source project. It isn't affiliated with or endorsed by Sierra, Meta, or the authors of the Personal Agent Protocol.
import { check, validateDocument, formatText } from "@nhtanvir/pollen";
const report = await check("example.com"); // or validateDocument(jsonOrObject)
console.log(report.score, report.ok);
console.log(formatText(report));Until the package is on npm, install it from GitHub: npm install github:NHTanvir/pollen.
Contributions are welcome. Pollen is small on purpose, so it's a good place to make a first contribution to the Poppy ecosystem:
- Found a false positive or a missed problem? Open an issue with the URL or the document, and the spec section.
- Add a rule. Each one is a short function with a spec citation, plus test cases; the tests make sure no rule ships without them.
- Ideas on the roadmap: check the documents listed in
supported_versions, check that listed OpenAPI and MCP URLs respond, and a web playground.
See CONTRIBUTING.md to get set up. It takes about a minute.
MIT © NHTanvir. The Personal Agent Protocol specification is © its authors, licensed Apache-2.0; tests/fixtures/valid/spec-example.json is the example from its section 3.