Comments

Anonymous, anchored comments on flypod sites, including visitor identity, access modes, threaded replies, and current hosted limitations.

flypod comments turn a deployed page into a lightweight review surface. When comments are enabled, HTML responses receive a same-origin widget. A visitor can highlight text, leave a note anchored to that passage, and continue the thread without creating an account.

The shorter setup instructions live in Enable comments.

What is available today

A floating comments panel injected into flypod-hosted HTML.
Stable pseudonymous visitor identity scoped to one deployed site.
Text-selection and page-level anchors.
Threaded replies, resolve/reopen state, and visitor rename.
Anonymous, passcode, and owner-approved access modes.
A JSON-LD companion feed for machine-readable review data.

Hosted status

The comments library also contains an MCP transport, agent-token model, webhook configuration, signing, and delivery primitives. Those pieces are not yet a complete hosted flypod.dev feature:

Hosted agent-token lookup is not wired, so owners cannot currently mint a usable fau_ token for the MCP surface.
Hosted webhook dispatch is a no-op; configuring a URL does not deliver events yet.

Do not treat the MCP or webhook surface as available on hosted flypod.dev until those integration points are connected.

Visitor identity

The widget mints a flypod_cmt cookie on first interaction. It contains a random identity, site ID, display pseudonym, and issued-at time protected by an HMAC signature. The cookie is HttpOnly, Secure, SameSite=Lax, and scoped to the deployed site host.

That host scope matters: a visitor to site-a.flypod.dev does not carry the same comment identity into site-b.flypod.dev.

Visitors can rename themselves. The stable random identity remains unchanged, so earlier comments display the new name without changing authorship.

Anchoring

Text threads use the W3C Web Annotation Data Model:

{
  "source": "https://abc.flypod.dev/about",
  "selector": [
    {
      "type": "TextQuoteSelector",
      "exact": "the canonical playbook",
      "prefix": "This page is ",
      "suffix": " for driving flypod"
    }
  ]
}

The surrounding prefix and suffix help relocate the passage after small text changes. Comments created without a selection use a page-level anchor.

Modes

The server enforces one of three modes:

Mode	Read	Post	Visibility
Anonymous	Public	Visitors with a pseudonym cookie	Immediate
Passcode	Valid grant or owner	Valid grant or owner	Immediate
Approved	Public	Anyone with a pseudonym cookie	Non-owner posts wait for approval

Configure an owned site from the CLI:

flypod comments enable --site <id> --mode approved
flypod comments mode passcode --site <id> --passcode <secret>
flypod comments off --site <id>

Disabling comments hides the widget but preserves stored threads.

Replies and moderation

Replies belong to the original thread and render in chronological order. In approved mode, non-owner root comments and replies remain visible to their author and the owner while hidden from everyone else. Owners can approve, reject, resolve, and reopen threads.

Companion JSON

The comments service can render a JSON-LD OrderedCollection of W3C Annotations. The site-wide route is /comments.json; page-specific companions use /<page>.comments.json. HTML advertises the relevant companion with a Link header when comments are enabled.

Security boundaries

Visitor identity is isolated by site host.
Comment bodies render as text, not trusted HTML.
Anchor selector types and body limits are validated server-side.
Passcode grants and identity cookies are HMAC-signed with distinct secrets.
Frozen sites block normal writes while leaving abuse reporting available.

Not yet shipped on hosted flypod.dev

Usable owner-minted agent tokens for MCP.
Outbound webhook delivery.
Realtime push; clients currently poll.
Embedding the same-origin widget on non-flypod hosts.

On this page