showdar-skills 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+## [0.9.0]
+
+### Added
+
+- Pack authoring CLI: `showdar create-pack <path>` scaffolds a minimal valid extension pack with `--vendor`, `--description`, `--with-workflow`, `--with-profile` flags; no interactive wizard.
+- Pack validation CLI: `showdar validate-pack <path> [--json]` performs dry-run validation without installation; deterministic JSON output.
+- Pack inspection CLI: `showdar inspect-pack <path> [--json]` outputs normalized read-only model (source, identity, skills, workflows, profiles, domains, full-tree hash, drift, compatibility, warnings, errors).
+- Pack diagnostics CLI: `showdar doctor --extensions` read-only diagnostics for installed extensions (source drift, ownership, catalog, overrides, profile refs, catalog build failures, collisions).
+- Pack update CLI: `showdar update-pack <local-path>` safe staged replacement with rollback; validates candidate before replacement; preserves overrides/foreign files; refuses unsafe overwrite; no network access.
+- Checkpoint compatibility assessment layer: `assessCheckpointCompatibility(checkpoint, extensionCatalog)` returns ephemeral `{compatible, replanRequired, reason}`; strict deserialization preserved; invalid checkpoints yield `workflow-incompatible` + `replanRequired` without fabricating BLOCKED WorkflowState; malformed checkpoints distinct from policy incompatibility.
+- Structured extension error model: 12 categories (`schema-invalid`, `namespace-invalid`, `collision`, `protected-field`, `unsafe-path`, `source-unavailable`, `source-unsupported`, `ownership-conflict`, `workflow-incompatible`, `profile-reference-invalid`, `override-invalid`, `drift-detected`) with stable codes and human messages; separate from drift.
+- Custom workflow description minimum lowered from 30 to 10 characters.
+- Source drift vs workflow incompatibility separation: source drift (`source-drift`) is hash-based identity change; workflow incompatibility (`workflow-incompatible`) is current-catalog validation failure; never conflated.
+- `showdar doctor --extensions` reports source drift and workflow compatibility separately (`source.drift`, `workflow.compatibility`); `inspect-pack --json` exposes normalized model; `list --extensions` grouped output with drift status.
+- Override precedence inspection: effective value + source (`built-in`/`pack:<name>`/`project-override`) + `protected` flag via `--json` surfaces.
+- Update-pack safety: staged replacement with rollback; validates candidate before replacement; preserves overrides/foreign files; refuses unsafe overwrite; no network access; fails on ownership conflict/missing managed file; workflow removal validation; manifest updated only after successful replacement.
+- Override precedence inspection via `computePrecedence` in `pack-inspect.js`: per-field effective value, source (`built-in`/`pack:<name>`/`project-override`), protected flag.
+- Custom workflow description minimum lowered from 30 to 10 characters (schema + validator).
+- Domain cap remains 8 with improved validation messages; domains remain discovery-only hints.
+- Error model: 12 structured categories with stable machine-readable codes + human messages; `drift-detected` distinct from `workflow-incompatible`.
+
+### Changed
+
+- `showdar doctor --extensions` now supports `--extensions` flag for extension diagnostics.
+- `showdar list --extensions` output improved: grouped PACKS/WORKFLOWS/PROFILES/OVERRIDES with drift status.
+- Custom workflow description minimum lowered 30 → 10 (schema + validator).
+- `validate-pack` uses existing canonical validation path; `--json` for machine-readable output.
+- `inspect-pack` outputs deterministic normalized model (human + `--json`).
+- Source drift (`source-drift`) and workflow incompatibility (`workflow-incompatible`) are distinct concepts with separate reporting.
+- `update-pack` warns on workflow definition changes: "Existing checkpoints referencing changed custom workflows will be revalidated on resume."
+
+### Security
+
+- `update-pack` refuses unsafe overwrite; validates candidate before replacement; staged replacement with atomic finalization; rollback on failure; overrides and foreign files preserved byte-identical; no network access; no lifecycle scripts/hooks; local directory sources only.
+
+### Fixed
+
+- Custom workflow description minimum lowered from 30 to 10 characters.
+- Extension error categories now structured with stable codes and human messages.
+- Source drift and workflow incompatibility are no longer conflated in reporting.
+
+### Fixed
+
+- Preserve extension-catalog context while validating skipped custom-workflow stages so valid checkpoints can serialize, deserialize, and resume correctly.
+
 ## [0.8.0]
 
 ### Added

package/README.md

@@ -557,7 +557,7 @@ is idempotent, preserves the configured profile, supports `--ai`/`--scope`
 overrides, and refuses to overwrite a foreign same-name skill directory that
 Showdar does not own.
 
-## Extensions (0.8.0)
+## Extensions (0.9.0)
 
 Extension packs are local, static, declarative directories installed from a
 local directory or workspace-relative path. A pack carries `pack.json`
@@ -565,16 +565,41 @@ metadata (name, version, skills, workflows, pack-local profiles), skill
 directories, custom workflow definitions, and docs. Packs contain no
 executable hooks, lifecycle scripts, or remote code.
 
+**Pack authoring & validation**
+
+```bash
+showdar create-pack <path> [--vendor <v>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]
+showdar validate-pack <local-path> [--json]
+showdar inspect-pack <local-path> [--json]
+```
+
+**Install & lifecycle**
+
 ```bash
-showdar add-pack ../acme-pack
+showdar add-pack <local-path>
 showdar list --extensions
-showdar remove-pack acme
+showdar remove-pack <name>
+showdar update-pack <local-path>
+```
+
+**Diagnostics**
+
+```bash
+showdar doctor --extensions
+```
+
+**Pack metadata**
+
+```bash
+showdar add-workflow <local-path>
+showdar init --pack <local-path>
 ```
 
 Pack skill IDs use the `vendor/skill` namespace (for example,
 `acme/lint`); the `showdar-` prefix is reserved for built-ins. Skill
 `domains` are lowercase kebab-case discovery hints only (at most 8 per
 skill) — they never create capabilities, routes, or authority.
+Custom workflow description minimum is 10 characters.
 
 Custom workflows compose built-in primitive stages under a `vendor-name`
 ID (for example, `acme-release`). Stages, skip rules, and completion
@@ -599,12 +624,23 @@ Showdar computes a full-tree SHA-256 over the validated pack source at
 install and records it in `.showdar.json` (`extensions.packs[].hash`).
 The hash is source-tree identity — a docs-only edit changes it without
 implying any behavior change. Drift means the source tree differs from
