Merge remote-tracking branch 'origin/develop'

Author: tig

.github/workflows/README.md

@@ -11,15 +11,14 @@
 
 Version is controlled by `<Version>` in `src/Clet/Clet.csproj`. The release workflow auto-increments a build number on each run.
 
-| Phase | csproj `<Version>` | main produces | develop produces |
-|-------|--------------------|---------------|------------------|
-| Alpha | `1.0.0-alpha` | `v1.0.0-alpha.1`, `.2`, `.3` ... | `v1.0.0-develop.1`, `.2`, `.3` ... |
-| Beta | `1.0.0-beta` | `v1.0.0-beta.1`, `.2`, ... | `v1.0.0-develop.N` ... |
-| Stable | `1.0.0` | `v1.0.0`, `v1.0.1`, `v1.0.2` ... | `v1.0.1-develop.1`, ... |
+| Phase | csproj `<Version>` | main produces |
+|-------|--------------------|---------------|
+| RC | `1.0.0-rc` | `v1.0.0-rc.1`, `.2`, `.3` ... |
+| Stable | `1.0.0` | `v1.0.0`, `v1.0.1`, `v1.0.2` ... |
 
 To move between phases, change `<Version>` in the csproj and merge to main.
 
-Build numbers auto-increment by finding the latest matching git tag (`v1.0.0-alpha.*`, `v1.0.0-develop.*`, etc.).
+Build numbers auto-increment by finding the latest matching git tag (`v1.0.0-rc.*`, etc.).
 
 ## Workflows
 
@@ -37,9 +36,11 @@ Runs on every push and every PR targeting `develop` or `main`.
 | Trigger | When | Channel |
 |---------|------|---------|
 | Push to `main` (changes in `src/` or `tests/`) | Merge develop → main | main |
-| Push to `develop` (changes in `src/` or `tests/`) | PR merge to develop | develop |
-| `repository_dispatch` from Terminal.Gui | TG release or develop publish | develop |
-| `workflow_dispatch` (manual) | Rollback patches, dry-runs | depends on branch |
+| `repository_dispatch` from Terminal.Gui | TG main-branch publish (`tg-main-published`) | main |
+| `repository_dispatch` from Terminal.Gui.Editor | Editor main-branch publish (`editor-main-published`) | main |
+| `workflow_dispatch` (manual) | Rollback patches, dry-runs | main |
+
+> **Branch guard:** Manual dispatch from a non-`main` branch is rejected unless `version_override` is provided. This prevents accidental prereleases from feature branches.
 
 **Pipeline:**
 
@@ -52,21 +53,24 @@ resolve-version → build (3 RIDs) → tag → publish-nuget
 
 **Build matrix:** `osx-arm64`, `linux-x64`, `win-x64`. Each RID builds AOT, runs unit + integration + smoke tests, uploads artifacts.
 
-**Tagging:** Every successful build is tagged (`v1.0.0-alpha.3`, `v1.0.0-develop.5`, etc.) so future runs can find the latest build number.
+**Tagging:** Every successful build is tagged (`v1.0.0-rc.3`, `v1.0.0`, etc.) so future runs can find the latest build number.
 
-**NuGet:** Both channels publish to package id `clet` (see [D-024](../../specs/decisions.md)). Prerelease versions (`-alpha`, `-develop`) are hidden from default `dotnet tool install -g clet`; consumers opt in with `--prerelease`.
+**NuGet:** Main publishes to package id `clet` (see [D-024](../../specs/decisions.md)). Prerelease versions (`-rc`) are hidden from default `dotnet tool install -g clet`; consumers opt in with `--prerelease`.
 
 **Homebrew / WinGet:** Only on stable main releases (version has no `-` suffix). Both are placeholders until `gui-cs/homebrew-tap` exists and WinGet tooling is wired (D-012).
 
-## Terminal.Gui version
+## Terminal.Gui versions
 
-The TG dependency version is set in the csproj as `<TerminalGuiVersion>`. The release workflow can override it via:
+The TG dependency versions are set in `Directory.Build.props` as `<TerminalGuiVersion>` and `<TerminalGuiEditorVersion>`. The release workflow can override them via:
 
 - `repository_dispatch` payload: `client_payload.tg_version`
+- `repository_dispatch` payload: `client_payload.tge_version`
 - `workflow_dispatch` input: `tg_version`
+- `workflow_dispatch` input: `tge_version`
 - MSBuild property: `-p:TerminalGuiVersion=2.0.3`
