docs: Update Markdown standards to prohibit HTML usage and enhance documentation clarity (#240)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: ctasada

AGENTS.md

@@ -1,9 +1,20 @@
 # AGENTS.md
 
+> **⚠️ IMPORTANT FOR AI AGENTS:** This file is automatically loaded as workspace rules in Cursor. Always refer to this document when making code changes, answering questions, or planning features. Follow the guidelines, workflows, and checklists provided here.
+
 ## Purpose
 
 This document provides a concise, structured reference for AI agents (such as GPT, Claude, Gemini, etc.) to understand and assist with the Stonks Overwatch project. It summarizes the architecture, extension points, and key development practices, enabling agents to answer questions, generate code, or plan enhancements effectively.
 
+**For AI Agents:** This file contains critical information about:
+- Code style and standards
+- Architecture patterns (Factory, Registry, Dependency Injection)
+- Validation workflows
+- Self-review checklists
+- Common pitfalls to avoid
+
+**Always consult this file before making changes.**
+
 ---
 
 ## Quick Reference for AI Agents
@@ -45,6 +56,7 @@ make collectstatic     # After editing static files
 - ❌ Don't skip type hints - They're required
 - ❌ Don't use bare `except:` - Always catch specific exceptions
 - ❌ Don't hardcode paths - Use environment variables or Django settings
+- ❌ Don't use HTML in Markdown files - Use pure Markdown syntax only
 
 ---
 
@@ -610,6 +622,17 @@ class PortfolioEntry:
 - **Auto-fix Markdown files:**
   - `make markdown-fix` — Automatically fix Markdown style issues.
 
+### Markdown Standards
+
+- **HTML is NOT allowed** - Use pure Markdown syntax only
+- Markdown files are linted using `pymarkdown` (run `make markdown-check` to verify)
+- **Image sizing:** Standard Markdown does not support image sizing. To resize images:
+  - Resize the actual image file itself using image editing tools
+  - Use a smaller version of the image file if available
+  - Do NOT use HTML `<img>` tags with width/height attributes
+- Follow standard Markdown conventions for consistency
+- Run `make markdown-fix` to auto-fix common Markdown style issues
+
 ### Additional Useful Commands
 
 - `make help` — List all available Makefile commands.
@@ -859,6 +882,12 @@ def test_fetch_data():
 - [ ] `make check-dependencies` passes (if dependencies changed)
 - [ ] `make pre-commit-run` passes (all hooks green)
 
+### Documentation
+- [ ] Markdown files use pure Markdown syntax (no HTML)
+- [ ] `make markdown-check` passes (no Markdown linting errors)
+- [ ] `make markdown-fix` run if needed (auto-fix Markdown style issues)
+- [ ] Documentation is clear and helpful for users
+
 ### Compatibility & Best Practices
 - [ ] Changes are backward compatible (unless explicitly breaking)
 - [ ] No commented-out code (Git tracks history)

CONTRIBUTING.md

@@ -268,6 +268,8 @@ class PortfolioService:
 - **Error handling**: Use custom exceptions with proper error messages
 - **Logging**: Use structured logging with appropriate log levels
 
+> **Note for AI Agents:** See [`AGENTS.md`](../AGENTS.md) for detailed architecture patterns, code examples, and AI-specific guidance.
+
 ## Testing
 
 ### Test Requirements

README.md

@@ -1,6 +1,6 @@
 # Stonks Overwatch
 
-![Stonks Overwatch Logo](src/icons/stonks_overwatch.png)
+![Stonks Overwatch Logo](src/icons/stonks_overwatch-256.png)
 
 **A privacy-first, open-source investment portfolio tracker**
 
@@ -111,6 +111,7 @@ For detailed installation instructions, see the [Quickstart Guide](docs/Quicksta
 - **🚀 [Quickstart Guide](docs/Quickstart.md)** - Get up and running in minutes
 - **🖥️ [Desktop App Guide](docs/Application.md)** - Native application installation and updates
 - **🔧 [Developer Guide](docs/Developing-Stonks-Overwatch.md)** - Contributing and development setup
+- **🤖 [AI Agent Guide](AGENTS.md)** - Guidelines for AI assistants working on this project
 - **🏦 Broker Setup**: [DEGIRO](docs/DEGIRO.md) • [Bitvavo](docs/Bitvavo.md) • [IBKR](docs/IBKR.md)
 - **❓ [FAQ](docs/FAQ.md)** - Frequently asked questions
 

docs/Developing-Stonks-Overwatch.md

@@ -3,6 +3,8 @@
 > **Audience:** Developers, contributors
 >
 > **Summary:** This guide explains how to set up the development environment and contribute to Stonks Overwatch.
+>
+> **Note for AI Agents:** For AI-specific guidance, code patterns, and validation workflows, see [`AGENTS.md`](../../AGENTS.md) in the project root.
 
 Stonks Overwatch is a portfolio tracker integrating with multiple brokers (DEGIRO, Bitvavo, IBKR). The system features a **unified broker architecture** with factory patterns, dependency injection, interface-based design, and a centralized broker registry that simplifies development and maintenance.