Usages:
  conventions: .goga/usages/conventions.md
  click: .goga/usages/cooks/click.md
  yaml: |
    Use yaml.dump() to generate .goga/config.yml.
    PyYAML library. Set default_flow_style=False for human-readable output.
  lang_conventions: |
    Download base language conventions from the qarium/goga-lang-conventions repository (branch 0.0.x).
    URL template: https://raw.githubusercontent.com/qarium/goga-lang-conventions/refs/heads/0.0.x/{language}/project.md
    The language identifier maps directly to the URL path segment (no mapping layer).
    Save the downloaded file to .goga/usages/conventions.md.
  image_defaults: |
    The default Docker image depends on the selected language.
    For languages with predefined images, display a list of suggestions; default to the last entry.
    Accept arbitrary user input for the image name.
    Language → available image mapping:
    - python: qarium/goga-python-{3.10-3.14}:latest
    - golang: qarium/goga-golang-{1.23, 1.24, 1.25, 1.26}:latest
    - javascript: qarium/goga-node-{22, 24}:latest
    - kotlin: qarium/goga-kotlin-{2.0, 2.1, 2.2, 2.3}:latest
    - swift: qarium/goga-swift-{6.0, 6.1, 6.2}:latest
  agent_env_defaults: |
    Map each agent to a list of environment variable keys for prompting.
    Display the keys to the user; collect corresponding values.
    Agent → env key mapping:
    - claude: ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_BASE_URL
    - codex: CODEX_MODEL

Annotations: |
  Practice `conventions` supports:
  - codebase navigation and development
  - REPL-based development workflow
  - debugging and testing
  - test infrastructure setup
  - understanding project-wide development and testing conventions
  Use `click` for interactive user input (Questionnaire).
  Use `yaml` for YAML file generation (FileGenerator).
  Use `lang_conventions` to download the base convention for the selected language (Questionnaire, FileGenerator).
  Use `image_defaults` to list available Docker images by language (Questionnaire).
  Use `agent_env_defaults` to suggest env keys for the selected agent (Questionnaire).
  All types must be immutable dataclasses (frozen=True, kw_only=True).

---

"InitAnswers(goga_config: GogaConfigAnswers)":
  location: answers.py
  annotations: |
    User response container. Extend with new properties for additional config files
    as needed.

    `goga_config`: responses for generating .goga/config.yml
  properties:
    "goga_config -> GogaConfigAnswers": |
      Responses for generating .goga/config.yml.

"GogaConfigAnswers(language: str, agent: str, image: str, env: dict | None, codemanifest_usages: dict | None, codemanifest_annotations: str | None, dockerfile_path: str | None)":
  location: answers.py
  annotations: |
    Input data for .goga/config.yml and Dockerfile generation.

    `language`: selected project language
    `agent`: selected AI executor
    `image`: build Docker image
    `env`: environment variables for task_executor
    `codemanifest_usages`: codemanifest practice mappings
    `codemanifest_annotations`: codemanifest annotation block
    `dockerfile_path`: path to custom Dockerfile (None to skip Dockerfile creation)
  properties:
    "language -> str": |
      Selected project language.
    "agent -> str": |
      Selected AI executor.
    "image -> str": |
      Build Docker image.
    "env -> dict | None": |
      Environment variables for task_executor.
    "codemanifest_usages -> dict | None": |
      Codemanifest practice mappings.
    "codemanifest_annotations -> str | None": |
      Codemanifest annotation block.
    "dockerfile_path -> str | None": |
      Path to custom Dockerfile. None — skip Dockerfile creation.

"Questionnaire()":
  location: questionnaire.py
  annotations: |
    Interactive user survey driven by `click`.

    Use `image_defaults` to list available Docker images for the chosen language.
    Use `lang_conventions` to offer downloading the base convention after language selection.
    Use `agent_env_defaults` to prompt for env keys after agent selection.
  methods:
    "ask() -> answers:InitAnswers": |
      Display the header "=== Goga Project Initialization ===" and wizard description.
      Delegate to ask_goga_config() and wrap the result in InitAnswers.
    "ask_goga_config() -> config:GogaConfigAnswers": |
      Survey for .goga/config.yml.
      Display "Collecting .goga/config.yml settings...".
      Each step includes a section header (---) and explanatory text.
      Survey steps:
      1. language — select from (python, golang, kotlin, swift, javascript).
      2. convention — offer to download the base convention via `lang_conventions`.
         On acceptance: add {"conventions": ".goga/usages/conventions.md"} to codemanifest_usages
         and set codemanifest_annotations.
      3. codemanifest_usages — optional; appended to pre-filled conventions.
      4. codemanifest_annotations — optional; appended to pre-filled values.
      5. agent — select from (claude, codex).
      6. image — display hints from `image_defaults`, default to the last entry; accept free-form input.
      7. dockerfile — optional; prompt to create a custom Dockerfile.
         On acceptance: request path (default "Dockerfile").
      8. env — first propose env keys from `agent_env_defaults` for the selected agent.
         Collect values for each proposed key.
         Then optionally collect arbitrary key-value pairs.

"FileGenerator()":
  location: generator.py
  annotations: |
    Project file generator. Use `yaml` for YAML serialization.
    Use `lang_conventions` to download the convention file when present in codemanifest_usages.
  methods:
    "generate(answers: InitAnswers) -> _:None": |
      Generate all project files from the provided answers.
      If dockerfile_path is set — create a Dockerfile with FROM {image}.
      Delegate to generate_goga_config() with answers.goga_config.
    "generate_goga_config(config: GogaConfigAnswers) -> _:None": |
      If codemanifest_usages contains the key "conventions" — download the convention file
      from the URL defined by `lang_conventions` (based on language) and save it to .goga/usages/conventions.md.
      On download failure, raise RuntimeError with the URL and cause; halt execution.
      Generate .goga/config.yml from GogaConfigAnswers.
      Create the .goga/ directory if it does not exist.
      Serialize YAML via yaml.dump() with default_flow_style=False, sort_keys=False to preserve field order.
      Serialize codemanifest_annotations as a literal block scalar (|) per the `yaml` practice.

      GogaConfigAnswers → YAML field mapping:
      - language → language
      - image → build.image
      - agent → build.task_executor.agent
      - env → build.task_executor.env (omit if None or empty)
      - codemanifest_usages → codemanifest.usages (omit if None or empty)
      - codemanifest_annotations → codemanifest.annotations (omit if None)

"InitLogic(questionnaire: Questionnaire, generator: FileGenerator)":
  location: logic.py
  annotations: |
    Orchestrator for the init command business logic.

    `questionnaire`: user survey provider
    `generator`: file generation provider
  methods:
    "run() -> exit_code:int": |
      Run the questionnaire via questionnaire.ask().
      Generate files via generator.generate().
      Return 0 on success, 1 on error.

---

Author: Goga
CreatedAt: 03/06/26
Description: |
  Interactive goga project initialization — user survey and configuration file generation
