Config-First Workflow
Verdictan uses declarative config. For most teams, policy-config.yaml is the
primary artifact. It defines routing, policy evaluation, secret references, and
tests. It also defines the runtime behavior that you verify in the product.
The working rule
Use this default structure:
- If a change changes runtime AI behavior, put it in
policy-config.yaml. - If a change stores secret material, reference it from config with
secret_key_ref.envorsecret_key_ref.store. - If a change versions, reviews, or rolls out config, use the console or CLI.
- If a change changes users, teams, SSO, tokens, budgets, or billing controls, use the related product surface. Do not put the change in runtime policy.
Recommended operating loop
Minimal loop
verdictan init
verdictan policy lint --file policy-config.yaml
verdictan policy test --json
export VERDICTAN_API_URL="https://api.verdictan.com"
export VERDICTAN_API_TOKEN="vdt_your_gateway_runtime_token"
verdictan gateway run --listen 127.0.0.1:41002 --agent docs-demo --policy-config policy-config.yaml
This loop is the core product workflow. Write the config, validate it, and run it. Use the measured behavior to make it better.
What belongs where
| Task | Primary surface | Why |
|---|---|---|
| Runtime policy behavior, routing, fallbacks, rate limits, and audit settings | policy-config.yaml | This is the source of truth for request-time behavior |
| Provider credentials for local development | Environment variables referenced by secret_key_ref.env | Keeps credentials out of YAML |
| Provider credentials for centrally managed runtimes | Stored secrets referenced by secret_key_ref.store | Keeps the same config portable across environments |
| Version history, review, rollout, and rollback | Configurations in the console or the matching CLI flow | These workflows move the same YAML safely |
| Runtime verification and investigation | Set since when you use verdictan events or GET /v1/events for request outcomes. Also use the applicable Gateways, Inbox, Trail, Usage, or capture-enabled History surface. | Each command, API, or console surface proves a different part of live behavior. History contains session content only if capture is enabled. |
| Team access, SSO, tokens, budgets, and billing | The matching settings or billing surfaces | These are other product controls, not request-time policy |
Recommended repository layout
For a single environment:
ai-governance/
├── policy-config.yaml
├── tests/
│ ├── allows-normal-request.yaml
│ ├── blocks-prompt-injection.yaml
│ └── redacts-pii.yaml
└── README.md
For multiple environments:
configs/
├── staging/policy-config.yaml
├── production/policy-config.yaml
└── regulated/policy-config.yaml
tests/
├── staging/
├── production/
└── regulated/
Declare each deployed environment. Do not use hidden inheritance or manual runtime drift.