Fix LiveSkills interactive installs

Author: Rowan Trollope

examples/liveskills/README.md

@@ -1,9 +1,9 @@
 # LiveSkills
 
-LiveSkills is an AFS-backed CLI for installing agent skills into the folders
-used by Codex, Claude Code, and other local agents.
+LiveSkills is a Go CLI example for installing agent skills into Codex, Claude
+Code, and other local agent skill folders through an AFS-backed registry model.
 
-The product direction is intentionally simple:
+The normal workflow is intentionally small:
 
 ```bash
 liveskills add <source-or-ref>
@@ -12,38 +12,36 @@ liveskills add -g <source-or-ref>
 liveskills list -g
 ```
 
-`add` is the happy path. It should register or version a skill in AFS when
-needed, then install it. Users should not need a separate `publish` step for
-normal installs.
-
-LiveSkills installs through the workspace-plus-symlink architecture: one
-mounted LiveSkills workspace per scope, with agent folders linked to the
-canonical skill copy by default.
+`add` is the happy path. It can take a local skill source and register it before
+installing, or it can install an existing registry reference such as
+`local/react-best-practices`. `publish`, `show`, and `download` remain available
+for explicit registry, debug, and export workflows.
 
 ## Quick Start
 
+Run these commands from this directory:
+
 ```bash
 make
-make install
-liveskills help
-go test ./...
-liveskills add ./examples/react-best-practices
-liveskills list
-liveskills add -g ./examples/react-best-practices
-liveskills list -g
+LIVESKILLS_AFS_MODE=local ./bin/liveskills help
+LIVESKILLS_AFS_MODE=local ./bin/liveskills add ./examples/react-best-practices --yes
+LIVESKILLS_AFS_MODE=local ./bin/liveskills list
+make test
 make surface-test
 ```
 
-LiveSkills uses the `afs` CLI when it is available. Set
-`LIVESKILLS_AFS_MODE=local` to use the local development stand-in instead.
+Use `LIVESKILLS_AFS_MODE=local` for isolated development. Without it,
+LiveSkills uses the `afs` CLI when it is available on `PATH`; if `afs` is not
+available, it falls back to the local adapter.
 
-Registry data and the local AFS staging area live under `~/.liveskills` by default. Set `LIVESKILLS_HOME` to isolate a run:
+Registry data and local AFS staging data live under `~/.liveskills` by default.
+Set `LIVESKILLS_HOME` to isolate a demo or test run:
 
 ```bash
-LIVESKILLS_HOME=/tmp/liveskills-demo go run . find
+LIVESKILLS_HOME=/tmp/liveskills-demo LIVESKILLS_AFS_MODE=local ./bin/liveskills list
 ```
 
-## Install
+## Build And Install
 
 Build the local binary:
 
@@ -57,121 +55,137 @@ Install it onto your command line:
 make install
 ```
 
-By default this installs `liveskills` to `~/.local/bin/liveskills`. Override the target with `BINDIR=/path/to/bin` or `PREFIX=/usr/local`:
+By default this installs `liveskills` to `~/.local/bin/liveskills`. Override the
+target with `BINDIR=/path/to/bin` or `PREFIX=/usr/local`:
 
 ```bash
 make install PREFIX=/usr/local
 ```
 
-## Full Surface Test
-
-Run the isolated CLI harness when changing command behavior:
+Other useful targets:
 
 ```bash
-make surface-test
+make test          # go test ./...
+make surface-test  # isolated end-to-end CLI harness
+make fmt           # gofmt -w *.go
+make clean         # remove bin/
 ```
 
-The harness builds a temporary `liveskills` binary, runs `go test ./...`, then
-uses isolated `HOME`, `LIVESKILLS_HOME`, and `LIVESKILLS_AFS_MODE=local` values
-to exercise the current Go command surface: auth, publish, find, show,
-download, add, list, update, remove, scan, project/global installs,
-agent-specific paths, validation errors, and deterministic stress coverage.
+## Current Install Model
 
-Use `--keep-temp` to inspect the generated project, home, store, and source
-fixtures after a run:
+Project installs are the default. Global installs use `-g` / `--global`.
 
-```bash
-python3 scripts/liveskills_surface_test.py --keep-temp --verbose
+For each scope, LiveSkills keeps a canonical skills workspace and installs one
+skill folder at a time from that canonical copy. Agent-facing skill folders are
+relative symlinks by default; `--copy` writes a standalone copy instead.
+
+```text
+<project>/.liveskills/mount/skills/<skill>  # project canonical copy
+<project>/.agents/skills/<skill>            # Codex/project universal target
+<project>/.claude/skills/<skill>            # Claude Code project target
+
+~/.liveskills/mount/skills/<skill>          # global canonical copy
+~/.codex/skills/<skill>                     # Codex global target
+~/.claude/skills/<skill>                    # Claude Code global target
 ```
 
