Merge remote-tracking branch 'origin/main' into sawka/wave-12

Author: sawka

.github/workflows/bump-version.yml

@@ -29,7 +29,7 @@ jobs:
         runs-on: ubuntu-latest
         steps:
             - name: Get App Token
-              uses: actions/create-github-app-token@v1
+              uses: actions/create-github-app-token@v2
               id: app-token
               with:
                   app-id: ${{ vars.WAVE_BUILDER_APPID }}

.roo/rules/rules.md

@@ -44,7 +44,7 @@ The frontend uses yarn (berry).
 
 ### Styling
 
-- We use tailwind v4 to style. Custom stuff is defined in tailwindsetup.css.
+- We use **Tailwind v4** to style. Custom stuff is defined in frontend/tailwindsetup.css
 - _never_ use cursor-help (it looks terrible)
 - We have custom CSS setup as well, so it is a hybrid system. For new code we prefer tailwind, and are working to migrate code to all use tailwind.
 
@@ -53,14 +53,16 @@ The frontend uses yarn (berry).
 - **TypeScript Types**: TypeScript types are automatically generated from Go types. After modifying Go types in `pkg/wshrpc/wshrpctypes.go`, run `task generate` to update the TypeScript type definitions in `frontend/types/gotypes.d.ts`.
 - **Manual Edits**: Do not manually edit generated files like `frontend/types/gotypes.d.ts` or `frontend/app/store/wshclientapi.ts`. Instead, modify the source Go types and run `task generate`.
 
-### Documentation References
+### Development Documentation
 
-Found in /aiprompts
+The `/aiprompts` directory contains comprehensive guides for common development tasks:
 
-- config-system.md -- for help with adding new config or settings values
-- contextmenu.md
-- getsetconfigvar.md
-- view-prompt.md -- view model guide
+- **config-system.md** - Complete guide for adding new configuration settings, including the hierarchical config system with global, connection, and block-level overrides
+- **contextmenu.md** - Instructions for adding context menu items and actions
+- **getsetconfigvar.md** - Reference for reading and writing configuration values programmatically
+- **view-prompt.md** - Architecture guide for implementing new view models and components
+
+These files provide step-by-step instructions, code examples, and best practices for extending Wave Terminal's functionality.
 
 ### Frontend Architecture
 

Taskfile.yml

@@ -110,10 +110,9 @@ tasks:
     package:
         desc: Package the application for the current platform.
         cmds:
-            - cmd: '{{.RMRF}} "make"'
-              ignore_error: true
             - yarn build:prod && yarn electron-builder -c electron-builder.config.cjs -p never {{.CLI_ARGS}}
         deps:
+            - clean
             - yarn
             - docsite:build:embedded
             - build:backend
@@ -267,6 +266,8 @@ tasks:
         sources:
             - "cmd/wsh/**/*.go"
             - "pkg/**/*.go"
+        generates:
+            - "dist/bin/wsh*"
 
     build:wsh:internal:
         vars:
@@ -429,3 +430,11 @@ tasks:
         desc: Recursively copy directory and its contents.
         internal: true
         cmd: '{{if eq OS "windows"}}powershell Copy-Item -Recurse -Force -Path {{index .MATCH 0}} -Destination {{index .MATCH 1}}{{else}}mkdir -p "$(dirname {{index .MATCH 1}})" && cp -r {{index .MATCH 0}} {{index .MATCH 1}}{{end}}'
+
+    clean:
+        desc: clean make/dist directories
+        cmds:
+            - cmd: '{{.RMRF}} "make"'
+              ignore_error: true
+            - cmd: '{{.RMRF}} "dist"'
+              ignore_error: true

aiprompts/config-system.md

@@ -41,6 +41,7 @@ waveterm/
 ```
 
 **Key Files:**
+
 - **[`pkg/wconfig/settingsconfig.go`](pkg/wconfig/settingsconfig.go)** - Defines the `SettingsType` struct with all configuration fields
 - **[`schema/settings.json`](schema/settings.json)** - JSON Schema for validation and type checking
 - **[`pkg/wconfig/defaultconfig/settings.json`](pkg/wconfig/defaultconfig/settings.json)** - Default values for all settings
@@ -56,6 +57,38 @@ waveterm/
 
 Settings cascade from defaults → user settings → block overrides.
 
+### Block-Level Metadata Override System
+
+Wave Terminal supports block-level configuration overrides through the metadata system. This allows settings to be applied globally, per-connection, or per-block:
+
+1. **Global Settings** (`~/.config/waveterm/settings.json`) - Apply to all blocks by default
+2. **Connection Settings** (in connections config) - Apply to all blocks using a specific connection
+3. **Block Metadata** - Override settings for individual blocks
+
+**Key Files for Block Overrides:**
+
+- **[`pkg/waveobj/wtypemeta.go`](pkg/waveobj/wtypemeta.go)** - Defines the `MetaTSType` struct for block-level metadata
+- Block metadata fields should match the corresponding settings fields for consistency
+
+**Frontend Usage:**
+
+```typescript
+// Use getOverrideConfigAtom for hierarchical config resolution
+const settingValue = useAtomValue(getOverrideConfigAtom(blockId, "namespace:setting"));
+
+// This automatically resolves in order: block metadata → connection config → global settings → default
+```
+
+**Setting Block Metadata:**
+
+```bash
+# Set for current block
+wsh setmeta namespace:setting=value
+
+# Set for specific block
+wsh setmeta --block BLOCK_ID namespace:setting=value
+```
+
 ## How to Add a New Configuration Value
 
 Follow these steps to add a new configuration setting:
@@ -94,6 +127,31 @@ type SettingsType struct {
 - Use `[]string` for arrays
 - Use `float64` for numbers that can be decimals
 
+### Step 1.5: Add to Block Metadata (Optional)
+
+If your setting should support block-level overrides, also add it to [`pkg/waveobj/wtypemeta.go`](pkg/waveobj/wtypemeta.go):
+
+```go
+type MetaTSType struct {
+    // ... existing fields ...
+
+    // Add your new field with matching JSON tag and type
+    MyNewSetting *string `json:"mynew:setting,omitempty"`  // Use pointer for optional values
+
+    // For different types:
+    MyBoolSetting   *bool    `json:"mynew:boolsetting,omitempty"`
+    MyNumberSetting *float64 `json:"mynew:numbersetting,omitempty"`
+    MyIntSetting    *int     `json:"mynew:intsetting,omitempty"`
+    MyArraySetting  []string `json:"mynew:arraysetting,omitempty"`
+}
+```
+
+**Block Metadata Guidelines:**
+
+- Use pointer types (`*string`, `*bool`, `*int`, `*float64`) for optional overrides
+- JSON tags should exactly match the corresponding settings field
+- This enables the hierarchical config system: block metadata → connection config → global settings
+
 ### Step 2: Add to JSON Schema
 
 Edit [`schema/settings.json`](schema/settings.json) and add your field to the `properties` section:
@@ -144,7 +202,7 @@ If your setting should have a default value, add it to [`pkg/wconfig/defaultconf
 ```json
 {
   "ai:preset": "ai@global",
-  "ai:model": "gpt-4o-mini",
+  "ai:model": "gpt-5-mini",
   // ... existing defaults ...
 
   "mynew:setting": "default value",
@@ -186,6 +244,7 @@ task generate
 ```
 
 Or run them individually:
+
 ```bash
 # Regenerate JSON schema
 task build:schema
@@ -201,20 +260,35 @@ This will update the schema files and [`frontend/types/gotypes.d.ts`](frontend/t
 Access your new setting in React components:
 
 ```typescript
-import { useSettingsKeyAtom } from "@/app/store/global";
+import { getOverrideConfigAtom, useAtomValue } from "@/store/global";
 
 // In a React component
-const MyComponent = () => {
-    // Read global setting with fallback
-    const mySetting = useSettingsKeyAtom("mynew:setting") ?? "fallback value";
+const MyComponent = ({ blockId }: { blockId: string }) => {
+    // Use override config atom for hierarchical resolution
+    // This automatically checks: block metadata → connection config → global settings → default
+    const mySettingAtom = getOverrideConfigAtom(blockId, "mynew:setting");
+    const mySetting = useAtomValue(mySettingAtom) ?? "fallback value";
 
-    // For block-specific overrides
-    const myBlockSetting = useOverrideConfigAtom(blockId, "mynew:setting") ?? "fallback";
+    // For global-only settings (no block overrides)
+    const globalOnlySetting = useAtomValue(getSettingsKeyAtom("mynew:globalsetting")) ?? "fallback";
 
     return <div>Setting value: {mySetting}</div>;
 };
 ```
 
+**Frontend Configuration Patterns:**
+
+```typescript
+// 1. Settings with block-level overrides (recommended)
+const termFontSize = useAtomValue(getOverrideConfigAtom(blockId, "term:fontsize")) ?? 12;
+
+// 2. Global-only settings
+const appGlobalHotkey = useAtomValue(getSettingsKeyAtom("app:globalhotkey")) ?? "";
+
+// 3. Connection-specific settings
+const connStatus = useAtomValue(getConnStatusAtom(connectionName));
+```
+
 ### Step 7: Use in Backend Code
 
 Access settings in Go code:
@@ -270,7 +344,7 @@ await RpcApi.SetMetaCommand(TabRpcClient, {
 
 ## Example: Adding a New Terminal Setting
 
-Let's walk through adding a new terminal setting `term:bellsound`:
+Let's walk through adding a new terminal setting `term:bellsound` with block-level override support:
 
 ### 1. Go Struct (settingsconfig.go)
 
@@ -281,7 +355,16 @@ type SettingsType struct {
 }
 ```
 
-### 2. JSON Schema (schema/settings.json)
+### 2. Block Metadata (wtypemeta.go)
+
+```go
+type MetaTSType struct {
+    // ... existing fields ...
+    TermBellSound *string `json:"term:bellsound,omitempty"`  // Pointer for optional override
+}
+```
+
+### 3. JSON Schema (schema/settings.json)
 
 ```json
 {
@@ -293,24 +376,39 @@ type SettingsType struct {
 }
 ```
 
-### 3. Default Value (defaultconfig/settings.json)
+### 4. Default Value (defaultconfig/settings.json)
 
 ```json
 {
   "term:bellsound": "default"
 }
 ```
 
-### 4. Documentation (docs/config.mdx)
+### 5. Documentation (docs/config.mdx)
 
 ```markdown
 | term:bellsound | string | Sound to play for terminal bell ("default", "none", or custom sound file path) |
 ```
 
-### 5. Frontend Usage
+### 6. Frontend Usage
 
 ```typescript
-const bellSound = useOverrideConfigAtom(blockId, "term:bellsound") ?? "default";
+// Use override config for hierarchical resolution
+const bellSoundAtom = getOverrideConfigAtom(blockId, "term:bellsound");
+const bellSound = useAtomValue(bellSoundAtom) ?? "default";
+```
+
+### 7. Usage Examples
+
+```bash
+# Set globally
+wsh setconfig term:bellsound="custom.wav"
+
+# Set for current block only
+wsh setmeta term:bellsound="none"
+
+# Set for specific block
+wsh setmeta --block BLOCK_ID term:bellsound="beep"
 ```
 
 ## Testing Your Configuration