showdar-skills 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.14.0]
+
+### Added
+
+- Project-aware onboarding through `showdar setup`, including repository inspection, GitHub/GitLab/local tracker detection, package script discovery, read-only `--dry-run --json` planning, and interactive confirmation.
+- Shared project documents under `docs/agents/` for project architecture, issue tracker, verification scripts and domain vocabulary; existing documents are preserved without overwrites, and agent routing guidance consumes them when present.
+- Native `/showdar/setup` entrypoint on command-capable harnesses (OpenCode and Claude), preserving the frozen router semantics and unchanged 22-skill catalog.
+- Interactive multi-select installation wizard (`showdar wizard` or `showdar add --interactive`) for profile, skills, workflows, agent target and project/global scope, with add/replace modes, previews and CI-friendly flags.
+
+### Safety
+
+- Setup edits require the existing Git preflight guard. Path traversal and symlinked output paths are rejected; no speculative glossary or ADR documents are created.
+- The wizard defaults to additive installation and requires explicit `--mode replace` for removing managed skills. Non-interactive installation requires explicit selections and `--yes`.
+
+
 ## [0.13.0]
 
 ### Added

package/README.md

@@ -66,6 +66,44 @@ authorize source mutation, commit, merge or push. A custom workflow JSON file
 uses the existing `add-workflow` validation/manifest semantics; remote files
 and arbitrary executable plugins are unsupported.
 
+## Guided onboarding and project context
+
+Showdar also offers repo-aware onboarding after installing the CLI and selected
+skills. It detects Git host, package scripts, stack and documentation, then
+previews the files it would create:
+
+```bash
+showdar setup --dry-run --json
+showdar setup                       # interactive terminal questionnaire
+showdar setup --yes --tracker gitlab # non-interactive, requires safe task branch
+```
+
+Run `showdar guard --mutation local-write --json` before applying setup changes.
+On an integration branch, use `showdar git-start` first. Setup never writes
+code or silently overwrites existing user docs. It creates only missing
+`docs/agents/project.md`, `issue-tracker.md`, `verification.md`, and
+`domain.md`. A glossary and ADRs are referenced if present, not created
+unnecessarily. Installed native guidance asks skills to consult relevant
+shared context when it exists. OpenCode/Claude expose `/showdar/setup`;
+other agents can run `showdar setup` from their terminal.
+
+The installer also has an interactive selector:
+
+```bash
+showdar wizard
+showdar add --interactive                 # additive wizard alias
+showdar wizard --profile developer --skills git,insurance-domain --workflow feature --ai opencode --dry-run
+showdar wizard --profile developer --skills git --ai opencode --yes
+showdar wizard --mode replace --profile insurance --ai codex --yes
+```
+
+The wizard chooses install mode (add or replace), profile, additional skills,
+built-in workflows, AI target, and scope. It previews the deduplicated skill
+set and confirms before changing files. Non-interactive executions require
+explicit skill selection and `--yes`, unless using `--dry-run`. The default
+mode is additive, preserving the current installation; replace mode uses
+the same semantics as `showdar init`. No downloads or remote writes occur.
+
 ## Runtime routing and task branches
 
 ```bash
@@ -871,6 +909,8 @@ Product behavior notes:
 ```bash
 showdar init [--scope <project|global>] --ai <target> --profile <profile>
 showdar add <skill> [--ai <target>] [--scope <project|global>]
+showdar setup [--dry-run|--yes] [--tracker github|gitlab|local] [--docs-dir docs/agents]
+showdar wizard [--mode add|replace] [--profile name] [--skills list] [--workflow list] [--ai target] [--scope project|global] [--yes|--dry-run]
 showdar add profile <profile> [--ai <target>] [--scope <project|global>]
 showdar add workflow <builtin-name|local-json-path> [--ai <target>] [--scope <project|global>]
 showdar add-pack <local-path>

package/bin/showdar.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 import path from 'node:path';
 import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import { planProjectSetup, applyProjectSetup } from '../src/setup.js';
+import { buildWizardPlan, applyWizardPlan, collectWizardAnswers } from '../src/wizard.js';
 import { startTaskBranch, formatGitStart } from '../src/git-start.js';
 import { guardMutation, formatMutationGuard } from '../src/git-guard.js';
 import { routeRequest, formatRoute } from '../src/runtime-route.js';
