# Troubleshooting - CLI Auto Context Detection

Common issues and solutions for MORPH-SPEC auto-detection.

## Claude Code Issues

### Issue: "Claude Code environment not detected"

**Cause**: Auto-detection requires Claude Code CLI to be installed and active.

**Solutions**:

1. **Use wizard mode** (recommended for first-time setup):
   ```bash
   morph-spec init --wizard
   ```

2. **Install Claude Code** and retry:
   - Download from https://claude.ai/claude-code
   - Ensure `claude` command is in PATH
   - Retry `morph-spec init`

3. **Skip auto-detection** and configure manually later:
   ```bash
   morph-spec init --skip-detection
   # Later: morph-spec update --wizard
   ```

### Issue: "LLM analysis timeout"

**Cause**: Analysis taking longer than 60 seconds (default timeout for interactive mode).

**Solutions**:

1. **Clean project before analysis**:
   ```bash
   rm -rf node_modules dist build .next
   morph-spec init
   ```

2. **Use wizard mode** (instant):
   ```bash
   morph-spec init --wizard
   ```

3. **Check Claude Code performance**:
   - Restart Claude Code
   - Check system resources (CPU, memory)

## LLM Analysis Errors

### Issue: "Schema validation failed"

**Cause**: LLM returned JSON that doesn't match the expected schema.

**Diagnosis**:
```bash
# Enable debug mode to see LLM response
DEBUG=1 morph-spec init
```

**Solutions**:

1. **Use wizard mode** to provide manual input:
   ```bash
   morph-spec init --wizard
   ```

2. **Report issue** if recurring:
   - Include project type in issue report
   - Share anonymized `package.json` or `.csproj` structure

### Issue: "LLM response is not valid JSON"

**Cause**: LLM returned malformed JSON (rare).

**Solutions**:

1. **Retry** - may be a one-time error:
   ```bash
   morph-spec init
   ```

2. **Use wizard mode**:
   ```bash
   morph-spec init --wizard
   ```

## File System Issues

### Issue: "Permission denied" when creating .morph/

**Cause**: Insufficient permissions in project directory.

**Solutions**:

1. **Run with correct permissions**:
   ```bash
   sudo morph-spec init  # Unix/Mac
   # Or run as administrator on Windows
   ```

2. **Check directory ownership**:
   ```bash
   ls -la .  # Should show your user as owner
   ```

### Issue: Config files getting overwritten

**Cause**: Running `morph-spec update` without reviewing changes.

**Protection**: Auto-detection creates backups:
- `.morph/project.md.YYYY-MM-DDTHH-MM-SS.backup`
- `.morph/config/config.json.YYYY-MM-DDTHH-MM-SS.backup`

**Solutions**:

1. **Review diff before approving**:
   - Auto-detection shows diff when updating
   - Choose "Edit" to modify before saving

2. **Restore from backup** if needed:
   ```bash
   cp .morph/project.md.2026-02-14T10-30-00.backup .morph/project.md
   ```

3. **Skip auto-detection** during update:
   ```bash
   morph-spec update --skip-detection
   ```

## Detection Accuracy Issues

### Issue: Wrong project type detected

**Example**: Monorepo detected as `nextjs` instead of `monorepo`.

**Solutions**:

1. **Use wizard mode** for accurate manual input:
   ```bash
   morph-spec init --wizard
   ```

2. **Edit config after generation**:
   - Choose "Edit" during review
   - Manually correct `type` field in config.json

3. **Report detection issue**:
   - Helps improve LLM prompt and examples

### Issue: Missing dependencies detected

**Cause**: Auto-detection only reads whitelisted files (package.json, .csproj).

**Solution**:

- This is by design (privacy/security)
- If critical dependency is missed, manually edit `.morph/project.md`

### Issue: Low confidence score (<70%)

**Cause**: Project structure is unclear or non-standard.

**Solutions**:

1. **Add README.md or CLAUDE.md** with project description
2. **Use wizard mode** for manual configuration
3. **Accept low confidence** - configs can be edited later

## Edge Case Handling

### Empty Project (no package.json or .csproj)

**Behavior**: Auto-fallback to wizard mode.

**Solution**: Answer 7 wizard questions to configure manually.

### Monorepo with Multiple Stacks

**Behavior**: Detects all stacks, sets `type: "monorepo"`.

**Example Output**:
```json
{
  "type": "monorepo",
  "stack": {
    "frontend": { "tech": "Next.js", "version": "15" },
    "backend": { "tech": ".NET", "version": "10" }
  }
}
```

### Project with No Database

**Behavior**: `stack.database` set to `null`.

**Warning**: May show "Database technology not detected" in warnings.

### Git Repo Without Remote

**Behavior**: `gitRemote` set to `null`.

**Not an error** - local repos are valid.

## Privacy & Security Concerns

### Question: What data is sent to LLM?

**Answer**: Only sanitized, whitelisted data:
- package.json (dependencies only, secrets removed)
- .csproj filenames (not contents)
- First 500 chars of README.md and CLAUDE.md
- Directory structure (folder names only)
- Infrastructure file counts (not contents)

**Never sent**:
- `.env` files
- Secrets/passwords/API keys
- File contents (except whitelisted files)
- node_modules/
- Source code

### Question: Is data sent to Anthropic servers?

**Answer**: No. LLM analysis runs locally in Claude Code. No external API calls.

### Question: What if sensitive data is detected?

**Behavior**: Secret redaction removes:
- API keys (10+ patterns detected)
- Passwords in connection strings
- Bearer tokens
- Private keys (PEM format)
- GitHub/NPM tokens

**Verification**: Review sanitized context in debug mode:
```bash
DEBUG=1 morph-spec init
```

## Getting Help

### Enable Debug Mode

```bash
DEBUG=1 morph-spec init
```

Shows:
- Full LLM prompts
- Raw LLM responses
- Schema validation errors
- File read operations

### Report Issues

GitHub: https://github.com/polymorphism-tech/morph-spec-framework/issues

Include:
- MORPH-SPEC version (`morph-spec --version`)
- Claude Code version
- Project type (Next.js, Blazor, etc.)
- Error message (with DEBUG=1 output if possible)
- Anonymized `package.json` or `.csproj` structure

---

**Need more help?** Check the [CLI Auto Detection Guide](./cli-auto-detection.md).
