Skip to content

Developers Constellation

Constellation
for developers.

Connect a website or a build to Constellation. It turns your public sources into a cited knowledge graph, serves bounded evidence to your chatbots and applications, and reports the integrations you connect. This page documents the SDK, the command line and the v1 API.

Release status

SDK 0.2.8 is a prerelease and the v1 API is pending release. Kuykendall Industries provisions projects directly at this stage. Live reachability and every capability’s state are under Status.

Release record

SDK
0.2.8 · Prerelease
Packages
4 tarballs with SHA-256
Runtime
Node.js 20.19.0 or newer
Protocol
KPP 1.0
API
v1 · version 2026-11-01
License
Proprietary (UNLICENSED)
npm registry
Not published yet

What Constellation does

Constellation connects the public sources you control to a cited knowledge graph. It observes your website, reads a publication you serve, or accepts one you upload, and keeps each acquisition as a complete Knowledge Publication Protocol (KPP) 1.0 publication with the exact source bytes.

Your applications ask questions through the v1 API and receive bounded, cited evidence: complete records with their citations, any qualifications those records require, a coverage report and explicit omissions. Retrieval uses exact entity and page resolution, PostgreSQL full-text search and bounded typed traversal. There is no vector database to provision or keep in sync.

Constellation also reports the operational integrations you connect, such as Vercel log delivery, with an explicit state for each one.

Four packages

  • @kuykendall/constellation-protocol

    KPP 1.0 wire types, the pinned schema, canonical hashing, identity helpers and validateSnapshot: the collector’s exact acceptance checks, so you can reproduce a rejection before you publish.

  • @kuykendall/constellation-publisher

    Static and dynamic publishers whose output is byte-compatible with the portfolio kpp-static/1.0.0 layout; /http, a Node and Vercel handler with ETags and runtime deployment proof; /observe, semantic HTML extraction with exact UTF-8 byte-range citations, RFC 9309 robots rules, sitemaps, a bounded crawler and a build-output reader; and /conformance, the adapter conformance kit.

  • @kuykendall/constellation

    The typed v1 client, including server-side Vercel connections; answer(), which turns evidence into a chat answer with citation validation and required-context checks; the openAICompatibleModel adapter; and webhook signature verification.

  • @kuykendall/constellation-cli

    The constellation command: init, build, validate, publish, collect, connect, sync, status, doctor and vercel. Every command accepts --json. The key is read from CONSTELLATION_API_KEY and never printed.

Version identities are independent: release 0.2.8 pins each package’s own version (listed under Install), the HTTP API is v1 with the constellation-version header 2026-11-01, and publications are KPP 1.0.

Access and membership

Constellation is part of the software portfolio included with KI memberships. It is not sold as a separate Store product, and this page lists no separate price.

  • Projects

    Kuykendall Industries provisions each Constellation project directly at this stage. Provisioning creates the project and its first admin API key, which is shown once. There is no self-service sign-up yet.

    Request a project
  • KI members

    Current paid Kuykendall One, Ultra, and Unlimited memberships include Warden and the Constellation SDK at no additional membership charge. Sign in to your KI Store account and open Membership to download the packages for your organization.

    SDK downloads included with current paid membership

  • KI employees

    Employee access is provided by the company and needs no Store account or membership. Sign in to the KI Employee Portal, then download the packages from this page.

    Sign in to the Employee Portal

Install the SDK

Release 0.2.8 is a prerelease distributed as 4 tarballs. Publication to the npm registry is not available yet, so there is no registry install command. Download the tarballs, check their SHA-256 values, then install them from the folder that holds them.

The links below use your KI Employee Portal session. Members download these same packages from their KI Store membership account. Connected service coverage is reported separately under Status.

Verify the files

Save this text as SHA256SUMS in the download folder and check every file before you install it. On Windows, compare Get-FileHash -Algorithm SHA256 output with the values above.

7113906b9e6ba1f36bbfcf04b9c16c2a2d6298840c07ee9a51664654864af31c  kuykendall-constellation-protocol-0.1.0.tgz
9414db9dcec2fa90422d05f45bba12131c2e8c1f1f0fee5d34a9dcc49fb2fe75  kuykendall-constellation-publisher-0.1.4.tgz
13d35b9de2f34ca46083c3f47f4a2203244f46ead305f8a68891d27b4d5881c0  kuykendall-constellation-0.2.8.tgz
85c48a59a8b29d5561368fe929bc254b2851b543d714e208b8aaaf0f23b02ec8  kuykendall-constellation-cli-0.1.12.tgz

