Quickstart

Rimthan is a stateless MCP workflow engine. Admins author step-gate workflows in Workflow Studio, publish signed immutable releases through the Admin API and PostgreSQL, and participants use exactly four read-only MCP tools from their existing agent harness. The harness owns all local writes and native subagent execution; Rimthan validates contracts and returns one permitted next step.

Start with Participant Architecture for the system boundary, then use the task table below to jump to the owner page for a change.

Wiki map

Section	Use it for
Participant Architecture	Current system view, trust boundaries, write plane versus participant action plane, and legacy boundary.
Four-Tool Workflow Protocol	rimthan.start_workflow, rimthan.continue_workflow, rimthan.prepare_step_validation, rimthan.submit_step_validation, progression statuses, deterministic validation, semantic report loop, and migration.
Checkpoints and Participant Data Perimeter	HMAC checkpoint tokens, validation bundles, key rotation, pinned-release resume, and transient artifact/report handling.
Resources, Prompts, and Host Adapters	Immutable MCP Resources, bootstrap prompt/resource, Codex/Claude Code/Cowork/Buzz adapter contracts, capabilities, and attestations.
Admin API	Authenticated write API, draft/revision routes, validation preview, publish, release detail, channels, trust root, CORS/auth/actor behavior.
Publication Pipeline	PublicationService, compilers, manifest v2 aggregate releases, signing, idempotency, activation, and rollback.
PostgreSQL Store	Migrations, roles, draft/revision tables, immutable release/artifact/source rows, triggers, channel generations, database-backed MCP.
Workflow Studio Architecture	Next.js app, session route, BFF boundary, lib/api.ts, TypeScript domain split, and state model.
Workflow Editor and Release UI	React Flow canvas, step editor, asset/validator sheets, immutable history, validation-before-publish release drawer, Playwright coverage.
Workflow Schemas and Starter	JSON Schema ownership, SchemaStore, engine-draft invariants, checkpoint/validation schemas, packaged research-decision starter.
Release Trust and Loader	ReleaseLoader, canonical JSON, path/digest checks, Ed25519 trust roots, signature payload, local versus published release semantics.
Legacy Local Registry and Pilot	Legacy module graph, operator MCP profiles/tools/prompts/resources, local materializer, progress/revision manager, pilot/readiness/research renderer.
Development, Testing, and Deployment	Setup commands, focused test routing, PostgreSQL integration DSNs, deployment env groups, bearer/OIDC modes, and release gates.

Task routing

Change intent	Read first	Source entrypoints and symbols	Focused tests	Minimal validation
Change the participant workflow protocol	Four-Tool Workflow Protocol	src/rimthan_workflow_mcp/workflow_engine.py::WorkflowEngineQueryModule, tool_contracts.py::workflow_engine_tool_contracts, server.py::create_mcp_application	tests/test_workflow_engine.py	uv run pytest tests/test_workflow_engine.py -k complete_stateless_validation_loop
Adjust checkpoint signing, resume, or data retention	Checkpoints and Participant Data Perimeter	WorkflowTokenSigner, parse_workflow_verification_keys, _verify_checkpoint, _McpStateProvider.for_tool_call	tests/test_workflow_engine.py	uv run pytest tests/test_workflow_engine.py -k "checkpoint or transient or pinned_release"
Add or change host adapter behavior	Resources, Prompts, and Host Adapters	workflow_engine.py::_host_blockers, _step_payload, _validate_host_attestation; starter assets	tests/test_workflow_engine.py	uv run pytest tests/test_workflow_engine.py -k "adapter or setup_attestation or repository_policy"
Change workflow schemas or starter workflow	Workflow Schemas and Starter	schemas/*.schema.json, rimthan_workflow_registry.workflow_engine.validate_engine_draft, starter/workflow-engine/	tests/test_schema_validation.py, tests/test_workflow_engine.py, tests/test_starter.py	uv run pytest tests/test_schema_validation.py tests/test_starter.py tests/test_workflow_engine.py -k engine_draft
Change Admin API routes or auth	Admin API	src/rimthan_admin_api/server.py::AdminApiConfig, AdminAuthAndLimitMiddleware, create_admin_app	tests/test_admin_api.py	RIMTHAN_TEST_ADMIN_POSTGRES_DSN=... uv run pytest tests/test_admin_api.py
Change publication or signing	Publication Pipeline and Release Trust and Loader	PublicationService.publish, WorkflowEngineDraftCompiler, WorkflowDraftCompiler, Ed25519ManifestSigner, trust.py	tests/test_workflow_publication.py, tests/test_trust.py, tests/test_workflow_engine.py	uv run pytest tests/test_workflow_publication.py tests/test_trust.py
Change PostgreSQL migrations or store behavior	PostgreSQL Store	PostgresRegistryStore, src/rimthan_publication/migrations/*.sql	tests/test_postgres_publication_e2e.py, tests/test_admin_api.py	RIMTHAN_TEST_POSTGRES_DSN=... uv run pytest tests/test_postgres_publication_e2e.py
Change Studio data loading/session/BFF	Workflow Studio Architecture	apps/admin-web/app/page.tsx, app/api/session/route.ts, lib/api.ts, lib/types.ts	apps/admin-web/tests/studio.spec.ts	cd apps/admin-web && pnpm typecheck && pnpm build
Change Studio canvas, drawers, release UI	Workflow Editor and Release UI	WorkflowCanvas.tsx, WorkflowStepEditorSheet.tsx, WorkflowReleaseSheet.tsx, editor sheets	apps/admin-web/tests/studio.spec.ts	cd apps/admin-web && pnpm test:e2e
Work on legacy operator/local tooling	Legacy Local Registry and Pilot	RimthanMcpQueryModule, WorkflowResolver, ProjectMaterializer, ProgressLedger, ProjectRevisionManager, ResearchDecisionParticipantPresenter, pilot.py, renderer.py	legacy-focused tests	uv run pytest tests/test_mcp.py tests/test_resolver.py tests/test_materializer.py tests/test_progress.py tests/test_revision.py tests/test_participant.py tests/test_pilot.py
Deploy or review staging readiness	Development, Testing, and Deployment	deploy/workflow-studio/env.example, http_server.py::RemoteHttpConfig, docs/operations/*	backend and Studio suites plus deployment evidence	uv run pytest && (cd apps/admin-web && pnpm typecheck && pnpm build)

Core concepts

• Step-gate workflow: a versioned workflow definition with one setup-workspace entry step, ordered steps, declared outputs, host assets, validators, and deterministic branches.
• Immutable release: a signed registry snapshot whose manifest pins every module, workflow, step, asset, schema, and validator by exact bytes and digest.
• Client-carried checkpoint: a signed envelope the harness persists at .rimthan/workflow-session.json; it contains release/step lineage and digests, not participant artifact bodies.
• Deterministic validation: server-side checks over exact JSON/Markdown artifact bytes, paths, schemas, attestations, capabilities, and repository policy before semantic review.
• Semantic validation: host-native subagents run pinned instructions with declared read-only inputs and return structured reports; Rimthan verifies report bindings but does not make the semantic judgment.
• Legacy boundary: the local module registry, materializer, operator MCP, and pilot tooling remain supported but must not override the current remote workflow-engine participant contract.

Backlog and valid deferrals

• No source area in the requested scope was intentionally deferred.
• The Next.js dynamic catch-all BFF file path contains bracket syntax that the filesystem reader rejected during evidence gathering. Its behavior is still documented from literal grep evidence, lib/api.ts, app/api/session/route.ts, deploy/workflow-studio/env.example, and Playwright route mocks.