Skip to main content

Context scan

An empty context is worth nothing, and nobody writes one from a blank page. A context scan reads a corpus of material the team has already written and proposes three things: the axes the content varies along, a voice profile draft, and candidate terms. You review and correct a first draft instead of authoring one. A scan is an onboarding aid, not an authority: nothing it proposes is enforced until you approve it through the ordinary Context surfaces, and the same correction loop that keeps the context current afterwards is what you use to review it.

A scan runs before any bring-your-own provider key exists, so it always uses platform AI credits. The credits it spends are reported on the job as it runs.

The flow​

A scan reads the sources you give it, assembles them into one corpus, and proposes what it found: the axes, a voice profile drafted from the corpus, and extracted term candidates. Each proposal is approved on its own.

Sourcespaste, URL, upload, git reporead sourcesCorpusassembled + source-taggedproposeAxesthe dimensions content varies alonginferVoice profile drafttone, style, vocabulary, examplesextract termsTerm candidatesterm + definition + domainreturn proposalsReviewapprove each, then it governs

A scan reads sources into one corpus and proposes axes, a voice profile and term candidates. Nothing governs until a person approves it.

The scan runs asynchronously. Creating one returns a job id; poll the scan until it reports completed and read the proposals it carries. The lifecycle is queued → processing → completed (or failed), and while processing the job reports a progress percentage and a phase label: reading sources, assembling the corpus, drafting the voice, extracting terms.

Sources​

A scan accepts any combination of four source kinds, assembled into a single source-tagged corpus:

  • Paste: copy or a style guide pasted directly as text.
  • URL: public web pages the scan fetches and reads as text. URL fetching is restricted to https and refuses private, loopback, and link-local addresses, re-checking on every redirect, so a scan cannot be pointed at internal infrastructure.
  • Upload: documents uploaded ahead of the scan. Uploads are validated against an allowlist of text-bearing formats before any bytes are stored; unsupported files are reported back rather than silently dropped. Per-file and per-batch size limits apply, and stored uploads are swept after a retention window so a "regenerate" during review can reuse the same files.
  • Git repository: a public https git repository, shallow-cloned; the scan reads its Markdown files.

The corpus is bounded: sources are read up to a total budget, and a scan reports which sources it read and which it skipped, so a corpus that was trimmed to fit is visible rather than silent.

What a scan proposes​

Axes​

A scan proposes the dimensions the corpus's content varies along: a brand, a mode (tutorial, how-to, reference, explanation), a market, or another axis the project has not yet named. An axis changes the shape of the context space, so it is approved separately from anything that sits on it.

An approved axis is recorded as a pending recipe change; it does not declare anything by itself. On a project connected from a checkout, the next kapi pull writes defaults.coordinates.<axis> into kapi.yaml, where git reviews it, and the axis exists once that lands and a push carries content at it. A structural axis, a product or a channel, is approved against a particular collection, because a scan reads a corpus rather than a project's collections and cannot know which one it meant; it lands as that collection's channel:. The recipe remains the only thing that mints a coordinate.

Voice profile​

The scan drafts a voice profile with the same shape a hand-authored one has: tone (personality, formality, emotion, humour), style rules (active voice, sentence length, point of view, contractions, prohibited patterns), vocabulary (preferred, forbidden, and competitor terms), and before/after examples. The draft is named to signal it needs review before it is adopted.

Each inferred section carries evidence: a confidence score and a short note citing what in the corpus supports it. The evidence travels alongside the draft so a reviewer can weigh each section rather than accept the whole profile blindly. It is a review aid, kept separate from the profile itself, so the profile still round-trips through the ordinary profile format.

Term candidates​

Alongside the voice profile, the scan extracts term candidates: terms found in the corpus, each with an optional definition and domain, deduplicated and merged with the profile's preferred terms. These are candidates for the terms explorer, not governed concepts; adopting them is a separate, deliberate step.

Review, then approve​

A scan never writes to the graph on its own. It produces proposals; approving each is a deliberate second action, so the separation between curation and governance holds from the very first profile.

Youmanage_voiceContext scanasync jobContextaxes + profiles + termscreate scan from sourcesread → propose → infer → extractspends platform creditsreturn proposals + evidenceapprove an axisa recipe change, delivered by pulltest edited draft against sample textno AI costadopt: save profile at its point, promote terms

A scan returns proposals you review. An approved axis reaches the recipe through pull; an adopted profile is bound at its point; promoted terms become concepts.

While reviewing, you can test a draft against a sample of your own text: the scan scores the sample against the (possibly edited) draft profile using the deterministic vocabulary matcher, with no AI call and no credit cost, so you can adjust the draft and see the effect before committing to it.

When the draft is ready, you approve it through the ordinary surfaces: the edited voice profile is saved as a voice profile bound at the point it governs, and the term candidates are promoted through the terms explorer. The scan itself creates none of these; it hands you proposals to carry forward.

Credits and quota​

Because onboarding happens before a workspace has configured a bring-your-own provider key, a scan always runs on platform AI credits, the same credits model that governs the rest of the platform's AI operations. A scan is refused up front if the workspace has no spendable credits, and the credits it spends (one credit per token) are metered per phase and reported on the job as tokens_used. On a self-hosted deployment with billing disabled, no credits are deducted. Approving an axis never costs anything.

Under the hood​