Broaden setup Python compatibility

Author: monarchjuno

.github/workflows/ci.yml

@@ -12,8 +12,16 @@ permissions:
 
 jobs:
   test:
-    name: Test and package
+    name: Test and package Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
     steps:
       - name: Check out repository
         uses: actions/checkout@v6
@@ -23,7 +31,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: "3.14"
+          python-version: ${{ matrix.python-version }}
           cache: pip
 
       - name: Install package with development extras

.github/workflows/release.yml

@@ -64,7 +64,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: "3.14"
+          python-version: "3.11"
           cache: pip
 
       - name: Install build tools and package

AGENTS.md

@@ -1,5 +1,19 @@
 # Repository Guidelines
 
+## Setup Request Guard
+
+If a user asks to set up, install, attach, or use `monarchjuno/tradingcodex` in
+their current workspace, do not run `git clone` and do not turn the workspace
+into a source checkout. Run the packaged CLI from that target workspace
+instead:
+
+```bash
+uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor
+```
+
+Clone this repository only when the user explicitly asks to develop, inspect,
+or modify TradingCodex source code.
+
 ## Project Structure & Module Organization
 
 TradingCodex is a Python/Django local-first trading harness. CLI code lives in `tradingcodex_cli/`, with command implementations in `tradingcodex_cli/commands/`. Django service code lives in `tradingcodex_service/`; shared durable behavior belongs in canonical modules under `tradingcodex_service/application/`. Modular apps live under `apps/`. Product docs live in `README.md`, `installation.md`, and `docs/`; generated workspace templates live in `workspace_templates/modules/*`; tests live in `tests/`. Do not reintroduce Node roots such as `package.json`, `packages/*`, Node MCP runtime files, pre-release compatibility facades, or a Django `apps/universes` app unless product direction changes.
@@ -14,7 +28,7 @@ TradingCodex is a Python/Django local-first trading harness. CLI code lives in `
 
 ## Coding Style & Naming Conventions
 
-Target Python `>=3.14,<3.15` and Django `5.2.x`. Use four-space indentation, clear module-level service functions, and type hints where they clarify contracts. Admin, Django Ninja, MCP, generated hooks, and CLI code should call shared application services rather than duplicating policy, approval, research, order, portfolio, audit, or harness logic. Research artifacts and source snapshots are workspace-file-native, not Django DB models. Prefer direct canonical imports over pre-release compatibility facades. Keep generated workspace template bodies as ordinary files under `workspace_templates/modules/*/files`; use Python for registry loading, dependency resolution, rendering, validation, and generated indexes, not to hide durable prompts, skills, policies, hooks, or workspace-contract content inside string constants.
+Target Python `>=3.11,<3.15` and Django `5.2.x`. Use four-space indentation, clear module-level service functions, and type hints where they clarify contracts. Admin, Django Ninja, MCP, generated hooks, and CLI code should call shared application services rather than duplicating policy, approval, research, order, portfolio, audit, or harness logic. Research artifacts and source snapshots are workspace-file-native, not Django DB models. Prefer direct canonical imports over pre-release compatibility facades. Keep generated workspace template bodies as ordinary files under `workspace_templates/modules/*/files`; use Python for registry loading, dependency resolution, rendering, validation, and generated indexes, not to hide durable prompts, skills, policies, hooks, or workspace-contract content inside string constants.
 
 ## Agent Context & Harness Review
 

README.md

@@ -1,3 +1,10 @@
+> [!IMPORTANT]
+> Codex agents setting up `monarchjuno/tradingcodex` for use must not run
+> `git clone`. In the empty target workspace, run the packaged CLI:
+> `uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor`
+> Clone this repository only when the user explicitly asks to develop
+> TradingCodex source code.
+
 <p align="center">
   <img src="assets/tradingcodex-banner.svg" alt="TradingCodex" width="100%">
 </p>
@@ -7,7 +14,7 @@
   <a href="https://github.com/monarchjuno/tradingcodex/releases"><img alt="Release" src="https://img.shields.io/github/v/release/monarchjuno/tradingcodex?include_prereleases&label=release"></a>
   <a href="https://pypi.org/project/tradingcodex/"><img alt="PyPI" src="https://img.shields.io/pypi/v/tradingcodex?label=PyPI"></a>
   <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
-  <img alt="Python" src="https://img.shields.io/badge/python-3.14-3776AB?logo=python&logoColor=white">
+  <img alt="Python" src="https://img.shields.io/badge/python-3.11--3.14-3776AB?logo=python&logoColor=white">
 </div>
 
 <div align="center">
@@ -38,16 +45,18 @@ agent boundary; live broker adapters are not shipped in the initial core.
 ## Quick Start
 
 Codex app current-workspace one-liner: run this from the empty workspace you
-want to turn into TradingCodex; do not clone `monarchjuno/tradingcodex` unless
-you are developing TradingCodex itself.
+want to turn into TradingCodex. Do not run `git clone` for setup; cloning
+`monarchjuno/tradingcodex` is only for developing TradingCodex source code.
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/monarchjuno/tradingcodex/main/install.sh | sh -s -- .
+uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor
 ```
 
