@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/vendor/skills/discover-shed-tool/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: discover-shed-tool
+description: "Search the Tool Shed for an existing wrapper, drill from hit to a pinnable changeset, classify candidates, and recommend or fall through."
+---
+
+# discover-shed-tool
+
+Follow the procedure below and use the artifact/reference sections as the runtime contract.
+
+## When To Use
+
+- Search the Tool Shed for an existing wrapper, drill from hit to a pinnable changeset, classify candidates, and recommend or fall through.
+
+## Inputs
+
+- No upstream artifact inputs declared. See the procedure for user-supplied runtime inputs.
+
+## Outputs
+
+- Write artifact `galaxy-tool-pin` as `galaxy-tool-pin.json`. Format: `json`. Schema: galaxy-tool-discovery. (owner, repo, tool_id, version, changeset_revision) pin for a Tool Shed wrapper plus discovery classification.
+
+## Required Tools
+
+- **`gxwf`** (gxwf). `npm install -g '@galaxy-tool-util/cli@^1.8.1'`.
+  Ephemeral run: `npx --yes --package @galaxy-tool-util/cli@1.8.1 gxwf`.
+  Check: `gxwf --help | grep -q draft-validate`.
+  Docs: https://github.com/jmchilton/galaxy-tool-util-ts/tree/main/packages/cli
+
+## Load Upfront
+
+- `references/schemas/galaxy-tool-discovery.schema.json`: Schema file copied verbatim into the bundle. Validate the hit, weak, or miss recommendation emitted by Tool Shed discovery.
+
+## Load On Demand
+
+- `references/cli/tool-revisions.json`: CLI command reference packaged as a sidecar. Resolve a Tool Shed tool version to an installable changeset revision. Use when: after selecting a candidate version that needs a reproducible changeset pin.
+- `references/cli/tool-search.json`: CLI command reference packaged as a sidecar. Search the Tool Shed for candidate wrappers matching a step's tool need. Use when: resolving a workflow step to an installable Galaxy tool wrapper.
+- `references/cli/tool-versions.json`: CLI command reference packaged as a sidecar. List available Tool Shed versions for a selected candidate. Use when: after a Tool Shed search candidate is selected and before pinning a version.
+- `references/notes/component-tool-shed-search.md`: Research note copied verbatim into the bundle. Explain Tool Shed search/indexing limitations that affect hit scoring and fallthrough decisions. Use when: results are missing, weak, duplicated across owners, stale, or ambiguous.
+
+## Validation
+
+- Validate `galaxy-tool-pin.json` before returning it: run `foundry validate-galaxy-tool-discovery galaxy-tool-pin.json` from `@galaxy-foundry/gxwf-foundry`. If the command is not on PATH, run `npx --package @galaxy-foundry/gxwf-foundry foundry validate-galaxy-tool-discovery galaxy-tool-pin.json`. This checks artifact `galaxy-tool-pin` against the galaxy-tool-discovery schema.
+
+## Procedure
+
+Discover whether the Galaxy Tool Shed already publishes a wrapper for the tool a workflow step needs, and resolve the discovery to a `(owner, repo, tool_id, version, changeset_revision)` quintuple that downstream steps can pin and cache.
+
+This skill is the **Tool Shed leg** of the `discover-or-author` branch in Galaxy-targeting per-step pipelines. On a hit, the skill recommends a pin and exits successfully. On a miss (or a low-quality hit), it falls through to author-galaxy-tool-wrapper. The branch itself is harness logic; this skill owns only the discovery half.
+
+### Inputs
+
+The skill expects, per step:
+
+- A free-text **need** describing what the step should do (typically a one-line description of the tool, plus any constraints — file format in/out, container language, license preferences).
+- Optional **owner hint** (e.g. `devteam`, `iuc`) when the caller has a strong prior.
+- Optional **exact-name hint** when the caller knows the canonical XML id.
+
+### Outputs
+
+A structured recommendation object, JSON-shaped:
+
+```json
+{
+  "status": "hit",
+  "candidate": {
+    "tool_shed_url": "https://toolshed.g2.bx.psu.edu",
+    "owner": "devteam",
+    "repo": "fastqc",
+    "tool_id": "fastqc",
+    "trs_tool_id": "devteam~fastqc~fastqc",
+    "version": "0.74+galaxy0",
+    "changeset_revision": "5ec9f6bceaee",
+    "score": 12.3,
+    "matched_terms": ["fastqc"],
+    "match_fields": ["name", "description"],
+    "rationale": "single dominant hit on tool name"
+  },
+  "alternates": [],
+  "rationale": "single dominant hit on tool name; latest version pinned to newest changeset",
+  "warnings": []
+}
+```
+
+`status` semantics:
+- `hit` — recommend pinning. Caller should cache and proceed.
+- `weak` — candidate exists but the skill is not confident (e.g. only help-text matched, multiple owners with similar tools, deprecated repo, stale-index suspicion). Caller should confirm or fall through.
+- `miss` — no usable hit. Caller falls through to author-galaxy-tool-wrapper.
+
+### Procedure
+
+The skill follows the gxwf-shaped discover-and-pin chain. **It does not call the Tool Shed HTTP API directly** — the TS CLI wraps the call sequence and gotchas covered in component-tool-shed-search.
+
+#### 1. Search
+
+Issue tool-search with the need's keywords. Start narrow:
+
+```
+gxwf tool-search "<keywords>" --json --max-results 10
+```
+
+If an owner hint is present, add `--owner <owner>`. If an exact-name hint is present, add `--match-name`. Lowercase the query (the tool index does not lowercase, see component-tool-shed-search §6).
+
+**Normalize a tool-id-shaped need before searching.** A caller (e.g. a template `_plan_context` that guessed a candidate) may hand this skill an XML-id token rather than a human name — `iuc/integron_finder`, `integron_finder`. The lexical index does **not** reliably match the underscored token: `tool-search integron_finder` returns no hits while `integron finder` and `integron` both score. So derive query variants instead of feeding the token verbatim: strip any `owner/` prefix, split on `_` / `-` into space-separated words, and also try the bare significant word. A `miss` is only honest after the name variants have been tried — a no-hit on the raw underscored token alone is a search artifact, not evidence the tool is absent.
+
+#### 2. Triage hits
+
+For each hit, score on:
+- **Name match.** Exact match on `toolId` or `name` is a strong signal; help-only matches are weak.
+- **Owner reputation.** `iuc` and `devteam` repos are typically maintained; an unfamiliar owner with a single-tool repo is a weaker prior. (No machine-readable approval flag exists — the Tool Shed's `approved` field is dead code.)
+- **Recency.** Recent `last_updated` strengthens a hit; very old wrappers can still be valid but warrant the `weak` classification.
+- **Duplicates across repos.** Two owners can publish wrappers with the same XML id. Either pick the maintained one or downgrade to `weak` and surface the choice.
+
+Drop hits from deprecated repos when detectable. Note: deprecated repos can still appear in shed search results until the next index rebuild — see component-tool-shed-search §6.
+
+#### 3. Resolve to a pinnable version
+
+For the top candidate, list versions:
+
+```
+gxwf tool-versions <trsToolId> --json
+```
+
+Pick the newest installable version unless the need specifies otherwise (rare: a workflow may pin to a specific historical version for reproducibility). Be aware that **TRS dedupes by version string** — multiple changesets may publish the same version, and only one is visible at this layer.
+
+#### 4. Resolve to a changeset
+
+Drill from `(trsToolId, version)` to a concrete changeset:
+
+```
+gxwf tool-revisions <trsToolId> --tool-version <v> --latest --json
+```
+
+Prefer `--latest` so the newest changeset publishing that version wins (tool versions are not monotonic; two changesets can legally publish the same version with different content). The output's `changesetRevision` is what lands in the workflow's `tool_shed_repository.changeset_revision` for reproducible reinstall.
+
+#### 5. Classify and emit
+
+Combine the scored hit and the resolved pin into the recommendation object above:
+- One dominant hit + clean version+changeset resolution → `hit`.
+- Multiple plausible hits, ambiguous owner, deprecated suspicion, or only-help-text match → `weak` with the leading candidate plus alternates.
+- No usable hit → `miss`.
+
+Validate the recommendation with `validate-galaxy-tool-discovery` before returning it. Do not rely on prose-only shape checks; downstream phases branch on this contract.
+
+### Caveats baked into the procedure
+
+The procedure assumes — and the skill must surface in its rationale when relevant — the following Tool Shed realities (full detail in component-tool-shed-search §6):
+
+- **Indexes are stale by design.** A freshly published tool may not appear; a deprecated tool may still appear. Treat absence as soft evidence, not proof.
+- **Wildcard `*term*` wrapping** disables stemming; spelling matters. Try alternate phrasings before declaring `miss`. In particular an underscored or owner-prefixed **tool-id token** (`integron_finder`, `iuc/integron_finder`) can score zero where the **human name** (`integron finder`) hits — never declare `miss` on a single id-token query (see §1 normalization).
+- **No EDAM in shed search** — semantic queries that work in Galaxy's installed-toolbox search will not work here. Stick to lexical name/keyword queries.
+- **Same XML id across repos.** Hits collapse only on `(repoName, owner)`; expect duplicates that need triage.
+- **Repo-level discovery is a different surface.** For "find me the *package* that contains a tool about X" with server-side `owner:` / `category:` keywords, `gxwf repo-search` is the right command — out of scope for this skill but a known sibling.
+
+### Non-goals
+
+- **Authoring.** This skill never produces a tool wrapper. On `miss`, the harness's `discover-or-author` branch fall-through invokes author-galaxy-tool-wrapper.
+- **Caching.** This skill emits a pin recommendation. The caller (or the next phase) runs `galaxy-tool-cache add toolshed.g2.bx.psu.edu/repos/<owner>/<repo>/<tool_id> --tool-version <v>` to populate the cache.
+- **Galaxy-instance discovery.** Hitting a running Galaxy server's installed-tool index (EDAM-aware, panel-aware) is a different mechanism — the future `discover-tool-via-galaxy-api` skill. The contrast is sketched in component-tool-shed-search §4.
+- **Test-data resolution.** Out of scope; handled by the `test-data-resolution` branch elsewhere in the pipeline.
+
+## Feedback Mode
+
+- Feedback mode is off unless the caller explicitly enables `--feedback` or supplies a feedback-ledger path.
+- When enabled, read `_feedback.md` before doing the work and use its registered `foundry-feedback.ledger.yml` protocol.
+- Preserve harness-owned run and phase state. Append only concrete observations about a canonical Foundry source asset or a related project that this run showed to be at fault; do not put ordinary workflow requirements in this ledger.
+- Before reporting completion, make one explicit pass over the work you just did. Do not ask yourself whether anything was unclear — recall what happened: where you guessed at something the instructions should have settled, needed information this bundle does not carry, hit an instruction that contradicted another or contradicted the artifacts in front of you, used a packaged reference that did not cover your case, or did something the procedure never describes.
+- Append an entry for each such event that clears the protocol's bar. If none do, append nothing and report `no feedback` explicitly. Silence and a clean pass are not the same thing, and nothing downstream can tell them apart unless you say which one it was.
+- Pass the same ledger path to any subagent used for this work, and merge updates serially so one writer cannot overwrite another.
+
+## Runtime Notes
+
+- Do not read Foundry source files at runtime; use only files packaged in this skill bundle and user-supplied artifacts.
+- Preserve declared artifact filenames unless the user or harness supplies explicit paths.
+- Carry unresolved assumptions into the output artifact instead of silently inventing missing source evidence.

package/extensions/orbit/vendor/skills/discover-shed-tool/_provenance.json

@@ -0,0 +1,130 @@
+{
+  "provenance_schema_version": 4,
+  "cast_target": "claude",
+  "mold": {
+    "name": "discover-shed-tool",
+    "path": "content/molds/discover-shed-tool/index.md",
+    "revision": 5,
+    "content_hash": "05c99cbac2ec6a4d130b06204c15d0e76cf4fd0e00cdc8164dd606dac72809e2",
+    "commit": "63a3f9cf9c97a637fe1628d298e524f35709e289"
+  },
+  "cast_at": "2026-09-13T20:58:27.321Z",
+  "cast_date": "2026-05-07",
+  "cast_revision": 5,
+  "cast_history": [
+    {
+      "rev": 1,
+      "date": "2026-05-05",
+      "note": "initial deterministic cast for Tool Shed discovery"
+    },
+    {
+      "rev": 2,
+      "date": "2026-05-05",
+      "note": "refresh after schema wiki-link merge"
+    },
+    {
+      "rev": 3,
+      "date": "2026-05-07",
+      "note": "deterministic skill render"
+    },
+    {
+      "rev": 4,
+      "date": "2026-05-07",
+      "note": "runtime-facing deterministic skill render"
+    },
+    {
+      "rev": 5,
+      "date": "2026-05-07",
+      "note": "mark discovery schema cast-validated"
+    }
+  ],
+  "refs": [
+    {
+      "kind": "cli-command",
+      "mode": "sidecar",
+      "ref": "[[tool-revisions]]",
+      "src": "content/cli/gxwf/tool-revisions.md",
+      "dst": "references/cli/tool-revisions.json",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Resolve a Tool Shed tool version to an installable changeset revision.",
+      "trigger": "After selecting a candidate version that needs a reproducible changeset pin.",
+      "src_hash": "82061af5970f0fd0335ac3901f6fc33426e192880c6859ab993e55de52bcfd5d",
+      "dst_hash": "db0b13f2b92593c9cd3bf5a80276a31e537c07caff76786167ebe9f7feac5938",
+      "source": "deterministic"
+    },
+    {
+      "kind": "cli-command",
+      "mode": "sidecar",
+      "ref": "[[tool-search]]",
+      "src": "content/cli/gxwf/tool-search.md",
+      "dst": "references/cli/tool-search.json",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Search the Tool Shed for candidate wrappers matching a step's tool need.",
+      "trigger": "When resolving a workflow step to an installable Galaxy tool wrapper.",
+      "src_hash": "cdf8be42eee7134c7cbd7a0a7891f36b0752f8d8d32251fc79664576257fd3dc",
+      "dst_hash": "72f5f7cc0cd5ed40038af89e6041c7916d65c51ba1c7bc7b2c46ba64c51d9359",
+      "source": "deterministic"
+    },
+    {
+      "kind": "cli-command",
+      "mode": "sidecar",
+      "ref": "[[tool-versions]]",
+      "src": "content/cli/gxwf/tool-versions.md",
+      "dst": "references/cli/tool-versions.json",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "List available Tool Shed versions for a selected candidate.",
+      "trigger": "After a Tool Shed search candidate is selected and before pinning a version.",
+      "src_hash": "d11b5ee6d85c3f880cbbdc41bea41f293bbea8dc0671bb409fd81a35a666ee3a",
+      "dst_hash": "90f35a407af778a1a1c714f79ceb8dc3559523964175e734b565eed8b9aeb6a5",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[component-tool-shed-search]]",
+      "src": "content/research/component-tool-shed-search/index.md",
+      "dst": "references/notes/component-tool-shed-search.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Explain Tool Shed search/indexing limitations that affect hit scoring and fallthrough decisions.",
+      "trigger": "When results are missing, weak, duplicated across owners, stale, or ambiguous.",
+      "src_hash": "37d96e364e4618d51a5e59efcc44298d488fa502ec8e93cfde7cc4b01fe68f88",
+      "dst_hash": "37d96e364e4618d51a5e59efcc44298d488fa502ec8e93cfde7cc4b01fe68f88",
+      "source": "deterministic"
+    },
+    {
+      "kind": "schema",
+      "mode": "verbatim",
+      "ref": "[[galaxy-tool-discovery]]",
+      "src": "package://@galaxy-foundry/gxwf-foundry#galaxyToolDiscoverySchema",
+      "dst": "references/schemas/galaxy-tool-discovery.schema.json",
+      "used_at": "runtime",
+      "load": "upfront",
+      "evidence": "cast-validated",
+      "purpose": "Validate the hit, weak, or miss recommendation emitted by Tool Shed discovery.",
+      "verification": "Run discover-shed-tool against known FastQC, ambiguous BWA-style, and no-hit queries and validate each emitted recommendation.",
+      "src_hash": "c0940fc0265e8fd25955f4380f03e088b62d25155fe98e7f051a5a3957d2840c",
+      "dst_hash": "c0940fc0265e8fd25955f4380f03e088b62d25155fe98e7f051a5a3957d2840c",
+      "source": "deterministic"
+    }
+  ],
+  "artifacts": {
+    "produces": [
+      {
+        "id": "galaxy-tool-pin",
+        "kind": "json",
+        "default_filename": "galaxy-tool-pin.json",
+        "schema": "[[galaxy-tool-discovery]]",
+        "description": "(owner, repo, tool_id, version, changeset_revision) pin for a Tool Shed wrapper plus discovery classification."
+      }
+    ],
+    "consumes": []
+  }
+}

