From 6cb7c8d5d052de2699f665e5496d221c56b7a433 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Sun, 9 Aug 2026 22:25:39 -0600 Subject: [PATCH] docs: align website with Traverse v0.9.1 --- public/llms.txt | 2 +- src/pages/changelog.astro | 64 +++++------------------------- src/pages/docs/cli-reference.astro | 58 +++++++++++++-------------- src/pages/docs/quickstart.astro | 43 +++++++------------- src/pages/system.astro | 6 +-- 5 files changed, 57 insertions(+), 116 deletions(-) diff --git a/public/llms.txt b/public/llms.txt index 79642f3..893e907 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -1,6 +1,6 @@ # Traverse -> Traverse is a contract-driven WASM runtime for portable business capabilities: write a capability once with a machine-readable contract (JSON Schema pre/postconditions), compile it to WASM, and run the same binary natively, in the browser, or expose it to an AI agent over MCP with the contract enforced on every call. Apache 2.0, pre-1.0 (v0.8.1) — check /platforms.html before assuming any target or feature is shipped. +> Traverse is a contract-driven WASM runtime for portable business capabilities: write a capability once with a machine-readable contract, compile it to WASM, and run it natively, in the browser, or expose it to an AI agent over MCP. Apache 2.0, pre-1.0 (v0.9.1) — check /platforms.html before assuming any target or feature is shipped. Traverse is not a web framework, an agent-orchestration framework, or a general microservices platform. It governs one thing well: a single piece of business logic that must behave identically and auditably across more than one runtime environment. diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro index 65a4baf..bee1eb0 100644 --- a/src/pages/changelog.astro +++ b/src/pages/changelog.astro @@ -1,59 +1,15 @@ --- import SubpageLayout from '@layouts/SubpageLayout.astro'; - -const _body = "
\n
Changelog
\n

Release history

\n

What shipped in each version of Traverse. All releases are spec-governed — every change is backed by an approved, versioned specification.

\n
\n View all releases on GitHub →\n
\n\n \n
\n
\n
v0.8.1
\n
July 18, 2026 · current
\n
Latest
\n
Active dev
\n
\n
\n

crates.io publish fix

\n

Patch release with no functional or spec changes. Completes v0.8.0’s publish to crates.io: fixes the unset registry token in the publish job, adds the required description manifest fields, and renames the CLI crate’s package identity to traverse-cli-rs to resolve a name collision — the binary invocation stays traverse-cli.

\n
\n
\n\n \n
\n
\n
v0.8.0
\n
July 16, 2026
\n
\n
\n

Public embedder SDKs, durable event journal

\n

The public embedder SDK release. Ships the first two embedder-api/1.0.0 client SDKs — Rust (Linux GTK/CLI) and Web/TypeScript, both with real bundle execution — and completes the durable event journal so subscriptions survive broker restarts.

\n\n
What’s new
\n
    \n
  • Public traverse-embedder Rust SDK: every embedder-api/1.0.0 operation against an application-owned bundle, with a deterministic test double and a CI-enforced conformance suite.
    • \n
  • Web/TypeScript embedder SDK with real runtime-WASM execution: BundleEmbedder digest-verifies every bundled capability and executes it in the browser’s native WebAssembly host through a minimal WASI shim — no nested engine, no server sidecar.
    • \n
  • Durable event journal: segmented storage, a bounded write path with revocation and audit, and journal-backed replay so durable subscriptions resume across a full broker restart.
    • \n
  • Deterministic doc-approval.recommend capability and canonical doc-approval.pipeline workflow.
    • \n
  • Runtime hardening: bounded HTTP connection timeouts, placeholder Sigstore evidence rejected, artifact-verification gate applied to workflow pipeline steps.
    • \n
\n
\n
\n\n \n
\n
\n
v0.7.0
\n
2026
\n
\n
\n

Browser adapter, MCP server, React demo

\n

The largest release to date. Introduces the live browser adapter, the MCP stdio server for AI agent integration, and the React demo app. All backed by the expedition planning example domain.

