Source for personalagentprotocol.org, the site that publishes the Personal Agent Protocol draft specification and its docs. The protocol lets personal agents discover participating companies, sign users in, and get things done through APIs, web pages, and company agents.
The site is a Next.js static export. It documents the protocol but does not implement the APIs the specification describes.
Use Node.js 20.9 or newer and pnpm 10.34.0. Dependencies install from the public npm registry.
pnpm install --frozen-lockfile
pnpm devThe site opens at http://localhost:3000. Before sending a change, run:
pnpm typecheck
pnpm format:check
pnpm buildIf you changed the docs or kit/, run pnpm kit first. It regenerates the kit, and the build fails
when the committed kit is out of date. pnpm kit and the validator's tests, pnpm test:kit, need
Node.js 22.18 or newer.
The production build writes the static site to out/. Serve that directory with any static host.
pnpm-workspace.yaml sets minimumReleaseAge, so pnpm won't install a package version until it
has been published for four days.
/: the overview, with interactive walkthroughs/docs/introduction,/docs/changelog: the pages with one copy/docs/<version>/spec,/docs/<version>/extensions,/docs/<version>/guides, and in 0.1 and 0.2,/docs/<version>/extensions/operations: each version of the protocol's pages, such as/docs/0.2/specfor draft 0.2 and/docs/0.1/specfor version 0.1, which is frozen. Without a version, such as/docs/spec, they redirect to the latest./licenseand/license/contributions: the license and the contribution terms/kit/company: the Company implementation kit, not linked from the navigation
Each docs page is also served as Markdown at the same path with .md, for example
/docs/0.2/spec.md, and /llms.txt lists them for AI agents. The kit's skill is served file by file
under /kit/company/, and as /kit/implement-personal-agent-protocol.zip. Section links use a fragment, for example /docs/0.2/spec#sessions. The site
also serves /robots.txt and /sitemap.xml, and unknown paths show a 404 page.
app/: Next.js routes, metadata, and the stylesheet.components/: navigation, walkthroughs, code blocks, and review comments.content/: the docs pages as MDX, inversions/<version>/andshared/,docs.ts(the index of docs tabs and pages),versions/versions.json(the versions), the home page, and the walkthrough data. Seecontent/AGENTS.md.lib/: the MDX pipeline (mdx.ts,mdx-markdown.ts,docs-content.ts), the docs outline, the kit generator (lib/kit/), syntax highlighting, and analytics.kit/company/: the source of the Company implementation kit: the skill's instructions, patterns, and milestones, the JSON Schemas, and the validator, with its tests.skills/and.claude-plugin/: the kit as agents install it, generated bypnpm kitfromkit/and the docs. Don't edit them by hand.public/: the logo, link preview image, pronunciation clip, and the license text.
See content/AGENTS.md for how the docs are written, where each page comes
from, and how a version is published.
On Vercel, vercel.json permanently redirects personalagentprotocol.ai,
personalagentprotocol.net, and personalagentprotocol.com to https://personalagentprotocol.org,
keeping paths and query strings. It also redirects older page URLs to their current paths, sends docs URLs without a version to the
latest version (pnpm docs:sync writes those redirects), and sets
security headers on every response: HSTS, nosniff, a strict referrer policy, a ban on framing
the site, and a Content Security Policy that loads everything from the site itself.
Other static hosts need equivalent configuration. pnpm dev does not apply Vercel rules. On other
hosts, a small script on the home page sends old /?page=spec links to the latest spec.
To send feedback on the specification, see Providing feedback in the introduction. To change this repository, see CONTRIBUTING.md. Contributions are accepted under the contribution terms.
The specification and documentation are licensed under the Apache License 2.0. The license doesn't cover the names Personal Agent Protocol and Poppy, the logo, or the design of the site.