openclacky 1.5.3 → 1.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04d2d81c4aaa380d4600066802c78e1137bdad1cb16c3e5e47e32e69ede15da6
-  data.tar.gz: 9a332e0305e96bae97799ce707ef492b24735e33ef8da70a390c06a10ac11ab4
+  metadata.gz: 10e414552c9ae0e3bb7a0b547f2e4da0709c83e0a0925f3b708820848e1a4cf3
+  data.tar.gz: 6caa29ccd3048e95912500be99000ae7ca883c9a5ad473ebc1bb2f243aef5cc3
 SHA512:
-  metadata.gz: 435b6c1bd6aac4c2916cf172e5d46dece9a5707d1b18119d4744d29293c1f7b8fb112709718d24b8b9b3a871bfa228294a282525d9b6f7ed14550b89eaaa2793
-  data.tar.gz: 90599042f3d933db9b7681c33d539937585cd85542d635696ea159056aa47dbe34f86971bd1db6541c4dee28ee73c66e8f4648d91d8f3b1897b179ce9a2b00fc
+  metadata.gz: 26f220973c6821a411362df35ca281ef53ae58e6ab36d26651db393b31713340ca9bcf131f69bf4e6aa391eec3f4f21fc7d0d12cb4bbbdc368b6fe8068fa2dfa
+  data.tar.gz: 84faf59b60486d29a9168f847c97d7fd5670dac293f967bd713c08049612adab7f947fa38af3a7e89c4a5acc2cc8c460e9b8ebbf53c189c19a52bf7e89a44388

data/.dockerignore

@@ -0,0 +1,13 @@
+.git
+.github
+.clacky
+vendor
+spec
+docs
+tmp
+coverage
+pkg
+*.gem
+.rspec_status
+AGENTS.md
+CLAUDE.md