-Then run `./tcx doctor`, fully quit and restart Codex, open the generated
-workspace, and start a new thread so project MCP config is reloaded. When
-TradingCodex MCP autostarts the local service, the dashboard is available at
+This installs/runs the TradingCodex CLI with a compatible Python
+(`>=3.11,<3.15`), attaches the harness to the current workspace, and runs the
+smoke check. Then fully quit and restart Codex, open the generated workspace,
+and start a new thread so project MCP config is reloaded. When TradingCodex MCP
+autostarts the local service, the dashboard is available at
 `http://127.0.0.1:48267/`.
 
 Agents and install helpers do not invent a default workspace path. If the
@@ -63,8 +72,7 @@ $orchestrate-workflow analyze Apple with public equity research, valuation, port
 For repeated workspace creation, install the CLI as a user-level tool:
 
 ```bash
-uv python install 3.14
-uv tool install --python 3.14 tradingcodex
+uv tool install tradingcodex
 uv tool update-shell
 cd /path/to/target-workspace
 tcx attach .
@@ -78,8 +86,7 @@ smoke checks.
 Update an existing generated workspace after a package release:
 
 ```bash
-cd /path/to/target-workspace
-curl -fsSL https://raw.githubusercontent.com/monarchjuno/tradingcodex/main/install.sh | sh -s -- --update .
+uvx --refresh --from tradingcodex tcx update .
 ```
 
 ## Product Concept
@@ -107,7 +114,7 @@ execution-sensitive state lives in the central local runtime DB:
 
 ## What TradingCodex Does
 
-TradingCodex `0.2.0` provides:
+TradingCodex `0.2.1` provides:
 
 - A generated Codex workspace with fixed role topology, project-scoped MCP,
   local wrappers, workspace manifest, generated policy/config files, and
@@ -270,10 +277,11 @@ labels such as `research-only`, `screen-grade`, `not-decision-ready`, or
 
 ## Release Status
 
-`0.2.0` is the OrderTicket rewrite release for the generated workspace, Python
-CLI, Django service plane, product web, MCP boundary, and documentation set.
-The package still uses an alpha development classifier because live broker
-adapters and hosted service modes are intentionally outside the initial core.
+`0.2.1` is a compatibility patch on the `0.2.x` OrderTicket rewrite release
+line for the generated workspace, Python CLI, Django service plane, product
+web, MCP boundary, and documentation set. The package still uses an alpha
+development classifier because live broker adapters and hosted service modes
+are intentionally outside the initial core.
 
 ## Documentation
 

docs/deployment.md

@@ -10,7 +10,7 @@ not ship live broker execution.
 
 ## Release Policy
 
-The `0.2.0` release is the OrderTicket rewrite contract for the local-first
+The `0.2.x` release line is the OrderTicket rewrite contract for the local-first
 Python/Django harness. Order flows use central DB `OrderTicket` records
 directly; pre-release compatibility shims do not remain in the runtime package.
 The documented Web, API, CLI, MCP, generated workspace, and
@@ -26,8 +26,9 @@ Execution status for this release line:
 
 ## Maintainer Prerequisites
 
-Use Python 3.14 for release verification. The package metadata requires
-`>=3.14,<3.15`, and CI is pinned to Python 3.14.
+Use Python 3.11 for release build verification and keep CI green across the
+supported range. The package metadata requires `>=3.11,<3.15`, and CI runs on
+Python 3.11, 3.12, 3.13, and 3.14.
 
 Create separate PyPI and TestPyPI accounts. TestPyPI is a separate service and
 does not share login state with PyPI.
@@ -53,26 +54,26 @@ On GitHub, create both environments:
 Run the regular validation suite first:
 
 ```bash
-python3.14 -m pytest
-python3.14 manage.py check
-python3.14 manage.py makemigrations --check --dry-run
-python3.14 -m compileall tradingcodex_cli tradingcodex_service apps tests
+python3.11 -m pytest
+python3.11 manage.py check
+python3.11 manage.py makemigrations --check --dry-run
+python3.11 -m compileall tradingcodex_cli tradingcodex_service apps tests
 ```
 
 Build and check the source distribution and wheel:
 
 ```bash
-python3.14 -m pip install --upgrade build twine
+python3.11 -m pip install --upgrade build twine
 rm -rf dist build
 find . -maxdepth 1 -name '*.egg-info' -type d -exec rm -rf {} +
