Skip to content

Commit 737f355

Browse files
cpcloudclaude
cpcloud
and
claude
authored
docs(blog): add help-text post for 2026-03-19 (#790)
## Summary - Add weekly blog post covering Kong-to-Cobra CLI migration, extraction ops JSON tree overlay, re-extraction improvements, Charm v2 migration, and demo subcommand - Record VHS tape and embed ops tree video in the post - Add `--buildFuture` to Hugo dev server and pagefind build so future-dated posts are always previewable locally --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 66c7922 commit 737f355

4 files changed

Lines changed: 246 additions & 2 deletions

File tree

‎docs/content/blog/help-text.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
+++
2+
title = "Your --help was the ugliest screen in the app"
3+
date = 2026-03-19
4+
description = "micasa swapped Kong for Cobra. Now there's tab completion, colored help, and CLI tests that run in 100ms."
5+
+++
6+
7+
Kong parsed my arguments for four months. It worked fine. It also didn't
8+
generate shell completions, so micasa had none. And `--help` was plain
9+
monochrome text next to a TUI with a color palette -- the one screen that
10+
looked like it belonged to a different application.
11+
12+
## Kong out, Cobra in
13+
14+
[#785](https://github.com/cpcloud/micasa/pull/785) replaces Kong with Cobra.
15+
The main reason was completions -- Kong doesn't generate them, so micasa
16+
never had tab completion. Cobra builds them from the command tree at runtime.
17+
`micasa completion bash` writes a script to stdout, same for zsh and fish.
18+
Add a subcommand next week, the completions already know about it.
19+
20+
While I was in there, I overrode Cobra's help function to use the Wong
21+
palette. Subcommands in one color, flags in another, descriptions in the
22+
adaptive foreground. `--help` looks like the rest of the app now.
23+
24+
Side benefit: Kong's CLI tests compiled the full binary and exec'd it in
25+
a subprocess, which took about ten seconds per run. Cobra commands are
26+
functions -- construct the root, set args, call `Execute()` against an
27+
`io.Writer`. CLI tests went from ~10s to ~100ms.
28+
29+
## The LLM shows its work
30+
31+
The extraction pipeline proposes database operations -- create a vendor,
32+
update a title, link a quote -- but you couldn't see the details. You got
33+
a summary and an accept/reject choice.
34+
35+
Documents now have an **Ops** column
36+
([#776](https://github.com/cpcloud/micasa/pull/776)). It opens an
37+
interactive JSON tree: every proposed `INSERT`, `UPDATE`, and `DELETE` with
38+
field values inline. <kbd>j</kbd>/<kbd>k</kbd> to navigate,
39+
<kbd>l</kbd> to expand, <kbd>h</kbd> to collapse. Collapsed nodes show
40+
inline previews. Clickable too.
41+
42+
<video src="/videos/ops-tree.webm" class="demo-video" autoplay loop muted playsinline></video>
43+
44+
You can point at the exact field the LLM got wrong before you accept.
45+
46+
## Faster the second time
47+
48+
Re-extracting a document used to redo the full pipeline -- OCR, text
49+
extraction, everything. Now it skips straight to the LLM with the cached
50+
text from the first run
51+
([#763](https://github.com/cpcloud/micasa/pull/763)).
52+
53+
Same PR: <kbd>r</kbd> in edit mode triggers extraction without opening a
54+
form. A **Model** column shows which LLM produced the extraction. The model
55+
name and operations JSON are persisted in the database -- if you need to
56+
know what model read your invoice six months from now, it's there.
57+
58+
## Other things since last week
59+
60+
- **Charm v2** -- bubbletea, lipgloss, huh, bubblezone, and glamour all
61+
migrated to their v2 releases. Go 1.26 required. The `bubbletea-overlay`
62+
dependency got inlined. Nothing should look different, but if something
63+
does, [open an issue](https://github.com/cpcloud/micasa/issues)
64+
([#788](https://github.com/cpcloud/micasa/pull/788)).
65+
- **`micasa demo`** -- `--demo` is now a subcommand. `micasa demo --years 10`
66+
instead of `micasa --demo --years 10`
67+
([#787](https://github.com/cpcloud/micasa/pull/787)).
68+
- **Keybinding hints** -- two-tier keycap rendering: pill keycaps for inline
69+
hints, bold accent for reference panels like the help overlay
70+
([#783](https://github.com/cpcloud/micasa/pull/783)).
71+
- **Document restore** -- accepting an extraction on a soft-deleted document
72+
now restores it instead of silently writing to a hidden row
73+
([#777](https://github.com/cpcloud/micasa/pull/777)).
74+
- **Hide-deleted** -- soft-deleting a row now respects your explicit
75+
hide-deleted toggle instead of overriding it
76+
([#774](https://github.com/cpcloud/micasa/pull/774)).
77+
- **Sort** -- toggling sort didn't visually activate until you pressed a
78+
navigation key; the cached viewport wasn't being invalidated
79+
([#773](https://github.com/cpcloud/micasa/pull/773)).
80+
- **Service log sync** -- closing the service log overlay auto-syncs and
81+
highlights the Last column so you see the update immediately
82+
([#772](https://github.com/cpcloud/micasa/pull/772)).
83+
- **Error rendering** -- failed extraction step errors render as plain text
84+
instead of raw JSON
85+
([#778](https://github.com/cpcloud/micasa/pull/778)).
86+
87+
## Try it
88+
89+
```sh
90+
go run github.com/cpcloud/micasa/cmd/micasa@latest demo
91+
```
92+
93+
Tab completions:
94+
95+
```sh
96+
source <(micasa completion bash)
97+
source <(micasa completion zsh)
98+
micasa completion fish | source
99+
```
100+
101+
Binaries on the
102+
[releases page](https://github.com/cpcloud/micasa/releases/latest).

‎docs/static/videos/ops-tree.webm‎

458 KB
Binary file not shown.

‎docs/tapes/ops-tree.tape‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
Require micasa
2+
3+
Output docs/static/videos/ops-tree.webm
4+
5+
Set Shell bash
6+
Set FontFamily "Hack Nerd Font"
7+
Set FontSize 32
8+
Set Width 2400
9+
Set Height 1200
10+
Set Padding 20
11+
Set Theme "Dracula"
12+
Set CursorBlink false
13+
Set TypingSpeed 0
14+
15+
Env NO_COLOR ""
16+
Env TERM "xterm-256color"
17+
Env COLORTERM "truecolor"
18+
Env COLORFGBG "15;0"
19+
Env PS1 ""
20+
21+
Hide
22+
Type "exec micasa demo"
23+
Enter
24+
Sleep 5s
25+
# Dismiss dashboard.
26+
Type "D"
27+
Sleep 1s
28+
# Navigate to Documents tab (6 f presses).
29+
Type "f"
30+
Sleep 0.3s
31+
Type "f"
32+
Sleep 0.3s
33+
Type "f"
34+
Sleep 0.3s
35+
Type "f"
36+
Sleep 0.3s
37+
Type "f"
38+
Sleep 0.3s
39+
Type "f"
40+
Sleep 1s
41+
# Navigate to Ops column (6 l presses from ID).
42+
Type "l"
43+
Sleep 0.2s
44+
Type "l"
45+
Sleep 0.2s
46+
Type "l"
47+
Sleep 0.2s
48+
Type "l"
49+
Sleep 0.2s
50+
Type "l"
51+
Sleep 0.2s
52+
Type "l"
53+
Sleep 1s
54+
Show
55+
56+
Sleep 0.5s
57+
58+
# Open ops tree overlay on the Invoice row.
59+
Enter
60+
Sleep 1.5s
61+
62+
# Navigate down through the tree, expanding as we go.
63+
# Expand first operation.
64+
Type "l"
65+
Sleep 0.8s
66+
# Move into action, table, then data.
67+
Type "j"
68+
Sleep 0.4s
69+
Type "j"
70+
Sleep 0.4s
71+
Type "j"
72+
Sleep 0.4s
73+
# Expand data node.
74+
Type "l"
75+
Sleep 0.8s
76+
# Browse the vendor fields.
77+
Type "j"
78+
Sleep 0.4s
79+
Type "j"
80+
Sleep 0.4s
81+
Type "j"
82+
Sleep 0.4s
83+
84+
Sleep 1s
85+
86+
# Move to second operation.
87+
Type "j"
88+
Sleep 0.4s
89+
# Expand it.
90+
Type "l"
91+
Sleep 0.8s
92+
Type "j"
93+
Sleep 0.4s
94+
Type "j"
95+
Sleep 0.4s
96+
Type "j"
97+
Sleep 0.4s
98+
# Expand data.
99+
Type "l"
100+
Sleep 0.8s
101+
Type "j"
102+
Sleep 0.4s
103+
Type "j"
104+
Sleep 0.4s
105+
106+
Sleep 1s
107+
108+
# Move to third operation and expand.
109+
Type "j"
110+
Sleep 0.4s
111+
Type "l"
112+
Sleep 0.8s
113+
Type "j"
114+
Sleep 0.4s
115+
Type "j"
116+
Sleep 0.4s
117+
Type "j"
118+
Sleep 0.4s
119+
Type "l"
120+
Sleep 0.8s
121+
122+
Sleep 1.5s
123+
124+
# Collapse everything back up -- jump to top and collapse root.
125+
Type "g"
126+
Sleep 0.5s
127+
Type "h"
128+
Sleep 1s
129+
130+
# Re-expand to show the toggle.
131+
Type "l"
132+
Sleep 1s
133+
134+
Sleep 1.5s
135+
136+
# Close overlay.
137+
Escape
138+
Sleep 1s
139+
140+
Hide
141+
Ctrl+Q
142+
Sleep 1s

‎flake.nix‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -471,15 +471,15 @@
471471
# Build once to generate the pagefind index, then copy it
472472
# into docs/static/ so hugo server serves it as a static asset.
473473
_tmpsite=$(mktemp -d)
474-
hugo --source docs --destination "$_tmpsite" --minify --quiet
474+
hugo --source docs --destination "$_tmpsite" --buildDrafts --buildFuture --minify --quiet
475475
pagefind --site "$_tmpsite" --quiet
476476
rm -rf docs/static/pagefind
477477
cp -r "$_tmpsite/pagefind" docs/static/pagefind
478478
rm -rf "$_tmpsite"
479479
480480
_port=$((RANDOM % 10000 + 30000))
481481
printf 'http://localhost:%s\n' "$_port"
482-
exec hugo server --source docs --buildDrafts --disableFastRender --noHTTPCache --port "$_port" --bind 0.0.0.0 &>/dev/null
482+
exec hugo server --source docs --buildDrafts --buildFuture --disableFastRender --noHTTPCache --port "$_port" --bind 0.0.0.0 &>/dev/null
483483
'';
484484
};
485485
# Records any VHS tape to WebM

0 commit comments

Comments
 (0)
⚡