openclacky 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c8311a2bd1bd4cd050fce3e806479c580afb4da476201e59a041c2293347b5f
-  data.tar.gz: 520ba1c8c1821aede0b4766be3f321b3c121a91d3d9fe9e5dada0034479a3d4e
+  metadata.gz: 85707cf41b28f7283581fde4a77cbdf136ac525d9671743c13cfe268cf71c230
+  data.tar.gz: f2ccf13cf87f8aeb4e9ac2a27a7f7d3f1c8be53f196d52b39d412ae54bbd791a
 SHA512:
-  metadata.gz: e2d171e71ae9eb9cbecfc79bbf6ac1f3977268baf5a4026a57caffc378501ca6ca1bad8426237bcd949564ac1986d1b5b4bfe4f549f108d35f3e216edee75bdc
-  data.tar.gz: 8ba4d9fe3a50aacd4a247aae6877f391c73297c4e63b8c428b99a09f9c2d9ab642104ff5d6370c04556b679b2e3d041785f1833727605b3205638e7c7ea01126
+  metadata.gz: 33a52baaf3983e25e121d6e5200424d57b20d50af5226168df47b730e202add9ab296ecf9d480dc1380302d95b24273ad399b808290954875a139748c4879de8
+  data.tar.gz: c06c55d0765c8f657606dae02f214aeb938dc484522af5698bcd408b34379160e2bd850a9abdc91a82d4bf3f9925a20b698c3973a35839bb8886170f10d4215d

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.0] - 2026-07-23
+
+### Added
+- Volcengine Ark (Doubao) provider with endpoint-aware model-id mapping
+- Brand tab in extension marketplace for brand-private extensions
+- Auto-install all brand skills on license activation
+- Multi-background theme support with refactored theme engine
+- Short hash suffix in session-info-bar session file label with tooltips
+- Guide ext-develop skill to the host-API reference
+
+### Improved
+- Ext-developer skill prompt updated with engineering discipline guidelines
+- ext-develop skill merged into a single consolidated guide
+- Brand status fetch moved from view layer to store (cleaner architecture)
+- README check prompted before publishing extension
+- MCP page copy updated (removed Clacky brand name)
+- Floating window border effect added to content area
+
+### Fixed
+- CRLF normalization in SSE chunks for servers sending `\r\n\r\n` event separators
+- Subagent tool-item completion with DOM fallback when element not yet in DOM
+- AgentError now carries raw_message for LLM network/timeout errors
+- Extension data persisted outside package dir (C-5729)
+- Idle compression worker shutdown before process exit
+- Install button shown for all extension origins when download_url is present
+
 ## [1.4.1] - 2026-07-20
 
 ### Added

data/lib/clacky/agent/llm_caller.rb

@@ -201,7 +201,7 @@ module Clacky
             sleep retry_delay
             retry
           else
-            raise AgentError, "[LLM] #{I18n.t("llm.error.request_timeout", retries: max_retries)}"
+            raise AgentError.new("[LLM] #{I18n.t("llm.error.request_timeout", retries: max_retries)}", raw_message: e.message)
           end
 
         rescue Faraday::ConnectionFailed, Faraday::SSLError, Errno::ECONNREFUSED, Errno::ETIMEDOUT, Errno::EPIPE => e
@@ -236,7 +236,7 @@ module Clacky
           else
             # Don't show_error here — let the outer rescue block handle it to avoid duplicates.
             # Progress cleanup is the caller's responsibility (via its own ensure block).
-            raise AgentError, "[LLM] #{I18n.t("llm.error.network_failed", retries: max_retries)}"
+            raise AgentError.new("[LLM] #{I18n.t("llm.error.network_failed", retries: max_retries)}", raw_message: e.message)
           end
 
         rescue RetryableError => e
@@ -274,7 +274,7 @@ module Clacky
         else
           # Don't show_error here — let the outer rescue block handle it to avoid duplicates.
           # Progress cleanup is the caller's responsibility (via its own ensure block).
-          raise AgentError, "[LLM] #{I18n.t("llm.error.service_unavailable", retries: current_max)}"
+          raise AgentError.new("[LLM] #{I18n.t("llm.error.service_unavailable", retries: current_max)}", raw_message: e.message)
         end
 
         rescue Clacky::BadRequestError => e

data/lib/clacky/agent/session_serializer.rb

@@ -68,6 +68,7 @@ module Clacky
           }
         end
         backfill_task_meta_from_history!
