Ship uvx installer bootstrap for alpha release

Author: monarchjuno

MANIFEST.in

@@ -2,6 +2,7 @@ include LICENSE
 include NOTICE
 include CONTRIBUTING.md
 include TRADEMARKS.md
+include install.sh
 recursive-include assets *
 recursive-include docs *
 recursive-include workspace_templates *

README.md

@@ -32,43 +32,37 @@ the durable service layer, and TradingCodex MCP is the execution boundary.
 ## Quick Start
 
 ```bash
-uv python install 3.14
-uv tool install --python 3.14 tradingcodex
-uv tool update-shell
-export PATH="$HOME/.local/bin:$PATH"
-mkdir -p ~/tradingcodex-workspaces/apple-research
-cd ~/tradingcodex-workspaces/apple-research
-tcx init .
-./tcx doctor
+curl -fsSL https://raw.githubusercontent.com/monarchjuno/tradingcodex/main/install.sh | sh -s -- ~/tradingcodex-workspaces/apple-research
 ```
 
-Install the CLI as a user-level tool before creating a TradingCodex workspace.
-Do not clone this repository into the generated workspace. `tcx init .` expects
-the target directory to be empty, and the generated `./tcx` wrapper will remember
-the Python interpreter that created it.
+The command above bootstraps a clean TradingCodex workspace, runs `./tcx doctor`,
+and leaves the workspace ready to open in Codex. Do not clone this repository
+into the generated workspace. `tcx init` expects the target directory to be
+empty.
 
-To install the current GitHub `main` source without cloning it into the
-workspace, replace the `uv tool install` line with:
+To bootstrap from the current GitHub `main` source without cloning it into the
+workspace:
 
 ```bash
-uv tool install --python 3.14 --force \
-  "tradingcodex @ git+https://github.com/monarchjuno/tradingcodex.git@main"
+curl -fsSL https://raw.githubusercontent.com/monarchjuno/tradingcodex/main/install.sh | sh -s -- --from-github ~/tradingcodex-workspaces/apple-research
 ```
 
-For a one-shot bootstrap without installing `tcx` first, use `uvx`:
+The installer uses `uvx` for the bootstrap step. The direct equivalent is:
 
 ```bash
-uvx --python 3.14 --from tradingcodex tcx init .
+UV_NO_CACHE=1 uvx --isolated --refresh --python 3.14 --from tradingcodex tcx init ~/tradingcodex-workspaces/apple-research && cd ~/tradingcodex-workspaces/apple-research && ./tcx doctor
 ```
 
-`uv tool install` is preferred for normal use because it keeps the `tcx` command
-available after bootstrap.
+For repeated workspace creation, installing `tcx` as a user-level tool is still
+available:
 
-For persistent Codex workspaces, do not point TradingCodex MCP at `uvx`.
-Generated `.codex/config.toml` records the Python interpreter that ran
-`tcx init`, and that MCP server also autostarts the experimental local Django
-dashboard service. A stable `uv tool install` environment avoids resolving the
-package again every time Codex starts MCP.
+```bash
+uv python install 3.14 && uv tool install --python 3.14 tradingcodex && uv tool update-shell
+```
+
+Generated `.codex/config.toml` starts TradingCodex MCP with `uvx`, using the
+same package spec recorded at bootstrap time. That MCP startup also autostarts
+the experimental local Django dashboard service.
 
 Start an orchestrated Codex workflow from the generated workspace:
 

docs/core-concepts-and-rules.md

@@ -143,10 +143,12 @@ Fail closed: if subagent dispatch is unavailable, the workflow waits. `head-mana
   trusted.
 - The generated TradingCodex MCP config sets
   `TRADINGCODEX_MCP_AUTOSTART_SERVICE=1`, so trusted Codex sessions start the
-  MCP stdio bridge and the local Django dashboard service together. The
-  autostart path must be idempotent, must not write non-MCP output to stdout,
-  and must not be required for direct `./tcx mcp stdio` smoke checks.
-- Generated fixed-role subagent TOML files pin `model = "gpt-5.5"` and `reasoning_effort = "high"`; spawn by fixed role label so the role file supplies these runtime defaults.
+  MCP stdio bridge and the local Django dashboard service together. The MCP
+  command uses `uvx --from <package-spec> tcx mcp stdio`, and bootstrap records
+  the package spec so GitHub-source installs do not silently fall back to PyPI.
+  The autostart path must be idempotent, must not write non-MCP output to
+  stdout, and must not be required for direct `./tcx mcp stdio` smoke checks.
+- Generated fixed-role subagent TOML files pin `model = "gpt-5.5"` and `model_reasoning_effort = "high"`; spawn by fixed role label so the role file supplies these runtime defaults.
 - The root `head-manager` MCP allowlist intentionally excludes
   `submit_approved_order`, `cancel_approved_order`, and approval creation.
   `risk-manager` owns approval receipt creation; `execution-operator` owns

docs/deployment.md

@@ -133,7 +133,7 @@ python3.14 -m venv /tmp/tcx-testpypi
 /tmp/tcx-testpypi/bin/pip install \
   --index-url https://test.pypi.org/simple/ \
   --extra-index-url https://pypi.org/simple/ \
-  tradingcodex==0.1.0a3
+  tradingcodex==0.1.0a4
 rm -rf /tmp/tcx-testpypi-smoke
 mkdir -p /tmp/tcx-testpypi-smoke
 cd /tmp/tcx-testpypi-smoke
@@ -162,19 +162,28 @@ After the PyPI workflow completes:
 
 ```bash
 python3.14 -m venv /tmp/tcx-pypi