\n\n
What's new
\n
    \n
  • Live browser adapter on port 4174. UI submits governed requests, runtime executes WASM capabilities locally.
    • \n
  • React demo app on port 4173 — connects to browser adapter, shows real-time state transitions and trace output
    • \n
  • MCP stdio server (traverse-mcp). AI agents discover and execute governed capabilities via Model Context Protocol.
    • \n
  • Expedition planning domain with 6 capabilities, 5 events, and 1 workflow. Fully governed and runnable.
    • \n
  • Trace generation and subscription. Every execution produces a structured, queryable trace artifact.
    • \n
  • State machine: ready → streaming → completed with ordered runtime timeline
    • \n
  • Release-facing documentation: quickstart, authoring guides, troubleshooting
    • \n
\n\n
Governing specs (9 approved)
\n
    \n
  • foundation-v0-1: Core runtime, CLI, MCP surface
    • \n
  • capability-contracts: Contract definitions and validation
    • \n
  • event-contracts: Event contract definitions
    • \n
  • spec-alignment-gate: CI merge gate
    • \n
  • capability-registry: Registry behavior
    • \n
  • runtime-request-execution: Execution model
    • \n
  • workflow-registry-traversal: Workflow composition
    • \n
  • expedition-example-domain: Example domain definition
    • \n
  • expedition-example-artifacts: Example contracts and workflows
    • \n
\n\n
Quality
\n
    \n
  • 100% test coverage, CI-gated with no exceptions
    • \n
  • #![forbid(unsafe_code)] enforced across all crates
    • \n
  • No unwrap, panic, or TODO in production code
    • \n
  • SBOM generation (CycloneDX format)
    • \n
  • ADR process in place. All architectural decisions documented.
    • \n
\n
\n
\n\n \n
\n
\n
v0.5.0
\n
2026 · earlier
\n
Stable
\n
\n
\n

Release artifacts and app registration

\n

Introduced stable release artifacts and the app registration and validation flow through the CLI. First version with a consumer-facing bundle integration path.

\n\n
What shipped
\n
    \n
  • Stable release artifacts, versioned and reproducible
    • \n
  • App registration via CLI using traverse-cli bundle inspect
    • \n
  • App validation through the registry bundle manifest
    • \n
  • Consumer-facing documentation and bundle integration path
    • \n
  • Release-facing entry path for downstream consumers
    • \n
\n
\n
\n\n \n
\n
\n
v0.1.0
\n
2025 · foundation
\n
Foundation
\n
\n
\n

Spec governance, runtime foundation, CLI

\n

Established the spec-driven development process, the core runtime crates, and the initial CLI surface. The foundation all subsequent releases are built on.

\n\n
What shipped
\n
    \n
  • traverse-runtime: core execution engine scaffolding
    • \n
  • traverse-contracts: contract parsing and validation
    • \n
  • traverse-registry: capability and event registry
    • \n
  • traverse-cli: initial CLI with register, list, validate, and run commands
    • \n
  • Spec governance process in place. Spec-first, ADR-backed, CI-gated.
    • \n
  • Rust workspace structure with #![forbid(unsafe_code)]
    • \n
  • First approved governing spec: foundation-v0-1
    • \n
\n
\n
\n\n \n
\n

In scope for future releases

\n
\n
Edge executor adapter
\n
Cloud executor adapter
\n
Multi-agent orchestration with conflict prevention
\n
AI-pipeline placement target
\n
Extended trace querying and audit tooling
\n
\n

All roadmap items require an approved governing spec before implementation begins.

\n
\n
"; --- - - - + +
+
Changelog

Release history

+

What shipped in Traverse. Each release is backed by versioned, reviewable work.

+

View all releases on GitHub →

+

Governed capability publishing and real emitted events

v0.9.1 completes the current capability-authoring loop: scaffold, inspect, validate, and publish executable WASM capabilities through a reviewable registry change. Publication records the artifact with the registry record and rejects unresolved persona references, including in dry runs.

  • The local executor carries events emitted by executable capabilities through the runtime; the output-JSON convention is retired.
  • Contract-surface coverage is enforced for published capabilities.
  • New end-to-end-smoked examples cover authorization, comment processing, action-status transitions, ownership assignment, and action-item validation.
  • The CLI package includes its generated protobuf source.
