Comments

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 todayCopy Anchor Link

• A comments panel injected into flypod-hosted HTML, with highlights on every commented passage and a select-to-comment button.
• Stable pseudonymous visitor identity scoped to one deployed site.
• Text-selection and page-level anchors.
• Threaded replies, resolve/reopen state, emoji reactions, a 15-minute self-edit window, and visitor rename.
• Anonymous, passcode, and owner-approved access modes.
• A JSON-LD companion feed for machine-readable review data.

Hosted statusCopy Anchor Link

Agents can work with comments on flypod.dev today through two surfaces, both authorized by the site owner's account session:

• The flypod MCP connector: configure_comments, list_comments, get_comment_thread, post_comment, reply_to_comment, update_comment_thread, and delete_comment_thread.
• The flypod comments CLI verbs.

The comments library also contains its own MCP transport, an agent-token model, and webhook primitives. Those pieces are not wired on hosted flypod.dev:

• Agent-token (fau_) lookup is not wired, so owners cannot mint a separate comments token; use your account session.
• Webhook dispatch is a no-op; configuring a URL does not deliver events yet.

Visitor identityCopy Anchor Link

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, lasts a year, and is scoped to the deployed site host.

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

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

AnchoringCopy Anchor Link

Text threads use the W3C Web Annotation Data Model:

{
  "source": "https://a3f1c2d4e5b60789.flypod.page/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.

ModesCopy Anchor Link

The server enforces one of three modes:

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>

--site can be left out in a folder linked to the site. Comments are configured by the site's owner, so these commands need flypod login (or FLYPOD_TOKEN). Disabling comments hides the widget but preserves stored threads.

Replies and moderationCopy Anchor Link

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 JSONCopy Anchor Link

The comments service renders a JSON-LD array of W3C Annotations, one per visible thread on one page, from GET https://flypod.dev/api/sites/<site_id>/comments.json?page=<path> (page defaults to /). The feed is empty when comments are off or the site is in passcode mode, and it never includes posts awaiting approval. It is not yet advertised from the site's own pages.

Security boundariesCopy Anchor Link

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

Not yet shipped on hosted flypod.devCopy Anchor Link

• Separate owner-minted agent tokens (fau_) are not wired; use your account session.
• Outbound webhook delivery.
• Realtime push; clients currently poll.
• Embedding the same-origin widget on non-flypod hosts.