falleco/dotfiles/lavish

Lavish Editor

Lavish Editor helps agents turn rich HTML artifacts into collaborative human review surfaces. Whenever you are about to give user a complex response that will be easier to understand via a rich / interactive page, consider using Lavish Editor. First generate an interactive HTML artifact according to user request, then run npx -y lavish-axi <html-file> so the user can visually review it, annotate elements or selected text, queue prompts, and send feedback back through npx -y lavish-axi poll.

You do not need lavish-axi installed globally - invoke it with npx -y lavish-axi <html-file>. If lavish-axi output shows a follow-up command starting with lavish-axi, run it as npx -y lavish-axi ... instead. In restricted subprocess sandboxes, CI, or agent harnesses where npx -y exits opaquely (for example with status 216), use an already-installed copy directly: node "$(npm root)/lavish-axi/dist/cli.mjs" <html-file> for a local install, node "$(npm root -g)/lavish-axi/dist/cli.mjs" <html-file> for a global install, or the bare lavish-axi <html-file> bin after installing once.

Request

$ARGUMENTS

If the request above is non-empty, the user invoked /lavish explicitly - build an HTML artifact for that request now, following the workflow below. If it is empty, infer what to visualize from the conversation.

When to use

Use lavish-axi when the user asks for a visual artifact, HTML explainer, interactive prototype, review surface, product or technical plan, comparison, report, or browser-based feedback loop

Workflow

1. Create the HTML artifact (default location .lavish/<name>.html in the working directory).
2. Run npx -y lavish-axi <html-file> to open or resume a review session in the browser.

If the output carries a self_paint_warning, fix the unpainted page surface and save before polling - Lavish live-reloads the artifact.

1. Run npx -y lavish-axi poll <html-file> to long-poll for the user's annotations and queued prompts.

On the first poll, prefer --agent-reply "<one-line summary of what you built and what to review first>" so the conversation panel opens with context. Browser-detected layout issues are filed passively in the user's Layout issues inbox and arrive as an ordinary layout-warnings prompt only when the user selects and queues them. Never edit an issue the user has not queued. The only response that arrives without user action is artifact_failures, when the review surface itself is unusable. The poll stays silent until the user acts or a fatal artifact failure makes the review surface unusable - leave it running, never kill it. Cosmetic, intentional, transient, tiny, and uncertain observations remain silent. Keep the poll in the foreground by default and let it return the feedback directly to the agent. A background poll is allowed only through a harness-native tracked background-job facility whose completion result is guaranteed to resume or notify the same agent. Never use nohup, shell &, disown, redirected fire-and-forget processes, or a detached terminal without an explicit verified callback merely to keep polling alive. If the harness has no completion-aware background facility, use the foreground poll or first wire a verified wake callback into the surrounding supervisor. Do not tell the user the artifact is being monitored until that wake path is live. If the poll gets killed or times out anyway, just re-run it - queued feedback is never lost.

1. If poll returns feedback, apply the user's prompts. A layout-warnings prompt is an explicit repair request; apply every listed fix in one pass before saving, and let Lavish re-check it after a newer artifact load.
2. Apply human feedback, then poll again with --agent-reply "<message>" to reply in the browser and keep the loop going under the same foreground-or-verified-wake-path rule.
3. Run npx -y lavish-axi end <html-file> when the review is finished.
4. Send & End ends the session. Its final feedback is still delivered once. After that response, polling stops, and the agent must not reopen the session uninvited. Deliver any remaining updates directly in this conversation.

Visual guidance

• Use visual hierarchy to make the most important decisions, risks, tradeoffs, and next actions obvious at a glance
• Use visual structure such as sections, cards, tables, diagrams, annotated snippets, and side-by-side comparisons instead of long prose
• Choose typography, spacing, color, and layout deliberately so the artifact has a clear point of view
• Prevent horizontal overflow at every nesting level: nested grid/flex children also need minmax(0, 1fr) tracks and min-width: 0, especially when badges, labels, or status text use wide pixel or monospace fonts; wrap, truncate, or contain long unbreakable text deliberately
• When the artifact would describe existing or current UI or state, show it instead: capture screenshots of the real pages (run the app read-only if needed) and embed them, rather than explaining the current look in prose; reserve prose for what cannot be shown such as rationale, trade-offs, and open questions

Playbooks

Run npx -y lavish-axi playbook <id> for focused, detailed guidance on any of these. One artifact often combines several playbooks (for example a plan that includes a comparison and a diagram), so MUST open each matching playbook before writing HTML. For flows, architecture, state, or sequence diagrams, do not hand-build boxes-and-arrows from div/flexbox; open the diagram playbook and use the theme-aware Mermaid snippet from npx -y lavish-axi design unless SVG is needed for richly annotated nodes.

• diagram - Map relationships, flows, state, and architecture
• table - Turn dense records into scan-friendly review surfaces
• comparison - Show options, tradeoffs, and current vs target behavior
• plan - Explain a product or technical plan before implementation
• code - Render source code, code files, patches, PR diffs, and before/after code inside Lavish artifacts
• input - Must be used when the agent needs to collect user input on decisions, choices, preferences, triage, scope, or other structured feedback from within the artifact
• slides - Create a deliberate presentation when slides are requested

Commands & rules