diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8e08171..2624e0c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,8 @@ All notable changes to ScriptGo will be documented in this file.
 ## [0.1.0-alpha.6] - 2026-09-23
 
 ### Features
+- feat(cli): support direct execution ('scriptgo file.ts', 'scriptgo -e "code"') and 'scg' CLI alias
+- feat(pkgmgr): implement scriptgo add to resolve, record, and install dependencies
 - feat(benchmarks): add JSON operation suites, standard dataset, and native benchmarks (#22) (a893439)
 
 ### Performance
diff --git a/Makefile b/Makefile
index 887a6f3..1a8a604 100644
--- a/Makefile
+++ b/Makefile
@@ -1,14 +1,16 @@
 .PHONY: all build test test-frontend test-parity test-sanitizers audit lint clean release help
 
 BINARY_NAME=scriptgo
+ALIAS_NAME=scg
 BUILD_DIR=bin
 
 all: build test
 
-## build: Build the scriptgo CLI binary
+## build: Build the scriptgo CLI binary and scg alias
 build:
 	@echo "==> Building $(BINARY_NAME)..."
 	go build -o $(BINARY_NAME) ./cmd/scriptgo
+	@ln -sf $(BINARY_NAME) $(ALIAS_NAME)
 
 ## test: Run full unit and integration test suite
 test:
@@ -51,7 +53,7 @@ release:
 ## clean: Clean up build artifacts and temporary files
 clean:
 	@echo "==> Cleaning up build artifacts..."
-	rm -f $(BINARY_NAME)
+	rm -f $(BINARY_NAME) $(ALIAS_NAME)
 	rm -rf $(BUILD_DIR)
 
 ## help: Display this help message
diff --git a/cmd/scg/main.go b/cmd/scg/main.go
new file mode 100644
index 0000000..d8a1b01
--- /dev/null
+++ b/cmd/scg/main.go
@@ -0,0 +1,40 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+)
+
+func main() {
+	// 1. Look for sibling "scriptgo" in the same directory as this binary
+	var scriptgoPath string
+	if selfExe, err := os.Executable(); err == nil {
+		candidate := filepath.Join(filepath.Dir(selfExe), "scriptgo")
+		if info, statErr := os.Stat(candidate); statErr == nil && !info.IsDir() {
+			scriptgoPath = candidate
+		}
+	}
+	// 2. Look in PATH
+	if scriptgoPath == "" {
+		if path, lookErr := exec.LookPath("scriptgo"); lookErr == nil {
+			scriptgoPath = path
+		}
+	}
+	if scriptgoPath == "" {
+		fmt.Fprintf(os.Stderr, "scg: could not locate 'scriptgo' binary in PATH or executable directory\n")
+		os.Exit(1)
+	}
+
+	cmd := exec.Command(scriptgoPath, os.Args[1:]...)
+	cmd.Stdin = os.Stdin
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	if err := cmd.Run(); err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			os.Exit(exitErr.ExitCode())
+		}
+		os.Exit(1)
+	}
+}
diff --git a/cmd/scriptgo/add_test.go b/cmd/scriptgo/add_test.go
new file mode 100644
index 0000000..c859305
--- /dev/null
+++ b/cmd/scriptgo/add_test.go
@@ -0,0 +1,189 @@
+package main
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"crypto/sha512"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func createMockTarball(t *testing.T, filename, content string) ([]byte, string) {
+	t.Helper()
+	var buf bytes.Buffer
+	gzw := gzip.NewWriter(&buf)
+	tw := tar.NewWriter(gzw)
+	hdr := &tar.Header{
+		Name: "package/" + filename,
+		Mode: 0o644,
+		Size: int64(len(content)),
+	}
+	if err := tw.WriteHeader(hdr); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := tw.Write([]byte(content)); err != nil {
+		t.Fatal(err)
+	}
+	if err := tw.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := gzw.Close(); err != nil {
+		t.Fatal(err)
+	}
+	archive := buf.Bytes()
+	digest := sha512.Sum512(archive)
+	integrity := "sha512-" + base64.StdEncoding.EncodeToString(digest[:])
+	return archive, integrity
+}
+
+func TestCLI_Add(t *testing.T) {
+	tmpDir := t.TempDir()
+	binPath := filepath.Join(tmpDir, "scriptgo")
+	buildCmd := exec.Command("go", "build", "-o", binPath, ".")
+	if out, err := buildCmd.CombinedOutput(); err != nil {
+		t.Fatalf("failed to build scriptgo: %v\noutput: %s", err, string(out))
+	}
+
+	pkgArchive, integrity := createMockTarball(t, "index.js", "module.exports = 'from-add-cli';\n")
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+		if request.URL.Path == "/my-pkg" {
+			tarball := "http://" + request.Host + "/my-pkg/-/my-pkg.tgz"
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"dist-tags": map[string]string{"latest": "1.5.0"},
+				"versions": map[string]any{
+					"1.5.0": map[string]any{
+						"name":    "my-pkg",
+						"version": "1.5.0",
+						"dist": map[string]string{
+							"tarball":   tarball,
+							"integrity": integrity,
+						},
+					},
+				},
+			})
+			return
+		}
+		if request.URL.Path == "/my-pkg/-/my-pkg.tgz" {
+			_, _ = w.Write(pkgArchive)
+			return
+		}
+		http.NotFound(w, request)
+	}))
+	defer server.Close()
+
+	t.Run("no packages specified returns error", func(t *testing.T) {
+		cmd := exec.Command(binPath, "add")
+		out, err := cmd.CombinedOutput()
+		if err == nil {
+			t.Fatalf("expected error for empty add, got: %s", string(out))
+		}
+		if !strings.Contains(string(out), "at least one package must be specified") {
+			t.Fatalf("unexpected output: %s", string(out))
+		}
+	})
+
+	t.Run("mutually exclusive flags return error", func(t *testing.T) {
+		cmd := exec.Command(binPath, "add", "-D", "-O", "my-pkg")
+		out, err := cmd.CombinedOutput()
+		if err == nil {
+			t.Fatalf("expected error for mutually exclusive flags, got: %s", string(out))
+		}
+		if !strings.Contains(string(out), "mutually exclusive") {
+			t.Fatalf("unexpected output: %s", string(out))
+		}
+	})
+
+	t.Run("add package successfully", func(t *testing.T) {
+		projectDir := filepath.Join(tmpDir, "project1")
+		if err := os.MkdirAll(projectDir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(projectDir, "package.json"), []byte(`{"name":"test1"}`), 0o644); err != nil {
+			t.Fatal(err)
+		}
+
+		cmd := exec.Command(binPath, "add", "--project", projectDir, "--registry", server.URL, "my-pkg")
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("add failed: %v\noutput: %s", err, string(out))
+		}
+		if !strings.Contains(string(out), "added my-pkg@^1.5.0") {
+			t.Fatalf("unexpected stdout: %s", string(out))
+		}
+
+		manifestBytes, err := os.ReadFile(filepath.Join(projectDir, "package.json"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !strings.Contains(string(manifestBytes), `"my-pkg": "^1.5.0"`) {
+			t.Fatalf("package.json does not contain dependency: %s", string(manifestBytes))
+		}
+
+		installedFile, err := os.ReadFile(filepath.Join(projectDir, "node_modules", "my-pkg", "index.js"))
+		if err != nil {
+			t.Fatalf("installed file missing: %v", err)
+		}
+		if string(installedFile) != "module.exports = 'from-add-cli';\n" {
+			t.Fatalf("unexpected installed content: %s", string(installedFile))
+		}
+	})
+
+	t.Run("add dev dependency with -D flag", func(t *testing.T) {
+		projectDir := filepath.Join(tmpDir, "project2")
+		if err := os.MkdirAll(projectDir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(projectDir, "package.json"), []byte(`{"name":"test2"}`), 0o644); err != nil {
+			t.Fatal(err)
+		}
+
+		cmd := exec.Command(binPath, "add", "--project", projectDir, "--registry", server.URL, "-D", "my-pkg")
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("add -D failed: %v\noutput: %s", err, string(out))
+		}
+
+		manifestBytes, err := os.ReadFile(filepath.Join(projectDir, "package.json"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !strings.Contains(string(manifestBytes), `"devDependencies"`) || !strings.Contains(string(manifestBytes), `"my-pkg": "^1.5.0"`) {
+			t.Fatalf("package.json does not contain devDependency: %s", string(manifestBytes))
+		}
+	})
+
+	t.Run("add exact version with -E flag", func(t *testing.T) {
+		projectDir := filepath.Join(tmpDir, "project3")
+		if err := os.MkdirAll(projectDir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(projectDir, "package.json"), []byte(`{"name":"test3"}`), 0o644); err != nil {
+			t.Fatal(err)
+		}
+
+		cmd := exec.Command(binPath, "add", "--project", projectDir, "--registry", server.URL, "-E", "my-pkg@1.5.0")
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("add -E failed: %v\noutput: %s", err, string(out))
+		}
+		if !strings.Contains(string(out), "added my-pkg@1.5.0") {
+			t.Fatalf("unexpected stdout: %s", string(out))
+		}
+
+		manifestBytes, err := os.ReadFile(filepath.Join(projectDir, "package.json"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !strings.Contains(string(manifestBytes), `"my-pkg": "1.5.0"`) {
+			t.Fatalf("package.json does not contain exact version: %s", string(manifestBytes))
+		}
+	})
+}
diff --git a/cmd/scriptgo/coverage_cmd.go b/cmd/scriptgo/coverage_cmd.go
new file mode 100644
index 0000000..a2f69e6
--- /dev/null
+++ b/cmd/scriptgo/coverage_cmd.go
@@ -0,0 +1,76 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/pilotworks/scriptgo/internal/compiler"
+)
+
+func handleCoverage(args []string) {
+	fs := flag.NewFlagSet("coverage", flag.ContinueOnError)
+	fs.Usage = printCoverageUsage
+	eval := fs.String("e", "", "evaluate inline script string")
+	format := fs.String("format", "summary", "coverage output format: summary, json")
+	output := fs.String("o", "", "write output to this path (default: stdout)")
+	verbose := fs.Bool("v", false, "print analysis stages to stderr")
+	dynamic := registerDynamicFlag(fs)
+	if err := fs.Parse(args); err != nil {
+		if err == flag.ErrHelp {
+			os.Exit(0)
+		}
+		os.Exit(2)
+	}
+
+	var entryPath string
+	var cleanup func()
+	if *eval != "" {
+		var err error
+		entryPath, cleanup, err = createInlineSourceFile(*eval)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "scriptgo:", err)
+			os.Exit(1)
+		}
+		defer cleanup()
+	} else if fs.NArg() == 1 {
+		var err error
+		entryPath, cleanup, err = resolveInput(fs.Arg(0))
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "scriptgo:", err)
+			os.Exit(1)
+		}
+		defer cleanup()
+	} else {
+		printCoverageUsage()
+		os.Exit(2)
+	}
+
+	if *verbose {
+		fmt.Fprintf(os.Stderr, "scriptgo: analyzing coverage for %s\n", entryPath)
+	}
+	options := compiler.BuildOptions{Dynamic: *dynamic}
+	var result string
+	var err error
+	switch *format {
+	case "summary":
+		result, err = compiler.CoverageSummary(entryPath, options)
+	case "json":
+		result, err = compiler.CoverageReportJSON(entryPath, options)
+	default:
+		fmt.Fprintf(os.Stderr, "scriptgo: unsupported coverage format %q (supported: summary, json)\n", *format)
+		os.Exit(2)
+	}
+	if err != nil {
+		printError(err)
+		os.Exit(1)
+	}
+	if *output == "" {
+		fmt.Print(result)
+		return
+	}
+	if err := os.WriteFile(*output, []byte(result), 0o644); err != nil {
+		fmt.Fprintln(os.Stderr, "scriptgo:", err)
+		os.Exit(1)
+	}
+}
diff --git a/cmd/scriptgo/emit_cmd.go b/cmd/scriptgo/emit_cmd.go
new file mode 100644
index 0000000..681296e
--- /dev/null
+++ b/cmd/scriptgo/emit_cmd.go
@@ -0,0 +1,98 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/pilotworks/scriptgo/internal/compiler"
+)
+
+func handleEmit(args []string) {
+	fs := flag.NewFlagSet("emit", flag.ContinueOnError)
+	fs.Usage = printEmitUsage
+	eval := fs.String("e", "", "evaluate inline script string")
+	mode := fs.String("mode", "llvm-ir", "output mode: llvm-ir, typed-ir")
+	output := fs.String("o", "", "write output to this path (default: stdout)")
+	verbose := fs.Bool("v", false, "print compilation stages to stderr")
+	target := fs.String("target", "", "native target triple (default: $SCRIPTGO_TARGET or native)")
+	debug := fs.Bool("debug", false, "include native debug metadata")
+	warnRuntimeCasts := fs.Bool("warn-runtime-casts", false, "warn on runtime checked casts")
+	strictCasts := fs.Bool("strict-casts", false, "treat cast warnings as errors")
+	optLevel := fs.String("O", "", "optimization level (0, 1, 2, 3, s, z, fast)")
+	release := fs.Bool("release", false, "build with release optimizations")
+	dynamic := registerDynamicFlag(fs)
+	if err := fs.Parse(args); err != nil {
+		if err == flag.ErrHelp {
+			os.Exit(0)
+		}
+		os.Exit(2)
+	}
+
+	var entryPath string
+	var cleanup func()
+
+	if *eval != "" {
+		var err error
+		entryPath, cleanup, err = createInlineSourceFile(*eval)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "scriptgo:", err)
+			os.Exit(1)
+		}
+		defer cleanup()
+	} else if fs.NArg() == 1 {
+		var err error
+		entryPath, cleanup, err = resolveInput(fs.Arg(0))
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "scriptgo:", err)
+			os.Exit(1)
+		}
+		defer cleanup()
+	} else {
+		printEmitUsage()
+		os.Exit(2)
+	}
+
+	options := compiler.BuildOptions{
+		Target:           *target,
+		Debug:            *debug,
+		OptLevel:         *optLevel,
+		Release:          *release,
+		WarnRuntimeCasts: *warnRuntimeCasts,
+		StrictCasts:      *strictCasts,
+		Dynamic:          *dynamic,
+	}
+	var result string
+	var err error
+
+	switch *mode {
+	case "typed-ir":
+		if *verbose {
+			fmt.Fprintf(os.Stderr, "scriptgo: emitting typed IR for %s\n", entryPath)
+		}
+		result, err = compiler.DumpIRWithOptions(entryPath, options)
+	case "llvm-ir":
+		if *verbose {
+			fmt.Fprintf(os.Stderr, "scriptgo: emitting LLVM IR for %s\n", entryPath)
+		}
+		result, err = compiler.CompileWithOptions(entryPath, options)
+	default:
+		fmt.Fprintf(os.Stderr, "scriptgo: unsupported emit mode %q (supported: llvm-ir, typed-ir)\n", *mode)
+		os.Exit(2)
+	}
+
+	printCompilerWarnings()
+	if err != nil {
+		printError(err)
+		os.Exit(1)
+	}
+
+	if *output == "" {
+		fmt.Print(result)
+		return
+	}
+	if err := os.WriteFile(*output, []byte(result), 0o644); err != nil {
+		fmt.Fprintln(os.Stderr, "scriptgo:", err)
+		os.Exit(1)
+	}
+}
diff --git a/cmd/scriptgo/main.go b/cmd/scriptgo/main.go
index 4215875..b597521 100644
--- a/cmd/scriptgo/main.go
+++ b/cmd/scriptgo/main.go
@@ -21,6 +21,34 @@ func init() {
 	}
 }
 
