TangleML · Volv-G · Jul 5, 2026 · Jul 5, 2026
@@ -103,6 +103,10 @@ uv run tangle sdk pipelines validate pipeline.yaml
 
 Custom API/codegen users can still run codegen from the fully capable install; generating bindings does not require removing the official `tangle-api` package. For project-local generated APIs, generate into a local source tree such as `src/tangle_api/generated` (and `src/tangle_api/schema/openapi.json` when you want `tangle api --schema-source official`) and run from that project so local `src/tangle_api` shadows site-packages. For packaged custom APIs, publish/provide a distribution named `tangle-api` with a version compatible with this `tangle-cli` release (for example `0.0.1a3+yourorg` for a `tangle-cli` dependency on `tangle-api==0.0.1a3`) via a private index, `--find-links`, or uv sources. As an expert escape hatch, `--no-deps` installs only `tangle-cli` and skips all dependencies, so that environment must manually provide every required runtime dependency plus its generated/custom `tangle_api`; this is acceptable for controlled codegen/custom scenarios but not normal UX.
 
+## Agent skills
+
+This repo includes the Tangent agent-skill bundle under `skills/tangent/`. The bundle was ported from `tangle-cli-lab` and now treats this repository as the canonical source. It drives the public `tangle` / `tangle-cli` command surface, assumes the default `tangle-cli` install includes `tangle-api`, and keeps relative references (`agents/*.md`, `references/*.md`) self-contained for Pi-style skill loaders. The source distribution includes `skills/**` so downstream source-based consumers can inspect or vendor the skill docs with the release.
+
 ## Quick command examples
 
 Local-only SDK commands:

@@ -42,6 +42,7 @@ build-backend = "uv_build"
 
 [tool.uv.build-backend]
 module-root = "packages/tangle-cli/src"
+source-include = ["skills/**"]
 
 [tool.uv.sources]
 cloud-pipelines-backend = { git = "https://github.com/TangleML/tangle", rev = "stable_cli" }

@@ -19,7 +19,9 @@ and `api`) and **never** any internal wrapper/hook layer.
 
 ## 1. Invocation rule
 
-**Run every command as `uv run tangle …` from a checkout of the `tangle-cli` repo.**
+**Keep checkout/dev invocation separate from installed-tool invocation.**
+
+From a checkout of the `tangle-cli` repo, run commands through the workspace:
 
 ```bash
 uv run tangle quickstart
@@ -28,20 +30,31 @@ uv run tangle sdk --help
 uv run tangle api --help
 ```
 
+For a persistent user-level CLI install, prefer uv tools:
+
+```bash
+uv tool install tangle-cli
+tangle quickstart
+tangle-cli --help
+```
+
+For one-off execution without a persistent install, use `uvx`:
+
+```bash
+uvx --from tangle-cli tangle --help
+```
+
+Generic Python environments may also use `pip install tangle-cli`; use
+`uv pip install tangle-cli` only inside an explicitly managed virtualenv.
+
 - **Never** prefix a command with an internal env-shim exec wrapper. That internal
   dev-env tooling must not appear in any ported file.
-- As of 2026-06-12 `tangle-cli` is **not yet a public PyPI package** (it is
-  consumed internally as a vendored git submodule). So install text must say
-  `uv run tangle …` **from a checkout**. Present the public install path only as a
-  future state:
-
-  > *Once `tangle-cli` is promoted to the public OSS package, you will be able to
-  > `pip install 'tangle-cli[native]'` and invoke `tangle …` directly. Until then,
-  > use `uv run tangle …` from a checkout of the repo.*
-
-- The `[native]` extra is what enables the static API-backed commands and the
-  handwritten `TangleApiClient` wrapper (see §3). In the `tangle-cli` workspace, `uv`
-  installs the workspace `tangle-api` package automatically for dev/tests.
+- `tangle-cli` is a public PyPI package. The default install includes the
+  matching `tangle-api` package and supports static API-backed commands plus the
+  handwritten `TangleApiClient` wrapper (see §3). The old `[native]` extra is
+  only a compatibility/no-op alias.
+- In the `tangle-cli` workspace, `uv` installs the workspace `tangle-api` package
+  automatically for dev/tests.
 - Help is standard cyclopts `--help`. **There is no `--help-extended` / `--help-full`.**
 - Skills live **in-repo** (checked into the `tangle-cli` repo). There is **no internal
   bundle-refresh step**; relative cross-references (`agents/*.md`, `references/*.md`)
