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.
- 1New versionthe base is the version in use
- 2Change and savechecked before saving; saving makes the next number
- optionalTrialrecent sealed decisions decided again with two versions, recorded only
- 3Use for decisionsevery server follows within about 5 seconds
The three-click flow
- "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. - 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.
- "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
| Screen | Address | What it shows and does |
|---|---|---|
| Versions (list) | /contexa/admin/prompt-quality/versions | Three 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/advanced | Document 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/releasesto the list,/releases/detail?promptVersion=v2.0to that version (else the list),/releases/compareto 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 screen | Lock | Drawn when |
|---|---|---|---|---|
| 1 | mission | Mission | Locked | always |
| 2 | precedence | Precedence | Locked | only 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." |
| 3 | evidence-reading | How to read the evidence | Locked | always |
| 4 | organization-blocks | Blocks your organization added | Locked | in 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." |
| 5 | more-reading | More reading | may change | always |
| 6 | similar-case-reading | Similar case reading | may change | always. A version that deletes it also turns the similarity search for past records off |
| 7 | similar-case-limits | Similar case limits | may change | always |
| 8 | how-to-judge | How to judge | may change | always |
| 9 | responses | Responses and what they do | Locked | always; with enforced minimum action floors its last sentence names the floor exception |
| 10 | minimum-action-floors | Minimum action floors (when enforced) | Locked | only with contexa.security.zerotrust.minimum-action.mode=ENFORCE: the rules turned on, with the host's values |
| 11 | decision-rules | Decision rules (prepared) | Locked | only in a version that puts it in (Parts Contexa prepared) |
| 12 | verified-signal-boundary | Verified signal boundary (prepared) | Locked | only in a version that puts it in |
| 13 | honesty | Honesty | Locked | always |
| 14 | honesty-more | More honesty | Locked | always |
| 15 | output | Answer format | Locked | always |
| 16 | reason-codes | Meaning of the reason codes | Locked | always (52 lines; 51 without VERIFIED_SIGNAL in a version on 2026.11.16-v1.0) |
| 17 | citation-rules | Citation rules | Locked | always |
| 18 | output-format | Format instruction | Locked | only 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.0and 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).
| Part | What it adds | On the screen |
|---|---|---|
Decision rules (prepared) decision-rules | Rules 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.
| Metric | v1.0 default | With Decision rules | With Verified signal boundary |
|---|---|---|---|
| Misses | 40.0% | 42.2% | 35.6% |
| Citation accuracy | 77.2% | 52.2% | 76.7% |
| Allowed action hits | 70.0% | 68.3% | 73.3% |
| Likely hypothesis is the answer | 25.0% | 38.3% | 25.0% (the same) |
| False alarms · decided without the model · asked again | 0 · 0 · 0 | 0 · 0 · 0 (the same) | — |
| Answer tokens | 132 | 118 | — |
| Blocks in the 10 control cases | 8 | 0 | 9 |
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 screen | What it refuses |
|---|---|
| No fixed part is touched | A 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 base | A 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's | An 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, andlayer2.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, actionsPROMPT_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.
- 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"). - The setting
contexa.security.tiered.prompt-bundle.active, when it names a version (v2.0;2andv2read 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. - 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,.sourceand.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.0with 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 codeVERIFIED_SIGNAL(Signal the server confirmed) afterTHREAT_MATCH, so the product default's own prompt differs only by that code line and the use stated for theVerifiedSignalline.2026.11.16-v1.0is still shipped, and an installation that registered it registers2026.11.18-v1.0as 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."
- Choose "Version to try", "Compared with" (the version in use is marked "(now)") and "Decisions to replay": latest 20, 50 or 100.
- "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."
- The result shows four cards and the details.
| Card · section | Meaning |
|---|---|
| Same action | Decisions 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 |
| Actions | ALLOW · CHALLENGE · ESCALATE · BLOCK and "No answer", for each version |
| Changed decisions | Up 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-percentand.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, markedkind: rendered, and cannot be uploaded. The file is namedcortex.security-decision-v2.0.yaml(-full.yamlfor 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
basedOnHashnames, else the version numberedbasedOn. 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
.yamlor.ymlfile 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 screen | Prompt key | What uses it | Product document |
|---|---|---|---|
| Policy generation | PolicyGeneration | AI policy generation (POST /contexa/admin/api/ai/policies/generate, AI Mode) | contexa-iam: prompt-versions/{key}/2026.11.17.yaml |
| Policy generation (streaming) | PolicyGenerationStreaming | AI policy generation, streamed (POST /contexa/admin/api/ai/policies/generate/stream) | |
| Condition templates | ConditionTemplate | Condition template generation (Condition templates) | |
| Resource naming | ResourceNaming | Names suggested for the resources the resource registry finds | |
| Query rewrite (behavior) | BehaviorQueryTransform | The behavior search of RAG (RAG) | contexa-core: prompt-versions/{key}/2026.11.17.yaml |
| Query rewrite (risk) | RiskQueryTransform | The risk search of RAG | |
| Query rewrite (policy) | PolicyQueryTransform | The 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 settingcontexa.security.tiered.prompt-bundle.activeapplies 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.
| List | Part (key) | Title in the document | On the screen | Lock | Drawn when |
|---|---|---|---|---|---|
| System | role | Role | Role | Locked | always |
| System | precedence | Precedence | Precedence | Locked | only in a version where the organization changed or added a part |
| System | scope | What to generate | What to generate | may change | always |
| System | rules-ids | Identifiers | Given identifiers only | Locked | always |
| System | rules-guidance | Least privilege and compliance | Least privilege and compliance | may change | always |
| System | rules-fields | Fields of the answer | Fields of the answer | Locked | always |
| System | rules-methods | HTTP methods | HTTP methods | may change | always |
| System | rules-permission-ids | No permission identifiers | No permission identifiers | Locked | always |
| System | rules-context | Existing policies and role hierarchy | Existing policies and role hierarchy | may change | always |
| System | output-format | Output format | Format instruction | Locked | always (answer format, at the end) |
| System | schema | Schema | Schema example | Locked | always (answer format, at the end) |
| User | requirements | Natural language requirements | Natural language requirements | Locked | always |
| User | available-items | Available items | Available items | Locked | always |
| User | data | Data | Data | Locked | always |
| User | generate | Answer | Answer request | Locked | always |
Policy generation (streaming)
| List | Part (key) | Title in the document | On the screen | Lock | Drawn when |
|---|---|---|---|---|---|
| System | role | Role | Role | Locked | always |
| System | precedence | Precedence | Precedence | Locked | only in a version where the organization changed or added a part |
| System | scope | What to generate | What to generate | may change | always |
| System | rules-ids | Identifiers | Given identifiers only | Locked | always |
| System | rules-guidance | Least privilege and compliance | Least privilege and compliance | may change | always |
| System | rules-fields | Fields of the answer | Fields of the answer | Locked | always |
| System | rules-methods | HTTP methods | HTTP methods | may change | always |
| System | rules-permission-ids | No permission identifiers | No permission identifiers | Locked | always |
| System | rules-context | Existing policies and role hierarchy | Existing policies and role hierarchy | may change | always |
| System | protocol | Streaming protocol | Streaming protocol | Locked | always (answer format, at the end) |
| System | json-rules | JSON output rules | JSON output rules | Locked | always (answer format, at the end) |
| System | structure-intro | Structure to output | Structure to output | Locked | always (answer format, at the end) |
| System | schema | Schema | Schema example | Locked | always (answer format, at the end) |
| User | request | Request | Request | Locked | always |
| User | instructions | Execution instructions | Execution instructions | Locked | always |
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.
| List | Part (key) | Title in the document | On the screen | Lock | Drawn when |
|---|---|---|---|---|---|
| System | universal-role | Role (universal) | Role (universal) | may change | when the three universal conditions are made |
| System | specific-role | Role (specific) | Role (specific) | may change | when the condition of each method is made |
| System | precedence | Precedence | Precedence | Locked | only in a version where the organization changed or added a part |
| System | universal-json | Pure JSON (universal) | JSON only (universal) | Locked | when the three universal conditions are made |
| System | universal-conditions | Universal conditions | Universal conditions | Locked | when the three universal conditions are made |
| System | universal-notes | Notes (universal) | Notes (universal) | Locked | when the three universal conditions are made |
| System | universal-output | Output (universal) | Output (universal) | Locked | when the three universal conditions are made |
| System | specific-json | Pure JSON (specific) | JSON only (specific) | Locked | when the condition of each method is made |
| System | specific-rules | Rules (specific) | Rules (specific) | Locked | when the condition of each method is made |
| System | specific-examples | Examples (specific) | Examples (specific) | Locked | when the condition of each method is made |
| System | specific-output | Output (specific) | Output (specific) | Locked | when the condition of each method is made |
| System | output-format | Output format | Format instruction | Locked | always (answer format, at the end) |
| System | schema-universal | Schema (universal) | Schema example (universal) | Locked | when the three universal conditions are made (answer format, at the end) |
| System | schema-specific | Schema (specific) | Schema example (specific) | Locked | when the condition of each method is made (answer format, at the end) |
| User | universal-request | Request (universal) | Request (universal) | Locked | when the three universal conditions are made |
| User | batch-reference | Reference context | Reference context (several methods) | Locked | when several methods are asked at once with a reference context |
| User | batch-required | Required answer | Required answer (several methods) | Locked | when several methods are asked at once |
| User | batch-important | Count of answers | Count of answers (several methods) | Locked | when several methods are asked at once |
| User | batch-methods | Method signatures | Method signatures | Locked | when several methods are asked at once |
| User | batch-rules | Generation rules | Generation rules (several methods) | Locked | when several methods are asked at once |
| User | batch-notes | Important notes | Notes (several methods) | Locked | when several methods are asked at once |
| User | batch-confirm | Confirmation | Confirmation (several methods) | Locked | when several methods are asked at once |
| User | single-request | Request (single) | Request (one method) | Locked | when one method is asked |
Resource naming
| List | Part (key) | Title in the document | On the screen | Lock | Drawn when |
|---|---|---|---|---|---|
| System | role | Role | Role | may change | always |
| System | precedence | Precedence | Precedence | Locked | only in a version where the organization changed or added a part |
| System | json-only | Pure JSON | JSON only | Locked | always |
| System | output-contract | Output contract | Output contract | Locked | always |
| System | naming-rules | Naming rules | Naming rules | may change | always |
| System | output-format | Output format | Format instruction | Locked | always (answer format, at the end) |
| System | schema | Schema | Schema example | Locked | always (answer format, at the end) |
| User | reference | Reference context | Reference context | Locked | when a reference context is given |
| User | required | Required answer | Required answer | Locked | when resources are given |
| User | resources | Resources | Resources | Locked | when resources are given |
| User | confirm | Confirmation | Confirmation | Locked | when resources are given |
| User | no-resources | No resources | No resources | Locked | when 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.
| List | Part (key) | Title in the document | On the screen | Lock | Drawn when |
|---|---|---|---|---|---|
| User | precedence | Precedence | Precedence | Locked | only in a version where the organization changed or added a part |
| User | purpose | Purpose | Purpose | may change | always |
| User | query | Original query | Original query | Locked | always |
| User | guidelines | Optimization Guidelines | Rewrite guidelines | may change | always |
| User | return-only | Answer | Answer | Locked | always |
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 path | What it does |
|---|---|
GET (base path), ?hidden=true | The 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|full | The 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 /check | The 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-check | What the confirmation of "Use for decisions" shows: the gate's answer and the latest trial |
POST /{number}/use | Use for decisions, body {"reason"} (optional). 200 applied, 422 blocked |
POST /{number}/hide | Hide |
POST /import | Upload a document, body {"fileName", "text"} |
GET /advanced · /folder · /history | The advanced screen, the folder's state, the history |
POST /folder/rescan | Read the folder now |
POST /canary/start · /canary/stop | Canary, body {"number", "percent", "tenants", "paths", "reason"} |
POST /shadow/start · /shadow/stop | Run alongside, body {"number", "samplePercent", "dailyLimit", "reason"} |
GET /shadow/results?days=7 | Results of running alongside (1–90 days) |
GET /trials · POST /trials | What a trial can start with, and start one, body {"candidate", "reference", "count"} |
GET /trials/{id} · POST /trials/{id}/cancel | A trial's result, cancel it |
POST /rollback · /rollback/{executionKey}/approve | Emergency 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
| Setting | Default | Meaning | When to change it |
|---|---|---|---|
contexa.security.tiered.prompt-bundle.active | none | The version decisions use when the screen has chosen none (v2.0 form), read for every decision | To pin a version by configuration |
contexa.prompt.versions.directory | none | The document folder each server reads at start and every minute | To keep versions as files |
contexa.prompt.governance.enabled | true | The screens, their API and trials, with the registry, release gate and rollback they use | Off 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-length | 32768 | The largest context an Ollama call asks for; the length check's limit for an Ollama model | When the Ollama server serves a larger context |
contexa.security.tiered.prompt-bundle.shadow.sample-percent | 0 | The 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-cap | 100 | Runs alongside of a version per UTC day on each server, when its registry row sets none | Rarely: 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.
| Field | Meaning |
|---|---|
prompt | Required. The prompt the document is for (cortex.security-decision) |
kind | product, organization or rendered. Without it, a document with release is a product document, else an organization's |
basedOn · basedOnHash | The base by number and by content hash (sha256: and the hex). The hash is looked for first; one of the two is required |
title · description | What the version is called and what it is for; without a title the version is called by its number |
system · user | The parts of the system prompt and the blocks of the user prompt |
A part: key | Required. A key of the base changes the part; a new key with add-after adds one |
A part: title · text | The 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: true | Add 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'sprompt-versions/cortex.security-decision/2026.11.18.yaml(release2026.11.18-v1.0). The earlier2026.11.16.yaml(2026.11.16-v1.0) is shipped beside it, unchanged. Each part haskey,title,lockedand its text, and may havejoin,heading,group,when(a condition such asminimum-action-enforce),prepared,whenText,items(the reason codes, a block's lines and their use) andeffects. It also holds thecorrectionsthat 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.