package/extensions/orbit/vendor/skills/discover-shed-tool/_required_tools.json

@@ -0,0 +1,18 @@
+[
+  {
+    "tool": "gxwf",
+    "origin": "npm",
+    "package": "@galaxy-tool-util/cli",
+    "package_version": "^1.8.1",
+    "invoke": "gxwf",
+    "invoke_fallback": "npx --yes --package @galaxy-tool-util/cli@1.8.1 gxwf",
+    "availability_check": "gxwf --help | grep -q draft-validate",
+    "docs_url": "https://github.com/jmchilton/galaxy-tool-util-ts/tree/main/packages/cli",
+    "source": "implied",
+    "implied_by": [
+      "gxwf tool-revisions",
+      "gxwf tool-search",
+      "gxwf tool-versions"
+    ]
+  }
+]

package/extensions/orbit/vendor/skills/discover-shed-tool/_verify.json

@@ -0,0 +1,17 @@
+{
+  "verify_schema_version": 1,
+  "entries": [
+    {
+      "artifact_id": "galaxy-tool-pin",
+      "direction": "output",
+      "kind": "json",
+      "default_filename": "galaxy-tool-pin.json",
+      "schema": "[[galaxy-tool-discovery]]",
+      "validator_bin": "foundry",
+      "args": [
+        "validate-galaxy-tool-discovery",
+        "{artifact_path}"
+      ]
+    }
+  ]
+}

