brainfish-ai/reasondb/blame-doc

Documentation Blame Report
==========================
 
Generated: [date]
Files analyzed: X docs, Y source files
 
## 🔴 Critical Issues
 
### Duplicate Content (count)
 
Content that appears in multiple places, causing maintenance burden:
 
| Topic | Files | Recommendation |
|-------|-------|----------------|
| Authentication setup | auth.mdx, quickstart.mdx, api/overview.mdx | Consolidate to auth.mdx, link from others |
| Error handling | errors.mdx, troubleshooting.mdx | Merge into single page |
 
**Details:**
- `auth.mdx:15-45` and `quickstart.mdx:80-110` contain nearly identical OAuth setup instructions
- `errors.mdx` and `troubleshooting.mdx` both list the same error codes
 
### Outdated Documentation (count)
 
Docs that don't match current codebase:
 
| File | Issue | Current State |
|------|-------|---------------|
| api/users.mdx | Wrong signature | `getUser(id)` is now `getUser(id, options)` |
| config.mdx | Missing options | `timeout` and `retries` not documented |
| quickstart.mdx | Old version | References v1.x, current is v2.x |
 
**Details:**
- `api/users.mdx:23` shows `getUser(id: string)` but code has `getUser(id: string, options?: UserOptions)`
- `config.mdx` missing 3 new configuration options added in v2.0
 
### Code-Doc Discrepancies (count)
 
Mismatches between documented and actual behavior:
 
| File | Documented | Actual |
|------|------------|--------|
| api/auth.mdx | Returns `{ token }` | Returns `{ token, expiresAt }` |
| guides/setup.mdx | Requires Node 14+ | package.json requires Node 18+ |
| api/errors.mdx | Error code 401 | Code throws 403 for this case |
 
## 🟡 Warnings
 
### Undocumented Features (count)
 
Code exists but no documentation:
 
- `src/utils/retry.ts` - Retry utility with backoff (exported, no docs)
- `src/api/webhooks.ts` - Webhook handlers (3 endpoints, no docs)
- `src/config/advanced.ts` - Advanced options (12 options, not in config.mdx)
 
### Stale Examples (count)
 
Code examples that may not work:
 
| File | Line | Issue |
|------|------|-------|
| quickstart.mdx | 45 | Uses deprecated `init()`, should be `initialize()` |
| api/fetch.mdx | 23 | Import path changed from `pkg` to `pkg/client` |
 
### Inconsistent Terminology
 
Terms used differently across docs:
 
| Term | Variations Found | Recommended |
|------|------------------|-------------|
| API key | "api key", "API Key", "apiKey", "api-key" | "API key" |
| endpoint | "endpoint", "route", "URL", "path" | "endpoint" |
 
## 🟢 Good Practices Found
 
✓ All public exports have corresponding docs
✓ Code examples have language tags
✓ Consistent use of components (Note, Warning, etc.)
 
## Recommendations
 
### High Priority
1. **Consolidate auth docs** - Merge duplicate OAuth content into single source
2. **Update API signatures** - 5 files have outdated function signatures
3. **Document webhooks** - Major feature with zero documentation
 
### Medium Priority
4. **Version bump** - Update all version references to v2.x
5. **Standardize terminology** - Create glossary in context.json
 
### Low Priority
6. **Add missing options** - Document 12 config options
7. **Fix stale examples** - Update deprecated imports