# Plan: `markitect helper` CLI Command

## Context

Add an interactive Q&A facility to markitect that answers questions about markitect itself using its own documentation as knowledge context. Uses the existing LLM adapter infrastructure with OpenRouter and `openrouter/aurora-alpha` as default.

## New Files

### 1. `markitect/helper/__init__.py`
Empty package init.

### 2. `markitect/helper/knowledge.py` — Knowledge Loader

- `collect_knowledge() -> str` function that:
  - Finds markitect's documentation directory relative to the package root (`Path(__file__).resolve().parent.parent.parent`)
  - Reads key markdown files in priority order:
    1. `INTRODUCTION.md`
    2. `docs/CLI_TUTORIAL.md`
    3. `docs/PROJECT_STRUCTURE.md`
    4. `docs/SCHEMA_MANAGEMENT_GUIDE.md`
    5. `docs/PLUGIN_SYSTEM.md`
    6. `docs/ERROR_HANDLING_STRATEGY.md`
    7. `docs/architecture/CAPABILITIES_ARCHITECTURE.md`
    8. `docs/architecture/caching-system.md`
    9. `docs/user-guides/*.md` (all files)
    10. `examples/content-generator/TUTORIAL.md`
    11. `examples/infospace-with-history/TUTORIAL.md`
    12. Module docstrings from `markitect/prompts/__init__.py` and `markitect/llm/__init__.py`
  - Concatenates with `## <filename>` section headers between each doc
  - Skips missing files gracefully (log warning if verbose)
  - Returns the combined knowledge string

### 3. `markitect/helper/cli.py` — Click Command

```python
@click.command("helper")
@click.argument("question", nargs=-1, required=True)  # accepts multi-word questions without quotes
@click.option("--provider", "-p", default="openrouter",
              type=click.Choice(["openrouter", "claude-code", "gemini", "openai"]),
              help="LLM provider")
@click.option("--model", "-m", default=None,
              help="Model name (overrides MARKITECT_HELPER_MODEL env var and default)")
```

Logic:
1. Join `question` tuple into a single string
2. Resolve model: CLI `--model` flag → `MARKITECT_HELPER_MODEL` env var → `openrouter/aurora-alpha`
3. Call `collect_knowledge()` to build the knowledge context
4. Build system prompt: `"You are a markitect expert assistant. Answer questions based on the following markitect documentation:\n\n{knowledge}"`
5. Call `create_adapter(provider, model=model, system_prompt=system_prompt)`
6. Call `adapter.execute_prompt(question, RunConfig(max_tokens=4000, temperature=0.3))`
7. Print `response.content` to stdout
8. Handle errors: `LLMConfigurationError` → helpful message about API key, other `LLMError` → stderr message

## Modified Files

### 4. `markitect/cli.py` — Register the Command

At the bottom with the other `cli.add_command()` calls, add:

```python
try:
    from markitect.helper.cli import helper_command
    cli.add_command(helper_command)
except ImportError:
    pass  # Helper module not available
```

This follows the existing pattern used for prompts, finance, etc.

## Configuration

- **Default provider**: `openrouter`
- **Default model**: `openrouter/aurora-alpha`
- **Environment variable**: `MARKITECT_HELPER_MODEL` — overrides the default model
- **CLI flag**: `--model` / `-m` — overrides both env var and default
- **Precedence**: `--model` flag > `MARKITECT_HELPER_MODEL` env var > `openrouter/aurora-alpha`

## Key Reference Files

- `markitect/cli.py` — main CLI (Click-based, `@cli.command()` pattern, register via `cli.add_command()`)
- `markitect/llm/factory.py` — `create_adapter(provider, model, api_key, system_prompt)`
- `markitect/llm/openrouter.py` — OpenRouterAdapter (default)
- `markitect/prompts/execution/models.py` — `RunConfig`, `LLMResponse`
- `markitect/prompts/execution/llm_adapter.py` — `LLMAdapter` base class (method: `execute_prompt(prompt, config) -> LLMResponse`)
- `markitect/llm/exceptions.py` — `LLMError`, `LLMConfigurationError`, `LLMAPIError`, `LLMRateLimitError`
- API key resolution: env var `OPENROUTER_API_KEY` or file `apikey-openrouter.txt` in project root

## Verification

1. `markitect helper "What is markitect?"` — should return a knowledge-based answer
2. `markitect helper --model anthropic/claude-sonnet-4 "How do schemas work?"` — uses different model
3. `MARKITECT_HELPER_MODEL=google/gemini-2.5-flash markitect helper "What are templates?"` — env var override
4. `markitect helper --provider claude-code "Explain the plugin system"` — uses Claude CLI
5. `markitect helper --help` — shows usage with all options