package/extensions/orbit/vendor/skills/discover-shed-tool/references/cli/tool-revisions.json

@@ -0,0 +1,48 @@
+{
+  "type": "cli-command",
+  "tool": "gxwf",
+  "command": "tool-revisions",
+  "summary": "Resolve a Tool Shed tool to changeset revisions for reproducible workflow pinning. Final step in discover-and-pin.",
+  "source_path": "content/cli/gxwf/tool-revisions.md",
+  "source_revision": 2,
+  "package": "@galaxy-tool-util/cli",
+  "description": "List changeset revisions that publish a Tool Shed tool (ordered oldest→newest). Use for reproducible (name, owner, changeset_revision) workflow pins. Caveat: version strings are not monotonic — the same version can appear in multiple changesets.",
+  "synopsis": "gxwf tool-revisions [options] <tool-id>",
+  "args": [
+    {
+      "raw": "tool-id",
+      "name": "tool-id",
+      "required": true,
+      "variadic": false,
+      "description": "TRS id (owner~repo~tool_id) or pretty form (owner/repo/tool_id)"
+    }
+  ],
+  "options": [
+    {
+      "flags": "--tool-version <v>",
+      "name": "toolVersion",
+      "description": "Restrict to revisions that publish this exact tool version",
+      "takesArgument": true,
+      "argumentPlaceholder": "<v>",
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--latest",
+      "name": "latest",
+      "description": "Print only the newest matching revision",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--json",
+      "name": "json",
+      "description": "Emit machine-readable JSON envelope",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    }
+  ],
+  "body": "# `gxwf tool-revisions`\n\nResolve a Tool Shed tool to the changeset revisions that publish it, ordered oldest→newest by `get_ordered_installable_revisions`. Needed when emitting a workflow that pins `(name, owner, changeset_revision)` for reproducible reinstall — TRS version strings alone are insufficient because the Tool Shed dedupes versions across changesets.\n\n`<tool-id>` accepts both TRS form (`owner~repo~tool_id`) and pretty form (`owner/repo/tool_id`).\n\n## Output\n\nDefault: lines of `<changesetRevision>\\t<toolVersion>`.\n\n`--json`:\n\n```json\n{\n  \"trsToolId\": \"devteam~fastqc~fastqc\",\n  \"version\": \"0.74+galaxy0\",\n  \"revisions\": [\n    { \"changesetRevision\": \"5ec9f6bceaee\", \"toolVersion\": \"0.74+galaxy0\" }\n  ]\n}\n```\n\n`--json` without `--tool-version` returns every installable revision for the tool, each tagged with whatever XML `version` it publishes.\n\n## Examples\n\n```bash\ngxwf tool-revisions devteam/fastqc/fastqc --json\ngxwf tool-revisions devteam/fastqc/fastqc --tool-version 0.74+galaxy0 --latest\ngxwf tool-revisions devteam~fastqc~fastqc --json | jq '.revisions[-1]'\n```\n\nPin the latest changeset for a known version:\n\n```bash\nREV=$(gxwf tool-revisions devteam/fastqc/fastqc \\\n        --tool-version 0.74+galaxy0 --latest --json \\\n        | jq -r '.revisions[0].changesetRevision')\necho \"$REV\"\n```\n\n## Gotchas\n\n- **Tool versions are not monotonic.** Two changesets can legally publish the same XML `version` with different content. When pinning for reproducibility, prefer the **newest matching revision** (`--latest`) or be explicit about which changeset you want — the version string alone is ambiguous. See component-tool-shed-search §5.\n- **Source of truth for installability.** Only changesets with a `RepositoryMetadata` row marked `downloadable=True` are returned. A repository may have many additional changesets in its Mercurial history that are not installable; those are correctly excluded here.\n- **Pin shape is `(name, owner, changeset_revision)`**, not the TRS id. Workflows ultimately reference repos as a triple via the Tool Shed's `get_repository_revision_install_info`. The `trsToolId` exists for discovery only.\n- **No bulk endpoint upstream.** Each tool's revision list is one HTTP call; batching N tools means N round-trips. Acceptable for the discover-and-pin path of a workflow author; do not loop over thousands.\n\n## Pairs with\n\n- tool-search → tool-versions → tool-revisions is the canonical discover-and-pin chain.\n- `galaxy-tool-cache add toolshed.g2.bx.psu.edu/repos/<owner>/<repo>/<tool_id> --tool-version <v>` — caches the `ParsedTool` once a version is chosen; the changeset revision pin lands in the workflow file (`tool_shed_repository.changeset_revision`), not in the cache."
+}

