Jev Quickstart

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Jev offloads bounded decisions — a yes/no gate, a pick from N known options, or a 1–N severity or priority score — so the LLM does not spend reasoning on questions with a fixed answer shape. the agent-owned decision operation sends one question plus optional context and returns a typed answer with confidence, or a fallback that means "decide it yourself with the LLM".

Savings vary by workload: offloading helps when you ask many small bounded questions and decide normally on fallback.

1. Install

Use AIWG to complete this documented outcome: 1. Install
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The `decision-engine` addon is opt-in and excluded from bulk installs (the agent-owned use operation, framework deploys). New to AIWG? Start with Install, connect and verify, then come back here to add the addon.

2. Store the token

the agent-owned decision operation counts as the explicit opt-in that enables `ask`. It stores the credential and records `"enabled": true` in the credential file. Pipe the token through stdin so it never appears in shell history:

printf '%s' "$TOKEN" | the agent-owned decision operation setup jev the token-stdin option the verify option

Token lookup order when running `ask`:

1. env `JEV_API_KEY`, 2. env `AIWG_DECISION_JEV_API_KEY`, 3. the user credential file `${XDG_CONFIG_HOME:-~/.config}/aiwg/credentials/jev.json` (`{"token":"...","region":"us","endpoint"?:...}`, mode 0600, parent dir 0700 — a group- or world-readable file is refused).

`setup` prints `aiwg-decision-jev-setup/v1` JSON: `{ configured, credentialSource: "file"|"env", region, verified?, model?, next: [...] }`. The token is never printed, logged, or written to results or project files. Region defaults to `"us"`; change it with the region option. The endpoint is the official `https://api.typesafe.ai/v1/systemone` unless the endpoint option names a custom origin that passes the adapter allowlist rules.

3. Verify

The the verify option flag in step 2 makes one tiny live yes/no call and reports status, model, and usage. Without the token-stdin option, `setup` uses the env token if one is present and otherwise exits 2 with instructions.

4. Ask

Use AIWG to complete this documented outcome: The the verify option flag in step 2 makes one tiny live yes/no call and reports status, model, and usage. Without the token-stdin option, setup uses the env token if one is present and otherwise exits 2 with instructions.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Use AIWG to complete this documented outcome: 4. Ask
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

the choices option takes 2–255 ids matching `[A-Za-z0-9_.-]{1,64}` with no duplicates. Write each as `id=what it means` (no commas in the description): Jev sees only the description, so bare ids produce more low-confidence fallbacks. `the scale option lo-hi` allows at most 10 levels and answers the most likely level. Context is untrusted data capped at 32 KiB — larger context exits 2 with `reason: "context-too-large"`. Nothing is written and nothing is executed.

Without the json option, output is one line: `answer (confidence 0.93, jev-1.13.0)` or `FALLBACK to LLM: <reason>`.

5. How agents use it

The `decision-offload` rule (with the `decision-offload` skill) says: before spending reasoning on a bounded decision, call the agent-owned decision operation. Use the answer when `status` is `answered`; on `fallback`, decide normally. Never use it for open-ended generation, code writing, multi-step plans, or anything that authorizes destructive or outward actions. Jev output is advisory data; it is never authorization.

6. Fallback semantics

`fallback: "llm"` (still exit 0) happens when Jev is not configured or not enabled (`reason: "not-configured"`), the token is missing, Jev abstained or errored or was unavailable, the call timed out, or confidence fell below the threshold option (default 0.8; yes-no confidence = max(p, 1-p)). Exit 2 is only for usage errors.

7. Privacy

The question and context are sent to Jev. Never send secrets: no tokens, passwords, private keys, or credentials in the question option or the context option.

8. Disabling

Use AIWG to complete this documented outcome: 8. Disabling
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

`AIWG_DECISION_ENABLED=1` also enables `ask`; `AIWG_DECISION_ENABLED=0` force-disables it.

9. Ledger, history and stats

Every completed `ask` call (CLI and MCP) appends exactly one record to a decision ledger — `.aiwg/decision/ledger.jsonl` under the project AIWG artifact root, resolved the same way as the agent-owned artifacts operation. This covers `fallback` and `not-configured` outcomes, not just `answered` ones. CLI/MCP usage errors — a bad flag, an oversized context, an invalid the session option/the caller option — never reach a completed call and are never recorded; those are rejected with exit 2 (CLI) before any Jev call.

Trust boundary. The ledger defends against accidental hazards — a stray symlink, a pre-planted hard link, loose permissions, a previous crash's partial write — under the assumption that the artifact root is owned and written by the same local user running `aiwg`. It is not a defense against a hostile process already running as that user: there is no cross-process lock, and an existing file or directory that fails a safety check is never modified (no chmod, no truncation) — recording is skipped and reported once. The ledger also has no built-in retention: it grows without bound, and the operator may truncate or delete it at any time; `history`/`stats` tolerate a missing file (empty result) rather than erroring.