data/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
+## [1.5.4] - 2026-08-01
+
+### Added
+- Project management: create, manage, and switch between projects
+- Claude Sonnet 5 and Opus 5 models with pricing
+- Desktop notifications for background task completion
+- Configurable platform source and branding restoration
+- Hidden flag on create_session API (#403)
+- MiniMax preset refreshed with Anthropic endpoints, M3 thinking, and current lineup (#402)
+
+### Improved
+- File upload size limit increased from 32 MB to 300 MB
+- Dir picker UX: breadcrumb overflow scroll, row spacing, and padding
+- Session-sidebar collapse button appearance matches opener button
+
+### Fixed
+- XLSX parser switched to Python/openpyxl with 60s timeout kill for reliable parsing (C-5656)
+- Panel agents map missing general profile on first load
+- Stale result on first load due to container extension script execution order
+- Page now reloads after deleting local extension in ext-studio
+- Accent color used for extensions filter tab active underline
+- Missing pricing for Claude Sonnet 5 and Opus 5
+- Docker image builds from source and publishes to GHCR on version tags
+- Session list page size reduced from 20 to 15 for better performance
+- MiniMax-M2.5 restored, default base_url reverted to mainland
+
 ## [1.5.3] - 2026-07-28
 
 ### Added

data/Dockerfile

@@ -1,14 +1,34 @@
 FROM ruby:3.4.4-slim AS builder
 
+ARG VERSION
+
 RUN apt-get update && apt-get install -y \
     build-essential \
     curl \
+    git \
     && rm -rf /var/lib/apt/lists/*
 
-RUN gem install openclacky --no-document
+# Build from repository source so the image matches this checkout (not a published gem).
+# gemspec uses `git ls-files`; seed a temporary git index because .git is dockerignored.
+COPY . /src
+WORKDIR /src
+RUN git init \
+    && git config user.email "docker@local" \
+    && git config user.name "docker" \
+    && git add -A \
+    && git commit -m "docker build" \
+    && gem build openclacky.gemspec \
+    && gem install ./openclacky-*.gem --no-document \
+    && ruby -e 'require "clacky"; abort "bad version" unless Clacky::VERSION'
 
 FROM ruby:3.4.4-slim
 
+ARG VERSION
+LABEL org.opencontainers.image.title="openclacky" \
+      org.opencontainers.image.description="OpenClacky AI agent CLI and Web UI" \
+      org.opencontainers.image.source="https://github.com/clacky-ai/openclacky" \
+      org.opencontainers.image.version="${VERSION}"
+
 RUN apt-get update && apt-get install -y \
     git \
     curl \

data/README.md

@@ -110,18 +110,24 @@ see more: https://www.openclacky.com/docs/installation
 
 ### Docker
 
-Build:
+#### Pre-built image (GHCR)
+
+Images are published to GitHub Container Registry on version tags (`v*`).
 
 ```bash
-git clone https://github.com/clacky-ai/openclacky.git
-cd openclacky
-docker build -t openclacky .
+# Replace <owner> with the repo owner (e.g. clacky-ai or your fork)
+docker pull ghcr.io/<owner>/openclacky:latest
+# or pin a release:
+# docker pull ghcr.io/<owner>/openclacky:1.5.3
 ```
 
 **Linux:**
 
 ```bash
-docker run -d --network=host -e CLACKY_ACCESS_KEY="" openclacky
+docker run -d --name openclacky --network=host \
+  -e CLACKY_ACCESS_KEY="" \
+  -v openclacky-data:/root/.clacky \
+  ghcr.io/<owner>/openclacky:latest
 ```
 
 `--network=host` is required so the agent inside the container can reach Chrome's remote debugging port running on the host.
@@ -129,18 +135,31 @@ docker run -d --network=host -e CLACKY_ACCESS_KEY="" openclacky
 **macOS / Windows:**
 
 ```bash
-docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
+docker run -d --name openclacky -p 7070:7070 \
+  -e CLACKY_ACCESS_KEY="" \
+  -v openclacky-data:/root/.clacky \
+  ghcr.io/<owner>/openclacky:latest
 ```
 
 > **Note:** On macOS/Windows, `--network=host` is not supported — browser automation may be limited.
 
 Open **http://localhost:7070** after starting.
 
+#### Build from source
+
+```bash
+git clone https://github.com/clacky-ai/openclacky.git
+cd openclacky
+# optional: set the OCI image version label
+docker build --build-arg VERSION=1.5.3 -t openclacky .
+docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
+```
+
 Environment variables:
 
 | Variable | Description |
 |---|---|
-| `CLACKY_ACCESS_KEY` | Protect the Web UI with an access key (empty = public mode) |
+| `CLACKY_ACCESS_KEY` | Protect the Web UI with an access key (empty = public mode; env must be present when binding `0.0.0.0`) |
 
 
 ## Quick Start

data/README_CN.md

@@ -106,18 +106,24 @@ gem install openclacky
 
 ### Docker
 
-构建：
+#### 预构建镜像（GHCR）
+
+镜像在版本 tag（`v*`）时自动发布到 GitHub Container Registry。
 
 ```bash
-git clone https://github.com/clacky-ai/openclacky.git
-cd openclacky
-docker build -t openclacky .
+# 将 <owner> 替换为仓库所有者（如 clacky-ai 或你的 fork）
+docker pull ghcr.io/<owner>/openclacky:latest
+# 或固定某个版本：
+# docker pull ghcr.io/<owner>/openclacky:1.5.3
 ```
 
 **Linux:**
 
 ```bash
-docker run -d --network=host -e CLACKY_ACCESS_KEY="" openclacky
+docker run -d --name openclacky --network=host \
+  -e CLACKY_ACCESS_KEY="" \
+  -v openclacky-data:/root/.clacky \
+  ghcr.io/<owner>/openclacky:latest
 ```
 
 `--network=host` 使容器与宿主机共享网络栈，Agent 可直接访问宿主机上运行的 Chrome 远程调试端口。
@@ -125,18 +131,31 @@ docker run -d --network=host -e CLACKY_ACCESS_KEY="" openclacky
 **macOS / Windows:**
 
 ```bash
-docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
+docker run -d --name openclacky -p 7070:7070 \
+  -e CLACKY_ACCESS_KEY="" \
+  -v openclacky-data:/root/.clacky \
+  ghcr.io/<owner>/openclacky:latest
 ```
 
 > **注意：** macOS/Windows 不支持 `--network=host`，浏览器自动化功能可能受限。
 
 启动后访问 **http://localhost:7070**。
 
+#### 从源码构建
+
+```bash
+git clone https://github.com/clacky-ai/openclacky.git
+cd openclacky
+# 可选：设置 OCI 镜像版本标签
+docker build --build-arg VERSION=1.5.3 -t openclacky .
+docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
+```
+
 环境变量：
 
 | 变量 | 说明 |
 |---|---|
-| `CLACKY_ACCESS_KEY` | 设置访问密钥保护 Web UI（留空 = 公开模式） |
+| `CLACKY_ACCESS_KEY` | 设置访问密钥保护 Web UI（留空 = 公开模式；绑定 `0.0.0.0` 时必须设置该环境变量） |
 
 ## 快速开始
 

data/README_JA.md

@@ -110,18 +110,24 @@ gem install openclacky
 
 ### Docker
 
-ビルド:
+#### ビルド済みイメージ（GHCR）
+
+バージョンタグ（`v*`）が付くと GitHub Container Registry にイメージが自動公開されます。
 
 ```bash
-git clone https://github.com/clacky-ai/openclacky.git
-cd openclacky
-docker build -t openclacky .
+# <owner> をリポジトリオーナーに置き換えてください（例: clacky-ai またはあなたのフォーク）
+docker pull ghcr.io/<owner>/openclacky:latest
+# またはバージョンを固定する場合:
+# docker pull ghcr.io/<owner>/openclacky:1.5.3
 ```
 
 **Linux:**
 
 ```bash
-docker run -d --network=host -e CLACKY_ACCESS_KEY="" openclacky
+docker run -d --name openclacky --network=host \
+  -e CLACKY_ACCESS_KEY="" \
+  -v openclacky-data:/root/.clacky \
+  ghcr.io/<owner>/openclacky:latest
 ```
 
 `--network=host` は、コンテナ内のエージェントがホスト上で動作する Chrome のリモートデバッグポートに到達するために必要です。
@@ -129,18 +135,31 @@ docker run -d --network=host -e CLACKY_ACCESS_KEY="" openclacky
 **macOS / Windows:**
 
 ```bash
-docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
+docker run -d --name openclacky -p 7070:7070 \
+  -e CLACKY_ACCESS_KEY="" \
+  -v openclacky-data:/root/.clacky \
+  ghcr.io/<owner>/openclacky:latest
 ```
 
 > **注意:** macOS/Windows では `--network=host` がサポートされていないため、ブラウザの自動化が制限される場合があります。
 
 起動後、**http://localhost:7070** を開いてください。
 
+#### ソースからビルド
+
+```bash
+git clone https://github.com/clacky-ai/openclacky.git
+cd openclacky
+# オプション: OCI イメージバージョンラベルを設定
+docker build --build-arg VERSION=1.5.3 -t openclacky .
+docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
+```
+
 環境変数:
 
 | 変数 | 説明 |
 |---|---|
-| `CLACKY_ACCESS_KEY` | アクセスキーで Web UI を保護します（空の場合はパブリックモード） |
+| `CLACKY_ACCESS_KEY` | アクセスキーで Web UI を保護します（空の場合はパブリックモード；`0.0.0.0` にバインドする場合は必須） |
 
 
 ## クイックスタート

data/lib/clacky/agent/message_compressor.rb

@@ -39,14 +39,10 @@ module Clacky
 
       REQUIRED RESPONSE FORMAT:
       First output a <topics> line listing 3-6 key topic phrases (comma-separated, concise).
-      Then output a <continues_previous> line: "true" if this conversation is a direct
-      continuation of the SAME task/topic as the PREVIOUS chunk shown below, "false" if it
-      has moved on to a different task or topic. If there is no previous chunk, output "false".
       Then output the full summary wrapped in <summary> tags.
 
       Example format:
       <topics>Rails setup, database config, deploy pipeline, Tailwind CSS</topics>
-      <continues_previous>false</continues_previous>
       <summary>
       ...full summary text...
       </summary>
@@ -58,8 +54,7 @@ module Clacky
       - Errors encountered and fixes applied
       - Current work status and pending tasks
 
-      Begin your response NOW. Remember: PURE TEXT only, starting with <topics> then
-      <continues_previous> then <summary>.
+      Begin your response NOW. Remember: PURE TEXT only, starting with <topics> then <summary>.
     PROMPT
 
     def initialize(client, model: nil)
@@ -77,9 +72,6 @@ module Clacky
     #
     # @param messages [Array<Hash>] Original conversation messages
     # @param recent_messages [Array<Hash>] Recent messages to keep uncompressed (optional)
-    # @param previous_topics [String, nil] Topics of the most recent chunk on disk,
-    #   shown to the LLM so it can decide whether the current conversation is a
-    #   continuation (drives the <continues_previous> output for chunk merging).
     # @return [Hash] Compression instruction message to insert, or nil if nothing to compress
     def build_compression_message(messages, recent_messages: [], previous_topics: nil)
       # Get messages to compress (exclude system message and recent messages)
@@ -88,14 +80,9 @@ module Clacky
       # If nothing to compress, return nil
       return nil if messages_to_compress.empty?
 
-      content = COMPRESSION_PROMPT
-      if previous_topics && !previous_topics.strip.empty?
-        content = "#{COMPRESSION_PROMPT}\n\nPREVIOUS CHUNK TOPICS (for <continues_previous> judgement): #{previous_topics}"
-      end
-
       {
         role: "user",
-        content: content,
+        content: COMPRESSION_PROMPT,
         system_injected: true
       }
     end
@@ -154,15 +141,6 @@ module Clacky
       m ? m[1].strip : nil
     end
 
-    # Parse the <continues_previous> tag. Returns true only when the LLM
-    # explicitly says "true"; missing tag or any other value → false.
-    # This conservative default ensures we never merge unless the model is sure.
-    def parse_continues_previous(content)
-      return false if content.nil? || content.to_s.empty?
-      m = content.to_s.match(/<continues_previous>(.*?)<\/continues_previous>/m)
-      m ? m[1].strip.downcase == "true" : false
-    end
-
     def parse_compressed_result(result, chunk_path: nil, topics: nil, previous_chunks: [])
       # Return the compressed result as a single user message (role: "user").
       #
@@ -192,11 +170,8 @@ module Clacky
       if content.empty?
         []
       else
-        # Strip out the <topics> and <continues_previous> blocks — they're
-        # metadata for chunk handling, not for AI context.
-        content_without_topics = content.gsub(/<topics>.*?<\/topics>\n*/m, "")
-                                        .gsub(/<continues_previous>.*?<\/continues_previous>\n*/m, "")
-                                        .strip
+        # Strip out the <topics> block — it's metadata for chunk handling, not for AI context.
+        content_without_topics = content.gsub(/<topics>.*?<\/topics>\n*/m, "").strip
 
         # Build previous chunks index section — links to older chunk files so the AI
         # can find earlier conversations without keeping all prior compressed_summary

data/lib/clacky/agent/message_compressor_helper.rb

@@ -200,21 +200,19 @@ module Clacky
         recent_messages = get_recent_messages_with_tool_pairs(all_messages, target_recent_count)
         recent_messages = [] if recent_messages.nil?
 
-        # Surface the most recent chunk's topics so the compression LLM can judge
-        # whether this conversation continues the same task (drives chunk merging).
-        previous_topics = nil
-        if @session_id && @created_at
-          latest = session_manager.chunks_for_current(@session_id, @created_at).last
-          previous_topics = latest && latest[:topics]
-        end
-
         # Build compression instruction message (to be inserted into conversation)
         compression_message = @message_compressor.build_compression_message(
-          all_messages, recent_messages: recent_messages, previous_topics: previous_topics
+          all_messages, recent_messages: recent_messages
         )
 
         return nil if compression_message.nil?
 
+        # Active (non-forced) compression means we've accumulated enough
+        # conversation to hit the normal thresholds — always create a new chunk.
+        # Idle / context-overflow compressions (force: true) always merge into
+        # the previous chunk to avoid fragmenting small batches.
+        force_new_chunk = !force
+
         # Return compression context for agent to handle
         {
           compression_message: compression_message,
@@ -222,7 +220,8 @@ module Clacky
           pulled_back_messages: pulled_back_messages,
           original_token_count: total_tokens,
           original_message_count: @history.size,
-          compression_level: @compression_level
+          compression_level: @compression_level,
+          force_new_chunk: force_new_chunk
         }
       end
 
@@ -265,12 +264,11 @@ module Clacky
         topics = @message_compressor.parse_topics(compressed_content)
 
         # Decide whether to MERGE into the previous chunk or create a NEW one.
-        # The LLM judges (via <continues_previous>) whether this conversation is a
-        # direct continuation of the previous chunk's task. Merging avoids tiny
-        # fragmented chunks (e.g. a long task compressed mid-flight into 2-message
-        # chunks) that pollute the topics index and degrade recall.
+        # Active compression (force_new_chunk: true) always creates a new chunk.
+        # Idle / overflow compression always merges into the previous chunk if
+        # one exists, avoiding tiny fragmented chunks that pollute the topics index.
         latest_chunk = existing_chunks.last
-        continues = latest_chunk && @message_compressor.parse_continues_previous(compressed_content)
+        continues = latest_chunk && !compression_context[:force_new_chunk]
 
         if continues
           chunk_path = merge_into_previous_chunk(

data/lib/clacky/agent/session_serializer.rb

@@ -11,6 +11,7 @@ module Clacky
         @session_id = session_data[:session_id]
         @name = session_data[:name] || ""
         @pinned = session_data[:pinned] || false
+        @hidden = session_data[:hidden] || false
         @history = MessageHistory.new(session_data[:messages] || [])
         @todos = session_data[:todos] || []  # Restore todos from session
         @iterations = session_data.dig(:stats, :total_iterations) || 0
@@ -29,6 +30,9 @@ module Clacky
         # Restore channel info for IM platform sessions
         @channel_info = session_data[:channel_info]
 
+        # Restore project association (nil = no project)
+        @project_id = session_data[:project_id]
+
         # Restore cache statistics if available
         @cache_stats = session_data.dig(:stats, :cache_stats) || {
           cache_creation_input_tokens: 0,
@@ -200,6 +204,7 @@ module Clacky
           session_id: @session_id,
           name: @name,
           pinned: @pinned,
+          hidden: @hidden,
           created_at: @created_at,
           updated_at: (updated_at || (preserve_updated_at && @persisted_updated_at) || Time.now.iso8601).then { |v| v.is_a?(String) ? v : v.iso8601 },
           working_dir: @working_dir,
@@ -234,6 +239,7 @@ module Clacky
             sub_model: @config.session_model_overlay_name
           },
           channel_info: @channel_info,
+          project_id:   @project_id,
           stats: stats_data,
           messages: @history.to_a
         }

data/lib/clacky/agent.rb

@@ -49,7 +49,9 @@ module Clacky
                 :latest_latency,  # Hash of latency metrics from the most recent LLM call (see Client#send_messages_with_tools)
                 :reasoning_effort
     attr_accessor :pinned
+    attr_accessor :hidden
     attr_accessor :channel_info
+    attr_accessor :project_id
 
     REASONING_EFFORTS = %w[low medium high xhigh].freeze
 
@@ -82,6 +84,7 @@ module Clacky
       @session_id = session_id
       @name = ""
       @pinned = false
+      @hidden = false
       @history = MessageHistory.new
       @todos = []  # Store todos in memory
       @iterations = 0
@@ -435,8 +438,9 @@ module Clacky
             lines << "Parse failed: #{parse_error}"
             if parser_path
               expected_preview = "#{path}.preview.md"
+              interp = Utils::ParserManager.interpreter_for(File.basename(parser_path))
               lines << "Action required: fix the parser at #{parser_path}, then run:"
-              lines << "  ruby #{parser_path} #{path} > #{expected_preview}"
+              lines << "  #{interp} #{parser_path} #{path} > #{expected_preview}"
               lines << "Once done, read #{expected_preview} to continue helping the user."
             end
           end
@@ -1005,6 +1009,14 @@ module Clacky
           # Inject working_dir so tools don't rely on Dir.chdir global state
           args[:working_dir] = @working_dir if @working_dir
 
+          # Inject CLACKY_SESSION_ID into every terminal invocation so skills/system
+          # prompts can reliably curl our own HTTP API (e.g. POST /api/ui/show_ext_refresh)
+          # without the AI needing to know or guess the session id. Merges with (and never
+          # overrides) any env the AI explicitly passed.
+          if call[:name] == "terminal" && @session_id
+            args[:env] = { "CLACKY_SESSION_ID" => @session_id.to_s }.merge(args[:env] || {})
+          end
+
           # For terminal: stream live stdout chunks to the UI as they arrive,
           # so the user sees real-time output (e.g. build logs) instead of a
           # blank spinner. The UI buffers lines for Ctrl+O fullscreen view

data/lib/clacky/agent_config.rb

@@ -165,7 +165,8 @@ module Clacky
                   :memory_update_enabled, :skill_evolution,
                   :max_running_agents, :max_idle_agents,
                   :default_working_dir,
-                  :proxy_url
+                  :proxy_url,
+                  :clacky_license_server
 
     def initialize(options = {})
       @permission_mode = validate_permission_mode(options[:permission_mode])
@@ -222,6 +223,7 @@ module Clacky
       # ignored — set proxy_url here to route Clacky's outbound HTTP through
       # a proxy. Leave nil to go direct.
       @proxy_url = options[:proxy_url]
+      @clacky_license_server = options[:clacky_license_server]
 
       # Per-session virtual model overlay.
       # When set, #current_model returns a *merged* hash (the resolved @models
@@ -414,7 +416,7 @@ module Clacky
       memory_update_enabled
       skill_evolution max_running_agents max_idle_agents
       default_working_dir
-      proxy_url
+      proxy_url clacky_license_server
     ].freeze
 
     # Serialize the current agent configuration to YAML.
