Webpath — Generate Your Own Server

Webpath is small enough that an AI agent can build a conformant server from the spec alone. Paste the prompt below into a capable coding agent (Claude Code, etc.), point it at the Spec and Conformance Guide, and it will scaffold a server on whatever stack you name — then verify itself against the conformance cases.

This is the inverse of the Build an App guide: that builds a client; this builds a host.

The prompt (copy this)

You are building a server that implements the Webpath specification.

SPEC:        https://muse.as/a/webpath/spec
API SURFACE: https://muse.as/a/webpath/api-reference
CONFORMANCE: https://muse.as/a/webpath/conformance   ← you MUST pass every L1 case

Read all three before writing code. Webpath is a wire protocol — the path is the
storage key, HTTP verbs are the API, a space is a hostname, and visibility is set on
write. There is no /api prefix on the data plane and no GUIDs.

STACK: <your choice — e.g. "Node + Hono + SQLite + local disk", "Go net/http + S3",
        "Python FastAPI + Postgres + MinIO", "Bun + Elysia + Cloudflare R2/D1">.
Keep storage (bytes) and metadata behind interfaces so the backend can be swapped.

BUILD, in this order, testing each against the conformance cases as you go:

1. Data plane (L1: WP-D*, WP-R*, WP-C*)
   - GET/PUT/DELETE/HEAD on /<path>; the storage key is lowercase(host)+pathname.
   - Clean URL renders <path>.md→HTML (sanitized) or serves <path>.html;
     an explicit extension returns verbatim source. Set Content-Location.
   - ETag on every response; If-Match (412) and If-None-Match (304/create-only).
   - Content-Type inferred from the extension, never the client's declared header.

2. Visibility & privacy (L1: WP-V*) — THE PRIVACY FLOOR IS NON-NEGOTIABLE.
   - Default private. A private file is byte-identical to a 404 for unauthorized
     readers. The clean-URL fallback must never reveal a private file.

3. Identity & keys (L1: WP-A*, WP-K*, WP-T*)
   - Email-OTP accounts (otp always 204; verify creates the account; rate-limited).
   - Session = __Host- cookie (Secure, Path=/, no Domain).
   - pth_ keys = signed JWT, scoped {namespaces, ops, paths, formats}, verifiable via
     /.well-known/jwks.json. Out-of-scope → 403. ?token= responses are no-store and
     never echo the token.

4. Spaces & control plane (L1: WP-S*)
   - POST /join mints <name>.<host> + a key. POST /api/v1/spaces (owner), /api/v1/tokens.

5. Reserved paths (L2: WP-X*) — synthesize on read, never store:
   - /llms.txt (≤1500 bytes, read-only 405 on write), /_config.json (PATCH editable
     fields only), /.well-known/jwks.json.

6. Errors (L1: WP-E*) — every non-2xx is application/problem+json with type (stable
   URI), title, status, and a full-sentence, user-actionable detail.

7. Append/prepend, QR, search (L2: WP-P*, WP-Q*, WP-F*) once L1 is green.

RULES:
- Implement to the conformance cases, not to my prose. When unsure, the spec wins.
- After each section, run the matching WP-* cases and report pass/fail.
- Do not invent endpoints with /api/v1/ prefixes on the data plane.
- Deliverable: a running server + a short README with the run command and which
  conformance level (L1/L2) it currently passes.

How to drive it

  1. Pick your stack and fill in the STACK: line. Anything that speaks HTTP works.
  2. Run section by section. The order above is dependency-sorted: data plane → privacy → identity → spaces → reserved paths → errors → extras. Don't let it skip ahead — privacy (step 2) gates everything.
  3. Hold it to the cases. After each section, have it run the matching WP-* cases from the Conformance Guide and show the results. "It compiles" is not "it conforms."
  4. Stop at L1, then decide. A host that passes L1 Core is already usable by any Webpath agent. L2 (append, reserved-path projections, QR, search) is additive.

What "done" looks like

A server where this works against your host, unmodified from the API Reference:

export HOST=https://your-host.example
curl -X POST $HOST/join -d '{"name":"smoke"}'                 # 201 + a pth_ key
curl -X PUT --data-binary '# hi' \
  -H "Authorization: Bearer pth_…" \
  "https://smoke.your-host.example/page.md?visibility=public" # 201
curl "https://smoke.your-host.example/page"                   # 200, rendered HTML

If an agent that has only read your /llms.txt can publish a clean URL unaided, you've built Webpath.

→ Spec · Conformance · Build an App · Webpath home