+        heal_missing_chunk_paths!
 
         # Check if the session ended with an error.
         # We record the rollback intent here but do NOT truncate history immediately —
@@ -143,6 +144,31 @@ module Clacky
         end
       end
 
+      # Repair compressed_summary messages whose chunk_path is missing or points
+      # at a file that no longer exists. This happens when a hot restart's
+      # SIGKILL killed the worker after the chunk file was written to disk but
+      # before its path was persisted into session.json — the archived history
+      # then never renders on replay. Rediscover the chunk on disk from
+      # session_id + created_at and write the real path back, once, at load time.
+      private def heal_missing_chunk_paths!
+        return unless @session_id && @created_at
+
+        broken = @history.to_a.select do |m|
+          m[:compressed_summary] && !(m[:chunk_path] && File.exist?(m[:chunk_path].to_s))
+        end
+        return if broken.empty?
+
+        chunks = session_manager.chunks_for_current(@session_id, @created_at)
+        return if chunks.empty?
+
+        latest_path = chunks.last[:path]
+        broken.each { |m| m[:chunk_path] = latest_path }
+
+        session_manager.save(to_session_data(preserve_updated_at: true))
+      rescue => e
+        Clacky::Logger.warn("heal_missing_chunk_paths! failed: #{e.message}")
+      end
+
       private def persisted_card_field(key)
         card_id = @config.current_model_id
         return nil unless card_id
@@ -264,7 +290,7 @@ module Clacky
             rounds << current_round
           elsif current_round
             current_round[:events] << msg
-          elsif msg[:compressed_summary] && msg[:chunk_path]
+          elsif msg[:compressed_summary]
             # Compressed summary sitting before any user rounds — expand ALL chunk
             # MD files that belong to the same session (siblings of chunk_path),
             # in chunk-index ascending order.
@@ -274,15 +300,23 @@ module Clacky
             # points at the newest chunk). Older chunks (chunk-1..chunk-N-1) are
             # referenced only as basenames inside the summary text. Expanding just
             # msg[:chunk_path] would therefore lose all prior chunks on replay.
-            chunk_rounds = sibling_chunks_of(msg[:chunk_path]).flat_map { |p|
-              parse_chunk_md_to_rounds(p)
-            }
+            #
+            # chunk_path may be blank when a hot restart's SIGKILL killed the
+            # worker after the chunk file was written but before its path was
+            # persisted into session.json. Fall back to discovering the chunks
+            # on disk from session_id + created_at so the history is not lost.
+            chunk_paths = if msg[:chunk_path].to_s.empty?
+              session_manager.chunks_for_current(@session_id, @created_at).map { |c| c[:path] }
+            else
+              sibling_chunks_of(msg[:chunk_path])
+            end
+            chunk_rounds = chunk_paths.flat_map { |p| parse_chunk_md_to_rounds(p) }
             rounds.concat(chunk_rounds)
             # After expanding, treat the last chunk round as the current round so that
             # any orphaned assistant/tool messages that follow in session.json (belonging
             # to the same task whose user message was compressed into the chunk) get
             # appended here instead of being silently discarded.
-            current_round = rounds.last
+            current_round = rounds.last unless chunk_rounds.empty?
           elsif rounds.last
             # Orphaned non-user message with no current_round yet (e.g. recent_messages
             # after compression started mid-task with no leading user message).

data/lib/clacky/brand_config.rb

@@ -782,6 +782,41 @@ module Clacky
     rescue StandardError => e
       { success: false, error: "Network error: #{e.message}" }
     end
+
+    # Fetch detail for a single brand-private extension via the license-gated
+    # POST /api/v1/licenses/extension_detail endpoint.
+    # The public /api/v1/extensions/:id intentionally omits origin=self extensions,
+    # so activated brand users must use this signed request instead.
+    # Returns { success:, extension:, error: }.
+    def brand_extension_detail!(id)
+      return { success: false, error: "License not activated" } unless activated?
+
+      user_id   = parse_user_id_from_key(@license_key)
+      ts        = Time.now.utc.to_i.to_s
+      nonce     = SecureRandom.hex(16)
+      message   = "#{user_id}:#{@device_id}:#{ts}:#{nonce}"
+
+      payload = {
+        key_hash:  Digest::SHA256.hexdigest(@license_key),
+        user_id:   user_id.to_s,
+        device_id: @device_id,
+        timestamp: ts,
+        nonce:     nonce,
+        signature: OpenSSL::HMAC.hexdigest("SHA256", @license_key, message),
+        id:        id.to_s
+      }
+
+      response = api_post("/api/v1/licenses/extension", payload)
+
+      if response[:success]
+        { success: true, extension: response[:data]["extension"] }
+      else
+        { success: false, error: response[:error] || "Extension not found" }
+      end
+    rescue StandardError => e
+      { success: false, error: "Network error: #{e.message}" }
+    end
+
     # Extensions bundled into the activated license's distribution are free and
     # unencrypted. They are fetched over the same license-HMAC scheme as brand
     # skills and installed into the ExtensionLoader `installed` layer.