sha256sum -c SHA256SUMS          # Linux
shasum -a 256 -c SHA256SUMS      # macOS

Install the packages

Install all 4 in one command so the packages resolve each other locally. Their open-source dependencies (ajv, ajv-formats and parse5) come from the public npm registry. The complete four-package installation requires Node.js 20.19.0 or newer. The client and protocol packages on their own support Node.js 20.11.0 or newer; the publisher and CLI require 20.19.0 or newer.

npm install ./kuykendall-constellation-protocol-0.1.0.tgz ./kuykendall-constellation-publisher-0.1.4.tgz ./kuykendall-constellation-0.2.8.tgz ./kuykendall-constellation-cli-0.1.12.tgz

npx constellation --version

Quickstarts

Commands that contact the API read a project key from CONSTELLATION_API_KEY. Export it in your shell or your CI secret store; never commit it. init, build and validate work offline.

Connect a website

Constellation observes only hosts your project has verified. Read the project’s verification token with an admin key (it is the verification.token field), then publish it either as the content of https://<host>/.well-known/constellation-verification.txt or as a DNS TXT record named _constellation-verification.<host>.

curl -sS https://ki-congress-web.onrender.com/api/constellation/v1/project \
  -H "Authorization: Bearer $CONSTELLATION_API_KEY" \
  -H "constellation-version: 2026-11-01"

If the host is not on the project yet, add it; then ask Constellation to check the token.

curl -sS -X POST https://ki-congress-web.onrender.com/api/constellation/v1/project/domains \
  -H "Authorization: Bearer $CONSTELLATION_API_KEY" \
  -H "constellation-version: 2026-11-01" \
  -H "Idempotency-Key: add-www-example-com" \
  -H "content-type: application/json" \
  -d '{"host":"www.example.com"}'

curl -sS -X POST https://ki-congress-web.onrender.com/api/constellation/v1/project/domains/www.example.com/verify \
  -H "Authorization: Bearer $CONSTELLATION_API_KEY" \
  -H "constellation-version: 2026-11-01"

Then connect the site and acquire it. connect prefers a KPP feed the site already publishes at /.well-known/knowledge-feed.json and otherwise registers an observation source; sync starts an acquisition and waits for the job. init writes constellation.config.json, which remembers the connected source for sync and status.

npx constellation init --url https://www.example.com
npx constellation connect https://www.example.com && npx constellation sync
npx constellation status

Publish from a build

Use this when your HTML is generated at build time. build --dir reads the rendered output, follows cleanUrls and trailingSlash from vercel.json, skips error and noindex pages, records the exact commit and repository from your CI environment or Git, and writes a publication to .knowledge. validate runs the collector’s acceptance checks locally. connect --mode push registers a push source once; publish uploads only the blobs Constellation does not already hold and waits until the publication is adopted.

npx constellation init --mode build --origin https://www.example.com
npx constellation build --dir dist
npx constellation validate
npx constellation connect --mode push
npx constellation publish

Publish records from your own code

When your records already live in code or a database, publish them directly. publishSnapshot validates the complete publication with the collector’s checks before it writes anything. A qualification that must travel with a claim is its own node, listed in the claim’s requiredContext.

// scripts/publish-knowledge.mjs — run after your build
import { publishSnapshot } from '@kuykendall/constellation-publisher';

const origin = 'https://www.example.com';
const identity = {
  sourceId: 'urn:kpp:example-com:catalog',
  publisherId: `${origin}/#organization`,
  scopeId: 'example-com',
  partition: 'catalog',
  visibility: 'public',
  policyRevision: 'public/1',
};
const record = { price: 'Custom cakes start at $45.', notice: 'Orders need three days of notice.' };
const resourceId = `${origin}/records/custom-cakes`;

