Skip to content

The design language that makes your AI harness better at design.

JavaScript

Fix: name the step that failed when a skill bundle download fails (#1138) (#1141)

Abdul Wahab5cb95eea9c96
diff --git a/crates/skills/src/bundle.rs b/crates/skills/src/bundle.rs
index 25c95a562..fb66da1c8 100644
--- a/crates/skills/src/bundle.rs
+++ b/crates/skills/src/bundle.rs
@@ -161,41 +161,44 @@ pub fn download_file_with(
dest: &str,
fetch: &mut dyn FnMut(&str) -> Result<FetchResponse, String>,
) -> Result<(), String> {
- download_file_capped(url, dest, fetch, MAX_DOWNLOAD_BYTES)
+ download_file_capped(url, dest, fetch, MAX_DOWNLOAD_BYTES).map_err(BundleError::into_detail)
}
+/// Failures of the request or the response body are `Download`; failures to
+/// create or write `dest` are `Unpack`.
fn download_file_capped(
url: &str,
dest: &str,
fetch: &mut dyn FnMut(&str) -> Result<FetchResponse, String>,
max_bytes: u64,
-) -> Result<(), String> {
+) -> Result<(), BundleError> {
+ use BundleError::{Download, Unpack};
let mut current = url.to_string();
let mut hops_left = 5;
loop {
// JS: new URL(current) throws `Invalid URL` (a TypeError) first.
- let parsed = url::Url::parse(&current).map_err(|_| "Invalid URL".to_string())?;
+ let parsed = url::Url::parse(&current).map_err(|_| Download("Invalid URL".to_string()))?;
if parsed.scheme() != "https" {
- return Err("Refusing non-HTTPS URL".to_string());
+ return Err(Download("Refusing non-HTTPS URL".to_string()));
}
- let res = fetch(&current)?;
+ let res = fetch(&current).map_err(Download)?;
if res.status >= 300 && res.status < 400 {
let Some(location) = res.location else {
- return Err(format!("HTTP {}", res.status));
+ return Err(Download(format!("HTTP {}", res.status)));
};
if hops_left <= 0 {
- return Err("Too many redirects".to_string());
+ return Err(Download("Too many redirects".to_string()));
}
hops_left -= 1;
// JS: new URL(location, current).href
current = parsed
.join(&location)
- .map_err(|_| "Invalid URL".to_string())?
+ .map_err(|_| Download("Invalid URL".to_string()))?
.to_string();
continue;
}
if res.status != 200 {
- return Err(format!("HTTP {}", res.status));
+ return Err(Download(format!("HTTP {}", res.status)));
}
// JS-PARITY: the `if (!res.body) throw new Error('Empty response
// body')` guard has no ureq equivalent — a response always carries a
@@ -209,36 +212,45 @@ fn download_file_capped(
// EEXIST comes from the `wx` open itself: JS leaves the existing
// file alone and rethrows.
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
- return Err(util::node_error("open", dest, &e));
+ return Err(Unpack(util::node_error("open", dest, &e)));
}
Err(e) => {
util::rm_rf(dest);
- return Err(util::node_error("open", dest, &e));
+ return Err(Unpack(util::node_error("open", dest, &e)));
}
};
// Stream at most `max_bytes` to disk; a longer response is rejected
- // and the partial file removed (triage C4).
- let copied = std::io::copy(&mut res.body.take(max_bytes + 1), &mut file)
- .and_then(|n| {
- use std::io::Write;
- file.flush().map(|_| n)
- });
- match copied {
- Ok(n) if n > max_bytes => {
- drop(file);
- util::rm_rf(dest);
- return Err(format!(
- "response too large downloading {current} (over {max_bytes} bytes)"
- ));
+ // and the partial file removed (triage C4). Reads and writes are
+ // separate calls so a full disk is not reported as a network failure.
+ use std::io::Write;
+ let mut body = res.body.take(max_bytes + 1);
+ let mut buffer = [0u8; 64 * 1024];
+ let mut copied = 0u64;
+ let result = loop {
+ match body.read(&mut buffer) {
+ Ok(0) => break file.flush().map_err(|e| Unpack(e.to_string())),
+ Ok(n) => {
+ copied += n as u64;
+ if let Err(e) = file.write_all(&buffer[..n]) {
+ break Err(Unpack(e.to_string()));
+ }
+ }
+ Err(e) if e.kind() == std::io::ErrorKind::Interrupted => {}
+ Err(e) => break Err(Download(e.to_string())),
}
- Ok(_) => {}
- Err(e) => {
- drop(file);
- util::rm_rf(dest);
- return Err(e.to_string());
+ };
+ let result = result.and_then(|()| {
+ if copied > max_bytes {
+ Err(Download(format!("response too large downloading {current} (over {max_bytes} bytes)")))
+ } else {
+ Ok(())
}
+ });
+ if result.is_err() {
+ drop(file);
+ util::rm_rf(dest);
}
- return Ok(());
+ return result;
}
}
@@ -340,50 +352,101 @@ fn extract_zip_from<R: Read + std::io::Seek>(reader: R, target_dir: &str, cwd: &
/// JS: downloadAndExtractBundle() after #479: a mkdtemp staging dir holds
/// both the zip and the extracted tree; any failure removes the whole
/// staging dir before rethrowing. Returns the staging dir (caller removes).
-pub fn download_and_extract_bundle(sys: &Sys) -> Result<String, String> {
+pub fn download_and_extract_bundle(sys: &Sys) -> Result<String, BundleError> {
if let Some(local) = sys.env.get("IMPECCABLE_BUNDLE_PATH").filter(|v| !v.is_empty()) {
- return copy_or_extract_local_bundle(sys, local);
+ return copy_or_extract_local_bundle(sys, local).map_err(BundleError::Local);
}
download_remote_bundle(sys, &mut ureq_fetch, bundle_signature::trusted_keys())
}
+/// Why no bundle was produced. A remote failure names the step that failed,
+/// so a network problem never reads as a signature problem (#1138).
+#[derive(Debug)]
+pub enum BundleError {
+ /// Fetching the release, its signature or its ZIP failed: connect error,
+ /// HTTP error status, stall, size cap.
+ Download(String),
+ /// The release could not be authenticated.
+ Verify(String),
+ /// Staging, saving, reading back or extracting the bundle on this machine failed
+ /// (disk space, permissions, an entry the extractor refuses).
+ Unpack(String),
+ /// An `IMPECCABLE_BUNDLE_PATH` bundle could not be read.
+ Local(String),
+}
+
+impl BundleError {
+ /// A failed remote bundle, which `install` treats as fatal even over an
+ /// existing installation (#734).
+ pub fn is_remote(&self) -> bool {
+ !matches!(self, BundleError::Local(_))
+ }
+
+ fn into_detail(self) -> String {
+ match self {
+ BundleError::Download(e) | BundleError::Verify(e) | BundleError::Unpack(e) | BundleError::Local(e) => e,
+ }
+ }
+}
+
+impl std::fmt::Display for BundleError {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ const RETRY: &str = ". Nothing was installed; retry or update the CLI. If this persists, report it at https://github.com/pbakaus/impeccable/issues/new";
+ match self {
+ BundleError::Download(e) => write!(f, "Could not download skill bundle: {e}{RETRY}"),
+ BundleError::Verify(e) => write!(f, "{}{e}{RETRY}", bundle_signature::ERROR_PREFIX),
+ BundleError::Unpack(e) => write!(f, "Could not unpack skill bundle: {e}{RETRY}"),
+ BundleError::Local(e) => f.write_str(e),
+ }
+ }
+}
+
+impl From<BundleError> for String {
+ fn from(e: BundleError) -> String {
+ e.to_string()
+ }
+}
+
fn download_remote_bundle(
sys: &Sys,
fetch: &mut dyn FnMut(&str) -> Result<FetchResponse, String>,
keys: Result<TrustedKeys, String>,
-) -> Result<String, String> {
- keys.and_then(|keys| download_and_extract_signed_bundle(sys, fetch, &keys))
- .map_err(|e| format!("{}{e}. Nothing was installed; retry or update the CLI. If this persists, report it at https://github.com/pbakaus/impeccable/issues/new", bundle_signature::ERROR_PREFIX))
+) -> Result<String, BundleError> {
+ download_and_extract_signed_bundle(sys, fetch, &keys.map_err(BundleError::Verify)?)
}
fn download_and_extract_signed_bundle(
sys: &Sys,
fetch: &mut dyn FnMut(&str) -> Result<FetchResponse, String>,
keys: &TrustedKeys,
-) -> Result<String, String> {
+) -> Result<String, BundleError> {
+ use BundleError::{Download, Unpack, Verify};
let tmp = util::tmpdir(&sys.env);
- let staging = util::mkdtemp(&jsp::join(&[&tmp, "impeccable-update-"]))?;
+ let staging = util::mkdtemp(&jsp::join(&[&tmp, "impeccable-update-"])).map_err(Unpack)?;
let tmp_zip = jsp::join(&[&staging, "bundle.zip"]);
let tmp_signature = jsp::join(&[&staging, "bundle.sig.json"]);
- let result = (|| -> Result<(), String> {
+ let result = (|| -> Result<(), BundleError> {
// Resolve once, then request both assets from that exact release. Never
// pair a latest-version lookup with a independently changing ZIP URL.
- let response = fetch(&format!("{API_BASE}/api/download/bundle/universal"))?;
+ let response = fetch(&format!("{API_BASE}/api/download/bundle/universal")).map_err(Download)?;
if !matches!(response.status, 301 | 302 | 303 | 307 | 308) {
- return Err(format!("Expected a signed bundle release redirect (HTTP {})", response.status));
+ // An error status is the server failing; any other answer is not
+ // the pinned release redirect.
+ let error = format!("Expected a signed bundle release redirect (HTTP {})", response.status);
+ return Err(if response.status >= 400 { Download(error) } else { Verify(error) });
}
- let location = response.location.ok_or("Missing bundle release redirect")?;
- let version = bundle_signature::release_version(&location)?;
+ let location = response.location.ok_or_else(|| Verify("Missing bundle release redirect".into()))?;
+ let version = bundle_signature::release_version(&location).map_err(Verify)?;
download_file_capped(&format!("{location}.sig.json"), &tmp_signature, fetch, MAX_SIGNATURE_BYTES)?;
- download_file_with(&location, &tmp_zip, fetch)?;
- let signature = std::fs::read(&tmp_signature).map_err(|e| e.to_string())?;
- let file = std::fs::File::open(&tmp_zip).map_err(|e| e.to_string())?;
+ download_file_capped(&location, &tmp_zip, fetch, MAX_DOWNLOAD_BYTES)?;
+ let signature = std::fs::read(&tmp_signature).map_err(|e| Unpack(e.to_string()))?;
+ let file = std::fs::File::open(&tmp_zip).map_err(|e| Unpack(e.to_string()))?;
let mut reader = std::io::BufReader::new(file);
- bundle_signature::verify_reader(&mut reader, &signature, &version, keys)?;
+ bundle_signature::verify_reader(&mut reader, &signature, &version, keys).map_err(Verify)?;
// Reuse the verified file handle rather than reopening by pathname.
use std::io::Seek;
- reader.rewind().map_err(|e| e.to_string())?;
- extract_zip_from(reader, &staging, &sys.cwd)?;
+ reader.rewind().map_err(|e| Unpack(e.to_string()))?;
+ extract_zip_from(reader, &staging, &sys.cwd).map_err(Unpack)?;
util::rm_rf(&tmp_zip);
util::rm_rf(&tmp_signature);
Ok(())
@@ -1029,7 +1092,7 @@ mod tests {
body: Box::new(std::io::repeat(b'a')),
})
};
- let err = download_file_capped("https://x/bundle", &dest, &mut fetch, 4096).unwrap_err();
+ let err = download_file_capped("https://x/bundle", &dest, &mut fetch, 4096).unwrap_err().into_detail();
assert!(err.contains("response too large"), "{err}");
assert!(!std::path::Path::new(&dest).exists());
let _ = std::fs::remove_dir_all(&dir);
@@ -1071,8 +1134,46 @@ mod tests {
panic!("A failed keyring must never reach the network");
};
let error = download_remote_bundle(&sys, &mut fetch, Err("Invalid compiled bundle signing keyring".into())).unwrap_err();
- assert!(error.starts_with(bundle_signature::ERROR_PREFIX), "{error}");
- assert!(error.contains("Invalid compiled bundle signing keyring"), "{error}");
+ assert!(matches!(error, BundleError::Verify(_)), "{error}");
+ assert!(error.to_string().starts_with(bundle_signature::ERROR_PREFIX), "{error}");
+ assert!(error.to_string().contains("Invalid compiled bundle signing keyring"), "{error}");
+ }
+
+ #[test]
+ fn transport_and_staging_failures_name_their_step() {
+ let release = "https://github.com/pbakaus/impeccable/releases/download/skill-v4.2.0/universal.zip";
+ struct Stalled;
+ impl Read for Stalled {
+ fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
+ Err(std::io::Error::new(std::io::ErrorKind::TimedOut, "no data received"))
+ }
+ }
+ for case in ["connect", "zip-stall"] {
+ let root = tmp_dir(case);
+ let sys = Sys::new([("TMPDIR".into(), root.clone()), ("TEMP".into(), root.clone())].into(), root.clone());
+ let mut fetch = |url: &str| -> Result<FetchResponse, String> {
+ match (case, url) {
+ ("connect", _) => Err("connection refused".into()),
+ (_, u) if u.ends_with("/api/download/bundle/universal") => Ok(FetchResponse { status: 302, location: Some(release.into()), body: Box::new(std::io::empty()) }),
+ (_, u) if u.ends_with(".sig.json") => Ok(FetchResponse { status: 200, location: None, body: Box::new(std::io::Cursor::new(b"{}".to_vec())) }),
+ _ => Ok(FetchResponse { status: 200, location: None, body: Box::new(Stalled) }),
+ }
+ };
+ let error = download_remote_bundle(&sys, &mut fetch, Ok(Default::default())).unwrap_err();
+ assert!(matches!(error, BundleError::Download(_)), "{case}: {error}");
+ assert!(error.to_string().starts_with("Could not download skill bundle: "), "{case}: {error}");
+ util::rm_rf(&root);
+ }
+ let unwritable = Sys::new([("TMPDIR".into(), "/nonexistent/impeccable".into()), ("TEMP".into(), "/nonexistent/impeccable".into())].into(), "/".into());
+ let mut fetch = |_: &str| -> Result<FetchResponse, String> { panic!("staging fails before any request") };
+ let error = download_remote_bundle(&unwritable, &mut fetch, Ok(Default::default())).unwrap_err();
+ assert!(matches!(error, BundleError::Unpack(_)), "{error}");
+ let mut fetch = |_: &str| -> Result<FetchResponse, String> {
+ Ok(FetchResponse { status: 200, location: None, body: Box::new(std::io::Cursor::new(b"zip".to_vec())) })
+ };
+ let error = download_file_capped("https://example.com/b.zip", "/nonexistent/impeccable/b.zip", &mut fetch, MAX_DOWNLOAD_BYTES).unwrap_err();
+ assert!(matches!(error, BundleError::Unpack(_)), "a failed save is not a download failure: {error}");
+ assert!(!BundleError::Local("Local bundle not found: x".into()).is_remote());
}
#[test]
@@ -1092,10 +1193,15 @@ mod tests {
};
let error = download_and_extract_signed_bundle(&sys, &mut fetch, &Default::default()).unwrap_err();
if matches!(status, 301 | 302 | 303 | 307 | 308) {
- assert_eq!(error, "reached signature download", "HTTP {status}");
+ assert!(matches!(&error, BundleError::Download(m) if m == "reached signature download"), "HTTP {status}: {error}");
assert_eq!(requests, 2);
} else {
- assert!(error.contains("Expected a signed bundle release redirect"), "{error}");
+ assert!(error.to_string().contains("Expected a signed bundle release redirect"), "{error}");
+ if status >= 400 {
+ assert!(matches!(error, BundleError::Download(_)), "HTTP {status}: {error}");
+ } else {
+ assert!(matches!(error, BundleError::Verify(_)), "HTTP {status}: {error}");
+ }
assert_eq!(requests, 1);
}
assert_eq!(std::fs::read_dir(&root).unwrap().count(), 0);
@@ -1157,6 +1263,12 @@ mod tests {
util::rm_rf(&staging);
} else {
let error = result.unwrap_err();
+ if matches!(case, "missing" | "oversized" | "downgrade") {
+ assert!(matches!(error, BundleError::Download(_)), "{case}: {error}");
+ } else {
+ assert!(matches!(error, BundleError::Verify(_)), "{case}: {error}");
+ }
+ let error = error.to_string();
if case == "malformed-zip" {
assert!(error.contains("size"), "must reject before ZIP parsing: {error}");
}
diff --git a/crates/skills/src/commands.rs b/crates/skills/src/commands.rs
index a1d3ba281..6e9f5c9b5 100644
--- a/crates/skills/src/commands.rs
+++ b/crates/skills/src/commands.rs
@@ -621,9 +621,9 @@ fn install(flags: &[String], io: &mut Io) -> R<()> {
match bundle::download_and_extract_bundle(&sys) {
Ok(dir) => bundle_dir = Some(dir),
Err(e) => {
- if e.starts_with(crate::bundle_signature::ERROR_PREFIX)
+ if e.is_remote()
|| !missing_hook_targets.is_empty() || !missing_selected_targets.is_empty() {
- return Err(e);
+ return Err(e.into());
}
update_check_skipped = true;
out(io, &format!("Could not check for skill updates: {e}"));
diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.md
index 7f228a325..52ba13645 100644
--- a/docs/CLI-CONTRACT.md
+++ b/docs/CLI-CONTRACT.md
@@ -484,7 +484,7 @@ retain their local-development trust behavior. See [bundle signing](BUNDLE-SIGNI
sorted by `id.localeCompare`.
- **Flag parsing** (`getFlagValue`): `--name=value` or `--name value` (next arg not starting with `-`). Boolean flags via `includes`.
- **install flags**: `--force`, `-y|--yes`, `--no-hooks`, `--providers=<list>`, scope: `--user|--home|--global` → user; `--project|--local` → project; `--scope=<v>`/`--install-scope=<v>` normalized (`u|user|home|global`→user, `p|project|local|repo`→project; unknown → error `Unknown install scope: ${v}. Use --scope=project or --scope=global.`). Project root = nearest ancestor with `.git`, else cwd. Detection: project harness dirs present in root, plus `GLOBAL_HARNESS_HINTS` under home (`.agent`, `.gemini/antigravity*`→`.agent`, `.claude`, `.codex`→`.agents`, `.cursor`, `.dsh` (resolved `$DSH_HOME`, fallback `~/.dsh`), `.gemini`, `.grok`, `.hermes`, `.kiro`, `.opencode`, opencode config dir, `.pi`, `.qoder`, `.rovodev`, `.vibe`). Targets: explicit list wins (invalid names → `Unknown provider(s): ...`); `-y` → detected project providers, else detected user providers, else DEFAULT_TARGETS; interactive → prints "Detected harnesses:" table then radio/checkbox prompts (raw-mode TTY) or line prompts (`Install target: [1] Detected only (...) [2] Customize [1]: `, `Select harnesses (comma-separated: ...)`). Scope: explicit; `-y` → project; interactive prompt `Install location` (Project/Global). Hooks: `decideHookInstall` reads `hook.consent` in config(.local).json; declined→false, accepted→true; all targets already have hook markers→true; `-y` or non-TTY→true; else prints HOOK_EXPLAINER and asks `Install the design hook? (Y/n) `, storing consent in `.impeccable/config.local.json`.
- Bundle: `IMPECCABLE_BUNDLE_PATH` (dir or zip) else download `https://impeccable.style/api/download/bundle/universal` (https only, up to 5 redirects, non-200 → `HTTP ${status}`; 30 s connect timeout and a 60 s idle timeout on every read, with no cap on the whole transfer, so a slow but steady connection finishes (#1115); a stall → `no data received for 60 s downloading <url>; check the network and retry`, under the `Could not verify skill bundle: ` prefix) to `${tmpdir}/impeccable-update-${Date.now()}.zip`, extracted with `fflate.unzipSync` into `${tmpdir}/impeccable-update-${Date.now()}` (zip-slip guarded: `Refusing to extract entry outside target dir: ${entry}`). Bundle layout `<bundle>/<provider>/skills/<skill>/...`, `<bundle>/<provider>/agents/*.md`, hook manifests `<bundle>/.claude/settings.json`, `.cursor/hooks.json`, `.codex/hooks.json`, `.github/hooks/impeccable.json`, `.grok/hooks/impeccable.json`.
+ Bundle: `IMPECCABLE_BUNDLE_PATH` (dir or zip) else download `https://impeccable.style/api/download/bundle/universal` (https only, up to 5 redirects, non-200 → `HTTP ${status}`; 30 s connect timeout and a 60 s idle timeout on every read, with no cap on the whole transfer, so a slow but steady connection finishes (#1115); a stall → `no data received for 60 s downloading <url>; check the network and retry`) to `${tmpdir}/impeccable-update-${Date.now()}.zip`, extracted with `fflate.unzipSync` into `${tmpdir}/impeccable-update-${Date.now()}` (zip-slip guarded: `Refusing to extract entry outside target dir: ${entry}`). Bundle layout `<bundle>/<provider>/skills/<skill>/...`, `<bundle>/<provider>/agents/*.md`, hook manifests `<bundle>/.claude/settings.json`, `.cursor/hooks.json`, `.codex/hooks.json`, `.github/hooks/impeccable.json`, `.grok/hooks/impeccable.json`. A failed remote bundle prints either `Could not download skill bundle: ${msg}` (the release lookup, signature, or ZIP request failed: connect error, HTTP status, stall, size cap), `Could not verify skill bundle: ${msg}` (keyring, release redirect or version check, signature envelope, key, signature, digest or size mismatch), or `Could not unpack skill bundle: ${msg}` (staging, saving, reading back or extracting the bundle on this machine), each followed by `. Nothing was installed; retry or update the CLI. If this persists, report it at https://github.com/pbakaus/impeccable/issues/new`.
Fresh install: `stdout> \nDownloading impeccable skills...`; migrate `*-impeccable` prefixed dirs → `impeccable`; copy each skill dir (rm existing dest first; drop an in-project cross-provider symlinked skills dir); copy agents (`.github`→`.github/agents` or `~/.copilot/agents`; `.cursor`→`.cursor/agents` or `~/.cursor/agents`); write hooks (Claude project scope: `.claude/settings.local.json`, skipped when project `.claude/settings.json` already carries the marker; Claude user scope: `~/.claude/settings.json`, with obsolete Impeccable entries pruned from `~/.claude/settings.local.json`; other destinations: `.cursor/hooks.json`, `.codex/hooks.json` for `.agents`, `.github/hooks/impeccable.json`, `.grok/hooks/impeccable.json`); merged with existing JSON (`mergeHookManifests`: strips existing impeccable entries by markers `skills/impeccable/scripts/hook-probe.mjs|hook.mjs|hook-before-edit.mjs|hook-after-edit.mjs|hook-stop.mjs`, then appends fresh); invalid existing JSON → error `Existing hook manifest is not valid JSON: ${dest}. Re-run with --force to replace it.` (with `--force`, `.bak` written). Claude and Gemini user settings are never replaced wholesale when invalid. Hook command rewriting: `[ ! -f '<abs>' ] || node '<abs>'` (POSIX, single-quote-escaped) when absolute (user scope or global skill), else `[ ! -f "<rel>" ] || node "<rel>"` where rel = `${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs` (Claude), `.agents/skills/impeccable/scripts/hook.mjs` (Codex; plus `commandWindows: if exist "<p>" (node "<p>" & exit /b)`), `.cursor/skills/impeccable/scripts/hook-before-edit.mjs`; on win32 for non-Codex: `node -e "<WIN32_HOOK_GUARD_SCRIPT>" "<path>"`. Output: `Installed impeccable into: ${targets.join(', ')} (${'global'|'project'})`, optional `Installed <Provider> agents into: <path>` (+ shadow warning), `Installed hooks into: ...`, then `\nDone! Now type /impeccable init in your AI coding agent's chat (not in this terminal) to set up design context.\n`. Errors: `Download failed: ...` / `Install failed: ...` / `Nothing was installed: the bundle had no variants for ...` → exit 1.
A Claude user-scope hook write also prunes obsolete Impeccable entries from the current project's `.claude/settings.local.json`, preventing a stale project hook from firing alongside the user hook.
GitHub Copilot hook (`.github/hooks/impeccable.json` in the project, `bash` key): a project install keeps the bundle's portable `$(git rev-parse --show-toplevel)/.github/skills/impeccable/scripts/impeccable` command; a user-scope install rewrites it to the home launcher (`$HOME/.github/skills/impeccable/scripts/impeccable` on POSIX, the resolved profile path with forward slashes on Windows), unless the project ships its own `.github/skills/impeccable/scripts/impeccable`, whose committed portable manifest is left as is. In user scope a project manifest that names the portable path while the project has no Copilot skill does not count as installed, so a repeat install rewrites it.