OpenUdon

OpenUdon is the public UWS workflow authoring, review, package, and executor-handoff tool. It can run directly or under optional external orchestration, and it hands approved packages to a trusted executor boundary such as the udon runtime.

iCoT UI is OpenUdon's primary interactive authoring entry point across API, authenticated-browser, and runtime-handoff sources; terminal commands remain expert and automation fallbacks. One distributed icot executable handles the operator flow, but it privately stabilizes and re-executes itself as an isolated Browsertools worker process for Playwright acquisition. Browsertools owns that Chromium context, browser safety policy, profile synthesis, and the shared validation library; the iCoT engine and HTTP server never initialize Playwright in-process. Production runtime replay belongs to Udon and Browserdriver. See Browsertools' canonical OpenUdon integration reference.

It owns project templates, optional workflow orchestration policy, example artifacts, deterministic validation, review handoff evidence, package digests, credential policy, and trusted-runner glue. Public workflow semantics belong in github.com/OpenUdon/uws; API/event source metadata discovery, import, materialization, search, and indexing belong in github.com/OpenUdon/apitools; desired-state conversion, planning, reconciliation, and audit behavior belong in github.com/OpenUdon/ramen. OpenUdon uses shared github.com/OpenUdon/evidence/... primitives for neutral digest, artifact, diagnostic, redaction, and approval evidence where the records are product-independent. Current shared use routes review/package hashing through evidence/digest and package artifact path-safety through evidence/artifact with OpenUdon labels for stable CLI wording. OpenUdon-specific approval JSON, review handoff, package digest policy, run evidence, tier rules, and trusted-runner behavior remain OpenUdon-owned; the tier-plus-digest approval model does not map onto evidence/approval. OpenUdon can stage OpenAPI, Google Discovery, AWS Smithy, AsyncAPI, GraphQL, OpenRPC, gRPC/protobuf, and OData source documents as first-class UWS source descriptions when the trusted executor supports them.

An operator may also add reviewable content-provenance declarations to workflows/intent.hcl. OpenUdon emits UWS 1.9.1 only when that optional contentTrust registry is present; otherwise existing packages keep their previous UWS selection, including UWS 1.9.0 for browser 1.7. These declarations are metadata for advisory analysis and human/AI review, not execution approval or runtime policy. During assessment, declared packages are analyzed with the UWS analyzer and contained browser profiles use the Browsertools resolver. Findings appear as non-failing warnings in quality and review evidence; they do not alter ordinary validation, trusted-runner authorization, or execution. See the intent content-trust contract.

v0.2 Security Migration

The source tree implements the unreleased v0.2 compatibility boundary for the deterministic package lifecycle (validate, build, promote, and assess), digest-bound approval and trusted handoff (approval-template and run), run-evidence verification/archive/signatures, and the v2 handoff artifacts. Existing v1 run configs and handoffs must be rebuilt before execution; v1 run evidence is read-only inspectable and cannot be archived as v2 evidence. iCoT, LLM/provider behavior, eval/catalog/smoke helpers, and exact generated prose remain experimental before v1. OpenUdon does not yet expose a supported Go-library API.

See SUPPORT.md and the v0.2 compatibility contract for the exact boundary.

The most recent published binaries remain v0.1.0 until v0.2 release evidence is complete; this change does not publish or tag v0.2.0.

Quick Start

Install the main CLI:

go install github.com/OpenUdon/openudon/cmd/openudon@v0.1.0
openudon version --json

Optional companion tools:

go install github.com/OpenUdon/openudon/cmd/icot@v0.1.0
go install github.com/OpenUdon/openudon/cmd/udon-runner@v0.1.0

Linux, macOS, and Windows archives for amd64 and arm64 are attached to the GitHub v0.1.0 release. Every archive contains openudon, icot, and udon-runner; verify it against the published SHA256SUMS file.

From a source checkout, the credential-free release path authors a local function-only project, builds and assesses it, then stages an approved sandbox dry run without invoking an executor:

DEMO_ROOT=.openudon-run/v0.1.0-quick-start
icot \
--from-example ./examples/eval/runtime-only-render \
--example "$DEMO_ROOT/package" \
--no-llm \
--yes
openudon build --example "$DEMO_ROOT/package"
openudon assess --example "$DEMO_ROOT/package"
openudon approval-template \
--example "$DEMO_ROOT/package" \
--state approved_for_sandbox \
--reviewer "Local Reviewer" \
>"$DEMO_ROOT/approval.json"
openudon run \
--example "$DEMO_ROOT/package" \
--tier sandbox \
--approval "$DEMO_ROOT/approval.json" \
--workdir "$DEMO_ROOT/run" \
--dry-run

Useful checks:

go test ./...
go vet ./...
go run ./cmd/openudon check
go run ./cmd/openudon check-apitools-boundary
go run ./cmd/openudon validate ./examples/uws-validation
make check
make release-check
make browser-integration-check
make browser-scenario-loopback
make browser-scenario-journey
make eval-seed-build
make release-saas-check
git diff --check

Execute through openudon run and the portable run-config handoff. Configure the final executor with OPENUDON_EXECUTOR as either an absolute binary path or docker://<image>. Reviewed browser workflows additionally use --browser-driver /absolute/path/browserdriver; OpenUdon derives the protocol, symbolic credential/session environment names, and exact browser approvals from one immutable, manifest-digest-validated package byte snapshot and binds them into the v2 config and evidence. Staging rehashes the current files and rejects later drift. For a Docker executor, that host executable is mounted read-only at /openudon/browser-driver and Udon receives the container path; the image does not need to contain the driver at the host path. Docker forwards only declared credentials and sessions with -e; approved driver environment names resolve from container-owned defaults and host desktop/socket requirements are rejected.

Layout

• cmd/openudon: local CLI for checks, synthesis, assessment, eval, readiness, approval templates, and trusted execution.
• cmd/icot: guided authoring CLI for project.md and workflows/intent.hcl.
• internal/: reusable OpenUdon implementation.
• examples/: committed examples and eval corpus.
• templates/project.md: starter project brief.
• docs/: detailed architecture, safety, operator, XRD, and release notes.

Authoring details:

• Agentic SaaS authoring describes the M15 path for common SaaS workflows and the role of n8n-derived evidence.
• SaaS operator release path gives the provider-free demo from strict SaaS fixtures to approval JSON and trusted-runner dry-run evidence.
• Project briefs and Data Flow describe the reviewable artifact contracts.

Execution Boundary

The intended lifecycle is:

natural-language project brief
-> externally orchestrated task or local authoring session
-> generated OpenAPI/UWS artifacts
-> deterministic validation and review
-> approved handoff package
-> trusted executor handoff

openudon synthesize, openudon build, openudon promote, openudon assess, openudon package prepare|promote|inspect|recover, cmd/icot, and eval commands generate, compile, validate, and report on artifacts. They do not execute production workflows.

openudon run is separate. It validates the handoff manifest, stored and current quality, approval JSON, package digest, and tier before writing a non-secret openudon.executor-run.v2 run config and openudon.run-evidence.v2 evidence in a unique per-run directory. Dry runs stage the reviewed package into a fresh workdir and verify the staged digest without invoking the executor or requiring credential values. Non-dry runs perform the same staging and digest check before calling the configured executor. The runner is also available directly with the digest and approval pinned by the parent process:

go run ./cmd/udon-runner \
--config <run-config.json> \
--config-sha256 <sha256> \
--approval <approval.json>

It revalidates current quality, handoff, package, approval, tier, and exact canonical config bytes before execution. v1 configs are rejected. OPENUDON_EXECUTOR accepts either an absolute path to an executable file or docker://<image>. The outer OPENUDON_UDON_RUNNER override must be an absolute path to an executable file. When that outer override is used, OpenUdon evidence marks its staged package as stage_kind: preflight; the external runner owns any final executor-visible staging and must fail closed on its own config checks.

Authoring With iCoT

iCoT turns a project idea into reviewed authoring artifacts. Terminal iCoT writes project.md and workflows/intent.hcl; the UI can additionally build and assess the reviewed package for handoff, but neither surface executes workflows. The generic interactive loop mechanics are shared through github.com/OpenUdon/authoring/icot; OpenUdon still owns the prompts, intent schema, artifact layout, model/provider clients, reports, and package gates. Reviewed API authentication is preserved as OR alternatives of AND symbolic bindings through authoring.prompt-context.v2. iCoT requires one numbered selection before request mappings, supports an explicit anonymous alternative, and never unions credentials or stores credential values.

