zai-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{zai_cli-0.2.0 → zai_cli-0.2.2}/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project uses [Semantic Versioning](https://semver.org/).
 
+## [0.2.2] - 2026-07-13
+
+### Added
+
+- Added structured live-provider validation results with the resolved model,
+  token usage, failure detail, and a recommended next action.
+
+### Changed
+
+- Authentication login validation now distinguishes missing or invalid
+  credentials, quota limits, model configuration errors, network failures, and
+  unexpected provider failures.
+- `zai model test` now reports actionable recovery commands and shows the token
+  cost of a successful validation request when providers return usage data.
+
+## [0.2.1] - 2026-06-30
+
+### Added
+
+- Added `@file` completion in normal interactive prompts.
+- Added safe `@file` mention expansion so prompts like `explain @app.py`
+  include bounded referenced file content.
+
+### Changed
+
+- Mention expansion skips missing, hidden, oversized, binary, and
+  sensitive-looking files without crashing the prompt.
+
 ## [0.2.0] - 2026-06-30
 
 ### Added

{zai_cli-0.2.0/zai_cli.egg-info → zai_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zai-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: Your personal AI CLI — free, fast, and smart
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
@@ -198,6 +198,10 @@ zai auth login openai
 zai auth login anthropic
 ```
 
+When prompted, authentication login can send one tiny live request to validate
+the key. The result identifies the resolved model and gives a recovery command
+for invalid credentials, quota limits, model errors, or network failures.
+
 Remove a saved API key from `zai`:
 
 ```bash
@@ -426,7 +430,7 @@ zai model add <name>        Add a custom model alias
 zai model remove <name>     Remove a custom model alias
 zai model configure <name>  Set timeout and retry policy
 zai model info <name>       Show effective model configuration
-zai model test <name>       Verify credentials and model availability
+zai model test <name>       Verify credentials/model and show recovery guidance
 zai auth status             Show API-key and external CLI auth status
 zai auth login <provider>   Connect a provider API key
 zai auth logout <provider>  Remove a provider API key from zai
@@ -538,6 +542,18 @@ Interactive input also provides:
 - `Ctrl+C` to cancel the current input or operation without ending the session;
 - a basic Rich prompt fallback in redirected or unsupported terminals.
 
+You can reference files in natural prompts with `@file`:
+
+```text
+explain @app.py
+fix @src/main.py
+compare @README.md and @CHANGELOG.md
+```
+
+`zai` loads bounded text from valid referenced files and appends it to the
+prompt context. Hidden files, sensitive-looking paths, binary files, and very
+large files are skipped with a note instead of crashing the session.
+
 ## How much of my project does zai see?
 
 `zai` starts from the folder where you run it. It does not load every file in a

{zai_cli-0.2.0 → zai_cli-0.2.2}/README.md

@@ -141,6 +141,10 @@ zai auth login openai
 zai auth login anthropic
 ```
 
+When prompted, authentication login can send one tiny live request to validate
+the key. The result identifies the resolved model and gives a recovery command
+for invalid credentials, quota limits, model errors, or network failures.
+
 Remove a saved API key from `zai`:
 
 ```bash
@@ -369,7 +373,7 @@ zai model add <name>        Add a custom model alias
 zai model remove <name>     Remove a custom model alias
 zai model configure <name>  Set timeout and retry policy
 zai model info <name>       Show effective model configuration
-zai model test <name>       Verify credentials and model availability
+zai model test <name>       Verify credentials/model and show recovery guidance
 zai auth status             Show API-key and external CLI auth status
 zai auth login <provider>   Connect a provider API key
 zai auth logout <provider>  Remove a provider API key from zai
@@ -481,6 +485,18 @@ Interactive input also provides:
 - `Ctrl+C` to cancel the current input or operation without ending the session;
 - a basic Rich prompt fallback in redirected or unsupported terminals.
 
+You can reference files in natural prompts with `@file`:
+
+```text
+explain @app.py
+fix @src/main.py
+compare @README.md and @CHANGELOG.md
+```
+
+`zai` loads bounded text from valid referenced files and appends it to the
+prompt context. Hidden files, sensitive-looking paths, binary files, and very
+large files are skipped with a note instead of crashing the session.
+
 ## How much of my project does zai see?
 
 `zai` starts from the folder where you run it. It does not load every file in a

{zai_cli-0.2.0 → zai_cli-0.2.2}/tests/test_auth.py

@@ -14,6 +14,7 @@ from zai.core.auth import (
     mask_secret,
     save_provider_key,
     validate_provider,
+    validate_provider_details,
 )
 
 
@@ -66,18 +67,58 @@ def test_external_login_command_for_codex_and_claude():
 def test_validate_provider_normalizes_results():
     provider = MagicMock()
     provider.is_available.return_value = True
-    provider.chat.return_value = MagicMock()
+    provider.chat.return_value = MagicMock(model="provider/model", tokens_used=7)
     with patch("zai.core.auth.get_provider", return_value=provider):
         assert validate_provider("groq") == "OK"
+        details = validate_provider_details("groq")
+        assert details.status == "OK"
+        assert details.model == "provider/model"
+        assert details.tokens_used == 7
+        assert "zai model set groq" in details.next_action
 
     provider.chat.side_effect = RuntimeError("unauthorized api key")
     with patch("zai.core.auth.get_provider", return_value=provider):
         assert validate_provider("groq") == "invalid"
+        details = validate_provider_details("groq")
+        assert details.status == "invalid"
+        assert "zai auth login groq" in details.next_action
 
     provider.chat.side_effect = RuntimeError("rate limit")
     with patch("zai.core.auth.get_provider", return_value=provider):
         assert validate_provider("groq") == "quota/rate limit"
 
+    provider.chat.side_effect = RuntimeError("unknown model does not exist")
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        details = validate_provider_details("groq")
+        assert details.status == "model error"
+        assert "zai model info groq" in details.next_action
+
+    provider.chat.side_effect = RuntimeError("unexpected provider failure")
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        details = validate_provider_details("groq")
+        assert details.status == "provider error"
+        assert "zai auth doctor" in details.next_action
+
+    provider.chat.side_effect = RuntimeError("api_key=super-secret-provider-token")
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        details = validate_provider_details("groq")
+        assert "super-secret-provider-token" not in details.detail
+        assert "[REDACTED_SECRET]" in details.detail
+
+
+def test_validate_provider_reports_unknown_and_unavailable():
+    unknown = validate_provider_details("unknown")
+    assert unknown.status == "missing"
+    assert unknown.detail == "Unknown provider."
+
+    provider = MagicMock()
+    provider.is_available.return_value = False
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        unavailable = validate_provider_details("groq")
+
+    assert unavailable.status == "missing"
+    assert "zai auth login groq" in unavailable.next_action
+
 
 def test_top_level_auth_status_does_not_print_secret(monkeypatch):
     monkeypatch.setenv("OPENAI_API_KEY", "sk-live-secret")

zai_cli-0.2.2/tests/test_file_mentions.py

@@ -0,0 +1,30 @@
+from zai.core.file_mentions import expand_file_mentions, extract_file_mentions
+
+
+def test_extract_file_mentions_keeps_order_and_uniqueness():
+    text = "explain @app.py then compare @README.md and @app.py."
+
+    assert extract_file_mentions(text) == ["app.py", "README.md"]
+
+
+def test_expand_file_mentions_loads_bounded_file_context(tmp_path):
+    (tmp_path / "app.py").write_text("print('hi')\n", encoding="utf-8")
+
+    expanded = expand_file_mentions("explain @app.py", tmp_path)
+
+    assert "explain @app.py" in expanded
+    assert "Referenced @file context" in expanded
+    assert "--- @app.py ---" in expanded
+    assert "print('hi')" in expanded
+
+
+def test_expand_file_mentions_skips_hidden_and_sensitive_files(tmp_path):
+    (tmp_path / ".env").write_text("API_KEY=secret\n", encoding="utf-8")
+    (tmp_path / "token.txt").write_text("secret\n", encoding="utf-8")
+
+    expanded = expand_file_mentions("read @.env and @token.txt", tmp_path)
+
+    assert "API_KEY=secret" not in expanded
+    assert "Mention notes" in expanded
+    assert "Skipped @.env" in expanded
+    assert "Skipped @token.txt" in expanded

{zai_cli-0.2.0 → zai_cli-0.2.2}/tests/test_input.py

@@ -97,6 +97,22 @@ def test_path_completion(tmp_path):
     assert not any(".secret" in candidate[0] for candidate in candidates)
 
 
+def test_file_mention_completion_in_natural_prompt(tmp_path):
+    (tmp_path / "src").mkdir()
+    (tmp_path / "sample.py").write_text("")
+    (tmp_path / ".secret").write_text("")
+
+    candidates = completion_candidates(
+        "explain @s",
+        str(tmp_path),
+        {"fix"},
+    )
+
+    assert ("@src/", "@src/", "file mention") in candidates
+    assert ("@sample.py", "@sample.py", "file mention") in candidates
+    assert not any(".secret" in candidate[0] for candidate in candidates)
+
+
 def test_prompt_falls_back_when_prompt_toolkit_missing(tmp_path):
     real_import = __import__
 

{zai_cli-0.2.0 → zai_cli-0.2.2}/tests/test_interactive.py

@@ -305,6 +305,32 @@ def test_interactive_pins_project_rules_before_agent_call(tmp_path, monkeypatch)
     )
 
 
+def test_interactive_expands_file_mentions_before_agent_call(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "app.py").write_text("print('hello')\n")
+    with patch("zai.cli.interactive.has_available_provider", return_value=True):
+        with patch("zai.cli.interactive.fire_hook", return_value=True):
+            with patch("zai.cli.interactive.plugin_loader.load_all", return_value={}):
+                with patch("zai.cli.interactive.plugin_loader.get_errors", return_value={}):
+                    with patch("zai.cli.interactive._connect_mcp_servers"):
+                        with patch(
+                            "zai.cli.interactive.InteractiveInput.prompt",
+                            side_effect=["explain @app.py", EOFError()],
+                        ):
+                            with (
+                                patch(
+                                    "zai.cli.interactive.run_agent",
+                                    return_value="done",
+                                ) as run_agent,
+                                patch("zai.cli.interactive.Confirm.ask", return_value=False),
+                            ):
+                                run_interactive("groq")
+
+    prompt = run_agent.call_args.args[0]
+    assert "Referenced @file context" in prompt
+    assert "print('hello')" in prompt
+
+
 def test_interactive_manual_compact_summarizes_history(tmp_path, monkeypatch, capsys):
     monkeypatch.chdir(tmp_path)
     prompts = [

{zai_cli-0.2.0 → zai_cli-0.2.2}/tests/test_settings_cli.py

@@ -159,6 +159,7 @@ def test_context_command_is_honest_about_unloaded_files(tmp_path, monkeypatch):
 def test_rules_command_shows_loaded_project_rules(tmp_path, monkeypatch):
     app = settings_app()
     monkeypatch.chdir(tmp_path)
+    (tmp_path / ".git").mkdir()
     (tmp_path / ".zai").mkdir()
     (tmp_path / ".zai" / "rules.md").write_text("Never commit secrets.\n")
 
@@ -271,6 +272,25 @@ def test_model_test_passes_and_reports_unavailable():
     assert "Model unavailable" in unavailable.output
 
 
+def test_model_test_reports_actionable_auth_failure():
+    from zai.core.errors import AuthenticationError
+
+    app = settings_app()
+    runner = CliRunner()
+    provider = MagicMock()
+    provider.name = "groq"
+    provider.is_available.return_value = True
+    provider.chat.side_effect = AuthenticationError("groq", "bad key")
+
+    with patch("zai.core.fallback.get_provider", return_value=provider):
+        result = runner.invoke(app, ["model", "test", "groq"])
+
+    assert result.exit_code == 0
+    assert "invalid credentials" in result.output
+    assert "zai auth login groq" in result.output
+    assert "bad key" in result.output
+
+
 def test_model_configure_updates_builtin_runtime_settings():
     app = settings_app()
     config = {

zai_cli-0.2.2/zai/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

{zai_cli-0.2.0 → zai_cli-0.2.2}/zai/cli/interactive.py

@@ -15,13 +15,14 @@ from ..core.auth import (
     get_auth_provider,
     run_external_login,
     save_provider_key,
-    validate_provider,
+    validate_provider_details,
 )
 from ..core.agent import plan_agent, run_agent, undo_last
 from ..core.commands import get_command_prompt, list_commands, load_commands
 from ..core.compaction import manual_compact_messages
 from ..core.hooks import fire as fire_hook
 from ..core.fallback import has_available_provider
+from ..core.file_mentions import expand_file_mentions
 from ..core.context import ContextManager
 from ..core.memory import add_project, get_last_session, save_session
 from ..core.project_memory import (
@@ -282,14 +283,13 @@ def _run_auth_login(provider: str, *, device: bool = False) -> None:
                 f"Test {info.display_name} now? This sends one tiny request.",
                 default=False,
             ):
-                status = validate_provider(info.key)
-                style = "green" if status == "OK" else "yellow"
-                console.print(f"[{style}]Validation: {status}[/{style}]")
-                if status != "OK":
-                    console.print(
-                        f"[dim]Update it with `/auth login {info.key}` "
-                        f"or remove it with `/auth logout {info.key}`.[/dim]"
-                    )
+                validation = validate_provider_details(info.key)
+                style = "green" if validation.status == "OK" else "yellow"
+                console.print(f"[{style}]Validation: {validation.status}[/{style}]")
+                if validation.model:
+                    console.print(f"[dim]Model: {validation.model}[/dim]")
+                if validation.next_action:
+                    console.print(f"[dim]{validation.next_action.replace('zai ', '/')}[/dim]")
     command = external_login_command(info.key, device=device)
     if command:
         command_text = " ".join(command)
@@ -748,12 +748,13 @@ def run_interactive(model: str = None) -> None:
                     console.print("[red]Usage: /plan <what you want to build>[/red]")
                 else:
                     console.print("[dim]Planning...[/dim]")
-                    plan = plan_agent(task, history, cwd, preferred)
+                    expanded_task = expand_file_mentions(task, cwd)
+                    plan = plan_agent(expanded_task, history, cwd, preferred)
                     if plan and Prompt.ask("[cyan]Proceed?[/cyan]", default="no").lower() in ("yes", "y"):
                         console.print("[dim]Executing...[/dim]")
-                        result = run_agent(task, history, cwd, preferred)
+                        result = run_agent(expanded_task, history, cwd, preferred)
                         if result:
-                            remember_turn(task, result)
+                            remember_turn(expanded_task, result)
                             save_session(task=task[:80], model=preferred)
                             maybe_offer_project_memory(task)
             elif stripped == "/test":
@@ -955,9 +956,10 @@ def run_interactive(model: str = None) -> None:
                     console.print("[dim]Type /commands to see available commands[/dim]")
             else:
                 fire_hook("UserPromptSubmit", {"message": stripped[:200]})
-                result = run_agent(stripped, history, cwd, preferred)
+                expanded = expand_file_mentions(stripped, cwd)
+                result = run_agent(expanded, history, cwd, preferred)
                 if result:
-                    remember_turn(stripped, result)
+                    remember_turn(expanded, result)
                     save_session(task=stripped[:80], model=preferred)
                     maybe_offer_project_memory(stripped)
         except KeyboardInterrupt:

{zai_cli-0.2.0 → zai_cli-0.2.2}/zai/cli/settings.py

@@ -14,8 +14,17 @@ from ..core.auth import (
     get_auth_provider,
     save_provider_key,
     run_external_login,
-    validate_provider,
+    validate_provider_details,
 )
+from ..core.errors import (
+    AuthenticationError,
+    ModelNotFoundError,
+    NetworkError,
+    NoAPIKeyError,
+    QuotaError,
+    classify_provider_error,
+)
+from ..core.tokens import redact_secrets
 from ..config import (
     ENV_FILE,
     MEMORY_FILE,
@@ -171,14 +180,13 @@ def auth(
                     f"Test {info.display_name} now? This sends one tiny request.",
                     default=False,
                 ):
-                    status = validate_provider(info.key)
-                    style = "green" if status == "OK" else "yellow"
-                    console.print(f"[{style}]Validation: {status}[/{style}]")
-                    if status != "OK":
-                        console.print(
-                            f"[dim]Update it with `zai auth login {info.key}` "
-                            f"or remove it with `zai auth logout {info.key}`.[/dim]"
-                        )
+                    validation = validate_provider_details(info.key)
+                    style = "green" if validation.status == "OK" else "yellow"
+                    console.print(f"[{style}]Validation: {validation.status}[/{style}]")
+                    if validation.model:
+                        console.print(f"[dim]Model: {validation.model}[/dim]")
+                    if validation.next_action:
+                        console.print(f"[dim]{validation.next_action}[/dim]")
         command = external_login_command(info.key, device=device)
         if command:
             command_text = " ".join(command)
@@ -356,13 +364,44 @@ def model(
             response = selected.chat([
                 Message(role="user", content="Reply with exactly: ok")
             ])
-        except Exception as error:
+        except NoAPIKeyError as error:
             console.print(f"[red]Model test failed:[/red] {error}")
+            console.print(f"[dim]Add a key with: zai auth login {selected.name}[/dim]")
+            return
+        except AuthenticationError as error:
+            console.print(f"[red]Model test failed:[/red] invalid credentials for {selected.name}")
+            console.print(f"[dim]Update the key with: zai auth login {selected.name}[/dim]")
+            console.print(f"[dim]{redact_secrets(error.detail)}[/dim]")
+            return
+        except QuotaError as error:
+            console.print(f"[yellow]Model test hit quota or rate limit:[/yellow] {selected.name}")
+            console.print("[dim]Wait, check quota, or switch models with: zai model set <name>[/dim]")
+            console.print(f"[dim]{redact_secrets(error.detail)}[/dim]")
+            return
+        except ModelNotFoundError as error:
+            console.print(f"[red]Model test failed:[/red] model not found")
+            console.print(f"[dim]Configured model id: {selected.model_id}[/dim]")
+            console.print(f"[dim]Change it with: zai model configure {name} or zai model add <name>[/dim]")
+            console.print(f"[dim]{redact_secrets(error.detail)}[/dim]")
+            return
+        except NetworkError as error:
+            console.print(f"[red]Model test failed:[/red] network error")
+            console.print("[dim]Check internet connection, local service, or provider status.[/dim]")
+            console.print(f"[dim]{redact_secrets(str(error))}[/dim]")
+            return
+        except Exception as error:
+            normalized = classify_provider_error(selected.name, error)
+            console.print(
+                f"[red]Model test failed:[/red] {redact_secrets(str(normalized))}"
+            )
+            console.print("[dim]Run `zai auth doctor` for provider setup guidance.[/dim]")
             return
         console.print(
             f"[green]Model test passed:[/green] {name} "
             f"([cyan]{response.model}[/cyan])"
         )
+        if response.tokens_used:
+            console.print(f"[dim]Tiny validation request used {response.tokens_used} tokens.[/dim]")
     else:
         console.print(
             "[red]Usage: zai model list | zai model set <name> | "

{zai_cli-0.2.0 → zai_cli-0.2.2}/zai/core/auth.py

@@ -10,8 +10,18 @@ from typing import Iterable
 
 from ..config import ENV_FILE, get_api_key, save_api_key
 from ..providers.base import Message
+from .errors import (
+    AuthenticationError,
+    ModelNotFoundError,
+    NetworkError,
+    NoAPIKeyError,
+    ProviderTimeoutError,
+    QuotaError,
+    classify_provider_error,
+)
 from .fallback import get_provider
 from .storage import atomic_write_text, file_lock
+from .tokens import redact_secrets
 
 
 @dataclass(frozen=True)
@@ -28,6 +38,16 @@ class AuthProvider:
     notes: str = ""
 
 
+@dataclass(frozen=True)
+class ProviderValidation:
+    provider: str
+    status: str
+    model: str = ""
+    detail: str = ""
+    next_action: str = ""
+    tokens_used: int = 0
+
+
 PROVIDERS: dict[str, AuthProvider] = {
     "gemini": AuthProvider(
         key="gemini",
@@ -233,22 +253,78 @@ def run_external_login(provider: str, *, device: bool = False) -> subprocess.Com
     return subprocess.run(command, text=True)
 
 
-def validate_provider(provider: str) -> str:
+def _validation_next_action(provider: str, status: str) -> str:
+    if status == "OK":
+        return f"Use it with: zai model set {MODEL_BY_PROVIDER.get(provider, provider)}"
+    if status == "missing":
+        info = get_auth_provider(provider)
+        if info and info.key_env_var:
+            return f"Add a key with: zai auth login {info.key}"
+        if provider == "ollama":
+            return "Start Ollama locally, then run: zai model test ollama"
+        return "Check provider setup."
+    if status == "invalid":
+        return f"Update the key with: zai auth login {provider}"
+    if status == "quota/rate limit":
+        return "Wait, check provider quota, or switch models with: zai model set <name>"
+    if status == "network error":
+        return "Check internet connection, local service, or provider status."
+    if status == "model error":
+        alias = MODEL_BY_PROVIDER.get(provider, provider)
+        return f"Check the model id with: zai model info {alias}"
+    return "Run: zai auth doctor"
+
+
+def validate_provider_details(provider: str) -> ProviderValidation:
     alias = MODEL_BY_PROVIDER.get(provider)
     if not alias:
-        return "missing"
+        return ProviderValidation(
+            provider=provider,
+            status="missing",
+            detail="Unknown provider.",
+            next_action=_validation_next_action(provider, "missing"),
+        )
     selected = get_provider(alias)
     if selected is None or not selected.is_available():
-        return "missing"
+        return ProviderValidation(
+            provider=provider,
+            status="missing",
+            model=alias,
+            detail="Provider is not configured or local service is unavailable.",
+            next_action=_validation_next_action(provider, "missing"),
+        )
     try:
-        selected.chat([Message(role="user", content="Reply with exactly: ok")])
+        response = selected.chat([Message(role="user", content="Reply with exactly: ok")])
     except Exception as error:
-        message = str(error).lower()
-        if any(marker in message for marker in ("unauthorized", "auth", "api key", "401")):
-            return "invalid"
-        if any(marker in message for marker in ("quota", "rate limit", "429")):
-            return "quota/rate limit"
-        if any(marker in message for marker in ("timeout", "network", "connection")):
-            return "network error"
-        return "network error"
-    return "OK"
+        normalized = classify_provider_error(provider, error)
+        if isinstance(normalized, NoAPIKeyError):
+            status = "missing"
+        elif isinstance(normalized, AuthenticationError):
+            status = "invalid"
+        elif isinstance(normalized, QuotaError):
+            status = "quota/rate limit"
+        elif isinstance(normalized, ModelNotFoundError):
+            status = "model error"
+        elif isinstance(normalized, (NetworkError, ProviderTimeoutError)):
+            status = "network error"
+        else:
+            status = "provider error"
+        return ProviderValidation(
+            provider=provider,
+            status=status,
+            model=getattr(selected, "model_id", alias),
+            detail=redact_secrets(str(normalized)),
+            next_action=_validation_next_action(provider, status),
+        )
+    return ProviderValidation(
+        provider=provider,
+        status="OK",
+        model=response.model or getattr(selected, "model_id", alias),
+        detail="Tiny live request completed.",
+        next_action=_validation_next_action(provider, "OK"),
+        tokens_used=response.tokens_used,
+    )
+
+
+def validate_provider(provider: str) -> str:
+    return validate_provider_details(provider).status

zai_cli-0.2.2/zai/core/file_mentions.py

@@ -0,0 +1,99 @@
+"""Safe @file mention expansion for user prompts."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .security import resolve_project_path
+
+MENTION_RE = re.compile(r"(?<![\w/\\.-])@([^\s]+)")
+MAX_MENTION_FILE_BYTES = 48 * 1024
+MAX_MENTION_CONTENT_CHARS = 16 * 1024
+SENSITIVE_PARTS = {
+    ".env",
+    "secret",
+    "secrets",
+    "token",
+    "tokens",
+    "password",
+    "passwords",
+    "credential",
+    "credentials",
+    "private_key",
+}
+
+
+def extract_file_mentions(text: str) -> list[str]:
+    """Return unique @file mentions in first-seen order."""
+    result: list[str] = []
+    seen: set[str] = set()
+    for match in MENTION_RE.finditer(text):
+        value = match.group(1).rstrip(".,;:)]}")
+        if value and value not in seen:
+            seen.add(value)
+            result.append(value)
+    return result
+
+
+def _looks_sensitive(path_text: str) -> bool:
+    parts = [part.lower() for part in Path(path_text.replace("\\", "/")).parts]
+    return any(
+        part.startswith(".")
+        or part in SENSITIVE_PARTS
+        or any(marker in part for marker in SENSITIVE_PARTS if marker != ".env")
+        for part in parts
+    )
+
+
+def _read_mentioned_file(cwd: str | Path, mention: str) -> tuple[str | None, str | None]:
+    if _looks_sensitive(mention):
+        return None, f"Skipped @{mention}: hidden or sensitive-looking path."
+    try:
+        path = resolve_project_path(str(cwd), mention)
+    except Exception as error:
+        return None, f"Skipped @{mention}: {error}"
+    try:
+        if not path.is_file():
+            return None, f"Skipped @{mention}: not a file."
+        if path.stat().st_size > MAX_MENTION_FILE_BYTES:
+            return None, f"Skipped @{mention}: file is too large."
+        content = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return None, f"Skipped @{mention}: not a UTF-8 text file."
+    except OSError as error:
+        return None, f"Skipped @{mention}: {error}"
+    if len(content) > MAX_MENTION_CONTENT_CHARS:
+        content = content[:MAX_MENTION_CONTENT_CHARS] + "\n\n[... file mention truncated ...]"
+    relative = path.relative_to(Path(cwd).resolve()).as_posix()
+    return f"--- @{relative} ---\n{content}", None
+
+
+def expand_file_mentions(text: str, cwd: str | Path = ".") -> str:
+    """Append bounded referenced file content to a prompt."""
+    mentions = extract_file_mentions(text)
+    if not mentions:
+        return text
+
+    loaded: list[str] = []
+    notes: list[str] = []
+    for mention in mentions:
+        content, note = _read_mentioned_file(cwd, mention)
+        if content:
+            loaded.append(content)
+        if note:
+            notes.append(note)
+
+    if not loaded and not notes:
+        return text
+
+    sections = [
+        text,
+        "",
+        "Referenced @file context:",
+    ]
+    if loaded:
+        sections.extend(loaded)
+    if notes:
+        sections.append("Mention notes:")
+        sections.extend(f"- {note}" for note in notes)
+    return "\n".join(sections)

{zai_cli-0.2.0 → zai_cli-0.2.2}/zai/main.py

@@ -16,6 +16,7 @@ from .core.fallback import (
     stream_with_fallback,
 )
 from .core.context import ContextManager
+from .core.file_mentions import expand_file_mentions
 from .core.memory import save_session, get_last_session
 from .core.project_rules import load_project_rules, project_rules_prompt
 from .core.errors import show_error, AllModelsFailedError
@@ -145,7 +146,8 @@ def _chat(message: str, model: str = None) -> str:
             context.add("user", project_rules_prompt(rules), pinned=True)
         _RULES_LOADED_FOR = cwd
 
-    context.add("user", message)
+    expanded_message = expand_file_mentions(message, cwd)
+    context.add("user", expanded_message)
 
     if config.get("auto_compact", True) and context.is_near_limit(
         float(config.get("compact_trigger_threshold", 0.85))

{zai_cli-0.2.0 → zai_cli-0.2.2}/zai/ui/input.py

@@ -52,6 +52,13 @@ def completion_candidates(
 ) -> list[tuple[str, str, str]]:
     """Return (insert_text, display, metadata) completion candidates."""
     before = text.lstrip()
+    mention_fragment = _mention_fragment(before)
+    if mention_fragment is not None:
+        return [
+            (f"@{insert}", f"@{display}", "file mention")
+            for insert, display in _path_candidates(mention_fragment, cwd)
+        ]
+
     if not before.startswith("/"):
         return []
 
@@ -136,6 +143,13 @@ def completion_candidates(
     return []
 
 
+def _mention_fragment(text: str) -> str | None:
+    token = text.split()[-1] if text.split() else text
+    if token.startswith("@"):
+        return token[1:]
+    return None
+
+
 class InteractiveInput:
     """Reusable input session. Enter submits; Alt+Enter/Ctrl+J inserts newline."""
 

{zai_cli-0.2.0 → zai_cli-0.2.2/zai_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zai-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: Your personal AI CLI — free, fast, and smart
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
@@ -198,6 +198,10 @@ zai auth login openai
 zai auth login anthropic
 ```
 
+When prompted, authentication login can send one tiny live request to validate
+the key. The result identifies the resolved model and gives a recovery command
+for invalid credentials, quota limits, model errors, or network failures.
+
 Remove a saved API key from `zai`:
 
 ```bash
@@ -426,7 +430,7 @@ zai model add <name>        Add a custom model alias
 zai model remove <name>     Remove a custom model alias
 zai model configure <name>  Set timeout and retry policy
 zai model info <name>       Show effective model configuration
-zai model test <name>       Verify credentials and model availability
+zai model test <name>       Verify credentials/model and show recovery guidance
 zai auth status             Show API-key and external CLI auth status
 zai auth login <provider>   Connect a provider API key
 zai auth logout <provider>  Remove a provider API key from zai
@@ -538,6 +542,18 @@ Interactive input also provides:
 - `Ctrl+C` to cancel the current input or operation without ending the session;
 - a basic Rich prompt fallback in redirected or unsupported terminals.
 
+You can reference files in natural prompts with `@file`:
+
+```text
+explain @app.py
+fix @src/main.py
+compare @README.md and @CHANGELOG.md
+```
+
+`zai` loads bounded text from valid referenced files and appends it to the
+prompt context. Hidden files, sensitive-looking paths, binary files, and very
+large files are skipped with a note instead of crashing the session.
+
 ## How much of my project does zai see?
 
 `zai` starts from the folder where you run it. It does not load every file in a

{zai_cli-0.2.0 → zai_cli-0.2.2}/zai_cli.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ tests/test_code_runner.py
 tests/test_config_main.py
 tests/test_core.py
 tests/test_errors.py
+tests/test_file_mentions.py
 tests/test_hooks_skills_session.py
 tests/test_input.py
 tests/test_integrations_cli.py
@@ -62,6 +63,7 @@ zai/core/compaction.py
 zai/core/context.py
 zai/core/errors.py
 zai/core/fallback.py
+zai/core/file_mentions.py
 zai/core/hooks.py
 zai/core/memory.py
 zai/core/process.py

zai_cli-0.2.0/zai/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"