docs: update comprehensive API documentation and project guides

This commit updates all documentation files throughout the project: - Updated IMPLEMENTATION_PLAN.md with new implementation details - Updated PROJECT_GUIDELINES.md with coding standards and practices - Updated README.md with current project information - Updated SCREENSHOT_AUTOMATION.md with new automation details - Added TEST_DATA.md with test fixtures data - Updated cover_image_serving_plan.md with static URL patterns Documentation API updates: - Updated API reference documentation for all endpoints including: - Authentication (login, logout, register, refresh_token) - Book matching (auto_link, bulk_link, link_book, search) - Collections (CRUD operations, shelf mappings, auto-assign rules) - Conflicts (bulk operations, resolve/dismiss) - Devices (registration, approval, shelf management) - Highlights (create, update, delete, get) - Kobo sync (bookmark, markup, initialization, sync) - KOReader sync (library, metadata, bookmarks, progress) - Libraries (CRUD, folders, media items, stats) - Media items (bulk operations, CRUD) - Notes (CRUD operations) - OPDS (acquisition, feeds, publication) - Progress (reading progress tracking) - Queue (device queue management) - Ratings (star ratings) - Scanner (watch mode, scan operations) - Sync protocols (Kobo, KOReader) - Users (profile, password, admin operations) - WebSocket protocols - Updated user guides (admin, dashboard, settings, sync) - Updated device setup guides (Kobo, KOReader) - Updated developer guides (testing, contributing, operations) - Updated scripts/README.md
2026-02-27 17:06:22 -05:00
parent 6562b20ee5
commit 4d321528b2
154 changed files with 2817 additions and 2152 deletions
@@ -5,9 +5,11 @@ This directory contains verification scripts that enforce compliance with PROJEC
 ## Scripts Overview

 ### `verify-guidelines.sh` (Comprehensive Verification)
+
 **Purpose:** Full validation of all project guidelines including documentation compliance
 **Usage:** `make verify-guidelines` or `./scripts/verify-guidelines.sh`
 **Features:**
+
 - 16 comprehensive checks covering all aspects of PROJECT_GUIDELINES.md
 - High-recall pattern detection for documentation routing validation
 - AI behavior protocol with multi-layered safeguards
@@ -15,6 +17,7 @@ This directory contains verification scripts that enforce compliance with PROJEC
 - Detailed analysis of recent changes and commit quality

 **Checks Included:**
+
 1. No Custom CSS (Frontend & Styling)
 2. No JavaScript Files (Use TypeScript)
 3. No Secrets Committed
@@ -33,15 +36,18 @@ This directory contains verification scripts that enforce compliance with PROJEC
 16. Documentation Completeness Validation

 ### `verify-quick.sh` (Critical-Only Verification)
+
 **Purpose:** Fast development-time checks focusing on critical violations only
 **Usage:** `make verify-quick` or `./scripts/verify-quick.sh`
 **Features:**
+
 - 7 core sections covering critical prohibitions and essential requirements
 - Optimized for speed during active development
 - AI behavior protocol with comprehensive safeguards
 - Focus on blocking issues (errors) vs. improvement suggestions (warnings)

 **Sections Included:**
+
 - 🚨 CRITICAL PROHIBITIONS: Backend & Database
 - 🚨 CRITICAL PROHIBITIONS: Frontend & Styling
 - 🚨 CRITICAL PROHIBITIONS: General
@@ -55,6 +61,7 @@ This directory contains verification scripts that enforce compliance with PROJEC
 Both scripts include comprehensive AI behavior safeguards to prevent automatic fixing of guideline violations:

 ### Protocol Requirements:
+
 1. **NEVER** automatically fix anything without explicit user permission
 2. **FOR EACH** issue found:
   - Explain what the issue is
@@ -69,6 +76,7 @@ Both scripts include comprehensive AI behavior safeguards to prevent automatic f
 7. **APPLY** to ALL file modifications, not just verification issues

 ### Implementation:
+
 - **Header Protocol**: Comprehensive instructions at script start
 - **Function Reminders**: Each error/warning includes AI instruction reminder
 - **Final Reminder**: End-of-script reinforcement of protocol