go run ./cmd/icot --example ./examples/<name>

Common modes:

# Print rendered project.md and intent.hcl without writing files.
go run ./cmd/icot --example ./examples/<name> --print
# Use the adaptive interview without LLM extraction.
go run ./cmd/icot --example ./examples/<name> --no-llm
# Ask every question and let you confirm defaults. This is the default mode.
go run ./cmd/icot --example ./examples/<name> --prompt-mode full
# Show the whole frontier and accept safe defaults visibly.
go run ./cmd/icot --example ./examples/<name> --prompt-mode normal
# Silently accept safe defaults; still show missing/conflicting/forced decisions.
go run ./cmd/icot --example ./examples/<name> --prompt-mode fast
# Seed from an existing example.
go run ./cmd/icot --from-example ./examples/eval/runtime-only-render --example ./examples/<name> --yes
# Use an openudon.icot-session.v2 YAML or JSON session.
go run ./cmd/icot --answers ./session.yaml --example ./examples/<name> --yes
# Start the experimental single-workspace API v4 shell. A private root is# required only for source upload, authenticated Chromium capture, or guided# registration authoring. The package triple enables the registration wizard;# --browser-transaction remains optional for an existing public transaction.
install -d -m 0700 /private/operator/openudon-authoring
go run ./cmd/icot ui --example ./examples/<name> \
--private-root /private/operator/openudon-authoring \
--package-scope examples/<name> \
--package-scratch /absolute/restrictive-scratch-parent \
--package-store /absolute/generation-store
# Seed the UI from a reviewed example without opening the browser.
go run ./cmd/icot ui --example ./examples/<name> \
--from-example ./examples/eval/runtime-only-render --no-open
# Observe or explicitly advance one public value-free browser transaction.
go run ./cmd/icot browser-transaction \
--transaction ./transaction.json \
--example ./examples/<name> --scope examples/<name> \
--scratch /absolute/restrictive-scratch-parent \
--store /absolute/generation-store --prepare
# Add reviewed sources or bounded discovery roots; flags are repeatable.
go run ./cmd/icot --example ./examples/<name> \
--api-source graphql:catalog=./schema.graphql \
--openapi weather=./openapi/weather.yaml \
--source-root ./provider-metadata --network ask
# Use reviewed browser capability/authentication profiles only when no adequate API capability exists.
go run ./cmd/icot --example ./examples/<name> \
--browser-profile status=./reviewed/status.browser.json \
--browser-verification ./reviewed/status.live-check.json \
--browser-verification ./reviewed/status.portability.json \
--browser-profile member-auth=./reviewed/member-auth.yaml \
--browser-registry https://profiles.example.org/catalog/ \
--network ask
# Verification reports are optional value-free review evidence. OpenUdon# revalidates them against the exact profile/actions and stages only summaries.# When no reviewed profile exists, emit a non-executing Browsertools handoff.
install -d -m 0700 /private/operator/browsertools-status
go run ./cmd/icot browser-authoring plan \
--example ./examples/<name> --url https://example.test/status \
--origin https://example.test --profile-id status \
--action-hint read_status --login-state not-required \
--private-root /private/operator/browsertools-status \
--out /private/operator/browsertools-status/handoff.json
# The CLI live mode is an expert fallback. It uses the bundled isolated worker# by default; --browsertools remains an expert compatibility override.
install -d -m 0700 /private/operator/member-authoring
go run ./cmd/icot browser-author live \
--example ./examples/member-dashboard \
--url https://members.example.test/login \
--dashboard-url https://members.example.test/dashboard \
--goal "reach the member dashboard and learn how to read account status" \
--origin https://members.example.test \
--origin https://login.example-idp.test \
--private-root /private/operator/member-authoring \
--profile-id member --goal-role heading --goal-label Dashboard
# Rebuild project.md from workflows/intent.hcl.
go run ./cmd/icot reconcile --example ./examples/<name># Check authoring quality, intent parseability, and advisory drift.
go run ./cmd/icot lint --example ./examples/<name># Noninteractive agent/JSON report surface.
go run ./cmd/icot --example ./examples/<name> --agent --json
# Provider-free iCoT reliability scorecard.
go run ./cmd/icot scorecard --root ./examples/eval --out eval/runs/icot-scorecard-local
# Include curated natural-language authoring variants.
go run ./cmd/icot scorecard --root ./examples/eval --include-variants --out eval/runs/icot-authoring-scorecard-local
# Verify scorecard report JSON plus digest sidecar.
go run ./cmd/icot report verify --file eval/runs/icot-authoring-scorecard-local/scorecard.json
# Validate variant metadata and reference-seeded clear slots.
go run ./cmd/icot variants validate --root ./examples/eval
# Check provider-family coverage across variant classes.
go run ./cmd/icot variants coverage --root ./examples/eval
# Optional real-LLM natural-language authoring evidence.
go run ./cmd/icot authoring-eval --root ./examples/eval --include-variants --provider copilot-api --model gpt-5.4-mini --out eval/runs/icot-authoring-eval-local
# Optional/manual verification for real-LLM authoring evidence.
go run ./cmd/icot report verify --file eval/runs/icot-authoring-eval-local/authoring-eval.json
# Bounded deterministic repair for mappings, outputs, and depends_on.
go run ./cmd/icot repair --example ./examples/<name> --dry-run --json
# Replay eval references through iCoT and save ignored transcripts.
go run ./cmd/icot replay-eval --root ./examples/eval --provider copilot-api --model gpt-5.4-mini

