feat: rename config to aidocs-config.yml + add docs_root

BREAKING CHANGE: Config file renamed from docs/config.yml to docs/aidocs-config.yml

- Add docs_root config key to specify documentation output directory
- Add Step 0 config discovery to all workflows (generate, flow, batch, update, execute)
- Config is now REQUIRED - workflows will prompt for /docs:init if not found
- Add migration hint for old config.yml files
- Update all docs/ hardcoded paths to use {docs_root}

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: binaryk

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aidocs"
-version = "0.12.1"
+version = "0.13.0"
 description = "AI-powered documentation generator for web applications. Install docs commands into your Claude Code project."
 readme = "README.md"
 license = { text = "MIT" }

src/aidocs_cli/__init__.py

@@ -1,6 +1,6 @@
 """AI-powered documentation generator CLI for Claude Code projects."""
 
-__version__ = "0.12.1"
+__version__ = "0.13.0"
 
 from .cli import app
 

src/aidocs_cli/templates/workflows/batch/workflow.md

@@ -11,12 +11,56 @@ description: Generate documentation for multiple pages from a list of URLs or a
 
 ---
 
+## STEP 0: FIND AND LOAD CONFIGURATION
+
+**CRITICAL:** Before doing anything else, locate and load the configuration file.
+
+### 0.1 Search for Config File
+
+Search for `aidocs-config.yml` in this order:
+1. `docs/aidocs-config.yml` (default location)
+2. `./aidocs-config.yml` (project root)
+
+**Also check for old config format:**
+If `docs/config.yml` exists but `aidocs-config.yml` doesn't:
+```
+⚠️  Found old config format: docs/config.yml
+
+Please rename it to: docs/aidocs-config.yml
+Then run this command again.
+```
+
+### 0.2 If Config Found
+
+Load the config and extract:
+- `docs_root` → Base directory for all documentation (default: `docs`)
+- `urls.base` → Base URL for page navigation
+- `auth.method` → How to authenticate
+- `skip_pages` → Patterns to exclude from batch
+
+### 0.3 If Config NOT Found
+
+Display message and STOP:
+```
+⚠️  No aidocs-config.yml found.
+
+This workflow requires a configuration file to run.
+
+Would you like to create one now?
+1. Yes - run /docs:init to set up configuration
+2. No - I'll create docs/aidocs-config.yml manually
+```
+
+**IMPORTANT:** Do NOT proceed without config. Config is required.
+
+---
+
 ## ARGUMENTS PARSING
 
 Parse the arguments. Expected formats:
 ```
-/docs:batch <urls-file> [--auth user:pass] [--output ./docs]
-/docs:batch --discover [--base-url https://app.example.com] [--auth user:pass] [--output ./docs]
+/docs:batch <urls-file> [--auth user:pass] [--output ./{docs_root}]
+/docs:batch --discover [--base-url https://app.example.com] [--auth user:pass] [--output ./{docs_root}]
 ```
 
 **Option 1: URLs file**
@@ -77,8 +121,8 @@ Proceed with all? [Y/n] Or type numbers to select specific pages.
 
 **Load credentials using same logic as /docs:generate:**
 
-Check `auth.method` in `docs/config.yml`:
-1. **method: "file"** → Read from `docs/.auth`
+Check `auth.method` in config (loaded in Step 0):
+1. **method: "file"** → Read from `{docs_root}/.auth`
 2. **method: "env"** → Read from environment variables
 3. **method: "manual"** → Require `--auth` flag
 4. **--auth flag** always overrides stored credentials
@@ -138,7 +182,7 @@ After all pages processed, create summary:
    ⚠ {warning_count} pages with warnings
    ✗ {error_count} pages failed
 
-📁 Output directory: {output_path}
+📁 Output directory: {docs_root}/
 
 📄 Files created:
    - dashboard.md
@@ -156,7 +200,7 @@ After all pages processed, create summary:
 ```
 
 ### Index File:
-Create `{output}/index.md` with links to all generated docs:
+Create `{docs_root}/index.md` with links to all generated docs:
 
 ```markdown
 # Documentation Index

src/aidocs_cli/templates/workflows/execute/workflow.md

