Introduce GET /api/ai/suggest with deterministic AISuggestionService results
and optional LLM enrichment (?rich=true), plus reusable suggestion chips,
notes ghost autocomplete, and a manual-entry Autofill popover. All UI hides
when AI is disabled; LLM failures degrade to deterministic suggestions only.
Describe the session JSON endpoint used by the main dashboard week
comparison chart: partial Monday-to-today window, parallel prior week,
dense by_day series, and null change_percent when last week has no hours.
Note the path with other internal dashboard routes in API_VERSIONING.md.
Register optional blueprints and the optional audit_logs module with full tracebacks (logger.exception and stable extra fields). Re-raise registration errors when FLASK_ENV is development or DEBUG is enabled so local misconfiguration fails fast; production and testing keep skipping optional modules after logging.
Update REST API, API versioning, architecture, project structure, contributor guide, and CONTRIBUTING for global search responses (partial and per-domain errors), shared run_global_search in app/services/global_search_service.py, and blueprint registry observability.
Document the dual HTTP surface everywhere integrators look: OpenAPI intro and servers, ARCHITECTURE, REST_API, API_VERSIONING (deprecated vs internal routes, shared modules), and CONTRIBUTING (v1-first rule).
Session JSON routes in app/routes/api.py that overlap REST v1 now return X-API-Deprecated and a Link header with rel successor-version, implemented via app/utils/api_deprecation.py.
Extract shared global search into app/services/global_search_service.py for both GET /api/search and GET /api/v1/search while preserving legacy short-query 200 empty responses and v1 400 validation.
Refactor legacy POST /api/timer/start, /api/timer/stop, and the start path of /api/timer/resume to use TimeTrackingService; keep existing socketio emits for the web UI.
Add tests/test_api_deprecation_headers.py and adjust search partial-failure tests to patch Project.query on the service module.
Complete reorganization of project documentation to improve discoverability,
navigation, and maintainability. All documentation has been restructured into
a clear, role-based hierarchy.
## Major Changes
### New Directory Structure
- Created `docs/api/` for API documentation
- Created `docs/admin/` with subdirectories:
- `admin/configuration/` - Configuration guides
- `admin/deployment/` - Deployment guides
- `admin/security/` - Security documentation
- `admin/monitoring/` - Monitoring and analytics
- Created `docs/development/` for developer documentation
- Created `docs/guides/` for user-facing guides
- Created `docs/reports/` for analysis reports and summaries
- Created `docs/changelog/` for detailed changelog entries (ready for future use)
### File Organization
#### Moved from Root Directory (40+ files)
- Implementation notes → `docs/implementation-notes/`
- Test reports → `docs/testing/`
- Analysis reports → `docs/reports/`
- User guides → `docs/guides/`
#### Reorganized within docs/
- API documentation → `docs/api/`
- Administrator documentation → `docs/admin/` (with subdirectories)
- Developer documentation → `docs/development/`
- Security documentation → `docs/admin/security/`
- Telemetry documentation → `docs/admin/monitoring/`
### Documentation Updates
#### docs/README.md
- Complete rewrite with improved navigation
- Added visual documentation map
- Organized by role (Users, Administrators, Developers)
- Better categorization and quick links
- Updated all internal links to new structure
#### README.md (root)
- Updated all documentation links to reflect new structure
- Fixed 8 broken links
#### app/templates/main/help.html
- Enhanced "Where can I get additional help?" section
- Added links to new documentation structure
- Added documentation index link
- Added admin documentation link for administrators
- Improved footer with organized documentation links
- Added "Complete Documentation" section with role-based links
### New Index Files
- Created README.md files for all new directories:
- `docs/api/README.md`
- `docs/guides/README.md`
- `docs/reports/README.md`
- `docs/development/README.md`
- `docs/admin/README.md`
### Cleanup
- Removed empty `docs/security/` directory (moved to `admin/security/`)
- Removed empty `docs/telemetry/` directory (moved to `admin/monitoring/`)
- Root directory now only contains: README.md, CHANGELOG.md, LICENSE
## Results
**Before:**
- 45+ markdown files cluttering root directory
- Documentation scattered across root and docs/
- Difficult to find relevant documentation
- No clear organization structure
**After:**
- 3 files in root directory (README, CHANGELOG, LICENSE)
- Clear directory structure organized by purpose and audience
- Easy navigation with role-based organization
- All documentation properly categorized
- Improved discoverability
## Benefits
1. Better Organization - Documentation grouped by purpose and audience
2. Easier Navigation - Role-based sections (Users, Admins, Developers)
3. Improved Discoverability - Clear structure with README files in each directory
4. Cleaner Root - Only essential files at project root
5. Maintainability - Easier to add and organize new documentation
## Files Changed
- 40+ files moved from root to appropriate docs/ subdirectories
- 15+ files reorganized within docs/
- 3 major documentation files updated (docs/README.md, README.md, help.html)
- 5 new README index files created
- 2 empty directories removed
All internal links have been updated to reflect the new structure.
Dries Peeters