skills.rest
Lingtai-AI
Lingtai-AIOFFICIAL
Explore all skills by this author →
GitHub

dev-guide-gotchas

Documents known implementation pitfalls and fixes for LingTai TUI and kernel development.

692|60|Updated Mar 15, 2026
Search Tags:#Golang#gotchas#tui#Debugging#bubble tea#editable install#pythonpath
One-click install
npx skills add https://github.com/Lingtai-AI/lingtai --skill dev-guide-gotchas
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: dev-guide-gotchas
Source: https://github.com/Lingtai-AI/lingtai/tree/main/tui/internal/preset/skills/lingtai-dev-guide/reference/gotchas
Command: npx skills add https://github.com/Lingtai-AI/lingtai --skill dev-guide-gotchas

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Developers working on the LingTai TUI and kernel repeatedly hit the same non-obvious bugs — silent paste failures in Bubble Tea v2, editable installs clobbered by the auto-upgrader, PYTHONPATH pollution shadowing the runtime import — and waste hours rediscovering fixes that were already diagnosed once.

Core Features & Use Cases

  • Bubble Tea v2 input pitfalls: Explains why tea.PasteMsg must be forwarded through every dispatcher layer and why textarea should replace textinput for paste-friendly fields.
  • Runtime environment traps: Covers auto-upgrader clobbering editable installs, stale editable checkouts after merges, and PYTHONPATH pollution surviving agent refreshes, with detection and recovery commands.
  • Project conventions: Documents the three-locale i18n rule, binary naming (lingtai-tui vs lingtai), preset directory ownership, authorization gates, and retired migration contracts.
  • Use Case: A developer finds pasting into a TUI input silently does nothing; this reference traces the cause to a missing tea.PasteMsg forward in the host model's outer switch and gives the fix pattern.

Quick Start

Ask the agent to look up the gotchas reference for the symptom you are hitting, such as paste not working in a TUI input or the runtime importing the wrong lingtai source.

Frequently Asked Questions about dev-guide-gotchas

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does paste not work in a Bubble Tea v2 text input?▼

Bubble Tea v2 delivers clipboard pastes as tea.PasteMsg, separate from tea.KeyPressMsg. If any dispatcher layer in the chain from tea.Program to the focused widget handles only key messages, the paste is silently dropped. Forward tea.PasteMsg at every level.

Should I use textarea or textinput for paste-friendly fields?▼

Use textarea for any field that receives pasted content like API keys or base URLs, since textinput drops characters on multi-byte or clipboard pastes. Configure it single-line with SetHeight(1), no newline insertion, and themed styles.

Why did my editable install get replaced by a PyPI wheel?▼

The TUI auto-upgrader compares the local lingtai version against PyPI and replaces the editable install if the local version is lower. Keep the kernel pyproject.toml version at or above PyPI's latest, and reinstall editable with uv pip install -e to recover.

How do I detect PYTHONPATH pollution in a running agent?▼

Inspect the live process environment with ps eww -p <pid> and grep for PYTHONPATH, then verify the import path with env -u PYTHONPATH <venv>/bin/python -c 'import lingtai; print(lingtai.__file__)'. A plain refresh re-inherits pollution, so relaunch from a clean environment.

Do I still need to bump migration versions for TUI and portal together?▼

No. Project migrations via meta.json are retired; neither production binary reads or gates on it. The only live migration surface is the TUI's per-machine registry under ~/.lingtai-tui/, which runs at TUI startup with no portal counterpart.

Related Skills

Explore More Software Engineering Skills→
Lingtai-AILingtai-AI
621

tutorial-guide

Guide learners through a 12-lesson tutorial on Lingtai with live exploration.

Official
Advanced
imclabimclab
1

bug-report

Create structured bug reports with reproduction steps and severity.

Official
Intermediate
BrownbullBrownbull

gabe-help

Scan Gabe Suite environments and recommend next commands without executing changes.

Community
Intermediate
rigercrigerc
2

bubbles-v2

Generate, explain, and debug Bubble Tea component code with Charm's Bubbles v2 library for Go.

Community
Intermediate