iCoT maps broad requests into one active workflow boundary plus unnumbered candidate workflows. It shows every dependency-ready decision as one frontier round before collecting answers, and has no fixed question ceiling. Candidate workflows receive a deferral reason and promotion trigger but no sources, operations, mappings, or implementation steps.

iCoT autosaves only resumable local state under <example>/.icot/session.yaml and resumes by default. Successful promotion deletes obsolete draft/readiness state. Transcripts are written under <example>/.icot/transcript.json unless --no-transcript is used. These local files are ignored by git.

icot ui is the primary interactive authoring shell over the same engine. It always binds 127.0.0.1 and opens a tokenless loopback page. A random 12-character Crockford Base32 access code is printed only in the terminal; it expires after five minutes, is single-use, and throttles after five failed attempts per minute. A successful POST exchange installs the existing scoped HttpOnly, SameSite=Strict cookie and redirects to the clean instance path. If that browser session is lost, the tokenless page can rotate an already-used or expired code and print the replacement only in the terminal. The UI requires separate authoring and capture revisions for mutations and asynchronous browser events, detects changes made by editors or another process, and freezes only after a passing reviewed package build. A detected workspace change preserves cached inspection but blocks mutation until the process is restarted. The shell polls experimental API v4 while visible and backs off after errors. It selects a journey, validates/stages bounded API uploads, performs isolated existing-account Chromium capture, renders the current frontier as accessible controls, submits complete revision-protected rounds, previews proposed artifacts and conflicts, supports explicit settled-answer reopening, shows candidate/source/review evidence, and requires explicit authoring approval. Package build is a second confirmation; failed quality can explicitly return to authoring and requires reapproval, while success exposes only allowlisted handoff artifacts and exact approval-template argv. A later artifact size or digest change invalidates the frozen handoff and requires resume, reapproval, and rebuild. The UI does not invoke an LLM extractor, create an approval, accept credentials, execute workflows, or expose a LAN service. See Local iCoT UI Server.

--prompt-mode full is the default when the flag is omitted; it prints every question and waits for you to confirm or replace defaults. --prompt-mode normal prints the full frontier and visibly accepts safe defaults. --prompt-mode fast silently accepts safe defaults but shows missing, low-confidence, conflicting, and forced decisions. Final proposal approval is forced in every mode; --yes is its explicit noninteractive equivalent.

When LLM extraction is enabled, iCoT also runs a bounded pre-final flow review before showing the current draft. That review is advisory: it looks for cross-step data-flow mistakes such as a report email step not consuming the report content, and surfaces findings as warnings without rewriting the draft.