package/extensions/orbit/vendor/skills/discover-shed-tool/references/cli/tool-search.json

@@ -0,0 +1,95 @@
+{
+  "type": "cli-command",
+  "tool": "gxwf",
+  "command": "tool-search",
+  "summary": "Free-text Tool Shed search returning candidate tools as JSON; first step in the discover-and-pin sequence.",
+  "source_path": "content/cli/gxwf/tool-search.md",
+  "source_revision": 2,
+  "package": "@galaxy-tool-util/cli",
+  "description": "Search the Galaxy Tool Shed for tools matching a query",
+  "synopsis": "gxwf tool-search [options] <query>",
+  "args": [
+    {
+      "raw": "query",
+      "name": "query",
+      "required": true,
+      "variadic": false,
+      "description": "Search text (e.g. 'fastqc')"
+    }
+  ],
+  "options": [
+    {
+      "flags": "--page-size <n>",
+      "name": "pageSize",
+      "description": "Server-side page size",
+      "takesArgument": true,
+      "argumentPlaceholder": "<n>",
+      "optionalArgument": false,
+      "negatable": false,
+      "defaultValue": "20"
+    },
+    {
+      "flags": "--max-results <n>",
+      "name": "maxResults",
+      "description": "Hard cap on hits returned",
+      "takesArgument": true,
+      "argumentPlaceholder": "<n>",
+      "optionalArgument": false,
+      "negatable": false,
+      "defaultValue": "50"
+    },
+    {
+      "flags": "--page <n>",
+      "name": "page",
+      "description": "Starting page (1-indexed)",
+      "takesArgument": true,
+      "argumentPlaceholder": "<n>",
+      "optionalArgument": false,
+      "negatable": false,
+      "defaultValue": "1"
+    },
+    {
+      "flags": "--owner <user>",
+      "name": "owner",
+      "description": "Filter hits to a single repo owner (client-side)",
+      "takesArgument": true,
+      "argumentPlaceholder": "<user>",
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--match-name",
+      "name": "matchName",
+      "description": "Drop hits where the query is not a token in the tool name",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--json",
+      "name": "json",
+      "description": "Emit machine-readable JSON envelope",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--enrich",
+      "name": "enrich",
+      "description": "Resolve each hit's ParsedTool and attach it as `parsedTool` (one fetch per hit; off by default)",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--cache-dir <dir>",
+      "name": "cacheDir",
+      "description": "Tool cache directory (used by --enrich; shared with galaxy-tool-cache)",
+      "takesArgument": true,
+      "argumentPlaceholder": "<dir>",
+      "optionalArgument": false,
+      "negatable": false
+    }
+  ],
+  "body": "# `gxwf tool-search`\n\nFree-text search over the Galaxy Tool Shed's tool index. Designed to feed `galaxy-tool-cache add` (and the rest of the `tool-versions` / `tool-revisions` chain) so a workflow author can go from a query string to a cached `ParsedTool` in a small number of commands.\n\nInstance-agnostic; targets `https://toolshed.g2.bx.psu.edu` by default.\n\n`<query>` is free text; whitespace separates terms. The Tool Shed wraps the term as `*term*` server-side, so noisy queries can match description and help text.\n\n## Output\n\nDefault: human-readable list.\n\n`--json`:\n\n```json\n{\n  \"query\": \"fastqc\",\n  \"hits\": [\n    {\n      \"toolId\": \"fastqc\",\n      \"name\": \"FastQC\",\n      \"description\": \"Read Quality reports\",\n      \"owner\": \"devteam\",\n      \"repoName\": \"fastqc\",\n      \"trsToolId\": \"devteam~fastqc~fastqc\",\n      \"score\": 12.3\n    }\n  ]\n}\n```\n\nA hit identifies `(owner, repoName, toolId)` plus a `trsToolId` (`owner~repo~toolId`). It does **not** include a changeset revision or specific tool version — those come from tool-versions and tool-revisions.\n\n## Examples\n\n```bash\ngxwf tool-search fastqc\ngxwf tool-search \"quality control\" --json --max-results 10\ngxwf tool-search bwa --owner devteam --match-name --json\n```\n\nPipe the top hit into the rest of the pin chain:\n\n```bash\ngxwf tool-search fastqc --json --max-results 5 \\\n  | jq -r '.hits[0].trsToolId' \\\n  | xargs gxwf tool-versions --latest --json\n```\n\n## Gotchas\n\n- **No EDAM**, no stem analyzer, no panel context — the Tool Shed tool index is much poorer than Galaxy's installed-toolbox index. Queries match only `name`, `description`, `help`, and `repo_owner_username`. See component-tool-shed-search §2b.\n- **Case-sensitivity asymmetry**. The tool search does not lowercase the query (unlike repo search). Mixed-case queries can miss; lowercase if uncertain.\n- **Stale indexes**. Tool Shed Whoosh indexes are rebuilt by cron / admin action, never automatically on upload. A freshly published tool may not show up for some time. Deprecated repos can still appear until the next rebuild.\n- **`*term*` wrapping** disables server-side stemming and structured query syntax. Prefer simple terms; combine `--match-name` and `--owner` to tighten.\n- **No exact-id matching**. The shed indexes `id` as `TEXT`, not Whoosh `ID`, so it tokenizes — you cannot pin a hit to an exact GUID via search.\n- **Same XML id across repos**. The same logical tool (e.g., `bwa`) can be wrapped and published in multiple independent repos. Hits collapse only by `(repoName, owner)`; expect duplicates that need human triage.\n- **Repo-level discovery is a different command**. For \"find me a *package* about X\" with server-side `owner:` / `category:` keywords and popularity-boosted ranking, use `gxwf repo-search` instead.\n\n## Pairs with\n\n- tool-versions — list TRS-published versions for a hit's `trsToolId`.\n- tool-revisions — resolve a `(trsToolId, version)` to changeset revisions for reproducible pinning.\n- `galaxy-tool-cache add` — terminal step of the discover-and-pin chain."
+}