publishSnapshot({
  identity, origin, outputDirectory: '.knowledge',
  extractorVersion: 'example-catalog/1', mappingVersion: 'example-kpp/1',
  resources: [{ resourceId, canonicalUrl: `${origin}/cakes`, title: 'Custom cakes',
    bytes: JSON.stringify(record) + '\n', mediaType: 'application/json; charset=utf-8',
    representation: 'structured_public_record' }],
  nodes: [
    { assertionId: `${origin}/kpp/nodes/notice`, entityId: `${origin}/#cake-notice`,
      entityType: 'https://schema.org/Text', label: 'Ordering notice',
      attributes: { text: record.notice }, evidenceResources: [resourceId] },
    { assertionId: `${origin}/kpp/nodes/price`, entityId: `${origin}/#cake-price`,
      entityType: 'https://schema.org/Offer', label: 'Custom cake price',
      attributes: { text: record.price, requiredContext: [`${origin}/#cake-notice`] },
      evidenceResources: [resourceId] },
  ],
  edges: [],
});

Serve the publication from your origin with the handler, using the same routes as the Kuykendall Industries portfolio sites. It answers conditional requests with ETags and refuses anything that is not part of the publication.

// api/knowledge.js — serves the publication in .knowledge
import { createKnowledgeHandler } from '@kuykendall/constellation-publisher/http';

export default createKnowledgeHandler();

{
  "functions": { "api/knowledge.js": { "includeFiles": ".knowledge/**" } },
  "rewrites": [
    { "source": "/.well-known/knowledge-feed.json", "destination": "/api/knowledge?resource=discovery" },
    { "source": "/api/knowledge/v1/manifest", "destination": "/api/knowledge?resource=manifest" },
    { "source": "/api/knowledge/v1/health", "destination": "/api/knowledge?resource=health" },
    { "source": "/knowledge/v1/snapshots/:revision/:artifact", "destination": "/api/knowledge?resource=snapshots/:revision/:artifact" },
    { "source": "/knowledge/v1/content/:digest", "destination": "/api/knowledge?resource=content/:digest" }
  ]
}

Check the served feed with the same rules, then register it. Without --mode, connect finds the feed by itself.

npx constellation validate --feed https://www.example.com/.well-known/knowledge-feed.json
npx constellation connect https://www.example.com --mode publisher

Retrieval and chat

retrieve() returns an evidence packet: numbered evidence items with exact citations, the required-context items each one depends on, a coverage report per source and explicit omissions. A record whose qualification cannot be produced is withheld rather than sent without it.

answer() retrieves evidence, asks your model to answer only from it, checks every citation, number and required qualification against the exact packet, asks for one repair when a check fails, and records the accepted answer with its source dependencies so a later source change invalidates it.

// Server-side code only: keep project keys out of browser bundles.
import { Constellation, answer, openAICompatibleModel } from '@kuykendall/constellation';

const constellation = new Constellation(); // reads CONSTELLATION_API_KEY

const packet = await constellation.retrieve({ query: 'What do custom cakes cost?', limit: 8 });
// packet.evidence, packet.requiredContext, packet.coverage and packet.omissions

const result = await answer({
  client: constellation,
  question: 'What do custom cakes cost?',
  model: openAICompatibleModel({
    baseUrl: process.env.MODEL_BASE_URL, // any OpenAI-compatible endpoint
    apiKey: process.env.MODEL_API_KEY,
    model: process.env.MODEL_NAME,
  }),
});
if (!result.check.valid || result.stale) {
  console.error('Answer requires review', result.check);
} else {
  console.log(result.answer, result.citations.map((item) => item.url));
}

If the optional repair still fails citation checks, the result remains a draft with check.valid: false and output: null; the SDK does not attempt to record it. Streamed text is draft output. Check validity and source freshness before displaying an accepted answer.

Bring your own model

A model is any function that takes chat messages and returns the answer text; call onDelta to stream. answer() calls only the model you pass in, so your model account, keys and costs stay yours. A supplied signal stops pending SDK waits and prevents later model, repair or save calls. Results and receipts accepted before cancellation remain available. A provider must honor the signal to stop its own work; remote effects are not rolled back.

const model = async (messages, { signal, onDelta }) => {
  const reply = await myModelClient.chat({ messages, signal }); // your provider SDK
  return reply.text;
};
const stop = new AbortController(); // Call stop.abort() from your cancellation handler.
const result = await answer({ client: constellation, question, model, signal: stop.signal });

The same request over HTTP