The normal terminal iCoT command, agent mode, and browser-authoring plan never launch a browser. UI capture and the expert browser-author live command start an isolated Browsertools worker. The bundled worker and terminal-only expert override use the same typed controller: worker events are reduced and closed-vocabulary validated before terminal, UI, or planner disclosure, and a process-private parent attestation binds the ordered interaction, output requests, and exact approved-origin ledger before staging. Browsertools owns one non-persistent Playwright-Go Chromium context across human login/MFA and post-login exploration; each new canonical HTTPS or loopback origin still needs an exact human approval. iCoT imports only reviewed canonical UWS profiles plus safe metadata, and --yes bypasses none of those live gates. See Authenticated Browser Authoring for the protocol, data boundary, failure behavior, and the separate Udon/ Browserdriver trusted-runtime replay.

--review-repair turns selected warnings into a bounded repair loop. It can apply narrow wiring repairs or add a local fnct transform/report/render step when the goal clearly asks for produced content and one known producer step can feed it. It rejects operation, source, credential, and side-effect-scope mutations.

Before questioning, iCoT inspects existing sources, explicit documents, and explicit roots through apitools' bounded multi-family discovery. It supports OpenAPI/Swagger, Google Discovery, AWS Smithy, AsyncAPI, GraphQL, OpenRPC, gRPC/protobuf, and OData; rejects symlinks and ambiguous documents; deduplicates by SHA-256; and never copies a source before proposal approval. If local evidence is exhausted, approved remote lookup is limited to curated apitools references plus one APIs.guru lookup with an eight-second deadline and at most three metadata candidates.

For a UI action that requires login state, iCoT can pair a reviewed, secret-free uws.browser-authentication.1.0 or 1.1 profile with a uws.browser.1.5, 1.6, or 1.7 capability profile. Browser 1.7 carries strict integer, number, and Boolean accessibility-text outputs under UWS 1.9. It authors an explicit sign-in flow, execution-local named session, symbolic credential bindings, bounded timeout, and separate authoring approval; Udon still requires separate runtime approval and keeps credentials, MFA responses, and live session state private.

OpenUdon also accepts already-reviewed, secret-free uws.browser-registration.1.0 profiles and browsertools.registration-review.v1 bundles as manual package-local sources. Its internal transaction engine can also turn an explicitly reviewed, path-free Browsertools registration candidate into the same package inputs; public snapshots and resumable drafts retain only value-free identities. The local UI and terminal expose that candidate lifecycle through the same driver-free engine. The UI can construct a v2 candidate in one isolated, GET/HEAD-only Browsertools session, disclose its retained structural query for explicit review, and adopt it only after clean worker teardown. Configure the package option triple for that guided path; a public transaction JSON file—never a private Browsertools result—remains the input to icot ui --browser-transaction ... or icot browser-transaction ... for an existing candidate. Review, scratch preparation, promotion, and recovery each require their own exact digest-bound decision. An explicit browser_registration intent lowers fixed duplicate, ambiguity, cleanup, symbolic-binding, and exact submit-approval policy to uws.browser-registration-call.1.0. Build, assessment, approval-template, and trusted-runner dry-run are offline. Non-dry registration is enabled only for the exact Udon report-v3 and Browserdriver protocol-v4 handoff, with a private digest-bound dedicated-test attestation and a separate exact --approve-browser-registration OP_ID; incomplete or legacy configurations still fail before executor invocation. Browser-Profile Authoring Transactions defines the common value-free review, prepare-only, atomic-promotion, and recovery record for the BAP+BCP and BRP paths.

If no in-workflow authentication step establishes the required login state, each affected browser step must instead name its own symbolic external browser_session. The aggregate opaque-session posture is review evidence, not a runtime session name, cookie, token, or substitute for the step-level binding.

--agent returns the entire frontier, candidate workflows, source evidence, blockers, and proposed file actions. It never prompts or writes deliverables, including when the session is otherwise complete.

Side-effect scope in iCoT:

• read-only: generate and validate artifacts only.
• sandbox-only: sandbox proof runs require approved_for_sandbox, approved bindings, and a trusted runner.
• after-approval: sandbox and production execution require the full OpenUdon review approval path.