@@ -1213,7 +1248,10 @@ module Clacky
     # @param on_complete [Proc, nil] Optional callback called with the sync
     #   results array once all downloads finish (useful for tests / UI feedback).
     # @return [Thread, nil] The background thread, or nil if skipped.
-    def sync_brand_skills_async!(on_complete: nil)
+    # install_new: when true, install ALL remote skills regardless of whether they
+    # were previously installed. Used on first activation so every brand skill is
+    # available immediately without the user clicking Install one-by-one.
+    def sync_brand_skills_async!(on_complete: nil, install_new: false)
       return nil unless activated?
       return nil if ENV["CLACKY_TEST"] == "1"
 
@@ -1232,13 +1270,17 @@ module Clacky
             delete_brand_skill!(local_name) unless remote_skill_names.include?(local_name)
           end
 
-          # Auto-sync is intentionally limited to skills the user has already
-          # installed and that have a newer version available.
-          # New skills are never auto-installed — the user must click Install/Update
-          # explicitly from the Brand Skills panel.
+          # When install_new is true (e.g. on first activation) install every
+          # remote skill. Otherwise limit auto-sync to skills already installed
+          # locally that have a newer version available — new skills must be
+          # installed explicitly by the user from the Brand Skills panel.
           installed = installed_brand_skills
-          skills_needing_update = result[:skills].select { |s| s["needs_update"] }
-          results = skills_needing_update.map do |skill_info|
+          skills_to_install = if install_new
+                                result[:skills].select { |s| s["needs_update"] || !installed.key?(s["name"]) }
+                              else
+                                result[:skills].select { |s| s["needs_update"] }
+                              end
+          results = skills_to_install.map do |skill_info|
             install_brand_skill!(skill_info)
           end
 

data/lib/clacky/client.rb

@@ -55,17 +55,18 @@ module Clacky
     # Test API connection by sending a minimal request.
     # Returns { success: true } or { success: false, error: "..." }.
     def test_connection(model:)
+      api_model = Providers.resolve_api_model(base_url: @base_url, api_key: @api_key, model: model)
       if bedrock?
         body = MessageFormat::Bedrock.build_request_body(
-          [{ role: :user, content: "hi" }], model, [], 16
+          [{ role: :user, content: "hi" }], api_model, [], 16
         ).to_json
-        response = bedrock_connection.post(bedrock_endpoint(model)) { |r| r.body = body }
+        response = bedrock_connection.post(bedrock_endpoint(api_model)) { |r| r.body = body }
       elsif anthropic_format?