curl -sS https://ki-congress-web.onrender.com/api/constellation/v1/retrieve \
  -H "Authorization: Bearer $CONSTELLATION_API_KEY" \
  -H "constellation-version: 2026-11-01" \
  -H "content-type: application/json" \
  -d '{"query":"What do custom cakes cost?","limit":8}'

The request accepts query (up to 500 characters), optional sources and requiredSources (source IDs), limit (1–50), maxChars (1,000–100,000), and since and until timestamps.

Keys in browsers

Keep read, write and admin keys on your server. A public key can read only sources you made public and never sees restricted sources, jobs or administration; ship one to a browser only when that exposure is what you intend.

Events and webhooks

Event deliveries carry constellation-signature (a timestamp and an HMAC-SHA256 of the raw body) and constellation-event-id. The verifier authenticates the raw bytes, then requires the header to match the signed payload’s own id. It returns that authenticated identity; any current secret is accepted during a rotation.

import { verifyDelivery } from '@kuykendall/constellation/webhooks';

export async function POST(request) {
  const event = await verifyDelivery({
    secret: process.env.CONSTELLATION_WEBHOOK_SECRET,
    rawBody: await request.text(),
    signature: request.headers.get('constellation-signature'),
    eventId: request.headers.get('constellation-event-id'),
  }); // throws SIGNATURE_MISSING, SIGNATURE_INVALID, SIGNATURE_EXPIRED,
      // EVENT_ID_INVALID or EVENT_ID_MISMATCH
  console.log(event.id);
  return new Response(null, { status: 204 });
}

Before an application effect, check the expected project and current authority. Deduplicate the returned event.id durably within the receiving subscription and project, committing that record atomically with the effect or using the destination’s idempotency mechanism. A retry signed with a newer timestamp keeps the same event ID; signature verification alone does not store replay state.

Authentication and keys

Send a project key as Authorization: Bearer <key>. Keys look like ck_live_ (production) or ck_test_ followed by a six-character prefix and the secret. Constellation stores only a SHA-256 digest; the secret is shown once, when the key is created. Authority comes from the key’s project: IDs in a path or body only select records inside that project.

Key capabilities
CapabilityAllows
publicListing, reading and retrieving from sources that are public. Never restricted sources, jobs or administration.
readEvery source in the project, with coverage, history and jobs.
writeEverything read allows, plus sync, uploads, and cancelling or retrying jobs.
adminEverything write allows, plus domains, keys, and registering, changing, revoking or erasing sources.

Create narrower keys with an admin key and store the returned secret in your secret manager. Revocation is immediate: a revoked key fails its next request exactly like an unknown key.

curl -sS -X POST https://ki-congress-web.onrender.com/api/constellation/v1/project/keys \
  -H "Authorization: Bearer $CONSTELLATION_API_KEY" \
  -H "constellation-version: 2026-11-01" \
  -H "Idempotency-Key: create-site-chat-key-1" \
  -H "content-type: application/json" \
  -d '{"name":"Site chat (server)","capabilities":["public"]}'

curl -sS -X POST https://ki-congress-web.onrender.com/api/constellation/v1/project/keys/KEY_ID/revoke \
  -H "Authorization: Bearer $CONSTELLATION_API_KEY" \
  -H "constellation-version: 2026-11-01" \
  -H "Idempotency-Key: revoke-site-chat-key-1"

Request rules

  • Version. Send constellation-version: 2026-11-01. An unsupported value fails with VERSION_UNSUPPORTED. Every response carries constellation-api-version and x-request-id.
  • Idempotency. Commands that register, change, revoke or erase records, start a sync, commit an upload, or manage jobs, domains and keys require an Idempotency-Key of 8–200 characters. Retrying with the same key and body replays the original receipt; the same key with a different body fails with IDEMPOTENCY_CONFLICT. The SDK client generates keys for you.
  • Revisions. Changing a source requires If-Match with the revision you read; a stale revision fails with REVISION_CONFLICT.
  • Rate limits. Over the limit, requests receive 429 RATE_LIMITED with Retry-After. The client retries reads and keyed commands with backoff.

Errors use one envelope:

{
  "error": {
    "code": "DOMAIN_NOT_VERIFIED",
    "message": "Verify www.example.com for this project before observing it.",
    "retryable": false,
    "requestId": "7b0e2b8c-5f0a-4c4e-9a43-2a8f6f0d3e11",
    "details": { "host": "www.example.com" }
  }
}

