fix: update command examples to remove 'npx' and improve formatting in run documentation

Author: pelikhan

docs/src/content/docs/reference/cli/run.mdx

@@ -1,52 +1,54 @@
 ---
 title: Run
-description: Learn how to execute genai scripts on files with streaming output
-    to stdout, including usage of glob patterns, environment variables, and output
-    options.
+description:
+  Learn how to execute genai scripts on files with streaming output
+  to stdout, including usage of glob patterns, environment variables, and output
+  options.
 sidebar:
-    order: 1
-keywords: CLI tool execution, genai script running, stdout streaming, file
-    globing, environment configuration
+  order: 1
+keywords:
+  CLI tool execution, genai script running, stdout streaming, file
+  globing, environment configuration
 hero:
-    image:
-        alt:
-            An abstract 8-bit style illustration depicts a colorful terminal window
-            featuring a simple gear, a cloud, and a document icon, all rendered in
-            bold, flat geometric shapes. Multiple file icons with glowing outlines
-            overlap each other, accompanied by a small branching arrow symbolizing a
-            pipeline, and a stylized folder icon. The color palette uses five
-            distinct, bold corporate colors, and the image is strictly 2D, without
-            background, text, shadows, or gradients. The layout is compact, sized at
-            128 by 128 pixels.
-        file: ./run.png
+  image:
+    alt:
+      An abstract 8-bit style illustration depicts a colorful terminal window
+      featuring a simple gear, a cloud, and a document icon, all rendered in
+      bold, flat geometric shapes. Multiple file icons with glowing outlines
+      overlap each other, accompanied by a small branching arrow symbolizing a
+      pipeline, and a stylized folder icon. The color palette uses five
+      distinct, bold corporate colors, and the image is strictly 2D, without
+      background, text, shadows, or gradients. The layout is compact, sized at
+      128 by 128 pixels.
+    file: ./run.png
 ---
 
 Runs a script on files and streams the LLM output to stdout or a folder from the workspace root.
 
 ```bash
-npx genaiscript run <script> "<files...>"
+genaiscript run <script> "<files...>"
 ```
 
 where `<script>` is the id or file path of the tool to run, and `<files...>` is the name of the spec file to run it on.
 
 Files can also include [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) pattern.
 
 ```sh
-npx genaiscript run code-annotator "src/*.ts"
+genaiscript run code-annotator "src/*.ts"
 ```
 
 If multiple files are specified, all files are included in `env.files`.
 
 ```sh
-npx genaiscript run <script> "src/*.bicep" "src/*.ts"
+genaiscript run <script> "src/*.bicep" "src/*.ts"
 ```
 
 ## Files
 
 `run` takes one or more [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) patterns to match files in the workspace.
 
 ```bash
-npx genaiscript run <script> "**/*.md" "**/*.ts"
+genaiscript run <script> "**/*.md" "**/*.ts"
 ```
 
 ### Resource resolutions
@@ -74,15 +76,15 @@ cat README.md | genaiscript run summarize > summary.md
 Excludes the specified files from the file set.
 
 ```sh "--excluded-files <excluded-files...>"
-npx genaiscript run <script> <files> --excluded-files <excluded-files...>
+genaiscript run <script> <files> --excluded-files <excluded-files...>
 ```
 
 ### `--exclude-git-ignore`
 
 Exclude files ignored by the `.gitignore` file at the workspace root.
 
 ```sh "--exclude-git-ignore"
-npx genaiscript run <script> <files> --exclude-git-ignore
+genaiscript run <script> <files> --exclude-git-ignore
 ```
 
 ## Configuration
@@ -106,13 +108,13 @@ Populate values in the `env.vars` map that can be used when running the prompt.
 Saves the results in a JSON file, along with markdown files of the output and the trace.
 
 ```sh "--out tmp"
-npx genaiscript run <script> <files> --out out/res.json
+genaiscript run <script> <files> --out out/res.json
 ```
 
 If `file` does not end with `.json`, the path is treated as a directory path.
 
 ```sh "--out tmp"
-npx genaiscript run <script> <files> --out tmp
+genaiscript run <script> <files> --out tmp
 ```
 
 ### `--json`
@@ -121,25 +123,25 @@ Output the entire response as JSON to the stdout.
 
 ### `--out-trace` _file_
 