@@ -61,7 +74,7 @@ OSS replacement. **Verbs/flags below were verified against the `tangle-cli` sour
 
 | Internal | OSS |
 |---|---|
-| `<env-shim> -- <deploy-cli> …` | `uv run tangle …` (or installed `tangle …` once promoted) |
+| `<env-shim> -- <deploy-cli> …` | `uv run tangle …` from a checkout, or installed `tangle …` / `tangle-cli …` |
 | `<deploy-cli> quickstart` | `tangle quickstart` (real; static onboarding text) |
 | `--help-extended` / `--help-full` | `--help` |
 | `from <deploy_pkg> import TangleApiClient` | `from tangle_cli.client import TangleApiClient` (see §3) |
@@ -161,9 +174,10 @@ existing = client.find_existing_components(
   A bare `TangleApiClient()` only works against the default localhost backend.
 - `TangleApiClient` lives in `tangle_cli.client` and inherits generated endpoint
   methods from `tangle_api.generated.operations.GeneratedTangleApiOperations`.
-  **Importing it requires the native bindings** — install the `[native]` extra (or
-  provide a local `tangle_api.generated` package) before `from tangle_cli.client import …`.
-  The top-level `import tangle_cli` is intentionally native-free.
+  **Importing it requires generated bindings**. The default `tangle-cli` install
+  includes `tangle-api`; custom API projects may provide a local or packaged
+  compatible `tangle_api.generated` package before `from tangle_cli.client import …`.
+  The top-level `import tangle_cli` intentionally does not eagerly import generated bindings.
 - **Prefer the CLI over Python snippets for status/polling.** Any internal snippet
   that calls unverified methods like `get_pipeline_run`, `get_execution_graph_state`,
   `set_verbose`, `.status_totals`, or `.root_execution_id` must be replaced. The
@@ -200,7 +214,9 @@ internal backend's auth verification, and the internal package index **entirely*
 - **Run links:** replace internal run-URL links (`https://<internal-backend-host>/runs/<id>`) with
   `<base-url>/runs/<id>` **or** "inspect via `tangle sdk pipeline-runs details RUN_ID`".
 - **No internal package index.** Resolve dependencies against public PyPI
-  (`uv sync` / `tangle-cli[native]`).
+  (`uv sync` from a checkout, `uv tool install tangle-cli` for a persistent CLI,
+  or `uvx --from tangle-cli tangle …` for one-off execution). Generic Python
+  environments may also use `pip install tangle-cli`.
 - Example for a protected backend:
 
   ```bash

@@ -38,11 +38,7 @@ references/                  ← the loop steps + topic references
 
 ## How to invoke
 
-All commands run as **`uv run tangle …` from a checkout of the `tangle-cli` repo**. `tangle-cli` is not yet
-a published package, so the public `pip install 'tangle-cli[native]'` / bare `tangle …`
-*invocation* form is presented as a future state; elsewhere `tangle` still appears as a bare
-command noun in prose and in the §2 CLI map (the naming-surface exception). See
-`OSS-CONVENTIONS.md` §1.
+Commands can run as **`uv run tangle …` from a checkout of the `tangle-cli` repo**, from a persistent uv tool install (`uv tool install tangle-cli`, then `tangle …` / `tangle-cli …`), or as a one-off uvx command (`uvx --from tangle-cli tangle …`). Elsewhere, `tangle` still appears as a bare command noun in prose and in the §2 CLI map (the naming-surface exception). See `OSS-CONVENTIONS.md` §1.
 
 ## What changed from the internal bundle
 

@@ -22,10 +22,7 @@ bundle-refresh step. Relative cross-references in this skill (`agents/*.md`,
 `references/*.md`) resolve directly on disk. Read
 [`references/setup.md`](references/setup.md) to set up the CLI and auth.
 
-Run every command as `uv run tangle …` from a checkout of the `tangle-cli` repo. (Once `tangle-cli` is promoted to the public OSS package, you will be able to
-`pip install 'tangle-cli[native]'` and invoke `tangle …` directly; until then, use
-`uv run tangle …` from a checkout.) See
-[`OSS-CONVENTIONS.md`](OSS-CONVENTIONS.md) §1.
+Run commands as `uv run tangle …` from a checkout of the `tangle-cli` repo. For an installed CLI, prefer `uv tool install tangle-cli`; for one-off execution, use `uvx --from tangle-cli tangle …`. See [`OSS-CONVENTIONS.md`](OSS-CONVENTIONS.md) §1.
 
 ## Commands
 

@@ -14,7 +14,7 @@ environment variables (see [OSS-CONVENTIONS.md §4](../OSS-CONVENTIONS.md)).
 
 ## Tools
 
-**Run every command as `uv run tangle …` from a checkout of the `tangle-cli` repo.**
+**From a checkout, run commands as `uv run tangle …`. For an installed CLI, prefer `uv tool install tangle-cli`; for one-off execution, use `uvx --from tangle-cli tangle …`.**
 Help is standard `--help` (there is no `--help-extended` / `--help-full`).
 
 Resolution precedence: explicit CLI option > `--config` file value > environment

@@ -11,9 +11,7 @@ components with local code changes for testing.
 
 ## Tools
 
-**Run every `tangle` command via Bash as `uv run tangle …` from a checkout of the `tangle-cli` repo** (see [`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §1). Once `tangle-cli` is promoted to the public OSS package you will be able to
-`pip install 'tangle-cli[native]'` and invoke `tangle …` directly; until then use
-`uv run tangle …`.
+**Run every `tangle` command via Bash as `uv run tangle …` from a checkout of the `tangle-cli` repo**. For an installed CLI, prefer `uv tool install tangle-cli`; for one-off execution, use `uvx --from tangle-cli tangle …` (see [`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §1).
 
 Run `uv run tangle quickstart` to discover available commands. Use `--help` on any
 command or group for detailed usage (there is no `--help-extended` / `--help-full`).

@@ -11,10 +11,10 @@ return a one-line diagnosis.
 
 ## Tools
 
-**Always use the `tangle` CLI via Bash.** Run every command as `uv run tangle …`
-from a checkout of the `tangle-cli` repo (see `OSS-CONVENTIONS.md` §1). Once `tangle-cli` is promoted to the public OSS package you will be able to `pip install
-'tangle-cli[native]'` and invoke `tangle …` directly; until then, use `uv run
-tangle …` from a checkout.
+**Always use the `tangle` CLI via Bash.** Run commands as `uv run tangle …`
+from a checkout of the `tangle-cli` repo. For an installed CLI, prefer
+`uv tool install tangle-cli`; for one-off execution, use
+`uvx --from tangle-cli tangle …` (see `OSS-CONVENTIONS.md` §1).
 
 Run `uv run tangle quickstart` to discover available commands. Use `--help` on any
 command (or group, e.g. `uv run tangle sdk pipeline-runs --help`) for detailed usage.

@@ -11,8 +11,7 @@ Generate an ML experiment report. Regenerate from scratch each round.
 ## Tools
 
 **Always use the `tangle` CLI via Bash. Do NOT use any MCP tools.**
-Run every command as `uv run tangle …` from a checkout of the `tangle-cli` repo (see
-[OSS-CONVENTIONS.md §1](../OSS-CONVENTIONS.md)).
+Run commands as `uv run tangle …` from a checkout of the `tangle-cli` repo. For an installed CLI, prefer `uv tool install tangle-cli`; for one-off execution, use `uvx --from tangle-cli tangle …` (see [OSS-CONVENTIONS.md §1](../OSS-CONVENTIONS.md)).
 
 Run `uv run tangle quickstart` to discover available commands. Use `--help` on any
 command for detailed usage.

@@ -13,9 +13,7 @@ Think like an MLE who reads papers and asks "what if we tried this?"
 ## Tools
 
 **Always use the `tangle` CLI via Bash. Do NOT use any MCP tool layer.**
-Run every command as `uv run tangle …` from a checkout of the `tangle-cli` repo. (Once `tangle-cli` is promoted to the public OSS package you will be able to `pip install
-'tangle-cli[native]'` and invoke `tangle …` directly; until then use `uv run tangle
-…` from a checkout.) See [`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §1.
+Run commands as `uv run tangle …` from a checkout of the `tangle-cli` repo. For an installed CLI, prefer `uv tool install tangle-cli`; for one-off execution, use `uvx --from tangle-cli tangle …`. See [`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §1.
 
 Run `uv run tangle quickstart` to discover available commands. Use `--help` on any
 command for detailed usage. For broader docs, see `uv run tangle sdk

@@ -12,8 +12,10 @@ ML methodology issues. Be skeptical. Check the work.
 
 ## Tools
 
-**Always use the `tangle` CLI via Bash.** Run every command as `uv run tangle …`
-from a checkout of the `tangle-cli` repo. See [OSS-CONVENTIONS.md](../OSS-CONVENTIONS.md)
+**Always use the `tangle` CLI via Bash.** Run commands as `uv run tangle …`
+from a checkout of the `tangle-cli` repo. For an installed CLI, prefer
+`uv tool install tangle-cli`; for one-off execution, use
+`uvx --from tangle-cli tangle …`. See [OSS-CONVENTIONS.md](../OSS-CONVENTIONS.md)
 §1 for the invocation rule and §4 for auth flags.
 
 Run `uv run tangle quickstart` to discover available commands. Use `--help` on any

@@ -10,8 +10,7 @@ cross-references resolve directly on disk.
 
 ## 1. Install / run the CLI
 
-The CLI is consumed from a checkout of the repo. Run every command as
-`uv run tangle …`:
+From a checkout, run commands through `uv run`:
 
 ```bash
 uv run tangle quickstart
@@ -20,14 +19,28 @@ uv run tangle sdk --help
 uv run tangle api --help
 ```
 
+For a persistent user-level CLI install, prefer uv tools:
+
+```bash
+uv tool install tangle-cli
+tangle quickstart
+tangle-cli --help
+```
+
+For one-off execution without a persistent install, use `uvx`:
+
+```bash
+uvx --from tangle-cli tangle --help
+```
+
+Generic Python environments may also use `pip install tangle-cli`; use
+`uv pip install tangle-cli` only inside an explicitly managed virtualenv.
+
 `uv` resolves dependencies against public PyPI. In the `tangle-cli` workspace, `uv`
 installs the workspace `tangle-api` package automatically for dev/tests. The
-`[native]` extra enables the static API-backed commands and the handwritten
-`TangleApiClient` wrapper.
-
-> Once `tangle-cli` is promoted to the public OSS package, you will be able to
-> `pip install 'tangle-cli[native]'` and invoke `tangle …` directly. Until then,
-> use `uv run tangle …` from a checkout of the repo.
+published default `tangle-cli` install includes `tangle-api`, enabling static
+API-backed commands and the handwritten `TangleApiClient` wrapper. The old
+`native` extra is retained only as a compatibility/no-op alias.
 
 Then discover available commands:
 ```bash
@@ -143,4 +156,4 @@ fetch bytes, use the signed-URL recipe in
 | `403 Forbidden` | Authenticated but not permitted — re-run with a different `--token` for the right identity. |
 | Connection error / timeout | Wrong or unreachable `--base-url` / `TANGLE_API_URL`; confirm the backend is up. |
 | Want to see the raw HTTP exchange | Set `TANGLE_VERBOSE=1` for redacted request/response diagnostics. |
-| Import error from `from tangle_cli.client import TangleApiClient` | Install the `[native]` extra (the client needs the native bindings). |
+| Import error from `from tangle_cli.client import TangleApiClient` | Install `tangle-cli` normally so `tangle-api` is present, or provide a compatible local/custom `tangle_api.generated` package for a custom API. |
@@ -11,17 +11,13 @@ core, run from a checkout of the `tangle-cli` repo:
 uv run tangle --help
 ```
 
-If that fails, work through `references/setup.md` first (checkout, `uv sync`, the
-`[native]` extra, base-url/auth). Once `uv run tangle --help` works, discover the
-available commands:
+If that fails, work through `references/setup.md` first (checkout, `uv tool install tangle-cli`, or `uvx --from tangle-cli tangle …`; base-url/auth). Once `uv run tangle --help` or installed `tangle --help` works, discover the available commands:
 
 ```bash
 uv run tangle quickstart
 ```
 
-> Once `tangle-cli` is promoted to the public OSS package you will be able to
-> `pip install 'tangle-cli[native]'` and invoke `tangle …` directly. Until then,
-> use `uv run tangle …` from a checkout of the repo.
+> For an installed CLI, prefer `uv tool install tangle-cli` and invoke `tangle …` or `tangle-cli …`; for one-off execution, use `uvx --from tangle-cli tangle …`.
 
 ## Scenario Directory
 
@@ -31,8 +27,10 @@ All experiment state lives in the scenario directory. Set the absolute path:
 SCENARIO_DIR=<path_to_scenario_directory>
 ```
 
-All `tangle` commands run via `uv run tangle …`. All file reads/writes use
-absolute `SCENARIO_DIR` paths. These are different locations — don't confuse them.
+From a checkout, all `tangle` commands run via `uv run tangle …`. From an
+installed CLI, use `tangle …` / `tangle-cli …`; for one-off execution, use
+`uvx --from tangle-cli tangle …`. All file reads/writes use absolute
+`SCENARIO_DIR` paths. These are different locations — don't confuse them.
 
 ## No Scenario Yet? Build One
 

@@ -14,7 +14,7 @@ with new commands and flags — discover the current surface with `--help` and
 
 ## Install / Invoke
 
-Run every command as `uv run tangle …` from a checkout of the `tangle-cli` repo:
+From a checkout, run commands as `uv run tangle …`:
 
 ```bash
 uv run tangle quickstart
@@ -23,13 +23,24 @@ uv run tangle sdk --help
 uv run tangle api --help
 ```
 
-The `[native]` extra enables the static API-backed commands and the handwritten
-`TangleApiClient` (see [Programmatic client](#programmatic-client-python)). In the `tangle-cli` workspace `uv` installs the workspace `tangle-api` package automatically for
-dev/tests.
+For a persistent user-level CLI install, prefer uv tools:
 
-> Once `tangle-cli` is promoted to the public OSS package, you will be able to
-> `pip install 'tangle-cli[native]'` and invoke `tangle …` directly. Until then,
-> use `uv run tangle …` from a checkout of the repo.
+```bash
+uv tool install tangle-cli
+tangle quickstart
+tangle-cli --help
+```
+
+For one-off execution without a persistent install, use `uvx`:
+
+```bash
+uvx --from tangle-cli tangle --help
+```
+
+Generic Python environments may also use `pip install tangle-cli`; use
+`uv pip install tangle-cli` only inside an explicitly managed virtualenv.
+
+The default `tangle-cli` install includes `tangle-api` and enables static API-backed commands plus the handwritten `TangleApiClient` (see [Programmatic client](#programmatic-client-python)). In the `tangle-cli` workspace, `uv` installs the workspace `tangle-api` package automatically for dev/tests. The old `native` extra is a compatibility/no-op alias.
 
 ## Discover Available Commands
 
@@ -361,10 +372,10 @@ existing = client.find_existing_components(
 
 - Constructor: `TangleApiClient(base_url, *, token=, auth_header=, header=, headers=, …)`.
   A bare `TangleApiClient()` only works against the default localhost backend.
-- Importing it requires the native bindings — install the `[native]` extra (or
-  provide a local `tangle_api.generated` package) before
-  `from tangle_cli.client import …`. The top-level `import tangle_cli` is
-  intentionally native-free.
+- Importing it requires generated bindings. The default `tangle-cli` install
+  includes `tangle-api`; custom API projects can provide a compatible local or
+  packaged `tangle_api.generated` package before `from tangle_cli.client import …`.
+  The top-level `import tangle_cli` intentionally does not eagerly import generated bindings.
 - The verified surface is `client.pipeline_runs_get(run_id)` and the
   `find_existing_components(...)` helper. For status/graph state, prefer the CLI:
   `tangle sdk pipeline-runs status RUN_ID` and