chore: refresh knowledge base

docs/faiss/index.faiss

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:4345d04c2c185f8c9c3cbd3106b7d7c379f08df78b1d9dfd0cf5cd66fe03fc3f
-size 1048621
+oid sha256:761c3e1c863aed9b8194abb693fb5cd07c237ebf4987efd4f58ab4349df6cbd7
+size 3424301

docs/faiss/index.pkl

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:ee3a2de1ce31b6c7d0162e15e6cac52ba5ad314d3062c93b89d360014a547cbf
-size 239138
+oid sha256:8a2bb4a67ed657a46ea93c309f4f686b6c7115bd2b18c7605c5b28c13d686ff1
+size 767874

docs/faiss/metadata.pkl

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:e21a8afdd183583c8da91ea779e9e50deeff9e4cb94fa0a221743e890cdc7ac5
-size 4461
+oid sha256:16da6051eb9ab58343238c7c7dd50c32229abdfab355d06871f7d817904ef93d
+size 16460

docs/github_activity/Abudy72_JustIn_PR_1_Added_some_files....md

@@ -0,0 +1,13 @@
+# PR: Added some files...
+
+**Repository:** Abudy72/JustIn
+**Number:** #1
+**State:** closed
+**Labels:** None
+**Created:** 2024-05-04T20:06:00Z
+**Updated:** 2024-05-04T20:06:11Z
+**URL:** https://github.com/Abudy72/JustIn/pull/1
+
+---
+
+

docs/github_activity/GDG-Guelph_Git-Workshop_PR_11_Add_new_user_Julien_Serbanescu_to_data.json.md

@@ -0,0 +1,13 @@
+# PR: Add new user Julien Serbanescu to data.json
+
+**Repository:** GDG-Guelph/Git-Workshop
+**Number:** #11
+**State:** closed
+**Labels:** None
+**Created:** 2026-02-21T01:26:27Z
+**Updated:** 2026-02-21T01:56:20Z
+**URL:** https://github.com/GDG-Guelph/Git-Workshop/pull/11
+
+---
+
+

docs/github_activity/GDG-Guelph_Git-Workshop_PR_12_Line_195_added_a_max_distance_for_push_effect.md

@@ -0,0 +1,13 @@
+# PR: Line 195, added a max distance for push effect
+
+**Repository:** GDG-Guelph/Git-Workshop
+**Number:** #12
+**State:** open
+**Labels:** None
+**Created:** 2026-02-21T04:51:19Z
+**Updated:** 2026-02-21T04:51:19Z
+**URL:** https://github.com/GDG-Guelph/Git-Workshop/pull/12
+
+---
+
+

docs/github_activity/Julien-ser_Java_PR_1_Mychanges.md

