happyskills 1.12.1 → 1.13.1

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.13.1] - 2026-06-29
+
+### Fixed
+
+- Stop a transient session-refresh hiccup from becoming a terminal "session expired" auth failure on a **write** (`publish`/`release` and other authenticated writes). When your `id_token` had expired and the automatic refresh blipped (a network/cold-start failure on the refresh call), the CLI would fire the write with no token, the API would answer `401`, and that was rendered as `AUTH_REQUIRED` ("your session has expired … run `happyskills login`") — aborting the command even though an immediate retry succeeds. Now, when valid credentials exist on disk but the token simply couldn't be refreshed at that moment, a write surfaces a **retryable** `NETWORK_ERROR` (a `retry` `next_step`) instead of sending a tokenless request. The guard is deliberately narrow: **reads are unchanged** (a `GET` still degrades to anonymous/public results), a **corrupt/unreadable credentials file** still falls through to re-login (it is not turned into an infinite "please retry" loop), and the genuinely-not-signed-in case (no credentials) is unchanged. (Spec 260629-02.)
+
+## [1.13.0] - 2026-06-29
+
+### Added
+
+- Add `list --all-scopes`, which merges project-local and global skills into one listing instead of showing a single scope at a time (`list` = project, `list -g` = global). Every entry is tagged with `scope` (`local`/`global`) and `native` (`true` for managed/draft HappySkills skills, `false` for manually-added external/agent-orphan skills), and the human table gains **Scope** and **Native** columns — so you can see at a glance where each skill is installed and whether it's a native HappySkills skill or one added by hand. In this mode `data.skills` becomes an array (a skill installed in both scopes surfaces once per scope, rather than colliding on a shared `owner/name` key); the single-scope output shape is unchanged for backward compatibility.
+- Add `update --all-scopes`, which updates outdated skills in **both** the project-local and global scopes in one run (local first, then global) and returns a per-scope report: `{ all_scopes: true, scopes: [{ scope: "local", … }, { scope: "global", … }], updated_count, outdated_count }`. Each `scopes[]` entry carries the same payload a single-scope update emits, so partial failure (e.g. local succeeds, global has an error) is visible per scope. Unlike `list --all-scopes`, this is opt-in, not the default — a write should not touch shared global state implicitly, so `update` stays project-local unless `-g` (global) or `--all-scopes` (both) is passed. The single-scope output shape is unchanged.
+- Add passive skill-drift awareness, so you're told when your installed skills have fallen behind the registry without having to remember to check. Before each command, the CLI does a once-per-24h, fire-and-forget, zero-latency check (a synchronous read of a `~/.config/happyskills/skill-update-check.json` cache; a stale cache triggers a background refresh for next time, never blocking the current command) of installed root skills against the registry, spanning **both** the project-local and global locks so a globally-installed constellation is surfaced even during project-scoped work. Outdated skills appear two ways: a one-line nudge on stderr (text mode) and a `SKILLS_UPDATE_AVAILABLE` entry in the existing `warnings[]` array of every command's envelope (`--json` mode) — `data` is untouched and the envelope schema is unchanged. The suggested command is scope-aware (`update --all`, adding `-g` when global skills are behind). Only registry-advance (`outdated`) is reported — never a locally-bumped (`ahead`) or drifted skill. Disable with `HAPPYSKILLS_NO_SKILL_UPDATE_CHECK=1`.
+
 ## [1.12.1] - 2026-06-23
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.12.1",
+	"version": "1.13.1",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/api/client.js

@@ -2,7 +2,7 @@ const { createHash } = require('crypto')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { API_URL, CLI_VERSION } = require('../constants')
 const { ApiError, NetworkError, AuthError } = require('../utils/errors')
-const { load_token } = require('../auth/token_store')
+const { load_token, credentials_present } = require('../auth/token_store')
 const { get_envelope, set_envelope } = require('../utils/intent')
 
 const get_base_url = () => process.env.HAPPYSKILLS_API_URL || API_URL