+func getProgramName() string {
+	if len(os.Args) > 0 {
+		base := filepath.Base(os.Args[0])
+		if base == "scg" || base == "scg.exe" {
+			return "scg"
+		}
+	}
+	return "scriptgo"
+}
+
+func shouldImplicitRun(firstArg string) bool {
+	if strings.HasPrefix(firstArg, "-") {
+		return true
+	}
+	ext := strings.ToLower(filepath.Ext(firstArg))
+	switch ext {
+	case ".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs":
+		return true
+	}
+	if info, err := os.Stat(firstArg); err == nil && !info.IsDir() {
+		return true
+	}
+	if _, err := pkgmgr.ResolveTask(".", "", firstArg); err == nil {
+		return true
+	}
+	return false
+}
+
 func main() {
 	if len(os.Args) < 2 {
 		printMainUsage()
@@ -41,12 +69,14 @@ func main() {
 		handleCoverage(normalizeFlagsFirst(os.Args[2:]))
 	case "init":
 		handleInit(normalizeFlagsFirst(os.Args[2:]))
+	case "add":
+		handleAdd(normalizeFlagsFirstForAdd(os.Args[2:]))
 	case "install":
 		handleInstall(normalizeFlagsFirst(os.Args[2:]))
 	case "task":
 		handleTask(os.Args[2:])
 	case "version", "--version", "-V":
-		fmt.Printf("scriptgo version %s (runtime %s)\n", compiler.Version, compiler.RuntimeABIVersion)
+		fmt.Printf("%s version %s (runtime %s)\n", getProgramName(), compiler.Version, compiler.RuntimeABIVersion)
 	case "help", "--help", "-h":
 		if len(os.Args) > 2 {
 			handleHelpCommand(os.Args[2])
@@ -54,7 +84,11 @@ func main() {
 		}
 		printMainUsage()
 	default:
-		fmt.Fprintf(os.Stderr, "scriptgo: unknown command %q\n\n", firstArg)
+		if shouldImplicitRun(firstArg) {
+			handleRun(normalizeFlagsFirst(os.Args[1:]))
+			return
+		}
+		fmt.Fprintf(os.Stderr, "%s: unknown command %q\n\n", getProgramName(), firstArg)
 		printMainUsage()
 		os.Exit(2)
 	}
@@ -74,14 +108,16 @@ func handleHelpCommand(cmd string) {
 		printCoverageUsage()
 	case "init":
 		printInitUsage()
+	case "add":
+		printAddUsage()
 	case "install":
 		printInstallUsage()
 	case "task":
 		printTaskUsage()
 	case "version":
-		fmt.Println("Usage: scriptgo version\n\nPrints the current compiler version and runtime ABI version.")
+		fmt.Printf("Usage: %s version\n\nPrints the current compiler version and runtime ABI version.\n", getProgramName())
 	default:
-		fmt.Fprintf(os.Stderr, "scriptgo: unknown command %q for help\n\n", cmd)
+		fmt.Fprintf(os.Stderr, "%s: unknown command %q for help\n\n", getProgramName(), cmd)
 		printMainUsage()
 		os.Exit(2)
 	}
@@ -151,6 +187,7 @@ func handleRun(args []string) {
 	fs := flag.NewFlagSet("run", flag.ContinueOnError)
 	fs.Usage = printRunUsage
 	eval := fs.String("e", "", "evaluate inline script string")
+	fs.StringVar(eval, "eval", "", "evaluate inline script string")
 	verbose := fs.Bool("v", false, "print compilation stages to stderr")
 	target := fs.String("target", "", "native target triple (default: $SCRIPTGO_TARGET or native)")
 	cc := fs.String("cc", "", "C compiler / toolchain driver (default: $SCRIPTGO_CC or clang)")
@@ -178,16 +215,24 @@ func handleRun(args []string) {
 		os.Exit(2)
 	}
 
+	hasEval := false
+	for _, a := range args {
+		if a == "-e" || a == "--eval" || strings.HasPrefix(a, "-e=") || strings.HasPrefix(a, "--eval=") {
+			hasEval = true
+			break
+		}
+	}
+
 	var entryPath string
 	var cleanup func()
 	var extraArgs []string
 	var extraSources []string
 
-	if *eval != "" {
+	if *eval != "" || hasEval {
 		var err error
 		entryPath, cleanup, err = createInlineSourceFile(*eval)
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "scriptgo: %v\n", err)
+			fmt.Fprintf(os.Stderr, "%s: %v\n", getProgramName(), err)
 			os.Exit(1)
 		}
 		defer cleanup()
@@ -201,7 +246,7 @@ func handleRun(args []string) {
 		var err error
 		entryPath, cleanup, err = resolveInput(firstArg)
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "scriptgo: %v\n", err)
+			fmt.Fprintf(os.Stderr, "%s: %v\n", getProgramName(), err)
 			os.Exit(1)
 		}
 		defer cleanup()
@@ -577,162 +622,6 @@ func handleCheck(args []string) {
 	}
 }
 
-func handleEmit(args []string) {
-	fs := flag.NewFlagSet("emit", flag.ContinueOnError)
-	fs.Usage = printEmitUsage
-	eval := fs.String("e", "", "evaluate inline script string")
-	mode := fs.String("mode", "llvm-ir", "output mode: llvm-ir, typed-ir")
-	output := fs.String("o", "", "write output to this path (default: stdout)")
-	verbose := fs.Bool("v", false, "print compilation stages to stderr")
-	target := fs.String("target", "", "native target triple (default: $SCRIPTGO_TARGET or native)")
-	debug := fs.Bool("debug", false, "include native debug metadata")
-	warnRuntimeCasts := fs.Bool("warn-runtime-casts", false, "warn on runtime checked casts")
-	strictCasts := fs.Bool("strict-casts", false, "treat cast warnings as errors")
-	optLevel := fs.String("O", "", "optimization level (0, 1, 2, 3, s, z, fast)")
-	release := fs.Bool("release", false, "build with release optimizations")
-	dynamic := registerDynamicFlag(fs)
-	if err := fs.Parse(args); err != nil {
-		if err == flag.ErrHelp {
-			os.Exit(0)
-		}
-		os.Exit(2)
-	}
-
-	var entryPath string
-	var cleanup func()
-
-	if *eval != "" {
-		var err error
-		entryPath, cleanup, err = createInlineSourceFile(*eval)
-		if err != nil {
-			fmt.Fprintln(os.Stderr, "scriptgo:", err)
-			os.Exit(1)
-		}
-		defer cleanup()
-	} else if fs.NArg() == 1 {
-		var err error
-		entryPath, cleanup, err = resolveInput(fs.Arg(0))
-		if err != nil {
-			fmt.Fprintln(os.Stderr, "scriptgo:", err)
-			os.Exit(1)
-		}
-		defer cleanup()
-	} else {
-		printEmitUsage()
-		os.Exit(2)
-	}
-
-	options := compiler.BuildOptions{
-		Target:           *target,
-		Debug:            *debug,
-		OptLevel:         *optLevel,
-		Release:          *release,
-		WarnRuntimeCasts: *warnRuntimeCasts,
-		StrictCasts:      *strictCasts,
-		Dynamic:          *dynamic,
-	}
-	var result string
-	var err error
-
-	switch *mode {
-	case "typed-ir":
-		if *verbose {
-			fmt.Fprintf(os.Stderr, "scriptgo: emitting typed IR for %s\n", entryPath)
-		}
-		result, err = compiler.DumpIRWithOptions(entryPath, options)
-	case "llvm-ir":
-		if *verbose {
-			fmt.Fprintf(os.Stderr, "scriptgo: emitting LLVM IR for %s\n", entryPath)
-		}
-		result, err = compiler.CompileWithOptions(entryPath, options)
-	default:
-		fmt.Fprintf(os.Stderr, "scriptgo: unsupported emit mode %q (supported: llvm-ir, typed-ir)\n", *mode)
-		os.Exit(2)
-	}
-
-	printCompilerWarnings()
-	if err != nil {
-		printError(err)
-		os.Exit(1)
-	}
-
-	if *output == "" {
-		fmt.Print(result)
-		return
-	}
-	if err := os.WriteFile(*output, []byte(result), 0o644); err != nil {
-		fmt.Fprintln(os.Stderr, "scriptgo:", err)
-		os.Exit(1)
-	}
-}
-
-func handleCoverage(args []string) {
-	fs := flag.NewFlagSet("coverage", flag.ContinueOnError)
-	fs.Usage = printCoverageUsage
-	eval := fs.String("e", "", "evaluate inline script string")
-	format := fs.String("format", "summary", "coverage output format: summary, json")
-	output := fs.String("o", "", "write output to this path (default: stdout)")
-	verbose := fs.Bool("v", false, "print analysis stages to stderr")
-	dynamic := registerDynamicFlag(fs)
-	if err := fs.Parse(args); err != nil {
-		if err == flag.ErrHelp {
-			os.Exit(0)
-		}
-		os.Exit(2)
-	}
-
-	var entryPath string
-	var cleanup func()
-	if *eval != "" {
-		var err error
-		entryPath, cleanup, err = createInlineSourceFile(*eval)
-		if err != nil {
-			fmt.Fprintln(os.Stderr, "scriptgo:", err)
-			os.Exit(1)
-		}
-		defer cleanup()
-	} else if fs.NArg() == 1 {
-		var err error
-		entryPath, cleanup, err = resolveInput(fs.Arg(0))
-		if err != nil {
-			fmt.Fprintln(os.Stderr, "scriptgo:", err)
-			os.Exit(1)
-		}
-		defer cleanup()
-	} else {
-		printCoverageUsage()
-		os.Exit(2)
-	}
-
-	if *verbose {
-		fmt.Fprintf(os.Stderr, "scriptgo: analyzing coverage for %s\n", entryPath)
-	}
-	options := compiler.BuildOptions{Dynamic: *dynamic}
-	var result string
-	var err error
-	switch *format {
-	case "summary":
-		result, err = compiler.CoverageSummary(entryPath, options)
-	case "json":
-		result, err = compiler.CoverageReportJSON(entryPath, options)
-	default:
-		fmt.Fprintf(os.Stderr, "scriptgo: unsupported coverage format %q (supported: summary, json)\n", *format)
-		os.Exit(2)
-	}
-	if err != nil {
-		printError(err)
-		os.Exit(1)
-	}
-	if *output == "" {
-		fmt.Print(result)
-		return
-	}
-	if err := os.WriteFile(*output, []byte(result), 0o644); err != nil {
-		fmt.Fprintln(os.Stderr, "scriptgo:", err)
-		os.Exit(1)
-	}
-}
-
 func printCompilerWarnings() {
 	warns := compiler.GetWarnings()
 	for _, w := range warns {
diff --git a/cmd/scriptgo/main_test.go b/cmd/scriptgo/main_test.go
index e5ee038..91d0827 100644
--- a/cmd/scriptgo/main_test.go
+++ b/cmd/scriptgo/main_test.go
@@ -201,3 +201,73 @@ func TestCLI_CheckTSConfig(t *testing.T) {
 		}
 	})
 }
+
+func TestCLI_DirectExecutionAndAlias(t *testing.T) {
+	tmpDir := t.TempDir()
+	binPath := testScriptGoBin
+
+	tsFile := filepath.Join(tmpDir, "hello.ts")
+	if err := os.WriteFile(tsFile, []byte("console.log('direct_file_works');\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	t.Run("scriptgo -e code", func(t *testing.T) {
+		cmd := exec.Command(binPath, "-e", "console.log('direct_eval_works');")
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("expected scriptgo -e to succeed: %v\noutput: %s", err, string(out))
+		}
+		if !strings.Contains(string(out), "direct_eval_works") {
+			t.Errorf("unexpected output: %s", string(out))
+		}
+	})
+
+	t.Run("scriptgo file.ts", func(t *testing.T) {
+		cmd := exec.Command(binPath, tsFile)
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("expected scriptgo file.ts to succeed: %v\noutput: %s", err, string(out))
+		}
+		if !strings.Contains(string(out), "direct_file_works") {
+			t.Errorf("unexpected output: %s", string(out))
+		}
+	})
+
+	scgBin := filepath.Join(tmpDir, "scg")
+	if err := os.Symlink(binPath, scgBin); err != nil {
+		t.Skipf("symlink not supported on this platform: %v", err)
+	}
+
+	t.Run("scg -e code", func(t *testing.T) {
+		cmd := exec.Command(scgBin, "-e", "console.log('scg_eval_works');")
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("expected scg -e to succeed: %v\noutput: %s", err, string(out))
+		}
+		if !strings.Contains(string(out), "scg_eval_works") {
+			t.Errorf("unexpected output: %s", string(out))
+		}
+	})
+
+	t.Run("scg file.ts", func(t *testing.T) {
+		cmd := exec.Command(scgBin, tsFile)
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("expected scg file.ts to succeed: %v\noutput: %s", err, string(out))
+		}
+		if !strings.Contains(string(out), "direct_file_works") {
+			t.Errorf("unexpected output: %s", string(out))
+		}
+	})
+
+	t.Run("scg version", func(t *testing.T) {
+		cmd := exec.Command(scgBin, "version")
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("expected scg version to succeed: %v\noutput: %s", err, string(out))
+		}
+		if !strings.Contains(string(out), "scg version") {
+			t.Errorf("unexpected output: %s", string(out))
+		}
+	})
+}
diff --git a/cmd/scriptgo/package_add.go b/cmd/scriptgo/package_add.go
new file mode 100644
index 0000000..a9cb39b
--- /dev/null
+++ b/cmd/scriptgo/package_add.go
@@ -0,0 +1,121 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/pilotworks/scriptgo/internal/pkgmgr"
+)
+
+func handleAdd(args []string) {
+	fs := flag.NewFlagSet("add", flag.ContinueOnError)
+	fs.Usage = printAddUsage
+	project := fs.String("project", ".", "project directory containing package.json")
+	manifest := fs.String("manifest", "", "package manifest path (default: <project>/package.json)")
+	lockfile := fs.String("lockfile", "", "lockfile path (default: <project>/scriptgo-lock.json)")
+	store := fs.String("store", "", "content store path (default: <project>/.scriptgo/store)")
+	registry := fs.String("registry", "", "npm-compatible registry URL")
+	token := fs.String("registry-token", "", "registry bearer token (default: SCRIPTGO_NPM_TOKEN or NPM_TOKEN)")
+	dev := fs.Bool("dev", false, "save package to devDependencies")
+	fs.BoolVar(dev, "D", false, "save package to devDependencies (shorthand)")
+	optional := fs.Bool("optional", false, "save package to optionalDependencies")
+	fs.BoolVar(optional, "O", false, "save package to optionalDependencies (shorthand)")
+	peer := fs.Bool("peer", false, "save package to peerDependencies")
+	exact := fs.Bool("exact", false, "save exact version instead of ^x.y.z")
+	fs.BoolVar(exact, "E", false, "save exact version instead of ^x.y.z (shorthand)")
+	offline := fs.Bool("offline", false, "install only from the existing lockfile and content store")
+
+	if err := fs.Parse(args); err != nil {
+		if err == flag.ErrHelp {
+			os.Exit(0)
+		}
+		os.Exit(2)
+	}
+
+	depCount := 0
+	if *dev {
+		depCount++
+	}
+	if *optional {
+		depCount++
+	}
+	if *peer {
+		depCount++
+	}
+	if depCount > 1 {
+		fmt.Fprintf(os.Stderr, "scriptgo add: --dev, --optional, and --peer are mutually exclusive\n")
+		os.Exit(2)
+	}
+
+	packages := fs.Args()
+	if len(packages) == 0 {
+		fmt.Fprintf(os.Stderr, "scriptgo add: at least one package must be specified\n\n")
+		printAddUsage()
+		os.Exit(2)
+	}
+
+	depType := pkgmgr.DepTypeRegular
+	if *dev {
+		depType = pkgmgr.DepTypeDev
+	} else if *optional {
+		depType = pkgmgr.DepTypeOptional
+	} else if *peer {
+		depType = pkgmgr.DepTypePeer
+	}
+
+	root, err := filepath.Abs(*project)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "scriptgo: %v\n", err)
+		os.Exit(1)
+	}
+
+	result, err := pkgmgr.Add(pkgmgr.AddOptions{
+		ProjectRoot:  root,
+		Manifest:     *manifest,
+		Lockfile:     *lockfile,
+		StoreRoot:    *store,
+		Registry:     pkgmgr.Registry{BaseURL: *registry, Token: *token},
+		Dependencies: packages,
+		DepType:      depType,
+		Exact:        *exact,
+		Offline:      *offline,
+	})
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "scriptgo add: %v\n", err)
+		os.Exit(1)
+	}
+
+	if len(result.Added) == 1 {
+		for name, spec := range result.Added {
+			fmt.Fprintf(os.Stdout, "added %s@%s, installed %d packages\n", name, spec, len(result.Lockfile.Packages))
+		}
+	} else {
+		fmt.Fprintf(os.Stdout, "added %d packages, installed %d packages\n", len(result.Added), len(result.Lockfile.Packages))
+	}
+}
+
+// normalizeFlagsFirstForAdd moves flags to the front so that positional packages
+// can appear before, after, or between flags.
+func normalizeFlagsFirstForAdd(args []string) []string {
+	var flags []string
+	var positionals []string
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		if strings.HasPrefix(arg, "-") {
+			flags = append(flags, arg)
+			if (arg == "-project" || arg == "--project" || arg == "-manifest" || arg == "--manifest" ||
+				arg == "-lockfile" || arg == "--lockfile" || arg == "-store" || arg == "--store" ||
+				arg == "-registry" || arg == "--registry" || arg == "-registry-token" || arg == "--registry-token") &&
+				i+1 < len(args) && !strings.HasPrefix(args[i+1], "-") {
+				i++
+				flags = append(flags, args[i])
+			}
+		} else {
+			positionals = append(positionals, arg)
+		}
+	}
+	return append(flags, positionals...)
+}
diff --git a/cmd/scriptgo/usage.go b/cmd/scriptgo/usage.go
index e22ce8b..d943f5a 100644
--- a/cmd/scriptgo/usage.go
+++ b/cmd/scriptgo/usage.go
@@ -6,10 +6,16 @@ import (
 )
 
 func printMainUsage() {
-	fmt.Fprintln(os.Stderr, `ScriptGo - TypeScript Native Compiler
+	prog := getProgramName()
+	fmt.Fprintf(os.Stderr, `ScriptGo - TypeScript Native Compiler
 
 Usage:
-  scriptgo <command> [flags] <arguments>
+  %[1]s [flags] <entry.ts> [-- <args...>]
+  %[1]s [flags] -e "<code string>" [-- <args...>]
+  %[1]s <command> [flags] <arguments>
+
+Alias:
+  scg (can be used interchangeably with scriptgo)
 
 Commands:
   run       Run a package.json script or compile and execute a TypeScript program
@@ -18,10 +24,11 @@ Commands:
   emit      Emit LLVM IR or Typed IR
   coverage  Analyze Static/Dynamic site coverage
   init      Initialize a new ScriptGo TypeScript project
+  add       Add dependencies to package.json and install them
   install   Resolve, verify, cache, and link package.json dependencies
   task      Run a package.json script with node_modules/.bin in PATH
   version   Print compiler and runtime ABI version
-  help      Show help for ScriptGo or a specific command
+  help      Show help for %[1]s or a specific command
 
 Global Flags:
   -v                     Verbose output
@@ -45,7 +52,7 @@ Global Flags:
   --store <path>         Content store path with --install
   -h, --help             Show help message
 
-Use 'scriptgo help <command>' or 'scriptgo <command> --help' for detailed command usage.`)
+Use '%[1]s help <command>' or '%[1]s <command> --help' for detailed command usage.`, prog)
 }
 
 func printTaskUsage() {
@@ -89,6 +96,37 @@ Examples:
   scriptgo init -f`)
 }
 
+func printAddUsage() {
+	fmt.Fprintln(os.Stderr, `Usage:
+  scriptgo add [flags] <package...>
+
+Description:
+  Resolves package versions from an npm-compatible registry or local workspace,
+  records them in package.json, and installs them into node_modules and
+  scriptgo-lock.json.
+
+Flags:
+  --project <dir>       Project directory containing package.json (default: .)
+  --manifest <path>     package.json path (default: <project>/package.json)
+  --lockfile <path>     Lockfile path (default: <project>/scriptgo-lock.json)
+  --store <path>        Content store path (default: <project>/.scriptgo/store)
+  --registry <url>      npm-compatible registry URL
+  --registry-token <t>  registry bearer token (or SCRIPTGO_NPM_TOKEN/NPM_TOKEN)
+  -D, --dev             Add to devDependencies
+  -O, --optional        Add to optionalDependencies
+  --peer                Add to peerDependencies
+  -E, --exact           Save exact version instead of ^x.y.z
+  --offline             Use only cached tarballs and lockfile
+  -h, --help            Show this help message
+
+Examples:
+  scriptgo add lodash
+  scriptgo add chalk@4.1.2
+  scriptgo add -D typescript @types/node
+  scriptgo add -E express
+  scriptgo add --optional redis`)
+}
+
 func printInstallUsage() {
 	fmt.Fprintln(os.Stderr, `Usage:
   scriptgo install [flags]
@@ -111,10 +149,13 @@ Flags:
 }
 
 func printRunUsage() {
-	fmt.Fprintln(os.Stderr, `Usage:
-  scriptgo run [<script>] [-- <args...>]
-  scriptgo run [flags] <entry.ts> [-- <args...>]
-  scriptgo run [flags] -e "<code string>" [-- <args...>]
+	prog := getProgramName()
+	fmt.Fprintf(os.Stderr, `Usage:
+  %[1]s [flags] <entry.ts> [-- <args...>]
+  %[1]s [flags] -e "<code string>" [-- <args...>]
+  %[1]s run [<script>] [-- <args...>]
+  %[1]s run [flags] <entry.ts> [-- <args...>]
+  %[1]s run [flags] -e "<code string>" [-- <args...>]
 
 Description:
   Runs a package.json script with ancestor node_modules/.bin in PATH, or
@@ -122,7 +163,7 @@ Description:
   binary directly on host.
 
 Flags:
-  -e <string>            Evaluate inline script string
+  -e, --eval <string>    Evaluate inline script string
   -m, --ffi-manifest     Path to FFI JSON metadata manifest (*.ffi.json)
   -v                     Verbose output (print compilation stages)
   --target <triple>      Target architecture triple (default: $SCRIPTGO_TARGET or native)
@@ -145,13 +186,15 @@ Flags:
   -h, --help             Show this help message
 
 Examples:
-  scriptgo run app.ts
-  scriptgo run -e "console.log('hello ' + 42)"
-  scriptgo run -e "console.log(100 * 20)"
-  scriptgo run app.ts --ffi-manifest mylib.ffi.json
-  scriptgo run app.ts helper.c
-  scriptgo run --cc "zig cc" app.ts
-  scriptgo run app.ts -- arg1 arg2`)
+  %[1]s app.ts
+  %[1]s -e "console.log('hello ' + 42)"
+  %[1]s run app.ts
+  %[1]s run -e "console.log(100 * 20)"
+  %[1]s run app.ts --ffi-manifest mylib.ffi.json
+  %[1]s run app.ts helper.c
+  %[1]s run --cc "zig cc" app.ts
+  %[1]s run app.ts -- arg1 arg2
+`, prog)
 }
 
 func printBuildUsage() {
diff --git a/docs/package-manager-architecture.md b/docs/package-manager-architecture.md
index 7cd25de..c30a9e6 100644
--- a/docs/package-manager-architecture.md
+++ b/docs/package-manager-architecture.md
@@ -418,6 +418,8 @@ contract rather than add a second resolver:
    manifest/resolver/lockfile contract is implemented in `internal/pkgmgr`.
 2. **Package Service**: Extend that focused package with registry, SemVer,
    integrity, CAS, and link behavior; `cmd/scriptgo` remains a thin caller.
-3. **Builtin Commands**: `scriptgo install` is exposed for production dependency
+3. **Builtin Commands**: `scriptgo install` is exposed for dependency
    installation and its output is consumed directly by the existing
-   TypeScript-Go/Dynamic compilation path. `scriptgo add` remains deferred.
+   TypeScript-Go/Dynamic compilation path. `scriptgo add` resolves package
+   versions from registries or local workspaces, records them into `package.json`,
+   and triggers deterministic installation.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 6bf95f9..28bc5b8 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -248,6 +248,16 @@ and declare local workspace packages through standard `workspaces` patterns.
 `workspace:` protocol edges resolve to local source directories and are recorded
 in the existing lockfile graph without introducing a second module resolver.
 
+#### 8G: Package Addition (scriptgo add) (Completed)
+
+`scriptgo add` resolves package versions from an npm-compatible registry or local
+workspaces, records them into `package.json` (`dependencies`, `devDependencies`,
+`optionalDependencies`, or `peerDependencies`), preserves formatting and top-level
+key ordering, and triggers deterministic installation into `node_modules` and
+`scriptgo-lock.json`. Supports `-D`/`--dev`, `-O`/`--optional`, `--peer`, and `-E`/`--exact`.
+If installation fails, `package.json` is rolled back atomically.
+
+
 ### Node.js And npm Compatibility Track
 
 This track is the long-term product direction. It must be implemented in
diff --git a/docs/typescript-parity-report.md b/docs/typescript-parity-report.md
index e4b1e9d..3f75c94 100644
--- a/docs/typescript-parity-report.md
+++ b/docs/typescript-parity-report.md
@@ -349,8 +349,10 @@ Below is the detailed audit of all TypeScript/ECMAScript Abstract Syntax Tree (A
 | Ecosystem Feature | Current Status in ScriptGo | Target Roadmap |
 | :--- | :---: | :--- |
 | **NPM Packages (`node_modules`)** | ⚠️ Installable and executable Dynamic slice | `scriptgo install` resolves production dependencies from an npm-compatible registry, selects deterministic SemVer versions, verifies SHA-512 SRI tarballs, caches immutable content, writes root dependency metadata to `scriptgo-lock.json`, and atomically projects an isolated nested `node_modules` graph. Optional dependencies, peer metadata/auto-install, package-configured bearer auth, `.bin` links, workspace packages, conflicting versions, and offline/frozen drift checks are supported. Lifecycle scripts and native addons remain unsupported; installed graphs execute through the existing TypeScript-Go/Dynamic path. |
+| **Package Management (`scriptgo add`)** | ✅ Full | `scriptgo add [flags] <pkg...>` resolves latest/matching versions from npm registry or workspace, records dependencies into `package.json` (`dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`), preserves key ordering and JSON formatting, and executes deterministic install with atomic rollback on failure. |
 | **Project Scaffolding (`scriptgo init`)** | ✅ Full | `scriptgo init [<dir>] [-y] [-f] [--name <name>]` scaffolds a new TypeScript project with standard `package.json` (`start`, `build`, `check`, `coverage`), `tsconfig.json`, `index.ts`, and `.gitignore`. |
 | **Task Runner (`package.json` scripts)** | ✅ Full | `scriptgo task [name] [-- <args>]` runs user-defined scripts from `package.json` with ancestor `node_modules/.bin` prepended to `PATH`, argument forwarding, and exact exit-code propagation; running `scriptgo task` without arguments lists available scripts; `scriptgo run <cmd>` prioritizes user scripts defined in `package.json` before falling back to local source file execution. Lifecycle scripts (`preinstall`/`postinstall`) remain deliberately unexecuted for security. |
+| **Direct Execution & CLI Alias (`scg`)** | ✅ Full | Direct script execution (`scriptgo file.ts`, `scg file.ts`), inline evaluation (`scriptgo -e "code"`, `scg -e "code"`), flag forwarding, and `scg` binary alias supported interchangeably across all subcommands (`scg run`, `scg build`, `scg check`, `scg add`, `scg install`, etc.). |
 | **CommonJS (`require` / `module.exports`)** | ⚠️ Synchronous graph slice | Local packages support dependency-resolved `require`, `exports.foo`, `module.exports`, named/default ESM imports of CommonJS, and synchronous CommonJS-to-ESM namespace access. Unresolved runtime-generated specifiers and lifecycle behavior remain unsupported. |
 | **Dynamic compatibility (`--dynamic`)** | ✅ Full (Milestone 8) | Mode plumbing, tier analysis, Dynamic IR, canonical boxed values, bounded `any` interoperability, persistent QuickJS-ng execution, module caching, re-exports, ESM/CommonJS graph execution, native closure callbacks passed into Dynamic functions, bounded synchronous Dynamic function handles, receiver-preserving method calls, immediate Promise/microtask settlement, and host-job timer event loop integration across the native ABI are implemented. |
 
@@ -447,7 +449,7 @@ Below is the detailed audit of all TypeScript/ECMAScript Abstract Syntax Tree (A
 | Track | Status | Roadmap Alignment |
 | :--- | :---: | :--- |
 | Timers, streams, EventEmitter, fetch, and core networking | ✅ Implemented | Delivered as part of the post-MVP language/runtime and standard-library expansion. |
-| npm and Node package resolution | ⚠️ Installable Dynamic slice | `scriptgo install` provides registry metadata/tarball resolution, SemVer selection, conflicting-version graph isolation, optional dependency handling, peer auto-install/validation, package-configured bearer auth, workspace protocol linking, SRI verification, CAS storage, hardlink projection, and offline/frozen lockfile installs; `scriptgo task` / `scriptgo run <script>` runs package scripts with ancestor `.bin` PATH; lifecycle scripts and native addons remain unsupported. |
+| npm and Node package resolution | ⚠️ Installable Dynamic slice | `scriptgo add` adds dependencies to `package.json` with SemVer/workspace resolution; `scriptgo install` provides registry metadata/tarball resolution, SemVer selection, conflicting-version graph isolation, optional dependency handling, peer auto-install/validation, package-configured bearer auth, workspace protocol linking, SRI verification, CAS storage, hardlink projection, and offline/frozen lockfile installs; `scriptgo task` / `scriptgo run <script>` runs package scripts with ancestor `.bin` PATH; lifecycle scripts and native addons remain unsupported. |
 | Dynamic islands with QuickJS-ng | ✅ Implemented | Local named/default-import synchronous functions, bounded `any`, persistent module state, re-exports, ESM/CommonJS dependency graphs, and async Promise timers execute through QuickJS-ng; all-Static builds remain engine-free. |
 | Dynamic ABI and executable boundary parity tests | ✅ Boundary parity | Canonical boxed layout, exceptions, persistent module initialization, dependency caching, ESM/CommonJS interop, plain object/array boundaries, native callbacks, returned function handles, receiver-preserving methods, immediate Promise fulfillment/rejection, timer host jobs, and pending host-job rejection with `SG5004` are covered. |
 | Native WebSocket engine | ✅ Implemented | RFC 6455 compliant native client linked into runtime with framing, handshake, ping/pong, and event loop dispatch. |
diff --git a/internal/pkgmgr/add.go b/internal/pkgmgr/add.go
new file mode 100644
index 0000000..2206ade
--- /dev/null
+++ b/internal/pkgmgr/add.go
@@ -0,0 +1,412 @@
+package pkgmgr
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// DependencyType indicates which dependency field in package.json to populate.
+type DependencyType int
+
+const (
+	DepTypeRegular DependencyType = iota
+	DepTypeDev
+	DepTypeOptional
+	DepTypePeer
+)
+
+// AddOptions specifies packages and target configuration for scriptgo add.
+type AddOptions struct {
+	ProjectRoot  string
+	Manifest     string
+	Lockfile     string
+	StoreRoot    string
+	Registry     Registry
+	Dependencies []string
+	DepType      DependencyType
+	Exact        bool
+	Offline      bool
+}
+
+// AddResult contains metadata about the added packages and resulting lockfile.
+type AddResult struct {
+	Added    map[string]string // packageName -> recordedSpec
+	Lockfile Lockfile
+}
+
+// ParsePackageSpec splits a package specification string into its package name
+// and version/range constraint.
+// Supports:
+//   - "lodash" -> ("lodash", "")
+//   - "lodash@^4.17.21" -> ("lodash", "^4.17.21")
+//   - "lodash@4.17.21" -> ("lodash", "4.17.21")
+//   - "@types/node" -> ("@types/node", "")
+//   - "@types/node@20.0.0" -> ("@types/node", "20.0.0")
+//   - "shared@workspace:*" -> ("shared", "workspace:*")
+func ParsePackageSpec(raw string) (string, string, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return "", "", fmt.Errorf("empty package specification")
+	}
+	var name, spec string
+	if strings.HasPrefix(raw, "@") {
+		idx := strings.Index(raw[1:], "@")
+		if idx != -1 {
+			name = raw[:idx+1]
+			spec = strings.TrimSpace(raw[idx+2:])
+		} else {
+			name = raw
+		}
+	} else {
+		idx := strings.Index(raw, "@")
+		if idx != -1 {
+			name = raw[:idx]
+			spec = strings.TrimSpace(raw[idx+1:])
+		} else {
+			name = raw
+		}
+	}
+	if !validPackageName(name) {
+		return "", "", fmt.Errorf("invalid package name %q", name)
+	}
+	return name, spec, nil
+}
+
+// Add resolves new dependency versions, updates package.json, and executes
+// a deterministic Install to project node_modules and scriptgo-lock.json.
+// If installation fails, package.json is rolled back.
+func Add(options AddOptions) (AddResult, error) {
+	if len(options.Dependencies) == 0 {
+		return AddResult{}, fmt.Errorf("no package specified to add")
+	}
+	root, err := filepath.Abs(options.ProjectRoot)
+	if err != nil {
+		return AddResult{}, fmt.Errorf("resolve project root: %w", err)
+	}
+	manifestPath := options.Manifest
+	if manifestPath == "" {
+		manifestPath = filepath.Join(root, "package.json")
+	}
+	originalContent, err := os.ReadFile(manifestPath)
+	if err != nil {
+		return AddResult{}, fmt.Errorf("read package manifest %q: %w", manifestPath, err)
+	}
+
+	manifest, err := LoadProjectManifest(manifestPath)
+	if err != nil {
+		return AddResult{}, err
+	}
+	if manifest.Scriptgo.RegistryToken != "" {
+		return AddResult{}, fmt.Errorf("package manifest must not contain a registry token; use registryTokenEnv or --registry-token")
+	}
+
+	var rawMap map[string]any
+	if err := json.Unmarshal(originalContent, &rawMap); err != nil {
+		return AddResult{}, fmt.Errorf("parse package manifest %q: %w", manifestPath, err)
+	}
+
+	workspaces, err := discoverWorkspaces(root, manifest.Workspaces)
+	if err != nil {
+		return AddResult{}, err
+	}
+
+	registry := options.Registry
+	if registry.BaseURL == "" {
+		registry.BaseURL = manifest.Scriptgo.Registry
+	}
+	if registry.Token == "" && manifest.Scriptgo.RegistryTokenEnv != "" {
+		registry.Token = os.Getenv(manifest.Scriptgo.RegistryTokenEnv)
+	}
+
+	lockPath := options.Lockfile
+	if lockPath == "" {
+		lockPath = filepath.Join(root, "scriptgo-lock.json")
+	}
+
+	var locked Lockfile
+	if options.Offline {
+		locked, err = LoadLockfile(lockPath)
+		if err != nil {
+			return AddResult{}, fmt.Errorf("lockfile required for offline add: %w", err)
+		}
+	}
+
+	resolvedSpecs := make(map[string]string, len(options.Dependencies))
+	for _, rawSpec := range options.Dependencies {
+		name, spec, err := ParsePackageSpec(rawSpec)
+		if err != nil {
+			return AddResult{}, err
+		}
+
+		recordedSpec, err := resolveAddSpec(name, spec, options, registry, workspaces, locked)
+		if err != nil {
+			return AddResult{}, err
+		}
+		resolvedSpecs[name] = recordedSpec
+	}
+
+	sectionName := "dependencies"
+	switch options.DepType {
+	case DepTypeDev:
+		sectionName = "devDependencies"
+	case DepTypeOptional:
+		sectionName = "optionalDependencies"
+	case DepTypePeer:
+		sectionName = "peerDependencies"
+	}
+
+	allSections := []string{"dependencies", "devDependencies", "optionalDependencies", "peerDependencies"}
+	for _, sec := range allSections {
+		if sec != sectionName {
+			if secMap, ok := rawMap[sec].(map[string]any); ok {
+				for name := range resolvedSpecs {
+					delete(secMap, name)
+				}
+			}
+		}
+	}
+
+	var targetSection map[string]any
+	if existing, ok := rawMap[sectionName].(map[string]any); ok {
+		targetSection = existing
+	} else {
+		targetSection = map[string]any{}
+		rawMap[sectionName] = targetSection
+	}
+	for name, spec := range resolvedSpecs {
+		targetSection[name] = spec
+	}
+
+	topLevelKeys := getTopLevelKeyOrder(originalContent)
+	topLevelKeys = insertDependencyKey(topLevelKeys, sectionName)
+
+	newContent, err := formatPackageJSON(rawMap, topLevelKeys)
+	if err != nil {
+		return AddResult{}, fmt.Errorf("format updated package.json: %w", err)
+	}
+
+	if err := os.WriteFile(manifestPath, newContent, 0o644); err != nil {
+		return AddResult{}, fmt.Errorf("write updated package.json: %w", err)
+	}
+
+	lock, err := Install(InstallOptions{
+		ProjectRoot: root,
+		Manifest:    manifestPath,
+		Lockfile:    lockPath,
+		StoreRoot:   options.StoreRoot,
+		Registry:    registry,
+		Offline:     options.Offline,
+		Frozen:      false,
+	})
+	if err != nil {
+		_ = os.WriteFile(manifestPath, originalContent, 0o644)
+		return AddResult{}, fmt.Errorf("install after add: %w", err)
+	}
+
+	return AddResult{
+		Added:    resolvedSpecs,
+		Lockfile: lock,
+	}, nil
+}
+
+func resolveAddSpec(name, spec string, options AddOptions, registry Registry, workspaces map[string]workspacePackage, locked Lockfile) (string, error) {
+	// Workspace package resolution
+	if workspace, ok := workspaces[name]; ok {
+		if strings.HasPrefix(spec, "workspace:") {
+			return spec, nil
+		}
+		if spec == "" {
+			if options.Exact {
+				return "workspace:" + workspace.Manifest.Version, nil
+			}
+			return "workspace:*", nil
+		}
+	}
+	if strings.HasPrefix(spec, "workspace:") {
+		return "", fmt.Errorf("workspace package %q not found", name)
+	}
+
+	// Registry package resolution
+	if options.Offline {
+		if lockedPkg, ok := locked.Packages[name]; ok && lockedPkg.Version != "" {
+			if spec == "" {
+				if options.Exact {
+					return lockedPkg.Version, nil
+				}
+				return "^" + lockedPkg.Version, nil
+			}
+			return spec, nil
+		}
+		return "", fmt.Errorf("offline add: package %q not found in lockfile", name)
+	}
+
+	meta, err := registry.FetchPackageMetadata(name)
+	if err != nil {
+		return "", err
+	}
+
+	candidates := make([]Version, 0, len(meta.Versions))
+	for vText := range meta.Versions {
+		if v, parseErr := ParseVersion(vText); parseErr == nil {
+			candidates = append(candidates, v)
+		}
+	}
+	if len(candidates) == 0 {
+		return "", fmt.Errorf("package %q has no valid semver versions in registry", name)
+	}
+
+	if spec != "" {
+		hasRangePrefix := strings.HasPrefix(spec, "^") || strings.HasPrefix(spec, "~") ||
+			strings.HasPrefix(spec, ">") || strings.HasPrefix(spec, "<") ||
+			strings.HasPrefix(spec, "=") || strings.Contains(spec, "||")
+		if hasRangePrefix {
+			if _, err := SelectVersion(spec, candidates); err != nil {
+				return "", fmt.Errorf("no version in registry satisfies %q for package %q: %w", spec, name, err)
+			}
+			return spec, nil
+		}
+		// Exact version like "4.17.21"
+		v, parseErr := ParseVersion(spec)
+		if parseErr != nil {
+			return "", fmt.Errorf("invalid version %q for package %q: %w", spec, name, parseErr)
+		}
+		found := false
+		for _, c := range candidates {
+			if CompareVersions(c, v) == 0 {
+				found = true
+				break
+			}
+		}
+		if !found {
+			return "", fmt.Errorf("version %q for package %q not found in registry", spec, name)
+		}
+		if options.Exact {
+			return v.String(), nil
+		}
+		return "^" + v.String(), nil
+	}
+
+	// spec is empty: choose latest
+	var targetVer Version
+	if tag, ok := meta.DistTags["latest"]; ok && tag != "" {
+		if v, parseErr := ParseVersion(tag); parseErr == nil {
+			targetVer = v
+		}
+	}
+	if targetVer == (Version{}) {
+		highest, selErr := SelectVersion("*", candidates)
+		if selErr != nil {
+			return "", fmt.Errorf("select highest version for %q: %w", name, selErr)
+		}
+		targetVer = highest
+	}
+	if options.Exact {
+		return targetVer.String(), nil
+	}
+	return "^" + targetVer.String(), nil
+}
+
+func getTopLevelKeyOrder(data []byte) []string {
+	dec := json.NewDecoder(bytes.NewReader(data))
+	t, err := dec.Token()
+	if err != nil || t != json.Delim('{') {
+		return nil
+	}
+	var keys []string
+	for dec.More() {
+		t, err := dec.Token()
+		if err != nil {
+			break
+		}
+		if key, ok := t.(string); ok {
+			keys = append(keys, key)
+			var v json.RawMessage
+			if err := dec.Decode(&v); err != nil {
+				break
+			}
+		}
+	}
+	return keys
+}
+
+func insertDependencyKey(keys []string, keyToInsert string) []string {
+	for _, k := range keys {
+		if k == keyToInsert {
+			return keys
+		}
+	}
+	order := []string{
+		"name", "version", "private", "description", "type", "main", "module",
+		"types", "exports", "bin", "scripts", "workspaces",
+		"dependencies", "devDependencies", "peerDependencies", "optionalDependencies",
+	}
+	targetIdx := -1
+	for i, o := range order {
+		if o == keyToInsert {
+			targetIdx = i
+			break
+		}
+	}
+	if targetIdx == -1 {
+		return append(keys, keyToInsert)
+	}
+
+	insertAfter := -1
+	for i := targetIdx - 1; i >= 0; i-- {
+		prev := order[i]
+		for j, k := range keys {
+			if k == prev {
+				insertAfter = j
+				break
+			}
+		}
+		if insertAfter != -1 {
+			break
+		}
+	}
+	if insertAfter != -1 {
+		res := make([]string, 0, len(keys)+1)
+		res = append(res, keys[:insertAfter+1]...)
+		res = append(res, keyToInsert)
+		res = append(res, keys[insertAfter+1:]...)
+		return res
+	}
+	return append(keys, keyToInsert)
+}
+
+func formatPackageJSON(rawMap map[string]any, keys []string) ([]byte, error) {
+	var activeKeys []string
+	for _, k := range keys {
+		if rawMap[k] != nil {
+			activeKeys = append(activeKeys, k)
+		}
+	}
+
+	var b bytes.Buffer
+	b.WriteString("{\n")
+	for i, key := range activeKeys {
+		val := rawMap[key]
+		keyBytes, err := json.Marshal(key)
+		if err != nil {
+			return nil, err
+		}
+		valBytes, err := json.MarshalIndent(val, "  ", "  ")
+		if err != nil {
+			return nil, err
+		}
+		b.WriteString("  ")
+		b.Write(keyBytes)
+		b.WriteString(": ")
+		b.Write(valBytes)
+		if i < len(activeKeys)-1 {
+			b.WriteString(",")
+		}
+		b.WriteString("\n")
+	}
+	b.WriteString("}\n")
+	return b.Bytes(), nil
+}
diff --git a/internal/pkgmgr/add_test.go b/internal/pkgmgr/add_test.go
new file mode 100644
index 0000000..db0d5f6
--- /dev/null
+++ b/internal/pkgmgr/add_test.go
@@ -0,0 +1,285 @@
+package pkgmgr
+
+import (
+	"crypto/sha512"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestParsePackageSpec(t *testing.T) {
+	tests := []struct {
+		raw      string
+		wantName string
+		wantSpec string
+		wantErr  bool
+	}{
+		{raw: "lodash", wantName: "lodash", wantSpec: ""},
+		{raw: "lodash@^4.17.21", wantName: "lodash", wantSpec: "^4.17.21"},
+		{raw: "lodash@4.17.21", wantName: "lodash", wantSpec: "4.17.21"},
+		{raw: "lodash@~4.17.0", wantName: "lodash", wantSpec: "~4.17.0"},
+		{raw: "@types/node", wantName: "@types/node", wantSpec: ""},
+		{raw: "@types/node@20.0.0", wantName: "@types/node", wantSpec: "20.0.0"},
+		{raw: "@types/node@^20.0.0", wantName: "@types/node", wantSpec: "^20.0.0"},
+		{raw: "shared@workspace:*", wantName: "shared", wantSpec: "workspace:*"},
+		{raw: "shared@workspace:^", wantName: "shared", wantSpec: "workspace:^"},
+		{raw: "", wantErr: true},
+		{raw: "   ", wantErr: true},
+		{raw: "foo/bar", wantErr: true},
+		{raw: "@scope", wantErr: true},
+		{raw: "foo\\bar", wantErr: true},
+	}
+
+	for _, tt := range tests {
+		name, spec, err := ParsePackageSpec(tt.raw)
+		if tt.wantErr {
+			if err == nil {
+				t.Errorf("ParsePackageSpec(%q) expected error, got nil", tt.raw)
+			}
+			continue
+		}
+		if err != nil {
+			t.Errorf("ParsePackageSpec(%q) unexpected error: %v", tt.raw, err)
+			continue
+		}
+		if name != tt.wantName || spec != tt.wantSpec {
+			t.Errorf("ParsePackageSpec(%q) = (%q, %q), want (%q, %q)", tt.raw, name, spec, tt.wantName, tt.wantSpec)
+		}
+	}
+}
+
+func TestAdd_RegistryPackage(t *testing.T) {
+	archive := testPackageArchive(t, "index.js", "module.exports = 'from-registry';\n")
+	digest := sha512.Sum512(archive)
+	integrity := "sha512-" + base64.StdEncoding.EncodeToString(digest[:])
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+		if request.URL.Path == "/demo" {
+			tarball := "http://" + request.Host + "/demo/-/demo.tgz"
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"dist-tags": map[string]string{"latest": "1.2.3"},
+				"versions": map[string]any{
+					"1.2.3": map[string]any{"name": "demo", "version": "1.2.3", "dist": map[string]string{"tarball": tarball, "integrity": integrity}},
+				},
+			})
+			return
+		}
+		if request.URL.Path == "/demo/-/demo.tgz" {
+			_, _ = w.Write(archive)
+			return
+		}
+		http.NotFound(w, request)
+	}))
+	defer server.Close()
+
+	root := t.TempDir()
+	initialManifest := `{
+  "name": "test-app",
+  "version": "1.0.0",
+  "scripts": {
+    "start": "scriptgo run index.ts"
+  }
+}`
+	if err := os.WriteFile(filepath.Join(root, "package.json"), []byte(initialManifest), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := Add(AddOptions{
+		ProjectRoot:  root,
+		Dependencies: []string{"demo"},
+		Registry:     Registry{BaseURL: server.URL},
+	})
+	if err != nil {
+		t.Fatalf("Add failed: %v", err)
+	}
+
+	if result.Added["demo"] != "^1.2.3" {
+		t.Fatalf("expected demo@^1.2.3, got: %s", result.Added["demo"])
+	}
+
+	manifestBytes, err := os.ReadFile(filepath.Join(root, "package.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var manifest PackageManifest
+	if err := json.Unmarshal(manifestBytes, &manifest); err != nil {
+		t.Fatalf("invalid package.json JSON: %v", err)
+	}
+	if manifest.Dependencies["demo"] != "^1.2.3" {
+		t.Fatalf("package.json dependencies[demo] = %q, want ^1.2.3", manifest.Dependencies["demo"])
+	}
+
+	linked, err := os.ReadFile(filepath.Join(root, "node_modules", "demo", "index.js"))
+	if err != nil {
+		t.Fatalf("node_modules/demo/index.js missing: %v", err)
+	}
+	if string(linked) != "module.exports = 'from-registry';\n" {
+		t.Fatalf("unexpected node_modules content: %s", string(linked))
+	}
+
+	lockBytes, err := os.ReadFile(filepath.Join(root, "scriptgo-lock.json"))
+	if err != nil {
+		t.Fatalf("scriptgo-lock.json missing: %v", err)
+	}
+	if !strings.Contains(string(lockBytes), "demo@1.2.3") {
+		t.Fatalf("lockfile missing demo@1.2.3: %s", string(lockBytes))
+	}
+}
+
+func TestAdd_ExactAndDevDependency(t *testing.T) {
+	archive := testPackageArchive(t, "index.js", "module.exports = 'exact';\n")
+	digest := sha512.Sum512(archive)
+	integrity := "sha512-" + base64.StdEncoding.EncodeToString(digest[:])
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+		if request.URL.Path == "/tool" {
+			tarball := "http://" + request.Host + "/tool/-/tool.tgz"
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"dist-tags": map[string]string{"latest": "2.0.0"},
+				"versions": map[string]any{
+					"2.0.0": map[string]any{"name": "tool", "version": "2.0.0", "dist": map[string]string{"tarball": tarball, "integrity": integrity}},
+				},
+			})
+			return
+		}
+		if request.URL.Path == "/tool/-/tool.tgz" {
+			_, _ = w.Write(archive)
+			return
+		}
+		http.NotFound(w, request)
+	}))
+	defer server.Close()
+
+	root := t.TempDir()
+	initialManifest := `{
+  "name": "test-dev-app",
+  "version": "1.0.0",
+  "dependencies": {
+    "tool": "^1.0.0"
+  }
+}`
+	if err := os.WriteFile(filepath.Join(root, "package.json"), []byte(initialManifest), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := Add(AddOptions{
+		ProjectRoot:  root,
+		Dependencies: []string{"tool"},
+		DepType:      DepTypeDev,
+		Exact:        true,
+		Registry:     Registry{BaseURL: server.URL},
+	})
+	if err != nil {
+		t.Fatalf("Add failed: %v", err)
+	}
+
+	if result.Added["tool"] != "2.0.0" {
+		t.Fatalf("expected exact version 2.0.0, got: %s", result.Added["tool"])
+	}
+
+	manifestBytes, err := os.ReadFile(filepath.Join(root, "package.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var manifest PackageManifest
+	if err := json.Unmarshal(manifestBytes, &manifest); err != nil {
+		t.Fatalf("invalid package.json JSON: %v", err)
+	}
+	if _, inDeps := manifest.Dependencies["tool"]; inDeps {
+		t.Fatalf("tool should have been removed from dependencies when added to devDependencies")
+	}
+	if manifest.DevDependencies["tool"] != "2.0.0" {
+		t.Fatalf("devDependencies[tool] = %q, want 2.0.0", manifest.DevDependencies["tool"])
+	}
+}
+
+func TestAdd_WorkspacePackage(t *testing.T) {
+	root := t.TempDir()
+	packagesDir := filepath.Join(root, "packages")
+	workspaceRoot := filepath.Join(packagesDir, "core")
+	if err := os.MkdirAll(workspaceRoot, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(workspaceRoot, "package.json"), []byte(`{"name":"@local/core","version":"3.4.5","main":"index.js"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(workspaceRoot, "index.js"), []byte("module.exports = 'core';\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	rootManifest := `{
+  "name": "mono-root",
+  "workspaces": ["packages/*"]
+}`
+	if err := os.WriteFile(filepath.Join(root, "package.json"), []byte(rootManifest), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := Add(AddOptions{
+		ProjectRoot:  root,
+		Dependencies: []string{"@local/core"},
+	})
+	if err != nil {
+		t.Fatalf("Add workspace package failed: %v", err)
+	}
+
+	if result.Added["@local/core"] != "workspace:*" {
+		t.Fatalf("expected workspace:*, got: %s", result.Added["@local/core"])
+	}
+
+	linked, err := os.ReadFile(filepath.Join(root, "node_modules", "@local", "core", "index.js"))
+	if err != nil {
+		t.Fatalf("workspace package node_modules entry missing: %v", err)
+	}
+	if string(linked) != "module.exports = 'core';\n" {
+		t.Fatalf("unexpected content: %s", string(linked))
+	}
+}
+
+func TestAdd_RollbackOnFailure(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+		if request.URL.Path == "/failing" {
+			tarball := "http://" + request.Host + "/failing/-/failing.tgz"
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"dist-tags": map[string]string{"latest": "1.0.0"},
+				"versions": map[string]any{
+					"1.0.0": map[string]any{"name": "failing", "version": "1.0.0", "dist": map[string]string{"tarball": tarball, "integrity": "sha512-invalid"}},
+				},
+			})
+			return
+		}
+		// Return 404 for tarball
+		http.NotFound(w, request)
+	}))
+	defer server.Close()
+
+	root := t.TempDir()
+	originalManifest := `{
+  "name": "rollback-test",
+  "version": "1.0.0"
+}`
+	manifestPath := filepath.Join(root, "package.json")
+	if err := os.WriteFile(manifestPath, []byte(originalManifest), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := Add(AddOptions{
+		ProjectRoot:  root,
+		Dependencies: []string{"failing"},
+		Registry:     Registry{BaseURL: server.URL},
+	})
+	if err == nil {
+		t.Fatal("expected Add to fail due to missing tarball")
+	}
+
+	contentAfterFailure, err := os.ReadFile(manifestPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(contentAfterFailure) != originalManifest {
+		t.Fatalf("package.json was not rolled back!\nGot:\n%s\nWant:\n%s", string(contentAfterFailure), originalManifest)
+	}
+}
diff --git a/internal/pkgmgr/bins.go b/internal/pkgmgr/bins.go
new file mode 100644
index 0000000..d343ee4
--- /dev/null
+++ b/internal/pkgmgr/bins.go
@@ -0,0 +1,56 @@
+package pkgmgr
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+func linkBins(nodeModules string, nodes map[string]*packageNode, rootEdges map[string]string) error {
+	binDir := filepath.Join(nodeModules, ".bin")
+	for _, identity := range rootEdges {
+		node := nodes[identity]
+		if node == nil {
+			continue
+		}
+		for name, target := range node.Manifest.Bin {
+			if name == "" {
+				name = node.Name
+			}
+			if filepath.Base(name) != name || filepath.IsAbs(target) || strings.HasPrefix(filepath.Clean(filepath.FromSlash(target)), ".."+string(filepath.Separator)) {
+				return fmt.Errorf("invalid bin declaration for %s", node.Name)
+			}
+			if err := os.MkdirAll(binDir, 0o755); err != nil {
+				return err
+			}
+			if err := linkBin(binDir, name, node.Name, target); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func linkBin(binDir, name, packageName, target string) error {
+	linkTarget := filepath.Join("..", filepath.FromSlash(packageName), filepath.FromSlash(target))
+	if runtime.GOOS != "windows" {
+		if err := os.Symlink(linkTarget, filepath.Join(binDir, name)); err != nil {
+			return fmt.Errorf("link bin %s: %w", name, err)
+		}
+		return nil
+	}
+	cmdTarget := strings.ReplaceAll(linkTarget, "/", "\\")
+	relativeTarget := strings.TrimPrefix(cmdTarget, `..\`)
+	cmd := fmt.Sprintf("@echo off\r\n\"%%~dp0\\%s\" %%*\r\n", relativeTarget)
+	if err := os.WriteFile(filepath.Join(binDir, name+".cmd"), []byte(cmd), 0o755); err != nil {
+		return fmt.Errorf("write bin shim %s: %w", name, err)
+	}
+	powershellTarget := strings.ReplaceAll(relativeTarget, `\`, "/")
+	powershell := fmt.Sprintf("& (Join-Path $PSScriptRoot '%s') $args\r\n", powershellTarget)
+	if err := os.WriteFile(filepath.Join(binDir, name+".ps1"), []byte(powershell), 0o755); err != nil {
+		return fmt.Errorf("write PowerShell bin shim %s: %w", name, err)
+	}
+	return nil
+}
diff --git a/internal/pkgmgr/install.go b/internal/pkgmgr/install.go
index c82b63a..fd1d28d 100644
--- a/internal/pkgmgr/install.go
+++ b/internal/pkgmgr/install.go
@@ -11,7 +11,6 @@ import (
 	"io"
 	"os"
 	"path/filepath"
-	"runtime"
 	"strings"
 )
 
@@ -180,6 +179,13 @@ func Install(options InstallOptions) (Lockfile, error) {
 		}
 		rootEdges[name] = identity
 	}
+	for name, spec := range manifest.DevDependencies {
+		identity, resolveErr := resolve(name, spec, "")
+		if resolveErr != nil {
+			return Lockfile{}, resolveErr
+		}
+		rootEdges[name] = identity
+	}
 	for name, spec := range manifest.OptionalDependencies {
 		identity, resolveErr := resolve(name, spec, "")
 		if resolveErr == nil {
@@ -284,6 +290,7 @@ func peerCandidate(identity, name string, edges map[string]map[string]string, pa
 func graphLockfile(nodes map[string]*packageNode, project PackageManifest, autoPeers map[string]string, projectRoot string) Lockfile {
 	lock := Lockfile{LockfileVersion: 1, Project: LockfileProject{
 		Dependencies:         cloneStrings(project.Dependencies),
+		DevDependencies:      cloneStrings(project.DevDependencies),
 		OptionalDependencies: cloneStrings(project.OptionalDependencies),
 		PeerDependencies:     cloneStrings(project.PeerDependencies),
 		AutoPeers:            cloneStrings(autoPeers),
@@ -323,6 +330,7 @@ func cloneStrings(source map[string]string) map[string]string {
 
 func validateProjectLock(manifest PackageManifest, lock Lockfile) error {
 	if !equalStrings(manifest.Dependencies, lock.Project.Dependencies) ||
+		!equalStrings(manifest.DevDependencies, lock.Project.DevDependencies) ||
 		!equalStrings(manifest.OptionalDependencies, lock.Project.OptionalDependencies) ||
 		!equalStrings(manifest.PeerDependencies, lock.Project.PeerDependencies) {
 		return fmt.Errorf("frozen install rejected: project manifest dependencies differ from lockfile")
@@ -649,50 +657,3 @@ func linkTree(source, destination string) error {
 	}
 	return nil
 }
-
-func linkBins(nodeModules string, nodes map[string]*packageNode, rootEdges map[string]string) error {
-	binDir := filepath.Join(nodeModules, ".bin")
-	for _, identity := range rootEdges {
-		node := nodes[identity]
-		if node == nil {
-			continue
-		}
-		for name, target := range node.Manifest.Bin {
-			if name == "" {
-				name = node.Name
-			}
-			if filepath.Base(name) != name || filepath.IsAbs(target) || strings.HasPrefix(filepath.Clean(filepath.FromSlash(target)), ".."+string(filepath.Separator)) {
-				return fmt.Errorf("invalid bin declaration for %s", node.Name)
-			}
-			if err := os.MkdirAll(binDir, 0o755); err != nil {
-				return err
-			}
-			if err := linkBin(binDir, name, node.Name, target); err != nil {
-				return err
-			}
-		}
-	}
-	return nil
-}
-
-func linkBin(binDir, name, packageName, target string) error {
-	linkTarget := filepath.Join("..", filepath.FromSlash(packageName), filepath.FromSlash(target))
-	if runtime.GOOS != "windows" {
-		if err := os.Symlink(linkTarget, filepath.Join(binDir, name)); err != nil {
-			return fmt.Errorf("link bin %s: %w", name, err)
-		}
-		return nil
-	}
-	cmdTarget := strings.ReplaceAll(linkTarget, "/", "\\")
-	relativeTarget := strings.TrimPrefix(cmdTarget, `..\`)
-	cmd := fmt.Sprintf("@echo off\r\n\"%%~dp0\\%s\" %%*\r\n", relativeTarget)
-	if err := os.WriteFile(filepath.Join(binDir, name+".cmd"), []byte(cmd), 0o755); err != nil {
-		return fmt.Errorf("write bin shim %s: %w", name, err)
-	}
-	powershellTarget := strings.ReplaceAll(relativeTarget, `\`, "/")
-	powershell := fmt.Sprintf("& (Join-Path $PSScriptRoot '%s') $args\r\n", powershellTarget)
-	if err := os.WriteFile(filepath.Join(binDir, name+".ps1"), []byte(powershell), 0o755); err != nil {
-		return fmt.Errorf("write PowerShell bin shim %s: %w", name, err)
-	}
-	return nil
-}
diff --git a/internal/pkgmgr/lockfile.go b/internal/pkgmgr/lockfile.go
index ea812fb..e10ae07 100644
--- a/internal/pkgmgr/lockfile.go
+++ b/internal/pkgmgr/lockfile.go
@@ -15,6 +15,7 @@ type Lockfile struct {
 
 type LockfileProject struct {
 	Dependencies         map[string]string `json:"dependencies,omitempty"`
+	DevDependencies      map[string]string `json:"devDependencies,omitempty"`
 	OptionalDependencies map[string]string `json:"optionalDependencies,omitempty"`
 	PeerDependencies     map[string]string `json:"peerDependencies,omitempty"`
 	AutoPeers            map[string]string `json:"autoPeers,omitempty"`
diff --git a/internal/pkgmgr/registry.go b/internal/pkgmgr/registry.go
index 9e47432..6d8353a 100644
--- a/internal/pkgmgr/registry.go
+++ b/internal/pkgmgr/registry.go
@@ -30,21 +30,34 @@ func (r Registry) endpoint(name string) (string, error) {
 	return u.String(), nil
 }
 
-// FetchPackage returns all published versions for one package name.
-func (r Registry) FetchPackage(name string) (map[string]PackageManifest, error) {
+// PackageMetadata contains registry metadata for a package including dist-tags.
+type PackageMetadata struct {
+	Name     string                     `json:"name"`
+	DistTags map[string]string          `json:"dist-tags"`
+	Versions map[string]PackageManifest `json:"versions"`
+}
+
+// FetchPackageMetadata returns all published versions and dist-tags for one package name.
+func (r Registry) FetchPackageMetadata(name string) (PackageMetadata, error) {
 	endpoint, err := r.endpoint(name)
 	if err != nil {
-		return nil, err
-	}
-	var payload struct {
-		Name     string                     `json:"name"`
-		Versions map[string]PackageManifest `json:"versions"`
+		return PackageMetadata{}, err
 	}
+	var payload PackageMetadata
 	if err := r.getJSON(endpoint, &payload); err != nil {
-		return nil, fmt.Errorf("fetch package %q metadata: %w", name, err)
+		return PackageMetadata{}, fmt.Errorf("fetch package %q metadata: %w", name, err)
 	}
 	if len(payload.Versions) == 0 {
-		return nil, fmt.Errorf("registry returned no versions for %q", name)
+		return PackageMetadata{}, fmt.Errorf("registry returned no versions for %q", name)
+	}
+	return payload, nil
+}
+
+// FetchPackage returns all published versions for one package name.
+func (r Registry) FetchPackage(name string) (map[string]PackageManifest, error) {
+	payload, err := r.FetchPackageMetadata(name)
+	if err != nil {
+		return nil, err
 	}
 	return payload.Versions, nil
 }