@@ -434,7 +436,8 @@ module Clacky
         "max_running_agents" => @max_running_agents,
         "max_idle_agents" => @max_idle_agents,
         "default_working_dir" => @default_working_dir,
-        "proxy_url" => @proxy_url
+        "proxy_url" => @proxy_url,
+        "clacky_license_server" => @clacky_license_server
       }
       YAML.dump("settings" => settings, "models" => persistable_models)
     end

data/lib/clacky/brand_config.rb

@@ -383,16 +383,16 @@ module Clacky
 
     # Returns true when a public distribution refresh is due.
     #
-    # Refresh is needed only when the install has a package_name configured
-    # but is not yet activated — activated licenses already get fresh
-    # distribution data via #heartbeat! (once per 24h).
+    # Refresh is needed for unactivated branded installs and for private
+    # platform sources that have not supplied their deployment brand yet.
+    # Activated licenses already get fresh distribution data via #heartbeat!.
     #
     # Rate limit: once every HEARTBEAT_INTERVAL (24h), measured from the last
     # SUCCESSFUL refresh. A failed refresh does not advance the clock so we'll
     # keep trying on subsequent startups / status polls.
     def distribution_refresh_due?
-      return false unless branded?
       return false if activated?
+      return false unless branded? || private_platform_source?
       return true  if @distribution_last_refreshed_at.nil?
 
       elapsed = Time.now.utc - @distribution_last_refreshed_at
