@webship.co/workspace 1.0.0-beta1 → 1.0.0-beta2

package/core/scripts/docker-gid.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+
+################################################################################
+## Webship Workspace — align the dashboard's docker group with this host
+################################################################################
+## The dashboard runs in its own DDEV web container with Docker-outside-of-Docker:
+## the host's /var/run/docker.sock is bind-mounted in, and that socket is
+## root:docker with the HOST's docker GID. The container's web user therefore has
+## to share that exact GID, or every `ddev` command inside the dashboard fails:
+##
+##   Docker error: permission denied while trying to connect to the docker API
+##
+## which does not look like a permissions problem from the outside. It looks like
+## a dashboard where every project is "Stopped" forever, no Start/Stop/Drush item
+## ever appears, and pressing Start seems to do nothing — while the project is in
+## fact running perfectly well on the host.
+##
+##   bash core/scripts/docker-gid.sh            align it, if it differs
+##   bash core/scripts/docker-gid.sh --check    report, change nothing
+##   bash core/scripts/docker-gid.sh --quiet     only speak when something changed
+##
+## The GID has to be baked at BUILD time, in
+## .ddev/web-build/Dockerfile.workspace-app: the container's main process runs as
+## uid 1000 (`Config.User=1000:1000`), so no entrypoint script can groupmod its
+## way out of it, and supervisord launches the app without calling initgroups() —
+## so it must be the web user's PRIMARY group, not a supplementary one.
+##
+## Which means the value in that file is machine-specific, in a file that
+## cmd-tools sync-tooling.sh mirrors wholesale. That is why this exists as a
+## script rather than a note in the README: install.sh runs it during setup, and
+## sync-tooling.sh runs it after mirroring, so a pull cannot leave the dashboard
+## blind to Docker.
+################################################################################
+
+set -u
+
+CHECK_ONLY='no'
+QUIET='no'
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -c|--check) CHECK_ONLY='yes'; shift ;;
+    -q|--quiet) QUIET='yes'; shift ;;
+    -h|--help)  sed -n '3,34p' "${BASH_SOURCE[0]}" | sed 's/^## \{0,1\}//'; exit 0 ;;
+    *) echo "Unknown option: $1 (see --help)"; exit 1 ;;
+  esac
+done
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+DOCKERFILE="${ROOT}/core/workspace-app/.ddev/web-build/Dockerfile.workspace-app"
+COMPOSE="${ROOT}/core/workspace-app/.ddev/docker-compose.dood.yaml"
+
+function say()  { [ "${QUIET}" == 'yes' ] || echo "$@" ; }
+function warn() { echo "$@" ; }
+
+if [ ! -f "${DOCKERFILE}" ] ; then
+  warn "  ✗ No ${DOCKERFILE#${ROOT}/} — nothing to align."
+  exit 1
+fi
+
+# The socket is the authority when it is there: it is the thing the container has
+# to reach. Fall back to the docker group, for a machine where Docker is not up.
+host_gid=''
+if [ -S /var/run/docker.sock ] ; then
+  host_gid="$(stat -c %g /var/run/docker.sock 2>/dev/null)"
+fi
+if [ -z "${host_gid}" ] ; then
+  host_gid="$(getent group docker 2>/dev/null | cut -d: -f3)"
+fi
+if [ -z "${host_gid}" ] ; then
+  warn "  ✗ No docker group and no /var/run/docker.sock — is Docker installed?"
+  exit 1
+fi
+
+# Both numbers in the file are the same GID: the group, then the web user's primary group.
+baked="$(grep -oE 'groupmod -g [0-9]+ docker' "${DOCKERFILE}" | grep -oE '[0-9]+' | head -1)"
+if [ -z "${baked}" ] ; then
+  warn "  ✗ Could not find the docker GID in ${DOCKERFILE##*/} — has that line changed?"
+  exit 1
+fi
+
+# The build-time GID makes the group exist in the image; the compose group_add is
+# what puts the running process in it. Both have to be right, and they are the same
+# number, so they are checked and written together.
+granted=""
+if [ -f "${COMPOSE}" ] ; then
+  granted="$(sed -n '/group_add:/,/^[^ ]/p' "${COMPOSE}" | grep -oE '"[0-9]+"' | tr -d '"' | head -1)"
+fi
+
+if [ "${baked}" == "${host_gid}" ] && { [ -z "${granted}" ] || [ "${granted}" == "${host_gid}" ]; } ; then
+  say "  ✓ dashboard docker GID ${baked} matches this host"
+  exit 0
+fi
+
+if [ "${CHECK_ONLY}" == 'yes' ] ; then
+  warn "  ✗ dashboard docker GID is ${baked}${granted:+ (granted ${granted})}, this host's docker socket is ${host_gid}"
+  warn "    Every ddev command inside the dashboard fails, so every project reads as Stopped."
+  warn "    Fix it: bash core/scripts/docker-gid.sh && (cd core/workspace-app && ddev restart)"
+  exit 1
+fi
+
+# Rewrite both occurrences on that one line, and nothing else in the file.
+sed -i -E "s/groupmod -g [0-9]+ docker/groupmod -g ${host_gid} docker/; s/groupadd -g [0-9]+ docker/groupadd -g ${host_gid} docker/; s/usermod -g [0-9]+ \\\$username/usermod -g ${host_gid} \$username/" "${DOCKERFILE}"
+
+# group_add in the compose override: the one the running process actually gets.
+if [ -f "${COMPOSE}" ] && [ -n "${granted}" ] ; then
+  sed -i -E "/group_add:/,/^[^ ]/ s/\"${granted}\"/\"${host_gid}\"/" "${COMPOSE}"
+fi
+
+after="$(grep -oE 'groupmod -g [0-9]+ docker' "${DOCKERFILE}" | grep -oE '[0-9]+' | head -1)"
+if [ "${after}" != "${host_gid}" ] ; then
+  warn "  ✗ Tried to set the docker GID to ${host_gid} and the file still says ${after}."
+  warn "    Edit ${DOCKERFILE#${ROOT}/} by hand — the line is near the end."
+  exit 1
+fi
+
+warn "  ✓ dashboard docker GID ${baked} → ${host_gid} (this host's docker socket)"
+warn "    The image carries the old GID until it is rebuilt:"
+warn "      cd ${ROOT}/core/workspace-app && ddev restart"
+exit 0