A ledger write failure, a slow/unavailable attribution lookup, or anything else inside the recording step never changes the `ask` result or exit code: recording is bounded by a short deadline (250 ms by default) and prints at most one warning to stderr. On timeout, that warning says exactly "completion unknown" — the in-flight attempt is not and cannot be cancelled (Node has no way to abort an in-flight filesystem call), so the record may or may not eventually land; no later stage of that same attempt starts once the deadline fires, so a slow attribution lookup cannot itself delay the write past the deadline.

Records carry the resolved provider (the provider option to override; otherwise the same runtime detection the agent-owned steward operation uses, degrading to `unknown` if detection itself fails), a session id (the session option, else `AIWG_SESSION_ID`, else the literal `unknown`), the decision kind and choice ids (at most 10 recorded, regardless of how many the `ask` call itself allowed — `choiceCount` and `choiceIdsTruncated` say how many there really were), `answerIndex` (the selected option's position in the original list — this survives redaction even when two different secret-shaped choice ids redact to the same display marker), SHA-256 digests of the question and context, the outcome, model, Jev usage, latency, and an estimated-LLM-tokens-avoided figure with the method that produced it (the D06 context-token estimator plus a named per-kind reasoning allowance for answered calls; the negative of the Jev usage spent for a fallback that actually called Jev; zero for `not-configured`, which never calls Jev).

An optional `the caller option <tag>` names the decision point for later attribution, for example `the caller option "address-issues:worker-pick"`. the session option and the caller option must match `^[A-Za-z0-9_.:/@-]{1,96}$`; the CLI rejects a value outside that shape with exit 2, and the MCP tool silently drops one instead (there is no CLI exit code to report through MCP).

Every persisted field is redacted, not only the two opt-in text fields: provider, session id, project root, caller, choice ids, model and a string answer all pass through the same governance redaction the agent-owned activity-log operation uses before being written, and each is capped to a bounded length. Question and context text are never written to the ledger at all unless the record-text option is passed, and even then the redacted text is truncated to a documented cap (marked `textTruncated: true` when it is). A whole record is capped below the conservative single-write atomicity boundary most platforms honor for `PIPE_BUF` (4096 bytes), making a single, non-interleaved write the overwhelmingly likely outcome — not a guarantee: there is no cross-process append lock, so two concurrent writers can in rare cases interleave and produce one malformed line, which `history`/`stats` detect and skip (counted), never silently merge into a neighboring record.

`questionDigest`/`contextDigest` are plain, deterministic SHA-256 over the raw text. That is not a confidentiality guarantee: a short or guessable question (or context) can still be identified by hashing candidate strings and comparing digests. Treat the digest as a correlation key, not a secret.

Use AIWG to complete this documented outcome: questionDigest/contextDigest are plain, deterministic SHA-256 over the raw text. That is not a confidentiality guarantee: a short or guessable question (or context) can still be identified by hashing candidate strings and comparing digests.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

`history` and `stats` read the ledger offline — no network, no Jev call. `history` supports the since option, the provider option, the session option, the kind option, the status option and the json option; the since option is strict ISO-8601 — a bare date or an offsetless timestamp is interpreted as UTC, and an invalid calendar date (e.g. `2026-02-30`) is rejected with exit 2, including when an explicit offset is present (the local calendar/time components are validated before the offset is applied). `stats` supports the same filters as `history`, plus `the group-by option provider|session|kind|caller`: a record with no the caller option tag groups under a distinct `null` key, never conflated with a caller literally named `unattributed`. It reports answered/fallback counts, a fallback rate (and a per-reason rate) as a fraction of the group's total calls, the confidence distribution, Jev tokens spent, the estimated LLM tokens avoided, and net savings (the avoided-tokens total minus Jev usage actually spent on answered calls only — a fallback's own estimate already nets out its own Jev cost, so it is not subtracted a second time). Both commands report how many stored lines failed validation as `skipped`. Retention (archiving or pruning old entries) is a documented follow-up, not implemented yet — delete or truncate `.aiwg/decision/ledger.jsonl` yourself if it grows too large; both commands tolerate a missing file.

10. Troubleshooting

Symptom	Cause / fix
`FALLBACK to LLM: not-configured`	Run the agent-owned decision operation (or set `AIWG_DECISION_ENABLED=1` with a token in env).
`setup` exits 2 without the token-stdin option	No env token found; it prints instructions — pipe the token via the token-stdin option.
`reason: "context-too-large"` (exit 2)	Trim context to 32 KiB or less.
Credential file refused	Fix permissions: parent dir 0700, file 0600; group/world-readable files are refused.
Frequent timeouts	Raise the timeout-ms option (default 15000); timeouts fall back to the LLM.
Low-confidence fallbacks	Give each choice a description (`id=meaning`) and add context. Lower the threshold option only if wrong answers are cheap. Fallback is the normal path, not an error.

See also the CLI/MCP driver guide, the transport contract, and the decision-engine operator guide.