Synthesize And Assess

Generate all reviewed artifacts for an example:

export COPILOT_API_BASE_URL=http://localhost:4141
export OPENUDON_LLM_PROVIDER=copilot-api
export OPENUDON_LLM_MODEL=gpt-5.4-mini
go run ./cmd/openudon synthesize \
--example ./examples/support-email \
--provider "$OPENUDON_LLM_PROVIDER" \
--model "$OPENUDON_LLM_MODEL" \
--max-attempts 5

The command reads project.md, discovers or imports API/event source documents under openapi/, google-discovery/, aws-smithy/, asyncapi/, graphql/, openrpc/, grpc-protobuf/, or odata/, writes workflows/intent.hcl when needed, and generates equivalent public UWS HCL/YAML workflow artifacts:

expected/plan.json
expected/plan.md
expected/discovery.json
expected/data.hcl
expected/refinement.json
expected/refinement.md
expected/review.md
expected/review-handoff.json
expected/quality.json
expected/quality.md

expected/data.hcl is for reviewed runtime inputs and env references, not plaintext secrets. Udon resolves markers such as client_secret = "ENVIRONMENT:GOOGLE_CLIENT_SECRET" from the execution environment.

Use narrower stages after editing artifacts:

# intent.hcl -> workflow/UWS/plan/review/quality
go run ./cmd/openudon build --example ./examples/support-email --max-attempts 5
# workflow.hcl -> UWS/review/quality
go run ./cmd/openudon promote --example ./examples/support-email
# quality reports only
go run ./cmd/openudon assess --example ./examples/support-email

The bounded refinement loop records retried stages, failed checks, and stop reason in expected/refinement.json.

Provider Catalog

OpenUdon can inspect first-class provider metadata from github.com/OpenUdon/apitools/catalog before falling back to public search. Catalog data is advisory: local API source files and explicit source inputs remain authoritative for generated packages.

# List known first-class providers and auth/security status.
go run ./cmd/openudon catalog list
# Inspect a provider's official OpenAPI, Discovery, Smithy, docs, and security-overlay metadata.
go run ./cmd/openudon catalog inspect github
go run ./cmd/openudon catalog advisory gmail
# Import a provider-owned OpenAPI document directly into an example.
go run ./cmd/openudon catalog import-openapi \
--provider stripe \
--example ./examples/<name> \
--name stripe

import-openapi writes only actual OpenAPI references into examples/<name>/openapi/. Catalog materialization and iCoT artifact migration may stage Google Discovery under google-discovery/, AWS Smithy JSON under aws-smithy/, AsyncAPI source documents under asyncapi/, GraphQL under graphql/, OpenRPC under openrpc/, gRPC/protobuf under grpc-protobuf/, and OData under odata/. Dropbox Stone, Postman Collection, RAML, API Blueprint, and human-docs entries remain advisory until lowered or reviewed separately.

Quality And Repair Loop

The pipeline is validation-first:

1. Run synthesize for a new or substantially changed project.md.
2. If it fails, read expected/refinement.json and expected/quality.json.
3. Repair the earliest failing stage.
4. For openapi.*, add a valid local OpenAPI file or explicit OpenAPI URL.
5. For intent.*, edit project.md or workflows/intent.hcl, then rerun build.
6. For workflow.*, prefer improving intent and rerunning build; use promote and assess for narrow workflow repairs.
7. For uws.*, review.*, review_handoff.*, or artifacts.*, repair the generated artifact or evidence, then run promote or assess.
8. Stop after the configured attempt limit and report blocking checks if quality still fails.

Eval And Release Evidence

Use deterministic checks for routine development:

go test ./...
go vet ./...
make check
git diff --check

Use the eval harness when changing prompts, synthesis/refinement behavior, model defaults, or quality gates that could affect generated artifacts:

go run ./cmd/openudon eval --root ./examples/eval --provider copilot-api --model gpt-5.4-mini

Eval reports are written under ignored eval/runs/. They include pass/fail summaries, provider/model/mode/prompt-version breakdowns, approximate prompt-token totals, generated workspace paths, provider drift watch data, and comparison against a previous report when available.

