Merge pull request TangleML#15 from TangleML/piforge/tangle-cli-fix/prefer-published-tangent-skills-7f6d2c1

docs: prefer published tangle-cli in tangent skills

Author: Volv-G

skills/tangent/OSS-CONVENTIONS.md

@@ -19,34 +19,32 @@ and `api`) and **never** any internal wrapper/hook layer.
 
 ## 1. Invocation rule
 
-**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
-uv run tangle --help
-uv run tangle sdk --help
-uv run tangle api --help
-```
+**Published-package usage is the default; checkout usage is for local `tangle-cli` development/validation.**
 
 For a persistent user-level CLI install, prefer uv tools:
 
 ```bash
 uv tool install tangle-cli
 tangle quickstart
-tangle-cli --help
+tangle --help
+tangle sdk --help
+tangle api --help
 ```
 
 For one-off execution without a persistent install, use `uvx`:
 
 ```bash
 uvx --from tangle-cli tangle --help
+uvx --from tangle-cli tangle quickstart
 ```
 
 Generic Python environments may also use `pip install tangle-cli`; use
 `uv pip install tangle-cli` only inside an explicitly managed virtualenv.
 
+When intentionally validating a local checkout of the `tangle-cli` repo, prefix
+examples with `uv run` (for example, `uv run tangle quickstart`). Skill examples
+otherwise use the installed-tool form (`tangle …` / `tangle-cli …`).
+
 - **Never** prefix a command with an internal env-shim exec wrapper. That internal
   dev-env tooling must not appear in any ported file.
 - `tangle-cli` is a public PyPI package. The default install includes the
@@ -74,7 +72,7 @@ OSS replacement. **Verbs/flags below were verified against the `tangle-cli` sour
 
 | Internal | OSS |
 |---|---|
-| `<env-shim> -- <deploy-cli> …` | `uv run tangle …` from a checkout, or installed `tangle …` / `tangle-cli …` |
+| `<env-shim> -- <deploy-cli> …` | `tangle …` / `tangle-cli …` (or `uv run tangle …` only when validating a local checkout) |
 | `<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) |
@@ -142,9 +140,9 @@ OSS replacement. **Verbs/flags below were verified against the `tangle-cli` sour
 | `--run-as IDENTITY` | `--run-as` exists on `submit` but the **OSS default hooks do not support it** (downstream extension seam only). Drop run-as examples (§10, D9). |
 
 **Invocation rule for the whole table:** every left-column command, however it was
-written internally, becomes the right-column form prefixed with `uv run` (e.g.
-`uv run tangle sdk pipeline-runs submit …`). Auth flags from §4 attach to any
-API-backed command.
+written internally, becomes the bare right-column form (for example,
+`tangle sdk pipeline-runs submit …`). Only prefix with `uv run` when intentionally
+validating a local checkout. Auth flags from §4 attach to any API-backed command.
 
 ---
 
@@ -214,13 +212,14 @@ 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` 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`.
+  (`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`; local checkout validation
+  uses `uv sync` / `uv run` inside the repo.
 - Example for a protected backend:
 
   ```bash
-  uv run tangle sdk pipeline-runs submit pipeline.yaml \
+  tangle sdk pipeline-runs submit pipeline.yaml \
     --base-url https://api.example \
     --auth-header 'Bearer …' \
     -H 'X-Gateway-Auth: …' \
@@ -257,11 +256,11 @@ records of the form `{id, uri, size, hash}` (and a `count`); the `uri` is
 
   1. Get metadata and read the `uri`:
      ```bash
-     uv run tangle sdk artifacts get RUN_ID -q '{"artifact_ids":["<artifact-id>"]}'
+     tangle sdk artifacts get RUN_ID -q '{"artifact_ids":["<artifact-id>"]}'
      ```
   2. Ask the backend for a signed URL:
      ```bash
-     uv run tangle api artifacts signed-artifact-url --id <artifact-id>
+     tangle api artifacts signed-artifact-url --id <artifact-id>
      ```
   3. Fetch with a generic client — `curl -L "<signed-url>" -o ./out`, or for
      `hf://` URIs `huggingface_hub` (`hf_hub_download` / `snapshot_download`).
@@ -317,7 +316,7 @@ selectors, and auth env vars) entirely. The OSS log surface is split by what sto
   log surface:
 
   ```bash
-  uv run tangle sdk pipeline-runs logs EXECUTION_ID
+  tangle sdk pipeline-runs logs EXECUTION_ID
   ```
 
   (Note: this is keyed by **EXECUTION_ID**, not run id.)

skills/tangent/PORT-README.md

@@ -38,7 +38,7 @@ references/                  ← the loop steps + topic references
 
 ## How to invoke
 
-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.
+Normal usage runs the **published `tangle-cli` package**: install persistently with `uv tool install tangle-cli`, then run `tangle …` / `tangle-cli …`, or use `uvx --from tangle-cli tangle …` for one-off commands. Local checkout invocation (`uv run tangle …`) is only for validating changes inside the `tangle-cli` repo. 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
 