@@ -49,6 +52,14 @@ function printHelp(version, command = null) {
     console.log('Usage: showdar guard --mutation <read-only|local-write> [--json]');
     return;
   }
+  if (command === 'setup') {
+    console.log('Usage: showdar setup [--dry-run|--yes] [--tracker github|gitlab|local] [--docs-dir docs/agents] [--json]');
+    return;
+  }
+  if (command === 'wizard') {
+    console.log('Usage: showdar wizard [--mode add|replace] [--profile name] [--skills comma,list] [--workflow comma,list] [--ai target] [--scope project|global] [--yes|--dry-run] [--json]');
+    return;
+  }
   if (command === 'init') {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>]\n\nDefaults: scope project, profile full, AI target universal.\nProject scope writes native skills, one native instruction surface, and project .showdar.json. Global scope writes verified user skill directories and ~/.showdar/global.json without instruction files. Codex and universal use .agents/skills in project scope and ~/.agents/skills in global scope; cursor uses .cursor/skills in project scope and ~/.cursor/skills in global scope; --ai all writes each shared destination once, generates OpenCode and Claude commands, and writes only the AGENTS.md block.\n\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
     return;
@@ -61,7 +72,7 @@ function printHelp(version, command = null) {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <target>] [--scope <project|global>]\n  showdar add profile <profile> [--ai <target>] [--scope <project|global>]\n  showdar add workflow <builtin-name|local-json-path> [--ai <target>] [--scope <project|global>]\n\nExamples:\n  showdar add git\n  showdar add showdar-git\n  showdar add profile insurance\n  showdar add workflow feature\n  showdar add workflow ./workflows/acme-release.json\n\nAdd preserves installed skills; init replaces the managed set. Built-in workflows add required stages.`);
     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 <target>] [--scope <project|global>]\n  showdar add profile <profile> [--ai <target>] [--scope <project|global>]\n  showdar add workflow <builtin-name|local-json-path> [--ai <target>] [--scope <project|global>]\n  showdar route (--stdin | --prompt <text>) [--json]\n  showdar git-start --type <type> --name <task> [--base <branch>] [--dry-run] [--json]\n  showdar guard --mutation <read-only|local-write> [--json]\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] [--checkpoint <file>]\n  showdar doctor ${scopeUsage} [--extensions] [--json]\n  showdar update-pack <local-path> [--dry-run] [--json]\n  showdar validate\n  showdar list [--extensions] [--json]\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 <target>] [--scope <project|global>]\n  showdar add profile <profile> [--ai <target>] [--scope <project|global>]\n  showdar add workflow <builtin-name|local-json-path> [--ai <target>] [--scope <project|global>]\n  showdar route (--stdin | --prompt <text>) [--json]\n  showdar git-start --type <type> --name <task> [--base <branch>] [--dry-run] [--json]\n  showdar guard --mutation <read-only|local-write> [--json]\n  showdar setup [--dry-run|--yes] [--tracker github|gitlab|local] [--json]\n  showdar wizard [--mode add|replace] [--profile <name>] [--skills <names>] [--workflow <names>] [--ai <target>] [--scope <project|global>] [--yes|--dry-run]\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] [--checkpoint <file>]\n  showdar doctor ${scopeUsage} [--extensions] [--json]\n  showdar update-pack <local-path> [--dry-run] [--json]\n  showdar validate\n  showdar list [--extensions] [--json]\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() {
@@ -79,6 +90,80 @@ async function main() {
 
   const scope = ['init', 'status', 'doctor', 'remove', 'add'].includes(command) ? scopeAfter(args) : null;
 
+  if (command === 'setup') {
+    const { values } = parseArgs({ args: args.slice(1), options: {
+      'dry-run': { type: 'boolean' }, yes: { type: 'boolean' },
+      tracker: { type: 'string' }, 'docs-dir': { type: 'string' },
+      json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+    } });
+    if (values.help) return printHelp(version, command);
+    let tracker = values.tracker ?? null;
+    let docsDir = values['docs-dir'] ?? 'docs/agents';
+    if (!values.yes && !values['dry-run']) {
+      if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw new Error('Setup needs an interactive TTY, --dry-run, or --yes.');
+      const initial = await planProjectSetup({ cwd: projectRoot, tracker, docsDir });
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      try {
+        tracker = (await rl.question('Issue tracker (github/gitlab/local) [' + initial.tracker + ']: ')).trim() || initial.tracker;
+        docsDir = (await rl.question('Shared docs path [docs/agents]: ')).trim() || docsDir;
+        const preview = await planProjectSetup({ cwd: projectRoot, tracker, docsDir });
+        console.log('Preview: ' + preview.files.map(f => f.action + ' ' + f.path).join(', '));
+        const approved = (await rl.question('Apply? Type yes: ')).trim() === 'yes';
+        if (!approved) { console.log('Setup cancelled without changes.'); return; }
+      } finally { rl.close(); }
+    }
+    const plan = await planProjectSetup({ cwd: projectRoot, tracker, docsDir });
+    if (values['dry-run']) {
+      console.log(values.json ? JSON.stringify({ ok: true, command, data: plan }, null, 2)
+        : 'Setup preview:\n' + plan.files.map(f => '  ' + f.action + ' ' + f.path).join('\n'));
+      return;
+    }
+    const result = await applyProjectSetup({ cwd: projectRoot, plan });
+    console.log(values.json ? JSON.stringify({ ok: true, command, data: result }, null, 2)
+      : 'Setup completed. Created: ' + result.created.length + '; preserved: ' + result.preserved.length
+        + '. Shared context: ' + result.docsDir);
+    return;
+  }
+
+  if (command === 'wizard' || (command === 'add' && args.includes('--interactive'))) {
+    const wizardArgs = command === 'add' ? args.filter(a => a !== '--interactive').slice(1) : args.slice(1);
+    const { values } = parseArgs({ args: wizardArgs, options: {
+      mode: { type: 'string' }, profile: { type: 'string' },
+      skills: { type: 'string' }, workflow: { type: 'string' },
+      ai: { type: 'string' }, scope: { type: 'string' },
+      yes: { type: 'boolean' }, 'dry-run': { type: 'boolean' },
+      json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+    } });
+    if (values.help) return printHelp(version, 'wizard');
+    let plan;
+    if (values.yes || values['dry-run']) {
+      plan = buildWizardPlan({
+        mode: values.mode ?? 'add', profile: values.profile ?? null,
+        skills: values.skills ?? '', workflows: values.workflow ?? '',
+        ai: values.ai ?? 'universal', scope: values.scope ?? 'project',
+      });
+    } else {
+      const collected = await collectWizardAnswers({
+        mode: values.mode, profile: values.profile, skills: values.skills,
+        workflows: values.workflow, ai: values.ai, scope: values.scope,
+      });
+      if (collected.cancelled) { console.log('Wizard cancelled without changes.'); return; }
+      plan = collected.plan;
+    }
+    if (values['dry-run']) {
+      console.log(values.json ? JSON.stringify({ ok: true, command: 'wizard', data: plan }, null, 2)
+        : 'Wizard preview (' + plan.action + '): ' + plan.skills.join(', '));
+      return;
+    }
+    const installed = await applyWizardPlan({
+      cwd: projectRoot, home: homedir(), packageRoot, packageVersion: version, plan,
+    });
+    console.log(values.json ? JSON.stringify({ ok: true, command: 'wizard', data: { plan, installed } }, null, 2)
+      : 'Wizard completed: ' + plan.action + ' ' + plan.skills.length + ' skills. Run showdar doctor to verify.');
+    return;
+  }
+
   if (command === 'guard') {
     const { values } = parseArgs({ args: args.slice(1), options: { mutation: { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
     if (values.help) return printHelp(version, command);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": {

package/src/adapter-renderers.js

@@ -3,7 +3,8 @@ import { ALL_SKILLS } from './catalog.js';
 const RUNTIME_GUIDANCE = `Automatic Showdar selection: route the current request through \`showdar route --stdin --json\` when the Showdar CLI is available. Supply the prompt as literal stdin data, never as interpolated shell syntax. Honor the canonical lifecycle primary; do not substitute another installed skill when it is missing. Report missing skills and suggest \`showdar add <name>\`; never auto-install. Include installed domain matches only as specialized context overlays; load returned advisors only when installed. Domain discovery does not grant authority or replace the lifecycle route.
 Explicit named-skill requests may load that installed skill directly without automatic routing. Workflow skills remain native discoverable choices; the router does not select workflows. If the CLI is unavailable, use native skill discovery/static descriptions below. Do not fetch a CLI through npx or install dependencies automatically.
 Routing does not authorize mutation. Inspect the returned mutation class and current task authority before work. For local-write tasks, before the first task-owned source edit inspect Git state. On develop, development, dev, main, master or the repository default/integration branch, DO NOT begin source edits yet: prepare one branch per coherent task first. Follow repository instructions/documented convention, explicit current user instruction, clearly detected convention, then the Showdar safe default. Explicit trunk/direct-work policy wins.
-Before ANY task-owned source/config/test/docs write, execute Git preflight even if the router selected build directly. On integration/default branches inspect repository policy and EXECUTE \`showdar git-start --type <type> --name <task>\` (not just --dry-run), or equivalent repository-safe branch preparation. Then EXECUTE \`showdar guard --mutation local-write --json\` and require ok=true AND data.allowed=true BEFORE invoking any file-writing tool. If blocked, STOP before editing. On a matching task branch run guard without creating a new branch. Recheck before each later mutating stage. Do not infer permission from \`showdar route\`. If the CLI is unavailable, manually inspect Git and confirm the appropriate task branch or documented direct-work policy; never silently write on develop/main. Dirty ownership/branch collisions require inspection; never infer stash/reset/restore/clean. Guard and git-start do not authorize source edits, commit, merge or push. Completion means verify and report.`;
+Before ANY task-owned source/config/test/docs write, execute Git preflight even if the router selected build directly. On integration/default branches inspect repository policy and EXECUTE \`showdar git-start --type <type> --name <task>\` (not just --dry-run), or equivalent repository-safe branch preparation. Then EXECUTE \`showdar guard --mutation local-write --json\` and require ok=true AND data.allowed=true BEFORE invoking any file-writing tool. If blocked, STOP before editing. On a matching task branch run guard without creating a new branch. Recheck before each later mutating stage. Do not infer permission from \`showdar route\`. If the CLI is unavailable, manually inspect Git and confirm the appropriate task branch or documented direct-work policy; never silently write on develop/main. Dirty ownership/branch collisions require inspection; never infer stash/reset/restore/clean. Guard and git-start do not authorize source edits, commit, merge or push. Completion means verify and report.
+Shared project context: before project work, read the relevant existing files under docs/agents/ (project.md, issue-tracker.md, verification.md, domain.md) when present. These are project-specific conventions, not mutation authority. Use the canonical glossary and ADRs when present; do not invent them. If project setup has not run, proceed using normal repository evidence and suggest showdar setup only when useful.`;
 
 const CANONICAL_ROUTE_ORDER = [
   ['map repository architecture, dependencies, or impact', 'showdar-understand'],
@@ -94,3 +95,22 @@ export function renderManagedBlock(skillIds, kind) {
   }
   return body;
 }