+- MSBuild property: `-p:TerminalGuiEditorVersion=2.2.5`
 
-See `specs/decisions.md` D-020 and D-023.
+Release builds reject Terminal.Gui or Terminal.Gui.Editor versions older than the latest stable NuGet release.
 
 ## Secrets and variables
 
@@ -83,7 +87,7 @@ See `docs/runbooks/release-rollback.md`.
 
 ## Related decisions
 
-- **D-023** — Two-branch versioning (main + develop)
+- **D-023** — Two-branch versioning (historical context; release publishing is now main-only)
 - **D-022** — Independent versioning from TG (superseded by D-023, principle retained)
 - **D-020** — TG dispatch types and MSBuild version variable
 - **D-012** — Code signing deferred post-1.0

.github/workflows/release.yml

@@ -2,10 +2,10 @@ name: Release
 
 # Versioning scheme:
 #
-#   main branch  → v1.0.0-alpha.1, v1.0.0-alpha.2, ...
+#   main branch  → v1.0.0-rc.1, v1.0.0-rc.2, ...
 #                   (base from csproj <Version>, build number auto-increments)
 #
-#   When alpha phase ends, change csproj <Version> to 1.0.0 (no suffix).
+#   When rc phase ends, change csproj <Version> to 1.0.0 (no suffix).
 #   Then main produces: v1.0.0, v1.0.1, ... (patch auto-increment).
 #
 # Triggers:
@@ -15,10 +15,10 @@ name: Release
 #   4. Manual workflow_dispatch
 on:
   push:
-    branches: [main, develop]
+    branches: [main]
     paths: ['src/**', 'tests/**']
   repository_dispatch:
-    types: [tg-main-published, editor-main-published, editor-develop-published]
+    types: [tg-main-published, editor-main-published]
   workflow_dispatch:
     inputs:
       tg_version:
@@ -48,6 +48,12 @@ jobs:
       tge_version: ${{ steps.version.outputs.tge_version }}
       channel: ${{ steps.version.outputs.channel }}
     steps:
+      - name: Guard non-main dispatch
+        if: github.event_name == 'workflow_dispatch' && github.ref_name != 'main' && github.event.inputs.version_override == ''
+        run: |
+          echo "::error::workflow_dispatch from non-main branch '${{ github.ref_name }}' requires version_override."
+          exit 2
+
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
@@ -60,7 +66,6 @@ jobs:
           TG_VERSION_INPUT: ${{ github.event.client_payload.tg_version || github.event.inputs.tg_version }}
           TGE_VERSION_INPUT: ${{ github.event.client_payload.tge_version || github.event.inputs.tge_version }}
           VERSION_OVERRIDE: ${{ github.event.inputs.version_override }}
-          EVENT_NAME: ${{ github.event_name }}
         run: |
           # --- Validate user-supplied version inputs (prevent script injection) ---
           # Empty TG_VERSION_INPUT is allowed; the script falls back to the csproj pin below.
@@ -78,20 +83,14 @@ jobs:
             exit 2
           fi
 
-          # --- Determine TG version ---
-          TG_VERSION="$TG_VERSION_INPUT"
-
           # --- Channel detection ---
-          if [ "${{ github.ref }}" = "refs/heads/develop" ] || [ "${{ github.event.action }}" = "editor-develop-published" ]; then
-            CHANNEL="develop"
-          else
-            CHANNEL="main"
-          fi
+          CHANNEL="main"
           echo "channel=$CHANNEL" >> "$GITHUB_OUTPUT"
 
           # --- Resolve TG version ---
           # Dispatch/manual: use the explicitly provided version.
           # Otherwise: use the Directory.Build.props pin (known-good).
+          TG_VERSION="$TG_VERSION_INPUT"
           if [ -z "$TG_VERSION" ]; then
             TG_VERSION=$(sed -n 's/.*<TerminalGuiVersion[^>]*>\([^<]*\)<.*/\1/p' Directory.Build.props | head -1)
           fi
@@ -118,7 +117,7 @@ jobs:
             exit 0
           fi
 
-          # Read base version from csproj (e.g. "1.0.0-alpha" or "1.0.0")
+          # Read base version from csproj (e.g. "1.0.0-rc" or "1.0.0")
           CSPROJ_VERSION=$(sed -n 's/.*<Version>\([^<]*\)<.*/\1/p' src/Clet/Clet.csproj | head -1)
           # Split into base (1.0.0) and prerelease phase (alpha, beta, rc, or empty)
           BASE_VERSION="${CSPROJ_VERSION%%-*}"