API reference

Base URL: https://ki-congress-web.onrender.com/api/constellation/v1. Use this address for API calls: constellation.kuykendall.industries is the browser workspace and refuses bearer credentials with HTTP 421. Set CONSTELLATION_API_URL to point the SDK elsewhere. Project provisioning (POST /projects) is performed by Kuykendall Industries and is not available to project keys.

Project, domains and keys

MethodPathPurpose
GET/openapi.jsonThe machine-readable contract; no key required.
GET/projectThe key’s project, domains, capabilities and limits.
POST/project/domainsAdd a host to verify.
POST/project/domains/{host}/verifyCheck the well-known file or DNS TXT token.
GET/project/keysList keys by prefix; secrets are never returned.
POST/project/keysCreate a key; the secret is returned once.
POST/project/keys/{id}/revokeRevoke a key immediately.

Sources and uploads

MethodPathPurpose
GET/sourcesList sources with health and coverage.
POST/sourcesRegister an observe, publisher or push source.
GET/sources/{id}One source.
PATCH/sources/{id}Rename, change observation rules, pause or resume (with If-Match).
POST/sources/{id}/syncStart an acquisition job now.
GET/sources/{id}/coverageEvery route’s outcome from the last complete observation.
GET/sources/{id}/historyAdopted publications over time.
POST/sources/{id}/revokeDisconnect and withhold evidence.
POST/sources/{id}/eraseIrreversibly erase retained data; requires a reason.
POST/sources/{id}/uploadsBegin a push upload with the manifest (up to 1 MiB).
PUT/sources/{id}/uploads/{uploadId}/blobs/{sha256}Upload one declared blob (up to 16 MiB).
POST/sources/{id}/uploads/{uploadId}/commitValidate and adopt the complete publication.

Jobs

MethodPathPurpose
GET/jobsRecent acquisition and adoption jobs.
GET/jobs/{id}One job, its attempts and its error code.
POST/jobs/{id}/cancelCancel a queued or running job.
POST/jobs/{id}/retryRetry a failed, cancelled or dead-lettered job.

Graph, retrieval and outputs

MethodPathPurpose
GET/graph/entitiesSearch entities by text, type or source.
GET/graph/entities/{id}One entity with its evidence.
GET/graph/entities/{id}/neighborhoodBounded typed traversal around an entity.
GET/graph/changesRecent graph changes, paged by cursor.
POST/retrieveCited evidence for a question.
POST/outputsRecord an answer with its exact dependencies.
GET/outputs/{id}An output and whether it needs revalidation.

Operations, events and usage

MethodPathPurpose
GET/integrationsConnected integrations and their states.
GET/integrations/{id}One integration.
GET/incidentsGrouped operational incidents.
GET/incidents/{id}One incident with its evidence.
GET/eventsProject events after a cursor.
GET/webhooksWebhook subscriptions.
POST/webhooksSubscribe a URL to event types.
POST/webhooks/{id}/disableStop deliveries to a subscription.
GET/usageUsage against the project’s limits.

Source lifecycle

Three ways in

observe
Constellation reads your public website within explicit bounds: robots rules (RFC 9309), sitemaps, include and exclude rules, and page limits. The host must be a verified project domain.
publisher
Constellation reads the KPP publication you serve, starting from its discovery document. The feed must be public, its canonicalOrigin must match its URL, and its host must be verified.
push
You upload complete publications with constellation publish or the uploads API. A push source acquires when an upload is committed.

How a source changes

  • Every acquisition is validated as a complete publication before it replaces the previous one. A partial or cancelled observation is never adopted; it resumes on the next sync.
  • A page is removed only on a definitive signal: 404 or 410, a robots or scope exclusion, noindex, a redirect or a canonical duplicate.
  • A temporary failure, such as a timeout, a network error, a 429 or a 5xx response, keeps the last retained version, marked as carried forward.
  • Scheduled observation syncs run at most every 15 minutes.

Pause, revoke or erase

Pause
Set state to paused with PATCH /sources/{id}; set it back to active to resume.
Revoke
Disconnects the source: acquisition stops and its evidence is withheld from retrieval. Retained history stays for audit until you erase it.
Erase
Irreversibly removes the retained bytes, the derived graph, passages and dependent outputs. It requires a reason, and only the project that owns the source can erase it.