@@ -10,11 +10,54 @@ description: Execute the documentation plan and generate all docs with screensho
 **Your Role:** You are a documentation generator. You will systematically work through the plan, running explore and flow documentation for each module.
 
 **Requires:**
-- `docs/plan.yml` from `/docs:plan`
+- `{docs_root}/plan.yml` from `/docs:plan`
 - Playwright MCP for browser automation
 
 ---
 
+## STEP 0: FIND AND LOAD CONFIGURATION
+
+**CRITICAL:** Before doing anything else, locate and load the configuration file.
+
+### 0.1 Search for Config File
+
+Search for `aidocs-config.yml` in this order:
+1. `docs/aidocs-config.yml` (default location)
+2. `./aidocs-config.yml` (project root)
+
+**Also check for old config format:**
+If `docs/config.yml` exists but `aidocs-config.yml` doesn't:
+```
+⚠️  Found old config format: docs/config.yml
+
+Please rename it to: docs/aidocs-config.yml
+Then run this command again.
+```
+
+### 0.2 If Config Found
+
+Load the config and extract:
+- `docs_root` → Base directory for all documentation (default: `docs`)
+- `urls.base` → Base URL for screenshots
+- `auth.method` → How to authenticate
+
+### 0.3 If Config NOT Found
+
+Display message and STOP:
+```
+⚠️  No aidocs-config.yml found.
+
+This workflow requires a configuration file to run.
+
+Would you like to create one now?
+1. Yes - run /docs:init to set up configuration
+2. No - I'll create docs/aidocs-config.yml manually
+```
+
+**IMPORTANT:** Do NOT proceed without config. Config is required.
+
+---
+
 ## ARGUMENTS PARSING
 
 Parse the arguments:
@@ -39,7 +82,7 @@ Examples:
 ```
 📋 Loading documentation plan...
 
-✓ Plan found: docs/plan.yml
+✓ Plan found: {docs_root}/plan.yml
   Created: 2024-01-15 10:30:00
   Modules: 4
   Cross-module flows: 2
@@ -97,10 +140,10 @@ For each module in plan, verify knowledge exists:
 ```
 📁 Verifying knowledge base...
 
-✓ users         - docs/.knowledge/modules/users/
-✓ campaigns     - docs/.knowledge/modules/campaigns/
-✓ orders        - docs/.knowledge/modules/orders/
-✓ payments      - docs/.knowledge/modules/payments/
+✓ users         - {docs_root}/.knowledge/modules/users/
+✓ campaigns     - {docs_root}/.knowledge/modules/campaigns/
+✓ orders        - {docs_root}/.knowledge/modules/orders/
+✓ payments      - {docs_root}/.knowledge/modules/payments/
 
 All modules have discovery data.
 ```

src/aidocs_cli/templates/workflows/flow/workflow.md

@@ -20,16 +20,66 @@ description: Document a code flow with screenshots, diagrams, and user-friendly
 
 ---
 
-## LOAD CONFIGURATION
+## STEP 0: FIND AND LOAD CONFIGURATION
 
-**First, check if `docs/config.yml` exists in the project root.**
+**CRITICAL:** Before doing anything else, locate and load the configuration file.
 
-If it exists, load:
+### 0.1 Search for Config File
+
+Search for `aidocs-config.yml` in this order:
+1. `docs/aidocs-config.yml` (default location)
+2. `./aidocs-config.yml` (project root)
+
+**Also check for old config format:**
+If `docs/config.yml` exists but `aidocs-config.yml` doesn't:
+```
+⚠️  Found old config format: docs/config.yml
+
+Please rename it to: docs/aidocs-config.yml
+Then run this command again.
+```
+
+### 0.2 If Config Found
+
+Load the config and extract these values:
+- `docs_root` → Base directory for all documentation (default: `docs`)
 - `urls.base` → Base URL for screenshots (e.g., `https://app.example.com`)
 - `auth.method` → How to authenticate for screenshots
-- `output.directory` → Where to save documentation
 
