v1.0.3

Walkthrough CLI

Versioned, public-API guided journeys from the terminal. Learn AI Governance Platform while exercising the same control plane used by Studio and external producers.

Purpose

ai-governance walkthrough is intentionally a guided product experience, not a second control plane. ai-governance walkthrough governed-replay records observed prompt and model evidence, selects an immutable dataset and replayable execution, inspects existing evaluation and decision evidence, and prepares a replay.

Each walkthrough persists a checkpoint manifest and uses only versioned REST endpoints available to Studio and external producers. The colourful quest presentation is opt-in; JSON, CI, and ordinary terminal output remain stable.

Available Walkthroughs

List the journeys installed with your version of AI Governance Platform:

bash

uv run ai-governance walkthrough list

World 1-1 · Governed Replay

Observe runtime evidence, select immutable inputs, prepare a replay, and inspect lineage.

World 1-2 · Evaluation Pipeline

Select an evaluated execution, inspect immutable history, and read evaluator metrics.

World 1-3 · Policy Gate

Inspect the policy authoring schema, a tenant policy, and its active rules.

World 2-1 · Decision Detective

Trace a persisted governance decision, its audit evidence, and deterministic explanation.

World 2-2 · Experiment Arena

Inspect experiment candidates and evidence-backed outcome insights without changing an experiment.

Run a walkthrough

From a repository clone, start the supported local stack and run the walkthrough that fits what you want to inspect. The local seed provides the evidence used by the journeys.

bash

./servers.sh

# The complete write-capable journey: prepares, but does not submit, a replay.
uv run ai-governance walkthrough governed-replay

# Read-only inspection journeys.
uv run ai-governance walkthrough evaluation-pipeline
uv run ai-governance walkthrough policy-gate
uv run ai-governance walkthrough decision-detective
uv run ai-governance walkthrough experiment-arena

The commands print actual resource IDs and Studio deep links. For the full replay narrative and expected outputs, use the Governed Replay Walkthrough Tutorial.

Interactive quest mode

Add --interactive --theme retro for an original retro-platform quest presentation with roomy progress, a mission scorecard, and learning milestones. It uses no Nintendo artwork, audio, sprites, or branding.

bash

uv run ai-governance walkthrough governed-replay --interactive --theme retro

# Keep the guided layout but disable colour for your terminal or accessibility needs.
uv run ai-governance walkthrough decision-detective --interactive --theme retro --no-color

Interactive mode asks only when a choice is optional: choose a replayable source execution, submit a prepared replay, open or copy a Studio URL, or clean up aged local checkpoints. At a Studio link, press O to open it, C to copy it, or N to continue. The read-only quests do not create, submit, or modify governed resources.

Authentication

No manual bearer-token export is required. In Keycloak mode, the CLI exchanges AI_GOVERNANCE_OAUTH_* client credentials for a short-lived token in memory. ./servers.sh generates local OAuth configuration in .env.oauth.generated; it is ignored by Git and never printed by the CLI.

A pre-obtained bearer token is supported only through an explicit --token argument. The walkthrough intentionally ignores a shell AI_GOVERNANCE_TOKEN export so stale credentials cannot silently override its service identity.

Automation and Manifests

Use --non-interactive to make a run explicit in CI and --output-json (or --json) to emit the complete run manifest on stdout. JSON cannot be combined with interactive mode.

bash

uv run ai-governance walkthrough governed-replay \
  --non-interactive \
  --output-json \
  --manifest artifacts/governed-replay-manifest.json

The JSON manifest is checkpointed after every successful step. It records selected and created IDs, outcome, API version, and Studio URLs; it is suitable for CI smoke tests and release validation. The detailed tutorial covers restart behavior and safe local manifest cleanup.

Checkpoints and Cleanup

By default, manifests are written to .ai-governance/walkthroughs/. Cleanup only touches those local files; it never removes replay, evaluation, policy, or decision records from AI Governance Platform.

bash

# Preview aged local checkpoints.
uv run ai-governance walkthrough cleanup --older-than-days 14

# Delete only the listed local checkpoint files.
uv run ai-governance walkthrough cleanup --older-than-days 14 --apply

Product Boundary

The CLI never calls repositories directly, inspects SQLite, or contains governance logic. It also never claims a completed replay, evaluation, or drift result before the standard worker lifecycle produces one. Ontology projection may be pending; the manifest records that state and links to the graph rather than fabricating lineage.

The scenario is versioned with its fixtures in examples/governed-replay/scenario.yaml. Read the Governed Replay Walkthrough Tutorial for the worker lifecycle and the Observed Assets Guide for producer integration.