-## Install Model
+LiveSkills owns only the specific installed skill folder. Neighboring manual
+skills under `.agents/skills`, `.claude/skills`, `~/.codex/skills`, or other
+agent folders must remain untouched.
 
-Project installs are the default. Global installs use `-g` / `--global`,
-matching the `skills` CLI scope model.
+## AFS Boundary
 
-LiveSkills should keep one hidden AFS-backed skills workspace per scope and put
-registered skill content under `skills/<skill-slug>` inside that workspace.
-Agent-facing skill folders then point at that canonical copy:
+`afs.go` and `workspace_mount.go` contain the AFS adapter boundary. In local
+mode, the adapter materializes checkpoint files and writes mount metadata under
+`$LIVESKILLS_HOME`. In CLI mode, it calls `afs` to create/import checkpoints and
+mount skill volumes into the canonical skills workspace.
 
-```text
-.liveskills/mount/skills/<skill>      # project canonical source
-.agents/skills/<skill>                # relative symlink by default
-.claude/skills/<skill>                # relative symlink by default
+The current shape is:
 
-~/.liveskills/mount/skills/<skill>    # global canonical source
-~/.codex/skills/<skill>               # relative symlink by default
-~/.claude/skills/<skill>              # relative symlink by default
-```
+- one skills workspace per scope
+- registered skill content under `skills/<skill-slug>` in that workspace
+- direct per-skill volume attachment at the canonical skill path
+- symlinked agent folders by default
+- copy fallback with `--copy`
 
-LiveSkills owns one skill folder at a time, not the whole skills parent
-directory. Neighboring manually downloaded skills under `.agents/skills`,
-`.claude/skills`, or global agent folders must remain untouched.
+## Commands
 
-Use `--copy` when symlinks are not wanted or not supported. Copy installs are
-not live-linked to the AFS workspace and should be reported that way by `list`.
+| Command | Description |
+| --- | --- |
+| `liveskills help` | Show the compact command screen. |
+| `liveskills add <source-or-ref>` | Register/version a local source if needed, then install it into the current project. |
+| `liveskills add -g <source-or-ref>` | Install into global agent folders. |
+| `liveskills add <source-or-ref> --agent <agent>` | Install for one or more selected agents. Repeat `--agent` for multiple targets. |
+| `liveskills add <source> --skill <skill>` | Select one or more skills from a multi-skill source. Repeat `--skill` for multiple selections. |
+| `liveskills add <source> --all` | Install every skill found in a multi-skill source. |
+| `liveskills add <source> --list` | List skills available in a source without installing. |
+| `liveskills add <source-or-ref> --copy` | Copy instead of symlinking from the LiveSkills canonical workspace. |
+| `liveskills add <source-or-ref> --yes` | Skip the interactive install confirmation. |
+| `liveskills list` / `liveskills ls` | Show current-project installed skills. |
+| `liveskills list -g` | Show global installed skills, plus current-project LiveSkills mounts. |
+| `liveskills find [query]` | Open the interactive skill finder in a terminal; with a query or non-TTY output, print copyable install refs. |
+| `liveskills find --interactive [query]` | Force the terminal skill finder, optionally seeded with a query. |
+| `liveskills publish <source> [--skill <name>]` | Advanced: register a source without installing it. |
+| `liveskills show <owner>/<skill>` | Show registry details and versions for a skill. |
+| `liveskills download <owner>/<skill> --output <dir>` | Export a registry snapshot to a local directory. |
+| `liveskills update <owner>/<skill>` | Move an existing install to the selected/latest version. |
+| `liveskills remove <owner>/<skill>` / `liveskills rm <owner>/<skill>` | Remove a managed install. |
+| `liveskills scan [-g|-p] [--agent <agent>]` | Scan local skill folders without using the registry. |
+| `liveskills auth login` | Store registry auth settings in the local registry config. |
+
+Most commands support `--json` for machine-readable output.
 
 ## Add Behavior
 
-Target command shape:
+`<source-or-ref>` may be:
 
