Universal AI Plugin

The Universal AI Plugin is the no-connector path: a portable, machine-readable recipe that teaches any AI agent, in any language, to map a project's content to the ingestion contract, sign requests correctly, and stream content in. The agent does the integration; bAInquet does the extraction, structuring, and publishing.

Use it when no prebuilt connector fits your stack, or when you want an AI assistant to build the pipeline for you. It complements the hand-built connectors rather than replacing them.

What it is

The plugin ships in two forms plus a Claude Skill. Both forms carry the same contractVersion (currently 0.3.0), the same field names, and the same HMAC scheme (bq.connector.hmac.v1), and both are generated from the frozen ingestion contract. They describe and target the contract; they do not redefine it.

1. Offline scaffold

bainquet-scaffold.md is a single self-contained Markdown file you drop into any project's repository. It carries:

• an embedded JSON contract block (the field tables, SourceType enum, and limits),
• the exact HMAC signing recipe (HKDF derivation and the six-line canonical string),
• the step-by-step agent recipe (token, map, sign, post, verify, sync),
• the error and retry guidance.

It works air-gapped: an agent given only this file can build a working pipeline with no network lookup. The file is pinned to a contractVersion via a header comment:

<!-- bainquet:contract
contractVersion: 0.3.0
apiBaseUrl: https://api.bainquet.online/v1
manifestUrl: https://api.bainquet.online/.well-known/bainquet/manifest.json
hmacScheme: bq.connector.hmac.v1
-->

The staleness rule is conservative: re-fetch the online recipe only when the remote major version is greater than the local one. A greater minor or patch within the same major is additive and forward-compatible, so the embedded scaffold stays safe.

2. Online machine-readable bundle

The online bundle is the hosted truth an agent fetches at stable URLs to self-configure against the current, versioned contract. Fetch the manifest first; it is the single discovery entrypoint and links to every other part.

URL	Contents
https://api.bainquet.online/.well-known/bainquet/manifest.json	Discovery entrypoint: contractVersion, hmacScheme, the five endpoint URLs, the onboarding routes, the limits, and links to the parts below.
https://api.bainquet.online/scaffold/openapi.json	OpenAPI 3.1 description of the five ingestion endpoints, including the connector bearer plus HMAC security scheme and all request and response schemas.
https://api.bainquet.online/scaffold/schema/ingest-item.json	JSON Schema (draft 2020-12) for IngestItem and the batch payload, to validate an outbound payload before sending.
https://api.bainquet.online/scaffold/recipe.md	The canonical online copy of the agent recipe, mirroring the offline scaffold.
https://api.bainquet.online/scaffold/examples/	Three worked, schema-valid batch payloads: a CMS page, a product with structured pricing, and a docs page.

The manifest also publishes the operational limits an agent must honor:

{
  "contractVersion": "0.3.0",
  "hmacScheme": "bq.connector.hmac.v1",
  "limits": {
    "MAX_BATCH_ITEMS": 500,
    "MAX_PAYLOAD_BYTES": 5242880,
    "replayWindowSeconds": 300,
    "idempotencyTtlHours": 24
  }
}

How an agent self-configures

1. Read bainquet-scaffold.md, or fetch the manifest and follow its recipe, openapi, and schema links.
2. Obtain a connector token: self-serve onboarding (POST /v1/onboard/register, verify the domain, then POST /v1/onboard/exchange) or a dashboard-issued connector (POST /v1/websites/{websiteId}/connectors). You end with BAINQUET_CONNECTOR_TOKEN, BAINQUET_WEBSITE_ID, and BAINQUET_SITE_DOMAIN.
3. Discover the project's content and map each unit to an IngestItem, computing a stable sha256: checksum for each.
4. Validate the items against ingest-item.json, sign each batch with the HMAC scheme, and POST to /v1/ingest/batch.
5. Verify the per-item results, then set up a heartbeat and incremental sync.

Two gates apply throughout: ingest is allowed only when the website's verification state is verified or grace (otherwise the server returns 409 website.not_verified), and a node never becomes public until the domain is verified.

TIP

For JavaScript and TypeScript projects, the recipe points the agent at @bainquet/connector-sdk instead of hand-rolling the signer. For any other language, the agent follows the raw recipe; see Generic API connector.

When to use it

• No prebuilt connector exists for your platform.
• You want an AI assistant to discover and map your content automatically.
• You are building a connector in a new language and want a machine-checkable contract plus worked examples to target.

For a connector you build by hand, the SDK and the conformance suite are the reference and the gate.