Docs + Reporting + Webservice + Agent Flow: default developer guide, provenance reports (markdown/pdf), and API/reporting integration

[renan-souza]

Summary

This PR consolidates major improvements across reporting, webservice APIs, docs, and agent workflows.
It introduces provenance reporting (Markdown cards + PDF reports), exposes report generation via webservice routes, and ships a new developer-first default guide to make end-to-end
adoption significantly easier.

Highlights

1) Reporting: Markdown + PDF

• Added/expanded report generation via Flowcept.generate_report(...):
  • report_type="provenance_card", format="markdown" (default)
  • report_type="provenance_report", format="pdf"
• PDF report generation now includes:
  • full workflow/activity summaries
  • telemetry/resource usage sections
  • object artifact summaries/details
  • plots (including ML-specialized KPI plots when applicable)
• Improved formatting/readability for PDF output:
  • better table wrapping
  • improved object detail rendering
  • consistent section structure and footer behavior

2) Webservice: FastAPI reporting/download + query routes

• Delivered FastAPI reporting/download APIs and OpenAPI docs integration.
• Added/expanded query routes and report download paths in webservice.
• Improved OpenAPI artifact generation and documentation exposure.

3) Agent + Skills integration

• Strengthened external-LLM interaction model and documented explicit tool flow.
• Clarified prompt/tool execution paths for DF query orchestration.
• Improved MCP/agent documentation and usability patterns.

4) Documentation overhaul

• Added a new default developer guide under docs:
  • docs/README.md
• Added ReadTheDocs-visible entry:
  • docs/default_user_guide.rst
• Highlighted this guide in:
  • docs/index.rst
  • docs/quick_start.rst
  • root README.md
• Developer guide improvements include:
  • TL;DR quickstart
  • 60-second setup path
  • choose-your-path navigation
  • online/offline/agent/report usage tracks
  • common failures + quick fixes
  • command cheat sheet
  • inlined beginner examples from:
    • examples/start_here.py
    • examples/unmanaged/simple_task2.py
  • duplicate example style removed between 2.1 and 2.2

5) CI and compatibility fixes

• CI/docs install and checks workflow adjustments (checks.yml fixes).
• stdlib timezone handling fix.
• formatting/reformat consistency commits.
• integration merge updates from skills, webservice, and MQTT fixes.

6) MQTT interceptor fix

• Included fix from @jackdmarquez:
  • MQTT interceptor now accepts check_safe_stops correctly.

Commit Context

This PR aggregates 23 commits from @renan-souza, @jackdmarquez, and CI bot, including:

• webservice/reporting feature delivery
• PDF reporting additions and refinements
• docs/user-guide additions
• CI workflow fixes
• MQTT interceptor fix
• merge commits across active integration branches

Impact

• Easier onboarding for software developers.
• Better production-grade report outputs (especially PDF).
• Cleaner integration path for report generation via API and agent tooling.
• More robust CI and docs build behavior.
• Improved practical usability of Flowcept for both offline and online workflows.

PR text generated by codex 5.3