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.
Complete the rename by updating:
- DeviceCatalogs struct field: BookmannUuid → BookhoardUuid (models.go)
- Generated queries: Update all references (queries.sql.go)
- Local variables: bookmannUUID → bookhoardUUID (kobo.go)
- Struct field access: catalog.BookmannUuid → catalog.BookhoardUuid
All "bookmann" and "BOOKMANN" references are now eliminated from the codebase.
Part of project rename to Bookhoard.
Changes:
- Update comments: "Bookmann UUID" → "Bookhoard UUID"
- Rename sidecar struct field: Bookmann → Bookhoard
- Update type names: SidecarBookmannConfig → SidecarBookhoardConfig
- Fix test database name in queue_test.go
- Fix uppercase env var examples in KOBO_SETUP.md
Internal Go variable names (BookmannUuid, bookmannUUID) left unchanged
as they're implementation details that don't affect functionality.
Part of project rename to Bookhoard.
Database changes:
- schema.sql: Update column name bookmann_uuid → bookhoard_uuid
- schema.sql: Update index names and example URLs
- queries.sql: Update all SQL queries to use bookhoard_uuid
- Update example configuration values
Part of project rename to Bookhoard.
Documentation updates:
- All docs/ files: Update project references
- Bruno API collection: Update collection name and tests
- Device setup guides: Update all examples
- Implementation plan: Update database schema examples
- README files: Update project references
Part of project rename to Bookhoard.
Test file updates:
- Update import paths in test files: bookmann/internal → bookhoard/internal
- Update test helper functions and references
- Update test comments and documentation
This is part 6 of the project rename to Bookhoard.
Documentation updates:
- Update README.md title and all references
- Update PROJECT_GUIDELINES.md title and guidelines
- Update all documentation files in docs/ directory
- Update device setup guides (Kobo, KOReader)
- Update API and architecture documentation
- Update completion summaries and progress reports
This is part 5 of the project rename to Bookhoard.
Bruno API test updates:
- Update test assertions: X-Bookmann-* → X-Bookhoard-*
- Update variable names and references in test scripts
- Update documentation and comments in API tests
This is part 4 of the project rename to Bookhoard.
Template changes:
- Update page titles: "Bookmann" → "Bookhoard"
- Update header branding and navigation text
- Regenerate compiled .go templates from .templ sources
- Update all UI references in HTML templates
This is part 3 of the project rename to Bookhoard.
john-okeefe