@@ -133,49 +132,25 @@ jobs:
           PATCH=$(echo "$BASE_VERSION" | cut -d. -f3)
 
           if [ -n "$PHASE" ]; then
-            if [ "$CHANNEL" = "develop" ]; then
-              # Develop channel: version is BASE-develop.N, auto-increment N
-              LATEST_TAG=$(git tag --list "v${BASE_VERSION}-develop.*" --sort=-v:refname | head -1)
-              if [ -n "$LATEST_TAG" ]; then
-                BUILD_NUM=$(echo "$LATEST_TAG" | sed 's/.*develop\.//' | sed 's/-.*//')
-                BUILD_NUM=$((BUILD_NUM + 1))
-              else
-                BUILD_NUM=1
-              fi
-              CLET_VERSION="${BASE_VERSION}-develop.${BUILD_NUM}"
+            # Main channel rc phase: version is BASE-PHASE.N, auto-increment N
+            # Find latest tag matching v1.0.0-rc.*
+            LATEST_TAG=$(git tag --list "v${BASE_VERSION}-${PHASE}.*" --sort=-v:refname | head -1)
+            if [ -n "$LATEST_TAG" ]; then
+              # Extract the build number (last dot-separated segment)
+              BUILD_NUM=$(echo "$LATEST_TAG" | sed "s/.*${PHASE}\.//" | sed 's/-.*//')
+              BUILD_NUM=$((BUILD_NUM + 1))
             else
-              # Main channel alpha/beta/rc phase: version is BASE-PHASE.N, auto-increment N
-              # Find latest tag matching v1.0.0-alpha.*
-              LATEST_TAG=$(git tag --list "v${BASE_VERSION}-${PHASE}.*" --sort=-v:refname | head -1)
-              if [ -n "$LATEST_TAG" ]; then
-                # Extract the build number (last dot-separated segment)
-                BUILD_NUM=$(echo "$LATEST_TAG" | sed "s/.*${PHASE}\.//" | sed 's/-.*//')
-                BUILD_NUM=$((BUILD_NUM + 1))
-              else
-                BUILD_NUM=1
-              fi
-              CLET_VERSION="${BASE_VERSION}-${PHASE}.${BUILD_NUM}"
+              BUILD_NUM=1
             fi
+            CLET_VERSION="${BASE_VERSION}-${PHASE}.${BUILD_NUM}"
           else
-            if [ "$CHANNEL" = "develop" ]; then
-              # Develop channel with stable base: version is MAJOR.MINOR.PATCH-develop.N
-              LATEST_TAG=$(git tag --list "v${BASE_VERSION}-develop.*" --sort=-v:refname | head -1)
-              if [ -n "$LATEST_TAG" ]; then
-                BUILD_NUM=$(echo "$LATEST_TAG" | sed 's/.*develop\.//' | sed 's/-.*//')
-                BUILD_NUM=$((BUILD_NUM + 1))
-              else
-                BUILD_NUM=1
-              fi
-              CLET_VERSION="${BASE_VERSION}-develop.${BUILD_NUM}"
-            else
-              # Stable phase: version is MAJOR.MINOR.PATCH, auto-increment patch
-              LATEST_TAG=$(git tag --list "v${MAJOR}.${MINOR}.*" --sort=-v:refname | grep -v '-' | head -1)
-              if [ -n "$LATEST_TAG" ]; then
-                LATEST_PATCH=$(echo "$LATEST_TAG" | sed 's/^v//' | cut -d. -f3)
-                PATCH=$((LATEST_PATCH + 1))
-              fi
-              CLET_VERSION="${MAJOR}.${MINOR}.${PATCH}"
+            # Stable phase: version is MAJOR.MINOR.PATCH, auto-increment patch
+            LATEST_TAG=$(git tag --list "v${MAJOR}.${MINOR}.*" --sort=-v:refname | grep -v '-' | head -1)
+            if [ -n "$LATEST_TAG" ]; then
+              LATEST_PATCH=$(echo "$LATEST_TAG" | sed 's/^v//' | cut -d. -f3)
+              PATCH=$((LATEST_PATCH + 1))
             fi
+            CLET_VERSION="${MAJOR}.${MINOR}.${PATCH}"
           fi
 
           echo "clet_version=$CLET_VERSION" >> "$GITHUB_OUTPUT"
@@ -251,7 +226,7 @@ jobs:
           retention-days: 30
 
   # Tag every successful build so future runs can find the latest build number.