@@ -79,7 +87,9 @@ Both scripts include comprehensive AI behavior safeguards to prevent automatic f
 ## Usage Guidelines

 ### During Active Development:
+
 Use `make verify-quick` for fast feedback on critical violations:
+
 - No local binaries
 - No custom CSS/JavaScript violations
 - No secrets committed
@@ -87,7 +97,9 @@ Use `make verify-quick` for fast feedback on critical violations:
 - Essential build requirements

 ### Pre-Commit / CI/CD:
+
 Use `make verify-guidelines` for comprehensive validation:
+
 - All critical prohibitions
 - Documentation compliance validation
 - Bruno API test coverage
@@ -97,9 +109,11 @@ Use `make verify-guidelines` for comprehensive validation:
 ### When Issues Are Found:

 #### Enhanced Error/Warning Output (Latest):
+
 Both scripts now provide detailed information for all issues found:

 #### For Errors (Critical Violations):
+
 ```bash
 # Example: AI detects local binary
 ❌ ERROR: Found 1 binary files (should build through Dockerfile)
@@ -114,6 +128,7 @@ Do you want me to fix this? [y/n]"
 ```

 #### For Warnings (Documentation/Style Issues):
+
 ```bash
 # Example: AI finds API content in README
 ⚠ WARNING: Found 2 API patterns in README.md (verify placement per guidelines)
@@ -126,7 +141,7 @@ Found patterns:
 "I found API documentation patterns in README.md. According to the guidelines, API endpoints should be in 'docs/api/<category>/<endpoint>.md' unless this is a breaking change.

 The specific patterns found are:
- Line 81: Rate limiting information 
+- Line 81: Rate limiting information
 - Line 98: WebSocket API reference

 Do you want me to fix this? [y/n]"
@@ -135,16 +150,18 @@ Do you want me to fix this? [y/n]"
 #### Complete Enhanced Output Examples:

 ##### 1. Build Failure with Detailed Errors:
+
 ```bash
 ❌ ERROR: Build failed (violation: must compile after edits)
   AI INSTRUCTION: Ask user before fixing this issue
 Build error details:
 # cmd/server/main.go:45:2: syntax error: unexpected newline, expecting }
-# 
+#
 # Try running: go build ./cmd/server
 ```

 ##### 2. Missing Configuration Files:
+
 ```bash
 ❌ ERROR: .env not in .gitignore (violation: secrets might be committed)
   AI INSTRUCTION: Ask user before fixing this issue
@@ -163,6 +180,7 @@ build/
 ```

 ##### 3. API Content Detection with Line Numbers:
+
 ```bash
 ⚠ WARNING: Found 2 API patterns in README.md (verify placement per guidelines)
   AI INSTRUCTION: Ask user before fixing this issue
@@ -172,6 +190,7 @@ Found patterns:
 ```

 ##### 4. File Organization Violations:
+
 ```bash
 ❌ ERROR: Found 3 .js files (violation: JavaScript prohibited, use TypeScript)
   AI INSTRUCTION: Ask user before fixing this issue
@@ -182,6 +201,7 @@ Found files:
 ```

 ##### 5. Documentation Structure Validation:
+
 ```bash
 ✓ PASS: docs/api directory exists
 ✓ PASS: docs/devices directory missing
@@ -197,6 +217,7 @@ Expected directory structure:
 ```

 ##### 6. Bruno API Tests Coverage Analysis:
+
 ```bash
 ✓ PASS: Found 47 Bruno test files
 ⚠ WARNING: Bruno test files (47) fewer than API docs (52)
@@ -205,6 +226,7 @@ Coverage gap: API docs (52) vs Bruno tests (47)
 ```

 ##### 7. Git Commit Quality Analysis:
+
 ```bash
 ⚠ WARNING: Found 3 recent commits changing >15 files each (should use multiple commits)
   AI INSTRUCTION: Ask user before fixing this issue
@@ -215,6 +237,7 @@ b7c8f9e: fix: resolve merge conflicts (16 files)
 ```

 ##### 8. CSS Template Violations:
+
 ```bash
 ❌ ERROR: Found 12 templates with <style> tags (violation: custom CSS prohibited)
   AI INSTRUCTION: Ask user before fixing this issue