-the recorded installation source.
+the recorded installation source. Source drift (`source-drift`) and
+workflow incompatibility (`workflow-incompatible`) are separate concerns.
+
+**Checkpoint compatibility**: Custom workflow checkpoints are revalidated
+against the current explicit extension catalog at resume. A valid checkpoint
+resumes normally. A checkpoint with a skip or stage no longer permitted by
+the current workflow definition yields a `workflow-incompatible` outcome
+with `replanRequired=true` — it is never fabricated into a `BLOCKED`
+WorkflowState. Malformed checkpoints remain distinct from workflow
+incompatibility. No pack hash, workflow fingerprint, or catalog snapshot is
+persisted in checkpoints; `schemaVersion` remains 1.
 
 Extensions cannot create capabilities, grant authority, modify Phase 6G,
 change built-in workflow semantics or profiles, or execute arbitrary
 code. Supported sources are local directories and workspace-relative
-paths; tarball, URL, Git, and npm/registry sources are rejected in 0.8.
+paths; tarball, URL, Git, and npm/registry sources are rejected.
+Executable plugins/hooks are not supported.
 
 Opt-in custom workflow evaluation (never part of the release gate):
 
@@ -615,6 +651,22 @@ node scripts/custom-workflows-eval.mjs \
   --pack .tmp/custom-eval-fixture/acme-pack/pack.json
 ```
 
+## Diagnostics (0.9.0)
+
+```bash
+showdar doctor --extensions
+```
+
+Read-only diagnostics for installed extension state:
+- manifest entries valid, installed files exist, ownership intact
+- source drift (`source-drift`, `source-unavailable`, `installed-file-drift`, `ownership-conflict`)
+- invalid overrides, duplicate/collision, broken profile references
+- catalog construction failures
+- source drift vs workflow incompatibility reported separately
+
+Byte-for-byte override preservation is enforced; `.showdar/overrides.json` is
+never rewritten by Showdar during any lifecycle operation.
+
 ## Routing
 
 Showdar routes each request through progressive disclosure: the host discovers
@@ -656,6 +708,13 @@ showdar list
 showdar list --extensions
 showdar status [--scope <project|global>]
 showdar doctor [--scope <project|global>]
+showdar doctor --extensions
+showdar validate
+showdar remove [--scope <project|global>]
+showdar create-pack <path> [--vendor <v>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]
+showdar validate-pack <local-path> [--json]
+showdar inspect-pack <local-path> [--json]
+showdar update-pack <local-path>
 showdar validate
 showdar remove [--scope <project|global>]
 ```

package/bin/showdar.js

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { AI_TARGETS, PRIMITIVE_COUNT, PROFILE_ALIASES, PROFILES, SKILLS, TOTAL_COUNT, WORKFLOW_COUNT, canonicalProfile, isDeprecatedProfile, resolveProfile } from '../src/catalog.js';
-import { addPack, addSkill, addWorkflow, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, listExtensions, removeGlobal, removePack, removeProject } from '../src/project.js';
+import { addPack, addSkill, addWorkflow, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, listExtensions, removeGlobal, removePack, removeProject, validatePackSource, createPack, inspectPack, doctor, updatePack, readProjectOverrides } from '../src/project.js';
 import { validateRepository } from '../src/validate.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -43,7 +43,7 @@ function printHelp(version, command = null) {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n\nExamples:\n  showdar add debug\n  showdar add showdar-security\n  showdar add test --ai cursor\n  showdar add review --scope global --ai claude\n\nDefault scope: project. Default AI target: universal, or the configured .showdar.json value when present.`);
     return;
   }