@@ -29,10 +29,28 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 
 	let token_attached = false
 	if (auth) {
-		const [, token_data] = await load_token()
+		const [token_err, token_data] = await load_token()
 		if (token_data) {
 			headers['Authorization'] = `Bearer ${token_data.id_token}`
 			token_attached = true
+		} else if (!token_err && credentials_present() && method !== 'GET' && method !== 'HEAD') {
+			// A WRITE (non-GET/HEAD) where load_token returned CLEANLY (no error) with no
+			// token, yet the credentials file still exists. That is uniquely the
+			// TRANSIENT-refresh-failure branch: a real session whose id_token expired and
+			// whose proactive refresh blipped (network / cold start) — load_token preserves
+			// the still-valid file and returns [null, null]. Permanent failures (Cognito
+			// rejected the token) and the no-refresh-token case both DELETE the file, and a
+			// corrupt/unreadable file returns [errors, undefined] (token_err set) — so
+			// guarding on `!token_err && file-present` isolates the genuinely-retryable case
+			// and lets a corrupt file fall through to a tokenless request (→ server 401 →
+			// re-login, which overwrites the bad file) rather than a dead retry loop.
+			// Firing a tokenless WRITE in the transient case makes the API answer 401 and
+			// the CLI render it as a terminal AUTH_REQUIRED "your session has expired" — the
+			// spurious-AUTH_REQUIRED bug (spec 260629-02). Surface a retryable error instead.
+			// Scoped to writes ONLY: a read (GET/HEAD) keeps its pre-existing behavior —
+			// proceed tokenless and degrade to anonymous/public results (spec §6.3: "keep
+			// the read-path behavior unchanged"); a write must not silently lose authorship.
+			throw new NetworkError('Your session could not be refreshed right now (a temporary issue). Please retry.')
 		}
 	}
 

package/src/api/client.test.js