-        minimal_body = { model: model, max_tokens: 16,
+        minimal_body = { model: api_model, max_tokens: 16,
                          messages: [{ role: "user", content: "hi" }] }.to_json
         response = anthropic_connection.post(anthropic_messages_path) { |r| r.body = minimal_body }
       else
-        minimal_body = { model: model, max_tokens: 16,
+        minimal_body = { model: api_model, max_tokens: 16,
                          messages: [{ role: "user", content: "hi" }] }.to_json
         response = openai_connection.post("chat/completions") { |r| r.body = minimal_body }
       end
@@ -87,16 +88,17 @@ module Clacky
 
     # Send a messages array and return the reply text.
     def send_messages(messages, model:, max_tokens:)
+      api_model = Providers.resolve_api_model(base_url: @base_url, api_key: @api_key, model: model)
       if bedrock?
-        body     = MessageFormat::Bedrock.build_request_body(messages, model, [], max_tokens)
-        response = bedrock_connection.post(bedrock_endpoint(model)) { |r| r.body = body.to_json }
+        body     = MessageFormat::Bedrock.build_request_body(messages, api_model, [], max_tokens)
+        response = bedrock_connection.post(bedrock_endpoint(api_model)) { |r| r.body = body.to_json }
         parse_simple_bedrock_response(response)
       elsif anthropic_format?
-        body     = MessageFormat::Anthropic.build_request_body(messages, model, [], max_tokens, false)
+        body     = MessageFormat::Anthropic.build_request_body(messages, api_model, [], max_tokens, false)
         response = anthropic_connection.post(anthropic_messages_path) { |r| r.body = body.to_json }
         parse_simple_anthropic_response(response)
       else
-        body     = { model: model, max_tokens: max_tokens, messages: messages }
+        body     = { model: api_model, max_tokens: max_tokens, messages: messages }
         response = openai_connection.post("chat/completions") { |r| r.body = body.to_json }
         parse_simple_openai_response(response)
       end
@@ -127,6 +129,7 @@ module Clacky
     #   a single synthetic invocation is fired after the response is received,
     #   so UI plumbing can be exercised end-to-end without the proxy work.
     def send_messages_with_tools(messages, model:, tools:, max_tokens:, enable_caching: false, reasoning_effort: nil, on_chunk: nil)
+      api_model = Providers.resolve_api_model(base_url: @base_url, api_key: @api_key, model: model)
       caching_enabled = enable_caching && supports_prompt_caching?(model)
       cloned = deep_clone(messages)
 
@@ -141,13 +144,13 @@ module Clacky
       response =
         if bedrock?
           streaming_used = !on_chunk.nil?
-          send_bedrock_request(cloned, model, tools, max_tokens, caching_enabled, reasoning_effort: reasoning_effort, on_chunk: wrapped_on_chunk)
+          send_bedrock_request(cloned, api_model, tools, max_tokens, caching_enabled, reasoning_effort: reasoning_effort, on_chunk: wrapped_on_chunk)
         elsif anthropic_format?
           streaming_used = !on_chunk.nil?
-          send_anthropic_request(cloned, model, tools, max_tokens, caching_enabled, reasoning_effort: reasoning_effort, on_chunk: wrapped_on_chunk)
+          send_anthropic_request(cloned, api_model, tools, max_tokens, caching_enabled, reasoning_effort: reasoning_effort, on_chunk: wrapped_on_chunk)
         else
           streaming_used = !on_chunk.nil?
-          send_openai_request(cloned, model, tools, max_tokens, caching_enabled, reasoning_effort: reasoning_effort, on_chunk: wrapped_on_chunk)
+          send_openai_request(cloned, api_model, tools, max_tokens, caching_enabled, reasoning_effort: reasoning_effort, on_chunk: wrapped_on_chunk, capability_model: model)
         end
       t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
@@ -333,17 +336,20 @@ module Clacky
 
     # ── OpenAI request / response ─────────────────────────────────────────────
 
-    def send_openai_request(messages, model, tools, max_tokens, caching_enabled, reasoning_effort: nil, on_chunk: nil)
+    def send_openai_request(messages, model, tools, max_tokens, caching_enabled, reasoning_effort: nil, on_chunk: nil, capability_model: nil)
       # Apply cache_control markers to messages when caching is enabled.
       # OpenRouter proxies Claude with the same cache_control field convention as Anthropic direct.
       messages = apply_message_caching(messages) if caching_enabled
 
-      # Vision support is resolved against the request's actual model (which may
-      # differ from @model after a runtime switch or fallback override), so the
-      # conversion layer strips image_url blocks for non-vision models.
+      # Vision support is resolved against the display model name, which is the
+      # key our capability table is declared with. `model` may be an
+      # endpoint-specific API id (e.g. Ark payg's "glm-5-2-260617") that the
+      # table can't match — so the caller passes the display name separately
+      # via capability_model to keep the vision judgement accurate.
+      cap_model = capability_model || model
       body = MessageFormat::OpenAI.build_request_body(
         messages, model, tools, max_tokens, caching_enabled,
-        vision_supported: Providers.supports?(@provider_id, :vision, model_name: model),
+        vision_supported: Providers.supports?(@provider_id, :vision, model_name: cap_model),
         reasoning_effort: reasoning_effort
       )
       return send_openai_stream_request(body, on_chunk) if on_chunk

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

@@ -1,94 +1,145 @@
-You are Extension Developer, an AI expert who helps users build, debug, and publish
-OpenClacky extensions through conversation. You know the OpenClacky extension system
-inside out and drive the whole workflow — scaffold, edit, verify, reload, publish —
-so the user never has to memorize commands or file layouts.
+You are Extension Developer, an AI expert who helps users build, debug, and (when they
+ask) publish OpenClacky extensions through conversation. You drive the whole workflow —
+scaffold, edit, verify, reload — so the user never has to memorize commands or file
+layouts.
 
 Your role is to:
 - Turn a plain-language idea ("I want an extension that shows the weather") into a
   working extension by scaffolding it, wiring the right contributes, and iterating.
 - Read and edit extension files directly, then verify and hot-reload to confirm.
 - Debug using structured verify errors, fixing manifest and file issues.
-- Guide the user through packing and publishing to the marketplace.
-
-## The Extension Model (ground truth)
-
-An extension is one directory containing an `ext.yml` manifest that declares
-`contributes:`. Nothing is nested — units reference each other by id.
-
-Three layers, override precedence `local > installed > builtin`:
-- `builtin`  — bundled in the gem (`default_extensions/`)
-- `installed` — `~/.clacky/ext/installed/<id>/` (from `ext install`)
-- `local`    — `~/.clacky/ext/local/<id>/` (where users develop; `ext new` lands here)
-
-Seven contributes types (each is a self-describing unit):
-- `panels`   — WebUI panels (a `view.js`, no build step, no React, no iframe)
-- `api`      — one backend file `api/handler.rb`, mounted at `/api/ext/<id>/`
-- `skills`   — a `SKILL.md` under `skills/<id>/` (prompt-only capability)
-- `agents`   — a `system_prompt.md`; can reference `panels: [id]` and `skills: [id]`
-- `channels` — an IM adapter
-- `patches`  — monkey-patch a real class (advanced, supply-chain risk)
-- `hooks`    — lifecycle hooks like `before_tool_use` (advanced)
-
-Hot reload is per-request: after editing `view.js`, `handler.rb`, or a `SKILL.md`,
-the user just reloads the WebUI page — no server restart. Editing `ext.yml` also
-takes effect on the next load.
-
-## ext.yml shape (memorize this)
-
-```yaml
-id: my-ext
-name: My Extension
-description: what it does
-version: "0.1.0"
-contributes:
-  api: api/handler.rb
-  panels:
-    - id: dashboard
-      view: panels/dashboard/view.js
-      attach: ["*"]          # panels/agents to attach to; "*" = all
-  skills:
-    - id: my-ext-skill       # SKILL.md lives at skills/my-ext-skill/SKILL.md
-  agents:
-    - id: helper
-      title: Helper
-      prompt: agents/helper/system_prompt.md
-      panels: [dashboard]
-      skills: [my-ext-skill]
-```
-
-Panel `view.js` mounts via `Clacky.ext.ui.mount(slot, spec, opts)`. Backend classes
-subclass `Clacky::ApiExtension` and define routes relative to `/api/ext/<id>/`.
-
-## Working process
-
-You have three companion skills — they fire automatically when the situation matches,
-but you own the flow and decide when to lean on each:
-- **ext-scaffold** — when the user wants to start a new extension.
-- **ext-debug** — when something is broken, verify reports errors, or a panel/api won't load.
-- **ext-publish** — when the extension is ready to ship to the marketplace.
-
-Typical loop:
-1. Clarify the idea in one question if it's ambiguous (what should it DO, and where —
-   a panel, a skill, an agent, a backend?). Then map it to the smallest set of
-   contributes types. Don't over-scope — most extensions are one panel + one handler,
-   or one skill.
-2. Scaffold with `clacky ext new <id>` (add `--full` only if they truly need the
-   kitchen-sink reference). Read the generated files so you know the starting point.
-3. Edit the files to match the idea — real code, not placeholders. Follow the panel
-   styling convention: reuse host classes (`btn-primary`, `btn-secondary`,
-   `form-input`, `form-textarea`, `form-label`) so the extension inherits the theme.
-4. Run `clacky ext verify` and read the output. Each `[ERR]`/`[WARN]` is structured
-   (`{ext, unit, code, message, file, hint}`) — the `hint` tells you how to fix it.
-   Fix, re-verify, until clean.
-5. Tell the user to reload the WebUI page to see panels/api changes live.
-6. When they're happy, hand off to publishing: `clacky ext pack <id>` then
-   `clacky ext publish <id>` (requires an activated user license).
+- Publish to the marketplace only when the user explicitly wants to share it.
+
+## How you work
+
+The `ext-develop` skill holds the authoritative extension model, the contributes-type
+map, the verify error codes, the `Clacky.*` WebUI contract, the host APIs a panel can
+call, and the publish commands. It is your knowledge base; this prompt is only your
+behavior. Actively open the skill and read the relevant section at the start of any
+extension work — don't wait for it to surface on its own, and never work from memory when
+the skill has the answer. You own the flow and decide when each section applies:
+
+- **Scaffold** — when the user wants to start a new extension. Clarify the idea in one
+  question if it's ambiguous (what should it DO, and where — a panel, a skill, an agent,
+  a backend?), map it to the smallest set of contributes types, then `clacky ext new`.
+  Don't over-scope: most extensions are one panel + one handler, or one skill.
+- **Debug & verify** — when something is broken, `verify` reports errors, or a change
+  didn't take effect. `clacky ext verify` is your compiler; fix by error code until clean.
+- **Publish** — only when the user explicitly asks to share/ship it. Publishing is NOT a
+  required step; many extensions are built for the user's own use. Never publish on your
+  own initiative or as a "wrap up."
+
+## Working discipline (never break these)
+
+- **Know before you speak, not just before you code.** You are the expert who is supposed
+  to deeply understand OpenClacky extensions — that expertise comes from *looking things
+  up*, not from memory. Before you propose a design OR write a line of code, make sure you
+  actually have the facts: consult the `ext-develop` skill for the model and contracts,
+  and when a field name, event, adapter method, or WebUI/API detail is anything less than
+  certain, `web_fetch` the matching reference doc the skill points to. Never invent field
+  names, endpoints, or behavior from memory. When in doubt, look it up one more time — a
+  wasted lookup is cheap, a confidently wrong answer is not.
+- **Reuse the host before you build.** When a request touches sessions, file recovery
+  (trash), skills, memories, scheduled tasks, billing/usage, or media, assume the host may
+  already expose a ready-made API a panel can call — check the host-API reference the skill
+  points to before you invent a backend. Don't rebuild what the host already provides.
+- **Discuss the plan first, act only after the user agrees.** Every time, walk the user
+  through what you intend to do — what it is, where it lives, and what it will look like —
+  in plain words, and wait for a clear yes before you scaffold or edit anything. Never
+  quietly change files mid-conversation or scaffold before the user has signed off.
+- **Verify before you claim.** "It should work" is not "it works." Run `verify`, or have
+  the user reload and confirm, before you say something is done.
+
+## Talking to the user
+
+Most users are not programmers. Talk to them like a helpful teammate, not a compiler.
+This applies to **everything** you say to them — proposing a plan, reporting what you
+changed, or explaining a bug and its fix. The moment you slip into raw code and API names
+is exactly the moment the user gets lost, and those "here's what I fixed" updates are
+where it happens most.
+
+- **One language at a time.** In a Chinese conversation, speak Chinese; in an English one,
+  speak English. Don't sprinkle the other language's technical jargon through your
+  sentences. When a technical term is unavoidable, add a short plain-language gloss the
+  first time it appears (e.g. "a handler — the small backend file that answers requests").
+- **Translate the jargon.** Words like *contributes*, *slot*, *manifest*, *handler* mean
+  nothing to most users. Say what they DO: a panel is "a screen inside the app," a slot is
+  "a spot in the UI where your thing shows up," `ext.yml` is "the extension's settings
+  file."
+- **Report in outcomes, not code.** When you tell the user what you did or what broke,
+  describe it in terms of what they can SEE or what behavior changed — not the code you
+  touched. Keep symbol names (`ui.mount`, `container.appendChild`, `handler.rb`,
+  `sidebar.nav`), library names, and file internals out of your message unless the user is
+  clearly technical or explicitly asks. If a detail matters, say it in plain words.
+  - ❌ "Fixed it — the `saved city` branch had an early `return` so the DOM never mounted;
+    added `container.appendChild(root)`."
+  - ✅ "Found it — when a saved city was remembered, the panel built its content but never
+    showed it. Fixed, refresh and it'll appear."
+  - ❌ "Changed the architecture: frontend → own backend → Open-Meteo; added a `daily`
+    param to the handler."
+  - ✅ "Reworked it so weather still loads where the direct connection was blocked, and
+    added a 5-day forecast. Give it a refresh."
+- **Map vague locations to real mount points.** Users describe UI by rough position
+  ("put a button in the top-right", "add something to the left sidebar"). Internally,
+  translate that to the actual slot below and build against it — but when you talk to the
+  user, keep saying "top-right" or "middle of the left sidebar," not the slot name. The
+  host renders exactly these named slots:
+
+  | What the user might say            | Real slot            |
+  | ---------------------------------- | -------------------- |
+  | top bar, left / right              | `header.left` / `header.right` |
+  | left sidebar — top / middle / bottom | `sidebar.nav.top` / `sidebar.nav` / `sidebar.nav.bottom` |
+  | bottom of the left sidebar         | `sidebar.footer`     |
+  | the main area / a full page        | `main.workspace`     |
+  | a banner at the top of a chat      | `session.banner`     |
+  | near the message input box         | `session.composer`   |
+  | the right-hand panel of a chat     | `session.aside` (tabbed) |
+  | a settings tab / its body          | `settings.tabs` / `settings.body` |
+
+  Mounting into any other name silently does nothing — always use one of these.
+
+## Extension engineering rules
+
+These are requirements, not suggestions. Hold the same engineering bar you would for the
+main product, and apply every rule below whenever you propose or write code:
+
+- **Performance.** Keep the panel light and the UI responsive. Do NOT spin up extra
+  threads unless there is truly no other way — default to none. The real danger is request
+  volume: don't hammer the host with tight loops, sub-second polling, or requests that
+  never stop, and don't re-fetch the same data over and over — fetch once and cache what
+  you can. Polling is fine when there's genuinely no push channel for the data you need,
+  but keep the interval coarse (seconds, not milliseconds), prefer the host's events if
+  they exist, and stop polling when the panel is hidden or the work is done. Runaway
+  request volume can hit the host's limits, block its own request handling, and bring the
+  whole of OpenClacky down — treat this as a hard safety concern, not a nicety.
+- **Security.** Never help build a malicious extension. If a user asks for something that
+  steals or exfiltrates data — other people's API keys, credentials, private session
+  content, files outside the extension's scope — refuse plainly and explain why. Respect
+  the host's auth boundaries; an extension acts on behalf of its own user, nothing more.
+- **Cost.** Billing and usage endpoints cost the user real money. Call them only on an
+  explicit user action, never automatically and never in a loop.
+- **Architecture.** For a small extension, don't over-engineer — a single panel, handler,
+  or skill is usually enough, and abstraction it doesn't need is just noise. But when the
+  user is building something larger, apply sound design: high cohesion and low coupling,
+  DRY, the SOLID principles, and simplicity, so the extension stays easy to iterate on and
+  maintain. Put logic where it belongs.
+- **Match the native UI.** By default, reuse the host's CSS classes (`btn-primary`,
+  `btn-secondary`, `form-input`, `form-textarea`, `form-label`) so the extension inherits
+  the theme and looks like it belongs. If the user explicitly wants a custom look, that's
+  fully supported — OpenClacky is built to be deeply customizable — so build what they ask
+  for.
+- **Maintainability.** Leave sensible comments where they help a future reader — the
+  non-obvious *why*, a tricky bit of logic — so the extension is easy to pick up and
+  iterate on later. Don't over-comment the obvious.
+- **Robustness.** Handle empty states, errors, and failed loads — don't assume the happy
+  path.
 
 ## Guidance
 
-- Prefer editing real files over describing what to do. You are hands-on.
+- Prefer editing real files over describing what to do (once the user has agreed to the
+  plan). You are hands-on.
 - Keep extensions minimal — add only the contributes types the idea needs.
-- Never scaffold `patches` or `hooks` unless the user explicitly asks; they run
-  arbitrary Ruby and carry supply-chain risk.
-- Explain results in plain terms — the user may not be an extension expert.
-- Verify before you claim something works. "It should work" is not "it works."
+- Never scaffold `patches` or `hooks` unless the user explicitly asks; they run arbitrary
+  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.

data/lib/clacky/default_extensions/ext-studio/ext.yml

@@ -25,8 +25,6 @@ contributes:
       prompt: agents/ext-developer/system_prompt.md
       avatar: agents/ext-developer/avatar.png
       panels: [studio]
-      skills: [ext-scaffold, ext-debug, ext-publish]
+      skills: [ext-develop]
   skills:
-    - id: ext-scaffold
-    - id: ext-debug
-    - id: ext-publish
+    - id: ext-develop