feat(python): make Vyral one command from source

PUBLIC-EXPORT-MANIFEST.json

@@ -1,5 +1,5 @@
 {
-  "fileCount": 817,
+  "fileCount": 818,
   "files": [
     {
       "mode": "644",
@@ -129,7 +129,7 @@
     {
       "mode": "644",
       "path": "README.md",
-      "sha256": "bbd9eaf054e2b410ab51ba9e044a9bfbccb6a24b6ef1430bd7afb84adb35190a"
+      "sha256": "191c7f8726bad2524ef718924f2c9839b1d371d42f9393704ea6a16d81dae14e"
     },
     {
       "mode": "644",
@@ -604,7 +604,7 @@
     {
       "mode": "644",
       "path": "examples/README.md",
-      "sha256": "48b5631d176c0a2102c01201d10144154624672eaf53096373e5335caba18e11"
+      "sha256": "2524b7193da3804fafc8c527739c42fd9e7cdb9bc942ed821670c6e0b1cae6ce"
     },
     {
       "mode": "644",
@@ -659,7 +659,7 @@
     {
       "mode": "644",
       "path": "runtimes/python/README.md",
-      "sha256": "2951f22ee69530a85f486dfd53e32408a0ae5c1cfbfef8fead446f3c47debc0e"
+      "sha256": "fb3358a624bfe57f27b4b1b04c7db9ec36be375d847b92c0b7c4d832ed9d585f"
     },
     {
       "mode": "644",
@@ -679,7 +679,7 @@
     {
       "mode": "644",
       "path": "runtimes/python/pyproject.toml",
-      "sha256": "f1cee92bb54f219014ec84bcd167ba9d0c32231c517968a90bededf7e1490e99"
+      "sha256": "525a7e612bf44aafaa29df37ce29e4f0191a3c45a29191523746cd4322b1a70b"
     },
     {
       "mode": "644",
@@ -979,7 +979,7 @@
     {
       "mode": "644",
       "path": "runtimes/python/src/vyral_runtime/host/cli.py",
-      "sha256": "1040cf0cecdd429197662cf2365047787ebbcf6b3faf532e8849cebdcac1a609"
+      "sha256": "a4216db3116918da043902525d84a8a73a1d9563e016b933310818636de813f0"
     },
     {
       "mode": "644",
@@ -1194,7 +1194,7 @@
     {
       "mode": "644",
       "path": "runtimes/python/tests/test_host_cli.py",
-      "sha256": "c6292c36a7b9c7d5c03f55c4a46b72d7489abee54f3011dad1a93a01b36024e2"
+      "sha256": "38776f48036cd936a80a95e99a71361e290362d03c79caa37ad05c68243731cc"
     },
     {
       "mode": "644",
@@ -1509,7 +1509,7 @@
     {
       "mode": "755",
       "path": "scripts/test-built-sdk-python-runtime.sh",
-      "sha256": "fef6f538284bef212589dfb6f36aa9864b93325a54ed0a6dd3773e9787e383eb"
+      "sha256": "4ffe5e55952ea71f8fa32005a123a325d8c41f1dbe5e75c41d9291fcd5a69df3"
     },
     {
       "mode": "755",
@@ -1714,7 +1714,7 @@
     {
       "mode": "755",
       "path": "scripts/verify-python-runtime-mcp-conformance.sh",
-      "sha256": "226c47e6027c4396779daa94cf47e9a2c9f8dacc266ac707090ef5b0ab2a55ea"
+      "sha256": "ec5ae1e62448f8a212cd60168a1af3c373ab046646f3692453577e7b23097e29"
     },
     {
       "mode": "644",
@@ -1734,12 +1734,12 @@
     {
       "mode": "755",
       "path": "scripts/verify-python-runtime.sh",
-      "sha256": "cb0c27829555b34ab3f7cdd6b21bcbdf7b99b164644d56e6a82c7b33945342b2"
+      "sha256": "fbd9cd085eff6803debdad5bc52407a85d99fc5f2b9bae3d5b9de167f59b8e63"
     },
     {
       "mode": "755",
       "path": "scripts/verify-release-artifacts.sh",
-      "sha256": "307ac0f94e51e6bac32fb6dfd52eb2f90d3a49f4cbfec845f881b93bf8574588"
+      "sha256": "37656bb728e094285b4915f11044fea227cc1c3c34d1497ad8cbde425090d0a6"
     },
     {
       "mode": "755",
@@ -1751,6 +1751,11 @@
       "path": "scripts/verify-version-policy.py",
       "sha256": "67f8af6f4a2cbc95c53ac71a61c18482b672e253ab8da36eab6e97f40a9e9f99"
     },
+    {
+      "mode": "755",
+      "path": "scripts/vyral",
+      "sha256": "6e9c31b95f0914c940dd30c9e587241eae45879270dc6fa16d37262bebaac232"
+    },
     {
       "mode": "755",
       "path": "scripts/with-local-cuda-libs.sh",
@@ -4089,5 +4094,5 @@
   ],
   "schemaVersion": 1,
   "sourceDirty": false,
-  "treeSha256": "27bea22ce5088757200df47d504dbeb8bca99315e7a69fb6a631085500f9bab8"
+  "treeSha256": "c5bb3835cc777c1ecdb5ca506913cd8f386ec756e56fa16af7695e2dd4588df8"
 }

README.md

@@ -23,6 +23,34 @@ for SQLite, Postgres/pgvector, Azure, AWS, Google Cloud, Cloudflare, Temporal,
 and others. Conformance tests and a versioned qualification matrix make adapter
 behavior explicit instead of assumed.
 
+## Quick start
+
+From a source checkout, run:
+
+```bash
+./scripts/vyral
+```
+
+That is the complete local path. It needs only Python 3.10 or newer—no package
+installation, .NET SDK, container runtime, cloud account, external service, or
+model download. It runs retrieval with citations, admits durable work, closes
+and reopens the runtime, and completes the preserved run. State remains visible
+under `./.vyral/quickstart`.
+
+Create a small editable application when you are ready to build:
+
+```bash
+./scripts/vyral init
+python ./vyral_app.py
+```
+
+The installed command is simply `vyral`; `vyral-runtime` remains a compatibility
+alias and the distribution name. Use `./scripts/vyral inspect` to explain the
+local providers and limitations. Windows users can invoke the source launcher
+with `python scripts/vyral`. Manual installation, custom state paths, JSON
+output, reset, and server instructions are in the
+[Python runtime guide](runtimes/python).
+
 | You need… | Start here |
 | --- | --- |
 | Local RAG / retrieval substrate | [Quick start](#quick-start) |
@@ -73,71 +101,7 @@ A package existing in the repository is not a production-readiness claim. The
 [qualification report](qualification/adapter-qualification.json) is the source
 of truth for recorded evidence.
 
-## Quick start
-
-The shortest path is the embedded Python runtime. It needs no .NET SDK,
-container runtime, cloud account, external service, or model download. From a
-source checkout, create an isolated environment and install the runtime:
-
-```bash
-python3 -m venv .venv
-. .venv/bin/activate
-python -m pip install --editable runtimes/python
-```
-
-Run the complete local retrieval-and-durable-execution proof:
-
-```bash
-vyral-runtime quickstart
-```
-
-It ingests a small corpus, prints citation-ready context and the active
-model-free local embedding shape, admits an idempotent durable handler before
-dispatch, closes the runtime, reopens the same directory, and completes the
-same run identity. State stays visible under `./.vyral/quickstart`. Inspect its
-providers, topology, readiness, and limitations without rerunning it:
-
-```bash
-vyral-runtime inspect
-```
-
-When you are ready to own the code, generate the smallest editable application:
-
-```bash
-vyral-runtime init
-python ./vyral_app.py
-```
-
-The generated file uses the concise `@vyral(...)` authoring surface, prints a
-durable receipt before dispatch, closes and reopens its local runtime, and then
-completes the preserved run. Rerunning it replays the same idempotent run
-instead of dispatching duplicate work. The generator never overwrites an
-existing path and keeps state beside the file under `.vyral/vyral_app`.
-After editing the intended work, increment the visible `RUN_VERSION` to admit a
-new idempotent run. `--path` and `--root` remain available when you want
-different code or state locations.
-
-Add `--json` to the quickstart to capture machine-readable first-citation,
-durable-receipt, restart-recovery, and completion timings. Clean wheel and
-source-distribution qualification generates and runs the editable application
-as well as the connected quickstart in isolated environments. It enforces a
-five-minute package-install-to-useful-result budget rather than relying on a
-synthetic import smoke.
-
-The quickstart owns only the directory bearing its marker. Its reset command
-refuses foreign, symbolic-link, home, filesystem-root, and working-directory
-targets:
-
-```bash
-vyral-runtime quickstart --reset
-```
-
-Package publication is still withheld, so the editable source install above is
-the public pre-release path. The deterministic token-hash provider demonstrates
-bounded local mechanics and lexical similarity; it is not presented as a
-semantic model.
-
-### Local REST and client examples
+## Server and client examples
 
 To exercise the server boundary instead, start the .NET host from the
 repository root:
@@ -158,7 +122,7 @@ node examples/javascript/rag-quickstart.mjs
 Set `VYRAL_URL` to use a different host. More complete retrieval, GraphRAG, AI,
 and execution examples live in [examples](examples) and [samples](samples).
 
-### Container
+## Container
 
 The server image is non-root, shell-free, and compatible with a read-only root
 filesystem. This local command keeps state in a Docker-managed volume:

examples/README.md

@@ -1,13 +1,10 @@
 # Vyral Examples
 
-For the no-server, no-.NET local path, install the embedded Python runtime and
-run its connected retrieval and durable-restart experience:
+For the no-server, no-.NET local path, run the embedded Python experience
+directly from the repository root:
 
 ```bash
-python3 -m venv .venv
-. .venv/bin/activate
-python -m pip install --editable runtimes/python
-vyral-runtime quickstart
+./scripts/vyral
 ```
 
 The remaining examples exercise the local HTTP boundary intended for Python

runtimes/python/README.md

@@ -55,18 +55,29 @@ silently delegate embedded behavior to .NET or to the existing HTTP client.
 
 ## Local single-player experience
 
-From the repository root, install the package into an isolated environment:
+From the repository root, the shortest path runs directly from source:
+
+```bash
+./scripts/vyral
+```
+
+It performs the connected retrieval-and-execution proof described below. No
+installation or third-party service is required. Use `python scripts/vyral` on
+Windows.
+
+To install the command into an isolated environment instead:
 
 ```bash
 python3 -m venv .venv
 . .venv/bin/activate
 python -m pip install --editable runtimes/python
 ```
 
-Run the connected retrieval-and-execution proof:
+The installed command is `vyral`, and running it without arguments performs the
+same proof:
 
 ```bash
-vyral-runtime quickstart
+vyral
 ```
 
 The quickstart creates and ingests a three-document corpus, returns cited hybrid
@@ -82,20 +93,20 @@ for local development; its ranking is not a semantic-model quality claim.
 Inspect the state and its material limitations independently:
 
 ```bash
-vyral-runtime inspect
+vyral inspect
 ```
 
 The quickstart records an ownership marker and will reset only a dedicated
 directory bearing that marker:
 
 ```bash
-vyral-runtime quickstart --reset
+vyral quickstart --reset
 ```
 
 Generate one editable application when you are ready to own the code:
 
 ```bash
-vyral-runtime init
+vyral init
 python ./vyral_app.py
 ```
 
@@ -110,10 +121,10 @@ work to admit a new run. Use `--path` or `--root` when you need non-default code
 or state locations.
 
 Use `--json` with `init`, `quickstart`, or `inspect` for machine-readable
-output. Package publication remains withheld, so the editable install is the
-supported public pre-release path. Once a qualified wheel is published, the
-install command can be replaced with `python -m pip install vyral-runtime`
-without changing the local commands.
+output. `vyral-runtime` remains a compatibility alias. Package publication is
+withheld, so direct source use or the editable install is the public pre-release
+path. Once a qualified wheel is published, the install command can be replaced
+with `python -m pip install vyral-runtime` without changing the local commands.
 
 The quickstart JSON includes measured `firstCitationMs`, `durableReceiptMs`,
 `restartRecoveryMs`, and `completedMs` milestones. Artifact qualification runs
@@ -248,7 +259,7 @@ Install the server extra and choose an explicit durable directory:
 ```bash
 python -m pip install "vyral-runtime[server]"
 export VYRAL_API_KEY="replace-with-a-secret"
-vyral-runtime --root ./.vyral --host 127.0.0.1 --port 5220
+vyral serve --root ./.vyral --host 127.0.0.1 --port 5220
 ```
 
 REST is available at the public OpenAPI paths and stateless MCP at `/mcp`.

runtimes/python/pyproject.toml

@@ -40,6 +40,7 @@ dev = [
 ]
 
 [project.scripts]
+vyral = "vyral_runtime.host.cli:main"
 vyral-runtime = "vyral_runtime.host.cli:main"
 
 [project.urls]