-  # Tags: v1.0.0-alpha.3, v1.0.0 (stable)
+  # Tags: v1.0.0-rc.3, v1.0.0 (stable)
   tag:
     needs: [resolve-version, build]
     runs-on: ubuntu-latest
@@ -427,14 +402,34 @@ jobs:
       TG_VERSION: ${{ needs.resolve-version.outputs.tg_version }}
       CHANNEL: ${{ needs.resolve-version.outputs.channel }}
     steps:
-      - name: Create failure issue
+      - name: Create or update failure issue
         uses: actions/github-script@v7
         with:
           script: |
-            await github.rest.issues.create({
+            const issueTitle = `Release clet v${process.env.CLET_VERSION} failed (${process.env.CHANNEL})`;
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            const issueBody = `The ${process.env.CHANNEL} release workflow for clet \`${process.env.CLET_VERSION}\` (TG \`${process.env.TG_VERSION}\`) failed.\n\nSee [workflow run](${runUrl}) for details.\n\nRefer to \`docs/runbooks/release-rollback.md\` for rollback procedures.`;
+            const labels = [`incident:${process.env.CHANNEL}`];
+            const issues = await github.paginate(github.rest.issues.listForRepo, {
               owner: context.repo.owner,
               repo: context.repo.repo,
-              title: `Release clet v${process.env.CLET_VERSION} failed (${process.env.CHANNEL})`,
-              body: `The ${process.env.CHANNEL} release workflow for clet \`${process.env.CLET_VERSION}\` (TG \`${process.env.TG_VERSION}\`) failed.\n\nSee [workflow run](${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}) for details.\n\nRefer to \`docs/runbooks/release-rollback.md\` for rollback procedures.`,
-              labels: [`incident:${process.env.CHANNEL}`]
+              state: 'open',
+              labels: labels.join(',')
             });
+            const existingIssue = issues.find(issue => !issue.pull_request && issue.title === issueTitle);
+            if (existingIssue) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existingIssue.number,
+                body: `Release workflow failed again for \`${process.env.CLET_VERSION}\`.\n\nSee [workflow run](${runUrl}) for details.`
+              });
+            } else {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title: issueTitle,
+                body: issueBody,
+                labels
+              });
+            }

.gitignore

@@ -58,6 +58,7 @@ nunit-*.xml
 
 # Visual Studio cache / IDE state
 .vs/
+*.DotSettings.user
 
 # Local AOT publish output (`make publish`) and release archives
 publish/

Clet.sln.DotSettings

@@ -0,0 +1,2 @@
+<wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=JSONC/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>

Directory.Build.props

@@ -13,9 +13,9 @@
     <Copyright>Copyright (c) gui-cs and contributors</Copyright>
 
     <!-- Pinned Terminal.Gui version. CI / release workflows can override via -p:TerminalGuiVersion=<x>. -->
-    <TerminalGuiVersion Condition="'$(TerminalGuiVersion)' == ''">2.2.1</TerminalGuiVersion>
+    <TerminalGuiVersion Condition="'$(TerminalGuiVersion)' == ''">2.2.2</TerminalGuiVersion>
     <!-- Pinned Terminal.Gui.Editor version. CI / release workflows can override via -p:TerminalGuiEditorVersion=<x>. -->
-    <TerminalGuiEditorVersion Condition="'$(TerminalGuiEditorVersion)' == ''">2.2.1</TerminalGuiEditorVersion>
+    <TerminalGuiEditorVersion Condition="'$(TerminalGuiEditorVersion)' == ''">2.2.5</TerminalGuiEditorVersion>
   </PropertyGroup>
 
 </Project>

Directory.Build.targets

@@ -0,0 +1,11 @@
+<Project>
+  <PropertyGroup>
+    <TerminalGuiFreshnessCheckScript>$([System.IO.Path]::Combine('$(MSBuildThisFileDirectory)', 'scripts', 'check-tg-pins-fresh.py'))</TerminalGuiFreshnessCheckScript>
+  </PropertyGroup>
+
+  <Target Name="CheckTerminalGuiPinsFresh"
+          BeforeTargets="Restore"
+          Condition="'$(GITHUB_ACTIONS)' == 'true' and '$(MSBuildProjectName)' == 'Clet'">
+    <Exec Command="python &quot;$(TerminalGuiFreshnessCheckScript)&quot; --props &quot;$(MSBuildThisFileDirectory)Directory.Build.props&quot; --terminal-gui-version &quot;$(TerminalGuiVersion)&quot; --terminal-gui-editor-version &quot;$(TerminalGuiEditorVersion)&quot;" />
+  </Target>
+</Project>

