대표 함수 편의성 강화 — OAuth URL 출력 + ask traceback 제거 + 에러 안내 개선

- setup('chatgpt') OAuth: 브라우저 열기 전 URL 항상 콘솔 출력, 타임아웃 시 URL 재출력
- ask(): raise 대신 print + return None (노트북 traceback 제거)
- Company(): 에러 메시지에 예시/검색/목록 안내 추가
- scan 4종: 빈 결과 시 downloadAll 안내 출력
- no_provider_message: "설정 후 다시 실행하세요" flow 개선

Author: eddmpython

src/dartlab/__init__.py

@@ -181,7 +181,11 @@ def governance():
     """
     from dartlab.market.governance import scan_governance
 
-    return scan_governance()
+    result = scan_governance()
+    if result is not None and hasattr(result, "is_empty") and result.is_empty():
+        print("\n  거버넌스 스캔 결과가 없습니다.")
+        print("  전체 시장 데이터가 필요합니다: dartlab.downloadAll('report')\n")
+    return result
 
 
 def workforce():
@@ -194,7 +198,11 @@ def workforce():
     """
     from dartlab.market.workforce import scan_workforce
 
-    return scan_workforce()
+    result = scan_workforce()
+    if result is not None and hasattr(result, "is_empty") and result.is_empty():
+        print("\n  인력 스캔 결과가 없습니다.")
+        print("  전체 시장 데이터가 필요합니다: dartlab.downloadAll('report')\n")
+    return result
 
 
 def capital():
@@ -207,7 +215,11 @@ def capital():
     """
     from dartlab.market.capital import scan_capital
 
-    return scan_capital()
+    result = scan_capital()
+    if result is not None and hasattr(result, "is_empty") and result.is_empty():
+        print("\n  주주환원 스캔 결과가 없습니다.")
+        print("  전체 시장 데이터가 필요합니다: dartlab.downloadAll('report')\n")
+    return result
 
 
 def debt():
@@ -220,7 +232,11 @@ def debt():
     """
     from dartlab.market.debt import scan_debt
 
-    return scan_debt()
+    result = scan_debt()
+    if result is not None and hasattr(result, "is_empty") and result.is_empty():
+        print("\n  부채 스캔 결과가 없습니다.")
+        print("  전체 시장 데이터가 필요합니다: dartlab.downloadAll('report')\n")
+    return result
 
 
 def screen(preset: str = "가치주"):
@@ -493,7 +509,7 @@ def ask(
         reflect: True면 답변 자체 검증 (1회 reflection).
 
     Returns:
-        str: 전체 답변 텍스트. (raw=True일 때만 Generator[str])
+        str | None: 전체 답변 텍스트. 설정 오류 시 None. (raw=True일 때만 Generator[str])
 
     Example::
 
@@ -526,9 +542,8 @@ def ask(
         if detected is None:
             from dartlab.core.ai.guide import no_provider_message
 
-            msg = no_provider_message()
-            print(msg)
-            raise RuntimeError("AI provider가 설정되지 않았습니다. dartlab.setup()을 실행하세요.")
+            print(no_provider_message())
+            return None
         provider = detected
 
     if len(args) == 2:
@@ -539,15 +554,21 @@ def ask(
 
         company, question = resolve_from_text(args[0])
         if company is None:
-            raise ValueError(
-                f"종목을 찾을 수 없습니다: '{args[0]}'\n"
-                "종목명 또는 종목코드를 포함해 주세요.\n"
-                "예: dartlab.ask('삼성전자 재무건전성 분석해줘')"
-            )
+            print(f"\n  종목을 찾을 수 없습니다: '{args[0]}'")
+            print("  종목명 또는 종목코드를 포함해 주세요.")
+            print("  예: dartlab.ask('삼성전자 재무건전성 분석해줘')")
+            print(f"  검색: dartlab.search('{args[0]}')\n")
+            return None
     elif len(args) == 0:
-        raise TypeError("질문을 입력해 주세요. 예: dartlab.ask('삼성전자 분석해줘')")
+        print("\n  질문을 입력해 주세요.")
+        print("  예: dartlab.ask('삼성전자 재무건전성 분석해줘')")
+        print("  예: dartlab.ask('005930', '영업이익률 추세는?')\n")
+        return None
     else:
-        raise TypeError(f"인자는 1~2개만 허용됩니다 (받은 수: {len(args)})")
+        print(f"\n  인자는 1~2개만 허용됩니다 (받은 수: {len(args)})")
+        print("  예: dartlab.ask('삼성전자 분석해줘')")
+        print("  예: dartlab.ask('005930', '영업이익률 추세는?')\n")
+        return None
 
     if raw:
         return _ask(

src/dartlab/cli/commands/setup.py

@@ -212,7 +212,12 @@ def serve():
 
     print("  브라우저에서 ChatGPT 로그인 페이지를 엽니다...")
     print("  (120초 안에 로그인을 완료하세요)\n")
-    webbrowser.open(auth_url)
+    print("  브라우저가 자동으로 열리지 않으면 아래 URL을 직접 여세요:")
+    print(f"  {auth_url}\n")
+    try:
+        webbrowser.open(auth_url)
+    except Exception:
+        pass
 
     # 완료 대기
     for _ in range(120):
@@ -233,7 +238,9 @@ def serve():
         print('     dartlab ask 005930 "재무 건전성 분석"\n')
     else:
         print("\n  ✗ 시간 초과 — 120초 안에 로그인하지 못했습니다.\n")
-        print("  다시 시도: dartlab setup oauth-codex\n")
+        print("  아래 URL을 브라우저에 직접 붙여넣어 보세요:")
+        print(f"  {auth_url}\n")
+        print("  또는 다시 시도: dartlab.setup('chatgpt')\n")
 
 
 def _setup_codex(info: dict) -> None:

src/dartlab/company.py

@@ -43,7 +43,11 @@ def Company(codeOrName: str) -> CompanyProtocol:
 
     normalized = codeOrName.strip()
     if not normalized:
-        raise ValueError("종목코드 또는 회사명을 입력해 주세요.")
+        raise ValueError(
+            "종목코드 또는 회사명을 입력해 주세요.\n"
+            "  예: Company('삼성전자') 또는 Company('005930')\n"
+            "  검색: dartlab.search('삼성')"
+        )
 
     # canHandle 체인: priority 순으로 시도
     firstError: Exception | None = None
@@ -70,4 +74,8 @@ def Company(codeOrName: str) -> CompanyProtocol:
             continue
 
     cause = f" (원인: {firstError})" if firstError else ""
-    raise ValueError(f"'{codeOrName}'을(를) 찾을 수 없습니다{cause}. dartlab.search('{codeOrName}')로 검색해 보세요.")
+    raise ValueError(
+        f"'{codeOrName}'을(를) 찾을 수 없습니다{cause}.\n"
+        f"  검색: dartlab.search('{codeOrName}')\n"
+        "  전체 목록: dartlab.listing()"
+    )

src/dartlab/core/ai/guide.py

@@ -163,7 +163,8 @@ def no_provider_message() -> str:
         '  6. OpenAI API      — dartlab.setup("openai")',
         '  7. 로컬 LLM        — dartlab.setup("ollama")',
         "",
-        '  설정 후: dartlab.ask("삼성전자 재무건전성 분석해줘")',
+        "  설정 후 다시 실행하세요:",
+        '     dartlab.ask("삼성전자 재무건전성 분석해줘")',
         "",
     ]
     return "\n".join(lines)