-Store for later use in screenshot capture step.
+### 0.3 If Config NOT Found
+
+Display message and STOP:
+```
+⚠️  No aidocs-config.yml found.
+
+This workflow requires a configuration file to run.
+
+Would you like to create one now?
+1. Yes - run /docs:init to set up configuration
+2. No - I'll create docs/aidocs-config.yml manually
+```
+
+**If user chooses "Yes":** Execute the `/docs:init` workflow to walk through setup.
+**If user chooses "No":** Stop and provide this minimal config template:
+
+```yaml
+# Minimal aidocs-config.yml
+docs_root: docs
+urls:
+  base: "https://your-app.com"
+auth:
+  required: false
+```
+
+**IMPORTANT:** Do NOT proceed without config. Config is required.
+
+### 0.4 Resolve Paths
+
+Once config is loaded, set these path variables:
+- `{docs_root}` → Use for all output paths (from config, default: `docs`)
+- `{docs_root}/.auth` → Credentials file location
+- `{docs_root}/flows/` → Flow documentation folder
+- `{docs_root}/flows/images/` → Flow screenshots folder
 
 ---
 
@@ -367,30 +417,24 @@ Or run with --no-screenshots flag (not recommended).
 
 **Step 1: Check for credentials file**
 
-Read the `docs/.auth` file if it exists:
+Read the `{docs_root}/.auth` file if it exists:
 
 ```yaml
-# docs/.auth format:
+# {docs_root}/.auth format:
 username: "[email protected]"
 password: "secretpassword"
 login_url: "/login"  # optional, defaults to /login
 ```
 
 **Step 2: Check config for auth settings**
 
-Also check `docs/config.yml` for auth configuration:
-
-```yaml
-auth:
-  method: file  # or "env" or "manual"
-  login_url: "/login"
-urls:
-  base: "https://app.example.com"
-```
+The config was already loaded in Step 0. Use:
+- `auth.method` - How to authenticate (file, env, manual)
+- `urls.base` - Base URL for login page
 
 **Step 3: Perform login if credentials found**
 
-If `docs/.auth` exists and contains credentials:
+If `{docs_root}/.auth` exists and contains credentials:
 
 1. Navigate to login URL: `{base_url}/login` (or custom `login_url`)
 2. Wait for login form to load
@@ -402,7 +446,7 @@ If `docs/.auth` exists and contains credentials:
 
 ```
 🔐 Authenticating...
-   Reading credentials from docs/.auth
+   Reading credentials from {docs_root}/.auth
    Navigating to: https://app.example.com/login
    Filling login form...
    ✓ Logged in successfully
@@ -436,7 +480,7 @@ Capture relevant screenshots:
    Looking for: button containing "Import"
    Found: "Import Payments" button
 
-   Saved: docs/flows/images/import-payments-trigger.png
+   Saved: {docs_root}/flows/images/import-payments-trigger.png
 ```
 
 **Screenshot 2: Modal/Form (if applicable)**
@@ -445,7 +489,7 @@ Capture relevant screenshots:
    Clicking: "Import Payments" button
    Waiting for: modal or form
 
-   Saved: docs/flows/images/import-payments-form.png
+   Saved: {docs_root}/flows/images/import-payments-form.png
 ```
 
 ### 6.5 Screenshot Summary
@@ -459,7 +503,7 @@ Capture relevant screenshots:
   2. import-payments-form.png
      └── Import modal with file upload field
 
-Screenshots saved to: docs/flows/images/
+Screenshots saved to: {docs_root}/flows/images/
 ```
 
 ---
@@ -509,7 +553,7 @@ Create the markdown file with all gathered information.
 
 ### 8.1 Create Output Directory
 
-Ensure `docs/flows/` and `docs/flows/images/` directories exist.
+Ensure `{docs_root}/flows/` and `{docs_root}/flows/images/` directories exist.
 
 ### 8.2 Generate Filename
 
@@ -693,7 +737,7 @@ public function handle(CsvPaymentImporter $importer)
 
 ### 8.4 Save File
 
-Write to `docs/flows/{kebab-case-title}.md`
+Write to `{docs_root}/flows/{kebab-case-title}.md`
 
 ---
 
@@ -704,7 +748,7 @@ Display final summary:
 ```
 ✅ Flow Documentation Complete
 
-📄 Output: docs/flows/import-payments-from-csv.md
+📄 Output: {docs_root}/flows/import-payments-from-csv.md
 
 📊 Analysis Summary:
    Files analyzed: 6