Clone, validate a Pool, run a query.

Quick start

Five steps from a clone to a question.

If everything works, you can clone, install, validate a sample Pool, and run a discovery query in under ten minutes. If it takes longer, that is a bug. Open an issue.

1. 1Step 1 of 5

   Clone and install

   You need git, Node.js and npm.

   $ git clone https://github.com/IntelliBotique/kindling.git$ cd kindling$ npm install

2. 2Step 2 of 5

   Validate a Pool manifest

   kindling-validate checks a Kindling document against its schema.

   $ npx kindling-validate https://example.com/pools/queer-creatives-la

3. 3Step 3 of 5

   Parse a profile URL

   kindling-parse turns a profile page into a structured parsed_profile JSON document.

   Illustrative The panel under the command shows the shape of the result, a parsed_profile that validates against the schema. The values depend on the page, and the real tool’s output may be laid out differently.

   $ npx kindling-parse https://noor.example.com

   parsed_profile · illustrativenot the tool’s exact output

   {
     "schema_version": "0.1",
     "profile_url": "https://noor.example.com",
     "display_name": "Noor",
     "pronouns": "she/her",
     "location": {
       "city": "Los Angeles",
       "region": "California"
     },
     "intent_tags": ["friendship", "hiking-buddies"],
     "about": "Illustrator. Up for a hike most weekends.",
     "contact_methods": [
       {
         "type": "email",
         "value": "noor@mail.example"
       }
     ],
     "verification": {
       "level": "unverified"
     },
     "kindling_noindex": false,
     "parsed_at": "2026-09-28T09:00:00Z",
     "parser": "kindling-parser/0.1.1"
   }

4. 4Step 4 of 5

   Run the starter discovery agent

   kindling-discover asks one or more Pools a question in natural language. Only people who said yes to a Pool are in it to be asked.

   $ npx kindling-discover \--pool https://example.com/pools/queer-creatives-la \--query "who is up for a hike this weekend?"

5. 5Step 5 of 5

   Deploy the registry to your own infrastructure

   See registry/README.md in the repository. It is designed to run on a single VPS or a small container.

   A registry is one consumer of the well-known file, and anyone may run one (§8.5). See the registry view.

   # see registry/README.md in the repository# designed to run on a single VPS or a small container

Ten minutes is the budget. If a step takes longer, the docs have a bug.Open an issue on GitHub.

Reference tooling

Five Node.js command-line tools.

Named as the changelog for 0.1.1 names them. Every command on this page appears in the project’s own README or live page; nothing here is guessed.

$ npx kindling-validate https://example.com/pools/queer-creatives-la

$ npx kindling-parse https://noor.example.com

$ npx kindling-discover --pool https://example.com/pools/queer-creatives-la \--query "who is up for a hike this weekend?"

The repository

What ships, and what doesn’t.

It does not contain a consumer experience. Consumer experiences belong to implementations.

spec/                  The protocol specificationschemas/               JSON schemas for profiles, Pools, handshakes, messagingtools/  validator/           CLI: validate a Pool manifest URL  parser/              CLI: parse a profile URL into structured JSON  handshake/           Reference handshake server  discovery-agent/     Starter agent: query Pools in natural language  blocklist-publisher/ Tool to publish and sign shared block listsregistry/              Source code for the public Kindling registryexamples/              Hand-authored example Pool manifests and profilesLICENSE                Apache 2.0 for code, CC BY 4.0 for the spec textCONTRIBUTING.md        How to propose spec changes and submit implementationsGOVERNANCE.md          Maintainership, RFC process, working-group transitionCODE_OF_CONDUCT.md     Community standards

Conformance · §11

Four things you can build that conform.

The text of §11, with the live page’s plain version under each.

• 11.1 Compliant Pool host

  Implements §3 (manifest), §5 (handshake), §9 (continuity), and publishes a §10 well-known file.

  In short: Implements the manifest, the handshake, and continuity, and publishes a .well-known/kindling-pool file.

• 11.2 Compliant Pool UI

  Renders §4.5 verification levels alongside every Profile, honors §7 spam-filtering layers, supports §5.3 withdrawal, and never performs silent inclusion.

  In short: Shows verification level beside every profile, honors all three spam layers, supports withdrawal, never includes silently.

• 11.3 Compliant parser

  Reads §2.2 h-card fields preferentially, records extraction provenance, respects §2.7 noindex, and stores no photo bytes.

  In short: Prefers h-card, records what was inferred, respects noindex, stores no photo bytes.

• 11.4 Compliant messaging client

  Validates envelopes against §6.2 schema, surfaces verification level, and applies §7.1 gating.

  In short: Validates every envelope, surfaces verification level, applies identity-based gating.

Contributing

Three ways to help now.

• Specification feedback

  Read it. Open issues for ambiguities, gaps, and overreach. Implementers, identity-protocol veterans, and IndieWeb regulars especially.

  A good place to start: where the text and the schemas differ.

• Reference implementations

  Build a Kindling client in your stack. A list, a search view, a printed zine. Send the link and the registry lists it.

• Founding Pool curators

  Run a Pool. Curate it well. Write down what worked. The first curators are deciding what curation is as a craft.

Spec changes land through RFCs. Read CONTRIBUTING.md for the RFC process and the pull-request workflow.Maintainers: josh@intellibotique.com