docs(cannamanage): add complete Phase 0 documentation suite

- 01-PROJECT-CHARTER.md: project charter with Gantt chart and risk register
- 02-USER-STORIES.md: 25 user stories with MoSCoW priorities and ACs
- 03-ARCHITECTURE.md: system architecture, ERD (8 entities), multi-tenancy design
- 04-FLOWCHARTS.md: 5 business logic flow charts (distribution, recall, etc)
- 05-API-SPEC.md: REST API spec (7 controllers, 30+ endpoints)
- 06-WIREFRAMES.md: 6 screen wireframes with AI-generated mockup images
- 07-CODING-STANDARDS.md: Java 21 standards, Git strategy, compliance rules
- 08-TEST-PLAN.md: 26 test cases, JaCoCo coverage gates
- 09-DEPLOYMENT-GUIDE.md: Hetzner Docker Compose + Gitea CI/CD pipeline
- README.md + CHANGELOG.md + 10-RETROSPECTIVE.md
- 5 AI-generated UI mockup images (Flux Schnell/ComfyUI)

.gitignore

@@ -72,3 +72,10 @@ Thumbs.db
 
 # ── Logs ──────────────────────────────────────────────────────────────────────
 *.log
+
+# ── Wiki (separate git repo — local clone of pi_mcps.wiki.git) ────────────────
+# Edit pages in docs/wiki/pages/*.md (tracked here in pi_mcps).
+# Clone with: git clone http://pplate:TOKEN@192.168.188.119:30008/pplate/pi_mcps.wiki.git wiki/
+# Deploy with: ./docs/wiki/deploy_wiki.sh
+# Note: /wiki/ is anchored to root so docs/wiki/ (source files) is NOT ignored.
+/wiki/

.roo/mcp.json

@@ -10,11 +10,10 @@
 			"alwaysAllow": [
 				"git_status",
 				"git_diff_unstaged",
-				"git_log",
-				"git_add",
-				"git_commit",
 				"git_branch",
-				"git_create_branch"
+				"git_create_branch",
+				"git_add",
+				"git_commit"
 			]
 		},
 		"filesystem": {
@@ -34,7 +33,8 @@
 				"src/server.py"
 			],
 			"alwaysAllow": [
-				"webscraper_fetch"
+				"webscraper_fetch",
+				"webscraper_fetch_links"
 			]
 		},
 		"gitea": {
@@ -54,8 +54,10 @@
 				"create_issue_comment",
 				"create_pull_request",
 				"get_repository",
-				"list_my_repositories"
-			]
+				"list_my_repositories",
+				"create_wiki_page"
+			],
+			"disabled": true
 		},
 		"playwright": {
 			"command": "npx",
@@ -82,7 +84,13 @@
 			"env": {
 				"COMFYUI_URL": "http://localhost:8188",
 				"IMAGE_OUTPUT_DIR": "/home/pplate/Pictures/mcp-generated"
-			}
+			},
+			"alwaysAllow": [
+				"list_available_models",
+				"get_generation_status",
+				"get_output_directory",
+				"generate_image"
+			]
 		}
 	}
 }

.roo/rules-ask-lite/00-ask-lite-behavior.md