-```bash
-liveskills add <source-or-ref>
-liveskills add <source-or-ref> --agent codex --agent claude
-liveskills add <source-or-ref> --skill react-best-practices --skill docs-review
-liveskills add <source-or-ref> --copy
-liveskills add -g <source-or-ref>
-```
+- a local skill folder containing `SKILL.md`
+- a local folder containing multiple skill folders
+- a remote Git/GitHub source
+- a registry reference in `<owner>/<skill>` form
+- a source with an inline `@skill` selector
 
-`<source-or-ref>` may be a local skill folder, a source containing multiple
-skills, or a registry reference once registry lookup is implemented for that
-shape.
+When adding a local source, LiveSkills publishes it with owner `local` by
+default, then installs the selected version. If a source contains multiple
+skills, pass repeated `--skill <name>` values or `--all`; otherwise the command
+fails rather than guessing.
 
-Repeated `--agent` selects multiple target agents. Repeated `--skill` selects
-multiple skills from a multi-skill source. Without explicit targets, `add`
-should prompt for any ambiguous agent, skill, scope, or install-method choice.
+The install output reports the selected skill, version, scope, workspace,
+canonical path, agent targets, and the matching `list` command. Non-JSON `add`
+also prints a local security assessment and a final reminder that installed
+skills run with full agent permissions.
 
-The install flow should show:
+## Lists And Scans
 
-- selected skills, agents, scope, and install method
-- security risk assessment before making filesystem changes
-- confirmation prompt unless a future noninteractive yes flag is used
-- installed paths grouped by universal, symlinked, and copied targets
-- final full-permissions warning for installed agent skills
+`liveskills list` is an installed inventory, not a registry browser. It shows
+LiveSkills-managed rows separately from local unmanaged skill folders discovered
+on disk. If no project skills are found, it hints to try `liveskills list -g`.
 
-Do not add the upstream `find-skills` upsell prompt.
+Use `liveskills find` for the interactive registry picker, or
+`liveskills find [query]` for copyable search output. Use `liveskills scan` for
+a read-only scan of project and global skill folders across supported agents.
+When the picker selection is confirmed with Enter, LiveSkills shows the skill
+summary, asks which agents to install to, asks for project or global scope,
+asks for symlink or copy when multiple agent folders are targeted, shows an
+installation summary and local security assessment, and asks before installing.
 
-## Commands
+## Full Surface Test
 
-| Command | Description |
-| --- | --- |
-| `liveskills help` | Show available commands. |
-| `liveskills add <source-or-ref>` | Register/version if needed, then install skills into the project. |
-| `liveskills add -g <source-or-ref>` | Install skills into global agent folders. |
-| `liveskills add <source-or-ref> --agent <agent>` | Install for one or more selected agents. |
-| `liveskills add <source-or-ref> --skill <skill>` | Install one or more selected skills from a source. |
-| `liveskills add <source-or-ref> --copy` | Copy instead of symlinking from the LiveSkills workspace. |
-| `liveskills list [-g]` | Show skills installed on this computer. |
-| `liveskills remove <skill>` | Remove a skill from this computer. |
-| `liveskills update <skill>` | Update an installed skill. |
-| `liveskills scan [-g|-p] [--agent codex]` | Scan local skill folders on this computer. |
-| `liveskills find [query]` | Show published registry skills when registry discovery is needed. |
-| `liveskills find --interactive [query]` | Search published registry skills interactively. |
-| `liveskills publish <source> [--skill <name>]` | Advanced: publish/register without installing. |
-| `liveskills show <owner>/<skill>` | Show registry details for a skill. |
-| `liveskills download <owner>/<skill> --output <dir>` | Download a registry skill snapshot. |
-| `liveskills add <source> --list` | Show skills available in a source. |
-| `liveskills auth login` | Configure registry authentication. |
+Run the isolated CLI harness when changing command behavior:
 
-## AFS Boundary
+```bash
+make surface-test
+```
 
-`afs.go` contains the AFS adapter. In normal use it calls the `afs` CLI; in
-`LIVESKILLS_AFS_MODE=local` it uses the local development stand-in.
+The harness builds a temporary `liveskills` binary, runs `go test ./...`, then
+uses isolated `HOME`, `LIVESKILLS_HOME`, and `LIVESKILLS_AFS_MODE=local` values
+to exercise auth, publish, find, show, download, add, list, update, remove,
+scan, project/global installs, agent-specific paths, validation errors, and
+deterministic stress coverage.
 
