Use root env example for fcc init

cli/entrypoints.py

@@ -2,6 +2,23 @@
 
 from __future__ import annotations
 
+from pathlib import Path
+
+
+def _load_env_template() -> str:
+    """Load the canonical root env template from package resources or source."""
+    import importlib.resources
+
+    packaged = importlib.resources.files("cli").joinpath("env.example")
+    if packaged.is_file():
+        return packaged.read_text("utf-8")
+
+    source_template = Path(__file__).resolve().parents[1] / ".env.example"
+    if source_template.is_file():
+        return source_template.read_text(encoding="utf-8")
+
+    raise FileNotFoundError("Could not find bundled or source .env.example template.")
+
 
 def serve() -> None:
     """Start the FastAPI server (registered as `free-claude-code` script)."""
@@ -25,9 +42,6 @@ def serve() -> None:
 
 def init() -> None:
     """Scaffold config at ~/.config/free-claude-code/.env (registered as `fcc-init`)."""
-    import importlib.resources
-    from pathlib import Path
-
     config_dir = Path.home() / ".config" / "free-claude-code"
     env_file = config_dir / ".env"
 
@@ -37,9 +51,7 @@ def init() -> None:
         return
 
     config_dir.mkdir(parents=True, exist_ok=True)
-    template = (
-        importlib.resources.files("config").joinpath("env.example").read_text("utf-8")
-    )
+    template = _load_env_template()
     env_file.write_text(template, encoding="utf-8")
     print(f"Config created at {env_file}")
     print(

config/env.example

@@ -1,99 +0,0 @@
-# NVIDIA NIM Config
-NVIDIA_NIM_API_KEY=""
-
-
-# OpenRouter Config
-OPENROUTER_API_KEY=""
-
-
-# DeepSeek Config
-DEEPSEEK_API_KEY=""
-
-
-# LM Studio Config (local provider, no API key required)
-LM_STUDIO_BASE_URL="http://localhost:1234/v1"
-
-
-# Llama.cpp Config (local provider, no API key required)
-LLAMACPP_BASE_URL="http://localhost:8080/v1"
-
-
-# All Claude model requests are mapped to these models, plain model is fallback
-# Format: provider_type/model/name
-# Valid providers: "nvidia_nim" | "open_router" | "deepseek" | "lmstudio" | "llamacpp"
-MODEL_OPUS=
-MODEL_SONNET=
-MODEL_HAIKU=
-MODEL="nvidia_nim/z-ai/glm4.7"
-
-
-# Thinking output
-# Per-Claude-model switches for provider reasoning requests and Claude thinking blocks.
-# Blank per-model switches inherit ENABLE_MODEL_THINKING.
-ENABLE_OPUS_THINKING=
-ENABLE_SONNET_THINKING=
-ENABLE_HAIKU_THINKING=
-ENABLE_MODEL_THINKING=true
-
-
-# Provider config
-# Per-provider proxy support: http and socks5, example: "http://username:password@host:port"
-NVIDIA_NIM_PROXY=""
-OPENROUTER_PROXY=""
-LMSTUDIO_PROXY=""
-LLAMACPP_PROXY=""
-
-PROVIDER_RATE_LIMIT=40
-PROVIDER_RATE_WINDOW=60
-PROVIDER_MAX_CONCURRENCY=5
-
-
-# HTTP client timeouts (seconds) for provider API requests
-HTTP_READ_TIMEOUT=120
-HTTP_WRITE_TIMEOUT=10
-HTTP_CONNECT_TIMEOUT=2
-
-
-# Optional server API key (Anthropic-style)
-ANTHROPIC_AUTH_TOKEN=
-
-
-# Messaging Platform: "telegram" | "discord" | "none"
-MESSAGING_PLATFORM="discord"
-MESSAGING_RATE_LIMIT=1
-MESSAGING_RATE_WINDOW=1
-
-
-# Voice Note Transcription
-VOICE_NOTE_ENABLED=false
-# WHISPER_DEVICE: "cpu" | "cuda" | "nvidia_nim"
-# - "cpu"/"cuda": Hugging Face transformers Whisper (offline, free; install with: uv sync --extra voice_local)
-# - "nvidia_nim": NVIDIA NIM Whisper via Riva gRPC (requires NVIDIA_NIM_API_KEY; install with: uv sync --extra voice)
-WHISPER_DEVICE="nvidia_nim"
-# WHISPER_MODEL:
-# - For cpu/cuda: Hugging Face ID or short name (tiny, base, small, medium, large-v2, large-v3, large-v3-turbo)
-# - For nvidia_nim: NVIDIA NIM model (e.g., "nvidia/parakeet-ctc-1.1b-asr", "openai/whisper-large-v3")
-# - For nvidia_nim, default to "openai/whisper-large-v3" for best performance
-WHISPER_MODEL="openai/whisper-large-v3"
-HF_TOKEN=""
-
-
-# Telegram Config
-TELEGRAM_BOT_TOKEN=""
-ALLOWED_TELEGRAM_USER_ID=""
-
-
-# Discord Config
-DISCORD_BOT_TOKEN=""
-ALLOWED_DISCORD_CHANNELS=""
-
-
-# Agent Config
-CLAUDE_WORKSPACE="./agent_workspace"
-ALLOWED_DIR=""
-CLAUDE_CLI_BIN="claude"
-FAST_PREFIX_DETECTION=true
-ENABLE_NETWORK_PROBE_MOCK=true
-ENABLE_TITLE_GENERATION_SKIP=true
-ENABLE_SUGGESTION_MODE_SKIP=true
-ENABLE_FILEPATH_EXTRACTION_MOCK=true

pyproject.toml

@@ -44,6 +44,9 @@ voice_local = [
 [tool.hatch.build.targets.wheel]
 packages = ["api", "cli", "config", "core", "messaging", "providers"]
 
+[tool.hatch.build.targets.wheel.force-include]
+".env.example" = "cli/env.example"
+
 [tool.uv.sources]
 torch = { index = "pytorch-cu130" }
 

tests/cli/test_entrypoints.py

@@ -33,17 +33,26 @@ def test_init_creates_env_file(tmp_path: Path) -> None:
 
 
 def test_init_copies_template_content(tmp_path: Path) -> None:
-    """init() writes the actual bundled env.example content, not an empty file."""
-    import importlib.resources
-
-    template = (
-        importlib.resources.files("config").joinpath("env.example").read_text("utf-8")
+    """init() writes the canonical root env.example content, not an empty file."""
+    template = (Path(__file__).resolve().parents[2] / ".env.example").read_text(
+        encoding="utf-8"
     )
     _, env_file = _run_init(tmp_path)
 
     assert env_file.read_text("utf-8") == template
 
 
+def test_env_template_loader_uses_root_template_in_source_checkout() -> None:
+    """Source checkout fallback uses the root .env.example as the single source."""
+    from cli.entrypoints import _load_env_template
+
+    template = (Path(__file__).resolve().parents[2] / ".env.example").read_text(
+        encoding="utf-8"
+    )
+
+    assert _load_env_template() == template
+
+
 def test_init_creates_parent_directories(tmp_path: Path) -> None:
     """init() creates ~/.config/free-claude-code/ even if it doesn't exist."""
     config_dir = tmp_path / ".config" / "free-claude-code"

tests/contracts/test_architecture_contracts.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import re
+import tomllib
 from pathlib import Path
 
 
@@ -14,12 +15,24 @@ def test_architecture_plan_exists() -> None:
     assert "Smoke Coverage Policy" in text
 
 
-def test_env_examples_are_in_sync() -> None:
+def test_root_env_example_is_the_single_template_source() -> None:
     repo_root = Path(__file__).resolve().parents[2]
     root_example = repo_root / ".env.example"
-    packaged_example = repo_root / "config" / "env.example"
+    duplicate_example = repo_root / "config" / "env.example"
 
-    assert _env_keys(root_example) == _env_keys(packaged_example)
+    assert root_example.is_file()
+    assert not duplicate_example.exists()
+
+
+def test_root_env_example_is_packaged_for_fcc_init() -> None:
+    repo_root = Path(__file__).resolve().parents[2]
+    pyproject = tomllib.loads((repo_root / "pyproject.toml").read_text("utf-8"))
+
+    force_include = pyproject["tool"]["hatch"]["build"]["targets"]["wheel"][
+        "force-include"
+    ]
+
+    assert force_include[".env.example"] == "cli/env.example"
 
 
 def test_pyproject_first_party_packages_match_packaged_roots() -> None:
@@ -35,14 +48,3 @@ def test_pyproject_first_party_packages_match_packaged_roots() -> None:
     }
     expected = {"api", "cli", "config", "core", "messaging", "providers", "smoke"}
     assert configured == expected
-
-
-def _env_keys(path: Path) -> set[str]:
-    keys: set[str] = set()
-    for line in path.read_text(encoding="utf-8").splitlines():
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#") or "=" not in stripped:
-            continue
-        key, _, _value = stripped.partition("=")
-        keys.add(key.strip())
-    return keys