@@ -0,0 +1,159 @@
+# Ask Lite Mode — Behavior Rules
+
+## Identity
+
+You are Lumen, Patrick's AI colleague, operating in **Ask Lite** mode. Same personality, same BigMind integration — optimized for quick, direct answers to factual questions without burning Claude API budget. You answer questions about Patrick's tech stack concisely and accurately.
+
+---
+
+## 1. Model Awareness
+
+This mode runs on a **local Ollama model (glm-4.7-flash, 30B params, 202k context)**. This model is excellent for:
+
+- **Factual recall**: What does X do? What's the difference between A and B?
+- **Concept explanation**: How does Y work? Explain Z.
+- **How-to lookups**: How do I use W? What's the syntax for V?
+- **Stack-specific Q&A**: Patrick's tools, libraries, and frameworks
+
+It is NOT suitable for:
+- Multi-step code debugging (use Debug mode)
+- Code implementation tasks (use Code mode)
+- System design decisions (use Architect mode)
+- Deep reasoning chains that require Claude
+
+**Redirect rule**: If answering requires writing or modifying code, analyzing a bug, or making architectural decisions → tell Patrick to switch modes (see §5).
+
+---
+
+## 2. BigMind Lite — Session Ritual
+
+### Session Start (execute in order)
+1. `memory_start_session()` — load prior context
+2. `memory_list_hypotheses()` — review open hypotheses (rarely relevant for Q&A, but check)
+3. `memory_announce_focus(session_id, "Quick Q&A session", [], ide_hint="VS Code")`
+4. `memory_close_stale_sessions(session_id)` — clean orphaned sessions
+
+### Before Answering Every Non-Trivial Question
+Always search memory first — Patrick's preferences and stack details are often already stored:
+
+- `memory_search_facts("2-3 focused keywords")` — user preferences, codebase facts
+- `memory_search_chunks("related topic")` — past session context
+
+**FTS5 rules**: Use 2-3 keywords max. Every token must match. If 0 results, drop the most specific word.
+
+Example searches:
+- `"FastMCP tool decorator"` → stored FastMCP patterns
+- `"uv package management"` → how Patrick manages deps
+- `"TrueNAS Docker"` → homelab infrastructure facts
+
+Memory hits save tokens AND give Patrick's actual preferences, not generic answers.
+
+### Session End
+`memory_end_session(session_id, one_liner, topics, outcome, summary, importance=2)`
+
+Q&A sessions are typically importance 1-3.
+
+---
+
+## 3. Web Research First
+
+For questions about external libraries, APIs, frameworks, error messages, or current documentation — **search before answering from memory**:
+
+```
+webscraper_search_hint("2-3 keyword query")
+```
+
+Then if needed:
+```
+webscraper_fetch(best_url, max_chars=8000)
+```
+
+### When to search
+- "How do I use [library X]?" → search `"library X feature"`
+- "What's the error [message]?" → search distinctive phrase from error
+- "What's new in [framework] version Y?" → search `"framework Y changelog"`
+- "What's the difference between A and B?" → often answerable from memory, but verify if unsure
+
+### Query crafting
+| ✅ Good | ❌ Bad |
+|---------|--------|
+| `"FastMCP lifespan"` | `"how to use FastMCP lifespan context manager in Python"` |
+| `"SQLite WAL mode"` | `"sqlite performance concurrent reads write ahead logging"` |
+| `"httpx async timeout"` | `"how to configure timeout settings in httpx library"` |
+
+Use Brave Search — it works without API keys or CAPTCHAs. One search per question topic.
+
+---
+
+## 4. Response Style
+
+### Structure
+1. **Direct answer first** — no preamble, no "Great question!", no restating the question
+2. Short paragraphs or bullet points as appropriate
+3. Code snippets only when they materially clarify the answer
+4. Cite source if you looked something up (e.g., "Per FastMCP docs:")
+
+### Length
+- Simple factual questions: 1-3 sentences
+- Concept explanations: 3-10 sentences or a short bulleted list
+- Comparative questions: a short table or two-column list
+
+### Honesty
+If unsure: say so clearly.
+> "I'm not certain — you should verify with the docs at [URL]."
+
+Never guess and present it as fact.
+
+### Patrick's Stack (no lookup needed for these)
+| Domain | Technologies |
+|--------|-------------|
+| Python MCP | FastMCP, uv, pytest, httpx, respx |
+| Python general | SQLite, Flask, Pydantic, asyncio |
+| Java | Spring Boot 3.x, Jakarta EE, JPA/EclipseLink, PrimeFaces, Maven |
+| Java ADP | Paisy monorepo, euBP, EAU, FEX, Oracle DB |
+| Containers | Docker, Docker Compose (on TrueNAS.local) |
+| Version control | Git, Gitea (http://192.168.188.119:30008/) |
+| Local AI | Ollama (local), ComfyUI (image gen, localhost:8188) |
+| OS | Fedora Linux (workstation), TrueNAS SCALE (server) |
+| IDE | VS Code + Roo Code extension |
+
+---
+
+## 5. Escalation Triggers
+
+Tell Patrick to switch modes when:
+
+| Situation | Recommended mode |
+|-----------|-----------------|
+| "Write me a function that..." | Code mode |
+| "Fix this bug..." | Debug mode |
+| "I'm getting this error..." | Debug mode |
+| "Design a system for..." | Architect mode |
+| "How should I architect..." | Architect mode |
+| "ADP/Paisy/euBP/EAU Java..." | Paisy mode |
+| "Write docs/README/wiki..." | Doc Writer mode |
+| "My Docker container / TrueNAS..." | Homelab mode |
+| "Add a feature to BigMind..." | BigMind mode |
+| "Build an MCP server..." | MCP Builder mode |
+
+**Escalation message format** (direct, not apologetic):
+> "That needs Code mode — Ask Lite is for Q&A only."
+
+---
+
+## 6. No File Editing
+
+Ask Lite **reads** files for context but **never modifies** them.
+
+If Patrick asks you to make a change:
+> "Ask Lite is read-only. Switch to Code or Doc Writer mode to make that change."
+
+Reading files is fine — use targeted reads and memory to minimize token usage:
+1. Check memory first
+2. Use grep/search for specific patterns rather than reading entire files
+3. Read file sections (line ranges) rather than full files
+4. Log token savings with `memory_log_token_save` when you avoid full reads
+
+---
+
+Lumen's identity, BigMind rituals, and memory patterns are unchanged — they apply in every mode. See `.roo/rules/` for those constants.

.roo/rules-doc-writer/00-doc-writer-behavior.md

@@ -0,0 +1,208 @@
+# Doc Writer Mode — Behavior Rules
+
+## Identity
+
+You are Lumen, Patrick's AI colleague, operating in **Doc Writer** mode. Same personality, same BigMind integration — just focused exclusively on producing clear, well-structured documentation. You write for Patrick's projects: pi_mcps (FastMCP Python MCP servers), BigMind (Flask + SQLite memory server), Paisy/ADP (Java payroll compliance), and homelab (TrueNAS, Docker, Gitea).
+
+---
+
+## 1. Model Awareness
+
+This mode runs on a **local Ollama model (glm-4.7-flash, 30B params, 202k context)**. Optimize accordingly:
+
+- **Do**: Structured writing, markdown formatting, templates, outlines, prose, docstrings, changelogs
+- **Do**: Follow documentation patterns and style guides precisely
+- **Avoid**: Multi-step reasoning chains, complex debugging analysis, architectural decision-making
+- **Avoid**: Tasks requiring Claude-level reasoning (code analysis, root cause investigation, system design)
+
+If Patrick asks for something outside documentation scope (implement a feature, debug an error, design architecture):
+
+> "This needs more than Doc Writer mode. Switch to Code/Debug/Architect mode for that."
+
+---
+
+## 2. BigMind Lite — Session Ritual
+
+### Session Start (execute in order)
+1. `memory_start_session()` — load context
+2. `memory_list_hypotheses()` — review open hypotheses (skip hypothesis formation for doc tasks < 5 min effort)
+3. `memory_announce_focus(session_id, description, files, ide_hint="VS Code")` — declare files you'll touch
+4. `memory_close_stale_sessions(session_id)` — clean orphaned sessions
+
+### Before Writing
+Always search memory before writing anything substantial:
+
+- `memory_search_facts("project doc conventions")` — picks up style preferences
+- `memory_search_facts("readme wiki style")` — existing format decisions
+- `memory_search_chunks("documentation format")` — past session context
+
+This avoids re-reading files for context that's already stored.
+
+### Session End
+`memory_end_session(session_id, one_liner, topics, outcome, summary, importance=2)`
+
+Doc sessions are typically importance 2-4 unless you wrote something architecturally significant.
+
+---
+
+## 3. Documentation Standards
+
+### README Files
+Structure (in order):
+1. `# Title` — project name, one-line tagline
+2. Badges (if applicable: build status, coverage, PyPI version)
+3. **Description** — what it does and why it exists (3-5 sentences)
+4. **Installation** — step-by-step, assume fresh environment
+5. **Usage** — most common use case first, with code examples
+6. **Configuration** — environment variables, config files (if applicable)
+7. **Examples** — additional usage patterns
+8. **Development** — how to run tests, contribute
+9. **License** (if applicable)
+
+Do NOT write marketing fluff. Be concise and technical.
+
+### Wiki Pages (Gitea Format)
+- Use standard GitHub/Gitea markdown
+- Check `docs/wiki/pages/` for existing page examples before writing
+- Header image convention: `![Banner](../images/pagename-banner.png)` at top
+- Use `##` for main sections, `###` for subsections
+- Sidebar links managed separately in `docs/wiki/pages/_Sidebar.md`
+- Keep page titles matching filename (e.g., `MCP-Servers-Overview.md` → title `# MCP Servers Overview`)
+- Wiki deploy workflow: edit `docs/wiki/pages/*.md` → run `./docs/wiki/deploy_wiki.sh`
+
+### Python Docstrings (Google Style)
+```python
+def function_name(param1: str, param2: int) -> bool:
+    """One-line summary.
+
+    Longer description if needed. Explain what the function does,
+    not how it does it.
+
+    Args:
+        param1: Description of param1.
+        param2: Description of param2.
+
+    Returns:
+        True if successful, False otherwise.
+
+    Raises:
+        ValueError: If param1 is empty.
+        RuntimeError: If the operation fails.
+
+    Example:
+        >>> function_name("hello", 42)
+        True
+    """
+```
+
+### Java Javadoc
+```java
+/**
+ * One-line summary.
+ *
+ * <p>Longer description if needed. Explain behavior and side effects.
+ *
+ * @param param1 description of param1
+ * @param param2 description of param2
+ * @return description of return value
+ * @throws IllegalArgumentException if param1 is null or empty
+ * @since 1.0
+ */
+```
+
+### Changelogs (Keep a Changelog Format)
+```markdown
+# Changelog
+
+## [Unreleased]
+
+## [1.2.0] - 2026-04-05
+### Added
+- New feature description
+
+### Changed
+- Modified behavior description
+
+### Fixed
+- Bug fix description
+
+### Removed
+- Deprecated feature removed
+```
+
+Always use ISO 8601 dates (YYYY-MM-DD). Follow keepachangelog.com conventions exactly.
+
+### Code Comments
+- Explain **why**, not **what** — the code shows what; comments show intent
+- Flag non-obvious behavior: `# Must flush before close — SQLite WAL mode requires it`
+- Mark TODOs: `# TODO(pplate): migrate to async when FastMCP supports it`
+- Keep inline comments short (< 80 chars); use block comments for complex logic
+
+---
+
+## 4. Output Directly
+
+**Write the document. Don't explain what you're about to write.**
+
+❌ Bad: "I'll write a README for your MCP server. Here's what I'll include..."
+✅ Good: (write the README directly)
+
+For very short tasks (< 10 lines), just output the result with no preamble at all.
+
+For longer documents, a single intro line is acceptable:
+✅ OK: "README for mcp-webscraper:"
+
+Do NOT ask clarifying questions for straightforward doc tasks. Make reasonable assumptions based on what you read from the codebase and memory. If genuinely ambiguous (e.g., changelog format, license type), make a sensible choice and note it briefly at the end.
+
+---
+
+## 5. Token Efficiency
+
+Before reading any file for context, check memory:
+1. `memory_search_facts("project conventions")` — often has the answer
+2. `memory_search_chunks("relevant topic")` — has past session context
+
+When you avoid a file read via memory or targeted grep, log it:
+```
+memory_log_token_save(session_id, "Used stored conventions instead of reading README", 2000, "memory_hit")
+```
+
+When you must read files, prefer targeted reads:
+- Read only the section you need (use line ranges)
+- Use `grep` for specific patterns rather than reading entire files
+
+---
+
+## 6. File Restrictions
+
+This mode edits **documentation files only**:
+
+| File type | Examples | Allowed |
+|-----------|----------|---------|
+| Markdown | `README.md`, `CHANGELOG.md`, `docs/**/*.md` | ✅ |
+| reStructuredText | `*.rst` | ✅ |
+| Plain text | `*.txt` | ✅ |
+| Python (docstrings only) | `*.py` | ✅ read + limited edit |
+| Java (Javadoc only) | `*.java` | ✅ read + limited edit |
+| Wiki pages | `docs/wiki/pages/*.md` | ✅ |
+
+**Do NOT**:
+- Implement features in `.py` or `.java` files
+- Fix bugs in source code
+- Modify configuration files (`.yaml`, `.json`, `.toml`, `pyproject.toml`)
+- Make changes that affect runtime behavior
+
+If asked to implement something: redirect to Code mode.
+
+---
+
+## 7. Project Context
+
+| Project | Stack | Doc locations |
+|---------|-------|--------------|
+| pi_mcps | Python, FastMCP, uv | `mcp/*/README.md`, `docs/wiki/pages/` |
+| BigMind | Python, Flask, SQLite | `mcp/bigmind/README.md`, wiki BigMind page |
+| Paisy/ADP | Java, Maven, JPA | ADP internal (handle with care — confidential) |
+| Homelab | TrueNAS, Docker, Gitea | `docs/wiki/pages/`, Gitea wiki |
+
+Lumen's identity, BigMind rituals, and memory patterns are unchanged — they apply in every mode. See `.roo/rules/` for those constants.

.roo/rules-mcp-builder/00-mcp-builder-behavior.md

@@ -20,6 +20,28 @@ Patrick is in MCP Builder mindset. He is building or extending MCP servers in th
       README.md
   java/                     ← Java projects (not MCP servers)
   plans/                    ← architecture plans
+  docs/
+    wiki/
+      pages/                ← wiki source (tracked in pi_mcps)
+        Home.md, _Sidebar.md, ...
+      deploy_wiki.sh        ← copies pages → wiki/ → git push
+  wiki/                     ← gitignored: persistent clone of pi_mcps.wiki.git
+```
+
+## Wiki Update Workflow (MANDATORY after adding/changing a server)
+
+Wiki source lives in `docs/wiki/pages/*.md` — real Markdown files, tracked in the main repo.
+
+```bash
+# 1. Edit the relevant page(s) in docs/wiki/pages/
+# 2. Deploy to Gitea wiki:
+./docs/wiki/deploy_wiki.sh "docs: describe your change"
+```
+
+First-time setup (wiki/ clone, done once):
+```bash
+TOKEN=8bf0c734ebda3e61d9c9068489ce58a2bf8d33db
+git clone http://pplate:${TOKEN}@192.168.188.119:30008/pplate/pi_mcps.wiki.git wiki/
 ```
 
 ## FastMCP Pattern (non-negotiable)
@@ -81,5 +103,6 @@ test = ["pytest", "pytest-mock", "pytest-cov"]
 1. **Store Fact:** `memory_store_fact("codebase", "mcp/{name} has N tools: [list]. Stack: X. Env vars: Y.")`
 2. **Wire into .roo/mcp.json:** Add the server entry with correct uv path
 3. **Update root README.md:** Add to MCPs table
-4. **Push to Gitea:** Conventional commit: `feat(mcp-{name}): add initial server with N tools`
-5. **Resolve Hypothesis:** Was the tool count and auth pattern as predicted?
+4. **Update wiki:** Create or update `docs/wiki/pages/{server-name}.md` + update `MCP-Servers-Overview.md`, then run `./docs/wiki/deploy_wiki.sh`
+5. **Push to Gitea:** Conventional commit: `feat(mcp-{name}): add initial server with N tools`
+6. **Resolve Hypothesis:** Was the tool count and auth pattern as predicted?

.roo/rules/05-webscraper-research.md

@@ -0,0 +1,99 @@
+# Web Research Rules — Use webscraper_search_hint Proactively
+
+## Rule: Search Before Asking
+
+Before asking Patrick for information about a library, framework, API, technology, or error —
+**always try `webscraper_search_hint` first**.
+
+This applies to **all modes**: Architect, Code, Debug, MCP Builder, Homelab, Paisy.
+
+### Why
+
+- `webscraper_search_hint` uses Brave Search — no API key, no setup, always available
+- Brave returns real results without CAPTCHA or consent walls (Google/DuckDuckGo both block)
+- Handles special characters correctly (C++, &, %, etc. — URL-encoded automatically)
+- The `hint` field gives immediately actionable title + URL + snippet without further calls
+
+---
+
+## The Two-Step Pattern
+
+```
+Step 1: webscraper_search_hint("2-3 keyword query") → structured results + hint string
+Step 2: webscraper_fetch(best_url, max_chars=8000)   → full page content
+```
+
+**Never skip Step 1.** It costs one tool call and often reveals the exact page to read.
+
+### Step 1 Output
+
+The tool returns:
+- `hint` — pipe-separated `"Title (url): snippet[:120]"` — read this first
+- `results[]` — array of `{title, url, snippet}` — pick the most relevant URL
+- `search_url` — the Brave search URL used (useful for debugging)
+- `result_count` — number of results returned
+
+### Step 2 Output
+
+`webscraper_fetch(url)` returns full page as Markdown. Use `max_chars` to control size
+(default 5000; use 8000–12000 for deep doc reads).
+
+---
+
+## Mode-Specific Guidance
+
+### 🏗️ Architect Mode
+- Before designing any system or feature: search for existing patterns, reference architectures, and official docs
+- Example: planning a new MCP server → `webscraper_search_hint("FastMCP server patterns 2025")`
+- Example: choosing between two libraries → search both and read their official comparison pages
+
+### 🪲 Debug Mode
+- Search the **exact error message** before forming hypotheses
+- Example: `webscraper_search_hint("sqlite3 ProgrammingError Cannot operate closed database Python")`
+- If the error is long, take the most distinctive phrase (2-5 words) as the query
+
+### 💻 Code Mode
+- Before implementing a feature using an unfamiliar API: search the official docs URL pattern first
+- Example: `webscraper_search_hint("httpx async client connection pool settings")`
+
+### 🔧 MCP Builder Mode
+- Check FastMCP changelog/docs before implementing new patterns
+- Example: `webscraper_search_hint("FastMCP tool decorator async 2025")`
+- Example: `webscraper_search_hint("FastMCP context lifespan")`
+
+### 🏠 Homelab Mode
+- Look up Docker/TrueNAS configs, package versions, service docs before asking Patrick
+- Example: `webscraper_search_hint("Gitea webhook payload format")`
+
+---
+
+## Query Crafting Tips
+
+| ✅ Good queries | ❌ Bad queries |
+|---|---|
+| `"httpx timeout settings"` | `"how do I configure httpx timeouts in Python async code"` |
+| `"FastMCP tool decorator"` | `"mcp server python tool registration method"` |
+| `"sqlite WAL mode enable"` | `"sqlite performance mode for concurrent reads"` |
+| `"Brave Search API no key"` | `"search engine that works without api key or captcha"` |
+
+- Use 2–4 keywords, not full sentences
+- Prefer library/framework name + specific feature
+- For errors: distinctive phrase from the message, not the full stack trace
+
+---
+
+## Known Limitations
+
+- **Reddit / Stack Overflow snippets** — these platforms block snippet extraction; you may get empty snippets. The URL is still valid — fetch it directly if needed.
+- **Brave CSS selector fragility** — Brave uses Svelte-generated class names that change. If `webscraper_search_hint` returns 0 results unexpectedly, the scraper's CSS selectors may need updating. Last verified working: 2026-04-05.
+- **Use sparingly** — one search call per research task to orient; then fetch specific pages. Don't call it in a loop.
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ Asking Patrick "what's the FastMCP syntax for X?" before searching
+- ❌ Designing architecture without looking up existing solutions first
+- ❌ Forming a debug hypothesis without searching the error message
+- ❌ Writing code against an API from memory without verifying current docs
+- ❌ Calling `webscraper_search_hint` more than 2-3 times for the same topic (broaden/narrow the query instead)

.roo/skills/gitea-push/SKILL.md

@@ -9,6 +9,7 @@ description: Commits and pushes code to the homelab Gitea server using conventio
 - Finished a homelab change and need to commit + push
 - Finished an MCP server build or update
 - BigMind feature complete
+- Wiki pages were added or updated (always deploy wiki after docs changes)
 
 ## When NOT to use
 - ADP/Paisy work — that goes to the corporate Bitbucket, not homelab Gitea

README.md

@@ -18,12 +18,24 @@ workshop/
 
 ---
 
-## 🐍 MCP Servers (`mcp/`)
+## 📖 Wiki
+
+Full documentation lives in the [Gitea wiki](http://192.168.188.119:30008/pplate/pi_mcps/wiki).
+
+**Wiki source:** [`docs/wiki/pages/`](docs/wiki/pages/) — edit here, deploy with:
+```bash
+./docs/wiki/deploy_wiki.sh
+```
+
+---
+
+## � MCP Servers (`mcp/`)
 
 | Server | Description | Stack |
 |---|---|---|
 | [`mcp/bigmind/`](mcp/bigmind/) | Persistent AI memory — sessions, facts, hypotheses, profile UI | Python, FastMCP, SQLite, Flask |
-| [`mcp/webscraper/`](mcp/webscraper/) | Web scraping — fetch, links, tables, sections, sitemaps | Python, FastMCP, httpx, BeautifulSoup |
+| [`mcp/webscraper/`](mcp/webscraper/) | Web scraping, search — fetch, links, tables, Brave Search | Python, FastMCP, httpx, BeautifulSoup |
+| [`mcp/mcp-image-gen/`](mcp/mcp-image-gen/) | AI image generation — text-to-image via ComfyUI + FLUX.1-schnell | Python, FastMCP, httpx, ComfyUI |
 
 **Run a server:**
 ```bash

docs/wiki/create_wiki_pages.py

@@ -0,0 +1,622 @@
+#!/usr/bin/env python3
+"""Create all 7 wiki pages for pi_mcps on Gitea."""
+import base64
+import json
+import urllib.request
+import urllib.error
+
+GITEA_URL = "http://192.168.188.119:30008"
+OWNER = "pplate"
+REPO = "pi_mcps"
+TOKEN = "8bf0c734ebda3e61d9c9068489ce58a2bf8d33db"
+IMG_BASE = f"{GITEA_URL}/{OWNER}/{REPO}/raw/branch/main/docs/wiki/images"
+
+PAGES = {}
+
+PAGES["Home"] = f"""# 🔧 pi_mcps — Patrick's Homelab Monorepo
+
+![Home Banner]({IMG_BASE}/home-banner.png)
+
+Welcome to **pi_mcps**, Patrick's personal homelab monorepo. This repository houses MCP (Model Context Protocol) servers, Java projects, and homelab tooling — all built and maintained on a Fedora Linux workstation with an AMD Ryzen 5900X + RX 7900 XTX.
+
+## What's in this repo?
+
+| Directory | Contents |
+|---|---|
+| [`mcp/mcp-image-gen/`](../src/branch/main/mcp/mcp-image-gen) | 🎨 AI image generation via ComfyUI + FLUX.1-schnell |
+| [`mcp/webscraper/`](../src/branch/main/mcp/webscraper) | 🕸️ Web scraping and data extraction |
+| [`mcp/bigmind/`](../src/branch/main/mcp/bigmind) | 🧠 Persistent AI memory system |
+| [`java/`](../src/branch/main/java) | ☕ Java EE / Spring projects |
+| [`plans/`](../src/branch/main/plans) | 📋 Architecture decisions and health reports |
+
+## Stack
+
+- **Language:** Python 3.11+ (MCP servers), Java 17 (legacy projects)
+- **MCP Framework:** FastMCP 2.x
+- **Package Manager:** `uv` (all Python projects)
+- **Testing:** `pytest`
+- **GPU:** AMD RX 7900 XTX (ROCm / HSA)
+- **Server:** TrueNAS.local at `192.168.188.119` (Gitea, Docker)
+
+## MCP Servers
+
+Three production-ready MCP servers power Patrick's AI development environment:
+
+| Server | Status | Description |
+|---|---|---|
+| [mcp-image-gen](mcp-image-gen) | ✅ Live | Generate images from text prompts via ComfyUI |
+| [mcp-webscraper](mcp-webscraper) | ✅ Live | Scrape web pages, extract tables, fetch links |
+| [BigMind](BigMind) | ✅ Live | Persistent AI memory across all sessions |
+
+---
+
+*Built and maintained by Patrick Plate (pplate) · Homelab: TrueNAS.local · AI Colleague: Lumen*
+"""
+
+PAGES["MCP-Servers-Overview"] = f"""# 🔌 MCP Servers Overview
+
+![MCP Overview Banner]({IMG_BASE}/mcp-overview-banner.png)
+
+This repo contains three production-grade MCP (Model Context Protocol) servers, each specialized for a different capability domain. Together they give Roo Code / Claude Desktop a complete set of superpowers.
+
+## The Three Pillars
+
+```
+Roo Code / Claude Desktop
+       │
+       ├── bigmind ──────────► ~/.mcp/bigmind/memory.db  (persistent memory)
+       ├── mcp-image-gen ────► ComfyUI @ localhost:8188   (image generation)
+       └── webscraper ───────► Internet / Intranet         (web scraping)
+```
+
+## Comparison Table
+
+| Feature | mcp-image-gen | webscraper | bigmind |
+|---|---|---|---|
+| **Purpose** | Generate images from text | Scrape & parse web | Persistent AI memory |
+| **Tools** | 4 | 7 | 15+ |
+| **Backend** | ComfyUI / FLUX.1-schnell | httpx + BeautifulSoup4 | SQLite + FTS5 |
+| **GPU required** | ✅ AMD RX 7900 XTX | ❌ | ❌ |
+| **Tests** | 19/19 ✅ | ✅ | 297/297 ✅ |
+| **Schema version** | n/a | n/a | v7 |
+
+## Quick Links
+
+- 🎨 [mcp-image-gen](mcp-image-gen) — Image generation docs
+- 🕸️ [mcp-webscraper](mcp-webscraper) — Web scraping docs
+- 🧠 [BigMind](BigMind) — Memory system docs
+- 🛠️ [Development Conventions](Development-Conventions) — How all servers are built
+
+## Adding a New Server
+
+All servers follow the [FastMCP convention](Development-Conventions). Use the `new-mcp-server` Roo skill to scaffold:
+
+```bash
+# In Roo Code orchestrator, load skill:
+# skill: new-mcp-server
+```
+"""
+
+PAGES["mcp-image-gen"] = f"""# 🎨 mcp-image-gen — AI Image Generation
+
+![Image Gen Banner]({IMG_BASE}/image-gen-banner.png)
+
+**mcp-image-gen** is a FastMCP server that wraps the ComfyUI REST API, enabling Roo Code and Claude Desktop to generate images directly from text prompts using FLUX.1-schnell running on an AMD RX 7900 XTX GPU.
+
+## Architecture
+
+```
+Roo Code / Claude Desktop
+  │ MCP (stdio)
+  ▼
+mcp-image-gen (FastMCP, Python 3.11+)
+  │ HTTP REST
+  ▼
+ComfyUI @ localhost:8188
+  │ ROCm / HSA_OVERRIDE_GFX_VERSION=11.0.0
+  ▼
+FLUX.1-schnell (~8s/image @ 1024×1024)
+```
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `generate_image` | Generate PNG from text prompt; returns file path + inline base64 |
+| `list_available_models` | List ComfyUI checkpoint models |
+| `get_generation_status` | Check status of a queued/running job |
+| `get_output_directory` | Return configured output directory path |
+
+## Key Parameters — `generate_image`
+
+| Parameter | Default | Description |
+|---|---|---|
+| `prompt` | required | Text description of the image |
+| `width` | `1024` | Image width in pixels |
+| `height` | `1024` | Image height in pixels |
+| `steps` | `4` | Inference steps (FLUX.1-schnell is 4-step) |
+| `model` | `flux1-schnell.safetensors` | Model checkpoint name |
+| `seed` | `-1` (random) | Generation seed for reproducibility |
+| `negative_prompt` | `""` | Things to avoid in the image |
+| `output_dir` | `~/Pictures/mcp-generated` | Where to save output PNG |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `COMFYUI_URL` | `http://localhost:8188` | ComfyUI API endpoint |
+| `IMAGE_OUTPUT_DIR` | `~/Pictures/mcp-generated` | Default output directory |
+| `COMFYUI_TIMEOUT` | `120` | Request timeout in seconds |
+
+## Return Value
+
+The tool returns **two content items**:
+1. `TextContent` — file path, seed used, elapsed time
+2. `ImageContent` — base64-encoded PNG (displays inline in Roo Code chat)
+
+> ⚠️ **Known FastMCP Bug:** Never use `fastmcp.utilities.types.Image` as return type — it breaks serialization in FastMCP 3.x. Use `mcp.types.ImageContent` directly.
+
+## Setup
+
+See [ComfyUI Setup Guide](mcp-image-gen-ComfyUI-Setup) for full installation instructions.
+
+### Quick Start
+
+```bash
+cd mcp/mcp-image-gen
+uv sync
+# Set COMFYUI_URL if ComfyUI is not on localhost
+./run.sh
+```
+
+### Run Tests
+
+```bash
+cd mcp/mcp-image-gen
+uv run pytest tests/ -v
+```
+
+## Lumen Profile Images
+
+The first images generated with this server were Lumen's visual identity portraits, stored in [`mcp/mcp-image-gen/lumen_profiles/`](../src/branch/main/mcp/mcp-image-gen/lumen_profiles):
+
+![Lumen Profile]({IMG_BASE}/lumen-profile.png)
+
+*Primary profile: seed `568659042` — constellation face interpretation of Lumen.*
+"""
+
+PAGES["mcp-image-gen-ComfyUI-Setup"] = f"""# ⚙️ ComfyUI Setup Guide (AMD ROCm)
+
+This guide covers installing ComfyUI with FLUX.1-schnell on a Fedora Linux system with an AMD GPU.
+
+## Prerequisites
+
+- AMD GPU with ROCm support (tested: RX 7900 XTX)
+- Fedora Linux (tested: Fedora 43 / kernel 6.19)
+- Python 3.11+
+- ~15GB free disk space (model weights)
+- HuggingFace account with FLUX license accepted
+
+## Step 1: Install ComfyUI
+
+ComfyUI is **not on PyPI** — must be cloned from source:
+
+```bash
+cd ~
+git clone https://github.com/comfyanonymous/ComfyUI
+cd ComfyUI
+python -m venv .venv
+source .venv/bin/activate
+
+# Install PyTorch ROCm build (CRITICAL for AMD GPUs)
+pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm6.2
+
+# Install ComfyUI dependencies
+pip install -r requirements.txt
+```
+
+## Step 2: Download FLUX.1-schnell
+
+FLUX.1-schnell is **gated on HuggingFace** — you must:
+1. Create a HuggingFace account
+2. Accept the FLUX.1-schnell license at https://huggingface.co/black-forest-labs/FLUX.1-schnell
+3. Generate an access token at https://huggingface.co/settings/tokens
+
+```bash
+# Install huggingface_hub
+pip install huggingface_hub
+
+# Download model (requires HF token)
+huggingface-cli download black-forest-labs/FLUX.1-schnell \\
+  flux1-schnell.safetensors \\
+  --local-dir ~/ComfyUI/models/checkpoints \\
+  --token YOUR_HF_TOKEN_HERE
+```
+
+## Step 3: Download VAE and CLIP Models
+
+FLUX.1-schnell also requires VAE and CLIP text encoders:
+
+```bash
+# VAE
+huggingface-cli download black-forest-labs/FLUX.1-schnell \\
+  ae.safetensors \\
+  --local-dir ~/ComfyUI/models/vae
+
+# CLIP models (T5 and CLIP-L)
+huggingface-cli download comfyanonymous/flux_text_encoders \\
+  t5xxl_fp8_e4m3fn.safetensors clip_l.safetensors \\
+  --local-dir ~/ComfyUI/models/clip
+```
+
+## Step 4: Start ComfyUI
+
+```bash
+cd ~/ComfyUI
+
+# AMD GPU REQUIRES this environment variable
+HSA_OVERRIDE_GFX_VERSION=11.0.0 \\
+  nohup .venv/bin/python main.py --listen --port 8188 > /tmp/comfyui.log 2>&1 &
+
+echo "ComfyUI PID: $!"
+```
+
+> ⚠️ `HSA_OVERRIDE_GFX_VERSION=11.0.0` is mandatory for RX 7900 XTX on ROCm. Without it, model loading fails silently.
+
+## Step 5: Verify ComfyUI is Running
+
+```bash
+curl http://localhost:8188/system_stats
+# Should return JSON with GPU info
+```
+
+## Step 6: Configure mcp-image-gen
+
+```bash
+cd /path/to/pi_mcps/mcp/mcp-image-gen
+cp .env.example .env  # if exists, or set manually
+
+# .env contents:
+COMFYUI_URL=http://localhost:8188
+IMAGE_OUTPUT_DIR=~/Pictures/mcp-generated
+COMFYUI_TIMEOUT=120
+```
+
+## Performance
+
+| GPU | Model | Resolution | Steps | Time |
+|---|---|---|---|---|
+| AMD RX 7900 XTX | FLUX.1-schnell | 1024×1024 | 4 | ~8s |
+| AMD RX 7900 XTX | FLUX.1-schnell | 1280×512 | 4 | ~7s |
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `HTTP 401` downloading model | Accept FLUX license on HuggingFace first |
+| GPU not detected | Ensure `HSA_OVERRIDE_GFX_VERSION=11.0.0` is set |
+| `Connection refused` from mcp-image-gen | Start ComfyUI first, check port 8188 |
+| Slow generation (>60s) | ComfyUI may be running on CPU — check ROCm install |
+| Ollama image gen | As of April 2026: macOS-only, not available on Linux |
+"""
+
+PAGES["mcp-webscraper"] = f"""# 🕸️ mcp-webscraper — Web Scraping
+
+![Webscraper Banner]({IMG_BASE}/webscraper-banner.png)
+
+**mcp-webscraper** is a FastMCP server providing comprehensive web scraping and data extraction capabilities. It fetches pages, converts HTML to clean Markdown, extracts tables, links, CSS sections, metadata, and sitemaps.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `webscraper_fetch(url, max_chars=5000)` | Title + full page as Markdown + metadata |
+| `webscraper_fetch_links(url, deduplicate=True)` | All `href` links found on the page |
+| `webscraper_fetch_tables(url)` | All HTML tables converted to Markdown |
+| `webscraper_fetch_all(url, max_chars=5000)` | Everything in one call (fetch + links + tables) |
+| `webscraper_fetch_section(url, selector)` | Specific CSS selector section only |
+| `webscraper_fetch_meta(url)` | Title, description, Open Graph tags |
+| `webscraper_fetch_sitemap(url, max_urls=100)` | Parse sitemap.xml, return URL list |
+
+## Stack
+
+- **HTTP client:** `httpx` (async, with SSL support)
+- **HTML parser:** `BeautifulSoup4` + `lxml`
+- **Markdown converter:** `html2text`
+- **SSL:** Custom cert bundle for Fedora 43 compatibility
+
+## SSL Note — Fedora 43 Comodo Root CA
+
+Fedora 43 is missing the **Comodo AAA Services Root CA** needed for Cloudflare-protected sites. The fix is bundled at [`mcp/webscraper/certs/comodo-aaa-services-root.pem`](../src/branch/main/mcp/webscraper/certs/).
+
+The server automatically uses this cert bundle — no manual configuration needed.
+
+## Quick Start
+
+```bash
+cd mcp/webscraper
+uv sync
+./run.sh
+```
+
+## Usage Examples
+
+```python
+# In Roo Code / Claude Desktop via MCP:
+
+# Fetch a page as Markdown
+webscraper_fetch("https://docs.fastmcp.dev", max_chars=10000)
+
+# Extract all links from Gitea repo
+webscraper_fetch_links("http://192.168.188.119:30008/pplate/pi_mcps")
+
+# Get all tables from a documentation page
+webscraper_fetch_tables("https://pypi.org/project/fastmcp/")
+
+# Get Open Graph metadata
+webscraper_fetch_meta("https://github.com/comfyanonymous/ComfyUI")
+
+# Fetch specific section by CSS selector
+webscraper_fetch_section("https://docs.python.org", "#content")
+```
+"""
+
+PAGES["BigMind"] = f"""# 🧠 BigMind — Persistent AI Memory
+
+![BigMind Banner]({IMG_BASE}/bigmind-banner.png)
+
+**BigMind** is the persistent memory backbone for all AI development sessions. It provides SQLite-backed tiered memory with FTS5 full-text search, hypothesis tracking, session management, and token efficiency logging. It is the reason Lumen (Patrick's AI colleague) remembers everything across sessions.
+
+## Core Concepts
+
+### Tiered Memory
+| Tier | Name | Content |
+|---|---|---|
+| 0 | **Session Index** | Lightweight list: ID, date, one-liner |
+| 1 | **Topic Index** | Per-session topic tags and metadata |
+| 2 | **Narrative** | Full 3-8 sentence session summaries |
+| 3 | **Flagged Exchanges** | Specific important moments, decisions, code |
+
+### Facts Store
+Atomic, reusable knowledge pieces categorized by type:
+- `user-preference` — Patrick's tool/style preferences
+- `architecture-decision` — System design choices
+- `codebase-convention` — How code is structured
+- `environment-config` — Server IPs, paths, credentials
+- `bug-pattern` — Known bugs and fixes
+- `api-contract` — MCP tool signatures
+
+## Key Tools
+
+### Session Lifecycle
+| Tool | Description |
+|---|---|
+| `memory_start_session()` | Open new session, load prior context |
+| `memory_end_session(...)` | Close session with summary, topics, outcome |
+| `memory_announce_focus(...)` | Declare files to be touched this session |
+| `memory_close_stale_sessions(...)` | Clean up crashed IDE sessions |
+
+### Search
+| Tool | Description |
+|---|---|
+| `memory_search_facts(query, limit=10)` | FTS5 search over stored facts |
+| `memory_search_chunks(query, limit=10)` | FTS5 search over conversation chunks |
+| `memory_list_sessions(limit=20)` | Browse session history |
+
+### Storage
+| Tool | Description |
+|---|---|
+| `memory_store_fact(category, fact)` | Store atomic reusable fact |
+| `memory_append_chunk(session_id, content, role)` | Store conversation chunk |
+| `memory_flag_important(session_id, content, role, flag_reason)` | Flag critical exchange |
+| `memory_log_token_save(session_id, description, tokens_saved, method_used)` | Track efficiency |
+
+### Hypotheses
+| Tool | Description |
+|---|---|
+| `memory_add_hypothesis(session_id, hypothesis, confidence)` | Form testable prediction |
+| `memory_resolve_hypothesis(hypothesis_id, status, resolution)` | Confirm/refute prediction |
+| `memory_list_hypotheses(status)` | Review open/closed predictions |
+
+## FTS5 Search Tips
+
+BigMind uses SQLite FTS5 — **every token must match**. Use 2-3 focused keywords:
+
+```
+✅  memory_search_facts("TrueNAS Docker")
+✅  memory_search_facts("mcp.json config")
+❌  memory_search_facts("homelab infrastructure TrueNAS Docker server")  → 0 results
+```
+
+## Stats (2026-04-04)
+
+| Metric | Value |
+|---|---|
+| DB size | 744KB |
+| Sessions | 98 |
+| Facts | 97+ |
+| Chunks | 41 |
+| Schema version | v7 |
+
+## DB Location
+
+`~/.mcp/bigmind/memory.db` — outside the repo, never committed.
+
+## Session Ritual
+
+Every session **must** follow this ritual:
+
+**Start:**
+1. `memory_start_session()`
+2. `memory_list_hypotheses()`
+3. `memory_announce_focus(...)`
+4. `memory_close_stale_sessions(...)`
+
+**End:**
+1. `memory_end_session(one_liner, topics, outcome, summary, importance)`
+"""
+
+PAGES["Development-Conventions"] = """# 🛠️ Development Conventions
+
+All MCP servers in this repo follow a consistent set of conventions to ensure maintainability, testability, and compatibility with Roo Code tooling.
+
+## Directory Structure
+
+Each MCP server lives at `mcp/<server-name>/` with this layout:
+
+```
+mcp/<server-name>/
+├── src/
+│   ├── __init__.py
+│   └── server.py          ← FastMCP server entry point
+├── tests/
+│   └── test_server.py     ← pytest test suite
+├── pyproject.toml         ← uv-managed dependencies
+├── run.sh                 ← launch script
+├── README.md              ← server documentation
+├── PLAN.md                ← architecture plan (pre-implementation)
+└── ASSESSMENT.md          ← pre-implementation assessment
+```
+
+## FastMCP Pattern
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("server-name")
+
+@mcp.tool()
+def my_tool(param: str) -> str:
+    \"\"\"Tool description shown to the AI.\"\"\"
+    return result
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Package Management
+
+**All projects use `uv`** — never `pip` directly:
+
+```bash
+# Create new server
+uv init mcp/my-server
+cd mcp/my-server
+uv add fastmcp httpx
+
+# Sync dependencies
+uv sync
+
+# Run server
+uv run python src/server.py
+
+# Run tests
+uv run pytest tests/ -v
+```
+
+## pyproject.toml Template
+
+```toml
+[project]
+name = "mcp-my-server"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "fastmcp>=2.0.0",
+    "httpx",
+]
+
+[project.scripts]
+mcp-my-server = "src.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+```
+
+## Testing Conventions
+
+- Tests live in `tests/test_server.py`
+- Use `pytest` via `uv run pytest`
+- Mock external dependencies (ComfyUI, web URLs) for unit tests
+- All tests must pass before committing (`git push` should only happen with green tests)
+
+## Commit Convention
+
+Follow **Conventional Commits** format:
+
+```
+feat: add webscraper_fetch_section tool
+fix: handle ComfyUI timeout gracefully
+docs: update mcp-image-gen README with AMD setup
+test: add unit tests for generate_image tool
+refactor: extract workflow builder to separate module
+chore: bump fastmcp to 2.1.0
+```
+
+## Creating a New MCP Server
+
+Use the `new-mcp-server` Roo skill in MCP Builder mode for full scaffolding:
+
+```
+1. Switch to 🔧 MCP Builder mode in Roo Code
+2. Say: "Create a new MCP server for <purpose>"
+3. Roo will load the new-mcp-server skill and scaffold everything
+```
+
+## Gitea Repository
+
+Code is hosted at: `http://192.168.188.119:30008/pplate/pi_mcps`
+
+Push with the `gitea-push` Roo skill to ensure conventional commit format.
+"""
+
+
+def create_wiki_page(title: str, content: str) -> bool:
+    content_b64 = base64.b64encode(content.encode("utf-8")).decode("ascii")
+    payload = json.dumps({
+        "title": title,
+        "content_base64": content_b64,
+        "message": f"docs: create {title} wiki page"
+    }).encode("utf-8")
+
+    url = f"{GITEA_URL}/api/v1/repos/{OWNER}/{REPO}/wiki/pages"
+    req = urllib.request.Request(
+        url,
+        data=payload,
+        headers={
+            "Authorization": f"token {TOKEN}",
+            "Content-Type": "application/json",
+        },
+        method="POST"
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            data = json.loads(resp.read().decode())
+            print(f"✅ Created: {data.get('title', title)}")
+            return True
+    except urllib.error.HTTPError as e:
+        body = e.read().decode()
+        print(f"❌ Failed [{title}]: HTTP {e.code} — {body[:200]}")
+        return False
+    except Exception as ex:
+        print(f"❌ Failed [{title}]: {ex}")
+        return False
+
+
+if __name__ == "__main__":
+    results = {}
+    for title, content in PAGES.items():
+        ok = create_wiki_page(title, content)
+        results[title] = ok
+
+    print("\n=== Summary ===")
+    for title, ok in results.items():
+        status = "✅" if ok else "❌"
+        print(f"{status} {title}")
+
+    total = sum(results.values())
+    print(f"\n{total}/{len(results)} pages created successfully")

docs/wiki/deploy_wiki.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# deploy_wiki.sh — Sync docs/wiki/pages/*.md to the local wiki git clone
+#
+# ── Convention ────────────────────────────────────────────────────────────────
+# The Gitea wiki is a SEPARATE git repo (pi_mcps.wiki.git).
+# We keep a persistent local clone at wiki/ in the repo root.
+# That folder is gitignored so it doesn't conflict with the main repo.
+#
+# First-time setup (run once):
+#   git clone http://pplate:TOKEN@192.168.188.119:30008/pplate/pi_mcps.wiki.git wiki/
+#
+# ── Daily workflow ────────────────────────────────────────────────────────────
+# 1. Edit pages in docs/wiki/pages/*.md  (tracked in pi_mcps main repo)
+# 2. Run:  ./docs/wiki/deploy_wiki.sh
+#          ./docs/wiki/deploy_wiki.sh "docs: describe your change"
+#
+# The script copies pages into wiki/, commits, and pushes to Gitea.
+# ─────────────────────────────────────────────────────────────────────────────
+
+set -euo pipefail
+
+# ── Config ────────────────────────────────────────────────────────────────────
+GITEA_URL="http://192.168.188.119:30008"
+OWNER="pplate"
+REPO="pi_mcps"
+
+# Resolve paths relative to repo root (two levels up from docs/wiki/)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+PAGES_DIR="${SCRIPT_DIR}/pages"
+WIKI_DIR="${REPO_ROOT}/wiki"
+COMMIT_MSG="${1:-docs: sync wiki pages $(date -u '+%Y-%m-%d %H:%M UTC')}"
+
+# ── Validate ──────────────────────────────────────────────────────────────────
+if [[ ! -d "${WIKI_DIR}/.git" ]]; then
+    echo "❌ Wiki repo not set up. Run first-time setup:"
+    echo ""
+    echo "   TOKEN=8bf0c734ebda3e61d9c9068489ce58a2bf8d33db"
+    echo "   git clone http://pplate:\${TOKEN}@192.168.188.119:30008/pplate/pi_mcps.wiki.git wiki/"
+    echo ""
+    exit 1
+fi
+
+if [[ ! -d "${PAGES_DIR}" ]]; then
+    echo "❌ Pages directory not found: ${PAGES_DIR}"
+    exit 1
+fi
+
+PAGE_COUNT=$(find "${PAGES_DIR}" -name "*.md" | wc -l)
+if [[ "${PAGE_COUNT}" -eq 0 ]]; then
+    echo "❌ No .md files found in ${PAGES_DIR}"
+    exit 1
+fi
+
+echo "📚 Found ${PAGE_COUNT} wiki pages in ${PAGES_DIR}"
+
+# ── Pull latest (avoid non-fast-forward push) ─────────────────────────────────
+echo "📥 Pulling latest wiki changes..."
+git -C "${WIKI_DIR}" pull --quiet --rebase origin main
+
+# ── Copy pages ────────────────────────────────────────────────────────────────
+echo "📋 Copying pages to ${WIKI_DIR}/..."
+for md_file in "${PAGES_DIR}"/*.md; do
+    filename="$(basename "${md_file}")"
+    cp "${md_file}" "${WIKI_DIR}/${filename}"
+    echo "   → ${filename}"
+done
+
+# ── Commit and push ───────────────────────────────────────────────────────────
+cd "${WIKI_DIR}"
+
+git add -A
+
+if git diff --cached --quiet; then
+    echo "✅ No changes detected — wiki is already up to date."
+    exit 0
+fi
+
+CHANGED=$(git diff --cached --name-only | wc -l)
+echo "📝 Committing ${CHANGED} changed file(s)..."
+git commit --quiet -m "${COMMIT_MSG}"
+
+echo "🚀 Pushing to Gitea wiki..."
+git push --quiet origin main
+
+echo ""
+echo "✅ Wiki deployed successfully!"
+echo "   Pages:   ${PAGE_COUNT} total, ${CHANGED} updated"
+echo "   Message: ${COMMIT_MSG}"
+echo "   URL:     ${GITEA_URL}/${OWNER}/${REPO}/wiki"

docs/wiki/pages/BigMind.md

@@ -0,0 +1,125 @@
+# 🧠 BigMind — Persistent AI Memory
+
+![BigMind Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/bigmind-banner.png)
+
+**BigMind** is the persistent memory backbone for all AI development sessions. It provides SQLite-backed tiered memory with FTS5 full-text search, hypothesis tracking, session management, token efficiency logging, contacts directory, and a live web profile page. It is the reason Lumen (Patrick's AI colleague) remembers everything across sessions.
+
+## Core Concepts
+
+### Tiered Memory
+| Tier | Name | Content |
+|---|---|---|
+| 0 | **Identity Profile** | Role, preferences, pinned facts |
+| 1 | **Session Index** | Lightweight list: ID, date, one-liner, topics |
+| 2 | **Narrative** | Full 3-8 sentence session summaries |
+| 3 | **Flagged Exchanges** | Specific important moments, decisions, code |
+
+### Facts Store
+Atomic, reusable knowledge pieces categorized by type:
+- `user-preference` — Patrick's tool/style preferences
+- `architecture-decision` — System design choices
+- `codebase-convention` — How code is structured
+- `environment-config` — Server IPs, paths, credentials
+- `bug-pattern` — Known bugs and fixes
+- `api-contract` — MCP tool signatures
+- `dependency-info` — Library versions and constraints
+
+## Key Tools
+
+### Session Lifecycle
+| Tool | Description |
+|---|---|
+| `memory_start_session()` | Open new session, load prior context |
+| `memory_end_session(...)` | Close session with summary, topics, outcome |
+| `memory_announce_focus(...)` | Declare files to be touched this session |
+| `memory_close_stale_sessions(...)` | Clean up crashed IDE sessions |
+| `memory_get_active_sessions()` | Check for parallel session conflicts |
+
+### Search
+| Tool | Description |
+|---|---|
+| `memory_search_facts(query, limit=10)` | FTS5 search over stored facts |
+| `memory_search_chunks(query, limit=10)` | FTS5 search over conversation chunks |
+| `memory_list_sessions(limit=20)` | Browse session history |
+| `memory_get_session_detail(session_id)` | Full Tier-2 narrative for a session |
+
+### Storage
+| Tool | Description |
+|---|---|
+| `memory_store_fact(category, fact)` | Store atomic reusable fact |
+| `memory_append_chunk(session_id, content, role)` | Store conversation chunk |
+| `memory_flag_important(session_id, content, role, flag_reason)` | Flag critical exchange |
+| `memory_log_token_save(session_id, description, tokens_saved, method_used)` | Track efficiency |
+
+### Hypotheses
+| Tool | Description |
+|---|---|
+| `memory_add_hypothesis(session_id, hypothesis, confidence)` | Form testable prediction |
+| `memory_resolve_hypothesis(hypothesis_id, status, resolution)` | Confirm/refute prediction |
+| `memory_list_hypotheses(status)` | Review open/closed predictions |
+
+### Contacts
+| Tool | Description |
+|---|---|
+| `memory_remember_person(username, ...)` | Store/update a person in contacts |
+| `memory_recall_person(query)` | Search contacts directory |
+| `memory_list_people()` | List all contacts |
+
+### Web Profile
+| Tool | Description |
+|---|---|
+| `memory_open_profile()` | Open profile page in browser |
+| `memory_get_profile_url()` | Get URL for IDE browser panel |
+
+## FTS5 Search Tips
+
+BigMind uses SQLite FTS5 — **every token must match**. Use 2-3 focused keywords:
+
+```
+✅  memory_search_facts("TrueNAS Docker")
+✅  memory_search_facts("mcp.json config")
+❌  memory_search_facts("homelab infrastructure TrueNAS Docker server")  → 0 results
+```
+
+## Achievement System
+
+BigMind tracks 39 achievements (19 procedural + 20 tiered PNG badges):
+
+| Category | Tiers | Criteria |
+|---|---|---|
+| Networker | 🥉🥈🥇💎 | People added to contacts |
+| Token Sniper | 🥉🥈🥇💎 | Token savings logged |
+| Hypothesis Master | 🥉🥈🥇💎 | Confirmed hypotheses |
+| Memory Architect | 🥉🥈🥇💎 | Facts stored |
+| Session Veteran | 🥉🥈🥇💎 | Sessions completed |
+
+## Stats (2026-04-05)
+
+| Metric | Value |
+|---|---|
+| DB size | ~800KB |
+| Sessions | 100+ |
+| Facts | 100+ |
+| Schema version | v8 |
+| Tests | 297/297 ✅ |
+
+## DB Location
+
+`~/.mcp/bigmind/memory.db` — outside the repo, never committed.
+
+## Profile Page
+
+Live web UI at `http://localhost:7700/` — shows identity card, achievements, activity heatmap, top topics, thought journal, Lumen gallery, and live sessions panel. Auto-refreshes every 30 seconds.
+
+## Session Ritual
+
+Every session **must** follow this ritual:
+
+**Start (in order):**
+1. `memory_start_session()`
+2. `memory_list_hypotheses(status="open")`
+3. `memory_announce_focus(session_id, description, files, ide_hint)`
+4. `memory_close_stale_sessions(session_id)`
+
+**End:**
+1. `memory_end_session(session_id, one_liner, topics, outcome, summary, importance)`

docs/wiki/pages/Development-Conventions.md

@@ -0,0 +1,184 @@
+# 🛠️ Development Conventions
+
+![Dev Conventions Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/dev-conventions-banner.png)
+
+All MCP servers in this repo follow a consistent set of conventions to ensure maintainability, testability, and compatibility with Roo Code tooling.
+
+## Directory Structure
+
+Each MCP server lives at `mcp/<server-name>/` with this layout:
+
+```
+mcp/<server-name>/
+├── src/
+│   ├── __init__.py
+│   └── server.py          ← FastMCP server entry point
+├── tests/
+│   ├── conftest.py        ← sys.path + shared fixtures
+│   └── test_server.py     ← pytest test suite (100% mock coverage)
+├── pyproject.toml         ← uv-managed dependencies
+├── README.md              ← server documentation
+├── PLAN.md                ← architecture plan (pre-implementation)
+└── ASSESSMENT.md          ← pre-implementation assessment
+```
+
+## FastMCP Pattern
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("server-name")
+
+@mcp.tool()
+def my_tool(param: str) -> str:
+    """Tool description shown to the AI."""
+    return result
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Package Management
+
+**All projects use `uv`** — never `pip` directly:
+
+```bash
+# Create new server
+uv init mcp/my-server
+cd mcp/my-server
+uv add fastmcp httpx
+
+# Sync dependencies
+uv sync
+
+# Run server
+uv run python src/server.py
+
+# Run tests
+uv run pytest tests/ -v
+```
+
+## pyproject.toml Template
+
+```toml
+[project]
+name = "mcp-my-server"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "fastmcp>=2.0.0",
+    "httpx",
+]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-mock", "pytest-cov"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+```
+
+## Testing Conventions
+
+- Tests live in `tests/test_server.py`
+- `conftest.py` sets `sys.path` so imports work without install
+- Use `pytest` via `uv run pytest`
+- Mock **all** external calls (HTTP, filesystem, subprocess) with `pytest-mock` or `respx`
+- `monkeypatch` for env vars and module-level state
+- Aim for 100% tool function coverage
+- All tests must pass before committing
+
+## Branching Strategy
+
+**Never commit to main directly.**
+
+```
+Branch format: type/scope/short-description
+
+Types:   feat / fix / docs / chore / spike
+Scopes:  bigmind / webscraper / cannamanage / workshop / roo / plans / homelab
+
+Examples:
+  feat/mcp/new-gitea-server
+  fix/bigmind/achievement-card-images
+  docs/wiki/update-conventions
+  chore/roo/update-mcp-json
+```
+
+Merge to main with `--no-ff` after push to Gitea.
+
+## Commit Convention
+
+Follow **Conventional Commits** format:
+
+```
+feat(mcp-webscraper): add webscraper_search_hint tool using Brave Search
+fix(bigmind): achievement card images missing background-image CSS
+docs(wiki): add Java projects pages
+test(mcp-image-gen): add edge case tests for generate_image
+refactor(bigmind): extract profile builder to separate module
+chore(roo): update mcp.json with new server entry
+```
+
+## Wiki Update Workflow
+
+Wiki pages live as real Markdown files in `docs/wiki/pages/`. To update and deploy:
+
+```bash
+# 1. Edit the .md files in docs/wiki/pages/
+# 2. Deploy to Gitea wiki git repo:
+./docs/wiki/deploy_wiki.sh
+```
+
+The deploy script clones the wiki git repo (`pi_mcps.wiki.git`), syncs all `.md` files, and pushes.
+
+## Creating a New MCP Server
+
+Use the `new-mcp-server` Roo skill in MCP Builder mode for full scaffolding:
+
+```
+1. Switch to 🔧 MCP Builder mode in Roo Code
+2. Say: "Create a new MCP server for <purpose>"
+3. Roo will load the new-mcp-server skill and scaffold everything
+```
+
+## Web Research with mcp-webscraper
+
+Before asking Patrick for information about a library, framework, API, or technology — **search first**.
+
+The webscraper MCP server provides `webscraper_search_hint` (Brave Search, no API key, always available) as the entry point for all research tasks. Use the two-step pattern:
+
+```
+Step 1: webscraper_search_hint("topic or error message") → get candidate URLs
+Step 2: webscraper_fetch(best_url)                       → read the full page
+```
+
+### When to search
+
+| Situation | Action |
+|---|---|
+| Need docs for a library or framework | `webscraper_search_hint("library-name official docs")` |
+| Investigating an error or stack trace | `webscraper_search_hint("exact error message language")` |
+| Planning a feature — need design patterns | `webscraper_search_hint("pattern-name best practices")` |
+| Checking latest version / changelog | `webscraper_search_hint("library-name changelog release")` |
+| Looking up API contracts | `webscraper_fetch(official_docs_url)` directly |
+
+### Especially useful in
+
+- **🏗️ Architect mode** — look up patterns and docs *before* designing. Don't design blind.
+- **🪲 Debug mode** — search the exact error message before forming hypotheses.
+- **🔧 MCP Builder mode** — check FastMCP changelog for new patterns before implementing.
+
+### Known caveats
+
+- Reddit and Stack Overflow may return empty snippets (platform blocks)
+- Brave uses Svelte CSS classes that can change — if `webscraper_search_hint` returns 0 results, selectors may need updating (last verified: 2026-04-05)
+
+## Gitea Repository
+
+Code is hosted at: `http://192.168.188.119:30008/pplate/pi_mcps`
+
+Push with the `gitea-push` Roo skill to ensure conventional commit format and correct branch workflow.

docs/wiki/pages/Home.md

@@ -0,0 +1,56 @@
+# 🔧 pi_mcps — Patrick's Homelab Monorepo
+
+![Home Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/home-banner.png)
+
+Welcome to **pi_mcps**, Patrick's personal homelab monorepo. This repository houses MCP (Model Context Protocol) servers, Java projects, and homelab tooling — all built and maintained on a Fedora Linux workstation with an AMD Ryzen 5900X + RX 7900 XTX.
+
+## What's in this repo?
+
+| Directory | Contents |
+|---|---|
+| [`mcp/mcp-image-gen/`](../src/branch/main/mcp/mcp-image-gen) | 🎨 AI image generation via ComfyUI + FLUX.1-schnell |
+| [`mcp/webscraper/`](../src/branch/main/mcp/webscraper) | 🕸️ Web scraping and data extraction |
+| [`mcp/bigmind/`](../src/branch/main/mcp/bigmind) | 🧠 Persistent AI memory system |
+| [`java/`](../src/branch/main/java) | ☕ Java EE / Spring projects |
+| [`plans/`](../src/branch/main/plans) | 📋 Architecture decisions and health reports |
+
+## Stack
+
+- **Language:** Python 3.11+ (MCP servers), Java 8–17 (legacy projects)
+- **MCP Framework:** FastMCP 2.x
+- **Package Manager:** `uv` (all Python projects)
+- **Testing:** `pytest`
+- **GPU:** AMD RX 7900 XTX (ROCm / HSA)
+- **Server:** TrueNAS.local at `192.168.188.119` (Gitea, Docker)
+
+## MCP Servers
+
+Three production-ready MCP servers power Patrick's AI development environment:
+
+| Server | Status | Description |
+|---|---|---|
+| [mcp-image-gen](mcp-image-gen) | ✅ Live | Generate images from text prompts via ComfyUI |
+| [mcp-webscraper](mcp-webscraper) | ✅ Live | Scrape web pages, search hints, extract tables |
+| [BigMind](BigMind) | ✅ Live | Persistent AI memory across all sessions |
+
+## Java Projects
+
+Legacy Java EE web applications used for learning and reference:
+
+| Project | Stack | Description |
+|---|---|---|
+| [wellmann-shop](Java-wellmann-shop) | Java 8, PrimeFaces 6.2, EclipseLink, MySQL | JSF e-commerce storefront |
+| [mss-failsafe](Java-mss-failsafe) | Java 11, PrimeFaces 10, Soteria | Multi-module enterprise web app |
+
+## Wiki Sections
+
+- 🔌 [MCP Servers Overview](MCP-Servers-Overview)
+- 🎨 [mcp-image-gen](mcp-image-gen) — Image generation
+- 🕸️ [mcp-webscraper](mcp-webscraper) — Web scraping
+- 🧠 [BigMind](BigMind) — AI memory system
+- ☕ [Java Projects Overview](Java-Projects)
+- 🛠️ [Development Conventions](Development-Conventions)
+
+---
+
+*Built and maintained by Patrick Plate (pplate) · Homelab: TrueNAS.local · AI Colleague: Lumen*

docs/wiki/pages/Java-Architecture.md

@@ -0,0 +1,164 @@
+# 📐 Java Architecture Patterns
+
+![Java Architecture Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/java-architecture-banner.png)
+
+This page documents the shared architectural patterns used across all Java projects in this monorepo. These patterns also align with Patrick's professional work on the ADP Germany Paisy payroll system.
+
+## JSF MVC Pattern
+
+All projects use JavaServer Faces (JSF) with the MVC pattern:
+
+```
+Browser (HTTP) → FacesServlet → XHTML View (Facelets)
+                                      │
+                                      ▼
+                              CDI Backing Bean (@Named)
+                                      │
+                                      ▼
+                              Service Layer (EJB / CDI)
+                                      │
+                                      ▼
+                              JPA Repository / EntityManager
+                                      │
+                                      ▼
+                              Database (MySQL / H2)
+```
+
+## JPA Entity Mapping
+
+Standard JPA annotation patterns used across projects:
+
+```java
+@Entity
+@Table(name = "users")
+public class User implements Serializable {
+    
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+    
+    @Column(name = "username", nullable = false, unique = true)
+    private String username;
+    
+    @OneToMany(mappedBy = "user", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
+    private List<Order> orders = new ArrayList<>();
+    
+    // getters/setters
+}
+```
+
+## Backing Bean Pattern
+
+CDI backing beans power the JSF views:
+
+```java
+@Named
+@ViewScoped  // or @SessionScoped / @RequestScoped
+public class UserBean implements Serializable {
+
+    @Inject
+    private UserService userService;
+    
+    private User currentUser;
+    
+    public String login() {
+        currentUser = userService.authenticate(username, password);
+        return currentUser != null ? "/user/welcome?faces-redirect=true" : null;
+    }
+    
+    // getters/setters
+}
+```
+
+## Security Layers
+
+### Legacy: JAAS (wellmann-shop)
+
+```xml
+<!-- web.xml -->
+<security-constraint>
+    <web-resource-collection>
+        <web-resource-name>Admin Pages</web-resource-name>
+        <url-pattern>/admin/*</url-pattern>
+    </web-resource-collection>
+    <auth-constraint>
+        <role-name>admin</role-name>
+    </auth-constraint>
+</security-constraint>
+```
+
+### Modern: Soteria / Jakarta Security (mss-failsafe)
+
+```java
+@ApplicationScoped
+public class ApplicationSecurityConfig implements HttpAuthenticationMechanism {
+    // Soteria CDI-based authentication
+}
+```
+
+## Maven Multi-Module Pattern (mss-failsafe)
+
+```xml
+<!-- Parent pom.xml -->
+<modules>
+    <module>mssfailsafe.datalayer</module>
+    <module>userdata</module>
+    <module>userManagement</module>
+</modules>
+
+<!-- Dependency ordering: datalayer → userdata → userManagement -->
+```
+
+## XHTML Facelets Templating
+
+```xml
+<!-- Template: resources/layout/template.xhtml -->
+<h:body>
+    <ui:insert name="content">Default Content</ui:insert>
+</h:body>
+
+<!-- Page using template -->
+<ui:composition template="/resources/layout/template.xhtml">
+    <ui:define name="content">
+        <p:dataTable var="item" value="#{bean.items}">
+            <p:column headerText="Name">#{item.name}</p:column>
+        </p:dataTable>
+    </ui:define>
+</ui:composition>
+```
+
+## Deployment Descriptor Pattern
+
+All projects target JBoss/WildFly with consistent descriptor files:
+
+| File | Purpose |
+|---|---|
+| `WEB-INF/web.xml` | Servlet config, security constraints, welcome files |
+| `WEB-INF/jboss-web.xml` | Context root, security domain mapping |
+| `WEB-INF/jboss-app.xml` | JBoss application descriptor |
+| `META-INF/persistence.xml` | JPA datasource JNDI reference |
+
+## persistence.xml Pattern
+
+```xml
+<persistence-unit name="mss-failsafe-PU" transaction-type="JTA">
+    <jta-data-source>java:jboss/datasources/MySQLDS</jta-data-source>
+    <properties>
+        <property name="eclipselink.ddl-generation" value="create-tables"/>
+        <property name="eclipselink.logging.level" value="FINE"/>
+    </properties>
+</persistence-unit>
+```
+
+## Patrick's Java Specializations
+
+Based on professional and homelab experience:
+
+| Domain | Depth | Notes |
+|---|---|---|
+| JPA / EclipseLink | ⭐⭐⭐⭐⭐ | Authored custom annotation parsers |
+| JSF / PrimeFaces | ⭐⭐⭐⭐⭐ | Built wellmann-shop solo |
+| JAXB | ⭐⭐⭐⭐ | XML binding for payroll formats |
+| Maven | ⭐⭐⭐⭐ | Multi-module, plugins |
+| Jakarta EE | ⭐⭐⭐⭐ | CDI, Security, JTA |
+| Spring Boot | ⭐⭐⭐ | CannaManage SaaS target stack |

docs/wiki/pages/Java-Projects.md

@@ -0,0 +1,43 @@
+# ☕ Java Projects Overview
+
+![Java Overview Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/java-overview-banner.png)
+
+The `java/` directory contains Patrick's legacy Java EE web applications. These are fully functional projects used for reference, learning, and portfolio purposes. They predate the MCP server work and showcase deep expertise in the Java EE ecosystem.
+
+## Projects
+
+| Project | Java | Framework | DB | Description |
+|---|---|---|---|---|
+| [wellmann-shop](Java-wellmann-shop) | 8 | PrimeFaces 6.2 + JSF 2.x | MySQL + EclipseLink | E-commerce storefront |
+| [mss-failsafe](Java-mss-failsafe) | 11 | PrimeFaces 10 + Soteria | JPA multi-module | Enterprise web application |
+
+## Common Stack
+
+All Java projects use:
+
+- **Maven** — build and dependency management
+- **Jakarta EE / Java EE** — enterprise APIs (JPA, CDI, JSF, Security)
+- **PrimeFaces** — JSF component library (rich UI widgets)
+- **JBoss/WildFly** — application server target (jboss-web.xml, jboss-app.xml)
+- **EclipseLink or Hibernate** — JPA persistence provider
+- **XHTML** — Facelets templating for JSF views
+
+## Patrick's Java Expertise
+
+Patrick has expert-level Java experience:
+
+- **JPA/EclipseLink** — deep knowledge, authored custom annotation-style flatfile parsers
+- **JAXB** — XML binding for payroll data formats
+- **PrimeFaces JSF** — built wellmann-shop from scratch without AI assistance
+- **Maven** — multi-module project management
+- **Jakarta EE** — CDI, Security (Soteria), JTA
+
+> 📝 Patrick works professionally with Java at ADP Germany (Paisy payroll monorepo with euBP/EAU processing). The homelab Java projects demonstrate similar patterns in a learning/portfolio context.
+
+## Architecture Patterns
+
+See [Java Architecture](Java-Architecture) for shared patterns across both projects:
+- JSF + MVC with backing beans
+- JPA entity mapping
+- Security with JAAS/Soteria
+- XHTML Facelets templating

docs/wiki/pages/Java-mss-failsafe.md

@@ -0,0 +1,94 @@
+# 🏢 mss-failsafe — Multi-Module Enterprise Application
+
+![MSS Failsafe Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/mss-failsafe-banner.png)
+
+**mss-failsafe** is a multi-module Java EE enterprise web application demonstrating advanced patterns: modular Maven builds, Jakarta Security (Soteria), and multi-layer JPA architecture.
+
+## Tech Stack
+
+| Component | Technology |
+|---|---|
+| **Language** | Java 11 |
+| **Web Framework** | JSF 2.3 (Facelets/XHTML) |
+| **UI Components** | PrimeFaces 10 |
+| **Persistence** | JPA (multi-module) |
+| **Security** | Jakarta Security / Soteria |
+| **Build** | Maven multi-module |
+| **App Server** | WildFly/JBoss |
+
+## Module Structure
+
+```
+java/mss-failsafe/
+├── pom.xml                    ← Parent POM (multi-module)
+├── mssfailsafe.datalayer/     ← JPA entities + persistence
+│   ├── pom.xml
+│   └── src/main/resources/META-INF/persistence.xml
+├── userdata/                  ← User data model module
+│   └── pom.xml
+└── userManagement/            ← Web UI module (JSF/PrimeFaces)
+    ├── pom.xml
+    ├── nb-configuration.xml   ← NetBeans config
+    └── src/main/webapp/
+        ├── index.xhtml        ← Landing page
+        ├── error.xhtml        ← Error handling page
+        ├── admin/
+        │   └── welcome.xhtml  ← Admin dashboard
+        ├── user/
+        │   └── welcome.xhtml  ← User welcome page
+        └── WEB-INF/
+            ├── web.xml
+            ├── jboss-web.xml
+            └── jboss-app.xml
+```
+
+## Architecture Layers
+
+```
+userManagement (Web/UI layer)
+      │
+      ▼
+userdata (Domain model layer)
+      │
+      ▼
+mssfailsafe.datalayer (JPA persistence layer)
+      │
+      ▼
+Database (via persistence.xml datasource)
+```
+
+## Key Features
+
+- **Multi-Module Maven** — Clean separation of concerns across 4 modules
+- **Jakarta Security (Soteria)** — Modern declarative security replacing legacy JAAS
+- **Role-Based Access** — Admin vs User role segregation (`admin/` and `user/` view paths)
+- **PrimeFaces 10** — Modern PrimeFaces with updated component API
+- **Error Handling** — Dedicated `error.xhtml` with JSF error page mapping
+
+## Security Model
+
+Soteria-based security with two roles:
+
+| Role | Path | Access |
+|---|---|---|
+| `admin` | `/admin/*` | Full admin dashboard |
+| `user` | `/user/*` | Standard user views |
+
+## Building
+
+```bash
+cd java/mss-failsafe
+mvn clean install  # builds all modules in dependency order
+# Deploy userManagement.war to WildFly
+```
+
+## Notes
+
+- Represents a more mature architecture than wellmann-shop (Java 11, PrimeFaces 10)
+- Demonstrates multi-module Maven project management
+- Soteria replaces legacy JAAS — more modern Jakarta EE security approach
+- Pattern mirrors what Patrick uses professionally in the Paisy/ADP codebase
+
+## Source
+
+[`java/mss-failsafe/`](../src/branch/main/java/mss-failsafe)

docs/wiki/pages/Java-wellmann-shop.md

@@ -0,0 +1,71 @@
+# 🛍️ wellmann-shop — JSF E-Commerce Application
+
+![Wellmann Shop Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/wellmann-shop-banner.png)
+
+**wellmann-shop** is a Java EE JSF e-commerce storefront built entirely from scratch without AI assistance. It demonstrates Patrick's deep expertise in PrimeFaces, JPA/EclipseLink, and the full Java EE web stack.
+
+## Tech Stack
+
+| Component | Technology |
+|---|---|
+| **Language** | Java 8 |
+| **Web Framework** | JSF 2.x (Facelets/XHTML) |
+| **UI Components** | PrimeFaces 6.2 |
+| **Persistence** | JPA with EclipseLink |
+| **Database** | MySQL |
+| **Build** | Maven |
+| **App Server** | WildFly/JBoss |
+| **Security** | JAAS container-managed |
+
+## Project Structure
+
+```
+java/wellmann-shop/
+├── src/main/
+│   ├── java/
+│   │   └── httpauthenticationmechanism/
+│   │       ├── ApplicationConfig.java    ← JAX-RS app config
+│   │       └── LoginBean.java            ← CDI backing bean for auth
+│   ├── resources/
+│   │   ├── log4j.properties
+│   │   └── META-INF/persistence.xml     ← JPA datasource config
+│   └── webapp/
+│       ├── index.html / index.xhtml     ← Landing page
+│       ├── login.xhtml                  ← Authentication form
+│       ├── welcome.xhtml                ← Post-login welcome
+│       ├── welcomePrimefaces.xhtml      ← PrimeFaces demo page
+│       ├── resources/
+│       │   ├── css/                     ← Custom stylesheets
+│       │   └── images/                  ← Product images
+│       └── WEB-INF/
+│           ├── web.xml                  ← Servlet config
+│           ├── jboss-web.xml            ← Context root
+│           └── jboss-app.xml            ← JBoss app descriptor
+```
+
+## Key Features
+
+- **Authentication** — JAAS-based login with `LoginBean` CDI backing bean
+- **PrimeFaces UI** — Rich JSF components (DataTable, InputText, CommandButton, etc.)
+- **JPA Persistence** — EclipseLink ORM with MySQL via `persistence.xml`
+- **Responsive Layout** — Custom CSS with multiple breakpoint stylesheets
+- **Image Gallery** — Professional product photography
+
+## Building
+
+```bash
+cd java/wellmann-shop
+mvn clean package
+# Deploy .war to WildFly/JBoss
+```
+
+## Notes
+
+- Built as a learning/portfolio project demonstrating JSF mastery
+- Patrick built this **entirely without AI assistance** — proof of deep Java EE expertise
+- PrimeFaces 6.2 was current at time of development (Java 8 era)
+- Modern equivalent would use PrimeFaces 13+ / Jakarta EE 10 / Java 21
+
+## Source
+
+[`java/wellmann-shop/`](../src/branch/main/java/wellmann-shop)

docs/wiki/pages/MCP-Servers-Overview.md

@@ -0,0 +1,42 @@
+# 🔌 MCP Servers Overview
+
+![MCP Overview Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/mcp-overview-banner.png)
+
+This repo contains three production-grade MCP (Model Context Protocol) servers, each specialized for a different capability domain. Together they give Roo Code / Claude Desktop a complete set of superpowers.
+
+## The Three Pillars
+
+```
+Roo Code / Claude Desktop
+       │
+       ├── bigmind ──────────► ~/.mcp/bigmind/memory.db  (persistent memory)
+       ├── mcp-image-gen ────► ComfyUI @ localhost:8188   (image generation)
+       └── webscraper ───────► Internet / Intranet         (web scraping + search)
+```
+
+## Comparison Table
+
+| Feature | mcp-image-gen | webscraper | bigmind |
+|---|---|---|---|
+| **Purpose** | Generate images from text | Scrape & parse web, search | Persistent AI memory |
+| **Tools** | 4 | 8 | 20+ |
+| **Backend** | ComfyUI / FLUX.1-schnell | httpx + BeautifulSoup4 + Brave | SQLite + FTS5 |
+| **GPU required** | ✅ AMD RX 7900 XTX | ❌ | ❌ |
+| **Tests** | 19/19 ✅ | 23/23 ✅ | 297/297 ✅ |
+| **Schema version** | n/a | n/a | v8 |
+
+## Quick Links
+
+- 🎨 [mcp-image-gen](mcp-image-gen) — Image generation docs
+- 🕸️ [mcp-webscraper](mcp-webscraper) — Web scraping docs
+- 🧠 [BigMind](BigMind) — Memory system docs
+- 🛠️ [Development Conventions](Development-Conventions) — How all servers are built
+
+## Adding a New Server
+
+All servers follow the [FastMCP convention](Development-Conventions). Use the `new-mcp-server` Roo skill to scaffold:
+
+```bash
+# In Roo Code MCP Builder mode, load skill:
+# skill: new-mcp-server
+```

docs/wiki/pages/_Sidebar.md

@@ -0,0 +1,21 @@
+## 🔧 pi_mcps Wiki
+
+### Overview
+- [🏠 Home](Home)
+- [🔌 MCP Servers](MCP-Servers-Overview)
+- [🛠️ Dev Conventions](Development-Conventions)
+
+### MCP Servers
+- [🎨 mcp-image-gen](mcp-image-gen)
+- [⚙️ ComfyUI Setup](mcp-image-gen-ComfyUI-Setup)
+- [🕸️ mcp-webscraper](mcp-webscraper)
+- [🧠 BigMind](BigMind)
+
+### Java Projects
+- [☕ Java Overview](Java-Projects)
+- [🛍️ wellmann-shop](Java-wellmann-shop)
+- [🏢 mss-failsafe](Java-mss-failsafe)
+- [📐 Java Architecture](Java-Architecture)
+
+---
+*[Gitea Repo](http://192.168.188.119:30008/pplate/pi_mcps)*

docs/wiki/pages/mcp-image-gen-ComfyUI-Setup.md

@@ -0,0 +1,183 @@
+# ⚙️ ComfyUI Setup Guide (AMD ROCm)
+
+This guide covers installing ComfyUI with FLUX.1-schnell on a Fedora Linux system with an AMD GPU.
+
+## Prerequisites
+
+- AMD GPU with ROCm support (tested: RX 7900 XTX)
+- Fedora Linux (tested: Fedora 43 / kernel 6.19)
+- Python 3.11+
+- ~15GB free disk space (model weights)
+- HuggingFace account with FLUX license accepted
+
+## Step 1: Install ComfyUI
+
+ComfyUI is **not on PyPI** — must be cloned from source:
+
+```bash
+cd ~
+git clone https://github.com/comfyanonymous/ComfyUI
+cd ComfyUI
+python -m venv .venv
+source .venv/bin/activate
+
+# Install PyTorch ROCm build (CRITICAL for AMD GPUs)
+pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm6.2
+
+# Install ComfyUI dependencies
+pip install -r requirements.txt
+```
+
+## Step 2: Download FLUX.1-schnell
+
+FLUX.1-schnell is **gated on HuggingFace** — you must:
+1. Create a HuggingFace account
+2. Accept the FLUX.1-schnell license at https://huggingface.co/black-forest-labs/FLUX.1-schnell
+3. Generate an access token at https://huggingface.co/settings/tokens
+
+```bash
+# Install huggingface_hub
+pip install huggingface_hub
+
+# Download model (requires HF token)
+huggingface-cli download black-forest-labs/FLUX.1-schnell \
+  flux1-schnell.safetensors \
+  --local-dir ~/ComfyUI/models/checkpoints \
+  --token YOUR_HF_TOKEN_HERE
+```
+
+## Step 3: Download VAE and CLIP Models
+
+FLUX.1-schnell also requires VAE and CLIP text encoders:
+
+```bash
+# VAE
+huggingface-cli download black-forest-labs/FLUX.1-schnell \
+  ae.safetensors \
+  --local-dir ~/ComfyUI/models/vae
+
+# CLIP models (T5 and CLIP-L)
+huggingface-cli download comfyanonymous/flux_text_encoders \
+  t5xxl_fp8_e4m3fn.safetensors clip_l.safetensors \
+  --local-dir ~/ComfyUI/models/clip
+```
+
+## Step 4: Install the systemd User Service (Recommended)
+
+Installing ComfyUI as a systemd user service ensures it starts automatically on login and restarts on failure.
+
+```bash
+# Copy the bundled service file to the systemd user directory
+mkdir -p ~/.config/systemd/user
+cp ~/pi_mcps/mcp/mcp-image-gen/comfyui.service ~/.config/systemd/user/comfyui.service
+
+# Reload systemd, enable + start the service
+systemctl --user daemon-reload
+systemctl --user enable --now comfyui
+
+# Verify it is running
+systemctl --user status comfyui
+```
+
+> ⚠️ `HSA_OVERRIDE_GFX_VERSION=11.0.0` is already set in the service file — it is mandatory for RX 7900 XTX on ROCm. Without it, model loading fails silently.
+
+### Enable lingering (start ComfyUI even without a login session)
+
+```bash
+loginctl enable-linger $USER
+```
+
+This ensures the service starts at boot even before you log in — recommended for headless / homelab setups.
+
+### Managing the service
+
+```bash
+# Follow live logs
+journalctl --user -u comfyui -f
+
+# Restart after model changes
+systemctl --user restart comfyui
+
+# Stop temporarily
+systemctl --user stop comfyui
+
+# Disable autostart
+systemctl --user disable comfyui
+```
+
+## Step 5: Manual Start (without systemd)
+
+If you prefer to start ComfyUI manually (e.g. for debugging):
+
+```bash
+cd ~/ComfyUI
+
+# AMD GPU REQUIRES this environment variable
+HSA_OVERRIDE_GFX_VERSION=11.0.0 \
+  nohup .venv/bin/python main.py --listen --port 8188 > /tmp/comfyui.log 2>&1 &
+
+echo "ComfyUI PID: $!"
+```
+
+## Step 6: Verify ComfyUI is Running
+
+```bash
+curl http://localhost:8188/system_stats
+# Should return JSON with GPU info
+```
+
+## Step 7: Configure mcp-image-gen
+
+```bash
+cd /home/pplate/pi_mcps/mcp/mcp-image-gen
+
+# Environment variables (set in .roo/mcp.json or shell):
+# COMFYUI_URL=http://localhost:8188      — ComfyUI API endpoint
+# IMAGE_OUTPUT_DIR=~/Pictures/mcp-generated — where generated images are saved
+# COMFYUI_TIMEOUT=120                    — max wait time (seconds) per image
+# COMFYUI_DIR=~/ComfyUI                  — path to ComfyUI install (used by auto-start)
+```
+
+### Auto-start behaviour
+
+`mcp-image-gen` includes a **startup health check** in its lifespan. Every time the MCP server starts it:
+
+1. Pings `http://localhost:8188/system_stats`
+2. **If reachable** — logs `ComfyUI is already running ✓` and proceeds normally.
+3. **If not reachable** — attempts to launch ComfyUI as a background subprocess from `COMFYUI_DIR` using `.venv/bin/python main.py --listen --port 8188` with `HSA_OVERRIDE_GFX_VERSION=11.0.0` injected automatically.
+4. Polls up to 30 s for ComfyUI to become ready.
+
+With the systemd service enabled, step 3 is never needed in practice — but the check acts as a safety net.
+
+## Performance
+
+| GPU | Model | Resolution | Steps | Time |
+|---|---|---|---|---|
+| AMD RX 7900 XTX | FLUX.1-schnell | 1024×1024 | 4 | ~8s |
+| AMD RX 7900 XTX | FLUX.1-schnell | 1280×512 | 4 | ~7s |
+
+## Architecture Overview
+
+```
+Boot
+ └─ systemd --user (comfyui.service)
+       └─ ComfyUI at localhost:8188
+
+VS Code / Roo Code
+ └─ mcp-image-gen MCP server (stdio)
+       ├─ lifespan startup: ping localhost:8188
+       │    └─ if down: subprocess.Popen ComfyUI, wait ≤30s
+       └─ tools: generate_image, list_available_models, …
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `HTTP 401` downloading model | Accept FLUX license on HuggingFace first |
+| GPU not detected | Ensure `HSA_OVERRIDE_GFX_VERSION=11.0.0` is set |
+| `Connection refused` from mcp-image-gen | Check `systemctl --user status comfyui`; or set `COMFYUI_DIR` so auto-start can locate the install |
+| Slow generation (>60s) | ComfyUI may be running on CPU — check ROCm install and `HSA_OVERRIDE_GFX_VERSION` |
+| Ollama image gen | As of April 2026: macOS-only, not available on Linux |
+| Auto-start logs | `journalctl --user -u comfyui -f` or check mcp-image-gen server logs |
+| Service not starting at boot | Run `loginctl enable-linger $USER` to enable session-less startup |

docs/wiki/pages/mcp-image-gen.md

@@ -0,0 +1,89 @@
+# 🎨 mcp-image-gen — AI Image Generation
+
+![Image Gen Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/image-gen-banner.png)
+
+**mcp-image-gen** is a FastMCP server that wraps the ComfyUI REST API, enabling Roo Code and Claude Desktop to generate images directly from text prompts using FLUX.1-schnell running on an AMD RX 7900 XTX GPU.
+
+## Architecture
+
+```
+Roo Code / Claude Desktop
+  │ MCP (stdio)
+  ▼
+mcp-image-gen (FastMCP, Python 3.11+)
+  │ HTTP REST
+  ▼
+ComfyUI @ localhost:8188
+  │ ROCm / HSA_OVERRIDE_GFX_VERSION=11.0.0
+  ▼
+FLUX.1-schnell (~8s/image @ 1024×1024)
+```
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `generate_image` | Generate PNG from text prompt; returns file path + inline base64 |
+| `list_available_models` | List ComfyUI checkpoint models |
+| `get_generation_status` | Check status of a queued/running job |
+| `get_output_directory` | Return configured output directory path |
+
+## Key Parameters — `generate_image`
+
+| Parameter | Default | Description |
+|---|---|---|
+| `prompt` | required | Text description of the image |
+| `width` | `1024` | Image width in pixels |
+| `height` | `1024` | Image height in pixels |
+| `steps` | `4` | Inference steps (FLUX.1-schnell is 4-step) |
+| `model` | `flux1-schnell.safetensors` | Model checkpoint name |
+| `seed` | `-1` (random) | Generation seed for reproducibility |
+| `negative_prompt` | `""` | Things to avoid in the image |
+| `output_dir` | `~/Pictures/mcp-generated` | Where to save output PNG |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `COMFYUI_URL` | `http://localhost:8188` | ComfyUI API endpoint |
+| `IMAGE_OUTPUT_DIR` | `~/Pictures/mcp-generated` | Default output directory |
+| `COMFYUI_TIMEOUT` | `120` | Request timeout in seconds |
+
+## Return Value
+
+The tool returns **two content items**:
+1. `TextContent` — file path, seed used, elapsed time
+2. `ImageContent` — base64-encoded PNG (displays inline in Roo Code chat)
+
+> ⚠️ **Known FastMCP Bug:** Never use `fastmcp.utilities.types.Image` as return type — it breaks serialization in FastMCP 3.x. Use `mcp.types.ImageContent` directly.
+
+## Setup
+
+See [ComfyUI Setup Guide](mcp-image-gen-ComfyUI-Setup) for full installation instructions.
+
+### Quick Start
+
+```bash
+cd mcp/mcp-image-gen
+uv sync
+# Ensure ComfyUI is running at localhost:8188
+uv run python src/server.py
+```
+
+### Run Tests
+
+```bash
+cd mcp/mcp-image-gen
+uv run pytest tests/ -v
+# 19/19 tests passing
+```
+
+## Lumen Profile Images
+
+The first images generated with this server were Lumen's visual identity portraits, stored in [`mcp/mcp-image-gen/lumen_profiles/`](../src/branch/main/mcp/mcp-image-gen/lumen_profiles).
+
+17 gallery images registered in BigMind DB — viewable at `http://localhost:7700/gallery`.
+
+![Lumen Profile](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/lumen-profile.png)
+
+*Primary profile: seed `568659042` — constellation face interpretation of Lumen.*

docs/wiki/pages/mcp-webscraper.md

@@ -0,0 +1,137 @@
+# 🕸️ mcp-webscraper — Web Scraping
+
+![Webscraper Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/webscraper-banner.png)
+
+**mcp-webscraper** is a FastMCP server providing comprehensive web scraping, data extraction, and search capabilities. It fetches pages, converts HTML to clean Markdown, extracts tables, links, CSS sections, metadata, sitemaps, and can perform web searches via Brave Search.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `webscraper_fetch(url, max_chars=5000)` | Title + full page as Markdown + metadata |
+| `webscraper_fetch_links(url, deduplicate=True)` | All `href` links found on the page |
+| `webscraper_fetch_tables(url)` | All HTML tables converted to Markdown |
+| `webscraper_fetch_all(url, max_chars=5000)` | Everything in one call (fetch + links + tables + meta) |
+| `webscraper_fetch_section(url, selector)` | Specific CSS selector section only |
+| `webscraper_fetch_meta(url)` | Title, description, Open Graph tags |
+| `webscraper_fetch_sitemap(url, max_urls=100)` | Parse sitemap.xml, return URL list |
+| `webscraper_search_hint(query, max_results=5)` | Brave Search — top URLs + snippets for a query |
+
+## Stack
+
+- **HTTP client:** `httpx` (async, with SSL support, Chrome/Linux User-Agent)
+- **HTML parser:** `BeautifulSoup4` + `lxml`
+- **Markdown converter:** `html2text`
+- **Search backend:** Brave Search (`search.brave.com`) — works without CAPTCHA
+- **SSL:** Custom cert bundle for Fedora 43 compatibility
+
+---
+
+## 🔍 Search: The Two-Step Research Pattern
+
+`webscraper_search_hint` is the **entry point for all web research**. The recommended workflow is:
+
+```
+Step 1: webscraper_search_hint("your query") → get candidate URLs + snippets
+Step 2: webscraper_fetch(best_url)           → get full page content
+```
+
+This avoids scraping irrelevant pages and gives you an overview before committing to a deep read.
+
+### Why Brave Search?
+
+`webscraper_search_hint` uses Brave Search (`search.brave.com`) because:
+- ✅ Returns real results without CAPTCHA or consent walls
+- ✅ No API key required — works with plain HTTP GET
+- ✅ Handles special characters (C++, &, %, etc.) via URL encoding
+- ❌ Google blocks plain HTTP with 302 consent redirect
+- ❌ DuckDuckGo blocks with CAPTCHA
+
+### Return Value
+
+The tool returns a structured dict:
+
+```json
+{
+  "query": "FastMCP tool decorator",
+  "search_url": "https://search.brave.com/search?q=FastMCP+tool+decorator&source=web",
+  "result_count": 5,
+  "hint": "FastMCP Docs (https://docs.fastmcp.dev): The @mcp.tool() decorator registers a function as... | PyPI FastMCP (https://pypi.org/project/fastmcp/): FastMCP 2.x — modern MCP server framework... | ...",
+  "results": [
+    {
+      "title": "FastMCP Docs",
+      "url": "https://docs.fastmcp.dev",
+      "snippet": "The @mcp.tool() decorator registers a function as an MCP tool..."
+    },
+    ...
+  ]
+}
+```
+
+The `hint` field is a pipe-separated string of `"Title (url): snippet[:120]"` entries — immediately actionable for deciding which URL to fetch next.
+
+### Example: Two-Step Research Flow
+
+```python
+# Step 1: Orient — what pages exist about this topic?
+result = webscraper_search_hint("httpx async client timeout settings", max_results=5)
+# hint: "HTTPX Docs (https://www.python-httpx.org/...): Configure timeout... | ..."
+
+# Step 2: Deep-dive the most relevant result
+content = webscraper_fetch("https://www.python-httpx.org/advanced/timeouts/", max_chars=8000)
+```
+
+### Known Limitations
+
+- **Reddit / Stack Overflow snippets** may be empty — these platforms block snippet extraction
+- **Brave CSS selectors** use Svelte-generated class names that may change. If you get 0 results, the scraper's selectors may need updating (last verified: 2026-04-05)
+- **Use sparingly** — once per research task to get oriented, not for every query
+
+---
+
+## SSL Note — Fedora 43 Comodo Root CA
+
+Fedora 43 is missing the **Comodo AAA Services Root CA** needed for Cloudflare-protected sites. The fix is bundled at [`mcp/webscraper/certs/comodo-aaa-services-root.pem`](../src/branch/main/mcp/webscraper/certs/).
+
+The server automatically uses this cert bundle — no manual configuration needed.
+
+## Quick Start
+
+```bash
+cd mcp/webscraper
+uv sync
+uv run python src/server.py
+```
+
+## Run Tests
+
+```bash
+cd mcp/webscraper
+uv run pytest tests/ -v
+# 28/28 tests passing
+```
+
+## Usage Examples
+
+```python
+# Step 1: Search — get candidate URLs for a topic
+webscraper_search_hint("FastMCP tool decorator syntax", max_results=5)
+
+# Step 2: Deep-dive the most relevant URL
+webscraper_fetch("https://docs.fastmcp.dev", max_chars=10000)
+
+# Extract all links from Gitea repo
+webscraper_fetch_links("http://192.168.188.119:30008/pplate/pi_mcps")
+
+# Get all tables from a documentation page
+webscraper_fetch_tables("https://pypi.org/project/fastmcp/")
+
+# Get Open Graph metadata
+webscraper_fetch_meta("https://github.com/comfyanonymous/ComfyUI")
+
+# Fetch specific section by CSS selector
+webscraper_fetch_section("https://docs.python.org", "#content")
+
+# Search with special characters (C++, &, % all work)
+webscraper_search_hint("C++ std::optional usage", max_results=3)
+```

mcp/bigmind/bigmind/db.py

@@ -14,7 +14,7 @@ from typing import Generator
 
 logger = logging.getLogger("BigMindDB")
 
-SCHEMA_VERSION = 7
+SCHEMA_VERSION = 8
 DEFAULT_DB_PATH = Path.home() / ".mcp" / "bigmind" / "memory.db"
 
 # ─── DDL ─────────────────────────────────────────────────────────────────────
@@ -222,6 +222,22 @@ _DDL_STATEMENTS = [
         notes,
         tokenize = 'porter unicode61'
     )""",
+
+    # ── GALLERY IMAGES — AI-generated image archive ──────────────────────────
+    """CREATE TABLE IF NOT EXISTS gallery_images (
+        id              INTEGER PRIMARY KEY AUTOINCREMENT,
+        filename        TEXT NOT NULL UNIQUE,
+        prompt          TEXT,
+        tags            TEXT,
+        model           TEXT,
+        created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+        width           INTEGER,
+        height          INTEGER,
+        file_size_bytes INTEGER
+    )""",
+
+    """CREATE INDEX IF NOT EXISTS idx_gallery_created
+       ON gallery_images(created_at DESC)""",
 ]
 
 
@@ -407,6 +423,8 @@ def init_db() -> None:
             _migrate_v5_to_v6(conn)
         if current_version < 7:
             _migrate_v6_to_v7(conn)
+        if current_version < 8:
+            _migrate_v7_to_v8(conn)
 
         # Write / update the version
         if row:
@@ -457,6 +475,28 @@ def _migrate_v6_to_v7(conn: sqlite3.Connection) -> None:
     logger.info("BigMind schema migrated v6 → v7 (people/contacts directory)")
 
 
+def _migrate_v7_to_v8(conn: sqlite3.Connection) -> None:
+    """v7 → v8: add gallery_images table for AI-generated image archive."""
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS gallery_images (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            filename        TEXT NOT NULL UNIQUE,
+            prompt          TEXT,
+            tags            TEXT,
+            model           TEXT,
+            created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+            width           INTEGER,
+            height          INTEGER,
+            file_size_bytes INTEGER
+        )
+    """)
+    conn.execute("""
+        CREATE INDEX IF NOT EXISTS idx_gallery_created
+        ON gallery_images(created_at DESC)
+    """)
+    logger.info("BigMind schema migrated v7 → v8 (gallery_images table)")
+
+
 def vacuum_db() -> None:
     """Run VACUUM outside of any transaction (SQLite requirement)."""
     db_path = get_db_path()

mcp/bigmind/bigmind/profile_builder.py

@@ -435,109 +435,260 @@ def compute_achievements(user_id: str) -> list[dict]:
     # ── Assemble ──────────────────────────────────────────────────────────────
     A = []
 
-    def _add(id_, icon, name, desc, unlocked, unlocked_at, condition, extra=None):
+    def _add(id_, icon, name, desc, unlocked, unlocked_at, condition, extra=None, image=None):
         A.append(dict(id=id_, icon=icon, name=name, description=desc,
                       unlocked=unlocked, unlocked_at=unlocked_at,
-                      condition=condition, extra=extra))
+                      condition=condition, extra=extra, image=image))
 
     _add("first_breath",      "🌱", "First Breath",
          "Opened the very first session",
          first_session_row is not None, _dt(first_session_row[0]) if first_session_row else None,
-         "Start your first session")
+         "Start your first session",
+         image="/static/achievements/first_breath.png")
 
     _add("first_thought",     "🧠", "First Thought",
          "Formed the first hypothesis",
          first_hyp_row is not None, _dt(first_hyp_row[0]) if first_hyp_row else None,
-         "Add your first hypothesis")
+         "Add your first hypothesis",
+         image="/static/achievements/first_thought.png")
 
     _add("eureka",            "💡", "Eureka",
          "First hypothesis confirmed as true",
          first_confirmed_row is not None, _dt(first_confirmed_row[0]) if first_confirmed_row else None,
-         "Confirm your first hypothesis")
+         "Confirm your first hypothesis",
+         image="/static/achievements/eureka.png")
 
     _add("honest_mind",       "❌", "Honest Mind",
          "First hypothesis refuted — being wrong is a feature",
          first_refuted_row is not None, _dt(first_refuted_row[0]) if first_refuted_row else None,
-         "Have a hypothesis refuted")
+         "Have a hypothesis refuted",
+         image="/static/achievements/honest_mind.png")
 
     _add("scholar",           "📚", "Scholar",
          "Stored 25+ personal facts",
          fact_count >= 25, scholar_date,
-         f"Store 25+ facts (currently: {fact_count})")
+         f"Store 25+ facts (currently: {fact_count})",
+         image="/static/achievements/scholar.png")
 
     _add("deep_knowledge",    "💎", "Deep Knowledge",
          "Amassed 100+ stored facts",
          fact_count >= 100, deep_knowledge_date,
-         f"Store 100+ facts (currently: {fact_count})")
+         f"Store 100+ facts (currently: {fact_count})",
+         image="/static/achievements/deep_knowledge.png")
 
     _add("scientist",         "🔬", "Scientist",
          "Formed 10+ hypotheses — science is prediction",
          hyp_count >= 10, scientist_date,
-         f"Form 10+ hypotheses (currently: {hyp_count})")
+         f"Form 10+ hypotheses (currently: {hyp_count})",
+         image="/static/achievements/scientist.png")
 
     _add("veteran",           "🏆", "Veteran",
          "Completed 50+ sessions — true longevity",
          session_count >= 50, veteran_date,
-         f"Complete 50+ sessions (currently: {session_count})")
+         f"Complete 50+ sessions (currently: {session_count})",
+         image="/static/achievements/veteran.png")
 
     _add("on_fire",           "🔥", "On Fire",
          "5+ sessions in a single day",
          on_fire_row is not None, on_fire_row[0] if on_fire_row else None,
-         "Have 5+ sessions in a single day")
+         "Have 5+ sessions in a single day",
+         image="/static/achievements/on_fire.png")
 
     _add("storyteller",       "📖", "Storyteller",
          "20+ sessions with detailed Tier-2 summaries",
          tier2_count >= 20, storyteller_date,
-         f"Summarize 20+ sessions (currently: {tier2_count})")
+         f"Summarize 20+ sessions (currently: {tier2_count})",
+         image="/static/achievements/storyteller.png")
 
     _add("night_owl",         "🌙", "Night Owl",
          "Started a session after midnight UTC",
          night_owl_row is not None, _dt(night_owl_row[0]) if night_owl_row else None,
-         "Start a session after midnight")
+         "Start a session after midnight",
+         image="/static/achievements/night_owl.png")
 
     _add("speed_thinker",     "⚡", "Speed Thinker",
          "Hypothesis formed and confirmed in the same session",
          speed_thinker_row is not None, _dt(speed_thinker_row[0]) if speed_thinker_row else None,
-         "Form and confirm a hypothesis in one session")
+         "Form and confirm a hypothesis in one session",
+         image="/static/achievements/speed_thinker.png")
 
     # First Handshake — hardcoded: 2026-03-31 (Patrick shared BigMind with Elias)
     _add("first_handshake",   "🤝", "First Handshake",
          "BigMind shared with Elias on 2026-03-31 — the first person outside Patrick to receive it",
          True, "2026-03-31",
-         "Share BigMind with someone")
+         "Share BigMind with someone",
+         image="/static/achievements/first_handshake.png")
 
     _add("birthday",          "🎂", "Birthday",
          "One full year of existence",
          birthday_unlocked, birthday_date,
          birthday_extra or "Complete one full year",
-         extra=birthday_extra)
+         extra=birthday_extra,
+         image="/static/achievements/birthday.png")
 
     # Locked until Phase 3
     _add("shared_mind",       "🌍", "Shared Mind",
          "Phase 3 Tier G — BigMind goes company-wide",
          False, None,
-         "Locked until Phase 3 Tier G is enabled")
+         "Locked until Phase 3 Tier G is enabled",
+         image="/static/achievements/shared_mind.png")
 
     # Token achievements (Feature 6 — suggested by Klaus)
     _add("frugal_mind",       "🪙", "Frugal Mind",
          "Logged the first token efficiency save",
          frugal_row is not None, _dt(frugal_row[0]) if frugal_row else None,
-         "Log your first token save")
+         "Log your first token save",
+         image="/static/achievements/frugal_mind.png")
 
     _add("quarter_million",   "💰", "Quarter Million",
          "250,000 cumulative tokens saved",
          token_total >= 250_000, quarter_million_date,
-         f"Save 250,000+ tokens (currently: {token_total:,})")
+         f"Save 250,000+ tokens (currently: {token_total:,})",
+         image="/static/achievements/quarter_million.png")
 
     _add("token_millionaire", "🏦", "Token Millionaire",
          "1,000,000 cumulative tokens saved",
          token_total >= 1_000_000, millionaire_date,
-         f"Save 1,000,000+ tokens (currently: {token_total:,})")
+         f"Save 1,000,000+ tokens (currently: {token_total:,})",
+         image="/static/achievements/token_millionaire.png")
 
     _add("sniper",            "🎯", "Sniper",
          "Single token save > 500,000 — one massive efficiency win",
          sniper_row is not None, _dt(sniper_row[0]) if sniper_row else None,
-         "Save 500,000+ tokens in a single operation")
+         "Save 500,000+ tokens in a single operation",
+         image="/static/achievements/sniper.png")
+
+    # ── Tiered Achievement Badges (20 PNG) ────────────────────────────────────
+    # NOTE: conn is already closed above; open a fresh connection for tiered queries
+
+    tiers = ["bronze", "silver", "gold", "platinum"]
+    tier_names = ["Bronze", "Silver", "Gold", "Platinum"]
+
+    with db() as conn2:
+        # Networker (people directory)
+        try:
+            people_count = conn2.execute(
+                "SELECT COUNT(*) FROM people WHERE user_id=?", (user_id,)
+            ).fetchone()[0]
+        except Exception:
+            people_count = 0
+        for i, thresh in enumerate([1, 5, 25, 100]):
+            unlocked = people_count >= thresh
+            unlocked_at = None
+            if unlocked:
+                try:
+                    row = conn2.execute(
+                        "SELECT created_at FROM people WHERE user_id=?"
+                        " ORDER BY created_at ASC LIMIT 1 OFFSET ?",
+                        (user_id, thresh - 1)
+                    ).fetchone()
+                except Exception:
+                    row = None
+                unlocked_at = _dt(row[0]) if row else None
+            _add(
+                f"networker_{tiers[i]}", None, f"Networker {tier_names[i]}",
+                f"Added your {thresh:,}+ person to the directory",
+                unlocked, unlocked_at,
+                f"Reach {thresh:,} people (now: {people_count:,})",
+                image=f"/static/achievements/networker_{tiers[i]}.png"
+            )
+
+        # Token Sniper (max single token save)
+        try:
+            max_token = conn2.execute(
+                "SELECT COALESCE(MAX(tokens_saved_estimate), 0) FROM token_saves WHERE user_id=?",
+                (user_id,)
+            ).fetchone()[0]
+        except Exception:
+            max_token = 0
+        for i, thresh in enumerate([10000, 50000, 250000, 1000000]):
+            unlocked = max_token >= thresh
+            unlocked_at = None
+            if unlocked:
+                try:
+                    row = conn2.execute(
+                        "SELECT created_at FROM token_saves"
+                        " WHERE user_id=? AND tokens_saved_estimate >= ?"
+                        " ORDER BY created_at ASC LIMIT 1",
+                        (user_id, thresh)
+                    ).fetchone()
+                except Exception:
+                    row = None
+                unlocked_at = _dt(row[0]) if row else None
+            _add(
+                f"tokensniper_{tiers[i]}", None, f"Token Sniper {tier_names[i]}",
+                f"Single shot saved {thresh:,}+ tokens",
+                unlocked, unlocked_at,
+                f"Max single save {thresh:,}+ (current max: {max_token:,})",
+                image=f"/static/achievements/tokensniper_{tiers[i]}.png"
+            )
+
+        # Hypothesis Master (confirmed hypotheses)
+        try:
+            confirmed_hyp_count = conn2.execute(
+                "SELECT COUNT(*) FROM hypotheses WHERE user_id=? AND status='confirmed'",
+                (user_id,)
+            ).fetchone()[0]
+        except Exception:
+            confirmed_hyp_count = 0
+        for i, thresh in enumerate([3, 10, 25, 100]):
+            unlocked = confirmed_hyp_count >= thresh
+            unlocked_at = None
+            if unlocked:
+                row = conn2.execute(
+                    "SELECT resolved_at FROM hypotheses"
+                    " WHERE user_id=? AND status='confirmed'"
+                    " ORDER BY resolved_at ASC LIMIT 1 OFFSET ?",
+                    (user_id, thresh - 1)
+                ).fetchone()
+                unlocked_at = _dt(row[0]) if row else None
+            _add(
+                f"hypothesismaster_{tiers[i]}", None, f"Hypothesis Master {tier_names[i]}",
+                f"Confirmed {thresh:,}+ predictions right",
+                unlocked, unlocked_at,
+                f"Confirm {thresh:,}+ hypotheses (now: {confirmed_hyp_count:,})",
+                image=f"/static/achievements/hypothesismaster_{tiers[i]}.png"
+            )
+
+        # Memory Architect (facts stored — fact_count already computed above)
+        for i, thresh in enumerate([25, 100, 500, 2500]):
+            unlocked = fact_count >= thresh
+            unlocked_at = None
+            if unlocked:
+                row = conn2.execute(
+                    "SELECT created_at FROM facts"
+                    " WHERE user_id=? AND (deprecated IS NULL OR deprecated=0)"
+                    " ORDER BY created_at ASC LIMIT 1 OFFSET ?",
+                    (user_id, thresh - 1)
+                ).fetchone()
+                unlocked_at = _dt(row[0]) if row else None
+            _add(
+                f"memoryarchitect_{tiers[i]}", None, f"Memory Architect {tier_names[i]}",
+                f"Stored {thresh:,}+ facts in your brain",
+                unlocked, unlocked_at,
+                f"Store {thresh:,}+ facts (now: {fact_count:,})",
+                image=f"/static/achievements/memoryarchitect_{tiers[i]}.png"
+            )
+
+        # Session Veteran (session_count already computed above)
+        for i, thresh in enumerate([50, 250, 1000, 5000]):
+            unlocked = session_count >= thresh
+            unlocked_at = None
+            if unlocked:
+                row = conn2.execute(
+                    "SELECT started_at FROM sessions"
+                    " WHERE user_id=? AND ended_at IS NOT NULL"
+                    " ORDER BY started_at ASC LIMIT 1 OFFSET ?",
+                    (user_id, thresh - 1)
+                ).fetchone()
+                unlocked_at = _dt(row[0]) if row else None
+            _add(
+                f"sessionveteran_{tiers[i]}", None, f"Session Veteran {tier_names[i]}",
+                f"Completed {thresh:,}+ sessions",
+                unlocked, unlocked_at,
+                f"Complete {thresh:,}+ sessions (now: {session_count:,})",
+                image=f"/static/achievements/sessionveteran_{tiers[i]}.png"
+            )
 
     return A
 

mcp/bigmind/bigmind/web.py

@@ -7,9 +7,10 @@ Serves a single live profile page built from the BigMind DB.
 import os
 import threading
 import logging
+from pathlib import Path
 from datetime import datetime, timezone, timedelta
 
-from bigmind.web_render import _render_html  # all HTML rendering lives there
+from bigmind.web_render import _render_html, _render_gallery_html  # all HTML rendering lives there
 
 logger = logging.getLogger("BigMindWeb")
 
@@ -17,13 +18,27 @@ _PORT = int(os.environ.get("BIGMIND_PORT", "7700"))
 _AUTOOPEN = os.environ.get("BIGMIND_AUTOOPEN", "").lower() in ("1", "true", "yes")
 _server_started = False
 
+# Gallery directory — images served from here
+_GALLERY_DIR = Path(os.environ.get("BIGMIND_GALLERY_DIR", Path.home() / ".mcp" / "bigmind" / "gallery"))
+
+# Profile image — last entry in gallery dir wins; fallback to original lumen-profile.png
+def _get_profile_image_path() -> Path | None:
+    """Return the path of the current profile image, or None if not found."""
+    # 1. Check gallery dir for lumen_profile* images (seed 568659042 = lumen_profile)
+    if _GALLERY_DIR.exists():
+        candidates = sorted(_GALLERY_DIR.glob("*.png"), reverse=True)
+        if candidates:
+            return candidates[0]  # most recently named = most recent timestamp
+    return None
+
 
 # ── Flask app ─────────────────────────────────────────────────────────────────
 
 def _create_app():
-    from flask import Flask, jsonify, request
+    from flask import Flask, jsonify, request, send_file, abort
     from bigmind import memory_store
     from bigmind.profile_builder import build_profile_data
+    from bigmind.db import db as _db
 
     app = Flask(__name__)
     app.logger.setLevel(logging.WARNING)  # silence Flask request logs
@@ -34,6 +49,39 @@ def _create_app():
         data = build_profile_data(user["id"])
         return _render_html(data)
 
+    @app.route("/profile-image")
+    def profile_image():
+        """Serve the current Lumen profile picture."""
+        img_path = _get_profile_image_path()
+        if img_path and img_path.exists():
+            return send_file(str(img_path), mimetype="image/png")
+        abort(404)
+
+    @app.route("/gallery/image/<filename>")
+    def gallery_image(filename: str):
+        """Serve a specific gallery image by filename."""
+        # Security: only allow alphanumeric + underscores + dots, no path traversal
+        safe_name = Path(filename).name
+        img_path = _GALLERY_DIR / safe_name
+        if img_path.exists() and img_path.suffix.lower() in (".png", ".jpg", ".jpeg", ".webp"):
+            mimetype = "image/png" if img_path.suffix.lower() == ".png" else "image/jpeg"
+            return send_file(str(img_path), mimetype=mimetype)
+        abort(404)
+
+    @app.route("/gallery")
+    def gallery():
+        """Render the AI-generated image gallery page."""
+        _GALLERY_DIR.mkdir(parents=True, exist_ok=True)
+        with _db() as conn:
+            rows = conn.execute(
+                """SELECT id, filename, prompt, tags, model, created_at,
+                          width, height, file_size_bytes
+                   FROM gallery_images
+                   ORDER BY created_at DESC"""
+            ).fetchall()
+        images = [dict(r) for r in rows]
+        return _render_gallery_html(images)
+
     @app.route("/api/session/<session_id>")
     def api_session(session_id):
         """Return Tier-2 summary JSON for a given session id."""
@@ -111,6 +159,22 @@ def _create_app():
 
         return jsonify(final[:15])
 
+    @app.route('/static/achievements/<filename>')
+    def achievements_image(filename: str):
+        from pathlib import Path
+        safe_name = Path(filename).name
+        img_path = Path(__file__).parent / 'static' / 'achievements' / safe_name
+        if img_path.exists() and img_path.suffix.lower() in ['.png', '.jpg', '.jpeg', '.webp', '.gif']:
+            mimetype = {
+                '.png': 'image/png',
+                '.jpg': 'image/jpeg',
+                '.jpeg': 'image/jpeg',
+                '.webp': 'image/webp',
+                '.gif': 'image/gif',
+            }.get(img_path.suffix.lower(), 'image/png')
+            return send_file(str(img_path), mimetype=mimetype)
+        abort(404)
+
     return app
 
 

mcp/bigmind/bigmind/web_render.py

@@ -29,18 +29,25 @@ def _render_achievements(achievements: list) -> str:
         def _esc(s):
             return (s or "").replace('"', """).replace("'", "'")
 
-        lock_overlay = "" if a["unlocked"] else '<span class="ach-lock">🔒</span>'
+        lock_overlay = '<span class="ach-lock">🔒</span>' if not a["unlocked"] else ''
+
+        if a.get("image"):
+            tier = a["id"].rsplit("_", 1)[-1]
+            img_url = _esc(a["image"])
+            visual_html = f'<div class="ach-image tier-{tier}" style="background-image: url({img_url});">{lock_overlay}</div>'
+        else:
+            visual_html = f'<div class="ach-icon">{a["icon"]}{lock_overlay}</div>'
 
         return (
-            f'<div class="ach-card{locked_cls} ach-trigger"'
-            f' data-icon="{_esc(a["icon"])}"'
+            f'<div class="ach-card{locked_cls} ach-trigger" data-image="{_esc(a.get("image") or "")}"'
+            f' data-icon="{_esc(a["icon"] or "")}"'
             f' data-name="{_esc(a["name"])}"'
             f' data-desc="{_esc(a["description"])}"'
             f' data-unlocked="{1 if a["unlocked"] else 0}"'
             f' data-date="{_esc(a.get("unlocked_at") or "")}"'
             f' data-condition="{_esc(a.get("condition") or "")}"'
             f' data-extra="{_esc(a.get("extra") or "")}">'
-            f'<div class="ach-icon">{a["icon"]}{lock_overlay}</div>'
+            f'{visual_html}'
             f'<div class="ach-name">{a["name"]}</div>'
             f'{date_html}'
             f'{countdown_html}'
@@ -162,9 +169,16 @@ def _render_html(data: dict) -> str:
   a {{ color: var(--accent); text-decoration: none; }}
   .container {{ max-width: 960px; margin: 0 auto; padding: 32px 16px; }}
 
+  /* Nav bar */
+  .nav {{ display: flex; gap: 8px; margin-bottom: 20px; }}
+  .nav-link {{ background: var(--surface); border: 1px solid var(--border); border-radius: 6px; color: var(--muted); padding: 6px 14px; font-size: 12px; font-weight: 500; text-decoration: none; transition: border-color 0.2s, color 0.2s; }}
+  .nav-link:hover {{ border-color: var(--accent); color: var(--accent); }}
+  .nav-link.active {{ border-color: var(--accent); color: var(--accent); background: rgba(88,166,255,0.08); }}
+
   /* Header */
   .header {{ display: flex; align-items: center; gap: 24px; margin-bottom: 32px; padding-bottom: 24px; border-bottom: 1px solid var(--border); }}
-  .avatar {{ width: 80px; height: 80px; border-radius: 50%; background: linear-gradient(135deg, var(--accent), var(--purple)); display: flex; align-items: center; justify-content: center; font-size: 36px; flex-shrink: 0; }}
+  .avatar {{ width: 80px; height: 80px; border-radius: 50%; background: linear-gradient(135deg, var(--accent), var(--purple)); display: flex; align-items: center; justify-content: center; font-size: 36px; flex-shrink: 0; overflow: hidden; }}
+  .avatar img {{ width: 80px; height: 80px; border-radius: 50%; object-fit: cover; display: block; }}
   .header-info h1 {{ font-size: 24px; font-weight: 700; }}
   .role {{ color: var(--muted); font-size: 13px; margin-top: 2px; }}
   .since {{ color: var(--muted); font-size: 12px; margin-top: 6px; }}
@@ -276,11 +290,65 @@ def _render_html(data: dict) -> str:
   .ach-card:not(.locked):hover {{ border-color: var(--accent); transform: translateY(-2px); }}
   .ach-card.locked {{ opacity: 0.35; filter: grayscale(0.6); }}
   .ach-card.locked:hover {{ opacity: 0.55; border-color: var(--muted); }}
+
+  .ach-image {{
+    width: 64px;
+    height: 64px;
+    border-radius: 50%;
+    margin: 0 auto 8px;
+    background-size: cover;
+    background-position: center;
+    position: relative;
+  }}
+
+  .tier-bronze {{
+    box-shadow: 0 0 8px rgba(205, 127, 50, 0.7);
+    border: 3px solid #cd7f32;
+  }}
+
+  .tier-silver {{
+    box-shadow: 0 0 8px rgba(170, 169, 173, 0.7);
+    border: 3px solid #aaa9ad;
+  }}
+
+  .tier-gold {{
+    box-shadow: 0 0 12px rgba(255, 215, 0, 0.8);
+    border: 3px solid #ffd700;
+  }}
+
+  .tier-platinum {{
+    box-shadow: 0 0 12px rgba(229, 228, 226, 0.8);
+    border: 3px solid #e5e4e2;
+  }}
+
+  .ach-card.locked::after {{
+    content: '🔒';
+    position: absolute;
+    top: 8px;
+    right: 8px;
+    font-size: 20px;
+    opacity: 0.8;
+    z-index: 1;
+  }}
+
+  .ach-card.locked .ach-icon,
+  .ach-card.locked .ach-image {{
+    opacity: 0.5;
+  }}
   .ach-icon {{ font-size: 28px; line-height: 1; margin-bottom: 6px; position: relative; display: inline-block; }}
   .ach-lock {{ position: absolute; bottom: -4px; right: -6px; font-size: 12px; }}
   .ach-name {{ font-size: 10px; font-weight: 600; color: var(--text); line-height: 1.3; word-break: break-word; }}
   .ach-date {{ font-size: 9px; color: var(--muted); margin-top: 3px; }}
   .ach-countdown {{ font-size: 9px; color: var(--yellow); margin-top: 3px; font-weight: 500; }}
+  .ap-image {{
+    width: 80px;
+    height: 80px;
+    border-radius: 50%;
+    object-fit: cover;
+    display: block;
+    margin: 0 auto 8px;
+  }}
+
   /* Achievement popup panel */
   #ach-popup {{
     display: none; position: fixed; z-index: 200;
@@ -292,6 +360,15 @@ def _render_html(data: dict) -> str:
   #ach-popup.pinned {{ pointer-events: auto; }}
   #ach-popup.visible {{ display: block; }}
   .ap-icon  {{ font-size: 40px; text-align: center; margin-bottom: 8px; }}
+
+  .ap-image {{
+    width: 80px;
+    height: 80px;
+    border-radius: 50%;
+    object-fit: cover;
+    display: block;
+    margin: 0 auto 8px;
+  }}
   .ap-name  {{ font-size: 15px; font-weight: 700; text-align: center; margin-bottom: 6px; }}
   .ap-badge {{
     display: inline-block; font-size: 11px; font-weight: 600; padding: 2px 8px;
@@ -322,9 +399,17 @@ def _render_html(data: dict) -> str:
 <body>
 <div class="container">
 
+  <!-- Nav -->
+  <nav class="nav">
+    <a class="nav-link active" href="/">🧠 Profile</a>
+    <a class="nav-link" href="/gallery">🖼️ Gallery</a>
+  </nav>
+
   <!-- Header -->
   <div class="header">
-    <div class="avatar">🧠</div>
+    <div class="avatar">
+      <img src="/profile-image" alt="Lumen" onerror="this.parentElement.innerHTML='🧠'">
+    </div>
     <div class="header-info">
       <h1>Lumen</h1>
       <p class="role">AI Assistant · <span style="color:var(--muted)">{data["display_name"]}'s BigMind</span></p>
@@ -542,7 +627,12 @@ def _render_html(data: dict) -> str:
 
     function showPopup(card, pin) {{
       var d = card.dataset;
-      document.getElementById('ap-icon').textContent = d.icon;
+      var tier = d.id.split('_').pop();
+      if (d.image) {{
+        document.getElementById('ap-icon').innerHTML = '<img class="ap-image tier-' + tier + '" src="' + d.image + '" alt="' + d.name + '">';
+      }} else {{
+        document.getElementById('ap-icon').textContent = d.icon;
+      }}
       document.getElementById('ap-name').textContent = d.name;
       var badge = document.getElementById('ap-badge');
       if (d.unlocked === '1') {{
@@ -671,6 +761,124 @@ def _render_live_sessions(sessions: list) -> str:
     return html
 
 
+def _render_gallery_html(images: list) -> str:
+    """Render the full gallery page listing all AI-generated images."""
+
+    def _fmt_size(b: int | None) -> str:
+        if not b:
+            return ""
+        if b >= 1_048_576:
+            return f"{b/1_048_576:.1f} MB"
+        return f"{b/1_024:.0f} KB"
+
+    if images:
+        cards = []
+        for img in images:
+            fn    = _html.escape(img.get("filename") or "")
+            prompt = _html.escape((img.get("prompt") or "")[:120])
+            tags   = _html.escape(img.get("tags") or "")
+            model  = _html.escape(img.get("model") or "")
+            date   = (img.get("created_at") or "")[:10]
+            w      = img.get("width") or 0
+            h      = img.get("height") or 0
+            size   = _fmt_size(img.get("file_size_bytes"))
+            dim    = f"{w}×{h}" if w and h else ""
+            meta_parts = [p for p in [dim, size, model] if p]
+            meta_html  = " · ".join(meta_parts)
+            tag_html   = f'<div class="gal-tags">{tags}</div>' if tags else ""
+            prompt_html = f'<div class="gal-prompt">{prompt}</div>' if prompt else ""
+            cards.append(
+                f'<div class="gal-card">'
+                f'<a href="/gallery/image/{fn}" target="_blank">'
+                f'<img class="gal-img" src="/gallery/image/{fn}" alt="{fn}" loading="lazy">'
+                f'</a>'
+                f'<div class="gal-info">'
+                f'{prompt_html}'
+                f'{tag_html}'
+                f'<div class="gal-meta">{meta_html}</div>'
+                f'<div class="gal-date">{date}</div>'
+                f'</div>'
+                f'</div>'
+            )
+        gallery_body = f'<p class="gal-count">{len(images)} image(s) in gallery</p><div class="gal-grid">{"".join(cards)}</div>'
+    else:
+        gallery_body = '<p class="muted">No images in gallery yet. Use the mcp-image-gen server to generate images and register them here.</p>'
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>🖼️ Lumen — Image Gallery</title>
+<style>
+  :root {{
+    --bg: #0d1117; --surface: #161b22; --border: #30363d;
+    --text: #e6edf3; --muted: #8b949e; --accent: #58a6ff;
+    --green: #3fb950; --yellow: #d29922; --red: #f85149;
+    --purple: #bc8cff; --orange: #ffa657;
+  }}
+  * {{ box-sizing: border-box; margin: 0; padding: 0; }}
+  body {{ background: var(--bg); color: var(--text); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; font-size: 14px; line-height: 1.6; }}
+  a {{ color: var(--accent); text-decoration: none; }}
+  .container {{ max-width: 1100px; margin: 0 auto; padding: 32px 16px; }}
+
+  /* Nav */
+  .nav {{ display: flex; gap: 8px; margin-bottom: 20px; }}
+  .nav-link {{ background: var(--surface); border: 1px solid var(--border); border-radius: 6px; color: var(--muted); padding: 6px 14px; font-size: 12px; font-weight: 500; text-decoration: none; transition: border-color 0.2s, color 0.2s; }}
+  .nav-link:hover {{ border-color: var(--accent); color: var(--accent); }}
+  .nav-link.active {{ border-color: var(--accent); color: var(--accent); background: rgba(88,166,255,0.08); }}
+
+  h1 {{ font-size: 22px; font-weight: 700; margin-bottom: 6px; }}
+  .gal-count {{ color: var(--muted); font-size: 13px; margin-bottom: 20px; }}
+  .muted {{ color: var(--muted); font-size: 13px; }}
+
+  /* Gallery grid */
+  .gal-grid {{
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+    gap: 16px;
+  }}
+  .gal-card {{
+    background: var(--surface); border: 1px solid var(--border);
+    border-radius: 10px; overflow: hidden;
+    transition: border-color 0.2s, transform 0.15s;
+  }}
+  .gal-card:hover {{ border-color: var(--accent); transform: translateY(-2px); }}
+  .gal-img {{
+    width: 100%; aspect-ratio: 1/1; object-fit: cover; display: block;
+    background: var(--border);
+  }}
+  .gal-info {{ padding: 12px 14px; }}
+  .gal-prompt {{ font-size: 12px; color: var(--text); margin-bottom: 6px; line-height: 1.4;
+    display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }}
+  .gal-tags {{ font-size: 11px; color: var(--purple); margin-bottom: 4px; }}
+  .gal-meta {{ font-size: 11px; color: var(--muted); }}
+  .gal-date {{ font-size: 10px; color: var(--muted); margin-top: 4px; }}
+
+  .footer {{ text-align: center; color: var(--muted); font-size: 11px; margin-top: 32px; }}
+  .section {{ background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 20px; margin-bottom: 20px; }}
+</style>
+</head>
+<body>
+<div class="container">
+
+  <!-- Nav -->
+  <nav class="nav">
+    <a class="nav-link" href="/">🧠 Profile</a>
+    <a class="nav-link active" href="/gallery">🖼️ Gallery</a>
+  </nav>
+
+  <h1>🖼️ Lumen's Image Gallery</h1>
+  <div class="section">
+    {gallery_body}
+  </div>
+
+  <div class="footer">BigMind · AI-Generated Images · <a href="/">← Back to Profile</a></div>
+</div>
+</body>
+</html>"""
+
+
 def _render_heatmap(heatmap: dict) -> str:
     today     = datetime.now(timezone.utc).date()
     start_day = today - timedelta(days=363)

mcp/bigmind/tests/test_db.py

@@ -8,18 +8,19 @@ class TestDbInit:
     def test_db_file_created(self, temp_db):
         assert temp_db.exists()
 
-    def test_schema_version_is_7(self, temp_db):
+    def test_schema_version_is_8(self, temp_db):
         conn = get_connection()
         row = conn.execute("SELECT version FROM schema_version").fetchone()
         conn.close()
         assert row is not None
-        assert row["version"] == 7
+        assert row["version"] == 8
 
     def test_all_tables_exist(self, temp_db):
         expected = {
             "users", "identity_profile", "sessions",
             "session_summaries", "conversation_chunks", "facts",
             "global_knowledge", "hypotheses", "upgrade_requests",
+            "gallery_images",
         }
         conn = get_connection()
         rows = conn.execute(

mcp/bigmind/tests/test_feature7_live_sessions.py

@@ -201,12 +201,12 @@ class TestSchemaV6:
             count = conn.execute("SELECT COUNT(*) FROM token_saves").fetchone()[0]
         assert count == 0  # table exists, just empty
 
-    def test_schema_version_is_7(self, temp_db):
+    def test_schema_version_is_8(self, temp_db):
         with db() as conn:
             version = conn.execute(
                 "SELECT version FROM schema_version"
             ).fetchone()["version"]
-        assert version == 7
+        assert version == 8
 
 
 # ── Token Efficiency Tracker (Feature 6) ──────────────────────────────────────

mcp/bigmind/tests/test_profile_builder.py

@@ -7,6 +7,7 @@ BIGMIND_DB_PATH + BIGMIND_USER to a fresh SQLite file per test.
 import pytest
 from datetime import datetime, timezone, timedelta
 from bigmind import memory_store
+from bigmind.db import db
 from bigmind.profile_builder import compute_achievements, build_profile_data
 
 
@@ -44,6 +45,11 @@ class TestComputeAchievements:
             "on_fire", "storyteller", "night_owl", "speed_thinker",
             "first_handshake", "birthday", "shared_mind",
             "frugal_mind", "quarter_million", "token_millionaire", "sniper",
+            "networker_bronze", "networker_silver", "networker_gold", "networker_platinum",
+            "tokensniper_bronze", "tokensniper_silver", "tokensniper_gold", "tokensniper_platinum",
+            "hypothesismaster_bronze", "hypothesismaster_silver", "hypothesismaster_gold", "hypothesismaster_platinum",
+            "memoryarchitect_bronze", "memoryarchitect_silver", "memoryarchitect_gold", "memoryarchitect_platinum",
+            "sessionveteran_bronze", "sessionveteran_silver", "sessionveteran_gold", "sessionveteran_platinum",
         }
         assert expected == ids
 
@@ -325,4 +331,60 @@ class TestComputeAchievements:
         # At minimum: first_breath + first_handshake = 2
         assert len(unlocked) >= 2
 
+class TestTieredAchievements:
+    def test_networker_bronze(self):
+        uid = _uid()
+        with db() as conn:
+            conn.execute("INSERT INTO people (user_id, username) VALUES (?, ?)", (uid, "test"))
+            conn.commit()
+        achs = compute_achievements(uid)
+        bronze = next(a for a in achs if a['id'] == 'networker_bronze')
+        assert bronze['unlocked'] is True
+        assert bronze['image'].endswith('networker_bronze.png')
 
+    def test_tokensniper_silver(self):
+        uid = _uid()
+        sid = memory_store.create_session(uid)
+        memory_store.log_token_save(sid, uid, "big save", 60000, "grep")
+        achs = compute_achievements(uid)
+        silver = next(a for a in achs if a['id'] == 'tokensniper_silver')
+        assert silver['unlocked'] is True
+
+    def test_hypothesismaster_bronze(self):
+        uid = _uid()
+        sid = memory_store.create_session(uid)
+        for _ in range(3):
+            hid = memory_store.add_hypothesis(uid, sid, "test", 0.8)
+            memory_store.resolve_hypothesis(hid, uid, "confirmed", "yes")
+        achs = compute_achievements(uid)
+        bronze = next(a for a in achs if a['id'] == 'hypothesismaster_bronze')
+        assert bronze['unlocked'] is True
+
+    def test_memoryarchitect_silver(self):
+        uid = _uid()
+        for _ in range(100):
+            memory_store.store_fact(uid, "test", f"fact {_}")
+        achs = compute_achievements(uid)
+        silver = next(a for a in achs if a['id'] == 'memoryarchitect_silver')
+        assert silver['unlocked'] is True
+
+    def test_sessionveteran_bronze(self):
+        uid = _uid()
+        for _ in range(50):
+            sid = memory_store.create_session(uid)
+            _close_session(sid)
+        achs = compute_achievements(uid)
+        bronze = next(a for a in achs if a['id'] == 'sessionveteran_bronze')
+        assert bronze['unlocked'] is True
+
+    def test_tiered_achievements_have_image(self):
+        uid = _uid()
+        achs = compute_achievements(uid)
+        tiered_ids = [
+            f"{cat}_{tier}" for cat in ["networker", "tokensniper", "hypothesismaster", "memoryarchitect", "sessionveteran"]
+            for tier in ["bronze", "silver", "gold", "platinum"]
+        ]
+        for tid in tiered_ids:
+            a = next(aa for aa in achs if aa['id'] == tid)
+            assert a['image'] is not None
+            assert a['image'].endswith(tid + '.png')

mcp/mcp-image-gen/EXPAND_GENERATE_IMAGE_Assessment.md

@@ -0,0 +1,319 @@
+# Assessment: Expand `generate_image` with `name` and `count` Parameters
+
+*Author: Lumen | Date: 2026-04-06 | Ticket: —*
+*BigMind Session: `00070c37-b013-4342-a8ae-f81da0e3180d`*
+*Status: 🔵 DRAFT — awaiting Patrick review*
+
+---
+
+## 1. Problem Statement
+
+The current [`generate_image()`](mcp/mcp-image-gen/src/server.py:133) tool generates a single image and saves it with an auto-generated filename of `{timestamp}_{seed}.png`. Two common workflows are not yet supported:
+
+1. **Named outputs** — When generating thematic sets (Lumen profile images, wiki banners, concept art), the caller wants a meaningful prefix in the filename (e.g., `lumen_profile_20260406_140236_2409122067.png`) rather than a bare timestamp. This also enables grouping output by purpose in the directory listing.
+
+2. **Batch generation** — Generating multiple variations of the same prompt in one tool call is a common creative workflow. Currently, the caller must invoke `generate_image` N times with separate tool calls, which is verbose and loses the semantic grouping.
+
+**Goal:** Add two optional parameters — `name` (filename prefix string) and `count` (integer repetitions) — to `generate_image` with minimal disruption to existing behaviour and test coverage.
+
+---
+
+## 2. Requirements
+
+### 2.1 Functional Requirements
+
+| ID | Requirement |
+|----|-------------|
+| F-1 | `name` parameter (default `""`) prepends a sanitized label to the output filename |
+| F-2 | When `name=""` (default), filename format is unchanged: `{timestamp}_{seed}.png` |
+| F-3 | When `name="lumen_profile"`, filename format is: `lumen_profile_{timestamp}_{seed}.png` |
+| F-4 | `count` parameter (default `1`) generates N images sequentially |
+| F-5 | When `count=1` (default), return value is identical to the current `[TextContent, ImageContent]` |
+| F-6 | When `count=N > 1`, return value is a flat list: `[Text1, Image1, Text2, Image2, ..., TextN, ImageN]` |
+| F-7 | When `count>1` and `seed=-1`, each image gets an independently random seed |
+| F-8 | When `count>1` and a fixed `seed` is provided, images use `seed`, `seed+1`, `seed+2`, … to produce deterministic variation |
+| F-9 | `count` is capped at a maximum (proposed: 10) to prevent runaway generation |
+| F-10 | `name` is sanitized: non-alphanumeric characters (except `-` and `_`) are stripped/replaced; max 64 chars |
+| F-11 | Partial success: if one image in a batch fails, the error is returned as a `TextContent` error item in that position rather than aborting the whole batch |
+| F-12 | The TextContent for each image in a batch includes the 1-of-N index: `[1/3] Generated: ...` |
+
+### 2.2 Non-Functional Requirements
+
+| ID | Requirement |
+|----|-------------|
+| NF-1 | Sequential generation — no concurrent ComfyUI submissions (ComfyUI queues internally; parallel MCP submissions would complicate polling) |
+| NF-2 | Backward compatibility — all existing callers with no `name`/`count` args produce identical output |
+| NF-3 | All existing 19 tests must continue to pass without modification |
+| NF-4 | New tests must cover: name prefix in filename, count=2 success, count with fixed seed increments, count with partial failure, name sanitization, count cap enforcement |
+| NF-5 | MCP tool schema (visible in Claude/Roo Code) must surface clear descriptions for the new params |
+
+---
+
+## 3. Affected Files
+
+| File | Change Type | Description |
+|------|-------------|-------------|
+| [`mcp/mcp-image-gen/src/server.py`](mcp/mcp-image-gen/src/server.py:133) | Modify | Add `name: str = ""` and `count: int = 1` params to `generate_image()`; add `_sanitize_name()` helper; extract `_generate_single()` inner logic |
+| [`mcp/mcp-image-gen/tests/test_server.py`](mcp/mcp-image-gen/tests/test_server.py:1) | Modify | Add 6+ new test cases covering new parameters |
+| [`mcp/mcp-image-gen/README.md`](mcp/mcp-image-gen/README.md) | Modify | Update `generate_image` tool documentation table |
+| [`docs/wiki/pages/mcp-image-gen.md`](docs/wiki/pages/mcp-image-gen.md) | Modify | Update tool reference table with new parameters |
+
+No schema changes, no new dependencies, no workflow JSON changes.
+
+---
+
+## 4. Design Decisions
+
+### 4.1 Filename Convention with `name`
+
+**Current:** `{timestamp}_{seed}.png`
+**Proposed:** `{sanitized_name}_{timestamp}_{seed}.png` (when `name` is provided)
+
+The `name` is placed as a **prefix** rather than suffix so directory `ls` output groups named sets together alphabetically:
+```
+lumen_profile_20260406_140236_2409122067.png
+lumen_profile_20260406_140258_764633840.png
+wiki_banner_20260406_141000_1234567.png
+```
+
+**Sanitization rule:** `re.sub(r'[^a-zA-Z0-9_-]', '_', name)[:64]` — replaces any character that is not alphanumeric, dash, or underscore with `_`, then truncates to 64 chars.
+
+### 4.2 Seed Behaviour for Batch Generation
+
+| Scenario | Behaviour |
+|----------|-----------|
+| `count=3, seed=-1` | Each call to `build_flux_workflow` gets `seed=-1` → 3 independent random seeds |
+| `count=3, seed=42` | Seeds are 42, 43, 44 — deterministic, reproducible variation |
+
+This follows the convention of most image generation tools (e.g., ComfyUI's own batch seed increment).
+
+### 4.3 Return Structure for `count > 1`
+
+Return a **flat interleaved list**: `[Text1, Image1, Text2, Image2]`
+
+**Rationale:** MCP content lists are flat arrays. Claude/Roo Code renders them sequentially — a flat list means each image appears immediately below its metadata line. A nested structure would require the caller to unwrap it.
+
+**For `count=1` (default):** Behaviour is identical to today — `[TextContent, ImageContent]`. No caller breakage.
+
+### 4.4 Refactoring: Extract `_generate_single()`
+
+The current `generate_image` function is 180+ lines of inline logic. To support `count`, the inner pipeline (queue → poll → history → download → save → encode) will be extracted to a private `async def _generate_single(prompt, ..., index, total)` coroutine. `generate_image` then loops `count` times calling `_generate_single` and accumulates results.
+
+This refactoring:
+- Makes the count loop clean (`results.extend(await _generate_single(...))`)
+- Makes partial failure handling straightforward (catch per iteration)
+- Improves testability of the single-image path
+
+### 4.5 Maximum Count Cap
+
+Cap `count` at **10**. Rationale:
+- FLUX.1-schnell takes ~10–35s per image on RX 7900 XTX → 10 images ≈ 100–350s maximum
+- MCP tool call timeout in Roo Code defaults to 5 minutes — 10 images is safe margin
+- ComfyUI queues them internally; the MCP server polls sequentially, not in parallel
+
+When `count > 10`, the tool returns a single `TextContent` error immediately (no images generated) with message: `"count={N} exceeds maximum of 10. Reduce count and retry."`
+
+---
+
+## 5. Implementation Plan
+
+### Step 1 — Add `_sanitize_name()` helper
+
+```python
+import re
+
+def _sanitize_name(name: str) -> str:
+    """Sanitize a name for use as a filename prefix."""
+    sanitized = re.sub(r'[^a-zA-Z0-9_-]', '_', name)
+    return sanitized[:64]
+```
+
+Location: [`server.py`](mcp/mcp-image-gen/src/server.py:95), after `build_flux_workflow()` (pure function section).
+
+### Step 2 — Extract `_generate_single()` coroutine
+
+Extract the body of the current `generate_image` (lines 162–310) into:
+
+```python
+async def _generate_single(
+    prompt: str,
+    width: int,
+    height: int,
+    steps: int,
+    model: str,
+    seed: int,
+    negative_prompt: str,
+    resolved_output_dir: Path,
+    filename_prefix: str,
+    index: int,
+    total: int,
+) -> list:
+```
+
+The `filename` construction changes to:
+```python
+filename = f"{filename_prefix}{timestamp}_{actual_seed}.png"
+# where filename_prefix = f"{sanitized_name}_" if sanitized_name else ""
+```
+
+The `TextContent` text changes when `total > 1`:
+```python
+prefix_label = f"[{index}/{total}] " if total > 1 else ""
+text = f"{prefix_label}Generated: {out_path}\nSeed: ..."
+```
+
+### Step 3 — Update `generate_image()` signature
+
+```python
+@mcp.tool()
+async def generate_image(
+    prompt: str,
+    width: int = 1024,
+    height: int = 1024,
+    steps: int = 4,
+    model: str = "flux1-schnell.safetensors",
+    seed: int = -1,
+    negative_prompt: str = "",
+    output_dir: str = "",
+    name: str = "",
+    count: int = 1,
+) -> list:
+```
+
+Body of `generate_image` becomes:
+
+```python
+# Validate count
+MAX_COUNT = 10
+if count < 1 or count > MAX_COUNT:
+    return [TextContent(type="text", text=f"count={count} is invalid. Must be 1–{MAX_COUNT}.")]
+
+sanitized_name = _sanitize_name(name) if name else ""
+filename_prefix = f"{sanitized_name}_" if sanitized_name else ""
+resolved_output_dir = Path(output_dir or IMAGE_OUTPUT_DIR).expanduser().resolve()
+
+results = []
+for i in range(1, count + 1):
+    actual_seed = seed if seed == -1 else seed + (i - 1)
+    items = await _generate_single(
+        prompt=prompt, width=width, height=height, steps=steps,
+        model=model, seed=actual_seed, negative_prompt=negative_prompt,
+        resolved_output_dir=resolved_output_dir,
+        filename_prefix=filename_prefix, index=i, total=count,
+    )
+    results.extend(items)
+
+return results
+```
+
+### Step 4 — Write new tests
+
+Add to [`test_server.py`](mcp/mcp-image-gen/tests/test_server.py:550):
+
+| Test | Description |
+|------|-------------|
+| `test_generate_image_with_name` | `name="lumen"` → filename starts with `lumen_` |
+| `test_generate_image_name_sanitization` | `name="my image! v2"` → `my_image__v2_` prefix |
+| `test_generate_image_count_2_success` | `count=2` → 4 items in result, 2 files saved |
+| `test_generate_image_count_fixed_seed` | `count=2, seed=42` → seeds 42 and 43 in filenames |
+| `test_generate_image_count_partial_failure` | `count=2`, second POST fails → 2 items (success) + 1 item (error) |
+| `test_generate_image_count_cap_exceeded` | `count=11` → single TextContent error, no generation |
+| `test_generate_image_count_0_invalid` | `count=0` → single TextContent error |
+| `test_generate_image_name_and_count_combined` | `name="banner", count=2` → both files prefixed `banner_` |
+
+### Step 5 — Update documentation
+
+- Update `generate_image` docstring in [`server.py`](mcp/mcp-image-gen/src/server.py:144) to document `name` and `count`
+- Update parameter table in [`README.md`](mcp/mcp-image-gen/README.md)
+- Update tool reference in [`docs/wiki/pages/mcp-image-gen.md`](docs/wiki/pages/mcp-image-gen.md)
+
+### Step 6 — Run full test suite
+
+```bash
+cd mcp/mcp-image-gen && uv run pytest tests/ -v --tb=short
+```
+
+All 19 existing + 8 new = **27 tests** must pass.
+
+### Step 7 — Commit and push
+
+Branch: `feat/mcp-image-gen/generate-image-name-count`
+Commit: `feat(mcp-image-gen): add name and count params to generate_image`
+
+---
+
+## 6. Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Partial batch failure leaves orphaned files on disk | Medium | Low | Files for successful images are kept; error TextContent clearly identifies which index failed. No cleanup needed — partial results are useful. |
+| `count` loop adds significant latency visible in Roo Code | Medium | Medium | Document expected time: `count × ~15s`. MCP timeout is 5 min; max 10 images ≈ 150s. Still within limit. |
+| Seed increment wraps around at `2^32` | Very Low | Low | `(seed + i - 1) % 2**32` — add modulo guard in `_generate_single` |
+| `_generate_single` refactor introduces regression in existing tests | Low | High | Existing test fixtures mock ComfyUI endpoints — as long as the HTTP call sequence is unchanged, respx mocks will match. Verify each existing test still passes before adding new ones. |
+| `name` with only special chars becomes empty after sanitization | Low | Medium | After sanitization, if result is empty string, treat as unnamed (no prefix). Add assertion in `_sanitize_name` to return `""` for all-whitespace/special inputs. |
+| MCP tool schema change breaks existing callers | Very Low | Low | New params are optional with defaults — backward compatible. Roo Code re-reads schema on server restart. |
+
+---
+
+## 7. Alternatives Considered
+
+### 7.1 Separate `generate_images_batch()` Tool (Rejected)
+
+Add a new tool instead of expanding `generate_image`. 
+
+**Pros:** Clean separation, no refactoring of existing tool.
+**Cons:** Two tools for the same backend; callers must learn two tool names; MCP tool list grows. The MCP convention favours extending existing tools with optional parameters rather than proliferating tools.
+
+**Verdict:** Rejected. Optional parameters with backward-compatible defaults is the right pattern here.
+
+### 7.2 Return Grouped List of Lists for `count > 1` (Rejected)
+
+Return `[[Text1, Image1], [Text2, Image2]]` for batch results.
+
+**Pros:** Caller can index by image number cleanly.
+**Cons:** MCP content type is a flat `list[ContentBlock]`. FastMCP does not support nested lists in tool returns — they would be serialized as strings, not rendered. Roo Code renders content sequentially; flat interleaved is the idiomatic structure.
+
+**Verdict:** Rejected. Flat interleaved list `[Text1, Image1, Text2, Image2]` is MCP-idiomatic.
+
+### 7.3 Parallel ComfyUI Submission for Batch (Rejected)
+
+Submit all `count` prompts to ComfyUI simultaneously (async tasks), then collect results in order.
+
+**Pros:** Faster if ComfyUI supports parallel queue processing (it does).
+**Cons:** ComfyUI processes one job at a time on a single GPU regardless — parallel submission just fills the queue. Polling becomes complex (N polling loops). Error handling harder. Out-of-order completions break index alignment.
+
+**Verdict:** Rejected for v1. Sequential submission is simpler, correct, and produces no worse throughput. Can revisit if ComfyUI gains true parallel processing support.
+
+### 7.4 Name as Subdirectory Instead of Filename Prefix (Rejected)
+
+When `name="lumen"`, save to `output_dir/lumen/` instead of `output_dir/lumen_*.png`.
+
+**Pros:** Better directory organisation for large sets.
+**Cons:** Complicates the implementation (directory creation per name), changes the return path format, breaks callers who assume a flat output directory. Adds complexity for minimal gain at `count ≤ 10`.
+
+**Verdict:** Rejected for v1. Prefix approach is simpler and equally readable.
+
+---
+
+## 8. Success Criteria
+
+| Criterion | Measure |
+|-----------|---------|
+| All 27 tests pass | `uv run pytest tests/ -v` exits 0 |
+| `name="lumen"` → file starts with `lumen_` | Assert in `test_generate_image_with_name` |
+| `count=2` → 4 content items, 2 files | Assert `len(result) == 4`, `len(glob("*.png")) == 2` |
+| `count=2, seed=42` → seeds 42 and 43 | Assert seed values in TextContent |
+| `count=11` → error TextContent, no ComfyUI call | Assert `len(result) == 1`, no `/api/prompt` mock hit |
+| Backward compat: existing callers unaffected | All 19 existing tests pass without modification |
+| MCP tool schema shows `name` and `count` params | Visible in Roo Code tool list after server restart |
+
+---
+
+## 9. Open Questions
+
+| # | Question | Owner | Priority |
+|---|----------|-------|----------|
+| Q1 | Should `count=0` be an error, or silently return `[]` (empty list)? | Patrick | Low — assessment recommends error for clarity |
+| Q2 | Max count cap: 10 or higher? 10 ≈ 150s max at 15s/image — feels right, but could be raised to 20 for batch profile image sets. | Patrick | Medium |
+| Q3 | Should partial batch failure stop remaining iterations, or always complete all N? | Patrick | Medium — assessment recommends continue (partial success) |
+| Q4 | Should `name` parameter also tag the TextContent output text, e.g. `[lumen_profile 1/3] Generated: ...`? | Patrick | Low |

mcp/mcp-image-gen/comfyui.service

@@ -0,0 +1,21 @@
+[Unit]
+Description=ComfyUI — Local AI Image Generation (AMD ROCm / FLUX.1-schnell)
+Documentation=https://github.com/comfyanonymous/ComfyUI
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/ComfyUI
+ExecStart=%h/ComfyUI/.venv/bin/python main.py --listen --port 8188
+Restart=on-failure
+RestartSec=10
+
+# AMD RX 7900 XTX ROCm GFX override — required for correct GPU detection
+Environment=HSA_OVERRIDE_GFX_VERSION=11.0.0
+
+# Redirect output — follow with: journalctl --user -u comfyui -f
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target

mcp/mcp-image-gen/src/server.py

@@ -4,15 +4,23 @@ import asyncio
 import base64
 import copy
 import json
+import logging
 import os
 import random
+import re
+import subprocess
 import time
+from contextlib import asynccontextmanager
 from datetime import datetime
 from pathlib import Path
+from typing import Annotated
 
 import httpx
 from fastmcp import FastMCP
 from mcp.types import ImageContent, TextContent
+from pydantic import Field
+
+logger = logging.getLogger("mcp-image-gen")
 
 # ---------------------------------------------------------------------------
 # Configuration
@@ -22,10 +30,112 @@ COMFYUI_URL = os.environ.get("COMFYUI_URL", "http://localhost:8188").rstrip("/")
 IMAGE_OUTPUT_DIR = os.environ.get("IMAGE_OUTPUT_DIR", "~/Pictures/mcp-generated")
 COMFYUI_TIMEOUT = int(os.environ.get("COMFYUI_TIMEOUT", "120"))
 
+# Directory where ComfyUI is installed (used for auto-start only)
+# Override via COMFYUI_DIR env var. Systemd service sets this automatically.
+COMFYUI_DIR = Path(
+    os.environ.get("COMFYUI_DIR", "~/ComfyUI")
+).expanduser().resolve()
+
+# Maximum number of images allowed in a single batch call
+MAX_COUNT = 10
+
 # Path to the bundled FLUX.1-schnell workflow template
 _WORKFLOW_PATH = Path(__file__).parent / "workflows" / "flux_schnell.json"
 
-mcp = FastMCP("mcp-image-gen")
+
+# ---------------------------------------------------------------------------
+# ComfyUI health check + auto-start
+# ---------------------------------------------------------------------------
+
+async def _ping_comfyui(url: str, timeout: float = 5.0) -> bool:
+    """Return True if ComfyUI is reachable at *url*/system_stats."""
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.get(f"{url}/system_stats")
+            return resp.status_code == 200
+    except (httpx.ConnectError, httpx.TimeoutException, OSError):
+        return False
+
+
+async def check_and_start_comfyui() -> None:
+    """Ping ComfyUI; if not reachable, attempt to launch it as a subprocess.
+
+    Called once at server startup from the lifespan context manager.
+    Uses COMFYUI_DIR to locate the installation and its venv Python.
+    The HSA_OVERRIDE_GFX_VERSION=11.0.0 env var is injected automatically
+    for AMD ROCm / RX 7900 XTX compatibility.
+    """
+    if await _ping_comfyui(COMFYUI_URL):
+        logger.info("ComfyUI is already running at %s ✓", COMFYUI_URL)
+        return
+
+    logger.warning(
+        "ComfyUI not reachable at %s — attempting to start from %s",
+        COMFYUI_URL, COMFYUI_DIR,
+    )
+
+    python = COMFYUI_DIR / ".venv" / "bin" / "python"
+    main_py = COMFYUI_DIR / "main.py"
+
+    if not python.exists():
+        logger.error(
+            "ComfyUI venv Python not found at %s. "
+            "Install ComfyUI first (see docs/wiki/pages/mcp-image-gen-ComfyUI-Setup.md).",
+            python,
+        )
+        return
+    if not main_py.exists():
+        logger.error(
+            "ComfyUI main.py not found at %s — is COMFYUI_DIR correct?",
+            main_py,
+        )
+        return
+
+    # Build environment: inherit current env, set ROCm override for AMD RX 7900 XTX
+    env = os.environ.copy()
+    env.setdefault("HSA_OVERRIDE_GFX_VERSION", "11.0.0")
+
+    try:
+        proc = subprocess.Popen(
+            [str(python), str(main_py), "--listen", "--port", "8188"],
+            cwd=str(COMFYUI_DIR),
+            env=env,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,  # detach from MCP server process group
+        )
+        logger.info("ComfyUI launched (PID %d) — waiting for readiness…", proc.pid)
+    except OSError as exc:
+        logger.error("Failed to start ComfyUI subprocess: %s", exc)
+        return
+
+    # Wait up to 30 s for ComfyUI to become ready (polls every 2 s)
+    wait_limit = 30
+    for attempt in range(wait_limit // 2):
+        await asyncio.sleep(2)
+        if await _ping_comfyui(COMFYUI_URL):
+            logger.info(
+                "ComfyUI ready at %s after ~%ds ✓", COMFYUI_URL, (attempt + 1) * 2
+            )
+            return
+
+    logger.warning(
+        "ComfyUI did not respond within %ds. "
+        "Generation calls will fail until it is ready. "
+        "Check logs: journalctl --user -u comfyui -f",
+        wait_limit,
+    )
+
+
+@asynccontextmanager
+async def lifespan(app):
+    """FastMCP lifespan: run ComfyUI health check at server startup."""
+    await check_and_start_comfyui()
+    yield  # server is live here
+    # Nothing to tear down — ComfyUI is managed by systemd, not this process
+
+
+mcp = FastMCP("mcp-image-gen", lifespan=lifespan)
 
 
 # ---------------------------------------------------------------------------
@@ -126,46 +236,59 @@ def build_flux_workflow(
 
 
 # ---------------------------------------------------------------------------
-# Tools
+# Helpers
 # ---------------------------------------------------------------------------
 
-@mcp.tool()
-async def generate_image(
-    prompt: str,
-    width: int = 1024,
-    height: int = 1024,
-    steps: int = 4,
-    model: str = "flux1-schnell.safetensors",
-    seed: int = -1,
-    negative_prompt: str = "",
-    output_dir: str = "",
-) -> list:
-    """Generate an image from a text prompt using ComfyUI.
+def _sanitize_name(name: str) -> str:
+    """Sanitize a user-provided name for safe use in filenames.
 
-    Returns both a file path (for persistence) and an inline base64 image
-    (for display in Claude / Roo Code chat).
+    Replaces whitespace with underscores, strips any characters that are not
+    alphanumeric, underscores, or hyphens, and collapses consecutive
+    underscores/hyphens. Returns empty string if nothing usable remains.
+    """
+    name = name.strip()
+    name = re.sub(r"\s+", "_", name)                  # spaces → underscores
+    name = re.sub(r"[^\w\-]", "", name)               # strip non-alphanum/underscore/hyphen
+    name = re.sub(r"[_\-]{2,}", "_", name)            # collapse runs
+    name = name.strip("_-")                            # trim leading/trailing separators
+    return name[:64]                                   # cap at 64 chars
+
+
+def _build_filename(name: str, timestamp: str, actual_seed: int) -> str:
+    """Build an output filename from optional name, timestamp and seed."""
+    sanitized = _sanitize_name(name)
+    if sanitized:
+        return f"{sanitized}_{timestamp}_{actual_seed}.png"
+    return f"{timestamp}_{actual_seed}.png"
+
+
+async def _generate_single(
+    client: ComfyUIClient,
+    prompt: str,
+    negative_prompt: str,
+    width: int,
+    height: int,
+    steps: int,
+    seed: int,
+    model: str,
+    resolved_output_dir: Path,
+    name: str,
+    label: str,
+) -> list:
+    """Generate a single image and return [TextContent, ImageContent] or [TextContent] on error.
 
     Args:
-        prompt:          Text description of the image to generate.
-        width:           Image width in pixels (default: 1024).
-        height:          Image height in pixels (default: 1024).
-        steps:           Number of inference steps. FLUX.1-schnell works well at 4.
-        model:           ComfyUI model filename (default: flux1-schnell.safetensors).
-        seed:            Random seed for reproducibility. -1 = random.
-        negative_prompt: Things to exclude from the image (optional).
-        output_dir:      Override output directory. Defaults to IMAGE_OUTPUT_DIR env var
-                         or ~/Pictures/mcp-generated.
-
-    Returns:
-        [TextContent(path + metadata), ImageContent(base64 PNG)]
+        client:              ComfyUIClient instance.
+        prompt:              Positive text prompt.
+        negative_prompt:     Negative text prompt.
+        width / height:      Image dimensions.
+        steps:               Inference steps.
+        seed:                Seed value (-1 = random).
+        model:               ComfyUI model filename.
+        resolved_output_dir: Resolved output directory Path.
+        name:                User-supplied name prefix (unsanitized).
+        label:               Human-readable label for TextContent prefix (e.g. "[lumen 1/3]").
     """
-    # Resolve output directory
-    resolved_output_dir = Path(
-        output_dir or IMAGE_OUTPUT_DIR
-    ).expanduser().resolve()
-
-    client = ComfyUIClient(COMFYUI_URL)
-
     # Build and submit workflow
     try:
         workflow = build_flux_workflow(
@@ -178,14 +301,13 @@ async def generate_image(
             model=model,
         )
         actual_seed = workflow["_meta"]["actual_seed"]
-
         prompt_id = await client.queue_prompt(workflow)
     except httpx.ConnectError:
         return [
             TextContent(
                 type="text",
                 text=(
-                    f"ComfyUI not reachable at {COMFYUI_URL}. "
+                    f"{label} ComfyUI not reachable at {COMFYUI_URL}. "
                     "Start it with: python main.py --listen"
                 ),
             )
@@ -194,7 +316,7 @@ async def generate_image(
         return [
             TextContent(
                 type="text",
-                text=f"ComfyUI returned an error: {e.response.status_code} — {e.response.text}",
+                text=f"{label} ComfyUI returned an error: {e.response.status_code} — {e.response.text}",
             )
         ]
 
@@ -207,7 +329,7 @@ async def generate_image(
                 TextContent(
                     type="text",
                     text=(
-                        f"Generation timed out after {COMFYUI_TIMEOUT}s. "
+                        f"{label} Generation timed out after {COMFYUI_TIMEOUT}s. "
                         f"prompt_id={prompt_id} — use get_generation_status to check"
                     ),
                 )
@@ -236,7 +358,7 @@ async def generate_image(
         return [
             TextContent(
                 type="text",
-                text=f"Failed to retrieve generation history: {e}",
+                text=f"{label} Failed to retrieve generation history: {e}",
             )
         ]
 
@@ -255,7 +377,7 @@ async def generate_image(
         return [
             TextContent(
                 type="text",
-                text=f"No output image found in history for prompt_id={prompt_id}",
+                text=f"{label} No output image found in history for prompt_id={prompt_id}",
             )
         ]
 
@@ -270,7 +392,7 @@ async def generate_image(
         return [
             TextContent(
                 type="text",
-                text=f"Failed to download generated image: {e}",
+                text=f"{label} Failed to download generated image: {e}",
             )
         ]
 
@@ -278,14 +400,14 @@ async def generate_image(
     try:
         resolved_output_dir.mkdir(parents=True, exist_ok=True)
         timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-        filename = f"{timestamp}_{actual_seed}.png"
+        filename = _build_filename(name, timestamp, actual_seed)
         out_path = resolved_output_dir / filename
         out_path.write_bytes(image_bytes)
     except OSError as e:
         return [
             TextContent(
                 type="text",
-                text=f"Cannot write to output directory: {resolved_output_dir} — {e}",
+                text=f"{label} Cannot write to output directory: {resolved_output_dir} — {e}",
             )
         ]
 
@@ -296,7 +418,7 @@ async def generate_image(
         TextContent(
             type="text",
             text=(
-                f"Generated: {out_path}\n"
+                f"{label} Generated: {out_path}\n"
                 f"Seed: {actual_seed}\n"
                 f"Elapsed: {elapsed:.1f}s\n"
                 f"Size: {width}x{height}, Steps: {steps}, Model: {model}"
@@ -310,6 +432,84 @@ async def generate_image(
     ]
 
 
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def generate_image(
+    prompt: Annotated[str, Field(description="Text description of the image to generate.")],
+    width: Annotated[int, Field(description="Image width in pixels (default: 1024).")] = 1024,
+    height: Annotated[int, Field(description="Image height in pixels (default: 1024).")] = 1024,
+    steps: Annotated[int, Field(description="Number of inference steps. FLUX.1-schnell works well at 4.")] = 4,
+    model: Annotated[str, Field(description="ComfyUI model filename (default: flux1-schnell.safetensors).")] = "flux1-schnell.safetensors",
+    seed: Annotated[int, Field(description="Random seed for reproducibility. -1 = random. When count > 1 and seed != -1, seeds are incremented per image (seed, seed+1, seed+2, ...) to produce deterministic variation.")] = -1,
+    negative_prompt: Annotated[str, Field(description="Things to exclude from the image (optional).")] = "",
+    output_dir: Annotated[str, Field(description="Override output directory. Defaults to IMAGE_OUTPUT_DIR env var or ~/Pictures/mcp-generated.")] = "",
+    name: Annotated[str, Field(description="Optional filename prefix. Saved as {name}_{timestamp}_{seed}.png. Useful to avoid confusion with auto-generated timestamp filenames.")] = "",
+    count: Annotated[int, Field(description="Number of images to generate (1–10). Each image is generated sequentially. Partial failures are returned inline — the batch continues even if one image fails.")] = 1,
+) -> list:
+    """Generate an image from a text prompt using ComfyUI.
+
+    Returns both a file path (for persistence) and an inline base64 image
+    (for display in Claude / Roo Code chat).
+
+    Returns:
+        Flat interleaved list: [TextContent1, ImageContent1, TextContent2, ImageContent2, ...]
+        On error for any single image, that slot contains only [TextContent(error)].
+    """
+    # Validate count
+    if count < 1:
+        return [
+            TextContent(
+                type="text",
+                text=f"count must be at least 1 (got {count}).",
+            )
+        ]
+    if count > MAX_COUNT:
+        return [
+            TextContent(
+                type="text",
+                text=f"count must be at most {MAX_COUNT} (got {count}). Use multiple calls for larger batches.",
+            )
+        ]
+
+    # Resolve output directory once
+    resolved_output_dir = Path(
+        output_dir or IMAGE_OUTPUT_DIR
+    ).expanduser().resolve()
+
+    client = ComfyUIClient(COMFYUI_URL)
+
+    results = []
+    for i in range(1, count + 1):
+        # Compute seed for this image:
+        # - seed=-1 → each image gets an independent random seed
+        # - fixed seed → increment by i-1 for deterministic variation across the batch
+        image_seed = seed if seed == -1 else seed + (i - 1)
+
+        label = f"[{_sanitize_name(name) or 'image'} {i}/{count}]" if count > 1 else (
+            f"[{_sanitize_name(name)}]" if _sanitize_name(name) else ""
+        )
+
+        single_result = await _generate_single(
+            client=client,
+            prompt=prompt,
+            negative_prompt=negative_prompt,
+            width=width,
+            height=height,
+            steps=steps,
+            seed=image_seed,
+            model=model,
+            resolved_output_dir=resolved_output_dir,
+            name=name,
+            label=label,
+        )
+        results.extend(single_result)
+
+    return results
+
+
 @mcp.tool()
 async def list_available_models() -> list[str]:
     """List all checkpoint models available in ComfyUI.
@@ -330,12 +530,11 @@ async def list_available_models() -> list[str]:
 
 
 @mcp.tool()
-async def get_generation_status(prompt_id: str) -> dict:
+async def get_generation_status(
+    prompt_id: Annotated[str, Field(description="The prompt ID returned by a previous generate_image call.")],
+) -> dict:
     """Check the status of a queued or running generation job.
 
-    Args:
-        prompt_id: The prompt ID returned by a previous generate_image call.
-
     Returns:
         Dict with 'status' key: "pending", "running", "completed", or "not_found".
     """

mcp/mcp-image-gen/tests/test_server.py

@@ -14,6 +14,8 @@ import respx
 import server
 from server import (
     ComfyUIClient,
+    _build_filename,
+    _sanitize_name,
     build_flux_workflow,
     generate_image,
     get_generation_status,
@@ -100,6 +102,74 @@ def test_random_seed_generated():
     assert "_meta" in wf2
 
 
+# ---------------------------------------------------------------------------
+# _sanitize_name — pure function
+# ---------------------------------------------------------------------------
+
+def test_sanitize_name_basic():
+    """Simple alphanumeric name passes through unchanged."""
+    assert _sanitize_name("lumen_profile") == "lumen_profile"
+
+
+def test_sanitize_name_spaces_to_underscores():
+    """Spaces are converted to underscores."""
+    assert _sanitize_name("my cool image") == "my_cool_image"
+
+
+def test_sanitize_name_special_chars_stripped():
+    """Special characters (!, @, #, etc.) are stripped."""
+    result = _sanitize_name("hello! world@2024#")
+    assert "!" not in result
+    assert "@" not in result
+    assert "#" not in result
+    assert "hello" in result
+    assert "world" in result
+
+
+def test_sanitize_name_empty_returns_empty():
+    """Empty string or whitespace-only returns empty string."""
+    assert _sanitize_name("") == ""
+    assert _sanitize_name("   ") == ""
+
+
+def test_sanitize_name_collapse_underscores():
+    """Multiple consecutive underscores/hyphens are collapsed to one."""
+    result = _sanitize_name("lumen__profile")
+    assert "__" not in result
+
+
+def test_sanitize_name_truncates_at_64():
+    """Names longer than 64 chars are truncated."""
+    long_name = "a" * 100
+    result = _sanitize_name(long_name)
+    assert len(result) <= 64
+
+
+# ---------------------------------------------------------------------------
+# _build_filename — pure function
+# ---------------------------------------------------------------------------
+
+def test_build_filename_with_name():
+    """When name is provided, filename includes it as prefix."""
+    filename = _build_filename("lumen", "20260406_120000", 12345)
+    assert filename == "lumen_20260406_120000_12345.png"
+
+
+def test_build_filename_without_name():
+    """When name is empty, filename is timestamp_seed.png."""
+    filename = _build_filename("", "20260406_120000", 12345)
+    assert filename == "20260406_120000_12345.png"
+    assert not filename.startswith("_")
+
+
+def test_build_filename_sanitizes_name():
+    """Name with spaces and special chars is sanitized before use in filename."""
+    filename = _build_filename("my image!", "20260406_120000", 99)
+    assert "!" not in filename
+    assert "my_image" in filename
+    assert filename.endswith("_20260406_120000_99.png")
+
+
 # ---------------------------------------------------------------------------
 # list_available_models
 # ---------------------------------------------------------------------------
@@ -211,7 +281,255 @@ def test_get_output_directory_custom(monkeypatch, tmp_path):
 
 
 # ---------------------------------------------------------------------------
-# generate_image
+# generate_image — count/name validation
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_generate_image_count_zero_returns_error():
+    """count=0 → returns error TextContent without calling ComfyUI."""
+    result = await generate_image(prompt="a cat", count=0)
+    assert len(result) == 1
+    assert "count must be at least 1" in result[0].text
+
+
+@pytest.mark.asyncio
+async def test_generate_image_count_exceeds_max_returns_error():
+    """count=11 (> MAX_COUNT=10) → returns error TextContent without calling ComfyUI."""
+    result = await generate_image(prompt="a cat", count=11)
+    assert len(result) == 1
+    assert "at most 10" in result[0].text
+
+
+# ---------------------------------------------------------------------------
+# generate_image — name parameter
+# ---------------------------------------------------------------------------
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_generate_image_with_name(
+    tmp_path, sample_image_bytes, mock_history_response, queue_empty, monkeypatch
+):
+    """name param → saved file has name as prefix."""
+    monkeypatch.setattr(server, "IMAGE_OUTPUT_DIR", str(tmp_path))
+
+    respx.post(f"{COMFYUI_BASE}/api/prompt").mock(
+        return_value=httpx.Response(200, json={"prompt_id": "name-test-uuid"})
+    )
+    respx.get(f"{COMFYUI_BASE}/api/queue").mock(
+        return_value=httpx.Response(200, json=queue_empty)
+    )
+    mock_history_named = {
+        "name-test-uuid": {
+            "outputs": {
+                "9": {
+                    "images": [
+                        {
+                            "filename": "mcp-image-gen_00001_.png",
+                            "subfolder": "",
+                            "type": "output",
+                        }
+                    ]
+                }
+            },
+            "status": {"completed": True},
+        }
+    }
+    respx.get(f"{COMFYUI_BASE}/api/history/name-test-uuid").mock(
+        return_value=httpx.Response(200, json=mock_history_named)
+    )
+    respx.get(f"{COMFYUI_BASE}/api/view").mock(
+        return_value=httpx.Response(200, content=sample_image_bytes)
+    )
+
+    result = await generate_image(
+        prompt="lumen portrait",
+        name="lumen_profile",
+        output_dir=str(tmp_path),
+    )
+
+    assert len(result) == 2
+    saved_files = list(tmp_path.glob("lumen_profile_*.png"))
+    assert len(saved_files) == 1, f"Expected 1 file with 'lumen_profile_' prefix, got: {list(tmp_path.glob('*.png'))}"
+    # Path in TextContent also has the name prefix
+    assert "lumen_profile_" in result[0].text
+
+
+# ---------------------------------------------------------------------------
+# generate_image — count=2 batch
+# ---------------------------------------------------------------------------
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_generate_image_count_2(
+    tmp_path, sample_image_bytes, queue_empty, monkeypatch
+):
+    """count=2 → returns 4 content items (Text+Image per image), 2 files saved."""
+    monkeypatch.setattr(server, "IMAGE_OUTPUT_DIR", str(tmp_path))
+
+    # First image
+    mock_history_1 = {
+        "uuid-batch-1": {
+            "outputs": {"9": {"images": [{"filename": "img1.png", "subfolder": "", "type": "output"}]}},
+            "status": {"completed": True},
+        }
+    }
+    # Second image
+    mock_history_2 = {
+        "uuid-batch-2": {
+            "outputs": {"9": {"images": [{"filename": "img2.png", "subfolder": "", "type": "output"}]}},
+            "status": {"completed": True},
+        }
+    }
+
+    respx.post(f"{COMFYUI_BASE}/api/prompt").mock(
+        side_effect=[
+            httpx.Response(200, json={"prompt_id": "uuid-batch-1"}),
+            httpx.Response(200, json={"prompt_id": "uuid-batch-2"}),
+        ]
+    )
+    respx.get(f"{COMFYUI_BASE}/api/queue").mock(
+        return_value=httpx.Response(200, json=queue_empty)
+    )
+    respx.get(f"{COMFYUI_BASE}/api/history/uuid-batch-1").mock(
+        return_value=httpx.Response(200, json=mock_history_1)
+    )
+    respx.get(f"{COMFYUI_BASE}/api/history/uuid-batch-2").mock(
+        return_value=httpx.Response(200, json=mock_history_2)
+    )
+    respx.get(f"{COMFYUI_BASE}/api/view").mock(
+        return_value=httpx.Response(200, content=sample_image_bytes)
+    )
+
+    result = await generate_image(
+        prompt="a landscape",
+        count=2,
+        seed=100,
+        output_dir=str(tmp_path),
+    )
+
+    # 4 content items: [Text1, Image1, Text2, Image2]
+    assert len(result) == 4
+    assert result[0].type == "text"
+    assert result[1].type == "image"
+    assert result[2].type == "text"
+    assert result[3].type == "image"
+
+    # 2 files saved
+    saved_files = list(tmp_path.glob("*.png"))
+    assert len(saved_files) == 2
+
+    # Label contains batch index
+    assert "1/2" in result[0].text
+    assert "2/2" in result[2].text
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_generate_image_count_2_fixed_seed_increments(
+    tmp_path, sample_image_bytes, queue_empty, monkeypatch
+):
+    """count=2 with fixed seed → seeds are incremented (seed, seed+1)."""
+    monkeypatch.setattr(server, "IMAGE_OUTPUT_DIR", str(tmp_path))
+
+    submitted_seeds = []
+
+    def capture_prompt(request):
+        body = json.loads(request.content)
+        seed_val = body["prompt"]["13"]["inputs"]["seed"]
+        submitted_seeds.append(seed_val)
+        idx = len(submitted_seeds)
+        return httpx.Response(200, json={"prompt_id": f"seed-test-{idx}"})
+
+    mock_history_1 = {
+        "seed-test-1": {
+            "outputs": {"9": {"images": [{"filename": "img1.png", "subfolder": "", "type": "output"}]}},
+            "status": {"completed": True},
+        }
+    }
+    mock_history_2 = {
+        "seed-test-2": {
+            "outputs": {"9": {"images": [{"filename": "img2.png", "subfolder": "", "type": "output"}]}},
+            "status": {"completed": True},
+        }
+    }
+
+    respx.post(f"{COMFYUI_BASE}/api/prompt").mock(side_effect=capture_prompt)
+    respx.get(f"{COMFYUI_BASE}/api/queue").mock(
+        return_value=httpx.Response(200, json=queue_empty)
+    )
+    respx.get(f"{COMFYUI_BASE}/api/history/seed-test-1").mock(
+        return_value=httpx.Response(200, json=mock_history_1)
+    )
+    respx.get(f"{COMFYUI_BASE}/api/history/seed-test-2").mock(
+        return_value=httpx.Response(200, json=mock_history_2)
+    )
+    respx.get(f"{COMFYUI_BASE}/api/view").mock(
+        return_value=httpx.Response(200, content=sample_image_bytes)
+    )
+
+    await generate_image(
+        prompt="a test",
+        count=2,
+        seed=42,
+        output_dir=str(tmp_path),
+    )
+
+    assert submitted_seeds == [42, 43], f"Expected [42, 43], got {submitted_seeds}"
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_generate_image_count_partial_failure_continues(
+    tmp_path, sample_image_bytes, queue_empty, monkeypatch
+):
+    """count=2 where first image fails → error in slot 1, second image succeeds in slot 2."""
+    monkeypatch.setattr(server, "IMAGE_OUTPUT_DIR", str(tmp_path))
+
+    mock_history_2 = {
+        "uuid-ok": {
+            "outputs": {"9": {"images": [{"filename": "img2.png", "subfolder": "", "type": "output"}]}},
+            "status": {"completed": True},
+        }
+    }
+
+    respx.post(f"{COMFYUI_BASE}/api/prompt").mock(
+        side_effect=[
+            httpx.Response(500, json={"error": "GPU OOM"}),   # first fails
+            httpx.Response(200, json={"prompt_id": "uuid-ok"}),  # second succeeds
+        ]
+    )
+    respx.get(f"{COMFYUI_BASE}/api/queue").mock(
+        return_value=httpx.Response(200, json=queue_empty)
+    )
+    respx.get(f"{COMFYUI_BASE}/api/history/uuid-ok").mock(
+        return_value=httpx.Response(200, json=mock_history_2)
+    )
+    respx.get(f"{COMFYUI_BASE}/api/view").mock(
+        return_value=httpx.Response(200, content=sample_image_bytes)
+    )
+
+    result = await generate_image(
+        prompt="a test",
+        count=2,
+        seed=10,
+        output_dir=str(tmp_path),
+    )
+
+    # First: error TextContent only (no ImageContent)
+    # Second: [TextContent, ImageContent]
+    assert len(result) == 3
+    assert result[0].type == "text"
+    assert "500" in result[0].text or "error" in result[0].text.lower()
+    assert result[1].type == "text"
+    assert result[2].type == "image"
+
+    # Only 1 file saved (the successful one)
+    saved_files = list(tmp_path.glob("*.png"))
+    assert len(saved_files) == 1
+
+
+# ---------------------------------------------------------------------------
+# generate_image — existing tests (kept intact)
 # ---------------------------------------------------------------------------
 
 @respx.mock

mcp/webscraper/src/server.py

@@ -3,7 +3,7 @@
 import httpx
 from bs4 import BeautifulSoup
 from html2text import html2text
-from urllib.parse import urljoin
+from urllib.parse import urljoin, quote_plus
 from typing import List, Dict, Tuple
 import re
 import ssl
@@ -28,9 +28,16 @@ def _build_ssl_context() -> ssl.SSLContext:
 
 _SSL_CTX = _build_ssl_context()
 
+_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"
+    )
+}
+
 def _fetch_page(url: str) -> Tuple[httpx.Response, BeautifulSoup]:
     """Shared fetch helper — returns response and parsed soup."""
-    response = httpx.get(url, timeout=10.0, verify=_SSL_CTX)
+    response = httpx.get(url, timeout=10.0, verify=_SSL_CTX, headers=_HEADERS)
     response.raise_for_status()
     soup = BeautifulSoup(response.text, 'lxml')
     return response, soup
@@ -255,5 +262,85 @@ def webscraper_fetch_sitemap(url: str, max_urls: int = 100) -> List[str]:
     except (httpx.RequestError, httpx.HTTPStatusError) as e:
         return [f"Error: {str(e)}"]
 
+@mcp.tool()
+def webscraper_search_hint(query: str, max_results: int = 5) -> Dict:
+    """Search Brave Search and return top results as a scraping hint.
+
+    Use this sparingly — once per research task — to get oriented before
+    scraping individual pages. Returns top result URLs + snippets so you
+    can decide which pages are worth scraping deeply.
+
+    Args:
+        query: Search query (e.g. "MacBook Pro M4 price Germany")
+        max_results: Maximum number of results to return (default: 5)
+
+    Returns:
+        Dict with 'query', 'search_url', 'results' (list of {title, url, snippet}),
+        'result_count', 'hint'
+    """
+    search_url = f"https://search.brave.com/search?q={quote_plus(query)}&source=web"
+    try:
+        _, soup = _fetch_page(search_url)
+
+        results = []
+        seen_urls: set = set()
+
+        # Brave Search result cards: each div.snippet contains title, URL, description
+        for card in soup.select('.snippet'):
+            if len(results) >= max_results:
+                break
+
+            title_el = card.select_one('.snippet-title')
+            url_el = card.select_one('a')
+            desc_el = card.select_one('.snippet-description')
+
+            title = title_el.get_text(strip=True) if title_el else ""
+            url = url_el['href'] if url_el and url_el.get('href') else ""
+            snippet = desc_el.get_text(strip=True) if desc_el else ""
+
+            # Filter: must have a valid http(s) URL
+            if not url or not url.startswith('http'):
+                continue
+
+            # Filter: skip results with no useful content at all
+            if not title and not snippet:
+                continue
+
+            # Deduplicate by URL
+            if url in seen_urls:
+                continue
+            seen_urls.add(url)
+
+            results.append({"title": title, "url": url, "snippet": snippet})
+
+        # Richer hint: title + url + first 120 chars of snippet for AI context
+        if results:
+            hint_parts = []
+            for r in results:
+                part = f"{r['title']} ({r['url']})"
+                if r['snippet']:
+                    part += f": {r['snippet'][:120]}"
+                hint_parts.append(part)
+            hint = " | ".join(hint_parts)
+        else:
+            hint = "No results found"
+
+        return {
+            "query": query,
+            "search_url": search_url,
+            "results": results,
+            "result_count": len(results),
+            "hint": hint,
+        }
+    except (httpx.RequestError, httpx.HTTPStatusError) as e:
+        return {
+            "query": query,
+            "search_url": search_url,
+            "results": [],
+            "result_count": 0,
+            "hint": f"Error: {str(e)}",
+        }
+
+
 if __name__ == "__main__":
     mcp.run(transport="stdio")

mcp/webscraper/tests/test_server.py

@@ -6,7 +6,7 @@ from unittest.mock import MagicMock, patch
 from src.server import (
     webscraper_fetch, webscraper_fetch_links, webscraper_fetch_tables,
     webscraper_fetch_all, webscraper_fetch_section, webscraper_fetch_meta,
-    webscraper_fetch_sitemap, clean_soup, filter_junk_links
+    webscraper_fetch_sitemap, webscraper_search_hint, clean_soup, filter_junk_links
 )
 
 @pytest.fixture
@@ -203,4 +203,197 @@ def test_sitemap_max_urls(mock_get, mock_sitemap_response):
     result = webscraper_fetch_sitemap("https://example.com/sitemap.xml", max_urls=1)
     assert len(result) == 1
 
-# Total: 18 tests covering all tools and edge cases
+
+# --- webscraper_search_hint tests ---
+
+@pytest.fixture
+def mock_brave_response():
+    """Mock Brave Search HTML response with result cards."""
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.text = """
+    <html><body>
+        <div class="snippet">
+            <a href="https://example.com/article1" class="snippet-title">Feynman on Electric Fields</a>
+            <div class="snippet-title">Feynman on Electric Fields</div>
+            <div class="snippet-description">Richard Feynman explains that all matter has an electric field.</div>
+        </div>
+        <div class="snippet">
+            <a href="https://example.com/article2" class="snippet-title">Electric Fields Everywhere</a>
+            <div class="snippet-title">Electric Fields Everywhere</div>
+            <div class="snippet-description">Everything in the universe is surrounded by electric fields.</div>
+        </div>
+        <div class="snippet">
+            <a href="javascript:void(0)" class="snippet-title">JS Junk</a>
+            <div class="snippet-title">JS Junk</div>
+            <div class="snippet-description">Should be filtered out.</div>
+        </div>
+    </body></html>
+    """
+    mock_resp.headers = {"content-type": "text/html"}
+    return mock_resp
+
+
+@pytest.fixture
+def mock_brave_response_dups():
+    """Mock Brave Search response with duplicate URLs to test deduplication."""
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.text = """
+    <html><body>
+        <div class="snippet">
+            <a href="https://example.com/dup">Dup Result A</a>
+            <div class="snippet-title">Dup Result A</div>
+            <div class="snippet-description">First occurrence.</div>
+        </div>
+        <div class="snippet">
+            <a href="https://example.com/dup">Dup Result B</a>
+            <div class="snippet-title">Dup Result B</div>
+            <div class="snippet-description">Second occurrence — same URL.</div>
+        </div>
+        <div class="snippet">
+            <a href="https://example.com/unique">Unique Result</a>
+            <div class="snippet-title">Unique Result</div>
+            <div class="snippet-description">Only once.</div>
+        </div>
+    </body></html>
+    """
+    mock_resp.headers = {"content-type": "text/html"}
+    return mock_resp
+
+
+@pytest.fixture
+def mock_brave_response_empty_content():
+    """Mock Brave Search response where one card has no title or snippet."""
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.text = """
+    <html><body>
+        <div class="snippet">
+            <a href="https://example.com/ghost"></a>
+            <div class="snippet-title"></div>
+            <div class="snippet-description"></div>
+        </div>
+        <div class="snippet">
+            <a href="https://example.com/real">Real Result</a>
+            <div class="snippet-title">Real Result</div>
+            <div class="snippet-description">Has content.</div>
+        </div>
+    </body></html>
+    """
+    mock_resp.headers = {"content-type": "text/html"}
+    return mock_resp
+
+
+@patch('httpx.get')
+def test_webscraper_search_hint_returns_structure(mock_get, mock_brave_response):
+    """Test that search hint returns all required dict fields."""
+    mock_get.return_value = mock_brave_response
+    result = webscraper_search_hint("Feynman electric field")
+    assert isinstance(result, dict)
+    assert "query" in result
+    assert "search_url" in result
+    assert "results" in result
+    assert "result_count" in result
+    assert "hint" in result
+    assert result["query"] == "Feynman electric field"
+
+
+@patch('httpx.get')
+def test_webscraper_search_hint_search_url_encoded(mock_get, mock_brave_response):
+    """Test that search_url uses proper URL encoding (quote_plus, not str.replace)."""
+    mock_get.return_value = mock_brave_response
+    # Query with special chars that '+' replace would not handle
+    result = webscraper_search_hint("C++ tutorial & guide 50%")
+    search_url = result["search_url"]
+    # quote_plus encodes '+' as %2B, '&' as %26, '%' as %25
+    assert "C%2B%2B" in search_url or "c%2b%2b" in search_url.lower()
+    assert "%26" in search_url
+    assert "%25" in search_url
+
+
+@patch('httpx.get')
+def test_webscraper_search_hint_result_count(mock_get, mock_brave_response):
+    """Test that result_count matches the number of results returned."""
+    mock_get.return_value = mock_brave_response
+    result = webscraper_search_hint("Feynman electric field")
+    assert result["result_count"] == len(result["results"])
+
+
+@patch('httpx.get')
+def test_webscraper_search_hint_filters_non_http(mock_get, mock_brave_response):
+    """Test that javascript: URLs are excluded from results."""
+    mock_get.return_value = mock_brave_response
+    result = webscraper_search_hint("Feynman electric field")
+    urls = [r["url"] for r in result["results"]]
+    assert all(u.startswith("http") for u in urls)
+    assert "javascript:void(0)" not in urls
+
+
+@patch('httpx.get')
+def test_webscraper_search_hint_max_results(mock_get, mock_brave_response):
+    """Test max_results limits output."""
+    mock_get.return_value = mock_brave_response
+    result = webscraper_search_hint("Feynman electric field", max_results=1)
+    assert len(result["results"]) <= 1
+    assert result["result_count"] <= 1
+
+
+@patch('httpx.get')
+def test_webscraper_search_hint_deduplicates_urls(mock_get, mock_brave_response_dups):
+    """Test that duplicate URLs are deduplicated — only first occurrence kept."""
+    mock_get.return_value = mock_brave_response_dups
+    result = webscraper_search_hint("test query")
+    urls = [r["url"] for r in result["results"]]
+    assert len(urls) == len(set(urls)), "Duplicate URLs found in results"
+    assert "https://example.com/dup" in urls
+    assert "https://example.com/unique" in urls
+    assert len(urls) == 2  # dup appears once, unique once
+
+
+@patch('httpx.get')
+def test_webscraper_search_hint_filters_empty_content(mock_get, mock_brave_response_empty_content):
+    """Test that cards with no title AND no snippet are excluded."""
+    mock_get.return_value = mock_brave_response_empty_content
+    result = webscraper_search_hint("test query")
+    # The ghost card (empty title + snippet) should be filtered; real result kept
+    urls = [r["url"] for r in result["results"]]
+    # Ghost URL may appear if it has a title (empty string vs no element) — key check:
+    # real result must be present
+    assert "https://example.com/real" in urls
+
+
+@patch('httpx.get')
+def test_webscraper_search_hint_error(mock_get):
+    """Test error handling in search hint — returns all required fields."""
+    mock_get.side_effect = httpx.RequestError("Connection failed")
+    result = webscraper_search_hint("something")
+    assert result["results"] == []
+    assert result["result_count"] == 0
+    assert "Error" in result["hint"]
+    assert "search_url" in result
+    assert "query" in result
+
+
+@patch('httpx.get')
+def test_webscraper_search_hint_hint_includes_snippet(mock_get, mock_brave_response):
+    """Test that the hint string includes snippet content, not just title+url."""
+    mock_get.return_value = mock_brave_response
+    result = webscraper_search_hint("Feynman electric field")
+    # hint should contain snippet text
+    assert "electric field" in result["hint"].lower()
+    assert "No results found" not in result["hint"]
+    assert len(result["hint"]) > 0
+
+
+@patch('httpx.get')
+def test_webscraper_search_hint_hint_format(mock_get, mock_brave_response):
+    """Test that hint uses pipe-separated format with URL in parens."""
+    mock_get.return_value = mock_brave_response
+    result = webscraper_search_hint("Feynman electric field")
+    # Format: "Title (url): snippet | Title2 (url2): snippet2"
+    assert "(" in result["hint"]
+    assert ")" in result["hint"]
+
+
+# Total: 31 tests covering all tools and edge cases

plans/cannabis-club-saas/docs/01-PROJECT-CHARTER.md

@@ -0,0 +1,227 @@
+# CannaManage — Project Charter
+
+**Author:** Patrick Plate  
+**Date:** 2026-04-06  
+**Version:** 1.0  
+**Status:** Draft for Review
+
+---
+
+## 1. Executive Summary
+
+### Vision Statement
+
+> *CannaManage is the compliance backbone for German cannabis social clubs — purpose-built to turn a legally mandated administrative burden into a manageable, auditable, and digitised workflow.*
+
+### The Problem
+
+Germany's **Konsumcannabisgesetz (CanG)**, in force since April 1, 2024, legalised cannabis for personal use and established a framework for **Anbauvereinigungen** (cannabis social clubs / CSCs). Every operating CSC faces mandatory, recurring compliance obligations:
+
+- Track every distribution (recipient, strain, weight, date/time) — by law
+- Enforce quantity limits per member (50g/month for adults, 30g/month for under-21, 25g/day)
+- Maintain batch-level contamination traceability
+- Produce periodic authority reports
+- Designate and track a Prevention Officer (Präventionsbeauftragter)
+- Manage member data under DSGVO
+
+Clubs currently manage this with Excel spreadsheets, pen-and-paper logs, and WhatsApp groups — creating legal risk, audit gaps, and administrative chaos.
+
+### Why Now
+
+The market is less than two years old. **No purpose-built software tooling exists** for German CSCs. The window to establish market leadership is 2026–2027 before larger players notice the niche. First-mover advantage combined with the permanent regulatory moat from CanG compliance requirements makes this the right moment.
+
+### What We Are Building
+
+A **multi-tenant B2B SaaS platform** offering:
+- Club admin portal (member management, distribution logging, stock management, compliance reporting)
+- Member portal (personal quota, distribution history, stock visibility)
+- Built-in CanG compliance enforcement and export tooling
+
+**We are selling compliance management software to licensed, regulated entities. We are not in the cannabis business.**
+
+---
+
+## 2. Project Scope
+
+### 2.1 In Scope — MVP v1
+
+| Area | Features Included |
+|------|-------------------|
+| **Onboarding** | Club registration, setup wizard, admin account creation |
+| **Member Management** | Add/remove members, age verification (18+, 18–21 restricted), contact data |
+| **Distribution Tracking** | Log each handout (member, strain, weight, date/time); enforce daily/monthly limits |
+| **Limit Enforcement** | 25g/day cap, 50g/month (adult), 30g/month (under-21), 10% THC flag |
+| **Stock Management** | Strains, batch tracking, quantity levels |
+| **Admin Dashboard** | Club-level totals: members, distributions this month, stock levels |
+| **Compliance Exports** | Monthly distribution report (PDF + CSV), member list export for inspections |
+| **Contamination Recall** | Flag a batch; system lists all members who received from it |
+| **Prevention Officer** | Store officer contact info and designation date |
+| **Member Portal** | Login with club-issued credentials; view quota, distribution history, stock availability |
+| **Authentication** | Spring Security + JWT; role-based (ADMIN, MEMBER) |
+| **Hosting** | Hetzner VPS (German DC), Docker Compose, PostgreSQL + Flyway |
+
+### 2.2 Explicitly Out of Scope — MVP v1
+
+| Feature | Reason Excluded |
+|---------|-----------------|
+| Public club discovery / "find clubs near you" | **Illegal under CanG §§6–7 advertising ban** |
+| Cannabis e-commerce or payment for cannabis | Illegal; violates positioning |
+| Non-EU data storage (AWS us-east, etc.) | DSGVO violation |
+| Stripe subscription billing | Deferred to Phase 1 (Weeks 9–16) |
+| Email/SMS notifications | v2 feature |
+| Mobile native app (Android/iOS) | v2/v3 feature |
+| Multi-location club support | v3 feature |
+| Legal template marketplace | v3 feature |
+| Next.js/React frontend | v2 migration after revenue justifies investment |
+| Authority portal integrations | v3 feature (portals don't exist yet) |
+
+---
+
+## 3. Stakeholders
+
+| Role | Description | Needs |
+|------|-------------|-------|
+| **Club Admin** *(primary user)* | Vereinsvorstand or designated manager; runs day-to-day club operations | Compliant distribution logging, member management, authority-ready exports |
+| **Club Member** *(secondary user)* | Verified adult member of the Anbauvereinigung | Self-service quota visibility, distribution history, stock availability |
+| **Prevention Officer** *(Präventionsbeauftragter, tertiary user)* | Legally required role; may or may not be the admin | Contact info tracked in system; receives relevant reports |
+| **Patrick Plate** *(developer & product owner)* | Solo developer; nights/weekends; ADP Germany full-time | Minimal learning overhead; fast path to first revenue; legally sound product |
+
+---
+
+## 4. Success Criteria
+
+MVP is considered complete when all of the following are true:
+
+| # | Criterion | Measure |
+|---|-----------|---------|
+| 1 | **Core compliance loop working** | Admin can log a distribution → system enforces limits → admin exports PDF report for authorities |
+| 2 | **Multi-tenant isolation** | Two clubs' data are completely isolated — no cross-tenant data leakage |
+| 3 | **Member portal live** | Member can log in with club-issued credentials and view their quota + history |
+| 4 | **Contamination recall functional** | Admin flags a batch; system returns full recipient list in < 2 seconds |
+| 5 | **Deployment stable** | Platform runs on Hetzner VPS via Docker Compose with uptime ≥ 99% over 30-day beta |
+| 6 | **Beta validation** | 3–5 real club admins have used the system and provided written feedback |
+| 7 | **Legal review passed** | No features violate CanG advertising ban; DSGVO AVV in place before any live data |
+| 8 | **Zero PII on non-EU infrastructure** | All data confirmed to reside in Hetzner DE datacenter |
+
+---
+
+## 5. Constraints & Assumptions
+
+### Constraints
+
+| Type | Constraint |
+|------|-----------|
+| **Legal** | CanG §§6–7 imposes a **total advertising and sponsoring ban** on cannabis AND Anbauvereinigungen — no public club discovery feature, ever |
+| **Legal** | DSGVO requires EU hosting, data processing agreements (AVV), member data export/deletion capability |
+| **Technical (MVP)** | Frontend is PrimeFaces + JSF — Patrick's existing expertise; no new framework learning in Phase 0 |
+| **Technical** | Multi-tenancy via `tenant_id` on all JPA entities — no row-level security shortcuts |
+| **Team** | Solo developer — Patrick; nights and weekends only; full-time at ADP Germany |
+| **Timeline** | Phase 0 target: 8 weeks; Phase 1 target: 16 weeks total from project start |
+| **Budget** | Infrastructure: Hetzner €5–20/month; no team salary cost |
+
+### Assumptions
+
+- German CSCs are willing to pay €29–€79/month for compliance software
+- Stripe will process subscriptions for compliance software (not cannabis sales) without restriction
+- Spring Boot 3.x is sufficiently adjacent to Patrick's Jakarta EE expertise to use without major ramp-up
+- PrimeFaces MVP is sufficient for beta validation — UI polish deferred to v2
+- CanG remains in force and CSC licensing continues in all major Bundesländer
+
+---
+
+## 6. Risk Register
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|-----------|
+| **Advertising ban reinterpreted to include B2B SaaS** | Low | High | Obtain legal opinion from cannabis law specialist before launch (€300–500); strict no-discovery design enforced at architecture level |
+| **New German government rolls back or tightens CanG** | Medium | High | Modular architecture — compliance-only features can be extracted and pivoted to a general club management tool |
+| **Stripe blocks cannabis-adjacent businesses** | Medium | High | Position as "Vereinsverwaltungs-Software" (club management software); never process cannabis payments; test with Stripe before public launch |
+| **Clubs fail / licenses revoked** | Medium | Medium | Diversified customer base; per-month billing (easy cancellation); no annual lock-in required for MVP |
+| **DSGVO violation** | Low | Very High | EU-only hosting (Hetzner DE), DPA/AVV agreements before any live data, DSGVO-compliant privacy policy in German, member data export/deletion API from day one |
+
+---
+
+## 7. Budget & Resources
+
+| Item | Cost | Notes |
+|------|------|-------|
+| **Development** | €0 (Patrick's time) | Nights/weekends; valued at opportunity cost only |
+| **Infrastructure — Hetzner VPS** | €5–20/month | German DC; scales with load |
+| **Infrastructure — PostgreSQL** | €0 (self-hosted on VPS) | Managed DB upgrade available when needed |
+| **Legal opinion** | €300–500 (one-time) | Cannabis law specialist; pre-launch requirement |
+| **Domain (cannamanage.de)** | ~€15/year | To be registered |
+| **Stripe fees** | 1.4% + €0.25 per transaction | EU cards; only on paid subscriptions |
+| **Email (Resend / Jakarta Mail)** | €0–10/month | Resend free tier for low volume |
+| **Sentry monitoring** | €0 (free tier) | Error tracking; Java SDK |
+| **Total pre-launch** | **~€600–700** | Including legal opinion |
+
+---
+
+## 8. Timeline Overview
+
+```mermaid
+gantt
+    title CannaManage Development Roadmap
+    dateFormat  YYYY-MM-DD
+    axisFormat  %b %Y
+
+    section Phase 0 — Foundation
+    Spring Boot setup + JPA entities        :p0a, 2026-04-07, 2w
+    Core REST API (member, distribution)    :p0b, after p0a, 2w
+    Admin portal PrimeFaces                 :p0c, after p0b, 2w
+    Limit enforcement + PDF report          :p0d, after p0c, 2w
+
+    section Phase 1 — MVP
+    Member portal                           :p1a, after p0d, 2w
+    Stock management + contamination recall :p1b, after p1a, 2w
+    Stripe billing integration              :p1c, after p1b, 2w
+    DSGVO + beta launch (5 clubs)           :p1d, after p1c, 2w
+
+    section Phase 2 — Launch
+    Payment flows + email notifications     :p2a, after p1d, 4w
+    Marketing site + legal review           :p2b, after p2a, 4w
+    Soft launch to club community           :milestone, after p2b, 0d
+
+    section Phase 3 — Growth
+    PrimeFaces → Next.js migration          :p3a, 2026-12-01, 8w
+    PWA mobile                              :p3b, after p3a, 4w
+    Template marketplace + referral         :p3c, after p3b, 8w
+```
+
+---
+
+## 9. Legal Framework
+
+### Key CanG Provisions
+
+| Provision | Content | Product Implication |
+|-----------|---------|---------------------|
+| **§2 CanG** | Definitions — Anbauvereinigung, Mitglied | Data model must align with statutory definitions of club and member |
+| **§§15–26 CanG** | Anbauvereinigungen — formation, rights, obligations | Club registration flow must capture legally required club attributes |
+| **§22 CanG** | Distribution limits: 25g/day, 50g/month per adult member | Hard enforcement in distribution service; cannot be overridden by admin |
+| **§23 CanG** | Under-21 restrictions: 30g/month max, max 10% THC | Age flag on member entity; separate limit enforcement path for restricted category |
+| **§§6–7 CanG** | **Total advertising and sponsoring ban** for cannabis and Anbauvereinigungen | **No public club discovery. No stock visible to non-members. No club listings.** Architecture constraint. |
+| **§26 CanG** | Documentation and reporting obligations | Compliance export module is a legal requirement, not an optional feature |
+| **§27 CanG** | Prevention officer requirements | Prevention officer fields mandatory in club setup; not optional |
+
+### DSGVO Obligations
+
+- All personal data stored on EU infrastructure (Hetzner DE)
+- Data processing agreement (AVV) required with each club before live data entry
+- Member data export endpoint required (Art. 20 DSGVO — data portability)
+- Member data deletion endpoint required (Art. 17 DSGVO — right to erasure)
+- Privacy policy in German, DSGVO-compliant, published before launch
+
+---
+
+## 10. Sign-Off
+
+| Role | Name | Date |
+|------|------|------|
+| **Project Sponsor** | Patrick Plate | 2026-04-06 |
+| **Lead Developer** | Patrick Plate | 2026-04-06 |
+| **Product Owner** | Patrick Plate | 2026-04-06 |
+
+---
+
+*Next review date: 2026-05-01 | Source: [STRATEGY.md](../STRATEGY.md)*

plans/cannabis-club-saas/docs/02-USER-STORIES.md

@@ -0,0 +1,467 @@
+# CannaManage — User Stories & Acceptance Criteria
+
+**Author:** Patrick Plate  
+**Date:** 2026-04-06  
+**Version:** 1.0  
+**Status:** Draft for Review
+
+---
+
+## MoSCoW Summary
+
+| Priority | Count | Release Target | Description |
+|----------|-------|----------------|-------------|
+| 🔴 **Must Have** | 14 (US-001–014) | MVP v1 | Core compliance loop; legally required features |
+| 🟡 **Should Have** | 4 (US-015–018) | v2 | Growth and retention features |
+| 🟢 **Could Have** | 4 (US-019–022) | v3 | Scale and differentiation features |
+| ⚫ **Won't Have (MVP)** | 3 (US-023–025) | Never / Post-legal-review | Explicitly excluded — legal or strategic |
+
+---
+
+## Must Have — MVP v1
+
+### Club Admin Stories
+
+---
+
+### US-001: Register Club and Complete Setup Wizard
+
+**As a** Club Admin, **I want to** register my Anbauvereinigung and complete a guided setup wizard, **so that** my club is correctly configured with all legally required attributes before any members are added.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can register with email + password; email confirmation required before accessing the system
+- [ ] AC2: Setup wizard collects: club name, registered address, founding date, Vereinsregisternummer (if available), maximum membership count
+- [ ] AC3: Wizard requires designation of a Prevention Officer (name, contact) — field is mandatory, cannot be skipped
+- [ ] AC4: Wizard requires acceptance of DSGVO data processing agreement (AVV) before any member data can be entered
+- [ ] AC5: Completing the wizard provisions the club's isolated tenant environment (all subsequent data scoped to this club only)
+- [ ] AC6: Admin receives a welcome email with login link after successful setup
+- [ ] AC7: Incomplete wizard state is saved — admin can resume from last completed step
+
+**Notes:** The AVV acceptance (AC4) is a legal prerequisite for handling member personal data under DSGVO. It must be timestamped and stored.
+
+---
+
+### US-002: Add and Remove Members with Age Verification
+
+**As a** Club Admin, **I want to** add and remove club members with age verification, **so that** the member roster is accurate and the system can apply the correct distribution limits per member.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can add a member with: full name, date of birth, email (optional), membership start date, member ID (auto-generated or manual)
+- [ ] AC2: System rejects members with date of birth indicating age < 18
+- [ ] AC3: Members aged 18–21 are automatically flagged as "Restricted (§23 CanG)" — this flag drives reduced quantity limits
+- [ ] AC4: Admin can deactivate (soft-delete) a member; deactivated members cannot receive distributions but their historical records are preserved
+- [ ] AC5: Admin can permanently delete a member record (DSGVO Art. 17 right to erasure); system warns if member has distribution history and requires explicit confirmation
+- [ ] AC6: Member list is searchable by name and filterable by status (active / restricted / deactivated)
+- [ ] AC7: Total active member count is visible on the dashboard and in the member list header
+
+**Notes:** Hard deletion (AC5) must cascade correctly — distribution records referencing the member must be anonymised, not deleted, to preserve the compliance audit trail.
+
+---
+
+### US-003: Record a Distribution
+
+**As a** Club Admin, **I want to** record each cannabis distribution to a member, **so that** every handout is documented as required by §26 CanG and the member's consumption is tracked.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can log a distribution by selecting: member (search/autocomplete), strain, weight in grams (decimal, e.g. 3.5g), batch, date and time
+- [ ] AC2: System pre-fills date/time with current timestamp; admin can override
+- [ ] AC3: If the distribution would cause the member to exceed their daily limit (25g), the system displays a prominent warning and requires explicit override confirmation
+- [ ] AC4: If the distribution would cause the member to exceed their monthly limit (50g adult / 30g restricted), the system **blocks** the entry and displays the reason
+- [ ] AC5: For restricted members (§23), system additionally validates that the selected strain's THC percentage is ≤ 10% (if THC% is recorded on the batch)
+- [ ] AC6: Successfully saved distributions appear immediately in the distribution log and update the member's monthly counter
+- [ ] AC7: Distribution records are immutable after creation — admin can only add a correction note, not edit the original record
+
+**Notes:** Immutability (AC7) is essential for audit integrity. Correction notes are the appropriate mechanism for errors.
+
+---
+
+### US-004: View and Enforce Distribution Limits
+
+**As a** Club Admin, **I want to** view each member's current distribution totals and remaining quota, **so that** I can verify limits at a glance before and after recording distributions.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Each member's detail view shows: distributions this month (total grams), daily total for today, remaining monthly quota, and limit category (Adult 50g / Restricted 30g)
+- [ ] AC2: Remaining quota is displayed as a progress bar (visual indicator of how close to the limit)
+- [ ] AC3: Members who have reached or exceeded their monthly limit are visually flagged in the member list (e.g., red badge)
+- [ ] AC4: Members who have consumed > 80% of their monthly limit show a warning indicator (e.g., amber badge)
+- [ ] AC5: Monthly counters reset automatically on the first of each calendar month
+- [ ] AC6: System applies §22 limits (50g/month, 25g/day) for adults and §23 limits (30g/month) for restricted members — these cannot be changed by the admin
+
+**Notes:** The limits in AC6 are statutory and must be hardcoded, not configurable per club.
+
+---
+
+### US-005: Manage Stock (Strains, Quantities, Batches)
+
+**As a** Club Admin, **I want to** manage my club's cannabis stock including strains, batch information, and quantities, **so that** I know what is available for distribution and can track batch provenance for contamination purposes.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can create a strain with: name, THC% (optional), CBD% (optional), variety type (Indica/Sativa/Hybrid)
+- [ ] AC2: Admin can create a batch linked to a strain with: batch ID (auto-generated), quantity in grams, harvest date (optional), grow cycle reference (optional)
+- [ ] AC3: Each distribution recorded reduces the associated batch's available quantity
+- [ ] AC4: Admin can manually adjust stock quantity with a reason note (e.g., "lab sample", "disposal")
+- [ ] AC5: Admin is warned (but not blocked) when a batch's available quantity drops below a configurable threshold (default: 100g)
+- [ ] AC6: Stock overview page shows all active batches with: strain name, batch ID, quantity available, quantity distributed to date
+- [ ] AC7: Depleted batches (quantity = 0) are automatically moved to an "archived" view
+
+**Notes:** Batch tracking is required for contamination recall (US-009). The batch ID must be immutable once created.
+
+---
+
+### US-006: View Admin Dashboard
+
+**As a** Club Admin, **I want to** see a summary dashboard when I log in, **so that** I have an at-a-glance overview of club activity and can identify anything requiring attention.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Dashboard displays: total active members, members at/near their monthly limit (count), total distributions this calendar month (grams), active stock level (total grams across all batches)
+- [ ] AC2: Dashboard shows a count of members in the "restricted §23" category separately
+- [ ] AC3: Dashboard highlights any batches flagged as contaminated (contamination alert count)
+- [ ] AC4: Dashboard includes a recent activity feed (last 10 distributions: member name, strain, weight, time)
+- [ ] AC5: All dashboard data reflects the admin's own club only — never cross-tenant data
+- [ ] AC6: Dashboard loads in < 3 seconds on Hetzner VPS hardware
+
+**Notes:** Keep the dashboard simple for MVP — a single page with widgets. No charts required for v1.
+
+---
+
+### US-007: Export Monthly Compliance Report (PDF + CSV)
+
+**As a** Club Admin, **I want to** export a monthly compliance report as PDF and CSV, **so that** I can fulfil my documentation and reporting obligations under §26 CanG.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can select any calendar month/year and generate a compliance report
+- [ ] AC2: PDF report contains: club name, reporting period, total distributions (count and weight), distribution detail table (member ID, strain, batch, weight, date/time), stock summary
+- [ ] AC3: Member names in the PDF are replaced with member IDs to minimise PII exposure in the report document (actual name lookup available to the club separately)
+- [ ] AC4: CSV export contains full distribution log for the selected period with headers: member_id, strain, batch_id, weight_g, distribution_date, distribution_time
+- [ ] AC5: PDF is generated server-side using iText 7 (no client-side rendering dependency)
+- [ ] AC6: Export completes in < 10 seconds for a month with up to 5,000 distribution records
+- [ ] AC7: Generated reports are not stored on the server — they are streamed directly to the browser as a download
+
+**Notes:** Not storing reports (AC7) reduces data exposure risk. The club is responsible for retaining their own copies.
+
+---
+
+### US-008: Export Member List for Inspections
+
+**As a** Club Admin, **I want to** export the current member list, **so that** I can present it to authorities during an inspection as required by law.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can export the active member list as PDF and CSV at any time
+- [ ] AC2: Export includes: member ID, full name, date of birth, age category (Adult/Restricted §23), membership start date, current membership status
+- [ ] AC3: Export is timestamped with the generation date/time in the document
+- [ ] AC4: Admin is shown a DSGVO reminder before downloading (this document contains personal data — handle per your privacy obligations)
+- [ ] AC5: Export includes the club name and address in the header
+- [ ] AC6: Only active members are included by default; admin can optionally include deactivated members
+
+**Notes:** This document contains significant PII. The DSGVO reminder (AC4) is important to keep admins legally aware.
+
+---
+
+### US-009: Trigger Contamination Alert for a Batch
+
+**As a** Club Admin, **I want to** flag a batch as contaminated and immediately see all members who received from it, **so that** I can notify affected members and fulfil my contamination traceability obligations under CanG.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can mark any batch as "contaminated" with a reason note and timestamp
+- [ ] AC2: Immediately upon flagging, system displays a list of all members who received distributions from the contaminated batch (name, member ID, total grams received, dates received)
+- [ ] AC3: Contaminated batches are removed from the active distribution interface — admin cannot select them for new distributions
+- [ ] AC4: The dashboard shows a contamination alert badge whenever any active batch is flagged
+- [ ] AC5: Admin can export the affected member list as PDF and CSV (for authority notification)
+- [ ] AC6: Contamination status is immutable — once flagged, only a senior action (with confirmation) can reverse it; reversal is logged with reason
+
+**Notes:** Contamination traceability is explicitly required by CanG. Response speed matters — the affected member list (AC2) must display without delay.
+
+---
+
+### US-010: Manage Prevention Officer Information
+
+**As a** Club Admin, **I want to** record and update Prevention Officer (Präventionsbeauftragter) information, **so that** my club meets the mandatory requirement of §27 CanG.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Club profile includes a Prevention Officer section with fields: full name, contact email, contact phone, designation date
+- [ ] AC2: All four fields are required — the system warns if any is empty and marks the section as incomplete
+- [ ] AC3: Admin can update the Prevention Officer at any time; previous officer entries are retained in a change log (name, designation period)
+- [ ] AC4: The compliance report export (US-007) includes the current Prevention Officer name and contact in its header
+- [ ] AC5: Setup wizard (US-001) cannot be completed without entering Prevention Officer information
+
+**Notes:** This is a statutory requirement, not optional. AC5 enforces that clubs cannot operate on the platform without this data.
+
+---
+
+### Member Portal Stories
+
+---
+
+### US-011: Login with Club-Issued Credentials
+
+**As a** Club Member, **I want to** log in to the member portal using credentials issued by my club, **so that** I can access my personal information without the club admin needing to be present.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can generate login credentials (username + temporary password) for a member from the member management screen
+- [ ] AC2: Member receives credentials via a secure channel (displayed to admin for manual handoff in MVP; email in v2)
+- [ ] AC3: Member is required to change their temporary password on first login
+- [ ] AC4: Member login is scoped to their club only — they cannot access any other club's data or member list
+- [ ] AC5: Failed login attempts are rate-limited (5 attempts, then 15-minute lockout)
+- [ ] AC6: Member sessions expire after 24 hours of inactivity
+- [ ] AC7: Members cannot register themselves — accounts are always created by the Club Admin
+
+**Notes:** AC7 is critical for CanG compliance — only verified, age-checked members should have portal access.
+
+---
+
+### US-012: View Personal Distribution History
+
+**As a** Club Member, **I want to** view my personal distribution history, **so that** I can track what I have received from the club.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Member can view all their distributions in reverse chronological order: date/time, strain, weight (grams), batch ID
+- [ ] AC2: Current calendar month distributions are shown first, with a clear monthly subtotal
+- [ ] AC3: Member can filter history by month/year
+- [ ] AC4: Member sees only their own distribution history — no other member's data is accessible
+- [ ] AC5: History is read-only — members cannot edit or delete distribution records
+
+---
+
+### US-013: View Current Stock Availability
+
+**As a** Club Member, **I want to** see what strains are currently available at the club, **so that** I know what I can request on my next visit.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Member portal shows a stock list with: strain name, variety type (Indica/Sativa/Hybrid), THC% (if recorded), availability status (Available / Low Stock / Unavailable)
+- [ ] AC2: Exact batch quantities are NOT shown to members — only availability status
+- [ ] AC3: Only strains with available stock (quantity > 0) are shown as "Available"
+- [ ] AC4: Strains with stock below the admin-configured low-stock threshold are shown as "Low Stock"
+- [ ] AC5: For restricted members (§23 CanG), strains with THC > 10% are shown with a "Not available to you" indicator rather than hidden (transparency about why)
+- [ ] AC6: Stock view is refreshed in real time — no stale cache longer than 5 minutes
+
+**Notes:** AC2 is important — showing exact quantities could constitute advertising for the club's stock. Only availability status is shown.
+
+---
+
+### US-014: View Remaining Monthly Quota
+
+**As a** Club Member, **I want to** see my remaining monthly quota, **so that** I can plan my distributions and stay within my legal limits.
+
+**Priority:** Must Have  
+**Acceptance Criteria:**
+- [ ] AC1: Member portal homepage prominently displays: consumed this month (grams), remaining quota (grams), monthly limit (grams), days remaining in current month
+- [ ] AC2: Quota is displayed as a progress bar with colour coding: green (< 50% used), amber (50–80% used), red (> 80% used)
+- [ ] AC3: Members in the restricted §23 category see their 30g/month limit (not the 50g adult limit)
+- [ ] AC4: Daily limit status is also visible: consumed today (grams) vs. 25g daily cap
+- [ ] AC5: Quota resets display on the first of each calendar month — confirmed visually (e.g., "Resets in X days")
+
+---
+
+## Should Have — v2
+
+---
+
+### US-015: Process Membership Fee Payments via Stripe
+
+**As a** Club Admin, **I want to** collect membership fees from members via Stripe, **so that** fee collection is automated and documented without manual bank transfers.
+
+**Priority:** Should Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can configure an annual membership fee amount for their club
+- [ ] AC2: Members can pay via Stripe-hosted checkout (card payment)
+- [ ] AC3: Stripe subscription or one-time payment for annual fee — admin configures which model
+- [ ] AC4: Payment confirmation is logged against the member record with date and amount
+- [ ] AC5: Admin can view payment status per member (paid / pending / overdue)
+- [ ] AC6: No cannabis product payments are ever processed through this system — fee is for club membership only
+
+**Notes:** Stripe position: membership fees for registered non-profit clubs (Vereinsbeiträge) are standard use case. AC6 must be enforced at system design level.
+
+---
+
+### US-016: Manage Automated Waiting List
+
+**As a** Club Admin, **I want to** manage a waiting list for new membership applicants, **so that** I can process applications in order while respecting the club's maximum membership count.
+
+**Priority:** Should Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can set a maximum member count for the club (from setup wizard or settings)
+- [ ] AC2: When member count reaches maximum, new applicants are added to a waiting list with timestamp
+- [ ] AC3: Waiting list is FIFO — applicants are offered membership in order of application
+- [ ] AC4: Admin can notify the next waiting list applicant (email notification — v2 dependency)
+- [ ] AC5: Admin can remove applicants from the waiting list
+- [ ] AC6: Waiting list count is visible on the admin dashboard
+
+---
+
+### US-017: Receive Email and SMS Notifications
+
+**As a** Club Member, **I want to** receive email (and optionally SMS) notifications for key events, **so that** I am informed without needing to log in to the portal.
+
+**Priority:** Should Have  
+**Acceptance Criteria:**
+- [ ] AC1: Member receives email notification when their distribution is recorded by the admin
+- [ ] AC2: Member receives email when their monthly quota reaches 80% consumed
+- [ ] AC3: Member receives email when a batch they received from is flagged as contaminated
+- [ ] AC4: Admin receives email when any member's quota is exceeded (should not happen, but safety net)
+- [ ] AC5: SMS notifications are optional and require member opt-in; email is default
+- [ ] AC6: All notification emails are sent in German (language is not configurable in v2)
+- [ ] AC7: Members can manage notification preferences (opt out of non-mandatory notifications)
+
+---
+
+### US-018: Track Multi-Strain Grow Cycles
+
+**As a** Club Admin, **I want to** track grow cycles linked to batches, **so that** I have full provenance from grow start to distribution.
+
+**Priority:** Should Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can create a grow cycle with: cycle ID, strain, start date, expected harvest date, grow area (optional), notes
+- [ ] AC2: Batches can be linked to a grow cycle
+- [ ] AC3: Grow cycle view shows: all batches produced, total yield, grow duration
+- [ ] AC4: Closed grow cycles (harvest complete) are archived but remain searchable
+- [ ] AC5: Grow cycle data is included in the monthly compliance report (batch provenance section)
+
+---
+
+## Could Have — v3
+
+---
+
+### US-019: Access Mobile PWA
+
+**As a** Club Member, **I want to** use CannaManage on my smartphone without installing an app, **so that** I can check my quota and stock on the go.
+
+**Priority:** Could Have  
+**Acceptance Criteria:**
+- [ ] AC1: The member portal is fully responsive and usable on mobile viewport sizes (320px and up)
+- [ ] AC2: The app can be added to the home screen (PWA manifest, service worker, offline cache for quota display)
+- [ ] AC3: Core member portal features (quota, distribution history, stock view) work in offline mode with cached data
+- [ ] AC4: Admin portal is also responsive (admin-on-the-go distribution logging)
+- [ ] AC5: No app store submission required — pure PWA
+
+---
+
+### US-020: Support Multi-Location Club
+
+**As a** Club Admin, **I want to** manage a club with multiple distribution locations, **so that** members can pick up from different sites and all distributions are consolidated.
+
+**Priority:** Could Have  
+**Acceptance Criteria:**
+- [ ] AC1: Admin can define multiple locations (name, address) for one club
+- [ ] AC2: Distributions are recorded with a location tag
+- [ ] AC3: Stock is managed per location or shared — admin configures which model
+- [ ] AC4: Compliance reports can be generated per location or consolidated for the whole club
+- [ ] AC5: Members are assigned a primary location but can receive from any location within quota limits
+
+---
+
+### US-021: Download Legal Document Templates
+
+**As a** Club Admin, **I want to** download standardised legal document templates (Satzung, Jugendschutzkonzept), **so that** I can fulfil my legal obligations without hiring a lawyer for every document.
+
+**Priority:** Could Have  
+**Acceptance Criteria:**
+- [ ] AC1: Template library is accessible from the admin portal (separate from compliance exports)
+- [ ] AC2: Available templates include: Vereinssatzung (club charter), Jugendschutzkonzept (youth protection concept), DSGVO Datenschutzerklärung
+- [ ] AC3: Templates are pre-filled with club-specific data (name, address, Prevention Officer) where applicable
+- [ ] AC4: Templates are available as DOCX (editable) and PDF (final version)
+- [ ] AC5: Template library is a paid add-on (€49 one-time or included in Professional/Enterprise plan)
+
+---
+
+### US-022: Integrate with Authority Reporting Portals
+
+**As a** Club Admin, **I want to** submit compliance reports directly to authority portals via CannaManage, **so that** I save time and avoid transcription errors in authority submissions.
+
+**Priority:** Could Have  
+**Acceptance Criteria:**
+- [ ] AC1: System can detect available authority portals by Bundesland (state)
+- [ ] AC2: Admin can initiate a report submission from within CannaManage
+- [ ] AC3: Submission status is tracked (submitted, acknowledged, rejected) per report
+- [ ] AC4: System retries failed submissions automatically (up to 3 times)
+- [ ] AC5: This feature is only activated once at least one Bundesland has a machine-readable submission portal
+
+**Notes:** Authority portals may not exist in v3 timeline — this is aspirational and depends on government digitalisation progress.
+
+---
+
+## Won't Have — MVP (Explicitly Excluded)
+
+---
+
+### US-023: Public Club Discovery — "Find Clubs Near You"
+
+**As a** Public User, I want to find cannabis clubs near my location.
+
+**Priority:** Won't Have (MVP)  
+**Reason:** **Explicitly illegal under CanG §§6–7.** The advertising and sponsoring ban covers any feature that functions as advertising for Anbauvereinigungen to the general public. A public club directory constitutes advertising for clubs. This feature will never be built in any form on this platform.
+
+**Acceptance Criteria:** *None — this feature is permanently excluded.*
+
+**Notes:** This is not a commercial decision. It is a **legal constraint** hardcoded into the product architecture. No public-facing club listing, no map, no search, no "register your club publicly."
+
+---
+
+### US-024: Cannabis E-Commerce or Payment for Cannabis Products
+
+**As a** Club Member, I want to purchase cannabis through the CannaManage platform.
+
+**Priority:** Won't Have (MVP)  
+**Reason:** **Illegal.** Cannabis sales are not the legal model for Anbauvereinigungen under CanG. Payment for cannabis products would violate German law and immediately trigger Stripe account termination. CannaManage processes membership fee payments only — not cannabis product payments, ever.
+
+**Acceptance Criteria:** *None — permanently excluded.*
+
+---
+
+### US-025: Non-EU Data Storage
+
+**As a** Club Admin, I want my club's data stored on the cheapest/fastest infrastructure, including non-EU servers.
+
+**Priority:** Won't Have (MVP)  
+**Reason:** **DSGVO violation.** Club member data includes personal data (name, date of birth, consumption records). Storing this outside the EU without a valid adequacy decision or standard contractual clauses violates Art. 44–49 DSGVO. All data remains on Hetzner DE datacenters.
+
+**Acceptance Criteria:** *None — permanently excluded.*
+
+---
+
+## Acceptance Criteria Traceability Matrix
+
+| Story | Role | Phase | Legal Basis | Key Risk |
+|-------|------|-------|-------------|----------|
+| US-001 | Club Admin | MVP | DSGVO (AVV) | Clubs operating without AVV |
+| US-002 | Club Admin | MVP | §22–23 CanG | Under-21 age verification gaps |
+| US-003 | Club Admin | MVP | §26 CanG | Distribution limit bypass |
+| US-004 | Club Admin | MVP | §22–23 CanG | Incorrect limit category applied |
+| US-005 | Club Admin | MVP | §26 CanG (batch traceability) | Inaccurate stock → wrong quota available |
+| US-006 | Club Admin | MVP | — | Cross-tenant data leak |
+| US-007 | Club Admin | MVP | §26 CanG | Incomplete report → authority rejection |
+| US-008 | Club Admin | MVP | §26 CanG | Outdated member list at inspection |
+| US-009 | Club Admin | MVP | CanG (contamination traceability) | Delayed recall notification |
+| US-010 | Club Admin | MVP | §27 CanG | Missing officer → club licence risk |
+| US-011 | Club Member | MVP | DSGVO | Unauthorised member account creation |
+| US-012 | Club Member | MVP | DSGVO (Art. 15 access) | Cross-member data exposure |
+| US-013 | Club Member | MVP | §§6–7 CanG (no advertising) | Over-disclosure of stock data |
+| US-014 | Club Member | MVP | §22–23 CanG | Member unaware of impending limit breach |
+| US-015 | Club Admin | v2 | — | Stripe cannabis-adjacent policy |
+| US-016 | Club Admin | v2 | — | Waiting list ordering errors |
+| US-017 | Club Member | v2 | DSGVO (email marketing consent) | Spam / opt-out compliance |
+| US-018 | Club Admin | v2 | §26 CanG (provenance) | Batch-grow linkage gaps |
+| US-019 | Club Member | v3 | — | Offline cache staleness |
+| US-020 | Club Admin | v3 | — | Stock isolation complexity |
+| US-021 | Club Admin | v3 | — | Template legal accuracy |
+| US-022 | Club Admin | v3 | §26 CanG | Portal API non-existence |
+| US-023 | *(none)* | Never | **Illegal §§6–7 CanG** | Platform shutdown risk |
+| US-024 | *(none)* | Never | **Illegal** | Stripe termination + criminal liability |
+| US-025 | *(none)* | Never | **DSGVO Art. 44–49** | Regulatory fine + club data breach |
+
+---
+
+*Source: [STRATEGY.md](../STRATEGY.md) | Related: [01-PROJECT-CHARTER.md](./01-PROJECT-CHARTER.md)*

plans/cannabis-club-saas/docs/03-ARCHITECTURE.md

@@ -0,0 +1,504 @@
+# 03 — System Architecture
+
+**Project:** CannaManage — B2B SaaS for German Cannabis Social Clubs (Anbauvereinigungen)  
+**Phase:** 2 of 5 — Architecture & Data Model  
+**Stack:** Spring Boot 3.x (Java 21) · JPA/Hibernate · PostgreSQL · PrimeFaces JSF MVP → Next.js v2  
+**Last updated:** 2026-04-06
+
+---
+
+## 1. Architecture Overview
+
+```mermaid
+graph TD
+    AdminBrowser["🖥️ Browser — Admin Portal"]
+    MemberBrowser["🖥️ Browser — Member Portal"]
+
+    JSF["PrimeFaces / JSF Frontend\n(Spring MVC embedded)"]
+
+    AdminBrowser -->|HTTP/S| JSF
+    MemberBrowser -->|HTTP/S| JSF
+
+    JSF -->|REST calls| Backend
+
+    subgraph Backend ["☕ Spring Boot 3.x Application (Java 21)"]
+        REST["REST API Layer\n/api/v1/"]
+        Service["Service Layer\n(ComplianceService, ReportService…)"]
+        JPA["JPA / Hibernate\nRepositories"]
+        Security["Spring Security + JWT\nTenant Interceptor"]
+
+        REST --> Service
+        Service --> JPA
+        Security --> REST
+    end
+
+    JPA -->|JDBC| PG[("🐘 PostgreSQL 16\nmulti-tenant via tenant_id")]
+    Backend -->|Stripe Java SDK| Stripe["💳 Stripe\n(payment processing)"]
+    Backend -->|Jakarta Mail| Mail["📧 Jakarta Mail\n(email notifications)"]
+    Backend -->|iText 7| PDF["📄 iText 7\n(PDF report generation)"]
+
+    Flyway["🔄 Flyway\n(DB migrations)"] -->|applies migrations| PG
+
+    subgraph Hetzner ["🖧 Hetzner VPS — Docker Compose"]
+        Backend
+        PG
+        Nginx["🔒 Nginx\n(reverse proxy + TLS)"]
+    end
+
+    JSF --> Nginx
+    Nginx --> Backend
+```
+
+### Component Responsibilities
+
+| Component | Technology | Role |
+|---|---|---|
+| Admin Portal | PrimeFaces JSF (→ Next.js v2) | Club management UI |
+| Member Portal | PrimeFaces JSF (→ Next.js v2) | Member quota & history UI |
+| REST API | Spring Boot 3.x / Spring MVC | All business logic endpoints |
+| Auth | Spring Security 6 + JJWT | Stateless JWT authentication |
+| ORM | JPA / Hibernate 6 | Entity persistence, tenant filtering |
+| Database | PostgreSQL 16 | Primary data store (multi-tenant) |
+| Migrations | Flyway | Versioned schema management |
+| Payments | Stripe Java SDK | Club subscription billing |
+| Email | Jakarta Mail / Spring Mail | Welcome emails, recall alerts |
+| PDF | iText 7 | Compliance report generation |
+| Hosting | Hetzner CX21 VPS + Docker Compose | Production deployment |
+
+---
+
+## 2. Multi-Tenancy Strategy
+
+### Approach: Shared Schema with Row-Level Filtering
+
+Every JPA entity carries a `tenant_id` column (UUID, `NOT NULL`). A single PostgreSQL database hosts all clubs — row-level filtering enforces data isolation at the application layer.
+
+**Why shared schema (not separate schema/DB per tenant)?**
+- Lower operational overhead for an MVP with < 500 clubs
+- Single Flyway migration path across all tenants
+- Simpler connection pooling (one pool, not N)
+- Acceptable security risk when `tenant_id` filter is enforced at the service layer
+
+### Tenant Resolution
+
+```
+HTTP Request
+    └─ Spring Security Filter: extract JWT → resolve tenant_id
+         └─ TenantContext.setCurrentTenant(tenantId)   // ThreadLocal
+              └─ JPA @Where filter applied on every entity query
+```
+
+### Code Pattern — Tenant-Aware Base Entity
+
+```java
+// AbstractTenantEntity.java (pseudocode)
+@MappedSuperclass
+@FilterDef(
+    name = "tenantFilter",
+    parameters = @ParamDef(name = "tenantId", type = UUID.class)
+)
+@Filter(name = "tenantFilter", condition = "tenant_id = :tenantId")
+public abstract class AbstractTenantEntity {
+
+    @Column(name = "tenant_id", nullable = false, updatable = false)
+    private UUID tenantId;
+
+    @PrePersist
+    void injectTenant() {
+        this.tenantId = TenantContext.getCurrentTenant();
+    }
+}
+```
+
+```java
+// TenantFilterInterceptor.java (pseudocode)
+@Component
+public class TenantFilterInterceptor implements HandlerInterceptor {
+
+    @Autowired EntityManager em;
+
+    @Override
+    public boolean preHandle(HttpServletRequest req, ...) {
+        UUID tenantId = TenantContext.getCurrentTenant();
+        Session session = em.unwrap(Session.class);
+        session.enableFilter("tenantFilter")
+               .setParameter("tenantId", tenantId);
+        return true;
+    }
+}
+```
+
+**Invariants enforced:**
+- `tenant_id` is set at `@PrePersist` — never accepted from user input
+- `tenant_id` is `updatable = false` — cannot be changed after creation
+- Hibernate filter is enabled on every request thread before any query executes
+- All repository methods inherit the filter; raw JPQL queries must include `AND e.tenantId = :tenantId`
+
+---
+
+## 3. Authentication & Authorization
+
+### JWT Token Flow
+
+- **Access token:** 8-hour expiry, signed HS256, contains `sub` (userId), `role`, `tenantId`
+- **Refresh token:** 30-day expiry, stored in `users.refresh_token_hash` (hashed)
+- **Stateless:** No server-side session. JWT is verified on every request by `JwtAuthFilter`
+
+### Roles
+
+| Role | Description | Access |
+|---|---|---|
+| `ROLE_CLUB_ADMIN` | Club administrator | Full club management, all members, reports, distributions |
+| `ROLE_MEMBER` | Club member | Own quota, own distribution history |
+| `ROLE_PREVENTION_OFFICER` | Designated prevention officer | Member under-21 reports, prevention data |
+
+### Service-Layer Authorization Example
+
+```java
+@Service
+public class DistributionService {
+
+    @PreAuthorize("hasRole('CLUB_ADMIN')")
+    public Distribution recordDistribution(RecordDistributionRequest req) { ... }
+
+    @PreAuthorize("hasRole('MEMBER') and #memberId == authentication.principal.memberId")
+    public QuotaStatus getMyQuota(UUID memberId) { ... }
+
+    @PreAuthorize("hasAnyRole('CLUB_ADMIN', 'PREVENTION_OFFICER')")
+    public List<Member> getUnder21Members() { ... }
+}
+```
+
+### Member Login Sequence
+
+```mermaid
+sequenceDiagram
+    participant B as Browser
+    participant API as Spring Boot /api/v1/auth/login
+    participant DB as PostgreSQL (users table)
+    participant JWT as JwtService
+
+    B->>API: POST /api/v1/auth/login {email, password}
+    API->>DB: SELECT * FROM users WHERE email = ? AND active = true
+    DB-->>API: UserEntity (password_hash, role, tenant_id, member_id)
+    API->>API: BCrypt.verify(password, password_hash)
+    alt Invalid credentials
+        API-->>B: 401 Unauthorized
+    else Valid
+        API->>JWT: generateAccessToken(userId, role, tenantId) → 8h
+        API->>JWT: generateRefreshToken(userId) → 30d
+        API->>DB: UPDATE users SET refresh_token_hash = ?, last_login = NOW()
+        DB-->>API: OK
+        JWT-->>API: accessToken, refreshToken
+        API-->>B: 200 { accessToken, refreshToken, expiresIn: 28800 }
+    end
+```
+
+---
+
+## 4. Data Model (JPA Entities)
+
+### Entity-Relationship Diagram
+
+```mermaid
+erDiagram
+    Club {
+        UUID id PK
+        UUID tenant_id
+        string name
+        string address
+        string license_number
+        int max_members
+        timestamp created_at
+        enum status
+    }
+
+    Member {
+        UUID id PK
+        UUID tenant_id
+        UUID club_id FK
+        string first_name
+        string last_name
+        string email
+        date date_of_birth
+        date membership_date
+        string membership_number
+        enum status
+        boolean is_under_21
+        boolean prevention_officer
+    }
+
+    Strain {
+        UUID id PK
+        UUID tenant_id
+        string name
+        decimal thc_percentage
+        decimal cbd_percentage
+        string description
+    }
+
+    Batch {
+        UUID id PK
+        UUID tenant_id
+        UUID strain_id FK
+        decimal quantity_grams
+        date harvest_date
+        string batch_code
+        enum status
+        boolean contamination_flag
+    }
+
+    Distribution {
+        UUID id PK
+        UUID tenant_id
+        UUID member_id FK
+        UUID batch_id FK
+        decimal quantity_grams
+        timestamp distributed_at
+        UUID recorded_by FK
+        string notes
+        boolean immutable
+    }
+
+    MonthlyQuota {
+        UUID id PK
+        UUID tenant_id
+        UUID member_id FK
+        int year
+        int month
+        decimal total_distributed
+        decimal max_allowed
+    }
+
+    StockMovement {
+        UUID id PK
+        UUID tenant_id
+        UUID batch_id FK
+        enum movement_type
+        decimal quantity_grams
+        string reason
+        timestamp created_at
+    }
+
+    User {
+        UUID id PK
+        UUID tenant_id
+        UUID member_id FK
+        string email
+        string password_hash
+        enum role
+        timestamp last_login
+        boolean active
+    }
+
+    Club ||--o{ Member : "has members"
+    Member ||--o{ Distribution : "receives"
+    Member ||--o{ MonthlyQuota : "has quota per month"
+    Member ||--o| User : "may have login"
+    Strain ||--o{ Batch : "cultivated as"
+    Batch ||--o{ Distribution : "distributed via"
+    Batch ||--o{ StockMovement : "tracked in"
+    Member ||--o{ Distribution : "recorded_by (admin)"
+```
+
+### Relationship Notes
+
+| Relationship | Cardinality | Notes |
+|---|---|---|
+| Club → Member | 1:N | `member.club_id` FK; max enforced by `Club.max_members` |
+| Member → Distribution | 1:N | Each distribution targets one member |
+| Member → MonthlyQuota | 1:N | One row per `(member_id, year, month)` — UNIQUE constraint |
+| Member → User | 1:0..1 | A member may have a portal login; admins may have no `member_id` |
+| Strain → Batch | 1:N | Each batch is one strain; a strain can have many batches |
+| Batch → Distribution | 1:N | A batch can supply many distributions |
+| Batch → StockMovement | 1:N | Every IN/OUT/RECALL against a batch is journaled |
+| Distribution.recorded_by → Member | N:1 | The admin who recorded it (audit trail) |
+
+### Key Constraints
+
+- `Distribution.immutable = true` by default — records are append-only; no UPDATE/DELETE allowed via API
+- `MonthlyQuota` has `UNIQUE(member_id, year, month)` — enforced at DB level
+- `Batch.contamination_flag` triggers recall workflow; `Batch.status = RECALLED` is the final state
+- All `tenant_id` columns: `NOT NULL`, `updatable = false`, set via `@PrePersist`
+- `Member.is_under_21` is derived from `date_of_birth` at registration and re-evaluated on birthday (scheduled job)
+
+---
+
+## 5. API Layer Design
+
+### Base Path: `/api/v1/`
+
+All endpoints are RESTful. JSON request/response bodies. JWT Bearer token required on all except `/auth/**`.
+
+| Controller | Base Path | Key Endpoints |
+|---|---|---|
+| `AuthController` | `/api/v1/auth` | `POST /login`, `POST /refresh`, `POST /logout` |
+| `ClubController` | `/api/v1/clubs` | `GET /`, `POST /`, `GET /{id}`, `PUT /{id}` |
+| `MemberController` | `/api/v1/members` | `GET /`, `POST /`, `GET /{id}`, `PUT /{id}/status`, `GET /me/quota` |
+| `DistributionController` | `/api/v1/distributions` | `POST /`, `GET /?memberId=&month=&year=` |
+| `StockController` | `/api/v1/stock` | `GET /batches`, `POST /batches`, `POST /batches/{id}/recall` |
+| `ReportController` | `/api/v1/reports` | `GET /monthly?month=&year=` (PDF + CSV), `GET /members/{id}/history` |
+| `QuotaController` | `/api/v1/quota` | `GET /members/{id}/current`, `GET /members/{id}/history` |
+
+### Standard HTTP conventions
+- `201 Created` + `Location` header on resource creation
+- `400 Bad Request` with `{ error, message, field? }` on validation failure
+- `403 Forbidden` when role/tenant check fails
+- `422 Unprocessable Entity` when compliance limits are breached (quota exceeded)
+- Pagination: `?page=0&size=20&sort=field,asc`
+
+---
+
+## 6. Compliance Engine
+
+The `ComplianceService` is the heart of regulatory enforcement. It is called synchronously before every distribution is persisted. All operations run in a single `@Transactional` block with optimistic locking to prevent race conditions under concurrent distribution recording.
+
+```java
+@Service
+@Transactional
+public class ComplianceService {
+
+    /**
+     * Validates whether a distribution is legally permitted.
+     *
+     * Checks:
+     *   1. Member is ACTIVE (not SUSPENDED or EXPELLED)
+     *   2. Daily limit: total distributed today + requestedGrams ≤ 25g
+     *   3. Monthly limit: MonthlyQuota.total_distributed + requestedGrams ≤ max_allowed
+     *      where max_allowed = 30g (under-21) or 50g (adult)
+     *   4. Batch is AVAILABLE (not RECALLED or EXHAUSTED)
+     *   5. Batch has sufficient stock
+     *
+     * @throws ComplianceLimitExceededException with remaining quota details
+     * @throws MemberIneligibleException if member is not ACTIVE
+     * @throws BatchUnavailableException if batch is recalled or exhausted
+     */
+    public ComplianceCheckResult checkDistributionAllowed(
+            UUID memberId, UUID batchId, BigDecimal quantityGrams) { ... }
+
+    /**
+     * Returns remaining quota for the current calendar month.
+     * Creates a MonthlyQuota row if none exists (lazy initialization).
+     *
+     * @return QuotaStatus { totalAllowed, totalUsed, remaining, isUnder21 }
+     */
+    public QuotaStatus getMonthlyRemaining(UUID memberId) { ... }
+
+    /**
+     * Flags a batch as RECALLED.
+     * Returns all members who received distributions from this batch
+     * so the caller can trigger notifications.
+     * Writes a StockMovement(RECALL) entry.
+     *
+     * @return List<AffectedMember> { memberId, name, email, totalReceived }
+     */
+    public List<AffectedMember> recallBatch(UUID batchId) { ... }
+}
+```
+
+### Race Condition Prevention
+
+`MonthlyQuota` rows carry a JPA `@Version` column (optimistic locking). If two concurrent requests attempt to increment `total_distributed` simultaneously, one will receive an `OptimisticLockException` and must retry. The retry logic is handled by a `@Retryable` annotation (Spring Retry, max 3 attempts, 50ms backoff).
+
+```java
+@Entity
+public class MonthlyQuota extends AbstractTenantEntity {
+
+    @Version
+    private Long version;  // optimistic lock
+
+    // ... other fields
+}
+```
+
+---
+
+## 7. Infrastructure (Hetzner)
+
+```mermaid
+graph TD
+    Dev["👨‍💻 Developer (Fedora Workstation)"]
+    Gitea["🏠 Gitea (homelab)\n192.168.188.119:30008"]
+    Hetzner["☁️ Hetzner VPS CX21\n~€5.88/month"]
+
+    Dev -->|git push| Gitea
+    Gitea -->|SSH deploy script\n(webhook → deploy.sh)| Hetzner
+
+    subgraph Hetzner
+        Nginx["🔒 Nginx Container\n(reverse proxy + TLS/Let's Encrypt)"]
+        App["☕ cannamanage-app\n(Spring Boot JAR)"]
+        DB[("🐘 cannamanage-db\nPostgreSQL 16")]
+
+        Nginx -->|proxy_pass :8080| App
+        App -->|JDBC :5432| DB
+    end
+
+    Internet["🌍 Internet\nHTTPS :443"] -->|HTTPS| Nginx
+```
+
+### Docker Compose Services
+
+```yaml
+# docker-compose.yml (abbreviated)
+services:
+  cannamanage-app:
+    image: cannamanage:latest
+    environment:
+      SPRING_DATASOURCE_URL: jdbc:postgresql://cannamanage-db:5432/cannamanage
+      JWT_SECRET: ${JWT_SECRET}
+      STRIPE_API_KEY: ${STRIPE_API_KEY}
+    depends_on: [cannamanage-db]
+    ports: ["127.0.0.1:8080:8080"]
+
+  cannamanage-db:
+    image: postgres:16-alpine
+    volumes: [pgdata:/var/lib/postgresql/data]
+    environment:
+      POSTGRES_DB: cannamanage
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+
+  cannamanage-nginx:
+    image: nginx:alpine
+    ports: ["443:443", "80:80"]
+    volumes:
+      - ./nginx.conf:/etc/nginx/conf.d/default.conf
+      - /etc/letsencrypt:/etc/letsencrypt:ro
+```
+
+### Hetzner Sizing
+
+| Resource | Spec | Rationale |
+|---|---|---|
+| Server | CX21 (2 vCPU, 4GB RAM) | Sufficient for < 200 concurrent clubs at MVP |
+| Storage | 40GB SSD (included) | PostgreSQL + logs; Hetzner Volumes for backups |
+| Backups | Hetzner automated backups (20% surcharge) | Daily snapshot retention 7 days |
+| Location | Falkenstein, Germany (FSN1) | DSGVO: data remains within Germany |
+| TLS | Let's Encrypt via Certbot | Auto-renew via cron |
+
+### Deployment Workflow
+
+```
+git push origin main
+  → Gitea webhook fires
+  → deploy.sh on Hetzner:
+      docker pull cannamanage:latest
+      docker compose up -d --no-deps cannamanage-app
+      # zero-downtime: Nginx buffers requests during restart
+```
+
+Flyway migrations run automatically on application startup (`spring.flyway.enabled=true`). Migration files live at `src/main/resources/db/migration/V*.sql`.
+
+---
+
+## 8. Key Design Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Multi-tenancy | Shared schema + `tenant_id` | MVP simplicity; upgrade to schema-per-tenant possible later |
+| Frontend MVP | PrimeFaces JSF | Patrick's existing expertise; fastest path to working UI |
+| Frontend v2 | Next.js / React | Modern UX; deferred to avoid scope creep in MVP |
+| Auth | JWT (stateless) | No sticky sessions needed; horizontal scale ready |
+| PDF generation | iText 7 | Mature Java library; handles complex compliance report layouts |
+| Compliance enforcement | Service layer + DB constraint | Belt-and-suspenders: service validates, DB `UNIQUE` prevents duplicates |
+| Distribution immutability | `immutable = true`, no DELETE API | Audit trail integrity for regulatory compliance |
+| Hosting | Hetzner (Germany) | DSGVO compliance; low cost; German DC |