package/core/scripts/functions/arg-site-template.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The name of the project. It becomes https://<PROJECT_NAME>.ddev.site')
+parser.add_argument('-v', '--site-template-version',
+                    default="",
+                    help='Composer constraint for the site template. Example: --site-template-version "^1.0". Default: the latest release.')
+parser.add_argument('-p', '--php-version',
+                    default="8.3",
+                    help='PHP version for the DDEV project [default %(default)s].')
+parser.add_argument('-i', '--install',
+                    action='store_true',
+                    default=False,
+                    help='Install the site with this template after building it. Without this the build stops at a codebase, exactly as every other builder in the workspace does, and you pick the template in the browser installer.')
+parser.add_argument('-s', '--skip-install',
+                    action='store_true',
+                    default=False,
+                    help='Explicitly stop at the codebase. That is already what happens without --install; the flag exists so a script that passes it keeps working.')
+parser.add_argument('-l', '--launch',
+                    action='store_true',
+                    default=False,
+                    help='Open the site in a browser when it is ready.')
+parser.add_argument('-r', '--require',
+                    default="_none_",
+                    nargs='+',
+                    help='Require more packages by composer. Example: --require "drupal/token:~1.0"')
+ARGEOF

package/core/scripts/functions/fun-ai-items-lock.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+
+# Tracks what ai-items installed where, so a later run can tell "is this stale"
+# without re-copying anything. One lock file per .claude root (global ~/.claude,
+# or a project's own .claude/), covering agents, skills and prompts together.
+#
+# Two kinds of source get two kinds of hash, same split as skills.sh:
+#   repo-sourced (ai_items_fetch, dest claude) -> the git object sha for that
+#     path at the fetched ref. We already hold a local clone when fetching, so
+#     `git rev-parse <ref>:<path>` gets it for free — no extra network call.
+#   workspace-sourced (install_ai_item)        -> a local content hash of the
+#     workspace draft, recomputed on check with no network at all.
+#
+# ai_items_check reads the lock and, only for entries still claiming a repo
+# source, fetches the WHOLE remote tree once (one `gh api` call covers every
+# item being checked) rather than one call per item.
+
+function ai_items_lock_file() {
+  local install_dir="$1";
+  echo "$(dirname "${install_dir}")/.ai-items-lock.json" ;
+}
+
+# Local content hash: sha256 of a file, or a sorted hash-of-hashes for a directory.
+# Deterministic across runs on the same content; not meant to match any external hash.
+function ai_items_local_hash() {
+  local path="$1";
+  if [ -f "${path}" ]; then
+    sha256sum "${path}" | awk '{print $1}' ;
+  elif [ -d "${path}" ]; then
+    find "${path}" -type f | LC_ALL=C sort | xargs sha256sum 2>/dev/null | sha256sum | awk '{print $1}' ;
+  fi
+}
+
+# Add or update one item's entry in the lock file next to `install_dir`.
+function ai_items_lock_set() {
+  local install_dir="$1" kind="$2" name="$3" source="$4" source_type="$5" source_path="$6" hash="$7";
+  local lock_file; lock_file=$(ai_items_lock_file "${install_dir}") ;
+  python3 - "${lock_file}" "${kind}" "${name}" "${source}" "${source_type}" "${source_path}" "${hash}" <<'PYEOF'
+import json, sys, pathlib, datetime
+lock_file, kind, name, source, source_type, source_path, hash_ = sys.argv[1:8]
+p = pathlib.Path(lock_file)
+try:
+    data = json.loads(p.read_text())
+except Exception:
+    data = {"version": 1, "items": {}}
+data.setdefault("items", {})
+key = f"{kind}:{name}"
+now = datetime.datetime.now(datetime.timezone.utc).isoformat()
+existing = data["items"].get(key, {})
+data["items"][key] = {
+    "kind": kind,
+    "name": name,
+    "source": source,
+    "sourceType": source_type,
+    "sourcePath": source_path,
+    "hash": hash_,
+    "installedAt": existing.get("installedAt", now),
+    "updatedAt": now,
+}
+p.parent.mkdir(parents=True, exist_ok=True)
+p.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+PYEOF
+}
+
+# Rows of "name\tsourceType\tsource\tsourcePath\thash" for entries of one kind
+# (optionally one name), read straight out of the lock file.
+function ai_items_lock_rows() {
+  local lock_file="$1" kind="$2" name="${3:-}";
+  [ -f "${lock_file}" ] || return 0 ;
+  python3 - "${lock_file}" "${kind}" "${name}" <<'PYEOF'
+import json, sys
+lock_file, kind, name = sys.argv[1:4]
+try:
+    data = json.loads(open(lock_file).read())
+except Exception:
+    data = {"items": {}}
+for _, entry in sorted(data.get("items", {}).items()):
+    if entry.get("kind") != kind:
+        continue
+    if name and name not in ("", "_all_") and entry.get("name") != name:
+        continue
+    print("\t".join([
+        entry.get("name", ""), entry.get("sourceType", ""), entry.get("source", ""),
+        entry.get("sourcePath", ""), entry.get("hash", ""),
+    ]))
+PYEOF
+}
+
+# Compare the lock against reality for one install location, without touching
+# the installed files. Repo-sourced entries are checked against ONE fetched
+# remote tree (whichever ref the entry itself recorded); workspace-sourced
+# entries are checked against the current workspace draft, purely locally.
+function ai_items_check() {
+  local kind="$1" name="${2:-}" to="${3:-}";
+  local target; target=$(ai_items_install_path "${kind}" "${to}") || return 1 ;
+  if [ ! -d "${target}" ]; then
+    echo "Nothing installed at ${target}." ;
+    return 1 ;
+  fi
+  local lock_file; lock_file=$(ai_items_lock_file "${target}") ;
+  if [ ! -f "${lock_file}" ]; then
+    echo "No lock file at ${lock_file} — nothing workspace-tracked yet (installed before checking existed, or copied by hand).";
+    ai_items_skills_cli_check "${kind}" "${to}" ;
+    return 0 ;
+  fi
+
+  echo "*---------------------------------------------------------------------*";
+  echo "  ${kind} — ${target}";
+  echo "*---------------------------------------------------------------------*";
+
+  local rows; rows=$(ai_items_lock_rows "${lock_file}" "${kind}" "${name}") ;
+  if [ -z "${rows}" ]; then
+    echo "  Nothing workspace-tracked for '${name:-_all_}'.";
+    ai_items_skills_cli_check "${kind}" "${to}" ;
+    return 0 ;
+  fi
+
+  local tree_json="" repo_checked="";
+  local item_name source_type source source_path hash status remote_hash;
+
+  while IFS=$'\t' read -r item_name source_type source source_path hash ; do
+    [ -z "${item_name}" ] && continue ;
+    status="unknown";
+    if [ "${source_type}" == 'repo' ] ; then
+      # One recursive tree fetch covers every repo-sourced item being checked —
+      # cached per <repo>@<ref>, not re-fetched per item.
+      if [ "${repo_checked}" != "${source}" ] ; then
+        ensure_gh_cli > /dev/null 2>&1 ;
+        local repo="${source%@*}" ref="${source##*@}";
+        tree_json=$(gh api "repos/${repo}/git/trees/${ref}?recursive=1" 2>/dev/null) ;
+        repo_checked="${source}";
+      fi
+      if [ -z "${tree_json}" ] ; then
+        status="could not reach ${source}";
+      else
+        remote_hash=$(echo "${tree_json}" | jq -r --arg p "${source_path}" '.tree[]? | select(.path==$p) | .sha' 2>/dev/null) ;
+        if [ -z "${remote_hash}" ] ; then
+          status="removed upstream";
+        elif [ "${remote_hash}" == "${hash}" ] ; then
+          status="up to date";
+        else
+          status="update available";
+        fi
+      fi
+    else
+      # Workspace-sourced: recompute the draft's current hash, no network.
+      local draft_path="${WORKSPACE_ROOT}/${source_path}";
+      if [ ! -e "${draft_path}" ] ; then
+        status="draft removed (${draft_path})";
+      else
+        remote_hash=$(ai_items_local_hash "${draft_path}") ;
+        if [ "${remote_hash}" == "${hash}" ] ; then
+          status="up to date";
+        else
+          status="draft changed since install";
+        fi
+      fi
+    fi
+    printf "  %-32s %-14s %s\n" "${item_name}" "(${source_type})" "${status}";
+  done <<< "${rows}"
+
+  ai_items_skills_cli_check "${kind}" "${to}" ;
+  return 0 ;
+}
+
+# Skills the skills.sh CLI installed live in ITS lock — its own `check` covers them.
+# Global scope only: that CLI's check reads ~/.agents/.skill-lock.json, not a project's.
+function ai_items_skills_cli_check() {
+  local kind="$1" to="$2";
+  [ "${kind}" == 'ai-skills' ] || return 0 ;
+  ai_items_skills_cli_available || return 0 ;
+  if [ -n "${to}" ] && [ ! "${to}" == '_none_' ] && [ ! "${to}" == 'claude' ] ; then return 0 ; fi
+  echo "skills.sh CLI (npx skills check):" ;
+  DISABLE_TELEMETRY=1 npx -y skills check || echo "  (skills.sh CLI check failed — the workspace-tracked report above stands)" ;
+}