@@ -226,6 +249,7 @@ templates/... (truncated, first 10 shown)
 ```

 #### Detailed Information Provided:
+
 - **Binary files**: Lists exact file paths found with full paths
 - **CSS violations**: Shows specific templates with <style> tags and line counts
 - **JavaScript files**: Lists all .js files outside allowed directories
@@ -242,12 +266,14 @@ templates/... (truncated, first 10 shown)
 ## Recent Enhancements

 ### AI Behavior Protocol Implementation (Latest):
+
 - Added comprehensive AI instructions to both scripts
 - Enhanced error/warning functions with AI reminders
 - Multi-layered safeguards prevent automatic fixing
 - Protocol applies to ALL file modifications

 ### verify-guidelines.sh Documentation Validation:
+
 - **Check 12**: Content placement validation (API patterns, device setup, development content)
 - **Check 13**: Structure validation (required directories, file counts)
 - **Check 14**: Bruno API tests validation (coverage comparison)
@@ -255,11 +281,13 @@ templates/... (truncated, first 10 shown)
 - **Check 16**: Completeness validation (orphaned docs, naming consistency)

 ### Makefile Integration:
+
 - `make verify-guidelines`: Runs comprehensive validation
 - `make verify-quick`: Runs critical-only validation
 - Fixed naming confusion (previously ran quick version for both targets)

 ### Bruno OpenCollection YAML Validation:
+
 - Counts Bruno OpenCollection YAML `.yml` test files in `bruno/` directory
 - Compares against API documentation file count in `docs/api/`
 - Flags insufficient coverage for human review
@@ -268,18 +296,22 @@ templates/... (truncated, first 10 shown)
 ## Bruno OpenCollection YAML Explained

 ### Purpose:
+
 Bruno is an API testing tool that uses OpenCollection YAML format (`.yml` files) to define:
+
 - API requests and responses
 - Test cases and validation
 - Contract testing examples

 ### Verification Logic:
+
 1. **Counts Test Files**: Scans `bruno/` directory for `.yml` files
-2. **Counts API Docs**: Scans `docs/api/` for `.md` files  
+2. **Counts API Docs**: Scans `docs/api/` for `.md` files
 3. **Compares Coverage**: Ensures test files >= documentation files
 4. **Flags Gaps**: Human review for insufficient test coverage

 ### Example Scenario:
+
 ```
 Developer adds: docs/api/users/login.md
 Should also add: bruno/user/auth/Login User.yml
@@ -291,6 +323,7 @@ This ensures **API documentation and test coverage stay synchronized** - a criti
 ## Verification Script Architecture

 ### Data Collection Strategy
+
 Both scripts use a **detailed-first approach** for error/warning reporting:

 ```bash
@@ -308,9 +341,10 @@ if [ -n "$JS_FILES_FOUND" ]; then
 ```

 ### Enhanced Error Message Pattern
+
 ```bash
 # Template for enhanced output:
-error_msg() { 
+error_msg() {
    echo -e "${RED}✗ ERROR: $1${NC}"
    echo -e "${RED}   AI INSTRUCTION: Ask user before fixing this issue${NC}"
    ((ERRORS++))
@@ -328,6 +362,7 @@ fi
 ### Content Detection Methods

 #### API Pattern Detection:
+
 ```bash
 # Line-by-line analysis with context:
 API_CONTENT=$(grep -n -E "## API|endpoint|GET |POST |/api/" README.md 2>/dev/null || true)
@@ -339,6 +374,7 @@ API_PATTERNS_IN_README=$(echo "$API_CONTENT" | wc -l)
 ```

 #### Build Error Capture:
+
 ```bash
 # Capture full build output for detailed analysis:
 if go build -o /tmp/bookhoard-test ./cmd/server 2> /tmp/build.log; then
@@ -354,6 +390,7 @@ fi
 ```

 #### Git Analysis with Context:
+
 ```bash
 # Show commit details with file counts:
 LARGE_COMMITS_LIST=$(git log --oneline -10 --pretty=format:"%h %s" | while read hash msg; do
@@ -371,22 +408,26 @@ done)
 ### Script Design Principles

 #### 1. High Recall with Actionable Details