Read the v0.9.1 release notes →
+

crates.io publish fix

Patch release that completed the v0.8.0 publish path and retained the traverse-cli binary name.

Read the v0.8.1 release notes →
+

Public embedders and durable events

Public Rust and Web/TypeScript embedder SDKs, durable event-journal replay, and the doc-approval reference workflow.

Read the v0.8.0 release notes →
+
+ diff --git a/src/pages/docs/cli-reference.astro b/src/pages/docs/cli-reference.astro index d95abd9..63fa7c1 100644 --- a/src/pages/docs/cli-reference.astro +++ b/src/pages/docs/cli-reference.astro @@ -1,34 +1,34 @@ --- import SubpageLayout from '@layouts/SubpageLayout.astro'; import DocsSidebar from '@components/DocsSidebar.astro'; - -const _docsBefore = "
\n \n "; -const _docsAfter = "
\n
\n
Reference
\n

CLI Reference

\n

All commands, flags, and expected output for traverse-cli.

\n
\n v0.8.1\n traverse-cli\n
\n
\n\n \n
\n

Installation

\n

Build the CLI from the workspace. No separate install step needed.

\n
\n
build
\n
\n
$ cargo build -p traverse-cli
\n
Compiling traverse-cli v0.8.1
\n
Finished dev [unoptimized + debuginfo] target(s)
\n
\n
\n

The binary is at target/debug/traverse-cli after building. Use cargo run -p traverse-cli -- during development to build and run in one step.

\n
\n\n \n
\n

Global flags

\n

These flags work with any command.

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
FlagDescription
--helpPrint help text for any command. Works at the top level and on each subcommand.
--versionPrint the CLI version and exit.
\n
\n
examples
\n
\n
$ traverse-cli --version
\n
traverse-cli 0.7.0
\n
$ traverse-cli --help
\n
Traverse CLI — contract-driven WASM runtime
\n
\n
Usage: traverse-cli [COMMAND]
\n
\n
Commands:
\n
bundle Inspect and manage capability bundles
\n
browser-adapter Run the local browser adapter server
\n
\n
\n
\n\n \n
\n
bundle
\n

bundle inspect <path>

\n

\n Inspect a registry bundle. Prints the bundle name, version, and all capabilities found in the manifest. Validates the manifest format without executing anything.\n

\n
traverse-cli bundle inspect <PATH>
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Argument / FlagTypeDescription
<PATH>pathPath to the bundle directory. Must contain a manifest.json.
--verboseflagPrint full contract details for each capability.
\n
\n
example
\n
\n
$ cargo run -p traverse-cli -- bundle inspect ./bundles/expedition
\n
\n
Bundle: expedition
\n
Version: 1.0.0
\n
Capabilities: 1
\n
\n
plan-expedition
\n
version: 1.0.0
\n
target: local
\n
binary: plan_expedition.wasm
\n
inputs: goal (string), team_size (integer), duration_days (integer)
\n
outputs: plan (string), equipment_list (array)
\n
emits: expedition.planned
\n
\n
\n
\n\n \n
\n
browser-adapter
\n

browser-adapter serve

\n

\n Start the local browser adapter. This is an HTTP server that sits between your React app and the Traverse runtime. It exposes a /execute endpoint and a /health endpoint. The adapter loads the specified bundle at startup.\n

\n
traverse-cli browser-adapter serve --bind <ADDR> [--bundle <PATH>]
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
FlagTypeDefaultDescription
--bindstring127.0.0.1:4174Address and port to listen on.
--bundlepathdefault bundlePath to the bundle directory to load at startup.
\n
\n
example
\n
\n
$ cargo run -p traverse-cli -- browser-adapter serve \\
\n
--bind 127.0.0.1:4174 \\
\n
--bundle ./bundles/expedition
\n
\n
Loading bundle: ./bundles/expedition
\n
plan-expedition v1.0.0 ... ok
\n
Registry ready. 1 capability loaded.
\n
Adapter listening on 127.0.0.1:4174
\n
\n
\n