README.md

@@ -14,7 +14,7 @@ Works for humans and AI agents alike.
 | `text`, `multiline-text`, `mt` | Prompts for multi-line text input using an editor and returns the entered string. | |
 | `int` | Prompts for an integer value using a numeric spinner. | `--step` |
 | `decimal` | Prompts for a decimal value using a numeric spinner. | `--step` |
-| `confirm` | Prompts for a yes/no confirmation and returns a boolean. | `--prompt` |
+| `confirm` | Prompts for a yes/no confirmation and returns a boolean. | |
 | `date` | Prompts for a date and returns an ISO-8601 date string (YYYY-MM-DD). | |
 | `time` | Prompts for a time and returns an ISO-8601 time string (HH:MM:SS). | |
 | `duration` | Prompts for a duration and returns an ISO-8601 duration string (e.g. PT1H30M). | |
@@ -126,15 +126,26 @@ Exit codes:
 - `2` usage error
 - `130` cancelled (SIGINT convention).
 
-### Demo
+### Demos
 
-![demo](./docs/images/demo.gif)
+**`clet help`**
 
-## Alpha feedback
+![clet help](./docs/images/clet-help.gif)
 
-clet is in **friends-and-family alpha** ([milestone tracker](https://github.com/gui-cs/clet/issues/33)). If something doesn't work, looks wrong, or is just confusing, **[file an issue](https://github.com/gui-cs/clet/issues/new)**. Include:
+**`clet pick-file`**
 
-- `clet --version` output (e.g. `1.0.0-alpha (Terminal.Gui 2.0.2-develop.37)`).
+![clet pick-file](./docs/images/clet-pick-file.gif)
+
+**`clet color`**
+
+![clet color](./docs/images/clet-color.gif)
+
+
+## RC feedback
+
+clet is in **release candidate** status ([milestone tracker](https://github.com/gui-cs/clet/issues/33)). If something doesn't work, looks wrong, or is just confusing, **[file an issue](https://github.com/gui-cs/clet/issues/new)**. Include:
+
+- `clet --version` output (e.g. `1.0.0-rc.3 (Terminal.Gui 2.0.2-develop.37)`).
 - Your terminal + OS (e.g. "Windows Terminal on Windows 11", "iTerm2 on macOS 15").
 - What you ran, what you expected, what happened.
 
@@ -213,6 +224,10 @@ Or, you can pick from a built-in Terminal.Gui Theme. This example picks the `And
 
 <img width="576" height="131" alt="image" src="https://github.com/user-attachments/assets/df36bca2-25b5-4904-af51-5a9de9e9be35" />
 
+Here's `clet color` with the Anders theme applied:
+
+![clet color with Anders theme](./docs/images/clet-color.gif)
+
 All clets render with the `Base` color scheme, so customizing `Base` controls every clet's appearance. See the [Terminal.Gui Configuration docs](https://gui-cs.github.io/Terminal.Gui/docs/configuration.html) for the full schema.
 
 ### Q: Key bindings?
@@ -237,11 +252,11 @@ This changes the quit/dismiss key for all clets. `clet md` shows the active quit
 
 ### Q: What's the `--prerelease` channel?
 
-Releases from `main` publish prerelease packages to NuGet (versioned `1.x.y-alpha.N` during alpha, then `-beta.N`, `-rc.N`). Stable users see no churn — `dotnet tool install -g clet` still resolves to the latest non-prerelease, and `brew`/`winget` only ship stable main releases. If you want the bleeding edge, pass `--prerelease`.
+Releases from `main` publish prerelease packages to NuGet (versioned `1.x.y-rc.N` during the RC phase). Stable users see no churn — `dotnet tool install -g clet` still resolves to the latest non-prerelease, and `brew`/`winget` only ship stable main releases. If you want the bleeding edge, pass `--prerelease`.
 
-### Q: How do I report a bug or give feedback during alpha?
+### Q: How do I report a bug or give feedback?
 
-[File an issue](https://github.com/gui-cs/clet/issues/new). That's the only feedback channel — no Discussions, no forum. See the [Alpha feedback](#alpha-feedback) section above for what to include.
+[File an issue](https://github.com/gui-cs/clet/issues/new). That's the only feedback channel — no Discussions, no forum. See the [RC feedback](#rc-feedback) section above for what to include.
 
 ## Native binaries install