Use release gates only for candidate release evidence:

make eval-seed-build
make release-saas-check
make browser-transaction-qualification
make release-evidence
make release-eval

make release-saas-check is the provider-free local SaaS release gate. It runs deterministic checks, the required sandboxed icot-ui-browser-check, the browser-free browser integration evaluation, the real network-free browser scenario loopback and journey suites, the eval seed/build matrix, icot-variants-validate, icot-authoring-scorecard, UWS validation, doc-memory validation, n8n bridge validation, strict MkDocs, selected strict fixture lint, and trusted-runner dry-run demos without live provider credentials or live provider execution. icot scorecard --include-variants is deterministic reference/variant package evidence; use icot authoring-eval separately for optional real LLM natural-language authoring evidence.

make icot-ui-browser-check launches Chromium through the test-only Playwright-Go harness and qualifies the embedded Phase C authoring, approval, accessibility, narrow/zoom layout, polling, stale-state, drift, retry, and freeze journeys against a real loopback server. It is part of the release gate, not the production UI runtime.

make release-eval uses OPENUDON_LLM_PROVIDER and OPENUDON_LLM_MODEL, defaulting to copilot-api and gpt-5.4-mini, and requires the current eval corpus size as the minimum brief count.

make release-evidence runs the local udon smoke, archives and verifies run-evidence.json plus async/executor report sidecars, drafts local release notes, and writes compact summaries under ignored .openudon-run/release-evidence/. It does not tag, publish, commit artifacts, or contact live providers.

make browser-integration-check runs and then verifies the value-free, digest-bound authoring-to-handoff matrix across OpenUdon, Browsertools, UWS, Udon, and Browserdriver. Its default path is offline/provider-free and does not launch a browser; installed-engine and headed-authentication checks require separate loopback-only CLI opt-ins.

make browser-scenario-loopback runs and verifies the required 23-case real Browsertools v2 to Udon/Browserdriver v3 release matrix. It requires installed pinned Chromium dependencies and a display (use xvfb-run -a on headless Linux). make browser-scenario-journey runs the required eight-case headless local read/write matrix through guided authoring, UWS 1.8, Udon v3, and Browserdriver v3. make browser-scenario-public is an explicit-network, informational four-site canary; it is never part of default tests.

xvfb-run -a make browser-transaction-qualification runs the complete cross-package BAP+BCP replay and BRP authoring-to-runtime qualification against only embedded loopback fixtures, after its adversarial matrix, and writes a canonical value-free v2 report under ignored eval/runs/. The BRP case keeps authoring GET/HEAD-only, then uses the exact private attestation and submit approval to prove one Browserdriver-v4 POST through Udon report v3 with no named session. It requires clean exact sibling revisions and sandboxed Chromium. Xvfb supplies only the display; see Browser-Profile Authoring Transactions for the host sandbox prerequisite and independent report verification.

Readiness

Local readiness reports record optional sibling checkout presence, deterministic gate results, git state, ignored local artifacts, provider credential environment presence as booleans only, and current maintainer automation policy.

go run ./cmd/openudon readiness --out eval/readiness/local.json
go run ./cmd/openudon readiness --run-gates --out eval/readiness/local.json

GitHub Actions runs public-module vet/test gates without local sibling checkouts. Real-provider release evidence remains local/manual.

Trusted Execution

After artifacts pass review, generate approval JSON with the current package digest:

mkdir -p approvals
go run ./cmd/openudon approval-template \
--example ./examples/support-email \
--state approved_for_sandbox \
--reviewer "Reviewer Name" \
> approvals/support-email-sandbox.json

Validate approval, quality, handoff policy, package digest, and tier compatibility before trusted executor handoff:

go run ./cmd/openudon run \
--example ./examples/support-email \
--tier sandbox \
--approval approvals/support-email-sandbox.json

Use --dry-run to validate all gates, stage the package, verify the staged digest, and write run evidence without invoking the executor.

Approval JSON shape:

{
"version": "openudon.approval.v1",
"scope": "examples/support-email",
"state": "approved_for_sandbox",
"reviewer": "Reviewer Name",
"approved_at": "2026-04-29T12:00:00Z",
"expires_at": "2026-05-06T12:00:00Z",
"package_sha256": "<current handoff package digest>",
"notes": "optional"
}

