- Add 'Run verification script' as first step in Before Committing
- Add verification script to Phase Completion Verification
- Ensures guideline compliance before commits
- Catches errors early in development workflow
- Verification must pass (0 errors) before declaring complete
- Add warning banner to api-reference.md (1,600+ lines)
- Point users to new split endpoint documentation
- Recommend API Documentation Portal for interactive explorer
- Clarify this is kept for backward compatibility
- Resolves device content warnings (appropriate as legacy reference)
- Add LibraryData type to templates/types.go
- Update bookshelf template to accept libraries parameter
- Render libraries server-side for faster initial page load
- Libraries now populated from server data instead of AJAX fetch
- JavaScript still uses API for dynamic content (bookshelf items)
- Update /bookshelf route to fetch libraries server-side before render
- Properly handle UUID and pgtype.Text conversions
- Maintain API endpoint compatibility for JavaScript calls
This improves initial page load performance while preserving
dynamic functionality via API calls.
- Add GetUserVisibleLibrariesData() method for server-side rendering
- Add GetLibraryTypeData() method for SSR type fetching
- These helpers return data directly instead of JSON responses
- Enables Hybrid SSR pattern while preserving API endpoints
- Add context import for new methods
- Add smart device content detection based on mention thresholds
- Check for README.md files in bruno directory (error)
- Update docs structure checks to match new paths (docs/developer/api, docs/user/devices)
- Add INFO-level warnings for moderate device mentions in docs
- Exclude README.md from device content placement checks
- Improve error recovery with better variable sanitization
- Update PROJECT_GUIDELINES.md to reflect current architecture (Hybrid SSR)
- Integrate service layer and SSR rules into existing sections
- Update README.md paths to match new docs structure (docs/developer/api, docs/user/devices)
- Remove redundant README.md files from bruno/ directories
- Update bruno/collection.bru documentation to current API standard
- Fix architectural pattern description from API-driven to Hybrid SSR
BREAKING CHANGE: Documentation URLs have changed
New structure:
- user/ - End-user documentation (device setup, sync guides, frontend)
- developer/ - Developer documentation (API reference, protocols, specs)
- operations/ - Operations documentation (deployment, troubleshooting)
- contributing/ - Contribution guides
Changes:
- Created portal INDEX.md files for each audience section
- Moved device guides to user/devices/ (kobo-setup.md, koreader-setup.md)
- Moved API docs to developer/ (api-reference.md, collections-api.md)
- Moved sync guide to user/sync-guide.md
- Moved troubleshooting to operations/troubleshooting.md
- Moved all split API docs to developer/api/
- Renamed protocol files (kobo-protocol.md, koreader-protocol.md)
- Added placeholder user guides (frontend, user-areas, settings, admin)
- Updated all internal links to new paths
- Updated Go code (http_handler.go, navigation.go) for new paths
- Updated main INDEX.md for audience-based navigation
Benefits:
- Clear separation of user and developer documentation
- Scalable structure for future user guide expansion
- Better organization and discoverability
- Audience-specific landing pages
Related to DOCS_IMPLEMENTATION_PLAN.md Phase 2 completion
- Add complete enhanced output examples for all error/warning types
- Document verification script architecture and design principles
- Include content detection methods and data collection strategies
- Add comprehensive usage scenarios for development, CI/CD, AI workflows
- Provide advanced troubleshooting with debugging techniques
- Include performance optimization and edge case handling
- Demonstrate integration patterns for hooks and pipelines
This creates definitive documentation for verification system that
covers all enhanced outputs, usage patterns, and integration
methods, making scripts fully understandable and actionable for
both human developers and AI assistance.
- Document detailed error/warning output patterns
- Show examples of enhanced information provided
- Explain specific content found for each violation type
- Include examples for both errors and warnings
- Demonstrate improved user experience with actionable details
This documents the latest enhancement where verification scripts now
provide specific file paths, line numbers, and content details
instead of generic error messages, making issues easier to understand
and resolve for both humans and AI assistance.
Enhanced Error/Warning Details:
- API content warnings now show actual lines found
- Build failures now display error logs
- Missing files now show expected locations
- Dockerfile warnings list found files
- Large commits now show specific commit details
- Git ignore issues display current contents
verify-guidelines.sh Comprehensive Documentation Validation:
- Check 12: Content placement validation (API patterns, device setup)
- Check 13: Structure validation (required directories, file counts)
- Check 14: Bruno API tests validation (coverage comparison)
- Full integration of comprehensive documentation checks
- Maintains AI behavior protocol across all operations
User Experience Improvement:
- All errors/warnings now include specific details
- Clear guidance on what was found and why it's an issue
- Verbose output helps identify false positives vs real violations
- Enables faster issue resolution without guesswork
This addresses user request for detailed error/warning information
instead of generic messages, making verification results actionable and
understandable for both humans and AI assistance.
Makefile Integration:
- Add make verify-quick target for critical-only checks
- Fix verify-guidelines target to call comprehensive script
- Clear separation of usage patterns
AI Behavior Protocol:
- Add 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-quick.sh Enhancements:
- Basic documentation structure validation
- API content placement detection in README.md
- Maintains fast performance for development
Documentation:
- Comprehensive scripts/README.md with usage guidelines
- Bruno API tests validation explained
- Troubleshooting and compliance sections
- Clear AI protocol instructions and examples
This provides dual-script approach: fast critical checks during development,
comprehensive validation for pre-commit/CI, with AI safety across all operations.
Check 14: Bruno API Tests Validation
- Count and verify Bruno .bru test files presence
- Compare API documentation vs Bruno test coverage
- Flag insufficient test coverage for human review
Check 15: Recent Documentation Changes Analysis
- Analyze recent commits for documentation compliance
- Flag code commits without corresponding documentation updates
- Verify proper commit message format (docs: prefix)
- Ensure documentation stays synchronized with code changes
These checks provide comprehensive validation of API testing coverage
and ensure documentation follows proper git commit conventions
per PROJECT_GUIDELINES.md requirements.
- Add comprehensive AI instructions at script start and end
- Enhance error/warning functions with AI reminders
- Multi-layered safeguards prevent automatic fixing
- Clear protocol: explain -> propose -> ask permission -> await response
- Instructions apply to ALL file modifications, not just verification issues
These safeguards ensure AI always asks permission before fixing any issues
found by the verification script, preventing automatic corrections of
potential false positives.
Update Documentation section to reflect new docs/ structure:
- Add comprehensive documentation location table
- Clarify when to use docs/ vs README.md
- Include workflow for documentation updates
- Update all checklist sections with documentation guidance
Changes:
- README.md: Setup/onboarding only
- docs/: User-facing features and workflows
- docs/api/: API reference and endpoints
- docs/devices/: Device setup guides
- docs/contributing/: Development documentation
Ensures documentation is properly organized and searchable
via the new docs system with Lunr.js search.
Regenerate all _templ.go files using templ generate after
removing custom <style> tags and converting to TailwindCSS.
Line numbers updated in error messages due to template changes.
Remove <style> tags from index, login, and register templates.
All theme CSS variables now come from centralized input.css,
eliminating duplicate theme definitions across templates.
Remove <style> tags with sidebar transitions, scrollbars, and mobile
responsive styles from docs template. Convert to TailwindCSS utility
classes for transitions and transforms.
Remove <style> tags from admin templates (admin, admin_library,
admin_profile) and rely on centralized theme CSS in input.css.
Converts inline styles to use CSS variables and TailwindCSS classes.
Move theme CSS custom properties from individual templates to
centralized location in web/static/input.css using Tailwind @layer
directives for better maintainability and to eliminate duplicate
code across templates.
Updated PROJECT_GUIDELINES.md and verification script to clarify:
1. OOP restriction applies to FRONTEND (TypeScript) only
2. Go methods are fine and encouraged
3. Avoid classes, inheritance, and OOP bloat in TypeScript
Changed verification script:
- Removed Go struct methods check (was incorrect)
- Added TypeScript class declaration check instead
- Now checks for 'class ' keyword in web/*.ts files
This clarifies the guideline was never about Go backend code,
only about avoiding OOP patterns in TypeScript frontend code.
Verification now shows: 13/13 checks passing, 0 warnings
Only 1 error remains: 12 legacy templates with custom CSS.
Updated verify-quick.sh to follow PROJECT_GUIDELINES.md structure:
- Added comments for each check showing which guideline it verifies
- Reordered checks to match guideline document order
- Expanded from 5 checks to 13 comprehensive checks
New checks added:
- Backend & Database: migration files, pgx v5 driver version
- Frontend & Styling: OOP pattern detection, TailwindCSS usage
- General: git history for secrets, Dockerfile proliferation
- Build & Deployment: code compilation (post-edit verification)
- Configuration: .env.example, .gitignore validation
- Code Modification Safety: commit quality check (no large commits)
Updated scripts/README.md to document all 13 checks with their
corresponding guidelines.
Current status: 12/13 checks passing
- Only 1 error: 12 legacy templates with custom CSS (need Tailwind conversion)
- 1 warning: some Go files have >10 methods (potential OOP, needs manual review)
Exclude web/static/ from verification checks:
- These are TypeScript compiled output files
- Already in .gitignore (web/static/*.js)
- Similar to node_modules/ - build artifacts, not source
Updated verify-quick.sh to exclude:
- web/static/*.js (TypeScript → JS compilation)
- web/static/*.css (TailwindCSS → CSS compilation)
Also removed ./bookhoard binary from repository.
Verification now shows only 1 error: 12 legacy templates with custom CSS.
Docs templates already comply (converted in Phase 4).
Created comprehensive verification script to check codebase against PROJECT_GUIDELINES.md
Features:
- Checks for custom CSS (TailwindCSS requirement)
- Detects JavaScript files that should be TypeScript
- Verifies no secrets committed (.env, credentials.json)
- Validates code compiles (go build)
- Finds local binaries (should use container builds)
- Quick checks with clear pass/fail/warning output
Usage:
make verify-guidelines
./scripts/verify-quick.sh
Current codebase status:
- 12 templates with custom CSS (need Tailwind conversion)
- 2 .js files in web/static/ (need TypeScript conversion)
- 1 binary file (./bookhoard)
This addresses the trust issue: AI now has a tool to prove guideline compliance
Phase 4 part 1: Add search infrastructure
- Add SearchDoc struct and GenerateSearchIndex to docs handler
- Add stripHTML helper for plain text extraction
- Add ServeSearchIndex endpoint to http handler
- Add /docs/search-index.json route in main.go
- Search index includes all documentation files with ID, title, content, URL
Phase 3 complete: Add API explorer to endpoint documentation
- Add DocsLayoutWithExplorer template function
- Update HTTPHandler.ShowAPIEndpoint to check authentication
- Add GetAPIEndpointData method to docs handler
- Include API explorer for all endpoint documentation
- Explorer shows mock data to non-authenticated users
- Explorer enables real API execution for logged-in users
- Add legacy fallback for endpoints without explorer data
Phase 3 part 1: Add interactive API explorer
- Create templates/api_explorer.templ with mock and real modes
- Add EndpointInfo and APIExplorerData types to templates/types.go
- Fix markdown rendering with UnsafeHTML.ToComponent()
- Add templ import for Component support
- API explorer supports:
- Mock data mode for non-authenticated users
- Real execution mode for logged-in users
- Request/response display
- cURL generation
- Copy to clipboard
Phase 2 part 6: Split advanced features endpoints
- Book Matching: search_books, link_book (manual and auto-link)
- Collections: INDEX.md linking to COLLECTIONS_API.md
- OPDS: feeds, acquisition, publication (OPDS 1.2 protocol)
- Include format conversion details (EPUB to KEPUB)
Phase 2 part 2: Split auth and user endpoints
- Authentication: register, login, refresh_token, logout
- Users: get_profile, update_profile, update_theme, change_password
- Each endpoint in separate markdown file
- Include request/response examples and error codes
Phase 2 part 1: Add API documentation landing page
- Create docs/api/INDEX.md with quick links
- Organize by category (auth, users, libraries, media items, etc.)
- Provide navigation to all API endpoint documentation
- Link to COLLECTIONS_API.md for collections details
- Add rawHTML helper function using template.HTML()
- Update docs template to use { template.HTML(doc.Content) }
- Docs now render HTML headings and content properly
- Markdown is converted to HTML by goldmark (with Unsafe()) and output directly
- Add internal/docs package with markdown renderer (goldmark)
- Create docs layout template with sidebar navigation
- Implement hierarchical navigation auto-generated from docs folder
- Add table of contents generator (extract ## headings)
- Add syntax highlighting for code blocks (highlight.js)
- Add mobile responsive design
- Add /docs routes to main.go
The documentation system features:
- Dark theme matching app design
- Collapsible sidebar sections (Getting Started, User Guide, Device Setup, API Reference, Contributing)
- Table of contents for each page
- Breadcrumb navigation
- Full-text search (client-side JavaScript, API endpoint ready)
- Syntax highlighting for code blocks
- Mobile-friendly with hamburger menu
All documentation is served from /docs route, no authentication required.
Markdown files are rendered using goldmark with GFM extensions and syntax highlighting.
- Update README.md with simplified documentation links
- Update docs/API_REFERENCE.md formatting and structure
- Update docs/SYNC_USER_GUIDE.md with minor improvements
These updates reflect the reorganized documentation structure
and new configuration approach with defaults in docker-compose.yml.
- Add conversion service configuration with sensible defaults
- BOOKHOARD_CONVERSION_CACHE_DIR: /app/cache/kepub
- BOOKHOARD_CONVERSION_TOOL: /usr/bin/kepubify
- BOOKHOARD_CONVERSION_CACHE_TTL: 24h
- Add named volume for conversion cache
- Add rate limiting configuration with defaults
- TEST_MODE: false
- RATE_LIMIT_ENABLED: true
- REQUESTS_PER_MINUTE: 10
- Simplify .env.example to only required secrets (JWT_SECRET, DBPASS)
- Add section comments to docker-compose.yml for better organization
- Document optional overrides in .env.example comments
This change separates secrets (in .env) from operational configuration
(in docker-compose.yml), following security best practices while
maintaining flexibility for custom deployments.
- Remove internal development docs (phase tracking, implementation plans, security audits)
- Move DEVELOPMENT.md to docs/contributing/ for contributor guidance
- Move TROUBLESHOOTING.md from root to docs/ folder
- Add docs/INDEX.md as navigation hub for all documentation
- Clean up docs to focus on user/self-hoster facing content
This reorganization separates user-facing documentation from
internal contributor documentation, making the project more
approachable for self-hosters.
john-okeefe