markitect-main/roadmap/helper-command/PLAN.md

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

@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:

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