Discoverable decisions tutorial

This tutorial moves from systems that merely execute to systems that can explain. Each lab exposes more of the proposal, validation, revision, execution, and trace lifecycle.

By Enrico Piovesan Updated June 22, 2026

Tutorial route

Keep the decision path in front of the reader so the queryable proof is visible while the tutorial is still on screen.

Open source folder All UMA examples Previous: Evolution Without Fragmentation Next: Portable MCP Runtime

What you will learn

why discoverability is different from execution
how edge proposals and cloud authority cooperate
how trace artifacts make final decisions auditable

Prerequisites

Rust 1.76 or newer
Node.js 20 or newer
a checkout of the repository

Full tutorial

Enter the example
```
cd chapter-12-discoverable-decisions
```
List the decision labs
```
./scripts/list_labs.sh
```

Validate the first decision scenario

./scripts/validate_decisions.sh lab1-capability-projection

Run capability projection

./scripts/run_decision_demo.sh lab1-capability-projection

Compare the edge proposal step

./scripts/diff_decisions.sh lab1-capability-projection lab2-edge-proposal

Run authority feedback

./scripts/run_decision_demo.sh lab3-authority-feedback

Run queryable trace

./scripts/run_decision_demo.sh lab6-queryable-trace

Run the full smoke path
```
./scripts/smoke_discoverability_labs.sh
```

What to inspect

After each command, look for these proof points. They are the signals that connect the code example back to the UMA architecture claim.

Verdict
proposal_hidden
authority_gap
Discoverable Surfaces
Trace

Acceptance check

The chapter-level validation path is:

./scripts/smoke_discoverability_labs.sh

Return to the repository root for the final acceptance gate:

cd ..
./scripts/smoke_reader_paths.sh

Where to go next

Chapter 13 applies the model to a portable MCP runtime.

Open source folder All UMA examples Read Chapter 13: Agents and MCP → Previous: Evolution Without Fragmentation Next: Portable MCP Runtime