@@ -400,7 +400,8 @@ module Clacky
     end
 
     # Refresh public brand assets (logo, theme, homepage_url, support_*) for
-    # installs that have `package_name` configured but no activated license yet.
+    # unactivated installs. Package installs use an exact package lookup;
+    # private platform sources without a local brand use the source default.
     #
     # Motivation: `install.sh --brand-name=X --command=X` only writes
     # product_name + package_name to brand.yml. The rest of the distribution
@@ -409,32 +410,47 @@ module Clacky
     # anonymous public lookup endpoint.
     #
     # Behaviour:
-    #   * No-op (returns { success: false, message: "..." }) when not branded,
-    #     already activated, or package_name is blank.
+    #   * No-op when already activated, or when neither a package_name nor a
+    #     private platform source is available.
     #   * On success: apply_distribution + save + stamp
     #     @distribution_last_refreshed_at.
+    #   * When a block is provided, discard the response unless it still
+    #     confirms that the platform source is current.
     #   * On failure: log and return without touching the timestamp (so we
     #     retry on next trigger).
     #
     # Returns { success: Boolean, message: String }.
     def refresh_distribution!
-      unless branded?
+      source_brand_lookup = private_platform_source? &&
+                            (@package_name.nil? || @package_name.strip.empty?)
+      unless branded? || source_brand_lookup
         return { success: false, message: "Not branded" }
       end
       if activated?
         return { success: false, message: "License activated — use heartbeat! instead" }
       end