@@ -0,0 +1,28 @@
+# PR: Mychanges
+
+**Repository:** Julien-ser/Java
+**Number:** #1
+**State:** closed
+**Labels:** None
+**Created:** 2025-10-20T13:41:55Z
+**Updated:** 2025-10-20T13:43:31Z
+**URL:** https://github.com/Julien-ser/Java/pull/1
+
+---
+
+<!--
+Thank you for your contribution!
+In order to reduce the number of notifications sent to the maintainers, please:
+- create your PR as draft, cf. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests,
+- make sure that all of the CI checks pass,
+- mark your PR as ready for review, cf. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#marking-a-pull-request-as-ready-for-review
+-->
+
+<!-- For completed items, change [ ] to [x] -->
+
+- [ ] I have read [CONTRIBUTING.md](https://github.com/TheAlgorithms/Java/blob/master/CONTRIBUTING.md).
+- [ ] This pull request is all my own work -- I have not plagiarized it.
+- [ ] All filenames are in PascalCase.
+- [ ] All functions and variable names follow Java naming conventions.
+- [ ] All new algorithms have a URL in their comments that points to Wikipedia or other similar explanations.
+- [ ] All new code is formatted with `clang-format -i --style=file path/to/your/file.java`

docs/github_activity/Julien-ser_agentic-slide-filler_PR_1_wiggum_session.md

@@ -0,0 +1,58 @@
+# PR: wiggum/session
+
+**Repository:** Julien-ser/agentic-slide-filler
+**Number:** #1
+**State:** closed
+**Labels:** None
+**Created:** 2026-03-29T02:51:40Z
+**Updated:** 2026-03-29T02:59:41Z
+**URL:** https://github.com/Julien-ser/agentic-slide-filler/pull/1
+
+---
+
+- **docs: define technical architecture and system design**
+- **Iteration 1: Define technical architecture: select Python as base language, choose `python-pptx` for PPT manipulation, `openai` API (or `anthropic`) for AI generation, and `python-docx` for Word outline parsing; create system architecture diagram**
+- **feat: setup project structure and dependencies**
+- **Iteration 2: Set up project structure with `src/`, `tests/`, `templates/`, `output/`, `docs/` directories; initialize Python virtual environment and `requirements.txt` with `python-pptx>=0.6.21`, `openai>=1.0.0`, `python-docx>=0.8.11`**
+- **Iteration 3: Create configuration management: implement `config.yaml` for API keys, template paths, and output settings; add `.env.example` template with `OPENAI_API_KEY` placeholder**
+- **Iteration 4: Create configuration management: implement `config.yaml` for API keys, template paths, and output settings; add `.env.example` template with `OPENAI_API_KEY` placeholder**
+- **chore: mark configuration management task as complete**
+- **Iteration 5: Create configuration management: implement `config.yaml` for API keys, template paths, and output settings; add `.env.example` template with `OPENAI_API_KEY` placeholder**
+- **docs: mark Git setup and README as complete**
+- **Iteration 6: Establish Git repository with `.gitignore` for Python, IDE files, and sensitive configs; write initial `README.md` with project overview and setup instructions**
+- **Iteration 7: Build PPT template parser: create `TemplateParser` class in `src/template_parser.py` that reads `.pptx` files, extracts slide layouts, placeholders, and shape types, returns structured template metadata**
+- **test: add comprehensive unit tests for TemplateParser**
+- **fix: add src/__init__.py for package imports**
+- **Iteration 8: Build PPT template parser: create `TemplateParser` class in `src/template_parser.py` that reads `.pptx` files, extracts slide layouts, placeholders, and shape types, returns structured template metadata**
+- **Iteration 9: Implement doc outline parser: develop `OutlineParser` class in `src/outline_parser.py` supporting `.docx` and `.md` formats; extracts headings, sections, and content hierarchy into JSON structure**
+- **feat: add ContentMapper class for section-to-placeholder alignment**
+- **Iteration 10: Create content mapping engine: build `ContentMapper` class in `src/content_mapper.py` that aligns outline sections with template slide placeholders using section titles and placeholder tags**
+- **Iteration 12: Add template validation: write unit tests in `tests/test_template_parser.py` that verify placeholder detection, layout identification, and error handling for corrupted templates**
+- **Fix template_parser: dynamic PP_PLACEHOLDER mapping to handle missing enum attributes, and robust test fixture for placeholder indices**
+- **Iteration 13: Add template validation: write unit tests in `tests/test_template_parser.py` that verify placeholder detection, layout identification, and error handling for corrupted templates**
+- **fix: handle KeyError when extracting placeholder indices in TemplateParser.\n\nSome slide layouts contain placeholders that reference invalid indices,\ncausing a KeyError from python-pptx when accessing placeholder_format.idx.\nThe _extract_placeholders method now catches KeyError and skips such\nplaceholders gracefully.**
+- **Iteration 14: Add template validation: write unit tests in `tests/test_template_parser.py` that verify placeholder detection, layout identification, and error handling for corrupted templates**
+- **fix: resolve lint and type errors in template_parser.py**
+- **feat(ai): complete Phase 3 AI tasks; add prompts, generator, validator, and fallback**
+- **Iteration 15: Add template validation: write unit tests in `tests/test_template_parser.py` that verify placeholder detection, layout identification, and error handling for corrupted templates**
+- **Iteration 16: Assemble end-to-end pipeline: create main `SlideFiller` class in `src/slide_filler.py` that orchestrates parsing, mapping, generation, and filling; integrate all modules with dependency injection**
+
+
+<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
+
+## Summary by CodeRabbit
+
+## Release Notes
+
+* **New Features**
+  * Complete command-line interface for converting document outlines into PowerPoint presentations.
+  * Support for multiple document formats (DOCX, Markdown) and mapping strategies.
+  * LLM-powered content generation with multiple model support and automatic fallback.
+  * Content validation and caching to optimize generation performance.
+  * Dry-run mode for testing workflows without producing output.
+
+* **Documentation**
+  * Comprehensive setup and usage guide with system architecture overview.
+  * Configuration examples and environment variable templates provided.
+
+<!-- end of auto-generated comment: release notes by coderabbit.ai -->

docs/github_activity/Julien-ser_agentic-slide-filler_PR_2_wiggum_session.md

@@ -0,0 +1,61 @@
+# PR: wiggum/session
+
+**Repository:** Julien-ser/agentic-slide-filler
+**Number:** #2
+**State:** open
+**Labels:** None
+**Created:** 2026-03-29T02:56:22Z
+**Updated:** 2026-03-29T03:05:45Z
+**URL:** https://github.com/Julien-ser/agentic-slide-filler/pull/2
+
+---
+
+- **docs: define technical architecture and system design**
+- **Iteration 1: Define technical architecture: select Python as base language, choose `python-pptx` for PPT manipulation, `openai` API (or `anthropic`) for AI generation, and `python-docx` for Word outline parsing; create system architecture diagram**
+- **feat: setup project structure and dependencies**
+- **Iteration 2: Set up project structure with `src/`, `tests/`, `templates/`, `output/`, `docs/` directories; initialize Python virtual environment and `requirements.txt` with `python-pptx>=0.6.21`, `openai>=1.0.0`, `python-docx>=0.8.11`**
+- **Iteration 3: Create configuration management: implement `config.yaml` for API keys, template paths, and output settings; add `.env.example` template with `OPENAI_API_KEY` placeholder**
+- **Iteration 4: Create configuration management: implement `config.yaml` for API keys, template paths, and output settings; add `.env.example` template with `OPENAI_API_KEY` placeholder**
+- **chore: mark configuration management task as complete**
+- **Iteration 5: Create configuration management: implement `config.yaml` for API keys, template paths, and output settings; add `.env.example` template with `OPENAI_API_KEY` placeholder**
+- **docs: mark Git setup and README as complete**
+- **Iteration 6: Establish Git repository with `.gitignore` for Python, IDE files, and sensitive configs; write initial `README.md` with project overview and setup instructions**
+- **Iteration 7: Build PPT template parser: create `TemplateParser` class in `src/template_parser.py` that reads `.pptx` files, extracts slide layouts, placeholders, and shape types, returns structured template metadata**
+- **test: add comprehensive unit tests for TemplateParser**
+- **fix: add src/__init__.py for package imports**
+- **Iteration 8: Build PPT template parser: create `TemplateParser` class in `src/template_parser.py` that reads `.pptx` files, extracts slide layouts, placeholders, and shape types, returns structured template metadata**
+- **Iteration 9: Implement doc outline parser: develop `OutlineParser` class in `src/outline_parser.py` supporting `.docx` and `.md` formats; extracts headings, sections, and content hierarchy into JSON structure**
+- **feat: add ContentMapper class for section-to-placeholder alignment**
+- **Iteration 10: Create content mapping engine: build `ContentMapper` class in `src/content_mapper.py` that aligns outline sections with template slide placeholders using section titles and placeholder tags**
+- **Iteration 12: Add template validation: write unit tests in `tests/test_template_parser.py` that verify placeholder detection, layout identification, and error handling for corrupted templates**
+- **Fix template_parser: dynamic PP_PLACEHOLDER mapping to handle missing enum attributes, and robust test fixture for placeholder indices**
+- **Iteration 13: Add template validation: write unit tests in `tests/test_template_parser.py` that verify placeholder detection, layout identification, and error handling for corrupted templates**
+- **fix: handle KeyError when extracting placeholder indices in TemplateParser.\n\nSome slide layouts contain placeholders that reference invalid indices,\ncausing a KeyError from python-pptx when accessing placeholder_format.idx.\nThe _extract_placeholders method now catches KeyError and skips such\nplaceholders gracefully.**
+- **Iteration 14: Add template validation: write unit tests in `tests/test_template_parser.py` that verify placeholder detection, layout identification, and error handling for corrupted templates**
+- **fix: resolve lint and type errors in template_parser.py**
+- **feat(ai): complete Phase 3 AI tasks; add prompts, generator, validator, and fallback**
+- **Iteration 15: Add template validation: write unit tests in `tests/test_template_parser.py` that verify placeholder detection, layout identification, and error handling for corrupted templates**
+- **Iteration 16: Assemble end-to-end pipeline: create main `SlideFiller` class in `src/slide_filler.py` that orchestrates parsing, mapping, generation, and filling; integrate all modules with dependency injection**
+- **Trigger CodeRabbit review**
+- **Trigger CodeRabbit review**
+- **Trigger CodeRabbit review**
+- **Trigger CodeRabbit review**
+
+
+<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
+
+## Summary by CodeRabbit
+
+* **New Features**
+  * Added a complete end-to-end tool for generating PowerPoint presentations from document outlines using LLMs.
+  * Added command-line interface with support for templates, outlines (`.docx`, `.md`), configuration options, and execution modes.
+  * Added integration with OpenAI and Anthropic APIs for AI-powered content generation.
+  * Added caching and retry mechanisms for efficient API usage.
+
+* **Documentation**
+  * Updated README with technical architecture, data flow, setup instructions, and configuration details.
+
+* **Tests**
+  * Added comprehensive test suites for all core components.
+
+<!-- end of auto-generated comment: release notes by coderabbit.ai -->

docs/github_activity/Julien-ser_flash-quote-api_PR_1_wiggum_session.md

@@ -0,0 +1,44 @@
+# PR: wiggum/session
+
+**Repository:** Julien-ser/flash-quote-api
+**Number:** #1
+**State:** open
+**Labels:** None
+**Created:** 2026-03-27T22:54:24Z
+**Updated:** 2026-03-27T23:05:01Z
+**URL:** https://github.com/Julien-ser/flash-quote-api/pull/1
+
+---
+
+- **Iteration 1: Define the quote data structure (e.g., JSON array with fields: id, text, author, category)**
+- **feat: define quote data structure with JSON format**
+- **Iteration 2: Define the quote data structure (e.g., JSON array with fields: id, text, author, category)**
+- **Iteration 3: Choose storage method: in-memory array vs JSON file vs SQLite database**
+- **chore: initialize project structure and mark Phase 1 complete**
+- **Iteration 5: Create quotes_data.json with at least 50 inspirational quotes**
+- **Iteration 7: Generate OpenAPI/Swagger docs with FastAPI automatic docs**
+- **Iteration 8: Create Dockerfile for containerized deployment**
+- **feat: add Dockerfile for containerized deployment**
+- **Iteration 9: Create Dockerfile for containerized deployment**
+- **ci: fix workflow to use requirements.txt and mark task complete**
+- **Iteration 10: Set up GitHub Actions for CI: linting (ruff), testing on push**
+- **Final worker session push**
+- **Finalize PR: all tasks complete**
+
+
+<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
+
+## Summary by CodeRabbit
+
+* **New Features**
+  * Introduced flash-quote-api service with three endpoints: retrieve random quotes, list all quotes with optional category filtering, and fetch quotes by ID.
+  * Enabled CORS for cross-origin requests.
+
+* **Documentation**
+  * Added interactive API documentation via Swagger/OpenAPI.
+
+* **Chores**
+  * Added Docker support for containerized deployment.
+  * Configured GitHub Actions for automated testing and CI.
+
+<!-- end of auto-generated comment: release notes by coderabbit.ai -->

docs/github_activity/Julien-ser_invoice-resolver-ai_PR_1_wiggum_session_1774066153.md

@@ -0,0 +1,50 @@
+# PR: wiggum/session 1774066153
+
+**Repository:** Julien-ser/invoice-resolver-ai
+**Number:** #1
+**State:** open
+**Labels:** None
+**Created:** 2026-03-21T06:55:42Z
+**Updated:** 2026-03-22T03:46:39Z
+**URL:** https://github.com/Julien-ser/invoice-resolver-ai/pull/1
+
+---
+
+- **feat: complete Task 1.2 - initialize FastAPI project structure**
+- **docs: add comprehensive API documentation (Task 1.4)**
+- **docs: mark Task 2.2 complete; update Python version note; bump pydantic to 2.11.0**
+- **feat: implement email automation with Jinja2 templates and Celery tasks**
+- **feat: implement AI dispute letter drafting with OpenAI and Anthropic**
+- **feat: add PDF generation with WeasyPrint for dispute letters and small claims forms**
+- **feat: add Streamlit dashboard with JWT authentication and user interface**
+- **feat: add admin panel to Streamlit dashboard with user management and system health monitoring**
+- **feat: implement Stripe Billing integration with subscription management**
+- **docs: add Billing Integration section to README**
+- **chore: mark Task 5.1 as complete - comprehensive pytest test suite in place\n\nTests cover email, AI, PDF, integrations, auth, invoices, webhooks, billing, A/B testing, admin, config, middleware, and Celery tasks. Requires PostgreSQL and Redis to run (see docker-compose.yml).**
+- **ci: add Docker multi-stage builds and production deployment configuration**
+- **Final worker session push**
+
+
+<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
+
+## Summary by CodeRabbit
+
+* **New Features**
+  * Added invoice management REST API with JWT authentication
+  * Integrated payment provider support (Stripe, PayPal, Plaid) with webhook event handling
+  * Added automated email follow-up sequences for invoice reminders
+  * Added admin dashboard for system monitoring and user management
+  * Added containerized deployment infrastructure with Docker and Fly.io support
+
+* **Documentation**
+  * Added comprehensive API reference documentation
+  * Added deployment runbook and database schema documentation
+
+* **Tests**
+  * Added test coverage for authentication, invoices, and webhooks
+
+* **Chores**
+  * Added monitoring stack with Prometheus and Grafana integration
+  * Added CI/CD pipeline configuration
+
+<!-- end of auto-generated comment: release notes by coderabbit.ai -->

docs/github_activity/Julien-ser_nltk_Group1_ENGG4450_PR_1_Marco_branch.md

@@ -0,0 +1,13 @@
+# PR: Marco branch
+
+**Repository:** Julien-ser/nltk_Group1_ENGG4450
+**Number:** #1
+**State:** closed
+**Labels:** None
+**Created:** 2025-11-22T17:44:33Z
+**Updated:** 2025-11-22T17:44:50Z
+**URL:** https://github.com/Julien-ser/nltk_Group1_ENGG4450/pull/1
+
+---
+
+Marco's edits

docs/github_activity/Julien-ser_nltk_Group1_ENGG4450_PR_2_Haris_edits_extending_from_punkt.md

@@ -0,0 +1,13 @@
+# PR: Haris' edits, extending from punkt
+
+**Repository:** Julien-ser/nltk_Group1_ENGG4450
+**Number:** #2
+**State:** closed
+**Labels:** None
+**Created:** 2025-11-22T17:47:14Z
+**Updated:** 2025-11-22T17:47:40Z
+**URL:** https://github.com/Julien-ser/nltk_Group1_ENGG4450/pull/2
+
+---
+
+

docs/github_activity/Julien-ser_nltk_Group1_ENGG4450_PR_3_Validation_testing.md

@@ -0,0 +1,13 @@
+# PR: Validation testing
+
+**Repository:** Julien-ser/nltk_Group1_ENGG4450
+**Number:** #3
+**State:** closed
+**Labels:** None
+**Created:** 2025-11-25T02:34:39Z
+**Updated:** 2025-11-25T02:34:50Z
+**URL:** https://github.com/Julien-ser/nltk_Group1_ENGG4450/pull/3
+
+---
+
+

docs/github_activity/Julien-ser_picoCTFopencodewriteups_PR_1_Add_runme.md_with_picoCTF_flag_from_runme.py.md

@@ -0,0 +1,13 @@
+# PR: Add runme.md with picoCTF flag from runme.py
+
+**Repository:** Julien-ser/picoCTFopencodewriteups
+**Number:** #1
+**State:** closed
+**Labels:** None
+**Created:** 2025-10-29T17:46:01Z
+**Updated:** 2025-10-29T17:46:18Z
+**URL:** https://github.com/Julien-ser/picoCTFopencodewriteups/pull/1
+
+---
+
+

docs/github_activity/Julien-ser_picoCTFopencodewriteups_PR_2_Add_staticnoise.md_with_picoCTF_flag_from_static_binary_analysis.md

@@ -0,0 +1,13 @@
+# PR: Add staticnoise.md with picoCTF flag from static binary analysis
+
+**Repository:** Julien-ser/picoCTFopencodewriteups
+**Number:** #2
+**State:** closed
+**Labels:** None
+**Created:** 2025-10-29T17:50:16Z
+**Updated:** 2025-10-29T17:50:26Z
+**URL:** https://github.com/Julien-ser/picoCTFopencodewriteups/pull/2
+
+---
+
+

docs/github_activity/Julien-ser_picoCTFopencodewriteups_PR_3_Master.md

@@ -0,0 +1,13 @@
+# PR: Master
+
+**Repository:** Julien-ser/picoCTFopencodewriteups
+**Number:** #3
+**State:** closed
+**Labels:** None
+**Created:** 2025-10-30T00:43:02Z
+**Updated:** 2025-10-30T00:43:14Z
+**URL:** https://github.com/Julien-ser/picoCTFopencodewriteups/pull/3
+
+---
+
+

docs/github_activity/Julien-ser_splunk-mcp-integration_PR_1_Wiggum_session.md

@@ -0,0 +1,33 @@
+# PR: Wiggum/session
+
+**Repository:** Julien-ser/splunk-mcp-integration
+**Number:** #1
+**State:** open
+**Labels:** None
+**Created:** 2026-03-29T02:40:02Z
+**Updated:** 2026-03-29T02:45:20Z
+**URL:** https://github.com/Julien-ser/splunk-mcp-integration/pull/1
+
+---
+
+
+
+<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
+
+## Summary by CodeRabbit
+
+## Release Notes
+
+* **New Features**
+  * Introduced Splunk MCP integration with server, client, and tool wrappers for search, indexing, system operations, and AI-powered analysis (SAIA).
+  * Added agent orchestration layer with message bus and communication protocol.
+
+* **Documentation**
+  * Comprehensive project README with setup instructions, architecture overview, and tool descriptions.
+  * Project structure and task management documentation.
+
+* **Chores**
+  * Added development environment configuration (Makefile, Python version specification, environment templates).
+  * Updated project gitignore patterns and setup files.
+
+<!-- end of auto-generated comment: release notes by coderabbit.ai -->

docs/github_activity/faizm10_uog-webring_PR_16_Add_user_Julien_Serbanescu.md

@@ -0,0 +1,50 @@
+# PR: Add user Julien Serbanescu
+
+**Repository:** faizm10/uog-webring
+**Number:** #16
+**State:** closed
+**Labels:** None
+**Created:** 2026-02-24T15:49:05Z
+**Updated:** 2026-02-24T17:18:05Z
+**URL:** https://github.com/faizm10/uog-webring/pull/16
+
+---
+
+## Member Submission
+
+Please fill this out so we can quickly review and merge your addition.
+
+### Member Data
+
+- Name: Julien Serbanescu
+- Year: 3rd
+- Website (full URL, https://...): https://julien-ser.github.io/JulienSerbanescu/
+- Role (optional, e.g. job title, "Student", "Founder"): Student Cloud Engineer
+
+Rest is on there
+
+### JSON Snippet Added to `data/members.json`
+
+Add your entry to the `sites` array in `data/members.json`. Use empty string `""` for any optional link you don't have. Omit `role` if you prefer not to include it.
+
+```json
+    {
+      "name": "Julien Serbanescu",
+      "website": "https://julien-ser.github.io/JulienSerbanescu/",
+      "year": 2028,
+      "role": "Cloud Engineer @ Co-operators and AI Researcher",
+      "links": {
+        "twitter": "https://x.com/Da_Julster",
+        "linkedin": "https://www.linkedin.com/in/julien-serbanescu-6ba52a241/",
+        "github": "https://github.com/Julien-ser"
+      }
+```
+
+### Checklist
+
+- [x] I added my entry to `data/members.json` in the `sites` array.
+- [X] My website URL is valid and starts with `https://`.
+- [X] If included, social links are full URLs; unused links use `""`.
+- [X] I kept the JSON valid (no trailing commas, correct quotes).
+- [X] I verified my row appears correctly in the table.
+

docs/github_activity/nltk_nltk_PR_3470_Pull_request_for_issue_3413_-_Python_package_for_extra_tokenizers.md

@@ -0,0 +1,14 @@
+# PR: Pull request for issue #3413 -> Python package for extra tokenizers
+
+**Repository:** nltk/nltk
+**Number:** #3470
+**State:** closed
+**Labels:** tokenizer
+**Created:** 2025-11-25T03:07:44Z
+**Updated:** 2025-11-25T04:49:04Z
+**URL:** https://github.com/nltk/nltk/pull/3470
+
+---
+
+Created a new python package to install additional tokenizers instead of the nltk.downloader() class.
+More information and documentation can be seen in the pypi page for this library https://pypi.org/project/nltk-extratokenizers/0.1.2/

docs/github_activity/vllm-project_vllm_PR_35358_Bugfix_Frontend_Fix_reasoning-end_detection_to_check_prompt_tail_o.md

@@ -0,0 +1,51 @@
+# PR: [Bugfix][Frontend] Fix reasoning-end detection to check prompt tail o…
+
+**Repository:** vllm-project/vllm
+**Number:** #35358
+**State:** open
+**Labels:** bug, frontend
+**Created:** 2026-02-26T03:58:27Z
+**Updated:** 2026-02-27T16:25:46Z
+**URL:** https://github.com/vllm-project/vllm/pull/35358
+
+---
+
+[Bugfix][Frontend] Fix reasoning-end detection to check prompt tail only (Fix #35349)
+
+## Purpose
+
+Fixes #35349.
+
+This PR fixes reasoning-end detection in OpenAI chat completion serving so we only treat the prompt as ended reasoning when the **last prompt token** is the reasoning end token (instead of matching anywhere in the prompt).
+It also adds a small helper to safely handle empty/`None` prompt token IDs.
+
+## Test Plan
+
+- Run focused unit tests for the new behavior:
+  - `python -m pytest tests/entrypoints/openai/test_serving_chat.py -k PromptEndsReasoning -q`
+- (Optional) Run the full serving chat tests:
+  - `python -m pytest tests/entrypoints/openai/test_serving_chat.py -q`
+
+## Test Result
+
+- Added targeted unit tests covering:
+  - end token in the middle of prompt → False
+  - end token at prompt tail → True
+  - empty / None prompt token IDs → False
+- Local run status: not executed in this environment yet.
+- To finalize before merge, run and paste output from:
+  - `python -m pytest tests/entrypoints/openai/test_serving_chat.py -k PromptEndsReasoning -q`
+
+---
+<details>
+<summary> Essential Elements of an Effective PR Description Checklist </summary>
+
+- [x] The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
+- [x] The test plan, such as providing test command.
+- [x] The test results, such as pasting the results comparison before and after, or e2e results
+- [x] (Optional) The necessary documentation update was considered (not needed for this internal bug fix).
+- [x] (Optional) Release notes update was considered (not required unless this behavior change is considered user-facing).
+
+</details>
+
+

docs/papers/arxiv_2510.21983v1_Uncovering_the_Persuasive_Fingerprint_of_LLMs_in_Jailbreaking_Attacks.md

@@ -0,0 +1,15 @@
+# Uncovering the Persuasive Fingerprint of LLMs in Jailbreaking Attacks
+
+**Authors:** Havva Alizadeh Noughabi, Julien Serbanescu, Fattane Zarrinkalam, Ali Dehghantanha
+**arXiv ID:** 2510.21983v1
+**Published:** 2025-10-24
+**Updated:** 2025-10-24
+**Categories:** cs.CL, cs.AI
+**PDF:** https://arxiv.org/pdf/2510.21983v1
+**Abstract URL:** https://arxiv.org/abs/2510.21983v1
+
+---
+
+## Abstract
+
+Despite recent advances, Large Language Models remain vulnerable to jailbreak attacks that bypass alignment safeguards and elicit harmful outputs. While prior research has proposed various attack strategies differing in human readability and transferability, little attention has been paid to the linguistic and psychological mechanisms that may influence a model's susceptibility to such attacks. In this paper, we examine an interdisciplinary line of research that leverages foundational theories of persuasion from the social sciences to craft adversarial prompts capable of circumventing alignment constraints in LLMs. Drawing on well-established persuasive strategies, we hypothesize that LLMs, having been trained on large-scale human-generated text, may respond more compliantly to prompts with persuasive structures. Furthermore, we investigate whether LLMs themselves exhibit distinct persuasive fingerprints that emerge in their jailbreak responses. Empirical evaluations across multiple aligned LLMs reveal that persuasion-aware prompts significantly bypass safeguards, demonstrating their potential to induce jailbreak behaviors. This work underscores the importance of cross-disciplinary insight in addressing the evolving challenges of LLM safety. The code and data are available.

docs/pdfs/resume.pdf

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:540c654c8072993a853f7a059fed4c50debfb4086b4b45ce87ecd5c0e4ca35ea
-size 170230

docs/readmes/AKO-Agentic-Kernel-Optimization-README.md

@@ -0,0 +1,94 @@
+# AKO-Agentic-Kernel-Optimization
+**Repository:** Julien-ser/AKO-Agentic-Kernel-Optimization
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** A proposed system that autonomously generates, profiles and refines GPU kernels using Agentic AI and LLMs in order to optimize high performance AI inference on AMD hardware.
+**Language:** Python
+**Last Updated:** 2026-02-07T01:42:48Z
+
+---
+
+
+# AKO: Agentic Kernel Optimization for High-Performance Inference on AMD Instinct
+
+## Overview
+
+
+AKO (Agentic Kernel Optimization) is an autonomous system for optimizing GPU kernel performance on AMD Instinct hardware. By leveraging Agentic AI and Large Language Models (LLMs), AKO automates the generation, profiling, and refinement of GPU kernels—specifically using AMD's TileLang domain-specific language—targeting the CDNA-3/4 architecture (MI300/350 series).
+
+The core innovation is a closed "Compile-Profile-Refine" agentic loop, moving beyond manual tuning or brute-force grid searches. The system is designed to unlock the full potential of AMD Instinct GPUs for high-performance AI inference workloads.
+
+## System Workflow
+
+1. **High-Level Specification:** The process begins with a high-level kernel specification (e.g., matrix multiplication or other AI-relevant GPU tasks).
+2. **Agentic LLM Code Generation:** An LLM-based agent generates specialized GPU kernel code in TileLang, tailored to the given task and hardware.
+3. **Compilation & Deployment:** The ROCm toolchain (HIP/LLVM) compiles the generated code and deploys it to the MI300X GPU.
+4. **Profiling & Metrics Collection:** During execution, ROCm's `rocprofiler` collects detailed metrics: execution time, memory bandwidth, utilization, occupancy, cache hit rates, and hardware stalls.
+5. **Performance Analysis & Feedback:** These metrics are compared to the AITER baseline. Bottlenecks and inefficiencies are identified and reported back to the LLM agent.
+6. **Reinforcement Learning Loop:** Using an RL system (e.g., verl), the agent receives reward signals based on performance improvements, conditioning it to generate increasingly optimized kernel code.
+
+This loop continues iteratively, enabling the agent to autonomously explore the optimization space (tiling sizes, memory layouts, MFMA scheduling, etc.) and converge on high-performance solutions.
+
+## Problem Space
+
+Current inference libraries (e.g., vLLM, SGLang) rely on hand-tuned or basic autotuned kernels. TileLang has demonstrated up to 5x speedups over Triton on AMD hardware, but the optimization space is vast and complex. AKO's agentic approach enables:
+
+- Automated navigation of kernel design choices (tiling, LDS usage, MFMA scheduling)
+- Hardware-aware code generation and profiling
+- Continuous improvement via RL-driven feedback
+
+## Research Goals
+
+- **Autonomous TileLang Synthesis:** Develop an LLM agent that generates TileLang code from high-level mathematical specs.
+- **Closed-Loop Profiling Feedback:** Integrate ROCm's `rocprofiler` to provide performance metrics as reward signals for iterative improvement.
+- **Inference Bottleneck Analysis:** Use Causal AI to model and optimize latency trade-offs in vLLM's PagedAttention vs. SGLang's RadixAttention on AMD Infinity Fabric.
+
+
+## Technical Stack
+
+- **Languages:** Python (integration), C++/HIP (kernel level), TileLang (DSL)
+- **Frameworks:** `verl` (RL agent training), `AITER` (AMD AI Inference Toolkit)
+- **Hardware:** Instinct MI300X, MI325X, MI350/355 series
+
+## Project Structure
+
+```
+AKO_Project/
+├── src/
+│   ├── agentic_loop.py           # Orchestrates the main optimization loop
+│   ├── kernel_generator.py       # LLM agent for kernel code generation
+│   ├── profiling_feedback.py     # Performance metric analysis from rocprof
+│   └── hardware_interface.py     # AMD hardware interaction (compilation, execution, profiling)
+├── diagrams/
+│   └── ako_architecture.mmd      # Mermaid diagram of system architecture
+└── README.md                     # This document
+```
+
+## System Architecture Diagram
+
+
+Below is the core system architecture, visualized in Mermaid:
+
+```mermaid
+graph TD
+	A[High-Level Kernel Specification] --> B(LLM Agent - KernelGenerator)
+	subgraph Agentic Loop
+		B -- Generates TileLang Code --> C{AMD ROCm Toolchain}
+		C -- Compiles & Deploys --> D[Executable Kernel on MI300X]
+		D -- Executes & Profiles --> E(ROCm Profiler - rocprof)
+		E -- Raw Metrics --> F(Performance Analysis & AITER Comparison)
+		F -- Optimization Feedback & Reward Signal --> B
+	end
+	G[AITER Baseline Library] -. Gold Standard Benchmarks .-> F
+	style A fill:#fde7f3,stroke:#333,stroke-width:2px,color:#111
+	style B fill:#e6ecff,stroke:#333,stroke-width:2px,color:#111
+	style C fill:#eef2ff,stroke:#333,stroke-width:2px,color:#111
+	style D fill:#eaf7ea,stroke:#333,stroke-width:2px,color:#111
+	style E fill:#ffecec,stroke:#333,stroke-width:2px,color:#111
+	style F fill:#edf9ed,stroke:#333,stroke-width:2px,color:#111
+	style G fill:#fff4dd,stroke:#333,stroke-width:2px,color:#111
+```
+
+---
+
+**To view or edit the diagram:** The `ako_architecture.mmd` file can be opened in any [Mermaid](https://mermaid.js.org/) editor (e.g., [Mermaid Live Editor](https://mermaid.live/)), or viewed directly on platforms like GitHub that support `.mmd` rendering.

docs/readmes/Free-Wiggum-README.md

@@ -0,0 +1,310 @@
+# Free-Wiggum
+**Repository:** Julien-ser/Free-Wiggum
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** A free implementation of the ever intriguing Ralph Wiggum loops
+**Language:** JavaScript
+**Last Updated:** 2026-03-12T03:23:50Z
+
+---
+
+
+
+# 🤖 Autonomous AI Task Loop with OpenCode
+
+Run autonomous AI task loops **completely free.** No subscriptions. No API bills. No infrastructure costs.
+
+While CrewAI, AutoGPT, and Claude API cost **$200-500+/month**, this setup uses [OpenCode](https://github.com/ripienaar/opencode) with OpenRouter's free models to build autonomous agents on your own machine for **$0**.
+
+This is a lightweight, recursive bash-driven loop that uses free LLM access to work through task lists methodically until completion.
+
+## 🛠 Prerequisites
+
+- **OpenCode AI** (`npm i -g opencode-ai`)
+- **GitHub CLI** (`gh`) — Required for authentication bypass (avoids broken OAuth handshake)
+- **OpenRouter API Key** (Free tier available at [openrouter.ai](https://openrouter.ai))
+- **Linux/macOS/Windows with bash** (Git Bash on Windows works fine)
+
+## 📝 Example Project
+
+**This repository itself is a real example of a project built using the Wiggum loop!**
+
+The [Free-Wiggum](.) folder contains a fully functional **Todo Application** that was built entirely by the autonomous AI agent:
+- **Express.js backend** with SQLite database
+- **Responsive HTML/CSS/JS frontend** with real-time task management
+- **Full test suite** for both backend and database operations
+- **All development tracked** in [TASKS.md](TASKS.md) (17 completed tasks)
+
+Look at [TASKS.md](TASKS.md) to see how the agent tracked every feature from project setup to deployment. This demonstrates exactly how the loop works in practice.
+
+Run it locally:
+```bash
+npm install
+npm start
+# Visit http://localhost:3000
+```
+
+## 📋 System Setup
+
+### Step 1: Install OpenCode AI
+
+```bash
+npm i -g opencode-ai
+```
+
+### Step 2: Authenticate with GitHub CLI
+
+Use the GitHub CLI to establish a persistent session that OpenCode borrows:
+
+```bash
+gh auth login
+```
+
+Choose **Device Code** flow when prompted. This avoids the broken OAuth browser handshake and creates a system-level authentication that OpenCode automatically uses.
+
+### Step 3: Set OpenRouter API Key & Token Limits
+
+Add your OpenRouter API key and token management settings to `.env` in your project directory:
+
+```
+OPENROUTER_API_KEY=sk-or-v1-...
+WIGGUM_MODEL=openrouter/stepfun/step-3.5-flash:free
+
+# Pre-emptive Token Management (Critical for long-running loops)
+# Forces OpenCode to truncate responses at 32k tokens, leaving 32k for input context (total 64k budget)
+OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX=32000
+```
+
+**Token Management Explained:**
+- **OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX=32000** — Prevents context bloat by capping each OpenCode response at 32k tokens
+- Leaves 32k tokens for input prompts (tasks, context, AGENTS.md)
+- Total budget: 64k tokens per iteration (the Wiggum rule)
+- When limit is reached, the loop automatically resets and continues fresh
+- Prevents model degradation after long sessions
+
+The `wiggum.sh` script loads this automatically at startup.
+
+## 💰 Cost Comparison
+
+| Tool | Monthly Cost | Setup | Model Quality |
+|------|-------------|-------|---------------|
+| **This Setup** | **$0** | 5 minutes | Excellent (Gemini, Qwen, Step) |
+| Claude API | $20-600+ | Easy | Excellent |
+| CrewAI + GPT-4 | $400+ | Medium | Excellent |
+| AutoGPT | $200+ | Complex | Good |
+| AWS SageMaker Agents | $500+ | Hard | Good |
+
+**This setup uses OpenRouter's free tier**, which provides legitimate, powerful models:
+- **Google Gemini 2.0 Flash** (best overall)
+- **Qwen 3** (excellent for reasoning)
+- **Step 3.5 Flash** (reliable and lightweight)
+
+1000 agent iterations = **$0.00**. Same iterations on Claude API = **$300+**.
+## 🚀 Quick Start
+
+### 1. Install Dependencies
+
+```bash
+# Install OpenCode AI globally
+npm i -g opencode-ai
+
+# Authenticate with GitHub (use Device Code flow)
+gh auth login
+```
+
+### 2. Create Your Project Structure
+
+Create these three core files in your project directory. Use **[TASKStemplate.md](TASKStemplate.md)** as your template for TASKS.md:
+
+**A. TASKS.md** (The Memory)
+
+This tracks the agent's own state. The agent reads this, completes one task at a time, and marks it as done `[x]`. Start with the structure in [TASKStemplate.md](TASKStemplate.md):
+
+```markdown
+# Current Tasks
+
+- [ ] Task 1: Your instruction here
+- [ ] Task 2: Your instruction here  
+- [ ] Task 3: Your instruction here
+- [ ] MISSION ACCOMPLISHED
+```
+
+**Important:** The script stops when it finds `[x] MISSION ACCOMPLISHED`. Until the agent marks this, the loop continues.
+
+**B. AGENTS.md** (The Brain)
+
+This file is auto-generated by OpenCode and contains project context the agent uses to understand your codebase architecture. Create it by running:
+
+```bash
+opencode .
+```
+
+Then inside the OpenCode interface, type:
+
+```
+/init
+```
+
+This generates `AGENTS.md` which the loop references via `@AGENTS.md` syntax.
+
+**C. prompt.txt** (The Logic)
+
+This is the system instruction sent to the agent on every iteration. It defines the agent's behavior and tells it what to do.
+
+**C. wiggum.sh** (The Engine)
+
+The bash script that drives the autonomous loop. Copy this repo's `wiggum.sh` and make it executable.
+
+### 3. Create .env File
+
+```bash
+cat > .env << 'EOF'
+OPENROUTER_API_KEY=sk-or-v1-your_key_here
+WIGGUM_MODEL=openrouter/stepfun/step-3.5-flash:free
+EOF
+```
+
+### 4. Launch the Loop
+
+## 📍 How It Works
+
+1. **GitHub Authentication**: Uses persistent `gh cli` session instead of OAuth2 (avoids browser handshake failures)
+2. **Initialization**: Loads `.env` with OpenRouter API key and model selection
+3. **Project Context**: Reads `@AGENTS.md` to understand your codebase structure
+4. **Iteration Loop**:
+   - Extracts the FIRST incomplete task (marked with `- [ ]`) from TASKS.md
+   - Builds a dynamic prompt containing:
+     - System instructions from `prompt.txt`
+     - Project context from `@AGENTS.md`
+     - Current `TASKS.md` state
+     - The specific task to complete
+   - Saves the complete iteration session to `logs/iteration-{iteration}.md` with formatted output for debugging
+   - Runs `opencode --message "$prompt" --enable-search --yes`:
+     - `--message`: Sends the task directly (non-interactive mode)
+     - `--enable-search`: Enables DuckDuckGo/MCP web search for live documentation
+     - `--yes`: Auto-approves file writes and shell command execution
+   - Waits for OpenCode to complete and update TASKS.md
+5. **Completion**: Checks if `[x] MISSION ACCOMPLISHED` is marked; if so, exits gracefully
+
+## 🎯 Choosing a Model
+
+The script defaults to `openrouter/stepfun/step-3.5-flash:free`. You can change this in `wiggum.sh` at the line with `--model`.
+
+To avoid the "yapping" loop (where the model talks but doesn't code), use models with high instruction-following and action-taking capabilities.
+
+**Recommended Free/Cheap Models:**
+
+- `openrouter/google/gemini-2.0-flash-exp:free` - Best overall performance
+- `openrouter/qwen/qwen-3-next-80b-a3b-instruct` - Good for complex logic
+- `openrouter/arcee-ai/trinity-mini` - Good for agent tasks
+- `openrouter/stepfun/step-3.5-flash:free` - Lightweight and reliable
+
+## 🔍 Token & Context Management
+
+### The 64k Rule
+
+The Wiggum loop operates under a **64k token budget per iteration**:
+
+- **32k tokens** — Maximum output from OpenCode (via `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX=32000`)
+- **32k tokens** — Reserved for input context (tasks, AGENTS.md, prompt.txt)
+- **Why:** Models degrade significantly after 64k tokens in a single session
+
+### How It Works
+
+1. **Pre-emptive Capping** — `.env` variable forces OpenCode to truncate responses at 32k
+2. **Soft Guardrails** — Dynamic prompt includes explicit token constraints warning
+3. **Active Monitoring** — Script checks log file size and estimates tokens
+4. **Error Detection** — Loop detects OpenRouter "context_length_exceeded" errors and resets
+5. **Auto-Reset** — When 64k threshold is hit, token counter resets for next iteration
+
+### What Happens at the Limit
+
+- Loop warns: `⚠️ Token limit (64000) reached!`
+- Resets token counter: `🔄 Resetting token counter for next iteration cycle...`
+- Continues with fresh iteration (no context loss, just fresh session)
+- `TASKS.md` tracks all progress, so agent knows what's been done
+
+This prevents the "yapping loop" symptom where models start repeating commands or forgetting the original goal.
+
+OpenCode includes powerful built-in capabilities, automatically enabled via the `wiggum.sh` loop:
+
+### GitHub Integration (via `gh` CLI)
+
+The authentication bridge is already established when you run `gh auth login`:
+
+```bash
+gh auth login
+# Choose: "GitHub.com" → "HTTPS" → "Yes to use git credential" → "Device Code" 
+```
+
+Benefits for your agent:
+- Automatically reads your GitHub context
+- Can push commits to your repositories
+- Access to GitHub Issues and PRs
+- No need for manual Personal Access Tokens
+
+### Code Search (via `--enable-search`)
+
+The `wiggum.sh` script automatically enables search with the `--enable-search` flag:
+
+```bash
+opencode --message "$prompt" --enable-search --yes
+```
+
+This gives OpenCode:
+- **DuckDuckGo web search** via MCP (free, no API key needed)
+- **Codebase semantic search** to find existing implementations
+- **Real-time documentation access** for libraries and tools
+
+The loop uses this to:
+- Find implementation patterns without external paid APIs
+- Avoid code duplication by discovering similar functions
+- Reference external libraries and best practices during execution
+
+### Configuring Search in Your Agent
+
+Add these capabilities to your `prompt.txt`:
+
+```
+You have access to:
+- Web search: Use the search tool to find relevant documentation and examples
+- Code search: Find existing functions before implementing new ones
+- GitHub context: Your repositories and issues are available
+- Execute freely: Use shell commands and write files without asking permission
+```
+
+## 🔍 Debugging
+
+**Iteration Logs**: All runs are logged to `logs/iteration-{iteration}.md` with formatted markdown containing:
+- The exact prompt sent
+- OpenCode's complete output
+- TASKS.md state after the iteration
+
+Review these if a task fails.
+
+**AGENTS.md Issues**: If tasks seem to lack project understanding, regenerate context:
+```bash
+opencode .
+# Inside interface, type: /reinit
+```
+
+**OpenCode Not Executing**: If the AI doesn't write files or run commands, ensure:
+- You're using `--yes` flag (auto-approves execution)
+- `.env` has valid `OPENROUTER_API_KEY`
+- `gh auth login` was successful
+
+**Search Not Working**: 
+- Verify `--enable-search` is in the `wiggum.sh` opencode call
+- Check that `OPENROUTER_API_KEY` is set (search requires API access)
+
+**Loop Stuck**: Check `logs/iteration-*.md` to see what prompt was sent and what OpenCode responded with.
+
+## ⚠️ Known Issues
+
+- **OAuth Handshake Failures**: Avoided by using `gh auth login` with Device Code flow instead of browser-based OAuth
+- **Login Walls**: Models may hang on login screens; use `prompt.txt` to instruct the agent to skip authentication
+- **Stuck Loops**: If no tasks complete, check `prompt-*.md` logs to see what context the agent received
+- **Windows Compatibility**: Use Git Bash or WSL for full bash script support
+- **Timeout Issues**: If OpenCode takes too long, increase the `sleep 3` duration in `wiggum.sh`
+
+

docs/readmes/Git-Workshop-README.md

@@ -0,0 +1,23 @@
+# Git-Workshop
+**Repository:** Julien-ser/Git-Workshop
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** JavaScript
+**Last Updated:** 2026-02-21T04:50:49Z
+
+---
+
+# Git Workshop Network
+
+A visual network graph showing contributors and their connections. Perfect for your first open source contribution!
+
+## Quick Start
+
+1. Open `src/index.html` in your browser
+2. Click on nodes or sidebar cards to see contributor details
+3. Zoom and pan to explore the network
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add yourself to the network.

docs/readmes/Our-Papers-README.md

@@ -0,0 +1,15 @@
+# Our-Papers
+**Repository:** CyberScienceLab/Our-Papers
+**Contribution:** 🤝 Contributor
+**Stars:** 2
+**Description:** None
+**Language:** Python
+**Last Updated:** 2025-11-13T15:12:49Z
+
+---
+
+# Our-Papers
+
+Here you may find our papers codes in this repo. The name of the director is the paper title and you can find the paper citation in the Readme file in the same folder!  
+
+Note: all codes in this repo are GNU v.3 license. Please cite the relevant paper when using our codes.

docs/readmes/ResumeWorthy-README.md

@@ -4,7 +4,7 @@
 **Stars:** 0
 **Description:** Allows your resume to be split into components, easier to modularize and customize to jobs
 **Language:** TypeScript
-**Last Updated:** 2025-12-29T21:59:16Z
+**Last Updated:** 2026-03-01T22:49:44Z
 
 ---
 

docs/readmes/Stockmetricagent-README.md

@@ -0,0 +1,154 @@
+# Stockmetricagent
+**Repository:** Julien-ser/Stockmetricagent
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-02-16T18:18:45Z
+
+---
+
+# Agentic Stock Dashboard
+
+A professional Streamlit app powered by LangChain agents and OpenRouter API. Users chat with an intelligent agent to generate stock insights, visualizations, and sentiment analysis in real-time. Modular, extensible, and ready for advanced financial workflows.
+
+## Features
+
+- 💬 **Interactive Chat Interface** - Real-time Q&A for stock queries
+- 🤖 **LangChain Agents** - Intelligent agentic workflows for complex analysis
+- 📊 **Dynamic Dashboards** - Beautiful visualizations powered by Plotly
+- 😊 **Sentiment Analysis** - Real-time sentiment scoring using VADER
+- 🔗 **API Integration** - YahooQuery for stock data, OpenRouter for LLM
+- 🏗️ **Modular Design** - Easily extensible tools and utilities
+
+## Prerequisites
+
+- Python 3.10+
+- OpenRouter API key (for LLM access)
+- Virtual environment (stocks venv included)
+
+## Installation
+
+1. **Activate the virtual environment:**
+   ```powershell
+   .\stocks\Scripts\activate
+   ```
+
+2. **Create a `.env` file** in the project root with your API keys:
+   ```
+   OPENROUTER_API_KEY=your_api_key_here
+   ```
+
+3. **Dependencies are pre-installed** in the venv. Core packages include:
+   - `langchain` - Agent orchestration
+   - `streamlit` - Web interface
+   - `yahooquery` - Stock data
+   - `plotly` - Visualizations
+   - `vaderSentiment` - Sentiment analysis
+   - `requests` - HTTP client
+
+## Running the App
+
+```powershell
+streamlit run app.py
+```
+
+The app will launch at `http://localhost:8501`
+
+## Project Structure
+
+```
+agentic_stock_dashboard/
+├── app.py              # Main Streamlit application
+├── agents.py           # LangChain agent configuration
+├── tools.py            # Custom tools for stock analysis
+├── utils.py            # Helper functions and utilities
+├── README.md           # This file
+└── .gitignore          # Git ignore rules
+```
+
+### Key Files
+
+- **app.py**: Main Streamlit entry point. Handles chat UI and agent orchestration
+- **agents.py**: LangChain agent setup with tool bindings
+- **tools.py**: Custom tools for stock analysis, data retrieval, and dashboard generation
+- **utils.py**: Utility functions for data processing and formatting
+
+## Usage
+
+1. Start the app with `streamlit run app.py`
+2. Enter queries about stocks, sectors, or market insights
+3. The agent will analyze your query and return:
+   - Text-based insights and analysis
+   - Interactive dashboard visualizations
+   - Sentiment analysis results
+
+## Agents & Tools
+
+### Core Agent: `stock_agent(query)`
+The main LangChain agent that orchestrates all tools. It:
+1. Parses user queries to extract stock symbols and analysis type
+2. Suggests relevant stocks for sector queries using LLM
+3. Fetches data and generates comprehensive insights
+4. Returns formatted analysis with visualizations
+
+### Tools Used by the Agent
+
+#### 1. **get_stock_metrics(symbol)**
+Fetches fundamental and valuation metrics for a stock using YahooQuery API.
+
+**Returns:**
+- Price, Market Cap, Enterprise Value
+- PE Ratios (Trailing & Forward)
+- Valuation ratios (Price/Sales, Price/Book, EV/Revenue, EV/Earnings)
+- Profitability margins (Profit Margin, Operating Margin)
+- Financial data (Revenue, Gross Profit, Debt, Debt/Equity)
+- Ownership metrics (Insider %, Institution %, Payout Ratio, Dividend Yield)
+
+#### 2. **get_sector_top_stocks(sector)**
+Retrieves top stocks within a given sector. Used to identify leading companies in industry sectors when users query broad categories.
+
+**Usage:** When user asks about sectors (e.g., "AI stocks", "Tech companies")
+
+#### 3. **get_sentiment(symbol)**
+Performs sentiment analysis on stock symbols using VADER (Valence Aware Dictionary and sEntiment Reasoner) from vaderSentiment library.
+
+**Returns:** Sentiment scores indicating positive/negative/neutral sentiment around a stock
+
+#### 4. **get_deepseek_insight(query)**
+Placeholder for AI-powered insights (currently returns template response). Can be extended to call external insight APIs.
+
+#### 5. **plot_stock_dashboard(stocks_data)**
+Creates interactive visualizations for stock data using Plotly.
+
+**Visualizations Generated:**
+- **Key Metrics Table** - Formatted display of all stock metrics with appropriate units ($, %, decimals)
+- **Valuation Radar Chart** - 5-axis radar chart comparing:
+  - Dividend Yield (ideal: 5%+)
+  - Operating Margin (ideal: 15-25%)
+  - PE Ratio (ideal: 15-25)
+  - Profit Margin (ideal: 15-25%)
+  - Institution Ownership (ideal: 33-34%)
+
+**Chart Features:**
+- Mobile-optimized (350px height, responsive margins)
+- Color-coded for visual appeal
+- Real-world metric ranges for accurate scoring
+
+## Example Queries
+
+- "What are today's top performing stocks?"
+- "Give me a technical analysis of AAPL"
+- "What's the sentiment around Tesla stock?"
+- "Compare NVIDIA vs AMD performance"
+
+## Environment Variables
+
+Create a `.env` file with:
+- `OPENROUTER_API_KEY`: Your OpenRouter API key (required)
+
+**Note:** The `.env` file is in `.gitignore` to protect your API keys
+
+## License
+
+MIT License - Feel free to use and modify as needed

docs/readmes/WiggumLoopAgenticSWDeveloper-README.md

@@ -0,0 +1,526 @@
+# WiggumLoopAgenticSWDeveloper
+**Repository:** Julien-ser/WiggumLoopAgenticSWDeveloper
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Shell
+**Last Updated:** 2026-03-27T23:02:31Z
+
+---
+
+# 🐳 WiggumLoopAgenticSWDeveloper
+
+> **Zero-cost, fully autonomous multi-project AI development.** Orchestrate unlimited OpenCode agents running free LLMs to build, test, and ship software—without writing a single line of code yourself.
+
+
+<!-- UI Overview -->
+![Wiggum Full Interface Overview (ui3.png)](./ui3.png)
+<p align="center"><i>WiggumLoop: Full system UI overview (ui3.png)</i></p>
+
+<!-- Optionally keep the old screenshot for reference -->
+<!-- ![Wiggum UI](./ui.png) -->
+---
+
+## 🖼️ User Interface
+
+WiggumLoop comes with a visual dashboard for monitoring and controlling projects. Below are detailed UI screenshots:
+
+<p align="center">
+    <img src="./ui1.png" alt="Project UI Detail 1" width="48%"/>
+    <img src="./ui2.png" alt="Project UI Detail 2" width="48%"/>
+</p>
+<p align="center"><i>Detailed project views: left (ui1.png), right (ui2.png)</i></p>
+
+The main overview (see top) shows the entire orchestration system, while these detailed views focus on individual project management and status.
+
+---
+
+---
+
+## ⚡ TL;DR
+
+What if you could spawn **10+ autonomous AI developers** that each own a project, write code, run tests, and push to GitHub—**for free**?
+
+That's WiggumLoop:
+
+1. **Create a project** → `bash wiggum_master.sh create "my-api" "Build a REST API"`
+2. **Write tasks** in `projects/my-api/TASKS.md`
+3. **Start the master loop** → `bash wiggum.sh`
+4. **Watch it work** → Agents code, commit, push, repeat
+
+No babysitting. No API bills. Just autonomous development.
+
+---
+
+## 🤖 What Is This?
+
+WiggumLoopAgenticSWDeveloper is a **master orchestration system** that:
+
+| ✅ What it Does | 🎯 Why It Matters |
+|----------------|-------------------|
+| Manages **multiple projects** simultaneously | Each project gets its own GitHub repo and autonomous agent |
+| Spawns **independent AI agents** using OpenCode | Projects develop in parallel, 24/7 |
+| Orchestrates **master + worker loops** | System-level tasks create/coordinate projects |
+| Includes **web dashboard + voice control** (optional) | Monitor and control from a browser |
+| Costs **$0/month** (OpenRouter free tier) | Unlimited iterations, no API fatigue |
+| Runs **Gemini 2.0 Flash, Qwen 3, Step 3.5 Flash** | Top-tier free models, not toy LLMs |
+
+**Each project is a separate GitHub repository** that develops independently while the master system coordinates everything.
+
+---
+
+## 🏗️ System Architecture
+
+```mermaid
+graph TB
+    subgraph "Master Control"
+        Master["🎛️ Master<br/>(wiggum_master.sh)"]
+        MasterLoop["🔄 Master Loop<br/>(wiggum.sh)"]
+    end
+
+    subgraph "Projects & Agents"
+        P1["📦 Project A<br/>projects/project-a/"]
+        P2["📦 Project B<br/>projects/project-b/"]
+        P3["📦 Project C<br/>projects/project-c/"]
+        
+        A1["🤖 Agent A<br/>OpenCode Loop"]
+        A2["🤖 Agent B<br/>OpenCode Loop"]
+        A3["🤖 Agent C<br/>OpenCode Loop"]
+    end
+
+    subgraph "External Services"
+        GitHub["🔗 GitHub<br/>Multiple Repos"]
+        API["🌐 OpenRouter<br/>Free LLMs"]
+    end
+
+    Master -->|creates| P1
+    Master -->|creates| P2
+    Master -->|creates| P3
+    
+    MasterLoop -->|spawns| A1
+    MasterLoop -->|spawns| A2
+    MasterLoop -->|spawns| A3
+    
+    P1 -->|runs in| A1
+    P2 -->|runs in| A2
+    P3 -->|runs in| A3
+    
+    A1 -->|commits to| GitHub
+    A2 -->|commits to| GitHub
+    A3 -->|commits to| GitHub
+    
+    A1 -->|queries| API
+    A2 -->|queries| API
+    A3 -->|queries| API
+```
+
+---
+
+## 🔄 Detailed Workflow
+
+### Master Loop Flow
+
+```mermaid
+flowchart TD
+    Start["Start wiggum.sh"] --> ReadSys["Read system TASKS.md"]
+    ReadSys --> CheckNew["Check for new projects?"]
+    
+    CheckNew -->|Yes| CreateProj["Create project via<br/>wiggum_master.sh"]
+    CreateProj --> InitGit["Initialize GitHub repo"]
+    InitGit --> SpawnWorkers
+    
+    CheckNew -->|No| SpawnWorkers
+    
+    SpawnWorkers["Spawn worker agents<br/>for each projects/*/"] --> AgentRun["Each agent:<br/>- Read TASKS.md<br/>- Complete next task<br/>- Commit & push<br/>- Mark complete"]
+    
+    AgentRun --> CheckComplete["All agents<br/>MISSION ACCOMPLISHED?"]
+    
+    CheckComplete -->|No| Sleep["Sleep interval"]
+    Sleep --> Start
+    
+    CheckComplete -->|Yes| Done["✅ System complete"]
+```
+
+### Agent Iteration Loop
+
+```mermaid
+flowchart LR
+    subgraph "Agent Loop (per project)"
+        A1["Read TASKS.md"] --> A2["Extract first<br/> unchecked task"]
+        A2 --> A3["Build prompt:<br/>prompt.txt + TASKS.md + task"]
+        A3 --> A4["Run OpenCode<br/>(free LLM)"]
+        A4 --> A5["Write code<br/>Commit & push"]
+        A5 --> A6["Mark task [x]"]
+        A6 --> A7["Check MISSION ACCOMPLISHED?"]
+        A7 -->|No| A1
+        A7 -->|Yes| Done["✅ Project complete"]
+    end
+```
+
+---
+
+## 💰 Why This Is a Game-Changer
+
+| | **WiggumLoop** | **Traditional AI Coding** |
+|---|---|---|
+| **Cost** | $0 (free LLMs) | $20–600+/month |
+| **Setup Time** | 10 minutes | 30 min–2 hours |
+| **Projects** | Unlimited (one repo each) | Usually one project per API key |
+| **Autonomy** | 24/7 worker loops | Manual prompting per task |
+| **Scalability** | Add more projects, no extra cost | Linear cost increase |
+
+**You could run this for a year and still pay nothing.** The only thing it costs is your time to set up and guide it.
+
+---
+
+## 🚀 Quick Start (5 minutes)
+
+### 1️⃣ Install Prerequisites
+
+```bash
+# Node.js (for OpenCode)
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# OpenCode AI (global install)
+npm install -g opencode-ai
+
+# GitHub CLI (auth)
+gh auth login --web
+
+# Python deps (for optional web dashboard)
+pip install -r requirements.txt
+```
+
+### 2️⃣ Configure
+
+```bash
+# Get free OpenRouter key: https://openrouter.ai
+cat > .env << 'EOF'
+OPENROUTER_API_KEY=sk-or-v1-YOUR_KEY_HERE
+WIGGUM_MODEL=openrouter/google/gemini-2.0-flash-exp:free
+EOF
+
+# Initialize system context for OpenCode
+opencode /init --yes
+```
+
+### 3️⃣ Create Your First Project
+
+```bash
+bash wiggum_master.sh create "todo-api" "Build a FastAPI REST API with SQLite and CRUD operations"
+```
+
+This creates `projects/todo-api/` with its own GitHub repo.
+
+### 4️⃣ Add Tasks
+
+Edit `projects/todo-api/TASKS.md`:
+
+````markdown
+## Todo API
+
+- [ ] Set up FastAPI app with CORS
+- [ ] Create SQLite models (Item, User)
+- [ ] Implement POST /items endpoint
+- [ ] Implement GET /items endpoint
+- [ ] Add PATCH /items/{id} endpoint
+- [ ] Add DELETE /items/{id} endpoint
+- [ ] Write unit tests (pytest)
+- [ ] Add request validation (Pydantic)
+- [ ] Create requirements.txt
+- [ ] Write README with example curl commands
+- [x] MISSION ACCOMPLISHED
+````
+
+### 5️⃣ Start the Master Loop
+
+```bash
+bash wiggum.sh
+```
+
+That's it. The master will:
+- Read system `TASKS.md`
+- Create new projects if needed
+- Spawn a worker agent for `todo-api`
+- Agent reads `projects/todo-api/TASKS.md`, completes first task, commits, pushes, repeats
+
+---
+
+## 📂 Repository Structure
+
+```
+WiggumLoopAgenticSWDeveloper/
+├── wiggum.sh                    # 🚀 Master orchestrator (run this)
+├── wiggum_master.sh             # Project management CLI
+├── server.py                    # Flask web dashboard
+├── voice_server.py              # Voice control (optional)
+├── prompt.txt                   # Master agent instructions
+├── TASKS.md                     # System-level tasks
+├── AGENTS.md                    # Auto-generated system context
+├── .env                         # Configuration
+├── ui.png                       # Dashboard screenshot
+│
+├── project_template/            # Scaffold for new projects
+│   ├── README.md
+│   ├── TASKS.md
+│   ├── prompt.txt
+│   └── src/
+│
+├── projects/                    # Managed projects (separate GitHub repos)
+│   ├── todo-api/
+│   │   ├── TASKS.md
+│   │   ├── prompt.txt
+│   │   ├── logs/
+│   │   └── src/
+│   └── another-project/
+│
+└── agents/                      # Specialized agent roles
+    ├── generic.md
+    ├── devops-engineer.md
+    └── ...
+```
+
+---
+
+## 🎯 Creating & Managing Projects
+
+### Create a Project
+
+```bash
+bash wiggum_master.sh create "project-name" "What this project should do"
+```
+
+**What happens:**
+- Creates `projects/project-name/`
+- Copies `project_template/` files
+- Initializes Git repo
+- Creates GitHub remote: `github.com/YOU/project-name`
+- Pushes initial commit
+
+### Add Tasks
+
+Edit `projects/project-name/TASKS.md`:
+
+```markdown
+## Project Name
+
+- [ ] First task (agent does this first)
+- [ ] Second task
+- [ ] Third task
+- [x] MISSION ACCOMPLISHED
+```
+
+**Pro tip:** Break tasks into small, verifiable chunks. Agents work better with clear, atomic objectives.
+
+### Control Projects
+
+```bash
+bash wiggum_master.sh list          # List all projects
+bash wiggum_master.sh status       # Show status (running/stopped)
+bash wiggum_master.sh stop "name"  # Stop a worker
+bash wiggum_master.sh start "name" # Start a worker
+```
+
+---
+
+## 🎭 Agent Roles: Specialize Your Workers
+
+Each project can switch between specialized roles for different phases.
+
+| Role | Best For |
+|------|----------|
+| `generic` | General full-stack development |
+| `devops-engineer` | CI/CD, deployment, infra |
+| `qa-specialist` | Testing, quality gates |
+| `release-manager` | Versioning, releases |
+| `documentation-specialist` | Docs, READMEs, API specs |
+| `project-orchestrator` | Planning, delegation |
+
+**Switch roles:**
+
+```bash
+cd projects/my-project
+echo "devops-engineer" > .agent_role
+git add .agent_role && git commit -m "ops: switch to devops-engineer" && git push
+```
+
+Next iteration, the agent loads specialized instructions from `agents/devops-engineer.md`.
+
+---
+
+## 🔁 Resilience: Stuck Detection & Recovery
+
+The worker **automatically detects** when a task is stuck (no progress for 5 iterations) and applies recovery strategies:
+
+1. **Decompose** – breaks the task into subtasks
+2. **Skeleton files** – creates minimal structure to unblock
+3. **Skip & retry later** – moves on, will retry later
+
+You don't have to micromanage. The system self-corrects.
+
+---
+
+## 🚨 CI/CD Error Handling
+
+When builds/tests fail, the worker extracts the error and:
+
+- **Code errors?** → Agent fixes the code
+- **Dependency/version errors?** → Agent updates version constraints
+- **Environment setup errors?** → Mark as `[CI-SKIP]`, document as prerequisite
+
+It **never** installs system tools or downloads large files. It only modifies code, configs, and version numbers.
+
+---
+
+## 🛠️ Advanced Features
+
+### Web Dashboard (Optional)
+
+```bash
+pip install -r requirements.txt
+python3 server.py
+# Visit: http://localhost:5000
+```
+
+Features:
+- Real-time project status
+- Create/stop/start projects from UI
+- View logs inline
+- Trigger CodeRabbit reviews
+
+### Background Operation
+
+```bash
+# Run master loop in background
+nohup bash wiggum.sh > logs/master.log 2>&1 &
+```
+
+### Logs
+
+Each project logs iterations to `projects/<name>/logs/`. Inspect with:
+
+```bash
+tail -f projects/todo-api/logs/iteration-*.log
+```
+
+---
+
+## ⚙️ Configuration
+
+### `.env` Options
+
+```bash
+OPENROUTER_API_KEY=sk-or-v1-...   # Required (free from openrouter.ai)
+WIGGUM_MODEL=openrouter/google/gemini-2.0-flash-exp:free
+GITHUB_USER=your-username
+MASTER_SLEEP_INTERVAL=300         # Seconds between master loops
+```
+
+### Recommended Free Models
+
+- `openrouter/google/gemini-2.0-flash-exp:free` ⭐ Best overall
+- `openrouter/qwen/qwen-3-80b` – Strong reasoning
+- `openrouter/stepfun/step-3.5-flash:free` – Fast & reliable
+
+---
+
+## 🐛 Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `opencode: command not found` | `npm install -g opencode-ai` |
+| GitHub auth fails | `gh auth logout && gh auth login --web` |
+| API key invalid | Get new key at openrouter.ai, update `.env` |
+| Agent loops hanging | Check `logs/master.log`, kill process, verify `wiggum.sh` is running |
+| Project repo not created | `gh auth status` – ensure you're logged in |
+
+---
+
+## 📚 Resources
+
+- [OpenCode GitHub](https://github.com/ripienaar/opencode)
+- [OpenRouter Docs](https://openrouter.ai/docs)
+- [GitHub CLI Manual](https://cli.github.com/manual)
+- [Free Model List](https://openrouter.ai/models)
+
+---
+
+## 📋 Core System Files
+
+### `wiggum.sh` — The Engine
+
+The master orchestrator. It:
+- Reads `TASKS.md` for system tasks
+- Creates projects via `wiggum_master.sh`
+- Spawns worker agents for each project
+- Sleeps and repeats
+
+**This is the only script you need to run** for full autonomy.
+
+### `wiggum_master.sh` — Project Manager
+
+CLI for creating, listing, starting, stopping projects. Handles GitHub repo creation and project scaffolding.
+
+### `prompt.txt` — Agent Instructions
+
+The system prompt sent to OpenCode on every iteration. Defines agent behavior, constraints, and workflow.
+
+### `TASKS.md` — Task Tracking
+
+Markdown checklist. The master loop reads this to know what to do. Each project has its own `TASKS.md`. The loop stops when it finds `[x] MISSION ACCOMPLISHED`.
+
+### `project_template/` — Blueprint
+
+When you create a project, it's copied from here. Customize this template to change default project structure.
+
+---
+
+## 🎬 Example: From Zero to Autonomous Project
+
+```bash
+# 1. Create project
+bash wiggum_master.sh create "weather-bot" "Telegram bot that posts daily forecast"
+
+# 2. Add tasks (edit projects/weather-bot/TASKS.md)
+#    - [ ] Set up python-telegram-bot
+#    - [ ] Integrate OpenWeatherMap API
+#    - [ ] Schedule daily message at 8 AM
+#    - [ ] Add error handling + logging
+#    - [x] MISSION ACCOMPLISHED
+
+# 3. Start master loop
+bash wiggum.sh
+
+# 4. Done. Watch GitHub repo get commits.
+```
+
+The agent will:
+- Build a Telegram bot skeleton
+- Add weather API integration
+- Implement scheduling
+- Add error handling
+- Mark each task complete as it goes
+- Push to GitHub
+
+---
+
+## 🦄 Why This Is One of My Favorite Projects
+
+- **It just works.** Set it and forget it. Agents run for days without intervention.
+- **Zero cost = zero guilt.** Run as many experiments as you want. Fail fast, learn faster.
+- **You stay in control.** Tasks are plain Markdown. No proprietary UI lock-in.
+- **It scales linearly.** Want 5 more projects? Just create them. No extra API cost.
+- **It's transparent.** Every prompt is saved as `prompt-*.md`. Every commit is on GitHub.
+
+This isn't just a coding assistant—it's an **autonomous development team** that never sleeps, never asks for a raise, and never bills you by the hour.
+
+---
+
+## 📖 License
+
+MIT. Do whatever you want with it.
+
+---
+
+**Built with OpenCode. Powered by free LLMs. Orchestrated by Wiggum.**

docs/readmes/agentic-founders-finding-README.md

@@ -0,0 +1,201 @@
+# agentic-founders-finding
+**Repository:** Julien-ser/agentic-founders-finding
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-12T17:42:10Z
+
+---
+
+# Founder Finding Agent
+
+An AI-powered agent that searches for startup founders across multiple platforms (X/Twitter, LinkedIn, Y Combinator, DuckDuckGo) based on a specified domain or sector.
+
+## Features
+
+- **Multi-platform search**: Query X (Twitter), LinkedIn, Y Combinator, and DuckDuckGo simultaneously
+- **AI-powered extraction**: Uses OpenAI or Anthropic LLMs to extract structured founder information
+- **Deduplication**: Fuzzy matching to consolidate duplicate founder records
+- **Scoring & ranking**: Ranks founders by relevance, social presence, and recency
+- **Flexible output**: Export results as JSON or CSV
+
+## Prerequisites
+
+- Python 3.11+ (if running locally)
+- Docker & Docker Compose (recommended for containerized deployment)
+- API keys for at least one LLM provider (OpenAI or Anthropic)
+- X (Twitter) API credentials (required for Twitter platform)
+
+## Quick Start (Docker)
+
+1. **Clone and navigate**:
+   ```bash
+   cd projects/agentic-founders-finding
+   ```
+
+2. **Create `.env` file** from template:
+   ```bash
+   cp .env.example .env
+   ```
+   
+   Edit `.env` and add your API keys (see [Configuration](#configuration) below).
+
+3. **Run with Docker Compose**:
+   ```bash
+   # Search for AI startup founders
+   docker-compose run --rm founder-finder "AI startups" --max-results 20
+   
+   # Save results to file
+   docker-compose run --rm founder-finder "fintech" --max-results 30 --output results.json
+   
+   # Use Anthropic instead of OpenAI
+   docker-compose run --rm founder-finder "biotech" --model-provider anthropic
+   ```
+
+4. **View output**: Results are saved to `./output/` directory (mounted volume).
+
+## Local Setup (Without Docker)
+
+1. **Install dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. **Create `.env` file**:
+   ```bash
+   cp .env.example .env
+   ```
+   Edit `.env` with your API credentials.
+
+3. **Run the agent**:
+   ```bash
+   python -m src.main "AI startups" --max-results 10
+   
+   # With output file
+   python -m src.main "cleantech" --max-results 25 --output founders.csv --format csv
+   ```
+
+## Configuration
+
+Create a `.env` file with the following variables:
+
+### Required
+- `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` - LLM provider API key
+- `TWITTER_API_KEY` - X (Twitter) API key
+- `TWITTER_API_SECRET` - X API secret
+- `TWITTER_ACCESS_TOKEN` - X access token
+- `TWITTER_ACCESS_SECRET` - X access secret
+
+### Optional
+- `LINKEDIN_USERNAME` - LinkedIn email (optional, may not work due to API restrictions)
+- `LINKEDIN_PASSWORD` - LinkedIn password (optional)
+- `MODEL_PROVIDER` - "openai" or "anthropic" (default: openai)
+- `MODEL_NAME` - Specific model to use (optional, defaults to provider's default)
+- `DUCKDUCKGO_TIMEOUT` - Search timeout in seconds (default: 30)
+- `MAX_RESULTS_PER_PLATFORM` - Maximum results per platform (default: 50)
+
+## Command-line Options
+
+```bash
+usage: src.main [-h] [--max-results MAX_RESULTS] [--output OUTPUT]
+                [--format {json,csv}] [--model-provider {openai,anthropic}]
+                domain
+
+positional arguments:
+  domain                Domain/sector to search for (e.g., 'AI', 'fintech', 'biotech')
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --max-results MAX_RESULTS, -m MAX_RESULTS
+                        Maximum results per platform (default: 10, max: 100)
+  --output OUTPUT, -o OUTPUT
+                        Output file path (if not specified, prints to stdout)
+  --format {json,csv}   Output format (default: json)
+  --model-provider {openai,anthropic}
+                        LLM provider to use for extraction (default: openai)
+```
+
+## Output Format
+
+Each founder record includes:
+
+```json
+{
+  "name": "John Doe",
+  "company": "Startup Inc",
+  "domain": "AI",
+  "location": "San Francisco, CA",
+  "source": "twitter",
+  "confidence": 0.95,
+  "score": 0.87,
+  "bio_snippet": "Founder @StartupInc building AI products...",
+  "url": "https://twitter.com/johndoe"
+}
+```
+
+## Project Structure
+
+```
+agentic-founders-finding/
+├── src/
+│   ├── agent/           # LangChain agent components
+│   │   ├── extractor.py  # LLM-based founder extraction
+│   │   ├── prompt.py     # System prompts
+│   │   └── tools.py      # Platform tool definitions
+│   ├── platforms/       # Platform integrations
+│   │   ├── duckduckgo.py
+│   │   ├── linkedin.py
+│   │   ├── twitter.py
+│   │   └── yc.py
+│   ├── output/          # Export functionality
+│   ├── utils/           # Deduplication and scoring
+│   └── main.py          # CLI entry point
+├── tests/               # Unit and integration tests
+├── docker-compose.yml   # Docker Compose configuration
+├── Dockerfile           # Docker image build
+├── requirements.txt     # Python dependencies
+└── .env.example         # Environment variable template
+```
+
+## Docker Details
+
+- **Multi-stage build**: Uses Python 3.11-slim with non-root user for security
+- **Lightweight**: Builder stage installs dependencies, runtime stage is minimal
+- **Persistent storage**: Output directory mounted as volume (`./output`)
+- **Configuration**: Environment variables loaded from host `.env` file (mounted read-only)
+
+### Build and Run Manually
+
+```bash
+# Build image
+docker build -t founder-finder .
+
+# Run
+docker run --rm --env-file .env -v $(pwd)/output:/app/output founder-finder "AI startups"
+```
+
+## Testing
+
+Run tests locally:
+
+```bash
+pytest tests/ -v
+```
+
+Run with Docker:
+
+```bash
+docker-compose run --rm founder-finder pytest tests/ -v
+```
+
+## Notes
+
+- LinkedIn API access may be limited; the `linkedin-api` package may not work reliably with modern LinkedIn
+- X (Twitter) API requires a paid tier for full search capabilities
+- Results quality depends on available API rate limits and query specificity
+- For production use, consider adding persistent storage (database) and async processing
+
+## License
+
+MIT

docs/readmes/agentic-slide-filler-README.md

@@ -0,0 +1,148 @@
+# agentic-slide-filler
+**Repository:** Julien-ser/agentic-slide-filler
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-29T03:00:58Z
+
+---
+
+# Agentic Slide Filler
+
+An AI-powered tool that automatically generates professional PowerPoint presentations from document outlines using LLMs.
+
+## Architecture
+
+### Technology Stack
+- **Language**: Python 3.11+
+- **PPT Manipulation**: `python-pptx` (>=0.6.21)
+- **AI Generation**: OpenAI API (GPT-4/3.5) or Anthropic API
+- **Document Parsing**: `python-docx` (>=0.8.11), Markdown support
+- **CLI**: argparse
+- **Testing**: pytest
+
+### System Architecture
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   Input Files   │    │   AI Content     │    │   Output File   │
+│  • Template     │───▶│   Generation     │───▶│  • presentation │
+│  • Outline       │    │                  │    │    .pptx        │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+         │                       │                       │
+         ▼                       ▼                       ▲
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│ TemplateParser  │    │  AIContent       │    │   PPTXWriter    │
+│ • Layout extract│    │  Generator       │    │ • Populate      │
+│ • Placeholders  │    │ • API calls      │    │ • Formatting    │
+└─────────────────┘    │ • Rate limiting  │    └─────────────────┘
+         │              │ • Caching        │            │
+         ▼              └──────────────────┘            │
+┌─────────────────┘                ▲                   │
+│ OutlineParser    │                │                   │
+│ • Docx/MD parse  │───────────────┘                   │
+│ • Hierarcy JSON  │                                    │
+└─────────────────┘                                    │
+         │                                              │
+         └────────────────┬─────────────────────────────┘
+                          ▼
+              ┌─────────────────────┐
+              │   ContentMapper     │
+              │ • Section align     │
+              │ • Placeholder match │
+              └─────────────────────┘
+```
+
+### Data Flow
+1. **Parse Template**: Extract slide layouts, placeholders, and shape types
+2. **Parse Outline**: Convert document (DOCX/MD) to hierarchical content structure
+3. **Map Content**: Align outline sections with appropriate template placeholders
+4. **Generate AI Content**: Call LLM API with prompts to generate slide content
+5. **Validate Content**: Check length, formatting, and compatibility
+6. **Write PPTX**: Populate template with generated content and save
+
+## Setup
+
+```bash
+# Install dependencies
+pip install python-pptx openai python-docx pytest PyYAML python-dotenv
+
+# Or with requirements.txt
+pip install -r requirements.txt
+
+# Set up environment
+cp .env.example .env
+# Edit .env and add your OPENAI_API_KEY
+
+# Optional: customize configuration
+# Copy and modify config.yaml as needed
+cp config.yaml config.local.yaml
+
+# Run the tool
+python -m src.cli --template template.pptx --outline outline.docx --output presentation.pptx
+```
+
+## Configuration
+
+The application supports configuration through:
+
+**Environment Variables** (`.env` file):
+- `OPENAI_API_KEY` - Your OpenAI API key (required)
+- `ANTHROPIC_API_KEY` - Anthropic API key (optional, for Claude)
+
+**Configuration File** (`config.yaml` or `config.local.yaml`):
+- OpenAI model settings (model name, temperature, max tokens)
+- File paths (templates, output, cache, logs)
+- Output filename patterns
+- Content generation parameters (retry attempts, caching)
+- Logging configuration
+
+Configuration precedence: environment variables > `config.local.yaml` > `config.yaml`
+
+## Project Structure
+
+```
+.
+├── README.md              # This file
+├── TASKS.md               # Development progress
+├── requirements.txt       # Python dependencies
+├── config.yaml            # Application configuration
+├── config.local.yaml      # Local overrides (optional)
+├── .env.example          # Environment variable template
+├── .env                  # Local environment variables (gitignored)
+├── src/                  # Source code
+│   ├── template_parser.py
+│   ├── outline_parser.py
+│   ├── content_mapper.py
+│   ├── ai_generator.py
+│   ├── validator.py
+│   ├── pptx_writer.py
+│   ├── slide_filler.py
+│   ├── prompts.py
+│   └── cli.py
+├── tests/                # Test suite
+├── templates/            # Sample PPT templates
+├── output/               # Generated presentations
+├── cache/                # LLM response cache
+└── logs/                 # Application logs
+```
+
+## Current Status
+
+✅ **Phase 1**: Planning & Setup - Complete
+🔄 **Phase 2**: Template & Outline Processing - In Progress
+
+### Completed
+- ✅ Template parser (`src/template_parser.py`): Extracts slide layouts, placeholders, and metadata from PPTX templates
+- ✅ Outline parser (`src/outline_parser.py`): Extracts hierarchical content from DOCX and Markdown documents
+- ✅ Content mapper (`src/content_mapper.py`): Aligns outline sections with template placeholders using intelligent matching
+- ✅ Comprehensive unit tests (`tests/test_template_parser.py`) covering placeholder detection, layout identification, and error handling
+- ✅ Comprehensive unit tests (`tests/test_outline_parser.py`) covering DOCX/Markdown parsing, hierarchy extraction, and error handling
+
+### In Progress
+- 🔄 Adding template validation
+
+### Up Next
+- Design LLM prompt templates (`src/prompts.py`)
+- Build AI content generator (`src/ai_generator.py`)

docs/readmes/agentic-team-README.md

@@ -0,0 +1,139 @@
+# agentic-team
+**Repository:** Julien-ser/agentic-team
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-14T02:24:45Z
+
+---
+
+# Agentic Team
+
+An autonomous multi-agent development system built on the wiggum loop concept. Three specialized agents (Security, Software Developer, Frontend) collaborate via Agent-to-Agent (A2A) communication to complete development tasks autonomously.
+
+## Architecture Overview
+
+The system consists of:
+- **3 Specialized Agents**: Security, Software Developer, Frontend
+- **Redis Message Broker**: A2A communication backbone
+- **SQLite Shared State**: Task persistence and coordination
+- **Flask Dashboard**: Real-time monitoring and control
+- **Wiggum Master Loop**: Task dispatcher and orchestrator
+
+Read the full architecture documentation in [`docs/architecture.md`](docs/architecture.md).
+
+## Current Progress
+
+**Phase 1 - Planning & Architecture** (Complete)
+- ✅ Task 1.1: System architecture and component diagram completed
+- ✅ Task 1.2: Define agent role specifications and protocols
+- ✅ Task 1.3: Create database schema for shared state
+- ✅ Task 1.4: Setup project dependencies and environment configuration
+
+**Phase 2 - Core Infrastructure & Wiggum Loop Enhancement** (Complete)
+- ✅ Task 2.1: Implement the enhanced wiggum loop with role-based agent selection
+- ✅ Task 2.2: Build the message broker using Redis pub/sub
+- ✅ Task 2.3: Create agent base class and lifecycle manager
+- ✅ Task 2.4: Implement shared state manager with SQLite
+
+**Phase 3 - Specialized Agent Workers** (Complete)
+- ✅ Task 3.1: Implement Security Agent with vulnerability scanning & code review
+  - ✅ OWASP Top 10 2021 compliance validation integrated (`src/security/owasp_validator.py`)
+  - ✅ Comprehensive security pattern detection (secrets, SQL injection, XSS, SSRF, etc.)
+  - ✅ Dependency CVE auditing with safety/pip-audit
+  - ✅ Automated security alerts and recommendations to other agents
+- ✅ Task 3.2: Implement Software Development Agent for backend code generation
+- ✅ Task 3.3: Implement Frontend Agent for UI/UX development
+- ✅ Task 3.4: Build agent worker orchestration with health monitoring
+
+**Phase 4 - A2A Communication & Integration Testing** (Complete)
+- ✅ Task 4.1: Implement A2A message routing and handling
+- ✅ Task 4.2: Build collaborative workflow: end-to-end feature development
+- ✅ Task 4.3: Create web dashboard for monitoring agent activity
+- ✅ Task 4.4: Write comprehensive documentation and finalize TASKS.md
+
+## Quick Start
+
+### Prerequisites
+- Python 3.12+
+- Redis (running on localhost:6379)
+- SQLite (included with Python)
+
+### Setup
+
+1. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. Configure environment (optional):
+   ```bash
+   cp .env.example .env
+   # Edit .env with your settings
+   ```
+
+3. Initialize the database:
+   ```bash
+   python -m src.state.migrate
+   ```
+
+4. Start the system:
+   ```bash
+   python -m src.orchestrator.main
+   ```
+
+5. Launch the dashboard (separate terminal):
+   ```bash
+   python -m src.dashboard.app
+   ```
+
+6. Visit `http://localhost:5000` to monitor agent activity
+
+## Project Structure
+
+```
+agentic-team/
+├── docs/                    # Documentation
+│   ├── architecture.md     # System design and specifications
+│   └── workflow_example.md # Collaborative workflow walkthrough
+├── src/                    # Source code
+│   ├── protocols/          # Agent specifications and message protocols
+│   ├── agents/            # Specialized agent implementations
+│   ├── messaging/         # Redis broker and message router
+│   ├── state/             # SQLite state manager
+│   ├── core/              # Wiggum loop implementation
+│   ├── orchestrator/      # Agent worker orchestration
+│   └── dashboard/         # Flask monitoring interface
+├── tests/                 # Unit and integration tests
+│   └── test_collaborative_workflow.py  # End-to-end workflow integration test
+├── requirements.txt       # Python dependencies
+├── .env.example          # Environment configuration template
+└── TASKS.md             # Development roadmap
+```
+
+## How It Works
+
+1. **Task Definition**: Tasks with role tags (`[SECURITY]`, `[SW_DEV]`, `[FRONTEND]`) are defined in `TASKS.md`
+2. **Task Dispatch**: Wiggum Master parses tasks and assigns them to appropriate agents
+3. **Collaboration**: Agents communicate via Redis pub/sub, exchanging messages and code
+4. **Shared State**: All interactions and task status persisted in SQLite
+5. **Monitoring**: Flask dashboard displays real-time agent activity and system metrics
+
+## Agent Capabilities
+
+- **Security Agent**: 
+  - OWASP Top 10 2021 compliance validation
+  - Vulnerability scanning (secrets, SQL injection, XSS, SSRF, etc.)
+  - Dependency CVE auditing (safety, pip-audit)
+  - Security recommendations and A2A alerts
+- **Software Dev Agent**: Code generation, unit testing, formatting (black), linting (ruff), refactoring
+- **Frontend Agent**: UI component generation, responsive design (Tailwind CSS), accessibility, API integration
+
+## Message Protocol
+
+Agents communicate using typed messages with Pydantic validation. See [`docs/architecture.md`](docs/architecture.md#message-protocol-specification) for complete specification.
+
+## License
+
+MIT

docs/readmes/basestation_server-README.md

@@ -4,7 +4,7 @@
 **Stars:** 0
 **Description:** None
 **Language:** JavaScript
-**Last Updated:** 2025-08-09T13:00:53Z
+**Last Updated:** 2026-03-04T14:01:34Z
 
 ---
 

docs/readmes/calorie-counter-README.md

@@ -0,0 +1,116 @@
+# calorie-counter
+**Repository:** Julien-ser/calorie-counter
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** JavaScript
+**Last Updated:** 2026-03-13T03:34:53Z
+
+---
+
+# Calorie Counter
+
+A full-stack web application for tracking daily calorie intake with a React frontend and Node.js/Express backend.
+
+## Current Status
+
+**Phase 1 (Planning & Setup)**: ✅ Complete  
+**Phase 2 (Backend)**: ✅ Complete - Express server with middleware, SQLite database, REST API endpoints with calorie calculation and date-based filtering fully implemented.  
+**Phase 3 (Frontend)**: ✅ Complete - React app with functional components, hooks, Context API for state management, MealForm and MealList components fully implemented.  
+**Phase 4 (Testing & Polish)**: ✅ Complete - Backend and frontend tests implemented, responsive CSS styling with clean UI design, mobile-first approach, and enhanced user experience.
+
+## Project Scope
+
+Build a calorie tracking system that allows users to:
+- Log meals with food name, calorie count, date, and meal type
+- View meals grouped by date with daily calorie totals
+- Query a food database for calorie information
+- Filter meals by date range
+
+## User Stories
+
+1. **As a user**, I want to add a meal entry with food name, calories, date, and meal type (breakfast/lunch/dinner/snack) so that I can track what I eat.
+
+2. **As a user**, I want to view all my meals grouped by date so that I can see my consumption patterns.
+
+3. **As a user**, I want to see daily calorie totals so that I can monitor my intake against goals.
+
+4. **As a user**, I want to delete incorrect meal entries so that my log stays accurate.
+
+5. **As a user**, I want to filter meals by date range so that I can focus on specific periods.
+
+6. **As a user**, I want quick access to common food calorie values so that I can log meals efficiently.
+
+## Tech Stack
+
+- **Frontend**: React with functional components, hooks, and Context API for state management
+- **Backend**: Node.js/Express with middleware (CORS, body-parser, helmet)
+- **Database**: SQLite with tables for users, foods, and meals
+- **API**: RESTful endpoints for CRUD operations on meals and food lookup
+- **Testing**: Jest/Supertest for backend, React Testing Library for frontend
+
+## Features
+
+- Meal creation with calorie tracking
+- Date-based grouping and filtering
+- Daily calorie summaries
+- Food database integration
+- Responsive CSS styling with modern UI
+- Mobile-first design approach
+- Smooth animations and transitions
+- Enhanced accessibility features
+- Clean, gradient-based color scheme
+- Interactive hover effects and visual feedback
+
+## Setup Instructions
+
+1. **Clone and install dependencies**:
+   ```bash
+   cd client && npm install
+   cd ../server && npm install
+   ```
+
+2. **Start the backend server**:
+   ```bash
+   cd server && npm start
+   ```
+   Server runs on http://localhost:3001
+
+3. **Start the frontend development server**:
+   ```bash
+   cd client && npm start
+   ```
+   App runs on http://localhost:3000
+
+4. **Run tests**:
+   ```bash
+   cd server && npm test
+   cd ../client && npm test
+   ```
+
+## API Endpoints
+
+- `GET /api/meals` - Retrieve all meals (with optional date filtering)
+- `POST /api/meals` - Create a new meal entry
+- `DELETE /api/meals/:id` - Delete a meal
+- `GET /api/foods` - Search food database for calorie information
+
+## Project Structure
+
+```
+calorie-counter/
+├── client/           # React frontend
+│   ├── src/
+│   │   ├── components/
+│   │   ├── context/
+│   │   └── App.js
+│   └── package.json
+├── server/           # Express backend
+│   ├── src/
+│   │   ├── routes/
+│   │   ├── middleware/
+│   │   └── database/
+│   └── package.json
+├── TASKS.md          # Development progress
+└── README.md         # This file
+```

docs/readmes/causal-github-pr-analysis-README.md

@@ -0,0 +1,38 @@
+# causal-github-pr-analysis
+**Repository:** Julien-ser/causal-github-pr-analysis
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Jupyter Notebook
+**Last Updated:** 2026-01-31T17:40:50Z
+
+---
+
+# Causal GitHub PR Analysis
+
+This project analyzes GitHub pull request data to uncover causal relationships and insights.
+
+## Files
+- **causaltest.ipynb**: Jupyter notebook for data analysis and experimentation.
+- **ghpr.csv**: Dataset containing GitHub pull request information.
+
+## Getting Started
+1. Open `causaltest.ipynb` in Jupyter or VS Code.
+2. Ensure you have Python and Jupyter installed.
+3. Install required packages (see notebook for details).
+4. Run the notebook cells to perform the analysis.
+
+## Project Purpose
+The goal is to explore causal inference techniques on real-world GitHub PR data, enabling better understanding of factors influencing PR outcomes.
+
+## Requirements
+- Python 3.x
+- Jupyter Notebook
+- pandas, numpy, matplotlib, and other data science libraries (see notebook)
+
+## Usage
+- Modify or extend the notebook to try new analyses.
+- Replace `ghpr.csv` with your own data if desired.
+
+## License
+MIT License

docs/readmes/causal-model-README.md

@@ -0,0 +1,137 @@
+# causal-model
+**Repository:** Julien-ser/causal-model
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-12T19:30:15Z
+
+---
+
+# Causal Model for Firmware Update Agent
+
+A causal inference model and visualization dashboard for an agentic loop that manages firmware updates.
+
+## Mission
+
+Create a sample causal model/visualization of an agentic loop for updating firmware. The project uses DoWhy for causal inference and Streamlit for interactive visualization.
+
+## Causal Model
+
+### DAG Structure
+
+The causal graph includes these variables:
+- **Update_Trigger**: Initiates update (manual, auto, emergency)
+- **Network_Stability**: Network quality (0-1 score)
+- **Device_Resources**: CPU, memory, storage availability
+- **Device_Health**: Battery, temperature, hardware status
+- **Device_Configuration**: Settings, encryption, policies
+- **Firmware_Version**: Current version (older harder to update)
+- **Update_Command**: Treatment - whether update command issued
+- **Update_Success**: Outcome - whether update succeeded
+- **Rollback_Needed**: Whether rollback was required
+- **Device_Downtime**: Downtime duration during update
+
+### Key Relationships
+
+- Main effect: `Update_Command` → `Update_Success`
+- Moderators: `Network_Stability`, `Device_Resources`, `Device_Health` → `Update_Success`
+- Confounders: `Firmware_Version`, `Device_Configuration` affect both treatment and outcome
+- Consequences: `Update_Success` → `Rollback_Needed, Device_Downtime`
+
+See `src/causal_graph.py` for complete definition.
+
+## Synthetic Data Generation
+
+The project includes a comprehensive synthetic data generator (`src/data_generator.py`) that simulates realistic firmware update scenarios.
+
+### Features
+
+- Generates 1000+ firmware update attempts with realistic confounding variables
+- Respects causal DAG structure: treatment affects outcome, confounders influence both
+- Categorical variables: `Update_Trigger` (manual/auto/emergency), `Firmware_Version` (v1.0-v3.0), `Device_Configuration` (low/medium/high)
+- Continuous variables: `Network_Stability`, `Device_Resources`, `Device_Health` (0-1 scores)
+- Binary outcomes: `Update_Command` (treatment), `Update_Success` (outcome), `Rollback_Needed`
+- Continuous outcome: `Device_Downtime` (seconds)
+
+### Usage
+
+```python
+from src.data_generator import generate_data, DataGenerator
+
+# Quick generation
+data = generate_data(n_samples=1000, random_seed=42)
+
+# Custom configuration
+config = DataGeneratorConfig(
+    n_samples=2000,
+    network_stability_mean=0.7,
+    treatment_effect_size=0.25
+)
+generator = DataGenerator(config)
+data = generator.generate()
+
+# Generate interventional data (set all devices to receive update command)
+interventional_data = generator.generate_interventional_data(treatment_value=1)
+```
+
+### Testing
+
+The data generator includes 17 comprehensive unit tests covering:
+- Data structure and variable types
+- Causal relationships (e.g., older firmware → more updates)
+- Effect sizes (e.g., better network → higher success rate)
+- Reproducibility with random seeds
+
+Run tests: `pytest tests/test_data_generator.py -v`
+
+## Setup
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the Streamlit dashboard (once implemented)
+streamlit run app.py
+```
+
+## Project Structure
+
+- `src/` - Source code (data generator, causal engine, agent, simulator, visualization)
+- `tests/` - Unit and integration tests
+- `app.py` - Streamlit dashboard
+- `docker-compose.yml` - Docker deployment configuration
+- `README.md` - This file
+
+## Progress
+
+- ✅ **Phase 1** - Planning & Setup (complete)
+- ✅ **Phase 2** - Causal Model Development (complete)
+  - Causal graph (`src/causal_graph.py`) implemented with 10 nodes and 12 edges
+  - Synthetic data generator (`src/data_generator.py`) creates realistic data respecting DAG
+  - Causal inference engine (`src/causal_engine.py`) built with DoWhy
+  - Comprehensive unit tests (`tests/test_causal.py`) passing (15 tests)
+- ✅ **Phase 3** - Agentic Loop Implementation (complete)
+  - `Agent` class (`src/agent.py`) with perception, reasoning, action modules
+  - Policy function maps predicted success probability to update decision (threshold)
+  - `Simulator` (`src/simulator.py`) runs 100 decisions and tracks outcomes vs. baselines
+- 🔄 **Phase 4** - Visualization & Dashboard (complete)
+  - Causal graph visualization (`src/visualization.py`) with Plotly
+  - Streamlit dashboard (`app.py`) with three tabs: Causal Graph, Agent Performance, Scenario Simulator
+  - Real-time metrics panel: agent win rate, false positives, rollback frequency
+  - Interactive scenario simulator
+  - This README and `docker-compose.yml`
+
+## Running the Dashboard
+
+1. Install dependencies: `pip install -r requirements.txt`
+2. Run: `streamlit run app.py`
+3. Open `http://localhost:8501` in your browser.
+
+Or with Docker Compose: `docker-compose up --build` then open `http://localhost:8501`.
+
+## Example Scenarios
+
+- **High-probability update**: Device with good network stability, ample resources, good health, and recent firmware → agent predicts high success probability and recommends update.
+- **Low-probability update**: Device with poor network, low resources, poor health, and old firmware → agent advises against update.
+- **Baseline comparison**: The dashboard shows how the agent compares to always-updating or never-updating baselines, accounting for rollback costs.

docs/readmes/cuda-optimizer-README.md

@@ -0,0 +1,231 @@
+# cuda-optimizer
+**Repository:** Julien-ser/cuda-optimizer
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-13T05:01:21Z
+
+---
+
+# CUDA Optimizer for PyTorch
+
+A specialized toolkit for optimizing PyTorch neural networks on CUDA devices. Maximize throughput, minimize memory usage, and achieve production-grade performance with minimal code changes.
+
+## Features
+
+- **Custom CUDA Kernels**: Fused operations (activation+layernorm) with 20%+ speedup
+- **Intelligent Memory Pool**: Caching allocator reducing fragmentation by >95%
+- **Automatic Mixed Precision**: Dynamic loss scaling per layer, maintaining FP32 accuracy
+- **Kernel Auto-Tuner**: Automatically finds optimal block/grid dimensions
+- **Gradient Checkpointing**: 50%+ memory reduction with selective recompute
+- **Tensor Parallelism**: Linear scaling across multiple GPUs with NCCL
+- **Fused Optimizer**: AdamW fused kernel 30% faster than standard
+- **Real-time Monitoring**: Live dashboard for GPU utilization, memory, throughput
+
+## Quick Start
+
+```bash
+# Install from source (requires CUDA 11.8+)
+pip install -e .
+
+# Or use Docker with pre-configured CUDA environment
+docker build -t cuda-optimizer -f Dockerfile.cuda-dev .
+```
+
+## Usage
+
+```python
+import torch
+from cuda_optimizer import Optimizer, profile_model
+
+# Profile your model to identify bottlenecks
+profile_model(model, input_shape=(32, 3, 224, 224))
+
+# Apply optimizations with one line
+optimized_model = Optimizer.optimize(model)
+
+# Train with 30% less memory, 20% more throughput
+criterion = torch.nn.CrossEntropyLoss()
+optimizer = torch.optim.AdamW(optimized_model.parameters(), lr=1e-3)
+
+# No code changes required - just drop-in replacement!
+```
+
+## Architecture
+
+```mermaid
+graph TD
+    A[PyTorch Model] --> B[Input Tensors]
+    B --> C[Memory Pool]
+    C --> D[Custom CUDA Kernels]
+    D --> E[Fused Optimizer]
+    E --> F[Grad Checkpoint]
+    F --> G[Tensor Parallel]
+    G --> H[Output/Loss]
+    
+    H --> I[AMP Wrapper]
+    I --> J[Profiler]
+    J --> K[Autotuner]
+    K --> L[Config Cache]
+    
+    J --> M[Monitoring Dashboard]
+    M --> N[Live Metrics]
+    
+    L --> D
+    
+    style A fill:#f9f,stroke:#333
+    style H fill:#bbf,stroke:#333
+    style N fill:#9f9,stroke:#333
+```
+
+## Performance Targets
+
+| Model | FPS Improvement | Memory Reduction |
+|-------|----------------|------------------|
+| ResNet50 | +30% | -33% |
+| BERT-small | +30% | -39% |
+| LSTM | +20% | -50% |
+| GPT-2 small | +25% | -50% |
+
+Full targets and validation criteria: [docs/optimization_targets.md](docs/optimization_targets.md)
+
+## Requirements
+
+- **CUDA**: 11.8+
+- **cuDNN**: 8.x+
+- **PyTorch**: 2.0+
+- **Python**: 3.9+
+- **GPU**: NVIDIA (Compute capability >= 7.0)
+
+## Project Structure
+
+```
+cuda-optimizer/
+├── src/
+│   ├── kernels/        # Custom CUDA kernels
+│   ├── memory/         # Caching allocator
+│   ├── optim/          # AMP wrapper
+│   ├── tuner/          # Auto-tuning
+│   ├── checkpoint/     # Gradient checkpointing
+│   ├── parallel/       # Tensor parallelism
+│   ├── fusion/         # Fused optimizers
+│   ├── monitoring/     # Dashboard
+│   └── profiling/      # Profiling tools
+├── docs/               # Documentation
+├── tests/              # Unit & integration tests
+├── scripts/            # CLI utilities
+├── notebooks/          # Tutorials 📚
+│   ├── 01_basics.ipynb           # CNN/ResNet50 optimization
+│   ├── 02_transformers.ipynb     # BERT optimization
+│   └── 03_distributed.ipynb      # Multi-GPU training
+├── data/               # Benchmark datasets
+└── dashboard/          # Monitoring UI
+```
+
+## Installation
+
+### From Source
+
+```bash
+# Clone and install
+git clone <repo-url>
+cd cuda-optimizer
+pip install -e .
+```
+
+### Docker (Recommended for quick start)
+
+```bash
+docker build -t cuda-optimizer -f Dockerfile.cuda-dev .
+docker run --gpus all -it cuda-optimizer
+```
+
+## Development
+
+```bash
+# Run baseline benchmarks
+python scripts/run_baseline.py --models resnet50 bert-small
+
+# Run tests (with GPU)
+pytest tests/ --gpu
+
+# Run tests with coverage
+pytest tests/ --cov=cuda_optimizer --cov-report=html
+
+# Run tests in parallel (requires pytest-xdist)
+pytest -n auto tests/
+
+# Run specific test suite
+pytest tests/unit/     # Unit tests only
+pytest tests/integration/  # Integration tests only
+
+# Lint and type check
+black src/ tests/
+isort src/ tests/
+flake8 src/ tests/
+mypy src/ tests/
+
+# Start monitoring dashboard
+streamlit run dashboard/app.py
+```
+
+## Documentation
+
+- [Quickstart Guide](docs/quickstart.md)
+- [API Reference](docs/api/)
+- [Migration Guide](docs/migration_guide.md)
+- [Optimization Targets](docs/optimization_targets.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+## Current Status
+
+**Phase 1: Planning & Setup**
+- ✅ Task 1.1: Define optimization targets and requirements
+- ✅ Task 1.2: Set up development environment with CUDA toolchain
+- ✅ Task 1.3: Establish baseline profiling infrastructure
+- ✅ Task 1.4: Create project structure and dependency management
+
+**Phase 2: Core CUDA Optimization Implementation**
+- ✅ Task 2.1: Implement custom CUDA kernels for tensor operations ([learn more](docs/custom_ops.md))
+- ✅ Task 2.2: Develop memory pool and caching allocator ([learn more](docs/cuda_cache.md))
+- ✅ Task 2.3: Create automatic mixed precision optimizer wrapper ([learn more](docs/amp_wrapper.md))
+- ✅ Task 2.4: Build kernel auto-tuner using NVIDIA NVTX ([learn more](docs/autotuner.md))
+
+**Phase 3: Advanced Features & Integration**
+- ✅ Task 3.1: Implement gradient checkpointing with custom recompute ([learn more](docs/checkpointing.md))
+- ✅ Task 3.2: Develop tensor parallelism utilities ([learn more](docs/tensor_parallel.md))
+- ✅ Task 3.3: Create optimizer fusion pass (AdamW fused kernel) ([learn more](docs/adam_fused.md))
+- ✅ Task 3.4: Build real-time monitoring dashboard ([learn more](docs/dashboard.md))
+
+ **Phase 4: Testing, Documentation & Deployment**
+ - ✅ Task 4.1: Implement comprehensive test suite ([learn more](docs/testing.md))
+ - ✅ Task 4.2: Create user documentation and API reference
+   - [Quickstart Guide](docs/quickstart.md)
+   - [API Reference](docs/api/)
+   - [Migration Guide](docs/migration_guide.md)
+   - [Troubleshooting](docs/troubleshooting.md)
+   - [Optimization Targets](docs/optimization_targets.md)
+ - ✅ Task 4.3: Package and publish to PyPI
+ - ✅ Task 4.4: Create Jupyter notebooks with tutorials
+   - [Notebook 1: CNN Optimization](notebooks/01_basics.ipynb) (ResNet50)
+   - [Notebook 2: Transformer Optimization](notebooks/02_transformers.ipynb) (BERT)
+   - [Notebook 3: Distributed Training](notebooks/03_distributed.ipynb) (Multi-GPU)
+
+See [TASKS.md](TASKS.md) for complete roadmap.
+
+## License
+
+MIT
+
+## Citation
+
+If you use this tool in your research, please cite:
+
+```bibtex
+@software{cuda_optimizer_2026,
+  title = {CUDA Optimizer for PyTorch},
+  year = {2026},
+  url = {https://github.com/your-org/cuda-optimizer}
+}
+```

docs/readmes/databricks-powerbi-pipeline-README.md

@@ -0,0 +1,209 @@
+# databricks-powerbi-pipeline
+**Repository:** Julien-ser/databricks-powerbi-pipeline
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-13T15:14:17Z
+
+---
+
+# Databricks Power BI Pipeline
+
+**Production-ready end-to-end analytics solution connecting Databricks to Power BI for e-commerce analytics.**
+
+**Status: Production Ready ✅**
+
+## Overview
+
+This project provides a production-ready pipeline that transforms raw e-commerce data into actionable Power BI dashboards using Databricks as the analytics engine.
+
+### Problem Statement
+Organizations need to analyze e-commerce data (orders, customers, products) to make data-driven decisions about inventory, marketing, and customer experience.
+
+### Solution
+Automated ETL pipeline with:
+- Bronze layer: Raw data ingestion
+- Silver layer: Cleaned and validated data
+- Gold layer: Business-level aggregates for reporting
+- Power BI integration with DirectQuery for real-time analytics
+
+## Architecture
+
+```
+Data Sources → Databricks (ETL) → Delta Tables → Power BI → Dashboards
+     ↓              ↓              ↓           ↓          ↓
+  CSV/API     Notebooks    Optimized   DirectQuery   KPIs &
+              (PySpark)     Layer                   Reports
+```
+
+### Components
+
+- **notebooks/** - Databricks notebooks (bronze, silver, gold transformations)
+- **src/** - Python automation scripts for deployment and monitoring
+- **data/** - Sample datasets and schema definitions
+- **config/** - Configuration files for environments
+- **tests/** - Unit and integration tests
+- **docs/** - Architecture and deployment guides
+
+## Quick Start
+
+### Prerequisites
+- Databricks workspace (Community Edition or paid)
+- Power BI Desktop (free) or Power BI Premium
+- Python 3.8+ with pip
+
+### Setup
+
+```bash
+# Clone and navigate
+cd databricks-powerbi-pipeline
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Configure Databricks connection
+cp config/env.example.py config/env.py
+# Edit config/env.py with your credentials (DATABRICKS_HOST and DATABRICKS_TOKEN)
+
+# Optional: Generate sample data (or upload your own)
+python src/generate_sample_data.py
+
+# Run tests (unit and integration)
+python -m pytest tests/
+
+# Deploy notebooks to Databricks workspace
+python src/deploy_notebooks.py
+
+# Execute the ETL pipeline (bronze → silver → gold)
+python src/monitor_pipeline.py
+```
+
+### Using the Pipeline
+
+**Quickest path to production:**
+
+1. **Configure & Deploy**:
+   - Set your Databricks credentials in `config/env.py`
+   - Run `python src/deploy_notebooks.py` to upload notebooks to workspace
+   - Upload sample data to `/mnt/data/raw/` in your Databricks workspace
+
+2. **Execute ETL**:
+   - Run `python src/monitor_pipeline.py` to execute the full pipeline
+   - The script runs bronze → silver → gold notebooks automatically
+   - Monitor logs in `logs/pipeline.log` for progress
+
+3. **Connect Power BI**:
+   - Follow the [Power BI Setup Guide](docs/powerbi-setup.md)
+   - Connect to gold Delta tables using DirectQuery
+   - Import the data model and build reports
+
+4. **Monitor and Maintain**:
+   - Run `make health-check` to verify pipeline health
+   - Check `logs/pipeline.log` for execution details
+   - Use `make rollback` for disaster recovery if needed
+   - Set up alerts via email or Slack (configure in `config/env.py`)
+
+## Project Structure
+
+```
+databricks-powerbi-pipeline/
+├── notebooks/                    # Databricks ETL notebooks (Medallion Architecture)
+│   ├── 01_bronze/
+│   │   └── bronze_ingestion.ipynb      # Raw data → Delta bronze tables
+│   ├── 02_silver/
+│   │   └── silver_transformation.ipynb # Cleaned data → Delta silver tables
+│   └── 03_gold/
+│       └── gold_aggregation.ipynb      # Business aggregates → Delta gold tables
+├── src/                          # Python automation scripts
+│   ├── deploy_notebooks.py       # Deploy notebooks to Databricks
+│   ├── monitor_pipeline.py       # Execute pipeline with monitoring
+│   ├── generate_sample_data.py   # Generate synthetic e-commerce data
+│   └── utils.py                  # Shared utilities (logging, config, etc.)
+├── data/                         # Sample datasets (CSV format)
+│   ├── sample_customers.csv
+│   ├── sample_products.csv
+│   ├── sample_orders.csv
+│   └── sample_order_items.csv
+├── config/                       # Configuration files
+│   ├── env.py                    # Environment credentials (gitignored)
+│   ├── env.example.py            # Template for env.py
+│   └── parameters.json           # Pipeline parameters (paths, catalog, etc.)
+├── tests/                        # Automated tests
+│   ├── unit/                     # Unit tests (utils, data generation)
+│   │   ├── test_utils.py
+│   │   └── test_data_generation.py
+│   └── integration/              # Integration tests (end-to-end)
+│       └── test_integration.py
+├── docs/                         # Documentation
+│   ├── architecture.md           # System design and architecture
+│   ├── deployment.md             # Step-by-step deployment guide
+│   └── powerbi-setup.md          # Power BI connection and dashboard setup
+├── logs/                         # Pipeline execution logs (auto-generated)
+├── requirements.txt              # Python dependencies
+├── README.md                     # This file
+└── TASKS.md                      # Project roadmap and progress tracking
+```
+
+## Sample Data
+
+The project includes synthetic e-commerce data:
+- **Orders**: Transaction records with timestamps, amounts, status
+- **Customers**: Demographics and segmentation data
+- **Products**: Catalog with categories and pricing
+
+## Power BI Integration
+
+After processing data through the Delta Lake pipeline, connect Power BI for analytics. See the **[Power BI Setup Guide](docs/powerbi-setup.md)** for detailed instructions.
+
+**Quick steps:**
+1. Get your Databricks workspace URL and token
+2. In Power BI Desktop: Get Data → Databricks
+3. Enter server and database name pointing to gold Delta table
+4. Use DirectQuery mode for real-time dashboard updates
+5. Build visuals for sales trends, customer segmentation, product performance
+
+Or, for step-by-step instructions with screenshots, follow the complete guide in `docs/powerbi-setup.md`.
+
+## Testing
+
+The project includes comprehensive tests:
+
+```bash
+# Unit tests (fast, no external dependencies)
+pytest tests/unit/
+
+# Integration tests (run in simulation mode by default, no Databricks required)
+pytest tests/integration/
+
+# Full test suite with coverage report
+pytest --cov=src tests/
+```
+
+**Note:** Integration tests run in *simulation mode* when databricks-sdk is not installed, making them suitable for CI/CD and local development without cloud credentials. To test against a real Databricks workspace, install `databricks-sdk` and configure your credentials.
+
+## Development Status
+
+See [TASKS.md](TASKS.md) for current progress and upcoming work.
+
+## Documentation
+
+- [Architecture Guide](docs/architecture.md)
+- [Deployment Guide](docs/deployment.md)
+- [Power BI Setup](docs/powerbi-setup.md)
+- [API Reference](docs/api-reference.md)
+- [Configuration Reference](docs/configuration.md)
+- [Monitoring & Operations](docs/monitoring.md)
+- [Data Dictionary](docs/data-dictionary.md)
+- [Contributing Guide](CONTRIBUTING.md)
+
+## Contributing
+
+1. Check TASKS.md for current priorities
+2. Create feature branch from main
+3. Add tests for new functionality
+4. Submit changes with clear commit messages
+
+## License
+
+MIT License - see LICENSE file for details.

docs/readmes/edgebot-ai-README.md

@@ -0,0 +1,815 @@
+# edgebot-ai
+**Repository:** Julien-ser/edgebot-ai
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** C++
+**Last Updated:** 2026-03-16T16:18:22Z
+
+---
+
+# EdgeBot AI
+
+[![CI](https://github.com/edgebot-ai/edgebot-ai/workflows/CI%20(Rust)/badge.svg)](https://github.com/edgebot-ai/edgebot-ai/actions)
+[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org)
+
+A Rust-based platform for deploying lightweight AI models on robots and IoT devices. EdgeBot AI provides zero-copy memory safety, WebAssembly compilation, and seamless ROS2 integration for edge inference.
+
+## Mission
+
+Build toolkits for deploying AI models on robots and IoT devices with:
+- **Zero-copy memory safety** using Rust's ownership model
+- **Cross-platform support** (x86_64, ARM, WebAssembly)
+- **ROS2 integration** for robotics ecosystems
+- **Burn framework** for efficient inference
+- **Simulation-ready** with Webots integration
+
+## Project Structure
+
+This is a Cargo workspace with multiple crates:
+
+| Crate | Purpose | Status |
+|-------|---------|--------|
+| `edgebot-core` | Core inference engine + memory safety + optimizer + tasks | ✅ Phase 2 (Core SDK completed) |
+| `edgebot-sim` | Simulation environment with Webots integration (headless testing) | ✅ Phase 3 (Webots integration completed) |
+| `edgebot-ros2` | ROS2 bridge for robot communication | 📦 Phase 2 |
+| `edgebot-wasm` | WebAssembly runtime for browser/IoT | ✅ Phase 2 (Runtime done) |
+| `edgebot-sim-server` | Cloud simulation service with Actix Web API | ✅ Phase 3 |
+| `edgebot-cli` | Command-line interface for compilation, deployment, simulation, and optimization | 🆕 Phase 4 (In progress) |
+
+## Prerequisites
+
+- Rust 1.70+ with `rustc`, `cargo`, `rustfmt`, `clippy`
+- For WASM target: `rustup target add wasm32-unknown-unknown`
+- A `rust-toolchain.toml` is included to ensure consistent toolchain versions.
+- For ROS2 integration: `ros2` installation (optional)
+
+## Setup
+
+```bash
+# Clone and enter workspace
+git clone https://github.com/edgebot-ai/edgebot-ai.git
+cd edgebot-ai
+
+# Build all crates
+cargo build
+
+# Run tests
+cargo test --workspace
+
+# Build for WASM (requires wasm32 target)
+cargo build --target wasm32-unknown-unknown --release -p edgebot-wasm
+```
+
+## Development
+
+```bash
+# Format code
+cargo fmt
+
+# Lint
+cargo clippy --workspace -- -D warnings
+
+# Build with optimizations
+cargo build --release
+
+# Run benchmarks (requires criterion)
+cargo bench -p edgebot-core
+
+# Generate JSON report for pro tier optimization
+cargo bench -p edgebot-core -- --output-format json > benchmark_results/raw.json
+# The pro tier optimization report is auto-generated at benchmark_results/inference_pro_report.json
+```
+
+## Current Status
+
+**Phase 3: Simulation & Compilation** - ✅ COMPLETED
+
+- [x] Phase 3 Task 1: Webots simulation integration
+- [x] Phase 3 Task 2: Cloud simulation service
+- [x] Phase 3 Task 3: ARM cross-compilation toolchain
+- [x] Phase 3 Task 4: Profiling & benchmarking suite (criterion)
+
+**Phase 4: Deployment & Monetization** - ✅ COMPLETED
+
+- [x] Phase 4 Task 1: EdgeBot CLI (deploy, simulate, optimize commands)
+- [x] Phase 4 Task 2: License verification system
+- [x] Phase 4 Task 3: Dashboard frontend
+- [x] Phase 4 Task 4: Comprehensive documentation
+
+---
+
+✅ **All planned development tasks are complete!** EdgeBot AI is feature-complete for initial release.
+
+See [TASKS.md](TASKS.md) for complete roadmap.
+
+## EdgeBot CLI
+
+The `edgebot-cli` is the main command-line interface for end-users, providing commands for deployment, simulation, optimization, and cross-compilation.
+
+### Installation
+
+Build from the workspace:
+
+```bash
+cargo build --release -p edgebot-cli
+# Binary will be at: target/release/edgebot
+```
+
+Or install globally:
+
+```bash
+cargo install --path edgebot-cli
+```
+
+### Commands
+
+#### 1. Compile for ARM targets
+
+Cross-compile models for embedded ARM devices (Raspberry Pi, STM32, generic ARM).
+
+```bash
+# Auto-detect hardware and compile
+edgebot compile --model model.onnx --output binary
+
+# Compile for specific hardware
+edgebot compile --model model.onnx --output binary --hardware raspberry-pi
+
+# Compile for all supported targets
+edgebot compile --model model.onnx --output-dir ./bin/ --all
+
+# With optimization features
+edgebot compile --model model.onnx --output binary --release --features "tch,cuda"
+```
+
+**Options:**
+- `--model <path>`: Model file to embed (optional)
+- `--output <path>`: Output binary path
+- `--target <triple>`: Target triple (e.g., aarch64-unknown-linux-musl)
+- `--hardware <type>`: Hardware type (raspberry-pi, stm32, generic-arm)
+- `--all`: Build for all supported ARM targets
+- `--release`: Build in release mode
+- `--features <feat>`: Enable Cargo features
+- `--static-link`: Statically link all dependencies
+
+#### 2. Deploy to device
+
+Deploy compiled binaries to remote devices via SSH or serial connection.
+
+```bash
+# Deploy via SSH (using SSH agent)
+edgebot deploy --binary ./target/release/edgebot --target 192.168.1.100 --username pi
+
+# Deploy with password authentication
+edgebot deploy --binary ./edgebot --target 192.168.1.100 --username pi --password secret
+
+# Deploy to custom destination path
+edgebot deploy --binary ./edgebot --target 192.168.1.100 --username pi --destination /home/pi/apps/
+
+# Serial deployment (placeholder)
+edgebot deploy --binary ./edgebot --target /dev/ttyUSB0 --method serial
+```
+
+**Options:**
+- `--binary <path>`: Binary file to deploy (required)
+- `--target <addr>`: Target IP address or serial port (required)
+- `--method <ssh|serial>`: Deployment method (default: ssh)
+- `--destination <path>`: Remote path (default: /opt/edgebot/)
+- `--username <user>`: SSH username (required for SSH)
+- `--password <pass>`: SSH password (optional; uses SSH agent if omitted)
+
+**Note:** Serial deployment is not yet fully implemented. Use SSH for now.
+
+#### 3. Run simulation
+
+Test models in either local Webots simulation or cloud simulation server.
+
+##### Local Simulation (Webots)
+
+```bash
+# Run local simulation with a world file
+edgebot simulate --model model.ebmodel --world worlds/warehouse.wbt --runs 10
+
+# Output JSON results
+edgebot simulate --model model.ebmodel --world worlds/warehouse.wbt --json
+
+# Adjust simulation timestep
+edgebot simulate --model model.ebmodel --world worlds/warehouse.wbt --timestep 16
+```
+
+##### Cloud Simulation
+
+```bash
+# Run on cloud simulation server
+edgebot simulate --model model.ebmodel --cloud --server http://localhost:8080 --runs 100
+
+# With custom world file uploaded to server
+edgebot simulate --model model.ebmodel --world worlds/custom.wbt --cloud --server http://sim.edgebot.ai
+```
+
+**Options:**
+- `--model <path>`: Model file to test (required)
+- `--world <path>`: Webots world file (required for local, optional for cloud)
+- `--cloud`: Use cloud simulation server
+- `--server <url>`: Cloud server URL (default: http://localhost:8080)
+- `--runs <n>`: Number of simulation runs (default: 1)
+- `--json`: Output results as JSON
+- `--timestep <ms>`: Simulation timestep in milliseconds (default: 32)
+
+**Output:** Simulation metrics including total steps, runtime, average inference time.
+
+#### 4. Optimize models
+
+Optimize models for edge deployment with quantization, pruning, and layer fusion.
+
+```bash
+# Basic optimization with int8 quantization and layer fusion
+edgebot optimize --input model.onnx --output model.ebmodel --quantize int8 --fuse-layers
+
+# Advanced: fp16 quantization + magnitude pruning (50% threshold)
+edgebot optimize \
+  --input model.onnx \
+  --output model.ebmodel \
+  --quantize fp16 \
+  --prune magnitude \
+  --pruning-threshold 0.5 \
+  --device cpu
+
+# No optimization (just convert format)
+edgebot optimize --input model.onnx --output model.ebmodel --quantize none
+```
+
+**Options:**
+- `--input <path>`: Input model file (ONNX or Burn .bin) (required)
+- `--output <path>`: Output optimized model (.ebmodel) (required)
+- `--quantize <none|int8|fp16>`: Quantization method (default: none)
+- `--prune <none|magnitude|structured>`: Pruning strategy (default: none)
+- `--pruning-threshold <0.0-1.0>`: Fraction of weights to prune (default: 0.5)
+- `--fuse-layers`: Enable layer fusion (Conv+ReLU, etc.)
+- `--device <cpu|cuda>`: Target device (default: cpu)
+
+**Output:** `.ebmodel` bundle containing optimized model and metadata. The CLI reports size reduction and optimization statistics.
+
+### Usage
+
+**Free Tier:**
+- All core SDK features are free and open source (MIT/Apache-2.0)
+- Local simulation with Webots is unlimited
+- Basic model optimization (quantization none, no pruning)
+- Cross-compilation for ARM targets
+
+**Pro Tier ($29/month):**
+- Cloud simulation with batch runs (100+ scenarios)
+- Advanced model optimization: int8/fp16 quantization, pruning, layer fusion
+- Priority support and custom integrations
+- Offline activation tokens available
+
+To enable pro features, set the `EDGEBOT_LICENSE_KEY` environment variable:
+
+```bash
+export EDGEBOT_LICENSE_KEY="your_license_key_here"
+```
+
+The license key is an Ed25519 signed token verified offline. Contact sales@edgebot.ai to obtain a pro license.
+
+## EdgeBot Dashboard
+
+The EdgeBot Dashboard is a modern web application built with Yew and Rust WebAssembly. It provides a comprehensive interface for monitoring simulation results, tracking model performance metrics, and managing your Pro subscription.
+
+### Features
+
+- **Simulation Monitoring**: View real-time and historical simulation jobs, including FPS, inference latency, memory usage, and detailed performance breakdowns.
+- **Model Metrics**: Track inference latency, memory footprint, and model size across different platforms (x86_64, ARM, WASM).
+- **License Management**: Check your subscription status, view active features, and manage your EDGEBOT_LICENSE_KEY.
+
+### Building
+
+Build the dashboard using **Trunk** (the recommended approach):
+
+```bash
+# Install trunk (once)
+cargo install trunk
+
+# Build for production
+cd edgebot-dashboard
+trunk build --release
+```
+
+Alternatively, use the included build script:
+
+```bash
+cd edgebot-dashboard
+./build-dashboard-wasm.sh --release
+```
+
+The compiled static files will be in the `dist/` directory.
+
+### Running Locally
+
+Start a local development server with hot reloading:
+
+```bash
+cd edgebot-dashboard
+trunk serve --open
+```
+
+Or serve the built files:
+
+```bash
+cd edgebot-dashboard/dist
+python3 -m http.server 8000
+# Open http://localhost:8080
+```
+
+### Deployment
+
+The dashboard is a static site and can be deployed to any static hosting service.
+
+#### GitHub Pages
+
+1. Build the dashboard: `trunk build --release`
+2. Copy the build output to the `docs/` directory (which GitHub Pages uses):
+   ```bash
+   cp -r dist/* ../docs/
+   ```
+3. Commit and push to GitHub. GitHub Pages will automatically serve from the `docs/` folder.
+   Alternatively, use the provided GitHub Actions workflow (`.github/workflows/dashboard.yml`) for automatic deployment on push to `main`.
+
+> **Note**: If your repository is served from a subpath (e.g., `https://username.github.io/edgebot-ai/`), you may need to set `public_url` in `edgebot-dashboard/trunk.toml` accordingly (e.g., `public_url = "/edgebot-ai"`).
+
+#### Netlify
+
+- Build command: `trunk build --release`
+- Publish directory: `edgebot-dashboard/dist`
+- Add an environment variable `EDGEBOT_SIM_SERVER_URL` if connecting to a remote simulation server.
+
+### Configuration
+
+- **Simulation Server**: By default, the dashboard connects to `http://localhost:8080`. Override via the `EDGEBOT_SIM_SERVER_URL` environment variable.
+- **License**: Pro license status is verified locally. Set `EDGEBOT_LICENSE_KEY` in the environment (or in your shell) to enable Pro features.
+
+### Architecture
+
+The dashboard integrates with the EdgeBot ecosystem via two main APIs:
+
+- **SimServerClient**: Fetches simulation jobs and results from the `edgebot-sim-server`.
+- **LicensingClient**: Checks local license verification using the `edgebot-licensing` crate.
+
+All data is fetched asynchronously using `wasm_bindgen_futures` and displayed using reactive Yew components.
+
+## Monetization & License Verification
+
+EdgeBot AI uses a freemium model:
+
+- **Free Core SDK**: All core inference, memory safety, ROS2 integration, and WebAssembly compilation remain open source under MIT/Apache-2.0.
+- **Pro Features**: Cloud simulation and advanced optimization require a paid subscription.
+
+### License Verification System
+
+The `edgebot-licensing` crate implements Ed25519-based license verification:
+
+- License keys are signed by EdgeBot AI's private key
+- Supports offline activation (no phone home)
+- Includes expiry dates and feature flags
+- Fast cryptographic verification using `ed25519-dalek`
+
+**Command-line usage:**
+
+```bash
+# Cloud simulation requires pro license
+edgebot simulate --model model.ebmodel --cloud --server https://sim.edgebot.ai
+
+# Model optimization requires pro license
+edgebot optimize --input model.onnx --output model.ebmodel --quantize int8 --fuse-layers
+```
+
+If no valid license is found, the commands will return an error with instructions.
+
+**Environment Variable:**
+
+Set `EDGEBOT_LICENSE_KEY` with your license key:
+
+```bash
+export EDGEBOT_LICENSE_KEY="signature_base64:payload_base64"
+```
+
+The license key format is two base64-encoded parts separated by a colon:
+- `signature`: Ed25519 signature over the payload
+- `payload`: JSON containing customer_id, timestamp, features, and optional expiry
+
+**Development License:**
+
+During development, you can generate test licenses using the `generate_dev_license` function (only available in debug builds):
+
+```rust
+#[cfg(debug_assertions)]
+let license = edgebot_licensing::generate_dev_license(
+    "test_customer",
+    vec!["cloud_sim", "optimization"],
+    "your_secret_key_base64"
+)?;
+```
+
+### Obtaining a Pro License
+
+Visit https://edgebot.ai/pricing to subscribe. After payment, you'll receive a license key via email. The key is valid for the subscription period and can be used on multiple machines.
+
+For enterprise deployments, offline activation tokens and custom feature flags are available. Contact sales@edgebot.ai.
+
+### Architecture Highlights
+
+### Zero-Copy Memory Safety
+
+The `edgebot-core/memory` module provides safe abstractions for sharing sensor data without memory copies between ROS2 messages and inference pipelines:
+
+```rust
+use edgebot_core::memory::{CameraBuffer, ImageFormat, ImageMetadata, ZeroCopyBuffer};
+
+// Create camera buffer from raw sensor data (zero-copy)
+let metadata = ImageMetadata::new(640, 480, ImageFormat::RGB);
+let mut buffer = CameraBuffer::new(metadata);
+
+// Fill buffer with ROS2 image data
+buffer.bytes_mut().copy_from_slice(&ros2_image_data);
+
+// Convert to Burn tensor (minimal copy if needed)
+let device = burn::backend::tch::TchBackend::Device::default();
+let tensor = buffer.to_tensor(&device);
+
+// Run inference
+// let output = inference_engine.forward(tensor);
+```
+
+**Key Types:**
+
+- `ZeroCopyBuffer<T>`: Safe buffer using `MaybeUninit` for uninitialized memory management
+- `CameraBuffer`: Zero-copy image buffer supporting RGB, BGR, RGBA, grayscale, depth
+- `LidarBuffer`: Point cloud buffer for LiDAR data (xyz, intensity, ring, timestamp)
+- `BorrowedBuffer<'a, T>`: Temporary view into initialized buffer data
+- ROS2 integration helpers (`Ros2ImageConverter`, `Ros2PointCloudConverter`)
+
+### Burn Integration
+
+The inference engine (`edgebot-core::inference`) supports multiple backends (Tch, Autocast) and model formats (ONNX, Burn binary):
+
+```rust
+use edgebot_core::inference::InferenceEngine;
+use burn::backend::tch::TchBackend;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let device = TchBackend::Device::default();
+
+    // Load ONNX model
+    let engine = InferenceEngine::<TchBackend>::load_onnx(
+        Path::new("model.onnx"),
+        &[1, 3, 224, 224], // input shape
+        device,
+    )?;
+
+    // Or load Burn binary
+    // let engine = InferenceEngine::<TchBackend>::load_bin(Path::new("model.bin"), device)?;
+
+    // Create input tensor (example)
+    let input = burn::tensor::Tensor::<TchBackend>::random(
+        [1, 3, 224, 224],
+        burn::tensor::Distribution::Uniform(-1.0, 1.0),
+        engine.device(),
+    );
+
+    // Run inference
+    let output = engine.forward(input)?;
+    println!("Output shape: {:?}", output.dims());
+
+    Ok(())
+}
+```
+
+### Model Optimizer
+
+Optimize models for edge deployment with quantization, pruning, and layer fusion using the `edgebot-optimize` CLI:
+
+```bash
+# Build the optimizer
+cargo build -p edgebot-core --bin edgebot-optimize --release
+
+# Optimize a model with int8 quantization
+./target/release/edgebot-optimize \
+  --input model.onnx \
+  --output model.ebmodel \
+  --quantize int8 \
+  --fuse-layers
+
+# With pruning (magnitude-based, 50% threshold)
+./target/release/edgebot-optimize \
+  --input model.onnx \
+  --output model.ebmodel \
+  --quantize fp16 \
+  --prune magnitude \
+  --pruning-threshold 0.5 \
+  --device cpu
+```
+
+**Output:** `.ebmodel` bundle containing optimized model + metadata (JSON with embedded binary).
+
+**CLI Options:**
+- `--quantize`: none/int8/fp16 (default: none)
+- `--prune`: none/magnitude/structured
+- `--pruning-threshold`: fraction of weights to prune (0.0-1.0)
+- `--fuse-layers`: enable layer fusion (Conv+ReLU, etc.)
+- `--device`: target device (cpu/cuda)
+
+**Optimization Stats:** The CLI prints size reduction, speedup estimates, and saves detailed stats in the .ebmodel bundle.
+
+### Webots Simulation
+
+The `edgebot-sim` crate provides integration with the Webots robotics simulator for testing AI models on virtual robots in a controlled environment. It offers a safe, Python-like Rust API and supports headless (no-GUI) mode for automated testing and CI.
+
+#### Features
+
+- **Supervisor control**: Launch simulations, spawn robots, and manipulate the scene.
+- **Sensor access**: Read data from cameras, LiDAR, distance sensors, IMU, GPS, etc.
+- **Headless mode**: Run simulations without a display, perfect for servers and CI.
+- **Remote control**: Connect to a running Webots instance or launch a new one directly from Rust.
+- **Zero-copy**: Efficient memory access to sensor data buffers.
+
+#### Usage Example
+
+```rust
+use edgebot_sim::webots::{Supervisor, Robot, Device, WebotsError};
+
+fn main() -> Result<(), WebotsError> {
+    // Launch Webots in headless mode with a world file
+    let supervisor = Supervisor::launch("worlds/warehouse.wbt", true)?;
+
+    // Spawn a robot from a prototype
+    let robot = supervisor.spawn_robot("prototypes/turtlebot3.proto", "test_bot")?;
+
+    // Step simulation to allow robot to initialize
+    supervisor.step(32)?;
+
+    // Get devices
+    let camera = robot.get_device("camera")?.as_camera()?;
+    let lidar = robot.get_device("lidar")?.as_lidar()?;
+    let wheel_motor = robot.get_device("wheel_left")?;
+
+    // Enable sensors with appropriate sampling period
+    camera.enable(32);
+    lidar.enable(32);
+
+    // Main simulation loop
+    for _ in 0..1000 {
+        supervisor.step(32)?;
+
+        // Retrieve camera image
+        let image = camera.get_image()?; // RGBA buffer
+        // Run inference with edgebot-core here...
+
+        // Retrieve lidar scan
+        let ranges = lidar.get_range_image()?; // Vec<f32>
+
+        // Simple obstacle avoidance example
+        if ranges.iter().any(|&r| r < 0.3) {
+            // Stop or reverse
+        }
+    }
+
+    // Clean shutdown
+    supervisor.terminate()?;
+    Ok(())
+}
+```
+
+#### Headless Mode
+
+Headless mode runs Webots without a graphical interface, ideal for automated testing and CI pipelines. Set the `WEBOTS_HOME` environment variable to your Webots installation directory:
+
+```bash
+export WEBOTS_HOME=/usr/local/webots
+cargo run --bin my_simulation_test
+```
+
+The `Supervisor::launch` function automatically starts Webots with `--batch` and `--no-rendering` flags.
+
+#### Remote Control
+
+You can also connect to an already running Webots instance (with remote control enabled on port 1234):
+
+```rust
+let supervisor = Supervisor::connect("localhost", 1234)?;
+```
+
+#### API Reference
+
+Key types:
+- `Supervisor`: Main simulation controller. Provides `spawn_robot`, `step`, `get_root`, `load_world`, etc.
+- `Robot`: Handle to a robot in the scene. Provides `get_device`, `get_node`, etc.
+- `Device`: Base device; can be cast to specific device types (`as_camera`, `as_lidar`, etc.).
+- `Node`: Scene tree node for robot and object manipulation.
+- `Field`: Access to node fields (position, rotation, children, etc.).
+
+Common methods:
+- `Supervisor::launch(world_path, headless)` -> Launch Webots and connect.
+- `Supervisor::spawn_robot(proto_url, name)` -> Create a new robot from prototype.
+- `Supervisor::step(ms)` -> Advance simulation.
+- `Device::enable(sampling_period)` -> Start sampling a sensor.
+- `Camera::get_image()` -> Get RGBA image bytes.
+- `Lidar::get_range_image()` -> Get distance measurements.
+
+For a full list of methods, see the API documentation or the source code in `edgebot-sim/src/webots.rs`.
+
+### ROS2 Bridge
+
+The `edgebot-ros2` crate provides ROS2 integration using the `rclrs` crate and standard ROS2 message definitions (`sensor_msgs`, `std_msgs`, `vision_msgs`). It enables publishing and subscribing to ROS2 topics with zero-copy message passing for sensor data (camera images, LiDAR). A YOLO inference example node is included, demonstrating how to subscribe to camera images, run inference with edgebot-core, and publish detection results.
+
+#### Running the YOLO Example
+
+```bash
+# Build the example node
+cargo build -p edgebot-ros2 --bin yolo_node --release
+
+# Run (requires a ROS2 environment and a camera topic publishing images)
+cargo run -p edgebot-ros2 --bin yolo_node -- --ros-args -p camera_topic:=/camera/color/image_raw
+```
+
+Note: The example currently uses a hardcoded model path `models/yolov8.onnx`. Place a suitable ONNX model in that location or modify the source code to point to your model.
+
+### WebAssembly Runtime
+
+The `edgebot-wasm` crate enables deployment of EdgeBot AI models in browser and IoT environments via WebAssembly. It provides:
+
+- **Browser support** (`wasm32-unknown-unknown`) with `wasm-bindgen` for JavaScript interop
+- **WASI support** (`wasm32-wasi`) for headless IoT devices
+- Zero-copy memory interfaces for efficient data passing between JS/Rust and WASM
+- Unified API for both targets with runtime selection
+
+#### Usage in JavaScript (Browser)
+
+```javascript
+// Import the WASM module (after building with `build-wasm.sh`)
+import init, { JsWasmRuntime } from './edgebot-wasm-browser.js';
+
+// Initialize the runtime
+await init();
+
+// Create runtime
+const runtime = new JsWasmRuntime();
+
+// Load a model (Uint8Array of .ebmodel or .onnx bytes)
+const modelBytes = await fetch('model.ebmodel').then(r => r.arrayBuffer());
+runtime.load_model('yolo', new Uint8Array(modelBytes));
+
+// Run inference
+const inputs = [{
+    name: 'input',
+    data: [/* float32 array */],
+    shape: [1, 3, 640, 640]
+}];
+const outputs = runtime.infer('yolo', inputs);
+
+console.log('Inference output:', outputs[0].data);
+```
+
+#### Usage in Rust (WASI)
+
+```rust
+use edgebot_wasm::{WasmRuntime, WasmTarget, WasmInferenceInput};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create WASI runtime
+    let mut runtime = WasmRuntime::new(WasmTarget::Wasi);
+
+    // Load model from file (WASI filesystem access)
+    let model_bytes = std::fs::read("/models/yolo.ebmodel")?;
+    runtime.load_model("yolo", model_bytes, None)?;
+
+    // Prepare input
+    let input = WasmInferenceInput {
+        name: "input".to_string(),
+        data: vec![0.0; 3 * 640 * 640],
+        shape: vec![1, 3, 640, 640],
+    };
+
+    // Run inference
+    let outputs = runtime.infer("yolo", &[input], None)?;
+    println!("Output shape: {:?}", outputs[0].shape);
+
+    Ok(())
+}
+```
+
+#### Building WASM Modules
+
+The `edgebot-wasm/build-wasm.sh` script builds optimized WASM binaries for both targets:
+
+```bash
+# Build browser target (default)
+./edgebot-wasm/build-wasm.sh browser
+
+# Build WASI target
+./edgebot-wasm/build-wasm.sh wasi
+
+# Build both targets
+./edgebot-wasm/build-wasm.sh all
+
+# Debug build
+./edgebot-wasm/build-wasm.sh browser --debug
+
+# With additional size optimizations
+./edgebot-wasm/build-wasm.sh browser --optimize
+```
+
+Output files are placed in `target/wasm/`:
+- `edgebot-wasm-browser.wasm` - Browser module (requires JS glue code)
+- `edgebot-wasm-wasi.wasm` - WASI standalone module
+
+#### Requirements
+
+Add to your Cargo.toml:
+```toml
+[dependencies]
+edgebot-wasm = { path = "edgebot-wasm" }
+
+# For browser builds
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+wasm-bindgen = "0.2"
+```
+
+Install wasm32 targets:
+```bash
+rustup target add wasm32-unknown-unknown wasm32-wasi
+```
+
+#### API Reference
+
+**Core Types:**
+- `WasmRuntime`: Unified runtime for model loading and inference
+- `WasmTarget`: Platform target (`Browser` or `Wasi`)
+- `WasmInferenceInput`: Input tensor with name, data (Vec<f32>), and shape
+- `WasmInferenceOutput`: Inference result with name, data, and shape
+
+**Key Methods:**
+- `WasmRuntime::new(target)` - Create runtime for specific platform
+- `load_model(name, bytes)` - Load model from bytes (requires .ebmodel or supported format)
+- `infer(model_name, inputs)` - Run inference with vector of inputs
+- `list_models()` - List loaded model names
+- `unload_model(name)` - Free model resources
+
+**Browser-Specific:**
+- `JsWasmRuntime`: Web-friendly runtime (automatically selected via `#[cfg(target_arch = "wasm32")]`)
+- `new()` constructor available from JavaScript
+- Methods return `Result<..., JsValue>` for proper error handling in JS
+
+**WASI-Specific:**
+- `WasiJsRuntime::new()` - Create WASI runtime
+- `load_model_from_path(name, path)` - Load model from filesystem
+- Automatic support for WASI environment (files, stdin/stdout)
+
+#### Performance Notes
+
+- Browser target uses WGPU for GPU acceleration (via Burn's wgpu backend)
+- WASI target uses CPU-optimized backends (Autocast, Tch)
+- Zero-copy memory interfaces minimize data marshaling overhead
+- Release builds with `opt-level = "z"` produce ~50% smaller WASM binaries
+- LTO and codegen-units=1 further reduce size
+
+## License
+
+MIT OR Apache-2.0. See [LICENSE](LICENSE) for details.
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Documentation
+
+Comprehensive documentation is available as a book:
+
+- **Online**: [https://edgebot-ai.github.io/edgebot-ai/](https://edgebot-ai.github.io/edgebot-ai/)
+- **Local**: `docs/book/` (markdown source) or `cargo doc --workspace --open`
+
+The documentation covers:
+
+- Quickstart guide
+- ROS2 integration
+- WebAssembly deployment
+- Pro workflow and licensing
+- API reference
+
+### Building the Docs
+
+```bash
+# Install mdbook (for book build)
+cargo install mdbook
+
+# Build the book
+mdbook build docs/book
+
+# Serve locally
+mdbook serve docs/book --open
+```
+
+The book is automatically published to GitHub Pages on pushes to `main`.
+
+---
+
+**Status:** Initial release candidate. API stabilizing.

docs/readmes/esp-robot-README.md

@@ -0,0 +1,281 @@
+# esp-robot
+**Repository:** Julien-ser/esp-robot
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** C++
+**Last Updated:** 2026-03-13T02:29:36Z
+
+---
+
+# ESP-32 Robot with Obstacle Avoidance
+
+An autonomous robot platform based on ESP32 with dual motor control and ultrasonic obstacle detection.
+
+## Hardware Components
+
+- ESP32 (esp32dev board)
+- Dual motor driver (L298N, TB6612, or compatible)
+- 2x DC motors with wheels
+- HC-SR04 ultrasonic sensor
+- Robot chassis kit
+- Power supply (7-12V for motors, 5V for ESP32)
+
+## GPIO Pin Configuration
+
+See `include/pin_config.h` for complete pin definitions.
+
+| Component    | Signal  | ESP32 Pin | Notes                        |
+|--------------|---------|-----------|------------------------------|
+| Motor A      | ENA     | GPIO13    | PWM speed control (ch0)      |
+| Motor A      | IN1     | GPIO12    | Direction                    |
+| Motor A      | IN2     | GPIO14    | Direction                    |
+| Motor B      | ENB     | GPIO27    | PWM speed control (ch1)      |
+| Motor B      | IN3     | GPIO26    | Direction                    |
+| Motor B      | IN4     | GPIO25    | Direction                    |
+| Ultrasonic   | TRIG    | GPIO23    | 5V tolerant                |
+| Ultrasonic   | ECHO    | GPIO22    | Requires voltage divider     |
+
+**Important:** ECHO pin needs a voltage divider (2.2kΩ + 3.3kΩ) to convert 5V→3.3V.
+
+## Project Structure
+
+```
+esp-robot/
+├── include/           # Header files
+│   └── pin_config.h   # Pin definitions and hardware constants
+├── src/              # Source code
+│   ├── main.cpp
+│   ├── Motor.cpp/h          # Individual motor control via PWM
+│   ├── MotorDriver.cpp/h    # Differential drive control
+│   ├── UltrasonicSensor.cpp/h  # HC-SR04 interface
+│   ├── ObstacleDetector.cpp/h   # Filtered distance reading
+│   ├── SensorArray.cpp/h        # Multi-sensor management
+│   ├── calibration.cpp/h       # Motor speed calibration
+│   └── Robot.cpp/h             # Main state machine (planned)
+├── test/             # Unit tests
+│   ├── motor_test.cpp
+│   └── sensor_test.cpp
+├── platformio.ini    # PlatformIO configuration
+├── TASKS.md          # Development progress
+└── README.md         # This file
+```
+
+## Calibration Procedure
+
+The motors may have different characteristics, so calibration is essential for accurate driving and turning.
+
+### What Calibration Does
+
+The calibration routine:
+1. Tests the robot at multiple PWM values (50-255)
+2. Measures actual speed (cm/s) for each motor
+3. Stores a PWM-to-speed lookup table in NVS (non-volatile storage)
+4. Enables speed compensation: you can request a speed in cm/s and the system converts to the correct PWM
+
+### How to Run Calibration
+
+1. Place the robot on a clear, level surface with a measured distance (default: 50cm)
+2. Upload the code with calibration support
+3. Open serial monitor at 115200 baud
+4. Send the `cal` command (or trigger calibration mode via code)
+5. Follow the prompts:
+   - For each PWM test value, place robot at start marker
+   - Press any key to start the test run
+   - Robot will drive forward at the test PWM
+   - Press any key when it reaches the end marker
+   - The system records time and calculates speed
+6. Repeat for both motors (left then right)
+7. Data is automatically saved to NVS and persists across reboots
+
+### Calibration Data Storage
+
+Data is stored in ESP32 NVS under namespace `robot_cal` with key `cal_data`. To clear calibration:
+- Send `cal_clear` command, OR
+- Call `calibration.clear()` in code
+
+### Using Calibrated Speeds
+
+After calibration, use:
+- `MotorDriver::driveForwardCalibrated(float speed_cm_s)` - drive at exact cm/s
+- `MotorDriver::turnCalibrated(uint8_t baseSpeed, int16_t degrees)` - precise turns using speed-based differential
+- `calibration.getPWMForSpeed('L' or 'R', desired_speed)` - manual PWM lookup
+
+## Current Progress
+
+✅ **Phase 1 Complete:**
+- [x] GPIO pin assignments defined in `include/pin_config.h`
+- [x] PlatformIO project initialization
+- [x] Directory structure and skeleton files
+- [x] Serial monitor configuration and blink test
+
+✅ **Phase 2 Complete:**
+- [x] Motor class with PWM speed control
+- [x] MotorDriver class with movement methods
+- [x] Unit tests for motor control
+- [x] Calibration routine with NVS storage
+
+✅ **Phase 3 Complete:**
+- [x] UltrasonicSensor class (NewPing library)
+- [x] ObstacleDetector with filtering and hysteresis
+- [x] Multi-sensor support via SensorArray
+- [x] Sensor tests (unit tests with mock ISonar interface)
+
+✅ **Phase 4 Complete:**
+- [x] Robot state machine (IDLE, DRIVING, AVOIDING, STOPPED)
+- [x] Obstacle avoidance algorithm
+- [x] Serial remote control with safety interlock
+- [x] Debug dashboard (1Hz serial output)
+- [x] Auto-start after 5s delay
+
+✅ **Phase 5 Complete:**
+- [x] Final integration test suite (`test/robot_integration_test.cpp`) with test doubles
+- [x] Full system documentation and assembly guide
+
+---
+
+### Testing
+
+The project includes a comprehensive integration test suite that validates the robot's state machine, motor control, and obstacle avoidance logic using test doubles.
+
+**Run tests with PlatformIO:**
+
+```bash
+pio test
+```
+
+The integration test uses mock implementations of `IMotorDriver` and `IObstacleDetector` to simulate sensor readings and verify motor outputs. It covers:
+- Initialization and IDLE state
+- Starting autonomous driving
+- Obstacle detection triggering avoidance
+- Full avoidance sequence (stop, reverse, pivot turn, resume)
+- Emergency stop and reset functionality
+- Manual command rejection when not in IDLE
+
+Test results are output to the serial monitor at 115200 baud when running on actual hardware, or displayed in the console for native builds.
+
+---
+
+## Serial Remote Control
+
+The robot can be controlled via serial commands (115200 baud). Commands are single characters:
+
+| Command | Description | Requirements |
+|---------|-------------|--------------|
+| w | Drive forward at default speed | Robot in IDLE state |
+| s | Drive backward | Robot in IDLE state |
+| a | Turn left (differential, ~90°) | Robot in IDLE state |
+| d | Turn right (differential, ~90°) | Robot in IDLE state |
+| q | Pivot counter-clockwise | Robot in IDLE state |
+| e | Pivot clockwise | Robot in IDLE state |
+| x | Emergency stop (brake) | Always accepted |
+| r | Reset from STOPPED to IDLE | Only from STOPPED |
+| ? or h | Show this help | Always accepted |
+
+**Safety Interlock:** Movement commands (w, s, a, d, q, e) are only accepted when the robot is in IDLE state. This prevents accidental commands during autonomous operation.
+
+**Auto-Start:** If the robot remains IDLE for 5 seconds, it automatically enters autonomous driving mode. Send commands before then to retain manual control.
+
+### Example Usage
+```bash
+# Open serial monitor
+screen /dev/ttyUSB0 115200
+
+# Press 'w' to drive forward (must be in IDLE)
+# Press 'x' for emergency stop
+# Press 'r' to reset after emergency stop
+```
+
+## Debug Dashboard
+
+The system outputs status information every 1 second:
+- Current state (IDLE, DRIVING, AVOIDING, STOPPED)
+- Movement status
+- Distance reading (mm)
+- Obstacle detection status
+
+Motor speeds can be added by connecting an ADC pin for battery monitoring (future enhancement).
+
+## Setup Instructions
+
+1. Install PlatformIO (VS Code extension or CLI)
+2. Create `platformio.ini` configured for `esp32dev` board
+3. Install required libraries: `NewPing`, `PID`, `AsyncTCP` (optional)
+4. Connect hardware according to pin configuration
+5. Build and flash to ESP32
+
+## Motor Control
+
+- PWM frequency: 5kHz
+- Speed range: 0-255 (8-bit)
+- Direction control via two GPIO pins per motor
+- Functionality: forward, backward, stop, brake, variable speed
+
+## Ultrasonic Sensor
+
+- Model: HC-SR04
+- Max range: 500cm (5m)
+- Trigger pulse: 10µs
+- Timeout: 30ms
+- Pin TRIG: output (5V compatible)
+- Pin ECHO: input with 5V→3.3V voltage divider
+
+## Obstacle Avoidance
+
+The robot implements a simple state machine with avoidance behavior:
+1. Drive forward continuously
+2. Monitor front distance
+3. If obstacle within 50cm: stop, reverse 0.5s, pivot turn 90°
+4. Resume driving
+
+## Calibration Procedure
+
+The motors may have different characteristics, so calibration is essential for accurate driving and turning.
+
+### What Calibration Does
+
+The calibration routine:
+1. Tests the robot at multiple PWM values (50-255)
+2. Measures actual speed (cm/s) for each motor
+3. Stores a PWM-to-speed lookup table in NVS (non-volatile storage)
+4. Enables speed compensation: you can request a speed in cm/s and the system converts to the correct PWM
+
+### How to Run Calibration
+
+1. Place the robot on a clear, level surface with a measured distance (default: 50cm)
+2. Upload the code with calibration support
+3. Open serial monitor at 115200 baud
+4. Send the `cal` command (or trigger calibration mode via code)
+5. Follow the prompts:
+   - For each PWM test value, place robot at start marker
+   - Press any key to start the test run
+   - Robot will drive forward at the test PWM
+   - Press any key when it reaches the end marker
+   - The system records time and calculates speed
+6. Repeat for both motors (left then right)
+7. Data is automatically saved to NVS and persists across reboots
+
+### Calibration Data Storage
+
+Data is stored in ESP32 NVS under namespace `robot_cal` with key `cal_data`. To clear calibration:
+- Send `cal_clear` command, OR
+- Call `calibration.clear()` in code
+
+### Using Calibrated Speeds
+
+After calibration, use:
+- `MotorDriver::driveForwardCalibrated(float speed_cm_s)` - drive at exact cm/s
+- `MotorDriver::turnCalibrated(uint8_t baseSpeed, int16_t degrees)` - precise turns using speed-based differential
+- `calibration.getPWMForSpeed('L' or 'R', desired_speed)` - manual PWM lookup
+
+## Power Requirements
+
+- ESP32: 5V via USB or regulator (draws ~200-500mA)
+- Motors: 7-12V depending on motor specs (up to 1A each under load)
+- Motor driver: Must match motor voltage, handle peak current
+
+Recommended: Separate power for motors and logic to avoid noise.
+
+## License
+
+TBD

docs/readmes/flash-quote-api-README.md

@@ -0,0 +1,142 @@
+# flash-quote-api
+**Repository:** Julien-ser/flash-quote-api
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-27T23:01:28Z
+
+---
+
+# flash-quote-api
+
+A tiny FastAPI service that returns random inspirational quotes.
+
+## Architecture
+
+**Storage Design:**
+- Quotes are stored in `quotes_data.json` (JSON array with id, text, author, category)
+- On startup, the entire JSON file is loaded into memory as a Python list
+- All API endpoints read from this in-memory array for maximum performance
+- This approach provides O(1) random access and O(n) category filtering with minimal overhead
+
+**Trade-offs:**
+- ✅ Fast read performance (no database queries)
+- ✅ Simple implementation and maintenance
+- ✅ No external dependencies beyond FastAPI
+- ⚠️ Data is read-only at runtime (modify JSON file to update quotes)
+- ⚠️ Memory usage scales with quote count (negligible for <1000 quotes)
+
+## Quick Start
+
+### Local Development
+
+```bash
+# Install dependencies
+pip install fastapi uvicorn
+
+# Run the server
+uvicorn main:app --reload
+```
+
+### Docker Deployment
+
+```bash
+# Build the Docker image
+docker build -t flash-quote-api .
+
+# Run the container
+docker run -p 8000:8000 flash-quote-api
+```
+
+The API will be available at http://localhost:8000
+
+## API Documentation
+
+The API provides three endpoints for accessing inspirational quotes. FastAPI automatically generates interactive OpenAPI/Swagger documentation at:
+
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+
+### Endpoints
+
+#### GET / (Root)
+
+Returns a single random quote.
+
+**Response:**
+```json
+{
+  "id": 42,
+  "text": "The only way to do great work is to love what you do.",
+  "author": "Steve Jobs",
+  "category": "motivation"
+}
+```
+
+#### GET /quotes
+
+Returns all quotes, with optional category filtering.
+
+**Query Parameters:**
+- `category` (optional): Filter quotes by category (e.g., "motivation", "life", "inspiration")
+
+**Example (all quotes):**
+```json
+[
+  {
+    "id": 1,
+    "text": "The only way to do great work is to love what you do.",
+    "author": "Steve Jobs",
+    "category": "motivation"
+  },
+  {
+    "id": 2,
+    "text": "Life is what happens when you're busy making other plans.",
+    "author": "John Lennon",
+    "category": "life"
+  }
+]
+```
+
+**Example (filtered by category=motivation):**
+```json
+[
+  {
+    "id": 1,
+    "text": "The only way to do great work is to love what you do.",
+    "author": "Steve Jobs",
+    "category": "motivation"
+  }
+]
+```
+
+#### GET /quote/{quote_id}
+
+Returns a specific quote by its unique ID.
+
+**Path Parameters:**
+- `quote_id`: The unique numeric identifier of the quote
+
+**Example response:**
+```json
+{
+  "id": 42,
+  "text": "The only way to do great work is to love what you do.",
+  "author": "Steve Jobs",
+  "category": "motivation"
+}
+```
+
+**Error responses:**
+- `404 Not Found`: When the specified quote ID does not exist
+
+## Project Status
+
+**Phase 1: Planning & Setup**
+- ✅ Quote data structure defined (JSON with id, text, author, category)
+- ✅ Storage method: JSON file loaded into memory at startup
+- ✅ Initialize FastAPI project with uv/pip
+- ✅ Set up tests directory and add unit tests
+
+See [TASKS.md](TASKS.md) for full development roadmap.

docs/readmes/football-management-sim-README.md

@@ -0,0 +1,577 @@
+# football-management-sim
+**Repository:** Julien-ser/football-management-sim
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** TypeScript
+**Last Updated:** 2026-03-17T08:01:48Z
+
+---
+
+# Football Manager Simulator
+
+**Version 0.1.0 (Beta)** | [Release Notes](docs/RELEASE_NOTES.md) | [User Manual](docs/USER_MANUAL.md)
+
+A strategic football management simulation game where you take charge of a football club and lead it to domestic and European glory.
+
+## 🎯 Mission
+
+Build, manage, and guide your football club through multiple seasons, balancing squad development, financial management, tactical innovation, and competition success across domestic leagues, cups, and European tournaments.
+
+## 🏆 Beta Release Ready (v0.1.0)
+
+The game is now **feature-complete** and ready for beta testing. All core systems implemented, tested, and optimized.
+
+### ✅ Current Status
+
+**Phase 1-3: All Complete** ✅
+
+All major features delivered:
+
+- Match simulation engine with AI team behavior
+- Comprehensive tactics & formations system
+- Full transfer market with scouting & negotiation
+- Multi-competition support (domestic + European)
+- Complete React-based UI with HUD, match day, menus
+- Audio system with crowds, events, and UI sounds
+- Save/load with 10 slots and auto-save
+
+**Phase 4: Testing & Deployment - In Progress**
+
+- ✅ Automated test suite: **348 tests** with **89.59%** coverage
+- ✅ Beta testing infrastructure and performance benchmarks
+- ✅ Gameplay balancing complete
+- ✅ **Release build ready** (`npm run build:web` → `dist-web/`)
+
+**Phase 4.4: Release Builds & Documentation** ⬜ **In Progress**
+
+- ✅ Web production build created
+- ✅ User manual written
+- ✅ Release notes prepared
+- ⬜ Promotional assets (screenshots, icons)
+- ⬜ Final deployment checklist
+
+See [Release Notes](docs/RELEASE_NOTES.md) for full details and [User Manual](docs/USER_MANUAL.md) for gameplay guide.
+
+---
+
+## 🚀 Quick Start
+
+### Play Now (No Installation)
+
+1. Download or clone this repository
+2. Navigate to `dist-web/` folder
+3. Open `index.html` in any modern browser
+   - OR serve with: `npx serve dist-web` or `python -m http.server -d dist-web`
+
+That's it! No build tools or dependencies needed to play.
+
+### For Development & Testing
+
+```bash
+# Install dependencies
+npm install
+
+# Run development server (hot reload)
+npm run dev
+
+# Build for production
+npm run build:web    # Build React frontend → dist-web/
+npm run build        # Build Node backend → dist/
+
+# Run tests
+npm test             # Unit tests (Jest)
+npm run test:e2e     # E2E tests (Cypress)
+npm run test:all     # All tests
+npm run benchmark    # Performance benchmarks
+
+# Preview production build locally
+npm run preview
+```
+
+**Requirements:** Node.js 18+, npm, modern browser
+
+---
+
+## 🎮 Core Features
+
+### Match Simulation Engine
+
+- Full 90+ minute simulation in **<5 seconds**
+- Event-driven mechanics: goals, cards, injuries, penalties, corners, fouls
+- Team AI with tactical awareness
+- Real-time stats: possession, shots, passes, fouls, corners, offsides
+- Performance: **27.2ms per match minute** (4x faster than 100ms target)
+
+### Tactics & Formation System
+
+- 6 preset formations (4-4-2, 4-3-3, 3-5-2, etc.)
+- Customizable tactical dimensions:
+  - Mentality (Defensive ↔ Attacking)
+  - Pressing (Low ↔ High)
+  - Passing Style (Short ↔ Long)
+  - Width (Narrow ↔ Wide)
+  - Defensive Line (Low ↔ High)
+- In-match tactical changes
+- Save/load custom tactic presets
+
+### Transfer Market
+
+- **Player Search:** Filter by position, rating, age, nationality, salary
+- **Scouting System:** Detailed reports with ratings, potential, strengths/weaknesses
+- **Negotiation:** Bidding, contract offers (wages, bonuses, length), counter-offers
+- **AI Clubs:** Computer teams actively participate in market
+- **Squad Registration:** Competition squad management with validation
+- **Budget Management:** Track fees, wages, ensure financial health
+
+### Competitions & Calendar
+
+- **Domestic League:** Round-robin format with promotion/relegation
+- **Domestic Cups:** Single-elimination tournaments
+- **European Competitions:**
+  - UEFA Champions League
+  - UEFA Europa League
+  - UEFA Conference League
+- **Calendar System:** Fixture generation, qualification rules, progression
+- **Match Scheduling:** Realistic season calendar
+
+### Interface & Experience
+
+- **Main Menu:** Start career, load game, settings
+- **Club Selection:** Browse and choose from playable clubs
+- **Game HUD:** Quick access to all management functions
+- **Match Day UI:** Live commentary, tactical overlay, animated stats
+- **Settings:** Graphics quality, audio controls, match speed, auto-save
+- **Save/Load:** 10 slots + auto-save with configurable intervals
+
+### Audio System
+
+- Crowd ambience and match event sounds
+- UI feedback sounds
+- Configurable volume controls (master, music, effects)
+- Mute support
+
+---
+
+## 🏗️ Architecture
+
+**Tech Stack:**
+
+| Component     | Technology              |
+| ------------- | ----------------------- |
+| Frontend UI   | React 18 + TypeScript 5 |
+| Build Tool    | Vite 5                  |
+| State/Events  | RxJS 7                  |
+| Backend (CLI) | Node.js + TypeScript    |
+| Database      | SQLite (better-sqlite3) |
+| Testing       | Jest + Cypress          |
+| Linting       | ESLint + Prettier       |
+
+**Architecture:** Layered clean architecture
+
+```
+Presentation Layer (React UI)
+    ↓
+Application Logic (Match Engine, Tactics, Transfers, etc.)
+    ↓
+Data Layer (SQLite + Models)
+```
+
+**Future Roadmap:**
+
+- Youth academy and training systems
+- Staff management
+- Club infrastructure upgrades
+- Historical statistics
+- Multiplayer cloud saves
+- Mobile responsiveness
+
+See [Technology ADR](docs/ADR-001-technology-stack.md) for detailed rationale.
+
+---
+
+## 📦 Build & Distribution
+
+### Production Builds
+
+**Web Version (Current):**
+
+```bash
+npm run build:web   # Creates dist-web/ with optimized bundles
+```
+
+Build outputs:
+
+- `dist-web/index.html` - Entry point (30 KB HTML)
+- `dist-web/assets/main-*.css` - Styles (30.59 KB, 5.59 KB gzipped)
+- `dist-web/assets/main-*.js` - JavaScript (230.62 KB, 69.13 KB gzipped)
+
+**Total Initial Load:** ~300 KB (very fast even on mobile)
+
+**Deployment:** Upload entire `dist-web/` folder to any static hosting service:
+
+- GitHub Pages, Netlify, Vercel (drag & drop)
+- AWS S3 + CloudFront
+- Any web server with static file support
+
+**Desktop Packages:** Not yet implemented. Would require Electron packaging.
+
+---
+
+## 🧪 Testing & Quality
+
+### Automated Test Suite
+
+- **348 total tests** covering all core systems
+- **Coverage:**
+  - Statements: 89.59%
+  - Branches: 81.34%
+  - Functions: 87.11%
+  - Lines: 91.01%
+
+**Test Types:**
+
+- Unit tests for models, utilities, game logic
+- Integration tests for workflows (match simulation, transfers, calendar)
+- E2E tests with Cypress for UI flows
+- Performance benchmarks (match speed, memory usage)
+
+### Performance Benchmarks
+
+| Metric           | Target     | Achieved          |
+| ---------------- | ---------- | ----------------- |
+| Match simulation | <100ms/min | **27.2ms/min** ✅ |
+| Memory usage     | <500MB     | **142MB** ✅      |
+| Test coverage    | ≥80%       | **>89%** ✅       |
+| Build size       | <500KB     | **~300KB** ✅     |
+
+---
+
+## 📚 Documentation
+
+All documentation is in the `docs/` folder:
+
+- **[Game Design Document (GDD)](docs/GDD.md)** - Complete design spec with features, wireframes, ER diagrams
+- **[User Manual](docs/USER_MANUAL.md)** - Comprehensive gameplay guide for players
+- **[Release Notes](docs/RELEASE_NOTES.md)** - Version history and changes
+- **[Technology ADR](docs/ADR-001-technology-stack.md)** - Architecture decisions and rationale
+- **[Beta Testing Guide](docs/BETA_TESTING.md)** - Testing procedures and templates
+- **[Beta Test Report](BETA_TEST_REPORT.md)** - Results and feedback summary
+- **[ER Diagram](docs/ER-diagram.md)** - Database schema visualization
+
+**Inline Documentation:**
+
+- All public functions and classes have TypeScript docstrings
+- Code is self-documenting with clear naming conventions
+
+---
+
+## 💾 Save System
+
+- 10 manual save slots
+- Auto-save after every match (configurable interval)
+- Save file format: JSON (human-readable)
+- Browser localStorage for persistence (local development)
+- File-based save system for production (via Node.js backend or future implementation)
+
+---
+
+## 🤝 Contributing
+
+This is currently a solo project. Contributions not accepted unless specified in future.
+
+**However, feedback is welcome:**
+
+- Bug reports via GitHub Issues
+- Feature suggestions via GitHub Discussions
+- Beta testing sign-ups (watch for announcements)
+
+---
+
+## 📋 Project Status
+
+**Phases 1-3: ✅ Complete**
+
+- ✅ Planning, design, and tech stack selection
+- ✅ Core systems: match engine, tactics, transfers, competitions
+- ✅ Complete UI: HUD, match day, menus, settings
+- ✅ Audio, animations, and polish
+
+**Phase 4: Testing & Deployment - 75% Complete**
+
+- ✅ Automated tests (348 tests)
+- ✅ Beta testing infrastructure
+- ✅ Performance optimization
+- ⬜ Promotional assets (in progress)
+- ⬜ Final deployment checklist
+
+**Phase 4.4: Release Builds & Documentation** - Current task
+
+Web build is ready, documentation created. Completing promotional assets and final verification.
+
+---
+
+## 🔮 Roadmap
+
+**Completed:**
+
+1. ✅ Phase 1: Planning & Setup
+2. ✅ Phase 2: Core Game Systems
+3. ✅ Phase 3: UI/UX & Polish
+4. 🔄 Phase 4: Testing & Deployment (near completion)
+
+**Upcoming (Post-Beta):**
+
+- Phase 5: Quality of Life improvements
+- Phase 6: Advanced features (youth academy, training, staff)
+- Phase 7: Community features and expansion
+
+See [TASKS.md](TASKS.md) for detailed task tracking.
+
+---
+
+## 📄 License
+
+To be determined - currently proprietary for beta testing.
+
+---
+
+## 🙏 Acknowledgments
+
+- **Testing:** Beta testers who provided invaluable feedback
+- **Tools:** Jest, Cypress, Vite, React, TypeScript communities
+- **Inspiration:** Classic football management games (Football Manager, Championship Manager)
+
+---
+
+## 🔗 Quick Links
+
+- **Play:** Open `dist-web/index.html` in browser
+- **Report Bug:** [GitHub Issues](.github/ISSUE_TEMPLATE/bug_report.md)
+- **Read Docs:** [docs/](docs/)
+- **View Roadmap:** [TASKS.md](TASKS.md)
+- **Source Code:** `src/` directory
+- **Tests:** `src/**/*.test.ts`, `cypress/e2e/`
+
+---
+
+**Enjoy your managerial career!** ⚽🏆
+
+_Lead your club to domestic and European glory!_
+
+## 🎮 Core Features
+
+- **Match Simulation Engine:** Full 90+ minute simulation in <5 seconds with realistic event-driven mechanics including:
+  - Goals, own goals, penalties, and missed penalties
+  - Yellow and red cards (including second yellow → red)
+  - Injuries and substitutions with AI decision-making
+  - Real-time statistics: possession, shots, passes, fouls, corners, offsides
+  - Tactical influence on match outcomes (formation, mentality, pressing, passing style)
+  - Event streaming via RxJS for live commentary and UI updates
+- **Tactics System:** Formation editor (4-4-2, 4-3-3, etc.), team/player instructions
+- **Transfer Market System (Phase 2 Complete):** Comprehensive player transfer management including:
+  - **Player Search & Filtering:** Search by position, rating, age, nationality, salary, contract expiry
+  - **Scouting System:** Hire scouts with region expertise, generate detailed reports with ratings, potential, strengths/weaknesses, and recommendations
+  - **Bidding & Negotiation:** Place bids, accept/reject/counter offers, contract negotiation with salary, bonuses, and contract length
+  - **AI Club Behavior:** Computer-controlled clubs actively participate in the transfer market, identifying squad needs and pursuing targets
+  - **Squad Registration:** Register players for competitions with position minimums, jersey number uniqueness, and captain/vice-captain assignments
+  - **Budget Management:** Track transfers fees, wages, and ensure financial viability with buffer requirements
+- **Competitions:** Domestic leagues, cups, and UEFA Champions League/Europa League/Conference League
+- **Squad Management:** Rosters, contracts, player development, injuries
+- **Club Finances:** Budgeting, revenue streams (matchday, TV, commercial), wage management
+- **Youth Academy:** Recruitment, development, promotion pathway
+- **Audio System:** Complete audio integration including crowd ambience, match event sounds (goals, cards, whistles), and UI feedback. Audio settings (master volume, music, sound effects, mute) are configurable in the Settings panel.
+- **Animations:** The interface includes smooth CSS animations for match commentary events, UI transitions, and interactive elements to enhance the visual experience.
+
+## 🏗️ Architecture
+
+The project follows a layered architecture:
+
+```
+Presentation Layer (Console UI → Future: React Web UI)
+    ↓
+Application Logic (Match Engine, Tactics, Transfer Market, etc.)
+    ↓
+Data Layer (SQLite database, models, serialization)
+```
+
+### Technology Stack
+
+**Core:**
+
+- **Language:** TypeScript 5.x
+- **Runtime:** Node.js 18+ (LTS)
+- **Database:** SQLite with `better-sqlite3` driver
+- **State/Events:** RxJS for reactive event handling
+
+**Development Tools:**
+
+- **Build:** TypeScript Compiler (`tsc`)
+- **Testing:** Jest + ts-jest
+- **Linting:** ESLint + @typescript-eslint
+- **Formatting:** Prettier
+- **CI/CD:** GitHub Actions (multi-version Node.js testing)
+
+**Future (Phase 3):**
+
+- **UI Framework:** React 18+ (for graphical interface)
+- **Styling:** Tailwind CSS or CSS Modules
+- **Routing:** React Router
+- **State Management:** React Context + hooks (or Zustand)
+
+**External APIs (Optional):**
+
+- football-data.org for real-world data integration
+- OpenFootball datasets for initial data bootstrapping
+
+See the [Architecture Decision Record](docs/ADR-001-technology-stack.md) for detailed rationale.
+
+See the [Game Design Document](docs/GDD.md) for:
+
+- Complete feature specification
+- Data models and ER diagrams
+- UI wireframes and layout designs
+- Performance requirements
+- Development phases and milestones
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Node.js 18+ (LTS) and npm
+- Git
+
+### Development Setup
+
+```bash
+# Clone repository
+git clone <repository-url>
+cd football-management-sim
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run the application
+npm start
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+### Project Structure
+
+```
+.
+├── docs/
+│   └── GDD.md           # Complete Game Design Document
+├── src/                 # Source code (to be created)
+├── tests/               # Test suite (to be created)
+├── data/                # Sample data, JSON fixtures
+├── TASKS.md             # Development task tracking
+├── README.md            # This file
+└── .github/workflows/   # CI/CD pipelines
+```
+
+## 🧪 Testing
+
+**Current Coverage: >89%** (Statements, Lines, Functions)
+
+The project includes a comprehensive automated test suite:
+
+- **Unit Tests:** Jest tests covering data models, utilities, match engine, tactics, transfer system, competitions, and UI components
+- **Integration Tests:** End-to-end workflows for match simulation, transfer market, squad registration, and calendar
+- **E2E Tests:** Cypress tests verifying complete user journeys through the React UI
+- **Performance Benchmarks:** Automated benchmarks for match simulation speed and memory usage
+
+### Running Tests
+
+```bash
+# Run all tests (unit + integration)
+npm test
+
+# Run with coverage report
+npm run test:coverage
+
+# Run E2E tests (Cypress)
+npm run test:e2e
+
+# Run all test suites
+npm run test:all
+
+# Run performance benchmarks
+npm run benchmark
+```
+
+### Continuous Integration
+
+Tests run automatically on every push and pull request via GitHub Actions:
+
+- Node.js 18.x and 20.x matrix
+- Linting, build, and test steps
+- Coverage thresholds enforced
+- Performance benchmarks included
+
+See `.github/workflows/test.yml` for CI configuration.
+
+## 🏆 Beta Testing
+
+The game has undergone structured beta testing with 5-10 external testers:
+
+- **Performance:** Excellent - 27.2ms per match minute (target: <100ms)
+- **Stability:** Zero crashes or data corruption
+- **Memory:** 142MB steady-state (target: <500MB)
+- **Feedback:** Positive overall, with minor bug fixes identified
+
+See [Beta Test Report](BETA_TEST_REPORT.md) for full results.
+
+### Bug Reporting
+
+Found an issue? Please use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) to file a GitHub issue with detailed reproduction steps.
+
+### Performance Targets
+
+- Match simulation: ≤100ms per match minute (achieved: 27.2ms)
+- Memory usage: <500MB steady state (achieved: 142MB)
+- Test coverage: ≥80% (achieved: 89.59%)
+- UI frame rate: 60 FPS (achieved)
+
+## 🤝 Contributing
+
+This is a solo development project for now. Contributions not accepted unless specified.
+
+## Saving and Loading
+
+- Access **Save Game** from the HUD's quick actions or **Load Game** from the main menu.
+- The game supports 10 manual save slots.
+- Auto-save is enabled by default every 5 minutes (adjustable in Settings).
+
+## 📄 License
+
+[To be determined]
+
+## 📚 Documentation
+
+- [Game Design Document](docs/GDD.md) - Comprehensive design specification
+- [Entity-Relationship Diagram](docs/ER-diagram.md) - Database schema visualization
+- [TASKS.md](TASKS.md) - Development roadmap
+- Inline code documentation (docstrings)
+
+## 🔮 Roadmap
+
+1. **Planning & Setup** (Tasks 1.1-1.4) → Complete GDD, choose tech stack, create data models
+2. **Core Game Systems** (Tasks 2.1-2.4) → Match engine, tactics, transfers, competitions
+3. **UI/UX & Polish** (Tasks 3.1-3.4) → Complete interface, match day UI, menus, assets
+4. **Testing & Deployment** (Tasks 4.1-4.4) → Automated tests, beta testing, performance tuning, release builds
+
+---
+
+**Status:** Early development phase - No playable build available yet.

docs/readmes/hipstercheck-README.md

@@ -0,0 +1,531 @@
+# hipstercheck
+**Repository:** Julien-ser/hipstercheck
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-17T00:14:46Z
+
+---
+
+# hipstercheck 🚀
+
+**AI-Powered Code Review for Indie Developers**
+
+> MVP READY FOR LAUNCH - Try the live demo at [https://hipstercheck.vercel.app](https://hipstercheck.vercel.app)
+
+hipstercheck is an AI-powered code review tool that scans GitHub repositories for bugs, optimization suggestions, and best practices. Built for solo coders and small teams working with Python, ROS2, or ML frameworks, it delivers comprehensive reviews in under 60 seconds through a simple web interface.
+
+## Key Features
+
+- 🔍 **Smart Code Analysis**: Detect bugs, performance issues, and style violations
+- 🤖 **AI-Powered Reviews**: Fine-tuned open-source LLM for accurate suggestions
+- 🚀 **GitHub Integration**: Seamless OAuth and repository scanning
+- 📝 **Manual Upload & Paste**: Try the Quick Demo on the landing page - upload files or paste code snippets directly without GitHub login
+- ⚡ **Fast Results**: Analysis completed in under 60 seconds
+- 💰 **Affordable**: $10/month per user with free tier (1 repo scan/week)
+- 🎯 **Specialized Support**: Python (PEP8), ROS2 best practices, ML frameworks (PyTorch, TensorFlow, scikit-learn)
+
+## 🎉 MVP Launch (March 2025)
+
+hipstercheck is now live and ready for users!
+
+**Live Demo**: [https://hipstercheck.vercel.app](https://hipstercheck.vercel.app)
+
+### What's Ready
+- ✅ Full GitHub OAuth integration
+- ✅ Repository scanning with rate limit handling
+- ✅ AI-powered code review using fine-tuned Phi-2 model
+- ✅ Support for Python, ROS2, ML frameworks (PyTorch, TensorFlow, scikit-learn)
+- ✅ Manual file upload and code paste
+- ✅ Dual-level caching (Redis/in-memory)
+- ✅ Stripe payments (Pro tier $10/month)
+- ✅ Free tier: 1 repo scan per week
+- ✅ Deployed on Vercel (backend) + Streamlit Cloud (frontend)
+- ✅ Comprehensive test suite passing
+- ✅ Ready for community feedback
+
+### Join the Beta
+We're looking for early adopters to test the MVP and provide feedback. Sign up for the free tier and help us improve!
+
+📢 **We're launching on Reddit and Indie Hackers!**  
+Follow our launch progress and share feedback:
+- r/Startup_Ideas
+- r/Python
+- r/MLQuestions
+- r/ROS2
+- Indie Hackers
+
+For launch materials and strategy, see [`launch/LAUNCH.md`](launch/LAUNCH.md).
+
+### Launch Metrics Goal
+- 🎯 50 free tier signups in first 30 days
+- 🎯 10 paid conversions
+- 🎯 500+ total visitors
+- 🎯 20+ meaningful feedback comments
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.9+
+- Git
+- GitHub account (for OAuth)
+- Hugging Face account (for AI model, Phase 2)
+
+### 1. Configure GitHub OAuth App
+
+Before running the app, you need to create a GitHub OAuth App:
+
+1. Go to [GitHub Developer Settings → OAuth Apps → New OAuth App](https://github.com/settings/developers)
+2. Fill in:
+   - **Application name**: hipstercheck (or your preferred name)
+   - **Homepage URL**: `http://localhost:8501` (or your deployed URL)
+   - **Authorization callback URL**: `http://localhost:8501` (or your deployed URL)
+3. Click "Register application"
+4. Copy the **Client ID** (generate a new client secret)
+5. Create a `.env` file from `.env.example` and add your credentials:
+   ```bash
+   cp .env.example .env
+   ```
+ 6. Edit `.env`:
+    ```bash
+    GITHUB_CLIENT_ID=your_client_id
+    GITHUB_CLIENT_SECRET=your_client_secret
+    APP_URL=http://localhost:8501
+    API_URL=http://localhost:8000
+    ```
+    *(Note: `APP_URL` must match the callback URL from step 2)*
+    *(Note: `API_URL` points to the FastAPI backend - start it with `python api.py`)*
+
+### 2. (Optional) Configure Stripe for Payments
+
+To enable paid subscriptions ($10/month Pro plan):
+
+1. Create a [Stripe account](https://stripe.com) (if you don't have one)
+2. Get your API keys from Stripe Dashboard → Developers → API keys:
+   - **Secret key** (starts with `sk_test_` or `sk_live_`)
+   - **Publishable key** (starts with `pk_test_` or `pk_live_`)
+3. Create a product and price in Stripe Dashboard → Products:
+   - Create product: "hipstercheck Pro"
+   - Add price: $10/month (recurring)
+   - Copy the **Price ID** (starts with `price_`)
+4. Set up a webhook endpoint in Stripe Dashboard → Developers → Webhooks:
+   - Endpoint URL: `https://your-app.com/api/stripe/webhook` (or `http://localhost:8000/stripe/webhook` for local)
+   - Select events: `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`
+   - Copy the **Webhook secret** (starts with `whsec_`)
+5. Add the following to your `.env`:
+
+```bash
+# Stripe API keys
+STRIPE_SECRET_KEY=sk_test_your_secret_key
+STRIPE_PUBLIC_KEY=pk_test_your_publishable_key
+STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
+STRIPE_PRICE_ID=price_your_price_id
+```
+
+**Note**: For local testing, you can use Stripe test mode and test cards (e.g., `4242 4242 4242 4242`). The fallback price ID in the code is for demo purposes; you should create your own.
+
+### 3. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 5. (Optional) Configure Redis for Caching
+
+To enable persistent caching across app restarts and multiple users:
+
+1. Install and run Redis:
+   ```bash
+   # Ubuntu/Debian
+   sudo apt-get install redis-server
+   sudo systemctl start redis
+   
+   # macOS
+   brew install redis
+   brew services start redis
+   
+   # Docker
+   docker run -p 6379:6379 redis:alpine
+   ```
+
+2. Add to your `.env`:
+   ```bash
+   REDIS_URL=redis://localhost:6379/0
+   ```
+
+   If Redis is not available, the app will fall back to in-memory caching.
+
+### 6. (Optional) Configure Rate Limit Buffer
+
+The app automatically monitors GitHub API rate limits and will wait when approaching the limit. You can adjust the buffer:
+
+```bash
+RATE_LIMIT_BUFFER=10
+```
+
+This sets how many remaining requests trigger a wait before the reset time.
+
+```bash
+streamlit run streamlit_app.py
+```
+
+### 3. (Optional) Run FastAPI Backend
+
+The FastAPI microservice provides the code analysis endpoint. To run it separately:
+
+```bash
+# Start the API server
+python api.py
+
+# Or with uvicorn directly
+uvicorn api:app --host 0.0.0.0 --port 8000 --reload
+```
+
+The API will be available at `http://localhost:8000` with:
+- `GET /health` - Health check endpoint
+- `POST /analyze` - Analyze single code snippet (5s timeout)
+- `POST /analyze/batch` - Analyze multiple snippets (max 50)
+
+### 4. Authenticate & Use
+
+1. Click **"Login with GitHub"** in the app
+2. Authorize the OAuth app on GitHub
+3. View your repositories in the dashboard
+4. (Future) Select a repo to analyze code
+
+## Backend Deployment
+
+### Backend Deployment
+
+The FastAPI backend is configured for serverless deployment on Vercel using Mangum.
+
+1. **Install Vercel CLI** (optional but recommended):
+   ```bash
+   npm i -g vercel
+   ```
+
+2. **Login to Vercel**:
+   ```bash
+   vercel login
+   ```
+
+3. **Link your project**:
+   ```bash
+   vercel link
+   ```
+   Follow the prompts to link your project. This uses the existing `vercel.json` configuration.
+
+4. **Set environment variables in Vercel dashboard**:
+
+   After linking, go to your project settings in the Vercel dashboard (https://vercel.com/[your-org]/hipstercheck/settings/environment-variables) and add all variables from `.env.example`:
+
+   - `GITHUB_CLIENT_ID` - From your GitHub OAuth app
+   - `GITHUB_CLIENT_SECRET` - From your GitHub OAuth app
+   - `APP_URL` - Your Vercel frontend URL (e.g., `https://hipstercheck.vercel.app`)
+   - `HF_TOKEN` - Your Hugging Face token (for model inference)
+   - `STRIPE_SECRET_KEY` - Your Stripe secret key
+   - `STRIPE_PUBLIC_KEY` - Your Stripe publishable key
+   - `STRIPE_WEBHOOK_SECRET` - Your Stripe webhook signing secret
+   - `STRIPE_PRICE_ID` - Your Stripe price ID for Pro subscription
+   - `REDIS_URL` (optional) - Redis connection URL for persistent caching
+   - `CACHE_TTL_HOURS` (optional) - Cache TTL in hours, default 24
+   - `RATE_LIMIT_BUFFER` (optional) - GitHub API rate limit buffer, default 10
+
+   Alternatively, set them via CLI:
+   ```bash
+   vercel env add GITHUB_CLIENT_ID production
+   vercel env add HF_TOKEN production
+   # ... repeat for each variable
+   ```
+
+5. **Deploy the backend**:
+   ```bash
+   vercel --prod
+   ```
+
+   The API will be available at:
+   - `https://your-project.vercel.app/api/health` (health check)
+   - `https://your-project.vercel.app/api/analyze` (analysis endpoint)
+   - `https://your-project.vercel.app/api/stripe/*` (Stripe endpoints)
+
+6. **Enable Vercel Analytics**:
+
+   In the Vercel dashboard, enable **Analytics** for your project to monitor:
+   - Request count and duration
+   - Error rates
+   - Function invocations
+
+   Vercel automatically collects backend metrics. View them under the "Analytics" tab.
+
+### Updating Frontend Configuration
+
+After deploying the backend, update your `.env` file for the Streamlit frontend:
+
+```bash
+API_URL=https://your-project.vercel.app
+```
+
+### Monitoring & Logs
+
+- **Real-time logs**: `vercel logs your-project.vercel.app --follow`
+- **Performance metrics**: Vercel dashboard → Analytics
+- **Alerts**: Set up notifications in Vercel dashboard
+
+### Notes
+
+- Backend uses `mangum` for ASGI-to-serverless adapter
+- Cold start: ~1-2 seconds for first request after inactivity
+- Redis recommended for production caching; falls back to in-memory if unavailable
+- Ensure Hugging Face token has `read` permissions for model access
+
+---
+
+## Frontend Deployment
+
+The Streamlit frontend can be deployed either on Streamlit Community Cloud (recommended) or on Vercel using Docker.
+
+### Prerequisites
+
+- GitHub repository with the hipstercheck code
+- Backend already deployed on Vercel (or another accessible URL)
+- Environment variables configured (see `.env.example`)
+
+### Option 1: Streamlit Community Cloud (Recommended)
+
+Streamlit Community Cloud provides free hosting for Streamlit apps with minimal configuration.
+
+1. **Push your code to GitHub** (if not already):
+   ```bash
+   git add .
+   git commit -m "Prepare for deployment"
+   git push origin main
+   ```
+
+2. **Go to [Streamlit Cloud](https://streamlit.io/cloud) and sign up** (you can use your GitHub account).
+
+3. **Create a new app**:
+   - Click **"New app"**.
+   - Choose your GitHub repository and branch (e.g., `main`).
+   - Set **Main file path** to `streamlit_app.py`.
+   - Leave the other settings as default.
+
+4. **Configure environment variables**:
+   In the app's settings (gear icon), go to **Secrets** and add each variable from your `.env.example`:
+   - `GITHUB_CLIENT_ID`
+   - `GITHUB_CLIENT_SECRET`
+   - `APP_URL` (set to your Streamlit Cloud URL, e.g., `https://your-app.streamlit.app`)
+   - `API_URL` (set to your deployed backend URL, e.g., `https://hipstercheck.vercel.app`)
+   - `HF_TOKEN` (if using local model inference)
+   - `STRIPE_SECRET_KEY`, `STRIPE_PUBLIC_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PRICE_ID` (if enabling payments)
+   - Optional: `REDIS_URL`, `CACHE_TTL_HOURS`, `RATE_LIMIT_BUFFER`
+
+   Alternatively, you can set these in the **Settings → Secrets** section.
+
+5. **Deploy**:
+   Click **"Deploy"**. Streamlit Cloud will build and deploy your app automatically. The deployment usually takes a few minutes.
+
+6. **Verify**:
+   Once deployed, open your app URL and test the functionality. Ensure the OAuth callback works and that code analysis calls reach the backend.
+
+### Option 2: Vercel with Docker (Advanced)
+
+If you prefer to host the frontend on Vercel, you can containerize the Streamlit app using Docker.
+
+1. **Create a `Dockerfile`** in the project root (if not already present):
+   ```dockerfile
+   FROM python:3.11-slim
+
+   WORKDIR /app
+
+   RUN apt-get update && apt-get install -y --no-install-recommends \
+       build-essential \
+       && rm -rf /var/lib/apt/lists/*
+
+   COPY requirements.txt .
+   RUN pip install --no-cache-dir -r requirements.txt
+
+   COPY . .
+
+   ENV PYTHONUNBUFFERED=1
+   EXPOSE 8501
+
+   CMD ["sh", "-c", "uvicorn api:app --host 0.0.0.0 --port 8000 & streamlit run streamlit_app.py --server.port $PORT --server.address 0.0.0.0"]
+   ```
+
+   This Dockerfile runs both the FastAPI backend (on port 8000 internally) and the Streamlit frontend (on the Vercel-provided `$PORT`). The frontend will communicate with the backend via `http://localhost:8000`.
+
+2. **Update `vercel.json`** to use Docker:
+   ```json
+   {
+     "version": 2,
+     "builds": [
+       {
+         "src": "Dockerfile",
+         "use": "@vercel/docker"
+       }
+     ],
+     "routes": [
+       {
+         "src": "/(.*)",
+         "dest": "/"
+       }
+     ]
+   }
+   ```
+
+3. **Set environment variables in Vercel**:
+   When you create a new Vercel project (or update the existing one), add all environment variables from `.env.example` in the Vercel dashboard → Project Settings → Environment Variables. Ensure `APP_URL` matches your Vercel frontend URL and `API_URL` is set to `http://localhost:8000` (since the backend is in the same container).
+
+4. **Deploy**:
+   ```bash
+   vercel --prod
+   ```
+
+5. **Notes**:
+   - The combined container starts both the backend and frontend. FastAPI runs in the background and is only accessible internally; all external traffic goes to Streamlit.
+   - If you already have a separate backend deployment, you can modify `API_URL` to point to that external URL instead.
+   - Vercel's Docker builds may take longer than serverless builds.
+
+### Adding a Custom Domain
+
+Both Streamlit Cloud and Vercel support custom domains:
+
+- **Streamlit Cloud**: In your app settings, go to **Settings → Custom domain**, add your domain, and follow the DNS verification instructions.
+- **Vercel**: In the Vercel dashboard, go to your project's **Domains** settings and add your domain. Vercel automatically provisions an SSL certificate.
+
+After adding a custom domain, update the `APP_URL` environment variable to match the new domain.
+
+---
+
+**Important**: The frontend requires the backend to be running and accessible. Ensure your backend deployment is healthy before connecting the frontend.
+
+## Project Structure
+
+```
+hipstercheck/
+├── api.py                    # FastAPI microservice (Phase 3)
+├── streamlit_app.py          # Main Streamlit frontend
+├── requirements.txt          # Python dependencies
+├── .env                      # Environment variables (create from .env.example)
+├── dataset/                  # Code review dataset collection
+│   ├── data_collector.py    # Dataset collection script
+│   ├── code_reviews.jsonl   # Combined dataset (generated)
+│   ├── split_train.jsonl    # Training split
+│   ├── split_val.jsonl      # Validation split
+│   ├── split_test.jsonl     # Test split
+│   └── README.md            # Dataset documentation
+├── models/                  # Fine-tuned AI model
+├── prompts/                 # Prompt templates for different languages
+├── tests/                   # Unit and integration tests
+├── README.md               # This file
+└── TASKS.md                # Development task tracking
+```
+
+## 📋 Development Status
+
+**All Phases Complete** ✅ MVP Ready for Launch
+
+### Phase 1: Foundation & GitHub Integration ✅ Completed
+- [x] Initialize Streamlit project structure
+- [x] Implement GitHub OAuth authentication
+- [x] Build repo scanning engine
+- [x] Configure GitHub API rate limiting with caching
+
+### Phase 2: Model Training & Code Analysis ✅ Completed
+- [x] Collect code review dataset (15K+ examples)
+- [x] Select base LLM (Microsoft Phi-2, 2.7B parameters)
+- [x] Fine-tune model with LoRA on code review generation
+- [x] Create prompt engineering templates for Python, ROS2, ML frameworks
+
+### Phase 3: App Integration & Deployment Prep ✅ Completed
+- [x] Wrap model in FastAPI microservice
+- [x] Integrate model calls into Streamlit with color-coded UI
+- [x] Implement dual-level caching (repo scan + review results)
+- [x] Set up Stripe subscription ($10/month Pro tier)
+
+### Phase 4: Testing, Deployment & Validation ✅ Completed
+- [x] Test with personal ROS2/ML projects
+- [x] Deploy backend on Vercel (serverless FastAPI)
+- [x] Deploy Streamlit frontend on Streamlit Community Cloud
+- [x] Validate via Reddit/Indie Hackers (launch materials prepared)
+
+**Next**: Community feedback collection and iterative improvements based on user input. See [`launch/ROADMAP.md`](launch/ROADMAP.md) for post-launch plan.
+
+## Caching
+
+hipstercheck implements **two-level caching** to optimize performance and reduce costs:
+
+### 1. Repository Scan Cache
+Scanning a repository clones it and extracts the file tree, which can be slow and rate-limited by GitHub. Results are cached for 24 hours with Redis (preferred) or in-memory fallback.
+
+**Cache Key**: Repository name + branch (hashed)
+
+**Cache Invalidation**: 
+- Automatic: Entries expire after 24 hours
+- Manual: Use "Re-Scan" button for fresh scan
+- Global: "Clear All Cache" button clears everything
+
+**Configuration**:
+```bash
+# Add to .env (optional)
+REDIS_URL=redis://localhost:6379/0
+CACHE_TTL_HOURS=24
+```
+
+If Redis is unavailable, the app falls back to in-memory caching (lost on restart).
+
+### 2. Code Review Cache
+Individual code file analyses are cached to avoid unnecessary model inference. This significantly reduces compute costs and improves response time.
+
+**Cache Key**: SHA256 hash of (code content + language)
+
+**Statistics**: Real-time hit/miss rates displayed in the UI. Typical hit rates >60% for repeated analyses.
+
+**Configuration**:
+```bash
+CACHE_TTL_HOURS=24  # Review cache TTL (default: 24 hours)
+```
+
+### Cache Performance Tips
+- ✅ **High cache hit rates** when scanning the same repo multiple times
+- ✅ **Fast re-scans** - bypass GitHub clone, instant results from cache
+- ✅ **Reduced model calls** - saves GPU/compute costs
+- ✅ **Offline capability** - memory cache works without Redis
+
+### Monitoring
+The dashboard displays:
+- **Scan Cache**: Backend type (Redis/Memory), total cached repos
+- **Review Cache**: Hit rate, total requests, backend
+- **Expandable details** in the "📊 Detailed Cache Statistics" section
+
+Use "Clear All Cache" to reset statistics and force fresh analyses.
+
+## Architecture
+
+### Tech Stack
+- **Frontend**: Streamlit (responsive UI, rapid prototyping)
+- **Backend**: FastAPI (async API, high performance)
+- **AI Model**: Phi-2 (2.7B parameters) fine-tuned with LoRA for code review
+- **Training**: PyTorch + Hugging Face Transformers + PEFT (LoRA)
+- **Database**: SQLite/Redis for caching
+- **Deployment**: Vercel (serverless)
+- **Payment**: Stripe Checkout
+
+### Data Flow
+1. User authenticates via GitHub OAuth
+2. Repository files are scanned and parsed
+3. AI model analyzes code for issues
+4. Results displayed with severity levels and suggestions
+5. Cached for future reference
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+This is a solo project for now. For feedback or collaboration, reach out via GitHub Issues.

docs/readmes/internlearningnetwork-README.md

@@ -0,0 +1,327 @@
+# internlearningnetwork
+**Repository:** Julien-ser/internlearningnetwork
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** HTML
+**Last Updated:** 2026-03-16T22:17:58Z
+
+---
+
+# InternLearningNetwork
+
+**Mission:** Allows interns all over the place to share anything they found/learned in a new blog-like system, with a gamified way of levelling up with new skills and points and also points for sharing something that gives other users skills.
+
+## Tech Stack
+
+- **Frontend**: React + Vite, TypeScript
+- **Backend**: Node.js + Express, TypeScript
+- **Database**: PostgreSQL
+- **ORM**: Prisma
+- **Authentication**: JWT + bcrypt
+- **Architecture**: Monorepo structure
+
+## Project Structure
+
+```
+internlearningnetwork/
+├── client/          # React frontend application
+│   ├── src/
+│   │   ├── components/   # Reusable UI components
+│   │   ├── pages/        # Page components
+│   │   ├── services/     # API client
+│   │   └── types/        # TypeScript definitions
+│   └── package.json
+├── server/          # Express backend API
+│   ├── src/
+│   │   ├── routes/       # API route handlers
+│   │   ├── middleware/   # Auth, validation, etc.
+│   │   ├── services/     # Business logic
+│   │   ├── prisma/       # Database schema & migrations
+│   │   └── utils/        # Helper functions
+│   └── package.json
+├── shared/          # Shared TypeScript types & utilities
+│   └── src/
+│       ├── types/        # Common type definitions
+│       └── validations/  # Shared validation schemas
+├── .github/workflows/
+│   └── test.yml    # CI/CD pipeline (to be created)
+├── TASKS.md        # Development task list
+└── README.md       # This file
+```
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Frontend (React)                   │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐  │
+│  │   PostFeed  │ │CreatePost   │ │    UserProfile      │  │
+│  └─────────────┘ └─────────────┘ └─────────────────────┘  │
+│         │                │                   │             │
+│         └────────────────┼───────────────────┘             │
+│                          │                                 │
+│                  ┌───────▼────────┐                        │
+│                  │  API Client    │ (axios/fetch)         │
+│                  └────────┬───────┘                        │
+└───────────────────────────┼─────────────────────────────────┘
+                            │ HTTPS/REST API
+                            │ JWT Auth
+┌───────────────────────────▼─────────────────────────────────┐
+│                    Backend (Express)                       │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐  │
+│  │   Auth API  │ │  Posts API  │ │  Skills & Points    │  │
+│  └─────────────┘ └─────────────┘ └─────────────────────┘  │
+│         │                │                   │             │
+│         └────────────────┼───────────────────┘             │
+│                          │                                 │
+│                  ┌───────▼────────┐                        │
+│                  │  Middleware    │ (auth, validation)    │
+│                  └────────┬───────┘                        │
+│                          │                                 │
+│                  ┌───────▼────────┐                        │
+│                  │  Services      │ (business logic)      │
+│                  └────────┬───────┘                        │
+└─────────���─────────────────┼─────────────────────────────────┘
+                            │ Prisma ORM
+┌───────────────────────────▼─────────────────────────────────┐
+│                 PostgreSQL Database                        │
+│  ┌────────┐ ┌───────┐ ┌──────┐ ┌─────────┐ ┌──────────┐  │
+│  │  users │ │ posts │ │skills││user_skills│points_log│  │
+│  └────────┘ └───────┘ └──────┘ └─────────┘ └──────────┘  │
+│  ┌────────┐ ┌──────────────────────────────────────────┐   │
+│  │ levels │ │        levels (calculated/derived)       │   │
+│  └────────┘ └──────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Database Schema
+
+### Core Tables
+- **users**: id, email, password_hash, username, created_at, updated_at
+- **posts**: id, title, content, author_id (FK), created_at, updated_at
+- **skills**: id, name, description, created_at
+- **post_skills**: post_id (FK), skill_id (FK) - junction table for many-to-many
+- **user_skills**: user_id (FK), skill_id (FK), claimed_at, source_post_id (FK) - tracks skills users have claimed
+- **points_log**: id, user_id (FK), points, action_type, reference_id (post/skill), created_at
+- **levels**: id, level_number, min_points, max_points (or use calculated levels)
+
+### Relationships
+- User ↔ Post: One-to-many (one author, many posts)
+- Post ↔ Skill: Many-to-many via post_skills
+- User ↔ Skill: Many-to-many via user_skills (skills they've claimed)
+- User ↔ Points: One-to-many via points_log (point history)
+- User ↔ Level: Calculated based on total points
+
+## Current Progress
+
+**Phase 1: Planning & Setup**
+- ✅ Technical stack defined (Node.js + Express, React, PostgreSQL, Prisma, JWT)
+- ✅ Architecture diagram created
+- ✅ Monorepo structure initialized with package.json files
+- ✅ Root workspace configuration created
+- ✅ Prisma schema designed
+- ✅ `.env.example` created and dependencies installed
+
+**Phase 2: Core Backend & Authentication**
+- ✅ Implemented user registration/login endpoints with JWT token generation using bcrypt
+  - `POST /api/auth/register` - User registration with email, username, password
+  - `POST /api/auth/login` - User login, returns JWT token
+  - `GET  /api/auth/me` - Get authenticated user's profile (requires Bearer token)
+- ✅ Created CRUD API for blog posts with validation middleware
+  - Posts include skill_tags array for associating skills
+- ✅ Built skill management system with full CRUD endpoints (authenticated)
+  - `GET    /api/skills` - List all skills
+  - `GET    /api/skills/:id` - Get skill details
+  - `POST   /api/skills` - Create new skill (requires authentication)
+  - `PUT    /api/skills/:id` - Update skill (requires authentication)
+  - `DELETE /api/skills/:id` - Delete skill (requires authentication)
+  - Skills can be associated with posts via skill_tags field
+- ✅ Implemented post approval system that assigns skills to authors
+  - `PUT /api/posts/:id/approve` - Approve post and automatically assign associated skills to the author (requires authentication)
+
+## Getting Started
+
+### Prerequisites
+- Node.js 18+ installed
+- PostgreSQL database running
+- Git
+
+### 1. Environment Configuration
+
+Copy the example environment file and update with your values:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and configure:
+- `DATABASE_URL`: Your PostgreSQL connection string
+- `JWT_SECRET`: A secure random string for JWT signing
+
+### 2. Database Setup
+
+Generate Prisma client and create/update database schema:
+
+```bash
+npx prisma generate
+npx prisma db push
+```
+
+(Optional) Seed the database with initial data:
+
+```bash
+npx prisma db seed
+```
+
+### 3. Running the Application
+
+**Development mode** (runs both frontend and backend):
+
+```bash
+npm run dev
+```
+
+Or run them separately:
+
+```bash
+# Backend only (server on port 3001)
+npm run dev:server
+
+# Frontend only (client on port 5173)
+npm run dev:client
+```
+
+**Build for production:**
+
+```bash
+npm run build
+```
+
+**Run linter:**
+
+```bash
+npm run lint
+```
+
+### 4. Access the Application
+
+- Frontend: http://localhost:5173
+- Backend API: http://localhost:3001/api
+- API Health check: http://localhost:3001/api/health (to be implemented)
+
+## Deployment
+
+### Prerequisites
+- Accounts on Vercel/Netlify (for frontend) and Railway/Render (for backend)
+- A PostgreSQL database (e.g., Supabase, Neon, AWS RDS, or any PostgreSQL provider)
+- GitHub repository connected to your deployment platforms
+
+### Frontend Deployment (Vercel / Netlify)
+
+1. Import your repository as a new project in Vercel or Netlify.
+2. Set the **Root Directory** to `client` (since it's a monorepo).
+3. Configure build settings:
+   - **Build Command**: `npm run build` (or `npm run build --workspace=client`)
+   - **Output Directory**: `dist` (Vite's default)
+4. Add environment variables:
+   - `VITE_API_URL`: Your backend API URL (e.g., https://your-backend.onrender.com/api)
+5. Deploy. The platform will install dependencies, build, and serve the static files.
+
+### Backend Deployment (Railway / Render)
+
+1. Create a new service on Railway or Render and connect your repository.
+2. Set the **Root Directory** to `server`.
+3. Configure build and start commands:
+   - **Build Command**: `npm run build` (or `npm run build --workspace=server`)
+   - **Start Command**: `npm start` (or `npm start --workspace=server`)
+4. Add environment variables:
+   - `DATABASE_URL`: Your PostgreSQL connection string
+   - `JWT_SECRET`: A secure random string for JWT signing
+   - `NODE_ENV`: `production`
+   - (Optional) `PORT`: The port your server should listen on (default 3001)
+5. Add a **Post-Deploy** script (Railway) or **After Build** hook to run migrations and seed:
+   - `npx prisma migrate deploy`
+   - `npx prisma db seed` (optional, for demo data)
+6. Deploy. The platform will build the TypeScript code, apply database migrations, and start the server.
+
+### Database Setup
+- Create a PostgreSQL database and obtain the connection URL.
+- Ensure the database user has privileges to create tables and indexes.
+- Update the `DATABASE_URL` in your production environment.
+
+### Notes
+- The project uses Prisma ORM. Migrations are stored in `server/prisma/migrations`.
+- The seed script (`server/prisma/seed.ts`) creates demo skills, levels, and an admin user (`admin@example.com` / `admin123`).
+- For security, change the default admin password after first login and use a strong `JWT_SECRET`.
+
+## API Endpoints
+
+### Authentication ✅
+- `POST /api/auth/register` - User registration
+  - Body: `{ email, username, password }`
+  - Returns: `{ message, user: { id, email, username, createdAt }, token }`
+- `POST /api/auth/login` - User login
+  - Body: `{ email, password }`
+  - Returns: `{ message, user: { id, email, username, createdAt, totalPoints, level }, token }`
+- `GET  /api/auth/me` - Get current user profile **(requires Bearer token)**
+  - Headers: `Authorization: Bearer <jwt_token>`
+  - Returns: `{ user: { id, email, username, createdAt, totalPoints, level, userSkills } }`
+
+### Posts
+- `GET    /api/posts` - List all posts (with skill tags)
+- `GET    /api/posts/:id` - Get single post
+- `POST   /api/posts` - Create new post
+- `PUT    /api/posts/:id` - Update post
+- `DELETE /api/posts/:id` - Delete post
+
+### Skills
+- `GET    /api/skills` - List all skills
+- `GET    /api/skills/:id` - Get skill details
+- `POST   /api/skills` - Create new skill (requires authentication)
+- `PUT    /api/skills/:id` - Update skill (requires authentication)
+- `DELETE /api/skills/:id` - Delete skill (requires authentication)
+
+### Claims (Skill Claiming)
+- `POST   /api/claims/posts/:postId/skills/:skillId/claim` - Claim a skill from a post (requires authentication)
+  - Awards 5 points to the post author
+  - Adds the skill to the claimant's profile
+- `GET    /api/claims/user/skills` - Get authenticated user's claimed skills (requires authentication)
+
+### Leveling
+- `GET    /api/level` - Get user's current level information (requires `userId` query param)
+  - Query: `?userId=1`
+  - Returns: `{ userId, totalPoints, currentLevel, levelName, minPoints, maxPoints, pointsToNextLevel }`
+- `POST   /api/level/calculate` - Calculate what level a given point total would be
+  - Body: `{ points: 250 }`
+  - Returns: `{ points, level, levelName, minPoints, maxPoints, pointsToNextLevel }`
+- `POST   /api/level/update` - Update user's level based on current points (called after point allocations)
+  - Query: `?userId=1`
+  - Returns: `{ userId, totalPoints, currentLevel, levelName, message }`
+
+**Leveling Algorithm:** Exponential thresholds with base 100 and multiplier 1.5
+- Level 1: 0 - 99 points
+- Level 2: 100 - 149 points
+- Level 3: 150 - 224 points
+- Level 4: 225 - 336 points
+- Level 5: 337 - 505 points
+- Level 6: 506 - 758 points
+- Level 7: 759 - 1138 points
+- Level 8: 1139 - 1707 points
+- Level 9: 1708 - 2561 points
+- Level 10: 2562+ points
+
+### Posts
+    - Skills can be attached to posts (like hashtags)
+    - Other users can "claim" skills from posts
+    - Claiming a skill adds it to the user's profile AND awards points to the post author
+4. **Gamification**:
+   - Points awarded: +10 for creating a post, +5 per skill claimed from your post
+   - Level progression based on total points
+   - Points log tracks all transactions
+5. **User Profiles**: Display level, points, earned skills with dates, recent activity
+6. **Leaderboard**: Competitive ranking based on points and level
+
+## License
+
+TBD

docs/readmes/invoice-resolver-ai-README.md

@@ -0,0 +1,427 @@
+# invoice-resolver-ai
+**Repository:** Julien-ser/invoice-resolver-ai
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-21T03:29:21Z
+
+---
+
+# Invoice Resolver AI
+
+**An autonomous AI agent for resolving invoice disputes and recovering unpaid invoices.**
+
+---
+
+## Problem
+
+Freelancers and small SaaS founders waste hours chasing unpaid invoices, drafting dispute letters, and navigating payment platforms. Payment delays and chargebacks are common, but resolution is manual and frustrating.
+
+## Solution
+
+An intelligent AI agent that monitors Stripe/PayPal/Bank feeds, detects overdue or disputed invoices, and automatically:
+
+- Sends polite follow-ups with payment links
+- Drafts formal dispute letters (with evidence attachments) for chargebacks
+- Escalates to small claims paperwork if needed (pre-filled forms)
+- Learns which templates and timing work best (A/B testing)
+
+## Features
+
+- **Multi-provider Integration**: Stripe, PayPal, and Plaid (bank feeds)
+- **AI-Powered Dispute Drafting**: GPT-4/Claude integration for legal letters
+- **Automated Email Campaigns**: Follow-up sequences (3, 7, 14 days)
+- **PDF Generation**: Dispute letters and small claims forms
+- **A/B Testing**: Optimize templates and timing
+- **Analytics Dashboard**: Recovery rates, campaign performance
+- **Admin Panel**: User management, system health monitoring
+- **Freemium Model**: 5 free invoices/month, $19/mo unlimited
+
+## Tech Stack
+
+- **Backend**: Python 3.11-3.13, FastAPI, PostgreSQL (Python 3.14 not yet supported due to pydantic-core compatibility)
+- **Task Queue**: Celery + Redis
+- **AI Integration**: OpenAI GPT-4 / Anthropic Claude
+- **Payment APIs**: Stripe, PayPal REST SDK, Plaid
+- **Email**: SendGrid / SMTP with Jinja2 templates
+- **Dashboard**: Streamlit
+- **PDF**: WeasyPrint or ReportLab
+- **Deployment**: Docker, GitHub Actions CI/CD
+
+## Project Structure
+
+```
+.
+├── README.md              # Project documentation
+├── TASKS.md               # Development task list (track progress)
+├── schema.sql             # PostgreSQL database schema
+├── docs/
+│   └── database-er-diagram.md  # ER diagram and table docs
+├── .github/
+│   └── workflows/
+│       └── test.yml       # CI pipeline (to be created)
+├── src/                   # Source code (to be created)
+│   ├── api/              # FastAPI endpoints
+│   ├── core/             # Configuration, logging
+│   ├── models/           # SQLAlchemy models
+│   ├── integrations/     # Stripe/PayPal/Plaid clients
+│   ├── email/            # Email automation
+│   ├── ai/               # AI dispute drafter
+│   ├── pdf/              # PDF generator
+│   ├── dashboard/        # Streamlit app
+│   ├── ab_testing/       # A/B testing framework
+│   ├── admin/            # Admin panel
+│   ├── billing/          # Stripe billing
+│   ├── tasks/            # Celery tasks
+│   └── utils/            # Helper functions
+├── tests/                 # Test suite (pytest)
+├── docker-compose.yml     # Local development (PostgreSQL, Redis)
+├── Dockerfile             # API container
+├── Dockerfile.celery      # Celery worker container
+├── pyproject.toml         # Dependencies (Poetry) or requirements.txt
+└── .env.example           # Environment variables template
+```
+
+## Current Progress
+
+### Phase 1: Planning & Setup
+
+- [x] **Task 1.1**: Database schema design
+  - 11 core tables with relationships
+  - Comprehensive indexes for performance
+  - Row Level Security (RLS) policies
+  - Database functions and views
+  - Full ER diagram with table documentation
+- [x] **Task 1.2**: FastAPI project structure initialization
+  - Core configuration module (`src/core/config.py`) with environment-based settings
+  - Logging setup (`src/core/logger.py`) with console and file handlers
+  - Main FastAPI application (`src/main.py`) with health check and CORS
+  - Dependencies in `requirements.txt`: fastapi, uvicorn, sqlalchemy, psycopg2-binary, pydantic, python-dotenv, bcrypt, python-jose, passlib
+  - Environment variable template (`.env.example`)
+- [ ] **Task 1.3**: PostgreSQL setup with SQLAlchemy + Alembic
+- [x] **Task 1.4**: API documentation outline
+
+### Phase 2: Core Backend & Data Model
+
+- [x] **Task 2.1**: User authentication system with JWT tokens
+  - Implemented `/api/auth/register` endpoint for user signup
+  - Implemented `/api/auth/login` endpoint for JWT authentication (access + refresh tokens)
+  - Implemented `/api/auth/refresh` endpoint for token rotation
+  - Implemented `/api/auth/logout` endpoint to revoke refresh tokens
+  - Bcrypt password hashing with passlib
+  - JWT token generation with expiration and payload validation
+  - Refresh token storage with single-use rotation in database
+  - Subscription limit enforcement middleware for free tier users
+  - Protected route dependencies (`get_current_user`, `get_current_admin_user`)
+  - Comprehensive test suite covering registration, login, token refresh, logout
+  - Test fixtures with SQLite in-memory database for isolated tests
+- [x] **Task 2.2**: Invoice management endpoints
+  - Full CRUD operations: create, list, update status, soft delete
+  - Filtering by status and due date range
+  - Pydantic schemas for request/response validation
+  - Integration with SQLAlchemy models and database
+  - Comprehensive tests with pytest
+- [x] **Task 2.3**: Webhook receivers for Stripe and PayPal
+  - Signature verification for both providers
+  - Idempotent processing with webhook_events table
+  - Automatic invoice status updates
+  - Endpoints: `/api/webhooks/stripe` and `/api/webhooks/paypal`
+  - Comprehensive logging and error handling
+  - Support for key events: invoice.payment_failed, charge.dispute.created, PAYMENT.DENIED, DISPUTE.CREATED
+- [x] **Task 2.4**: Celery background task setup
+  - Redis broker and Celery worker configuration
+  - Docker Compose setup with Redis service
+  - Periodic sync task (`tasks/sync.py`) for invoice status synchronization (fallback if webhooks fail)
+  - 15-minute polling interval via Celery Beat
+  - Integration with Stripe and PayPal APIs
+  - Per-user credential handling for PayPal connections
+  - System metrics recording for monitoring
+
+### Phase 3: Integrations & AI Features
+
+- [x] **Task 3.1**: Payment provider integration layer
+  - Structured clients for Stripe (`integrations/stripe_client.py`), PayPal (`integrations/paypal_client.py`), and Plaid (`integrations/plaid_client.py`)
+  - Unified interface: `connect_account()`, `get_invoice_status()`, `list_transactions()`
+  - Error handling and retry logic built-in
+  - Ready for API credential injection via encrypted database storage
+- [x] **Task 3.2**: Email automation system with follow-up sequences ✓ **COMPLETED**
+  - **Email sender abstraction**: `SMTPSender` and `SendGridSender` (placeholder) implementing common interface
+  - **Template rendering**: Jinja2-based renderer with HTML and plain text support
+  - **Follow-up sequences**: Three automated templates
+    - 3-day reminder: Polite pre-due notification
+    - 7-day overdue: Clear overdue notice with red warning
+    - 14-day final notice: Urgent final warning before dispute escalation
+  - **Campaign tracking**: `Campaign` and `EmailEvent` models for send/delivery/engagement metrics
+  - **Celery integration**: Asynchronous background tasks (`tasks/email_tasks.py`)
+    - `send_followup_task`: Wrapper for single email sending
+    - `process_followup_campaign`: Bulk processor for eligible invoices
+    - `scheduled_followups`: Periodic task to run every 15 minutes (via Celery Beat)
+  - **Database-backed templates**: Template model supports system defaults and user customizations
+  - **Comprehensive tests** (`tests/test_email.py`):
+    - EmailTemplateRenderer with Jinja2
+    - SMTPSender with mocked SMTP
+    - `send_followup_email` function with database fixtures
+    - Celery task logic and queuing behavior
+    - Template file existence and variable validation
+  - **Professional email templates**: Responsive HTML templates with inline styling, company branding, payment buttons, and legal compliance footers
+- [x] **Task 3.3**: AI-powered dispute letter drafting
+  - **Dispute letter generator** (`src/ai/dispute_drafter.py`) with support for:
+    - OpenAI GPT-4 Turbo (`gpt-4-turbo-preview`)
+    - Anthropic Claude 3 Opus (`claude-3-opus-20240229`)
+  - **Three letter types**:
+    - `formal_dispute`: Professional payment dispute letter with 14-day deadline
+    - `small_claims_prep`: Court preparation document with case summary and evidence
+    - `demand_letter`: Urgent final demand with 7-day deadline and payment plan option
+  - **Prompt engineering**: Context-aware prompts that include:
+    - Invoice details (number, client, amount, dates, status)
+    - Evidence timeline (communications, payments, attempts)
+    - Legal references and formatting requirements
+    - Output format specification (HTML)
+  - **Cost tracking**: Automatic token counting and USD cost calculation
+    - GPT-4 Turbo: $0.01/1K input + $0.03/1K output
+    - Claude 3 Opus: $0.015/1K input + $0.075/1K output
+  - **Provider fallback**: Configurable preference (OpenAI prioritized if both keys present)
+  - **Comprehensive test suite** (`tests/test_dispute_drafter.py`):
+    - Provider initialization and error handling
+    - Prompt building verification for each letter type
+    - API mocking for both OpenAI and Anthropic
+    - Cost calculation accuracy
+    - Evidence formatting and recipient handling
+- [x] **Task 3.4**: PDF generation for dispute letters and small claims forms ✓ **COMPLETED**
+  - **PDF Generator** (`src/pdf/generator.py`) using WeasyPrint (HTML → PDF)
+  - **Two professional templates**:
+    - `dispute_letter.html`: Formal dispute letter with sender/recipient info, invoice details, evidence log, payment instructions, and legal notices
+    - `small_claims_form.html`: Court preparation packet with case summary, timeline, evidence list, damages calculation, witness information, filing instructions, and presentation tips
+  - **Template rendering**: Jinja2-based with strict variable checking to ensure all required context is provided
+  - **Flexible output**: Save to file path or return PDF bytes for S3/cloud storage upload
+  - **Customization**: Support for custom CSS, page sizes (A4, Letter), and margins
+  - **Comprehensive tests** (`tests/test_pdf.py`) with 11 passing tests:
+    - PDF generation from raw HTML
+    - Template rendering with context
+    - Error handling for missing variables/templates
+    - Custom formatting (margins, page size, CSS)
+    - Multiple generation scenarios
+
+
+### Completed Deliverables
+
+1. **`schema.sql`**: Complete PostgreSQL migration script with:
+   - Users, invoices, payment connections, templates
+   - Campaigns, A/B tests, email events, webhooks
+   - Audit logs, refresh tokens, system metrics
+   - Triggers for auto-updating timestamps
+   - Functions for business logic (`check_invoice_limit`, `calculate_recovery_rate`, `get_overdue_count`)
+   - Materialized views for common queries
+   - Encryption extension support for security
+
+2. **`docs/database-er-diagram.md`**: Detailed documentation including:
+   - Visual ER diagram with relationship cardinalities
+   - Table descriptions with column types and purposes
+   - Index strategy and performance notes
+   - Security policies (RLS)
+   - Migration and rollback instructions
+
+## Getting Started (Local Development)
+
+### Running the Dashboard
+
+The Streamlit dashboard provides a user-friendly interface for managing invoices and tracking campaigns.
+
+```bash
+# Install dashboard dependencies
+pip install streamlit streamlit-authenticator plotly pandas
+
+# Set API URL (optional, defaults to http://localhost:8000)
+export API_BASE_URL=http://localhost:8000
+
+# Run the dashboard
+streamlit run dashboard/app.py
+```
+
+Access the dashboard at http://localhost:8501. Login with credentials you created via the registration API at http://localhost:8000/api/auth/register.
+
+**Dashboard Features:**
+- **Overview**: View KPIs (total invoices, recovery rate, overdue count)
+- **Invoices**: Browse and filter invoices, update status inline
+- **Campaigns**: Track email campaign performance and A/B test results
+- **Settings**: Manage payment connections (Stripe, PayPal, Plaid)
+
+
+### Prerequisites
+
+- Python 3.11+
+- Git
+- Docker & Docker Compose (recommended for database and Redis)
+
+### Quick Start (Using Docker Compose)
+
+The fastest way to get started is using Docker Compose, which spins up PostgreSQL and Redis:
+
+```bash
+# 1. Start database and Redis
+docker-compose up -d postgres redis
+
+# 2. Install Python dependencies
+pip install -r requirements.txt
+
+# 3. Set up environment configuration
+cp .env.example .env
+# Edit .env if needed (defaults work for local Docker setup)
+
+# 4. Run database migrations
+# (Alembic will be configured in upcoming tasks; for now, tables are created on startup)
+
+# 5. Start the FastAPI server
+uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
+
+# 6. In another terminal, start Celery worker
+celery -A src.celery_app worker --loglevel=info
+
+# 7. In another terminal, start Celery beat scheduler
+celery -A src.celery_app beat --loglevel=info
+```
+
+Access the API at http://localhost:8000/docs (Swagger UI) or http://localhost:8000/redoc.
+
+### Manual Setup (Without Docker)
+
+If you prefer to run PostgreSQL and Redis locally without Docker:
+
+```bash
+# 1. Install and start PostgreSQL and Redis on your system
+
+# 2. Create the database
+createdb invoice_resolver
+
+# 3. Install Python dependencies
+pip install -r requirements.txt
+
+# 4. Configure environment
+cp .env.example .env
+# Edit .env with your local database and Redis URLs
+
+# 5. Start services (same as above)
+uvicorn src.main:app --reload
+celery -A src.celery_app worker --loglevel=info
+celery -A src.celery_app beat --loglevel=info
+```
+
+### Configuration
+
+Create a `.env` file from `.env.example` and configure:
+
+- **Database**: `DATABASE_URL` (PostgreSQL connection string)
+- **JWT**: `SECRET_KEY` for token signing
+- **Payment APIs**: Stripe, PayPal, Plaid credentials
+- **AI**: `OPENAI_API_KEY` and/or `ANTHROPIC_API_KEY` for dispute letter generation
+- **Email**: SMTP settings for sending follow-ups
+- **Redis**: `REDIS_URL` for Celery task queue
+
+See `.env.example` for all available options.
+
+### Project Structure
+
+```
+.
+├── .env.example            # Environment variables template
+├── requirements.txt        # Python dependencies
+├── src/
+│   ├── main.py            # FastAPI application entry point
+│   └── core/
+│       ├── config.py      # Settings management (pydantic-settings)
+│       └── logger.py      # Logging configuration
+├── docs/                  # Documentation
+├── schema.sql             # Database schema (Phase 1.1)
+└── TASKS.md               # Development task list
+```
+
+### Current Status
+
+- ✅ Phase 1.1: Database schema design complete
+- ✅ Phase 1.2: FastAPI project structure initialized
+- 🔄 Phase 1.3: PostgreSQL setup (next task)
+- 🔄 Phase 1.4: API documentation outline (pending)
+
+## API Overview (Planned)
+
+### Public Endpoints
+
+- `POST /register` - User registration
+- `POST /login` - JWT authentication
+- `POST /refresh` - Refresh token rotation
+
+### Protected Endpoints
+
+- `GET|POST /invoices` - Invoice CRUD with filters
+- `GET /invoices/{id}` - Retrieve invoice details
+- `PATCH /invoices/{id}/status` - Update payment status
+- `POST /templates` - Create custom email templates
+- `GET|POST /campaigns` - Campaign management
+- `GET /analytics/recovery-rate` - KPI metrics
+
+### Webhook Endpoints
+
+- `POST /webhooks/stripe` - Stripe event receiver
+- `POST /webhooks/paypal` - PayPal IPN handler
+- `POST /webhooks/plaid` - Plaid transaction sync
+
+### Admin Endpoints (Admin only)
+
+- `GET /admin/users` - List all users
+- `GET /admin/metrics` - System health metrics
+- `POST /admin/users/{id}/tier` - Change subscription tier
+
+## Database Schema Highlights
+
+### Tables (11 core tables)
+
+| Table | Purpose | Key Columns |
+|-------|---------|-------------|
+| `users` | Account management | subscription_tier, invoice_limit |
+| `payment_connections` | Encrypted credentials | provider (stripe/paypal/plaid) |
+| `invoices` | Invoice records | status, stripe_payment_intent_id |
+| `templates` | Email/document templates | type, variables (JSON) |
+| `campaigns` | Campaign tracking | ab_test_variant, paid_after_send |
+| `ab_tests` | Experiment definitions | test_type, variants (JSON) |
+| `email_events` | Engagement tracking | event_type, occurred_at |
+| `webhook_events` | Idempotency store | provider, event_id (unique) |
+| `audit_logs` | Compliance logging | action, old_values, new_values |
+| `refresh_tokens` | JWT rotation | token_hash, expires_at |
+| `system_metrics` | Time-series data | metric_name, metric_value |
+
+### Key Features
+
+- **UUID primary keys** for security and distributed systems
+- **JSONB columns** for flexible metadata storage
+- **Partial indexes** on frequently queried external IDs
+- **Row Level Security** for multi-tenant isolation
+- **Encrypted credentials** for payment provider integrations
+- **Audit trail** for all data changes
+- **Idempotent webhook processing** via unique constraints
+- **Automatic timestamp updates** via triggers
+- **Materialized views** for dashboard performance
+
+## Environment Variables
+
+To be documented once implemented (after Task 1.2).
+
+## Testing
+
+Test suite will be implemented in Phase 5 using pytest with >80% coverage.
+
+```bash
+pytest tests/ -v --cov=src --cov-report=html
+```
+
+## Deployment
+
+Production deployment instructions will be added in Phase 5 (Docker, cloud hosting, CI/CD).
+
+## License
+
+To be determined.
+
+## Contact
+
+For questions or feedback about this project, please open an issue on GitHub.

docs/readmes/jira-and-confluence-agent-README.md

@@ -0,0 +1,306 @@
+# jira-and-confluence-agent
+**Repository:** Julien-ser/jira-and-confluence-agent
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-13T13:12:38Z
+
+---
+
+# Jira and Confluence Agent
+
+An autonomous agent that creates and modifies Jira and Confluence spaces, similar to what a Jira/Confluence administrator would do manually.
+
+## Features
+
+- **Jira Operations**: Create and manage projects, issue types, custom fields, workflows, screens, and permissions
+- **Confluence Operations**: Create and manage spaces, pages, templates, and permissions
+- **Configuration-driven**: Define operations in YAML configuration files
+- **Dry-run mode**: Preview changes before applying them
+- **Idempotent operations**: Safe to run multiple times
+- **Structured logging**: Complete audit trail in `logs/` directory
+- **Detailed reporting**: JSON and text summaries of all operations
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed design and technical specifications.
+
+## Project Structure
+
+```
+jira-and-confluence-agent/
+├── src/
+│   ├── __init__.py
+│   ├── models.py          # Data models and types
+│   ├── parser.py          # Configuration parser
+│   ├── jira_client.py     # Jira REST API client
+│   ├── confluence_client.py  # Confluence REST API client (planned)
+│   ├── engine.py          # Operation orchestrator (planned)
+│   ├── reporter.py        # Report generation
+│   └── utils.py           # Utility functions
+├── config/                # Configuration files (create your own)
+├── tests/                 # Unit and integration tests
+├── logs/                  # Execution logs and reports
+├── requirements.txt       # Python dependencies
+├── ARCHITECTURE.md        # Architecture documentation
+├── TASKS.md               # Development progress
+└── README.md              # This file
+```
+
+## Setup
+
+### Prerequisites
+
+- Python 3.10+
+- Jira/Confluence instance with admin credentials
+- API tokens for authentication
+
+### Installation
+
+```bash
+# Install dependencies using system Python (no virtualenv needed)
+pip install -r requirements.txt
+```
+
+## Configuration
+
+Create a configuration file (YAML format) defining the operations you want to perform:
+
+```yaml
+# example_config.yaml
+connections:
+  jira:
+    url: "https://your-jira-instance.atlassian.net"
+    username: "admin@example.com"
+    password: "YOUR_API_TOKEN"
+  confluence:
+    url: "https://your-confluence-instance.atlassian.net"
+    username: "admin@example.com"
+    password: "YOUR_API_TOKEN"
+
+jira:
+  projects:
+    - key: "TEST"
+      name: "Test Project"
+      description: "A test project"
+      projectTypeKey: "business"
+
+confluence:
+  spaces:
+    - key: "TEST"
+      name: "Test Space"
+      description: "A test space"
+```
+
+## Usage
+
+### Command Line
+
+```bash
+# Run with dry-run to preview changes
+python run_agent.py config/example_config.yaml --dry-run
+
+# Execute actual operations
+python run_agent.py config/example_config.yaml
+
+# Enable verbose logging
+python run_agent.py config/example_config.yaml --verbose
+
+# Custom log directory
+python run_agent.py config/example_config.yaml --log-dir mylogs
+```
+
+### Programmatic Usage
+
+```python
+from src.parser import OperationParser
+from src.engine import Engine
+from src.reporter import Reporter
+
+# Parse configuration
+parser = OperationParser()
+operations = parser.parse_file("config/example.yaml")
+
+# Execute operations
+engine = Engine(config["connections"], dry_run=False)
+with engine:
+    report = engine.run(operations)
+
+# Report is automatically generated in logs/ directory
+```
+
+## Deployment
+
+The Jira and Confluence Agent can be deployed in multiple ways:
+
+### Option 1: Docker (Recommended)
+
+The easiest way to deploy is using Docker:
+
+```bash
+# Build the Docker image
+docker build -t jira-confluence-agent .
+
+# Run with a specific config file
+docker run -v $(pwd)/config:/app/config:ro \
+           -v $(pwd)/logs:/app/logs \
+           -e AGENT_CONFIG=/app/config/example_config.yaml \
+           jira-confluence-agent
+
+# Or use docker-compose for easier setup
+docker-compose up
+```
+
+**Using environment variables with Docker Compose:**
+
+1. Copy `.env.example` to `.env` and fill in your credentials
+2. Update `config/agent_config.yaml` or use the example config
+3. Run: `docker-compose up`
+
+The container is designed for manual execution only (restart: "no"). For scheduled/automated runs, consider:
+
+- Using cron to execute `docker-compose run jira-agent`
+- Setting up a CI/CD pipeline (see below)
+
+### Option 2: Direct Python Execution
+
+For simple deployments, run directly on the host:
+
+```bash
+# Install dependencies system-wide
+pip install -r requirements.txt
+
+# Run the agent
+python run_agent.py config/example_config.yaml --dry-run
+
+# With environment variables (recommended for credentials)
+export JIRA_URL="https://your-company.atlassian.net"
+export JIRA_USERNAME="admin@example.com"
+export JIRA_PASSWORD="your_api_token"
+# ... set other variables as needed
+python run_agent.py config/example_config.yaml
+```
+
+### Option 3: Package Installation
+
+Create a pip-installable package (requires `setup.py` - to be added):
+
+```bash
+pip install -e .
+jira-agent config/example_config.yaml
+```
+
+### Production Considerations
+
+#### Security
+- **Never store credentials in config files** for production. Use environment variables or a secrets manager
+- The agent supports reading credentials from environment variables:
+  - `JIRA_URL`, `JIRA_USERNAME`, `JIRA_PASSWORD`
+  - `CONFLUENCE_URL`, `CONFLUENCE_USERNAME`, `CONFLUENCE_PASSWORD`
+- Rotate API tokens regularly
+- Use SSL verification (default: true)
+
+#### Scheduling Automated Runs
+Use cron (with Docker) or systemd timers:
+
+```bash
+# Example cron job (runs daily at 2 AM)
+0 2 * * * cd /path/to/agent && docker-compose run --rm jira-agent /app/config/daily_ops.yaml >> /var/log/jira-agent.log 2>&1
+```
+
+#### Monitoring
+- Check `logs/` directory for `agent.log`, `audit.log`, and reports
+- Set up log rotation for `logs/` directory
+- Monitor exit codes: `0` = success, `1` = failure
+
+#### High Availability
+- The agent is idempotent and can be safely re-run
+- Design configurations to be modular and reusable
+- Use dry-run mode (`--dry-run`) to validate before production runs
+
+### CI/CD Integration
+
+Example GitHub Actions workflow (`.github/workflows/deploy.yml`):
+
+```yaml
+name: Deploy Jira Agent
+on:
+  schedule:
+    - cron: '0 2 * * *'  # Daily at 2 AM
+  workflow_dispatch:
+
+jobs:
+  run-agent:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Run agent
+        env:
+          JIRA_URL: ${{ secrets.JIRA_URL }}
+          JIRA_USERNAME: ${{ secrets.JIRA_USERNAME }}
+          JIRA_PASSWORD: ${{ secrets.JIRA_PASSWORD }}
+          CONFLUENCE_URL: ${{ secrets.CONFLUENCE_URL }}
+          CONFLUENCE_USERNAME: ${{ secrets.CONFLUENCE_USERNAME }}
+          CONFLUENCE_PASSWORD: ${{ secrets.CONFLUENCE_PASSWORD }}
+        run: |
+          python run_agent.py config/production.yaml --dry-run
+          python run_agent.py config/production.yaml
+```
+
+## Current Status
+
+**Project Status: Production Ready** ✅
+
+All core features implemented and tested:
+
+- ✅ Configuration parser (YAML/JSON)
+- ✅ Jira REST API client (projects, issue types, custom fields, workflows)
+- ✅ Confluence REST API client (spaces, pages, templates)
+- ✅ Operation engine with dry-run support
+- ✅ Comprehensive reporting and audit logging
+- ✅ 40 passing unit and integration tests
+- ✅ Command-line interface (run_agent.py)
+- ✅ Example configuration file
+
+See [TASKS.md](TASKS.md) for detailed development progress.
+
+## Development
+
+Run tests (when available):
+```bash
+pytest tests/
+```
+
+Check linting (when configured):
+```bash
+ruff check src/
+```
+
+## Logging
+
+All operations are logged to the `logs/` directory:
+- `agent.log` - Structured application logs
+- `audit.log` - JSON audit trail of each operation
+- `report_<timestamp>.json` - Machine-readable execution report
+- `summary_<timestamp>.txt` - Human-readable summary
+
+## Security
+
+- Never commit credentials or API tokens to version control
+- Use environment variables or secure credential stores
+- The `.gitignore` excludes sensitive files
+
+## Contributing
+
+This is an autonomous project managed by OpenCode. See TASKS.md for current development status.
+
+## License
+
+[Add your license here]

docs/readmes/julien-rag-README.md

@@ -0,0 +1,298 @@
+# julien-rag
+**Repository:** Julien-ser/julien-rag
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-13T02:30:35Z
+
+---
+
+# julien-rag
+
+**Mission:** Create a vector database of everything I've done online/GitHub that can be used elsewhere as a RAG implementation.
+
+## Overview
+
+This project builds a Retrieval-Augmented Generation (RAG) system that:
+- Collects data from GitHub (repos, commits, issues, PRs, gists, starred)
+- Scrapes web presence (blog, forums, social media)
+- Processes and chunks documents intelligently
+- Stores embeddings in a vector database
+- Provides a FastAPI REST interface for semantic search and Q&A
+- Can be used as a Python SDK in other projects
+
+## Technology Stack
+
+- **Vector Database**: ChromaDB (local, persistent)
+- **Embeddings**: OpenAI `text-embedding-ada-002` or `sentence-transformers/all-MiniLM-L6-v2`
+- **API**: FastAPI with async endpoints
+- **Data Collection**: PyGithub, beautifulsoup4, requests
+- **Processing**: tiktoken for token counting, recursive text splitting
+
+## Current Status
+
+**Phase 1: Planning & Infrastructure Setup** ✅ Complete
+- [x] **Task 1.1**: Vector database selection (ChromaDB chosen for local-first, zero-config approach)
+- [x] **Task 1.2**: Design data schema and document structure
+- [x] **Task 1.3**: Choose embedding model and API setup
+- [x] **Task 1.4**: Initialize project structure and dependencies
+
+**Phase 2: Data Collection & Ingestion Pipeline** ✅ Complete
+- [x] **Task 2.1**: Implement GitHub API data collector ✅
+- [x] **Task 2.2**: Implement web content scraper for online presence ✅
+- [x] **Task 2.3**: Build document preprocessing and chunking pipeline ✅
+- [x] **Task 2.4**: Create unified data pipeline with error handling ✅
+  - `src/pipeline.py` with comprehensive orchestration
+  - Retry logic, incremental updates, detailed logging
+  - Shell script: `scripts/ingest_all.sh`
+  - Logs written to `logs/ingestion_*.log`
+  - Statistics saved to `data/processed/pipeline_stats.json`
+
+**Phase 3: Vector Database Implementation** ✅ Complete
+- [x] **Task 3.1**: Initialize vector database and collections ✅
+- [x] **Task 3.2**: Implement embedding generation and storage ✅
+- [x] **Task 3.3**: Implement similarity search functionality ✅
+- [x] **Task 3.4**: Perform database validation and optimization ✅
+  - `scripts/validate_db.py` with comprehensive validation suite
+  - `docs/database_performance.md` with performance metrics and recommendations
+  - Tests: data integrity, latency benchmarks, metadata filtering, recall@k support
+
+**Phase 4: RAG API & External Integration** ✅ Complete
+- [x] **Task 4.1**: Build FastAPI REST endpoints ✅
+  - Complete API with interactive docs at `/docs`
+  - All endpoints: `/query`, `/sources`, `/stats`, `/refresh`, `/health`, `/metrics`, `/collections`
+  - Async support, CORS enabled, admin authentication, comprehensive error handling
+  - 22/22 API unit tests passing
+
+- [x] **Task 4.2**: Implement RAG generation pipeline ✅
+  - `src/rag.py` with `RAGPipeline` class supporting OpenAI and local providers
+  - API endpoint `/rag-query` returns `{answer, confidence, sources, stats}`
+  - Configuration in `config/rag.yaml` with LLM settings and prompts
+  - 22/23 tests passing (1 requires optional dependency)
+
+- [x] **Task 4.3**: Create SDK/client library for external use ✅
+  - Complete Python package `julien_rag` with `RAGClient` class
+  - Supports all API endpoints with typed Pydantic models
+  - Full test suite (15/15 passing)
+  - Usage examples in `examples/usage_example.py`
+  - Documentation in README and package
+
+- [x] **Task 4.4**: Add monitoring, logging, and deployment configuration ✅
+  - `src/monitoring.py` with Prometheus metrics (Counter, Histogram, Gauge) and `/metrics` endpoint
+  - Metrics middleware for automatic request tracking (latency, status codes, endpoints)
+  - Database query metrics (operation duration, document counts)
+  - Embedding generation metrics (token count, duration, provider)
+  - RAG pipeline metrics (query count, confidence scores)
+  - Optional system metrics (CPU, memory) when psutil available
+  - Production-ready `docker/Dockerfile` with multi-stage build, health checks, non-root user
+  - `docker/docker-compose.yml` with API service and optional monitoring stack (Prometheus, Grafana)
+  - Comprehensive integration test suite in `tests/integration/test_full_flow.py`
+  - Deployment guide in `docs/deployment.md`
+
+**MISSION ACCOMPLISHED** ✅
+Vector DB with full RAG implementation ready for external use.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.9+
+- Git
+- (Optional) GitHub API token for data collection: `GITHUB_TOKEN`
+- (Optional) OpenAI API key for embeddings: `OPENAI_API_KEY`
+- (Optional) For Docker deployment: Docker and Docker Compose
+
+### Option 1: Local Python Installation
+
+```bash
+# Clone and navigate
+cd projects/julien-rag
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Set up environment variables
+cp .env.example .env  # if .env.example exists
+# Edit .env with your API keys:
+# - GITHUB_TOKEN (optional, for GitHub data collection)
+# - OPENAI_API_KEY (optional, for embeddings and RAG with OpenAI)
+# - ADMIN_TOKEN (optional, for protected refresh endpoint)
+
+# Run data ingestion (collect and process data)
+./scripts/ingest_all.sh
+# Or: python -m src.pipeline
+
+# Start the FastAPI server
+uvicorn src.api:app --reload --port 8000
+
+# Visit http://localhost:8000/docs for interactive API documentation
+```
+
+### Option 2: Docker Deployment (Recommended for Production)
+
+```bash
+# Build and run using Docker Compose
+docker-compose up -d
+
+# Or build manually:
+docker build -t julien-rag -f docker/Dockerfile .
+docker run -p 8000:8000 \
+  -v $(pwd)/data:/home/app/data \
+  -v $(pwd)/logs:/home/app/logs \
+  -v $(pwd)/config:/home/app/config:ro \
+  -e OPENAI_API_KEY=${OPENAI_API_KEY} \
+  -e ADMIN_TOKEN=${ADMIN_TOKEN} \
+  julien-rag
+
+# Access API at http://localhost:8000/docs
+```
+
+**Optional Monitoring Stack:**
+
+```bash
+# Deploy with Prometheus and Grafana for metrics
+docker-compose --profile monitoring up -d
+
+# Access services:
+# - API: http://localhost:8000
+# - Prometheus: http://localhost:9090
+# - Grafana: http://localhost:3000 (admin/admin)
+```
+
+For detailed deployment options, see [docs/deployment.md](docs/deployment.md).
+
+### Running the Ingestion Pipeline
+
+The unified pipeline orchestrates data collection, preprocessing, and chunk generation.
+
+**Using the shell script (recommended):**
+
+```bash
+# Full ingestion with default settings
+./scripts/ingest_all.sh
+
+# With custom configuration
+./scripts/ingest_all.sh --config config/pipeline_config.json
+
+# Set log level (DEBUG, INFO, WARNING, ERROR)
+./scripts/ingest_all.sh --log-level DEBUG
+```
+
+**Using Python module directly:**
+
+```bash
+# Run with default configuration
+python -m src.pipeline
+
+# With configuration file
+python -m src.pipeline --config config/my_config.json
+
+# With debug logging
+python -m src.pipeline --log-level DEBUG
+```
+
+**Configuration:**
+
+Create a JSON configuration file (see `config/pipeline_config.example.json`):
+
+```json
+{
+  "incremental": true,
+  "chunk_size": 512,
+  "chunk_overlap": 100,
+  "github_token": null,
+  "web_scrape_config": {
+    "personal": ["https://yourwebsite.com/about"],
+    "blog": ["https://yourblog.com/rss"]
+  }
+}
+```
+
+**Logs & Statistics:**
+
+- Logs: `logs/ingestion_YYYYMMDD_HHMMSS.log` (rotating, max 10MB per file)
+- Statistics: `data/processed/pipeline_stats.json`
+- Processed chunks: `data/processed/*_chunks.jsonl`
+
+**Features:**
+
+- ✅ Retry logic with exponential backoff for API calls
+- ✅ Incremental updates (skips unchanged files)
+- ✅ Graceful error handling - continues on failures
+- ✅ Comprehensive logging with rotation
+- ✅ Automatic fallback to existing raw data
+- ✅ Statistics and performance metrics
+
+## Project Structure
+
+```
+julien-rag/
+├── src/
+│   ├── database.py      # ✅ ChromaDB initialization (Task 3.1)
+│   ├── embedder.py      # ✅ Embedding generation (Task 3.2)
+│   ├── vector_store.py  # ✅ Vector storage operations (Task 3.2)
+│   ├── retriever.py     # Similarity search (Task 3.3 - pending)
+│   ├── github_collector.py
+│   ├── web_scraper.py
+│   ├── preprocessor.py
+│   ├── pipeline.py
+│   ├── api.py           # FastAPI endpoints (Task 4.1 - pending)
+│   ├── rag.py           # RAG generation (Task 4.2 - pending)
+│   └── monitoring.py    # Monitoring (Task 4.4 - pending)
+├── data/
+│   ├── raw/            # Raw collected data
+│   ├── processed/      # Chunked documents
+│   └── vector_db/      # ChromaDB storage
+├── config/
+│   ├── embeddings.yaml  # Embedding configuration
+│   └── rag.yaml         # RAG configuration (pending)
+├── tests/
+│   ├── test_embedder.py       # ✅ All tests passing (54/54)
+│   ├── test_vector_store.py   # ✅ Vector store tests
+│   ├── test_database.py       # ✅ Database tests
+│   ├── test_preprocessor.py   # ✅ Preprocessor tests
+│   ├── test_web_scraper.py    # ✅ Web scraper tests
+│   └── test_github_collector.py # ✅ GitHub collector tests
+├── docs/
+│   ├── vector_db_selection.md  # ✅ Completed
+│   ├── schema_design.md        # ✅ Completed
+│   ├── database_performance.md # ✅ Completed (Task 3.4)
+│   └── deployment.md           # Pending (Task 4.4)
+├── logs/
+├── scripts/
+│   ├── ingest_all.sh       # Full ingestion pipeline
+│   └── validate_db.py      # Database validation & benchmarking
+├── examples/
+│   └── github_collector_example.py
+├── requirements.txt
+├── TASKS.md
+└── README.md
+```
+
+## Using the SDK
+
+The SDK is now available as a Python package! Install it and use the RAG API in any project.
+
+### SDK Installation
+
+```bash
+# Install the SDK from the local package
+pip install -e .
+
+# Or install from a published package (once available)
+# pip install julien_rag
+```
+
+### SDK Usage
+
+See [docs/deployment.md](docs/deployment.md) for detailed deployment options including:
+- Docker deployment with docker-compose
+- Production configuration
+- Monitoring with Prometheus/Grafana
+- Security best practices
+- Troubleshooting
+
+---
+
+## Project Structure

docs/readmes/mlflow-ai-experiment-README.md

@@ -0,0 +1,379 @@
+# mlflow-ai-experiment
+**Repository:** Julien-ser/mlflow-ai-experiment
+**Contribution:** 👑 Owner
+**Stars:** 0
+**Description:** None
+**Language:** Python
+**Last Updated:** 2026-03-19T12:51:49Z
+
+---
+
+# MLFlow AI Experiment: Text Classification Model Comparison
+
+## Overview
+This project uses **MLFlow** to systematically compare state-of-the-art machine learning models for sentiment analysis on the IMDB movie reviews dataset. We evaluate both traditional ML approaches and modern transformer-based architectures to identify the optimal balance of accuracy, speed, and resource efficiency.
+
+## Problem Statement
+**Task**: Binary text classification (positive/negative sentiment) on 50,000 movie reviews.
+
+**Goal**: Compare multiple model architectures and determine the best-performing model(s) based on:
+- Accuracy and F1 score
+- Inference latency
+- Model size and memory footprint
+- Training efficiency
+
+**Detailed problem statement**: [docs/problem-statement.md](docs/problem-statement.md)
+
+## Project Structure
+```
+.
+├── README.md              # Project documentation
+├── TASKS.md              # Development task tracking
+├── requirements.txt      # Python dependencies
+├── config.yaml           # MLflow and experiment configuration
+├── setup_mlflow.py       # MLflow tracking setup script
+├── .github/workflows/    # CI/CD pipelines
+│   └── test.yml
+├── docs/                 # Documentation and problem statement
+│   └── problem-statement.md
+├── src/                  # Source code
+│   ├── models/          # Model implementations
+│   ├── training.py      # Training pipeline
+│   ├── evaluation.py    # Metrics computation
+│   └── ...
+├── data/                # Processed datasets
+├── models/              # Saved model artifacts
+├── experiments/         # Experiment configurations
+├── notebooks/           # Jupyter notebooks for exploration
+└── mlruns/              # MLFlow tracking data (auto-generated)
+```
+
+## Setup
+
+### Prerequisites
+- Python 3.9+
+- Git
+
+### Option 1: Using pip (system Python)
+```bash
+# Install dependencies directly into system Python
+pip install -r requirements.txt
+
+# Verify environment
+python verify_environment.py
+```
+
+### Option 2: Using Conda (recommended for isolation)
+```bash
+# Create and activate conda environment
+conda env create -f environment.yml
+conda activate mlflow-ai-experiment
+
+# Verify environment
+python verify_environment.py
+```
+
+### Quick Start
+1. Start MLflow tracking server:
+   ```bash
+   mlflow ui
+   ```
+   Open http://localhost:5000 in your browser.
+
+2. Explore the notebooks:
+   ```bash
+   jupyter lab notebooks/01_data_exploration.ipynb
+   ```
+
+3. Run baseline training:
+   ```bash
+   python src/train.py --model logistic_regression --config config/baseline.yaml
+   ```
+
+## Usage
+
+### Starting MLFlow UI
+```bash
+mlflow ui
+```
+Then open http://localhost:5000 in your browser.
+
+### Running Experiments
+
+#### Baseline Model (TF-IDF + Logistic Regression)
+```bash
+python scripts/run_baseline.py
+```
+
+#### Classical ML Models
+```bash
+# Train baseline model using classical pipeline
+python src/train.py --model logistic_regression --config config.yaml
+
+# Train other classical models
+python src/train.py --model svm --config config.yaml
+python src/train.py --model random_forest --config config.yaml
+python src/train.py --model xgboost --config config.yaml
+```
+
+Or train all classical models at once with the comprehensive script:
+```bash
+python scripts/run_classical_models.py
+```
+
+This script trains all classical models (Logistic Regression, SVM, Random Forest, XGBoost) and generates a comparison table with all metrics logged to MLflow.
+
+#### Transformer Models
+The project now includes a unified transformer interface supporting multiple architectures:
+
+```bash
+# BERT base or large
+python src/train.py --model bert --config config/transformer_bert.yaml
+python src/train.py --model bert-large --config config/transformer_bert.yaml
+
+# RoBERTa
+python src/train.py --model roberta --config config/transformer_roberta.yaml
+
+# DeBERTa (v3)
+python src/train.py --model deberta --config config/transformer_deberta.yaml
+
+# XLNet
+python src/train.py --model xlnet --config config/transformer_xlnet.yaml
+
+# Or use custom HuggingFace model names
+python src/train.py --model distilbert-base-uncased --config config/transformer_distilbert.yaml
+python src/train.py --model google/electra-base-discriminator --config config/transformer_electra.yaml
+```
+
+The transformer models are implemented in `src/models/transformers.py` with:
+- Unified `TransformerModel` base class with consistent API
+- Specific wrappers: `BERTModel`, `RoBERTaModel`, `DeBERTaModel`, `XLNetModel`
+- Factory functions: `create_transformer_model()` and `create_transformer_model_from_name()`
+- Support for custom classification heads with configurable dropout
+ - Automatic MLflow logging with transformers flavor
+
+### Viewing Dashboards & Analysis
+
+#### Interactive Streamlit Dashboard
+An interactive dashboard for model comparison and analysis:
+```bash
+streamlit run app/dashboard.py
+```
+Then open http://localhost:8501 in your browser.
+
+The dashboard provides:
+- Performance comparison across all models (bar charts)
+- Latency vs accuracy trade-off analysis
+- Model size vs performance visualizations
+- Metric correlation heatmaps
+- Statistical significance testing (Friedman test, bootstrap CIs)
+- Exportable results tables
+
+**Note**: The dashboard automatically loads data from MLflow. If insufficient data exists, it will display sample data for demonstration.
+
+#### Jupyter Notebook Analysis
+For detailed exploratory analysis:
+```bash
+jupyter lab notebooks/analysis.ipynb
+```
+
+The analysis notebook includes:
+- Comprehensive data exploration
+- Statistical testing (Friedman, Nemenyi, bootstrap)
+- Correlation analysis
+- Production deployment recommendations
+- Key insights and visualizations
+
+#### Documentation
+Detailed model comparison report: [docs/model_comparison.md](docs/model_comparison.md)
+
+### Evaluating Models
+
+The project includes a comprehensive automated evaluation suite that computes all metrics (accuracy, precision, recall, F1, confusion matrix, inference latency, memory footprint) and logs them consistently.
+
+#### Single Model Evaluation
+```bash
+python src/evaluate.py --model-path models/best_model/
+```
+
+#### Batch Evaluation & Comparison
+Evaluate all models from an MLflow experiment and generate comparison tables:
+```bash
+python scripts/evaluate_all.py \
+  --experiment-name "my_experiment" \
+  --test-data data/test.csv \
+  --output-dir comparison_results
+```
+
+Or evaluate specific runs:
+```bash
+python scripts/evaluate_all.py \
+  --run-ids <run_id1> <run_id2> \
+  --test-data data/test.csv
+```
+
+All results are automatically logged to MLflow and saved as CSV/JSON comparison tables.
+
+## Data Pipeline Performance Benchmark
+
+The project includes a comprehensive benchmark to measure data loading and preprocessing performance across different batch sizes and configurations.
+
+### Running the Benchmark
+
+```bash
+# Install psutil if not already installed
+pip install psutil
+
+# Run the benchmark (logs results to MLFlow)
+python scripts/benchmark_data.py
+```
+
+The benchmark measures:
+- **Data loading**: Time and memory for loading IMDB dataset with different batch sizes
+- **Classical preprocessing**: TF-IDF vectorization with various feature counts
+- **Transformer tokenization**: BERT, RoBERTa, DistilBERT tokenization throughput
+
+All results are automatically logged to MLFlow in the `data_pipeline_benchmarks` experiment.
+
+### Viewing Results
+
+```bash
+# Start MLFlow UI
+mlflow ui
+# Open http://localhost:5000
+```
+
+Detailed analysis and recommendations are available in:
+- [docs/data_performance.md](docs/data_performance.md)
+
+### Benchmark Outputs
+
+The script generates CSV files with detailed metrics and uploads them as MLFlow artifacts:
+- `data_loading_benchmark.csv`
+- `classical_preprocessing_benchmark.csv`
+- `transformer_preprocessing_benchmark.csv`
+
+## Model Categories
+
+### Classical ML Models
+- Logistic Regression (baseline)
+- Support Vector Machines (SVM)
+- Random Forest
+- XGBoost
+- LightGBM
+
+### Transformer Models
+The project includes a **unified transformer interface** with support for:
+
+**Core architectures** (directly implemented):
+- BERT (base, large, and any HuggingFace variant)
+- RoBERTa (base, large)
+- DeBERTa (v3 base/large)
+- XLNet (base, large)
+
+**Extended support** (any HuggingFace model):
+- DistilBERT
+- ELECTRA
+- ALBERT
+- GPT-2/3 for classification
+- And any other text-classification model from HuggingFace Hub
+
+All transformer models share the same API via `TransformerModel` base class with:
+- Consistent training, prediction, and logging interfaces
+- Customizable classification heads
+- Automatic device management (CPU/GPU)
+- MLflow transformers flavor integration
+
+## Tracking Experiments
+All experiments are automatically tracked in MLFlow with:
+- Model parameters
+- Performance metrics
+- System metrics (inference time, memory usage)
+- Model artifacts
+- Dataset version information
+
+## Data Utilities & Versioning
+
+### Data Versioning (`src/data_versioning.py`)
+The project implements checksum-based data versioning to ensure reproducibility:
+- **Automatic version detection**: SHA-256 hashes of dataset content
+- **Version manifest**: `data/version_manifest.yaml` stores checksums and timestamps
+- **Integrity verification**: `verify_dataset_integrity()` ensures datasets haven't changed
+- **Version string**: Compact format (e.g., `v1.0-a1b2c3d4`) for tracking
+
+### MLFlow Data Logging (`src/data_utils.py`)
+Comprehensive utilities to log data information to MLFlow:
+- `log_dataset_statistics()`: Sample counts, class distribution, text lengths
+- `log_preprocessing_parameters()`: Track preprocessing configuration
+- `log_data_artifacts()`: Save dataset splits as artifacts (CSV/Parquet)
+- `create_and_log_data_report()`: Generate markdown data reports
+- `prepare_data_for_mlflow()`: All-in-one function for complete data logging
+
+### Usage Example
+```python
+from mlflow_ai_experiment.data_loader import load_and_log_dataset
+
+# Load data and automatically log to MLFlow with versioning
+train_df, val_df, test_df = load_and_log_dataset(
+    log_to_mlflow=True,
+    preprocessing_params={
+        "cleaning": "lowercase, remove_html",
+        "tokenization": "bert-base-uncased",
+    }
+)
+```
+
+This automatically:
+- Calculates dataset checksums
+- Creates `data/version_manifest.yaml`
+- Logs statistics, parameters, and artifacts to MLFlow
+- Generates a comprehensive data report
+
+## Current Status
+
+**Phase 1: Planning & Setup** - ✓ Complete
+- [x] Problem statement and requirements defined (see [docs/problem-statement.md](docs/problem-statement.md))
+- [x] MLFlow tracking infrastructure setup
+- [x] Development environment creation
+- [x] Baseline model implementation
+
+**Phase 2: Data Management & Preprocessing** - ✓ Complete
+- [x] Dataset download and preparation
+- [x] Text preprocessing pipeline
+- [x] Data utilities for MLFlow logging
+- [x] Data pipeline performance benchmarking
+
+**Phase 3: Model Implementation & Training** - ✓ Complete
+- [x] HuggingFace transformer integration
+- [x] Classical ML model implementations
+- [x] State-of-the-art models (ELECTRA, ALBERT, DistilBERT)
+- [x] Unified training pipeline
+
+**Phase 4: Experimentation, Logging & Analysis** - ✓ Complete
+- [x] Comprehensive MLFlow experiment tracking
+- [x] Hyperparameter optimization framework
+- [x] Automated model evaluation suite
+- [x] Interactive dashboards and visualizations
+- [x] Final report and recommendations
+- [x] Reproducibility framework
+- [x] Model artifact management and export utilities
+
+**Project Status: 100% COMPLETE** ✅
+
+All deliverables have been successfully implemented and documented. See the [Final Report](docs/FINAL_REPORT.md) for comprehensive results and recommendations.
+
+## Dependencies
+Key dependencies (see [requirements.txt](requirements.txt) for complete list):
+- `mlflow` - Experiment tracking and model registry
+- `transformers` - HuggingFace transformer models
+- `torch` or `tensorflow` - Deep learning backend
+- `datasets` - HuggingFace datasets library
+- `scikit-learn` - Classical ML algorithms
+- `pandas`, `numpy` - Data manipulation
+- `optuna` or `ray[tune]` - Hyperparameter optimization (optional)
+
+## License
+[Add license information here]
+
+## Contact
+[Add contact/team information here]