lacy 1.8.11 → 1.8.13

package/README.md

@@ -1,61 +1,231 @@
-# lacy
+<p align="center">
+  <a href="https://lacy.sh">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/lacymorrow/lacy/HEAD/.github/assets/logo-horizontal-dark.svg">
+      <img src="https://raw.githubusercontent.com/lacymorrow/lacy/HEAD/.github/assets/logo-horizontal.svg" alt="Lacy" width="220">
+    </picture>
+  </a>
+</p>
 
-Interactive installer for [Lacy Shell](https://github.com/lacymorrow/lacy) — talk directly to your shell.
+<p align="center"><strong>Talk to your shell.</strong> Commands run. Questions go to AI. No prefixes. No context switching. You just type.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/lacy"><img alt="npm version" src="https://img.shields.io/npm/v/lacy?style=flat"></a>
+  <a href="https://www.npmjs.com/package/lacy"><img alt="npm downloads" src="https://img.shields.io/npm/dm/lacy?style=flat"></a>
+  <a href="https://github.com/lacymorrow/lacy/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/lacymorrow/lacy/ci.yml?style=flat&label=CI"></a>
+  <a href="https://github.com/lacymorrow/lacy/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/lacymorrow/lacy?style=flat"></a>
+  <a href="https://fsl.software"><img alt="License: FSL-1.1-MIT" src="https://img.shields.io/badge/License-FSL--1.1--MIT-blue?style=flat"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lacymorrow/lacy/HEAD/docs/demo-full.gif" alt="Lacy Shell demo — commands run in shell, questions go to AI" width="680" />
+</p>
+
+## Why Lacy?
+
+- **No new tools to learn** — Lacy works with your existing AI CLI (Claude Code, Gemini, OpenCode, Codex, Lash). It's a complement, not a replacement.
+- **Zero friction** — No slash commands, no hotkeys, no separate terminal. Type naturally and Lacy routes it. A real-time color indicator shows you what will happen before you press enter.
+- **Smart detection** — Lacy classifies input using word analysis, not AI. It's instant. Commands like `ls -la` stay green (shell). Questions like `what files are here` turn magenta (AI). If a command fails with natural language patterns, it silently reroutes to AI.
+
+> *Works with ZSH and Bash 4+ on macOS, Linux, and WSL.*
 
 ## Install
 
+> Supported installation methods: `npm`, `curl`, `homebrew`, `git`
+
+#### Install using `npx`
+
 ```bash
 npx lacy
 ```
 
-Features:
-- Arrow-key tool selection
-- Auto-detects installed AI CLI tools
-- Offers to install lash if selected
-- Automatic shell restart
+#### Install using `curl`
 
-## Uninstall
+```bash
+curl -fsSL https://lacy.sh/install | bash
+```
+
+<details>
+<summary>Other methods</summary>
 
 ```bash
-npx lacy --uninstall
+# Homebrew
+brew tap lacymorrow/tap
+brew install lacy
+
+# Manual
+git clone https://github.com/lacymorrow/lacy.git ~/.lacy
+echo 'source ~/.lacy/lacy.plugin.zsh' >> ~/.zshrc
 ```
 
-## Options
+</details>
 
+## How It Works
+
+Real-time visual feedback shows what will happen before you hit enter:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lacymorrow/lacy/HEAD/docs/demo-indicator.gif" alt="Green indicator for shell commands, magenta for AI" width="680" />
+</p>
+
+Commands execute in your shell. Natural language goes to your AI agent. No prefixes, no context switching — you just type.
+
+| Input                          | Routes to  | Why                                         |
+| ------------------------------ | ---------- | ------------------------------------------- |
+| `ls -la`                       | Shell      | Valid command                               |
+| `what files are here`          | AI         | Natural language                            |
+| `git status`                   | Shell      | Valid command                               |
+| `do we have a way to install?` | AI         | Reserved word — never a real command        |
+| `fix the bug`                  | AI         | Multi-word, not a command                   |
+| `kill the process on 3000`     | Shell → AI | Valid command, but fails — rerouted         |
+| `go ahead and fix it`          | Shell → AI | "go" is valid, but "ahead" triggers reroute |
+| `!rm -rf *`                    | Shell      | `!` prefix forces shell                     |
+
+The first word of your input is also syntax-highlighted in real-time: **green** for shell commands, **magenta** for AI queries.
+
+**Smart rerouting** (auto mode): When a valid command contains natural language patterns (3+ bare words with articles, pronouns, etc.) and fails, lacy shows a hint and automatically re-sends it to the AI agent. Shell reserved words like `do`, `then`, `in`, `else` are routed directly to the agent — they pass `command -v` but are never standalone commands.
+
+**Terminal context**: When you ask the AI a question, lacy automatically includes your current directory, git branch, recent commands, and exit codes, but only what changed since your last query. In supported terminals (tmux, screen, iTerm2, Terminal.app), it also captures the visible screen output so the agent can see error messages and stack traces.
+
+## Modes
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lacymorrow/lacy/HEAD/assets/mode-indicators.jpeg" alt="Shell and Agent mode indicators" width="480" />
+</p>
+
+| Mode      | Behavior                | Activate                     |
+| --------- | ----------------------- | ---------------------------- |
+| **Auto**  | Smart routing (default) | `mode auto`                  |
+| **Shell** | Everything to shell     | `mode shell` or `Ctrl+Space` |
+| **Agent** | Everything to AI        | `mode agent` or `Ctrl+Space` |
+
+## Supported Tools
+
+Lacy auto-detects your installed AI CLI. All tools handle their own auth — no API keys needed.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lacymorrow/lacy/HEAD/assets/supported-tools.jpeg" alt="Supported AI CLI tools" width="680" />
+</p>
+
+```bash
+tool set claude    # Use Claude Code
+tool set lash      # Use Lash
+tool set auto      # Auto-detect (first available)
 ```
-Usage:
-  npx lacy              Install Lacy Shell
-  npx lacy --uninstall  Uninstall Lacy Shell
 
-Options:
-  -h, --help       Show help message
-  -u, --uninstall  Uninstall Lacy Shell
+Or edit `~/.lacy/config.yaml`:
+
+```yaml
+agent_tools:
+  active: claude # lash, claude, opencode, gemini, codex, custom, or empty for auto
 ```
 
-## What is Lacy Shell?
+## Commands
+
+| Command                     | Description          |
+| --------------------------- | -------------------- |
+| `mode`                      | Show current mode    |
+| `mode [shell\|agent\|auto]` | Switch mode          |
+| `tool`                      | Show active AI tool  |
+| `tool set <name>`           | Set AI tool          |
+| `ask "query"`               | Direct query to AI   |
+| `Ctrl+Space`                | Toggle between modes |
 
-Lacy routes natural language to AI and commands to your shell — automatically.
+## CLI
 
+After installation, the `lacy` command is available (no Node required):
+
+```bash
+lacy setup        # Interactive settings (tool, mode, config)
+lacy status       # Show installation status
+lacy doctor       # Diagnose common issues
+lacy update       # Pull latest changes
+lacy config edit  # Open config in $EDITOR
+lacy uninstall    # Remove Lacy Shell
+lacy help         # Show all commands
 ```
-❯ ls -la                → runs in shell
-❯ what files are here   → AI answers
-❯ git status            → runs in shell
-❯ fix the build error   → AI answers
+
+## Uninstall
+
+```bash
+lacy uninstall
+# or
+npx lacy --uninstall
+# or
+curl -fsSL https://lacy.sh/install | bash -s -- --uninstall
 ```
 
-Works with: **lash**, **claude**, **opencode**, **gemini**, **codex**
+## Configuration
 
-## Alternative Install Methods
+Config file: `~/.lacy/config.yaml`
 
-```bash
-# curl
-curl -fsSL https://lacy.sh/install | bash
+```yaml
+agent_tools:
+  active: claude # lash, claude, opencode, gemini, codex, or empty for auto
 
-# Homebrew
-brew tap lacymorrow/tap
-brew install lacy
+modes:
+  default: auto # shell, agent, auto
+
+api_keys:
+  openai: "sk-..." # Only needed if no CLI tool installed
+  anthropic: "sk-ant-..."
+```
+
+## Troubleshooting
+
+**No AI response** — Check `tool` to see if a tool is detected. Install one: `npm i -g lashcode` or `brew install claude`.
+
+**Colors not showing** — Ensure your terminal supports 256 colors (green=34, magenta=200, blue=75).
+
+**Command rerouted unexpectedly** — In auto mode, commands with natural language patterns that fail are re-sent to the AI. Switch to `mode shell` to disable this, or prefix with `!`.
+
+**Emergency bypass** — Prefix any command with `!` to force shell execution: `!rm -rf node_modules`
+
+## Releasing
+
+Requires [Bun](https://bun.sh), [gh](https://cli.github.com), and `npm login`.
+
+```bash
+bun run release          # interactive — prompts for patch/minor/major
+bun run release patch    # patch bump  (1.5.3 → 1.5.4)
+bun run release minor    # minor bump  (1.5.3 → 1.6.0)
+bun run release major    # major bump  (1.5.3 → 2.0.0)
+bun run release 2.0.0    # explicit version
 ```
 
+The script handles the full release flow:
+
+1. Bumps version in both `package.json` files
+2. Commits with `release: v<version>` and tags
+3. Pushes to GitHub and creates a GitHub release
+4. Publishes the npm package (prompts for OTP if required)
+
+## Support This Project
+
+Lacy Shell is free and open source. If it saves you time, consider sponsoring the project:
+
+[![Sponsor](https://img.shields.io/badge/Sponsor-❤-ea4aaa?style=for-the-badge&logo=github)](https://github.com/sponsors/lacymorrow)
+
+Your support keeps development active and helps cover infrastructure costs.
+
+## Contributors Welcome
+
+Lacy is open source and contributions are welcome! Whether you're fixing a typo, adding a feature, or improving docs, we'd love your help.
+
+- **[Good First Issues](https://github.com/lacymorrow/lacy/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)** -- great starting points for new contributors
+- **[Contributing Guide](CONTRIBUTING.md)** -- dev setup, code style, and PR process
+- **[Discussions](https://github.com/lacymorrow/lacy/discussions)** -- questions, ideas, and general chat
+
+## Star History
+
+<a href="https://star-history.com/#lacymorrow/lacy&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=lacymorrow/lacy&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=lacymorrow/lacy&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=lacymorrow/lacy&type=Date" />
+ </picture>
+</a>
+
 ## License
 
-MIT
+[FSL-1.1-MIT](LICENSE) — Functional Source License v1.1 with MIT Future License (converts to MIT after 2 years). See [fsl.software](https://fsl.software) for the full text.

package/RELEASING.md

@@ -0,0 +1,148 @@
+# Releasing Lacy Shell
+
+Step-by-step process for publishing a new version across all distribution channels.
+
+## Prerequisites
+
+Before you start, verify:
+
+```bash
+npm whoami          # Must be logged in as lacymorrow
+gh auth status      # Must be authenticated with repo + workflow scopes
+```
+
+You need push access to:
+- `lacymorrow/lacy` (main repo)
+- `lacymorrow/homebrew-tap` (Homebrew formula)
+- `lacymorrow/lacy-sh` (website — only if updating)
+
+Have your npm 2FA authenticator ready — you'll need a one-time password for `npm publish`.
+
+## Copy-Paste Release Script
+
+Set your version and run each block in order. The entire process takes under 2 minutes.
+
+```bash
+# ── Set version ──────────────────────────────────────────────
+VERSION="1.4.0"  # ← Change this
+```
+
+### 1. Bump versions
+
+Both `package.json` files must stay in sync:
+
+```bash
+npm version $VERSION --no-git-tag-version
+cd packages/lacy && npm version $VERSION --no-git-tag-version && cd ../..
+```
+
+Then update `CHANGELOG.md` — add a section at the top:
+
+```markdown
+## [x.y.z] - YYYY-MM-DD
+
+### Added
+- ...
+
+### Fixed
+- ...
+```
+
+### 2. Commit and push
+
+```bash
+git add package.json packages/lacy/package.json packages/lacy/package-lock.json CHANGELOG.md
+git commit -m "release: v$VERSION"
+git push origin main
+```
+
+### 3. Create GitHub release
+
+This creates the git tag. Homebrew depends on it.
+
+```bash
+gh release create "v$VERSION" \
+  --title "v$VERSION" \
+  --notes "See CHANGELOG.md for details." \
+  --target main
+```
+
+### 4. Publish to npm
+
+```bash
+cd packages/lacy
+npm publish --otp=YOUR_OTP_CODE
+cd ../..
+```
+
+Verify: `npm view lacy version` → should print the new version.
+
+### 5. Update Homebrew tap
+
+Get the SHA of the release tarball, then update the formula:
+
+```bash
+# Get SHA
+SHA=$(curl -sL "https://github.com/lacymorrow/lacy/archive/refs/tags/v$VERSION.tar.gz" | shasum -a 256 | cut -d' ' -f1)
+echo "SHA: $SHA"
+
+# Clone/update tap
+gh repo clone lacymorrow/homebrew-tap /tmp/homebrew-tap 2>/dev/null || git -C /tmp/homebrew-tap pull
+
+# Update formula (url + sha256)
+sed -i '' "s|url \".*\"|url \"https://github.com/lacymorrow/lacy/archive/refs/tags/v$VERSION.tar.gz\"|" /tmp/homebrew-tap/Formula/lacy.rb
+sed -i '' "s|sha256 \".*\"|sha256 \"$SHA\"|" /tmp/homebrew-tap/Formula/lacy.rb
+
+# Push (pull first to avoid rejected pushes from remote changes)
+cd /tmp/homebrew-tap
+git pull --rebase origin main
+git add Formula/lacy.rb
+git commit -m "lacy: update to v$VERSION"
+git push origin main
+cd -
+```
+
+### 6. Update the website (if needed)
+
+Only required when install instructions, features, or docs change. The site auto-deploys on push.
+
+```bash
+gh repo clone lacymorrow/lacy-sh /tmp/lacy-sh 2>/dev/null || git -C /tmp/lacy-sh pull
+# Make changes, then:
+cd /tmp/lacy-sh && git add . && git commit -m "update for v$VERSION" && git push origin main && cd -
+```
+
+### 7. Verify
+
+```bash
+gh release view "v$VERSION"                    # GitHub release exists
+npm view lacy version                       # npm shows new version
+brew update && brew info lacymorrow/tap/lacy   # Homebrew shows new version
+```
+
+## Quick Reference
+
+```
+bump versions → commit & push → gh release → npm publish → update homebrew tap → verify
+```
+
+## Channels
+
+| Channel | What gets updated | Trigger |
+|---------|-------------------|---------|
+| GitHub | Release + tag | `gh release create` |
+| npm | `lacy` package | `npm publish` in `packages/lacy` |
+| Homebrew | `lacymorrow/tap/lacy` formula | Push to `homebrew-tap` repo |
+| curl install | `install.sh` | Pulls from git main (automatic) |
+| Website | lacy.sh | Push to `lacy-sh` repo (Vercel auto-deploy) |
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `npm publish` OTP expired | TOTP codes last ~30s. Get a fresh code and retry. |
+| `npm publish` permission denied | Run `npm whoami` — must be `lacymorrow`. |
+| Homebrew still shows old version | Run `brew update` to fetch the new tap index. |
+| GitHub release tarball 404 | Wait a few seconds after `gh release create` for the tarball to generate. |
+| SHA mismatch after Homebrew update | Re-fetch: `curl -sL "...tar.gz" \| shasum -a 256` and update formula. |
+| Version mismatch between package.json files | Both root and `packages/lacy/package.json` must match. |

package/STYLE.md

@@ -0,0 +1,202 @@
+# lacymorrow Style Guide
+
+Style reference for all open-source repositories under [github.com/lacymorrow](https://github.com/lacymorrow). Pass this document to anyone working on a repo, README, website, or social asset.
+
+---
+
+## Voice
+
+**Short, direct, declarative.** Write like a man page, not a blog post. Lead with what it does, not what it is. No exclamation marks. No "easily" or "simply" or "just works." No emoji unless the project literally involves emoji.
+
+- Good: "Talk to your shell."
+- Bad: "An amazing AI-powered shell plugin that lets you easily interact with your terminal using natural language!"
+
+One-liner descriptions follow the pattern: **verb + object + differentiator.**
+
+```
+Talk to your shell.                          (lacy)
+AI coding agent for the terminal.            (lash)
+Graceful degradation for missing images.     (crosshatch)
+```
+
+## README Structure
+
+Every repo README follows the same skeleton. Omit sections that don't apply, but keep the order.
+
+```
+# Project Name                    ← plain name, no tagline in the heading
+                                  ← one-sentence description
+                                  ← hero image (if available)
+
+## Install                        ← primary method first, others in <details>
+## How It Works / Usage           ← the meat — images, tables, code
+## API / Commands / Options       ← reference material
+## Configuration                  ← if applicable
+## Uninstall                      ← if applicable (CLI tools)
+## Troubleshooting                ← inline, not a separate doc
+## License                        ← one line
+```
+
+### Rules
+
+- **No badges.** No build status, npm version, download count, or coverage badges. They add noise and age poorly.
+- **No "Table of Contents" section.** GitHub generates one. Don't duplicate it.
+- **No "Contributing" section in the README.** Use CONTRIBUTING.md if needed.
+- **No "Acknowledgements" or "Credits" sections.** Use package.json or a separate file.
+- **Images over colored text.** GitHub markdown can't render colored text. Use generated images (dark background, monospaced font, accent colors) for anything that needs color.
+- **`<details>` for secondary content.** Alternative install methods, full API reference, verbose config examples — collapse them.
+- **Tables for structured data.** Commands, options, comparisons. Left-aligned, no unnecessary columns.
+- **One install command above the fold.** The most common method, in a bash code block, before anything else. No prose before the install block.
+
+### Image Guidelines
+
+When generating images for READMEs (via Gemini, Midjourney, or any tool):
+
+- **Background:** `#09090b` (near-black, matches GitHub dark mode)
+- **Text:** Monospaced, white (`#fafafa`) for primary, gray (`#a1a1aa`) for secondary
+- **Accent colors:** Use the palette below — small, precise doses only
+- **No window chrome.** No title bars, no traffic light dots, no drop shadows
+- **No rounded corners** on containers or cards
+- **Width:** Generate at 2x resolution, display at `width="680"` max in markdown
+- **Centered:** Wrap in `<p align="center"><img ... /></p>`
+
+## Color Palette
+
+Six grays and four accents. Use these exact values everywhere.
+
+### Grays (Zinc scale)
+
+| Token | Hex | Use |
+|-------|-----|-----|
+| black | `#09090b` | Page/card backgrounds |
+| surface | `#111113` | Raised surfaces, code blocks |
+| raised | `#19191d` | Active states |
+| line | `#27272a` | Borders, dividers |
+| line-dim | `#1c1c1f` | Subtle dividers |
+| fg | `#fafafa` | Primary text |
+| fg-2 | `#a1a1aa` | Secondary text, descriptions |
+| fg-3 | `#52525b` | Tertiary text, labels, muted |
+| fg-4 | `#3f3f46` | Metadata, prompts |
+
+### Accents
+
+| Token | Hex | Use |
+|-------|-----|-----|
+| green | `#4ade80` | Success, shell, active |
+| magenta | `#d946ef` | Agent, AI, attention |
+| violet | `#a78bfa` | Brand accent, links, highlights |
+| blue | `#60a5fa` | Info, auto mode |
+
+**Rules:**
+- Colors appear at full saturation in small doses — dots, bars, single words. Never as backgrounds.
+- Background tinting uses 8% opacity max: `rgba(74,222,128,0.08)`
+- No gradients. No glows. No shadows with color.
+
+## Typography
+
+### Websites
+
+| Role | Font | Weight |
+|------|------|--------|
+| Display headings | Instrument Serif | 400 regular, 400 italic |
+| Everything else | DM Mono | 300, 400, 500 |
+
+```
+https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=DM+Mono:wght@300;400;500&display=swap
+```
+
+- Mono is the default voice. Serif is rare — headings and CTAs only.
+- No sans-serif anywhere.
+- Body text: 13–14px. Headings: let the size do the work, never bold (weight 400).
+- The italic serif word in a heading carries the violet accent color.
+
+### READMEs and Markdown
+
+GitHub renders markdown in its own fonts, so typography control is limited. Compensate with structure:
+
+- Use `##` headings, not `###` or deeper. Two levels of hierarchy is enough.
+- Use code blocks (`bash`, `yaml`, etc.) aggressively. They're the closest thing to the mono aesthetic.
+- Use tables instead of bullet lists when data has structure.
+- Bold (`**text**`) sparingly — for the first mention of a key term, not for emphasis.
+
+## Website Layout
+
+- Max width: **680px**. Narrow, document-like.
+- Padding: **24px** horizontal.
+- Left-aligned by default. Only closing CTAs are centered.
+- Sections separated by `1px solid #1c1c1f` horizontal rules.
+- Section padding: **80px** vertical.
+- No border-radius on structural elements. Sharp corners everywhere.
+- Single responsive breakpoint at **640px**.
+
+## Components
+
+### Install block
+
+Tabbed interface (curl / brew / npx / git). Flat border, `#111113` background. Tabs separated by 1px borders, not floating pills. Active tab: `#19191d` background. Code uses syntax coloring: commands in `#a1a1aa`, URLs in `#a78bfa`, flags in `#52525b`.
+
+### Indicator bars
+
+The defining visual motif across all properties. 3px wide, 14–20px tall, 1px border-radius. Color maps to function (green=shell, magenta=agent, violet=brand). They appear in navs, demo lines, and mode cells.
+
+### Data rows
+
+Simple grid with colored dot, name, description, and optional note. Separated by `#1c1c1f` bottom borders. No hover effects.
+
+### Section labels
+
+11px, uppercase, 0.12em letter-spacing, `#52525b` color. Every section starts with one. Examples: "install", "how it works", "supported tools".
+
+## GitHub Repository Settings
+
+### Topics
+
+Use lowercase, hyphenated terms. Lead with what users search for, not implementation details.
+
+```
+ai ai-agent ai-terminal cli developer-tools terminal open-source
+```
+
+Add project-specific topics after the common ones. Don't list languages or frameworks as topics unless the project is specifically about that language.
+
+### Description
+
+Same one-liner from the README. No period at the end. No emoji.
+
+### Social Preview
+
+If creating a social preview image (1280x640):
+
+- Background: `#09090b`
+- Project name in Instrument Serif italic, large, centered
+- One-line description in DM Mono below, `#a1a1aa`
+- Violet (`#a78bfa`) accent on a keyword or indicator bar
+- No logos, no avatars, no screenshots
+
+## Anti-Patterns
+
+Do not use any of the following in websites, READMEs, or assets:
+
+- Gradient text or gradient backgrounds
+- Rounded pill shapes (buttons, badges, tabs)
+- Card hover effects (scale, glow, border color change)
+- Ambient/radial background blobs
+- Fake terminal windows with macOS traffic light dots
+- Icon grids with colored icon backgrounds
+- "Get started" / "Learn more" pill buttons
+- Badge rows at the top of READMEs (build passing, npm version, etc.)
+- Sans-serif fonts on websites
+- Centered section headers with centered subtext
+- Decorative SVG icons
+- Any element wider than 680px on websites
+- Emoji in headings or descriptions
+- Exclamation marks in copy
+
+## Applying to a New Repo
+
+1. Write the one-liner description
+2. Structure the README using the skeleton above
+3. Generate images if the project has visual concepts (use the image guidelines)
+4. Set GitHub topics and description
+5. If the project has a website, use the typography + color palette + layout rules from this document
+6. Reference `STYLE.md` in any contributor-facing docs