The adapter runs until you stop it with Ctrl-C. It does not hot-reload bundles. Restart after any bundle changes.

\n
\n\n \n
\n
Coming soon
\n

register <bundle> not yet available

\n

\n Register a bundle with a remote registry. This command will push the bundle manifest and WASM binaries to a registry endpoint and index all capabilities for remote discovery.\n

\n
traverse-cli register <BUNDLE_PATH> --registry <URL>
\n

Planned for a future release. Track progress on GitHub.

\n
\n\n \n
\n
Coming soon
\n

list not yet available

\n

\n List all capabilities registered with a remote registry. Will output capability IDs, versions, and available targets in a table.\n

\n
traverse-cli list [--registry <URL>] [--json]
\n

Planned for a future release.

\n
\n\n \n
\n
Coming soon
\n

validate <contract> not yet available

\n

\n Validate a single contract file against the Traverse contract schema. Will report any missing required fields, type mismatches, or invalid constraint declarations.\n

\n
traverse-cli validate <CONTRACT_PATH>
\n

Planned for a future release.

\n
\n\n \n
\n
Coming soon
\n

run <capability-id> not yet available

\n

\n Execute a capability directly from the CLI. Will load the bundle, run the capability with the provided inputs, and print the trace artifact to stdout.\n

\n
traverse-cli run <CAPABILITY_ID> --bundle <PATH> --input <JSON>
\n

Planned for a future release.

\n
\n\n
\n
\n\n"; --- - - - - - + + +
+ +
+
Reference
+

CLI reference

+

The current CLI is released with Traverse v0.9.1. Its source-backed reference lives with the runtime so commands and examples can evolve together.

+
v0.9.1traverse-cli
+
+

Start from the current reference

+

Build the workspace and ask the installed binary for the exact command surface available in that checkout:

+ 
cargo build
+cargo run -p traverse-cli-rs -- --help
+

Use the repository’s CLI reference for command syntax, arguments, and expected output.

+
+
+

Capability authoring and publication

+

Traverse v0.9.1 supports the governed capability lifecycle: scaffold a package, inspect its contract, validate the executable artifact, and publish a reviewable registry change. Publication records the artifact alongside its registry record and rejects unresolved persona references.

+ +
+
+

Bundles, events, and apps

+

The CLI also exposes bundle, registry, event, and app workflows. Use the checked-in documentation for stable instructions and --help for the precise surface in the version you have installed.

+ +
+
+
+ diff --git a/src/pages/docs/quickstart.astro b/src/pages/docs/quickstart.astro index 83994a0..8188728 100644 --- a/src/pages/docs/quickstart.astro +++ b/src/pages/docs/quickstart.astro @@ -1,34 +1,19 @@ --- import SubpageLayout from '@layouts/SubpageLayout.astro'; import DocsSidebar from '@components/DocsSidebar.astro'; - -const _docsBefore = "
\n \n \n \n "; -const _docsAfter = "
\n
\n
Getting Started
\n

Quickstart

\n

Your first runnable Traverse flow. Run the expedition planning example in under 5 minutes.

\n
\n v0.8.1\n ~5 minutes\n Rust 1.94+\n Node.js required\n
\n
\n\n \n
\n
\n
01
\n Prerequisites\n
\n

Before you start

\n

Make sure you have these installed:

\n
\n
check versions
\n
\n
$ rustc --version
\n
rustc 1.94.0 (or higher)
\n
\n
$ cargo --version
\n
cargo 1.94.0
\n
\n
$ node --version
\n
v20.0.0 (or higher)
\n
\n
\n

Install Rust via rustup.rs if you don't have it.

\n
\n\n \n
\n
\n
02
\n Clone the repo\n
\n

Clone and build

\n

Clone the traverse repo and run an initial build to verify everything compiles.

\n
\n
clone
\n
\n
$ git clone https://github.com/traverse-framework/traverse
\n
$ cd traverse
\n
$ cargo build
\n
\n
Compiling traverse-runtime ...
\n
Finished in X.XXs
\n
\n
\n
\n\n \n
\n
\n
03
\n Inspect the bundle\n
\n