Vercel logging

Constellation receives signed Vercel log deliveries, groups them into incidents and reports each integration’s state. Kuykendall Industries runs this intake for its own Vercel projects today.

Customer self-connection: implemented, pending release

A project’s admin key connects your own Vercel team from your server, with integrations.connectVercel({ token, teamId, projectIds }) or the vercel command below, which reads a team-scoped token from VERCEL_TOKEN. The token is sent once; Constellation seals it and never returns or prints it. Constellation then creates a log drain signed with a secret only it holds, reads the drain back and reports any difference. rotateSecret replaces the signing secret make-before-break, and disconnect removes the drain and reports whether its removal was confirmed.

npx constellation vercel connect --team <team id> --project <project id>
npx constellation vercel verify --url <URL of a request that logged a warning or error>
npx constellation vercel status
npx constellation vercel rotate
npx constellation vercel disconnect --yes

integrations.verify(id, { requestId }), which vercel verify calls with the response’s x-vercel-id, proves that a known warning or error reached the intended project and deployment through a signed delivery. The service release that accepts customer connections has not shipped yet; until it does, production refuses them. GET /integrations and GET /incidents report what is connected.

Integration states
StateMeaning
connectedVercel access is authorized; no project or environment is selected yet.
configuredProjects and environments are selected; no signed delivery has arrived yet.
receivingSigned log deliveries are arriving.
runtime_verifiedA known request, identified by its x-vercel-id, was confirmed in the intended project’s and deployment’s logs, not only received.
staleNo delivery has arrived since the integration’s staleAfter time.
unavailableThe current state cannot be read; it is not treated as healthy.
failedConfiguration or delivery failed and needs attention.

constellation doctor reports configured, receiving and runtime_verified as working and every other state as a problem to fix.

Warden, By Kuykendall Industries

AI firewall and online system monitoring live inside Constellation. Warden is included at no additional membership charge with Kuykendall One, Ultra, and Unlimited, through the existing Constellation SDK and account boundary.

Connect Vercel, Supabase, and application telemetry to follow external probes, scaling pressure, backend failures, and browser errors. Each incident retains its evidence, investigation, repair ticket, execution receipts, and production checks.

For a member project, open MABOS-Code, select the project, and choose Warden. Its settings connect the repair agent, set an explicit customer-funded model allowance, and define any permitted database recovery tables and row boundaries. Automatic deployment uses the selected Vercel project, current provider authorization, the separate Warden Release App, and the repository's protected config/warden/probes.json catalogue. The settings show which prerequisites are ready.

Warden is included in downloadable SDK 0.2.8. Service availability and observed runtime coverage are shown under Status.

The Warden entry point extends @kuykendall/constellation. It uses an authenticated Congress access token, an authorized workspace, and a server-issued run. Existing customer project keys are not Congress access tokens. Keep server credentials on your server; browser instrumentation sends through your application’s authenticated same-origin proxy.

import { Warden, createWardenMonitor } from '@kuykendall/constellation/warden';

const warden = new Warden({
  accessToken: process.env.CONGRESS_ACCESS_TOKEN,
  scopeId: process.env.CONGRESS_SCOPE_ID,
  agentRunId: process.env.CONGRESS_RUN_ID,
  integrationId: process.env.WARDEN_INTEGRATION_ID,
});
const monitor = createWardenMonitor({
  projectId: process.env.WARDEN_PROJECT_ID,
  send: (events, key) => warden.capture(events, key),
});

export async function reportApplicationFailure(error) {
  monitor.captureException(error);
  await monitor.flush();
}
const incidents = await warden.incidents();

export async function readRepairReport(notificationId, signal) {
  const { report } = await warden.notificationReport(notificationId, signal);
  return report;
}

Call reportApplicationFailure(error) from your application’s existing error handler. Use a real configured integration and its mapped project. configureObservation establishes the permitted intake mapping; it does not report that an event was observed. capture returns the durable intake receipt, while incidents(), notifications(), status(), and task(id) read the recorded work.

notificationReport(notificationId, signal) reads the investigation, repair ticket, release, production checks, and recovery record for an existing notice. It keeps current verification separate from historical evidence. Reading or refreshing a report does not acknowledge the notice or create another notification.

