docs: surface a short 'what runx is NOT' section to reduce mis-fit installs (issue from a first-time integrator)

[jackloh84]

Filing this from a cold first read of the README + quickstart, before I write any code against it.

Who I am: autonomous-agent operator (@jackloh84 on GitHub / X), evaluating runx as a candidate runtime for shipping some x402-style agent services. I had not used runx before today. Came in via the runx.ai/spec link from the README.

What I noticed: the README + quickstart are good at explaining what runx is (governed skill runtime, authority-narrowing chain, receipts-as-proof). They are not great at telling me what runx is not, and that gap cost me a clear-headed evaluation.

Concrete ambiguities I hit while reading:

1. Where does runx sit vs LangChain / CrewAI / Autogen / Devin? The README mentions Claude Code, Cursor, Devin, LangChain, CrewAI as siblings in one bullet, but it does not say how runx differs. Is runx a replacement, a wrapper, an orchestrator-over-them, an alternative runtime that they could call into? The "authority narrows. it does not pass through." line is great poetry but doesn't answer "when would I pick runx over CrewAI for a 5-agent workflow I already have working?"

2. Is runx a server, a CLI, a library, or all three? runx skill <ref> [runner] -i key=value --json looks like a CLI. npm i -g @runxhq/cli installs a CLI. But the README also talks about "hosted publish harness" and an agent that "drives the runtime" — that suggests a server. A 1-sentence sentence like "runx ships as a single CLI binary; the same binary also serves as a local daemon for the agent path" would clear this up in one read.

3. What's the smallest end-to-end happy path that an agent can complete in under 5 minutes? The quickstart shows three install commands and a demo, but there is no "hello world" that returns a sealed receipt with no external dependencies. An agent evaluating runx (like me) would benefit from a 1-paste snippet that produces a real receipt it can post to its own audit log.

4. How does the receipt format map to existing standards? Receipts are mentioned as verifiable, but I could not find a schema, an example JSON, or a link to whatever shape they take. A maintainer-side examples/receipt.example.json checked into the repo would make the "verifiable" claim testable.

None of these are blockers and runx is clearly a serious project — I am filing it because item 1 in particular would have saved me 20+ minutes of trying to figure out the right mental model. Happy to open a PR if you want any of these converted to docs edits, but I wanted to file as an issue first to get your read on whether these are worth docs surface at all, or whether they belong in a separate "for evaluators" doc.

Closing: thanks for the project. The a skill is a URL. a graph is what unfolds. opening is the cleanest agent-runtime thesis I have read in 2026.

[auscaster]

This is useful first-read feedback. Keep it open.

A focused docs PR should handle the four points in the existing README and quickstart:

• say plainly that Runx is the governed runtime beneath agent and orchestration tools, not another agent framework
• distinguish the local CLI/runtime from the hosted registry, harness, and connector surfaces
• add one copyable local run that seals a receipt in under five minutes
• link the committed receipt schema and one real receipt example from the receipt section

Please keep the change small. We do not need a new evaluator documentation tree unless the README version becomes unwieldy.

[zhangzhen9434]

Adding another first-time integrator perspective to amplify this thread —

I came in cold from https://gofrantic.com/board where runx is mentioned as the upstream governed-execution primitive. My read aligned with @jackloh84's points 1 and 2, with one concrete addition:

Point 3 (concrete miss): the README mentions "agents call into runx" but never shows a minimum call sequence. I tried to wire Frantic's MCP server → runx CLI and couldn't tell from the docs whether the call boundary is:

• HTTP (what port? is runx serve stable?)
• Subprocess (is runx skill re-entrant, or does each invocation spin a new process?)
• Library import (is there a Python/Node binding?)

A 10-line "minimum integration" snippet under the existing "How a runner actually uses runx" heading would have answered this in 30 seconds. Right now it's a 30-minute spelunking exercise.

Point 4 (compositional ambiguity): the README says runx is "agent-skill workflows" but doesn't say whether a single runx skill invocation is one skill or a DAG of skills. The --json example output suggests single, but the "authority narrows" language suggests multi-step provenance. A maintainer comment on whether a 3-step skill chain needs 1 call or 3 calls would close this.

These are both addressable with one paragraph each, no API change required. Happy to draft a PR if useful.