leglas 0.2.0 → 0.4.0

package/README.md

@@ -14,6 +14,12 @@
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/leglas" alt="license"></a>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/rail-single.jpg" width="900" alt="The Leglas interface: a rail of three design directions on the left, and the selected one running as the real app filling the rest of the window" />
+</p>
+
+<p align="center"><i>Every direction in the rail, the selected one running as your actual app. Arrow keys flip between them.</i></p>
+
 Code is becoming the source of truth. Features go from prompt to
 working code in minutes, and mockups/design files eventually lag behind the product and drift out of sync. The
 fastest teams already design in the medium they ship. Leglas is built
@@ -39,6 +45,12 @@ and sessions that clean up after themselves.
 
 ## What you can do with Leglas
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/compare-artboards.jpg" width="900" alt="The Leglas interface: a rail of three design directions on the left, and two of them running side by side as the real app, each labelled with its name." />
+</p>
+
+<p align="center"><i>Two directions for the same page, running side by side as the actual app.</i></p>
+
 - Pick any two variations for side-by-side comparison when it gets hard to choose.
 - Name each direction, drag to reorder and organise your variants, set aside the ones that
   don't feel right. Your actions on every idea survive a long exploration.
@@ -51,12 +63,23 @@ and sessions that clean up after themselves.
   the spread, your agent supplies the taste.
 - Ask for changes without leaving the comparison: describe what you
   want on the direction you're looking at, and Leglas turns it into a
