docs: align CLI docs and install guidance

.agents/skills

@@ -0,0 +1 @@
+../.claude/skills

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -77,8 +77,8 @@ Full documentation is at **<https://pipelinesascode.com>**
 Install the CLI and bootstrap your first repository:
 
 ```shell
-brew install tektoncd/pipelines-as-code/tkn-pac
-tkn pac bootstrap github
+brew install --cask openshift-pipelines/pipelines-as-code/tektoncd-pac
+tkn pac bootstrap
 ```
 
 Then follow the [getting started tutorial](https://pipelinesascode.com/docs/getting-started/).

config/302-pac-configmap.yaml

@@ -43,8 +43,8 @@ data:
   # i.e: "owner/private-repo1, org/repo2"
   secret-github-app-scope-extra-repos: ""
 
-  # The default hub url to use, by default it is artifacthub.
-  hub-url: "https://artifacthub.io"
+  # The default hub API url to use, by default it is Artifact Hub's API.
+  hub-url: "https://artifacthub.io/api/v1"
 
   # The default hub catalog type, by default it is artifacthub.
   # Other supported values: tektonhub (for custom self-hosted Tekton Hub instances)

docs/content/docs/api/configmap.md

@@ -57,11 +57,11 @@ secret-github-app-scope-extra-repos: "owner/private-repo1, org/repo2"
 
 ### Hub Configuration
 
-{{< param name="hub-url" type="string" default="<https://artifacthub.io>" id="param-hub-url" >}}
-Specifies the default hub URL that Pipelines-as-Code uses to fetch remote tasks.
+{{< param name="hub-url" type="string" default="<https://artifacthub.io/api/v1>" id="param-hub-url" >}}
+Specifies the default hub API URL that Pipelines-as-Code uses to fetch remote tasks.
 
 ```yaml
-hub-url: "https://artifacthub.io"
+hub-url: "https://artifacthub.io/api/v1"
 ```
 
 {{< /param >}}
@@ -89,7 +89,7 @@ Name of the catalog.
 {{< /param >}}
 
 {{< param name="catalog-{N}-url" type="string" id="param-catalog-n-url" >}}
-URL of the catalog API.
+URL of the catalog API endpoint.
 {{< /param >}}
 
 {{< param name="catalog-{N}-type" type="string" id="param-catalog-n-type" >}}
@@ -163,6 +163,16 @@ custom-console-url-pr-tasklog: "https://url/ns/{{ namespace }}/{{ pr }}/logs/{{
 
 {{< /param >}}
 
+{{< param name="custom-console-url-namespace" type="string" id="param-custom-console-url-namespace" >}}
+Defines the template URL for namespace-level views in your custom console.
+Supports the `{{ namespace }}` variable.
+
+```yaml
+custom-console-url-namespace: "https://url/ns/{{ namespace }}"
+```
+
+{{< /param >}}
+
 ### Error Detection and Logging
 
 {{< param name="error-log-snippet" type="boolean" default="true" id="param-error-log-snippet" >}}
@@ -351,7 +361,7 @@ data:
   secret-github-app-token-scoped: "true"
   secret-github-app-scope-extra-repos: "org/shared-repo"
 
-  hub-url: "https://artifacthub.io"
+  hub-url: "https://artifacthub.io/api/v1"
   hub-catalog-type: "artifacthub"
   remote-tasks: "true"
 

docs/content/docs/api/settings.md

@@ -32,6 +32,19 @@ settings:
 
 {{< /param >}}
 
+{{< param name="gitops_command_prefix" type="string" id="param-gitops-command-prefix" >}}
+Sets a custom prefix for GitOps commands such as `/test`, `/retest`, and `/cancel`.
+Use a plain word such as `pac`; Pipelines-as-Code adds the leading slash
+automatically. For command behavior and examples, see the
+[GitOps commands guide]({{< relref "/docs/guides/gitops-commands/advanced" >}}).
+
+```yaml
+settings:
+  gitops_command_prefix: "pac"
+```
+
+{{< /param >}}
+
 {{< param name="policy" type="Policy" >}}
 Defines authorization policies for the repository. These policies control which users can trigger PipelineRuns under different conditions.
 
@@ -270,6 +283,8 @@ Specifies the LLM model for this role. If omitted, Pipelines-as-Code uses provid
 
 {{< param name="roles[].on_cel" type="string" id="param-roles-on-cel" >}}
 Defines a CEL expression that determines when Pipelines-as-Code triggers this role.
+Use the structured LLM CEL context, such as `body.event.*`,
+`body.pipelineRun.*`, and `body.repository.*`.
 {{< /param >}}
 
 {{< param name="roles[].output" type="string" id="param-roles-output" >}}
@@ -321,7 +336,7 @@ settings:
       - name: "failure-analysis"
         prompt: "Analyze the following CI/CD failure and suggest fixes"
         model: "gpt-4"
-        on_cel: "event_type == 'pull_request' && status == 'failed'"
+        on_cel: 'body.event.event_type == "pull_request" && body.pipelineRun.status.conditions[0].status == "False"'
         context_items:
           commit_content: true
           error_content: true
@@ -385,7 +400,7 @@ spec:
             2. Specific fix recommendations
             3. Prevention strategies
           model: "gpt-4"
-          on_cel: 'event_type == "pull_request" && status == "failed"'
+          on_cel: 'body.event.event_type == "pull_request" && body.pipelineRun.status.conditions[0].status == "False"'
           output: "pr-comment"
           context_items:
             commit_content: true
@@ -397,7 +412,7 @@ spec:
         - name: "security-review"
           prompt: "Review this change for potential security issues"
           model: "gpt-4"
-          on_cel: 'event_type == "pull_request" && has_label("security-review")'
+          on_cel: '"security-review" in body.event.pull_request_labels'
           context_items:
             commit_content: true
             pr_content: true

docs/content/docs/cli/_index.md

@@ -10,26 +10,32 @@ This section covers the `tkn pac` command-line tool, which you use to install, c
 Pipelines-as-Code provides a CLI designed to work as a plug-in to the [Tekton CLI (tkn)](https://github.com/tektoncd/cli). With `tkn pac`, you can:
 
 * `bootstrap`: Install and configure Pipelines-as-Code with a GitHub App.
+* `cel`: Evaluate CEL expressions locally against webhook payloads.
+* `completion`: Generate shell completion scripts.
 * `create` / `delete`: Create or remove a Repository CR linked to your Git repository.
 * `generate`: Scaffold a starter PipelineRun in your `.tekton/` directory.
 * `list`: List Repository CRs and their current PipelineRun status.
 * `describe`: View details of a Repository CR and its associated runs.
 * `logs`: Stream the logs of a PipelineRun attached to a Repository CR.
 * `resolve`: Process a PipelineRun locally as Pipelines-as-Code would on the server.
-* `webhook`: Add or update webhook secrets for your Git provider.
 * `info`: Display installation details and test globbing patterns.
+* `version`: Show the installed CLI version.
+* `webhook`: Add or update webhook secrets for your Git provider.
 
 {{< cards >}}
   {{< card link="installation" title="Installation" subtitle="Install the tkn-pac plugin" >}}
   {{< card link="bootstrap" title="bootstrap" subtitle="Install PAC and create a GitHub App" >}}
+  {{< card link="cel" title="cel" subtitle="Evaluate CEL expressions locally" >}}
+  {{< card link="completion" title="completion" subtitle="Generate shell completion scripts" >}}
   {{< card link="create" title="create / delete" subtitle="Create or remove a Repository CR" >}}
   {{< card link="repository" title="list" subtitle="List Repository CRs and status" >}}
   {{< card link="describe" title="describe" subtitle="Details of a Repository and its runs" >}}
   {{< card link="generate" title="generate" subtitle="Scaffold a PipelineRun" >}}
   {{< card link="logs" title="logs" subtitle="Stream PipelineRun logs" >}}
   {{< card link="resolve" title="resolve" subtitle="Resolve a PipelineRun locally" >}}
-  {{< card link="webhook" title="webhook" subtitle="Add or update webhook secrets" >}}
   {{< card link="info" title="info" subtitle="Installation details and globbing" >}}
+  {{< card link="version" title="version" subtitle="Show the installed CLI version" >}}
+  {{< card link="webhook" title="webhook" subtitle="Add or update webhook secrets" >}}
 {{< /cards >}}
 
 ## Screenshot

docs/content/docs/cli/bootstrap.md

@@ -42,4 +42,10 @@ Do not use gosmee in production environments. It is intended for testing only.
 
 ## bootstrap github-app
 
-To create only a GitHub App without running the full bootstrap process, use `tkn pac bootstrap github-app`. This skips the installation step and only creates the GitHub App and the corresponding secret in the `pipelines-as-code` namespace.
+Use `tkn pac bootstrap github-app` when you want help creating the GitHub App without running the full interactive bootstrap flow.
+
+This command does not perform the installation flow from `tkn pac bootstrap`. It creates the GitHub App configuration and the corresponding secret for a fresh Pipelines-as-Code setup.
+
+{{< callout type="info" >}}
+If Pipelines-as-Code is already installed, the command exits unless you pass `--force-install`.
+{{< /callout >}}

docs/content/docs/cli/completion.md

@@ -39,6 +39,12 @@ Load completions in the current session:
 source <(tkn pac completion zsh)
 ```
 
+If shell completion is not already enabled in your environment, run this once first:
+
+```shell
+echo "autoload -U compinit; compinit" >> ~/.zshrc
+```
+
 To load completions automatically for every session, run once:
 
 ```shell
@@ -58,3 +64,11 @@ To load completions automatically for every session, run once:
 ```shell
 tkn pac completion fish > ~/.config/fish/completions/tkn-pac.fish
 ```
+
+### PowerShell
+
+Load completions in the current session:
+
+```powershell
+tkn pac completion powershell | Out-String | Invoke-Expression
+```

docs/content/docs/cli/create.md

@@ -9,7 +9,7 @@ Use `tkn pac create` and `tkn pac delete` to manage Repository CRs. These comman
 
 ```shell
 tkn pac create repo
-tkn pac delete repo [--cascade]
+tkn pac delete repo <repository-name> [--cascade]
 ```
 
 ## Creating a Repository CR
@@ -20,6 +20,6 @@ If you have not configured a Git provider previously, the command prompts you to
 
 ## Deleting a Repository CR
 
-`tkn pac delete repo` deletes a Repository CR.
+`tkn pac delete repo <repository-name>` deletes a Repository CR. You can also use the full subcommand name, `tkn pac delete repository <repository-name>`.
 
 Specify the `--cascade` flag to also delete the attached secrets (such as webhook or provider secrets) associated with the Repository CR.

docs/content/docs/cli/installation.md

@@ -27,7 +27,7 @@ On Windows, tkn-pac will look for the Kubernetes config in `%USERPROFILE%\.kube\
 {{< /tab >}}
 
 {{< tab name="Homebrew" >}}
-The `tkn pac` plug-in is available from Homebrew as a "Tap". Install it with:
+The `tkn pac` plug-in is available from Homebrew as a cask. Install it with:
 
 ```shell
 brew install --cask openshift-pipelines/pipelines-as-code/tektoncd-pac

docs/content/docs/dev/architecture.md

@@ -408,8 +408,8 @@ data:
   # Application settings
   application-name: "Pipelines as Code"
 
-  # Tekton Hub URL
-  hub-url: "https://api.hub.tekton.dev/v1"
+  # Artifact Hub API URL
+  hub-url: "https://artifacthub.io/api/v1"
 
   # Remote tasks support
   remote-tasks: "true"

docs/content/docs/guides/llm-analysis/_index.md

@@ -93,7 +93,7 @@ Each role defines a specific analysis scenario. You can configure multiple roles
 | `name` | string | Yes | Unique identifier for this role |
 | `prompt` | string | Yes | Prompt template for the LLM |
 | `model` | string | No | Model name (consult provider documentation for available models). Uses provider default if not specified. |
-| `on_cel` | string | No | CEL expression for conditional triggering. If not specified, the role will always run. |
+| `on_cel` | string | No | CEL expression for conditional triggering. If not specified, the role runs only for failed PipelineRuns. |
 | `output` | string | Yes | Output destination (currently only `pr-comment` is supported) |
 | `context_items` | object | No | Configuration for context inclusion |
 
@@ -129,4 +129,3 @@ When you set `commit_content: true`, Pipelines-as-Code includes the following fi
 - Pipelines-as-Code **intentionally excludes email addresses** from the commit context to protect personally identifiable information (PII) when sending data to external LLM providers.
 - Fields appear only if your Git provider makes them available. Some providers supply limited information (for example, Bitbucket Cloud provides only the author name).
 - Author and committer may be the same person or different (for example, when using `git commit --amend` or rebasing).
-asing).

docs/content/docs/guides/repository-crd/comment-settings.md

@@ -7,10 +7,10 @@ This page explains how to control the volume and behavior of Pull/Merge Request
 
 For GitHub (Webhook), GitLab, and Gitea/Forgejo integrations, you can control which
 Pull/Merge Request comments Pipelines-as-Code posts by using
-the `spec.<provider>.comment_strategy` setting. This is useful for reducing notification
+the `spec.settings.<provider>.comment_strategy` setting. This is useful for reducing notification
 volume in repositories that use long-lasting Pull/Merge Requests with many PipelineRuns.
 
-The `spec.<provider>.comment_strategy` field accepts `""`
+The `spec.settings.<provider>.comment_strategy` field accepts `""`
 (default), `"update"`, and `"disable_all"`.
 
 Setting `comment_strategy` to `update` creates a single comment for

docs/content/docs/guides/repository-crd/github-token-scoping.md

@@ -23,14 +23,21 @@ When using a GitHub webhook, the scoping of the token is what you set when creat
 ## Prerequisites
 
 - You must have Pipelines-as-Code installed with the **GitHub App** method. Token scoping does not apply to webhook-based installations because the token scope is determined by your personal access token.
-- In the `pipelines-as-code` ConfigMap, set the `secret-github-app-token-scoped` key to `false`.
-This setting enables Pipelines-as-Code to scope the GitHub token to private and public repositories listed in the global and repository level configuration.
+
+| Scoping method | `secret-github-app-token-scoped` setting |
+| --- | --- |
+| **Global** (`secret-github-app-scope-extra-repos`) | Can stay `true` (default) |
+| **Repository-level** (`settings.github_app_token_scope_repos`) | Must be `false` |
+| **Both combined** | Can stay `true` |
 
 ## Scoping the GitHub token using Global configuration
 
 Use the global configuration to define a list of repositories accessible from any Repository CR in any namespace.
 You can specify repositories using exact names or glob patterns (for example, `myorg/*` to match all repositories under an organization where the app is installed).
 
+Unlike repository-level scoping, this global configuration does not require you to disable
+`secret-github-app-token-scoped`.
+
 To set the global configuration, add the `secret-github-app-scope-extra-repos` key to the `pipelines-as-code` ConfigMap as shown in the following example:
 
   ```yaml
@@ -49,6 +56,10 @@ You can also use the Repository CR to scope the generated GitHub token to a list
 The repositories can be public or private, but must reside in the same namespace as the Repository CR.
 You can specify repositories using exact names or glob patterns (for example, `myorg/*` to match all repositories under an organization that has the GitHub App installed).
 
+When you use only `settings.github_app_token_scope_repos`, set
+`secret-github-app-token-scoped` to `false`. Otherwise Pipelines-as-Code rejects the
+repository-level scope extension request.
+
 Set the `github_app_token_scope_repos` field in the Repository CR spec, as shown in the following example:
 
   ```yaml

docs/content/docs/installation/openshift.md

@@ -57,7 +57,7 @@ spec:
           enable-cancel-in-progress-on-pull-requests: 'false'
           enable-cancel-in-progress-on-push: 'false'
           skip-push-event-for-pr-commits: 'true'
-          hub-url: 'https://artifacthub.io'
+          hub-url: 'https://artifacthub.io/api/v1'
           hub-catalog-type: 'artifacthub'
           error-detection-max-number-of-lines: '50'
           error-detection-simple-regexp: >-

docs/content/docs/installation/overview.md

@@ -26,3 +26,4 @@ After installing Pipelines-as-Code, configure your Git provider to send webhook
 * [GitLab]({{< relref "/docs/providers/gitlab" >}})
 * [Bitbucket Data Center]({{< relref "/docs/providers/bitbucket-datacenter" >}})
 * [Bitbucket Cloud]({{< relref "/docs/providers/bitbucket-cloud" >}})
+* [Forgejo]({{< relref "/docs/providers/forgejo" >}})

docs/content/docs/installation/requirements.md

@@ -55,21 +55,25 @@ You need the following tools to interact with your cluster and manage Pipelines-
 
 ### Required Tools
 
-1
+1. `kubectl`
 
-kubectl
+The Kubernetes command-line tool for cluster access.
 
-The Kubernetes command-line tool for cluster access.**Installation**: [kubectl installation guide](https://kubernetes.io/docs/tasks/tools/)**Verify**:
+**Installation**: [kubectl installation guide](https://kubernetes.io/docs/tasks/tools/)
+
+**Verify**:
 
 ```bash
 kubectl version --client
 ```
 
-2
+1. `oc` (OpenShift only)
 
-oc (OpenShift only)
+The OpenShift command-line tool.
 
-The OpenShift command-line tool.**Installation**: [OpenShift CLI tools](https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html)**Verify**:
+**Installation**: [OpenShift CLI tools](https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html)
+
+**Verify**:
 
 ```bash
 oc version
@@ -79,11 +83,13 @@ oc version
 
 These tools enhance the Pipelines-as-Code experience:
 
-1
+1. `tkn`
+
+The Tekton CLI for managing Tekton resources.
 
-tkn
+**Installation**: [Tekton CLI installation](https://tekton.dev/docs/cli/)
 
-The Tekton CLI for managing Tekton resources.**Installation**: [Tekton CLI installation](https://tekton.dev/docs/cli/)**Install via Homebrew**:
+**Install via Homebrew**:
 
 ```bash
 brew install tektoncd-cli
@@ -95,14 +101,14 @@ brew install tektoncd-cli
 tkn version
 ```
 
-2
+1. `tkn-pac`
 
-tkn-pac
+The Pipelines-as-Code CLI plugin for `tkn`.
 
-The Pipelines-as-Code CLI plugin for tkn.**Install via Homebrew**:
+**Install via Homebrew**:
 
 ```bash
-brew install openshift-pipelines/pipelines-as-code/tkn-pac
+brew install --cask openshift-pipelines/pipelines-as-code/tektoncd-pac
 ```
 
 **Install via Direct Download** (Linux):