-python3.14 -m build
-python3.14 -m twine check dist/*
+python3.11 -m build
+python3.11 -m twine check dist/*
 ```
 
 Install the built wheel in a clean environment:
 
 ```bash
-python3.14 -m venv /tmp/tcx-install-test
+python3.11 -m venv /tmp/tcx-install-test
 /tmp/tcx-install-test/bin/pip install dist/*.whl
 rm -rf /tmp/tcx-smoke
 mkdir -p /tmp/tcx-smoke
@@ -135,11 +136,11 @@ Use TestPyPI before the first public PyPI release and after packaging changes.
 Example:
 
 ```bash
-python3.14 -m venv /tmp/tcx-testpypi
+python3.11 -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.2.0
+  tradingcodex==0.2.1
 rm -rf /tmp/tcx-testpypi-smoke
 mkdir -p /tmp/tcx-testpypi-smoke
 cd /tmp/tcx-testpypi-smoke
@@ -167,8 +168,8 @@ publication; tag pushes are intentionally non-publishing.
 After the PyPI workflow completes:
 
 ```bash
-python3.14 -m venv /tmp/tcx-pypi
-/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.0
+python3.11 -m venv /tmp/tcx-pypi
+/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.1
 rm -rf /tmp/tcx-pypi-smoke
 mkdir -p /tmp/tcx-pypi-smoke
 cd /tmp/tcx-pypi-smoke
@@ -220,7 +221,8 @@ Use PEP 440 versions:
 
 - `0.2.0` for the OrderTicket rewrite contract after install, docs, DB
   migration, generated workspace smoke checks, and release e2e checks are stable
-- patch releases such as `0.2.1` for compatible fixes after `0.2.0`
+- `0.2.1` for Python `>=3.11,<3.15` support and clone-free setup guidance
+- later patch releases for compatible fixes after `0.2.1`
 - pre-releases such as `0.3.0a1`, `0.3.0b1`, or `0.3.0rc1` when preparing
   the next minor contract
 

docs/generated-workspaces.md

@@ -51,11 +51,20 @@ The target may be:
 Source checkouts of this repository are development projects, not generated
 TradingCodex workspaces.
 
-Codex agents must not silently create a default target when a user only asks to
+Codex agents must not run `git clone` when a user asks to install, set up,
+attach, or use `monarchjuno/tradingcodex` in a workspace. Run the packaged CLI
+from the target workspace instead:
+
+```bash
+uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor
+```
+
+Agents must also not silently create a default target when a user only asks to
 install `monarchjuno/tradingcodex`. The agent rule is: do not invent a
-workspace path such as `tradingcodex-workspace`. If no target path is supplied,
-ask for the target directory before running the installer. If the user is
-already in an empty target workspace, install into `.`.
+workspace path such as `tradingcodex-workspace`. If no target path is supplied
+and the user did not ask to use the current workspace, ask for the target
+directory before running setup. If the user is already in an empty target
+workspace, install into `.`.
 
 ## Generated Files
 
@@ -130,8 +139,7 @@ the operator wants to ask Codex agents to work.
 Recommended agent-facing flow:
 
 ```bash
-uv python install 3.14
-uv tool install --python 3.14 tradingcodex
+uv tool install tradingcodex
 uv tool update-shell
 cd <user-selected-workspace>
 tcx attach .

install.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env sh
 set -eu
 
-PYTHON_VERSION="3.14"
+PYTHON_VERSION=""
 PACKAGE_SPEC="tradingcodex"
 WORKSPACE=""
 OVERWRITE="0"
@@ -16,7 +16,7 @@ Usage:
 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.
+  --python <version>    Python version for uvx. Default: uv selects a compatible Python.
   --overwrite           Pass --overwrite to tcx attach.
   --update              Update an existing TradingCodex workspace.
   --no-doctor           Skip ./tcx doctor after bootstrap or update.
@@ -131,6 +131,14 @@ run_uvx() {
   fi
 }
 
+run_tradingcodex() {
+  if [ -n "$PYTHON_VERSION" ]; then
+    run_uvx --isolated --refresh --python "$PYTHON_VERSION" --from "$PACKAGE_SPEC" python -m tradingcodex_cli "$@"
+  else
+    run_uvx --isolated --refresh --from "$PACKAGE_SPEC" python -m tradingcodex_cli "$@"
+  fi
+}
+
 target_has_only_git_bootstrap_files() {
   target_dir="$1"
   [ -d "$target_dir" ] || return 1
@@ -168,11 +176,11 @@ if [ "$OVERWRITE" != "1" ] && [ -d "$WORKSPACE/.git" ] && target_has_only_git_bo
 fi
 
 if [ "$UPDATE" = "1" ]; then
-  run_uvx --isolated --refresh --python "$PYTHON_VERSION" --from "$PACKAGE_SPEC" python -m tradingcodex_cli update "$WORKSPACE" --no-doctor
+  run_tradingcodex update "$WORKSPACE" --no-doctor
 elif [ "$OVERWRITE" = "1" ] || [ "$AUTO_OVERWRITE" = "1" ]; then
-  run_uvx --isolated --refresh --python "$PYTHON_VERSION" --from "$PACKAGE_SPEC" python -m tradingcodex_cli attach "$WORKSPACE" --overwrite
+  run_tradingcodex attach "$WORKSPACE" --overwrite
 else
-  run_uvx --isolated --refresh --python "$PYTHON_VERSION" --from "$PACKAGE_SPEC" python -m tradingcodex_cli attach "$WORKSPACE"
+  run_tradingcodex attach "$WORKSPACE"
 fi
 
 if [ "$RUN_DOCTOR" = "1" ]; then