bugfix-329-it-ends-up-stuck-in-an-unknown-version-loop-if-no-version-is-detected-in-the-repository: Clarify that it creates a default tag v1.0.0 if no version tags exist, preventing "Unknown Version" loops. Update examples and CLI command descriptions for consistency.

Author: efraespada

docs/features.mdx

@@ -79,7 +79,7 @@ When you set `single-action` (and, when required, `single-action-issue`, `single
 | **`detect_potential_problems_action`** | `single-action-issue` | Bugbot: OpenCode analyzes the branch vs base; reports findings as comments on the issue and as PR review comments; updates issue comments and marks PR review threads as resolved when findings are fixed. |
 | **`recommend_steps_action`** | `single-action-issue` | Uses OpenCode Plan to recommend implementation steps from the issue description; posts a comment on the issue. |
 | **`think_action`** | — | Uses OpenCode Plan for deep code analysis and change proposals (reasoning over the codebase). No issue required. |
-| **`initial_setup`** | — | Performs initial setup steps (e.g. for repo or project). No issue required. |
+| **`initial_setup`** | — | Performs initial setup: creates labels, issue types, verifies access. If the repo has no version tags, creates default tag `v1.0.0` so release/hotfix issues get a base version. No issue required. |
 | **`create_release`** | `single-action-version`, `single-action-title`, `single-action-changelog` | Creates a GitHub release with the given version, title, and changelog. |
 | **`create_tag`** | `single-action-version` | Creates a Git tag with prefix `v` (e.g. `v1.2.0`) for the given version from the release branch. |
 | **`publish_github_action`** | `single-action-version` | Publishes or updates the GitHub Action: creates/updates the major version tag (e.g. `v2` from `v2.0.4`). Requires `create_tag` to have been run first. |

docs/single-actions/available-actions.mdx

@@ -23,7 +23,7 @@ These actions need **`single-action-issue`** set to the issue number. The workfl
 | Action | Required inputs | Description | When to use |
 |--------|-----------------|-------------|-------------|
 | **`think_action`** | — | **Deep code analysis** and change proposals (OpenCode Plan). You can pass a question (e.g. from CLI with `-q "..."`). No issue required. | One-off reasoning over the codebase; use from CLI or a workflow that provides context. |
-| **`initial_setup`** | — | Performs **initial setup** steps: creates labels, issue types (if supported), verifies access. No issue required. | First-time repo setup; run once or when you add new labels/types. |
+| **`initial_setup`** | — | Performs **initial setup**: creates labels, issue types (if supported), verifies access. If the repo has no version tags, creates default tag **`v1.0.0`** so release/hotfix issues get a base version. No issue required. | First-time repo setup; run once or when you add new labels/types. Run on new repos before creating release/hotfix issues to avoid "Unknown Version" loops. |
 | **`create_release`** | `single-action-version`, `single-action-title`, `single-action-changelog` | Creates a **GitHub release** with the given version, title, and changelog (markdown body). | From a workflow after tests pass; use version and changelog from your build or inputs. |
 | **`create_tag`** | `single-action-version` | Creates a **Git tag** with prefix `v` (e.g. `v1.2.3`) for the given version from the release branch. | When you only need a tag (e.g. for versioning) without a full release. The tag is created from the `releaseBranch` stored in issue configuration. |
 | **`publish_github_action`** | `single-action-version` | **Publishes or updates** the GitHub Action: creates/updates the major version tag (e.g. `v2` from `v2.0.4`) and the corresponding GitHub Release. Requires that `create_tag` has been run first to create the source tag `v{version}`. | In a CI job that builds and publishes the action, after `create_tag` and `create_release` have run. |

docs/single-actions/examples.mdx

@@ -137,7 +137,7 @@ Mark issue `100` as deployed (e.g. from your release workflow):
 
 ## Workflow: initial setup
 
-Run initial setup (labels, issue types, verify access):
+Run initial setup (labels, issue types, verify access). If the repo has no version tags, Copilot creates default tag **`v1.0.0`** so release/hotfix issues get a base version and do not get stuck in an "Unknown Version" loop:
 
 ```yaml
 - uses: vypdev/copilot@v2
@@ -146,7 +146,7 @@ Run initial setup (labels, issue types, verify access):
     single-action: initial_setup
 ```
 
-Often run once per repo or after adding new label/type config.
+Often run once per repo or after adding new label/type config. On new repos, run this before creating release/hotfix issues.
 
 ---
 

docs/single-actions/workflow-and-cli.mdx

@@ -44,7 +44,7 @@ giik <command> [options]
 
 | CLI command | Single action equivalent | Required option | Description |
 |-------------|---------------------------|-----------------|-------------|
-| `setup` | `initial_setup` | — | Labels, issue types, verify access |
+| `setup` | `initial_setup` | — | Labels, issue types, verify access; creates default tag `v1.0.0` if repo has no tags |
 | `check-progress` | `check_progress_action` | `-i <issue>` | Progress check on demand |
 | `detect-potential-problems` | `detect_potential_problems_action` | `-i <issue>` [-b \<branch\>] | Bugbot: detect potential problems, report on issue and PR (OpenCode) |
 | `recommend-steps` | `recommend_steps_action` | `-i <issue>` | Recommend steps from issue (OpenCode) |