-Production behavior should preserve the same CLI contract while moving installs
-to the workspace-plus-symlink model:
+Use `--keep-temp` to inspect the generated project, home, store, and source
+fixtures after a run:
 
-- one hidden skills workspace per scope
-- skill content under `skills/<skill-slug>` in that workspace
-- symlinked agent folders by default
-- copy fallback with `--copy`
-- no ownership of the whole agent skills parent directory
+```bash
+python3 scripts/liveskills_surface_test.py --keep-temp --verbose
+```

examples/liveskills/afs.go

@@ -100,7 +100,7 @@ func (a *LocalAFSAdapter) PublishVersion(volumeID, version string, files []Skill
 		return "", "", err
 	}
 	if a.usesCLI() {
-		if err := a.Runner.Run("vol", "import", "--force", volumeID, versionRoot); err != nil {
+		if err := a.importVolumeSnapshot(volumeID, versionRoot); err != nil {
 			return "", "", err
 		}
 		if err := a.Runner.Run("cp", "create", volumeID, checkpointID, "--description", "LiveSkills "+version); err != nil {
@@ -162,6 +162,9 @@ func (a *LocalAFSAdapter) MountSkillVolume(volumeID, checkpointID, mountPoint, s
 			if isExistingAFSMount(err, volumeID, mountPoint) {
 				return nil
 			}
+			if existingPath, ok := existingMountedVolumePath(err, volumeID); ok {
+				return ensureCanonicalMountAlias(mountPoint, existingPath)
+			}
 			return err
 		}
 		return nil
@@ -184,12 +187,23 @@ func (a *LocalAFSAdapter) importStagedCheckpoint(volumeID, checkpointID string)
 	if _, err := os.Stat(source); err != nil {
 		return err
 	}
-	if err := a.Runner.Run("vol", "import", "--force", volumeID, source); err != nil {
+	if err := a.importVolumeSnapshot(volumeID, source); err != nil {
 		return err
 	}
 	return a.Runner.Run("cp", "create", volumeID, checkpointID, "--description", "LiveSkills "+checkpointID)
 }
 
+func (a *LocalAFSAdapter) importVolumeSnapshot(volumeID, source string) error {
+	err := a.Runner.Run("vol", "import", volumeID, source)
+	if err == nil {
+		return nil
+	}
+	if !isExistingVolumeImportError(err) {
+		return err
+	}
+	return a.Runner.Run("vol", "import", "--force", volumeID, source)
+}
+
 func needsStagedCheckpointImport(err error) bool {
 	if err == nil {
 		return false
@@ -198,6 +212,16 @@ func needsStagedCheckpointImport(err error) bool {
 	return strings.Contains(message, "does not exist") || strings.Contains(message, "not found")
 }
 
+func isExistingVolumeImportError(err error) bool {
+	if err == nil {
+		return false
+	}
+	message := strings.ToLower(err.Error())
+	return strings.Contains(message, "already exists") ||
+		strings.Contains(message, "rerun with --force") ||
+		strings.Contains(message, "re-run with --force")
+}
+
 func isExistingAFSMount(err error, volumeID, mountPoint string) bool {
 	if err == nil {
 		return false
@@ -208,6 +232,32 @@ func isExistingAFSMount(err error, volumeID, mountPoint string) bool {
 		strings.Contains(message, strings.ToLower(filepath.Clean(mountPoint)))
 }
 
+func isMountedVolumeAtDifferentPath(err error, volumeID string) bool {
+	_, ok := existingMountedVolumePath(err, volumeID)
+	return ok
+}
+
+func existingMountedVolumePath(err error, volumeID string) (string, bool) {
+	if err == nil {
+		return "", false
+	}
+	message := err.Error()
+	lower := strings.ToLower(message)
+	if !strings.Contains(lower, strings.ToLower(volumeID)) || !strings.Contains(lower, "already mounted at ") {
+		return "", false
+	}
+	index := strings.LastIndex(lower, "already mounted at ")
+	if index < 0 {
+		return "", false
+	}
+	path := strings.TrimSpace(message[index+len("already mounted at "):])
+	path = strings.TrimRight(path, ". \t\r\n")
+	if path == "" {
+		return "", false
+	}
+	return filepath.Clean(path), true
+}
+
 func afsMode(env map[string]string) string {
 	mode := strings.ToLower(envValue(env, "LIVESKILLS_AFS_MODE"))
 	if mode == "" {