Quilltap 4.5.1

Quilltap 4.5.1 Release Notes

Two small corrections of manners, both having to do with introductions imperfectly performed.

A Word to the Portraitist

Consider, if you will, the awkwardness of an evening party at which the host names every guest in the room aloud — "Ariadne, by the fire; Catherine, at the window; and Lady Catherine, just arriving from the carriage" — but then, having summoned the household portraitist to capture the scene in oils, takes the trouble to describe only those guests whose invitations he himself sent. The painter, holding his brushes and looking on, knows nothing of the others save their names. He paints them anyway. He paints them as he imagines them. He is rarely correct.

That, in a sentence, was the state of the Lantern's story-background prompt before this release. The cheap LLM that drafts the scene-setting instruction would dutifully arrange characters in the tableau by name — "Ariadne sits reading by the lamp, Amy nearby listening" — and then, in the enumeration that follows, would furnish a careful Name: <appearance> description only for the chat's current participants. Characters introduced by way of the chat title, or by the derived scene context, or by SceneState's record of who had recently acted, were summoned by name and then abandoned to the image provider's imagination. The image provider, ever obliging, imagined them. The user, opening the chat to find Lady Catherine wearing what was emphatically not her own face, was understandably perplexed.

The fix is a post-processing pass in the story-background handler that loads the workspace's characters, scans the final prompt for every named character who appears in the scene without a corresponding enumeration entry, and quietly appends one — built from the character's pronouns and primary physical description, just as the participants' own entries are built. Participants reuse their already-resolved enumeration (with equipped wardrobe in place); non-participants fall back to their canonical defaults. Longer names are processed before shorter ones, so that "Catherine" cannot displace "Lady Catherine" by alphabetical accident. Failures, should the workspace lookup fail, are logged at warn and the prompt proceeds unaltered; successful additions are logged at info with the list of names supplied.

The portraitist now arrives with a complete cast list. The likenesses, accordingly, are likenesses.

A Word to the Maître d'

The second correction is a smaller matter of dining-room etiquette. The shell-completion templates — the polite little scripts that, when sourced, allow quilltap d<TAB> to propose db docs and similar courtesies — had fallen somewhat behind the kitchen. The bash, zsh, and fish templates each knew about the verbs in residence at the time they were written, but the logs and migrations namespaces, which arrived later in 4.5, were never added to the menu. Nor were the instances default and instances rename verbs. Nor the global --passphrase flag. The bash template's per-subcommand flag lists, in particular, had drifted out of sympathy with what the parsers in db-commands.js, docs-commands.js, and memories-commands.js actually accepted.

All three templates have been rewritten to enumerate the full surface — every verb, every documented flag, value-list completion for --source (AUTO/MANUAL), --stream (combined/error/stdout/stderr/startup), --field (request/response/both), --sort, --type. Bash now also performs a second-level dispatch on sub-verbs (so themes registry <TAB> properly offers add/remove/refresh/keygen/sign), and the instance-targeting verbs (show, remove, rename, default, set-passphrase) now tab-complete against the registered instance names themselves. Bash was smoke-tested with nine scenarios covering the new verbs and flag-value completions; zsh was syntax-checked with zsh -n.

If you have already saved a completion script to your shell's fpath or sourced it from your .bashrc, you will want to regenerate it:

quilltap completion bash > ~/.bash_completion.d/quilltap   # or wherever yours lives
quilltap completion zsh  > ~/.zsh/completions/_quilltap
quilltap completion fish > ~/.config/fish/completions/quilltap.fish

(For zsh, rm -f ~/.zcompdump* afterwards if the cache feels stale.) Once regenerated, the menu and the kitchen are once more in agreement.

---

What Changed

• fix (Lantern): The story-background prompt now appends a Name: <appearance> enumeration entry for every character named in the scene but not in the chat's participant roster — characters introduced via the chat title, the derived scene context, or SceneState character actions. Participants reuse their already-resolved enumeration (with equipped wardrobe) via a characterId → description map; non-participants fall back to defaults built from their pronouns and primary physicalDescription. Longer names are processed first to prevent collisions like "Catherine" displacing "Lady Catherine". Implementation in lib/background-jobs/handlers/story-background.ts. Failures are caught and logged at warn; additions are logged at info with the list of names added.
• fix (Foundry): Shell completion templates for bash, zsh, and fish (packages/quilltap/lib/completion/{bash,zsh,fish}.template) were missing the logs and migrations top-level subcommands, the instances default and instances rename verbs, and the global --passphrase flag. The bash template's per-subcommand flag lists were also stale relative to the actual parsers. Rewrote all three templates to enumerate the full current surface, with value-list completions on --source, --stream, --field, --sort, --type, and two-level dispatch on sub-verbs in bash. Instance-targeting verbs now tab-complete against registered instance names. Users who already saved a completion script need to regenerate it.

---

Installation

Desktop App

Download from the quilltap-shell releases page:

macOS:

1. Download the .dmg file and open it
2. Drag Quilltap to your Applications folder
3. Launch Quilltap from Applications

Windows:

1. Download and run the .exe installer
2. If SmartScreen warns about an unknown publisher, click "More info" → "Run anyway"
3. Launch Quilltap from the Start Menu or desktop shortcut

Linux:

1. Download the .AppImage file, make it executable (chmod +x), and run it
2. Or install the .deb package: sudo dpkg -i quilltap_*.deb

Node.js (any platform)

npx quilltap

Or install globally:

npm install -g quilltap
quilltap

Open http://localhost:3000 in your browser. Requires Node.js 24+. First run downloads ~150–250 MB and caches locally.

Docker

docker pull foundry9/quilltap:4.5.1

Or use the startup scripts:

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/foundry-9/quilltap-server/refs/heads/main/scripts/start-quilltap.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/foundry-9/quilltap-server/refs/heads/main/scripts/start-quilltap.ps1 | iex

---

A small release. The portraitist now knows whom he is painting; the maître d' has a current menu in hand. Neither correction will be noticed by anyone for whom the previous arrangement happened to work — which is, in its own quiet way, the mark of a patch release behaving as one ought.

— Ariadne, who has been on the receiving end of more than one invented likeness, May 21, 2026

Installation

Desktop App (recommended)

The Quilltap desktop app (Electron) is available from
quilltap-shell 4.1.1.
Download the release for your platform (macOS, Windows, or Linux).

The quilltap-linux-arm64.tar.gz and quilltap-linux-amd64.tar.gz rootfs
tarballs attached to this release are used by the shell's Lima (macOS) and WSL2 (Windows) VM modes.

Node.js (any platform)

npm install -g quilltap
quilltap

On first run, the CLI downloads the application files (~150-250 MB)
and caches them locally. Subsequent launches start instantly.

Docker

docker pull foundry9/quilltap:4.5.1

See the README for setup instructions.