1Introduction
1.1Purpose
Kindling is an open protocol for finding people. It describes how anyone can publish a freeform profile, how curators can collect those profiles into Pools, how a consent handshake brings a profile into a Pool with the owner's permission, and how any UI a developer wants to build can sit on top.
1.2Layers
Kindling is two stacked open standards:
- Layer 1, Profile standard (§2). A freeform self-hosted page becomes a structured profile.
- Layer 2, Pool standard (§3). A Pool is a manifest of structured profiles with a declared curator, intent, visibility, and consent model.
UIs are implementation-defined. The two layers underneath are the protocol.
1.3Non-goals
Kindling does not define a hosted consumer product, a single canonical UI, a federation transport (v0.1 uses email under the hood for messaging), or a chargeable surface at the connection layer.
1.4Terminology
See GLOSSARY.md for defined terms. Defined terms are capitalized when used in a protocol sense (Pool, Profile, Curator, Asker, Handshake).
2Profile Layer
2.1Profile definition
A Profile is whatever the owner publishes at a URL. There is no required format. The protocol parses what is present.
2.2Baseline schema: h-card
A Profile owner SHOULD include IndieWeb h-card microformat markup on the source page. Parsers MUST read h-card fields where present and MUST NOT infer values that contradict explicit h-card markup.
2.3AI-assisted extraction
Where h-card markup is absent, a parser MAY infer fields from prose, layout, and embedded media. Implementations MUST record which fields were h-card-derived and which were inferred. The parsed profile's extraction_source field (see schemas/parsed_profile.schema.json) carries this provenance.
2.4Extracted fields
A parsed Profile MUST include, where discoverable:
display_namepronouns(if stated on the source)location(city / region / "remote" / "anywhere")photo_hints(URLs to images on the source page; never cached content)intent_tags(what the person is open to)about(free-text "about me" in compressed form)contact_methods(declared email, social handles, scheduling links)verification_level(§4.5)messaging_preferences(§7.2)
2.5Photo handling
Photos MUST be referenced by URL only. Kindling and Pools MUST NOT store photo bytes. Displaying implementations MAY cache locally for performance.
2.6Re-parse cadence
Re-parsing is trigger-based. A Pool MUST re-parse a Profile when the owner pushes an update. A Pool MUST collapse multiple update pushes within any 24-hour window into a single re-parse. A Profile owner MAY force a hard re-parse on demand through the messaging channel (§6).
2.7Noindex directive
A Profile MAY include a kindling-noindex directive (as an h-card class, meta tag, or robots-style signal). Compliant Pools and crawlers MUST NOT include such a Profile in any Pool, registry, or discovery surface.
3Pool Layer
3.1Pool definition
A Pool is a manifest plus a list of Profile entries. A Pool MUST be retrievable as a JSON document, either from a public Git repository or from a Pool API endpoint that returns the same shape. The document MUST validate against schemas/pool_manifest.schema.json.
3.2Required manifest fields
namecurator(one or more verified Kindling identities; verification level visible)intent_tagsvisibility— one ofpublic,unlisted,invite-onlyconsent_model— defaults touniversal-opt-in; other values:vouching-required,curator-only-addscurator_contactcharter(free-text description)
3.3Optional manifest fields
geographic_scope, governance_rules, created_at, updated_at, Pool-level messaging preferences, and block-list subscriptions.
3.4Pool entries
Each entry MUST contain:
profile_url(canonical source URL)parsed_profile(cached JSON sidecar)parsed_at(last parse timestamp)consent_proof(reference to the handshake response authorizing inclusion)verification_level
3.5Coupling
A Profile MAY appear in many Pools. A Pool MAY list many Profiles. Pools and Profiles are loosely coupled by URL.
4Identity
4.1Principle
A Profile owner MUST be able to prove they control the URL they published. Verification level MUST be visible to Askers.
4.2Email verification
The baseline. The first time a Profile is brought into any Pool, Kindling MUST send a verification link to the declared contact email. The verified email becomes the owner's Kindling identity.
4.3OAuth
A Profile owner MAY authenticate via a supported identity provider (Google, Apple, or others declared by the implementation). The OAuth-bound identifier becomes the owner's Kindling identity.
4.4Curator vouching
A Curator MAY vouch for a Profile owner inside their own Pool. The identity is local to that Pool and MUST NOT automatically apply to other Pools.
4.5Verification levels
Implementations MUST surface one of: email-verified, oauth-verified, curator-vouched, unverified. A v1-conforming UI MUST render this alongside every Profile.
4.6Future identity (non-normative)
Cryptographic identity and cross-Pool portability are planned for v0.2 (see framework Future Revisions).
5Consent and the Handshake
5.1Principle
A Profile MUST NOT be added to a Pool without the owner's explicit consent. Silent inclusion is forbidden. There is no exception.
5.2Handshake flow
- A Curator submits a Profile URL to a Pool.
- The Pool's parser performs a lightweight pre-fetch to find a contact method.
- The Pool sends a handshake message conforming to
schemas/handshake_message.schema.json, containing: Pool name, charter, curator identity, intent tags, visibility, and a one-click accept link + a one-click decline link. - On accept, the Pool parses the page in full, caches the structured Profile, and lists it.
- On decline, the URL MUST be recorded as declined for that Pool and MUST NOT be re-submitted by the same Curator without owner permission.
- No response within the handshake window (default 14 days, configurable per Pool) causes the submission to expire.
5.3Withdrawal
A Profile owner MAY withdraw consent and remove themselves from any Pool at any time through the messaging channel (§6). Implementations MUST process withdrawal within 60 seconds of receipt.
5.4Stricter consent models
Pools declaring consent_model: vouching-required or consent_model: curator-only-adds MAY add pre-handshake steps but MUST NOT remove the owner's ability to decline or withdraw.
5.5Auto-accept
A Profile owner MAY declare auto-accept rules in their messaging preferences. An auto-accept rule matches on:
intent_tags(subset match)- minimum
curator_verification_level visibilityconstraint
Auto-accept defaults to off. A Profile MUST NOT have more than five active auto-accept rules. Every auto-accept event MUST produce a notification to the owner; silent acceptance is forbidden. Any auto-accept MAY be revoked retroactively, removing the Profile from any Pool it was auto-accepted into.
6Native Messaging
6.1Transport
In v0.1, Kindling messaging is delivered as structured email over standard email infrastructure. Identities map to verified email addresses (or OAuth-bound addresses). UIs MAY render the conversation as a native thread; end users MAY never see the underlying email.
6.2Message envelope
Messages MUST validate against schemas/kindling_message.schema.json. The envelope contains: sender identity, recipient identity, message type, body, and pool_ref (the Pool the message was triggered through, where applicable).
6.3Message types
handshake-request, handshake-response, intro, reply.
6.4Forward compatibility
Future versions MAY define richer transports (federated rooms, real-time delivery, end-to-end encryption). Such additions MUST be negotiated via the envelope's transport field and MUST preserve email as a fallback through v1.x.
7Spam Filtering
Spam protection is a stated requirement. A v1-conforming implementation MUST support all three layers.
7.1Layer 1: identity-based gating
Messages from senders with stronger verification MUST pass. Messages from unverified senders MUST be quarantined or rejected per the recipient's per-profile preference. Curator-vouched senders MUST pass within the Pool that vouched for them.
7.2Layer 2: per-profile preferences
A Profile MAY declare messaging rules. Supported rules include:
open-to-allpool-mates-onlyvouched-onlyno-cold-messages(require confirmed mutual interest)minimum-sender-verification
Implementations MUST honor the declared rules.
7.3Layer 3: shared block lists
The Kindling project MUST publish a public block list of known abusers, identified by Kindling identity. Third parties MAY publish their own block lists. Implementations MUST be able to subscribe to one or more lists and filter accordingly. Block lists MUST validate against schemas/block_list.schema.json.
8Discovery
8.1Surfaces
A spec-compliant Pool MUST be findable through at least one of these surfaces, and SHOULD be findable through the well-known convention (§8.3):
8.2Social sharing
Pool URLs travel through Reddit, Twitter, newsletters, group chats, and word of mouth. Kindling has no opinion about how a Pool URL is shared, only that the URL resolves to a valid Pool manifest.
8.3Well-known discovery file
Any domain hosting a Pool SHOULD publish a .well-known/kindling-pool document validating against schemas/well_known_pool.schema.json. Crawlers and registries MUST be able to consume this file without prior authorization.
8.4Kindling public registry
The project runs a public registry of opt-in Pools at registry.kindling.dev. Listing is by curator self-submission. The registry is one consumer of the well-known convention; it MUST NOT be the only way a Pool is discoverable.
8.5Third-party registries
Anyone MAY run a registry of Pools they curate or trust. The protocol treats third-party registries as first-class; a Pool's inclusion in or exclusion from any registry is a curator decision, not a protocol requirement.
9Pool Continuity
9.1Inactivity
A Curator is considered inactive if they have taken no curation action (handshake review, manifest edit, removal response) for 90 days. When this threshold is hit, the Pool MUST enter dormant status. Pool members MUST see a notice. The well-known file MUST reflect dormancy.
9.2Active member
Any inhabitant who has accepted a handshake into the Pool, posted to the Pool, or sent a Kindling message through the Pool in the last 60 days.
9.3Curator transition
A dormant Pool opens a curator-transition process. Any active member MAY nominate themselves or another active member. The participation window is 14 days. Transition succeeds if at least two-thirds of responding active members support the nominee (equivalently, fewer than one-third block). Co-curators listed in the manifest are first in line.
9.4Archive
If the participation window closes without a successful transition, the Pool MUST archive. Archived Pools remain readable, profiles remain listed, but no new submissions or messages are processed. Archived Pools MAY be revived if a returning member re-opens the transition process.
10Well-known Discovery File
10.1Location
/.well-known/kindling-pool on the domain hosting one or more Pools.
10.2Shape
A JSON document validating against schemas/well_known_pool.schema.json. It MUST list, for each Pool on the domain: name, pool_url, visibility, intent_tags, status (active, dormant, archived), and curator_contact.
10.3Crawler conventions
Crawlers and registries MUST respect Cache-Control headers on the well-known file, MUST back off on 429/5xx responses, and MUST identify themselves via a User-Agent that identifies both the software and a contact URL.
11Conformance
11.1Compliant Pool host
Implements §3 (manifest), §5 (handshake), §9 (continuity), and publishes a §10 well-known file.
11.2Compliant Pool UI
Renders §4.5 verification levels alongside every Profile, honors §7 spam-filtering layers, supports §5.3 withdrawal, and never performs silent inclusion.
11.3Compliant parser
Reads §2.2 h-card fields preferentially, records extraction provenance, respects §2.7 noindex, and stores no photo bytes.
11.4Compliant messaging client
Validates envelopes against §6.2 schema, surfaces verification level, and applies §7.1 gating.
12Versioning
12.1Version field
Every manifest, parsed Profile, handshake message, and native message MUST carry a kindling_version field.
12.2Semver
Spec versions follow SemVer. A parser or Pool encountering a newer minor version SHOULD continue to operate on the fields it understands. A parser encountering a newer major version MUST refuse to consume the document and MUST surface a clear error.
12.3Deprecation
Deprecations between minor versions MUST be marked in the relevant schema and listed in CHANGELOG.md at least one minor version before removal.
Appendix A: Normative references
schemas/parsed_profile.schema.jsonschemas/pool_manifest.schema.jsonschemas/handshake_message.schema.jsonschemas/kindling_message.schema.jsonschemas/well_known_pool.schema.jsonschemas/block_list.schema.json
Appendix B: Informative references
- IndieWeb h-card specification — https://microformats.org/wiki/h-card
- RFC 2119 — Key words for use in RFCs to Indicate Requirement Levels
- Framework essay (longer narrative form) — docs/FRAMEWORK.md
Spec text © 2026 TranquilTech and Kindling spec contributors, licensed CC BY 4.0. Reference tooling is Apache 2.0. Questions, ambiguities, and proposed changes: josh@intellibotique.com. Conduct concerns: josh@intellibotique.com.