fix(docs): correct critical API documentation inaccuracies for v2.3.1

BREAKING DOCUMENTATION FIXES:
- Fix API methods: Changed pipeline.query() and pipeline.ingest() to pipeline.run()
- Fix response structure: Updated from { text, sources, metadata } to { success, query, results, error? }
- Add accessibility indicators: Mark features as Public API, CLI Tool, or CLI/Internal
- Add warnings for non-exported features (JWTValidator, InputSanitizer, Federated Learning, etc.)

Changes:
- API-Reference.md: Complete rewrite of pipeline methods to match actual exports
- Introduction.md: Added feature availability legend with ✅📦🔧 indicators
- Usage.md: Updated all code examples to use pipeline.run() with correct signatures
- Added DOCUMENTATION_ACCURACY_AUDIT.md with full audit report

Impact: Users following old docs would get "function not found" errors. These fixes prevent that.

Related: Addresses discrepancies found in codebase audit against documentation

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

Co-Authored-By: Claude <noreply@anthropic.com>

Author: github-actions[bot]

DOCUMENTATION_ACCURACY_AUDIT.md

@@ -0,0 +1,327 @@
+# Documentation Accuracy Audit Report
+
+## RAG Pipeline Utils v2.3.1 Documentation Site
+
+**Audit Date:** 2025-11-09
+**Audited Version:** 2.3.1
+**Auditor:** Automated codebase verification
+
+---
+
+## Executive Summary
+
+This report assesses the accuracy, truthfulness, and honesty of the RAG Pipeline Utils documentation site against the actual codebase implementation. The audit identifies **critical discrepancies** between documented APIs and actual exports, as well as feature claims that are not publicly accessible.
+
+**Overall Assessment:** ⚠️ **MAJOR ISSUES IDENTIFIED**
+
+---
+
+## Critical Issues
+
+### 1. **API Method Names Mismatch** ❌ CRITICAL
+
+**Documentation Claims:**
+
+- `pipeline.query(query, options)` - Execute queries against pipeline
+- `pipeline.ingest(source, options)` - Ingest documents into pipeline
+
+**Actual Implementation (src/core/create-pipeline.js:98):**
+
+```javascript
+return { run: runOnce, cleanup() {} };
+```
+
+**Reality:**
+
+- The public API exports `pipeline.run()`, NOT `pipeline.query()` or `pipeline.ingest()`
+- All tests use `pipeline.run()` (verified in **tests**/)
+- The InstrumentedPipeline wrapper has query/ingest, but createRagPipeline doesn't
+
+**Impact:** Users following documentation will get "function not found" errors.
+
+**Recommendation:** Update all API documentation to use `pipeline.run()` or export a wrapper with query/ingest methods.
+
+---
+
+### 2. **Unaccessible Features Advertised as Available** ❌ CRITICAL
+
+**Documentation Claims (Introduction.md):**
+
+#### "Federated Learning"
+
+- **Claimed:** "Distributed model training with privacy-preserving aggregation"
+- **Reality:** Code exists in `src/ai/federation/federated-learning-coordinator.js` but NOT exported in `src/index.js`
+- **Accessible:** NO
+
+#### "Model Training Orchestrator"
+
+- **Claimed:** "End-to-end training workflows with hyperparameter tuning"
+- **Reality:** Code exists in `src/ai/training/model-training-orchestrator.js` but NOT exported
+- **Accessible:** NO
+
+#### "SLO Monitoring System"
+
+- **Claimed:** "Built-in Service Level Objectives tracking with error budgets and alerting"
+- **Reality:** Code exists in `src/observability/slo-monitor.js` but NOT exported
+- **Accessible:** NO
+
+#### "Plugin Marketplace"
+
+- **Claimed:** "Certified plugin ecosystem with discovery and installation workflows"
+- **Reality:** Code exists in `src/core/plugin-marketplace/` but NOT exported
+- **Accessible:** NO
+
+**Actual Public Exports (src/index.js:44-86):**
+
+```javascript
+module.exports = {
+  createRagPipeline,
+  loadConfig,
+  validateRagrc,
+  normalizeConfig,
+  pluginRegistry,
+  logger,
+  errorFormatter,
+  createError,
+  wrapError,
+  ERROR_CODES,
+  MultiModalProcessor,
+  AdaptiveRetrievalEngine,
+  DAGEngine,
+  ParallelProcessor,
+  eventLogger,
+  metrics,
+  AuditLogger,
+  DataGovernance,
+  HotReloadManager,
+  createHotReloadManager,
+  DevServer,
+  createDevServer,
+};
+```
+
+**Impact:** Users cannot access advertised enterprise features. Documentation misleads users about available functionality.
+
+**Recommendation:** Either export these features OR clearly mark them as "Internal/CLI-only" in documentation.
+
+---
+
+## Moderate Issues
+
+### 3. **createRagPipeline Parameter Mismatch** ⚠️ MODERATE
+
+**Documentation (API-Reference.md:35):**
+
+- Claims `pipeline.run()` returns object with `text`, `sources`, `metadata`
+
+**Actual Implementation (src/core/create-pipeline.js:88):**
+
+```javascript
+return { success: true, query, results };
+```
+
+**Reality:**
+
+- Returns `{ success, query, results }` NOT `{ text, sources, metadata }`
+- On error: `{ success: false, error: String(e.message || e) }`
+
+**Impact:** Response structure doesn't match documentation.
+
+---
+
+### 4. **Missing Required Parameters in createRagPipeline** ⚠️ MODERATE
+
+**Documentation Claims:**
+
+- All parameters optional (API-Reference.md:28-33 shows "No" for Required column)
+
+**Actual Implementation:**
+
+- src/core/pipeline-factory.js:12-18 shows required check:
+
+```javascript
+const required = ["loader", "embedder", "retriever", "llm"];
+const missing = required.filter((name) => !arguments[0] || !arguments[0][name]);
+if (missing.length > 0) {
+  throw new Error(`Required components missing: ${missing.join(", ")}`);
+}
+```
+
+**Reality:**
+
+- Two implementations exist:
+  1. `create-pipeline.js` - All optional (the one exported)
+  2. `pipeline-factory.js` - Required parameters
+- Documentation doesn't specify which one applies
+
+**Impact:** Ambiguity about parameter requirements.
+
+---
+
+## Accurate Components
+
+### 5. **Core Exports Verified** ✅ ACCURATE
+
+These exports match documentation:
+
+- `createRagPipeline` - Factory function (exists)
+- `pluginRegistry` - Plugin system (exists)
+- `DAGEngine` - Workflow engine (exists)
+- `MultiModalProcessor` - AI capabilities (exists)
+- `AdaptiveRetrievalEngine` - Retrieval engine (exists)
+- `AuditLogger` - Enterprise logging (exists)
+- `DataGovernance` - Enterprise governance (exists)
+- `HotReloadManager` - Development tools (exists)
+- `DevServer` - Development server (exists)
+
+---
+
+### 6. **Interactive Tools Code Examples** ✅ MOSTLY ACCURATE
+
+**CodePlayground Examples:**
+
+- Plugin patterns are conceptually correct
+- Shows proper plugin contracts (embed, retrieve, generate)
+- Example structure matches expected plugin architecture
+
+**Issues:**
+
+- Examples show `pipeline.run()` which is correct ✅
+- But API docs show `pipeline.query()` which is wrong ❌
+
+---
+
+### 7. **Performance Calculator Numbers** ✅ REASONABLE ESTIMATES
+
+**Latency Estimates:**
+
+- OpenAI Embedder: ~120ms - Realistic for API calls
+- HNSW Retrieval: ~45ms - Reasonable for in-memory search
+- GPT-3.5: ~800ms - Typical for generation
+- GPT-4: ~1500ms - Reasonable for larger model
+
+**Cost Estimates:**
+
+- OpenAI Embedding: $0.13 per 1M tokens - Matches official pricing
+- GPT-3.5: $1.50 per 1M tokens - Approximate combined input/output cost
+- GPT-4: $30 per 1M tokens - Approximate pricing
+
+**Verdict:** Estimates are reasonable ballpark figures, properly labeled as "Estimated Performance"
+
+---
+
+### 8. **CHANGELOG Accuracy** ✅ HONEST
+
+**Current CHANGELOG (versioned_docs/version-2.3.1/CHANGELOG.md):**
+
+- Lists only verifiable features actually present in v2.3.1
+- Removed fabricated version history
+- Removed unverifiable performance benchmarks
+- Honest about what's available
+
+**Verdict:** CHANGELOG is accurate after recent corrections.
+
+---
+
+## Security Concerns
+
+### 9. **Security Features Exist But Not Exported** ⚠️
+
+**Available in Codebase:**
+
+- `JWTValidator` (src/security/jwt-validator.js) - NOT exported
+- `InputSanitizer` (src/utils/input-sanitizer.js) - NOT exported
+
+**Impact:** Security utilities exist but users can't access them via public API.
+
+---
+
+## Node.js Version Claims
+
+### 10. **Node.js Support** ✅ ACCURATE
+
+**Documentation Claims:**
+
+- Node.js 18.x, 20.x, 22.x
+
+**package.json (line 19-21):**
+
+```json
+"engines": {
+  "node": ">=18"
+}
+```
+
+**Verdict:** Accurate - Supports Node 18+
+
+---
+
+## Recommendations
+
+### Immediate Actions Required
+
+1. **Fix API Method Names (CRITICAL)**
+
+   - Option A: Change all `pipeline.query()` / `pipeline.ingest()` references to `pipeline.run()`
+   - Option B: Export a wrapper that provides query/ingest methods
+   - Timeline: URGENT - This breaks user code
+
+2. **Clarify Feature Availability (CRITICAL)**
+
+   - Add "Accessibility" column to feature lists:
+     - ✅ Public API
+     - 🔧 CLI Only
+     - 📦 Internal
+   - Remove claims about unavailable features OR export them
+
+3. **Fix Response Structure Documentation (HIGH)**
+
+   - Update API docs to show actual return values: `{ success, query, results }`
+   - Document error response format
+
+4. **Add Disclaimer to Performance Calculator (MEDIUM)**
+   - Current label: "Estimate throughput, latency, and costs"
+   - Add: "Note: Estimates are approximate. Actual performance varies by workload, network conditions, and API rate limits."
+
+### Long-term Improvements
+
+5. **API Contract Testing**
+
+   - Add tests that verify documentation examples actually work
+   - CI/CD check to prevent docs/code drift
+
+6. **Export Missing Features**
+
+   - Decide which internal features should be public
+   - Export valuable features like FederatedLearning, SLOMonitor
+
+7. **Versioning Documentation**
+   - Document breaking changes between internal implementations
+   - Clarify when create-pipeline.js vs pipeline-factory.js should be used
+
+---
+
+## Conclusion
+
+The documentation site contains **significant inaccuracies** that will confuse and frustrate users:
+
+**Critical Problems:**
+
+- ❌ API methods `query()` and `ingest()` don't exist on public pipeline
+- ❌ Major features advertised but not accessible via public API
+- ⚠️ Response structure mismatch
+
+**What's Accurate:**
+
+- ✅ Core exports match codebase
+- ✅ Performance estimates are reasonable
+- ✅ CHANGELOG is honest after recent cleanup
+- ✅ Node.js version requirements accurate
+
+**Overall Grade:** **D+ (60/100)**
+
+- Documentation exists and is well-structured
+- But contains critical functional inaccuracies
+- Advertises features users cannot access
+
+**Priority:** Fix API method names immediately to prevent broken user code.