@@ -47,7 +47,7 @@ replaced with the project's open, backend-agnostic equivalent:
 
 | Internal coupling (removed)        | Open-source replacement                                              |
 | ---------------------------------- | -------------------------------------------------------------------- |
-| Internal CLI wrapper + env shim    | `uv run tangle …` (the public CLI), no environment shim              |
+| Internal CLI wrapper + env shim    | `tangle …` / `tangle-cli …` from the published package, no environment shim |
 | Cloud-object-storage artifact URIs | Scheme-agnostic artifact `uri` (e.g. `hf://…`); fetch via signed URL |
 | Hosted log-search backend          | `tangle sdk pipeline-runs logs` + launcher-native system events      |
 | Hard-coded internal API endpoint   | `--base-url` / `TANGLE_API_URL`                                      |

skills/tangent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tangent
-description: ML experiment toolkit and autonomous agent. Say "tangent" for help, "tangent <subagent>" for a specific tool, or "tangent auto" for the full autonomous experiment loop. Requires the Tangle CLI (the `tangle-cli` checkout) and a reachable Tangle backend.
+description: ML experiment toolkit and autonomous agent. Say "tangent" for help, "tangent <subagent>" for a specific tool, or "tangent auto" for the full autonomous experiment loop. Requires the published Tangle CLI (`uv tool install tangle-cli` or `uvx --from tangle-cli tangle ...`) and a reachable Tangle backend.
 allowed-tools: [Bash, Read, Write, Glob, Grep, Agent, dispatch]
 ---
 
@@ -22,7 +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 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.
+Normal usage runs the published CLI: install persistently with `uv tool install tangle-cli` and use `tangle …`, or run one-off commands with `uvx --from tangle-cli tangle …`. If intentionally validating a local `tangle-cli` checkout, prefix examples with `uv run`. See [`OSS-CONVENTIONS.md`](OSS-CONVENTIONS.md) §1.
 
 ## Commands
 
@@ -61,10 +61,10 @@ Automation:
 ## Tools
 
 Always use the `tangle` CLI via Bash. Do **not** use any `tangle` MCP tools.
-Run `uv run tangle quickstart` to discover commands. See
+Run `tangle quickstart` to discover commands. See
 [`references/tangle-tools.md`](references/tangle-tools.md).
 
-Cancel a run: `uv run tangle sdk pipeline-runs cancel RUN_ID`
+Cancel a run: `tangle sdk pipeline-runs cancel RUN_ID`
 
 Background execution: `dispatch`. Subagents: `agents/*.md`.
 

skills/tangent/agents/auth-wizard.md

@@ -14,7 +14,7 @@ environment variables (see [OSS-CONVENTIONS.md §4](../OSS-CONVENTIONS.md)).
 
 ## Tools
 
-**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 …`.**
+**Use the published `tangle` CLI via Bash.** Install persistently with `uv tool install tangle-cli`, or run one-off commands with `uvx --from tangle-cli tangle …`. Examples below use bare `tangle …`; if intentionally validating a local `tangle-cli` checkout, prefix examples with `uv run`.
 Help is standard `--help` (there is no `--help-extended` / `--help-full`).
 
 Resolution precedence: explicit CLI option > `--config` file value > environment
@@ -80,7 +80,7 @@ chosen in Step 2):
 **a) Inline flag** — explicit, per-command, highest precedence:
 
 ```bash
-uv run tangle sdk pipeline-runs search --limit 1 \
+tangle sdk pipeline-runs search --limit 1 \
   --base-url https://api.example \
   --token '<token>'
 ```
@@ -90,7 +90,7 @@ uv run tangle sdk pipeline-runs search --limit 1 \
 ```bash
 export TANGLE_API_URL='https://api.example'
 export TANGLE_API_TOKEN='<token>'
-uv run tangle sdk pipeline-runs search --limit 1
+tangle sdk pipeline-runs search --limit 1
 ```
 
 For `--auth-header` set `TANGLE_API_AUTH_HEADER`; for `-H` set
@@ -105,7 +105,7 @@ token: "<token>"
 ```
 
 ```bash
-uv run tangle sdk pipeline-runs search --limit 1 --config tangle.config.yaml
+tangle sdk pipeline-runs search --limit 1 --config tangle.config.yaml
 ```
 
 **Advise against committing secrets.** Prefer the env var, or keep the
@@ -116,7 +116,7 @@ uv run tangle sdk pipeline-runs search --limit 1 --config tangle.config.yaml
 Run a cheap, read-only call to confirm the credential works:
 
 ```bash
-uv run tangle sdk pipeline-runs search --limit 1
+tangle sdk pipeline-runs search --limit 1
 ```
 
 (attach the auth flags from Step 3 if not using env/`--config`). A clean exit —