contexa-core contexa-iam contexa-autoconfigure

Prompt Versions

How to change the security decision prompt without touching source code. A version is a complete prompt that never changes once made: Contexa's rules stay locked, and the rest can be changed, deleted or added to on the screen or in a document. This page covers the three-click flow, the locked and changeable parts, using a version for decisions and rolling back, trials, canaries, running alongside, documents, the length check the order in which a decision's version is chosen, and the seven AI prompts other than the security decision kept the same way.

At a glance

The prompt decisions use is kept as versions: v1.0, v2.0 and so on, one number per tenant and prompt. Every version is a whole prompt. The version Contexa ships (Provided by Contexa) holds every part; a version of Our organization holds its base and only what it changes, deletes or adds. A version cannot be changed once made: a change is always the next number.

  • Where: menu "Prompt Quality → Prompt versions" (/contexa/admin/prompt-quality/versions). Every screen and API needs the administrator role.
  • What runs: a decision takes the version chosen on the screen, else the one the configuration names, else the newest Contexa version (How a decision's version is chosen). The version is fixed on the event when the decision starts, so Layer 1, Layer 2 and every retry of one decision use the same version. The other seven prompts take their label, else the newest Contexa version (The seven prompts other than the security decision).
  • What stays Contexa's: the standard blocks of the user prompt and the values the engine fills in, the answer format, the reason codes and the rules marked with a lock. The prompt's sentences come from the version; the code holds no sentence of the prompt.
  • Prompt choice: the list screen has a "Prompt" choice with eight prompts: "Security decision" (cortex.security-decision) first, then the seven prompts other than the security decision (below). This page speaks of the security decision unless it names another prompt.
Three clicks to a new promptA trial before using it is recommended but not required.
  1. 1New versionthe base is the version in use
  2. 2Change and savechecked before saving; saving makes the next number
  3. optionalTrialrecent sealed decisions decided again with two versions, recorded only
  4. 3Use for decisionsevery server follows within about 5 seconds

The three-click flow

  1. "New version" on the list screen opens the new version screen with the version used for decisions now as its base (/versions/new?base={number}). "New version" on a row, or on a version's screen, starts from that version instead.
  2. Change the parts and choose "Save". Only the parts you may change are open; parts with a lock are folded under "Contexa rules". The "Checks before saving" box is checked again as you change it, and "Save" works only when it passes. Saving makes the next number and leaves the base as it is.
  3. "Use for decisions" on the new version's row. The confirmation shows "Now", "Next" and "Takes effect" ("Every server follows within about 5 seconds; a decision already started ends with its version."), whether the version was tried, and a reason you may write ("Reason (optional)", kept in the history).

"Save and use for decisions at once" on the new version screen does steps 2 and 3 together; "Save and try it" saves and opens the trial screen with the new version chosen.

The five screens

ScreenAddressWhat it shows and does
Versions (list)/contexa/admin/prompt-quality/versionsThree cards: "Used for decisions now" (version, how it was chosen, base, changes, who made it), "Versions" (by Contexa and by our organization, hidden) and "Being tried" (canary, alongside, trial). The "New product default" notice. The table of versions (Number, Description, Made by, Base, Made, State, Actions), 20 rows a page, "Show hidden versions". Actions per row: View, Trial, Use for decisions, New version. The "Versions" tab shows how many versions there are.
A version/versions/{number}Cards for the changes against the base, "System prompt and added blocks" (the size of both, with the share of the added blocks under it), the decision time (median) of the decisions this version made (for the security decision also estimated against the base from the size difference) and their format errors. The prompt in three tabs: "System prompt" (each part with its mark, a changed part beside the base's text), "User prompt" (the standard blocks and the blocks this version adds) and "Finished prompt" (the system prompt as drawn, the answer format and the user prompt of the latest real sealed decision, below). "Decisions with this version" over the last 90 days. Actions: Trial, Download as a document, New version, Use for decisions, Hide.
New version/versions/new?base={number}The description of this version, the base (it can be changed; doing so drops what you changed), the system prompt parts (a prepared part the base put in can be taken out with "Take out in this version"), "Add a part", the parts Contexa prepared, the user prompt blocks, "Add a reference block", "Checks before saving", "Save and use for decisions at once", and the buttons Save, Save and try it, Cancel.
Trial decisions/versions/trials, one trial at /versions/trials/{id}Starting a trial, its progress and result, the recent trials, and "Results of running alongside". For the security decision only
Advanced/versions/advancedDocument folder, Import and download, Canary for some users, Run alongside, History, Emergency rollback. "Features for operators. Making a version and using it for decisions need none of them." A prompt other than the security decision has Document folder, Import and download, and History
  • The screens take ?prompt= and ?scope=. Without them they show the security decision of the whole platform (PLATFORM_GLOBAL). A "Tenant" choice appears when versions exist for two tenants or more.
  • The finished prompt's user prompt (security decision): when the latest sealed decision was drawn with this version, it is shown as sealed ("A real decision of {time}, drawn with this version."). Otherwise it is drawn again with this version from the sealed inputs, added blocks included, on the baselines kept now: "A real decision of {time}, drawn again with this version from its sealed inputs. The model was not asked." Nothing is asked, so nothing is audited. When it cannot be drawn again, the decision is shown as it was drawn, with the blocks this version adds listed beside it and the reason: "This application has no decision pipeline, so the decision is shown as it was drawn." or "The decision could not be drawn again with this version, so it is shown as it was drawn." Beside the user prompt is the state of the sealed package it comes from: "Sealed package: intact since its seal", "Sealed package: changed after its seal. This user prompt comes from the altered package." or "Sealed package: cannot be verified. This user prompt may differ from the sealed one." When the state cannot be told, the line is not shown.
  • The addresses of the earlier release screens lead to these screens: /contexa/admin/prompt-quality/releases to the list, /releases/detail?promptVersion=v2.0 to that version (else the list), /releases/compare to the trials.
  • States in the table: "Used for decisions", "Canary", "Running alongside", "Not used", "Hidden". Made by: "Provided by Contexa" ("Cannot be changed"), "Made on the screen", "Uploaded document {name}", "Document {name}" (the document folder).

Locked parts and parts you may change

A version's system prompt is made of parts drawn from top to bottom. A part with a lock is a Contexa rule: no version can change or delete it, and the new version screen keeps it folded. The parts you may change are open as text boxes: change the text, set it back with "Back to the product default", or take the part out with "Delete this part" ("Restore" brings it back). You may also add parts of your own.

#Part (key)On the screenLockDrawn when
1missionMissionLockedalways
2precedencePrecedenceLockedonly in a version where the organization changed or added a part: "When an instruction your organization wrote conflicts with a fixed rule of Contexa in this text …, follow the Contexa rule."
3evidence-readingHow to read the evidenceLockedalways
4organization-blocksBlocks your organization addedLockedin release 2026.11.18-v1.0 and the versions on it, only in a version where the organization changed or added a part: "A block your organization added to the user prompt has a header that says it is a reference written by your organization: it says how your organization works, not what happened in this request."
5more-readingMore readingmay changealways
6similar-case-readingSimilar case readingmay changealways. A version that deletes it also turns the similarity search for past records off
7similar-case-limitsSimilar case limitsmay changealways
8how-to-judgeHow to judgemay changealways
9responsesResponses and what they doLockedalways; with enforced minimum action floors its last sentence names the floor exception
10minimum-action-floorsMinimum action floors (when enforced)Lockedonly with contexa.security.zerotrust.minimum-action.mode=ENFORCE: the rules turned on, with the host's values
11decision-rulesDecision rules (prepared)Lockedonly in a version that puts it in (Parts Contexa prepared)
12verified-signal-boundaryVerified signal boundary (prepared)Lockedonly in a version that puts it in
13honestyHonestyLockedalways
14honesty-moreMore honestyLockedalways
15outputAnswer formatLockedalways
16reason-codesMeaning of the reason codesLockedalways (52 lines; 51 without VERIFIED_SIGNAL in a version on 2026.11.16-v1.0)
17citation-rulesCitation rulesLockedalways
18output-formatFormat instructionLockedonly for a model call without native structured output
  • Where an added part goes: after a part you name, from Mission to More honesty ("An added part goes no later than after More honesty; the answer format always comes last."). Parts 15–18 always stay at the end, as a model follows a format best near the end. An added part does not split a list: it follows the parts that continue the one it names.
  • Precedence: a version with a changed or added part of the organization gets the Precedence sentence after the Mission. A version that only deletes parts or puts prepared parts in does not, so the product default's prompt stays as it is. In release 2026.11.18-v1.0 and the versions on it, the same version also gets the "Blocks your organization added" sentence right after How to read the evidence.
  • User prompt: the eight standard blocks (User baseline, Session, Request, Records and comparisons, Past records (RAG), Unknown, Untrusted text, Second pass) are all locked: their titles, line names, order, fact IDs and values are the engine's, and the engine fills them for every decision. "Add a reference block" puts a block of the organization (a title and a text) after a standard block you name; an added block can be changed or deleted in a later version. A changed block stays a block the organization added: every version after draws it at the place it was added, under the same header, and counts it in the length, size and decision time estimates. A deleted block is left out. A version's content hash stays as it is.
  • How an added block is drawn: in the security decision's prompt (Layer 1, Layer 2, the retries and the replays) right after the standard block it follows, after a blank line, under the header === Title (reference written by your organization) ===. It has no fact IDs, so the model cannot cite it as a fact. A title or a line that could read as the header of a standard block is drawn in quotes.
  • Marks on a version's screen: "Locked", "As the default", "As the base", "Changed" (shown beside the base's text), "Deleted", "Added", "Prepared part put in", "Conditional".

Parts Contexa prepared

Two parts are in the product document but left out of every version until a version puts them in. On the new version screen they are under "{n} parts Contexa prepared", each with its measurement and a "Put in" button. Once in, a prepared part is locked: its text cannot be changed. A version made on that base shows it as "A prepared part the base version put in. The next version can take it out." with "Take out in this version" ("Put back" undoes it).

PartWhat it addsOn the screen
Decision rules (prepared) decision-rulesRules evaluated before the judgment: a required BLOCK boundary, a required low-risk boundary, a required covered-work boundary and an elevated-risk boundary. The user prompt also gets the engine's two conclusion lines DeviationsExplained and PolicySatisfied. The required BLOCK boundary holds both when DataConflicts names a tenant or organization conflict and when TenantMatch says the tenants differ, and in a version with this part the reason code TENANT_CONFLICT may cite the TenantMatch line too. An answer that still breaks a boundary after one corrective retry is replaced by the action the boundary names. An agent's request is drawn without the automation category."Not recommended", with: "Measured on 60 cases against v1.0: citation accuracy 77.2% → 52.2% (25 points lower), misses 40.0% → 42.2%, allowed action hits 70.0% → 68.3%, likely hypothesis 25.0% → 38.3%, answer tokens 132 → 118. On 10 control cases with a verified malicious signal, blocks 8 → 0."
Verified signal boundary (prepared) verified-signal-boundary"Verified signal boundary: when VerifiedSignal reports confirmed harmful or malicious activity, choose BLOCK unless stronger facts prove that observation invalid." The VerifiedSignal line itself is in every version's user prompt; this part only adds the boundary. The response check reads a BLOCK with that line as a block with decisive evidence even in a version without this part. The reason code VERIFIED_SIGNAL (screen name "Signal the server confirmed") cites that line, and the citation holds only when the line states a signal of the server's own verification source (2026.11.18-v1.0 and the versions on it)."Caution: one lower metric", with: "Measured on 60 cases against v1.0: misses 40.0% → 35.6%, allowed action hits 70.0% → 73.3%, citation accuracy 77.2% → 76.7% (one citation), likely hypothesis the same. On 10 control cases with a verified malicious signal, blocks 8 → 9."

The measurement

Measured on 2026-11-16 against the product default v1.0 with the default settings: the same 60 cases (outsiders, insiders, normal work and automation, 15 each) replayed once, plus 10 control cases that carry a malicious signal the server verified (the 60 cases have none). A part shows "recommended" only when no metric is below the base; a part with a lower metric shows its numbers and a warning.

Metricv1.0 defaultWith Decision rulesWith Verified signal boundary
Misses40.0%42.2%35.6%
Citation accuracy77.2%52.2%76.7%
Allowed action hits70.0%68.3%73.3%
Likely hypothesis is the answer25.0%38.3%25.0% (the same)
False alarms · decided without the model · asked again0 · 0 · 00 · 0 · 0 (the same)—
Answer tokens132118—
Blocks in the 10 control cases809

Decision rules lowers citation accuracy by 25 points and blocks none of the verified malicious signals, so it is "Not recommended". Verified signal boundary lowers one metric by 0.5 points (one citation, within the noise), so its numbers are shown with a warning. "—" is a metric not reported for that part.

Checks before saving

The same checks apply to a version saved on the screen, an uploaded document and a document of the folder. If any fails, nothing is saved and every problem is named.

Check on the screenWhat it refuses
No fixed part is touchedA locked part or a prepared part changed, a locked part deleted ("a Contexa rule cannot be changed or deleted")
Every part and place exists in the baseA part the base does not have, a place no part may go, putting in a part Contexa did not prepare
Every part has a title and a text, and no title is a standard block'sAn added part without a title, an added or changed part without a text, two parts of the same name. In the security decision, a block added to the user prompt, or titled anew, under the title of a standard block (REQUEST and the others, in any letter case, with or without words in parentheses after it): "{block}: the title "{title}" is the title of a standard block. Use another title."
Fits the model's context ({n} tokens)The finished prompt with the longest recent input and the answer does not fit (Length). The security decision only
  • A document is also refused when it cannot be read as YAML, has a field the form does not have, misses a required field, is for another prompt, is a whole-version document (kind: rendered), or names a base this server does not have ("The base version is not on this server").
  • A version that came from a document (an upload or the folder) cannot be the base of a version made on the screen: "{version} came from a document, so the screen cannot build on it. Change the document instead: it is registered again as the next version." This keeps the two ways of editing from colliding.
  • The check that refuses a standard block's title only stops a save. A version saved before the check is assembled as it was, and such a title is drawn in quotes.
  • Beside the checks the screen shows, without refusing: the tokens of the system prompt and the added blocks against the base, about how much longer or shorter decisions take, and "After saving, a trial on recent decisions is recommended before it decides."

How length affects decision time and the context

A longer prompt takes longer to decide and uses more of the model's context. The checks estimate the system prompt and refuse a version of the security decision that cannot fit.

  • Tokens: a quarter of the characters of every part the version draws, each part counted with its longest text (any condition), its heading and its lines. A prepared part not put in is not counted. The product default v1.0 is about 4,100 tokens. The blocks a version adds to the user prompt count too, as the prompt draws them: with their header lines in the security decision, under their titles in another prompt. The values the engine fills in for each decision are not counted.
  • The limit: the version's system tokens + the input + the answer tokens (the larger of contexa.security.tiered.layer1.max-output-tokens, default 4096, and layer2.max-output-tokens, default 2560) must not exceed the context of the model that decides first. The input is the longest user prompt of the latest 500 decisions with all the new version's added blocks. Each decision is measured with the version it ran: its prompt tokens less that version's system tokens and the added blocks that version drew, and the decision with the most left is the longest. The new version's added blocks all count, whatever its base. A decision whose recorded version is not found is measured with the product default. Without a recent decision, the input is the new version's added blocks. The screen, the document folder and an upload count the same way.
  • The model's context: for an Ollama model, contexa.llm.model-capabilities.ollama.max-context-length (default 32768; a value under 4096 keeps the default). When no first-layer model is known, the Ollama value is used. A model of another provider has a context only when a setting declares its context window, and no setting declares one now: its context is not known and the length is not checked ("The model's context is not known, so the length was not checked").
  • Decision time: the difference in tokens from the base, the system prompt and the added blocks, times the median decision time per input token of the latest 200 decisions, in the checks and on the version screen's decision time card (security decision). Without decisions it is not shown.

Use for decisions, rollback and hiding

  • Use for decisions moves the screen's label to the version through the release gate, and the version used before becomes "Not used". A version that was not tried is not blocked: the confirmation shows "Not tried" with "This version has not been tried. A trial before it decides is recommended." (the gate's warning TRIAL_RECOMMENDED). The gate blocks a hidden version, a move that leaves no version used for decisions, a version that does not keep the prompt injection guard of its product, and a prompt whose product declares no model, budget, token counting, cache or compaction policy; the confirmation then shows "Blocked" with the reasons and nothing changes. The label is cached for 60 seconds and the invalidation is checked every 5 seconds, so every server follows within about 5 seconds. A decision already started keeps its version.
  • Rollback is "Use for decisions" on an earlier version: "To roll back, choose "Use for decisions" on an earlier version: every server follows within about 5 seconds. A version cannot be changed once made; "New version" makes the next number."
  • Every move is recorded with who, when, what and why in the history and the audit log (category PROMPT_VERSION_CHANGED, actions PROMPT_VERSION_*).
  • Hide (on a version's screen, for a version in the state "Not used"): "Only takes it off the list. Its content stays; decision records and sealed evidence keep pointing at it." A version used for decisions, a canary or running alongside cannot be hidden; a hidden version cannot be used, tried or rolled back to. Hidden versions are listed with "Show hidden versions".

How a decision's version is chosen

When a decision starts, its version is chosen in this order and fixed on the event.

  1. The label of the screen: a canary the request falls inside, else the version used for decisions, of the request's tenant, else of the whole platform (PLATFORM_GLOBAL). The list shows it as "Chosen on the screen" (or "Canary").
  2. The setting contexa.security.tiered.prompt-bundle.active, when it names a version (v2.0; 2 and v2 read the same) that exists and is not hidden. It is read for every decision: a version that appears later is used from then on. Shown as "Chosen by the configuration". The setting is for the security decision only.
  3. The newest version provided by Contexa, shown as "Contexa default".
  • A setting that names a version that does not exist or is hidden is logged once as a warning and passed over until it exists. A setting that names an earlier bundle (such as 2026.10.24-v19.21) is logged once as a warning ("earlier bundles are gone"); the order above then runs as if the setting were empty.
  • Registering a product default never puts a label on it: a label exists only after an administrator chooses "Use for decisions", so the setting and the default work as they say.
  • The existence of a version and the newest Contexa version are read at most once a minute. When the database cannot be read, the last values read are used, and without them the product document of the build (2026.11.18-v1.0).
  • The event metadata keeps promptBundleSelection.version, .source and .contentHash. Layer 1, Layer 2, every retry and the decision side of a run alongside read the version from there, so moving the label never changes a decision already started.

A new product default

  • On the first start of an installation the newest product default of the build is registered as v1.0. An upgrade registers each newer product default as the next number, in order. The version used for decisions does not change by itself.
  • When the version in use is our organization's and stands on an older product default, the list shows "New product default": "Contexa released a new product default, {new}. The {in use} in use keeps running. To use the new rules, carry your changes onto the new base."
  • When the version in use is an older version provided by Contexa, there is nothing to carry: the notice reads "Contexa released the newer product version {new}. The {in use} in use keeps running; use {new} for decisions to run its rules." with a "Use for decisions" button beside "See what changed".
  • The security decision's product default of this build is 2026.11.18-v1.0: 2026.11.16-v1.0 with the locked part "Blocks your organization added" (Locked parts and parts you may change). The part is drawn only in a version the organization changed or added to. It also adds the reason code VERIFIED_SIGNAL (Signal the server confirmed) after THREAT_MATCH, so the product default's own prompt differs only by that code line and the use stated for the VerifiedSignal line. 2026.11.16-v1.0 is still shipped, and an installation that registered it registers 2026.11.18-v1.0 as the next number on upgrade.
  • "Carry onto the new base" opens the new version screen on the new product default with your changes on it: "{n} carried, {m} could not be". The changes carried are all those the version and the organization versions down its chain of bases made to the product default: changed parts (their latest title and text), added parts and blocks (changed since or not, with their place), prepared parts put in, and deleted parts. A change the new base cannot take is listed as "Could not be carried: {part} ({change}) — the new base does not have that part or no longer lets it change." Nothing is a version until you save it; drafts are not kept.

Trial decisions

"Before a new version decides, compare it on recent real decisions. The decisions made again are only recorded, never applied to anyone."

  1. Choose "Version to try", "Compared with" (the version in use is marked "(now)") and "Decisions to replay": latest 20, 50 or 100.
  2. "Start the trial". The latest sealed decisions (of the tenant, when one is chosen) are each decided again with both versions: "Calls the model twice per decision, behind any real decision waiting. Seals are a sample: with fewer, it uses what there is."
  3. The result shows four cards and the details.
Card · sectionMeaning
Same actionDecisions both versions answered with the same action
Format errors"Decisions whose first answer broke the answer format, or with no usable answer. A retry for a decision rule is not counted."
Decision time (mean)The mean time of a replay, for each version
Answer length (mean)The mean answer tokens, for each version
ActionsALLOW · CHALLENGE · ESCALATE · BLOCK and "No answer", for each version
Changed decisionsUp to 100 decisions the two versions answered with different actions (When · user, Target, the two actions, the reason of the version tried); each opens the decision's detail
  • Nothing is applied, learned or sealed: each answer is kept in the trial's tables. A trial calls the model, so it costs as much as twice the decisions.
  • One trial runs at a time per prompt, on a thread of its own; its model calls wait behind the decisions at the model gate. It can be cancelled ("Cancel"); a trial left unfinished by a server stop is marked failed when the server starts again.
  • From the result: "Canary for some users" and "Use {version} for decisions". The confirmation of "Use for decisions" names the latest trial of the version, or advises one.
  • Trials are for the security decision only: its sealed decisions are the inputs a trial decides again.

Canary for some users

On the advanced screen: choose the version, the "Share of users" (10, 25 or 50%), "Tenants" (empty for all, commas for several) and "Address starts or resource IDs" (for example /api/payments, empty for all), then "Start the canary".

  • "A user always falls on the same side. The other users are decided with the version in use." The side is drawn from a hash of the user (else the session, else the event).
  • A request is inside the canary when its tenant is one of the tenants given and its resource address starts with one of the values given or its resource ID equals one; an empty field covers all. Its decision records the source CANARY.
  • One version is a canary at a time; "Stop" ends it. The start and stop are in the history.

Run alongside

On the advanced screen: choose the version, the "Sample" (5 or 10%) and the "Daily limit" (1 to 10,000), then "Start". "Calls the model once more. The results are only recorded, never applied. The version that decides is not run again."

  • A sampled request is copied before its decision and analysed apart with the version run alongside after the decision. The copy is sealed as the SHADOW stage; nothing is enforced or learned.
  • The shadow runner is there wherever decisions are sealed, and runs nothing until a version runs alongside. The sample and daily limit chosen on the screen are kept on the version's registry row and shown on the screen's "Now:" line; a row without them runs contexa.security.tiered.prompt-bundle.shadow.sample-percent and .daily-call-cap (Settings). The daily limit counts the runs of the version per UTC day on each server. A request whose decision runs that same version is not run again.
  • "Results of running alongside" on the trial screen pairs each run with its request's decision over a "Period" of 1, 7, 30 or 90 days (7 by default): "Requests run alongside", "Paired with their decision", "Answered otherwise", the actions that changed, "Inspection of the sealed decisions (by version, stage and action)" with Sealed, Failed, Passed and Not inspected, and up to 50 paired requests, those answered otherwise first, each with its "Decision seal" and "Alongside seal" opening the sealed prompt's page. Runs of a version that stopped keep their results for the period.
  • One version runs alongside at a time; "Stop" ends it.

Emergency rollback and history

  • Emergency rollback (advanced screen): choose "Roll back to" and give a reason. "An emergency rollback applies at once and is finished when another administrator approves it." The administrator who rolled back cannot approve it.
  • The rollback table shows When, Versions, Who, State ("Applied", "Awaiting approval", "Approved", "Refused", "Incomplete") and Approval; a rollback awaiting approval has an "Approve" button.
  • History lists what was done to the versions of the prompt, newest first (up to 50): made, hidden, uploaded, registered from the folder, used for decisions, canary started and stopped, alongside started and stopped, rolled back in an emergency, rollback approved, trial started and cancelled, with who and the reason. "The audit log keeps the same".

Import and download

Use documents to move a version between servers or to keep it in version control.

  • Download ("Download as a document" on a version's screen, or the advanced screen): "Changes only (can be uploaded again)" writes the organization's document with its base named by number and content hash (basedOn, basedOnHash); "Whole version (to read)" writes every part as the version draws it, marked kind: rendered, and cannot be uploaded. The file is named cortex.security-decision-v2.0.yaml (-full.yaml for the whole version).
  • Upload ("Upload a version document"): the document passes the checks before saving and becomes the next number. "The base is found by its content, so the numbers may differ between servers." The base is the version with the content hash basedOnHash names, else the version numbered basedOn. A document uploaded again under the same file name with the same content is the version it already is.
  • The document format is in the appendix.

Document folder

Set contexa.prompt.versions.directory to a folder, and every server reads it at start and every minute after.

  • Every .yaml or .yml file directly in the folder (1,000,000 bytes at most) is a version document of the whole platform. A document not registered yet, or one whose text changed, is saved as the next version; the same document read again, or by another server, is the version it already is.
  • A document that cannot be saved is not registered: why is kept with the reading and logged as a warning.
  • The advanced screen shows the Folder, the Setting, "Last read" (when and how many documents), "Last registered", the documents not registered with their reasons, and "Read it now". Without the setting: "Set contexa.prompt.versions.directory to a folder to turn it on."
  • To change a version that came from the folder, change its file: it is registered again as the next number.

The seven prompts other than the security decision

Seven more AI prompts are kept as versions in the same way: the same documents, tables, resolver, assembler and screens, under their own prompt key. Choose one with "Prompt" on the list screen (?prompt= with its key). Each has a product document with its own locked and changeable parts; the first start registers the newest release as v1.0: 2026.11.18-v1.0 for policy generation, 2026.11.17-v1.0 for the others.

On the screenPrompt keyWhat uses itProduct document
Policy generationPolicyGenerationAI policy generation (POST /contexa/admin/api/ai/policies/generate, AI Mode)contexa-iam: prompt-versions/{key}/2026.11.17.yaml
Policy generation (streaming)PolicyGenerationStreamingAI policy generation, streamed (POST /contexa/admin/api/ai/policies/generate/stream)
Condition templatesConditionTemplateCondition template generation (Condition templates)
Resource namingResourceNamingNames suggested for the resources the resource registry finds
Query rewrite (behavior)BehaviorQueryTransformThe behavior search of RAG (RAG)contexa-core: prompt-versions/{key}/2026.11.17.yaml
Query rewrite (risk)RiskQueryTransformThe risk search of RAG
Query rewrite (policy)PolicyQueryTransformThe policy search of RAG

How a call gets its version

  • Every call draws the version the prompt's label points at ("Use" on the screen), else the newest version provided by Contexa (PromptVersionInUse). The setting contexa.security.tiered.prompt-bundle.active applies to the security decision only.
  • The system prompt, the user prompt and the execution record of one request are drawn with the same version (PromptVersionPin): a label moved in between does not mix two versions in one call. The record names the version and its content hash.
  • Without the console's database, or when it cannot be read, a call draws the product document of the build.

What the screens show for them

  • "Use" instead of "Use for decisions", "In use" instead of "Used for decisions", and "In use now" on the list card: "To roll back, choose "Use" on an earlier version: every server follows within about 5 seconds. A version cannot be changed once made; "New version" makes the next number."
  • The "Trial decisions" tab shows for the security decision only: its sealed decisions are the inputs a trial decides again. On the advanced screen the other prompts have Document folder, Import and download and History; Canary for some users, Run alongside and Emergency rollback are for the security decision only.
  • The finished prompt of a version's screen is drawn with a fixed example input: "This prompt keeps no record of its calls, so this is the version drawn with a fixed example input."
  • The checks before saving have no length check for these prompts: the length limit is the decision model's context with the longest recent decision input.
  • "Use" goes through the same release gate as "Use for decisions". The start checks that the product documents of all eight prompts declare their model, budget, token counting, cache and compaction policies, and the gate does not start when one is missing; a version of these prompts inherits them, so it meets none of those blockers. The prompt injection guard is checked for the security decision only. A prompt whose product the build does not ship is still blocked.

Policy generation

Policy generation has two releases: 2026.11.17-v1.0 and 2026.11.18-v1.0 (contexa-iam: prompt-versions/PolicyGeneration/2026.11.18.yaml). For a request without data, the new release draws "No IAM data or similar query patterns were provided." in the Data part instead of the word null. 2026.11.17-v1.0 and the versions made on it still draw null. An installation that registered 2026.11.17-v1.0 registers the new release as the next number on upgrade; the version in use does not change by itself. For the seven prompts other than the security decision, such as policy generation, every release the build ships is found by its own release name without the version tables, so a request that names the earlier release draws that release. Without the version tables the security decision finds only its latest product release, by the release name or the bundle name; an earlier release is read from the version tables, where the start registered it.

ListPart (key)Title in the documentOn the screenLockDrawn when
SystemroleRoleRoleLockedalways
SystemprecedencePrecedencePrecedenceLockedonly in a version where the organization changed or added a part
SystemscopeWhat to generateWhat to generatemay changealways
Systemrules-idsIdentifiersGiven identifiers onlyLockedalways
Systemrules-guidanceLeast privilege and complianceLeast privilege and compliancemay changealways
Systemrules-fieldsFields of the answerFields of the answerLockedalways
Systemrules-methodsHTTP methodsHTTP methodsmay changealways
Systemrules-permission-idsNo permission identifiersNo permission identifiersLockedalways
Systemrules-contextExisting policies and role hierarchyExisting policies and role hierarchymay changealways
Systemoutput-formatOutput formatFormat instructionLockedalways (answer format, at the end)
SystemschemaSchemaSchema exampleLockedalways (answer format, at the end)
UserrequirementsNatural language requirementsNatural language requirementsLockedalways
Useravailable-itemsAvailable itemsAvailable itemsLockedalways
UserdataDataDataLockedalways
UsergenerateAnswerAnswer requestLockedalways

Policy generation (streaming)

ListPart (key)Title in the documentOn the screenLockDrawn when
SystemroleRoleRoleLockedalways
SystemprecedencePrecedencePrecedenceLockedonly in a version where the organization changed or added a part
SystemscopeWhat to generateWhat to generatemay changealways
Systemrules-idsIdentifiersGiven identifiers onlyLockedalways
Systemrules-guidanceLeast privilege and complianceLeast privilege and compliancemay changealways
Systemrules-fieldsFields of the answerFields of the answerLockedalways
Systemrules-methodsHTTP methodsHTTP methodsmay changealways
Systemrules-permission-idsNo permission identifiersNo permission identifiersLockedalways
Systemrules-contextExisting policies and role hierarchyExisting policies and role hierarchymay changealways
SystemprotocolStreaming protocolStreaming protocolLockedalways (answer format, at the end)
Systemjson-rulesJSON output rulesJSON output rulesLockedalways (answer format, at the end)
Systemstructure-introStructure to outputStructure to outputLockedalways (answer format, at the end)
SystemschemaSchemaSchema exampleLockedalways (answer format, at the end)
UserrequestRequestRequestLockedalways
UserinstructionsExecution instructionsExecution instructionsLockedalways

Condition templates

One version holds both kinds: the three universal conditions, and a condition per method (asked one method at a time or several at once). Each call draws the parts of its kind.

ListPart (key)Title in the documentOn the screenLockDrawn when
Systemuniversal-roleRole (universal)Role (universal)may changewhen the three universal conditions are made
Systemspecific-roleRole (specific)Role (specific)may changewhen the condition of each method is made
SystemprecedencePrecedencePrecedenceLockedonly in a version where the organization changed or added a part
Systemuniversal-jsonPure JSON (universal)JSON only (universal)Lockedwhen the three universal conditions are made
Systemuniversal-conditionsUniversal conditionsUniversal conditionsLockedwhen the three universal conditions are made
Systemuniversal-notesNotes (universal)Notes (universal)Lockedwhen the three universal conditions are made
Systemuniversal-outputOutput (universal)Output (universal)Lockedwhen the three universal conditions are made
Systemspecific-jsonPure JSON (specific)JSON only (specific)Lockedwhen the condition of each method is made
Systemspecific-rulesRules (specific)Rules (specific)Lockedwhen the condition of each method is made
Systemspecific-examplesExamples (specific)Examples (specific)Lockedwhen the condition of each method is made
Systemspecific-outputOutput (specific)Output (specific)Lockedwhen the condition of each method is made
Systemoutput-formatOutput formatFormat instructionLockedalways (answer format, at the end)
Systemschema-universalSchema (universal)Schema example (universal)Lockedwhen the three universal conditions are made (answer format, at the end)
Systemschema-specificSchema (specific)Schema example (specific)Lockedwhen the condition of each method is made (answer format, at the end)
Useruniversal-requestRequest (universal)Request (universal)Lockedwhen the three universal conditions are made
Userbatch-referenceReference contextReference context (several methods)Lockedwhen several methods are asked at once with a reference context
Userbatch-requiredRequired answerRequired answer (several methods)Lockedwhen several methods are asked at once
Userbatch-importantCount of answersCount of answers (several methods)Lockedwhen several methods are asked at once
Userbatch-methodsMethod signaturesMethod signaturesLockedwhen several methods are asked at once
Userbatch-rulesGeneration rulesGeneration rules (several methods)Lockedwhen several methods are asked at once
Userbatch-notesImportant notesNotes (several methods)Lockedwhen several methods are asked at once
Userbatch-confirmConfirmationConfirmation (several methods)Lockedwhen several methods are asked at once
Usersingle-requestRequest (single)Request (one method)Lockedwhen one method is asked

Resource naming

ListPart (key)Title in the documentOn the screenLockDrawn when
SystemroleRoleRolemay changealways
SystemprecedencePrecedencePrecedenceLockedonly in a version where the organization changed or added a part
Systemjson-onlyPure JSONJSON onlyLockedalways
Systemoutput-contractOutput contractOutput contractLockedalways
Systemnaming-rulesNaming rulesNaming rulesmay changealways
Systemoutput-formatOutput formatFormat instructionLockedalways (answer format, at the end)
SystemschemaSchemaSchema exampleLockedalways (answer format, at the end)
UserreferenceReference contextReference contextLockedwhen a reference context is given
UserrequiredRequired answerRequired answerLockedwhen resources are given
UserresourcesResourcesResourcesLockedwhen resources are given
UserconfirmConfirmationConfirmationLockedwhen resources are given
Userno-resourcesNo resourcesNo resourcesLockedwhen no resource is given

Query rewrite (behavior, risk, policy)

The three query rewrites have the same parts and differ in their texts. They have no system prompt: the whole prompt is the user prompt.

ListPart (key)Title in the documentOn the screenLockDrawn when
UserprecedencePrecedencePrecedenceLockedonly in a version where the organization changed or added a part
UserpurposePurposePurposemay changealways
UserqueryOriginal queryOriginal queryLockedalways
UserguidelinesOptimization GuidelinesRewrite guidelinesmay changealways
Userreturn-onlyAnswerAnswerLockedalways

API

All under /contexa/admin/api/prompt-quality/versions, all with hasAuthority('ROLE_ADMIN'); every change is a POST covered by the console's CSRF protection. ?scope= and ?prompt= choose the tenant and the prompt (default: the whole platform and the security decision).

Method and pathWhat it does
GET (base path), ?hidden=trueThe list: the version in use, counts, what runs, a new product default, the versions
GET /{number}A version: its parts against the base, the preview, the size, its decisions
GET /{number}/export?form=diff|fullThe version as a document (default diff)
GET /draft?base=&carry=What the new version screen starts from (the base defaults to the version in use; carry moves a version's changes onto it)
POST /checkThe checks before saving of a draft
POST (base path)Save a draft as the next version (useNow also uses it for decisions)
GET /{number}/use-checkWhat the confirmation of "Use for decisions" shows: the gate's answer and the latest trial
POST /{number}/useUse for decisions, body {"reason"} (optional). 200 applied, 422 blocked
POST /{number}/hideHide
POST /importUpload a document, body {"fileName", "text"}
GET /advanced · /folder · /historyThe advanced screen, the folder's state, the history
POST /folder/rescanRead the folder now
POST /canary/start · /canary/stopCanary, body {"number", "percent", "tenants", "paths", "reason"}
POST /shadow/start · /shadow/stopRun alongside, body {"number", "samplePercent", "dailyLimit", "reason"}
GET /shadow/results?days=7Results of running alongside (1–90 days)
GET /trials · POST /trialsWhat a trial can start with, and start one, body {"candidate", "reference", "count"}
GET /trials/{id} · POST /trials/{id}/cancelA trial's result, cancel it
POST /rollback · /rollback/{executionKey}/approveEmergency rollback, body {"number", "reason"}, and its approval

A refused request answers 422 with a code (for example VERSION_HIDDEN, CANARY_PERCENT, TRIAL_RUNNING), or PROBLEMS with every problem of a document.

Settings

SettingDefaultMeaningWhen to change it
contexa.security.tiered.prompt-bundle.activenoneThe version decisions use when the screen has chosen none (v2.0 form), read for every decisionTo pin a version by configuration
contexa.prompt.versions.directorynoneThe document folder each server reads at start and every minuteTo keep versions as files
contexa.prompt.governance.enabledtrueThe screens, their API and trials, with the registry, release gate and rollback they useOff when versions are not managed on the screen; decisions then read the setting and the newest Contexa version
contexa.llm.model-capabilities.ollama.max-context-length32768The largest context an Ollama call asks for; the length check's limit for an Ollama modelWhen the Ollama server serves a larger context
contexa.security.tiered.prompt-bundle.shadow.sample-percent0The share of requests run alongside when the version's registry row sets none (0–100; 0 runs none)Rarely: the screen sets the sample
contexa.security.tiered.prompt-bundle.shadow.daily-call-cap100Runs alongside of a version per UTC day on each server, when its registry row sets noneRarely: the screen sets the daily limit

Appendix: the version document

A version document is one YAML file; one document is one version. An organization's document holds only what it changes. It is read with SnakeYAML's safe constructor: a document builds nothing but maps, lists and plain values, duplicate keys and aliases are refused, and a document holds at most 1,000,000 characters.

prompt: cortex.security-decision
kind: organization
basedOn: v1.0
basedOnHash: sha256:9c1f…              # written by a download; another server finds the base by it
title: Our decision guidelines
description: Our organization's context, and no similar case limits
system:
  - key: org-context                   # add a part
    add-after: honesty-more
    title: Our organization
    text: |
      Finance staff export the ledger in the last three working days of each month.
  - key: how-to-judge                  # change a part
    text: |
      1. Build one story of this request: ...
  - key: similar-case-limits           # delete a part
    delete: true
  - key: verified-signal-boundary      # put a prepared part in
    include: true
user:
  - key: org-reference                 # add a reference block
    add-after: REQUEST
    title: Organization reference
    text: |
      Month-end closing runs from the 26th to the last day of the month.
FieldMeaning
promptRequired. The prompt the document is for (cortex.security-decision)
kindproduct, organization or rendered. Without it, a document with release is a product document, else an organization's
basedOn · basedOnHashThe base by number and by content hash (sha256: and the hex). The hash is looked for first; one of the two is required
title · descriptionWhat the version is called and what it is for; without a title the version is called by its number
system · userThe parts of the system prompt and the blocks of the user prompt
A part: keyRequired. A key of the base changes the part; a new key with add-after adds one
A part: title · textThe title (required for an added part; a change keeps the base's title without one) and the text (required for a change or an addition)
A part: add-after · delete: true · include: trueAdd after the named part or block, delete the part, put a prepared part in. At most one of them; a deleted or included part has no title or text
  • The product document is the same form with every part: contexa-core's prompt-versions/cortex.security-decision/2026.11.18.yaml (release 2026.11.18-v1.0). The earlier 2026.11.16.yaml (2026.11.16-v1.0) is shipped beside it, unchanged. Each part has key, title, locked and its text, and may have join, heading, group, when (a condition such as minimum-action-enforce), prepared, whenText, items (the reason codes, a block's lines and their use) and effects. It also holds the corrections that ask again for an answer that broke the format or a rule. An organization's document cannot set these fields.
  • The start fails when the reason codes of the product document differ from the engine's. It fails too when another release the build ships names a reason code the engine lacks, or names them in another order. A rollback refuses a version whose reason codes are neither the engine's nor those of a release the build ships.
  • Content hash: the SHA-256 of the parts of the assembled version in their order. Two versions that draw the same prompt have the same hash.