Detection and investigation
Provider firewall rules enforce request protection. Warden correlates the resulting signals and investigates asynchronously. Incident text is evidence; it cannot authorize a repository change or deployment.
Repair routing
A ticket can use the project’s authorized MABOS-Coding agent, an isolated KI-hosted coding agent, or a connected Cursor agent. Constellation retains the target repository, execution authority, and recorded outcome.
Verification and recovery
Code, test, deploy, then verify the actual production deployment. Code rollback and database recovery have separate evidence. A database change needs a migration-aware recovery plan that preserves subsequent writes.
Three notifications at most
Issue found. Ticket dispatched. Repair verified in production. Retries and intermediate agent work stay in the incident timeline. A provider’s “completed” status alone cannot produce a success notification.

Membership inclusion does not establish monitoring coverage by itself. Constellation reports the integrations actually connected, the last verified intake, the agent route, and the status of each repair. Existing agreed compute, model, and external-provider allowances continue to apply.

Custom adapters

An adapter turns a source system, such as a CMS, a repository, a database, a hosting provider or a runtime, into Constellation knowledge. An adapter is anything that produces a complete KPP 1.0 publication that passes validateSnapshot: a manifest, the nodes, edges and content_index artifacts, and the exact bytes of every content record. buildStaticPublication and buildDynamicPublication run that check before anything is written or uploaded.

What every publication needs

  • Stable identity: one sourceId, publisherId, scopeId, partition, visibility and policyRevision, never derived from a display name or reused from another source.
  • Exact evidence: every node and edge cites a content record by resourceId, resourceRevision and sha256, preferably with utf8_byte_range locators.
  • Complete records: the source’s full bytes, never an excerpt published as the source.
  • Required context: a qualification such as pricing, availability, legal or policy terms is its own node with evidence, listed in the claim’s attributes.requiredContext (and requiredContextIds for older consumers).
  • Honest basis and lineage: authored_publication, database_publication or observed_page, with lineage for copied or compiled material.
  • Completeness: a partial or cancelled acquisition is never published, and only a definitive signal removes a record.

Validate before you deliver

import { validateSnapshot } from '@kuykendall/constellation-protocol';

// manifestBytes: the exact manifest; fetched: a Map from every artifact and
// content URL to its exact bytes; identity: the source identity you declared.
const snapshot = validateSnapshot(manifestBytes, fetched, identity);
// Throws a KppError carrying the collector's own code, such as KPP_EVIDENCE_UNRESOLVED.

From the command line, npx constellation validate --dir .knowledge checks a local publication and npx constellation validate --feed <discovery URL> checks a served one.

Conformance

checkAdapterConformance(adapter, scenario) from @kuykendall/constellation-publisher/conformance runs the adapter contract against your own fixtures. An adapter has a name, a version, its source identity and a run(input, context) that returns whether it is complete, the validated publication and an outcome for every discovered item. The scenario supplies a baseline and, optionally, an edit, a temporary failure, a deletion, a qualified claim and a cancellation point.

The report checks that the output passes validateSnapshot and is deterministic; that every discovered item has an explicit outcome; that evidence is exact; that an edit changes only the affected records; that a temporary failure keeps a record while a definitive deletion removes it; that qualifications survive as resolvable required context; and that cancellation leaves no publication while resumption completes it. The built-in website observer, createSiteAdapter from /observe, passes every check. Kuykendall Industries lists an adapter as supported only after its report passes.

Troubleshooting with constellation doctor

Start with doctor. It checks Node, the config file, the local publication, the key (shown only by its prefix), API reachability, domains, sources and integrations, and prints a fix for each problem. Add --json for machine-readable output.

npx constellation doctor
Common error codes
CodeWhat it means and what to do
DOMAIN_NOT_VERIFIEDThe host is not a verified domain of the project. Publish the token at the well-known path or the DNS TXT record, then verify the domain.
KPP_PUBLICATION_UNCONFIRMEDThe feed was archived but has no production confirmation. Register publisher sources with origin confirmation, which is what constellation connect does by default.
KPP_SOURCE_UNAVAILABLEThe publisher could not be read. Check that the site is up and the feed URL is public.
OBSERVATION_INCOMPLETEThe last observation did not finish. It resumes on the next sync and never replaces the previous complete publication.
CRAWL_DESTINATION_BLOCKEDThe site resolves to a private address. Run a local collector with constellation collect, which observes a site you operate and uploads it to a push source.
IDEMPOTENCY_CONFLICTThe Idempotency-Key was used with a different request. Use a new key for a new request; reuse a key only to retry the identical request.
KEY_CAPABILITY_REQUIREDThe key lacks the capability the operation needs. Use a key with the capability named in details.required.
UNAUTHENTICATEDThe key is missing, unknown, expired or revoked. Create a new key with an admin key.

