@shunagent/shun 0.0.0-stage → 0.1.145

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyles Light
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# Shun
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Serious coding agents, running on hardware you own.**
+
+[Website](https://shunagent.com) · [GitHub](https://github.com/kyleslight/shun) · [Download Desktop](https://shunagent.com/download) · [Report an issue](https://github.com/kyleslight/shun/issues)
+
+Shun brings streaming conversations, coding tools, Agent Skills, and plugins to
+your terminal. Connect a local model server or a hosted model provider.
+
+## Install
+
+Requires **Node.js 22.19 or newer** on macOS, Linux, or Windows.
+
+```sh
+npm install -g @shunagent/shun
+shun
+```
+
+Alternatively, use `pnpm add -g @shunagent/shun` or `bun add -g @shunagent/shun`.
+The terminal app can run without Shun Desktop.
+
+## Start a conversation
+
+```sh
+shun                       # Start without selecting a project
+shun .                     # Work in the current directory
+shun /path/to/project      # Work in another project
+shun -c                    # Continue the latest conversation in this scope
+shun -r                    # Choose a conversation from history
+shun --session <id>         # Resume a specific conversation
+shun tasks                 # List conversations
+shun run "Explain this project" --workspace .
+```
+
+On first use, follow the prompts to connect a provider and choose a model.
+Existing local Shun provider settings are reused. Type `/` to open the command
+menu. `/connect` adds a connection, `/providers` manages connections, and `/model`
+chooses a model. `/new` starts a new conversation; `/resume` opens history.
+
+Answers stream as they arrive. Markdown and tables render in the terminal.
+Click an activity row to expand its details. Older messages appear in pages of
+24; scroll up and click **Show earlier messages** to read more.
+
+Ctrl+C stops the current generation, cancels an open menu, or returns from a
+finished conversation to the welcome screen. At the welcome screen, press it
+twice to exit. Ctrl+D on an empty prompt detaches from Shun. Exiting the terminal
+does not stop background tasks; use `/stop` to stop the current run.
+
+## Images
+
+On macOS, use **Cmd+V**. If iTerm2 asks how to paste an image, choose **Save to
+Temp File and Paste Path**; you can remember that choice. Shun recognizes a single
+pasted image path and adds it as an attachment. Ordinary pasted text stays text.
+
+`/paste` reads an image from the local clipboard, `/attach /path/to/image.png`
+attaches an image file, and `/images` previews or removes pending attachments.
+A remote SSH terminal cannot read your computer's local clipboard.
+
+## Desktop, plugins, and saved conversations
+
+[Shun Desktop](https://shunagent.com/download) provides the graphical interface.
+Compatible Desktop and terminal versions share conversations and model settings
+on the same machine. With Desktop running, the terminal can also use its browser
+and computer tools. Remote access uses Desktop's existing Remote connection.
+Plugin graphical views stay in Desktop; the terminal exposes supported tools and
+Agent Skills. Standalone Browser Preview uses a separate testing browser.
+
+Use `/desktop` to open the current conversation in Desktop. Older Desktop
+versions may need an update to support shared conversations and capabilities.
+
+Shun stores its local profile under `~/.shun`. Set `SHUN_HOME` to use an isolated
+profile. A selected project is a working directory, not a filesystem sandbox;
+tools run with your account's permissions.
+
+## Update
+
+```sh
+npm install -g @shunagent/shun@latest
+shun --version
+```
+
+This updates the npm installation. Desktop updates separately. Restart the
+terminal interface to load its new version. If a background service needs a
+restart, use `shun service stop` after its tasks finish. There is currently no
+`shun upgrade` command.
+
+## Learn more
+
+- [Shun website](https://shunagent.com)
+- [Source code and documentation](https://github.com/kyleslight/shun)
+- [Desktop downloads](https://shunagent.com/download)
+- [Issues and feedback](https://github.com/kyleslight/shun/issues)
+
+MIT licensed.

package/bin/shun.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const [major, minor] = process.versions.node.split('.').map(Number)
+if (major < 22 || (major === 22 && minor < 19)) {
+  console.error('Shun requires Node.js 22.19 or newer. Use the standalone installer if Node.js is not installed.')
+  process.exit(1)
+}
+await import('../dist/cli.js')