The shared github.com/OpenUdon/evidence/approval package supplies neutral approval evidence primitives for cross-product reuse. The openudon.approval.v1 JSON shape above remains the OpenUdon trusted-runner contract.

Tier rules:

• sandbox accepts approved_for_sandbox or approved_for_production.
• production accepts only approved_for_production.
• Expired approvals fail.
• Scope mismatch fails.
• Package digest mismatch fails.
• Stored or current quality failures fail.
• Malformed handoff manifests fail.
• Credential-value artifacts and direct production execution remain prohibited.
• run-evidence.json records gate outcomes, package paths, staged paths, stage kind, executor status, and credential binding names only; it must not contain credential values.
• Approval JSON and saved run configs from before the OpenUdon package rename should be regenerated so scope, version, and package digest fields match the current artifact set.

Agent Workflow

OpenUdon issues may be run through externally orchestrated Codex sessions. Agents should follow this policy:

• Use UWS as the workflow interchange format.
• Use reviewed API/event source documents for HTTP method, path, channel, message, schema, server, and security details.
• Use openudon catalog inspect or openudon catalog import-openapi when a first-class provider-owned OpenAPI source is available, and use first-class materialization for Google Discovery, AWS Smithy, AsyncAPI, GraphQL, OpenRPC, gRPC/protobuf, or OData sources when supported.
• Use extension-owned UWS operations for non-HTTP runtimes such as SMTP, command execution, SSH, SQL, or LLM calls.
• Use ../uws for public schema/model validation.
• Use openudon run to hand approved UWS/API-source packages to a trusted executor such as udon.
• Do not execute production side effects directly from an agent session.
• If execution is requested, produce or update the approved artifact and document the trusted runner command.

Expected artifact locations:

examples/<name>/project.md
examples/<name>/openapi/
examples/<name>/google-discovery/
examples/<name>/aws-smithy/
examples/<name>/discovery/
examples/<name>/asyncapi/
examples/<name>/graphql/
examples/<name>/openrpc/
examples/<name>/grpc-protobuf/
examples/<name>/odata/
examples/<name>/workflows/intent.hcl
examples/<name>/workflows/workflow.hcl
examples/<name>/workflows/workflow.uws.yaml
examples/<name>/expected/plan.json
examples/<name>/expected/plan.md
examples/<name>/expected/discovery.json
examples/<name>/expected/data.hcl
examples/<name>/expected/refinement.json
examples/<name>/expected/refinement.md
examples/<name>/expected/review.md
examples/<name>/expected/review-handoff.json
examples/<name>/expected/quality.json
examples/<name>/expected/quality.md

Before handoff:

go test ./...
go vet ./...
make check
git diff --check
go run ./cmd/openudon validate examples/uws-validation
go run ./cmd/openudon assess --example examples/<name>

If side-effectful execution is explicitly requested, use openudon run with approval JSON. Do not run production effects from synthesis, build, promote, assess, iCoT, or eval.

Model And Credential Guidance

Use the local copilot-api proxy with gpt-5.4-mini as the default model for synthesis. OpenUdon reliability comes mostly from prompt preprocessing, structured output when available, deterministic quality gates, and bounded repair attempts. Escalate to a larger model only after the default model fails deterministic checks.

LLM credentials must come from provider environment variables such as COPILOT_API_BASE_URL, COPILOT_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY. Do not place tokens in prompts, commands, examples, or workflow artifacts. Gemini sends its key only through x-goog-api-key; provider response bodies are bounded to 8 MiB.

Use OPENUDON_LLM_PROVIDER and OPENUDON_LLM_MODEL when you want shell-level defaults for local LLM-assisted commands; explicit --provider and --model flags still take precedence.

More Documentation

• Project authoring
• iCoT
• iCoT corpus and provider roadmap
• Intent contract
• Data flow
• Enterprise authoring/execution boundary
• Safety
• Eval gallery
• SaaS operator release path
• Release stewardship
• Release note template
• v0.2 compatibility contract
• Support policy
• Security policy
• Contributing
• License