improve: README usage/troubleshooting and CI pip cache (#38)

* docs: add AGENTS.md for agent discoverability

* fix: eliminate B008 noqa hacks with module-level defaults; handle None flattening

* improve: README usage/troubleshooting add pip cache to CI

Author: Coding-Dev-Tools

.github/workflows/ci.yml

@@ -25,9 +25,11 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: "pip"
 
       - name: Install dependencies
         run: |
+          pip config set global.retries 5 || true
           pip install -e ".[dev]"
 
       - name: Lint with ruff

README.md

@@ -92,6 +92,22 @@ Use `--output silent` for CI gating:
 configdrift check dev.yaml prod.yaml --output silent || echo "Drift detected!"
 ```
 
+### GitHub Actions example
+
+```yaml
+- name: Detect config drift
+  run: |
+    pip install configdrift
+    configdrift check ./config/staging/app.yaml ./config/prod/app.yaml --output silent
+```
+
+## Troubleshooting
+
+- **Exit code 1 with no output**: use `--output table` to inspect drift details.
+- **TOML parsing errors on Python < 3.11**: install `tomli` and `tomli-w` or use Python 3.11+.
+- **Large config scans are slow**: narrow the scan to changed files or a single directory.
+- **Unexpected breaking drift**: review severity rules in the project settings; `database*` and `auth*` keys are flagged as breaking by default.
+
 ## Supported Formats
 
 | Format  | Extension      | Notes                         |