openrunner-sdk 2.41.5__tar.gz → 2.41.7__tar.gz

{openrunner_sdk-2.41.5 → openrunner_sdk-2.41.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrunner-sdk
-Version: 2.41.5
+Version: 2.41.7
 Summary: OpenRunner SDK - W&B-compatible ML experiment tracking client
 Project-URL: Homepage, https://github.com/jqueguiner/openrunner
 Project-URL: Repository, https://github.com/jqueguiner/openrunner

{openrunner_sdk-2.41.5 → openrunner_sdk-2.41.7}/openrunner/CLAUDE.md

@@ -96,10 +96,11 @@ falling back to pure-Python httpx otherwise:
 ord.search_dataset(repo, q, mode="mixed"|"exact", lang="fr")   # BM25 / phrase, lang filter
 ord.optimize_embedding_search(repo)                            # build ANN index (once)
 ord.semantic_search(repo, q, lang="en,fr")                     # vector (cosine) search
+ord.regex_search(repo, r"\bcancel(led)?\b", lang="en")         # Python-re over the text column (bounded)
 ord.word_lookup(repo, "medical,doctor", op="union"|"intersect", lang="fr")  # lexical_map
 ord.keyword_expand("medical terms in french", count=300)       # LLM -> {keywords, csv, count}
 
-# derive: mode = word (op union/intersect) | fts | exact | semantic; lang filter; append via target_repo_id
+# derive: mode = word (op union/intersect) | fts | exact | regex | semantic; lang filter; append via target_repo_id
 child = ord.derive_by_query(parent, keywords_csv, name="org/medical-fr",
                             mode="word", lang="fr", limit=5000)
 ord.derive_by_query(parent, "more,terms", target_repo_id="org/medical-fr", mode="word")  # append, de-dup
@@ -175,3 +176,45 @@ When the user asks about papers, research, or sessions:
 - Use `mcp__openrunner__openrunner_search_research` for research plans
 - Use `mcp__openrunner__openrunner_search_sessions` for AI session history
 - Use `mcp__openrunner__openrunner_update_paper` to modify paper sections
+
+## Container registry & serverless deployment
+
+Register a container registry (Docker Hub, GHCR, Google Artifact Registry, AWS
+ECR, Azure ACR, OVH/Harbor) once; the upstream credential is stored encrypted
+server-side and the OpenRunner **broker** proxies pull/push — the client never
+holds the upstream key.
+
+```
+openrunner registry add --name "Harbor ML" --url REG_URL --username U --token T --namespace NS
+openrunner registry set-default <id>     # broker fallback when the repo path is ambiguous
+openrunner registry login                # docker login the broker (short-lived token)
+docker push <registry_host>/<namespace>/<project-slug>:<user>-<name>-<tag>
+```
+
+Repo convention (`canonical_image_name`): `{namespace}/{project_slug}`, tag leads
+with the user — e.g. `model-team/ner-email:jl-int8-v1`.
+
+**Images link to a project = the deploy gate.** An image pushed **through the
+broker** is **auto-linked** to its project on the manifest PUT (project resolved
+from the repo's project-slug segment), so it appears under the project's
+**Registry** tab (artifact page) and the project-overview **Registry** panel with
+no manual step. Direct-to-upstream pushes (or registries that hide their catalog,
+e.g. OVH Harbor robots can't list `_catalog`) must be linked explicitly:
+
+```
+openrunner deploy link IMAGE -p ORG/NAME [--registry-id UUID]
+openrunner deploy images -p ORG/NAME     # list linked images
+openrunner deploy gpus  -p ORG/NAME      # deployable GPU offers
+openrunner deploy create ... ; openrunner deploy scale <id> N ; openrunner deploy call <id> ...
+```
+API: `GET/POST /projects/{id}/images`, `.../deployments`. SDK:
+`client.list_project_images(pid)`, `client.link_project_image(pid, image, registry_id=)`.
+Slash: `/openrunner:registry`, `/openrunner:deploy`, `/openrunner:build-api`.
+
+## Full LLM map: llms.txt
+
+The complete end-to-end, LLM-oriented map of OpenRunner (dataset → run
+instrumentation → GPU training → sweep → registry → deploy → handover) lives at
+**https://openrun.gladia.io/llms-full.txt** (source: `src/web/public/llms-full.txt`),
+with a short index at **/llms.txt**. Read the full doc to ground yourself in the
+real commands + conventions before driving OpenRunner end-to-end for a new project.

{openrunner_sdk-2.41.5 → openrunner_sdk-2.41.7}/openrunner/__init__.py

@@ -107,15 +107,25 @@ from openrunner.datasets import (
     optimize_embedding_search,
     push_dataset,
     search_dataset,
+    regex_search,
     semantic_search,
     word_lookup,
     set_dataset_card,
     set_storage_policy,
+    update_dataset,
     upload_file,
     upload_sharded,
     upload_folder,
 )
 from openrunner.config import Config
+from openrunner.llms import (
+    llms_txt,
+    llms_txt_path,
+    LLMS_TXT_URL,
+    LLMS_FULL_TXT_URL,
+    LLMS_TXT_PATH,
+    LLMS_FULL_TXT_PATH,
+)
 from openrunner.model import Model
 from openrunner.prompt import MessagesPrompt, Prompt, StringPrompt
 from openrunner.launch import LaunchJob, launch, from_run as _launch_from_run

{openrunner_sdk-2.41.5 → openrunner_sdk-2.41.7}/openrunner/_native.py

@@ -11,8 +11,8 @@ Covered surface today: projects (incl. linked repo), artifacts/versions,
 presigned downloads (selective, GIL released during transfers), container
 registries + broker login tokens, dataset editable-overlay columns
 (add column / set cell / edit row / get row — source columns stay read-only),
-and dataset search + query-derivation (full-text / semantic / word union·intersect,
-LLM keyword-expand, derive-by-query + derived rows).
+and dataset search + query-derivation (full-text / semantic / regex / word
+union·intersect, LLM keyword-expand, derive-by-query + derived rows).
 """
 
 from __future__ import annotations

{openrunner_sdk-2.41.5 → openrunner_sdk-2.41.7}/openrunner/cli.py

@@ -863,8 +863,11 @@ def artifact_list(project: str | None, project_opt: str | None) -> None:
 
 @artifact.command("get")
 @click.argument("name")
-@click.option("--root", "-r", default=".", help="Download directory (default: .)")
-def artifact_get(name: str, root: str) -> None:
+@click.option("--root", "-r", "--output", "-o", "root", default=".",
+              help="Download directory (default: .). --output/-o is an alias.")
+@click.option("--project", "-p", default=None,
+              help="Scope the lookup to ORG/PROJECT (else searches all accessible projects)")
+def artifact_get(name: str, root: str, project: str | None = None) -> None:
     """Download an artifact to a local directory.
 
     NAME can use colon syntax: my-dataset:latest or my-model:v3.
@@ -886,8 +889,16 @@ def artifact_get(name: str, root: str) -> None:
         else:
             alias = ref
 
-    # Find artifact by listing all accessible projects
+    # Find artifact by listing accessible projects. When --project is given we
+    # only search that one (faster, and disambiguates a name shared across
+    # projects); otherwise fall back to scanning every accessible project.
     projects = client.list_projects()
+    if project:
+        projects = [
+            p for p in projects
+            if project in (p.get("id"), p.get("name"), p.get("slug"),
+                           f"{p.get('org_slug')}/{p.get('slug')}")
+        ] or projects
     artifact_detail = None
     target_version_id = None
 
@@ -1135,9 +1146,12 @@ def cache_cleanup(max_size: float | None) -> None:
 
 @main.command("download-artifact")
 @click.argument("name")
-@click.option("--root", "-r", default=".", help="Download directory (default: .)")
+@click.option("--root", "-r", "--output", "-o", "root", default=".",
+              help="Download directory (default: .). --output/-o is an alias.")
+@click.option("--project", "-p", default=None,
+              help="Scope the lookup to ORG/PROJECT (else searches all accessible projects)")
 @click.pass_context
-def download_artifact_cmd(ctx: click.Context, name: str, root: str) -> None:
+def download_artifact_cmd(ctx: click.Context, name: str, root: str, project: str | None) -> None:
     """Download an artifact to a local directory.
 
     NAME can use colon syntax: my-dataset:latest or my-model:v3.
@@ -1145,7 +1159,7 @@ def download_artifact_cmd(ctx: click.Context, name: str, root: str) -> None:
 
     This is a top-level alias for `openrunner artifact get`.
     """
-    ctx.invoke(artifact_get, name=name, root=root)
+    ctx.invoke(artifact_get, name=name, root=root, project=project)
 
 
 @main.command("upload-artifact")
@@ -3221,6 +3235,24 @@ def version_cmd(check: bool) -> None:
         click.echo("Up to date.")
 
 
+@main.command("llms")
+@click.option("--full", is_flag=True, help="Print the complete guide (llms-full.txt) instead of the index")
+@click.option("--path", "show_path", is_flag=True, help="Print the bundled file path instead of its content")
+def llms_cmd(full: bool, show_path: bool) -> None:
+    """Print the bundled LLM-oriented OpenRunner doc.
+
+    The short index by default, or the complete end-to-end guide with --full.
+    Bundled in the package (works offline); also served at /llms.txt and
+    /llms-full.txt on the instance.
+    """
+    from openrunner import llms as _llms
+
+    if show_path:
+        click.echo(_llms.llms_txt_path(full=full))
+    else:
+        click.echo(_llms.llms_txt(full=full))
+
+
 @main.command("_update_nudge", hidden=True)
 def update_nudge_cmd() -> None:
     """Print ONE update-hint line if a newer SDK exists, else nothing. Cheap:

{openrunner_sdk-2.41.5 → openrunner_sdk-2.41.7}/openrunner/datasets.py

@@ -453,11 +453,24 @@ class DatasetsClient:
         complete — so the dataset's file count grows live and an interrupted run
         is genuinely resumable (re-run with ``skip_existing`` to continue). The
         API stays out of the byte path, so throughput is bandwidth-bound.
+
+        ``skip_existing`` skips a file only when the remote copy has the SAME
+        path AND the SAME content (sha256). A file whose bytes changed since the
+        last upload is re-uploaded — a pure path match would silently drop
+        edits, making a dataset update look successful while sending nothing.
         """
+        import hashlib
         import os
         import sys
         from concurrent.futures import ThreadPoolExecutor, as_completed
 
+        def _sha256(fp: str) -> str:
+            h = hashlib.sha256()
+            with open(fp, "rb") as fh:
+                for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+                    h.update(chunk)
+            return h.hexdigest()
+
         ds = self._resolve(repo_id)
         items: list[tuple[str, str]] = []
         for root, _dirs, names in os.walk(folder):
@@ -469,8 +482,16 @@ class DatasetsClient:
                 items.append((full, rel))
         if skip_existing:
             try:
-                have = {f["path"] for f in self.list_files(repo_id)}
-                items = [it for it in items if it[1] not in have]
+                # Map remote path -> sha256. Skip a local file only when both the
+                # path and the content hash match; changed files are re-uploaded.
+                remote = {f["path"]: (f.get("sha256") or "") for f in self.list_files(repo_id)}
+                kept: list[tuple[str, str]] = []
+                for full, rel in items:
+                    rsha = remote.get(rel)
+                    if rsha and rsha == _sha256(full):
+                        continue
+                    kept.append((full, rel))
+                items = kept
             except Exception:
                 pass
         if not items:
@@ -794,6 +815,25 @@ class DatasetsClient:
         _check(r)
         return r.json().get("rows", r.json().get("hits", []))
 
+    def regex_search(
+        self, repo_id: str, pattern: str, *, limit: int = 20, lang: str = ""
+    ) -> list[dict]:
+        """Regex search: match a Python-``re`` ``pattern`` against the dataset's
+        text column (streamed, bounded — no index needed). Case-insensitive is
+        opt-in via an inline ``(?i)`` flag. Native core when available, else httpx.
+        Pairs with ``derive_by_query(mode="regex")`` to build a regex-derived set.
+        """
+        ds = self._resolve(repo_id)
+        nat = self._native_client()
+        if nat is not None:
+            return nat.regex_search(str(ds.id), pattern, lang, limit).get("rows", [])
+        params: dict[str, Any] = {"q": pattern, "limit": limit, "mode": "regex"}
+        if lang:
+            params["lang"] = lang
+        r = self._http.get(f"/datasets/{ds.id}/search", params=params)
+        _check(r)
+        return r.json().get("rows", [])
+
     def optimize_embedding_search(
         self,
         repo_id: str,
@@ -869,7 +909,8 @@ class DatasetsClient:
         """Create (or append to) a dataset **derived from a query** over ``repo_id``.
 
         ``mode``: "word" (``q`` = term / CSV; pairs with LLM ``keyword_expand``),
-        "fts" (BM25), "exact" (phrase), "semantic" (vector — needs
+        "fts" (BM25), "exact" (phrase), "regex" (``q`` = a Python-``re`` pattern
+        matched over the text column, bounded), "semantic" (vector — needs
         ``optimize_embedding_search``). ``lang`` filters by language / CSV. Pass
         ``name`` to create, or ``target_repo_id`` to append (must derive from the
         same parent). Lineage is recorded automatically. The query runs and
@@ -988,6 +1029,24 @@ class DatasetsClient:
         _check(r)
         return r.json().get("columns", [])
 
+    def delete_column(self, repo_id: str, name: str) -> list[str]:
+        """Delete an editable column from an indexed dataset.
+
+        Miroir exact de :meth:`add_column` — retire la colonne overlay (ou de la
+        members table d'un dérivé) ``name`` ; les colonnes source indexées
+        ("parent") restent **en lecture seule** et ne peuvent pas être supprimées.
+
+        Exact mirror of :meth:`add_column`: removes the overlay (or derived-member)
+        column ``name`` — the indexed source ("parent") columns stay **read-only**
+        and cannot be deleted. A read-only source column (or the primary key) is
+        rejected (400); an unknown column returns 404. Returns the remaining
+        editable column names.
+        """
+        ds = self._resolve(repo_id)
+        r = self._http.delete(f"/datasets/{ds.id}/columns/{name}")
+        _check(r)
+        return r.json().get("columns", [])
+
     def set_cell(self, repo_id: str, debug_id: str, column: str,
                  value: str | None = None) -> dict:
         """Set ONE editable cell (creates the column on first write).
@@ -1241,6 +1300,12 @@ def add_column(repo_id: str, name: str, *, default: str | None = None) -> list[s
     return _c().add_column(repo_id, name, default=default)
 
 
+def delete_column(repo_id: str, name: str) -> list[str]:
+    """Delete an editable column from an indexed dataset (source columns stay
+    read-only). Module-level mirror of DatasetsClient.delete_column."""
+    return _c().delete_column(repo_id, name)
+
+
 def set_cell(repo_id: str, debug_id: str, column: str, value: str | None = None) -> dict:
     """Set one editable cell of a dataset row (creates the column if new)."""
     return _c().set_cell(repo_id, debug_id, column, value)
@@ -1292,6 +1357,11 @@ def semantic_search(repo_id: str, query: str, **kwargs: Any) -> list[dict]:
     return _c().semantic_search(repo_id, query, **kwargs)
 
 
+def regex_search(repo_id: str, pattern: str, **kwargs: Any) -> list[dict]:
+    """Regex search — Python-``re`` ``pattern`` over the text column (bounded)."""
+    return _c().regex_search(repo_id, pattern, **kwargs)
+
+
 def optimize_embedding_search(repo_id: str, **kwargs: Any) -> dict:
     """Embed rows + build the ANN index for semantic search / semantic-derive."""
     return _c().optimize_embedding_search(repo_id, **kwargs)

{openrunner_sdk-2.41.5 → openrunner_sdk-2.41.7}/openrunner/gpu/__init__.py

@@ -534,25 +534,65 @@ async def terminate(
     provider: str | None = None,
     api_key: str | None = None,
 ) -> bool:
-    """Terminate a GPU instance on the provider and update the platform.
-
-    1. Looks up instance details from the backend (to find provider if
-       not specified).
-    2. Terminates the instance via the provider API.
-    3. Updates the backend status to ``"terminated"`` via PATCH.
-    4. Stops the cost guard thread if one is running.
+    """Terminate a GPU instance.
+
+    Preferred path (governed): when no explicit ``api_key`` is passed, the
+    platform terminates the pod SERVER-SIDE — it decrypts the org's stored
+    provider key (which never leaves the API), kills the pod, VERIFIES it is
+    gone, and only then marks the instance ``terminated``. This is the only
+    path that works when the provider key lives on the platform (the common
+    case): a client-side terminate cannot see that key and would fail with
+    "No API key found for provider …".
+
+    Fallback (BYO key): when an explicit ``api_key`` is given, terminate the
+    pod directly via the provider API. The backend status is marked
+    ``terminated`` ONLY if the provider kill actually succeeded — never
+    unconditionally, since a falsely-"terminated" record strands a BILLING pod
+    that our records claim is dead.
 
     Args:
         instance_id: Platform instance ID.
         provider: Provider name (auto-detected from backend if None).
-        api_key: Explicit provider API key.
+        api_key: Explicit provider API key (opts into the client-side path).
 
     Returns:
-        True if termination succeeded.
+        True if termination is confirmed.
     """
     api_client = _get_api_client()
 
-    # Resolve provider and provider_instance_id from backend
+    def _stop_guard() -> None:
+        guard_entry = _active_guards.pop(instance_id, None)
+        if guard_entry:
+            guard_entry["stop"].set()
+            logger.info("Cost guard stopped for instance %s", instance_id)
+
+    # Governed server-side terminate: kills + verifies with the org's stored
+    # key. Used whenever we aren't handed an explicit BYO key.
+    if api_key is None and api_client is not None:
+        ok = api_client.terminate_instance(instance_id)
+        if ok:
+            # The API only reports success once the pod is confirmed gone.
+            inst = api_client.get_instance(instance_id) or {}
+            confirmed = inst.get("status") == "terminated"
+            if not confirmed:
+                # Non-terminal ("terminating") — the reconciler keeps retrying;
+                # surface that the pod is not yet confirmed dead.
+                logger.warning(
+                    "terminate %s: server accepted but pod not yet confirmed "
+                    "gone (status=%s) — the reconciler will keep retrying",
+                    instance_id, inst.get("status"),
+                )
+            else:
+                _stop_guard()
+            return confirmed
+        logger.error(
+            "terminate %s: governed server-side termination failed — the pod "
+            "may still be BILLING; check `openrunner gpu ls` / provider console",
+            instance_id,
+        )
+        return False
+
+    # BYO-key path: resolve provider + provider_instance_id, then kill directly.
     provider_instance_id = instance_id
     if provider is None and api_client is not None:
         instances = api_client.list_instances()
@@ -569,7 +609,6 @@ async def terminate(
         logger.error("terminate: cannot determine provider for instance %s", instance_id)
         return False
 
-    # Get provider instance and terminate
     try:
         prov = _get_provider_instance(provider, api_key=api_key, api_client=api_client)
         result = await prov.terminate_instance(provider_instance_id)
@@ -577,18 +616,16 @@ async def terminate(
         logger.warning("terminate: provider termination failed: %s", exc)
         result = False
 
-    # Update backend
-    if api_client is not None:
+    # Only mark terminated when the provider kill actually succeeded — a
+    # falsely-"terminated" record strands a billing pod.
+    if result and api_client is not None:
         try:
             api_client.update_instance_status(instance_id, "terminated")
         except Exception as exc:
             logger.warning("terminate: backend update failed: %s", exc)
 
-    # Stop cost guard thread
-    guard_entry = _active_guards.pop(instance_id, None)
-    if guard_entry:
-        guard_entry["stop"].set()
-        logger.info("Cost guard stopped for instance %s", instance_id)
+    if result:
+        _stop_guard()
 
     return result
 

{openrunner_sdk-2.41.5 → openrunner_sdk-2.41.7}/openrunner/install_commands.py

@@ -2135,7 +2135,7 @@ Give the dataset **URL** (`<base>/datasets/<id>`), the modality/tasks/languages,
 
 DERIVE_DATASET_CMD = """---
 name: {prefix}derive-dataset
-description: Derive a dataset from an existing one — either by a SEARCH QUERY (semantic / word union·intersect / fts / exact, with language filter + LLM keyword expansion) or by adding a computed column. Keeps lineage, never re-uploads the parent's media.
+description: Derive a dataset from an existing one — either by a SEARCH QUERY (semantic / regex / word union·intersect / fts / exact, with language filter + LLM keyword expansion) or by adding a computed column. Keeps lineage, never re-uploads the parent's media.
 argument-hint: "[parent org/name] [child org/name] [--query ... | --column NAME]"
 allowed-tools:
   - Bash
@@ -2152,7 +2152,7 @@ Pick by intent: **subset/select rows -> A**; **annotate/flag rows -> B**.
 
 ---
 
-## A. Query-derivation (semantic / word union·intersect / fts / exact + lang + LLM keywords)
+## A. Query-derivation (semantic / regex / word union·intersect / fts / exact + lang + LLM keywords)
 
 All server-side; the SDK delegates to the native Rust core when installed. `PARENT` must be indexed (`ds.index_dataset(...)`; for `semantic`, also `ds.optimize_embedding_search(...)`).
 
@@ -2177,7 +2177,7 @@ print(ds.derived_rows('ORG/medical-fr', limit=10))
 "
 ```
 
-Query modes (`mode=`): `word` (CSV of terms; `op='union'|'intersect'`), `fts` (BM25), `exact` (phrase), `semantic` (vector ANN). `lang=` takes a language or CSV ("fr" / "en,fr"); "" = all. Lineage to `PARENT` is recorded automatically by `derive_by_query`.
+Query modes (`mode=`): `word` (CSV of terms; `op='union'|'intersect'`), `fts` (BM25), `exact` (phrase), `regex` (a Python-`re` pattern over the text column, e.g. `ds.regex_search('ORG/PARENT', r'\\bcancel(led)?\\b')` / `ds.derive_by_query('ORG/PARENT', r'\\brefund', name='ORG/refunds', mode='regex')`), `semantic` (vector ANN). `lang=` takes a language or CSV ("fr" / "en,fr"); "" = all. Lineage to `PARENT` is recorded automatically by `derive_by_query`.
 
 ---
 
@@ -3254,6 +3254,93 @@ directly SSH-reachable** (`publicIp:22`): SSH is only via the **proxy**
 """
 
 
+REPORT_BUG_CMD = """---
+name: {prefix}report-bug
+description: Open a GitHub issue on the OpenRunner open-source repo for a bug you hit
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - AskUserQuestion
+---
+<objective>
+File a high-quality bug report as a GitHub issue on the OpenRunner open-source
+repository when the user hits a bug (or asks to report one). Gather REAL context
+from this session, avoid duplicates, confirm before creating (an issue is public),
+and return the issue URL.
+</objective>
+
+<preconditions>
+- The `gh` CLI must be installed and authenticated. Check with `gh auth status`.
+  If it is not authenticated, tell the user to run it themselves -- suggest they
+  type `! gh auth login` in the prompt -- then stop.
+- Target repo = the OpenRunner open-source repository. Detect it (below); if it
+  cannot be resolved, fall back to `jqueguiner/openrunner`.
+</preconditions>
+
+<process>
+1. Verify gh is ready: `gh auth status`. If not, stop and ask the user to
+   `! gh auth login`.
+2. Resolve the target repo. Prefer an explicit OpenRunner repo. If the current
+   directory is the OpenRunner checkout, use its origin:
+   `gh repo view --json nameWithOwner -q .nameWithOwner`. Otherwise default to
+   `jqueguiner/openrunner`. Store it as REPO.
+3. Collect context (do NOT ask the user for what you can already observe):
+   - SDK version: `openrunner version`.
+   - OS + Python: `python3 -V` and `uname -sr`.
+   - The failing command and its EXACT error output (quote verbatim), the repro
+     steps, and expected vs actual behaviour -- reconstruct these from the current
+     session. Use AskUserQuestion ONLY for the pieces you genuinely cannot infer.
+4. De-dupe: search existing issues before opening a new one:
+   `gh issue list --repo REPO --state all --search "<key error phrase>"`.
+   If a clear match exists, show it and ask whether to comment on it
+   (`gh issue comment <n> --repo REPO --body ...`) instead of opening a new one.
+5. Draft the issue using the body template below. SHOW the full title + body to
+   the user and get EXPLICIT confirmation before creating -- an issue is public
+   and outward-facing. Do not create it on your own initiative.
+6. Create it:
+   `gh issue create --repo REPO --title "<title>" --body "<body>" --label bug`.
+   If the `bug` label does not exist the call fails -- retry without `--label`.
+7. Print the returned issue URL to the user.
+</process>
+
+<body-template>
+Compose the issue body as markdown with these sections (fill from real data;
+write "unknown" where you truly cannot determine a value -- never invent):
+
+  ### Summary
+  One or two sentences: what broke.
+
+  ### Environment
+  - openrunner-sdk: <version>
+  - OS / Python: <uname> / <python -V>
+  - Instance base_url: <from ~/.openrunner/settings.json, host only -- no api_key>
+
+  ### Steps to reproduce
+  1. ...
+
+  ### Expected
+  ...
+
+  ### Actual
+  ... (paste the exact error, in a fenced code block)
+
+  ### Notes
+  Anything else relevant (workaround found, related area of the codebase).
+</body-template>
+
+<safety>
+- NEVER create the issue (or a comment) without explicit user confirmation. It is
+  public and cannot be un-published cleanly.
+- REDACT secrets before including anything: strip api keys, tokens, passwords,
+  bearer headers, `Authorization:` values, and the api_key from settings.json.
+  Include only the base_url host, never credentials.
+- Quote error text verbatim (do not paraphrase the failure) -- but with secrets
+  stripped.
+</safety>
+"""
+
+
 FORGE_CMD = """---
 name: {prefix}forge
 description: Run or write a Python function on the Forge (Shadow-PaaS) serverless GPU fleet. Use for "run/launch/train on forge", "forge GPU", or writing an @app.function. Forge is a serverless PROVIDER (like Modal) -- NOT an ssh host or runner, so don't hunt ~/.ssh/config or `hosts ls`.
@@ -3577,6 +3664,7 @@ def install_claude_code() -> list[str]:
         "unregister-machine.md": UNREGISTER_MACHINE_CMD,
         "train.md": TRAIN_CMD,
         "deploy.md": DEPLOY_CMD,
+        "report-bug.md": REPORT_BUG_CMD,
         "forge.md": FORGE_CMD,
     }
 
@@ -3812,6 +3900,7 @@ def _install_all_commands_to_dir(cmd_dir: Path, prefix: str = "openrunner:") ->
         "unregister-machine.md": UNREGISTER_MACHINE_CMD,
         "train.md": TRAIN_CMD,
         "deploy.md": DEPLOY_CMD,
+        "report-bug.md": REPORT_BUG_CMD,
         "forge.md": FORGE_CMD,
     }