+
+export function renderShowdarSetupCommand() {
+  return [
+    '---',
+    'description: Configure Showdar project context after inspecting repository conventions',
+    '---',
+    '',
+    'Project onboarding only; do not automatically install dependencies, create issues, or edit source.',
+    'Run showdar setup --dry-run --json to inspect and preview. Show the detected tracker, scripts, and documents.',
+    'Ask only for missing/ambiguous choices; explain the proposed defaults.',
+    'Before applying, inspect Git state and follow showdar-git branch preflight. Never edit develop/main without documented direct-work policy.',
+    'After user approval, run showdar setup --yes with chosen --tracker and --docs-dir.',
+    'Do not overwrite existing project context files. The setup CLI preserves them.',
+    'Read docs/agents/project.md, issue-tracker.md, verification.md and domain.md as shared context where they exist.',
+    '',
+    'Request: $ARGUMENTS',
+    '',
+  ].join('\n');
+}

package/src/project.js

@@ -15,7 +15,7 @@ import {
 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 { renderManagedBlock, renderShowdarCommand, renderShowdarAggregator, renderShowdarSetupCommand } from './adapter-renderers.js';
 import { validatePack } from './validate-pack.js';
 
 const PROJECT_MANIFEST = '.showdar.json';
@@ -164,6 +164,14 @@ async function generateCommandFiles({ baseRoot, skillIds, target, commandRoot, p
   await writeTextAtomic(aggregatorDest, aggregatorContent);
   newFiles.push({ path: aggregatorRel, hash: await hashTree(aggregatorDest) });
   files.push({ destination: aggregatorDest, skillId: 'aggregator', shortName: 'skill' });
+  const setupDest = path.join(commandRoot, 'setup.md');
+  const setupRel = manifestPathFor(baseRoot, setupDest);
+  if ((await exists(setupDest)) && !priorOwned.has(setupRel)) {
+    throw new Error('Refusing to overwrite existing non-Showdar-managed command: ' + setupDest);
+  }
+  await writeTextAtomic(setupDest, renderShowdarSetupCommand());
+  newFiles.push({ path: setupRel, hash: await hashTree(setupDest) });
+  files.push({ destination: setupDest, skillId: 'setup', shortName: 'setup' });
   return files;
 }
 

package/src/setup.js

@@ -0,0 +1,136 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { assertSafeManagedPath } from './path-safety.js';
+import { guardMutation } from './git-guard.js';
+
+const DOC_ROOT = 'docs/agents';
+const DOCS = ['project.md', 'issue-tracker.md', 'verification.md', 'domain.md'];
+const codeQuote = text => String.fromCharCode(96) + text + String.fromCharCode(96);
+
+async function exists(file) {
+  try { await access(file); return true; }
+  catch (e) { if (e.code === 'ENOENT') return false; throw e; }
+}
+function git(cwd, ...args) {
+  try {
+    return execFileSync('git', ['--no-optional-locks', ...args], {
+      cwd, encoding: 'utf8', timeout: 6000, stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch { return ''; }
+}
+async function readJson(file) {
+  if (!(await exists(file))) return null;
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch { return null; }
+}
+export function validateDocsDir(value) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('Document directory must be a relative path.');
+  if (value.includes('\0') || value.includes('\\') || path.isAbsolute(value) ||
+      value.split('/').some(part => !part || part === '.' || part === '..') ||
+      value === '.git' || value.startsWith('.git/')) {
+    throw new Error('Invalid document directory: use a safe project-relative path.');
+  }
+  return value;
+}
+export async function inspectSetupProject(cwd) {
+  const pkg = await readJson(path.join(cwd, 'package.json'));
+  const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+  const remote = git(cwd, 'remote', 'get-url', 'origin');
+  const tracker = /github\.com[:/]/i.test(remote) ? 'github'
+    : /gitlab/i.test(remote) ? 'gitlab' : 'local';
+  const workspace = await exists(path.join(cwd, 'pnpm-workspace.yaml')) || !!pkg?.workspaces;
+  const technologies = [
+    ['next', 'Next.js'], ['react', 'React'], ['react-native', 'React Native'],
+    ['vue', 'Vue'], ['vite', 'Vite'], ['typescript', 'TypeScript'],
+    ['vitest', 'Vitest'], ['jest', 'Jest'],
+  ].filter(([key]) => pkg?.dependencies?.[key] || pkg?.devDependencies?.[key]).map(([, label]) => label);
+  const docs = {
+    glossary: await exists(path.join(cwd, 'GLOSSARY.md')),
+    glossaryMap: await exists(path.join(cwd, 'GLOSSARY-MAP.md')),
+    adr: await exists(path.join(cwd, 'docs', 'adr')),
+    agents: await exists(path.join(cwd, 'AGENTS.md')),
+    claude: await exists(path.join(cwd, 'CLAUDE.md')),
+  };
+  return {
+    root: cwd, remote: remote || null, tracker,
+    workspace: workspace ? 'monorepo' : 'single-context',
+    packageName: pkg?.name || path.basename(cwd),
+    technologies, scripts: Object.fromEntries(Object.entries(scripts).filter(
+      ([name, script]) => ['test', 'typecheck', 'type-check', 'lint', 'build', 'check', 'validate'].includes(name)
+        && typeof script === 'string')),
+    docs,
+  };
+}
+function docText(name, details, tracker, docsDir) {
+  const { technologies, packageName, scripts, workspace, docs } = details;
+  if (name === 'project.md') return [
+    '# Project context', '', 'Project: ' + packageName, 'Layout: ' + workspace,
+    'Detected stack: ' + (technologies.join(', ') || 'not detected'), '',
+    'Project-specific context for all installed Showdar skills. Review detected values.',
+    'Detection does not authorize changes to code or configuration.', '',
+  ].join('\n');
+  if (name === 'issue-tracker.md') return [
+    '# Issue tracker', '', 'Provider: ' + tracker,
+    'Remote: ' + (details.remote || 'not configured'), '',
+    tracker === 'github' ? 'Use repository GitHub Issues and PR conventions.'
+      : tracker === 'gitlab' ? 'Use repository GitLab Issues and MR conventions.'
+        : 'Use local files or replace this section with your tracker convention.',
+    'Do not modify remote issues without explicit task authorization.', '',
+  ].join('\n');
+  if (name === 'verification.md') {
+    const lines = Object.entries(scripts).map(([name, script]) =>
+      '- ' + name + ': ' + codeQuote(script.replaceAll('\n', ' ')));
+    return ['# Verification', '', 'Detected package scripts (inspect before running):',
+      ...(lines.length ? lines : ['- No standard verification scripts detected']),
+      '', 'Run narrow checks first and full checks before handoff.',
+      'Never execute untrusted project scripts without reviewing their content.', ''].join('\n');
+  }
+  return ['# Domain context', '', 'Layout: ' + workspace,
+    'Glossary: ' + (docs.glossary ? 'GLOSSARY.md' : docs.glossaryMap ? 'GLOSSARY-MAP.md' : 'not yet present'),
+    'Architecture decisions: ' + (docs.adr ? 'docs/adr/' : 'not yet present'), '',
+    'Read an existing glossary and relevant ADRs before changing domain names.',
+    'Create glossary entries and ADRs lazily when actual decisions are resolved.',
+    'Shared context directory: ' + docsDir, ''].join('\n');
+}
+export async function planProjectSetup({ cwd, docsDir = DOC_ROOT, tracker = null } = {}) {
+  if (!cwd) throw new Error('Project directory is required.');
+  const root = path.resolve(cwd);
+  const folder = validateDocsDir(docsDir);
+  const details = await inspectSetupProject(root);
+  const selected = tracker || details.tracker;
+  if (!['github', 'gitlab', 'local'].includes(selected)) throw new Error('Tracker must be github, gitlab or local.');
+  const files = [];
+  for (const name of DOCS) {
+    const rel = folder + '/' + name;
+    const dest = path.resolve(root, rel);
+    await assertSafeManagedPath(root, dest);
+    const present = await exists(dest);
+    files.push({ path: rel, action: present ? 'preserve' : 'create',
+      content: present ? null : docText(name, details, selected, folder) });
+  }
+  return { schemaVersion: 1, tracker: selected, docsDir: folder, inspection: details, files };
+}
+export async function applyProjectSetup({ cwd, plan }) {
+  if (!plan || plan.schemaVersion !== 1) throw new Error('Invalid setup plan.');
+  const root = path.resolve(cwd);
+  const gate = guardMutation({ cwd: root, mutation: 'local-write' });
+  if (!gate.allowed) throw new Error('Setup blocked by Git preflight: ' + gate.code + '. Run showdar git-start first.');
+  const folder = validateDocsDir(plan.docsDir);
+  const fresh = await planProjectSetup({ cwd: root, docsDir: folder, tracker: plan.tracker });
+  const created = [], preserved = [];
+  for (const file of fresh.files) {
+    const dest = path.resolve(root, file.path);
+    await assertSafeManagedPath(root, dest);
+    if (file.action === 'preserve') { preserved.push(file.path); continue; }
+    await mkdir(path.dirname(dest), { recursive: true });
+    try {
+      await writeFile(dest, file.content, { flag: 'wx' });
+      created.push(file.path);
+    } catch (e) {
+      if (e.code === 'EEXIST') { preserved.push(file.path); continue; }
+      throw e;
+    }
+  }
+  return { created, preserved, docsDir: folder, tracker: fresh.tracker };
+}

package/src/wizard.js

@@ -0,0 +1,81 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { PROFILES, ALL_SKILLS, resolveProfile, normalizeSkillName, getWorkflow } from './catalog.js';
+import { NATIVE_TARGETS } from './adapters.js';
+import { addSkills, initGlobal, initProject } from './project.js';
+
+const split = value => typeof value === 'string' ? value.split(',').map(x => x.trim()).filter(Boolean) : [];
+function ensureChoice(value, choices, label) {
+  if (!choices.includes(value)) throw new Error('Unknown ' + label + ': ' + value + '. Expected ' + choices.join(', '));
+  return value;
+}
+export function buildWizardPlan({
+  mode = 'add', profile = null, skills = '', workflows = '', ai = 'universal', scope = 'project',
+} = {}) {
+  ensureChoice(mode, ['add', 'replace'], 'mode');
+  ensureChoice(ai, [...NATIVE_TARGETS, 'all'], 'AI target');
+  ensureChoice(scope, ['project', 'global'], 'scope');
+  const selected = profile ? resolveProfile(profile) : [];
+  const workflowsFound = [];
+  for (const name of split(workflows)) {
+    const wf = getWorkflow(name.startsWith('showdar-') ? name : 'showdar-' + name);
+    if (!wf) throw new Error('Unknown built-in workflow ' + name);
+    workflowsFound.push(wf.id);
+    selected.push(wf.id, ...wf.stages);
+  }
+  selected.push(...split(skills).map(normalizeSkillName));
+  const all = [...new Set(selected)];
+  if (!all.length) throw new Error('Choose at least one skill, profile, or workflow.');
+  return { schemaVersion: 1, mode, profile, scope, ai, skills: all,
+    workflows: workflowsFound, action: mode === 'add' ? 'union' : 'replace' };
+}
+export async function applyWizardPlan({ cwd, home, packageRoot, packageVersion, plan }) {
+  if (plan?.schemaVersion !== 1 || !['add', 'replace'].includes(plan.mode)) {
+    throw new Error('Invalid wizard plan.');
+  }
+  const safe = buildWizardPlan({ mode: plan.mode, profile: null,
+    skills: plan.skills.join(','), ai: plan.ai, scope: plan.scope });
+  if (safe.skills.length !== plan.skills.length) throw new Error('Invalid wizard plan members.');
+  if (plan.mode === 'add') {
+    return addSkills({ cwd, home, packageRoot, packageVersion,
+      skills: safe.skills, ai: safe.ai, scope: safe.scope });
+  }
+  const profile = plan.profile || 'custom';
+  return safe.scope === 'global'
+    ? initGlobal({ homeRoot: home, packageRoot, packageVersion, profile,
+      ai: safe.ai, skillIds: safe.skills })
+    : initProject({ projectRoot: cwd, homeRoot: home, packageRoot, packageVersion,
+      profile, ai: safe.ai, skillIds: safe.skills });
+}
+export async function collectWizardAnswers(defaults = {}) {
+  if (!stdin.isTTY || !stdout.isTTY) {
+    throw new Error('Interactive wizard requires a TTY. Use --profile/--skills/--workflow with --yes or --dry-run in CI.');
+  }
+  const rl = createInterface({ input: stdin, output: stdout });
+  async function ask(label, defaultValue) {
+    const response = (await rl.question(label + ' [' + defaultValue + ']: ')).trim();
+    return response || defaultValue;
+  }
+  try {
+    stdout.write('\nShowdar installation wizard (no files changed until confirmation)\n');
+    const mode = await ask('Mode (add/replace)', defaults.mode || 'add');
+    const ai = await ask('AI target (' + [...NATIVE_TARGETS, 'all'].join('/') + ')', defaults.ai || 'universal');
+    const scope = await ask('Scope (project/global)', defaults.scope || 'project');
+    stdout.write('Available profiles: ' + Object.keys(PROFILES).join(', ') + '\n');
+    const profile = await ask('Profile (or none)', defaults.profile || 'none');
+    stdout.write('Available skills: ' + ALL_SKILLS.map(s => s.id.replace(/^showdar-/, '')).join(', ') + '\n');
+    const skills = await ask('Extra skills (comma-separated, or none)', defaults.skills || 'none');
+    const workflows = await ask('Built-in workflows (comma-separated, or none)', defaults.workflows || 'none');
+    const plan = buildWizardPlan({
+      mode, ai, scope, profile: profile === 'none' ? null : profile,
+      skills: skills === 'none' ? '' : skills,
+      workflows: workflows === 'none' ? '' : workflows,
+    });
+    stdout.write('\nPreview: ' + plan.action + ' ' + plan.skills.length +
+      ' skills on ' + plan.ai + ' (' + plan.scope + ')\n' +
+      plan.skills.map(s => '  - ' + s).join('\n') + '\n');
+    const confirm = await ask('Apply changes? (yes/no)', 'no');
+    if (confirm !== 'yes') return { plan, cancelled: true };
+    return { plan, cancelled: false };
+  } finally { rl.close(); }
+}