-Save the markdown trace to the specified file.
+Save the markdown trace to the specified file. Use `--no-out-trace` to disable the trace output.
 
 ```sh wrap
-npx genaiscript run <script> <files> --out-trace file
+genaiscript run <script> <files> --out-trace file
 ```
 
 In a GitHub Actions workflow, you can use this feature to save the trace as a step summary (`GITHUB_STEP_SUMMARY`):
 
 ```yaml title=".github/workflows/genaiscript.yml" wrap
 - name: Run GenAIScript tool on spec
   run: |
-      genaiscript run <script> <files> --out-trace $GITHUB_STEP_SUMMARY
+    genaiscript run <script> <files> --out-trace $GITHUB_STEP_SUMMARY
 ```
 
 In Azure Dev Ops, you can use the [task.uploadSummary](https://learn.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands?view=azure-devops&tabs=bash#uploadsummary-add-some-markdown-content-to-the-build-summary)
 in your pipeline to upload the trace as a summary.
 
 ```yaml title="genaiscript.pipeline.yml" "##vso[task.uploadsummary]" wrap
-- script: npx --yes genaiscript run poem --out-trace $(System.DefaultWorkingDirectory)/trace.md
+- script: --yes genaiscript run poem --out-trace $(System.DefaultWorkingDirectory)/trace.md
   displayName: "Run GenAIScript tool"
   continueOnError: true
 - script: echo "##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/trace.md"
@@ -151,13 +153,13 @@ in your pipeline to upload the trace as a summary.
 Emit annotations in the specified file as a JSON array, JSON Lines, [SARIF](https://sarifweb.azurewebsites.net/) or a CSV file if the file ends with `.csv`.
 
 ```sh wrap
-npx genaiscript run <script> <files> --out-annotations diags.csv
+genaiscript run <script> <files> --out-annotations diags.csv
 ```
 
 Use JSON lines (`.jsonl`) to aggregate annotations from multiple runs in a single file.
 
 ```sh wrap
-npx genaiscript run <script> <files> --out-annotations diags.jsonl
+genaiscript run <script> <files> --out-annotations diags.jsonl
 ```
 
 ### `--out-data` _file_
@@ -166,15 +168,24 @@ Emits parsed data as JSON, YAML or JSONL. If a JSON schema is specified
 and available, the JSON validation result is also stored.
 
 ```sh
-npx genaiscript run <script> <files> --out-data data.jsonl
+genaiscript run <script> <files> --out-data data.jsonl
 ```
 
 ### `--out-changelogs` _file_
 
 Emit changelogs in the specified file as text.
 
 ```sh
-npx genaiscript run <script> <files> --out-changelogs changelogs.txt
+genaiscript run <script> <files> --out-changelogs changelogs.txt
+```
+
+## Remote scripts
+
+You can specify a repository, branch to run a script from a remote repository. In that mode,
+the scripts from the current repository are ignored.
+
+```sh
+genaiscript run --remote <owner>/<repo>
 ```
 
 ## Pull Requests and Issues <a href="" id="pull-requests" />
@@ -189,13 +200,13 @@ Update your workflow configuration to include the following:
 
 ```yaml
 permissions:
-    pull-requests: write
+  pull-requests: write
 ```
 
 - set the `GITHUB_TOKEN` secret in the `env` when running the cli
 
 ```yaml
-    - run: npx --yes genaiscript run ... --pull-request-comment --out-trace $GITHUB_STEP_SUMMARY
+    - run: --yes genaiscript run ... --pull-request-comment --out-trace $GITHUB_STEP_SUMMARY
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ... # LLM secrets
@@ -207,7 +218,7 @@ permissions:
 - pass secrets to scripts, including `System.AccessToken`
 
 ```yaml
-- script: npx genaiscript run ... --pull-request-description
+- script: genaiscript run ... --pull-request-description
   env:
     SYSTEM_ACCESSTOKEN: $(System.AccessToken)
     ... # LLM secrets
@@ -219,7 +230,7 @@ When running within a GitHub Action or Azure DevOps pipeline on a pull request,
 the CLI inserts the LLM output in the description of the pull request ([example](https://github.com/microsoft/genaiscript/pull/564))
 
 ```sh
-npx genaiscript run ... --pull-request-description
+genaiscript run ... --pull-request-description
 ```
 
 The `tag` parameter is a unique id used to differentiate description generate by different runs. Default is the script id.
@@ -229,7 +240,7 @@ The `tag` parameter is a unique id used to differentiate description generate by
 Upserts a comment on the pull request/issue with the LLM output ([example](https://github.com/microsoft/genaiscript/pull/564#issuecomment-2200474305))
 
 ```sh
-npx genaiscript run ... --pull-request-comment
+genaiscript run ... --pull-request-comment
 ```
 
 The `tag` parameter is a unique id used to differentiate description generate by different runs. Default is the script id.
@@ -240,7 +251,7 @@ Create pull request review comments from each [annotations](/genaiscript/referen
 ([example](https://github.com/microsoft/genaiscript/pull/564#pullrequestreview-2151692644)).
 
 ```sh
-npx genaiscript run ... --pull-request-reviews
+genaiscript run ... --pull-request-reviews
 ```
 
 ## Read more