@@ -122,3 +122,156 @@ describe('api client — 401 message never tells a signed-in user to log in', ()
 		})
 	})
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Transient backend failure on a write/publish path (spec 260629-02). The API no
+// longer maps a transient verify/lookup hiccup to a 401 "session expired" — it
+// returns a retryable 503 DB_UNAVAILABLE. The CLI must surface that as a RETRY
+// affordance, NOT collapse it into an AUTH_REQUIRED / "run login" dead-end. This
+// is the operator-facing half of the fix: an authenticated, authorized operator
+// whose publish hit a blip is told to retry (and an immediate retry succeeds),
+// instead of being sent down a pointless re-login path.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const with_503 = async (code, fn) => {
+	const orig = global.fetch
+	global.fetch = async () => ({
+		ok: false,
+		status: 503,
+		headers: { get: () => null },
+		json: async () => ({ error: { code, message: 'Authentication is temporarily unavailable. Please retry.' } }),
+	})
+	try { return await fn() } finally { global.fetch = orig }
+}
+
+describe('api client — transient 503 on publish surfaces retry, not a login dead-end (spec 260629-02)', () => {
+	const { next_step_for_error } = require('../constants/next_step_by_error_code')
+
+	it('a 503 DB_UNAVAILABLE on push preserves the retryable code (NOT AUTH_REQUIRED)', async () => {
+		await with_503('DB_UNAVAILABLE', async () => {
+			const [errors] = await client.post('/repos/acme/deploy/push', { commit: 'x' }, { auth: false })
+			assert.ok(errors, 'expected an error tuple')
+			const err = errors.find(e => e && e.name === 'ApiError')
+			assert.ok(err, 'a 503 must surface as an ApiError, not an AuthError')
+			assert.equal(err.code, 'DB_UNAVAILABLE')
+			assert.notEqual(err.code, 'AUTH_REQUIRED')
+			assert.equal(err.status_code, 503)
+		})
+	})
+
+	it('the operator-facing next_step for that code is RETRY, not login', () => {
+		const next_step = next_step_for_error('DB_UNAVAILABLE', 'whatever', {})
+		assert.equal(next_step.action, 'retry')
+		assert.notEqual(next_step.action, 'login')
+	})
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The ACTUAL 2026-06-29 incident (spec 260629-02 Findings): the operator's session
+// had expired and the CLI's proactive token refresh hit a TRANSIENT failure. On a
+// transient refresh failure, load_token preserves the (still-valid) refresh_token
+// on disk but returns null — so the client fired an authed request WITHOUT a token,
+// the API answered 401 (no-token branch), and the CLI rendered it as AUTH_REQUIRED
+// "session expired". An immediate retry (after the refresh blip cleared) succeeded.
+//
+// The fix: a real session whose token can't be refreshed *right now* (file present
+// but load_token null) must surface a RETRYABLE error, never a tokenless request
+// that turns into a terminal "session expired".
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('api client — transient token-refresh failure → retry, never a tokenless 401 (spec 260629-02)', () => {
+	const auth_path = require.resolve('./auth')
+
+	const write_expired_token = (dir) => {
+		const token = {
+			id_token: 'expired-id-token',
+			access_token: 'expired-access-token',
+			refresh_token: 'still-valid-refresh-token',
+			expires_in: 1,
+			stored_at: new Date(Date.now() - 5000).toISOString(),
+		}
+		fs.mkdirSync(path.join(dir, 'happyskills'), { recursive: true })
+		fs.writeFileSync(path.join(dir, 'happyskills', 'credentials.json'), JSON.stringify(token), { mode: 0o600 })
+	}
+
+	// Make the refresh endpoint fail transiently (NetworkError) for both attempts.
+	const with_transient_refresh = async (fn) => {
+		const { NetworkError } = require('../utils/errors')
+		const orig = require.cache[auth_path]
+		require.cache[auth_path] = {
+			id: auth_path, filename: auth_path, loaded: true,
+			exports: { refresh: async () => [[new NetworkError('refresh endpoint unreachable')], null] },
+		}
+		try { return await fn() } finally {
+			if (orig) require.cache[auth_path] = orig; else delete require.cache[auth_path]
+		}
+	}
+
+	it('expired session + transient refresh blip on a push → retryable NetworkError, no tokenless request, NOT AUTH_REQUIRED', async () => {
+		await with_tmp_config(async (dir) => {
+			write_expired_token(dir)
+			await with_transient_refresh(async () => {
+				let fetched = false
+				const orig_fetch = global.fetch
+				global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+				try {
+					const [errors] = await client.post('/acme/deploy/push', { commit: 'z' })
+					assert.ok(errors, 'expected an error tuple')
+					assert.equal(fetched, false, 'must NOT fire a tokenless authed request when the session merely failed to refresh')
+					assert.ok(errors.find(e => e && e.name === 'NetworkError'), 'a transient refresh failure must surface as a retryable NetworkError')
+					assert.ok(!errors.find(e => e && e.name === 'AuthError'), 'must NOT surface AUTH_REQUIRED / "session expired" for a transient refresh blip')
+				} finally { global.fetch = orig_fetch }
+			})
+		})
+	})
+
+	it('NO credentials at all → proceeds tokenless (anonymous), unchanged', async () => {
+		await with_tmp_config(async () => {
+			// No creds file written → genuinely not signed in.
+			let fetched = false
+			const orig_fetch = global.fetch
+			global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+			try {
+				await client.get('/repos:search')
+				assert.equal(fetched, true, 'with no session, the request still goes out (server decides auth)')
+			} finally { global.fetch = orig_fetch }
+		})
+	})
+
+	it('transient refresh blip on a GET (read) → proceeds tokenless (anonymous), read-path unchanged (spec §6.3)', async () => {
+		await with_tmp_config(async (dir) => {
+			write_expired_token(dir)
+			await with_transient_refresh(async () => {
+				let fetched = false
+				const orig_fetch = global.fetch
+				global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+				try {
+					const [errors] = await client.get('/repos:search')
+					assert.equal(fetched, true, 'a read must still go out tokenless during a refresh blip (degrade to anonymous), not throw')
+					assert.ok(!errors || !errors.find(e => e && e.name === 'NetworkError'), 'reads keep their pre-existing anonymous-degrade behavior')
+				} finally { global.fetch = orig_fetch }
+			})
+		})
+	})
+
+	// A corrupt/unparseable credentials file ALSO leaves the file on disk while
+	// load_token yields no token — but it returns an ERROR (JSON.parse throws),
+	// NOT a clean null like the transient-refresh branch. It must NOT be treated as
+	// a retryable refresh blip (retrying never fixes a corrupt file → a dead loop).
+	// The actionable path is the pre-existing one: proceed tokenless so the server
+	// 401s and the user is steered to re-login (which overwrites the bad file).
+	it('corrupt credentials file → does NOT become a retry loop; proceeds tokenless so re-login is reachable', async () => {
+		await with_tmp_config(async (dir) => {
+			fs.mkdirSync(path.join(dir, 'happyskills'), { recursive: true })
+			fs.writeFileSync(path.join(dir, 'happyskills', 'credentials.json'), 'not-valid-json{{{', { mode: 0o600 })
+			let fetched = false
+			const orig_fetch = global.fetch
+			global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+			try {
+				const [errors] = await client.post('/acme/deploy/push', { commit: 'z' })
+				assert.equal(fetched, true, 'a corrupt creds file must proceed tokenless (server → 401 → login), not throw a retryable error')
+				assert.ok(!errors || !errors.find(e => e && e.name === 'NetworkError'), 'a corrupt creds file must NOT be reported as a transient/retryable refresh failure')
+			} finally { global.fetch = orig_fetch }
+		})
+	})
+})

package/src/auth/token_store.js

@@ -97,6 +97,15 @@ const load_token = () => catch_errors('Failed to load token', async () => {
 	return data
 })
 
+// Synchronous presence check for the credentials file. Used by the API client to
+// tell "no session at all" (file absent) apart from "a real session whose token
+// could not be refreshed right now" (file present but load_token returned null —
+// the transient-refresh-failure branch preserves the file, whereas permanent /
+// no-refresh-token failures delete it). See spec 260629-02.
+const credentials_present = () => {
+	try { return fs.existsSync(credentials_path()) } catch { return false }
+}
+
 const clear_token = () => catch_errors('Failed to clear token', async () => {
 	const creds_path = credentials_path()
 	try {
@@ -115,4 +124,4 @@ const require_token = async () => {
 	return data
 }
 
-module.exports = { save_token, load_token, clear_token, require_token }
+module.exports = { save_token, load_token, clear_token, require_token, credentials_present }

package/src/commands/list.js

@@ -1,3 +1,4 @@
+const path = require('path')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { verify_lock_disk_consistency, detect_ahead_state } = require('../lock/verify')
@@ -17,7 +18,10 @@ const HELP_TEXT = `Usage: happyskills list [options]
 List installed skills.
 
 Options:
-  -g, --global      List globally installed skills
+  -g, --global      List globally installed skills (~/.agents/skills/)
+  --all-scopes      List BOTH project-local and global skills in one view,
+                    each row tagged with its scope (local/global) and whether
+                    it is a native HappySkills skill or a manually-added one
   --json            Output as JSON
 
 Aliases: ls
@@ -25,16 +29,23 @@ Aliases: ls
 Examples:
   happyskills list
   happyskills ls --json
-  happyskills ls -g`
+  happyskills ls -g
+  happyskills ls --all-scopes --json`
 
-const run = (args) => catch_errors('List failed', async () => {
-	if (args.flags._show_help) {
-		print_help(HELP_TEXT)
-		return process.exit(EXIT_CODES.SUCCESS)
-	}
+// scope_tag — the public, machine-readable scope label for an entry.
+const scope_tag = (is_global) => (is_global ? 'global' : 'local')
+// scope_label — the human, title-cased scope label for the table.
+const scope_label = (is_global) => (is_global ? 'Global' : 'Local')
 
-	const is_global = args.flags.global || false
-	const project_root = find_project_root()
+// gather_scope — collect the full, render-ready inventory for ONE scope
+// (project or global). Returns normalized "views" so the JSON and human
+// renderers share one computation of status / type / enabled, rather than
+// each re-deriving it. The four buckets mirror `list`'s data contract:
+//   managed_views  → native, recorded in skills-lock.json (data.skills)
+//   draft_skills   → native, scaffolded by `init`, not yet published (data.drafts)
+//   external_skills→ manual/foreign on disk (data.external)
+//   orphan_skills  → manual/foreign dropped into an agent folder (data.agent_orphans)
+const gather_scope = (is_global, project_root, agents_flag) => catch_errors('Gather scope failed', async () => {
 	const base_dir = skills_dir(is_global, project_root)
 
 	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
@@ -42,7 +53,7 @@ const run = (args) => catch_errors('List failed', async () => {
 	const managed_entries = Object.entries(skills)
 
 	// Resolve agents and build enabled/disabled map for managed skills
-	const [, agents_result] = await resolve_agents(args.flags.agents, { global: is_global, project_root })
+	const [, agents_result] = await resolve_agents(agents_flag, { global: is_global, project_root })
 	const agents = agents_result?.agents || []
 	const managed_short_names = managed_entries.map(([k]) => k.split('/')[1])
 	const [, enabled_map] = agents.length > 0
@@ -65,31 +76,13 @@ const run = (args) => catch_errors('List failed', async () => {
 	const [, agent_orphans] = await scan_agent_orphan_skills(AGENTS, is_global, project_root, all_known_names)
 	const orphan_skills = agent_orphans || []
 
-	if (managed_entries.length === 0 && draft_skills.length === 0 && external_skills.length === 0 && orphan_skills.length === 0) {
-		if (args.flags.json) {
-			print_json({ data: { skills: {}, drafts: [], external: [], agent_orphans: [] } })
-			return
-		}
-		print_info('No skills installed.')
-		return
-	}
-
-	// Resolve type for each managed entry from lock data or skill.json on disk
-	const resolve_type = async (name, data) => {
-		if (data.type) return data.type
-		const dir = skill_install_dir(base_dir, name.split('/')[1])
-		const json_path = require('path').join(dir, SKILL_JSON)
-		const [, manifest] = await read_json(json_path)
-		return manifest?.type || SKILL_TYPES.SKILL
-	}
-
 	// Compute drift AND ahead state up-front for every managed entry. Cheap
 	// (one skill.json read per skill, plus an optional CHANGELOG read) and lets
 	// both the JSON and human paths report identically.
 	//
 	// §10.5: drift is narrowed to genuine inconsistency (regression, missing
-	// files); the disk-greater-than-lock case is reported under top-level
-	// status:ahead, not under drift.
+	// files); the disk-greater-than-lock case is reported under status:ahead,
+	// not under drift.
 	const drift_by_skill = {}
 	const ahead_by_skill = {}
 	await Promise.all(managed_entries.map(async ([name, data]) => {
@@ -104,86 +97,167 @@ const run = (args) => catch_errors('List failed', async () => {
 		if (ahead && ahead.ahead) ahead_by_skill[name] = ahead
 	}))
 
-	if (args.flags.json) {
-		const skills_map = {}
-		for (const [name, data] of managed_entries) {
-			const short = name.split('/')[1]
-			const dir = skill_install_dir(base_dir, short)
-			const [, exists] = await file_exists(dir)
-			const drift = drift_by_skill[name]
-			const ahead = ahead_by_skill[name]
-			let status
-			if (drift) status = 'drift'
-			else if (ahead) status = 'ahead'
-			else if (exists) status = 'installed'
-			else status = 'missing'
-			const source = data.requested_by?.includes('__root__') ? 'direct' : 'dep'
-			const type = await resolve_type(name, data)
-			const enabled = enabled_map?.get(short) ?? true
-			const entry = { version: data.version, type, source, status, enabled }
-			if (drift) entry.drift = { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual }
-			if (ahead) entry.ahead = {
-				lock_version: ahead.lock_version,
-				disk_version: ahead.disk_version,
-				has_changelog_entry: ahead.has_changelog_entry || false,
-				changelog_version: ahead.changelog_version || null
-			}
-			skills_map[name] = entry
-		}
-		const drafts = draft_skills.map(s => ({
-			name: s.name,
-			description: s.description || '',
-			version: s.version || null,
-			type: s.type || SKILL_TYPES.SKILL
-		}))
-		const external = external_skills.map(s => ({ name: s.name, description: s.description || '' }))
-		const agent_orphan_list = orphan_skills.map(s => ({
-			name: s.name,
-			description: s.description || '',
-			agents: s.agents
-		}))
-		print_json({ data: { skills: skills_map, drafts, external, agent_orphans: agent_orphan_list } })
-		return
+	const resolve_type = async (name, data) => {
+		if (data.type) return data.type
+		const dir = skill_install_dir(base_dir, name.split('/')[1])
+		const [, manifest] = await read_json(path.join(dir, SKILL_JSON))
+		return manifest?.type || SKILL_TYPES.SKILL
 	}
 
-	const rows = []
-	for (const [name, data] of managed_entries) {
+	// Normalize each managed entry into a single render-ready view. Both the
+	// JSON and human renderers consume these, so status/type/enabled are
+	// computed exactly once.
+	const managed_views = await Promise.all(managed_entries.map(async ([name, data]) => {
 		const short = name.split('/')[1]
 		const dir = skill_install_dir(base_dir, short)
 		const [, exists] = await file_exists(dir)
 		const drift = drift_by_skill[name]
 		const ahead = ahead_by_skill[name]
-		let status_label
-		if (drift) status_label = red(`drift (${drift.reason})`)
-		else if (ahead) status_label = `ahead (disk ${ahead.disk_version})`
-		else if (exists) status_label = 'installed'
-		else status_label = yellow('missing')
+		let status
+		if (drift) status = 'drift'
+		else if (ahead) status = 'ahead'
+		else if (exists) status = 'installed'
+		else status = 'missing'
 		const source = data.requested_by?.includes('__root__') ? 'direct' : 'dep'
 		const type = await resolve_type(name, data)
-		const display_name = type === SKILL_TYPES.KIT ? `${name} [kit]` : name
 		const enabled = enabled_map?.get(short) ?? true
-		const enabled_label = enabled ? green('enabled') : yellow('disabled')
-		rows.push([display_name, data.version, source, status_label, enabled_label])
+		return { name, short, version: data.version, type, source, status, enabled, drift, ahead }
+	}))
+
+	return {
+		is_global,
+		managed_views,
+		draft_skills,
+		external_skills,
+		orphan_skills,
 	}
+}).then(([errors, result]) => {
+	if (errors) throw e('Failed to gather scope', errors)
+	return result
+})
 
-	for (const s of draft_skills) {
-		const type_label = s.type === SKILL_TYPES.KIT ? `${s.name} [kit]` : s.name
-		rows.push([type_label, s.version || '-', 'draft', 'unpublished', '-'])
+// json_managed_entry — the canonical per-skill JSON shape, shared by the
+// object form (single scope) and the array form (--all-scopes).
+const json_managed_entry = (v) => {
+	const entry = { version: v.version, type: v.type, source: v.source, status: v.status, enabled: v.enabled }
+	if (v.drift) entry.drift = { reason: v.drift.reason, lock_version: v.drift.expected, disk_version: v.drift.actual }
+	if (v.ahead) entry.ahead = {
+		lock_version: v.ahead.lock_version,
+		disk_version: v.ahead.disk_version,
+		has_changelog_entry: v.ahead.has_changelog_entry || false,
+		changelog_version: v.ahead.changelog_version || null,
 	}
+	return entry
+}
+
+const run = (args) => catch_errors('List failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const all_scopes = args.flags['all-scopes'] || false
+	const is_global = args.flags.global || false
+	const project_root = find_project_root()
+
+	// --all-scopes overrides -g: it always covers BOTH project and global.
+	const scope_flags = all_scopes ? [false, true] : [is_global]
+	const scopes = await Promise.all(scope_flags.map(g => gather_scope(g, project_root, args.flags.agents)))
+
+	const total_entries = scopes.reduce((n, s) =>
+		n + s.managed_views.length + s.draft_skills.length + s.external_skills.length + s.orphan_skills.length, 0)
 
-	for (const s of external_skills) {
-		rows.push([s.name, '-', 'external', 'installed', '-'])
+	if (total_entries === 0) {
+		if (args.flags.json) {
+			print_json({ data: all_scopes
+				? { skills: [], drafts: [], external: [], agent_orphans: [] }
+				: { skills: {}, drafts: [], external: [], agent_orphans: [] } })
+			return
+		}
+		print_info('No skills installed.')
+		return
 	}
 
-	for (const s of orphan_skills) {
-		const agent_label = s.agents.map(a => a.name).join(', ')
-		rows.push([s.name, '-', `agent-orphan (${agent_label})`, 'installed', '-'])
+	if (args.flags.json) {
+		if (all_scopes) {
+			// Merged, collision-safe ARRAY form: a skill installed in BOTH scopes
+			// is genuinely two installs (separate lock files, possibly different
+			// versions / enabled state) and surfaces as two entries.
+			const skills = []
+			const drafts = []
+			const external = []
+			const agent_orphans = []
+			for (const s of scopes) {
+				const tag = scope_tag(s.is_global)
+				for (const v of s.managed_views) skills.push({ name: v.name, scope: tag, native: true, ...json_managed_entry(v) })
+				for (const d of s.draft_skills) drafts.push({ name: d.name, scope: tag, native: true, description: d.description || '', version: d.version || null, type: d.type || SKILL_TYPES.SKILL })
+				for (const x of s.external_skills) external.push({ name: x.name, scope: tag, native: false, description: x.description || '' })
+				for (const o of s.orphan_skills) agent_orphans.push({ name: o.name, scope: tag, native: false, description: o.description || '', agents: o.agents })
+			}
+			print_json({ data: { skills, drafts, external, agent_orphans } })
+			return
+		}
+
+		// Single-scope (default / -g): object-keyed `skills`, unchanged contract.
+		const s = scopes[0]
+		const skills_map = {}
+		for (const v of s.managed_views) skills_map[v.name] = json_managed_entry(v)
+		const drafts = s.draft_skills.map(d => ({
+			name: d.name,
+			description: d.description || '',
+			version: d.version || null,
+			type: d.type || SKILL_TYPES.SKILL,
+		}))
+		const external = s.external_skills.map(x => ({ name: x.name, description: x.description || '' }))
+		const agent_orphan_list = s.orphan_skills.map(o => ({
+			name: o.name,
+			description: o.description || '',
+			agents: o.agents,
+		}))
+		print_json({ data: { skills: skills_map, drafts, external, agent_orphans: agent_orphan_list } })
+		return
+	}
+
+	// ── Human output ──────────────────────────────────────────────────────
+	// In --all-scopes mode each row is prefixed with Scope + Native cells
+	// (after the Skill name); push_row handles that uniformly so the per-bucket
+	// loops only describe the trailing columns.
+	const rows = []
+	const push_row = (s_label, native_cell, name_cell, tail) => {
+		rows.push(all_scopes ? [name_cell, s_label, native_cell, ...tail] : [name_cell, ...tail])
+	}
+	for (const s of scopes) {
+		const s_label = scope_label(s.is_global)
+		for (const v of s.managed_views) {
+			let status_label
+			if (v.drift) status_label = red(`drift (${v.drift.reason})`)
+			else if (v.ahead) status_label = `ahead (disk ${v.ahead.disk_version})`
+			else if (v.status === 'missing') status_label = yellow('missing')
+			else status_label = 'installed'
+			const display_name = v.type === SKILL_TYPES.KIT ? `${v.name} [kit]` : v.name
+			const enabled_label = v.enabled ? green('enabled') : yellow('disabled')
+			push_row(s_label, green('yes'), display_name, [v.version, v.source, status_label, enabled_label])
+		}
+		for (const d of s.draft_skills) {
+			const type_label = d.type === SKILL_TYPES.KIT ? `${d.name} [kit]` : d.name
+			push_row(s_label, green('yes'), type_label, [d.version || '-', 'draft', 'unpublished', '-'])
+		}
+		for (const x of s.external_skills) {
+			push_row(s_label, yellow('no'), x.name, ['-', 'external', 'installed', '-'])
+		}
+		for (const o of s.orphan_skills) {
+			const agent_label = o.agents.map(a => a.name).join(', ')
+			push_row(s_label, yellow('no'), o.name, ['-', `agent-orphan (${agent_label})`, 'installed', '-'])
+		}
 	}
 
-	print_table(['Skill', 'Version', 'Source', 'Status', 'Enabled'], rows)
+	if (all_scopes) print_table(['Skill', 'Scope', 'Native', 'Version', 'Source', 'Status', 'Enabled'], rows)
+	else print_table(['Skill', 'Version', 'Source', 'Status', 'Enabled'], rows)
 
-	const drift_count = Object.keys(drift_by_skill).length
-	const ahead_count = Object.keys(ahead_by_skill).length
+	// Aggregate the advisory tails across every gathered scope.
+	const drift_count = scopes.reduce((n, s) => n + s.managed_views.filter(v => v.drift).length, 0)
+	const ahead_count = scopes.reduce((n, s) => n + s.managed_views.filter(v => v.ahead && !v.drift).length, 0)
+	const draft_count = scopes.reduce((n, s) => n + s.draft_skills.length, 0)
 	if (drift_count > 0) {
 		console.log()
 		print_warn(`${drift_count} skill(s) drifted: lock and on-disk skill.json disagree.`)
@@ -193,37 +267,46 @@ const run = (args) => catch_errors('List failed', async () => {
 		console.log()
 		print_info(`${ahead_count} skill(s) ahead of lock — bumped locally, not yet published. Run publish when ready.`)
 	}
-	if (draft_skills.length > 0) {
+	if (draft_count > 0) {
 		console.log()
-		print_info(`${draft_skills.length} draft(s) ready to publish — run ${code('happyskills release <name>')} to ship.`)
+		print_info(`${draft_count} draft(s) ready to publish — run ${code('happyskills release <name>')} to ship.`)
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 const schema = {
 	name:     'list',
 	audience: 'consumer',
-	purpose:  'List installed skills, showing version, source, drift/ahead status, and agent-enabled state.',
+	purpose:  'List installed skills, showing version, source, drift/ahead status, and agent-enabled state. With --all-scopes, merges project-local and global skills into one view, each tagged with its scope and whether it is a native HappySkills skill.',
 	mutation: false,
 	interactive_in_text_mode: false,
 	input: {
 		positional: [],
 		flags: [
 			{ name: 'global', alias: 'g', type: 'boolean', default: false, description: 'List globally installed skills' },
+			{ name: 'all-scopes',         type: 'boolean', default: false, description: 'List both project-local and global skills, tagged with scope (local/global) and native (true/false)' },
 			{ name: 'json',               type: 'boolean', default: false, description: 'Output as JSON' },
 		],
 	},
 	output: {
 		data_shape: {
+			// Default / -g (single scope): `skills` is an object keyed by owner/name.
 			skills:       'object<string, { version: string, type: string, source: string, status: string, enabled: boolean, drift?: object, ahead?: object }>',
 			drafts:       'array<{ name: string, description: string, version: string|null, type: string }>',
 			external:     'array<{ name: string, description: string }>',
 			agent_orphans: 'array<{ name: string, description: string, agents: string[] }>',
+			// With --all-scopes: `skills` becomes an ARRAY and every bucket entry
+			// carries `scope: "local"|"global"` and `native: boolean`.
+			// skills:       'array<{ name, scope, native: true,  version, type, source, status, enabled, drift?, ahead? }>'
+			// drafts:       'array<{ name, scope, native: true,  description, version, type }>'
+			// external:     'array<{ name, scope, native: false, description }>'
+			// agent_orphans:'array<{ name, scope, native: false, description, agents }>'
 		},
 	},
 	errors: [],
 	examples: [
 		'happyskills list',
 		'happyskills ls --json',
+		'happyskills ls --all-scopes --json',
 	],
 }