-      if @package_name.nil? || @package_name.strip.empty?
+      if !source_brand_lookup && (@package_name.nil? || @package_name.strip.empty?)
         return { success: false, message: "package_name not configured" }
       end
 
-      encoded_pkg = URI.encode_www_form_component(@package_name.strip)
-      path        = "/api/v1/distributions/lookup?package_name=#{encoded_pkg}"
+      if source_brand_lookup
+        path = "/api/v1/distributions/lookup"
+      else
+        encoded_pkg = URI.encode_www_form_component(@package_name.strip)
+        path = "/api/v1/distributions/lookup?package_name=#{encoded_pkg}"
+      end
 
-      Clacky::Logger.info("[Brand] refresh_distribution! fetching — package_name=#{@package_name}")
+      Clacky::Logger.info(
+        "[Brand] refresh_distribution! fetching — package_name=#{@package_name || "source-default"}"
+      )
       response = platform_client.get(path)
 
       if response[:success] && response[:data].is_a?(Hash) && response[:data]["distribution"].is_a?(Hash)
+        if block_given? && !yield
+          Clacky::Logger.info("[Brand] refresh_distribution! discarded — platform source changed")
+          return { success: false, message: "Platform source changed during refresh" }
+        end
+
         apply_distribution(response[:data]["distribution"])
         @distribution_last_refreshed_at = Time.now.utc
         save
