docs: fix --output flag description to match actual behavior

- --output accepts full file path, format auto-detected from extension
- --output-dir for directory-only (uses default filename)
- Copilot's assumption was incorrect for this implementation

Signed-off-by: spencercjh <spencercjh@gmail.com>

Author: spencercjh

README.zh_CN.md

@@ -159,7 +159,7 @@ LLM **从不** 虚构类型或改变结构 —— 它只为我们已经验证存
 
 ## 配置
 
-在项目根目录创建 `.spec-forge.yaml`：
+在当前工作目录创建 `.spec-forge.yaml`：
 
 ```yaml
 enrich:
@@ -173,10 +173,12 @@ output:
   format: yaml
 ```
 
-**注意：** AI 增强需要通过环境变量提供 API 密钥：
-- OpenAI: `OPENAI_API_KEY`
-- Anthropic: `ANTHROPIC_API_KEY`
-- 自定义提供商: `LLM_API_KEY`（或在 `apiKeyEnv` 中配置的变量）
+**注意：**
+- AI 增强需要通过环境变量提供 API 密钥：
+  - OpenAI: `OPENAI_API_KEY`
+  - Anthropic: `ANTHROPIC_API_KEY`
+  - 自定义提供商: `LLM_API_KEY`
+- 配置文件只在当前工作目录读取，不会自动读取项目目录。如果在其他目录运行 `spec-forge generate ./path/to/project`，请确保配置文件在当前目录。
 
 查看 [.spec-forge.example.yaml](.spec-forge.example.yaml) 了解所有选项。
 

docs/ai-enrichment.md

@@ -264,11 +264,10 @@ Use `--no-stream` for concurrent processing:
 spec-forge enrich ./openapi.json --no-stream
 ```
 
-Or increase concurrency:
+Or increase concurrency (CLI flag only):
 
-```yaml
-enrich:
-  concurrency: 10
+```bash
+spec-forge enrich ./openapi.json --no-stream --concurrency 10
 ```
 
 ### Poor quality descriptions
@@ -279,7 +278,7 @@ enrich:
 
 ### Rate limiting
 
-- Reduce concurrency: `enrich.concurrency: 3`
+- Reduce concurrency: use `--concurrency 3` flag
 - Add delays between batches (not directly supported, use smaller specs)
 - Consider upgrading your API plan
 

docs/configuration.md

@@ -4,10 +4,9 @@ Complete reference for `.spec-forge.yaml` configuration.
 
 ## Configuration File Location
 
-Spec Forge looks for `.spec-forge.yaml` in:
+Spec Forge looks for `.spec-forge.yaml` in the current working directory only.
 
-1. Current working directory
-2. Project directory (when using `spec-forge generate ./project`)
+**Note:** If you run `spec-forge generate ./path/to/project`, the config file must be in your current directory, not in `./path/to/project`. Use `--config /path/to/.spec-forge.yaml` to specify a custom location.
 
 ## Configuration Priority
 
@@ -126,14 +125,15 @@ CLI equivalent: `--custom-base-url`
 
 ### `enrich.apiKeyEnv`
 
-Environment variable containing the API key.
+Environment variable containing the API key. **Only used for `custom` provider.**
 
 ```yaml
 enrich:
-  apiKeyEnv: LLM_API_KEY
+  provider: custom
+  apiKeyEnv: MY_API_KEY
 ```
 
-Default: `LLM_API_KEY` for custom, `OPENAI_API_KEY` for OpenAI, etc.
+**Note:** For OpenAI and Anthropic providers, API keys are always read from `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` respectively. The `apiKeyEnv` setting only applies to custom providers.
 
 ### `enrich.language`
 
@@ -174,7 +174,7 @@ output:
 
 Default: Current directory
 
-CLI equivalent: `--output` (accepts file or directory)
+CLI equivalent: `--output-dir` for directory, `--output` for full file path
 
 ### `output.format`
 
@@ -309,21 +309,23 @@ enrich:
   enabled: true
   provider: openai
   model: gpt-4o
-  apiKeyEnv: OPENAI_API_KEY
   language: en
 ```
 
+**Note:** Requires `OPENAI_API_KEY` environment variable.
+
 ### Anthropic
 
 ```yaml
 enrich:
   enabled: true
   provider: anthropic
   model: claude-3-sonnet-20240229
-  apiKeyEnv: ANTHROPIC_API_KEY
   language: en
 ```
 
+**Note:** Requires `ANTHROPIC_API_KEY` environment variable.
+
 ### Ollama (Local)
 
 ```yaml

docs/publishing.md

@@ -18,14 +18,15 @@ Guide to publishing OpenAPI specs to documentation platforms.
 The default output is a local file.
 
 ```bash
-# Default output: ./openapi.yaml
+# Default output
 spec-forge generate ./project
 
-# Custom output path
+# Custom output path (format auto-detected from extension)
 spec-forge generate ./project --output ./docs/api.yaml
-
-# JSON format
 spec-forge generate ./project --output ./api.json
+
+# Custom output directory (uses default filename)
+spec-forge generate ./project --output-dir ./docs
 ```
 
 ---
@@ -181,9 +182,11 @@ enrich:
 ✅ Good:
 
 ```yaml
-# .spec-forge.yaml
+# .spec-forge.yaml - No API keys here!
 enrich:
-  apiKeyEnv: OPENAI_API_KEY
+  enabled: true
+  provider: openai
+  model: gpt-4o
 ```
 
 ```bash
@@ -193,16 +196,26 @@ spec-forge generate ./
 
 ### Use Environment Variables
 
-All sensitive values support `*Env` variants:
+Keep API keys in environment variables, never in config files:
 
 ```yaml
+# .spec-forge.yaml - Safe: no API keys
 enrich:
-  apiKeyEnv: OPENAI_API_KEY      # Instead of apiKey
+  enabled: true
+  provider: openai
+  model: gpt-4o
+```
 
-readme:
-  # No slug here, pass via CLI or keep in CI secrets
+```bash
+# Set environment variable
+export OPENAI_API_KEY="sk-xxx"
+
+# Run spec-forge
+spec-forge generate ./
 ```
 
+**Note:** For OpenAI and Anthropic, API keys are always read from `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` respectively. For custom providers, use `LLM_API_KEY` or set `apiKeyEnv` in config.
+
 ### CI/CD Secrets
 
 Store in your CI system's secret management:

docs/quick-start.md

@@ -109,7 +109,7 @@ Requirements:
 
 ## Configuration
 
-Create `.spec-forge.yaml` in your project root:
+Create `.spec-forge.yaml` in your **current working directory**:
 
 ```yaml
 # AI Enrichment
@@ -127,6 +127,8 @@ output:
   format: yaml              # yaml or json
 ```
 
+**Important:** Spec Forge reads `.spec-forge.yaml` from the current working directory, not the project directory. If you run `spec-forge generate ./path/to/project`, ensure the config file is in your current directory, not `./path/to/project`.
+
 **Priority:** CLI flags > Environment variables > Config file > Defaults
 
 ---
@@ -145,8 +147,12 @@ spec-forge generate ./project --language zh
 # Disable enrichment
 spec-forge generate ./project --language zh --skip-enrich
 
-# Custom output
+# Custom output path (format auto-detected from extension)
 spec-forge generate ./project --output ./specs/api.yaml
+spec-forge generate ./project --output ./specs/api.json
+
+# Custom output directory (uses default filename)
+spec-forge generate ./project --output-dir ./specs
 
 # Verbose logging
 spec-forge generate ./project -v