-  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
+  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n  showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]\n  showdar validate-pack <local-path> [--json]\n  showdar inspect-pack <local-path> [--json]\n  showdar doctor ${scopeUsage}\n  showdar update-pack <local-path>\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
 }
 
 async function main() {
@@ -180,7 +180,77 @@ async function main() {
     return;
   }
 
-  throw new Error(`Unknown command "${command}". Run "showdar --help".`);
+  if (command === 'create-pack') {
+    const packPath = args[1];
+    if (!packPath) throw new Error('Pack path is required. Usage: showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]');
+    const vendor = valueAfter(args, '--vendor', 'custom');
+    const description = valueAfter(args, '--description', null);
+    const withWorkflow = valueAfter(args, '--with-workflow', null);
+    const withProfile = valueAfter(args, '--with-profile', null);
+    const result = await createPack({ cwd: projectRoot, path: packPath, vendor, description, withWorkflow, withProfile });
+    console.log(`Showdar pack scaffolded.\nPack: ${result.manifest.name}\nVersion: ${result.manifest.version}\nSkill: ${result.skillId}${result.workflowId ? `\nWorkflow: ${result.workflowId}` : ''}${result.profileName ? `\nProfile: ${result.profileName}` : ''}\nPath: ${result.packDir}`);
+    return;
+  }
+
+  if (command === 'validate-pack') {
+    const packPath = args[1];
+    if (!packPath) throw new Error('Pack path is required. Usage: showdar validate-pack <local-path> [--json]');
+    const isJson = args.includes('--json');
+    const result = await validatePackSource({ cwd: projectRoot, source: packPath });
+    if (isJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      if (result.ok) {
+        console.log(`Pack validation OK`);
+      } else {
+        console.log(`Pack validation FAILED (${result.errors.length} errors).`);
+        for (const error of result.errors) console.log(`- ${error}`);
+        process.exitCode = 1;
+      }
+    }
+    return;
+  }
+
+  if (command === 'inspect-pack') {
+    const packPath = args[1];
+    if (!packPath) throw new Error('Pack path is required. Usage: showdar inspect-pack <local-path> [--json]');
+    const isJson = args.includes('--json');
+    const result = await inspectPack({ cwd: projectRoot, source: packPath });
+    if (isJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      if (result.ok) {
+        console.log(`Pack: ${result.name}@${result.version}`);
+        console.log(`Description: ${result.description}`);
+        console.log(`Source: ${result.source}`);
+        console.log(`Full-tree hash: ${result.fullTreeHash}`);
+        console.log(`Skills: ${result.skills.length}`);
+        console.log(`Workflows: ${result.workflows.length}`);
+        console.log(`Profiles: ${Object.keys(result.profiles).length}`);
+        if (result.errors.length > 0) {
+          console.log(`Errors: ${result.errors.length}`);
+          for (const error of result.errors) console.log(`  - ${error}`);
+        }
+        if (result.warnings.length > 0) {
+          console.log(`Warnings: ${result.warnings.length}`);
+          for (const warning of result.warnings) console.log(`  - ${warning}`);
+        }
+      } else {
+        console.log(`Inspection FAILED (${result.errors.length} errors).`);
+        for (const error of result.errors) console.log(`- ${error}`);
+        process.exitCode = 1;
+      }
+    }
+    return;
+  }
+
+  if (command === 'update-pack') {
+    const packSource = args[1];
+    if (!packSource) throw new Error('Pack source is required. Usage: showdar update-pack <local-path>');
+    const result = await updatePack({ cwd: projectRoot, source: packSource });
+    console.log(`Showdar pack ${result.status}.\nPack: ${result.pack}\nVersion: ${result.version}${result.oldHash ? `\nOld hash: ${result.oldHash}\nNew hash: ${result.newHash}` : ''}\nFiles: ${result.files}`);
+    return;
+  }
 }
 
 main().catch((error) => {

package/config/custom-workflow.schema.json

@@ -7,7 +7,7 @@
   "additionalProperties": false,
   "properties": {
     "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*-[a-z][a-z0-9-]*$" },
-    "description": { "type": "string", "minLength": 30 },
+    "description": { "type": "string", "minLength": 10 },
     "stages": {
       "type": "array",
       "minItems": 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },

package/src/extension-errors.js

@@ -0,0 +1,90 @@
+const EXTENSION_ERROR_CATEGORIES = {
+  SCHEMA_INVALID: 'schema-invalid',
+  NAMESPACE_INVALID: 'namespace-invalid',
+  COLLISION: 'collision',
+  PROTECTED_FIELD: 'protected-field',
+  UNSAFE_PATH: 'unsafe-path',
+  SOURCE_UNAVAILABLE: 'source-unavailable',
+  SOURCE_UNSUPPORTED: 'source-unsupported',
+  OWNERSHIP_CONFLICT: 'ownership-conflict',
+  WORKFLOW_INCOMPATIBLE: 'workflow-incompatible',
+  PROFILE_REFERENCE_INVALID: 'profile-reference-invalid',
+  OVERRIDE_INVALID: 'override-invalid',
+  DRIFT_DETECTED: 'drift-detected',
+};
+
+const ERROR_MESSAGES = {
+  [EXTENSION_ERROR_CATEGORIES.SCHEMA_INVALID]: 'Schema validation failed',
+  [EXTENSION_ERROR_CATEGORIES.NAMESPACE_INVALID]: 'Invalid namespace/identifier',
+  [EXTENSION_ERROR_CATEGORIES.COLLISION]: 'Identifier collision detected',
+  [EXTENSION_ERROR_CATEGORIES.PROTECTED_FIELD]: 'Protected field modification not allowed',
+  [EXTENSION_ERROR_CATEGORIES.UNSAFE_PATH]: 'Unsafe path detected',
+  [EXTENSION_ERROR_CATEGORIES.SOURCE_UNAVAILABLE]: 'Source path unavailable',
+  [EXTENSION_ERROR_CATEGORIES.SOURCE_UNSUPPORTED]: 'Source type not supported',
+  [EXTENSION_ERROR_CATEGORIES.OWNERSHIP_CONFLICT]: 'Ownership conflict with existing managed files',
+  [EXTENSION_ERROR_CATEGORIES.WORKFLOW_INCOMPATIBLE]: 'Workflow definition incompatible with checkpoint',
+  [EXTENSION_ERROR_CATEGORIES.PROFILE_REFERENCE_INVALID]: 'Invalid profile reference',
+  [EXTENSION_ERROR_CATEGORIES.OVERRIDE_INVALID]: 'Invalid project override',
+  [EXTENSION_ERROR_CATEGORIES.DRIFT_DETECTED]: 'Source drift detected',
+};
+
+export class ExtensionError extends Error {
+  constructor(category, message, details = {}) {
+    super(message);
+    this.name = 'ExtensionError';
+    this.category = category;
+    this.code = category.toUpperCase().replace(/-/g, '_');
+    this.details = details;
+  }
+}
+
+export function createExtensionError(category, details = {}) {
+  const message = details.message ?? ERROR_MESSAGES[category] ?? 'Extension error';
+  return new ExtensionError(category, message, details);
+}
+
+export function isExtensionError(error) {
+  return error instanceof ExtensionError;
+}
+
+export function formatErrorForCli(error, verbose = false) {
+  if (isExtensionError(error)) {
+    const lines = [`[${error.category}] ${error.message}`];
+    if (verbose && Object.keys(error.details).length > 0) {
+      lines.push('Details:', JSON.stringify(error.details, null, 2));
+    }
+    return lines.join('\n');
+  }
+  return error.message;
+}
+
+export function formatErrorForJson(error) {
+  if (isExtensionError(error)) {
+    return {
+      category: error.category,
+      code: error.code,
+      message: error.message,
+      details: error.details,
+    };
+  }
+  return {
+    category: 'unknown',
+    code: 'UNKNOWN',
+    message: error.message,
+    details: {},
+  };
+}
+
+export { EXTENSION_ERROR_CATEGORIES, ERROR_MESSAGES };
+
+export const extensionErrorsAPI = {
+  ExtensionError,
+  createExtensionError,
+  isExtensionError,
+  formatErrorForCli,
+  formatErrorForJson,
+  categories: EXTENSION_ERROR_CATEGORIES,
+  messages: ERROR_MESSAGES,
+};
+
+export default extensionErrorsAPI;

package/src/pack-inspect.js

@@ -0,0 +1,298 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { readFile, readdir, lstat, access } from 'node:fs/promises';
+import { 
+  validatePackManifest, 
+  validateCustomWorkflowDoc, 
+  validatePack, 
+  containsForbiddenAuthorityKey,
+  validateCustomWorkflowId,
+  validateProjectOverridesDoc,
+} from './validate-pack.js';
+import { EXTENSION_DIR, OVERRIDES_FILE, readManifest, readProjectOverrides, hashTree } from './project.js';
+import { EXTENSION_ERROR_CATEGORIES, createExtensionError } from './extension-errors.js';
+
+const DRIFT_CATEGORIES = {
+  NO_DRIFT: 'no-drift',
+  SOURCE_DRIFT: 'source-drift',
+  SOURCE_UNAVAILABLE: 'source-unavailable',
+  INSTALLED_FILE_DRIFT: 'installed-file-drift',
+  OWNERSHIP_CONFLICT: 'ownership-conflict',
+};
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+async function readPackManifest(packRoot) {
+  try {
+    return JSON.parse(await readFile(path.join(packRoot, 'pack.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function readWorkflowDoc(packRoot, workflowPath) {
+  try {
+    return JSON.parse(await readFile(path.join(packRoot, workflowPath), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function computePackHash(packRoot, manifest) {
+  const h = createHash('sha256');
+  async function walk(current, relative = '') {
+    const info = await lstat(current);
+    if (info.isDirectory()) {
+      const entries = await readdir(current, { withFileTypes: true });
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      for (const entry of entries) await walk(path.join(current, entry.name), path.join(relative, entry.name));
+      return;
+    }
+    h.update(relative.replaceAll(path.sep, '/'));
+    h.update('\0');
+    h.update(await readFile(current));
+    h.update('\0');
+  }
+  await walk(packRoot);
+  return h.digest('hex');
+}
+
+async function inspectPackSource(packRoot) {
+  const errors = [];
+  const warnings = [];
+  
+  const manifest = await readPackManifest(packRoot);
+  if (!manifest) {
+    return { ok: false, errors: ['pack.json not found or unreadable'] };
+  }
+  
+  const manifestValidation = validatePackManifest(manifest);
+  if (!manifestValidation.ok) errors.push(...manifestValidation.errors);
+  
+  const skills = [];
+  for (const skill of manifest.skills ?? []) {
+    const skillDir = path.join(packRoot, skill.path);
+    try {
+      await access(skillDir);
+      const skillFile = path.join(skillDir, 'SKILL.md');
+      let skillContent = '';
+      try {
+        skillContent = await readFile(skillFile, 'utf8');
+      } catch {}
+      skills.push({ id: skill.id, path: skill.path, description: skill.description, domains: skill.domains ?? [], hasSkillFile: true });
+    } catch {
+      skills.push({ id: skill.id, path: skill.path, description: skill.description, domains: skill.domains ?? [], hasSkillFile: false });
+    }
+  }
+  
+  const workflows = [];
+  for (const workflow of manifest.workflows ?? []) {
+    const doc = await readWorkflowDoc(packRoot, workflow.path);
+    if (doc) {
+      const validation = validateCustomWorkflowDoc(doc, `workflow ${workflow.id}`);
+      if (validation.length > 0) {
+        workflows.push({ id: workflow.id, path: workflow.path, valid: false, errors: validation });
+      } else {
+        workflows.push({ 
+          id: workflow.id, 
+          path: workflow.path, 
+          valid: true, 
+          description: doc.description,
+          stages: doc.stages,
+          requiredStages: doc.requiredStages ?? [],
+          allowedSkips: doc.allowedSkips ?? [],
+          completionPolicy: doc.completionPolicy,
+        });
+      }
+    } else {
+      workflows.push({ id: workflow.id, path: workflow.path, valid: false, errors: ['workflow file not found or unreadable'] });
+    }
+  }
+  
+  const profiles = {};
+  for (const [name, members] of Object.entries(manifest.profiles ?? {})) {
+    const validMembers = [];
+    const invalidMembers = [];
+    for (const member of members) {
+      profiles[name] = { members, valid: true };
+    }
+  }
+  
+  const computedHash = await computePackHash(packRoot, manifest);
+  
+  return {
+    ok: errors.length === 0,
+    source: 'local-directory',
+    name: manifest.name,
+    version: manifest.version,
+    description: manifest.description,
+    skills,
+    workflows,
+    profiles,
+    domains: Array.from(new Set(manifest.skills?.flatMap(s => s.domains ?? []) ?? [])),
+    fullTreeHash: computedHash,
+    warnings,
+    errors,
+    manifest,
+  };
+}
+
+async function inspectPackInstalled(cwd, packName, manifest) {
+  const packDir = path.join(cwd, '.showdar', 'extensions', 'packs', packName);
+  
+  try {
+    await access(path.join(cwd, '.showdar', 'extensions', 'packs', packName));
+  } catch {
+    return { installed: false, drift: 'source-unavailable', details: 'Pack directory missing' };
+  }
+  
+  const sourceValidation = await validatePack(path.join(cwd, '.showdar', 'extensions', 'packs', packName)).catch(() => ({ ok: false, errors: ['validation failed'] }));
+  const sourceHash = await hashTree(path.join(cwd, '.showdar', 'extensions', 'packs', packName)).catch(() => null);
+  
+  const recordedHash = manifest.hash;
+  let drift = 'no-drift';
+  let details = '';
+  
+  if (sourceHash === null) {
+    drift = 'source-unavailable';
+    details = 'Cannot compute source hash';
+  } else if (sourceHash !== recordedHash) {
+    drift = 'source-drift';
+    details = 'Full-tree hash differs from recorded manifest hash';
+  }
+  
+  return {
+    installed: true,
+    recordedHash,
+    computedHash: sourceHash,
+    drift,
+    driftDetails: details,
+    validation: sourceValidation,
+  };
+}
+
+async function inspectCustomWorkflows(cwd, manifest) {
+  const workflows = manifest.extensions?.customWorkflows ?? [];
+  const results = [];
+  
+  for (const wf of workflows) {
+    try {
+      const docPath = path.join(cwd, wf.path);
+      const doc = JSON.parse(await readFile(docPath, 'utf8'));
+      const { validateCustomWorkflowDoc, validateCustomWorkflowId } = await import('./validate-pack.js');
+      const validation = validateCustomWorkflowDoc(doc, `workflow ${doc.id}`);
+      results.push({ id: wf.id, path: wf.path, source: wf.source, valid: validation.ok, errors: validation.errors });
+    } catch (error) {
+      results.push({ id: wf.id, path: wf.path, source: wf.source, valid: false, errors: [error.message] });
+    }
+  }
+  return results;
+}
+
+async function inspectOverrides(cwd) {
+  const overridesPath = path.join(cwd, '.showdar', 'overrides.json');
+  try {
+    await access(overridesPath);
+    const { validateProjectOverridesDoc } = await import('./validate-pack.js');
+    const doc = JSON.parse(await readFile(overridesPath, 'utf8'));
+    const result = validateProjectOverridesDoc(doc);
+    return { present: true, valid: result.ok, errors: result.errors };
+  } catch {
+    return { present: false, valid: true, errors: [] };
+  }
+}
+
+function computePrecedence(installedManifest, projectOverrides) {
+  const fields = {};
+  
+  const builtinSkills = new Set(['showdar-understand', 'showdar-plan', 'showdar-design', 'showdar-build', 'showdar-debug', 'showdar-test', 'showdar-review', 'showdar-upgrade', 'showdar-ship', 'showdar-recover', 'showdar-git', 'showdar-requirements', 'showdar-quality', 'showdar-security', 'showdar-ops']);
+  
+  for (const skill of ['showdar-understand', 'showdar-plan', 'showdar-design', 'showdar-build', 'showdar-debug', 'showdar-test', 'showdar-review', 'showdar-upgrade', 'showdar-ship', 'showdar-recover', 'showdar-git', 'showdar-requirements', 'showdar-quality', 'showdar-security', 'showdar-ops']) {
+    fields[skill] = { field: skill, effective: skill, source: 'built-in', protected: true };
+  }
+  
+  for (const pack of installedManifest.extensions?.packs ?? []) {
+    const packName = pack.name;
+    const packSkills = pack.skills ?? [];
+    for (const skill of packSkills) {
+      const existing = fields[skill.id];
+      if (!existing || !existing.protected) {
+        fields[skill.id] = { field: skill.id, effective: skill.description, source: `pack:${packName}`, protected: false };
+      }
+    }
+  }
+  
+  if (projectOverrides?.skillDescriptions) {
+    for (const [id, desc] of Object.entries(projectOverrides.skillDescriptions)) {
+      const existing = fields[id];
+      if (existing && !existing.protected) {
+        fields[id] = { field: id, effective: desc, source: 'project-override', protected: false };
+      }
+    }
+  }
+  
+  return Object.values(fields);
+}
+
+async function assessWorkflowCompatibility(checkpoint, extensionCatalog) {
+  const { deserializeWorkflowState, validateWorkflowState } = await import('./workflow-state.js');
+  
+  let state;
+  try {
+    state = deserializeWorkflowState(checkpoint, { extensionCatalog });
+  } catch (error) {
+    return { compatible: false, replanRequired: true, reason: `malformed checkpoint: ${error.message}`, workflowIncompatible: false };
+  }
+  
+  const validation = validateWorkflowState(state, { extensionCatalog });
+  if (!validation.ok) {
+    return { compatible: false, replanRequired: true, reason: `workflow-incompatible: ${validation.errors.join('; ')}`, workflowIncompatible: true };
+  }
+  
+  return { compatible: true, replanRequired: false, reason: null };
+}
+
+async function listExtensionsWithDetails(cwd) {
+  const manifest = await readManifest(path.join(cwd, '.showdar.json'), cwd);
+  if (!manifest) return null;
+  
+  const overrides = await import('./project.js').then(m => m.readProjectOverrides({ cwd })).catch(() => null);
+  const overridesStatus = overrides ? 'valid' : 'absent';
+  
+  const packs = [];
+  for (const pack of manifest.extensions?.packs ?? []) {
+    const installed = await inspectPackInstalled(cwd, pack.name, pack);
+    packs.push({ name: pack.name, version: pack.version, hash: pack.hash, drift: installed.drift, driftDetails: installed.driftDetails });
+  }
+  
+  const customWorkflows = [];
+  for (const wf of manifest.extensions?.customWorkflows ?? []) {
+    customWorkflows.push({ id: wf.id, source: wf.source, path: wf.path });
+  }
+  
+  return { packs, customWorkflows, overrides: { present: true, status: overridesStatus } };
+}
+
+export { 
+  inspectPackSource, 
+  inspectPackInstalled, 
+  inspectCustomWorkflows, 
+  inspectOverrides,
+  computePrecedence,
+  assessWorkflowCompatibility,
+  listExtensionsWithDetails,
+  DRIFT_CATEGORIES,
+};
+
+export const packInspectAPI = {
+  inspectPackSource,
+  inspectPackInstalled,
+  inspectCustomWorkflows,
+  computePrecedence,
+  assessWorkflowCompatibility,
+  listExtensionsWithDetails,
+};
+
+export default { inspectPackSource, inspectPackInstalled };

package/src/pack-scaffold.js

@@ -0,0 +1,331 @@
+import path from 'node:path';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { EXTENSION_ERROR_CATEGORIES, createExtensionError } from './extension-errors.js';
+
+const SKILL_TEMPLATE = `---
+name: {{skillName}}
+description: {{skillDescription}}
+---
+
+# {{skillTitle}}
+
+## Purpose
+
+Describe when to use this skill.
+
+## When to use
+
+- List specific scenarios where this skill applies
+- Provide concrete examples of applicable situations
+- Explain the context in which this skill is most valuable
+- Document the types of problems this skill solves
+
+## When not to use
+
+- List scenarios where this skill should not be used
+- Explain limitations and boundaries
+- Note any conflicting approaches
+- Document known incompatibilities
+
+## Inputs and assumptions
+
+- List required inputs and assumptions
+- Document any prerequisites
+- Specify expected data formats
+- Note any environmental dependencies
+
+## Non-negotiable rules
+
+- List non-negotiable constraints
+- Document mandatory practices
+- Specify compliance requirements
+- Note any regulatory requirements
+
+## Workflow
+
+### Phase 1 - Discovery
+- Step 1: Gather requirements
+- Step 2: Analyze context
+- Step 3: Identify stakeholders
+
+### Phase 2 - Analysis
+- Step 1: Evaluate options
+- Step 2: Assess trade-offs
+- Step 3: Document findings
+
+### Phase 3 - Output
+- Step 1: Produce deliverable
+- Step 2: Validate results
+- Step 3: Document outcomes
+
+## Decision points
+
+- List decision points and criteria
+- Document evaluation criteria
+- Specify escalation paths
+- Note decision deadlines
+
+## Stack detection
+
+- How to detect if this skill applies
+- Technology stack indicators
+- File pattern matching
+- Configuration indicators
+
+## Failure modes
+
+- Known failure scenarios
+- Common error patterns
+- Recovery procedures
+- Mitigation strategies
+
+## Stop conditions
+
+- When to stop using this skill
+- Completion criteria
+- Termination signals
+- Rollback triggers
+
+## Escalation conditions
+
+- When to escalate
+- Escalation contacts
+- Severity thresholds
+- Communication protocols
+
+## Verification
+
+- How to verify correct usage
+- Validation checkpoints
+- Quality gates
+- Acceptance criteria
+
+## Output contract
+
+- What this skill produces
+- Expected deliverables
+- Format specifications
+- Quality standards
+
+## Anti-patterns
+
+- Common mistakes to avoid
+- Anti-pattern examples
+- Corrective actions
+- Prevention techniques
+
+## Example
+
+\`\`\`markdown
+### Summary
+Example usage summary
+\`\`\`
+`;
+
+function normalizeVendor(vendor) {
+  return vendor.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+function normalizeSkillName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+}
+
+function normalizeWorkflowName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+}
+
+function generateSkillId(vendor, skillName) {
+  const v = normalizeVendor(vendor);
+  const s = normalizeSkillName(skillName);
+  return `${v}/${s}`;
+}
+
+function generateWorkflowId(vendor, workflowName) {
+  const v = normalizeVendor(vendor);
+  const w = normalizeWorkflowName(workflowName);
+  return `${v}-${w}`;
+}
+
+function toTitleCase(str) {
+  return str.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}
+
+function createPackManifest({ name, version, description, vendor, skillName, withWorkflow, withProfile }) {
+  const skillId = generateSkillId(vendor, skillName);
+  const skills = [{
+    id: skillId,
+    path: `skills/${skillId}`,
+    description: `Custom skill for ${skillName}`,
+    domains: ['custom', 'utility'],
+  }];
+  
+  const workflows = [];
+  if (withWorkflow) {
+    const workflowId = generateWorkflowId(vendor, withWorkflow);
+    workflows.push({ id: workflowId, path: `workflows/${workflowId}.json` });
+  }
+  
+  const profiles = {};
+  if (withProfile) {
+    const memberIds = [generateSkillId(vendor, skillName)];
+    if (withWorkflow) memberIds.push(generateWorkflowId(vendor, withWorkflow));
+    profiles[withProfile] = memberIds;
+  }
+  
+  return {
+    name,
+    version,
+    description: description ?? `Custom pack: ${name}`,
+    skills,
+    workflows,
+    profiles,
+  };
+}
+
+function createWorkflowDoc({ vendor, workflowName, stages, description }) {
+  const workflowId = generateWorkflowId(vendor, workflowName);
+  const allowedSkips = stages
+    .filter(s => s !== 'showdar-understand')
+    .map(stage => ({
+      stage,
+      reason: 'no-ux-decision',
+      policy: 'no-ux-decision',
+      evidence: [],
+    }));
+  
+  return {
+    id: workflowId,
+    description: description ?? `Custom workflow ${workflowId} for ${stages.join(', ')}`,
+    stages,
+    allowedSkips,
+    requiredStages: ['showdar-understand', 'showdar-build', 'showdar-test'],
+    completionPolicy: {
+      allSelectedStagesAccounted: true,
+      noBlockers: true,
+      requiredVerificationSatisfied: true,
+      noNegativeEvidence: true,
+    },
+    workflowStateCompat: {
+      schemaVersion: 1,
+      selectableStages: stages,
+      skipRules: Object.fromEntries(allowedSkips.map(s => [s.stage, {
+        reason: s.reason,
+        policy: s.policy,
+        evidence: s.evidence,
+      }])),
+    },
+  };
+}
+
+function createSkillFile({ vendor, skillName }) {
+  const title = toTitleCase(skillName);
+  return SKILL_TEMPLATE
+    .replace(/\{\{skillName\}\}/g, skillName)
+    .replace(/\{\{skillTitle\}\}/g, title)
+    .replace(/\{\{skillDescription\}\}/g, `Custom ${title} skill providing reusable functionality for ${skillName} tasks across projects.`);
+}
+
+function createSkillDir(skillId) {
+  const parts = skillId.split('/');
+  return `skills/${parts.join('/')}`;
+}
+
+async function createPackScaffold({
+  destination,
+  name,
+  version = '0.1.0',
+  vendor = 'custom',
+  description,
+  skillName = 'notes',
+  withWorkflow,
+  withProfile,
+} = {}) {
+  if (!name || !name.trim()) {
+    throw createExtensionError('NAMESPACE_INVALID', { field: 'name', message: 'Pack name is required' });
+  }
+  
+  const normalizedName = name.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/^-|-$/g, '');
+  if (!/^[a-z][a-z0-9-]*$/.test(normalizedName)) {
+    throw createExtensionError('NAMESPACE_INVALID', { field: 'name', message: 'Pack name must match ^[a-z][a-z0-9-]*$' });
+  }
+  
+  const vendorNorm = normalizeVendor(vendor);
+  if (vendorNorm === 'showdar') {
+    throw createExtensionError('PROTECTED_FIELD', { field: 'vendor', message: 'Vendor cannot be "showdar" (reserved prefix)' });
+  }
+  
+  const packDir = path.resolve(destination, normalizedName);
+  const manifest = createPackManifest({ 
+    name: normalizedName, 
+    version, 
+    description, 
+    vendor: vendorNorm, 
+    skillName,
+    withWorkflow,
+    withProfile 
+  });
+  
+  // Check if destination already exists
+  const fs = await import('node:fs/promises');
+  try {
+    const stat = await fs.stat(packDir);
+    if (stat.isDirectory()) {
+      throw createExtensionError('COLLISION', { path: packDir, message: 'Destination directory already exists' });
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  
+  // Create directory structure
+  await mkdir(path.join(packDir, 'skills', manifest.skills[0].id), { recursive: true });
+  if (manifest.workflows.length > 0) {
+    await mkdir(path.join(packDir, 'workflows'), { recursive: true });
+  }
+  
+  // Write pack.json
+  await import('node:fs/promises').then(fs => 
+    fs.writeFile(path.join(packDir, 'pack.json'), JSON.stringify(manifest, null, 2), 'utf8')
+  );
+  
+  // Write skill SKILL.md
+  const skillContent = createSkillFile({ vendor: vendorNorm, skillName });
+  
+  await import('node:fs/promises').then(fs => 
+    fs.writeFile(path.join(packDir, 'skills', manifest.skills[0].id, 'SKILL.md'), skillContent, 'utf8')
+  );
+  
+  // Write workflow if requested
+  if (withWorkflow) {
+    const workflowId = generateWorkflowId(vendor, withWorkflow);
+    const stages = ['showdar-understand', 'showdar-debug', 'showdar-build', 'showdar-test', 'showdar-review'];
+    const workflowDoc = createWorkflowDoc({
+      vendor: vendorNorm,
+      workflowName: withWorkflow,
+      stages,
+      description: `Custom workflow ${withWorkflow} for ${manifest.name}`,
+    });
+    await import('node:fs/promises').then(fs => 
+      fs.writeFile(path.join(packDir, 'workflows', `${workflowId}.json`), JSON.stringify(workflowDoc, null, 2), 'utf8')
+    );
+  }
+  
+  return {
+    packDir,
+    manifest,
+    skillId: manifest.skills[0].id,
+    workflowId: withWorkflow ? generateWorkflowId(vendorNorm, withWorkflow) : null,
+    profileName: withProfile,
+  };
+}
+
+export { createPackScaffold, generateSkillId, generateWorkflowId, createPackManifest, createWorkflowDoc };
+
+export const packScaffoldAPI = {
+  createPackScaffold,
+  generateSkillId,
+  generateWorkflowId,
+  createPackManifest,
+  createWorkflowDoc,
+};
+
+export default { createPackScaffold };

package/src/pack-update.js

@@ -0,0 +1,208 @@
+import path from 'node:path';
+import { access, cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { 
+  hashTree, 
+  readManifest, 
+  writeJsonAtomic, 
+  ownedPathSet, 
+  manifestPathFor, 
+  EXTENSION_DIR,
+  lstatWithoutSymlink,
+  assertSafeManagedPath,
+} from './project.js';
+import { validatePack } from './validate-pack.js';
+import { validatePackManifest } from './validate-pack.js';
+import { createExtensionError, EXTENSION_ERROR_CATEGORIES } from './extension-errors.js';
+
+const EXTENSION_PACKS_DIR = path.join(EXTENSION_DIR, 'packs');
+
+async function readPackManifest(packRoot) {
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(path.join(packRoot, 'pack.json'), 'utf8'));
+  } catch (error) {
+    throw new Error(`Invalid pack manifest: ${error.message}`);
+  }
+  return manifest;
+}
+
+async function buildPackFileList(packRoot, manifest) {
+  const files = [{ source: path.join(packRoot, 'pack.json'), relative: 'pack.json' }];
+  for (const skill of manifest.skills ?? []) {
+    const skillDir = path.join(packRoot, skill.path);
+    const entries = await readdir(skillDir, { recursive: true, withFileTypes: true }).catch(() => {
+      throw new Error(`Pack skill path unreadable: ${skill.id} -> ${skill.path}`);
+    });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      const full = path.join(entry.parentPath ?? skillDir, entry.name);
+      files.push({ source: full, relative: path.relative(packRoot, full).replaceAll(path.sep, '/') });
+    }
+  }
+  for (const workflow of manifest.workflows ?? []) {
+    files.push({ source: path.join(packRoot, workflow.path), relative: workflow.path.replaceAll(path.sep, '/') });
+  }
+  const seen = new Set();
+  for (const file of files) {
+    if (seen.has(file.relative)) throw new Error(`Pack contains duplicate logical path: ${file.relative}`);
+    seen.add(file.relative);
+  }
+  return [...seen].sort().map((relative) => files.find((f) => f.relative === relative));
+}
+
+async function copyOwned({ baseRoot, source, destination, priorOwned, newFiles, managedRoots = [] }) {
+  const relative = manifestPathFor(baseRoot, destination);
+  if ((await access(destination).then(() => true).catch(() => false)) && !priorOwned.has(relative)) {
+    throw new Error(`Refusing to overwrite existing non-Showdar-managed file: ${destination}`);
+  }
+  await rm(destination, { recursive: true, force: true });
+  await mkdir(path.dirname(destination), { recursive: true });
+  await cp(source, destination, { recursive: true });
+  newFiles.push({ path: relative, hash: await hashTree(destination), extension: true });
+}
+
+function compareWorkflowDefinitions(oldManifest, newManifest) {
+  const changes = [];
+  
+  const oldWorkflows = new Map((oldManifest.workflows ?? []).map(w => [w.id, w]));
+  const newWorkflows = new Map((newManifest.workflows ?? []).map(w => [w.id, w]));
+  
+  for (const [id, oldWf] of oldWorkflows) {
+    if (!newWorkflows.has(id)) {
+      changes.push({ type: 'removed', workflowId: id });
+      continue;
+    }
+    const newWf = newWorkflows.get(id);
+    if (JSON.stringify(oldWf) !== JSON.stringify(newWf)) {
+      changes.push({ type: 'modified', workflowId: id });
+    }
+  }
+  
+  for (const [id, newWf] of newWorkflows) {
+    if (!oldWorkflows.has(id)) {
+      changes.push({ type: 'added', workflowId: id });
+    }
+  }
+  
+  return changes;
+}
+
+async function updatePack({ cwd, source, home = process.cwd() }) {
+  const packRoot = await resolvePackSource({ cwd, source });
+  const newManifest = await readPackManifest(packRoot);
+  const validation = await validatePack(packRoot);
+  if (!validation.ok) throw new Error(`Invalid pack: ${validation.errors.join('; ')}`);
+  
+  const manifestPath = path.join(cwd, '.showdar.json');
+  const existing = await readManifest(manifestPath, cwd);
+  if (!existing) throw new Error('Showdar is not installed in project scope. Run "showdar init" first.');
+  
+  const existingPack = existing.extensions?.packs?.find(p => p.name === newManifest.name);
+  if (!existingPack) throw new Error(`Pack not installed: ${newManifest.name}. Use add-pack instead.`);
+  
+  const newPackHash = await hashTree(packRoot);
+  
+  if (newPackHash === existingPack.hash) {
+    return { pack: newManifest.name, version: newManifest.version, status: 'already-up-to-date', hash: newPackHash };
+  }
+  
+  const fileList = await buildPackFileList(packRoot, newManifest);
+  const priorOwned = ownedPathSet(existing);
+  
+  const destination = path.join(cwd, '.showdar', 'extensions', 'packs', newManifest.name);
+  const tempDir = path.join(cwd, '.showdar', 'extensions', 'packs', `.${newManifest.name}.tmp-${process.pid}-${Date.now()}`);
+  
+  const workflowChanges = [];
+  const oldPackDir = path.join(cwd, '.showdar', 'extensions', 'packs', existingPack.name);
+  let oldManifest = null;
+  try {
+    oldManifest = await readPackManifest(oldPackDir);
+  } catch {}
+  
+  if (oldManifest) {
+    const workflowChangesResult = compareWorkflowDefinitions(oldManifest, newManifest);
+    if (workflowChangesResult.length > 0) {
+      console.warn(`Warning: Custom workflow definitions changed. Existing checkpoints will be revalidated against the current definition when resumed.`);
+      console.warn(`Changed workflows: ${workflowChangesResult.map(c => `${c.type}:${c.workflowId}`).join(', ')}`);
+    }
+  }
+  
+  const newFiles = [];
+  
+  for (const file of fileList) {
+    await assertSafeManagedPath(packRoot, file.source);
+    const dest = path.join(tempDir, file.relative);
+    await assertSafeManagedPath(cwd, dest);
+    await mkdir(path.dirname(dest), { recursive: true });
+    await cp(file.source, dest, { recursive: true });
+  }
+  
+  for (const file of fileList) {
+    const dest = path.join(cwd, '.showdar', 'extensions', 'packs', newManifest.name, file.relative);
+    await assertSafeManagedPath(cwd, dest);
+    const relative = path.relative(cwd, dest).replaceAll(path.sep, '/');
+    
+    if ((await exists(dest)) && !priorOwned.has(relative)) {
+      throw new Error(`Refusing to overwrite existing non-Showdar-managed file: ${dest}`);
+    }
+    await rm(dest, { recursive: true, force: true });
+    await mkdir(path.dirname(dest), { recursive: true });
+    await cp(file.source, dest, { recursive: true });
+    newFiles.push({ path: relative, hash: await hashTree(dest), extension: true });
+  }
+  
+  const merged = new Map((existing.files ?? []).map((e) => [e.path, e]));
+  for (const file of newFiles) merged.set(file.path, file);
+  
+  const packDir = path.join(cwd, '.showdar', 'extensions', 'packs', newManifest.name);
+  await rm(packDir, { recursive: true, force: true }).catch(() => {});
+  
+  const updated = {
+    ...existing,
+    files: [...merged.values()],
+    extensions: {
+      ...(existing.extensions ?? {}),
+      packs: (existing.extensions?.packs ?? []).map(p => p.name === newManifest.name 
+        ? { ...p, version: newManifest.version, hash: newPackHash, installedAt: new Date().toISOString() }
+        : p),
+      customWorkflows: existing.extensions?.customWorkflows?.filter(w => w.source !== `pack:${newManifest.name}`) ?? [],
+    },
+  };
+  
+  if (newManifest.workflows) {
+    updated.extensions.customWorkflows = [
+      ...updated.extensions.customWorkflows,
+      ...newManifest.workflows.map(w => ({
+        id: w.id,
+        source: `pack:${newManifest.name}`,
+        path: `.showdar/extensions/packs/${newManifest.name}/${w.path}`.replaceAll(path.sep, '/'),
+      }))
+    ];
+  }
+  
+  await writeJsonAtomic(manifestPath, updated);
+  
+  return { 
+    pack: newManifest.name, 
+    version: newManifest.version, 
+    status: 'updated', 
+    oldHash: existingPack.hash, 
+    newHash: newPackHash,
+    files: newFiles.length 
+  };
+}
+
+async function exists(target) {
+  try { await access(target); return true; } catch { return false; }
+}
+
+function resolvePackSource({ cwd, source }) {
+  if (typeof source !== 'string' || !source.trim()) throw new Error('Extension source must be a non-empty local path.');
+  const value = source.trim();
+  const resolved = path.resolve(cwd, value);
+  return resolved;
+}
+
+export { updatePack };
+export const packUpdateAPI = { updatePack };

package/src/project.js

@@ -14,6 +14,7 @@ import {
 } from './adapters.js';
 import { normalizeSkillName, ALL_SKILLS } from './catalog.js';
 import { assertSafeManagedPath, lstatWithoutSymlink, safeOwnedPath } from './path-safety.js';
+export { assertSafeManagedPath, lstatWithoutSymlink, safeOwnedPath } from './path-safety.js';
 import { renderManagedBlock, renderShowdarCommand, renderShowdarAggregator } from './adapter-renderers.js';
 import { validatePack } from './validate-pack.js';
 
@@ -55,11 +56,11 @@ async function readManifest(manifestPath, baseRoot) {
   catch (error) { throw new Error(`Invalid Showdar manifest: ${error.message}`); }
 }
 
-async function writeJsonAtomic(target, value) {
+export async function writeJsonAtomic(target, value) {
   await writeTextAtomic(target, `${JSON.stringify(value, null, 2)}\n`);
 }
 
-async function writeTextAtomic(target, value) {
+export async function writeTextAtomic(target, value) {
   const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
   await writeFile(tmp, value, { flag: 'wx' });
   await rename(tmp, target);
@@ -108,7 +109,7 @@ async function removeCursorRule(filePath) {
   }
 }
 
-function ownedPathSet(manifest) {
+export function ownedPathSet(manifest) {
   return new Set((manifest?.files ?? []).map((entry) => entry.path));
 }
 
@@ -121,7 +122,7 @@ function uniqueRoots(targets, resolveRoot) {
   return [...roots.values()];
 }
 
-function manifestPathFor(baseRoot, destination) {
+export function manifestPathFor(baseRoot, destination) {
   const relative = path.relative(baseRoot, destination);
   return relative.replaceAll(path.sep, '/');
 }
@@ -938,4 +939,84 @@ export async function readProjectOverrides({ cwd }) {
   return doc;
 }
 
-export { SHA_HEX_RE };
+export async function validatePackSource({ cwd, source }) {
+  const { validatePack } = await import('./validate-pack.js');
+  const packRoot = path.resolve(cwd, source);
+  return validatePack(packRoot);
+}
+
+export async function createPack({ cwd, path: packPath, vendor, description, withWorkflow, withProfile }) {
+  const { createPackScaffold } = await import('./pack-scaffold.js');
+  const absolutePath = path.resolve(cwd, packPath);
+  const name = path.basename(absolutePath);
+  return createPackScaffold({ destination: absolutePath, name, vendor, description, withWorkflow, withProfile });
+}
+
+export async function inspectPack({ cwd, source }) {
+  const { inspectPackSource } = await import('./pack-inspect.js');
+  const packRoot = path.resolve(cwd, source);
+  return inspectPackSource(packRoot);
+}
+
+export async function doctor({ cwd }) {
+  const { inspectPackInstalled, inspectCustomWorkflows, inspectOverrides, listExtensionsWithDetails } = await import('./pack-inspect.js');
+  const manifestPath = path.join(cwd, '.showdar.json');
+  const manifest = await readManifest(manifestPath, cwd);
+  if (!manifest) throw new Error('Showdar is not installed in project scope.');
+  
+  const packs = [];
+  for (const pack of manifest.extensions?.packs ?? []) {
+    const installed = await import('./pack-inspect.js').then(m => m.inspectPackInstalled(cwd, pack.name, pack));
+    packs.push({ 
+      name: pack.name, 
+      version: pack.version, 
+      hash: pack.hash, 
+      drift: installed.drift, 
+      driftDetails: installed.driftDetails,
+      validation: installed.validation,
+    });
+  }
+  
+  const customWorkflows = await import('./pack-inspect.js').then(m => m.inspectCustomWorkflows(cwd, manifest));
+  
+  const overrides = await readProjectOverrides({ cwd });
+  const overridesStatus = overrides ? 'valid' : 'absent';
+  
+  const issues = [];
+  const warnings = [];
+  
+  for (const pack of packs) {
+    if (pack.drift !== 'no-drift') {
+      issues.push(`Pack ${pack.name}: ${pack.drift} - ${pack.driftDetails}`);
+    }
+    if (!pack.validation?.ok) {
+      for (const error of pack.validation.errors ?? []) {
+        issues.push(`Pack ${pack.name} validation: ${error}`);
+      }
+    }
+  }
+  
+  for (const wf of customWorkflows) {
+    if (!wf.valid) {
+      issues.push(`Workflow ${wf.id}: ${wf.errors?.join(', ')}`);
+    }
+  }
+  
+  const healthy = issues.length === 0;
+  
+  return {
+    healthy,
+    packs,
+    customWorkflows,
+    overrides: { present: overridesStatus !== 'absent', status: overridesStatus },
+    issues,
+    warnings,
+  };
+}
+
+export async function updatePack({ cwd, source }) {
+  const { updatePack } = await import('./pack-update.js');
+  return updatePack({ cwd, source });
+}
+
+export { SHA_HEX_RE, hashTree, readManifest };

package/src/validate-pack.js

@@ -90,7 +90,7 @@ export function validateCustomWorkflowDoc(doc, field = 'workflow') {
   const known = new Set(['id', 'description', 'stages', 'allowedSkips', 'requiredStages', 'completionPolicy', 'workflowStateCompat']);
   for (const key of Object.keys(doc)) if (!known.has(key)) errors.push(`${field} contains unknown key: ${key}`);
   if (!validateCustomWorkflowId(doc.id)) errors.push(`${field} id must use custom namespace grammar (vendor-name, never showdar-*): ${JSON.stringify(doc.id)}`);
-  if (typeof doc.description !== 'string' || doc.description.trim().length < 30) errors.push(`${field} description must be at least 30 characters`);
+  if (typeof doc.description !== 'string' || doc.description.trim().length < 10) errors.push(`${field} description must be at least 10 characters`);
   if (!Array.isArray(doc.stages) || !doc.stages.length) {
     errors.push(`${field} stages must be a non-empty array`);
   } else {

package/src/workflow-state.js

@@ -190,7 +190,7 @@ function validateSkipped(entry, workflowId, selectedStages, catalog = null) {
   for (const key of Object.keys(entry)) {
     if (!SKIPPED_KEYS.has(key)) errors.push(`skipped stage contains unknown key: ${key}`);
   }
-  const rule = (SKIP_RULES[workflowId] ?? {})[entry.stage];
+  const rule = snapshotSkipRule(catalog, workflowId, entry.stage);
   if (!rule) errors.push(`stage ${entry.stage} is not skippable under ${workflowId} policy`);
   else {
     if (entry.reason !== rule.reason) errors.push(`skip reason for ${entry.stage} must be ${rule.reason}`);