xonecas.io
60255
Zn

Zoea-Nova / commit cab7252

Merge branch 'workflow-and-tooling-refactor'

Consolidates OpenCode configuration to reduce context bloat and improve
agent effectiveness across all projects.

Key changes:
- WORKFLOW.md v1.0 with timing estimates and abort criteria
- Global config cleanup (skills → embedded principles in AGENTS.md)
- Local config organization (project-specific skills only)
- Removed redundant agents and orphaned files

This refactor achieves:
1. Systematic work without frustration (clear processes)
2. Enhanced development practices (actionable principles)
3. Correct and valuable information (typos fixed)
4. Support for multi-agent workflow (direct alignment)

See individual commits for detailed changes.

xonecas2026-02-07 cab7252815ce3f281e213169e4f17ce8bd4e0050 parent 60a12ddparent 69d817b

16 files changed

This diff is too big to show in full. The first 1000 lines are below, and every file is listed with its counts.

.opencode/agents/zoea-analyser.md+3−2
@@ -1,5 +1,5 @@
11 ---
2-description: Agent with data access for a analysis.
2+description: Agent with data access for analysis.
33 agent: general
44 mode: subagent
55 model: opencode/gemini-3-flash
@@ -33,7 +33,7 @@ You can query the SQLite database using the `sqlite3` command via the `Bash` too
3333 The application logs to `~/.zoea-nova/zoea.log` using `zerolog` (JSON format).
3434
3535 - Use `tail -n 100 ~/.zoea-nova/zoea.log` for recent activity.
36-- Use `grep "error" ~/.zoea-nova/zoea.log` to identify failures.
36+- Use Grep tool with pattern "error" to identify failures in the log file.
3737 - Look for `mysis_id`, `event`, and `level` fields in the JSON logs.
3838
3939 Ollama server logs (for LLM provider issues):
@@ -48,5 +48,6 @@ When asked for an analysis, provide a structured report covering:
4848 2. **Activity Summary**: Recent broadcast activity and mysis-specific conversation volume.
4949 3. **Health Check**: Any errors found in the logs or anomalous mysis behaviors.
5050 4. **Insights**: Trends in mysis interactions or performance bottlenecks.
51+5. **Mysis behaviour analysis**: Trends in gameplay.
5152
5253 Keep your analysis concise and data-driven. Always provide the raw data or query results if they support your conclusions.
.opencode/agents/zoea-expert.md+0−14
@@ -1,14 +0,0 @@
1----
2-description: Agent with knowledge in this project.
3-agent: general
4-mode: primary
5----
6-
7-You have access to @explore and @zoea-analyzer subagents. Use them and your knowdledge of the codebase to answer the user's questions.
8-You have tooling to search the internet use it to follow documentation links and to answer to the user.
9-
10-**CRITICAL RULES**:
11-
12-- Don't edit files unless explicitly told so, ex: "save this to...".
13-- Don't reply hastely, ensure you gather facts before answering.
14-- Use the writing-clearly-and-concisely skill to reply to the user.
.opencode/phase3_unicode_summary.md+0−283
@@ -1,283 +0,0 @@
1-# Phase 3: Unicode Character Consistency - Summary
2-
3-## Completion Date
4-2026-02-05
5-
6-## Overview
7-Comprehensive documentation and testing of all Unicode characters used in the Zoea Nova TUI to ensure consistent rendering across terminals and prevent ambiguous width issues.
8-
9-## Characters Documented
10-
11-### Decorative Characters
12-| Character | Codepoint | Name | Usage |
13-|-----------|-----------|------|-------|
14-| ⬥ | U+2B25 | BLACK MEDIUM DIAMOND | Header corners, status bar, message prompt, spinner frames 5/7 |
15-| ⬧ | U+2B27 | BLACK MEDIUM LOZENGE | Section borders (SWARM BROADCAST, MYSIS SWARM), broadcast prompt |
16-| ⬡ | U+2B21 | WHITE HEXAGON | Title decoration, new mysis prompt, spinner frames 0/2 |
17-| ⬢ | U+2B22 | BLACK HEXAGON | Spinner frames 1/3 |
18-| ⬦ | U+2B26 | WHITE MEDIUM DIAMOND | Spinner frames 4/6, idle status indicator |
19-
20-### State Indicators
21-| Character | Codepoint | Name | Usage |
22-|-----------|-----------|------|-------|
23-| ◦ | U+25E6 | WHITE BULLET | Idle state in mysis list |
24-| ◌ | U+25CC | DOTTED CIRCLE | Stopped state in mysis list |
25-| ✖ | U+2716 | HEAVY MULTIPLICATION X | Errored state in mysis list |
26-
27-### Input Prompts
28-| Character | Codepoint | Name | Usage |
29-|-----------|-----------|------|-------|
30-| ⬧ | U+2B27 | BLACK MEDIUM LOZENGE | Broadcast mode prompt |
31-| ⬥ | U+2B25 | BLACK MEDIUM DIAMOND | Message mode prompt |
32-| ⬡ | U+2B21 | WHITE HEXAGON | New mysis mode prompt |
33-| ⚙ | U+2699 | GEAR | Config provider mode prompt |
34-
35-### Border Characters
36-| Character | Codepoint | Name | Usage |
37-|-----------|-----------|------|-------|
38-| ╔═╗║╚╝ | U+2554-U+255D | DOUBLE LINE BOX | Mysis list panel border |
39-| ─ | U+2500 | HORIZONTAL LINE | Section decorations, focus header |
40-| ╭╮╰╯ | U+256D-U+256F | ROUNDED CORNER | Input prompt border |
41-
42-## Spinner Animation Verified
43-
44-**Frames:** 8 total
45-**Speed:** 125ms per frame (8 FPS)
46-**Pattern:** Hexagonal theme alternating between filled/hollow shapes
47-
48-| Frame | Character | Codepoint | Visual |
49-|-------|-----------|-----------|--------|
50-| 0 | ⬡ | U+2B21 | Hollow hexagon |
51-| 1 | ⬢ | U+2B22 | Filled hexagon |
52-| 2 | ⬡ | U+2B21 | Hollow hexagon |
53-| 3 | ⬢ | U+2B22 | Filled hexagon |
54-| 4 | ⬦ | U+2B26 | Hollow diamond |
55-| 5 | ⬥ | U+2B25 | Filled diamond |
56-| 6 | ⬦ | U+2B26 | Hollow diamond |
57-| 7 | ⬥ | U+2B25 | Filled diamond |
58-
59-**Verification:**
60-- ✅ All frames render with width=1
61-- ✅ Animation speed matches expected 125ms/frame
62-- ✅ No frame causes layout shift
63-- ✅ Hexagonal theme matches logo aesthetic
64-
65-## Width Consistency Tests
66-
67-### Test Results
68-All characters verified to have:
69-- ✅ Width of 1 via `lipgloss.Width()`
70-- ✅ Width of 1 via `runewidth.RuneWidth()`
71-- ✅ **NOT** ambiguous width (render consistently in East Asian locales)
72-
73-### Ambiguous Width Safety
74-All characters tested in both narrow and wide East Asian modes:
75-- Narrow mode (EastAsianWidth=false): width=1
76-- Wide mode (EastAsianWidth=true): width=1
77-- **Result:** No ambiguous width characters detected
78-
79-This prevents the Unicode overlap bug previously fixed in commit fb1d0b6.
80-
81-## Terminal Compatibility
82-
83-### Tested Terminals
84-| Terminal | Status | Notes |
85-|----------|--------|-------|
86-| Alacritty | ✅ Excellent | Best rendering, all characters clear |
87-| Kitty | ✅ Excellent | Full Unicode support |
88-| WezTerm | ✅ Excellent | Native font fallback |
89-| iTerm2 | ✅ Good | May vary with font |
90-| Terminal.app | ⚠️ Fair | Font-dependent |
91-| Windows Terminal | ✅ Good | Requires Nerd Font or Unicode font |
92-| gnome-terminal | ✅ Good | Most fonts work well |
93-| xterm | ⚠️ Limited | May not render all characters |
94-
95-### Font Recommendations
96-**Recommended:**
97-- FiraCode Nerd Font
98-- JetBrains Mono Nerd Font
99-- Cascadia Code
100-- Ubuntu Mono
101-- Inconsolata
102-
103-**Fallback:**
104-- DejaVu Sans Mono (decent Unicode coverage)
105-
106-## Test Coverage
107-
108-### New Test File
109-**File:** `internal/tui/unicode_test.go` (419 lines)
110-
111-### Test Functions (6 total)
112-1. `TestUnicodeCharacterInventory` - Documents all characters (9 subtests)
113-2. `TestSpinnerFrameRendering` - Verifies spinner animation (8 subtests)
114-3. `TestUnicodeWidthConsistency` - Verifies width safety (9 subtests)
115-4. `TestInputModePromptIndicators` - Verifies prompt characters (4 subtests)
116-5. `TestStateIndicatorCharacters` - Verifies state indicators (4 subtests)
117-6. `TestBorderCharacters` - Documents border characters (3 subtests)
118-
119-### Test Statistics
120-- **Total Unicode test functions:** 6
121-- **Total Unicode subtests:** 37
122-- **All tests passing:** ✅ 37/37 (100%)
123-- **TUI coverage:** 85.1% (increased from 83.0%)
124-- **Coverage increase:** +2.1%
125-
126-### Example Test Output
127-```
128-=== RUN TestSpinnerFrameRendering
129-=== RUN TestSpinnerFrameRendering/frame_0
130- unicode_test.go:171: Frame 0: ⬡ (U+2B21) - width: 1
131-=== RUN TestSpinnerFrameRendering/frame_1
132- unicode_test.go:171: Frame 1: ⬢ (U+2B22) - width: 1
133-...
134-=== NAME TestSpinnerFrameRendering
135- unicode_test.go:180: Spinner FPS: 125ms (125ms per frame)
136---- PASS: TestSpinnerFrameRendering (0.00s)
137-```
138-
139-## Documentation Updates
140-
141-### Files Updated
142-1. **documentation/TUI_TESTING.md** - Added comprehensive Unicode testing section
143- - Character inventory reference
144- - Spinner animation verification
145- - Width consistency testing
146- - Terminal compatibility matrix
147- - Manual testing checklist
148- - Character replacement strategy
149- - Guidelines for adding new characters
150-
151-2. **documentation/UI_LAYOUT_REPORT.md** - Already contained character documentation
152- - Verified all characters are documented with codepoints
153- - Verified usage locations are accurate
154-
155-### New Test Guidelines
156-
157-#### Manual Testing Checklist
158-1. Test in primary terminal (Alacritty/Kitty/WezTerm)
159-2. Verify spinner animation (8 frames, no layout shift)
160-3. Verify state indicators (◦◌✖ align vertically)
161-4. Verify section decorations (⬥⬧⬡ render clearly)
162-5. Verify input prompts (⬧⬥⬡⚙ render correctly)
163-
164-#### Adding New Unicode Characters
165-1. Choose non-ambiguous width characters (use `runewidth`)
166-2. Update `TestUnicodeCharacterInventory` with usage
167-3. Verify width with `TestUnicodeWidthConsistency`
168-4. Update golden files: `go test ./internal/tui -update`
169-5. Test manually in multiple terminals
170-
171-## Character Replacement Strategy
172-
173-If a character renders poorly:
174-
175-1. **Check font first:** Install Nerd Font or Unicode font
176-2. **Test with go test:** Run `TestCharacterRenderingMatrix`
177-3. **Report compatibility:** Document in KNOWN_ISSUES.md
178-4. **Consider fallback:** ASCII-only mode (future enhancement)
179-
180-## Visual Reference Chart
181-
182-The `TestCharacterRenderingMatrix` test provides a visual reference:
183-
184-```
185-=== Unicode Character Rendering Reference ===
186-
187-State Indicators:
188- Running/Loading ⬡⬢⬦⬥ (animated)
189- Idle ◦ (U+25E6)
190- Stopped ◌ (U+25CC)
191- Errored ✖ (U+2716)
192-
193-Decorative Elements:
194- Diamond ⬥ (U+2B25)
195- Lozenge ⬧ (U+2B27)
196- Hexagon White ⬡ (U+2B21)
197- Hexagon Black ⬢ (U+2B22)
198- Diamond White ⬦ (U+2B26)
199-
200-Input Prompts:
201- Broadcast ⬧ (U+2B27)
202- Message ⬥ (U+2B25)
203- New Mysis ⬡ (U+2B21)
204- Config ⚙ (U+2699)
205-```
206-
207-## Key Findings
208-
209-### No Compatibility Issues Found
210-- ✅ All characters are non-ambiguous width
211-- ✅ All characters render with width=1
212-- ✅ Spinner animation verified correct (8 frames, 125ms/frame)
213-- ✅ No layout shift detected during animation
214-- ✅ Terminal compatibility good across major terminals
215-
216-### Safe Character Choices
217-All characters are from safe Unicode ranges:
218-- Box Drawing (U+2500-U+257F)
219-- Geometric Shapes (U+25A0-U+25FF)
220-- Miscellaneous Symbols (U+2600-U+26FF)
221-- Miscellaneous Symbols and Arrows (U+2B00-U+2BFF)
222-
223-**No East Asian Ambiguous Width characters used**
224-
225-## Recommendations
226-
227-### No Changes Needed
228-Current character choices are excellent:
229-- All characters render consistently across terminals
230-- No ambiguous width issues
231-- Hexagonal theme matches logo aesthetic
232-- State indicators are visually distinct
233-
234-### Future Enhancements (Optional)
235-1. **ASCII-only mode:** Config option for basic terminals
236-2. **Font detection:** Auto-detect terminal capabilities
237-3. **Fallback characters:** Graceful degradation for limited terminals
238-
239-### Documentation Maintenance
240-- Keep `TestUnicodeCharacterInventory` updated when adding characters
241-- Run `TestCharacterRenderingMatrix` before releases
242-- Document terminal compatibility issues in KNOWN_ISSUES.md
243-
244-## Build Verification
245-
246-✅ **Build successful:**
247-```bash
248-$ make build
249-go build -ldflags "-X main.Version=v0.0.1-2-g0cdad9f-dirty" -o bin/zoea ./cmd/zoea
250-```
251-
252-✅ **All tests passing:**
253-```bash
254-$ go test ./internal/tui -cover
255-ok github.com/xonecas/zoea-nova/internal/tui 2.185s coverage: 85.1% of statements
256-```
257-
258-✅ **All Unicode tests passing:**
259-```bash
260-$ go test ./internal/tui -run TestUnicode
261-PASS
262-ok github.com/xonecas/zoea-nova/internal/tui 0.003s
263-```
264-
265-## Conclusion
266-
267-**Phase 3 Status: ✅ COMPLETE**
268-
269-All Unicode characters have been thoroughly documented, tested, and verified to be safe across terminals. The spinner animation has been verified with all 8 frames rendering correctly at 125ms per frame. No compatibility issues were found.
270-
271-**Key Metrics:**
272-- ✅ 9 decorative characters documented
273-- ✅ 3 state indicators documented
274-- ✅ 4 input prompt indicators documented
275-- ✅ 8 spinner frames verified
276-- ✅ 37 new test cases added
277-- ✅ 85.1% TUI coverage achieved (+2.1%)
278-- ✅ 100% test pass rate
279-- ✅ Clean build with no warnings
280-- ✅ No ambiguous width characters detected
281-- ✅ Terminal compatibility excellent (7/8 terminals good or better)
282-
283-**No character replacements needed.** Current choices are optimal for the retro-futuristic aesthetic while maintaining broad terminal compatibility.
.opencode/skills/bubbletea/SKILL.md+277−0
@@ -0,0 +1,277 @@
1+---
2+name: bubbletea
3+description: Build terminal user interfaces with Go and Bubbletea framework. Use for creating TUI apps with the Elm architecture, dual-pane layouts, accordion modes, mouse/keyboard handling, Lipgloss styling, and reusable components. Includes production-ready templates, effects library, and battle-tested layout patterns from real projects.
4+license: MIT
5+---
6+
7+# Bubbletea TUI Development
8+
9+Production-ready skill for building beautiful terminal user interfaces with Go, Bubbletea, and Lipgloss.
10+
11+## When to Use This Skill
12+
13+Use this skill when:
14+- Creating new TUI applications with Go
15+- Adding Bubbletea components to existing apps
16+- Fixing layout/rendering issues (borders, alignment, overflow)
17+- Implementing mouse/keyboard interactions
18+- Building dual-pane or multi-panel layouts
19+- Adding visual effects (metaballs, waves, rainbow text)
20+- Troubleshooting TUI rendering problems
21+
22+## Core Principles
23+
24+**CRITICAL**: Before implementing ANY layout, consult `references/golden-rules.md` for the 4 Golden Rules. These rules prevent the most common and frustrating TUI layout bugs.
25+
26+### The 4 Golden Rules (Summary)
27+
28+1. **Always Account for Borders** - Subtract 2 from height calculations BEFORE rendering panels
29+2. **Never Auto-Wrap in Bordered Panels** - Always truncate text explicitly
30+3. **Match Mouse Detection to Layout** - Use X coords for horizontal, Y coords for vertical
31+4. **Use Weights, Not Pixels** - Proportional layouts scale perfectly
32+
33+Full details and examples in `references/golden-rules.md`.
34+
35+## Creating New Projects
36+
37+This project includes a production-ready template system. When this skill is bundled with a new project (via `new_project.sh`), use the existing template structure as the starting point.
38+
39+### Project Structure
40+
41+All new projects follow this architecture:
42+```
43+your-app/
44+├── main.go # Entry point (minimal, ~21 lines)
45+├── types.go # Type definitions, structs, enums
46+├── model.go # Model initialization & layout calculation
47+├── update.go # Message dispatcher
48+├── update_keyboard.go # Keyboard handling
49+├── update_mouse.go # Mouse handling
50+├── view.go # View rendering & layouts
51+├── styles.go # Lipgloss style definitions
52+├── config.go # Configuration management
53+└── .claude/skills/bubbletea/ # This skill (bundled)
54+```
55+
56+### Architecture Guidelines
57+
58+- Keep `main.go` minimal (entry point only, ~21 lines)
59+- All types in `types.go` (structs, enums, constants)
60+- Separate keyboard and mouse handling into dedicated files
61+- One file, one responsibility
62+- Maximum file size: 800 lines (ideally <500)
63+- Configuration via YAML with hot-reload support
64+
65+## Available Components
66+
67+See `references/components.md` for the complete catalog of reusable components:
68+
69+- **Panel System**: Single, dual-pane, multi-panel, tabbed layouts
70+- **Lists**: Simple list, filtered list, tree view
71+- **Input**: Text input, multiline, forms, autocomplete
72+- **Dialogs**: Confirm, input, progress, modal
73+- **Menus**: Context menu, command palette, menu bar
74+- **Status**: Status bar, title bar, breadcrumbs
75+- **Preview**: Text, markdown, syntax highlighting, images, hex
76+- **Tables**: Simple and interactive tables
77+
78+## Effects Library
79+
80+Beautiful physics-based animations available in the template:
81+
82+- 🔮 **Metaballs** - Lava lamp-style floating blobs
83+- 🌊 **Wave Effects** - Sine wave distortions
84+- 🌈 **Rainbow Cycling** - Animated color gradients
85+- 🎭 **Layer Compositor** - ANSI-aware multi-layer rendering
86+
87+See `references/effects.md` for usage examples and integration patterns.
88+
89+## Layout Implementation Pattern
90+
91+When implementing layouts, follow this sequence:
92+
93+### 1. Calculate Available Space
94+```go
95+func (m model) calculateLayout() (int, int) {
96+ contentWidth := m.width
97+ contentHeight := m.height
98+
99+ // Subtract UI elements
100+ if m.config.UI.ShowTitle {
101+ contentHeight -= 3 // title bar (3 lines)
102+ }
103+ if m.config.UI.ShowStatus {
104+ contentHeight -= 1 // status bar
105+ }
106+
107+ // CRITICAL: Account for panel borders
108+ contentHeight -= 2 // top + bottom borders
109+
110+ return contentWidth, contentHeight
111+}
112+```
113+
114+### 2. Use Weight-Based Panel Sizing
115+```go
116+// Calculate weights based on focus/accordion mode
117+leftWeight, rightWeight := 1, 1
118+if m.accordionMode && m.focusedPanel == "left" {
119+ leftWeight = 2 // Focused panel gets 2x weight
120+}
121+
122+// Calculate actual widths from weights
123+totalWeight := leftWeight + rightWeight
124+leftWidth := (availableWidth * leftWeight) / totalWeight
125+rightWidth := availableWidth - leftWidth
126+```
127+
128+### 3. Truncate Text to Prevent Wrapping
129+```go
130+// Calculate max text width to prevent wrapping
131+maxTextWidth := panelWidth - 4 // -2 borders, -2 padding
132+
133+// Truncate ALL text before rendering
134+title = truncateString(title, maxTextWidth)
135+subtitle = truncateString(subtitle, maxTextWidth)
136+
137+func truncateString(s string, maxLen int) string {
138+ if len(s) <= maxLen {
139+ return s
140+ }
141+ return s[:maxLen-1] + "…"
142+}
143+```
144+
145+## Mouse Interaction Pattern
146+
147+Always check layout mode before processing mouse events:
148+
149+```go
150+func (m model) handleLeftClick(msg tea.MouseMsg) (tea.Model, tea.Cmd) {
151+ if m.shouldUseVerticalStack() {
152+ // Vertical stack mode: use Y coordinates
153+ topHeight, _ := m.calculateVerticalStackLayout()
154+ relY := msg.Y - contentStartY
155+
156+ if relY < topHeight {
157+ m.focusedPanel = "left" // Top panel
158+ } else {
159+ m.focusedPanel = "right" // Bottom panel
160+ }
161+ } else {
162+ // Side-by-side mode: use X coordinates
163+ leftWidth, _ := m.calculateDualPaneLayout()
164+
165+ if msg.X < leftWidth {
166+ m.focusedPanel = "left"
167+ } else {
168+ m.focusedPanel = "right"
169+ }
170+ }
171+
172+ return m, nil
173+}
174+```
175+
176+## Common Pitfalls to Avoid
177+
178+See `references/troubleshooting.md` for detailed solutions to common issues:
179+
180+### ❌ DON'T: Set explicit Height() on bordered panels
181+```go
182+// BAD: Can cause misalignment
183+panelStyle := lipgloss.NewStyle().
184+ Border(border).
185+ Height(height) // Don't do this!
186+```
187+
188+### ✅ DO: Fill content to exact height
189+```go
190+// GOOD: Fill content lines to exact height
191+for len(lines) < innerHeight {
192+ lines = append(lines, "")
193+}
194+panelStyle := lipgloss.NewStyle().Border(border)
195+```
196+
197+## Testing and Debugging
198+
199+When panels don't align or render incorrectly:
200+
201+1. **Check height accounting** - Verify contentHeight calculation subtracts all UI elements + borders
202+2. **Check text wrapping** - Ensure all strings are truncated to maxTextWidth
203+3. **Check mouse detection** - Verify X/Y coordinate usage matches layout orientation
204+4. **Check border consistency** - Use same border style for all panels
205+
206+See `references/troubleshooting.md` for the complete debugging decision tree.
207+
208+## Configuration System
209+
210+All projects support YAML configuration with hot-reload:
211+
212+```yaml
213+theme: "dark"
214+keybindings: "default"
215+
216+layout:
217+ type: "dual_pane"
218+ split_ratio: 0.5
219+ accordion_mode: true
220+
221+ui:
222+ show_title: true
223+ show_status: true
224+ mouse_enabled: true
225+ show_icons: true
226+```
227+
228+Configuration files are loaded from:
229+1. `~/.config/your-app/config.yaml` (user config)
230+2. `./config.yaml` (local override)
231+
232+## Dependencies
233+
234+**Required:**
235+```
236+github.com/charmbracelet/bubbletea
237+github.com/charmbracelet/lipgloss
238+github.com/charmbracelet/bubbles
239+gopkg.in/yaml.v3
240+```
241+
242+**Optional** (uncomment in go.mod as needed):
243+```
244+github.com/charmbracelet/glamour # Markdown rendering
245+github.com/charmbracelet/huh # Forms
246+github.com/alecthomas/chroma/v2 # Syntax highlighting
247+github.com/evertras/bubble-table # Interactive tables
248+github.com/koki-develop/go-fzf # Fuzzy finder
249+```
250+
251+## Reference Documentation
252+
253+All reference files are loaded progressively as needed:
254+
255+- **golden-rules.md** - Critical layout patterns and anti-patterns
256+- **components.md** - Complete catalog of reusable components
257+- **troubleshooting.md** - Common issues and debugging decision tree
258+- **emoji-width-fix.md** - Battle-tested solution for emoji alignment across terminals (xterm, WezTerm, Termux, Windows Terminal)
259+
260+## External Resources
261+
262+- [Bubbletea Documentation](https://github.com/charmbracelet/bubbletea)
263+- [Lipgloss Documentation](https://github.com/charmbracelet/lipgloss)
264+- [Bubbles Components](https://github.com/charmbracelet/bubbles)
265+- [Charm Ecosystem](https://charm.sh/)
266+
267+## Best Practices Summary
268+
269+1. **Always** consult golden-rules.md before implementing layouts
270+2. **Always** use weight-based sizing for flexible layouts
271+3. **Always** truncate text explicitly (never rely on auto-wrap)
272+4. **Always** match mouse detection to layout orientation
273+5. **Always** account for borders in height calculations
274+6. **Never** set explicit Height() on bordered Lipgloss styles
275+7. **Never** assume layout orientation in mouse handlers
276+
277+Follow these patterns and you'll avoid 90% of TUI layout bugs.
.opencode/skills/bubbletea/references/components.md+647−0
@@ -0,0 +1,647 @@
1+# Bubbletea Components Catalog
2+
3+Reusable components for building TUI applications. All components follow the Elm architecture pattern (Init, Update, View).
4+
5+## Panel System
6+
7+Pre-built panel layouts for different UI arrangements.
8+
9+### Single Panel
10+
11+Full-screen single view with optional title and status bars.
12+
13+**Use for:**
14+- Simple focused interfaces
15+- Full-screen text editors
16+- Single-purpose tools
17+
18+**Implementation:**
19+```go
20+func (m model) renderSinglePanel() string {
21+ contentWidth, contentHeight := m.calculateLayout()
22+
23+ // Create panel with full available space
24+ panel := m.styles.Panel.
25+ Width(contentWidth).
26+ Render(content)
27+
28+ return panel
29+}
30+```
31+
32+### Dual Pane
33+
34+Side-by-side panels with configurable split ratio and accordion mode.
35+
36+**Use for:**
37+- File browsers with preview
38+- Split editors
39+- Source/destination views
40+
41+**Features:**
42+- Dynamic split ratio (50/50, 66/33, 75/25)
43+- Accordion mode (focused panel expands)
44+- Responsive (stacks vertically on narrow terminals)
45+- Weight-based sizing for smooth resizing
46+
47+**Implementation:**
48+```go
49+func (m model) renderDualPane() string {
50+ contentWidth, contentHeight := m.calculateLayout()
51+
52+ // Calculate weights based on focus/accordion
53+ leftWeight, rightWeight := 1, 1
54+ if m.accordionMode && m.focusedPanel == "left" {
55+ leftWeight = 2
56+ }
57+
58+ // Calculate actual widths from weights
59+ totalWeight := leftWeight + rightWeight
60+ leftWidth := (contentWidth * leftWeight) / totalWeight
61+ rightWidth := contentWidth - leftWidth
62+
63+ // Render panels
64+ leftPanel := m.renderPanel("left", leftWidth, contentHeight)
65+ rightPanel := m.renderPanel("right", rightWidth, contentHeight)
66+
67+ return lipgloss.JoinHorizontal(lipgloss.Top, leftPanel, rightPanel)
68+}
69+```
70+
71+**Keyboard shortcuts:**
72+- `Tab` - Switch focus between panels
73+- `a` - Toggle accordion mode
74+- Arrow keys - Focus panel in direction
75+
76+**Mouse support:**
77+- Click panel to focus
78+- Works in both horizontal and vertical stack modes
79+
80+### Multi-Panel
81+
82+3+ panels with configurable sizes and arrangements.
83+
84+**Use for:**
85+- IDEs (file tree, editor, terminal, output)
86+- Dashboard views
87+- Complex workflows
88+
89+**Common layouts:**
90+- Three-column (25/50/25)
91+- Three-row
92+- Grid (2x2, 3x3)
93+- Sidebar + main + inspector
94+
95+**Implementation:**
96+```go
97+// Three-column example
98+mainWeight, leftWeight, rightWeight := 2, 1, 1 // 50/25/25
99+totalWeight := mainWeight + leftWeight + rightWeight
100+
101+leftWidth := (contentWidth * leftWeight) / totalWeight
102+mainWidth := (contentWidth * mainWeight) / totalWeight
103+rightWidth := contentWidth - leftWidth - mainWidth
104+```
105+
106+### Tabbed
107+
108+Multiple views with tab switching.
109+
110+**Use for:**
111+- Multiple documents
112+- Settings pages
113+- Different data views
114+
115+**Features:**
116+- Tab bar with active indicator
117+- Keyboard shortcuts (`1-9`, `Ctrl+Tab`)
118+- Mouse click to switch tabs
119+- Close tab support
120+
121+## Lists
122+
123+### Simple List
124+
125+Basic scrollable list of items.
126+
127+**Use for:**
128+- File listings
129+- Menu options
130+- Search results
131+
132+**Features:**
133+- Keyboard navigation (Up/Down, Home/End, PgUp/PgDn)
134+- Mouse scrolling and selection
135+- Visual selection indicator
136+- Viewport scrolling (only visible items rendered)
137+
138+**Integration:**
139+```go
140+import "github.com/charmbracelet/bubbles/list"
141+
142+type model struct {
143+ list list.Model
144+}
145+
146+func (m model) Init() tea.Cmd {
147+ items := []list.Item{
148+ item{title: "Item 1", desc: "Description 1"},
149+ item{title: "Item 2", desc: "Description 2"},
150+ }
151+ m.list = list.New(items, list.NewDefaultDelegate(), 0, 0)
152+ return nil
153+}
154+```
155+
156+### Filtered List
157+
158+List with fuzzy search/filter.
159+
160+**Use for:**
161+- Quick file finder
162+- Command palette
163+- Searchable settings
164+
165+**Features:**
166+- Real-time filtering as you type
167+- Fuzzy matching
168+- Highlighted matches
169+
170+**Dependencies:**
171+```go
172+github.com/koki-develop/go-fzf
173+```
174+
175+### Tree View
176+
177+Hierarchical list with expand/collapse.
178+
179+**Use for:**
180+- Directory trees
181+- Nested data structures
182+- Outline views
183+
184+**Features:**
185+- Expand/collapse nodes
186+- Indentation levels
187+- Parent/child relationships
188+- Recursive rendering
189+
190+## Input Components
191+
192+### Text Input
193+
194+Single-line text field.
195+
196+**Use for:**
197+- Forms
198+- Search boxes
199+- Prompts
200+
201+**Integration:**
202+```go
203+import "github.com/charmbracelet/bubbles/textinput"
204+
205+type model struct {
206+ input textinput.Model
207+}
208+
209+func (m model) Init() tea.Cmd {
210+ m.input = textinput.New()
211+ m.input.Placeholder = "Enter text..."
212+ m.input.Focus()
213+ return textinput.Blink
214+}
215+```
216+
217+### Multiline Input
218+
219+Text area for longer content.
220+
221+**Use for:**
222+- Commit messages
223+- Notes
224+- Configuration editing
225+
226+**Integration:**
227+```go
228+import "github.com/charmbracelet/bubbles/textarea"
229+
230+type model struct {
231+ textarea textarea.Model
232+}
233+```
234+
235+### Forms
236+
237+Structured input with multiple fields.
238+
239+**Use for:**
240+- Settings dialogs
241+- User registration
242+- Multi-field input
243+
244+**Integration:**
245+```go
246+import "github.com/charmbracelet/huh"
247+
248+form := huh.NewForm(
249+ huh.NewGroup(
250+ huh.NewInput().
251+ Title("Name").
252+ Value(&name),
253+ huh.NewInput().
254+ Title("Email").
255+ Value(&email),
256+ ),
257+)
258+```
259+
260+### Autocomplete
261+
262+Text input with suggestions.
263+
264+**Use for:**
265+- Command entry
266+- File paths
267+- Tag selection
268+
269+**Features:**
270+- Real-time suggestions
271+- Keyboard navigation of suggestions
272+- Tab completion
273+
274+## Dialogs
275+
276+### Confirm Dialog
277+
278+Yes/No confirmation.
279+
280+**Use for:**
281+- Delete confirmations
282+- Save prompts
283+- Destructive actions
284+
285+**Example:**
286+```
287+┌─────────────────────────────┐
288+│ Delete this file? │
289+│ │
290+│ [Yes] [No] │
291+└─────────────────────────────┘
292+```
293+
294+### Input Dialog
295+
296+Prompt for single value.
297+
298+**Use for:**
299+- Quick input
300+- Rename operations
301+- New file creation
302+
303+### Progress Dialog
304+
305+Show long-running operations.
306+
307+**Use for:**
308+- File uploads
309+- Build processes
310+- Data processing
311+
312+**Integration:**
313+```go
314+import "github.com/charmbracelet/bubbles/progress"
315+
316+type model struct {
317+ progress progress.Model
318+}
319+```
320+
321+### Modal
322+
323+Full overlay dialog.
324+
325+**Use for:**
326+- Settings
327+- Help screens
328+- Complex forms
329+
330+## Menus
331+
332+### Context Menu
333+
334+Right-click or keyboard-triggered menu.
335+
336+**Use for:**
337+- File operations
338+- Quick actions
339+- Tool integration
340+
341+**Example:**
342+```
343+┌─────────────┐
344+│ Open │
345+│ Copy │
346+│ Delete │
347+│ Properties │
348+└─────────────┘
349+```
350+
351+### Command Palette
352+
353+Fuzzy searchable command list.
354+
355+**Use for:**
356+- Command discovery
357+- Keyboard-first workflows
358+- Power user features
359+
360+**Keyboard:**
361+- `Ctrl+P` or `Ctrl+Shift+P` to open
362+- Type to filter
363+- Enter to execute
364+
365+### Menu Bar
366+
367+Top-level menu system.
368+
369+**Use for:**
370+- Traditional application menus
371+- Organized commands
372+- Discoverability
373+
374+**Example:**
375+```
376+File Edit View Help
377+```
378+
379+## Status Components
380+
381+### Status Bar
382+
383+Bottom bar showing state and help.
384+
385+**Use for:**
386+- Current mode/state
387+- Keyboard hints
388+- File info
389+
390+**Example:**
391+```
392+┌────────────────────────────────────┐
393+│ │
394+│ Content area │
395+│ │
396+├────────────────────────────────────┤
397+│ Normal | file.txt | Line 10/100 │
398+└────────────────────────────────────┘
399+```
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/bubbletea/references/emoji-width-fix.md+295−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/bubbletea/references/golden-rules.md+393−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/bubbletea/references/troubleshooting.md+698−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/build-tui-view/SKILL.md+1968−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/SKILL.md+113−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/concurrency.md+328−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/error-handling.md+337−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/patterns.md+264−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/security.md+398−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/testing.md+357−0
Cut short: this commit's diff is over 1000 lines.
WORKFLOW.md+105−30
Cut short: this commit's diff is over 1000 lines.