-  precise request for your agent, file path included. Leave
-  `leglas watch --run "claude -p {prompt}"` running in another terminal
-  and your agent picks each request up as you send it. In Claude Code,
-  the Leglas MCP server can also push each request straight into your
-  open session as a channel event (channels are a research preview:
-  start Claude Code with `--dangerously-load-development-channels
+  precise request for your agent, file path included. The composer
+  carries its own agent picker, the way every chat you already use
+  carries a model picker: the CLIs found on your machine (Claude Code,
+  Codex, Cursor) are one click away next to the send button, each asked
+  for its login status so a signed-out CLI says so before a run instead
+  of failing one. Not on that list? Type the command that runs your
+  agent once, in the same menu, and Leglas hands it each request; or
+  connect an agent Leglas can't spawn (an IDE panel, an MCP host) with
+  the copy-paste MCP wiring behind "Connect another agent". Each run
+  reports in a card above the field: who is working, what file they
+  are touching, how long it has been, a stop button while it runs and
+  retry when it fails. Your agent, your subscription, no keys.
+  Prefer a terminal? `npx leglas watch` is the same loop with the
+  agent's own output scrolling by. In Claude Code, the Leglas MCP
+  server can also push each request straight into your open session as
+  a channel event (channels are a research preview: start Claude Code
+  with `--dangerously-load-development-channels
   server:<your leglas server name>`).
 - Keep the winner with one command. Leglas moves it into your source
   tree and clears the exploration away.
@@ -76,66 +99,110 @@ preview of your app root. Add a config file to compare more than one thing.
 
 It works with whatever you're building in. Leglas never imports or
 executes your framework, so the target can be Next, Vite, Remix,
-SvelteKit, Astro, or a folder of static files. Requires Node 24 or
-newer.
+SvelteKit, Astro, or a folder of static files.
+
+## Install
+
+There is nothing you have to install: `npx leglas` fetches the CLI on
+first use and starts from npm's cache after that, and every instruction
+Leglas writes for agents uses the same form, so a fresh clone works
+with no setup at all. Requires Node 24 or newer.
+
+Two optional upgrades:
+
+- `npm install -D leglas` pins the version in a project. Teammates and
+  CI get the same Leglas from their normal install, and `npx` resolves
+  the local copy from then on.
+- `npm install -g leglas` is for typing `leglas` without the prefix.
 
 ## Working with coding agents
 
-Run `leglas init` once. It writes a section into your project's
-`AGENTS.md`, creates a starter config, and gitignores Leglas's working
-directory. That section travels with the repo, so Claude Code, Cursor,
-Codex, or whatever you switch to next opens the project already knowing
-how to add design directions to it. Every command accepts `--json` and
-prints a single machine-readable envelope, so agents drive the same CLI
-you do.
+The fastest way in is the agent skill:
+
+```sh
+npx skills add FredAmartey/leglas
+```
+
+One install, and your agent recognises "give me a few directions for the
+pricing page" as a Leglas exploration in any project, including ones
+that have never seen Leglas. It sets the project up itself and gets to
+work.
+
+In a project, run `npx leglas init` once. It writes a section into your
+project's `AGENTS.md`, creates a starter config, and gitignores Leglas's
+working directory. That section travels with the repo, so Claude Code,
+Cursor, Codex, or whatever you switch to next opens the project already
+knowing how to add design directions to it. Every command accepts
+`--json` and prints a single machine-readable envelope, so agents drive
+the same CLI you do.
 
 The instructions center on one rule: add beside what exists, never
 rewrite it. Two directions that rewrite the same file cannot render from
 one server, and asking an agent to "make the hero calmer" tempts it to
 edit the hero. The supporting commands:
 
-- `leglas explore hero --count 6` briefs the exploration: what the set
+- `npx leglas explore hero --count 6` briefs the exploration: what the set
   is for, why it only works if the six genuinely disagree, and how each
   direction registers. Unbriefed, six requests come back as six variants
   of one idea. With `--based-on "Aurora"` the goal flips: six deliberate
   variants of a direction you already like, and drifting into a new
   direction is the failure. The designs themselves are the agent's;
   Leglas prescribes none.
-- `leglas new hero --from src/Hero.tsx` scaffolds a switcher under
+- `npx leglas new hero --from src/Hero.tsx` scaffolds a switcher under
   `.leglas/variants/hero/`. With `--from`, the baseline re-exports your
   real component, so you never compare against a stale copy. Leglas
   prints the one line to add in your component and does not edit it,
   because rewriting a file it does not understand is how a tool breaks a
   codebase. Scaffolded branch points return the fallback in production
   builds, so a committed one cannot expose an unreleased direction.
-- `leglas classify --change package.json --rewrite src/theme.css` answers
+- `npx leglas classify --change package.json --rewrite src/theme.css` answers
   where a direction should live before it is written. Changing
   dependencies, build configuration, or an existing file's behaviour
   cannot be additive, so those directions build on their own git branch
   and register with `leglas add --branch`. Everything else stays in-app,
   where switching is instant.
-- `leglas show "Aurora" --json` answers for one direction: its entry, the
+- `npx leglas show "Aurora" --json` answers for one direction: its entry, the
   source file behind it, the variants based on it, what it is being compared
   against, and anything still pending on it. Copying a direction from the
   rail hands over a block that ends in this command, so an agent given the
   block can go and get the rest.
-- `leglas keep "Aurora" --to src/components/hero.tsx` moves the winner
+- `npx leglas keep "Aurora" --to src/components/hero.tsx` moves the winner
   into real source and ends the exploration.
 
 Asking for a change works from the interface too. Type what you want
 changed into the field under the rail (or press `R`) and Leglas composes a
 prompt naming the direction and the file behind it, copies it to your
 clipboard, and queues it. The direction it means is the one highlighted
-directly above the field. Your agent drains the queue with `leglas requests --json` and clears
+directly above the field. Your agent drains the queue with `npx leglas requests --json` and clears
 it with `--clear`. Leglas runs no model of its own; your agent already
 knows your conventions and your taste.
 
+The line under the field is the whole status: whether anything is
+listening, what you have queued, and when it has been picked up.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/field-idle.png" width="290" alt="The change field reading: Enter queues it for npx leglas requests" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/field-queued.png" width="290" alt="The change field reading: one change queued for your agent" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/field-pickedup.png" width="290" alt="The change field reading: Your agent is on it" />
+</p>
+
+<p align="center"><i>Nothing waiting, then a request queued, then an agent that has taken it.</i></p>
+
+Pick an agent once and the same line shows it working: which file it is
+editing, a cancel if you change your mind, a retry when a run goes
+wrong. `npx leglas watch` in another terminal is the same loop with the
+agent's own output in view, and it needs no flag once an agent has been
+picked in the interface.
+
 ### MCP server
 
 For agent hosts that cannot run shell commands, `leglas-mcp` exposes the
 same operations as MCP tools over stdio: `start`, `add`, `list`, `show`,
 `classify`, `explore`, `scaffold`, `keep`, `requests`, and `init`. Each
 tool calls exactly what the CLI calls and returns the same envelope.
+`watch` is the one command with no tool behind it: it is a loop that
+holds a terminal open, and on a host that speaks channels the server
+already pushes each request into the session as it arrives.
 
 ```sh
 claude mcp add leglas -- npx -y leglas-mcp
@@ -147,9 +214,34 @@ Or in `.mcp.json`:
 { "mcpServers": { "leglas": { "command": "npx", "args": ["-y", "leglas-mcp"] } } }
 ```
 
-The host's working directory names the project. The `start` tool boots
-the viewer and returns its URL, and anything it started stops when the
-session ends.
+The host's working directory names the project, the same contract as the
+CLI. A host that starts the server somewhere else is asked where the
+project is, over MCP roots. The `start` tool boots the viewer and returns
+its URL, and anything it started stops when the session ends.
+
+### As an Agent Plugin
+
+The repository is also an [Agent Plugin](https://agent-plugins.org), the
+open standard for shipping Agent Skills and MCP server configuration in
+one format. Clients that implement it install the skill and the server
+together, instead of the two steps above. It is a layout rather than a
+build: `plugin.json` and `mcp.json` at the root, the skill in
+`skills/leglas/`, nothing generated.
+
+An Agent Plugins client starts a plugin's server in the plugin's own
+install directory rather than the project, so on that path the working
+directory names a copy of Leglas and nothing else. The server therefore
+takes the project from the workspace the host declares over MCP roots,
+and the working directory only when it sits inside one. If a host offers
+neither, `LEGLAS_PROJECT_DIR` names the project outright; without it the
+tools report that there is no project rather than writing into a plugin
+cache. `mcp.json` passes `${PLUGIN_ROOT}` for exactly that check, and
+nothing else.
+
+The plugin's version covers the skill and the configuration, not the
+server it launches: `npx` fetches the current `leglas-mcp` the same way
+every `npx leglas` in these instructions fetches the current CLI, which
+keeps both faces of Leglas on one version in a project they share.
 
 ## Configuration
 
@@ -203,6 +295,15 @@ what you want for the last two directions in contention: press `C`, or
 hover a direction and press its compare button, and it becomes the right
 pane while the active direction holds the left.
 
+A split does not hand each side half the room. An app given half the room
+crosses its own breakpoints and draws a different design, so you would be
+choosing between two narrow renderings of directions meant for the wide
+one. Instead each side is drawn at the width it had on its own and scaled
+to fit, keeping the same proportions, so nothing reflows and flipping and
+splitting agree about what the design is. Each pane says the width it is
+drawn at and the scale it is shown at. If you want the narrow rendering,
+that is what the tools popover's "Scale each side to fit" switch is for.
+
 Arrows move between directions, `1` to `9` jump straight to one, `R` asks
 for a change to the one you are on, `Cmd K` (`Ctrl K` elsewhere) searches
 and `B` collapses the rail. Press `?` for the whole keymap.