-/tmp/tcx-pypi/bin/pip install tradingcodex==0.1.0a3
+/tmp/tcx-pypi/bin/pip install tradingcodex==0.1.0a4
 rm -rf /tmp/tcx-pypi-smoke
 mkdir -p /tmp/tcx-pypi-smoke
 cd /tmp/tcx-pypi-smoke
 /tmp/tcx-pypi/bin/tcx init .
 ./tcx doctor
 ```
 
+Also verify the user-facing installer path:
+
+```bash
+rm -rf /tmp/tcx-install-sh-smoke
+sh ./install.sh --no-doctor /tmp/tcx-install-sh-smoke
+cd /tmp/tcx-install-sh-smoke
+./tcx doctor
+```
+
 ## Versioning
 
 Use PEP 440 versions:
 
-- `0.1.0a1`, `0.1.0a2`, `0.1.0a3` for alpha releases
+- `0.1.0a1`, `0.1.0a2`, `0.1.0a3`, `0.1.0a4` for alpha releases
 - `0.1.0b1` for beta releases
 - `0.1.0rc1` for release candidates
 - `0.1.0` only after install, docs, DB migration, and generated workspace

docs/tradingcodex-prd.md

@@ -272,10 +272,13 @@ Generated Codex workspaces also render a project-scoped
 OpenAI Codex MCP configuration shape: a stdio `command`, `args`, `enabled`,
 `env`, `enabled_tools`, `default_tools_approval_mode`, `startup_timeout_sec`,
 and `tool_timeout_sec`. Project-scoped Codex config applies only when the
-generated workspace is trusted by Codex. The TradingCodex MCP config sets
-`TRADINGCODEX_MCP_AUTOSTART_SERVICE=1`, so Codex MCP startup idempotently starts
-the local Django dashboard service at `127.0.0.1:8000` while keeping MCP stdio
-stdout clean. The root `head-manager` allowlist exposes research, audit,
+generated workspace is trusted by Codex. The generated TradingCodex MCP command
+uses `uvx --from <package-spec> tcx mcp stdio`, where the package spec is
+recorded during bootstrap so PyPI and GitHub-source installs keep the same MCP
+source. The TradingCodex MCP config sets `TRADINGCODEX_MCP_AUTOSTART_SERVICE=1`,
+so Codex MCP startup idempotently starts the local Django dashboard service at
+`127.0.0.1:8000` while keeping MCP stdio stdout clean. The root `head-manager`
+allowlist exposes research, audit,
 portfolio/status, and policy simulation tools, but excludes approval creation
 and execution submission. Role-scoped agent TOML files expose the narrower risky
 tools only to their owner roles: `risk-manager` can create approval receipts,
@@ -357,18 +360,19 @@ Codex-native bootstrap verification:
   role boundary.
 - `./tcx mcp stdio` `tools/list` verifies the TradingCodex MCP bridge and tool
   annotations, including `experimental = true` on execution tools.
-- Generated Codex MCP config starts the stdio MCP bridge and local dashboard
-  service together; direct `./tcx mcp stdio` remains service-free unless
-  `TRADINGCODEX_MCP_AUTOSTART_SERVICE=1` is set.
-- `codex mcp get tradingcodex` verifies Codex's own resolved MCP config only
-  after the generated workspace is a trusted Codex project; otherwise Codex may
-  show only user/global MCP servers.
+- Generated Codex MCP config starts the stdio MCP bridge through `uvx` and
+  starts the local dashboard service together; direct `./tcx mcp stdio` remains
+  service-free unless `TRADINGCODEX_MCP_AUTOSTART_SERVICE=1` is set.
+- `codex exec -C <workspace> --skip-git-repo-check ...` can verify that Codex
+  CLI loads the generated project context. The management command
+  `codex mcp list/get` may show only user/global MCP servers, even when a
+  session uses project-scoped MCP config after workspace trust.
 
 Generated workspaces contain:
 
 - one root `head-manager`
 - nine fixed subagents
-- fixed subagents configured for `model = "gpt-5.5"` and `reasoning_effort = "high"`
+- fixed subagents configured for `model = "gpt-5.5"` and `model_reasoning_effort = "high"`
 - twenty-one repo skills
 - information-barrier policies
 - order/approval schemas

install.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env sh
+set -eu
+
+PYTHON_VERSION="3.14"
+PACKAGE_SPEC="tradingcodex"
+WORKSPACE=""
+OVERWRITE="0"
+RUN_DOCTOR="1"
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  install.sh [options] <workspace>
+
+Options:
+  --from <package-spec>  Install from a PyPI name, path, URL, or PEP 508 spec.
+  --from-github         Install from monarchjuno/tradingcodex main.
+  --python <version>    Python version for uvx. Default: 3.14.
+  --overwrite           Pass --overwrite to tcx init.
+  --no-doctor           Skip ./tcx doctor after bootstrap.
+  -h, --help            Show this help.
+
+Examples:
+  install.sh ~/tradingcodex-workspaces/apple-research
+  install.sh --from-github ~/tradingcodex-workspaces/apple-research
+USAGE
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --from)
+      if [ "$#" -lt 2 ]; then
+        echo "install.sh: --from requires a package spec" >&2
+        exit 2
+      fi
+      PACKAGE_SPEC="$2"
+      shift 2
+      ;;
+    --from-github)
+      PACKAGE_SPEC="tradingcodex @ git+https://github.com/monarchjuno/tradingcodex.git@main"
+      shift
+      ;;
+    --python)
+      if [ "$#" -lt 2 ]; then
+        echo "install.sh: --python requires a version" >&2
+        exit 2
+      fi
+      PYTHON_VERSION="$2"
+      shift 2
+      ;;
+    --overwrite)
+      OVERWRITE="1"
+      shift
+      ;;
+    --no-doctor)
+      RUN_DOCTOR="0"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      echo "install.sh: unknown option: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+    *)
+      if [ -n "$WORKSPACE" ]; then
+        echo "install.sh: only one workspace path is supported" >&2
+        usage >&2
+        exit 2
+      fi
+      WORKSPACE="$1"
+      shift
+      ;;
+  esac
+done
+
+if [ -z "$WORKSPACE" ] && [ "$#" -gt 0 ]; then
+  WORKSPACE="$1"
+  shift
+fi
+
+if [ -z "$WORKSPACE" ]; then
+  usage >&2
+  exit 2
+fi
+
+ensure_uvx() {
+  if command -v uvx >/dev/null 2>&1; then
+    return 0
+  fi
+  if command -v uv >/dev/null 2>&1; then
+    return 0
+  fi
+  echo "install.sh: uv/uvx not found; installing uv into the user environment" >&2
+  if command -v curl >/dev/null 2>&1; then
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+  elif command -v wget >/dev/null 2>&1; then
+    wget -qO- https://astral.sh/uv/install.sh | sh
+  else
+    echo "install.sh: install uv first: https://docs.astral.sh/uv/" >&2
+    exit 127
+  fi
+  PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
+  export PATH
+  if ! command -v uvx >/dev/null 2>&1 && ! command -v uv >/dev/null 2>&1; then
+    echo "install.sh: uv installation finished, but uvx is still not on PATH" >&2
+    exit 127
+  fi
+}
+
+run_uvx() {
+  if command -v uvx >/dev/null 2>&1; then
+    uvx "$@"
+  else
+    uv tool run "$@"
+  fi
+}
+
+ensure_uvx
+
+echo "install.sh: bootstrapping TradingCodex workspace: $WORKSPACE" >&2
+echo "install.sh: package spec: $PACKAGE_SPEC" >&2
+TRADINGCODEX_MCP_PACKAGE_SPEC="$PACKAGE_SPEC"
+export TRADINGCODEX_MCP_PACKAGE_SPEC
+UV_NO_CACHE=1
+export UV_NO_CACHE
+
+if [ "$OVERWRITE" = "1" ]; then
+  run_uvx --isolated --refresh --python "$PYTHON_VERSION" --from "$PACKAGE_SPEC" tcx init "$WORKSPACE" --overwrite
+else
+  run_uvx --isolated --refresh --python "$PYTHON_VERSION" --from "$PACKAGE_SPEC" tcx init "$WORKSPACE"
+fi
+
+if [ "$RUN_DOCTOR" = "1" ]; then
+  (cd "$WORKSPACE" && ./tcx doctor)
+fi

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tradingcodex"
-version = "0.1.0a3"
+version = "0.1.0a4"
 description = "Codex-native trading harness with a Django service plane and MCP execution boundary."
 readme = "README.md"
 requires-python = ">=3.14,<3.15"

tests/test_python_migration.py

@@ -109,11 +109,12 @@ def test_python_generator_creates_workspace_contract(tmp_path: Path) -> None:
     stale_mcp_tool_names = {"evaluate_policy", "get_positions_snapshot", "write_audit_event"}
     root_config = tomllib.loads((workspace / ".codex" / "config.toml").read_text(encoding="utf-8"))
     root_mcp = root_config["mcp_servers"]["tradingcodex"]
-    assert root_mcp["command"] == sys.executable
-    assert root_mcp["args"] == [str(workspace / ".tradingcodex" / "mcp" / "server.py")]
+    assert root_mcp["command"] == "uvx"
+    assert root_mcp["args"] == ["--python", "3.14", "--from", "tradingcodex", "tcx", "mcp", "stdio"]
     assert root_mcp["enabled"] is True
     assert root_mcp["env"]["TRADINGCODEX_MCP_AUTOSTART_SERVICE"] == "1"
     assert root_mcp["env"]["TRADINGCODEX_SERVICE_ADDR"] == "127.0.0.1:8000"
+    assert root_mcp["env"]["TRADINGCODEX_WORKSPACE_ROOT"] == str(workspace)
     assert set(root_mcp["enabled_tools"]).issubset(actual_mcp_tools)
     assert stale_mcp_tool_names.isdisjoint(root_mcp["enabled_tools"])
     assert "simulate_policy" in root_mcp["enabled_tools"]
@@ -124,10 +125,13 @@ def test_python_generator_creates_workspace_contract(tmp_path: Path) -> None:
     for agent_file in agent_files:
         agent_config = agent_file.read_text(encoding="utf-8")
         assert 'model = "gpt-5.5"' in agent_config
-        assert 'reasoning_effort = "high"' in agent_config
+        assert 'model_reasoning_effort = "high"' in agent_config
         agent_toml = tomllib.loads(agent_config)
         agent_mcp = agent_toml["mcp_servers"]["tradingcodex"]
+        assert agent_mcp["command"] == "uvx"
+        assert agent_mcp["args"] == ["--python", "3.14", "--from", "tradingcodex", "tcx", "mcp", "stdio"]
         assert agent_mcp["env"]["TRADINGCODEX_MCP_AUTOSTART_SERVICE"] == "1"
+        assert agent_mcp["env"]["TRADINGCODEX_WORKSPACE_ROOT"] == str(workspace)
         configured_tools = set(agent_mcp.get("enabled_tools", [])) | set(agent_mcp.get("disabled_tools", []))
         assert configured_tools.issubset(actual_mcp_tools), agent_file
         assert stale_mcp_tool_names.isdisjoint(configured_tools), agent_file
@@ -185,7 +189,7 @@ def test_init_current_directory_and_overwrite_language(tmp_path: Path) -> None:
 
     assert f"TradingCodex workspace created: {workspace.resolve()}" in result.stdout
     assert (workspace / "tcx").exists()
-    assert json.loads((workspace / ".tradingcodex" / "generated" / "module-lock.json").read_text(encoding="utf-8"))["tradingcodex_version"] == "0.1.0a3"
+    assert json.loads((workspace / ".tradingcodex" / "generated" / "module-lock.json").read_text(encoding="utf-8"))["tradingcodex_version"] == "0.1.0a4"
 
     repeated = run([sys.executable, "-m", "tradingcodex_cli", "init", "."], workspace, expect_ok=False, env_extra=env_extra)
     assert "--overwrite" in repeated.stderr

tradingcodex_cli/generator.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import os
 import shutil
 import sys
 from dataclasses import dataclass
@@ -50,7 +51,8 @@ def bootstrap_workspace(project_dir: Path | str, force: bool = False, dry_run: b
         "SOURCE_ROOT": str(repo_root()),
         "PYTHON_EXECUTABLE": sys.executable,
         "GENERATED_AT": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
-        "TRADINGCODEX_VERSION": "0.1.0a3",
+        "TRADINGCODEX_VERSION": "0.1.0a4",
+        "TRADINGCODEX_MCP_PACKAGE_SPEC": os.environ.get("TRADINGCODEX_MCP_PACKAGE_SPEC", "tradingcodex"),
         "SUBAGENT_COUNT": str(len(subagents)),
     }
     result = {

tradingcodex_cli/workspace.py

@@ -221,7 +221,9 @@ def mcp(root: Path, argv: list[str]) -> None:
         return
     if argv and argv[0] == "stdio":
         from tradingcodex_cli.mcp_stdio import run_stdio
+        from tradingcodex_cli.service_autostart import maybe_autostart_service
 
+        maybe_autostart_service(root)
         run_stdio(root)
         return
     if argv and argv[0] in {"ledger", "calls"}: