leglas 0.9.0 → 1.0.0

package/README.md

@@ -44,7 +44,7 @@ Your app doesn't change to make any of this work. Leglas proxies the same
 dev server in your project: one config file to delete when you're done
 and sessions that clean up after themselves.
 
-## What you can do with Leglas
+## What it does
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/compare-artboards.jpg" width="900" alt="The Leglas interface: the rail on the left, and two directions running side by side as the real app, each labelled with its name and the width it is drawn at." />
@@ -52,66 +52,30 @@ and sessions that clean up after themselves.
 
 <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.
-- Send a teammate the link to a direction. They open the live version instead of a screenshot and a paragraph of explanation.
-- Compare things no design tool can hold: 3 git branches, a local
-  build against production, yesterday's direction against today's, or even 7 different worktrees.
-- `leglas init` teaches any coding agent the workflow, and
-  `leglas explore` briefs an exploration. Five directions can be five
-  separate ideas, or five variants of the one you already like: you choose
-  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. 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. Leglas checks
-  your shell path and the conventional per-user install locations, then asks
-  each CLI for its login status so a signed-out agent says so before a run
-  instead of failing one. Claude Code and Codex can optionally override effort
-  for this project, remembered separately for each agent; `Agent default`
-  leaves the CLI's own setting untouched. To
-  work from an IDE panel or chat host, choose
-  "Connect agent via MCP" for the exact setup and a live confirmation
-  once the agent uses a Leglas tool. 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. Claude
-  Code, Codex and Cursor pick the conversation back up between
-  requests, so a run after the first goes straight to the change
-  instead of reading the project again. Claude Code and Codex warm up
-  while you type and let their process go once you have left Leglas
-  alone for a few minutes, so an open window is not holding one.
-  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>`).
-- A change makes a variant, not a rewrite. Ask for something on the
-  direction you are looking at and the result registers under it in the
-  rail, with the original still there to compare against. A chip beside
-  the send button switches to changing the direction itself, for when a
-  change really is a fix. Hover any direction to see what it was built
-  from and the change that was asked for, in the words that were typed.
-- Your agent sees what you see. Every change you send carries a screenshot
-  of the direction at the width you are looking at, a crop of whatever you
-  pointed at with a note, the other pane when you are comparing, and any
-  image you pasted into the composer as a reference. Leglas renders them
-  with a Chrome, Chromium, Brave or Edge already on your machine, nothing
-  to install; with none found, the request says so and goes anyway. Agents
-  can look for themselves too: `npx leglas show "Aurora" --screenshot`
-  writes a PNG of a direction (`--width 390` for the phone layout) and the
-  MCP `show` tool returns the image. The instructions Leglas writes for
-  agents ask for one look after each change, so a broken layout gets fixed
-  before you see it.
-- Keep the winner with one command. Leglas moves it into your source
-  tree and clears the exploration away.
-- No app yet or want plain HTML comparisons? Some people want exactly that, and it works fine. Same comparison, no dev server.
-
-## Quick start
+- Put any two directions side by side when it gets hard to choose.
+- Name each direction, drag to reorder, set aside the ones that don't feel
+  right. Your opinion of every idea survives a long exploration.
+- Share the rail with someone who has no repo: a client, a cofounder, a
+  teammate on another machine. They get the real app, in your order, and
+  cannot change anything. See [Sharing](#sharing).
+- Compare things no design tool can hold: three git branches, a local build
+  against production, yesterday's direction against today's.
+- Hand the workflow to your coding agent. `leglas init` teaches it, and
+  `leglas explore` briefs an exploration: five separate ideas, or five
+  variants of the one you already like. You choose the spread; your agent
+  supplies the taste.
+- Ask for changes without leaving the comparison. Describe what you want on
+  the direction you are looking at, or point at it, and Leglas turns that
+  into a precise request for your agent, file path and screenshots
+  included. The agents on your machine are one click away next to the send
+  button. Your agent, your subscription, no keys.
+- A change makes a variant, not a rewrite. The result registers under the
+  direction it came from, with the original still there to compare against.
+- Keep the winner with one command. Leglas moves it into your source tree,
+  writes down what the exploration decided and clears the rest away.
+- No app yet? Plain HTML files compare the same way, no dev server needed.
+
+## Get started
 
 Start your dev server, then run Leglas from the project directory:
 
@@ -119,194 +83,162 @@ Start your dev server, then run Leglas from the project directory:
 npx leglas
 ```
 
-Leglas starts on port 4100, proxies your app, and opens
+Leglas starts on port 4100, proxies your app and opens
 `http://localhost:4100/leglas`. With no configuration you get a single
-preview of your app root. Add a config file to compare more than one thing.
-If that port turns out to be served from outside your project, Leglas
-says so and points at `devServer` and `--user-port` rather than quietly
-proxying the wrong app.
+preview of your app root; a config file, described under
+[Configuration](#configuration), is how you get more than one thing to
+compare.
+If that port turns out to be served from outside your project, Leglas says
+so and points at `devServer` and `--user-port` rather than quietly proxying
+the wrong app.
+
+It works with whatever you are 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. It needs Node 24 or newer, and nothing
+else: `npx` fetches the CLI on first use and starts from the cache after
+that. To pin a version for a project, `npm install -D leglas`; to type
+`leglas` without the prefix, `npm install -g leglas`.
+
+## Using Leglas
+
+### The rail and the stage
+
+Directions live in a rail on the left. The stage shows the active one in a
+framed viewport at Full, 1440, 834 or 390 wide. Rename, reorder, hide and
+tag directions from the rail; open the removed list to restore one, delete
+it for good or clear the list. Your layout is saved per project and
+survives restarts.
 
-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.
+A small tools widget floats over the stage and can be dragged to any
+corner. Its popover holds the viewport presets and a few preferences,
+including hiding the dev badge your framework paints over the corner of
+the app when it lands on the part you are judging.
 
-## Install
+### Comparing
 
-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.
+Flipping shows a difference over time. A split shows it at once, which is
+what you want for the last two 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.
+
+Each side is drawn at the width it had on its own and scaled to fit, so
+nothing reflows and flipping and splitting agree about what the design is.
+An app given half the room would cross its own breakpoints and draw a
+different design. If the narrow rendering is what you want, the tools
+popover's "Scale each side to fit" switch is for that.
+
+### Asking for a change
+
+Type what you want into the field under the rail, or press `R`, and Leglas
+composes a request 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. By default the request asks for a
+new variant beside that direction; the chip next to the send button
+switches it to a change in place, for when a change really is a fix.
+
+Pick an agent once from the picker beside the send button and the card
+above the field shows it working: which file it is editing, how long it
+has been, a stop if you change your mind, a retry when a run goes wrong.
+Every request carries a screenshot of the direction at the width you are
+looking at, a crop of anything you pointed at, the other pane when you are
+comparing and any image you pasted in as a reference. Leglas runs no model
+of its own; your agent already knows your conventions and your taste.
 
-Two optional upgrades:
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-idle.png" width="290" alt="The change field, empty, with its agent picker reading Choose an agent" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-queued.png" width="290" alt="A card above the change field reading: Change queued, pick who runs your changes" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-pickedup.png" width="290" alt="A card above the change field reading: Codex is on it, editing .leglas/variants/hero/poster.tsx, 56s, with a stop button" />
+</p>
 
-- `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.
+<p align="center"><i>Nothing waiting, then a request queued, then an agent that has taken it.</i></p>
 
-## Working with coding agents
+Hover any direction to see what it was built from and the change that was
+asked for, in the words that were typed.
 
-The fastest way in is the agent skill:
+### Pointing at the problem
 
-```sh
-npx skills add FredAmartey/leglas
-```
+Most of what you would type is the part describing where the problem is,
+so point at it instead. Press `A` and the preview becomes a picker:
+hovering outlines the element under the pointer, clicking drops a numbered
+pin that takes a note, and dragging marks an area and names every element
+inside it. Click a pin again to reread it, reword it or drop it. The page
+still scrolls, so the thing three screens down is as easy to mark as the
+headline.
 
-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.
+Annotations are a request on their own, so the field can stay empty: leave
+three and send once. Each carries the element's own words, its tag and
+classes, a path and the box it filled, and tells your agent which of those
+to trust first, because the design moves under them by design. A pin whose
+element has since gone turns amber rather than pointing confidently at the
+wrong thing.
 
-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:
-
-- `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.
-- `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.
-- `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.
-- `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. Add `--screenshot` and it
-  renders the direction too, so an agent can look at what it built. 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.
-- `npx leglas keep "Aurora" --to src/components/hero.tsx` moves the winner
-  into real source and ends the exploration. It also writes down what the
-  exploration was, into `design-log/`: every direction with its note, the words
-  you typed at each of them, the captures the agent was sent, and which one
-  won. Plain markdown and PNGs, committed, so a pull request can link it and
-  somebody can read it in three months without this tool. Exploring is
-  episodic, and the archive is what makes coming back to a surface cheaper than
-  starting over. `npx leglas log` lists what is there. Set `logDir` if you want
-  it somewhere else.
-
-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. By default the request asks for a new variant
-beside that direction; the chip next to the send button switches it to a
-change in place. 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.
-
-Most of what you would type into that field is the part describing where
-the problem is, so you can point at it instead. Press `A` and the preview
-becomes a picker: hovering outlines the element under the pointer,
-clicking drops a numbered pin that takes a note, and dragging marks an
-area and names every element inside it. Click a pin again to reread what
-it says, reword it or drop it. The page still scrolls, so the thing three
-screens down is as easy to mark as the headline. Annotations
-are a request on their own, so the field can stay empty; leave three and
-send once. Each one carries the element's own words, its tag and classes,
-a path and the box it filled, and the request tells your agent which of
-those to trust first, because the design moves under them by design. One
-whose element has since gone turns amber rather than pointing confidently
-at the wrong thing, and one already sent with a change takes a ring until
-that change settles.
-
-The card above the field is the whole status: what you have queued, who
-has taken it and for how long, and what went wrong when a run fails.
+### Sharing
+
+The rail is local, and the person who most needs to see it often has no
+repo. The share control in the rail's header fixes that: pick the whole rail
+as you see it, or what is on stage (one direction, or the pair being
+compared), and start sharing. Leglas opens a second listener on your
+machine, points a tunnel at it and copies the link once it answers.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-idle.png" width="290" alt="The change field, empty, with its agent picker reading Choose an agent" />
-  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-queued.png" width="290" alt="A card above the change field reading: Change queued, pick who runs your changes" />
-  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-pickedup.png" width="290" alt="A card above the change field reading: Codex is on it, editing .leglas/variants/hero/poster.tsx, 56s, with a stop button" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/share-links.png" width="426" alt="The share panel under the rail's header while sharing: the tunnel address, two links named Link 1 and Client review each with 24h left, the hovered row showing copy, extend and turn off, Another link, the scope line reading The whole rail, 6 directions, only what you shared, then Replace all and Stop" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/share-viewer.png" width="426" alt="The same rail as a viewer sees it: a strip reading Shared with you, the whole rail, then the directions in the sharer's order with no composer" />
 </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 card shows it working: which file it is
-editing, a stop 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.
-
-To use a CLI that is not in the picker, keep the custom command explicit
-in the terminal:
+<p align="center"><i>Sharing, and what the person on the other end gets.</i></p>
+
+Whoever opens the link gets the real app, running, with your order, your
+names, your folded families and your viewport. They can flip, compare,
+search and change the width. They cannot change anything: the share
+listener refuses every write, whoever the caller is, and answers every path
+with 403 without the cookie the link sets, so your dev server never faces
+the internet bare. Viewers do not get hot reload either, since an app's
+live-reload socket is a way in; they refresh to see a change.
+
+What a viewer can do is read what your dev server serves, and you choose
+how much of it. **Anywhere in the app** is the whole dev server over GET,
+source included, because Leglas proxies it faithfully and that is the
+point; it suits a demo. **Only what you shared** serves the pages you shared
+and the files they load, refuses the rest before the dev server hears of it
+and holds against a console or curl as well as a browser. The list is read
+off what your own directions loaded while you looked at them, not written
+by hand, and anything it did not predict shows up in the panel with one
+click to let that path or its folder through. Bounded still means a viewer
+sees everything your shared pages themselves load. Either way Leglas
+refuses the routes a dev server mounts to act on your machine, Vite's
+editor launcher among them, hidden files like `.env` however the path is
+spelled and a service worker that would outlive the share.
 
-```sh
-npx leglas watch --run "my-agent {prompt}"
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/share-reach.png" width="426" alt="The share panel before starting: The whole rail, 6 directions, 2 on branches left out; The direction on stage, Table; How far they can go: Anywhere in the app, Your whole dev server over GET; Only what you shared, These pages and the 22 files they loaded; a Start sharing button" />
+</p>
 
-### MCP server
+<p align="center"><i>Choosing what to share, and how far a viewer goes.</i></p>
 
-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.
+A share hands out links rather than a link. Name one for each person, up
+to sixteen; each lasts a day, extends by another with one click and turns
+off on its own without touching the others. The panel shows which links
+are answering and how many sessions are on each. When your rail has moved
+since you shared, it offers to push what you see now; stop the share from
+the same place, and it stops with Leglas either way.
 
-```sh
-claude mcp add leglas -- npx -y leglas-mcp
-```
+The tunnel is borrowed, not shipped. Leglas looks for `cloudflared` or
+`ngrok` on your machine and runs whichever it finds; with neither, the link
+only works on this machine and the panel says so. Branch directions run on
+their own port and are left out of a share for now.
 
-Or in `.mcp.json`:
+### Keys
 
-```json
-{ "mcpServers": { "leglas": { "command": "npx", "args": ["-y", "leglas-mcp"] } } }
-```
+Arrows move between directions and `1` to `9` jump straight to one. `R`
+asks for a change, `A` annotates, `C` compares, `Cmd K` (`Ctrl K`
+elsewhere) searches, `T` opens the tools popover and `B` collapses the
+rail. Press `?` for the whole keymap.
 
-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.
+## Setting up a project
 
-### As an Agent Plugin
+### Configuration
 
-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
-
-Create `leglas.config.ts` at the project root. `.js`, `.mjs`, and `.json`
+Create `leglas.config.ts` at the project root. `.js`, `.mjs` and `.json`
 work too. Resolution walks upward from the working directory, so in a
 monorepo the nearest file wins. Node reads the TypeScript config natively;
 there is no compiler or extra dependency involved.
@@ -346,129 +278,18 @@ A broken config never stops the server. Leglas starts anyway and the
 interface reports what to fix, so you are not hunting through a stack
 trace.
 
-## The interface
-
-Directions live in a rail on the left. The stage shows the active one in
-a framed viewport at Full, 1440, 834 or 390 wide. Rename, reorder, hide
-and tag directions from the rail. Open the removed list to restore a
-direction, delete one permanently or clear the full list. Machine-local
-directions are removed from `.leglas/previews.json`; shared project config
-and preview source files stay untouched. Layout is saved per project and
-survives restarts and port changes.
-
-Flipping shows a difference over time. A split shows it at once, which is
-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, `A` annotates the design itself,
-`Cmd K` (`Ctrl K` elsewhere) searches, `T` opens the tools popover and `B`
-collapses the rail. Press `?` for the whole keymap.
-
-A small tools widget floats over the stage and can be dragged to any
-corner, because a floating control has a habit of sitting exactly where
-you need to look. Its popover holds the viewport presets and a few
-preferences.
-
-Frameworks paint a dev badge over the corner of the running app. It
-belongs to your app, so Leglas leaves it alone; when it lands on the part
-you are judging, the popover hides it, and does that by styling inside
-the preview frame, never by altering what the proxy forwards.
-
-## Command line
-
-```text
-Usage
-  leglas init                Prepare a project and teach its agents
-  leglas [options]           Start the server and open the interface
-  leglas new <surface>       Scaffold a branch point for a surface
-  leglas explore <surface>   Brief an agent's exploration of a surface
-  leglas classify            Decide where a direction should live
-  leglas add --title T --url U   Register a preview on this machine
-  leglas list                Show every preview, shared and local
-  leglas log [entry]         What past explorations decided
-  leglas show <title>        Everything Leglas knows about one direction
-  leglas requests            Show change requests made from the interface
-  leglas watch --run "<cmd>" Hand each request to your agent as it arrives
-  leglas keep <title> --to <path>  Keep a winner and end the exploration
-
-Options
-  --user-port <port>   Port your dev server is on (default: from config, or 3000)
-  --port <port>        Port for Leglas itself (default: 4100, next free if taken)
-  --config <path>      Config file to use instead of searching upward
-  --no-open            Do not open the browser
-  --json               Print a single machine-readable envelope
-  -h, --help           Show this
-  -v, --version        Show the version
-
-Options for new
-  --print              Print the scaffold instead of writing it
-  --from <path>        Use an existing component as the baseline
-
-Options for explore
-  --count <n>          How many directions (default 3)
-  --based-on <title>     Variants of an existing direction instead of new ones
-
-Options for watch
-  --run <command>      Your agent, with {prompt} where the request goes, for
-                       example "claude -p {prompt}". Remembered after first use
-  --port <port>        Port Leglas itself is on (default: 4100)
-
-Options for classify
-  --change <path>      A file the direction creates or wires up (repeatable)
-  --rewrite <path>     An existing file whose behaviour it must change (repeatable)
-
-Options for add
-  --note <text>        Second line under the title
-  --tag <text>         Repeatable
-  --branch <name>      Back the preview with a checkout of this git branch
-  --file <path>        Preview a plain HTML file served by Leglas itself
-  --based-on <title>   The direction this is a variant of; groups the family
-  --asked-for <text>   The change that was asked for, in the words that were typed
-
-Options for show
-  --screenshot         Render the direction and write a PNG
-  --width <n>          Capture width from 320 to 3840 (needs --screenshot)
-  --port <port>        Running Leglas port (needs --screenshot)
-```
-
-`leglas.config.ts` is the shared description of a project: commit it and a
+The config is the shared description of a project: commit it and a
 teammate gets the same directions on clone. `leglas add` registers a
 preview on your machine only, in `.leglas/previews.json`, because
-exploration is short-lived and its code lives in a gitignored directory.
-`leglas list` shows both and marks which are local.
-
-Renaming a direction in the rail is local in the same way, recorded in
-`.leglas/renames.json`. Leglas will not edit your config to rename
-something you only renamed for yourself, so the config title stays the
-one a teammate sees, and `leglas show` and `leglas keep` take either
-name.
-
-## Comparing branches
-
-A preview with a `branch` field is served from its own checkout: Leglas
-creates a worktree, installs, starts the app with your `devCommand` on a
-free port, and tears it all down when you quit. In the interface it looks
-like any other direction, so a branch against your working tree, or three
-branches against each other, compares the same way two query parameters
-do.
-
-## Without a dev server
+exploration is short-lived and its code lives in a gitignored directory;
+`leglas list` shows both and marks which are local. Renaming a direction
+in the rail is local in the same way, so the config title stays the one a
+teammate sees, and `leglas show` and `leglas keep` take either name.
 
-Leglas does not require a running app.
+### Without a dev server
 
 If the project exists but nothing is listening, set `devCommand` and
-Leglas starts your app itself, proxies it, and stops it on exit. When
+Leglas starts your app itself, proxies it and stops it on exit. When
 `--user-port` names a server explicitly, Leglas never starts a different
 one behind that flag.
 
@@ -489,7 +310,16 @@ the lone file, so stylesheets and images beside it resolve. When the real
 app arrives, directions graduate to app code and nothing about the
 interface changes.
 
-## How it works
+### Comparing branches
+
+A preview with a `branch` field is served from its own checkout: Leglas
+creates a worktree, installs, starts the app with your `devCommand` on a
+free port and tears it all down when you quit. In the interface it looks
+like any other direction, so a branch against your working tree, or three
+branches against each other, compares the same way two query parameters
+do.
+
+### How it works
 
 Leglas runs one local server that serves the interface at `/leglas` and
 forwards every other request to your dev server. Previews load through
@@ -503,7 +333,7 @@ app behaves differently through Leglas than on its own port, that is a
 bug.
 
 Because a preview is a URL, the same interface compares two routes, two
-implementations behind a query parameter, or a local server against a
+implementations behind a query parameter or a local server against a
 deployed one. Absolute URLs load directly rather than through the proxy,
 so a site that refuses to be framed will not preview; the interface says
 so instead of showing an empty pane.
@@ -511,10 +341,10 @@ so instead of showing an empty pane.
 Leglas also compares what each preview actually draws and warns when two
 are identical. This catches a typo like `?v-hero=wavee` that your app
 silently ignores while the rail implies a comparison. The check reads the
-rendered page, runs only on previews you have opened, and skips
+rendered page, runs only on previews you have opened and skips
 cross-origin previews, which the browser will not let it read.
 
-## Limitations
+### Limitations
 
 - Leglas runs no model of its own. Comparing existing routes costs
   nothing, but a new direction is still code your agent writes; Leglas
@@ -526,43 +356,125 @@ cross-origin previews, which the browser will not let it read.
 - The interface is built for desktop widths.
 - Leglas is a development tool. Nothing in it ships to production.
 
-## Development
+## Working with agents
+
+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, `npx leglas init` writes a section into `AGENTS.md`, creates
+a starter config and gitignores Leglas's working directory. That section
+is the agent's whole workflow, and it 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.
+
+### Add beside, never rewrite
+
+The instructions center on one rule. 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. So a direction is added next to what
+exists: a switcher scaffolded beside your component, a query parameter
+that selects it, and your real component untouched as the baseline.
+Anything that cannot be additive, a dependency, a build change, an
+existing file's behaviour, builds on its own git branch instead.
+
+### What an agent runs
+
+| Command | What it does |
+| --- | --- |
+| `leglas explore <surface> --count 6` | Briefs the exploration: what the set is for, and why it only works if the six genuinely disagree. `--based-on "Aurora"` flips it to six deliberate variants of one you like. The designs are the agent's; Leglas prescribes none. |
+| `leglas new <surface> --from src/Hero.tsx` | Scaffolds a switcher under `.leglas/variants/`, with the baseline re-exporting your real component. Prints the one line to add and does not edit your file. Scaffolded branch points return the fallback in production builds. |
+| `leglas classify --change … --rewrite …` | Says where a direction should live before it is written: in-app, where switching is instant, or on its own branch. |
+| `leglas add --title … --url …` | Registers a direction on this machine. |
+| `leglas show "Aurora" --json` | Everything about one direction: its entry, the file behind it, its variants, what it is compared against, what is pending. `--screenshot` renders it too, so an agent can look at what it built. |
+| `leglas requests --json` | The change requests queued from the interface; `--clear` acknowledges them. |
+| `leglas keep "Aurora" --to src/components/hero.tsx` | Moves the winner into real source and ends the exploration, writing what it decided into `design-log/` as markdown and PNGs. `leglas log` lists what is there. |
+
+### Running requests
+
+Requests made from the interface wait in a queue. An agent picked in the
+interface drains it on its own. In a terminal, `npx leglas watch` is the
+same loop with the agent's own output in view, and needs no flag once an
+agent has been picked; for a CLI that is not in the picker, keep the
+command explicit:
+
+```sh
+npx leglas watch --run "my-agent {prompt}"
+```
+
+### MCP server
 
-This repository is a pnpm workspace.
+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. The
+`start` tool boots the viewer and returns its URL, and anything it started
+stops when the session ends.
 
 ```sh
-pnpm install
-pnpm build       # build every package
-pnpm test        # run the test suite
-pnpm typecheck   # type check every package
-pnpm site        # build the site, homepage and changelog, into dist/site
+claude mcp add leglas -- npx -y leglas-mcp
 ```
 
-| Package           | Contents                                           |
-| ----------------- | -------------------------------------------------- |
-| `packages/server` | Config loading, the proxy, and the local server    |
-| `packages/shell`  | The interface, a React application built with Vite |
-| `packages/cli`    | The `leglas` binary                                |
-| `packages/mcp`    | The `leglas-mcp` stdio server for agent hosts      |
-
-To work on the interface with live reload, run a Leglas server in one
-terminal and `pnpm --filter @leglas/shell dev` in another.
-
-Two packages are published, both unscoped: `leglas`, which bundles the
-server and the built interface, and `leglas-mcp`. Releases are
-tag-driven: set the same version in both packages and `plugin.json`, turn
-the changelog's Unreleased section into that version with a title for what
-the release was about, push a `v<version>` tag, and CI runs the suite and
-publishes through npm trusted publishing. A tag that disagrees with the
-manifests is refused, and so is a patch tag when `api-surface.txt` has
-moved since the previous one. No npm token exists anywhere in the project.
-
-The [site](https://leglas.vercel.app/) is two pages, the homepage and the
-[changelog](https://leglas.vercel.app/changelog/), written by `site.ts`. The
-changelog page is made from `CHANGELOG.md` and nothing else, so describing a
-release in the changelog is the whole job. Vercel builds it from
-`vercel.json` on every push, so main is the live site and every pull request
-gets a preview.
+Or in `.mcp.json`:
+
+```json
+{ "mcpServers": { "leglas": { "command": "npx", "args": ["-y", "leglas-mcp"] } } }
+```
+
+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. On a host that speaks channels, the server
+pushes each request into the session as it arrives.
+
+### Agent Plugin
+
+The repository is also an [Agent Plugin](https://agent-plugins.org), the
+open standard for shipping a skill and MCP configuration together, so a
+client that implements it installs both in one step. It is a layout, not a
+build: `plugin.json` and `mcp.json` at the root, the skill in
+`skills/leglas/`. Such a client starts the server in the plugin's own
+directory, so the project is taken from the workspace the host declares
+over MCP roots, or from `LEGLAS_PROJECT_DIR` when it declares none. The
+plugin's version covers the skill and the configuration; the server it
+launches is whatever `npx` fetches, the same as every command above.
+
+## Command line
+
+```text
+leglas init                Prepare a project and teach its agents
+leglas [options]           Start the server and open the interface
+leglas new <surface>       Scaffold a branch point for a surface
+leglas explore <surface>   Brief an agent's exploration of a surface
+leglas classify            Decide where a direction should live
+leglas add --title T --url U   Register a preview on this machine
+leglas list                Show every preview, shared and local
+leglas log [entry]         What past explorations decided
+leglas show <title>        Everything Leglas knows about one direction
+leglas requests            Show change requests made from the interface
+leglas watch --run "<cmd>" Hand each request to your agent as it arrives
+leglas keep <title> --to <path>  Keep a winner and end the exploration
+```
+
+`--json` on any command prints a single machine-readable envelope.
+`--port` chooses Leglas's own port and `--user-port` your dev server's;
+`--config` names a config file instead of searching upward. Every
+command's options are under `leglas <command> --help`.
+
+## Development
+
+This repository is a pnpm workspace: `pnpm install`, then `pnpm build`,
+`pnpm test` and `pnpm typecheck`. Two packages are published, `leglas` and
+`leglas-mcp`, and the repository is also the Agent Plugin. How to work on
+it, what a pull request needs and how a release is cut are in
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License