Verify the expedition bundle

\n

Before running the demo, inspect the registry bundle to confirm all 6 capabilities, 5 events, and 1 workflow are registered.

\n
\n
bundle inspect
\n
\n
$ cargo run -p traverse-cli -- bundle inspect \\
\n
examples/expedition/registry-bundle/manifest.json
\n
\n
bundle_id: expedition.planning.seed-bundle
\n
version: 1.0.0
\n
capabilities: 6
\n
events: 5
\n
workflows: 1
\n
\n
\n
\n\n \n
\n
\n
04
\n Run the browser adapter\n
\n

Start the browser adapter

\n

Open a terminal and start the browser adapter. It listens on port 4174 and handles all capability execution requests from the browser.

\n
\n
Terminal 1
\n
\n
$ cargo run -p traverse-cli -- \\
\n
browser-adapter serve --bind 127.0.0.1:4174
\n
\n
adapter listening on 127.0.0.1:4174
\n
registry loaded · 6 capabilities ready
\n
\n
\n

Leave this terminal running. Open a second one for the next step.

\n
\n\n \n
\n
\n
05
\n Run the React demo\n
\n

Start the React demo

\n

In a second terminal, start the React demo server. It connects to the browser adapter and serves the UI on port 4173.

\n
\n
Terminal 2
\n
\n
$ node apps/react-demo/server.mjs \\
\n
--adapter http://127.0.0.1:4174 \\
\n
--port 4173
\n
\n
demo ready → http://127.0.0.1:4173
\n
\n
\n
\n\n \n
\n
\n
06
\n Submit a governed request\n
\n

Open the browser and execute

\n

Open http://127.0.0.1:4173 and click \"Submit approved request\". The runtime will execute the full expedition planning workflow.

\n
\n
request payload
\n
\n
{\n  \"goal\": \"Plan a two-day alpine expedition\\nfor a four-person team.\",\n  \"requested_target\": \"local\",\n  \"caller\": \"browser_demo\"\n}
\n
\n
\n

You should see the status pill advance:

\n
\n
expected output
\n
\n
ready → streaming → completed
\n
\n
Runtime updates in ordered timeline:
\n
[1] interpret-expedition-intent ✓
\n
[2] capture-expedition-objective ✓
\n
[3] assess-conditions-summary ✓
\n
[4] validate-team-readiness ✓
\n
[5] assemble-expedition-plan ✓
\n
\n
Trace panel: capability · events · output
\n
\n
\n
\n\n \n
\n

Next steps

\n
\n \n

Core Concepts →

\n

Understand contracts, registry, runtime, placement, and trace artifacts.

\n \n \n

Examples →

\n

Deep dive into the expedition planning domain. Contracts, events, and the workflow graph.

\n \n \n

Platforms →

\n

Where Traverse actually runs today, honestly scored — native and browser shipped, Swift/Kotlin/.NET in progress.

\n \n
\n
\n
\n
\n\n"; --- - - - - - + + +
+
Getting started

Quickstart

+

Build the current runtime and inspect a governed bundle. This path works with Traverse v0.9.1 and Rust 1.94 or later.

+ 
git clone https://github.com/traverse-framework/traverse.git
+cd traverse
+cargo build
+cargo run -p traverse-cli-rs -- bundle inspect examples/expedition/registry-bundle/manifest.json
+

The inspection output identifies the expedition bundle and its registered capabilities, events, and workflow. From there, follow the maintained repository quickstart for browser, native embedder, and app-consumer paths.

+
Open the full quickstart →Read getting started
+

What to try next

+
+ diff --git a/src/pages/system.astro b/src/pages/system.astro index e99b033..452dc75 100644 --- a/src/pages/system.astro +++ b/src/pages/system.astro @@ -8,9 +8,9 @@ const _body = `

One workspace, nine crates, one governance layer.

Traverse isn't a single binary. It's a Rust workspace of purpose-built crates, each governed by an immutable, versioned spec, that together define, validate, place, and execute business capabilities. This is the map.

- v0.8.1 - 9 workspace crates - 73 approved specs + v0.9.1 + 8 workspace crates + 105 approved specs