+
 - **Flag anything questionable** for human review
 - **Provide specific evidence** of what triggered the flag
 - **Show exact locations** (file paths, line numbers)
 - **Include context** for easy assessment

 #### 2. Minimal False Negatives
+
 - **Comprehensive pattern matching** catches all potential violations
 - **Multiple detection methods** (file names, content patterns, directory structure)
 - **Cross-validation** across different check types

 #### 3. AI Safety Integration
+
 - **Every error/warning includes AI protocol reminder**
 - **Multi-layered safeguards** (header, functions, footer)
 - **Override protection** for conflicting AI instructions

 #### 4. User-Friendly Output
+
 - **Color-coded messages** for quick visual scanning
 - **Structured information** with clear sections
 - **Actionable guidance** showing exactly what to fix
@@ -395,6 +436,7 @@ done)
 ### Troubleshooting Enhanced Output

 #### When Details Don't Show:
+
 ```bash
 # Check if command succeeded:
 if [ -n "$DETECTED_CONTENT" ]; then
@@ -410,6 +452,7 @@ echo "Debug result: $DEBUG_OUTPUT"
 ```

 #### When Too Much Output:
+
 ```bash
 # Limit detailed output for readability:
 FOUND_FILES=$(find . -name "*.js" | head -10)
@@ -421,6 +464,7 @@ find . -name "*.js" | less
 ```

 #### Performance Considerations:
+
 - **Quick validation**: `verify-quick.sh` focuses on critical violations only
 - **Comprehensive validation**: `verify-guidelines.sh` includes full analysis
 - **Parallel execution**: Some checks run concurrently where possible
@@ -429,18 +473,22 @@ find . -name "*.js" | less
 ## Troubleshooting

 ### verify-guidelines.sh Issues:
+
 If comprehensive script fails to run completely:
+
 1. Use `make verify-quick` for essential checks
 2. Check for syntax errors: `bash -n scripts/verify-guidelines.sh`
 3. Run without `set -e` to identify failing command
 4. Check file permissions and accessibility

 ### Common False Positives:
+
 - **CSS/JS files in `web/static/`**: These are compiled output, exclude with `-not -path "./web/static/*"`
 - **Device setup in README.md**: Legitimate for quick start setup instructions
 - **Binary files in build artifacts**: Exclude build directories from checks

 ### When in Doubt:
+
 - **High Recall Approach**: Flag for human review rather than risk missing violations
 - **User Decision Required**: Always ask before fixing anything
 - **Document Decisions**: Note when certain patterns are accepted as legitimate
@@ -448,12 +496,14 @@ If comprehensive script fails to run completely:
 ## Legacy vs New Features

 ### Original verify-quick.sh Features:
+
 - Basic critical prohibitions checking
 - Simple error/warning system
 - Exit codes for CI/CD integration
 - Focus on technical violations

 ### Enhanced Features:
+
 - **AI Behavior Protocol**: Comprehensive safeguards
 - **Documentation Validation**: High-recall pattern detection
 - **Bruno Test Coverage**: API documentation synchronization
@@ -463,10 +513,12 @@ If comprehensive script fails to run completely:
 ## Understanding Results

 ### Exit Codes:
+
 - `0`: All checks passed (or only warnings)
 - `1`: Errors found - fix before committing

 ### Message Types:
+
 - ✅ **PASS**: Guideline followed correctly
 - ⚠️ **WARNING**: Minor issue, should fix soon
 - ❌ **ERROR**: Critical violation of PROJECT_GUIDELINES.md
@@ -474,6 +526,7 @@ If comprehensive script fails to run completely:
 ## Current Codebase Status

 ### Quick Verification Status:
+
 - ✅ No server binaries
 - ✅ Migration structure OK
 - ✅ No custom CSS violations
@@ -484,6 +537,7 @@ If comprehensive script fails to run completely:
 - ⚠️ Some documentation routing patterns (human review needed)

 ### Comprehensive Verification:
+
 - Detailed analysis of all guideline aspects
 - High-recall documentation pattern detection
 - API test coverage validation
@@ -492,9 +546,10 @@ If comprehensive script fails to run completely:
 ## Compliance Status

 These verification scripts implement the high-recall safety net approach specified in PROJECT_GUIDELINES.md, ensuring:
+
 - ✅ AI never automatically fixes guideline violations
 - ✅ Documentation follows proper routing guidelines
- ✅ API testing stays synchronized with documentation  
+- ✅ API testing stays synchronized with documentation
 - ✅ Critical violations are caught quickly during development
 - ✅ Comprehensive validation prevents regressions before commits

@@ -505,6 +560,7 @@ The verification system provides multiple layers of protection against guideline
 ### Development Workflow Integration

 #### During Feature Development:
+
 ```bash
 # 1. Initial check (fast):
 make verify-quick
@@ -520,6 +576,7 @@ git commit -m "feat: implement user authentication"
 ```

 #### When Issues Are Detected:
+
 ```bash
 # Example: API content in README.md
 ⚠ WARNING: Found 2 API patterns in README.md (verify placement per guidelines)
@@ -535,6 +592,7 @@ Found patterns:
 #### Fix Resolution Examples:

 ##### Moving API Documentation:
+
 ```bash
 # Before: README.md contains API endpoints
 # After: Move to docs/api/ and create individual endpoint files
@@ -545,6 +603,7 @@ echo "# Authentication Endpoints" > docs/api/authentication/login.md
 ```

 ##### Fixing CSS Violations:
+
 ```bash
 # Before: templates contain <style> tags
 # After: Convert to TailwindCSS classes
@@ -555,6 +614,7 @@ echo "# Authentication Endpoints" > docs/api/authentication/login.md
 ### CI/CD Pipeline Integration

 #### GitHub Actions Example:
+
 ```yaml
 name: Verify Guidelines
 on: [push, pull_request]
@@ -566,7 +626,7 @@ jobs:
      - uses: actions/checkout@v3
      - uses: actions/setup-go@v4
        with:
-          go-version: '1.25'
+          go-version: "1.25"
      - name: Run Comprehensive Verification
        run: |
          make verify-guidelines
@@ -577,6 +637,7 @@ jobs:
 ```

 #### Pre-commit Hook Example:
+
 ```bash
 # .git/hooks/pre-commit
 #!/bin/bash
@@ -596,6 +657,7 @@ fi
 ### AI-Assisted Development Workflow

 #### When AI Implements Features:
+
 ```bash
 # 1. User requests feature with guidelines
 User: "Add user password reset feature, follow all PROJECT_GUIDELINES.md"
@@ -613,6 +675,7 @@ User: git commit -m "feat: add password reset feature"
 ```

 #### When AI Makes Mistakes:
+
 ```bash
 # 1. AI violates guideline unknowingly
 AI: [adds custom CSS] → <style>.custom { color: red; }</style>
@@ -634,6 +697,7 @@ Do you want me to fix this? [y/n]"
 ### Advanced Troubleshooting

 #### Debugging Verification Issues:
+
 ```bash
 # Test individual components:
 bash -x scripts/verify-quick.sh 2>&1 | tee debug.log
@@ -649,6 +713,7 @@ grep -E "## API|endpoint" README.md | wc -l
 ```

 #### Handling Edge Cases:
+
 ```bash
 # Missing directories (graceful handling):
 if [ ! -d "docs/api" ]; then
@@ -668,6 +733,7 @@ echo "$LONG_OUTPUT" | less  # or | head -20
 ```

 #### Performance Optimization:
+
 ```bash
 # Quick development checks (skip expensive operations):
 export FAST_MODE=true
@@ -682,9 +748,9 @@ make verify-guidelines
    check_binary_files
 ) &
 (
-    check_css_violations  
+    check_css_violations
 ) &
 wait  # Wait for both to complete
 ```

-This comprehensive documentation ensures verification scripts are fully understood and can be effectively integrated into any development workflow.
+This comprehensive documentation ensures verification scripts are fully understood and can be effectively integrated into any development workflow.