872b0adb48
Split flat docs/ into user-docs/ (guides, config, troubleshooting) and dev/ (ADRs, architecture, extension guides, proposals). Updated docs/README.md index to reflect new paths.
25 lines
1.4 KiB
Markdown
25 lines
1.4 KiB
Markdown
# Key Rules & Gotchas
|
|
|
|
|
|
### Must-Follow Rules
|
|
|
|
1. **Use `StringEnum` for string enums** — `Type.Union`/`Type.Literal` breaks Google's API.
|
|
2. **Truncate tool output** — Large output causes context overflow, compaction failures, degraded performance.
|
|
3. **Use theme from callback** — Don't import theme directly. Use the `theme` parameter from `ctx.ui.custom()` or render functions.
|
|
4. **Type the DynamicBorder color param** — Write `(s: string) => theme.fg("accent", s)`.
|
|
5. **Call `tui.requestRender()` after state changes** in `handleInput`.
|
|
6. **Return `{ render, invalidate, handleInput }`** from custom components.
|
|
7. **Lines must not exceed `width`** in `render()` — use `truncateToWidth()`.
|
|
8. **Session control methods only in commands** — `waitForIdle()`, `newSession()`, `fork()`, `navigateTree()`, `reload()` will deadlock in event handlers.
|
|
9. **Strip leading `@` from path arguments** in custom tools — some models add it.
|
|
10. **Store state in tool result `details`** for proper branching support.
|
|
|
|
### Common Patterns
|
|
|
|
- **Rebuild on `invalidate()`** when your component pre-bakes theme colors
|
|
- **Check `signal?.aborted`** in long-running tool executions
|
|
- **Use `pi.exec()` instead of `child_process`** for shell commands
|
|
- **Overlay components are disposed when closed** — create fresh instances each time
|
|
- **Treat `ctx.reload()` as terminal** — code after it runs from the pre-reload version
|
|
|
|
---
|