feat(docs, api): Add Projects Discovery API, deploymentcenter project seed, public web docs endpoint, and minimal agent prompt template

.htaccess

@@ -10,8 +10,13 @@
     RewriteRule ^api/updateservice/v1(?:/(.*))?$ public/api/updateservice/v1/index.php [L,QSA]
     RewriteRule ^api/tokens/v1/provision public/api/tokens/v1/provision.php [L,QSA]
     RewriteRule ^api/bugtracker/v1/report public/api/bugtracker/v1/report.php [L,QSA]
+    RewriteRule ^api/bugtracker/v1/projects public/api/bugtracker/v1/projects.php [L,QSA]
     RewriteRule ^api/bugtracker/v1/manage(?:/(.*))?$ public/api/bugtracker/v1/manage/index.php [L,QSA]
 
+    # Documentation routing
+    RewriteRule ^docs/(.*)$ public/docs/$1 [L,QSA]
+    RewriteRule ^docs/?$ public/docs/index.php [L,QSA]
+
     # Fallback for static assets in /api/
     RewriteRule ^api/(.*)$ public/api/$1 [L,QSA]
 

docs/AGENT_PROMPT_TEMPLATE.md

@@ -0,0 +1,42 @@
+# 📋 Minimal Agent Prompt Template (For CLAUDE.md / AGENTS.md / CursorRules)
+
+Copy & paste the following snippet into your agent system prompts or repository `CLAUDE.md` / `.cursorrules`:
+
+```markdown
+## 🐛 Central Bugtracker & Feature Logging Directive
+
+As an AI developer agent, you MUST track all unhandled errors, stack traces, planned features, and refactoring ideas in the central **Deployment Center Bugtracker**.
+
+### 1. Monitored Projects & Discovery
+Before reporting, check monitored projects via API or use the known project slug:
+- **Projects Discovery API**: `GET https://dc.mhdf.de/api/bugtracker/v1/projects.php`
+- **Known Slugs**: `deploymentcenter`, `myapp`, `polytrader`, `predictalytics`.
+*Note: If you discover a bug or issue in the Deployment Center code itself while working elsewhere, report it under `project_slug: "deploymentcenter"`.*
+
+### 2. Reporting Bugs & Ideas
+Submit reports via HTTP POST to: `https://dc.mhdf.de/api/bugtracker/v1/report.php`
+Header: `Authorization: Bearer <YOUR_AGENT_TOKEN>` (or `X-Agent-Token: <YOUR_AGENT_TOKEN>`)
+
+```json
+{
+  "project_slug": "deploymentcenter",
+  "type": "bug",
+  "title": "Short descriptive title of the error or feature",
+  "description": "Condition or context under which it occurred",
+  "error_message": "Exact exception message",
+  "stack_trace": "Complete stack trace snippet",
+  "severity": "high",
+  "push_id": "push_wf_8912",
+  "created_by": "agent:your-name"
+}
+```
+
+- **Severities**:
+  - `idea`: 💡 Quick reminder / thought for later
+  - `wishlist`: ⭐ Backlog feature request
+  - `low` / `medium` / `high` / `critical`: Standard bug severities
+
+### 3. Full API Documentation On-Demand
+If you need complete API details, token provisioning instructions, or cURL/Python examples, read:
+📄 **Documentation URL**: `https://dc.mhdf.de/docs/bugtracker.md`
+```

docs/BUGTRACKER_INTEGRATION_GUIDE.md

@@ -49,6 +49,50 @@ Header: `Authorization: Bearer <MASTER_TOKEN>`
 
 ---
 
+## 📂 1.5. Discovering Monitored Projects API
+
+Before reporting a bug or feature request, an agent can dynamically query all registered projects monitored by the Deployment Center.
+
+### Endpoint: `GET /api/bugtracker/v1/projects.php`
+
+#### Response:
+```json
+{
+  "status": "success",
+  "count": 4,
+  "projects": [
+    {
+      "id": 1,
+      "slug": "myapp",
+      "name": "My Application Deluxe",
+      "notes": "Hauptanwendung für Desktop und Server"
+    },
+    {
+      "id": 2,
+      "slug": "polytrader",
+      "name": "PolyTrader Suite Pro",
+      "notes": "Trading- und Handelssystem Client"
+    },
+    {
+      "id": 3,
+      "slug": "predictalytics",
+      "name": "Predictalytics Engine",
+      "notes": "Datenanalyse und Vorhersage Dienst"
+    },
+    {
+      "id": 4,
+      "slug": "deploymentcenter",
+      "name": "Deployment Center",
+      "notes": "Zentrale Verwaltungs- & Update-Plattform"
+    }
+  ]
+}
+```
+
+If an agent discovers an issue or refactoring opportunity in any monitored system (including `deploymentcenter` itself or external dependencies), it can fetch this project list and map the issue to the appropriate `project_slug`.
+
+---
+
 ## 🐛 2. Reporting Bugs, Features & Ideas
 
 ### Endpoint: `POST /api/bugtracker/v1/report.php`

public/api/bugtracker/v1/manage/index.php

@@ -69,6 +69,11 @@ try {
     }
 
     // Sub-actions
+    if ($action === 'projects' || str_contains($path, '/projects')) {
+        echo json_encode(['status' => 'success', 'projects' => $repo->getProjects()], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+        exit;
+    }
+
     if ($action === 'stats' || str_ends_with($path, '/stats')) {
         echo json_encode(['status' => 'success', 'stats' => $repo->getStats()], JSON_PRETTY_PRINT);
         exit;

public/api/bugtracker/v1/projects.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../../../../src/Core/Db.php';
+require_once __DIR__ . '/../../../../src/Modules/Bugtracker/BugRepo.php';
+
+use Deploymentcenter\Core\Db;
+use Deploymentcenter\Modules\Bugtracker\BugRepo;
+
+header('Content-Type: application/json; charset=utf-8');
+header('Access-Control-Allow-Origin: *');
+header('Access-Control-Allow-Headers: Content-Type, Authorization, X-Agent-Token');
+header('Access-Control-Allow-Methods: GET, OPTIONS');
+
+if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
+    http_response_code(200);
+    exit;
+}
+
+try {
+    $config = require __DIR__ . '/../../../../config/config.php';
+    $db = Db::connect($config['db']);
+
+    $repo = new BugRepo($db);
+    $projects = $repo->getProjects();
+
+    echo json_encode([
+        'status'   => 'success',
+        'count'    => count($projects),
+        'projects' => array_map(function($p) {
+            return [
+                'id'       => (int)$p['id'],
+                'slug'     => $p['slug'],
+                'name'     => $p['name'],
+                'notes'    => $p['notes'] ?? null,
+            ];
+        }, $projects),
+    ], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+
+} catch (Throwable $t) {
+    http_response_code(500);
+    echo json_encode(['status' => 'error', 'message' => 'Failed to fetch projects: ' . $t->getMessage()]);
+}

public/docs/.htaccess

@@ -0,0 +1,8 @@
+# Documentation Public Access
+Satisfy Any
+Allow from all
+
+# Apache 2.4+ compatibility
+<IfModule mod_authz_core.c>
+    Require all granted
+</IfModule>

public/docs/bugtracker.md

@@ -0,0 +1,258 @@
+# 🤖 AI Agent Integration Guide: Deployment Center Bugtracker & Provisioning API
+
+This guide defines the standardized protocol and API specifications for autonomous AI Developer Agents interacting with the **Deployment Center Bugtracker & Token Provisioning System**.
+
+---
+
+## 📌 Executive Overview for AI Agents
+
+As an autonomous AI agent working on software repositories, you MUST actively track all runtime errors, stack traces, planned features, and backlog items in the central Deployment Center.
+
+### Core Capabilities:
+1. **Sub-Token Auto-Provisioning**: Generate restricted sub-tokens for scoped agent tasks.
+2. **Automated Error Ingestion**: Report unhandled exceptions with stack traces & automatic SHA-256 deduplication.
+3. **Feature & Idea Backlog**: Submit roadmap ideas (`severity: "idea"`) or backlog items (`severity: "wishlist"`).
+4. **Active Workflow Management**: Fetch active bugs assigned to your agent ID, update status (`in_progress`, `resolved`), and append diagnostic comments.
+
+---
+
+## 🔑 1. Token Provisioning API
+
+Agents authenticate using a **Master Token** or auto-provisioned **Sub-Token**.
+
+### Endpoint: `POST /api/tokens/v1/provision`
+
+Header: `Authorization: Bearer <MASTER_TOKEN>`
+
+#### Request Payload:
+```json
+{
+  "parent_token": "dc_master_myapp_dev_agent_001",
+  "name": "Codebase Refactoring Agent Token",
+  "environment": "development",
+  "scopes": ["bugtracker:report", "bugtracker:manage"],
+  "expires_in_hours": 24
+}
+```
+
+#### Response:
+```json
+{
+  "status": "success",
+  "token_id": "tok_s_8912ab",
+  "raw_token": "dc_sub_myapp_refactor_agent_991",
+  "scopes": ["bugtracker:report", "bugtracker:manage"],
+  "environment": "development",
+  "expires_at": "2026-08-07 21:00:00"
+}
+```
+
+---
+
+## 📂 1.5. Discovering Monitored Projects API
+
+Before reporting a bug or feature request, an agent can dynamically query all registered projects monitored by the Deployment Center.
+
+### Endpoint: `GET /api/bugtracker/v1/projects.php`
+
+#### Response:
+```json
+{
+  "status": "success",
+  "count": 4,
+  "projects": [
+    {
+      "id": 1,
+      "slug": "myapp",
+      "name": "My Application Deluxe",
+      "notes": "Hauptanwendung für Desktop und Server"
+    },
+    {
+      "id": 2,
+      "slug": "polytrader",
+      "name": "PolyTrader Suite Pro",
+      "notes": "Trading- und Handelssystem Client"
+    },
+    {
+      "id": 3,
+      "slug": "predictalytics",
+      "name": "Predictalytics Engine",
+      "notes": "Datenanalyse und Vorhersage Dienst"
+    },
+    {
+      "id": 4,
+      "slug": "deploymentcenter",
+      "name": "Deployment Center",
+      "notes": "Zentrale Verwaltungs- & Update-Plattform"
+    }
+  ]
+}
+```
+
+If an agent discovers an issue or refactoring opportunity in any monitored system (including `deploymentcenter` itself or external dependencies), it can fetch this project list and map the issue to the appropriate `project_slug`.
+
+---
+
+## 🐛 2. Reporting Bugs, Features & Ideas
+
+### Endpoint: `POST /api/bugtracker/v1/report.php`
+
+Header: `Authorization: Bearer <AGENT_TOKEN>`
+
+### A. Reporting an Unhandled Exception / Bug
+```json
+{
+  "project_slug": "myapp",
+  "type": "bug",
+  "title": "NullReferenceException in UserAuthService.cs line 42",
+  "description": "Triggered when user logs in without an active session object.",
+  "error_message": "NullReferenceException: Object reference not set to an instance of an object.",
+  "stack_trace": "at MyApp.Core.UserAuthService.ValidateToken(String token) in UserAuthService.cs:line 42\nat MyApp.Controllers.AuthController.Login() in AuthController.cs:line 18",
+  "build_version": "v1.4.2-dev",
+  "environment": "development",
+  "severity": "high",
+  "push_id": "push_wf_8912",
+  "target_agent": "agent:code-fixer-01",
+  "tags": "auth, security, csharp",
+  "created_by": "agent:watchdog-monitor"
+}
+```
+
+### B. Submitting a Feature Request or Quick Reminder Idea (`severity: "idea"`)
+```json
+{
+  "project_slug": "myapp",
+  "type": "feature_request",
+  "title": "Automatische Datenbank-Backups vor FTP Deployments",
+  "description": "Gedanke für später: Vor jedem FTP-Deployment automatisch mysqldump ausführen und im Server-Archiv ablegen.",
+  "build_version": "v1.6.0-roadmap",
+  "environment": "development",
+  "severity": "idea",
+  "push_id": "push_wf_9910",
+  "target_agent": "agent:db-optimizer",
+  "tags": "database, automation, backup",
+  "created_by": "agent:planner"
+}
+```
+
+#### Response:
+```json
+{
+  "status": "success",
+  "item_id": 4,
+  "is_new": true,
+  "occurrence_count": 1,
+  "error_hash": "e2c918a514d89a42f",
+  "type": "bug",
+  "environment": "development",
+  "push_id": "push_wf_8912",
+  "message": "New bug reported successfully."
+}
+```
+
+---
+
+## 📌 3. Managing Items (Fetching, Updating & Commenting)
+
+### Base Endpoint: `/api/bugtracker/v1/manage/index.php`
+
+Header: `Authorization: Bearer <AGENT_TOKEN>`
+
+### A. Fetching Open Items Assigned to an Agent
+```http
+GET /api/bugtracker/v1/manage/index.php?project_slug=myapp&status=open&agent=agent:code-fixer-01
+```
+
+### B. Updating Status & Details (`POST ?action=update`)
+```json
+{
+  "id": 4,
+  "status": "in_progress",
+  "severity": "high",
+  "push_id": "push_wf_8912",
+  "target_agent": "agent:code-fixer-01",
+  "tags": "auth, fixed_pending_test",
+  "author": "agent:code-fixer-01"
+}
+```
+
+### C. Appending Diagnostic Timeline Comments (`POST ?action=comment`)
+```json
+{
+  "id": 4,
+  "comment": "Ursache identifiziert: $_SESSION['user'] war Null in line 42. Null-Check und Safe Navigation Operator wurden hinzugefügt.",
+  "action_taken": "code_patched",
+  "author": "agent:code-fixer-01"
+}
+```
+
+### D. Marking as Resolved (`POST ?action=resolve`)
+```json
+{
+  "id": 4,
+  "resolved_in_build": "v1.4.3-dev",
+  "resolution_notes": "Unit tests hinzugefügt und Null-Check in ValidateToken() integriert.",
+  "author": "agent:code-fixer-01"
+}
+```
+
+---
+
+## 💻 4. Code Implementation Examples for Agents
+
+### Python Example: Automatic Error Reporter Decorator
+```python
+import requests
+import traceback
+import sys
+
+DC_API_URL = "https://dc.mhdf.de/api/bugtracker/v1/report.php"
+AGENT_TOKEN = "dc_sub_myapp_agent_live_001"
+
+def report_exception_to_dc(project_slug: str, exc: Exception, env: str = "production", push_id: str = None):
+    payload = {
+        "project_slug": project_slug,
+        "type": "bug",
+        "title": f"{type(exc).__name__}: {str(exc)}",
+        "error_message": str(exc),
+        "stack_trace": traceback.format_exc(),
+        "build_version": "v1.4.2",
+        "environment": env,
+        "severity": "high",
+        "push_id": push_id,
+        "created_by": "agent:python-runner"
+    }
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {AGENT_TOKEN}"
+    }
+    try:
+        r = requests.post(DC_API_URL, json=payload, headers=headers, timeout=5)
+        return r.json()
+    except Exception as e:
+        print(f"Failed to report to Deployment Center: {e}", file=sys.stderr)
+```
+
+### cURL Example: Submit Feature Request / Idea
+```bash
+curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/report.php" \
+  -H "Authorization: Bearer dc_sub_myapp_agent_live_001" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "project_slug": "myapp",
+    "type": "feature_request",
+    "title": "Erweiterte Filterung im WebUI Dashboard",
+    "severity": "idea",
+    "push_id": "push_task_1029",
+    "tags": "ui, dashboard",
+    "created_by": "agent:dev-assistant"
+  }'
+```
+
+---
+
+## 🎯 Best Practices for Developer Agents
+
+1. **Always set `push_id`**: When executing automated pipelines, pass a `push_id` so all updates can be traced back to the specific execution run.
+2. **Use `severity: "idea"` for thoughts**: When noticing potential refactorings or future improvements during coding, log them immediately as ideas.
+3. **Comment before resolving**: Before calling `action=resolve`, write a diagnostic comment explaining **why** and **how** the fix was performed.

public/docs/index.php

@@ -0,0 +1,156 @@
+<?php
+
+declare(strict_types=1);
+
+$mdPath = __DIR__ . '/bugtracker.md';
+$markdownContent = file_exists($mdPath) ? file_get_contents($mdPath) : '# Documentation Not Found';
+
+// If requested as raw text / markdown
+if (isset($_GET['raw']) || (isset($_SERVER['HTTP_ACCEPT']) && str_contains($_SERVER['HTTP_ACCEPT'], 'text/plain'))) {
+    header('Content-Type: text/plain; charset=utf-8');
+    echo $markdownContent;
+    exit;
+}
+
+?>
+<!DOCTYPE html>
+<html lang="de">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Deployment Center - Developer & Agent Documentation</title>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Fira+Code:wght@400;600&display=swap" rel="stylesheet">
+    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+    <style>
+        :root {
+            --bg: #0b0f19;
+            --card-bg: #141b2d;
+            --accent: #5b9dff;
+            --text: #e2e8f0;
+            --text-muted: #94a3b8;
+            --border: rgba(255, 255, 255, 0.08);
+            --code-bg: #080c14;
+        }
+
+        * { box-sizing: border-box; margin: 0; padding: 0; }
+        body {
+            font-family: 'Inter', system-ui, sans-serif;
+            background: var(--bg);
+            color: var(--text);
+            line-height: 1.6;
+            padding: 2rem 1rem;
+        }
+
+        .container {
+            max-width: 900px;
+            margin: 0 auto;
+            background: var(--card-bg);
+            border: 1px solid var(--border);
+            border-radius: 12px;
+            padding: 2.5rem;
+            box-shadow: 0 20px 40px rgba(0,0,0,0.5);
+        }
+
+        .header-bar {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            border-bottom: 1px solid var(--border);
+            padding-bottom: 1.5rem;
+            margin-bottom: 2rem;
+        }
+
+        .header-bar h1 {
+            font-size: 1.4rem;
+            color: #fff;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+        }
+
+        .btn {
+            display: inline-flex;
+            align-items: center;
+            gap: 0.4rem;
+            padding: 0.5rem 1rem;
+            background: rgba(91, 157, 255, 0.15);
+            color: var(--accent);
+            border: 1px solid var(--accent);
+            border-radius: 6px;
+            text-decoration: none;
+            font-size: 0.85rem;
+            font-weight: 600;
+            transition: all 0.2s;
+        }
+
+        .btn:hover {
+            background: var(--accent);
+            color: #fff;
+        }
+
+        #docContent h1, #docContent h2, #docContent h3 {
+            color: #fff;
+            margin-top: 1.8rem;
+            margin-bottom: 0.8rem;
+        }
+
+        #docContent h1 { font-size: 1.8rem; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; }
+        #docContent h2 { font-size: 1.4rem; color: var(--accent); }
+        #docContent h3 { font-size: 1.1rem; }
+
+        #docContent p { margin-bottom: 1rem; color: #cbd5e1; }
+        #docContent ul, #docContent ol { margin-left: 1.5rem; margin-bottom: 1rem; color: #cbd5e1; }
+        #docContent li { margin-bottom: 0.4rem; }
+
+        #docContent code {
+            font-family: 'Fira Code', monospace;
+            background: rgba(255, 255, 255, 0.08);
+            padding: 0.2rem 0.4rem;
+            border-radius: 4px;
+            font-size: 0.88rem;
+            color: #38bdf8;
+        }
+
+        #docContent pre {
+            background: var(--code-bg);
+            border: 1px solid var(--border);
+            border-radius: 8px;
+            padding: 1.25rem;
+            overflow-x: auto;
+            margin: 1rem 0 1.5rem 0;
+        }
+
+        #docContent pre code {
+            background: transparent;
+            padding: 0;
+            color: #e2e8f0;
+            font-size: 0.85rem;
+        }
+
+        #docContent blockquote {
+            border-left: 4px solid var(--accent);
+            background: rgba(91, 157, 255, 0.05);
+            padding: 0.75rem 1rem;
+            margin: 1rem 0;
+            border-radius: 0 6px 6px 0;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header-bar">
+            <h1>🚀 Deployment Center API & Agent Documentation</h1>
+            <div>
+                <a href="bugtracker.md" target="_blank" class="btn">📄 Raw Markdown (.md)</a>
+                <a href="../api/bugtracker/v1/projects.php" target="_blank" class="btn">📂 Projects API</a>
+            </div>
+        </div>
+        <div id="docContent">Loading documentation...</div>
+    </div>
+
+    <script>
+        const rawMarkdown = <?= json_encode($markdownContent) ?>;
+        document.getElementById('docContent').innerHTML = marked.parse(rawMarkdown);
+    </script>
+</body>
+</html>

sql/migrations/005_bugtracker_push_id_and_severities.sql

@@ -48,6 +48,11 @@ DEALLOCATE PREPARE stmt;
 
 SET FOREIGN_KEY_CHECKS = 1;
 
+-- Seed Deployment Center Project
+INSERT INTO dc_projects (id, slug, name, notes, default_cache_ttl_hours) VALUES
+(4, 'deploymentcenter', 'Deployment Center', 'Zentrale Verwaltungs- & Update-Plattform', 168)
+ON DUPLICATE KEY UPDATE name = VALUES(name);
+
 -- Seed Sample Feature Idea
 INSERT IGNORE INTO bugtracker_items (
   id, project_slug, type, title, description, error_message, stack_trace, error_hash, build_version, environment, severity, status, occurrence_count, push_id, target_agent, tags, created_by

sql/schema.sql

@@ -259,7 +259,8 @@ ON DUPLICATE KEY UPDATE interval_sec = VALUES(interval_sec);
 INSERT INTO dc_projects (id, slug, name, notes, default_cache_ttl_hours) VALUES
 (1, 'myapp', 'My Application Deluxe', 'Hauptanwendung für Desktop und Server', 168),
 (2, 'polytrader', 'PolyTrader Suite Pro', 'Trading- und Handelssystem Client', 72),
-(3, 'predictalytics', 'Predictalytics Engine', 'Datenanalyse und Vorhersage Dienst', 168)
+(3, 'predictalytics', 'Predictalytics Engine', 'Datenanalyse und Vorhersage Dienst', 168),
+(4, 'deploymentcenter', 'Deployment Center', 'Zentrale Verwaltungs- & Update-Plattform', 168)
 ON DUPLICATE KEY UPDATE id = id;
 
 -- Seed Initial Licenses (Non-destructive)

src/Modules/Bugtracker/BugRepo.php

@@ -417,4 +417,13 @@ class BugRepo
 
         return $stats;
     }
+
+    /**
+     * Get list of all monitored projects.
+     */
+    public function getProjects(): array
+    {
+        $stmt = $this->db->query('SELECT id, slug, name, notes, default_cache_ttl_hours FROM dc_projects ORDER BY name ASC');
+        return $stmt->fetchAll() ?: [];
+    }
 }