package/extensions/orbit/vendor/skills/discover-shed-tool/references/cli/tool-versions.json

@@ -0,0 +1,39 @@
+{
+  "type": "cli-command",
+  "tool": "gxwf",
+  "command": "tool-versions",
+  "summary": "List TRS-published versions of a Tool Shed tool, oldest→newest. Second step in the discover-and-pin sequence.",
+  "source_path": "content/cli/gxwf/tool-versions.md",
+  "source_revision": 2,
+  "package": "@galaxy-tool-util/cli",
+  "description": "List TRS-published versions of a Tool Shed tool (newest last)",
+  "synopsis": "gxwf tool-versions [options] <tool-id>",
+  "args": [
+    {
+      "raw": "tool-id",
+      "name": "tool-id",
+      "required": true,
+      "variadic": false,
+      "description": "TRS id (owner~repo~tool_id) or pretty form (owner/repo/tool_id)"
+    }
+  ],
+  "options": [
+    {
+      "flags": "--json",
+      "name": "json",
+      "description": "Emit machine-readable JSON envelope",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--latest",
+      "name": "latest",
+      "description": "Print only the latest version",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    }
+  ],
+  "body": "# `gxwf tool-versions`\n\nList the TRS-published versions of a Tool Shed tool, ordered oldest→newest (newest last). Used after tool-search has surfaced a candidate `trsToolId` and the caller needs to pick a version to cache.\n\n`<tool-id>` accepts both forms:\n- TRS form: `owner~repo~tool_id` (e.g. `devteam~fastqc~fastqc`).\n- Pretty form: `owner/repo/tool_id` (e.g. `devteam/fastqc/fastqc`).\n\nThe `~` form is the Tool Shed's TRS encoding (slashes break FastAPI path-param decoding); the CLI accepts both and normalizes.\n\n## Output\n\nDefault: one version string per line, oldest first.\n\n`--json`:\n\n```json\n{\n  \"trsToolId\": \"devteam~fastqc~fastqc\",\n  \"versions\": [\"0.72+galaxy1\", \"0.73+galaxy0\", \"0.74+galaxy0\"]\n}\n```\n\n`--latest --json`:\n\n```json\n{\n  \"trsToolId\": \"devteam~fastqc~fastqc\",\n  \"versions\": [\"0.74+galaxy0\"]\n}\n```\n\n## Examples\n\n```bash\ngxwf tool-versions devteam/fastqc/fastqc\ngxwf tool-versions devteam~fastqc~fastqc --latest\ngxwf tool-versions devteam/fastqc/fastqc --json\n```\n\n## Gotchas\n\n- **TRS dedupes by version string.** If multiple changesets publish the same `version` (which is legal — the XML version field is not monotonic and not enforced unique), only the last-seen one appears. The other changesets are invisible at this layer. To see the full set of changesets that publish a given version, use tool-revisions. See component-tool-shed-search §3 and §5.\n- **`--latest` returns the lexicographically/iteration-order last item, not a semver-parsed maximum.** In practice the TRS list is ordered consistent with the Tool Shed's installable-revisions ordering, so \"newest\" is normally what you want — but do not assume strict semver semantics.\n- **Versions ≠ changesets.** A single TRS version can correspond to multiple changesets in the underlying Mercurial repo. Pinning a workflow for reproducible reinstall requires a `(name, owner, changeset_revision)` triple, not just a version — that is what tool-revisions produces.\n- **Stub list endpoint.** The Tool Shed's TRS `/tools` enumerator is unimplemented (returns `[]`). You cannot bulk-list tools via TRS; you must already have a `trsToolId` from search or a known input.\n\n## Pairs with\n\n- tool-search — produces the `trsToolId` consumed here.\n- tool-revisions — drills from a `(trsToolId, version)` down to changeset revisions.\n- `galaxy-tool-cache add toolshed.g2.bx.psu.edu/repos/<owner>/<repo>/<tool_id> --tool-version <v>` — caches the picked version's `ParsedTool`."
+}