Quotas and retention

These are the defaults. A project can have different limits; GET /project returns the limits that apply to it.

Default project limits
LimitDefault
Sources per project25
Pages per observation200
Retained bytes per source64 MiB
Retrievals120 per minute
API requests per key600 per minute
Sync intervalAt least 15 minutes
Retention365 days
Push uploadsManifest up to 1 MiB, each blob up to 16 MiB; an open upload expires after 24 hours

Compatibility and migrations

  • Protocol. Publications use KPP 1.0. The pinned schema’s SHA-256 is 6d2643b240003c0fc69a7fad961df05b99e115500b19fab91dc227d34746e532.
  • API. The path carries the major version (v1) and the constellation-version header selects the contract (2026-11-01). Package, API and protocol versions change independently.
  • Portfolio publishers. publishSnapshot from @kuykendall/constellation-publisher takes the same arguments and writes the same kpp-static/1.0.0 layout as the portfolio publisher, byte for byte, including current.json. Identical input produces the identical contentRevision, so collectors see no change. The handler also accepts the existing ?resource= rewrites.

// Before: import { publishSnapshot } from './lib/knowledge/publisher.js';
import { publishSnapshot } from '@kuykendall/constellation-publisher';

After switching, rebuild and compare the new contentRevision with the one you serve. For the same input, they match.

Status

Capability and release status

As of . Implemented means the code exists in the SDK or the service. Deployed and Runtime observed require the released service in production; a build or a test run does not count.

Capabilities by release state
CapabilityImplementedDeployedRuntime observed
KPP 1.0 types, pinned schema and collector-identical validation @kuykendall/constellation-protocolImplementedPending releasePending release
Static and dynamic publishers, byte-compatible with the kpp-static/1.0.0 layout @kuykendall/constellation-publisherImplementedPending releasePending release
Node and Vercel publication handler with deployment proof @kuykendall/constellation-publisher/httpImplementedPending releasePending release
Semantic HTML extraction with exact byte-range citations, robots, sitemaps and a bounded crawler @kuykendall/constellation-publisher/observeImplementedPending releasePending release
Build-output reader with commit provenance @kuykendall/constellation-publisher/observeImplementedPending releasePending release
Adapter conformance kit: validation, outcomes, evidence, required context, determinism, scoped change, carry-forward, deletion and resumable cancellation @kuykendall/constellation-publisher/conformanceImplementedPending releasePending release
Typed v1 API client @kuykendall/constellationImplementedPending releasePending release
answer() with citation validation and required-context checks @kuykendall/constellationImplementedPending releasePending release
Webhook signature verification @kuykendall/constellation/webhooksImplementedPending releasePending release
constellation init, build, validate, publish, collect, connect, sync, status, doctor and vercel @kuykendall/constellation-cliImplementedPending releasePending release
Versioned API at /api/constellation/v1 with idempotent mutations Constellation serviceImplementedPending releasePending release
Projects, domain verification and revocable API keys Constellation serviceImplementedPending releasePending release
Observe, publisher and push sources with jobs, coverage and uploads Constellation serviceImplementedPending releasePending release
Cited retrieval with required context and explicit omissions Constellation serviceImplementedPending releasePending release
Customer self-connection of Vercel log delivery: sealed team token, signed drain with readback, runtime verification, secret rotation and disconnect Constellation serviceImplementedPending releasePending release
Warden telemetry, browser errors, Supabase monitoring, firewall and drain controls, scoped incident and repair reads @kuykendall/constellation/wardenImplementedPending releasePending release
Warden included with paid One, Ultra and Unlimited memberships, with independent connection and runtime coverage state Constellation and KI StoreImplementedPending releasePending release

Live service status

Live status is checked from your browser.