package/core/scripts/functions/fun-ai-items-sources.sh

@@ -0,0 +1,298 @@
+#!/usr/bin/env bash
+
+# `--add <source>` and `--update`: the skills.sh verbs, on top of the lock file.
+#
+#   add     any GitHub repo -> ~/.claude (or one project's .claude/) + lock entry
+#   update  re-copy every lock entry whose source moved, nothing else
+#
+# The Webship repo keeps its own dedicated verb (--fetch, curated + filtered);
+# --add is for everything else: a public skills repo, a client's repo, a fork.
+
+# Normalize a source into "owner/repo<TAB>ref<TAB>subpath" (ref/subpath may be empty).
+# Accepts: owner/repo, owner/repo@ref, https://github.com/owner/repo[.git],
+# and https://github.com/owner/repo/tree/ref[/subpath].
+function ai_items_parse_source() {
+  local input="$1" owner_repo="" ref="" subpath="";
+
+  case "${input}" in
+    *github.com/*)
+      local path="${input#*github.com/}"; path="${path%/}";
+      if [[ "${path}" == */tree/* ]] ; then
+        owner_repo="${path%%/tree/*}";
+        local rest="${path#*/tree/}";
+        ref="${rest%%/*}";
+        [ "${rest}" != "${ref}" ] && subpath="${rest#*/}";
+      else
+        owner_repo="${path}";
+      fi
+      owner_repo="${owner_repo%.git}";
+      ;;
+    */*)
+      owner_repo="${input}";
+      if [[ "${owner_repo}" == *@* ]] ; then
+        ref="${owner_repo##*@}"; owner_repo="${owner_repo%@*}";
+      fi
+      ;;
+    *)
+      echo "Not a source I can read: '${input}'. Use owner/repo, owner/repo@ref, or a github.com URL." >&2 ;
+      return 1 ;
+      ;;
+  esac
+
+  if ! echo "${owner_repo}" | grep -qE '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$' ; then
+    echo "Not a source I can read: '${input}'. Use owner/repo, owner/repo@ref, or a github.com URL." >&2 ;
+    return 1 ;
+  fi
+  if [[ "${subpath}" == *..* ]] ; then
+    echo "Refusing subpath with '..': ${subpath}" >&2 ;
+    return 1 ;
+  fi
+  printf '%s\t%s\t%s\n' "${owner_repo}" "${ref}" "${subpath}" ;
+}
+
+# Shallow-clone one repo@ref into a temp dir and print the dir. gh's credential
+# helper covers private repos the caller can read; public ones need nothing.
+function ai_items_clone_source() {
+  local owner_repo="$1" ref="$2" tmp;
+  tmp=$(mktemp -d) ;
+  ensure_git_github_auth ;
+  local ref_args=() ;
+  [ -n "${ref}" ] && ref_args=(--branch "${ref}") ;
+  if ! git clone --quiet --depth 1 "${ref_args[@]}" "https://github.com/${owner_repo}.git" "${tmp}/repo" 2>/dev/null ; then
+    echo "Could not clone ${owner_repo}${ref:+@${ref}} — check the name, ref and access." >&2 ;
+    rm -rf "${tmp}" ;
+    return 1 ;
+  fi
+  echo "${tmp}/repo" ;
+}
+
+# Discover items of one kind in a checkout, as "name<TAB>path-in-repo" rows.
+# Skills are directories holding a SKILL.md; agents and prompts are .md files.
+# Container dirs cover the skills.sh conventions plus this workspace's own.
+function ai_items_discover() {
+  local kind="$1" root="$2" base="${3:-}";
+  local search="${root}${base:+/${base}}";
+  [ -d "${search}" ] || return 0 ;
+
+  if [ "${kind}" == 'ai-skills' ] ; then
+    # A subpath pointing straight at one skill.
+    if [ -f "${search}/SKILL.md" ] && [ -n "${base}" ] ; then
+      printf '%s\t%s\n' "$(basename "${search}")" "${base}" ;
+      return 0 ;
+    fi
+    local d container;
+    for container in "" "skills" ".claude/skills" ".agents/skills" ; do
+      local dir="${search}${container:+/${container}}";
+      [ -d "${dir}" ] || continue ;
+      for d in "${dir}"/*/ ; do
+        [ -f "${d}SKILL.md" ] || continue ;
+        local rel="${d#${root}/}"; rel="${rel%/}";
+        printf '%s\t%s\n' "$(basename "${d}")" "${rel}" ;
+      done
+    done
+  else
+    local container_names;
+    if [ "${kind}" == 'ai-agents' ] ; then
+      container_names=".claude/agents agents";
+    else
+      container_names=".claude/commands commands prompts";
+    fi
+    local f container;
+    for container in ${container_names} ; do
+      local dir="${search}/${container}";
+      [ -d "${dir}" ] || continue ;
+      for f in "${dir}"/*.md ; do
+        [ -f "${f}" ] || continue ;
+        case "$(basename "${f}")" in README.md|AGENTS.md|CLAUDE.md|RULES.md) continue ;; esac
+        local rel="${f#${root}/}";
+        printf '%s\t%s\n' "$(basename "${f}" .md)" "${rel}" ;
+      done
+    done
+  fi | sort -u ;
+}
+
+# The skills.sh CLI (github.com/vercel-labs/skills) is the ecosystem's own installer
+# for the skills kind — same SKILL.md format, richer source support, its own lock and
+# `update`. Delegate to it when node is here; agents and prompts stay on the bash path
+# because that CLI only handles skills. AI_ITEMS_NO_SKILLS_CLI=1 opts out.
+function ai_items_skills_cli_available() {
+  [ -n "${AI_ITEMS_NO_SKILLS_CLI}" ] && return 1 ;
+  command -v npx > /dev/null 2>&1 ;
+}
+
+# DISABLE_TELEMETRY: the CLI reports installed skill names to skills.sh for its
+# leaderboard — fine for public repos, not for client or private ones, so off always.
+function ai_items_skills_cli_add() {
+  local name="$1" source="$2" to="$3";
+  local skill_filter="${name:-*}";
+  [ "${skill_filter}" == '_all_' ] && skill_filter='*' ;
+  echo "Using the skills.sh CLI (npx skills add) — its own lock manages these; agents and prompts stay on the workspace tooling." ;
+  if [ -z "${to}" ] || [ "${to}" == '_none_' ] || [ "${to}" == 'claude' ] ; then
+    DISABLE_TELEMETRY=1 npx -y skills add "${source}" --skill "${skill_filter}" -a claude-code --copy -g -y ;
+  else
+    local project_dir="${WORKSPACE_ROOT}/${to}";
+    [ -d "${project_dir}" ] || { echo "No ${to}." >&2 ; return 1 ; }
+    ( cd "${project_dir}" && DISABLE_TELEMETRY=1 npx -y skills add "${source}" --skill "${skill_filter}" -a claude-code --copy -y ) ;
+  fi
+}
+
+function ai_items_skills_cli_update() {
+  local to="$1";
+  if [ -z "${to}" ] || [ "${to}" == '_none_' ] || [ "${to}" == 'claude' ] ; then
+    DISABLE_TELEMETRY=1 npx -y skills update -g -y ;
+  else
+    local project_dir="${WORKSPACE_ROOT}/${to}";
+    [ -d "${project_dir}" ] || return 0 ;
+    ( cd "${project_dir}" && DISABLE_TELEMETRY=1 npx -y skills update -p -y ) ;
+  fi
+}
+
+# Install items of one kind from any GitHub repo, and lock what was copied.
+#   name    one item, or _all_/empty for everything discovered
+#   source  owner/repo[@ref] or a github.com URL (tree URLs carry ref + subpath)
+#   to      empty for ~/.claude, or <workspace>/<project>
+function ai_items_add() {
+  local kind="$1" name="$2" source="$3" to="${4:-}";
+  name=$(ai_items_sanitize_name "${name}") || return 1 ;
+
+  if [ "${kind}" == 'ai-skills' ] && ai_items_skills_cli_available ; then
+    if ai_items_skills_cli_add "${name}" "${source}" "${to}" ; then
+      return 0 ;
+    fi
+    echo "skills.sh CLI could not add it — falling back to the workspace installer." ;
+  fi
+
+  local parsed owner_repo ref subpath;
+  parsed=$(ai_items_parse_source "${source}") || return 1 ;
+  IFS=$'\t' read -r owner_repo ref subpath <<< "${parsed}" ;
+
+  local target; target=$(ai_items_install_path "${kind}" "${to}") || return 1 ;
+  local checkout; checkout=$(ai_items_clone_source "${owner_repo}" "${ref}") || return 1 ;
+  local tmp_root; tmp_root=$(dirname "${checkout}") ;
+  local ref_name; ref_name=$(git -C "${checkout}" rev-parse --abbrev-ref HEAD 2>/dev/null) ;
+
+  local rows; rows=$(ai_items_discover "${kind}" "${checkout}" "${subpath}") ;
+  if [ -z "${rows}" ]; then
+    echo "No ${kind} found in ${owner_repo}${ref:+@${ref}}${subpath:+ under ${subpath}}." ;
+    rm -rf "${tmp_root}" ;
+    return 1 ;
+  fi
+
+  mkdir -p "${target}" ;
+  local copied=0 skipped=0 item path;
+  while IFS=$'\t' read -r item path ; do
+    [ -z "${item}" ] && continue ;
+    if [ -n "${name}" ] && [ "${name}" != '_all_' ] && [ "${item}" != "${name}" ] ; then continue ; fi
+    # Discovered names come from a remote repo: same character rule as everywhere else.
+    if ! echo "${item}" | grep -qE '^[a-zA-Z0-9_.-]+$' ; then
+      echo "  skipping '${item}': unsafe name." ; skipped=$((skipped+1)) ; continue ;
+    fi
+    local sha; sha=$(git -C "${checkout}" rev-parse "HEAD:${path}" 2>/dev/null) ;
+    if [ "${kind}" == 'ai-skills' ] ; then
+      rsync -a --delete "${checkout}/${path}/" "${target}/${item}/" || { skipped=$((skipped+1)) ; continue ; }
+    else
+      cp "${checkout}/${path}" "${target}/" || { skipped=$((skipped+1)) ; continue ; }
+    fi
+    copied=$((copied+1)) ;
+    [ -n "${sha}" ] && ai_items_lock_set "${target}" "${kind}" "${item}" \
+      "${owner_repo}@${ref_name}" "repo" "${path}" "${sha}" ;
+    echo "  + ${item}" ;
+  done <<< "${rows}"
+  rm -rf "${tmp_root}" ;
+
+  if [ "${copied}" -eq 0 ]; then
+    echo "No ${kind%s} '${name}' in ${owner_repo}${ref:+@${ref}} — nothing installed." ;
+    return 1 ;
+  fi
+  echo "Added ${copied} ${kind} from ${owner_repo}${ref:+@${ref}} into ${target}." ;
+  echo "Review third-party ${kind} before use — a session runs them with its full permissions." ;
+  echo "Restart your Claude Code session to pick it up." ;
+}
+
+# Re-copy every lock entry of one kind whose source moved. Repo entries are
+# grouped so each repo@ref clones once; workspace entries re-install from the
+# draft. Nothing is touched when the recorded hash still matches.
+function ai_items_update() {
+  local kind="$1" name="${2:-}" to="${3:-}";
+  local target; target=$(ai_items_install_path "${kind}" "${to}") || return 1 ;
+  local lock_file; lock_file=$(ai_items_lock_file "${target}") ;
+
+  # No workspace-tracked entries is not "nothing to do" for skills: the
+  # skills.sh CLI keeps its own lock, and its update below still runs.
+  local rows="";
+  if [ -f "${lock_file}" ]; then
+    rows=$(ai_items_lock_rows "${lock_file}" "${kind}" "${name}") ;
+  fi
+  if [ -z "${rows}" ]; then
+    echo "Nothing workspace-tracked for '${name:-_all_}' at ${target}." ;
+  fi
+
+  local updated=0 checked=0 current_source="" checkout="" tmp_root="";
+  local item_name source_type source source_path hash;
+
+  # Sorting by source groups repo entries so one clone serves all of them.
+  while IFS=$'\t' read -r item_name source_type source source_path hash ; do
+    [ -z "${item_name}" ] && continue ;
+    checked=$((checked+1)) ;
+
+    if [ "${source_type}" == 'repo' ] ; then
+      if [ "${source}" != "${current_source}" ] ; then
+        [ -n "${tmp_root}" ] && rm -rf "${tmp_root}" ;
+        checkout=$(ai_items_clone_source "${source%@*}" "${source##*@}") || { checkout=""; tmp_root=""; current_source="${source}"; continue ; }
+        tmp_root=$(dirname "${checkout}") ;
+        current_source="${source}";
+      fi
+      [ -n "${checkout}" ] || { printf "  %-32s %s\n" "${item_name}" "source unreachable" ; continue ; }
+      local sha; sha=$(git -C "${checkout}" rev-parse "HEAD:${source_path}" 2>/dev/null) ;
+      if [ -z "${sha}" ] ; then
+        printf "  %-32s %s\n" "${item_name}" "removed upstream — left as is" ;
+      elif [ "${sha}" == "${hash}" ] ; then
+        printf "  %-32s %s\n" "${item_name}" "up to date" ;
+      else
+        if [ "${kind}" == 'ai-skills' ] ; then
+          rsync -a --delete "${checkout}/${source_path}/" "${target}/${item_name}/" ;
+        else
+          cp "${checkout}/${source_path}" "${target}/" ;
+        fi
+        ai_items_lock_set "${target}" "${kind}" "${item_name}" "${source}" "repo" "${source_path}" "${sha}" ;
+        updated=$((updated+1)) ;
+        printf "  %-32s %s\n" "${item_name}" "updated" ;
+      fi
+    else
+      local draft_path="${WORKSPACE_ROOT}/${source_path}";
+      if [ ! -e "${draft_path}" ] ; then
+        printf "  %-32s %s\n" "${item_name}" "draft removed — left as is" ;
+        continue ;
+      fi
+      local new_hash; new_hash=$(ai_items_local_hash "${draft_path}") ;
+      if [ "${new_hash}" == "${hash}" ] ; then
+        printf "  %-32s %s\n" "${item_name}" "up to date" ;
+      else
+        if [ "${kind}" == 'ai-skills' ] ; then
+          rsync -a "${draft_path}/" "${target}/${item_name}/" ;
+        else
+          cp "${draft_path}" "${target}/" ;
+        fi
+        ai_items_lock_set "${target}" "${kind}" "${item_name}" "workspace" "workspace" "${source_path}" "${new_hash}" ;
+        updated=$((updated+1)) ;
+        printf "  %-32s %s\n" "${item_name}" "updated from draft" ;
+      fi
+    fi
+  done <<< "$(echo "${rows}" | sort -t$'\t' -k3,3)"
+
+  [ -n "${tmp_root}" ] && rm -rf "${tmp_root}" ;
+  echo "Checked ${checked}, updated ${updated}.";
+
+  # Skills the skills.sh CLI installed live in ITS lock, not this one — its own
+  # update covers them, after the workspace-tracked entries above. Its update has
+  # no per-skill filter, so a NAMED update stays on the workspace lock alone
+  # rather than refreshing every CLI-tracked skill as a side effect.
+  if [ "${kind}" == 'ai-skills' ] && ai_items_skills_cli_available \
+     && { [ -z "${name}" ] || [ "${name}" == '_all_' ] ; } ; then
+    echo "skills.sh CLI (npx skills update):" ;
+    ai_items_skills_cli_update "${to}" || echo "  (skills.sh CLI update failed — workspace-tracked items above are done)" ;
+  fi
+
+  [ "${updated}" -gt 0 ] && echo "Restart your Claude Code session to pick the updates up." ;
+  return 0 ;
+}