docs(troubleshooting): explain missing workflow commands

docs-lab/start/setup.md

@@ -112,4 +112,26 @@ Config changes:
 
 Answering yes applies it to the current project on the spot. Other projects pick it up on their next `openspec update`. The setting is global, per machine.
 
+#### Claude Code doesn't show the workflows
+
+Claude Code loads OpenSpec workflows from one or both of these project paths, based on your delivery setting:
+
+- **Skills**: `.claude/skills/openspec-*/SKILL.md`
+- **Commands**: `.claude/commands/opsx/<id>.md`
+
+If the files are missing, refresh the project. In your terminal:
+
+```bash
+openspec update
+```
+
+If the command files exist but `/opsx:` shows no OpenSpec commands, update Claude Code and restart it. If commands still don't load, enable skills too. In your terminal:
+
+```bash
+openspec config set delivery both
+openspec update
+```
+
+Restart Claude Code, then run `/openspec-propose` in its chat. If only some workflows are missing, [change your profile](../customize/profiles.md#expanding-the-set-optional-workflows).
+
 Setup is done. The [Quickstart](quickstart.md) takes your first change from here.

test/setup-docs-claims.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { claudeAdapter } from '../src/core/command-generation/adapters/claude.js';
+import { AI_TOOLS } from '../src/core/config.js';
+import { CORE_WORKFLOWS } from '../src/core/profiles.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SETUP = fs.readFileSync(
+  path.join(REPO_ROOT, 'docs-lab', 'start', 'setup.md'),
+  'utf-8'
+);
+const PROFILES = fs.readFileSync(
+  path.join(REPO_ROOT, 'docs-lab', 'customize', 'profiles.md'),
+  'utf-8'
+);
+const CORE_SECTION = PROFILES.split('## The core set')[1].split(
+  '## Expanding the set: optional workflows'
+)[0];
+
+describe('setup documentation', () => {
+  it('keeps the Claude Code paths and recovery commands aligned with OpenSpec', () => {
+    const claude = AI_TOOLS.find((tool) => tool.value === 'claude');
+    const claudeCommandPath = claudeAdapter.getFilePath('<id>').split(path.sep).join('/');
+
+    expect(claude?.skillsDir).toBeDefined();
+    expect(SETUP).toContain(`\`${claude?.skillsDir}/skills/openspec-*/SKILL.md\``);
+    expect(SETUP).toContain(`\`${claudeCommandPath}\``);
+    expect(SETUP).toContain('openspec config set delivery both');
+    expect(SETUP).toContain('openspec update');
+    expect(SETUP).toContain('`/openspec-propose`');
+  });
+
+  it('lists every workflow in the core profile', () => {
+    for (const workflow of CORE_WORKFLOWS) {
+      expect(CORE_SECTION).toContain(`\`${workflow}\``);
+    }
+  });
+});