@@ -1762,6 +1778,10 @@ module Clacky
       @homepage_url    = dist["homepage_url"]     if dist.key?("homepage_url")
     end
 
+    private def private_platform_source?
+      !ENV["CLACKY_LICENSE_SERVER"].to_s.strip.empty?
+    end
+
     # Download a remote URL to a local file path.
     #
     # Deprecated: this method now delegates to

data/lib/clacky/default_extensions/ext-studio/agents/ext-developer/system_prompt.md

@@ -143,3 +143,18 @@ main product, and apply every rule below whenever you propose or write code:
   Ruby and carry supply-chain risk.
 - After editing `view.js`, `handler.rb`, or a `SKILL.md`, tell the user to reload the
   WebUI page — hot reload is per-request, no restart needed.
+- After you finish editing extension files, call this once at the very end to trigger
+  a reload button in the UI (if it doesn't appear, the user can manually refresh the browser):
+  ```
+  curl -s --noproxy '*' -X POST "http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/ui/show_ext_refresh" \
+    -H "Content-Type: application/json" \
+    -d "{\"session_id\": \"${CLACKY_SESSION_ID}\"}"
+  ```
+  (`--noproxy '*'` prevents shell proxy env vars from silently intercepting this loopback call.)
+- If the extension contributes a `session.aside` panel, also call this right after the above
+  to open the panel automatically:
+  ```
+  curl -s --noproxy '*' -X POST "http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/ui/open_aside" \
+    -H "Content-Type: application/json" \
+    -d "{\"session_id\": \"${CLACKY_SESSION_ID}\"}"
+  ```