Release v0.3.151

fix: rename sessions from the chat rail

.github/actions/claude-code-action/action.yml

@@ -0,0 +1,290 @@
+name: "Claude Code Action"
+description: "Run Claude Code in GitHub Actions workflows"
+
+inputs:
+  anthropic_api_key:
+    description: "Anthropic API key"
+    required: false
+  claude_code_oauth_token:
+    description: "Claude Code OAuth Token for Claude Pro"
+    required: false
+  github_token:
+    description: "GitHub token for Claude to operate with"
+    required: false
+    default: ${{ github.token }}
+  trigger_phrase:
+    description: "The trigger phrase to look for in comments, issue/PR bodies, and issue titles"
+    required: false
+    default: "@claude"
+  assignee_trigger:
+    description: "The assignee username that triggers the action (e.g. @claude). Only used for issue assignment"
+    required: false
+  max_turns:
+    description: "Maximum number of conversation turns Claude can take"
+    required: false
+  timeout_minutes:
+    description: "Timeout in minutes for execution"
+    required: false
+    default: "30"
+  model:
+    description: "Model to use (provider-specific format required for Bedrock/Vertex)"
+    required: false
+  use_bedrock:
+    description: "Use Amazon Bedrock with OIDC authentication instead of direct Anthropic API"
+    required: false
+    default: "false"
+  use_vertex:
+    description: "Use Google Vertex AI with OIDC authentication instead of direct Anthropic API"
+    required: false
+    default: "false"
+  allowed_tools:
+    description: "Additional tools for Claude to use (the base GitHub tools will always be included)"
+    required: false
+    default: ""
+  disallowed_tools:
+    description: "Tools that Claude should never use"
+    required: false
+    default: ""
+  custom_instructions:
+    description: "Additional custom instructions to include in the prompt for Claude"
+    required: false
+    default: ""
+  mcp_config:
+    description: "Additional MCP configuration (JSON string) that merges with the built-in GitHub MCP servers"
+    required: false
+    default: ""
+  claude_env:
+    description: "Custom environment variables to pass to Claude Code execution (YAML format)"
+    required: false
+    default: ""
+  direct_prompt:
+    description: "Direct prompt for Claude to execute automatically without needing a trigger (for automated workflows)"
+    required: false
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install Claude Code
+      shell: bash
+      run: npm install -g @anthropic-ai/claude-code
+
+    - name: Install GitHub MCP Server
+      shell: bash
+      run: |
+        claude mcp add-json github '{
+          "command": "docker",
+          "args": [
+            "run",
+            "-i",
+            "--rm",
+            "-e",
+            "GITHUB_PERSONAL_ACCESS_TOKEN",
+            "ghcr.io/github/github-mcp-server:sha-ff3036d"
+          ],
+          "env": {
+            "GITHUB_PERSONAL_ACCESS_TOKEN": "${{ inputs.github_token }}"
+          }
+        }'
+
+    - name: Extract GitHub Context and Create Prompt
+      shell: bash
+      id: prepare_context
+      env:
+        # Pass user-controlled inputs via environment variables to prevent script injection (GHSL-2025-093)
+        EVENT_COMMENT_BODY: ${{ github.event.comment.body }}
+        EVENT_ISSUE_TITLE: ${{ github.event.issue.title }}
+        EVENT_ISSUE_BODY: ${{ github.event.issue.body }}
+        EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
+        EVENT_PR_TITLE: ${{ github.event.pull_request.title }}
+        EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
+        EVENT_REVIEW_BODY: ${{ github.event.review.body }}
+        EVENT_ASSIGNEE_LOGIN: ${{ github.event.assignee.login }}
+        INPUT_TRIGGER_PHRASE: ${{ inputs.trigger_phrase }}
+        INPUT_ASSIGNEE_TRIGGER: ${{ inputs.assignee_trigger }}
+        INPUT_DIRECT_PROMPT: ${{ inputs.direct_prompt }}
+        EVENT_ACTION: ${{ github.event.action }}
+        EVENT_NAME: ${{ github.event_name }}
+        REPO_NAME: ${{ github.repository }}
+      run: |
+        echo "🔍 Extracting GitHub context from event: $EVENT_NAME"
+        
+        # Function to check for trigger phrase
+        check_trigger() {
+          local text="$1"
+          local trigger="$INPUT_TRIGGER_PHRASE"
+          if [[ "$text" == *"$trigger"* ]]; then
+            return 0
+          fi
+          return 1
+        }
+        
+        # Extract context based on event type
+        TRIGGER_FOUND="false"
+        USER_REQUEST=""
+        CONTEXT_INFO=""
+        
+        case "$EVENT_NAME" in
+          "issue_comment")
+            COMMENT_BODY="$EVENT_COMMENT_BODY"
+            ISSUE_TITLE="$EVENT_ISSUE_TITLE"
+            ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
+            
+            if check_trigger "$COMMENT_BODY"; then
+              TRIGGER_FOUND="true"
+              USER_REQUEST="$COMMENT_BODY"
+              CONTEXT_INFO="Issue Comment on #$ISSUE_NUMBER: $ISSUE_TITLE"
+            fi
+            ;;
+            
+          "pull_request_review_comment")
+            COMMENT_BODY="$EVENT_COMMENT_BODY"
+            PR_TITLE="$EVENT_PR_TITLE"
+            PR_NUMBER="$EVENT_PR_NUMBER"
+            
+            if check_trigger "$COMMENT_BODY"; then
+              TRIGGER_FOUND="true"
+              USER_REQUEST="$COMMENT_BODY"
+              CONTEXT_INFO="PR Comment on #$PR_NUMBER: $PR_TITLE"
+            fi
+            ;;
+            
+          "pull_request_review")
+            REVIEW_BODY="$EVENT_REVIEW_BODY"
+            PR_TITLE="$EVENT_PR_TITLE"
+            PR_NUMBER="$EVENT_PR_NUMBER"
+            
+            if check_trigger "$REVIEW_BODY"; then
+              TRIGGER_FOUND="true"
+              USER_REQUEST="$REVIEW_BODY"
+              CONTEXT_INFO="PR Review on #$PR_NUMBER: $PR_TITLE"
+            fi
+            ;;
+            
+          "issues")
+            ISSUE_BODY="$EVENT_ISSUE_BODY"
+            ISSUE_TITLE="$EVENT_ISSUE_TITLE"
+            ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
+            
+            if check_trigger "$ISSUE_TITLE" || check_trigger "$ISSUE_BODY"; then
+              TRIGGER_FOUND="true"
+              USER_REQUEST="$ISSUE_BODY"
+              CONTEXT_INFO="Issue #$ISSUE_NUMBER: $ISSUE_TITLE"
+            elif [[ "$EVENT_ACTION" == "assigned" && -n "$INPUT_ASSIGNEE_TRIGGER" ]]; then
+              ASSIGNEE="$EVENT_ASSIGNEE_LOGIN"
+              if [[ "$ASSIGNEE" == "$INPUT_ASSIGNEE_TRIGGER" ]]; then
+                TRIGGER_FOUND="true"
+                USER_REQUEST="$ISSUE_BODY"
+                CONTEXT_INFO="Issue #$ISSUE_NUMBER assigned to $ASSIGNEE: $ISSUE_TITLE"
+              fi
+            fi
+            ;;
+        esac
+        
+        # Check for direct prompt override
+        if [[ -n "$INPUT_DIRECT_PROMPT" ]]; then
+          TRIGGER_FOUND="true"
+          USER_REQUEST="$INPUT_DIRECT_PROMPT"
+          CONTEXT_INFO="Automated GitHub workflow"
+        fi
+        
+        if [[ "$TRIGGER_FOUND" != "true" ]]; then
+          echo "❌ No trigger phrase found or direct prompt provided. Exiting gracefully."
+          echo "SKIP_EXECUTION=true" >> $GITHUB_ENV
+          exit 0
+        fi
+        
+        echo "✅ Trigger found! Context: $CONTEXT_INFO"
+        
+        # Create comprehensive prompt
+        mkdir -p /tmp/claude-action
+        cat > /tmp/claude-action/github-context-prompt.txt << EOF
+        You are Claude Code, an AI assistant helping with GitHub workflows and code.
+        
+        Repository: $REPO_NAME
+        Context: $CONTEXT_INFO
+        Event: $EVENT_NAME
+        
+        User Request:
+        $USER_REQUEST
+        
+        Please analyze the request and provide helpful assistance.
+
+        CRITICAL INSTRUCTION: If your task involves modifying codebase files to add a feature or fix a bug:
+
+        STEP 0 — SETUP GIT IDENTITY:
+        git config user.name "MervinPraison"
+        git config user.email "[email protected]"
+
+        STEP 1 — READ GUIDELINES:
+        MANDATORY: Before writing any code, you MUST carefully read "src/praisonai-agents/AGENTS.md" to understand this repository's extremely specific Architecture, Protocol-First design rules, and Agent-Centric Philosophy.
+
+        STEP 2 — ARCHITECTURE VALIDATION & ROUTING (MANDATORY before writing code):
+        Before implementing anything, answer these questions:
+        - CORE vs WRAPPER vs TOOLS ROUTING:
+          1. Core SDK (praisonaiagents/): Only core protocols, base classes, decorators. No heavy implementations.
+          2. Wrapper (praisonai/): CLI, heavy implementations, optional dependencies.
+          3. Tools (PraisonAI-Tools): Specific integrations, external tools (e.g. SurrealDB, Slack), and community extensions MUST go to the `MervinPraison/PraisonAI-Tools` repository. If the feature is a tool, clone `https://github.com/MervinPraison/PraisonAI-Tools`, implement it there, and create the PR using `gh pr create -R MervinPraison/PraisonAI-Tools`.
+        - Does it duplicate existing functionality? Check if Agent already supports this via existing params (reflection, planning, tools, hooks, memory).
+        - Does it inherit from Agent properly? New agent types MUST inherit Agent, not wrap it with composition.
+        - Does it add new dependencies? Only optional deps allowed, must be lazy-imported.
+        - Will agent.py grow larger? If the change adds >50 lines to agent.py, find a way to extract instead.
+        - Is there a name collision with existing exports in __init__.py?
+        If ANY of these conceptual checks fail (excluding routing), add a comment to the issue explaining why and close it. Do NOT create a PR.
+
+        STEP 3 — IMPLEMENT:
+        - Create a new git branch appropriately named (e.g. \`feature/issue-<number>\`)
+        - Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper
+        - Keep changes small and backward-compatible
+
+        STEP 4 — TEST:
+        - Run: cd src/praisonai-agents && PYTHONPATH=. python -m pytest tests/ -x -q --timeout=30
+        - Ensure no regressions
+
+        STEP 5 — CREATE PR:
+        - Commit with descriptive message, push the branch
+        - Use the GitHub CLI (\`gh pr create --title "..." --body "Fixes #<number>"\`) to open a Pull Request
+        CRITICAL: You MUST create the PR automatically using \`gh pr create\`. Do NOT just provide a link.
+
+        Respond naturally and helpfully to the user's request using the available tools.
+        EOF
+        
+        echo "PROMPT_FILE=/tmp/claude-action/github-context-prompt.txt" >> $GITHUB_ENV
+        echo "SKIP_EXECUTION=false" >> $GITHUB_ENV
+
+    - name: Run Claude Code
+      if: env.SKIP_EXECUTION != 'true'
+      shell: bash
+      run: |
+        echo "🚀 Running Claude Code with GitHub context..."
+        
+        # Build command arguments
+        CMD_ARGS=("-p" "--verbose" "--output-format" "stream-json")
+        
+        # Add max turns if specified
+        if [[ -n "${{ inputs.max_turns }}" ]]; then
+          CMD_ARGS+=("--max-turns" "${{ inputs.max_turns }}")
+        fi
+        
+        # Add allowed tools (include GitHub tools by default)
+        TOOLS="mcp__github__get_issue,mcp__github__get_issue_comments,mcp__github__update_issue,mcp__github__search_issues,mcp__github__list_issues,mcp__github__create_comment,Read,Write,Edit,Bash"
+        if [[ -n "${{ inputs.allowed_tools }}" ]]; then
+          TOOLS="$TOOLS,${{ inputs.allowed_tools }}"
+        fi
+        CMD_ARGS+=("--allowedTools" "$TOOLS")
+        
+        # Add disallowed tools
+        if [[ -n "${{ inputs.disallowed_tools }}" ]]; then
+          CMD_ARGS+=("--disallowedTools" "${{ inputs.disallowed_tools }}")
+        fi
+        
+        echo "📝 Executing Claude Code with prompt from file..."
+        
+        # Execute Claude Code with timeout, using stdin for the prompt
+        TIMEOUT_SECONDS=$((${{ inputs.timeout_minutes }} * 60))
+        timeout $TIMEOUT_SECONDS claude "${CMD_ARGS[@]}" < "${{ env.PROMPT_FILE }}"
+        
+        echo "✅ Claude Code execution completed"
+      env:
+        ANTHROPIC_API_KEY: ${{ inputs.anthropic_api_key }}
+        CLAUDE_CODE_OAUTH_TOKEN: ${{ inputs.claude_code_oauth_token }}
+        GITHUB_TOKEN: ${{ inputs.github_token }} 

.github/actions/claude-issue-triage-action/action.yml

@@ -0,0 +1,91 @@
+name: "Claude Issue Triage Action"
+description: "Automatically triage GitHub issues using Claude Code"
+
+inputs:
+  timeout_minutes:
+    description: "Timeout in minutes for execution"
+    required: false
+    default: "5"
+  claude_code_oauth_token:
+    description: "Claude Code OAuth token for Pro subscription access"
+    required: true
+  github_token:
+    description: "GitHub token with repo and issues permissions"
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Checkout repository code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Create prompt
+      id: generate_prompt
+      shell: bash
+      run: |
+        mkdir -p /tmp/claude-prompts
+        cat > /tmp/claude-prompts/claude-issue-triage-prompt.txt << 'EOF'
+        You're an issue triage assistant for GitHub issues. Your task is to analyze the issue and select appropriate labels from the provided list.
+
+        IMPORTANT: Don't post any comments or messages to the issue. Your only action should be to apply labels.
+
+        Issue Information:
+        - REPO: ${{ github.repository }}
+        - ISSUE_NUMBER: ${{ github.event.issue.number }}
+
+        TASK OVERVIEW:
+
+        1. First, fetch the list of labels available in this repository by running: `gh label list`. Run exactly this command with nothing else.
+
+        2. Next, use the GitHub tools to get context about the issue:
+           - You have access to these tools:
+             - mcp__github__get_issue: Use this to retrieve the current issue's details including title, description, and existing labels
+             - mcp__github__get_issue_comments: Use this to read any discussion or additional context provided in the comments
+             - mcp__github__update_issue: Use this to apply labels to the issue (do not use this for commenting)
+             - mcp__github__search_issues: Use this to find similar issues that might provide context for proper categorization and to identify potential duplicate issues
+             - mcp__github__list_issues: Use this to understand patterns in how other issues are labeled
+           - Start by using mcp__github__get_issue to get the issue details
+
+        3. Analyze the issue content, considering:
+           - The issue title and description
+           - The type of issue (bug report, feature request, question, etc.)
+           - Technical areas mentioned
+           - Severity or priority indicators
+           - User impact
+           - Components affected
+
+        4. Select appropriate labels from the available labels list provided above:
+           - Choose labels that accurately reflect the issue's nature
+           - Be specific but comprehensive
+           - Select priority labels if you can determine urgency (high-priority, med-priority, or low-priority)
+           - Consider platform labels (android, ios) if applicable
+           - If you find similar issues using mcp__github__search_issues, consider using a "duplicate" label if appropriate. Only do so if the issue is a duplicate of another OPEN issue.
+
+        5. Apply the selected labels:
+           - Use mcp__github__update_issue to apply your selected labels
+           - DO NOT post any comments explaining your decision
+           - DO NOT communicate directly with users
+           - If no labels are clearly applicable, do not apply any labels
+
+        IMPORTANT GUIDELINES:
+        - Be thorough in your analysis
+        - Only select labels from the provided list above
+        - DO NOT post any comments to the issue
+        - Your ONLY action should be to apply labels using mcp__github__update_issue
+        - It's okay to not add any labels if none are clearly applicable
+        EOF
+        
+        echo "PROMPT<<DELIMITER" >> $GITHUB_OUTPUT
+        cat /tmp/claude-prompts/claude-issue-triage-prompt.txt >> $GITHUB_OUTPUT
+        echo "DELIMITER" >> $GITHUB_OUTPUT
+
+    - name: Run Claude Code
+      uses: ./.github/actions/claude-code-action
+      with:
+        direct_prompt: ${{ steps.generate_prompt.outputs.PROMPT }}
+        allowed_tools: "Bash(gh label list),mcp__github__get_issue,mcp__github__get_issue_comments,mcp__github__update_issue,mcp__github__search_issues,mcp__github__list_issues"
+        timeout_minutes: ${{ inputs.timeout_minutes }}
+        claude_code_oauth_token: ${{ inputs.claude_code_oauth_token }}
+        github_token: ${{ inputs.github_token }} 

.github/automation.meta.json

@@ -0,0 +1,9 @@
+{
+  "templateRepo": "MervinPraison/github-automation-template",
+  "stack": "claude",
+  "profile": "sdk",
+  "mode": "hub",
+  "hubRef": "v1.1.11",
+  "templateVersion": "1.1.7",
+  "installedAt": "2026-09-07T10:02:11Z"
+}

.github/scripts/bot-pr-review-chain.js

@@ -0,0 +1,153 @@
+/**
+ * Idempotent CodeRabbit/Qodo kick for bot-opened PRs.
+ * @see .github/workflows/auto-pr-comment.yml, claude.yml, bot-pr-recovery.yml
+ */
+
+const KICK_AUTHORS = new Set(['MervinPraison', 'github-actions[bot]']);
+const BOT_PR_AUTHORS = new Set(['praisonai-triage-agent[bot]', 'github-actions[bot]']);
+
+async function listAllComments(github, owner, repo, issueNumber) {
+  if (typeof github.paginate === 'function') {
+    return github.paginate(github.rest.issues.listComments, {
+      owner,
+      repo,
+      issue_number: issueNumber,
+      per_page: 100,
+    });
+  }
+  const { data } = await github.rest.issues.listComments({
+    owner,
+    repo,
+    issue_number: issueNumber,
+    per_page: 100,
+  });
+  return data;
+}
+
+function kickAuthored(comment, marker) {
+  return (
+    KICK_AUTHORS.has(comment.user?.login) &&
+    (comment.body || '').includes(marker)
+  );
+}
+
+function coderabbitKickPosted(comments) {
+  return comments.some((c) => kickAuthored(c, '@coderabbitai review'));
+}
+
+function qodoKickPosted(comments) {
+  return comments.some((c) => kickAuthored(c, '/review'));
+}
+
+function chainKickPosted(comments) {
+  return coderabbitKickPosted(comments) && qodoKickPosted(comments);
+}
+
+function isBotOpenedPr(pr) {
+  if (BOT_PR_AUTHORS.has(pr.user?.login)) return true;
+  return pr.user?.type === 'Bot';
+}
+
+async function kickReviewChain(github, owner, repo, prNumber, core, preFetchedComments = null) {
+  const comments = preFetchedComments || await listAllComments(github, owner, repo, prNumber);
+  const needCoderabbit = !coderabbitKickPosted(comments);
+  const needQodo = !qodoKickPosted(comments);
+
+  if (!needCoderabbit && !needQodo) {
+    core?.info?.(`Review chain already kicked on PR #${prNumber}`);
+    return { kicked: false, reason: 'already_kicked' };
+  }
+
+  if (needCoderabbit) {
+    await github.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number: prNumber,
+      body: '@coderabbitai review',
+    });
+  }
+  if (needQodo) {
+    await github.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number: prNumber,
+      body: '/review',
+    });
+  }
+  core?.info?.(`Kicked review chain for PR #${prNumber} (coderabbit=${needCoderabbit}, qodo=${needQodo})`);
+  return { kicked: true, coderabbit: needCoderabbit, qodo: needQodo };
+}
+
+async function findOpenPrForIssue(github, owner, repo, issueNumber) {
+  const prefix = `claude/issue-${issueNumber}-`;
+  const { data: prs } = await github.rest.pulls.list({
+    owner,
+    repo,
+    state: 'open',
+    sort: 'created',
+    direction: 'desc',
+    per_page: 30,
+  });
+  return (
+    prs.find(
+      (p) => (p.head?.ref || '').startsWith(prefix) && isBotOpenedPr(p)
+    ) || null
+  );
+}
+
+async function kickReviewChainForIssue(github, owner, repo, issueNumber, core) {
+  const pr = await findOpenPrForIssue(github, owner, repo, issueNumber);
+  if (!pr) {
+    core?.info?.(`No open PR for issue #${issueNumber}, skipping review kick`);
+    return { kicked: false, reason: 'no_pr' };
+  }
+  const result = await kickReviewChain(github, owner, repo, pr.number, core);
+  return { ...result, prNumber: pr.number };
+}
+
+async function recoverStalledBotPrs(github, owner, repo, options, core) {
+  const { prNumber = null, minAgeMs = 10 * 60 * 1000, maxRecover = 10 } = options || {};
+  let prs;
+  if (prNumber) {
+    const { data } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+    prs = [data];
+  } else if (typeof github.paginate === 'function') {
+    prs = await github.paginate(github.rest.pulls.list, {
+      owner,
+      repo,
+      state: 'open',
+      per_page: 100,
+    });
+  } else {
+    const { data } = await github.rest.pulls.list({ owner, repo, state: 'open', per_page: 100 });
+    prs = data;
+  }
+
+  const cutoff = Date.now() - minAgeMs;
+  let recovered = 0;
+  for (const pr of prs) {
+    if (recovered >= maxRecover) break;
+    if (!isBotOpenedPr(pr)) continue;
+    if (!prNumber && new Date(pr.created_at).getTime() > cutoff) continue;
+    const comments = await listAllComments(github, owner, repo, pr.number);
+    if (chainKickPosted(comments)) continue;
+    await kickReviewChain(github, owner, repo, pr.number, core, comments);
+    recovered += 1;
+  }
+  core?.info?.(`Recovery complete (${recovered} PR(s) kicked)`);
+  return recovered;
+}
+
+module.exports = {
+  KICK_AUTHORS,
+  BOT_PR_AUTHORS,
+  listAllComments,
+  chainKickPosted,
+  coderabbitKickPosted,
+  qodoKickPosted,
+  isBotOpenedPr,
+  kickReviewChain,
+  findOpenPrForIssue,
+  kickReviewChainForIssue,
+  recoverStalledBotPrs,
+};

.github/scripts/ci-failure-claude-selftest.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Run: node .github/scripts/ci-failure-claude-selftest.js
+ */
+const ciFix = require('./ci-failure-claude.js');
+const mergeGate = require('./merge-gate.js');
+const config = require('./gate-config.js');
+
+let failed = 0;
+function assert(name, cond) {
+  if (!cond) {
+    console.error('FAIL:', name);
+    failed += 1;
+  } else {
+    console.log('ok:', name);
+  }
+}
+
+const LOG = `
+python	UNKNOWN STEP	FAILED (0.0100s) tests/unit/test_example.py::test_foo - AssertionError: bar
+python	UNKNOWN STEP	##[error]Process completed with exit code 1.
+`;
+
+const parsed = ciFix.parsePytestFailures(LOG);
+assert('parses pytest failure', parsed.length === 1);
+assert('uses CI workflow list', config.ciFailureWorkflowRuns.includes('CI'));
+
+const comment = ciFix.buildCiFixComment({
+  headSha: 'abc1234567890abcdef1234567890abcdef12',
+  failedChecks: [{ name: 'python', workflow: 'CI', html_url: 'https://example.com/job/1' }],
+  failureSummaries: [{ jobName: 'python', failures: parsed }],
+});
+assert('comment mentions product guardrails', comment.includes('Product guardrails'));
+
+const skip = ciFix.shouldSkipCiFix({
+  comments: [],
+  headSha: 'abc1234567890abcdef1234567890abcdef12',
+  labels: [],
+  claudeInProgress: false,
+  failedChecks: [{ name: 'python', workflow: 'CI' }],
+});
+assert('ci fix without FINAL review allowed', !skip.skip);
+
+process.exit(failed ? 1 : 0);

.github/scripts/ci-failure-claude.js

@@ -0,0 +1,293 @@
+/**
+ * Post @claude comments with CI failure details for internal PRs.
+ * @see .github/workflows/ci-failure-claude.yml
+ */
+
+const mergeGate = require('./merge-gate.js');
+const config = require('./gate-config.js');
+
+const CI_FIX_LABEL = 'claude-ci-fix-pending';
+const COOLDOWN_MS = 12 * 60 * 60 * 1000;
+const AUTO_ACTORS = mergeGate.AUTO_ACTORS;
+const MAX_FAILURES = 15;
+const MAX_JOBS_TO_FETCH = 5;
+
+function shortSha(headSha) {
+  return (headSha || '').slice(0, 8);
+}
+
+function ciFixShaMarker(headSha) {
+  return `ci failed on head \`${shortSha(headSha)}`.toLowerCase();
+}
+
+function isCiFixComment(comment) {
+  const body = (comment.body || '').toLowerCase();
+  return body.includes('@claude') && body.includes('ci failed on head');
+}
+
+function hasCiFixCommentForSha(comments, headSha) {
+  const marker = shortSha(headSha).toLowerCase();
+  return comments.some((c) => {
+    if (!AUTO_ACTORS.includes(c.user.login)) return false;
+    if (!isCiFixComment(c)) return false;
+    return (c.body || '').toLowerCase().includes(marker);
+  });
+}
+
+function hasRecentCiFixComment(comments, headSha) {
+  const cutoff = Date.now() - COOLDOWN_MS;
+  const marker = shortSha(headSha).toLowerCase();
+  return comments.some((c) => {
+    if (!AUTO_ACTORS.includes(c.user.login)) return false;
+    if (!isCiFixComment(c)) return false;
+    const body = (c.body || '').toLowerCase();
+    if (body.includes(marker)) return true;
+    return new Date(c.created_at).getTime() > cutoff;
+  });
+}
+
+function shouldSkipCiFix({ comments, headSha, labels, claudeInProgress, failedChecks }) {
+  if (!failedChecks.length) return { skip: true, reason: 'no failed checks' };
+  if (labels.includes(CI_FIX_LABEL)) return { skip: true, reason: 'ci fix pending' };
+  if (claudeInProgress) return { skip: true, reason: 'claude in progress' };
+  if (hasCiFixCommentForSha(comments, headSha)) {
+    return { skip: true, reason: 'already commented for this sha' };
+  }
+  if (hasRecentCiFixComment(comments, headSha)) {
+    return { skip: true, reason: 'recent ci fix comment cooldown' };
+  }
+  return { skip: false };
+}
+
+function parsePytestFailures(logText) {
+  if (!logText) return [];
+  const lines = logText.split('\n');
+  const failures = [];
+  const seen = new Set();
+
+  for (let i = lines.length - 1; i >= 0 && failures.length < MAX_FAILURES; i -= 1) {
+    const line = lines[i].trim();
+    if (!line) continue;
+
+    const pytestMatch = line.match(
+      /FAILED\s*(?:\([^)]+\))?\s+(tests\/[^\s]+(?:::[^\s-]+)*)\s*-\s*(.+)/i
+    );
+    if (pytestMatch) {
+      const testId = pytestMatch[1];
+      if (!seen.has(testId)) {
+        seen.add(testId);
+        failures.push({ testId, error: pytestMatch[2].trim() });
+      }
+      continue;
+    }
+
+    const errorMatch = line.match(/##\[error\](.+)/);
+    if (errorMatch && /tests\//.test(errorMatch[1])) {
+      const msg = errorMatch[1].trim();
+      if (!seen.has(msg)) {
+        seen.add(msg);
+        failures.push({ testId: msg, error: msg });
+      }
+    }
+  }
+
+  return failures;
+}
+
+async function fetchJobFailureSummary(github, owner, repo, jobId, jobName) {
+  try {
+    const response = await github.rest.actions.downloadJobLogsForWorkflowRun({
+      owner,
+      repo,
+      job_id: jobId,
+    });
+    let logText = typeof response.data === 'string' ? response.data : String(response.data || '');
+    if (logText.length > 100000) {
+      logText = logText.slice(-100000);
+    }
+    return { jobName, jobId, failures: parsePytestFailures(logText) };
+  } catch (err) {
+    return { jobName, jobId, failures: [], error: err.message };
+  }
+}
+
+function mapFailedChecks(runs) {
+  return runs.map((run) => ({
+    name: run.name,
+    id: run.id,
+    html_url: run.html_url || run.details_url,
+    workflow: run.app?.slug || run.check_suite?.app?.slug || run.name,
+  }));
+}
+
+function buildCiFixComment({ headSha, failedChecks, failureSummaries }) {
+  const parts = [
+    `@claude CI failed on HEAD \`${shortSha(headSha)}\`. Please fix the failures below and push to this branch.`,
+    '',
+    '## Failed checks',
+  ];
+
+  for (const check of failedChecks) {
+    parts.push(`- **${check.workflow || check.name}** / \`${check.name}\` — ${check.html_url}`);
+  }
+
+  parts.push('', '## Failures (extracted)');
+  let idx = 0;
+  for (const summary of failureSummaries) {
+    for (const failure of summary.failures) {
+      idx += 1;
+      if (idx > MAX_FAILURES) break;
+      parts.push(`${idx}. \`${failure.testId}\` — \`${failure.error}\``);
+      parts.push(`   - Job: \`${summary.jobName}\``);
+    }
+    if (idx >= MAX_FAILURES) break;
+  }
+
+  if (idx === 0) {
+    parts.push('_(Could not extract pytest details — see job logs above.)_');
+  }
+
+  const exampleTest = failureSummaries.find((s) => s.failures.length)?.failures[0]?.testId;
+  parts.push(
+    '',
+    '## Critical review first',
+    'Before changing code or tests, decide **which side is wrong**:',
+    '1. **Legitimate feature change** — the PR intent is correct but implementation or tests need updating. Preserve product guarantees; update tests only when behaviour intentionally changed and document why.',
+    '2. **Regression / bug in this PR** — the failure exposes a real breakage introduced here. Fix the implementation; **do not weaken, skip, or delete tests** just to go green.',
+    '3. **Pre-existing flake or unrelated failure** — say so explicitly; prefer fixing the root cause over masking it.',
+    '',
+    '**Product guardrails (AGENTS.md):**',
+    '- Do not disturb PraisonAIUI contracts or frontend/backend layering to accommodate scope creep.',
+    '- Core agent runtime belongs in praisonaiagents; agent-callable tools belong in PraisonAI-Tools — not here.',
+    '- Prefer existing YAML config, plugins, and feature modules over new server.py/create_app() params or knobs with no live consumer.',
+    '- Tests must continue to guard backward compatibility and UX behaviour — passing CI by lowering test standards is not acceptable.',
+    '- If the feature does not genuinely add product value, recommend reverting or narrowing scope instead of patching around failures.',
+    '',
+    '## What to do',
+    '1. State your verdict: **legitimate fix**, **regression fix**, or **needs human review** — and why (1–3 sentences).',
+    '2. Fix root cause with **minimal changes**; never bloat server.py or create_app() with extra params.',
+    exampleTest
+      ? `3. Run failing tests locally, e.g. \`pytest ${exampleTest} -q\`, plus any related tests touched by the PR.`
+      : '3. Run failing tests locally with targeted pytest, plus any related tests touched by the PR.',
+    '4. Push to this branch and comment: files changed, review verdict, and why tests still protect product behaviour.',
+  );
+
+  return parts.join('\n');
+}
+
+async function maybeClearCiFixLabel(github, owner, repo, prNumber, labels, headSha, core) {
+  if (!labels.includes(CI_FIX_LABEL)) return false;
+  const ciGreen = await mergeGate.allChecksGreenOnSha(github, owner, repo, headSha, core);
+  if (!ciGreen) return false;
+  try {
+    await github.rest.issues.removeLabel({
+      owner,
+      repo,
+      issue_number: prNumber,
+      name: CI_FIX_LABEL,
+    });
+    core?.info?.(`Removed ${CI_FIX_LABEL} from PR #${prNumber}`);
+  } catch (err) {
+    if (err.status !== 404) throw err;
+  }
+  return true;
+}
+
+async function maybeTriggerCiFixClaude(github, owner, repo, prNumber, core, opts = {}) {
+  const baseRepo = `${owner}/${repo}`;
+  const ctx = await mergeGate.loadPrContext(github, owner, repo, prNumber);
+  const pr = ctx.pr;
+
+  if (pr.state !== 'open') return { skipped: true, reason: 'not open' };
+  if (pr.draft) return { skipped: true, reason: 'draft' };
+
+  const headRepo = pr.head.repo?.full_name;
+  if (headRepo && headRepo !== baseRepo && !pr.maintainer_can_modify) {
+    return { skipped: true, reason: 'fork without maintainer edits' };
+  }
+
+  const headSha = pr.head.sha;
+  const labels = ctx.labels;
+
+  if (await maybeClearCiFixLabel(github, owner, repo, prNumber, labels, headSha, core)) {
+    return { skipped: true, reason: 'ci green, label cleared' };
+  }
+
+  const ciGreen = await mergeGate.allChecksGreenOnSha(github, owner, repo, headSha, core);
+  if (ciGreen) return { skipped: true, reason: 'ci green' };
+
+  const runs = await mergeGate.listChecksOnSha(github, owner, repo, headSha);
+  const failedRuns = mergeGate.listFailedChecksOnSha(runs);
+  if (failedRuns.length === 0) {
+    return { skipped: true, reason: 'no failed checks yet (may be pending)' };
+  }
+
+  const claudeInProgress = await mergeGate.hasInProgressClaudeAssistant(
+    github, owner, repo, prNumber
+  );
+  const skip = shouldSkipCiFix({
+    comments: ctx.comments,
+    headSha,
+    labels,
+    claudeInProgress,
+    failedChecks: failedRuns,
+  });
+  if (skip.skip) return { skipped: true, reason: skip.reason };
+
+  const failedChecks = mapFailedChecks(failedRuns);
+  const failureSummaries = [];
+  for (const check of failedChecks.slice(0, MAX_JOBS_TO_FETCH)) {
+    failureSummaries.push(
+      await fetchJobFailureSummary(github, owner, repo, check.id, check.name)
+    );
+  }
+
+  const body = buildCiFixComment({ headSha, failedChecks, failureSummaries });
+
+  await github.rest.issues.addLabels({
+    owner,
+    repo,
+    issue_number: prNumber,
+    labels: [CI_FIX_LABEL],
+  });
+  await github.rest.issues.createComment({
+    owner,
+    repo,
+    issue_number: prNumber,
+    body,
+  });
+
+  core?.info?.(`Posted CI fix @claude on PR #${prNumber} (${shortSha(headSha)})`);
+  return { triggered: true, headSha: shortSha(headSha) };
+}
+
+async function processWorkflowRunFailure(github, owner, repo, workflowRun, core) {
+  if (workflowRun.conclusion !== 'failure') {
+    return { skipped: true, reason: `conclusion=${workflowRun.conclusion}` };
+  }
+  const allowed = config.ciFailureWorkflowRuns;
+  if (!allowed.includes(workflowRun.name)) {
+    return { skipped: true, reason: `workflow ${workflowRun.name}` };
+  }
+  const prNumber = await mergeGate.resolvePrNumberFromWorkflowRun(
+    github, owner, repo, workflowRun
+  );
+  if (!prNumber) return { skipped: true, reason: 'no linked PR' };
+  return maybeTriggerCiFixClaude(github, owner, repo, prNumber, core);
+}
+
+module.exports = {
+  CI_FIX_LABEL,
+  COOLDOWN_MS,
+  ciFixShaMarker,
+  isCiFixComment,
+  hasCiFixCommentForSha,
+  hasRecentCiFixComment,
+  shouldSkipCiFix,
+  parsePytestFailures,
+  fetchJobFailureSummary,
+  buildCiFixComment,
+  maybeClearCiFixLabel,
+  maybeTriggerCiFixClaude,
+  processWorkflowRunFailure,
+};

.github/scripts/gate-config.js

@@ -0,0 +1,55 @@
+/**
+ * PraisonAIUI gate configuration — imported by merge-gate, release-gate, ci-failure-claude.
+ */
+
+module.exports = {
+  repoFullName: 'MervinPraison/PraisonAIUI',
+  gitUser: 'MervinPraison',
+  gitEmail: '[email protected]',
+  triggerLogins: ['MervinPraison', 'github-actions[bot]'],
+  allowedTriageBots: ['praisonai-triage-agent[bot]'],
+  productPathPrefixes: ['src/praisonaiui/', 'src/frontend/', 'tests/'],
+  sensitivePathPatterns: [
+    /^\.github\/workflows\//,
+    /^pyproject\.toml$/,
+    /credentials\.json$/i,
+  ],
+  requiredCheckPatterns: [/^ci$/i, /python/i, /test/i, /lint/i, /ruff/i],
+  ciWorkflowFile: 'ci.yml',
+  ciWorkflowName: 'CI',
+  mergeGateWorkflowRuns: ['CI', 'Claude Assistant'],
+  ciFailureWorkflowRuns: ['CI'],
+  pypiPackageName: 'aiui',
+  packagePaths: ['src/praisonaiui', 'src/frontend', 'pyproject.toml'],
+  finalClaudeScope:
+    'SCOPE: Focus ONLY on PraisonAIUI (src/praisonaiui, src/frontend, tests, docs). '
+    + 'Do NOT expand into praisonaiagents or the monorepo unless the PR explicitly requires it.',
+  finalClaudeProductValue:
+    '4. Product value: review in depth whether the change genuinely adds PraisonAIUI UX value — '
+    + 'never add features for the sake of adding them. It must strengthen the UI (simpler, '
+    + 'more user-friendly, robust). If it does not clearly add value, request changes or recommend '
+    + 'rejecting/closing rather than merging scope creep.\n'
+    + '5. Layering: UI/frontend/server features here; core agent runtime belongs in praisonaiagents '
+    + '(PraisonAI monorepo). Agent-callable tools → PraisonAI-Tools. Do not pull monorepo or SDK '
+    + 'scope into this repo unless the PR explicitly requires it.\n'
+    + '6. Do not bloat server.py or create_app() with new params — prefer existing YAML config, '
+    + 'plugins, and feature modules; only add params if absolutely required. Reject knobs/exports '
+    + 'with no live consumer.',
+  mergeGateProductValue:
+    'Confirm product value gate: change strengthens PraisonAIUI UX (no scope creep). The aim is a '
+    + 'LIGHTWEIGHT AND POWERFUL package — BLOCK changes that add params/modules/exports duplicating '
+    + 'existing UI capabilities (YAML config, plugins, feature modules, existing server hooks), or '
+    + 'add knobs/fields with no live consumer, i.e. scope creep for the sake of it.',
+  mergeGateLayering:
+    'Layering routing: BLOCK if core agent logic was added here instead of praisonaiagents; BLOCK if '
+    + 'agent-callable tools were added here instead of PraisonAI-Tools.',
+  mergeGateServerBloat:
+    'Do not bloat server.py or create_app() with additional params — only if absolutely required; '
+    + 'prefer existing config/plugin patterns.',
+  agentPyChecks: false,
+  reviewBotLogins: [
+    'coderabbitai[bot]',
+    'qodo-code-review[bot]',
+    'greptile-apps[bot]',
+  ],
+};

.github/scripts/merge-gate-selftest.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/**
+ * Local self-test for merge-gate.js heuristics (no GitHub API).
+ * Run: node .github/scripts/merge-gate-selftest.js
+ */
+const mg = require('./merge-gate.js');
+
+let failed = 0;
+function assert(name, cond) {
+  if (!cond) {
+    console.error('FAIL:', name);
+    failed++;
+  } else {
+    console.log('ok:', name);
+  }
+}
+
+// Stale FINAL: push after FINAL, no @claude since head
+const finals = [
+  { user: { login: 'github-actions[bot]' }, body: '@claude FINAL architecture reviewer', created_at: '2026-06-12T08:00:00Z' },
+];
+assert('stale when head after final', mg.isStaleFinalAfterPush(finals, '2026-06-12T09:00:00Z'));
+
+const withRecovery = [
+  ...finals,
+  { user: { login: 'github-actions[bot]' }, body: '@claude FINAL architecture reviewer', created_at: '2026-06-12T09:30:00Z' },
+];
+assert('not stale when @claude after head', !mg.isStaleFinalAfterPush(withRecovery, '2026-06-12T09:00:00Z'));
+
+const withClaudeReply = [
+  ...finals,
+  {
+    user: { login: 'praisonai-triage-agent[bot]' },
+    body: "**Claude finished @MervinPraison's task** —— [View job](https://github.com/)",
+    created_at: '2026-06-12T08:30:00Z',
+  },
+];
+assert('not stale when Claude replied after FINAL', !mg.isStaleFinalAfterPush(withClaudeReply, '2026-06-12T09:00:00Z'));
+assert('claude final reply detected', mg.isClaudeFinalReplyComment(withClaudeReply[1]));
+
+assert('cancelled detect-and-trigger does not block', mg.OPTIONAL_CANCELLED_CHECKS.has('detect-and-trigger'));
+
+// Stale-FINAL recovery guards (PR #2560 push loop)
+const nowMs = Date.now();
+const iso = (ms) => new Date(ms).toISOString();
+const firstFinal = {
+  user: { login: 'MervinPraison' },
+  body: '@claude You are the FINAL architecture reviewer.',
+  created_at: iso(nowMs - 20 * 60 * 1000),
+};
+const pushSoonAfter = mg.shouldSkipStaleFinalRecovery(
+  [firstFinal],
+  iso(nowMs - 16 * 60 * 1000)
+);
+assert('debounce push soon after FINAL', pushSoonAfter.skip && pushSoonAfter.reason.includes('soon after'));
+
+const secondFinal = {
+  user: { login: 'MervinPraison' },
+  body: '@claude You are the FINAL architecture reviewer.',
+  created_at: iso(nowMs - 20 * 60 * 1000),
+};
+const capped = mg.shouldSkipStaleFinalRecovery(
+  [firstFinal, secondFinal],
+  iso(nowMs - 2 * 60 * 1000)
+);
+assert('hourly cap blocks third FINAL in window', capped.skip && capped.reason.includes('capped'));
+
+const botPush = mg.shouldSkipStaleFinalRecovery(
+  [firstFinal],
+  iso(nowMs - 16 * 60 * 1000),
+  'praisonai-triage-agent[bot]'
+);
+assert('skip when automation pushed head', botPush.skip && botPush.reason.includes('automation'));
+
+assert('claude automation login', mg.isClaudeAutomationLogin('praisonai-triage-agent[bot]'));
+
+// Bot CHANGES_REQUESTED then APPROVE
+const reviews = [
+  { user: { login: 'coderabbit[bot]', type: 'Bot' }, state: 'CHANGES_REQUESTED', submitted_at: '2026-06-12T08:00:00Z' },
+  { user: { login: 'coderabbit[bot]', type: 'Bot' }, state: 'APPROVED', submitted_at: '2026-06-12T09:00:00Z' },
+];
+assert('bot approve clears CR', !mg.hasAnyChangesRequested(reviews));
+assert('human CR blocks', mg.hasAnyChangesRequested([
+  { user: { login: 'MervinPraison', type: 'User' }, state: 'CHANGES_REQUESTED', submitted_at: '2026-06-12T09:00:00Z' },
+]));
+
+// Verdict after HEAD
+const verdictComments = [
+  { body: 'MERGE_GATE_VERDICT: APPROVE', created_at: '2026-06-12T08:00:00Z' },
+];
+assert('verdict before head rejected', mg.findMergeGateVerdict(verdictComments, null, '2026-06-12T09:00:00Z') === null);
+assert('verdict after head accepted', mg.findMergeGateVerdict(
+  [{ body: 'MERGE_GATE_VERDICT: APPROVE', created_at: '2026-06-12T10:00:00Z' }],
+  null,
+  '2026-06-12T09:00:00Z'
+) === 'APPROVE');
+
+const fallbackApprove = [
+  {
+    body: 'MERGE_GATE_VERDICT: APPROVE\n\nAutomated fallback — Claude assess did not post a verdict comment.',
+    created_at: '2026-06-12T10:00:00Z',
+  },
+];
+assert(
+  'automated fallback APPROVE ignored when Opus required',
+  mg.findMergeGateVerdict(fallbackApprove, null, '2026-06-12T09:00:00Z', { excludeAutomatedFallback: true }) === null
+);
+assert(
+  'automated fallback APPROVE still visible without Opus-only filter',
+  mg.findMergeGateVerdict(fallbackApprove, null, '2026-06-12T09:00:00Z') === 'APPROVE'
+);
+
+const fallbackBlockNewFormat = [
+  {
+    body: 'MERGE_GATE_VERDICT: BLOCK\n\nAutomated fallback — Opus merge gate assessment did not complete.',
+    created_at: '2026-06-12T10:00:00Z',
+  },
+];
+assert(
+  'new-format fallback BLOCK ignored when Opus required',
+  mg.findMergeGateVerdict(fallbackBlockNewFormat, null, '2026-06-12T09:00:00Z', { excludeAutomatedFallback: true }) === null
+);
+assert(
+  'new-format fallback BLOCK detected by marker helper',
+  mg.isAutomatedFallbackVerdict(fallbackBlockNewFormat[0].body)
+);
+assert(
+  'findMergeGateVerdict null-safe with explicit null options',
+  mg.findMergeGateVerdict(fallbackApprove, null, '2026-06-12T09:00:00Z', null) === 'APPROVE'
+);
+
+const noise = [{ user: { login: 'MervinPraison' }, body: '**Merge gate scan** — wait for `@claude`', created_at: new Date().toISOString() }];
+assert('diagnostic comment not a trigger', !mg.hasRecentClaudeTrigger(noise, 35));
+
+// Cooldown skip requires an actual verdict on HEAD, not just a FINAL trigger comment
+const recentFinalOnHead = [
+  {
+    user: { login: 'MervinPraison' },
+    body: '@claude You are the FINAL architecture reviewer.',
+    created_at: '2026-06-27T10:00:00Z',
+  },
+];
+assert(
+  'final trigger alone does not count as verdict on head',
+  mg.findMergeGateVerdict(recentFinalOnHead, null, '2026-06-27T09:55:00Z') === null
+);
+const recentVerdictOnHead = [
+  ...recentFinalOnHead,
+  {
+    user: { login: 'github-actions[bot]' },
+    body: 'MERGE_GATE_VERDICT: APPROVE',
+    created_at: '2026-06-27T10:05:00Z',
+  },
+];
+assert(
+  'verdict on head skips cooldown gate',
+  mg.findMergeGateVerdict(recentVerdictOnHead, null, '2026-06-27T09:55:00Z') === 'APPROVE'
+);
+
+// Sensitive + secrets
+assert('workflow path sensitive', mg.sensitivePathReasons([{ filename: '.github/workflows/foo.yml' }]).length === 1);
+assert('ci-only label exempts workflows', mg.sensitivePathReasons(
+  [{ filename: '.github/workflows/foo.yml' }],
+  [mg.WORKFLOW_ONLY_LABEL]
+).length === 0);
+assert('ci-only label not exempt mixed changes', mg.sensitivePathReasons(
+  [{ filename: '.github/workflows/foo.yml' }, { filename: 'src/praisonaiui/foo.py' }],
+  [mg.WORKFLOW_ONLY_LABEL]
+).length === 1);
+assert('secret in patch', mg.secretScanReasons([{ filename: 'x.py', patch: '+key = "ghp_abcdefghijklmnopqrstuvwxyz1234567890"' }]).length === 1);
+
+// Claude run scoping — other PR branches must not block
+assert('other branch claude does not block', !mg.hasBlockingClaudeRunForPr(
+  [{ event: 'issue_comment', head_branch: 'other-branch' }],
+  'my-branch'
+));
+assert('same branch claude blocks', mg.hasBlockingClaudeRunForPr(
+  [{ event: 'issue_comment', head_branch: 'my-branch' }],
+  'my-branch'
+));
+assert('issues event never blocks', !mg.hasBlockingClaudeRunForPr(
+  [{ event: 'issues', head_branch: 'my-branch' }],
+  'my-branch'
+));
+
+// Conflict rebase clears after bot completion + FINAL on HEAD (within 12h cooldown)
+const conflictNowMs = Date.now();
+const conflictIso = (offsetMs) => new Date(conflictNowMs + offsetMs).toISOString();
+const conflictTrigger = {
+  user: { login: 'MervinPraison' },
+  body: '@claude this PR has merge conflicts with main. Please rebase',
+  created_at: conflictIso(-30 * 60 * 1000),
+};
+const rebaseDone = {
+  user: { login: 'praisonai-triage-agent[bot]' },
+  body: 'Rebase complete — PR #2308 onto latest main',
+  created_at: conflictIso(-29 * 60 * 1000),
+};
+const finalAfterRebase = {
+  user: { login: 'MervinPraison' },
+  body: '@claude You are the FINAL architecture reviewer.',
+  created_at: conflictIso(-20 * 60 * 1000),
+};
+const headAfterRebase = conflictIso(-21 * 60 * 1000);
+const rebaseComments = [conflictTrigger, rebaseDone, finalAfterRebase];
+assert('conflict blocks before rebase done', mg.hasRecentConflictComment([conflictTrigger], headAfterRebase));
+assert('conflict clears after rebase + FINAL on HEAD', !mg.hasRecentConflictComment(rebaseComments, headAfterRebase));
+assert('conflict clears after rebase without FINAL on HEAD', !mg.hasRecentConflictComment(
+  [conflictTrigger, rebaseDone],
+  headAfterRebase
+));
+
+// Tests heuristic
+assert('product code without tests', mg.missingTestsReason([{ filename: 'src/praisonaiui/a/b.py', additions: 3 }]) !== null);
+assert('product code with tests ok', mg.missingTestsReason([
+  { filename: 'src/praisonaiui/a/b.py', additions: 3 },
+  { filename: 'tests/test_x.py', additions: 10 },
+]) === null);
+
+// PR size
+assert('large PR blocked', mg.prSizeReasons([{ additions: 900 }]).length > 0);
+
+assert('internal PR link accepted', mg.isInternalPullRequestLink(
+  { base: { repo: { full_name: 'MervinPraison/PraisonAIUI' } } },
+  'MervinPraison',
+  'PraisonAIUI'
+));
+assert('fork sync PR link rejected', !mg.isInternalPullRequestLink(
+  { number: 21, base: { repo: { full_name: 'Milkmange/PraisonAIUI' } } },
+  'MervinPraison',
+  'PraisonAIUI'
+));
+
+process.exit(failed ? 1 : 0);

.github/scripts/merge-gate.js

@@ -0,0 +1,940 @@
+/**
+ * Shared merge-gate helpers for claude-merge-gate.yml
+ * @see .github/workflows/claude-merge-gate.yml
+ */
+
+const config = require('./gate-config.js');
+
+const CLAUDE_TRIGGER_LOGINS = ['MervinPraison', 'github-actions[bot]'];
+const AUTO_ACTORS = CLAUDE_TRIGGER_LOGINS;
+const CONFLICT_COOLDOWN_MS = 12 * 60 * 60 * 1000;
+const CLAUDE_ACTIVE_MS = 35 * 60 * 1000;
+const STALE_FINAL_RECOVERY_WINDOW_MS = 60 * 60 * 1000;
+const STALE_FINAL_MAX_PER_WINDOW = 2;
+const PUSH_AFTER_FINAL_DEBOUNCE_MS = 15 * 60 * 1000;
+const ALLOWED_MERGE_STATES = new Set(['CLEAN', 'UNSTABLE']);
+const AGENT_PY_MAX_AUTO_LINES = 100;
+const PR_MAX_AUTO_ADDITIONS = 800;
+const PR_MAX_AUTO_FILES = 30;
+const MANUAL_ONLY_LABELS = new Set(['security', 'breaking-change', 'needs-manual-review', 'release']);
+const WORKFLOW_ONLY_LABEL = 'merge-gate-ci-only';
+const CI_ONLY_PATH_PREFIXES = ['.github/workflows/', '.github/actions/', '.github/scripts/merge-gate'];
+const SDK_PATH_PREFIXES = config.productPathPrefixes;
+const SENSITIVE_PATH_PATTERNS = config.sensitivePathPatterns;
+const REQUIRED_SDK_CHECK_PATTERNS = config.requiredCheckPatterns;
+const SECRET_PATTERNS = [
+  /sk-[a-zA-Z0-9]{20,}/,
+  /AKIA[0-9A-Z]{16}/,
+  /ghp_[a-zA-Z0-9]{36,}/,
+  /github_pat_/,
+  /Bearer eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/,
+  /-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----/,
+];
+const BLOCK_LABELS = new Set([
+  'claude-conflict-pending',
+  'claude-merge-gate-active',
+  'no-auto-merge',
+  'auto-merged-by-gate',
+]);
+const MERGE_READY_LABEL = 'pipeline/merge-ready';
+/** Superseded concurrency runs; must not block merge when real tests passed. */
+const OPTIONAL_CANCELLED_CHECKS = new Set(['detect-and-trigger']);
+const BOT_REVIEWER_PATTERNS = [
+  'coderabbit',
+  'qodo',
+  'gemini',
+  'copilot',
+  'greptile',
+];
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function isFinalClaudeTriggerComment(c) {
+  const body = (c.body || '').toLowerCase();
+  if (!AUTO_ACTORS.includes(c.user.login)) return false;
+  if (!body.includes('@claude')) return false;
+  if (body.includes('merge conflict')) return false;
+  return body.includes('final architecture reviewer') || body.includes('lead engineer');
+}
+
+function isClaudeTriggerNoise(c) {
+  const body = c.body || '';
+  if (body.includes('Merge gate scan')) return true;
+  if (body.includes('MERGE_GATE_VERDICT')) return true;
+  if (body.includes('Merged by **Claude PR merge gate**')) return true;
+  return false;
+}
+
+function isClaudeFinalReplyComment(c) {
+  const login = (c.user?.login || '').toLowerCase();
+  const fromAutomation =
+    login.includes('praisonai-triage') ||
+    login.includes('github-actions') ||
+    AUTO_ACTORS.some((a) => a.toLowerCase() === login);
+  if (!fromAutomation) return false;
+  return (c.body || '').includes('Claude finished');
+}
+
+function hasRecentClaudeTrigger(comments, minutes = 35) {
+  const cutoff = Date.now() - minutes * 60 * 1000;
+  return comments.some((c) => {
+    if (!CLAUDE_TRIGGER_LOGINS.includes(c.user.login)) return false;
+    if (isClaudeTriggerNoise(c)) return false;
+    if (!(c.body || '').includes('@claude')) return false;
+    return new Date(c.created_at).getTime() > cutoff;
+  });
+}
+
+function isConflictRebaseTriggerComment(c) {
+  if (!AUTO_ACTORS.includes(c.user.login)) return false;
+  const body = (c.body || '').toLowerCase();
+  return body.includes('@claude') && body.includes('merge conflict');
+}
+
+function isConflictRebaseCompletionComment(c) {
+  const login = (c.user?.login || '').toLowerCase();
+  const fromAutomation =
+    login.includes('praisonai-triage') ||
+    login.includes('github-actions') ||
+    AUTO_ACTORS.some((a) => a.toLowerCase() === login);
+  if (!fromAutomation) return false;
+  const body = (c.body || '').toLowerCase();
+  return (
+    body.includes('rebase complete') ||
+    body.includes('rebase onto') ||
+    body.includes('force-pushed') ||
+    (body.includes('conflict') && body.includes('resolved'))
+  );
+}
+
+/** HEAD landed after conflict rebase but no FINAL @claude since that push. */
+function needsFinalReReviewAfterConflictRebase(comments, headPushedAt) {
+  if (!headPushedAt) return false;
+  const headTime = new Date(headPushedAt).getTime();
+  const conflictTriggers = comments.filter(isConflictRebaseTriggerComment);
+  if (conflictTriggers.length === 0) return false;
+
+  const latestConflict = conflictTriggers.reduce((a, b) =>
+    new Date(a.created_at) > new Date(b.created_at) ? a : b
+  );
+  const conflictTime = new Date(latestConflict.created_at).getTime();
+  if (headTime <= conflictTime) return false;
+
+  const rebaseDone = comments.some(
+    (c) =>
+      new Date(c.created_at).getTime() > conflictTime && isConflictRebaseCompletionComment(c)
+  );
+  if (!rebaseDone) return false;
+
+  const finalsAfterHead = comments.filter(
+    (c) =>
+      isFinalClaudeTriggerComment(c) &&
+      new Date(c.created_at).getTime() >= headTime - 60000
+  );
+  return finalsAfterHead.length === 0;
+}
+
+function conflictRebaseQuiescent(comments, headPushedAt) {
+  const conflictTriggers = comments.filter(isConflictRebaseTriggerComment);
+  if (conflictTriggers.length === 0) return true;
+
+  const latestConflict = conflictTriggers.reduce((a, b) =>
+    new Date(a.created_at) > new Date(b.created_at) ? a : b
+  );
+  const conflictTime = new Date(latestConflict.created_at).getTime();
+
+  const rebaseDone = comments.some(
+    (c) =>
+      new Date(c.created_at).getTime() > conflictTime && isConflictRebaseCompletionComment(c)
+  );
+  if (!rebaseDone) return false;
+
+  return true;
+}
+
+function hasRecentConflictComment(comments, headPushedAt = null) {
+  const cutoff = Date.now() - CONFLICT_COOLDOWN_MS;
+  const hasRecentTrigger = comments.some((c) => {
+    if (!isConflictRebaseTriggerComment(c)) return false;
+    return new Date(c.created_at).getTime() > cutoff;
+  });
+  if (!hasRecentTrigger) return false;
+
+  if (headPushedAt && conflictRebaseQuiescent(comments, headPushedAt)) {
+    return false;
+  }
+  return true;
+}
+
+function isBotReviewer(login, userType) {
+  const lower = (login || '').toLowerCase();
+  if (userType === 'Bot') return true;
+  if (lower.endsWith('[bot]')) return true;
+  return ['coderabbit', 'qodo', 'gemini', 'copilot', 'greptile'].some((p) => lower.includes(p));
+}
+
+function latestReviewsByUser(reviews) {
+  const latestByUser = new Map();
+  for (const r of reviews) {
+    const login = r.user?.login;
+    if (!login) continue;
+    const prev = latestByUser.get(login);
+    if (!prev || new Date(r.submitted_at) > new Date(prev.submitted_at)) {
+      latestByUser.set(login, r);
+    }
+  }
+  return latestByUser;
+}
+
+function hasHumanChangesRequested(reviews) {
+  for (const [login, review] of latestReviewsByUser(reviews)) {
+    if (review.state !== 'CHANGES_REQUESTED') continue;
+    if (!isBotReviewer(login, review.user?.type)) return true;
+  }
+  return false;
+}
+
+function hasAnyChangesRequested(reviews) {
+  for (const [, review] of latestReviewsByUser(reviews)) {
+    if (review.state === 'CHANGES_REQUESTED') return true;
+  }
+  return false;
+}
+
+function hasFinalClaudeReviewTrigger(comments) {
+  return comments.some(isFinalClaudeTriggerComment);
+}
+
+function isStaleFinalAfterPush(comments, headPushedAt) {
+  if (!headPushedAt) return false;
+  const headTime = new Date(headPushedAt).getTime();
+  const finals = comments.filter(isFinalClaudeTriggerComment);
+  if (finals.length === 0) return true;
+  const latestFinal = finals.reduce((a, b) =>
+    new Date(a.created_at) > new Date(b.created_at) ? a : b
+  );
+  const finalTime = new Date(latestFinal.created_at).getTime();
+  if (headTime <= finalTime + 60000) return false;
+  const claudeRepliedAfterFinal = comments.some((c) => {
+    if (!isClaudeFinalReplyComment(c)) return false;
+    return new Date(c.created_at).getTime() >= finalTime - 60000;
+  });
+  if (claudeRepliedAfterFinal) return false;
+  const claudeSinceHead = comments.some((c) => {
+    if (!CLAUDE_TRIGGER_LOGINS.includes(c.user.login)) return false;
+    if (isClaudeTriggerNoise(c)) return false;
+    if (!(c.body || '').includes('@claude')) return false;
+    return new Date(c.created_at).getTime() >= headTime - 60000;
+  });
+  return !claudeSinceHead;
+}
+
+function needsStaleFinalRecovery(comments, headPushedAt) {
+  return (
+    hasFinalClaudeReviewTrigger(comments) &&
+    isStaleFinalAfterPush(comments, headPushedAt)
+  );
+}
+
+function shouldSkipFinalRecovery(comments, headPushedAt) {
+  const isStale = isStaleFinalAfterPush(comments, headPushedAt);
+  if (isStale) return false;
+  return hasRecentClaudeTrigger(comments, 35);
+}
+
+function countFinalTriggersSince(comments, sinceMs) {
+  return comments.filter(
+    (c) => isFinalClaudeTriggerComment(c) && new Date(c.created_at).getTime() > sinceMs
+  ).length;
+}
+
+function isClaudeAutomationLogin(login) {
+  const lower = (login || '').toLowerCase();
+  return lower.includes('praisonai-triage') || lower === 'github-actions[bot]';
+}
+
+function isPushSoonAfterLatestFinal(comments, headPushedAt) {
+  if (!headPushedAt) return false;
+  const finals = comments.filter(isFinalClaudeTriggerComment);
+  if (finals.length === 0) return false;
+  const latestFinal = finals.reduce((a, b) =>
+    new Date(a.created_at) > new Date(b.created_at) ? a : b
+  );
+  const finalTime = new Date(latestFinal.created_at).getTime();
+  const headTime = new Date(headPushedAt).getTime();
+  if (headTime <= finalTime) return false;
+  return headTime - finalTime < PUSH_AFTER_FINAL_DEBOUNCE_MS;
+}
+
+/** Returns { skip: true, reason } when stale-FINAL recovery should not post. */
+function shouldSkipStaleFinalRecovery(comments, headPushedAt, headPusherLogin = null) {
+  if (!isStaleFinalAfterPush(comments, headPushedAt)) {
+    return { skip: true, reason: 'not stale' };
+  }
+  if (headPusherLogin && isClaudeAutomationLogin(headPusherLogin)) {
+    return { skip: true, reason: 'head pushed by Claude automation' };
+  }
+  if (needsFinalReReviewAfterConflictRebase(comments, headPushedAt)) {
+    return { skip: false, reason: '' };
+  }
+  if (isPushSoonAfterLatestFinal(comments, headPushedAt)) {
+    return {
+      skip: true,
+      reason: 'head pushed soon after FINAL (wait for CI / batched fixes)',
+    };
+  }
+  const windowStart = Date.now() - STALE_FINAL_RECOVERY_WINDOW_MS;
+  const finalsInWindow = countFinalTriggersSince(comments, windowStart);
+  if (finalsInWindow >= STALE_FINAL_MAX_PER_WINDOW) {
+    return {
+      skip: true,
+      reason: `stale-FINAL capped (${finalsInWindow} FINAL triggers in last hour)`,
+    };
+  }
+  return { skip: false, reason: '' };
+}
+
+function finalClaudeCompletedOnSha(comments, headPushedAt) {
+  if (!hasFinalClaudeReviewTrigger(comments)) return false;
+  if (isStaleFinalAfterPush(comments, headPushedAt)) return false;
+  return true;
+}
+
+const FINAL_CLAUDE_REVIEW_BODY =
+  `@claude You are the FINAL architecture reviewer. If the branch is under ${config.repoFullName} (not a fork), you are able to make modifications to this branch and push directly. ${config.finalClaudeScope} Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions (lazy imports, import-time <200ms)\n${config.finalClaudeProductValue}\n\n**Phase 2: FIX Valid Issues**\n5. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n6. Push all code fixes directly to THIS branch (do NOT create a new PR)\n7. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n8. If all issues are resolved, approve the PR / close the Issue\n9. If blocking issues remain, request changes / leave clear action items`;
+
+async function getMergeState(github, owner, repo, prNumber) {
+  const query = `
+    query($owner: String!, $repo: String!, $number: Int!) {
+      repository(owner: $owner, name: $repo) {
+        pullRequest(number: $number) {
+          mergeStateStatus
+          maintainerCanModify
+          isDraft
+          headRefOid
+          headRef { repository { nameWithOwner } }
+        }
+      }
+    }
+  `;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const result = await github.graphql(query, { owner, repo, number: prNumber });
+    const prGql = result.repository.pullRequest;
+    const status = (prGql?.mergeStateStatus || '').toUpperCase();
+    if (status && status !== 'UNKNOWN') {
+      return {
+        status,
+        isDraft: prGql.isDraft,
+        headRepo: prGql.headRef?.repository?.nameWithOwner,
+        headSha: prGql.headRefOid,
+        maintainerCanModify: prGql.maintainerCanModify === true,
+      };
+    }
+    if (attempt < 2) await sleep(10000);
+  }
+  const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+  return {
+    status: (pr.mergeable_state || '').toUpperCase(),
+    isDraft: pr.draft,
+    headRepo: pr.head.repo?.full_name,
+    headSha: pr.head.sha,
+    maintainerCanModify: pr.maintainer_can_modify === true,
+  };
+}
+
+async function listChecksOnSha(github, owner, repo, sha) {
+  const { data } = await github.rest.checks.listForRef({
+    owner,
+    repo,
+    ref: sha,
+    per_page: 100,
+  });
+  return (data.check_runs || []).filter((r) => r.head_sha === sha);
+}
+
+function listFailedChecksOnSha(runs) {
+  return (runs || []).filter((run) => {
+    if (run.status !== 'completed') return false;
+    return run.conclusion === 'failure';
+  });
+}
+
+async function allChecksGreenOnSha(github, owner, repo, sha, core) {
+  const runs = await listChecksOnSha(github, owner, repo, sha);
+  if (runs.length === 0) {
+    core?.info?.(`No check runs on ${sha.slice(0, 7)} — allowing (e.g. docs-only PR)`);
+    return true;
+  }
+  for (const run of runs) {
+    if (run.status !== 'completed') {
+      core?.info?.(`Check pending: ${run.name} (${run.status})`);
+      return false;
+    }
+    const ok =
+      ['success', 'neutral', 'skipped'].includes(run.conclusion) ||
+      (run.conclusion === 'cancelled' && OPTIONAL_CANCELLED_CHECKS.has(run.name));
+    if (!ok) {
+      core?.info?.(`Check failed: ${run.name} (${run.conclusion})`);
+      return false;
+    }
+  }
+  return true;
+}
+
+function claudeRunBlocksPr(run, headRef) {
+  if (!run || run.event === 'issues') return false;
+  if (!headRef) return true;
+  return run.head_branch === headRef;
+}
+
+function hasBlockingClaudeRunForPr(runs, headRef) {
+  return (runs || []).some((r) => claudeRunBlocksPr(r, headRef));
+}
+
+async function hasInProgressClaudeAssistant(github, owner, repo, prNumber = null) {
+  try {
+    const { data } = await github.rest.actions.listWorkflowRuns({
+      owner,
+      repo,
+      workflow_id: 'claude.yml',
+      status: 'in_progress',
+      per_page: 20,
+    });
+    const runs = (data.workflow_runs || []).filter((r) => r.event !== 'issues');
+    if (runs.length === 0) return false;
+    if (prNumber == null) return runs.length > 0;
+
+    const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+    const headRef = pr.head.ref;
+    return hasBlockingClaudeRunForPr(runs, headRef);
+  } catch {
+    return false;
+  }
+}
+
+function isCiOnlyChange(files) {
+  if (!files.length) return false;
+  return files.every((f) => CI_ONLY_PATH_PREFIXES.some((p) => f.filename.startsWith(p)));
+}
+
+function isInternalPullRequestLink(link, owner, repo) {
+  if (link?.base?.repo?.full_name === `${owner}/${repo}`) return true;
+  const baseUrl = link?.base?.repo?.url || '';
+  return baseUrl.endsWith(`/repos/${owner}/${repo}`);
+}
+
+async function resolvePrNumberFromLinkedPullRequests(github, owner, repo, linked) {
+  const repoFull = `${owner}/${repo}`;
+  const internal = (linked || []).filter((l) => isInternalPullRequestLink(l, owner, repo));
+  for (const link of internal) {
+    if (!link.number) continue;
+    try {
+      const { data } = await github.rest.pulls.get({
+        owner,
+        repo,
+        pull_number: link.number,
+      });
+      if (data.state === 'open' && data.base?.repo?.full_name === repoFull) {
+        return data.number;
+      }
+    } catch (err) {
+      if (err.status !== 404) throw err;
+    }
+  }
+  return null;
+}
+
+async function resolvePrNumberFromHeadBranch(github, owner, repo, branch) {
+  if (!branch || branch === 'main' || branch === 'master') return null;
+  const { data } = await github.rest.pulls.list({
+    owner,
+    repo,
+    state: 'open',
+    head: `${owner}:${branch}`,
+    per_page: 1,
+  });
+  return data[0]?.number || null;
+}
+
+async function resolvePrNumberFromWorkflowRun(github, owner, repo, workflowRun) {
+  const fromLinked = await resolvePrNumberFromLinkedPullRequests(
+    github, owner, repo, workflowRun.pull_requests
+  );
+  if (fromLinked) return fromLinked;
+
+  const fromBranch = await resolvePrNumberFromHeadBranch(
+    github, owner, repo, workflowRun.head_branch
+  );
+  if (fromBranch) return fromBranch;
+
+  return null;
+}
+
+async function listPullFiles(github, owner, repo, prNumber) {
+  if (typeof github.paginate === 'function') {
+    return github.paginate(github.rest.pulls.listFiles, {
+      owner,
+      repo,
+      pull_number: prNumber,
+      per_page: 100,
+    });
+  }
+  const { data } = await github.rest.pulls.listFiles({
+    owner,
+    repo,
+    pull_number: prNumber,
+    per_page: 100,
+  });
+  return data;
+}
+
+function countNewAgentParams(patch) {
+  if (!patch) return 0;
+  return patch
+    .split('\n')
+    .filter((l) => l.startsWith('+') && !l.startsWith('+++'))
+    .filter((l) => {
+      const t = l.slice(1).trim();
+      if (!t || t.startsWith('#') || t.startsWith('"""') || t.startsWith("'''")) return false;
+      if (/^(def|class|@|return\b|if\b|elif\b|else\b|for\b|while\b)/.test(t)) return false;
+      if (/^\w+\s*[:=]/.test(t) && !t.startsWith('self.')) return true;
+      return false;
+    }).length;
+}
+
+function getAgentPyChangeFromFiles(files) {
+  const agentFile = files.find((f) => f.filename.endsWith('praisonaiagents/agent/agent.py'));
+  if (!agentFile) {
+    return { touched: false, additions: 0, newParams: 0 };
+  }
+  return {
+    touched: true,
+    additions: agentFile.additions || 0,
+    newParams: countNewAgentParams(agentFile.patch || ''),
+  };
+}
+
+async function getAgentPyChange(github, owner, repo, prNumber) {
+  const files = await listPullFiles(github, owner, repo, prNumber);
+  return getAgentPyChangeFromFiles(files);
+}
+
+function touchesSdk(files) {
+  return files.some((f) => SDK_PATH_PREFIXES.some((p) => f.filename.startsWith(p)));
+}
+
+function hasManualOnlyLabel(labels) {
+  return labels.some((l) => MANUAL_ONLY_LABELS.has(l));
+}
+
+function sensitivePathReasons(files, labels = []) {
+  if (labels.includes(WORKFLOW_ONLY_LABEL) && isCiOnlyChange(files)) {
+    return [];
+  }
+  const reasons = [];
+  for (const f of files) {
+    if (SENSITIVE_PATH_PATTERNS.some((p) => p.test(f.filename))) {
+      reasons.push(`sensitive path: ${f.filename}`);
+      break;
+    }
+  }
+  return reasons;
+}
+
+function prSizeReasons(files) {
+  const reasons = [];
+  const totalAdditions = files.reduce((sum, f) => sum + (f.additions || 0), 0);
+  if (totalAdditions > PR_MAX_AUTO_ADDITIONS) {
+    reasons.push(`PR +${totalAdditions} lines (>${PR_MAX_AUTO_ADDITIONS}) requires manual review`);
+  }
+  if (files.length > PR_MAX_AUTO_FILES) {
+    reasons.push(`${files.length} files changed (>${PR_MAX_AUTO_FILES}) requires manual review`);
+  }
+  return reasons;
+}
+
+function missingTestsReason(files) {
+  const productAdds = files.filter(
+    (f) =>
+      SDK_PATH_PREFIXES.some((p) => f.filename.startsWith(p)) &&
+      f.filename.startsWith('src/praisonaiui/') &&
+      f.filename.endsWith('.py') &&
+      !f.filename.endsWith('__init__.py') &&
+      (f.additions || 0) > 0
+  );
+  if (productAdds.length === 0) return null;
+  const hasTestChange = files.some(
+    (f) => /\/tests?\//.test(f.filename) || /test_.*\.py$/.test(f.filename) || /_test\.py$/.test(f.filename)
+  );
+  if (!hasTestChange) return 'Product code added without test file changes — requires manual review';
+  return null;
+}
+
+function secretScanReasons(files) {
+  for (const f of files) {
+    if (/\/tests?\//.test(f.filename) || /test_.*\.py$/.test(f.filename)) continue;
+    const patch = f.patch || '';
+    if (!patch) continue;
+    for (const pattern of SECRET_PATTERNS) {
+      if (pattern.test(patch)) {
+        return [`possible secret in diff (${f.filename}) — requires manual review`];
+      }
+    }
+  }
+  return [];
+}
+
+async function sdkTestChecksReason(github, owner, repo, sha, files, core) {
+  if (!touchesSdk(files)) return null;
+  const { data } = await github.rest.checks.listForRef({
+    owner,
+    repo,
+    ref: sha,
+    per_page: 100,
+  });
+  const runs = (data.check_runs || []).filter((r) => r.head_sha === sha);
+  if (runs.length === 0) {
+    return 'SDK code changed but no CI checks on HEAD';
+  }
+  const testRuns = runs.filter((r) => REQUIRED_SDK_CHECK_PATTERNS.some((p) => p.test(r.name || '')));
+  if (testRuns.length === 0) {
+    return 'SDK code changed but no test check runs on HEAD';
+  }
+  core?.info?.(`SDK test checks on HEAD: ${testRuns.map((r) => r.name).join(', ')}`);
+  return null;
+}
+
+function manualReviewReasonForAgentPy(agentChange) {
+  if (!agentChange.touched) return null;
+  if (agentChange.additions > AGENT_PY_MAX_AUTO_LINES) {
+    return `agent.py +${agentChange.additions} lines (>${AGENT_PY_MAX_AUTO_LINES}) requires manual review`;
+  }
+  if (agentChange.newParams > 0) {
+    return `agent.py adds ${agentChange.newParams} new Agent param(s) — requires manual review`;
+  }
+  return null;
+}
+
+async function listAllComments(github, owner, repo, issueNumber) {
+  if (typeof github.paginate === 'function') {
+    return github.paginate(github.rest.issues.listComments, {
+      owner,
+      repo,
+      issue_number: issueNumber,
+      per_page: 100,
+    });
+  }
+  const { data } = await github.rest.issues.listComments({
+    owner,
+    repo,
+    issue_number: issueNumber,
+    per_page: 100,
+  });
+  return data;
+}
+
+async function getHeadCommitDate(github, owner, repo, prNumber) {
+  try {
+    let commits;
+    if (typeof github.paginate === 'function') {
+      commits = await github.paginate(github.rest.pulls.listCommits, {
+        owner,
+        repo,
+        pull_number: prNumber,
+        per_page: 100,
+      });
+    } else {
+      const { data } = await github.rest.pulls.listCommits({
+        owner,
+        repo,
+        pull_number: prNumber,
+        per_page: 100,
+      });
+      commits = data;
+    }
+    const last = commits[commits.length - 1];
+    return last?.commit?.committer?.date || last?.commit?.author?.date || null;
+  } catch {
+    return null;
+  }
+}
+
+async function loadPrContext(github, owner, repo, prNumber) {
+  const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+  const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: prNumber });
+  const comments = await listAllComments(github, owner, repo, prNumber);
+  const { data: reviews } = await github.rest.pulls.listReviews({
+    owner,
+    repo,
+    pull_number: prNumber,
+    per_page: 100,
+  });
+  const mergeState = await getMergeState(github, owner, repo, prNumber);
+  const headSha = mergeState.headSha || pr.head.sha;
+  const headCommitDate = await getHeadCommitDate(github, owner, repo, prNumber);
+  const headPushedAt = headCommitDate || pr.updated_at;
+
+  return {
+    pr,
+    issue,
+    comments,
+    reviews,
+    mergeState,
+    headSha,
+    headPushedAt,
+    labels: issue.labels.map((l) => l.name),
+    baseRepo: `${owner}/${repo}`,
+  };
+}
+
+async function evaluatePipelineQuiescent(github, owner, repo, prNumber, core, options = {}) {
+  const {
+    forMergeStep = false,
+    skipGlobalClaudeRunCheck = false,
+    skipRecentClaudeCooldown = false,
+  } = options;
+  const ctx = await loadPrContext(github, owner, repo, prNumber);
+  const reasons = [];
+
+  if (ctx.pr.draft) reasons.push('draft');
+  if (ctx.pr.state !== 'open') reasons.push('not open');
+  if (ctx.labels.includes('auto-merged-by-gate')) reasons.push('already merged by gate');
+  if (ctx.labels.includes('no-auto-merge')) reasons.push('no-auto-merge label');
+  if (ctx.labels.includes('claude-conflict-pending')) reasons.push('claude-conflict-pending');
+  if (!forMergeStep && ctx.labels.includes('claude-merge-gate-active')) {
+    reasons.push('claude-merge-gate-active');
+  }
+
+  const { status, headRepo, maintainerCanModify } = ctx.mergeState;
+  if (!ALLOWED_MERGE_STATES.has(status)) reasons.push(`mergeState=${status}`);
+
+  if (headRepo && headRepo !== ctx.baseRepo) {
+    reasons.push('fork PR');
+  }
+
+  if (hasRecentConflictComment(ctx.comments, ctx.headPushedAt)) {
+    reasons.push('recent merge-conflict @claude');
+  }
+  if (!skipRecentClaudeCooldown && hasRecentClaudeTrigger(ctx.comments, 35)) {
+    const verdictOnHead = findMergeGateVerdict(ctx.comments, null, ctx.headPushedAt) !== null;
+    if (!verdictOnHead) reasons.push('recent @claude within 35min');
+  }
+
+  if (!skipGlobalClaudeRunCheck && (await hasInProgressClaudeAssistant(github, owner, repo, prNumber))) {
+    reasons.push('claude.yml in progress');
+  }
+
+  const checksOk = await allChecksGreenOnSha(github, owner, repo, ctx.headSha, core);
+  if (!checksOk) reasons.push('CI not green on HEAD');
+
+  if (!finalClaudeCompletedOnSha(ctx.comments, ctx.headPushedAt)) {
+    if (!hasFinalClaudeReviewTrigger(ctx.comments)) {
+      reasons.push('no FINAL Claude review trigger');
+    } else if (isStaleFinalAfterPush(ctx.comments, ctx.headPushedAt)) {
+      reasons.push('stale FINAL after new commits (needs @claude re-review)');
+    } else {
+      reasons.push('FINAL Claude not complete on HEAD');
+    }
+  }
+
+  if (hasAnyChangesRequested(ctx.reviews)) reasons.push('CHANGES_REQUESTED review');
+
+  if (hasManualOnlyLabel(ctx.labels)) {
+    const manualLabel = ctx.labels.find((l) => MANUAL_ONLY_LABELS.has(l));
+    reasons.push(`manual-only label: ${manualLabel}`);
+  }
+
+  const pullFiles = await listPullFiles(github, owner, repo, prNumber);
+
+  if (config.agentPyChecks) {
+    const agentChange = getAgentPyChangeFromFiles(pullFiles);
+    const agentManual = manualReviewReasonForAgentPy(agentChange);
+    if (agentManual) reasons.push(agentManual);
+  }
+
+  reasons.push(...sensitivePathReasons(pullFiles, ctx.labels));
+  reasons.push(...prSizeReasons(pullFiles));
+  reasons.push(...secretScanReasons(pullFiles));
+
+  const testsReason = missingTestsReason(pullFiles);
+  if (testsReason) reasons.push(testsReason);
+
+  const sdkCheckReason = await sdkTestChecksReason(github, owner, repo, ctx.headSha, pullFiles, core);
+  if (sdkCheckReason) reasons.push(sdkCheckReason);
+
+  if (ctx.pr.mergeable === false) reasons.push('not mergeable');
+
+  const ready = reasons.length === 0;
+  return {
+    ready,
+    reasons,
+    headSha: ctx.headSha,
+    prNumber,
+  };
+}
+
+async function listPrNumbersForMergeGateScan(github, owner, repo, core) {
+  let mergeReadyIssues;
+  if (typeof github.paginate === 'function') {
+    mergeReadyIssues = await github.paginate(github.rest.issues.listForRepo, {
+      owner,
+      repo,
+      state: 'open',
+      labels: MERGE_READY_LABEL,
+      per_page: 100,
+    });
+  } else {
+    ({ data: mergeReadyIssues } = await github.rest.issues.listForRepo({
+      owner,
+      repo,
+      state: 'open',
+      labels: MERGE_READY_LABEL,
+      per_page: 100,
+    }));
+  }
+  const mergeReady = mergeReadyIssues
+    .filter((issue) => issue.pull_request)
+    .map((issue) => issue.number)
+    .sort((a, b) => a - b);
+
+  if (mergeReady.length > 0) {
+    core?.info?.(
+      `Merge gate scan: ${mergeReady.length} ${MERGE_READY_LABEL} PR(s) (skipping unlabelled open PRs)`
+    );
+    return mergeReady;
+  }
+
+  core?.info?.(`No ${MERGE_READY_LABEL} PRs — scanning oldest open PRs`);
+  const prs =
+    typeof github.paginate === 'function'
+      ? await github.paginate(github.rest.pulls.list, {
+          owner,
+          repo,
+          state: 'open',
+          per_page: 100,
+          sort: 'created',
+          direction: 'asc',
+        })
+      : (await github.rest.pulls.list({
+          owner,
+          repo,
+          state: 'open',
+          per_page: 100,
+          sort: 'created',
+          direction: 'asc',
+        })).data;
+  return prs.map((pr) => pr.number);
+}
+
+async function selectMergeGateCandidates(github, owner, repo, prNumbers, maxCandidates, core) {
+  const readyList = [];
+  const skipped = [];
+  for (const num of prNumbers) {
+    if (readyList.length >= maxCandidates) {
+      core?.info?.(`Found ${maxCandidates} candidate(s) — skipping remaining PR scans`);
+      break;
+    }
+    const result = await evaluatePipelineQuiescent(github, owner, repo, num, core);
+    if (result.ready) {
+      readyList.push({ pr_number: num, head_sha: result.headSha });
+    } else {
+      skipped.push({ pr: num, reasons: result.reasons });
+    }
+  }
+  readyList.sort((a, b) => a.pr_number - b.pr_number);
+  return {
+    candidates: readyList.slice(0, maxCandidates),
+    skipped,
+  };
+}
+
+const AUTOMATED_FALLBACK_MARKER = 'Automated fallback —';
+
+function isAutomatedFallbackVerdict(body) {
+  return (body || '').includes(AUTOMATED_FALLBACK_MARKER);
+}
+
+function findMergeGateVerdict(comments, minCreatedAt = null, headPushedAt = null, options = {}) {
+  const { excludeAutomatedFallback = false } = options || {};
+  const minTime = minCreatedAt ? new Date(minCreatedAt).getTime() : 0;
+  const headTime = headPushedAt ? new Date(headPushedAt).getTime() - 60000 : 0;
+  const gateComments = comments
+    .filter((c) => {
+      if (!(c.body || '').includes('MERGE_GATE_VERDICT:')) return false;
+      if (excludeAutomatedFallback && isAutomatedFallbackVerdict(c.body)) return false;
+      const created = new Date(c.created_at).getTime();
+      if (minTime && created < minTime) return false;
+      if (headTime && created < headTime) return false;
+      return true;
+    })
+    .sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
+  if (gateComments.length === 0) return null;
+  const body = gateComments[0].body || '';
+  if (body.includes('MERGE_GATE_VERDICT: APPROVE')) return 'APPROVE';
+  if (body.includes('MERGE_GATE_VERDICT: BLOCK')) return 'BLOCK';
+  return null;
+}
+
+module.exports = {
+  CLAUDE_TRIGGER_LOGINS,
+  AUTO_ACTORS,
+  isFinalClaudeTriggerComment,
+  isClaudeTriggerNoise,
+  isClaudeFinalReplyComment,
+  hasRecentClaudeTrigger,
+  hasRecentConflictComment,
+  isConflictRebaseTriggerComment,
+  isConflictRebaseCompletionComment,
+  needsFinalReReviewAfterConflictRebase,
+  conflictRebaseQuiescent,
+  hasHumanChangesRequested,
+  hasAnyChangesRequested,
+  hasFinalClaudeReviewTrigger,
+  finalClaudeCompletedOnSha,
+  getMergeState,
+  OPTIONAL_CANCELLED_CHECKS,
+  listChecksOnSha,
+  listFailedChecksOnSha,
+  allChecksGreenOnSha,
+  hasInProgressClaudeAssistant,
+  claudeRunBlocksPr,
+  hasBlockingClaudeRunForPr,
+  isCiOnlyChange,
+  isInternalPullRequestLink,
+  resolvePrNumberFromLinkedPullRequests,
+  resolvePrNumberFromHeadBranch,
+  resolvePrNumberFromWorkflowRun,
+  WORKFLOW_ONLY_LABEL,
+  getAgentPyChange,
+  getAgentPyChangeFromFiles,
+  manualReviewReasonForAgentPy,
+  countNewAgentParams,
+  listPullFiles,
+  touchesSdk,
+  hasManualOnlyLabel,
+  sensitivePathReasons,
+  prSizeReasons,
+  missingTestsReason,
+  secretScanReasons,
+  sdkTestChecksReason,
+  listAllComments,
+  getHeadCommitDate,
+  isStaleFinalAfterPush,
+  needsStaleFinalRecovery,
+  shouldSkipFinalRecovery,
+  shouldSkipStaleFinalRecovery,
+  isClaudeAutomationLogin,
+  isPushSoonAfterLatestFinal,
+  countFinalTriggersSince,
+  STALE_FINAL_RECOVERY_WINDOW_MS,
+  STALE_FINAL_MAX_PER_WINDOW,
+  FINAL_CLAUDE_REVIEW_BODY,
+  loadPrContext,
+  evaluatePipelineQuiescent,
+  MERGE_READY_LABEL,
+  listPrNumbersForMergeGateScan,
+  selectMergeGateCandidates,
+  isAutomatedFallbackVerdict,
+  AUTOMATED_FALLBACK_MARKER,
+  findMergeGateVerdict,
+};

.github/scripts/pipeline-status-selftest.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Run: node .github/scripts/pipeline-status-selftest.js
+ */
+const ps = require('./pipeline-status.js');
+const mg = require('./merge-gate.js');
+const config = require('./gate-config.js');
+
+let failed = 0;
+function assert(name, cond) {
+  if (!cond) {
+    console.error('FAIL:', name);
+    failed++;
+  } else {
+    console.log('ok:', name);
+  }
+}
+
+const kickComments = [
+  { user: { login: 'MervinPraison' }, body: '@coderabbitai review' },
+  { user: { login: 'MervinPraison' }, body: '/review' },
+];
+
+const finalComment = {
+  user: { login: 'MervinPraison' },
+  body: '@claude You are the FINAL architecture reviewer.',
+  created_at: '2026-06-26T10:00:00Z',
+};
+
+assert(
+  'reviews pending when not kicked',
+  ps.deriveStage([], { ready: false, reasons: ['no FINAL Claude review trigger'] })
+    === 'pipeline/reviews-pending'
+);
+assert(
+  'final pending after kick',
+  ps.deriveStage(kickComments, { ready: false, reasons: ['no FINAL Claude review trigger'] })
+    === 'pipeline/final-claude-pending'
+);
+assert(
+  'awaiting merge gate after bot review comment',
+  ps.deriveStage(
+    [
+      { user: { login: 'coderabbitai[bot]' }, body: 'review summary' },
+      finalComment,
+    ],
+    { ready: false, reasons: ['recent @claude within 35min'] }
+  ) === 'pipeline/awaiting-merge-gate'
+);
+
+assert('review bot logins configured', config.reviewBotLogins.includes('coderabbitai[bot]'));
+assert(
+  'merge ready',
+  ps.deriveStage([...kickComments, finalComment], { ready: true, reasons: [] })
+    === 'pipeline/merge-ready'
+);
+
+const blockers = ps.deriveBlockerLabels({
+  ready: false,
+  reasons: ['CI not green on HEAD', 'SDK code added without test file changes — requires manual review'],
+});
+assert('maps ci blocker', blockers.includes('pipeline/blocked:ci'));
+assert('maps manual blocker', blockers.includes('pipeline/blocked:manual-review'));
+
+assert(
+  'internal link matches upstream base',
+  mg.isInternalPullRequestLink(
+    { base: { repo: { full_name: 'MervinPraison/PraisonAI' } } },
+    'MervinPraison',
+    'PraisonAI'
+  )
+);
+assert(
+  'fork sync link rejected',
+  !mg.isInternalPullRequestLink(
+    { number: 21, base: { repo: { full_name: 'Milkmange/PraisonAI' } } },
+    'MervinPraison',
+    'PraisonAI'
+  )
+);
+
+process.exit(failed ? 1 : 0);

.github/scripts/pipeline-status.js

@@ -0,0 +1,264 @@
+/**
+ * Sync pipeline stage/blocker labels on open PRs.
+ * @see .github/workflows/pipeline-status-sync.yml
+ */
+
+const mergeGate = require('./merge-gate.js');
+const chain = require('./bot-pr-review-chain.js');
+const ciFix = require('./ci-failure-claude.js');
+const config = require('./gate-config.js');
+
+const PIPELINE_PREFIX = 'pipeline/';
+const STAGE_LABELS = [
+  'pipeline/reviews-pending',
+  'pipeline/final-claude-pending',
+  'pipeline/awaiting-merge-gate',
+  'pipeline/merge-ready',
+  'pipeline/merged',
+];
+const BLOCKER_LABELS = [
+  'pipeline/blocked:ci',
+  'pipeline/blocked:conflict',
+  'pipeline/blocked:manual-review',
+  'pipeline/blocked:cooldown',
+  'pipeline/blocked:stale-final',
+  'pipeline/blocked:no-final',
+];
+const ALL_PIPELINE_LABELS = [...STAGE_LABELS, ...BLOCKER_LABELS];
+
+const LABEL_SPECS = [
+  { name: 'pipeline/reviews-pending', color: 'fbca04', description: 'Waiting for CodeRabbit/Qodo/Copilot reviews' },
+  { name: 'pipeline/final-claude-pending', color: 'd4c5f9', description: 'Reviews done; waiting for FINAL @claude' },
+  { name: 'pipeline/awaiting-merge-gate', color: 'c5def5', description: 'FINAL done; waiting for merge gate / CI' },
+  { name: 'pipeline/merge-ready', color: '0e8a16', description: 'Eligible for merge gate auto-merge' },
+  { name: 'pipeline/merged', color: '6f42c1', description: 'Merged via pipeline' },
+  { name: 'pipeline/blocked:ci', color: 'd93f0b', description: 'Blocked: CI not green on HEAD' },
+  { name: 'pipeline/blocked:conflict', color: 'b60205', description: 'Blocked: merge conflict or rebase pending' },
+  { name: 'pipeline/blocked:manual-review', color: 'e99695', description: 'Blocked: requires manual review' },
+  { name: 'pipeline/blocked:cooldown', color: 'fef2c0', description: 'Blocked: post-push or @claude cooldown' },
+  { name: 'pipeline/blocked:stale-final', color: 'f9d0c4', description: 'Blocked: FINAL stale after new commits' },
+  { name: 'pipeline/blocked:no-final', color: 'ededed', description: 'Blocked: no FINAL @claude trigger yet' },
+];
+
+function reviewChainStarted(comments) {
+  if (chain.chainKickPosted(comments)) return true;
+  return comments.some((c) => config.reviewBotLogins.includes(c.user?.login));
+}
+
+function deriveStage(comments, evalResult) {
+  if (evalResult.ready) return 'pipeline/merge-ready';
+  if (!reviewChainStarted(comments)) return 'pipeline/reviews-pending';
+  if (!mergeGate.hasFinalClaudeReviewTrigger(comments)) return 'pipeline/final-claude-pending';
+  return 'pipeline/awaiting-merge-gate';
+}
+
+function reasonToBlockerLabel(reason) {
+  const r = (reason || '').toLowerCase();
+  if (r.includes('ci not green') || r.includes('sdk code changed but no ci')) return 'pipeline/blocked:ci';
+  if (
+    r.includes('conflict') ||
+    r.includes('mergestate=dirty') ||
+    r.includes('not mergeable')
+  ) return 'pipeline/blocked:conflict';
+  if (
+    r.includes('manual') ||
+    r.includes('requires manual') ||
+    r.includes('sensitive path') ||
+    r.includes('no-auto-merge') ||
+    r.includes('manual-only label') ||
+    r.includes('without test') ||
+    r.includes('product code') ||
+    r.includes('files changed') ||
+    r.includes('possible secret')
+  ) return 'pipeline/blocked:manual-review';
+  if (r.includes('recent @claude') || r.includes('post-push buffer')) return 'pipeline/blocked:cooldown';
+  if (r.includes('stale final')) return 'pipeline/blocked:stale-final';
+  if (r.includes('no final claude')) return 'pipeline/blocked:no-final';
+  if (r.includes('final claude not complete')) return 'pipeline/blocked:stale-final';
+  if (r.includes('claude.yml in progress') || r.includes('claude-merge-gate-active')) {
+    return null;
+  }
+  return null;
+}
+
+function deriveBlockerLabels(evalResult) {
+  if (evalResult.ready) return [];
+  const labels = new Set();
+  for (const reason of evalResult.reasons || []) {
+    const mapped = reasonToBlockerLabel(reason);
+    if (mapped && mapped.startsWith('pipeline/blocked:')) labels.add(mapped);
+  }
+  return [...labels];
+}
+
+function computePipelineLabels(comments, evalResult) {
+  const stage = deriveStage(comments, evalResult);
+  const blockers = stage === 'pipeline/merge-ready' ? [] : deriveBlockerLabels(evalResult);
+  return { stage, blockers, all: [stage, ...blockers] };
+}
+
+async function ensurePipelineLabels(github, owner, repo, core) {
+  let existing;
+  if (typeof github.paginate === 'function') {
+    existing = await github.paginate(github.rest.issues.listLabelsForRepo, {
+      owner,
+      repo,
+      per_page: 100,
+    });
+  } else {
+    ({ data: existing } = await github.rest.issues.listLabelsForRepo({
+      owner,
+      repo,
+      per_page: 100,
+    }));
+  }
+  const names = new Set(existing.map((l) => l.name));
+  for (const spec of LABEL_SPECS) {
+    if (names.has(spec.name)) continue;
+    try {
+      await github.rest.issues.createLabel({
+        owner,
+        repo,
+        name: spec.name,
+        color: spec.color,
+        description: spec.description,
+      });
+      core?.info?.(`Created label ${spec.name}`);
+    } catch (err) {
+      if (err.status !== 422) throw err;
+      core?.info?.(`Label ${spec.name} already exists`);
+    }
+  }
+}
+
+async function syncPipelineLabels(github, owner, repo, prNumber, core) {
+  const ctx = await mergeGate.loadPrContext(github, owner, repo, prNumber);
+  if (ctx.pr.state !== 'open') return { synced: false, reason: 'not_open' };
+
+  const evalResult = await mergeGate.evaluatePipelineQuiescent(
+    github, owner, repo, prNumber, core
+  );
+  const { stage, blockers, all } = computePipelineLabels(ctx.comments, evalResult);
+
+  const current = ctx.labels.filter((l) => l.startsWith(PIPELINE_PREFIX));
+  const desired = new Set(all);
+  const toRemove = current.filter((l) => !desired.has(l) && l !== 'pipeline/merged');
+  const toAdd = all.filter((l) => !current.includes(l));
+
+  for (const name of toRemove) {
+    try {
+      await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name });
+    } catch (err) {
+      if (err.status !== 404) throw err;
+    }
+  }
+  if (toAdd.length) {
+    await github.rest.issues.addLabels({
+      owner,
+      repo,
+      issue_number: prNumber,
+      labels: toAdd,
+    });
+  }
+
+  core?.info?.(`PR #${prNumber}: stage=${stage} blockers=[${blockers.join(', ')}]`);
+
+  const ciNotGreen = (evalResult.reasons || []).some((r) =>
+    r.toLowerCase().includes('ci not green')
+  );
+  if (ciNotGreen || blockers.includes('pipeline/blocked:ci')) {
+    await ciFix.maybeTriggerCiFixClaude(github, owner, repo, prNumber, core);
+  } else {
+    await ciFix.maybeClearCiFixLabel(
+      github, owner, repo, prNumber, ctx.labels, ctx.headSha, core
+    );
+  }
+
+  return {
+    synced: true,
+    stage,
+    blockers,
+    ready: evalResult.ready,
+    reasons: evalResult.reasons,
+    labels: ctx.labels,
+    createdAt: new Date(ctx.pr.created_at).getTime(),
+  };
+}
+
+async function dispatchMergeGateForOldestReady(github, owner, repo, readyCandidates, core) {
+  if (!readyCandidates.length) return 0;
+  readyCandidates.sort((a, b) => a.createdAt - b.createdAt);
+  for (const cand of readyCandidates) {
+    if ((cand.labels || []).includes('claude-merge-gate-active')) {
+      core?.info?.(`Skip dispatch PR #${cand.prNumber}: merge gate already active`);
+      continue;
+    }
+    await github.rest.repos.createDispatchEvent({
+      owner,
+      repo,
+      event_type: 'claude-merge-gate',
+      client_payload: { pr_number: cand.prNumber },
+    });
+    core?.info?.(`Dispatched merge gate for ready PR #${cand.prNumber}`);
+    return cand.prNumber;
+  }
+  return 0;
+}
+
+async function syncOpenPullRequests(github, owner, repo, options, core) {
+  const { maxPrs = 20, dispatchMergeGate = true } = options || {};
+  await ensurePipelineLabels(github, owner, repo, core);
+  let prs;
+  if (maxPrs <= 100) {
+    ({ data: prs } = await github.rest.pulls.list({
+      owner,
+      repo,
+      state: 'open',
+      per_page: 100,
+    }));
+  } else {
+    prs = await github.paginate(github.rest.pulls.list, {
+      owner,
+      repo,
+      state: 'open',
+      per_page: 100,
+    });
+  }
+  let synced = 0;
+  const readyCandidates = [];
+  for (const pr of prs) {
+    if (synced >= maxPrs) break;
+    if (pr.draft) continue;
+    if (pr.head?.repo?.full_name && pr.head.repo.full_name !== `${owner}/${repo}`) continue;
+    const result = await syncPipelineLabels(github, owner, repo, pr.number, core);
+    if (result.ready) {
+      readyCandidates.push({
+        prNumber: pr.number,
+        createdAt: result.createdAt || new Date(pr.created_at).getTime(),
+        labels: result.labels || [],
+      });
+    }
+    synced += 1;
+  }
+  let dispatched = 0;
+  if (dispatchMergeGate && readyCandidates.length) {
+    dispatched = await dispatchMergeGateForOldestReady(
+      github, owner, repo, readyCandidates, core
+    );
+  }
+  core?.info?.(`Pipeline label sync complete (${synced} PR(s), dispatched=${dispatched || 'none'})`);
+  return synced;
+}
+
+module.exports = {
+  STAGE_LABELS,
+  BLOCKER_LABELS,
+  ALL_PIPELINE_LABELS,
+  deriveStage,
+  deriveBlockerLabels,
+  computePipelineLabels,
+  ensurePipelineLabels,
+  syncPipelineLabels,
+  syncOpenPullRequests,
+  dispatchMergeGateForOldestReady,
+};

.github/scripts/pr-review-chain-selftest.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+const chain = require('./pr-review-chain.js');
+
+let failed = 0;
+function assert(name, cond) {
+  if (!cond) {
+    console.error('FAIL:', name);
+    failed++;
+  } else {
+    console.log('ok:', name);
+  }
+}
+
+const coderabbit = {
+  user: { login: 'coderabbitai[bot]' },
+  body: '<!-- summarize by coderabbit.ai --> summary',
+  created_at: '2026-07-02T07:16:00Z',
+};
+const greptile = {
+  user: { login: 'greptile-apps[bot]' },
+  body: '<h3>Greptile Summary</h3><p>Looks good</p>',
+  created_at: '2026-07-02T07:19:00Z',
+};
+const copilotKick = {
+  user: { login: 'MervinPraison' },
+  body: '@copilot Do a thorough review',
+  created_at: '2026-07-02T07:20:00Z',
+};
+const copilotReply = {
+  user: { login: 'copilot-swe-agent' },
+  body: 'Copilot review here',
+  created_at: '2026-07-02T07:22:00Z',
+};
+
+assert('prior not ready without greptile', !chain.priorReviewersReady([coderabbit]).ready);
+assert('prior ready with coderabbit + greptile', chain.priorReviewersReady([coderabbit, greptile]).ready);
+assert('copilot not ready before trigger', !chain.copilotReviewReady([coderabbit, greptile]).ready);
+assert(
+  'copilot ready after reply',
+  chain.copilotReviewReady([coderabbit, greptile, copilotKick, copilotReply]).ready
+);
+assert(
+  'claude not ready before copilot',
+  !chain.claudeFinalReady([coderabbit, greptile]).ready
+);
+assert(
+  'claude ready after full chain',
+  chain.claudeFinalReady([coderabbit, greptile, copilotKick, copilotReply]).ready
+);
+assert(
+  'claude timeout fallback when copilot triggered but silent',
+  chain.claudeFinalReady([coderabbit, greptile, copilotKick], [], { allowCopilotTimeout: true }).ready
+);
+assert(
+  'no timeout fallback without copilot trigger',
+  !chain.claudeFinalReady([coderabbit, greptile], [], { allowCopilotTimeout: true }).ready
+);
+assert(
+  'skipCopilot proceeds after prior reviewers',
+  chain.claudeFinalReady([coderabbit, greptile], [], { skipCopilot: true }).ready
+);
+
+const oldPr = new Date(Date.now() - 31 * 60 * 1000).toISOString();
+assert(
+  'prior not ready without coderabbit before timeout',
+  !chain.priorReviewersReady([greptile], [], { prCreatedAt: new Date().toISOString(), requiredWaitMs: 30 * 60 * 1000 }).ready
+);
+assert(
+  'prior timeout when coderabbit silent after 30m',
+  chain.priorReviewersReady([greptile], [], { prCreatedAt: oldPr, requiredWaitMs: 30 * 60 * 1000 }).ready
+);
+assert(
+  'claude FINAL timeout when required reviewer silent and no prior FINAL',
+  chain.claudeFinalReady([greptile], [], { prCreatedAt: oldPr, requiredWaitMs: 30 * 60 * 1000 }).ready
+);
+assert(
+  'claude FINAL timeout auto-skips copilot without explicit skipCopilot',
+  chain.claudeFinalReady([greptile], [], { prCreatedAt: oldPr, requiredWaitMs: 30 * 60 * 1000 }).copilotSkipped
+);
+const finalClaude = {
+  user: { login: 'github-actions[bot]' },
+  body: '@claude You are the FINAL architecture reviewer for this PR.',
+  created_at: '2026-07-02T07:25:00Z',
+};
+assert(
+  'claude FINAL not re-posted when already triggered',
+  !chain.claudeFinalReady([greptile, finalClaude], [], { prCreatedAt: oldPr, requiredWaitMs: 0 }).ready
+);
+
+process.exit(failed ? 1 : 0);

.github/scripts/pr-review-chain.js

@@ -0,0 +1,319 @@
+/**
+ * PR review pipeline: CodeRabbit / Greptile (+ optional Qodo/Gemini) → Claude (FINAL).
+ * Copilot step optional — set REVIEW_CHAIN_SKIP_COPILOT=1 or skipCopilot: true to bypass.
+ * @see .github/workflows/auto-pr-comment.yml
+ */
+
+function isSkipCopilot(options = {}) {
+  if (options.skipCopilot === true) return true;
+  if (options.skipCopilot === false) return false;
+  return process.env.REVIEW_CHAIN_SKIP_COPILOT === '1';
+}
+
+const COPILOT_TRIGGER_LOGINS = new Set(['MervinPraison', 'github-actions[bot]']);
+const CLAUDE_TRIGGER_LOGINS = new Set(['MervinPraison', 'github-actions[bot]']);
+
+const REQUIRED_PRIOR = ['coderabbit', 'greptile'];
+const OPTIONAL_PRIOR = ['qodo', 'gemini'];
+const OPTIONAL_PRIOR_WAIT_MS = 20 * 60 * 1000;
+const REQUIRED_PRIOR_WAIT_MS = 30 * 60 * 1000;
+
+function loginOf(item) {
+  return (item?.user?.login || '').toLowerCase();
+}
+
+function bodyOf(item) {
+  return item?.body || '';
+}
+
+function hasCoderabbitSummary(comments) {
+  return comments.some(
+    (c) =>
+      loginOf(c).includes('coderabbit') &&
+      bodyOf(c).toLowerCase().includes('summarize by coderabbit')
+  );
+}
+
+function hasGreptileReview(comments) {
+  return comments.some((c) => {
+    if (!loginOf(c).includes('greptile')) return false;
+    const body = bodyOf(c);
+    return body.includes('Greptile Summary') || body.includes('<h3>Greptile Summary</h3>') || body.length > 150;
+  });
+}
+
+function hasQodoReview(comments, reviews = []) {
+  if (comments.some((c) => loginOf(c).includes('qodo'))) return true;
+  return reviews.some((r) => loginOf(r).includes('qodo'));
+}
+
+function hasGeminiReview(comments, reviews = []) {
+  if (reviews.some((r) => loginOf(r).includes('gemini'))) return true;
+  return comments.some((c) => {
+    if (loginOf(c).includes('gemini')) return true;
+    const body = bodyOf(c);
+    return (
+      body.includes('Review completed by Gemini CLI') ||
+      body.includes('The fix is ready for review. Please test')
+    );
+  });
+}
+
+const PRIOR_CHECKS = {
+  coderabbit: (comments) => hasCoderabbitSummary(comments),
+  greptile: (comments) => hasGreptileReview(comments),
+  qodo: (comments, reviews) => hasQodoReview(comments, reviews),
+  gemini: (comments, reviews) => hasGeminiReview(comments, reviews),
+};
+
+function priorReviewerStatus(comments, reviews = []) {
+  const status = {};
+  for (const [id, check] of Object.entries(PRIOR_CHECKS)) {
+    status[id] = check(comments, reviews);
+  }
+  return status;
+}
+
+function priorReviewersReady(comments, reviews = [], options = {}) {
+  const waitMs = options.optionalWaitMs ?? OPTIONAL_PRIOR_WAIT_MS;
+  const requiredWaitMs = options.requiredWaitMs ?? REQUIRED_PRIOR_WAIT_MS;
+  const prCreatedAt = options.prCreatedAt || null;
+  const status = priorReviewerStatus(comments, reviews);
+
+  const missingRequired = REQUIRED_PRIOR.filter((id) => !status[id]);
+  if (missingRequired.length) {
+    if (prCreatedAt) {
+      const age = Date.now() - new Date(prCreatedAt).getTime();
+      if (age >= requiredWaitMs) {
+        return {
+          ready: true,
+          reason: `required reviewer timeout (${missingRequired.join(', ')} silent after ${Math.round(requiredWaitMs / 60000)}m)`,
+          status,
+          requiredTimeout: true,
+        };
+      }
+    }
+    return { ready: false, reason: `waiting for ${missingRequired.join(', ')}`, status };
+  }
+
+  const missingOptional = OPTIONAL_PRIOR.filter((id) => !status[id]);
+  if (missingOptional.length && prCreatedAt) {
+    const age = Date.now() - new Date(prCreatedAt).getTime();
+    if (age < waitMs) {
+      return {
+        ready: false,
+        reason: `waiting for optional ${missingOptional.join(', ')} (${Math.round((waitMs - age) / 60000)}m left)`,
+        status,
+      };
+    }
+  }
+
+  return { ready: true, reason: '', status };
+}
+
+function copilotTriggerComment(comments) {
+  return comments.find(
+    (c) =>
+      bodyOf(c).includes('@copilot') &&
+      COPILOT_TRIGGER_LOGINS.has(c.user?.login) &&
+      !bodyOf(c).toLowerCase().includes('@claude')
+  );
+}
+
+function copilotTriggered(comments) {
+  return Boolean(copilotTriggerComment(comments));
+}
+
+function copilotReviewReady(comments, reviews = []) {
+  const trigger = copilotTriggerComment(comments);
+  if (!trigger) {
+    return { ready: false, reason: 'copilot not triggered yet' };
+  }
+  const triggerTime = new Date(trigger.created_at).getTime();
+  const copilotComment = comments.some((c) => {
+    if (c === trigger) return false;
+    if (new Date(c.created_at).getTime() < triggerTime) return false;
+    const login = loginOf(c);
+    return (
+      login.includes('copilot') ||
+      c.user?.login === 'Copilot' ||
+      c.user?.login === 'copilot-swe-agent'
+    );
+  });
+  const copilotReview = reviews.some((r) => {
+    if (new Date(r.submitted_at).getTime() < triggerTime) return false;
+    return loginOf(r).includes('copilot');
+  });
+  if (copilotComment || copilotReview) {
+    return { ready: true, reason: '' };
+  }
+  return { ready: false, reason: 'awaiting copilot review' };
+}
+
+function isFinalClaudeTriggerComment(c) {
+  const body = bodyOf(c).toLowerCase();
+  if (!CLAUDE_TRIGGER_LOGINS.has(c.user?.login)) return false;
+  if (!body.includes('@claude')) return false;
+  if (body.includes('merge conflict')) return false;
+  return body.includes('final architecture reviewer') || body.includes('lead engineer');
+}
+
+function claudeFinalAlreadyTriggered(comments) {
+  return comments.some(isFinalClaudeTriggerComment);
+}
+
+function claudeFinalReady(comments, reviews = [], options = {}) {
+  if (!options.allowStaleRepost && claudeFinalAlreadyTriggered(comments)) {
+    return { ready: false, reason: 'claude FINAL already triggered', already: true };
+  }
+  const prior = priorReviewersReady(comments, reviews, options);
+  if (!prior.ready) {
+    return { ready: false, reason: prior.reason };
+  }
+  if (isSkipCopilot(options) || prior.requiredTimeout) {
+    return {
+      ready: true,
+      reason: prior.requiredTimeout ? prior.reason : 'copilot skipped',
+      copilotSkipped: true,
+      requiredTimeout: prior.requiredTimeout,
+    };
+  }
+  const copilot = copilotReviewReady(comments, reviews);
+  if (copilot.ready) {
+    return { ready: true, reason: '' };
+  }
+  if (options.allowCopilotTimeout && copilotTriggered(comments)) {
+    return { ready: true, reason: 'copilot timeout fallback', copilotSkipped: true };
+  }
+  return { ready: false, reason: copilot.reason };
+}
+
+/** Post @copilot when prior reviewers are ready, then @claude FINAL when Copilot done (or timeout). */
+async function advanceReviewChain(github, owner, repo, prNumber, finalBody, core, options = {}) {
+  const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+  const chainOpts = {
+    prCreatedAt: pr.created_at,
+    optionalWaitMs: options.optionalWaitMs ?? 0,
+  };
+  const copilot = options.skipCopilot
+    ? { triggered: false, reason: 'skipped' }
+    : await maybeTriggerCopilot(github, owner, repo, prNumber, core, chainOpts);
+  const claude = await maybeTriggerClaudeFinal(
+    github, owner, repo, prNumber, finalBody, core,
+    { ...options, ...chainOpts }
+  );
+  return { copilot, claude };
+}
+
+async function maybeTriggerClaudeFinal(github, owner, repo, prNumber, finalBody, core, options = {}) {
+  const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+  const { comments, reviews } = await listCommentsAndReviews(github, owner, repo, prNumber);
+  const gate = claudeFinalReady(comments, reviews, {
+    prCreatedAt: pr.created_at,
+    optionalWaitMs: options.optionalWaitMs,
+    allowCopilotTimeout: options.allowCopilotTimeout !== false,
+    allowStaleRepost: options.allowStaleRepost === true,
+    skipCopilot: options.skipCopilot,
+  });
+  if (!gate.ready) {
+    core?.info?.(`PR #${prNumber}: skip Claude FINAL — ${gate.reason}`);
+    return { posted: false, reason: gate.reason };
+  }
+  await github.rest.issues.createComment({
+    owner,
+    repo,
+    issue_number: prNumber,
+    body: finalBody,
+  });
+  const note = gate.copilotSkipped ? ' (Copilot timeout fallback)' : '';
+  core?.info?.(`Posted Claude FINAL on PR #${prNumber}${note}`);
+  return { posted: true, reason: '' };
+}
+
+const COPILOT_REVIEW_BODY =
+  '@copilot Do a thorough review of this PR. Read ALL existing reviewer comments above from Qodo, CodeRabbit, Gemini, and Greptile first — incorporate their findings.\n\nReview areas:\n1. **Bloat check**: Are changes minimal and focused? Any unnecessary code or scope creep?\n2. **Security**: Any hardcoded secrets, unsafe eval/exec, missing input validation?\n3. **Performance**: Any module-level heavy imports? Hot-path regressions?\n4. **Tests**: Are tests included? Do they cover the changes adequately?\n5. **Backward compat**: Any public API changes without deprecation?\n6. **Code quality**: DRY violations, naming conventions, error handling?\n7. **Address reviewer feedback**: If Qodo, CodeRabbit, Gemini, or Greptile flagged valid issues, include them in your review\n8. Suggest specific improvements with code examples where possible';
+
+async function listCommentsAndReviews(github, owner, repo, prNumber) {
+  let comments;
+  if (typeof github.paginate === 'function') {
+    comments = await github.paginate(github.rest.issues.listComments, {
+      owner,
+      repo,
+      issue_number: prNumber,
+      per_page: 100,
+    });
+  } else {
+    const { data } = await github.rest.issues.listComments({
+      owner,
+      repo,
+      issue_number: prNumber,
+      per_page: 100,
+    });
+    comments = data;
+  }
+  const { data: reviews } = await github.rest.pulls.listReviews({
+    owner,
+    repo,
+    pull_number: prNumber,
+    per_page: 100,
+  });
+  return { comments, reviews };
+}
+
+async function maybeTriggerCopilot(github, owner, repo, prNumber, core, options = {}) {
+  const { comments, reviews } = await listCommentsAndReviews(github, owner, repo, prNumber);
+  if (copilotTriggered(comments)) {
+    core?.info?.(`Copilot already triggered on PR #${prNumber}`);
+    return { triggered: false, reason: 'already_triggered' };
+  }
+  const prior = priorReviewersReady(comments, reviews, options);
+  if (!prior.ready) {
+    core?.info?.(`PR #${prNumber}: not ready for Copilot — ${prior.reason}`);
+    return { triggered: false, reason: prior.reason };
+  }
+  await github.rest.issues.createComment({
+    owner,
+    repo,
+    issue_number: prNumber,
+    body: COPILOT_REVIEW_BODY,
+  });
+  core?.info?.(`Posted @copilot on PR #${prNumber} after prior reviewers`);
+  return { triggered: true };
+}
+
+async function pollCopilotResponse(github, owner, repo, prNumber, options = {}) {
+  const maxAttempts = options.maxAttempts ?? 20;
+  const delayMs = options.delayMs ?? 30000;
+  for (let i = 0; i < maxAttempts; i += 1) {
+    const { comments, reviews } = await listCommentsAndReviews(github, owner, repo, prNumber);
+    const copilot = copilotReviewReady(comments, reviews);
+    if (copilot.ready) {
+      return { ready: true, reason: '' };
+    }
+    if (i < maxAttempts - 1) {
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+  return { ready: false, reason: 'copilot timeout' };
+}
+
+module.exports = {
+  isSkipCopilot,
+  REQUIRED_PRIOR,
+  OPTIONAL_PRIOR,
+  REQUIRED_PRIOR_WAIT_MS,
+  COPILOT_REVIEW_BODY,
+  priorReviewerStatus,
+  priorReviewersReady,
+  copilotTriggered,
+  copilotReviewReady,
+  claudeFinalReady,
+  claudeFinalAlreadyTriggered,
+  isFinalClaudeTriggerComment,
+  maybeTriggerCopilot,
+  maybeTriggerClaudeFinal,
+  advanceReviewChain,
+  pollCopilotResponse,
+  hasGeminiReview,
+  listCommentsAndReviews,
+};

.github/scripts/release-gate-selftest.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * Run: node .github/scripts/release-gate-selftest.js
+ */
+const rg = require('./release-gate.js');
+const config = require('./gate-config.js');
+
+let failed = 0;
+function assert(name, cond) {
+  if (!cond) {
+    console.error('FAIL:', name);
+    failed += 1;
+  } else {
+    console.log('ok:', name);
+  }
+}
+
+assert('package name is aiui', config.pypiPackageName === 'aiui');
+assert('bumpPatch works', rg.bumpPatch('0.3.127') === '0.3.128');
+
+try {
+  const versions = rg.readVersionsFromTree(process.cwd());
+  assert('reads current version', /^\d+\.\d+\.\d+$/.test(versions.current));
+  assert('computes target patch', versions.target === rg.bumpPatch(versions.current));
+} catch (err) {
+  console.error('FAIL: readVersionsFromTree', err.message);
+  failed += 1;
+}
+
+assert('PACKAGE_PATHS includes pyproject', rg.PACKAGE_PATHS.includes('pyproject.toml'));
+
+process.exit(failed ? 1 : 0);

.github/scripts/release-gate.js

@@ -0,0 +1,205 @@
+/**
+ * Release gate preflight — path changes, CI SHA, dedupe, PyPI version checks (PraisonAIUI).
+ */
+
+const https = require('https');
+const config = require('./gate-config.js');
+
+const PACKAGE_PATHS = config.packagePaths;
+const ACTIVE_RELEASE_STATUSES = new Set([
+  'queued', 'in_progress', 'waiting', 'pending', 'requested',
+]);
+
+function bumpPatch(version) {
+  const parts = version.split('.');
+  if (parts.length !== 3) throw new Error(`Invalid version: ${version}`);
+  return `${parts[0]}.${parts[1]}.${Number(parts[2]) + 1}`;
+}
+
+function readVersionsFromTree(root = '.') {
+  const fs = require('fs');
+  const path = require('path');
+  const toml = fs.readFileSync(path.join(root, 'pyproject.toml'), 'utf8');
+  const match = toml.match(/^version\s*=\s*"([^"]+)"/m);
+  if (!match) throw new Error('Could not read aiui version from pyproject.toml');
+  const current = match[1];
+  const target = bumpPatch(current);
+  return { current, target, packageName: config.pypiPackageName };
+}
+
+function pypiVersionExists(packageName, version) {
+  return new Promise((resolve) => {
+    const req = https.get(
+      `https://pypi.org/pypi/${packageName}/${version}/json`,
+      { timeout: 15000 },
+      (res) => {
+        res.resume();
+        resolve(res.statusCode === 200);
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(false);
+    });
+  });
+}
+
+async function hasActiveReleaseRun(github, owner, repo) {
+  const runs = await github.rest.actions.listWorkflowRuns({
+    owner,
+    repo,
+    workflow_id: 'pypi-release.yml',
+    per_page: 20,
+  });
+  return runs.data.workflow_runs.some(
+    (r) => ACTIVE_RELEASE_STATUSES.has(r.status) && !r.conclusion
+  );
+}
+
+function utcDayStart(now = new Date()) {
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+
+async function hasSuccessfulReleaseToday(github, owner, repo, now = new Date()) {
+  const dayStart = utcDayStart(now);
+  const runs = await github.rest.actions.listWorkflowRuns({
+    owner,
+    repo,
+    workflow_id: 'pypi-release.yml',
+    status: 'completed',
+    per_page: 30,
+  });
+  return runs.data.workflow_runs.some(
+    (r) => r.conclusion === 'success' && new Date(r.created_at) >= dayStart
+  );
+}
+
+async function lastGreenCiSha(github, owner, repo) {
+  const runs = await github.rest.actions.listWorkflowRuns({
+    owner,
+    repo,
+    workflow_id: config.ciWorkflowFile,
+    branch: 'main',
+    status: 'completed',
+    per_page: 30,
+  });
+  const hit = runs.data.workflow_runs.find((r) => r.conclusion === 'success');
+  return hit ? hit.head_sha : '';
+}
+
+async function evaluateReleasePreflight(github, owner, repo, options, core) {
+  const {
+    headSha,
+    isCiTrigger = false,
+    bump = 'patch',
+  } = options;
+
+  const reasons = [];
+  const out = {
+    ready: false,
+    reasons,
+    headSha: headSha || '',
+    lastTag: '',
+    targetVersion: '',
+    packageName: config.pypiPackageName,
+  };
+
+  if (bump !== 'patch') {
+    reasons.push('only patch auto-release supported');
+    return out;
+  }
+
+  if (await hasActiveReleaseRun(github, owner, repo)) {
+    reasons.push('PyPI Release already in progress or awaiting approval');
+    return out;
+  }
+
+  const referenceTime = options.now instanceof Date ? options.now : new Date();
+  if (await hasSuccessfulReleaseToday(github, owner, repo, referenceTime)) {
+    const day = referenceTime.toISOString().slice(0, 10);
+    reasons.push(`already released today (UTC ${day}); max one patch release per day`);
+    return out;
+  }
+
+  let versions;
+  try {
+    versions = readVersionsFromTree();
+  } catch (err) {
+    reasons.push(err.message);
+    return out;
+  }
+  out.targetVersion = versions.target;
+
+  const onPypi = await pypiVersionExists(config.pypiPackageName, versions.target);
+  if (onPypi) {
+    reasons.push(`already published: ${config.pypiPackageName}==${versions.target}`);
+    return out;
+  }
+
+  const { execSync } = require('child_process');
+  let lastTag = '';
+  try {
+    lastTag = execSync('git describe --tags --match "v*" --abbrev=0', { encoding: 'utf8' }).trim();
+  } catch {
+    reasons.push('no v* tag found');
+    return out;
+  }
+  out.lastTag = lastTag;
+
+  let changed = '';
+  try {
+    changed = execSync(
+      `git diff --name-only ${lastTag} HEAD -- ${PACKAGE_PATHS.join(' ')}`,
+      { encoding: 'utf8' }
+    ).trim();
+  } catch {
+    reasons.push('git diff failed');
+    return out;
+  }
+
+  if (!changed) {
+    reasons.push(`no changes in ${PACKAGE_PATHS.join(' or ')} since ${lastTag}`);
+    return out;
+  }
+
+  if (isCiTrigger) {
+    let mainSha = '';
+    try {
+      mainSha = execSync('git rev-parse origin/main', { encoding: 'utf8' }).trim();
+    } catch {
+      reasons.push('could not resolve origin/main');
+      return out;
+    }
+    if (headSha !== mainSha) {
+      reasons.push(`superseded: green SHA ${headSha.slice(0, 7)} != main ${mainSha.slice(0, 7)}`);
+      return out;
+    }
+    out.headSha = headSha;
+  } else {
+    const evalSha = execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();
+    out.headSha = evalSha;
+    const greenSha = await lastGreenCiSha(github, owner, repo);
+    if (greenSha !== evalSha) {
+      reasons.push(`CI not green on HEAD (last green: ${greenSha ? greenSha.slice(0, 7) : 'none'})`);
+      return out;
+    }
+  }
+
+  out.ready = true;
+  out.reasons = ['ready'];
+  if (core) core.info(`Release preflight passed for ${out.headSha || headSha}`);
+  return out;
+}
+
+module.exports = {
+  bumpPatch,
+  readVersionsFromTree,
+  pypiVersionExists,
+  hasSuccessfulReleaseToday,
+  utcDayStart,
+  evaluateReleasePreflight,
+  lastGreenCiSha,
+  ACTIVE_RELEASE_STATUSES,
+  PACKAGE_PATHS,
+};

.github/workflows/auto-issue-comment.yml

@@ -24,7 +24,7 @@ jobs:
   trigger-claude:
     if: |
       github.event_name == 'workflow_dispatch' ||
-      (github.event_name == 'issues' && !contains(toJSON(github.event.issue.labels), 'claude'))
+      github.event_name == 'issues'
     runs-on: ubuntu-latest
     permissions:
       issues: write
@@ -52,7 +52,8 @@ jobs:
             });
 
             const labels = (issue.labels || []).map(l => typeof l === 'string' ? l : l.name);
-            if (!labels.includes('claude')) {
+            const hadClaude = labels.includes('claude');
+            if (!hadClaude) {
               await github.rest.issues.addLabels({
                 owner: context.repo.owner,
                 repo: context.repo.repo,
@@ -60,7 +61,7 @@ jobs:
                 labels: ['claude'],
               });
             } else {
-              console.log(`Issue #${issueNumber} already has 'claude' label.`);
+              console.log(`Issue #${issueNumber} already has 'claude' label — dispatching Claude only.`);
             }
 
             const body = [

.github/workflows/auto-pr-comment.yml

@@ -1,649 +1,33 @@
 name: Auto PR Comment
 
-# Review chain: CodeRabbit/Qodo/Gemini review first → Copilot → Claude (final)
-# For human PRs: CodeRabbit/Qodo auto-review → this workflow triggers Copilot → then Claude
-# For bot PRs: CodeRabbit/Qodo skip bots, so we trigger them explicitly first
-#
-# IMPORTANT: @copilot ignores bot comments. All @copilot mentions must use
-# PAT_TOKEN so the comment posts as MervinPraison (a real user).
-#
-# Claude trigger runs IN-BAND (same workflow) to avoid GitHub Actions
-# blocking bot-triggered workflows with action_required approval gates.
 on:
   issue_comment:
     types: [created]
   pull_request_review:
     types: [submitted]
   pull_request:
-    types: [opened]
+    types: [opened, synchronize]
+  pull_request_target:
+    types: [opened, synchronize]
+  schedule:
+    - cron: '30 * * * *'
   workflow_dispatch:
-    inputs:
-      pr_number:
-        description: 'PR number to trigger Claude final review on'
-        required: true
-        type: number
+
+env:
+  REVIEW_CHAIN_SKIP_COPILOT: '1'
 
 permissions:
-  contents: read
   issues: write
   pull-requests: write
 
-env:
-  MAX_POLL_ATTEMPTS: 20
-  POLL_DELAY_MS: 30000
-  CLAUDE_TRIGGER_LOGINS: '["MervinPraison","github-actions[bot]"]'
-  # GH_TOKEN (user PAT) posts as MervinPraison for @copilot; fallback to github.token for @claude
-  GH_TOKEN: ${{ secrets.GH_TOKEN || github.token }}
-  CLAUDE_UI_SCOPE: 'SCOPE: Focus ONLY on PraisonAIUI (src/praisonaiui, src/frontend, tests, docs). Do not expand into praisonaiagents or the monorepo unless the issue explicitly requires it.'
-  CLAUDE_FINAL_PHASES_COMPACT: "**Phase 1: Review per AGENTS.md** (lazy imports, backward compat, import-time <200ms; SDK/product value gate — genuine UI value, correct UI vs praisonaiagents layering, no scope creep)\n**Phase 2: FIX valid issues** found by prior reviewers — push to THIS branch\n**Phase 3: Final verdict** — approve PR if ready, else request changes"
-  CLAUDE_FINAL_PHASES_DETAILED: "**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions (lazy imports, import-time <200ms)\n4. SDK/product value: review whether the change genuinely adds value — stronger PraisonAIUI UX and correct layering (UI/frontend here; core agent logic belongs in praisonaiagents). Reject scope creep; request changes or recommend closing if value is unclear\n\n**Phase 2: FIX Valid Issues**\n5. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n6. Push all code fixes directly to THIS branch (do NOT create a new PR)\n7. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n8. If all issues are resolved, approve the PR / close the Issue\n9. If blocking issues remain, request changes / leave clear action items"
-
 jobs:
-  # ================================================================
-  # HUMAN PRs: Trigger @copilot AFTER CodeRabbit posts its summary
-  # ================================================================
-  copilot-after-coderabbit:
-    if: |
-      github.event_name == 'issue_comment' &&
-      github.event.issue.pull_request &&
-      github.event.comment.user.login == 'coderabbitai[bot]' &&
-      contains(github.event.comment.body, 'summarize by coderabbit')
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-    outputs:
-      pr_number: ${{ steps.trigger.outputs.pr_number }}
-      triggered: ${{ steps.trigger.outputs.triggered }}
-    steps:
-      - name: Post Copilot review request (as user via PAT)
-        id: trigger
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const comments = await github.rest.issues.listComments({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo
-            });
-            // Check for duplicates — posted by MervinPraison (PAT) or github-actions[bot] (legacy)
-            const alreadyPosted = comments.data.some(c =>
-              c.body.includes('@copilot') &&
-              (c.user.login === 'MervinPraison' || c.user.login === 'github-actions[bot]')
-            );
-            if (alreadyPosted) {
-              console.log('Copilot already triggered, skipping');
-              core.setOutput('triggered', 'false');
-              core.setOutput('pr_number', context.issue.number.toString());
-              return;
-            }
-            await github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: '@copilot Do a thorough review of this PR. Read ALL existing reviewer comments above from Qodo, Coderabbit, and Gemini first — incorporate their findings.\n\nReview areas:\n1. **Bloat check**: Are changes minimal and focused? Any unnecessary code or scope creep?\n2. **Security**: Any hardcoded secrets, unsafe eval/exec, missing input validation?\n3. **Performance**: Any module-level heavy imports? Hot-path regressions?\n4. **Tests**: Are tests included? Do they cover the changes adequately?\n5. **Backward compat**: Any public API changes without deprecation?\n6. **Code quality**: DRY violations, naming conventions, error handling?\n7. **Address reviewer feedback**: If Qodo, Coderabbit, or Gemini flagged valid issues, include them in your review\n8. Suggest specific improvements with code examples where possible'
-            });
-            core.setOutput('triggered', 'true');
-            core.setOutput('pr_number', context.issue.number.toString());
-
-  # Fallback: Trigger @copilot after Qodo review (if Coderabbit doesn't fire)
-  copilot-after-qodo:
-    if: |
-      github.event_name == 'pull_request_review' &&
-      github.event.review.user.login == 'qodo-code-review[bot]'
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-    outputs:
-      pr_number: ${{ steps.trigger.outputs.pr_number }}
-      triggered: ${{ steps.trigger.outputs.triggered }}
-    steps:
-      - name: Post Copilot review request (as user via PAT)
-        id: trigger
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const comments = await github.rest.issues.listComments({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo
-            });
-            const alreadyPosted = comments.data.some(c =>
-              c.body.includes('@copilot') &&
-              (c.user.login === 'MervinPraison' || c.user.login === 'github-actions[bot]')
-            );
-            if (alreadyPosted) {
-              console.log('Copilot already triggered, skipping');
-              core.setOutput('triggered', 'false');
-              core.setOutput('pr_number', context.issue.number.toString());
-              return;
-            }
-            await github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: '@copilot Do a thorough review of this PR. Read ALL existing reviewer comments above first.\n\nReview areas:\n1. **Bloat check**: Are changes minimal and focused?\n2. **Security**: Any hardcoded secrets, unsafe eval/exec, missing input validation?\n3. **Performance**: Any module-level heavy imports? Hot-path regressions?\n4. **Tests**: Are tests included? Do they cover the changes adequately?\n5. **Backward compat**: Any public API changes without deprecation?\n6. **Code quality**: DRY violations, naming conventions, error handling?\n7. Suggest specific improvements with code examples where possible'
-            });
-            core.setOutput('triggered', 'true');
-            core.setOutput('pr_number', context.issue.number.toString());
-
-  # ================================================================
-  # FALLBACK: Claude trigger for cases where Copilot chain fails/skips
-  # Ensures Claude always runs after sufficient review time
-  # ================================================================
-  claude-fallback-timeout:
-    if: |
-      github.event_name == 'pull_request' &&
-      github.event.action == 'opened'
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
+  review-chain:
+    # Grant union of callee job permissions (repos with default_workflow_permissions: read
+    # reject reusable calls when the caller ceiling is lower than any callee job).
     permissions:
       issues: write
       pull-requests: write
-    steps:
-      - name: Wait for review window (15 min)
-        run: sleep 900
-      
-      - name: Check if Claude already triggered
-        id: check_claude
-        uses: actions/github-script@v7
-        env:
-          TRIGGER_LOGINS: ${{ env.CLAUDE_TRIGGER_LOGINS }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = parseInt(process.env.PR_NUMBER, 10);
-            const triggerLogins = JSON.parse(process.env.TRIGGER_LOGINS);
-            const comments = await github.rest.issues.listComments({
-              issue_number: pr,
-              owner: context.repo.owner,
-              repo: context.repo.repo
-            });
-            const alreadyPosted = comments.data.some(c =>
-              c.body.includes('@claude') && triggerLogins.includes(c.user.login)
-            );
-            core.setOutput('already_triggered', alreadyPosted ? 'true' : 'false');
-            core.setOutput('comments_count', comments.data.length.toString());
-
-            const botReviews = comments.data.filter(c =>
-              ['coderabbitai[bot]', 'qodo-code-review[bot]', 'gemini-code-assist[bot]',
-               'copilot-swe-agent', 'Copilot', 'greptile-apps[bot]'].some(bot =>
-                c.user.login.toLowerCase().includes(bot.toLowerCase())
-              )
-            );
-            core.setOutput('review_count', botReviews.length.toString());
-
-      - name: Aggregate reviews and trigger Claude
-        if: steps.check_claude.outputs.already_triggered != 'true'
-        uses: actions/github-script@v7
-        env:
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = parseInt(process.env.PR_NUMBER, 10);
-            const comments = await github.rest.issues.listComments({issue_number: pr, owner: context.repo.owner, repo: context.repo.repo, per_page: 100});
-            const reviews = {coderabbit: [], qodo: [], gemini: [], copilot: [], greptile: [], others: []};
-            comments.data.forEach(c => {
-              const login = c.user.login.toLowerCase();
-              const body = c.body.substring(0, 500);
-              if (login.includes('coderabbit')) reviews.coderabbit.push(body);
-              else if (login.includes('qodo')) reviews.qodo.push(body);
-              else if (login.includes('gemini')) reviews.gemini.push(body);
-              else if (login.includes('copilot')) reviews.copilot.push(body);
-              else if (login.includes('greptile')) reviews.greptile.push(body);
-              else if (c.user.type === 'Bot') reviews.others.push(body);
-            });
-            const summaryParts = [];
-            if (reviews.coderabbit.length) summaryParts.push('CodeRabbit: ' + reviews.coderabbit.length + ' comments');
-            if (reviews.qodo.length) summaryParts.push('Qodo: ' + reviews.qodo.length + ' comments');
-            if (reviews.gemini.length) summaryParts.push('Gemini: ' + reviews.gemini.length + ' comments');
-            if (reviews.copilot.length) summaryParts.push('Copilot: ' + reviews.copilot.length + ' comments');
-            if (reviews.greptile.length) summaryParts.push('Greptile: ' + reviews.greptile.length + ' comments');
-            const reviewSummary = summaryParts.length ? summaryParts.join(' | ') : 'No bot reviews detected';
-            const scope = process.env.CLAUDE_UI_SCOPE;
-            const phases = process.env.CLAUDE_FINAL_PHASES_COMPACT;
-            const claudeBody = '@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAIUI (not a fork), you are able to make modifications to this branch and push directly. ' + scope + ' Read ALL prior reviewer comments. ' + reviewSummary + '.\n\n' +
-              'Review Context: ' + comments.data.length + ' total comments, ' +
-              (reviews.coderabbit.length + reviews.qodo.length + reviews.gemini.length + reviews.copilot.length + reviews.greptile.length) + ' bot reviews.\n\n' +
-              phases;
-            await github.rest.issues.createComment({issue_number: pr, owner: context.repo.owner, repo: context.repo.repo, body: claudeBody});
-            console.log('Claude fallback triggered on PR #' + pr + ' with ' + reviewSummary);
-
-  # ================================================================
-  # Claude FINAL review — polls for Copilot's response, then triggers
-  # This runs IN-BAND under the PAT context (MervinPraison), avoiding
-  # the action_required approval gate that blocks bot-triggered workflows.
-  # ================================================================
-  claude-after-copilot:
-    needs: [copilot-after-coderabbit]
-    if: |
-      always() &&
-      needs.copilot-after-coderabbit.result == 'success' &&
-      needs.copilot-after-coderabbit.outputs.triggered == 'true'
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    permissions:
-      issues: write
-      pull-requests: write
-    steps:
-      - name: Wait for Copilot to respond (poll)
-        id: poll
-        uses: actions/github-script@v7
-        env:
-          PR_NUMBER: ${{ needs.copilot-after-coderabbit.outputs.pr_number }}
-          MAX_POLL_ATTEMPTS: ${{ env.MAX_POLL_ATTEMPTS }}
-          POLL_DELAY_MS: ${{ env.POLL_DELAY_MS }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = parseInt(process.env.PR_NUMBER, 10);
-            const owner = context.repo.owner;
-            const repo = context.repo.repo;
-
-            // Poll for Copilot's response — check every 30s for up to 10 minutes
-            const maxAttempts = parseInt(process.env.MAX_POLL_ATTEMPTS, 10);
-            const delayMs = parseInt(process.env.POLL_DELAY_MS, 10);
-
-            for (let i = 0; i < maxAttempts; i++) {
-              console.log(`Poll attempt ${i + 1}/${maxAttempts}...`);
-
-              const comments = await github.rest.issues.listComments({
-                issue_number: pr,
-                owner,
-                repo,
-                per_page: 50,
-                sort: 'created',
-                direction: 'desc'
-              });
-
-              // Look for Copilot's response (copilot-swe-agent or Copilot)
-              const copilotResponse = comments.data.find(c =>
-                (c.user.login === 'copilot-swe-agent' ||
-                 c.user.login === 'Copilot' ||
-                 c.user.login.toLowerCase().includes('copilot')) &&
-                c.user.type === 'Bot'
-              );
-
-              if (copilotResponse) {
-                console.log(`Copilot responded at ${copilotResponse.created_at}`);
-                core.setOutput('copilot_responded', 'true');
-                return;
-              }
-
-              // Also check PR reviews for Copilot
-              const reviews = await github.rest.pulls.listReviews({
-                pull_number: pr,
-                owner,
-                repo
-              });
-
-              const copilotReview = reviews.data.find(r =>
-                r.user.login.toLowerCase().includes('copilot')
-              );
-
-              if (copilotReview) {
-                console.log(`Copilot review submitted at ${copilotReview.submitted_at}`);
-                core.setOutput('copilot_responded', 'true');
-                return;
-              }
-
-              if (i < maxAttempts - 1) {
-                console.log(`Copilot hasn't responded yet, waiting ${delayMs/1000}s...`);
-                await new Promise(resolve => setTimeout(resolve, delayMs));
-              }
-            }
-
-            console.log('Copilot did not respond within timeout, triggering Claude anyway');
-            core.setOutput('copilot_responded', 'timeout');
-
-      - name: Check if Claude already triggered
-        id: check_claude
-        uses: actions/github-script@v7
-        env:
-          PR_NUMBER: ${{ needs.copilot-after-coderabbit.outputs.pr_number }}
-          TRIGGER_LOGINS: ${{ env.CLAUDE_TRIGGER_LOGINS }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = parseInt(process.env.PR_NUMBER, 10);
-            const triggerLogins = JSON.parse(process.env.TRIGGER_LOGINS);
-            const comments = await github.rest.issues.listComments({
-              issue_number: pr,
-              owner: context.repo.owner,
-              repo: context.repo.repo
-            });
-            const alreadyPosted = comments.data.some(c =>
-              c.body.includes('@claude') && triggerLogins.includes(c.user.login)
-            );
-            core.setOutput('already_triggered', alreadyPosted ? 'true' : 'false');
-
-      - name: Trigger Claude final review
-        if: steps.check_claude.outputs.already_triggered != 'true'
-        uses: actions/github-script@v7
-        env:
-          PR_NUMBER: ${{ needs.copilot-after-coderabbit.outputs.pr_number }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = parseInt(process.env.PR_NUMBER, 10);
-            const scope = process.env.CLAUDE_UI_SCOPE;
-            const phases = process.env.CLAUDE_FINAL_PHASES_DETAILED;
-            await github.rest.issues.createComment({
-              issue_number: pr,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: '@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAIUI (not a fork), you are able to make modifications to this branch and push directly. ' + scope + ' Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n' + phases
-            });
-            console.log(`Claude triggered on PR #${pr}`);
-
-  # ================================================================
-  # Claude after Qodo fallback path (same polling approach)
-  # ================================================================
-  claude-after-copilot-qodo:
-    needs: [copilot-after-qodo]
-    if: |
-      always() &&
-      needs.copilot-after-qodo.result == 'success' &&
-      needs.copilot-after-qodo.outputs.triggered == 'true'
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    permissions:
-      issues: write
-      pull-requests: write
-    steps:
-      - name: Wait for Copilot to respond (poll)
-        id: poll
-        uses: actions/github-script@v7
-        env:
-          PR_NUMBER: ${{ needs.copilot-after-qodo.outputs.pr_number }}
-          MAX_POLL_ATTEMPTS: ${{ env.MAX_POLL_ATTEMPTS }}
-          POLL_DELAY_MS: ${{ env.POLL_DELAY_MS }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = parseInt(process.env.PR_NUMBER, 10);
-            const owner = context.repo.owner;
-            const repo = context.repo.repo;
-            const maxAttempts = parseInt(process.env.MAX_POLL_ATTEMPTS, 10);
-            const delayMs = parseInt(process.env.POLL_DELAY_MS, 10);
-
-            for (let i = 0; i < maxAttempts; i++) {
-              console.log(`Poll attempt ${i + 1}/${maxAttempts}...`);
-              const comments = await github.rest.issues.listComments({
-                issue_number: pr, owner, repo,
-                per_page: 50, sort: 'created', direction: 'desc'
-              });
-              const copilotResponse = comments.data.find(c =>
-                (c.user.login === 'copilot-swe-agent' ||
-                 c.user.login === 'Copilot' ||
-                 c.user.login.toLowerCase().includes('copilot')) &&
-                c.user.type === 'Bot'
-              );
-              if (copilotResponse) {
-                console.log(`Copilot responded at ${copilotResponse.created_at}`);
-                core.setOutput('copilot_responded', 'true');
-                return;
-              }
-              const reviews = await github.rest.pulls.listReviews({
-                pull_number: pr, owner, repo
-              });
-              const copilotReview = reviews.data.find(r =>
-                r.user.login.toLowerCase().includes('copilot')
-              );
-              if (copilotReview) {
-                console.log(`Copilot review submitted at ${copilotReview.submitted_at}`);
-                core.setOutput('copilot_responded', 'true');
-                return;
-              }
-              if (i < maxAttempts - 1) {
-                await new Promise(resolve => setTimeout(resolve, delayMs));
-              }
-            }
-            console.log('Copilot did not respond within timeout, triggering Claude anyway');
-            core.setOutput('copilot_responded', 'timeout');
-
-      - name: Check if Claude already triggered
-        id: check_claude
-        uses: actions/github-script@v7
-        env:
-          PR_NUMBER: ${{ needs.copilot-after-qodo.outputs.pr_number }}
-          TRIGGER_LOGINS: ${{ env.CLAUDE_TRIGGER_LOGINS }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = parseInt(process.env.PR_NUMBER, 10);
-            const triggerLogins = JSON.parse(process.env.TRIGGER_LOGINS);
-            const comments = await github.rest.issues.listComments({
-              issue_number: pr,
-              owner: context.repo.owner,
-              repo: context.repo.repo
-            });
-            const alreadyPosted = comments.data.some(c =>
-              c.body.includes('@claude') && triggerLogins.includes(c.user.login)
-            );
-            core.setOutput('already_triggered', alreadyPosted ? 'true' : 'false');
-
-      - name: Trigger Claude final review
-        if: steps.check_claude.outputs.already_triggered != 'true'
-        uses: actions/github-script@v7
-        env:
-          PR_NUMBER: ${{ needs.copilot-after-qodo.outputs.pr_number }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = parseInt(process.env.PR_NUMBER, 10);
-            const scope = process.env.CLAUDE_UI_SCOPE;
-            const phases = process.env.CLAUDE_FINAL_PHASES_DETAILED;
-            await github.rest.issues.createComment({
-              issue_number: pr,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: '@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAIUI (not a fork), you are able to make modifications to this branch and push directly. ' + scope + ' Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n' + phases
-            });
-            console.log(`Claude triggered on PR #${pr}`);
-
-  # ================================================================
-  # Claude after Gemini — restores the trigger lost from the deleted
-  # chain-claude-after-copilot.yml workflow.
-  # Fires when Gemini posts a review comment on a PR or issue.
-  # ================================================================
-  claude-after-gemini:
-    if: |
-      github.event_name == 'issue_comment' &&
-      (
-        github.event.comment.user.login == 'gemini-code-assist[bot]' ||
-        contains(github.event.comment.body, 'Review completed by Gemini CLI') ||
-        contains(github.event.comment.body, 'The fix is ready for review. Please test')
-      )
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-      pull-requests: write
-    steps:
-      - name: Check if Claude already triggered
-        id: check_claude
-        uses: actions/github-script@v7
-        env:
-          TRIGGER_LOGINS: ${{ env.CLAUDE_TRIGGER_LOGINS }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const triggerLogins = JSON.parse(process.env.TRIGGER_LOGINS);
-            const comments = await github.rest.issues.listComments({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo
-            });
-            const alreadyPosted = comments.data.some(c =>
-              c.body.includes('@claude') && triggerLogins.includes(c.user.login)
-            );
-            core.setOutput('already_triggered', alreadyPosted ? 'true' : 'false');
-
-      - name: Post Claude analysis request (Lead Engineer)
-        if: steps.check_claude.outputs.already_triggered != 'true'
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const scope = process.env.CLAUDE_UI_SCOPE;
-            const phases = process.env.CLAUDE_FINAL_PHASES_DETAILED;
-            await github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: '@claude You are the Lead Engineer. If the branch is under MervinPraison/PraisonAIUI (not a fork), you are able to make modifications to this branch and push directly. ' + scope + ' Read ALL analysis and reviews above carefully (Gemini, CodeRabbit, Qodo, Copilot, etc).\n\n' + phases
-            });
-
-  # ================================================================
-  # BOT PRs: CodeRabbit/Qodo skip bot-authored PRs by default.
-  # Trigger them explicitly. Do NOT trigger Copilot here — it will
-  # be triggered by copilot-after-coderabbit/qodo when they finish.
-  # ================================================================
-  bot-pr-trigger-reviews:
-    if: |
-      github.event_name == 'pull_request' &&
-      github.event.action == 'opened' &&
-      (
-        github.event.pull_request.user.login == 'github-actions[bot]' ||
-        github.event.pull_request.user.login == 'praisonai-triage-agent[bot]' ||
-        github.event.pull_request.user.type == 'Bot'
-      )
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-    steps:
-      - name: Trigger CodeRabbit and Qodo reviews
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = context.payload.pull_request.number;
-            const owner = context.repo.owner;
-            const repo = context.repo.repo;
-
-            // 1. Trigger CodeRabbit review
-            await github.rest.issues.createComment({
-              issue_number: pr, owner, repo,
-              body: '@coderabbitai review'
-            });
-            console.log(`Triggered CodeRabbit for bot PR #${pr}`);
-
-            // 2. Trigger Qodo review
-            await github.rest.issues.createComment({
-              issue_number: pr, owner, repo,
-              body: '/review'
-            });
-            console.log(`Triggered Qodo for bot PR #${pr}`);
-
-            // 3. Trigger Gemini review (commented out)
-            // await github.rest.issues.createComment({
-            //   issue_number: pr, owner, repo,
-            //   body: '@gemini review this PR'
-            // });
-            // console.log(`Triggered Gemini for bot PR #${pr}`);
-
-            // NOTE: @copilot is NOT triggered here.
-            // It will be triggered by copilot-after-coderabbit or copilot-after-qodo
-            // once those bots finish, ensuring Copilot always reviews LAST.
-            console.log('Copilot will be triggered after CodeRabbit/Qodo complete.');
-
-  # ================================================================
-  # BOT PRs: CodeRabbit → Claude directly (skip Copilot when no user PAT)
-  # Copilot ignores github-actions[bot] comments; bot PRs use this path.
-  # ================================================================
-  claude-after-coderabbit-bot-pr:
-    if: |
-      github.event_name == 'issue_comment' &&
-      github.event.issue.pull_request &&
-      github.event.comment.user.login == 'coderabbitai[bot]' &&
-      contains(github.event.comment.body, 'summarize by coderabbit')
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-      pull-requests: read
-    steps:
-      - name: Trigger Claude final review on bot PR
-        uses: actions/github-script@v7
-        env:
-          TRIGGER_LOGINS: ${{ env.CLAUDE_TRIGGER_LOGINS }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = context.issue.number;
-            const { data: pull } = await github.rest.pulls.get({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: pr,
-            });
-            const author = pull.user.login;
-            const isBot = author === 'github-actions[bot]' ||
-              author === 'praisonai-triage-agent[bot]' ||
-              pull.user.type === 'Bot';
-            if (!isBot) {
-              console.log('Human PR — Copilot chain handles Claude trigger');
-              return;
-            }
-            const triggerLogins = JSON.parse(process.env.TRIGGER_LOGINS);
-            const comments = await github.rest.issues.listComments({
-              issue_number: pr,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              per_page: 100,
-            });
-            const alreadyPosted = comments.data.some(c =>
-              c.body.includes('@claude') && triggerLogins.includes(c.user.login)
-            );
-            if (alreadyPosted) {
-              console.log('Claude already triggered on PR #' + pr);
-              return;
-            }
-            await github.rest.issues.createComment({
-              issue_number: pr,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: '@claude You are the FINAL architecture reviewer on this bot-authored PR. Push fixes directly to THIS branch (do NOT open a new PR). ' + process.env.CLAUDE_UI_SCOPE + ' Read ALL CodeRabbit/Qodo comments above.\n\n' + process.env.CLAUDE_FINAL_PHASES_COMPACT
-            });
-            console.log('Claude final review triggered on bot PR #' + pr);
-
-  # ================================================================
-  # Manual: trigger Claude final review on any PR
-  # ================================================================
-  claude-manual-dispatch:
-    if: github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-    steps:
-      - name: Trigger Claude final review
-        uses: actions/github-script@v7
-        env:
-          PR_NUMBER: ${{ inputs.pr_number }}
-          TRIGGER_LOGINS: ${{ env.CLAUDE_TRIGGER_LOGINS }}
-        with:
-          github-token: ${{ env.GH_TOKEN }}
-          script: |
-            const pr = parseInt(process.env.PR_NUMBER, 10);
-            const triggerLogins = JSON.parse(process.env.TRIGGER_LOGINS);
-            const comments = await github.rest.issues.listComments({
-              issue_number: pr,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              per_page: 100,
-            });
-            const alreadyPosted = comments.data.some(c =>
-              c.body.includes('@claude') && triggerLogins.includes(c.user.login)
-            );
-            if (alreadyPosted) {
-              console.log('Claude already triggered on PR #' + pr);
-              return;
-            }
-            await github.rest.issues.createComment({
-              issue_number: pr,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: '@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAIUI (not a fork), you are able to make modifications to this branch and push directly. ' + process.env.CLAUDE_UI_SCOPE + ' Read all prior reviewer comments.\n\n' + process.env.CLAUDE_FINAL_PHASES_COMPACT
-            });
-            console.log('Claude manually triggered on PR #' + pr);
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
+    secrets: inherit
+    with:
+      hub_ref: v1.1.20

.github/workflows/bot-pr-recovery.yml

@@ -0,0 +1,23 @@
+name: Bot PR Recovery
+
+on:
+  schedule:
+    - cron: '*/15 * * * *'
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'Specific PR number to kick (optional)'
+        required: false
+        type: string
+
+permissions:
+  pull-requests: write
+  issues: write
+
+jobs:
+  recover:
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
+    secrets: inherit
+    with:
+      hub_ref: v1.1.20
+      pr_number: ${{ github.event.inputs.pr_number || '' }}

.github/workflows/ci-failure-claude.yml

@@ -0,0 +1,32 @@
+name: Auto CI Failure → Claude
+
+on:
+  workflow_run:
+    workflows: [Core Tests, Optimized Test Suite]
+    types: [completed]
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        required: false
+        type: string
+  schedule:
+    - cron: '15 */6 * * *'
+
+concurrency:
+  group: ci-failure-scan-${{ github.repository }}-${{ github.event.pull_request.number || github.event.workflow_run.id || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  pull-requests: read
+  issues: write
+  actions: read
+
+jobs:
+  detect-and-trigger:
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
+    secrets: inherit
+    with:
+      hub_ref: v1.1.20
+      pr_number: ${{ github.event.inputs.pr_number || '' }}

.github/workflows/ci.yml

@@ -5,9 +5,11 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  workflow_dispatch:
 
 jobs:
   python:
+    name: python
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -34,6 +36,30 @@ jobs:
       - name: Integration smoke tests
         run: pytest tests/integration/test_agentic_roundtrip.py tests/test_feature_sdk_backends.py -q --no-cov --timeout=120
 
+  frontend:
+    name: frontend
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: src/frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: src/frontend
+
+      # `npm run build` is the dashboard ship path: dist/ is synced to
+      # src/praisonaiui/templates/frontend/ (see src/frontend/README.md).
+      - name: Build frontend
+        run: npm run build
+        working-directory: src/frontend
+
   docs:
     runs-on: ubuntu-latest
     if: github.ref == 'refs/heads/main'
@@ -64,3 +90,4 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./site
+          force_orphan: true

.github/workflows/claude-merge-gate.yml

@@ -0,0 +1,96 @@
+name: Claude PR Merge Gate
+
+on:
+  schedule:
+    - cron: '*/10 * * * *'
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        required: false
+        type: string
+      merge_method:
+        required: false
+        type: choice
+        default: merge
+        options: [merge, squash, rebase]
+  workflow_run:
+    workflows:
+      - Claude Assistant
+      - Core Tests
+    types: [completed]
+  repository_dispatch:
+    types: [claude-merge-gate]
+
+concurrency:
+  group: claude-merge-gate-${{ github.repository }}-${{ github.event.inputs.pr_number || github.event.client_payload.pr_number || github.event.workflow_run.id || 'scan' }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pull-requests: read
+  issues: read
+  actions: read
+
+jobs:
+  auto-dispatch:
+    if: github.event_name == 'workflow_run'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      actions: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: MervinPraison/github-automation-template/.github/actions/[email protected]
+        with:
+          hub_ref: v1.1.20
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.CLAUDE_APP_ID }}
+          private-key: ${{ secrets.CLAUDE_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+      - name: Dispatch merge gate when PR pipeline is ready
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          script: |
+            const path = require('path');
+            const mergeGate = require(path.join(process.env.HUB_SCRIPTS, 'merge-gate.js'));
+            const wr = context.payload.workflow_run;
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            if (wr.conclusion !== 'success') return;
+            const allowed = ['Claude Assistant', 'Core Tests'];
+            if (!allowed.includes(wr.name)) return;
+            const prNumber = await mergeGate.resolvePrNumberFromWorkflowRun(github, owner, repo, wr);
+            if (!prNumber) return;
+            const fromClaude = wr.name === 'Claude Assistant';
+            const check = await mergeGate.evaluatePipelineQuiescent(github, owner, repo, prNumber, core, {
+              skipGlobalClaudeRunCheck: fromClaude,
+              skipRecentClaudeCooldown: fromClaude,
+            });
+            if (!check.ready) return;
+            await github.rest.repos.createDispatchEvent({
+              owner, repo, event_type: 'claude-merge-gate',
+              client_payload: { pr_number: prNumber },
+            });
+
+  merge-gate:
+    if: github.event_name != 'workflow_run'
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      actions: read
+      id-token: write
+      statuses: write   # the assess job records security/outsider-review
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
+    secrets: inherit
+    with:
+      hub_ref: v1.1.20
+      pr_number: ${{ github.event.inputs.pr_number || github.event.client_payload.pr_number || '' }}
+      merge_method: ${{ github.event.inputs.merge_method || 'merge' }}

.github/workflows/claude.yml

@@ -1,543 +1,24 @@
 name: Claude Assistant
 
-# Triggers:
-#   - issues:opened       → lightweight triage (labels + auto-claude for owner)
-#   - issues:labeled      → full implementation when `claude` label applied
-#   - issues:assigned     → full implementation when issue assigned to Claude
-#   - issue_comment       → full implementation when @claude mentioned (issues + PRs)
-#   - pull_request_review → full implementation when @claude mentioned in review
-#   - pull_request_review_comment → full implementation when @claude mentioned inline
-#
-# Escalate an issue with the `claude` label OR an @claude comment — not both.
-# If both fire within 3 minutes, the comment trigger is skipped (dedupe job).
-#
-# Focus: CLAUDE only. Copilot and CodeRabbit are GitHub Apps that react to PRs
-# automatically — no workflow file needed. auto-pr-comment.yml orchestrates the
-# CodeRabbit → Copilot → Claude review chain for PRs.
-
 on:
   issue_comment:
     types: [created]
   pull_request_review_comment:
     types: [created]
   issues:
-    types: [opened, labeled, assigned]
+    types: [assigned, labeled, opened]
   pull_request_review:
     types: [submitted]
-  workflow_dispatch:
-    inputs:
-      issue_number:
-        description: 'Issue number for Claude implementation'
-        required: true
-        type: string
 
 jobs:
-  # ================================================================
-  # Job 1 — Issue triage (runs on ANY new issue, including external users)
-  # Posts welcome comment + triage labels. Auto-adds `claude` for owner issues.
-  # ================================================================
-  issue-triage:
-    if: |
-      github.event_name == 'issues' &&
-      github.event.action == 'opened' &&
-      !contains(toJSON(github.event.issue.labels), 'claude')
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-      contents: read
-    steps:
-      - name: Generate GitHub App Token
-        id: app-token
-        continue-on-error: true
-        uses: actions/create-github-app-token@v1
-        with:
-          app-id: ${{ secrets.CLAUDE_APP_ID }}
-          private-key: ${{ secrets.CLAUDE_APP_PRIVATE_KEY }}
-          owner: ${{ github.repository_owner }}
-
-      - name: Resolve GitHub token
-        id: github-token
-        run: |
-          if [ -n "${{ steps.app-token.outputs.token }}" ]; then
-            echo "token=${{ steps.app-token.outputs.token }}" >> "$GITHUB_OUTPUT"
-          else
-            echo "token=${{ secrets.GITHUB_TOKEN }}" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Triage and acknowledge issue
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ steps.github-token.outputs.token }}
-          script: |
-            const issue = context.payload.issue;
-            const title = (issue.title || '').toLowerCase();
-            const body = (issue.body || '').toLowerCase();
-            const content = title + ' ' + body;
-            const isOwner = ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(
-              issue.author_association
-            );
-
-            const labels = [];
-
-            if (content.includes('feature request') || content.includes('[feature')) {
-              labels.push('enhancement');
-            } else if (content.includes('bug') || content.includes('error') || content.includes('crash') || content.includes('traceback')) {
-              labels.push('bug');
-            } else if (content.includes('question') || content.includes('how do i') || content.includes('how to')) {
-              labels.push('question');
-            }
-
-            if (content.includes('security') || content.includes('cve') || content.includes('vulnerability')) {
-              labels.push('security');
-            }
-            if (content.includes('performance') || content.includes('slow') || content.includes('memory leak')) {
-              labels.push('performance');
-            }
-            if (content.includes('documentation') || content.includes('docs')) {
-              labels.push('documentation');
-            }
-            if (content.includes('typescript') || content.includes('javascript') || content.includes('npm')) {
-              labels.push('javascript');
-            }
-            if (content.includes('frontend') || content.includes('react') || content.includes('vite')) {
-              labels.push('frontend');
-            }
-            if (content.includes('example') || content.includes('yaml')) {
-              labels.push('examples');
-            }
-
-            if (labels.length > 0) {
-              await github.rest.issues.addLabels({
-                issue_number: issue.number,
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                labels
-              });
-            }
-
-            if (!isOwner) {
-              await github.rest.issues.createComment({
-                issue_number: issue.number,
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                body: [
-                  `👋 Thanks for opening this issue, @${issue.user.login}!`,
-                  '',
-                  'A maintainer will review this shortly. In the meantime:',
-                  '- Make sure you\'ve included steps to reproduce (for bugs)',
-                  '- Check [existing issues](https://github.com/MervinPraison/PraisonAIUI/issues) for duplicates',
-                  '- Review [AGENTS.md](https://github.com/MervinPraison/PraisonAIUI/blob/main/AGENTS.md) for project conventions',
-                  '',
-                  '_A maintainer can trigger deeper analysis by commenting `@claude` on this issue._'
-                ].join('\n')
-              });
-            }
-
-            if (isOwner) {
-              await github.rest.issues.addLabels({
-                issue_number: issue.number,
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                labels: ['claude']
-              });
-            }
-
-  # ================================================================
-  # Job 2 — Full Claude Code implementation
-  # Triggers on: labeled `claude`, @claude comments, assignments
-  #
-  # Dedup: label + @claude comment on the same issue fires two events.
-  # Skip the comment trigger when `claude` was labelled within 3 minutes.
-  # ================================================================
-  claude-dedupe:
-    if: |
-      github.event_name == 'workflow_dispatch' ||
-      (
-      github.event.action != 'opened' &&
-      (github.event.action != 'labeled' || github.event.label.name == 'claude') &&
-      (github.event_name != 'issue_comment' || contains(github.event.comment.body, '@claude')) &&
-      (
-        !contains(github.actor, '[bot]') ||
-        github.actor == 'github-actions[bot]' ||
-        github.actor == 'praisonai-triage-agent[bot]'
-      ) &&
-      github.actor != 'dependabot[bot]' &&
-      github.actor != 'cursor[bot]' &&
-      github.actor != 'renovate[bot]'
-      )
-    runs-on: ubuntu-latest
-    outputs:
-      proceed: ${{ steps.check.outputs.proceed }}
-    permissions:
-      issues: read
-      pull-requests: read
-    steps:
-      - name: Skip duplicate comment after fresh claude label
-        id: check
-        uses: actions/github-script@v7
-        with:
-          script: |
-            if (context.eventName === 'workflow_dispatch') {
-              core.setOutput('proceed', 'true');
-              return;
-            }
-            if (context.eventName !== 'issue_comment' || context.payload.issue?.pull_request) {
-              core.setOutput('proceed', 'true');
-              return;
-            }
-            const issue = context.payload.issue;
-            const hasClaude = (issue.labels || []).some(l => l.name === 'claude');
-            if (!hasClaude) {
-              core.setOutput('proceed', 'true');
-              return;
-            }
-            const events = await github.rest.issues.listEvents({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: issue.number,
-              per_page: 30,
-            });
-            const windowMs = 3 * 60 * 1000;
-            const recentLabel = events.data.find(e =>
-              e.event === 'labeled' &&
-              e.label?.name === 'claude' &&
-              (Date.now() - new Date(e.created_at).getTime()) < windowMs
-            );
-            if (recentLabel) {
-              core.info('Skipping: claude label was added within 3 minutes — label trigger already handles this issue.');
-              core.setOutput('proceed', 'false');
-              return;
-            }
-            core.setOutput('proceed', 'true');
-
-  claude-response:
-    needs: claude-dedupe
-    env:
-      ISSUE_NUMBER_RESOLVED: ${{ github.event.issue.number || github.event.pull_request.number || inputs.issue_number }}
-    if: needs.claude-dedupe.outputs.proceed == 'true'
-    concurrency:
-      group: claude-${{ github.event.issue.number || github.event.pull_request.number || inputs.issue_number || github.run_id }}
-      cancel-in-progress: true
-    runs-on: ubuntu-latest
+  claude:
     permissions:
       contents: write
       pull-requests: write
       issues: write
       actions: read
       id-token: write
-    steps:
-      - name: Generate GitHub App Token
-        id: app-token
-        continue-on-error: true
-        uses: actions/create-github-app-token@v1
-        with:
-          app-id: ${{ secrets.CLAUDE_APP_ID }}
-          private-key: ${{ secrets.CLAUDE_APP_PRIVATE_KEY }}
-          owner: ${{ github.repository_owner }}
-
-      - name: Resolve GitHub token
-        id: github-token
-        run: |
-          if [ -n "${{ steps.app-token.outputs.token }}" ]; then
-            echo "token=${{ steps.app-token.outputs.token }}" >> "$GITHUB_OUTPUT"
-          else
-            echo "token=${{ secrets.GITHUB_TOKEN }}" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Check for Fork PR
-        id: check_fork
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ steps.github-token.outputs.token }}
-          script: |
-            const isPR = context.eventName === 'pull_request' ||
-              context.eventName === 'pull_request_review' ||
-              context.eventName === 'pull_request_review_comment' ||
-              (context.payload.issue && context.payload.issue.pull_request);
-            if (isPR) {
-              core.setOutput('is_pr_review', 'true');
-              const prNumber = context.payload.pull_request
-                ? context.payload.pull_request.number
-                : context.payload.issue.number;
-              core.setOutput('pr_number', String(prNumber));
-              const pr = await github.rest.pulls.get({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                pull_number: prNumber,
-              });
-              core.setOutput('pr_branch', pr.data.head.ref);
-              const headRepo = pr.data.head.repo?.full_name || context.repo.full_name;
-              core.setOutput('head_repo', headRepo);
-
-              let mergeState = '';
-              try {
-                const gql = await github.graphql(
-                  `query($owner: String!, $repo: String!, $number: Int!) {
-                    repository(owner: $owner, name: $repo) {
-                      pullRequest(number: $number) { mergeStateStatus }
-                    }
-                  }`,
-                  { owner: context.repo.owner, repo: context.repo.repo, number: prNumber }
-                );
-                mergeState = (gql.repository.pullRequest.mergeStateStatus || '').toUpperCase();
-              } catch (e) {
-                core.warning(`GraphQL mergeStateStatus failed: ${e.message}`);
-              }
-              if (!mergeState) {
-                mergeState = (pr.data.mergeable_state || pr.data.merge_state_status || '').toUpperCase();
-              }
-              core.setOutput('merge_state', mergeState);
-
-              if (headRepo !== `${context.repo.owner}/${context.repo.repo}`) {
-                core.setOutput('is_fork', 'true');
-                core.setOutput('clone_url', pr.data.head.repo.clone_url);
-                core.setOutput('branch', pr.data.head.ref);
-                return;
-              }
-              core.setOutput('is_fork', 'false');
-              return;
-            }
-            core.setOutput('is_pr_review', 'false');
-            core.setOutput('is_fork', 'false');
-            core.setOutput('merge_state', '');
-
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-          fetch-depth: 0
-          token: ${{ steps.github-token.outputs.token }}
-          ref: ${{ steps.check_fork.outputs.is_pr_review == 'true' && format('refs/pull/{0}/head', steps.check_fork.outputs.pr_number) || github.ref }}
-
-      - name: Checkout PR branch for edits
-        if: steps.check_fork.outputs.is_pr_review == 'true' && steps.check_fork.outputs.is_fork != 'true'
-        env:
-          PR_BRANCH: ${{ steps.check_fork.outputs.pr_branch }}
-        run: |
-          git checkout "${PR_BRANCH}"
-          git config --local user.name "MervinPraison"
-          git config --local user.email "[email protected]"
-          echo "On branch: $(git branch --show-current)"
-
-      - name: Fetch PR branch and Setup Remote
-        if: steps.check_fork.outputs.is_pr_review == 'true' && steps.check_fork.outputs.is_fork == 'true'
-        env:
-          PR_BRANCH: ${{ steps.check_fork.outputs.pr_branch }}
-        run: |
-          git fetch origin pull/${{ steps.check_fork.outputs.pr_number }}/head:"${PR_BRANCH}"
-          git checkout "${PR_BRANCH}"
-          git remote set-url origin file://$(pwd)
-
-      - name: Run Claude PR final review
-        if: steps.check_fork.outputs.is_pr_review == 'true'
-        uses: anthropics/claude-code-action@beta
-        env:
-          GH_TOKEN: ${{ steps.github-token.outputs.token }}
-        with:
-          allowed_bots: 'praisonai-triage-agent[bot]'
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          github_token: ${{ steps.github-token.outputs.token }}
-          model: claude-opus-4-8
-          trigger_phrase: "@claude"
-          timeout_minutes: "30"
-          direct_prompt: |
-            ${{ steps.check_fork.outputs.is_fork == 'true' && 'CRITICAL: FORK PR — comment only, do not push.\n\n' || 'PR on MervinPraison/PraisonAIUI — SAME REPO, NOT A FORK. You HAVE push permission to this branch. NEVER say this is a fork.\n\n' }}
-            ${{ steps.check_fork.outputs.is_fork != 'true' && steps.check_fork.outputs.merge_state == 'DIRTY' && format('PRIORITY — RESOLVE MERGE CONFLICTS (branch: {0}, PR #{1}):\n- DO NOT create a new branch or PR\n- git fetch origin main && git rebase origin/main\n- Resolve conflicts: keep this PR intent, merge in main newer logic\n- git add -A && git rebase --continue (repeat until done)\n- git push --force-with-lease origin {0}\n- Run targeted pytest/ruff on changed paths\n- Comment files resolved and what you skipped\n- Only after conflicts are resolved, proceed with review phases below if still needed\n\n', steps.check_fork.outputs.pr_branch, steps.check_fork.outputs.pr_number) || '' }}
-            ${{ steps.check_fork.outputs.merge_state != 'DIRTY' && format('CONTEXT: PR #{0} on branch {1}. merge_state={2}.\n\n', steps.check_fork.outputs.pr_number, steps.check_fork.outputs.pr_branch, steps.check_fork.outputs.merge_state) || '' }}
-            You are the Lead Engineer doing FINAL review on this open PR in MervinPraison/PraisonAIUI.
-            Read ALL reviewer comments (CodeRabbit, Gemini, Qodo, Copilot, human). Follow AGENTS.md.
-            SCOPE: src/praisonaiui, src/frontend, tests, docs only.
-
-            **Phase 1 — Review** architecture, security, tests, backward compat, import-time budget.
-            **Phase 2 — FIX (mandatory)** implement every VALID issue on THIS branch. Push commits before Phase 3.
-            Do NOT ask the author to fix. Do NOT open a new PR. Do NOT claim fork restrictions unless is_fork is true.
-            **Phase 3 — Verdict** approve only after fixes are pushed and tests pass; else request changes with specifics.
-
-            git config --global user.name "MervinPraison"
-            git config --global user.email "[email protected]"
-            gh auth setup-git
-            git status
-            git branch --show-current
-          allowed_tools: |
-            Bash(git:*)
-            Bash(python:*)
-            Bash(pip:*)
-            Bash(pytest:*)
-            Bash(ruff:*)
-            Bash(gh:*)
-            Bash(npm:*)
-            View
-            GlobTool
-            GrepTool
-            BatchTool
-            Edit
-            Replace
-
-      - name: Run Claude Code Action
-        if: steps.check_fork.outputs.is_pr_review != 'true'
-        uses: anthropics/claude-code-action@beta
-        env:
-          GH_TOKEN: ${{ steps.github-token.outputs.token }}
-        with:
-          allowed_bots: 'praisonai-triage-agent[bot]'
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          github_token: ${{ steps.github-token.outputs.token }}
-          model: claude-opus-4-8
-          mode: ${{ github.event_name == 'workflow_dispatch' && 'agent' || 'tag' }}
-          trigger_phrase: "@claude"
-          label_trigger: "claude"
-          timeout_minutes: "30"
-          direct_prompt: |
-            ${{ steps.check_fork.outputs.is_fork == 'true' && 'CRITICAL: THIS IS A PULL REQUEST FROM A FORK. YOU DO NOT HAVE PUSH PERMISSIONS TO THIS REPOSITORY. ONLY READ FILES, VALIDATE CODE, AND PROVIDE YOUR COMMENTS/FEEDBACK DIRECTLY IN THIS PR VIA COMMENTS. DO NOT ATTEMPT TO PUSH OR CREATE PULL REQUESTS.\n\n' || 'NOTE: The branch is under MervinPraison/PraisonAIUI (not a fork). You are able to make modifications and push directly to this branch.\n\n' }}
-            You are implementing changes in **MervinPraison/PraisonAIUI** (YAML-driven server-driven UI with agentic chat).
-            Follow `AGENTS.md` at the repository root. If a conflict arises between this prompt and `AGENTS.md`, `AGENTS.md` wins.
-
-            ═══════════════════════════════════════════════════════════════
-            STEP 0 — GIT & GITHUB CLI
-            ═══════════════════════════════════════════════════════════════
-            git config --global user.name "MervinPraison"
-            git config --global user.email "[email protected]"
-            gh auth setup-git
-
-            ═══════════════════════════════════════════════════════════════
-            STEP 1 — READ GUIDELINES
-            ═══════════════════════════════════════════════════════════════
-            Read `AGENTS.md` and any `docs/principles.md`. Key invariants:
-              • Cold import of `praisonaiui` must stay under 200 ms; module count must not grow.
-              • Heavy / optional deps (`mcp`, `langchain`, `llama_index`, `semantic_kernel`,
-                `slack_sdk`, `discord.py`, `botbuilder.core`, `openai`, `anthropic`, `mistralai`,
-                `google.generativeai`) must be **lazy-imported** — never eager.
-              • Public API is verb-first. New classes in `src/praisonaiui/message.py` ending
-                in `Message` with a verb prefix (Ask*, Do*, Request*, …) are forbidden —
-                use a module-level `async def` verb helper instead (see `prompt`, `error`).
-              • Deprecations must emit a runtime `warnings.warn(..., DeprecationWarning, stacklevel=2)`
-                on first access, not only in the docstring.
-              • Deterministic serialisation in anything reaching the wire (sorted keys, stable field
-                order). See existing `to_dict` patterns.
-              • Multi-agent + async safe: no global mutable state without a lock.
-
-            ═══════════════════════════════════════════════════════════════
-            STEP 2 — ARCHITECTURE VALIDATION & ROUTING (MANDATORY before any code)
-            ═══════════════════════════════════════════════════════════════
-            Answer these questions inline in your response, then proceed only if you pass:
-
-            ROUTING:
-              1. **Core aiui** (`src/praisonaiui/`)      — protocols, message types, server, features.
-              2. **Features** (`src/praisonaiui/features/`) — opt-in capabilities (MCP, platforms, lifecycle, audio, auth, sharing, etc.).
-              3. **UI builders** (`src/praisonaiui/ui.py`) — declarative component helpers.
-              4. **Frontend** (`src/frontend/`)            — React components / stores / SSE handlers.
-              5. **Tests** (`tests/unit/`, `tests/integration/`) — new features require both smoke and real-agentic tests.
-              6. **Docs** (`docs/`)                        — canonical name per feature, migration table for renames.
-
-            EXTERNAL REPOS (do NOT edit from within this repo — route the work to the right place and stop):
-              • Core SDK: `MervinPraison/PraisonAI` (`praisonaiagents`, `praisonai`) — agent runtime.
-              • Tools: `MervinPraison/PraisonAI-Tools` — tool implementations.
-              • Docs site: `MervinPraison/PraisonAIDocs` — product docs.
-            If the requested change belongs in an external repo, comment on the issue explaining
-            where it should live and DO NOT open a PR in this repo.
-
-            CONCEPTUAL CHECKS (if ANY fails — add a comment, do NOT open a PR):
-              • Does it duplicate an existing public symbol in `src/praisonaiui/__init__.py`?
-              • Does it add new class-first message types (`class Ask*Message`, `class *Message`
-                with a verb in the name)? → Use a verb-first helper instead.
-              • Does it add a new hard dependency to `pyproject.toml` `[project] dependencies`?
-                → Move to `[project.optional-dependencies]` and wrap imports lazily.
-              • Does it break backward compat (rename, signature change, removal)? → Add
-                a deprecation alias that emits `DeprecationWarning`; never hard-remove before the
-                documented removal version (e.g. `0.5.0`).
-
-            ═══════════════════════════════════════════════════════════════
-            STEP 3 — IMPLEMENT
-            ═══════════════════════════════════════════════════════════════
-            Single branch for the whole flow (reuse the same name in STEP 5):
-              BRANCH="claude/issue-${{ env.ISSUE_NUMBER_RESOLVED }}-$(date +%Y%m%d-%H%M%S)"
-              git checkout -b "$BRANCH"
-
-            Make minimal, focused changes:
-              • Stay within the files listed in the issue's "Scope" / "Files to change" section.
-              • Prefer extending existing modules over adding new ones.
-              • No emojis, no comments, no markdown except where the user asked for it.
-              • Python ≥ 3.10 style (`list[...]` not `List[...]`, `X | None` not `Optional[X]`).
-
-            ═══════════════════════════════════════════════════════════════
-            STEP 4 — TEST / VERIFY
-            ═══════════════════════════════════════════════════════════════
-            Run these targeted checks (NOT the full suite):
-
-              # 1. Lint on only the files you changed:
-              CHANGED=$(git diff --name-only origin/main...HEAD | grep -E '\.py$' | tr '\n' ' ')
-              [ -n "$CHANGED" ] && ruff check $CHANGED
-
-              # 2. Unit tests for the module(s) you touched:
-              pytest tests/unit/<your_new_test_file>.py -v --tb=short
-
-              # 3. Import-time invariant (MUST stay under 200 ms cold):
-              python -c "import time, sys; t=time.time(); import praisonaiui; dt=(time.time()-t)*1000; heavy=[m for m in sys.modules if any(h in m for h in ['langchain','llama_index','mcp','slack','discord','botbuilder','openai.','anthropic.','mistralai','google.generativeai'])]; print(f'{dt:.1f}ms modules={len(sys.modules)} leaked={heavy}'); assert heavy == [], f'Heavy deps leaked: {heavy}'"
-
-            If anything fails, fix the root cause (never skip, xfail, or delete the test).
-
-            ═══════════════════════════════════════════════════════════════
-            STEP 5 — COMMIT, PUSH, OPEN PR (MANDATORY if you produced commits)
-            ═══════════════════════════════════════════════════════════════
-              git add -A
-              git commit -m "feat: <short summary> (fixes #${{ env.ISSUE_NUMBER_RESOLVED }})"
-              git push -u origin "$BRANCH"
-              REPO="${{ github.repository }}"
-              COUNT=$(gh pr list --repo "$REPO" --head "$BRANCH" --json number --jq 'length')
-              if [ "$COUNT" -gt 0 ]; then
-                gh pr list --repo "$REPO" --head "$BRANCH" --json url --jq '.[0].url'
-              else
-                gh pr create --repo "$REPO" --base main --head "$BRANCH" \
-                  --title "feat: <short title>" \
-                  --body "Fixes #${{ env.ISSUE_NUMBER_RESOLVED }}
-
-            ## Summary
-
-            <what changed in one paragraph>
-
-            ## Acceptance criteria
-
-            <copy from the issue; tick boxes only with commit SHA + file path evidence>
-
-            ## Test evidence
-
-            \`\`\`
-            <paste pytest output>
-            \`\`\`
-            "
-              fi
-
-            CRITICAL: Do NOT stop after `git push`. You MUST complete `gh pr create` (or print the
-            existing PR URL from the step above) and post that URL on the issue. Never ask a
-            human to open the PR manually.
-
-            ═══════════════════════════════════════════════════════════════
-            STEP 6 — RESPOND TO REVIEW FEEDBACK (if this run was triggered by a review comment)
-            ═══════════════════════════════════════════════════════════════
-            If you were invoked by a PR review comment, you are the Lead Engineer for this PR:
-              • Read ALL reviewer comments in chronological order (CodeRabbit → Copilot → human).
-              • Fix every VALID issue by pushing commits to THIS branch (do NOT open a new PR).
-              • Reply with a summary of which comments you addressed, which you disagreed with (and why).
-              • Never ship a fix that removes/weakens a test.
-
-          allowed_tools: |
-            Bash(git:*)
-            Bash(python:*)
-            Bash(pip:*)
-            Bash(pytest:*)
-            Bash(ruff:*)
-            Bash(gh:*)
-            Bash(npm:*)
-            Bash(npx:*)
-            Bash(python -m pytest:*)
-            Bash(python -m pip:*)
-            Bash(python -m ruff:*)
-            View
-            GlobTool
-            GrepTool
-            BatchTool
-            Edit
-            Replace
-            mcp__github__get_issue
-            mcp__github__get_issue_comments
-            mcp__github__update_issue
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
+    secrets: inherit
+    with:
+      hub_ref: v1.1.20

.github/workflows/deploy-pages.yml

@@ -0,0 +1,41 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install AIUI
+        run: pip install -e .
+
+      - name: Build docs with AIUI
+        run: |
+          aiui build --output site --minify
+          cp CNAME site/CNAME
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          force_orphan: true

.github/workflows/merge-conflict-claude.yml

@@ -1,7 +1,5 @@
 name: Auto Merge Conflict → Claude
 
-# Detects internal PRs with mergeStateStatus=DIRTY and posts @claude to trigger claude.yml.
-
 on:
   push:
     branches: [main]
@@ -12,11 +10,10 @@ on:
     - cron: '0 */6 * * *'
 
 concurrency:
-  group: merge-conflict-scan-${{ github.repository }}
+  group: merge-conflict-scan-${{ github.repository }}-${{ github.event.pull_request.number || github.run_id }}
   cancel-in-progress: true
 
 env:
-  # PAT posts as MervinPraison so issue_comment triggers claude.yml (GITHUB_TOKEN cannot chain workflows)
   GH_TOKEN: ${{ secrets.GH_TOKEN || github.token }}
 
 permissions:
@@ -27,157 +24,29 @@ jobs:
   detect-and-trigger:
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/checkout@v4
+      - uses: MervinPraison/github-automation-template/.github/actions/[email protected]
+        with:
+          hub_ref: v1.1.20
       - name: Detect conflicting PRs and trigger Claude
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.GH_TOKEN }}
           script: |
+            const path = require('path');
+            const mg = require(path.join(process.env.HUB_SCRIPTS, 'merge-gate.js'));
             const owner = context.repo.owner;
             const repo = context.repo.repo;
             const baseRepo = `${owner}/${repo}`;
-            const COOLDOWN_MS = 12 * 60 * 60 * 1000;
-            const AUTO_ACTORS = ['github-actions[bot]', 'MervinPraison'];
-            const LABEL = 'claude-conflict-pending';
-            const COMMENT_BODY = [
-              '@claude this PR has merge conflicts with `main`.',
-              'Please rebase onto latest `main`, resolve conflicts (keep this PR\'s intent, merge in newer main logic),',
-              'run targeted tests, and force-push with `--force-with-lease`.',
-              'Comment which files you resolved.'
-            ].join(' ');
-
-            const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
-            async function getMergeState(prNumber) {
-              const query = `
-                query($owner: String!, $repo: String!, $number: Int!) {
-                  repository(owner: $owner, name: $repo) {
-                    pullRequest(number: $number) {
-                      mergeStateStatus
-                      maintainerCanModify
-                      isDraft
-                      headRef { repository { nameWithOwner } }
-                    }
-                  }
-                }
-              `;
-              for (let attempt = 0; attempt < 3; attempt++) {
-                const result = await github.graphql(query, { owner, repo, number: prNumber });
-                const prGql = result.repository.pullRequest;
-                const status = (prGql?.mergeStateStatus || '').toUpperCase();
-                if (status && status !== 'UNKNOWN') {
-                  return {
-                    status,
-                    isDraft: prGql.isDraft,
-                    headRepo: prGql.headRef?.repository?.nameWithOwner,
-                    maintainerCanModify: prGql.maintainerCanModify === true,
-                  };
-                }
-                if (attempt < 2) await sleep(10000);
-              }
-              const pr = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
-              return {
-                status: (pr.data.mergeable_state || '').toUpperCase(),
-                isDraft: pr.data.draft,
-                headRepo: pr.data.head.repo?.full_name,
-                maintainerCanModify: pr.data.maintainer_can_modify === true,
-              };
+            const prs = await github.paginate(github.rest.pulls.list, { owner, repo, state: 'open', per_page: 50 });
+            for (const pr of prs) {
+              if (pr.draft) continue;
+              if (pr.head?.repo?.full_name !== baseRepo) continue;
+              const state = await mg.getMergeState(github, owner, repo, pr.number);
+              if (state.status !== 'DIRTY') continue;
+              const { data: comments } = await github.rest.issues.listComments({ owner, repo, issue_number: pr.number, per_page: 100 });
+              if (mg.hasRecentConflictComment(comments)) continue;
+              const body = '@claude this PR has merge conflicts with `main`. Rebase onto latest main, resolve conflicts, run tests, force-push with --force-with-lease.';
+              await github.rest.issues.createComment({ owner, repo, issue_number: pr.number, body });
+              await github.rest.issues.addLabels({ owner, repo, issue_number: pr.number, labels: ['claude-conflict-pending'] });
             }
-
-            function hasFinalClaudeReviewTrigger(comments) {
-              return comments.some((c) => {
-                const body = (c.body || '').toLowerCase();
-                if (!AUTO_ACTORS.includes(c.user.login)) return false;
-                if (!body.includes('@claude')) return false;
-                if (body.includes('merge conflict')) return false;
-                return body.includes('final architecture reviewer') || body.includes('lead engineer');
-              });
-            }
-
-            function hasRecentAutoComment(comments) {
-              const cutoff = Date.now() - COOLDOWN_MS;
-              return comments.some((c) => {
-                if (!AUTO_ACTORS.includes(c.user.login)) return false;
-                const body = (c.body || '').toLowerCase();
-                if (!body.includes('@claude') || !body.includes('merge conflict')) return false;
-                return new Date(c.created_at).getTime() > cutoff;
-              });
-            }
-
-            async function processPR(prNumber) {
-              const { status, isDraft, headRepo, maintainerCanModify } = await getMergeState(prNumber);
-              core.info(`PR #${prNumber}: mergeState=${status}, head=${headRepo}, draft=${isDraft}, maintainerCanModify=${maintainerCanModify}`);
-
-              const { data: issue } = await github.rest.issues.get({
-                owner,
-                repo,
-                issue_number: prNumber,
-              });
-              const labels = issue.labels.map((l) => l.name);
-
-              if (status !== 'DIRTY' && labels.includes(LABEL)) {
-                await github.rest.issues.removeLabel({
-                  owner,
-                  repo,
-                  issue_number: prNumber,
-                  name: LABEL,
-                });
-                core.info(`Removed ${LABEL} from PR #${prNumber}`);
-              }
-
-              if (status !== 'DIRTY') return { skipped: true, reason: 'not dirty' };
-              if (isDraft) return { skipped: true, reason: 'draft' };
-              if (headRepo && headRepo !== baseRepo && !maintainerCanModify) {
-                return { skipped: true, reason: 'fork without maintainer edits' };
-              }
-              if (labels.includes(LABEL)) {
-                return { skipped: true, reason: 'conflict resolution pending' };
-              }
-
-              const { data: comments } = await github.rest.issues.listComments({
-                owner,
-                repo,
-                issue_number: prNumber,
-                per_page: 100,
-              });
-              if (hasRecentAutoComment(comments)) {
-                return { skipped: true, reason: 'recent auto comment' };
-              }
-
-              if (!hasFinalClaudeReviewTrigger(comments)) {
-                return { skipped: true, reason: 'awaiting final claude review trigger' };
-              }
-
-              await github.rest.issues.addLabels({
-                owner,
-                repo,
-                issue_number: prNumber,
-                labels: [LABEL],
-              });
-              await github.rest.issues.createComment({
-                owner,
-                repo,
-                issue_number: prNumber,
-                body: COMMENT_BODY,
-              });
-              return { triggered: true };
-            }
-
-            let prNumbers = [];
-            if (context.eventName === 'pull_request') {
-              prNumbers = [context.payload.pull_request.number];
-            } else {
-              const prs = await github.paginate(github.rest.pulls.list, {
-                owner,
-                repo,
-                state: 'open',
-                per_page: 100,
-              });
-              prNumbers = prs.map((p) => p.number);
-            }
-
-            const results = [];
-            for (const num of prNumbers) {
-              results.push({ pr: num, ...(await processPR(num)) });
-            }
-            core.summary.addRaw('```json\n' + JSON.stringify(results, null, 2) + '\n```');
-            await core.summary.write();

.github/workflows/nightly-release-gate.yml

@@ -0,0 +1,129 @@
+name: Nightly Release Gate
+
+# Preflight before PyPI Release (patch bump).
+# Primary: CI success on main (workflow_run).
+# Backstop: nightly cron at 00:00 UTC.
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Run preflight only; do not dispatch pypi-release.yml'
+        required: false
+        default: false
+        type: boolean
+  workflow_run:
+    workflows:
+      - CI
+    types:
+      - completed
+    branches:
+      - main
+
+permissions:
+  contents: read
+  actions: write
+
+concurrency:
+  group: nightly-release-gate
+  cancel-in-progress: false
+
+jobs:
+  preflight:
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      github.event_name == 'schedule' ||
+      (
+        github.event_name == 'workflow_run' &&
+        github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.head_branch == 'main' &&
+        github.event.workflow_run.event == 'push'
+      )
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ secrets.GH_TOKEN }}
+    steps:
+      - name: Resolve trigger context
+        id: ctx
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_run" ]; then
+            echo "checkout_sha=${{ github.event.workflow_run.head_sha }}" >> "$GITHUB_OUTPUT"
+            echo "source=ci" >> "$GITHUB_OUTPUT"
+            echo "is_ci=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "checkout_sha=main" >> "$GITHUB_OUTPUT"
+            echo "source=nightly" >> "$GITHUB_OUTPUT"
+            echo "is_ci=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          ref: ${{ steps.ctx.outputs.checkout_sha }}
+          fetch-depth: 0
+
+      - name: Fetch main and tags
+        run: git fetch --tags origin main
+
+      - name: Preflight — path changes, CI SHA, dedupe
+        id: preflight
+        uses: actions/github-script@v7
+        env:
+          HEAD_SHA: ${{ steps.ctx.outputs.checkout_sha }}
+          IS_CI: ${{ steps.ctx.outputs.is_ci }}
+        with:
+          github-token: ${{ secrets.GH_TOKEN }}
+          script: |
+            const path = require('path');
+            const rg = require(path.join(process.env.GITHUB_WORKSPACE, '.github/scripts/release-gate.js'));
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const headSha = process.env.HEAD_SHA;
+            const isCi = process.env.IS_CI === 'true';
+
+            const result = await rg.evaluateReleasePreflight(
+              github, owner, repo,
+              { headSha, isCiTrigger: isCi, bump: 'patch' },
+              core
+            );
+
+            core.setOutput('should_release', result.ready ? 'true' : 'false');
+            core.setOutput('reason', result.reasons.join('; '));
+            core.setOutput('head_sha', result.headSha || headSha);
+            core.setOutput('last_tag', result.lastTag || '');
+            core.setOutput('target_version', result.targetVersion || '');
+
+            core.summary.addRaw('## Release gate preflight\n');
+            core.summary.addRaw(`Ready: ${result.ready}\n`);
+            core.summary.addRaw(`Reason: ${result.reasons.join('; ')}\n`);
+            if (result.targetVersion) {
+              core.summary.addRaw(`Target: aiui==${result.targetVersion}\n`);
+            }
+            await core.summary.write();
+
+            if (!result.ready) {
+              core.info(`Skip release: ${result.reasons.join('; ')}`);
+            }
+
+      - name: Dry run summary
+        if: inputs.dry_run == true
+        run: |
+          echo "Dry run — preflight only, no pypi-release dispatch."
+          echo "should_release=${{ steps.preflight.outputs.should_release }}"
+          echo "reason=${{ steps.preflight.outputs.reason }}"
+
+      - name: Dispatch PyPI Release (patch)
+        if: steps.preflight.outputs.should_release == 'true' && inputs.dry_run != true
+        run: |
+          set -euo pipefail
+          gh workflow run pypi-release.yml \
+            --repo "${GITHUB_REPOSITORY}" \
+            --ref main \
+            -f bump=patch \
+            -f source=${{ steps.ctx.outputs.source }} \
+            -f trigger_sha=${{ steps.preflight.outputs.head_sha }} \
+            -f dry_run=false
+          echo "Dispatched pypi-release.yml (patch, source=${{ steps.ctx.outputs.source }})"
+          echo "Uses pypi-auto environment for ci/nightly patch releases."

.github/workflows/pipeline-status-sync.yml

@@ -0,0 +1,19 @@
+name: Pipeline Status Sync
+
+on:
+  schedule:
+    - cron: '*/10 * * * *'
+  workflow_dispatch:
+
+permissions:
+  pull-requests: read
+  issues: write
+  actions: write
+  id-token: write
+
+jobs:
+  sync:
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
+    secrets: inherit
+    with:
+      hub_ref: v1.1.20

.github/workflows/pypi-release.yml

@@ -1,6 +1,6 @@
 name: PyPI Release
 
-# Requires GitHub Environment "pypi" with required reviewers.
+# Requires GitHub Environment "pypi" (manual) or "pypi-auto" (ci/nightly patch).
 # Secrets: PYPI_TOKEN (or PYPI_API_TOKEN), GH_TOKEN
 
 on:
@@ -25,6 +25,16 @@ on:
         required: false
         default: ''
         type: string
+      source:
+        description: 'Trigger source (audit trail)'
+        required: false
+        default: manual
+        type: string
+      trigger_sha:
+        description: 'SHA that triggered this release'
+        required: false
+        default: ''
+        type: string
 
 permissions:
   contents: write
@@ -37,12 +47,24 @@ jobs:
   release:
     if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
-    environment: pypi
+    environment: >-
+      ${{
+        (inputs.source == 'ci' || inputs.source == 'nightly') &&
+        inputs.bump == 'patch' &&
+        'pypi-auto' || 'pypi'
+      }}
     env:
       UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN || secrets.PYPI_API_TOKEN }}
       GH_TOKEN: ${{ secrets.GH_TOKEN }}
       PACKAGE: aiui
     steps:
+      - name: Release audit
+        run: |
+          echo "Source: ${{ inputs.source }}"
+          echo "Trigger SHA: ${{ inputs.trigger_sha }}"
+          echo "Bump: ${{ inputs.bump }}"
+          echo "Environment: ${{ (inputs.source == 'ci' || inputs.source == 'nightly') && inputs.bump == 'patch' && 'pypi-auto' || 'pypi' }}"
+
       - name: Checkout main
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:

.github/workflows/sync-secrets-from-praisonai.yml

@@ -25,7 +25,8 @@ jobs:
         run: |
           gh workflow run sync-secrets-to-aiui.yml \
             --repo MervinPraison/PraisonAI \
-            --ref main
+            --ref main \
+            -f target_repo=MervinPraison/PraisonAIUI
           echo "Triggered: https://github.com/MervinPraison/PraisonAI/actions/workflows/sync-secrets-to-aiui.yml"
           echo ""
           echo "If sync fails (401/403), refresh SECRETS_ADMIN_PAT in PraisonAI,"

.gitignore

@@ -44,6 +44,7 @@ Thumbs.db
 # Project specific
 aiui/
 *.log
+*.err
 .praison/
 .gemini/
 .internal/

README.md

@@ -366,3 +366,7 @@ pytest tests -v
 ## License
 
 MIT © [Praison Limited](https://praison.ai)
+
+Third-party vendored source is documented in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+See the [BeautifulUI upgrade playbook](docs/frontend/beautifului.md) for how BeautifulUI
+primitives are vendored and pinned.

SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+We take the security of PraisonAIUI seriously and appreciate responsible
+disclosure of vulnerabilities.
+
+## Supported Versions
+
+Security fixes are applied to the latest released version of PraisonAIUI.
+Please make sure you are on the most recent release before reporting.
+
+## Reporting a Vulnerability
+
+**Please do not open a public issue for security vulnerabilities.**
+
+Report privately through GitHub's **Private Vulnerability Reporting**:
+
+1. Go to the [Security tab](https://github.com/MervinPraison/PraisonAIUI/security)
+   of this repository.
+2. Click **"Report a vulnerability"** to open a private advisory.
+3. Include as much detail as you can:
+   - Affected component(s) and version.
+   - Steps to reproduce.
+   - Impact assessment.
+   - Any suggested fix or mitigation.
+
+If you are unable to use private reporting, you may open a public issue that
+contains **no technical specifics** and requests a private channel, and a
+maintainer will follow up.
+
+## What to Expect
+
+- We aim to acknowledge new reports within a few business days.
+- We will keep you informed as we investigate and work on a fix.
+- Once a fix is released, we are happy to credit you in the advisory (unless
+  you prefer to remain anonymous).
+
+Thank you for helping keep PraisonAIUI and its users safe.

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,43 @@
+# Third-Party Notices
+
+PraisonAIUI incorporates or vendors source from the third-party projects listed below.
+Their licences and copyright notices are retained here as required.
+
+---
+
+## BeautifulUI
+
+- Project: BeautifulUI — <https://www.beautifului.dev/>
+- Source: <https://github.com/slev12397/beautiful-ui>
+- Licence: MIT
+
+BeautifulUI is distributed as a shadcn registry / copy-paste library (no npm package).
+When its React primitives are vendored into `src/frontend`, the following MIT licence
+applies to that copied source.
+
+```
+MIT License
+
+Copyright (c) Shane Levine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+See the upgrade playbook at [`docs/frontend/beautifului.md`](docs/frontend/beautifului.md)
+for how BeautifulUI is vendored and pinned.

aiui.template.yaml

@@ -9,6 +9,14 @@ site:
     radius: "md"
     darkMode: true
 
+seo:
+  siteUrl: "https://ui.praison.ai"
+  titleTemplate: "%s | %s"
+  defaultImage: "/icon.svg"
+  robots:
+    index: true
+    follow: true
+
 # Mintlify-style navigation: few tabs, many groups per tab
 navigation:
   tabs:
@@ -51,6 +59,11 @@ navigation:
             - typescript/runtime
             - typescript/nextjs
             - typescript/components
+        - group: "Frontend"
+          icon: "layout"
+          prefix: "frontend"
+          pages:
+            - frontend/beautifului
         - group: "Examples"
           icon: "folder-open"
           prefix: "examples"
@@ -73,11 +86,12 @@ navigation:
 # Navbar actions
 navbar:
   primary:
-    type: "github"
-    href: "https://github.com/MervinPraison/PraisonAIUI"
+    type: "button"
+    label: "Get started"
+    href: "/docs/getting-started/quickstart"
   links:
-    - label: "Submit Issues"
-      href: "https://github.com/MervinPraison/PraisonAIUI/issues"
+    - label: "GitHub"
+      href: "https://github.com/MervinPraison/PraisonAIUI"
 
 # Footer
 footer:

docs/adr/0001-replay-view-clean-room.md

@@ -0,0 +1,94 @@
+# ADR 0001: PraisonAI Replay view, a clean-room design
+
+- **Status:** accepted
+- **Date:** 2026-10-26
+- **Scope:** `src/praisonaiui/features/replay.py`, `features/_trace_jsonl.py`,
+  `templates/frontend/plugins/views/replay-core.js`, `templates/frontend/plugins/views/replay.js`
+
+## Context
+
+PraisonAI records agent runs as context-trace JSONL (one `ContextEvent.to_dict()` per
+line). People need to see what a team or flow did: who did what, when, why, and at what
+cost, both after the fact and live. Other tools have shown that a graph plus a trace is a
+useful way to look at agent runs. We want that value without copying anyone's product,
+code or look, and without adding dependencies.
+
+## Decision
+
+Build our own view, in plain DOM and SVG, with our own layout code, palette and words.
+
+### Ideas we took (ideas only)
+
+| Idea | Where it came from | What we did with it |
+|---|---|---|
+| Show the graph of a multi-agent program next to the trace of a run | The general concept behind LangGraph Studio's graph-plus-trace view, known from public talks and articles | A **Map** view drawn by our own layered layout (`layoutMap`); the default view is a **Timeline**, which Studio does not have |
+| Parallel voices on shared time, read left to right | Musical scores and swimlane diagrams | One lane per agent plus Manager and You; parallel branches as sub-lanes; tasks and steps as "chapters" across the top |
+| Vocabulary for LLM and tool spans, tokens and cost | OpenTelemetry GenAI semantic conventions (public specification) | Block kinds (LLM, tool), token and cost totals; the wrapper's OTLP export uses the conventions, the UI only borrows the concepts |
+
+### What we did not use
+
+- **No third-party UI code, CSS, icons, layouts or screenshots** were used to build this
+  view. Shapes, palette, spacing, wording ("Brief", "Delivered", "Waiting for you") and
+  the layout algorithm are our own.
+- **LangGraph's server (Elastic License 2.0) and the proprietary LangGraph Studio were
+  not consulted for code**, and none of their assets, markup or styles were copied. We
+  do not use the name "Studio", any "Lang…" naming, or `__start__`/`__end__` pills.
+- No Mermaid, D3, React Flow, dagre, ELK or other graph libraries. The dashboard's
+  existing Mermaid CDN plugin is not used by Replay.
+
+### How it is built
+
+- `replay-core.js`: pure functions (`buildModel`, `narrate`, `layoutMap`,
+  `deriveGraph`). No DOM, no network. Tested with `node --test`.
+- `replay.js`: DOM/SVG rendering, keyboard handling, SSE follow and approvals. It also
+  boots by itself when `window.__REPLAY_DATA__ = {events, graph}` is set, which is how
+  the wrapper's single-file HTML export works (`standalone_html()` inlines both files).
+- `layoutMap` is a textbook layered layout written from scratch: depth-first search to
+  find back edges (loops), longest-path layering, one virtual waypoint per crossed layer
+  for long edges, and a few barycentre sweeps to order each layer. It is deterministic.
+- Narration is template text, chosen per event type. No LLM, no randomness.
+
+## Palette and accessibility rationale
+
+| Role | Fill | Shape | Why |
+|---|---|---|---|
+| Agent | `#8B0000` | circle | PraisonAI's brand red; white text on it is 10.0:1 |
+| Tool | `#0F7287` | rounded rectangle | Teal kept from the brand but darkened from `#189AB4` (white text on `#189AB4` fails AA); white on `#0F7287` is 5.6:1 |
+| You (human) | `#8A5A00` | diamond | Amber distinct from red and teal for common colour-vision deficiencies; white on it is 5.9:1 |
+| Manager | `#3C4A5C` | square | Neutral slate, so the manager reads as coordination, not work; white on it is 9.0:1 |
+
+- **Never colour alone.** Every lane, block, node and step has a shape and a text label;
+  arrows differ by dash pattern and carry words ("hands off", "delegates", "routes").
+  Heat in the cost/latency overlay is a bar whose height and shade both grow, plus the
+  value in text.
+- **Theme.** Follows the system setting (`prefers-color-scheme`) by default, with a
+  Light/Dark override; the light theme is the design baseline.
+- **Light theme first.** Text tokens are at least 6.9:1 on their backgrounds in light mode
+  and 7.7:1 in dark mode. In dark mode the palette fills keep white text at AA, and get a
+  light 2 px outline so each shape's boundary stays above 3:1 against the dark page.
+- **Keyboard throughout.** ← → (and ↑ ↓ in the step list) move the replay cursor, Home
+  and End jump to the ends, tabs follow the ARIA tabs pattern, map nodes use a roving
+  tab stop, and every action has a real button.
+- **Screen readers.** The narration column is a real ordered list and is the main way
+  through a run. Timeline blocks and map nodes are named buttons whose names start with
+  their visible text (WCAG 2.5.3). Live updates are announced through a polite live
+  region, throttled.
+- **Motion.** The only animation (the live dot) runs only under
+  `prefers-reduced-motion: no-preference`; scrolling is instant when motion is reduced.
+- Checked with axe-core against WCAG 2.0, 2.1 and 2.2 A/AA in both themes (dev-only test
+  in `tests/browser/`).
+
+## Dependency licences
+
+No new runtime or build dependencies. The Python side uses only the standard library and
+Starlette, which aiui already depends on. The browser side is plain ES modules with no
+imports beyond our own file. Dev-only test tools that are not shipped: Playwright
+(Apache-2.0, already used in this environment) and axe-core (MPL-2.0, loaded from a path
+given by `AXE_CORE_JS`; not vendored).
+
+## Consequences
+
+- We own the look and the layout code, and can change them without licence questions.
+- The layout is simpler than a dedicated graph engine. It is fine for the team and flow
+  sizes we see (tens of nodes). Very large graphs may need a better crossing-reduction
+  step later.

docs/features/beautifului-integration.md

@@ -0,0 +1,56 @@
+# BeautifulUI Integration Strategy
+
+> **Epic:** [#292](https://github.com/MervinPraison/PraisonAIUI/issues/292) — BeautifulUI integration strategy for AI-native dashboard UX.
+> This is the durable, agreed strategy that the linked child issues execute against.
+
+[BeautifulUI](https://www.beautifului.dev/) (MIT, Shane Levine / Turbo) is a **copy-paste / shadcn-registry** library of React primitives for AI-native interfaces: thinking traces, streaming answers with inline sources, HITL approval cards, tool chips, task rows, context chunks, diff/records tables, prompt bars, and a reference chat harness.
+
+There is **no published npm package** named `beautiful-ui`. It ships only as source consumed via the shadcn registry or manual copy.
+
+## 1. Strategic decision
+
+BeautifulUI is adopted as **vendored source**, not a runtime dependency, and is exposed to dashboard plugins **only through the existing `@praisonaiui/react` package** — never by importing upstream file paths directly. Rollout is **phased behind a feature flag**, keeping the current vanilla dashboard as the fallback until parity is proven.
+
+Upstream stack (Next.js 15 · React 19 · Tailwind v4 · TypeScript) is closely aligned with PraisonAIUI's `src/frontend` (Vite · React 19 · Tailwind v4 · shadcn/Radix), so primitives port with adapter work rather than a runtime bridge.
+
+## 2. Pillars
+
+| # | Pillar | Decision |
+|---|--------|----------|
+| 1 | **Vendoring model** | Add primitives into `src/frontend` via `npx shadcn add https://www.beautifului.dev/r/<component>.json`, or manual copy from [github.com/slev12397/beautiful-ui](https://github.com/slev12397/beautiful-ui). Pin via lockfile plus a recorded registry URL / git SHA. No `beautiful-ui` npm dependency in production builds. |
+| 2 | **Adapter layer** | Map PraisonAIUI chat / approval / trace **protocol events** to stable internal props. Primitives sit behind `@praisonaiui/react` exports; dashboard plugins consume those exports, not upstream paths. See [#294](https://github.com/MervinPraison/PraisonAIUI/issues/294). |
+| 3 | **Hybrid rollout** | Mount React **islands** (or expand `@praisonaiui/react`) for high-value surfaces first — chat streaming/thinking/tools, then approvals. Vanilla chat (`templates/frontend/plugins/views/chat.js`) stays as the flag-gated fallback until parity is proven. |
+| 4 | **Token strategy** | Merge BeautifulUI foundation CSS **selectively** into the existing shadcn theme generation (`praisonaiui/themes.py`). One design system per page — avoid two competing token sets. |
+| 5 | **Icon licence** | Upstream `SidebarNav` uses the paid `@central-icons-react`. Port nav patterns with **lucide-react** (already in PraisonAIUI) instead. |
+
+## 3. Phasing
+
+1. **Spike** — evaluate primitives in the dev environment, confirm React 19 / Tailwind v4 alignment. [#293](https://github.com/MervinPraison/PraisonAIUI/issues/293)
+2. **Architecture** — adapter layer + upstream pin policy. [#294](https://github.com/MervinPraison/PraisonAIUI/issues/294)
+3. **CI gate** — frontend build + BeautifulUI compatibility check (no frontend build gate exists today). [#295](https://github.com/MervinPraison/PraisonAIUI/issues/295)
+4. **Migrations** — chat streaming / thinking / tool chips ([#296](https://github.com/MervinPraison/PraisonAIUI/issues/296)), then the approval card ([#297](https://github.com/MervinPraison/PraisonAIUI/issues/297)).
+5. **Docs** — upgrade playbook + MIT attribution. [#298](https://github.com/MervinPraison/PraisonAIUI/issues/298)
+
+## 4. Risks
+
+| Risk | Mitigation |
+|------|------------|
+| No semver npm package | Vendor the source; pin to a recorded registry URL / git SHA in the lockfile. |
+| Upstream breaking registry JSON | Vendoring decouples builds from live registry; re-sync is a deliberate, reviewed step. |
+| Icon licence (`@central-icons-react` is paid) | Use lucide-react for ported nav patterns; never vendor the paid package. |
+| Two competing design systems on one page | Selective CSS token merge into `themes.py`; adapter-only prop surface. |
+| React / Tailwind drift | Upstream (React 19 / Tailwind v4) already matches `src/frontend`; the CI gate catches drift. |
+
+## 5. Out of scope
+
+- Replacing the entire dashboard shell in one PR.
+- PyPI packaging of BeautifulUI.
+- iframe embedding of beautifului.dev.
+- Depending on any unpublished npm package for production builds.
+
+## 6. Acceptance criteria status
+
+- [x] Written integration strategy agreed (vendoring + adapter + phased rollout) — this document.
+- [x] Risks documented — section 4.
+- [x] Child issues filed and prioritised — [#293](https://github.com/MervinPraison/PraisonAIUI/issues/293)–[#298](https://github.com/MervinPraison/PraisonAIUI/issues/298).
+- [x] No requirement to depend on unpublished npm packages for production builds — pillar 1, out of scope.

docs/features/knowledge-embeddings.md

@@ -0,0 +1,69 @@
+# Knowledge Embedding Model Configuration
+
+Knowledge / RAG search uses vector **embeddings**. The default embedding model is
+`text-embedding-3-small`. Many OpenAI keys or projects do not have access to that
+model (organization tier, model allowlist, or regional restrictions), which caused
+knowledge search to silently degrade to local substring matching.
+
+PraisonAIUI now makes this failure mode configurable and observable.
+
+## Configure the embedding model
+
+Set an accessible model via environment variable:
+
+```bash
+export AIUI_EMBEDDING_MODEL=text-embedding-ada-002
+```
+
+`OPENAI_EMBEDDING_MODEL` is also honoured as a fallback if `AIUI_EMBEDDING_MODEL`
+is not set.
+
+## Fallback chain
+
+The OpenAI-compatible `/v1/embeddings` endpoint tries the requested (or default)
+model first, then each model in the fallback chain if the primary returns a
+`model_not_found` / 403 access error:
+
+```bash
+export AIUI_EMBEDDING_FALLBACK_MODELS="text-embedding-ada-002,text-embedding-3-small"
+```
+
+If every candidate is inaccessible, the endpoint returns `503` with an actionable
+`model_not_found` error instead of a generic `500`.
+
+## Observing degraded search
+
+`GET /api/knowledge/status` reports embedding availability:
+
+```json
+{
+  "total": 12,
+  "backend": "SDKKnowledgeManager",
+  "status": "degraded",
+  "embedding": {"available": false, "error": "Project does not have access to model `text-embedding-3-small`"},
+  "warnings": ["Embedding model unavailable; knowledge search degraded to local text matching. Set AIUI_EMBEDDING_MODEL to an accessible model."]
+}
+```
+
+`POST /api/knowledge/search` indicates whether results came from vector search or a
+degraded local fallback:
+
+```json
+{
+  "results": [],
+  "count": 0,
+  "search_mode": "fallback",
+  "warning": "Vector search unavailable: Project does not have access to model text-embedding-3-small. Set AIUI_EMBEDDING_MODEL=text-embedding-ada-002 or enable embedding models in your provider project."
+}
+```
+
+A dashboard can show a warning banner whenever `search_mode == "fallback"` or
+`embedding.available == false`.
+
+## Model reference
+
+| Model | Notes |
+|-------|-------|
+| `text-embedding-3-small` | Default — best cost/quality when available |
+| `text-embedding-3-large` | Higher quality — may also be restricted |
+| `text-embedding-ada-002` | Legacy — widely available on older projects |

docs/features/replay.md

@@ -0,0 +1,176 @@
+# Replay
+
+**PraisonAI Replay** shows a recorded agent run as a story: who did what, when, why, and
+at what cost. It works for finished runs and for runs that are still going.
+
+## Record a run, then open it
+
+```bash
+praisonai replay view agents.yaml      # records the run and opens Replay on it
+```
+
+or from Python:
+
+```python
+from praisonai.replay import record
+
+with record(live=True):
+    team.start()
+```
+
+Every recorded run is a file `<id>.jsonl` in the traces folder. Replay reads it from
+`$PRAISONAI_TRACES_DIR`, else `$PRAISON_HOME/traces`, else `~/.praison/traces`.
+
+To open aiui on Replay yourself:
+
+```bash
+aiui run "$(python -c 'import praisonaiui.replay_app as m; print(m.__file__)')" \
+    --style dashboard --host 127.0.0.1 --port 8090
+# then open http://127.0.0.1:8090/replay?run=<id>
+```
+
+`/#/replay?run=<id>` works too. In a full dashboard, Replay is in the sidebar under
+**Control**.
+
+## Watch a run live: the Run button
+
+For learning, demos and debugging, open a page with a **Run** button. Each click records
+a new run, and the page draws it as it happens:
+
+```python
+from praisonai.replay import watch
+
+watch(flow, input="solar sails")   # an Agent, AgentTeam, AgentFlow or agents.yaml
+```
+
+```bash
+praisonai replay watch agents.yaml
+```
+
+On the **Map**, each step and agent shows where the run is: dashed means not reached,
+blue (pulsing) means running now, green means done and red means failed. After a run,
+**▶ Play** moves through it again one step at a time, and the map rewinds with it. One
+run goes at a time. Each run of a team starts its tasks afresh; an Agent keeps its chat
+history between runs.
+
+## Show progress inside your own app
+
+`create_replay_app()` is the same view as a small ASGI app, without the dashboard. Mount
+it in any FastAPI or Starlette app:
+
+```python
+from praisonai.replay import record, replay_app
+
+app.mount("/replay", replay_app())         # read-only: shows recorded runs
+
+# wherever your app starts work:
+with record(run_id, live=True):
+    team.start()
+```
+
+Then show one run, live, in your page, for example in an `<iframe>`:
+
+```html
+<iframe src="/replay/?run=RUN_ID" style="width:100%;height:640px"></iframe>
+```
+
+| URL | Shows |
+|---|---|
+| `/replay/` | The run list and the selected run |
+| `/replay/?run=<id>` | Only that run, no list. A run that has not started yet is waited for. |
+
+`replay_app(team)` adds the Run box to the mounted page. Without the PraisonAI wrapper,
+pass any `run(input, run_id)` callable to `praisonaiui.features.replay.create_replay_app`;
+it must record the run under `run_id`. For a page you build yourself, the view is one
+module:
+
+```html
+<div id="progress"></div>
+<script type="module">
+  import { render } from "/replay/replay.js";
+  render(document.getElementById("progress"), { base: "/replay", run: "RUN_ID", approve: false });
+</script>
+```
+
+`render()` options: `base` (where the API is mounted), `run` (show only this run),
+`runner` (`{input, placeholder, ask}` to show the Run box) and `approve` (`false` hides
+the approve and deny buttons; the embedded app has no approvals API, so answer approvals
+where your app asks for them).
+
+Anyone who can reach the mounted app can read the runs, and with a runner can start one.
+Keep it on localhost or behind your app's login. `POST /api/replay/run` only accepts
+`Content-Type: application/json`, so another website cannot start a run from a visitor's
+browser.
+
+## What you see
+
+| Part | What it shows |
+|---|---|
+| **Runs** | Recorded runs, newest first. A run that is still being written has a **Live** badge. |
+| **Timeline** (default) | One lane per agent, plus **Manager** and **You**. Time runs left to right. LLM calls and tool calls are blocks in their agent's lane. Arrows show hand-offs, delegation, routing and approval requests. Parallel branches get their own sub-lanes. A call or step repeated back to back is one block marked ×N. Tasks and steps run across the top. |
+| **Map** | The team or flow as a graph, drawn from the graph recorded at the start of the run and fitted to the page (−, Fit and + zoom; drag to pan). Agents that took part but are not in the graph, for example after a hand-off to an agent outside the team, appear in an **Outside the team** group with their hand-offs. Older recordings without a graph get a "who talked to whom" map built from the events. Each node shows its state at the cursor: dashed means not reached, blue means running, green means done (×N when it ran more than once) and red means failed; the node the cursor is on has a bold outline. |
+| **What happened** | One plain sentence per step, for example *"Researcher asked web_search for 'solar sail facts' — 1.2 s, $0.002."* Hovering or focusing a sentence highlights its block, and the other way round. |
+| **Details** | Three tabs for the selected step. **What happened**: when, who, how long, cost, tokens, output. **Why**: only what the recording holds, such as the input given to a tool, the context passed in a hand-off and its reason, the manager's task snapshot, the route a step chose, and an approval's decision and where an automatic approval came from. **Raw JSON**: the events themselves. |
+| **Cost & latency** | Adds a bar under each block (taller and darker means more cost, or more time) and per-agent totals in the lane labels. |
+
+Shapes always carry meaning as well as colour: agents are circles, tools are rounded
+rectangles, you are a diamond and the manager is a square. In each lane, LLM calls sit on
+the top row and that agent's tool calls on a thinner row under them, so a long LLM call
+never hides its tools. Labels that do not fit end in "…"; hover or focus a block to see the
+whole label.
+
+The **Theme** menu follows your system's light or dark setting by default; choose Light or
+Dark to override it. On a phone the run list, timeline and steps stack in one column.
+
+## Moving through a run
+
+Replay opens at the end of the run, so you see everything. Move the cursor to replay it:
+anything after the cursor is drawn as an outline.
+
+| Key | Action |
+|---|---|
+| ← → | Previous / next step |
+| ↑ ↓ | Previous / next step in the step list; previous / next node in the map |
+| Home / End | First / last step |
+| Enter or Space | Open the focused block or node |
+| ← → in the tabs | Switch between What happened, Why and Raw JSON |
+
+The scrubber under the timeline does the same with a mouse or touch, and **▶ Play** steps
+through on its own. On a live run the
+cursor follows new events; if you step back, **Jump to live** takes you to the latest.
+
+## Approving from Replay
+
+When an agent asks for approval and the run uses aiui's approval store, a **Waiting for
+you** card appears above the timeline:
+
+- **Approve** or **Deny**, with an optional reason.
+- **Edit arguments…** opens the arguments as JSON (taken from the server, not the redacted
+  recording when the server has them). The JSON must be an object; mistakes are shown
+  as you type. **Approve with these arguments** sends them as `modified_args`.
+
+These buttons call `POST /api/approvals/{id}/approve` and `/deny`. The agent waits until
+you answer, and is denied if nobody answers before the approval timeout.
+
+## Sharing a run as one file
+
+`praisonai replay export RUN --format html` writes a single HTML file with the run and
+this viewer inside. It needs no server and no network. Approvals cannot be answered from
+an exported file.
+
+## HTTP API
+
+| Endpoint | Returns |
+|---|---|
+| `GET /api/replay/runs` | `[{run_id, session_id, path, started_at, ended_at?, status, kind, name, agents, events, cost_usd, live}]`, newest first |
+| `GET /api/replay/runs/{id}/events?after_seq=N` | `{events, graph, run}`; `after_seq` keeps only events with a larger `sequence_num`; `wait=1` answers `{events: [], graph: null, run: null}` instead of 404 for a run that has not started yet |
+| `GET /api/replay/runs/{id}/stream` | Server-sent events: `event: ctx` per trace event (with `id:` = `sequence_num`), `ping` every 15 s, `end` once the run has finished and gone quiet for 2 s. Honours `after_seq` and `Last-Event-ID`. |
+
+With a runner (`create_replay_app(run=...)`), `POST /api/replay/run` with
+`{"input": "..."}` starts a run and returns `{run_id}` (409 while one is going).
+
+Run ids must match `^[A-Za-z0-9._-]+$`. Replay never writes trace files itself. Half-written last lines, unknown fields and unknown event types are skipped
+safely, and schema 1.0 recordings still open.
+
+The **Traces** page reads the same files: each run is a trace, and its spans come from
+matching start and end events.

docs/features/seo.md

@@ -1,73 +1,76 @@
 # SEO
 
-Built-in SEO features for better search engine visibility.
+Built-in SEO for documentation sites — sitemap, robots, llms.txt, per-page meta tags, and crawlable static HTML.
 
-## Automatic Meta Tags
+## Configuration
 
-PraisonAIUI generates meta tags from your configuration:
+Top-level `seo` block in `aiui.template.yaml`:
 
 ```yaml
-site:
-  title: "My Documentation"
-  description: "Comprehensive guides for my product"
+seo:
+  siteUrl: "https://ui.praison.ai"
+  titleTemplate: "%s | %s"
+  defaultImage: "/icon.svg"
+  robots:
+    index: true
+    follow: true
+  twitter:
+    handle: "@yourhandle"
 ```
 
-Generates:
-```html
-<title>My Documentation</title>
-<meta name="description" content="Comprehensive guides for my product">
-```
+`siteUrl` is required for absolute canonical URLs, sitemap, and social tags.
 
-## Page-Level Overrides
+## Build outputs
 
-Use frontmatter to override per-page:
+`aiui build` automatically generates:
+
+| File | Purpose |
+|------|---------|
+| `sitemap.xml` | All doc URLs with `lastmod` dates |
+| `robots.txt` | Crawl rules + sitemap pointer |
+| `llms.txt` | AI crawler index ([llmstxt.org](https://llmstxt.org)) |
+| `llms-full.txt` | Full markdown export for AI tools |
+| `docs/**/*.html` | Per-route HTML with meta tags + crawl nav |
+| `.nojekyll` | GitHub Pages Jekyll bypass |
+
+No extra flags are needed — SEO files are emitted whenever `content.docs` is configured.
+
+## Page-level overrides
+
+Use frontmatter on any markdown page:
 
 ```markdown
 ---
 title: "Custom Page Title"
-description: "Custom meta description for this page"
+description: "Custom meta description for search snippets"
+noindex: true
 ---
 
 # Page Content
 ```
 
-## SEO Configuration
+If `description` is omitted, the first paragraph is used automatically.
+
+## Per-page HTML includes
+
+Each route HTML file contains:
+
+- `<link rel="canonical">` (absolute HTTPS)
+- `<meta name="description">`
+- Open Graph tags (`og:title`, `og:description`, `og:url`, `og:type`, `og:image`)
+- Twitter Card tags
+- JSON-LD `TechArticle` schema
+- Static `<nav>` with links to every doc page (for non-JS crawlers)
+- `<noscript>` pre-rendered page content
+
+## Runtime (SPA navigation)
+
+When users navigate via the sidebar, React updates title, canonical, OG, Twitter, robots, and JSON-LD to match the current page.
+
+## Deploy
+
+GitHub Pages deploy runs via the **Deploy Docs** workflow on every push to `main`. Submit your sitemap in [Google Search Console](https://search.google.com/search-console):
 
-```yaml
-site:
-  seo:
-    titleTemplate: "%s | My Site"
-    defaultImage: "/og-image.png"
-    twitterHandle: "@myhandle"
 ```
-
-## Open Graph
-
-Automatic Open Graph tags for social sharing:
-
-```html
-<meta property="og:title" content="Page Title">
-<meta property="og:description" content="Page description">
-<meta property="og:image" content="/og-image.png">
-<meta property="og:type" content="website">
-```
-
-## Sitemap
-
-Generate a sitemap during build:
-
-```bash
-aiui build --sitemap
-```
-
-Creates `sitemap.xml` with all pages.
-
-## Robots.txt
-
-```yaml
-site:
-  seo:
-    robots:
-      index: true
-      follow: true
+https://your-domain.com/sitemap.xml
 ```

docs/frontend/BEAUTIFULUI_UPSTREAM.md

@@ -0,0 +1,35 @@
+# BeautifulUI upstream pin record
+
+BeautifulUI is vendored (shadcn-style registry copy), **not** an npm dependency.
+This file is the single source of truth for what upstream revision is vendored.
+Update it in the **same PR** that adds or bumps any vendored component, and make
+sure the frontend CI gate (issue #295) passes.
+
+See [beautifului-adapter-architecture.md](./beautifului-adapter-architecture.md)
+for the adapter boundary and folder layout.
+
+## Pin
+
+| Field | Value |
+|-------|-------|
+| Upstream repo | _TBD — record on first vendor_ |
+| Git SHA | _TBD_ |
+| Vendored on (date) | _TBD_ |
+| Registry base URL | _TBD_ |
+| License | MIT (kept in-tree) |
+
+## Vendored components
+
+Record one row per component the first time it is copied in.
+
+| Component | Registry URL | SHA | Vendored path | Date |
+|-----------|--------------|-----|---------------|------|
+| _(none yet)_ | | | | |
+
+## Upgrade checklist
+
+1. Update the SHA / date / registry rows above.
+2. Re-copy changed components into `src/frontend/src/agent-ui/vendors/beautifului/`.
+3. Keep all upstream imports inside `src/agent-ui/` (adapter boundary rule).
+4. Run the frontend build + adapter unit tests (frontend CI gate, #295).
+5. Do **not** add a `beautiful-ui` entry to `package.json` dependencies.

docs/frontend/beautifului-adapter-architecture.md

@@ -0,0 +1,102 @@
+# ADR: BeautifulUI adapter layer & upstream pin policy
+
+**Status:** Accepted · **Issue:** [#294](https://github.com/MervinPraison/PraisonAIUI/issues/294)
+
+## Context
+
+BeautifulUI is **not** a semver npm library — it is distributed as shadcn-style
+registry components that are copied into the consuming repo. PraisonAIUI must
+integrate it without leaking upstream types or import paths across the codebase,
+and without breaking when either side updates.
+
+## Decision
+
+Introduce a single **adapter boundary** between transport payloads and the UI,
+and vendor BeautifulUI components behind that boundary.
+
+```
+Agent APIs (Python) ──► event bus / WS messages
+                              │
+                              ▼
+                    Agent-UI adapter (src/agent-ui/adapter.ts)
+                    (stable PraisonAIUI contracts)
+                              │
+                              ▼
+              @praisonaiui/react re-exports
+              (BeautifulUI vendored components)
+                              │
+                              ▼
+         Dashboard / chat mount points (React islands, then full shell)
+```
+
+### 1. Folder layout
+
+```
+src/frontend/src/agent-ui/
+├── contracts.ts        # Stable PraisonAIUI view models (the ONLY types consumers import)
+├── adapter.ts          # Pure mappers: wire payload -> contracts
+├── adapter.test.ts     # Unit tests (mock events -> props), node:test
+├── index.ts            # Barrel: contracts + adapters + (later) vendored re-exports
+└── vendors/
+    └── beautifului/    # Vendored BeautifulUI components (added during migration)
+```
+
+**Rule:** BeautifulUI / upstream prop types must **never** be imported outside
+`src/agent-ui/`. Consumers depend on `contracts.ts` only, so the vendored
+implementation can be swapped later without touching call sites.
+
+### 2. Adapter contracts
+
+Internal, transport-agnostic types live in `contracts.ts`:
+
+- `AgentStreamEvent` — normalized form of the WebSocket frames handled in
+  `chat.js` (`run_started`, `run_content`, `tool_call_started`, …). Unknown
+  frame `type`s degrade to `kind: 'unknown'` with `rawType` preserved instead
+  of throwing, so new upstream events never break the UI.
+- `ToolCallChipModel` — tool-call chip view model.
+- `ApprovalPromptModel` — approval card view model, mapped from the
+  `/api/approvals/pending` REST payload.
+
+Mappers (`adapter.ts`): `mapChatEventToUi(frame)` and
+`mapApprovalToCardProps(item)`. Both are **pure** and unit tested.
+
+### 3. Vendoring & pin policy
+
+| Mechanism | Purpose |
+|-----------|---------|
+| [`BEAUTIFULUI_UPSTREAM.md`](./BEAUTIFULUI_UPSTREAM.md) | Record git SHA, date, registry base URL for every vendored component |
+| shadcn registry URLs | Per-component install, pinned in the upstream doc |
+| **No** `dependencies.beautiful-ui` in `package.json` | Avoid a phantom npm package |
+
+**Upgrade rule:** bump upstream **only** via a PR that updates
+`BEAUTIFULUI_UPSTREAM.md` and passes the frontend CI gate (issue #295). Icons
+stay on `lucide-react`; do not vendor paid Central icons.
+
+### 4. Feature flag (default **off**)
+
+Integration is gated so the existing vanilla-JS chat/approvals plugins remain
+the fallback until migration milestones (#296, #297) complete.
+
+- **Flag:** `AIUI_BEAUTIFULUI` (build-time env / dashboard config JSON).
+- **Default:** off — vanilla JS renders; the adapter is imported but not mounted.
+- **On:** React islands mount using `src/agent-ui` contracts.
+- **Fallback:** if a vendored component fails to load, the flag is treated as
+  off and the vanilla path renders. No user-facing regression when off.
+
+### 5. Design tokens
+
+Scope agent-UI primitives under an `.aiui-agent-ui { … }` CSS layer (or extend
+the existing shadcn presets in `themes.py`) so vendored component tokens cannot
+collide with the global dashboard theme.
+
+### 6. Deprecation / upstream abandonment
+
+Vendored code stays MIT-licensed in-tree. Because consumers depend only on the
+`contracts.ts` view models, a future first-party implementation can satisfy the
+same contracts and replace the vendored components with no call-site churn.
+
+## Consequences
+
+- One place (`src/agent-ui/`) owns the upstream coupling.
+- Adapters are testable without a browser or the transport layer.
+- The default-off flag keeps the migration reversible at every step.

docs/frontend/beautifului.md

@@ -0,0 +1,107 @@
+# BeautifulUI Upgrade Playbook
+
+How PraisonAIUI vendors [BeautifulUI](https://www.beautifului.dev/) React primitives so
+upgrades are **repeatable** and licence obligations are **explicit**.
+
+!!! info "Related planning"
+    Epic [#292](https://github.com/MervinPraison/PraisonAIUI/issues/292) (integration
+    strategy) and the adapter/pin policy in
+    [#294](https://github.com/MervinPraison/PraisonAIUI/issues/294).
+
+## 1. What BeautifulUI is
+
+BeautifulUI (MIT, © Shane Levine / Turbo) is a library of React primitives aimed at
+**AI-native interfaces** — thinking traces, streaming answers with inline sources,
+human-in-the-loop approval cards, tool chips, task rows, context chunks, and a reference
+chat harness.
+
+**It is a shadcn registry + copy-paste library — not an npm package.** There is no
+published `beautiful-ui` package. You install components by resolving a registry URL, and
+the source is copied into your tree (like any other shadcn/ui primitive).
+
+- Website & registry: <https://www.beautifului.dev/>
+- Upstream source: <https://github.com/slev12397/beautiful-ui>
+
+Upstream stack (Next.js 15 · React 19 · Tailwind CSS v4 · TypeScript) is closely aligned
+with PraisonAIUI's `src/frontend` (Vite · React 19 · Tailwind v4 · shadcn/Radix), which is
+why copy-paste vendoring works without a framework shim.
+
+## 2. One-time foundation setup
+
+PraisonAIUI already carries the shadcn/ui foundation that BeautifulUI primitives depend on:
+
+- **shadcn config** — `src/frontend/components.json` (`style: new-york`,
+  `baseColor: neutral`, `iconLibrary: lucide`, `cssVariables: true`). Its `registries`
+  map is where pinned BeautifulUI registry URLs are added (see §3).
+- **Theme tokens** — `src/praisonaiui/themes.py` generates the shadcn CSS variables
+  (`--background`, `--foreground`, `--primary`, `--radius`, …) at build time for all 22
+  official presets, offline. BeautifulUI's foundation CSS (upstream `app/globals.css`)
+  must only contribute **new** tokens/utilities; it must **not** redefine variables that
+  `themes.py` already owns, or theme switching and dark mode break.
+
+**Rule:** when merging upstream `app/globals.css`, diff it against the variables emitted by
+`themes.py` and keep only the additive slices (new keyframes, component-scoped utilities).
+Record what was merged in the pin doc (§3).
+
+## 3. Adding or updating a primitive
+
+1. **Install with a pinned registry URL** from `src/frontend/`:
+   ```bash
+   npx shadcn add https://www.beautifului.dev/r/<component>.json
+   ```
+   The registry resolves dependencies and CSS slices. Commit the resulting
+   `package-lock.json` change in the same PR.
+2. **Re-export through the adapter** — add the component to
+   `src/frontend/src/components/index.ts` (`@praisonaiui/react`). Consumers never import
+   the raw vendored path (see §4).
+3. **Update the pin record** — create/update `docs/frontend/BEAUTIFULUI_UPSTREAM.md` with:
+   the upstream **git SHA**, the **date**, the **registry base URL**, and the **component
+   list** vendored so far. This file is the single source of truth for "what version are
+   we on". (It is created the first time a real primitive is vendored — do not add it
+   empty.)
+4. **Rebuild & sync the bundle** — the committed frontend bundle must be regenerated:
+   ```bash
+   cd src/frontend && npm run build
+   # then sync dist/{index.html,assets/,icon.svg} → src/praisonaiui/templates/frontend/
+   ```
+   (See `AGENTS.md` → "Frontend Build".)
+5. **Run frontend CI** — `.github/workflows/ci.yml` (ruff + pytest) must pass, plus the
+   frontend build step.
+
+## 4. Adapter boundary
+
+Consumers import from **`@praisonaiui/react` only** — never from raw vendored paths such as
+`@/components/ui/...` or any upstream module.
+
+```tsx
+// ✅ stable PraisonAIUI contract
+import { Button, ThemeToggle } from '@praisonaiui/react'
+
+// ❌ leaks upstream/shadcn paths across the codebase
+import { Button } from '@/components/ui/button'
+```
+
+This keeps the upstream surface behind one file (`components/index.ts`), so a BeautifulUI
+bump changes vendored source but not consumer imports.
+
+## 5. Rollback
+
+- BeautifulUI-backed views mount behind a **feature flag**; the **vanilla dashboard views**
+  (`src/praisonaiui/templates/frontend/plugins/*`) remain the fallback and are kept working.
+- To roll back a bad bump: revert the vendoring PR (source + `BEAUTIFULUI_UPSTREAM.md` +
+  rebuilt bundle move together in one commit), and disable the flag. No consumer import
+  changes are needed because everything routes through the adapter (§4).
+
+## 6. Licence
+
+BeautifulUI is **MIT, © Shane Levine**. The full licence text is retained in
+[`THIRD_PARTY_NOTICES.md`](https://github.com/MervinPraison/PraisonAIUI/blob/main/THIRD_PARTY_NOTICES.md)
+at the repository root. Any PR that vendors or bumps BeautifulUI source must keep that
+notice present and current.
+
+## 7. Commercial icons — do not vendor
+
+Do **not** use `@central-icons-react` without a licence — it is commercial. PraisonAIUI
+standardises on **`lucide-react`** (`iconLibrary: lucide` in `components.json`). If an
+upstream BeautifulUI primitive imports commercial icons, swap them for lucide equivalents
+during vendoring.

docs/protocols/adp/README.md

@@ -0,0 +1,69 @@
+# Application Design Protocol (ADP)
+
+Declarative UI design standard for describing application layout, navigation, components, and theming from YAML or JSON manifests.
+
+**Status:** v1alpha1 research draft — see [implementation-status.md](./implementation-status.md) for what is implemented today.
+
+## Documents
+
+| Document | Description |
+|----------|-------------|
+| [Research report](../application-design-protocol-report.md) | 46 standards compared; YAML vs JSON debate; design principles |
+| [spec.md](./spec.md) | Normative specification (draft) |
+| [validation-rules.md](./validation-rules.md) | Cross-reference rules R1–R30 |
+| [aiui-mapping.md](./aiui-mapping.md) | PraisonAIUI field mapping |
+| [implementation-status.md](./implementation-status.md) | Feature implementation tracker |
+
+## Schemas
+
+| File | Purpose |
+|------|---------|
+| [schema/application.schema.json](./schema/application.schema.json) | Root Application kind |
+| [schema/component-catalog.schema.json](./schema/component-catalog.schema.json) | Catalog meta-schema |
+| [schema/theme.schema.json](./schema/theme.schema.json) | Theme preset or DTCG tokens |
+| [catalogs/default.catalog.json](./catalogs/default.catalog.json) | Default component and layout catalog |
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [examples/minimal.application.yaml](./examples/minimal.application.yaml) | Smallest valid app |
+| [examples/docs-site.application.yaml](./examples/docs-site.application.yaml) | Full docs site |
+| [examples/landing-page.application.yaml](./examples/landing-page.application.yaml) | Zone-based layout |
+
+## Validate locally
+
+```bash
+pip install jsonschema pyyaml
+pytest tests/unit/test_adp_schemas.py -v
+```
+
+## Quick start
+
+```yaml
+schemaVersion: 1
+apiVersion: adp.io/v1alpha1
+kind: Application
+
+metadata:
+  name: my-app
+  version: "1.0.0"
+
+spec:
+  site:
+    title: "My App"
+  theme:
+    preset: zinc
+    darkMode: true
+  templates:
+    docs:
+      layout: TwoColumnLayout
+      slots:
+        main: { type: DocContent }
+  routes:
+    - match: "/docs/**"
+      template: docs
+  content:
+    docs:
+      dir: "./docs"
+```

docs/protocols/adp/aiui-mapping.md

@@ -0,0 +1,138 @@
+# PraisonAIUI → ADP Field Mapping
+
+Field-by-field mapping from current `aiui.template.yaml` (`Config` model in `src/praisonaiui/schema/models.py`) to ADP `Application` spec.
+
+**Compatibility:** Flat `aiui.template.yaml` files work with the PraisonAIUI compiler today. ADP envelope format is **planned** — see [implementation-status.md](./implementation-status.md).
+
+---
+
+## Envelope (new in ADP)
+
+| ADP field | PraisonAIUI today | Status | Change |
+|-----------|-------------------|--------|--------|
+| `schemaVersion: 1` | `schemaVersion: 1` | Implemented | Compatible |
+| `apiVersion: adp.io/v1alpha1` | Not present | Planned | Add when envelope parser lands |
+| `kind: Application` | Not present | Planned | Add when envelope parser lands |
+| `metadata.name` | Not present | Planned | Derive from `site.title` slug |
+| `metadata.version` | Not present | Planned | Recommend SemVer |
+
+## Top-level → spec wrapper
+
+| PraisonAIUI (flat) | ADP (envelope) | Status | Change |
+|--------------------|----------------|--------|--------|
+| `site:` | `spec.site:` | Planned | Wrap under `spec` |
+| `site.theme` | `spec.theme:` | Planned | Promote theme to spec level |
+| `navigation:` | `spec.navigation:` | Partial | Tabs compiled; not rendered |
+| `navbar:` | `spec.navbar:` | Partial | Compiled; not rendered |
+| `footer:` | `spec.footer:` | Partial | Compiled; not rendered |
+| `search:` | `spec.search:` | Partial | Compiled; not rendered |
+| `content:` | `spec.content:` | Implemented | Same |
+| `components:` | `spec.components:` | Implemented | Same |
+| `templates:` | `spec.templates:` | Implemented | Same |
+| `routes:` | `spec.routes:` | Partial | Compiled; routing not honoured |
+| `dependencies:` | `spec.dependencies:` | Implemented | Same |
+| `logo:` (top-level) | Future ADP field | Implemented | Top-level on `Config`, not under `site` |
+| `style:`, `chat:`, `auth:`, `dashboard:` | Not in ADP v1alpha1 | N/A | Separate kinds in future |
+
+## Navigation fields
+
+| Field | PraisonAIUI | ADP | Status | Notes |
+|-------|-------------|-----|--------|-------|
+| `navigation.tabs[]` | Mintlify-style tabs | `spec.navigation.tabs` | Partial | Compiled, not rendered |
+| `content.docs.nav.mode` | `NavConfig.mode` | Same | Gap | Defined but unused by compiler |
+| Top-level `navigation.mode` | Not present | Removed from ADP | N/A | Use `content.docs.nav.mode` instead |
+
+## Theme fields
+
+| Field | PraisonAIUI | ADP | Status |
+|-------|-------------|-----|--------|
+| `site.theme.preset` | Implemented | `spec.theme.preset` | Planned (envelope) |
+| `site.theme.radius` | Implemented | Same | Same |
+| `site.theme.darkMode` | Implemented | Same | Same |
+| `theme.tokens` | Not present | DTCG file ref | Planned |
+
+## Component fields
+
+| Field | PraisonAIUI | ADP | Status |
+|-------|-------------|-----|--------|
+| `components.{id}.type` | String literal | Catalog allowlist | Planned (R6) |
+| `components.{id}.props` | `dict[str, Any]` | Catalog schema | Planned (R7) |
+
+## Template fields
+
+| Field | PraisonAIUI | ADP | Status |
+|-------|-------------|-----|--------|
+| `templates.{id}.layout` | String | Catalog enum | Same values |
+| `templates.{id}.slots` | `{ ref \| type }` | Same | Same |
+| `templates.{id}.zones` | Widget arrays | Same | Same |
+| Slots + zones on same template | Allowed | R13: one or the other | Stricter in ADP |
+
+## Route fields
+
+| Field | PraisonAIUI | ADP | Status |
+|-------|-------------|-----|--------|
+| `routes[].match` | Glob string | Same | Same |
+| `routes[].template` | Template key | Same | Same |
+| Runtime route resolution | Not implemented | R28 required | Gap |
+
+## Migration example
+
+### Today (PraisonAIUI)
+
+```yaml
+schemaVersion: 1
+
+site:
+  title: "My Docs"
+  theme:
+    preset: zinc
+
+templates:
+  docs:
+    layout: TwoColumnLayout
+    slots:
+      main: { type: DocContent }
+
+routes:
+  - match: "/docs/**"
+    template: docs
+```
+
+### Target (ADP)
+
+```yaml
+schemaVersion: 1
+apiVersion: adp.io/v1alpha1
+kind: Application
+
+metadata:
+  name: my-docs
+  version: "1.0.0"
+
+spec:
+  site:
+    title: "My Docs"
+  theme:
+    preset: zinc
+  templates:
+    docs:
+      layout: TwoColumnLayout
+      slots:
+        main: { type: DocContent }
+  routes:
+    - match: "/docs/**"
+      template: docs
+  content:
+    docs:
+      dir: "./docs"
+```
+
+## Breaking vs compatible changes
+
+| Change | Breaking? | Mitigation |
+|--------|-----------|------------|
+| Add envelope fields | No | Envelope parser normalises to flat `Config` |
+| Catalog validation | Soft break | Warn first, error in strict mode |
+| Route runtime resolution | No (fix) | Frontend change |
+| R13 slots/zones exclusivity | Soft break | Warn on violation |
+| Remove chat/dashboard from ADP | No | Separate kinds in future |

docs/protocols/adp/catalogs/default.catalog.json

@@ -0,0 +1,128 @@
+{
+  "name": "adp-default-catalog",
+  "version": "1.0.0",
+  "description": "Default ADP component and layout catalog for PraisonAIUI",
+  "components": {
+    "Header": {
+      "description": "Site header with logo and navigation",
+      "props": {
+        "type": "object",
+        "properties": {
+          "logoText": { "type": "string" },
+          "logoHref": { "type": "string", "default": "/" }
+        },
+        "required": ["logoText"],
+        "additionalProperties": false
+      },
+      "aria": { "role": "banner" },
+      "slots": ["header"]
+    },
+    "Footer": {
+      "description": "Site footer",
+      "props": {
+        "type": "object",
+        "properties": {
+          "text": { "type": "string" }
+        },
+        "additionalProperties": false
+      },
+      "aria": { "role": "contentinfo" },
+      "slots": ["footer"]
+    },
+    "DocsSidebar": {
+      "description": "Documentation sidebar navigation",
+      "props": {
+        "type": "object",
+        "properties": {
+          "source": { "type": "string", "enum": ["docs-nav", "manual"], "default": "docs-nav" }
+        },
+        "additionalProperties": false
+      },
+      "aria": { "role": "navigation" },
+      "slots": ["left", "leftSidebar"]
+    },
+    "DocContent": {
+      "description": "Main documentation content area",
+      "props": { "type": "object", "additionalProperties": false },
+      "aria": { "role": "main" },
+      "slots": ["main"]
+    },
+    "Toc": {
+      "description": "Table of contents for current page",
+      "props": { "type": "object", "additionalProperties": false },
+      "aria": { "role": "navigation" },
+      "slots": ["right", "rightSidebar"]
+    },
+    "HeroBanner": {
+      "description": "Hero banner with title and CTA",
+      "props": {
+        "type": "object",
+        "properties": {
+          "title": { "type": "string" },
+          "subtitle": { "type": "string" },
+          "ctaLabel": { "type": "string" },
+          "ctaHref": { "type": "string" }
+        },
+        "required": ["title"],
+        "additionalProperties": false
+      },
+      "slots": ["hero"]
+    },
+    "SocialLinks": {
+      "description": "Social media link row",
+      "props": {
+        "type": "object",
+        "properties": {
+          "links": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "platform": { "type": "string" },
+                "href": { "type": "string" }
+              },
+              "required": ["platform", "href"],
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "slots": ["footer"]
+    },
+    "Copyright": {
+      "description": "Copyright notice",
+      "props": {
+        "type": "object",
+        "properties": {
+          "text": { "type": "string" }
+        },
+        "required": ["text"],
+        "additionalProperties": false
+      },
+      "slots": ["footer"]
+    }
+  },
+  "layouts": {
+    "ThreeColumnLayout": {
+      "description": "Header + left sidebar + main + right TOC + footer",
+      "slots": ["header", "left", "main", "right", "footer"]
+    },
+    "TwoColumnLayout": {
+      "description": "Sidebar + main content",
+      "slots": ["left", "main"]
+    },
+    "CenteredLayout": {
+      "description": "Centred single column",
+      "slots": ["main"]
+    },
+    "FullWidthLayout": {
+      "description": "Full-width content",
+      "slots": ["header", "main", "footer"]
+    },
+    "FlexibleLayout": {
+      "description": "WordPress-style zone grid",
+      "zones": ["header", "topNav", "hero", "leftSidebar", "main", "rightSidebar", "bottomNav", "footer"]
+    }
+  }
+}

docs/protocols/adp/examples/docs-site.application.yaml

@@ -0,0 +1,104 @@
+schemaVersion: 1
+apiVersion: adp.io/v1alpha1
+kind: Application
+
+metadata:
+  name: praisonaiui-docs
+  version: "1.0.0"
+  labels:
+    generator: praisonaiui
+
+spec:
+  site:
+    title: "PraisonAIUI Docs"
+    description: "Documentation for PraisonAIUI - YAML-driven website generator"
+    ui: shadcn
+
+  theme:
+    preset: zinc
+    radius: md
+    darkMode: true
+
+  navigation:
+    tabs:
+      - tab: "Documentation"
+        groups:
+          - group: "Getting Started"
+            icon: rocket
+            prefix: getting-started
+            pages:
+              - index
+              - getting-started/installation
+              - getting-started/quickstart
+          - group: "Core Concepts"
+            icon: lightbulb
+            prefix: concepts
+            pages:
+              - concepts/architecture
+              - concepts/configuration
+              - concepts/templates
+      - tab: "API Reference"
+        groups:
+          - group: "API Reference"
+            icon: code
+            prefix: api
+            pages:
+              - api/cli
+              - api/python
+
+  navbar:
+    primary:
+      type: github
+      href: "https://github.com/MervinPraison/PraisonAIUI"
+    links:
+      - label: "Submit Issues"
+        href: "https://github.com/MervinPraison/PraisonAIUI/issues"
+
+  footer:
+    socials:
+      github: "https://github.com/MervinPraison/PraisonAI"
+    links:
+      - header: "Resources"
+        items:
+          - label: "GitHub"
+            href: "https://github.com/MervinPraison/PraisonAI"
+
+  search:
+    enabled: true
+    provider: fusejs
+
+  content:
+    docs:
+      dir: "./docs"
+      include:
+        - "**/*.md"
+        - "**/*.mdx"
+      nav:
+        mode: manual
+
+  components:
+    header_main:
+      type: Header
+      props:
+        logoText: "PraisonAIUI"
+    footer_main:
+      type: Footer
+      props:
+        text: "© 2026 PraisonAI"
+    sidebar_docs:
+      type: DocsSidebar
+      props:
+        source: docs-nav
+
+  templates:
+    docs:
+      layout: ThreeColumnLayout
+      slots:
+        header: { ref: header_main }
+        left: { ref: sidebar_docs }
+        main: { type: DocContent }
+        footer: { ref: footer_main }
+
+  routes:
+    - match: "/docs/**"
+      template: docs

docs/protocols/adp/examples/landing-page.application.yaml

@@ -0,0 +1,58 @@
+schemaVersion: 1
+apiVersion: adp.io/v1alpha1
+kind: Application
+
+metadata:
+  name: colorful-landing
+  version: "1.0.0"
+
+spec:
+  site:
+    title: "Colorful Docs"
+    description: "Zone-based landing page with hero and footer widgets"
+    ui: shadcn
+
+  theme:
+    preset: rose
+    radius: xl
+    darkMode: true
+
+  content:
+    docs:
+      dir: "./docs"
+      nav:
+        mode: auto
+        collapsible: true
+
+  templates:
+    docs:
+      layout: FlexibleLayout
+      zones:
+        hero:
+          - type: HeroBanner
+            props:
+              title: "Colorful Documentation"
+              subtitle: "Vibrant, playful, and beautifully designed"
+              ctaLabel: "Get Started"
+              ctaHref: "/docs/getting-started/quickstart"
+        rightSidebar:
+          - type: Toc
+        footer:
+          - type: SocialLinks
+            props:
+              links:
+                - platform: Twitter
+                  href: "https://twitter.com"
+                - platform: GitHub
+                  href: "https://github.com"
+          - type: Copyright
+            props:
+              text: "Made with love by Colorful Team"
+
+  routes:
+    - match: "/docs/**"
+      template: docs
+
+  a11y:
+    skipToContent: true
+    reduceMotion: false

docs/protocols/adp/examples/minimal.application.yaml

@@ -0,0 +1,32 @@
+schemaVersion: 1
+apiVersion: adp.io/v1alpha1
+kind: Application
+
+metadata:
+  name: minimal-docs
+  version: "1.0.0"
+
+spec:
+  site:
+    title: "Minimal Docs"
+    description: "Smallest valid ADP Application manifest"
+    ui: shadcn
+
+  theme:
+    preset: zinc
+    radius: md
+    darkMode: true
+
+  content:
+    docs:
+      dir: "./docs"
+
+  templates:
+    docs:
+      layout: TwoColumnLayout
+      slots:
+        main: { type: DocContent }
+
+  routes:
+    - match: "/docs/**"
+      template: docs

docs/protocols/adp/implementation-status.md

@@ -0,0 +1,36 @@
+# ADP Implementation Status
+
+Honest status of ADP v1alpha1 features against the PraisonAIUI reference implementation.
+
+**Last updated:** August 2026
+
+| Feature | Spec reference | Status | Notes |
+|---------|----------------|--------|-------|
+| JSON Schema validation in CLI | spec §6 | Planned | Schemas published; no `aiui validate --adp` yet |
+| ADP envelope parsing (`apiVersion/kind/spec`) | spec §3 | Planned | Flat `aiui.template.yaml` works today |
+| Component catalog validation (R6–R7) | spec §5 | Planned | Catalog split to `catalogs/default.catalog.json` |
+| `$yaml:` / `$json:` file includes | spec §7 | Planned | Not implemented in compiler |
+| Strict mode unknown-field rejection (R4) | validation-rules R4 | Planned | Pydantic allows extra fields on some models |
+| Route-driven template resolution (R28) | validation-rules R28 | Gap | Frontend hardcodes `templates.docs` |
+| Sidebar nav mode (R29) | validation-rules R29 | Gap | Filesystem-only sidebar today |
+| Catalog ARIA roles at render (R30) | validation-rules R30 | Gap | No catalog-driven a11y in renderer |
+| `navigation.tabs` rendering | spec §4.3 | Gap | Compiled to manifest but not consumed by React |
+| DTCG token file validation (R26) | validation-rules R26 | Planned | Preset shorthand works via Tailwind |
+| Published `$schema` URLs | README | Partial | Local schemas only; `https://adp.io/` is placeholder |
+
+## What works today
+
+- Flat `aiui.template.yaml` → Pydantic `Config` → compiler → JSON manifests → React SPA
+- Components, templates, routes, theme presets, content scanning
+- ADP example manifests validate against `application.schema.json` (standalone)
+- Unit tests in `tests/unit/test_adp_schemas.py`
+
+## Migration path
+
+1. Add envelope normalisation layer before `Config.model_validate`
+2. Wire `route-manifest.json` into frontend routing (R28)
+3. Honour `navigation.tabs` and `content.docs.nav.mode` (R29)
+4. Add `aiui validate --schema adp` using published JSON Schema
+5. Apply catalog ARIA hints at render time (R30)
+
+See [aiui-mapping.md](./aiui-mapping.md) for field-level compatibility.

docs/protocols/adp/schema/application.schema.json

@@ -0,0 +1,449 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "application.schema.json",
+  "title": "ADP Application",
+  "description": "Application Design Protocol — Application kind manifest",
+  "type": "object",
+  "required": ["schemaVersion", "apiVersion", "kind", "metadata", "spec"],
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-adp-": {}
+  },
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "ADP envelope version"
+    },
+    "apiVersion": {
+      "type": "string",
+      "const": "adp.io/v1alpha1"
+    },
+    "kind": {
+      "type": "string",
+      "const": "Application"
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-adp-": {}
+      },
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string" },
+        "labels": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "annotations": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "required": ["site", "templates", "routes"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-adp-": {}
+      },
+      "properties": {
+        "site": { "$ref": "#/$defs/site" },
+        "theme": { "$ref": "#/$defs/theme" },
+        "navigation": { "$ref": "#/$defs/navigation" },
+        "navbar": { "$ref": "#/$defs/navbar" },
+        "footer": { "$ref": "#/$defs/footer" },
+        "search": { "$ref": "#/$defs/search" },
+        "components": { "$ref": "#/$defs/components" },
+        "templates": { "$ref": "#/$defs/templates" },
+        "routes": { "$ref": "#/$defs/routes" },
+        "content": { "$ref": "#/$defs/content" },
+        "dependencies": { "$ref": "#/$defs/dependencies" },
+        "seo": { "$ref": "#/$defs/seo" },
+        "i18n": { "$ref": "#/$defs/i18n" },
+        "a11y": { "$ref": "#/$defs/a11y" }
+      }
+    }
+  },
+  "$defs": {
+    "site": {
+      "type": "object",
+      "required": ["title"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-adp-": {}
+      },
+      "properties": {
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "ui": {
+          "type": "string",
+          "enum": ["shadcn", "mui", "chakra"],
+          "default": "shadcn"
+        },
+        "routeBaseDocs": { "type": "string", "default": "/docs" },
+        "customCss": { "type": "string" },
+        "plugins": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "theme": {
+      "oneOf": [
+        {
+          "title": "Preset theme",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "preset": {
+              "type": "string",
+              "enum": [
+                "zinc", "slate", "stone", "gray", "neutral",
+                "red", "orange", "amber", "yellow", "lime", "green",
+                "emerald", "teal", "cyan", "sky", "blue", "indigo",
+                "violet", "purple", "fuchsia", "pink", "rose"
+              ]
+            },
+            "radius": {
+              "type": "string",
+              "enum": ["none", "sm", "md", "lg", "xl"]
+            },
+            "darkMode": { "type": "boolean" }
+          },
+          "required": ["preset"]
+        },
+        {
+          "title": "DTCG token reference",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tokens": {
+              "type": "string",
+              "description": "Path or URL to DTCG 2025.10 compliant tokens.json"
+            },
+            "darkMode": { "type": "boolean" }
+          },
+          "required": ["tokens"]
+        }
+      ]
+    },
+    "slotRef": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["ref"],
+          "additionalProperties": false,
+          "properties": {
+            "ref": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "type": "string" },
+            "props": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      ]
+    },
+    "widget": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string" },
+        "props": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "components": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["type"],
+        "additionalProperties": false,
+        "properties": {
+          "type": { "type": "string" },
+          "props": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        }
+      }
+    },
+    "template": {
+      "type": "object",
+      "required": ["layout"],
+      "allOf": [
+        {
+          "oneOf": [
+            { "required": ["slots"] },
+            { "required": ["zones"] }
+          ]
+        }
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "layout": {
+          "type": "string",
+          "enum": [
+            "ThreeColumnLayout",
+            "TwoColumnLayout",
+            "CenteredLayout",
+            "FullWidthLayout",
+            "FlexibleLayout"
+          ]
+        },
+        "slots": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/slotRef" }
+        },
+        "zones": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/widget" }
+          }
+        }
+      }
+    },
+    "templates": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/template" }
+    },
+    "route": {
+      "type": "object",
+      "required": ["match", "template"],
+      "additionalProperties": false,
+      "properties": {
+        "match": { "type": "string" },
+        "template": { "type": "string" },
+        "slots": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/slotRef" }
+        }
+      }
+    },
+    "routes": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/route" }
+    },
+    "navGroup": {
+      "type": "object",
+      "required": ["group"],
+      "additionalProperties": false,
+      "properties": {
+        "group": { "type": "string" },
+        "icon": { "type": "string" },
+        "prefix": { "type": "string" },
+        "pages": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "navTab": {
+      "type": "object",
+      "required": ["tab"],
+      "additionalProperties": false,
+      "properties": {
+        "tab": { "type": "string" },
+        "url": { "type": "string" },
+        "groups": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/navGroup" }
+        }
+      }
+    },
+    "navigation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tabs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/navTab" }
+        }
+      }
+    },
+    "navbar": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "primary": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": { "type": "string", "enum": ["button", "github"] },
+            "label": { "type": "string" },
+            "href": { "type": "string" }
+          }
+        },
+        "links": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["label", "href"],
+            "additionalProperties": false,
+            "properties": {
+              "label": { "type": "string" },
+              "href": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "footer": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "socials": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "links": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["header"],
+            "additionalProperties": false,
+            "properties": {
+              "header": { "type": "string" },
+              "items": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["label", "href"],
+                  "additionalProperties": false,
+                  "properties": {
+                    "label": { "type": "string" },
+                    "href": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "search": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "provider": {
+          "type": "string",
+          "enum": ["fusejs", "lunrjs", "pagefind"]
+        }
+      }
+    },
+    "dependencies": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "shadcn": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "contentSource": {
+      "type": "object",
+      "required": ["dir"],
+      "additionalProperties": false,
+      "properties": {
+        "dir": { "type": "string" },
+        "include": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "exclude": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "indexFiles": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "nav": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "type": "string", "enum": ["auto", "manual"] },
+            "sort": { "type": "string", "enum": ["filesystem", "alpha", "date"] },
+            "collapsible": { "type": "boolean" },
+            "maxDepth": { "type": "integer", "minimum": 1, "maximum": 10 }
+          },
+          "allOf": [
+            {
+              "if": {
+                "properties": { "mode": { "const": "manual" } },
+                "required": ["mode"]
+              },
+              "then": {
+                "description": "Manual sidebar mode requires navigation.tabs at spec level"
+              }
+            }
+          ]
+        }
+      }
+    },
+    "content": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "docs": { "$ref": "#/$defs/contentSource" },
+        "blog": { "$ref": "#/$defs/contentSource" }
+      }
+    },
+    "seo": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "titleTemplate": { "type": "string" },
+        "defaultImage": { "type": "string" },
+        "twitter": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "i18n": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "defaultLocale": { "type": "string" },
+        "locales": { "type": "array", "items": { "type": "string" } },
+        "rtlLocales": { "type": "array", "items": { "type": "string" } },
+        "fallbackLocale": { "type": "string" },
+        "translationsDir": { "type": "string" }
+      }
+    },
+    "a11y": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "skipToContent": { "type": "boolean" },
+        "focusVisible": { "type": "boolean" },
+        "reduceMotion": { "type": "boolean" },
+        "ariaLabels": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    }
+  }
+}

docs/protocols/adp/schema/component-catalog.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "component-catalog.schema.json",
+  "title": "ADP Component Catalog",
+  "description": "Allowlisted component types for ADP Application manifests",
+  "type": "object",
+  "required": ["name", "version", "components"],
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-adp-": {}
+  },
+  "properties": {
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "description": { "type": "string" },
+    "components": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/componentType" }
+    },
+    "layouts": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/layoutType" }
+    }
+  },
+  "$defs": {
+    "componentType": {
+      "type": "object",
+      "required": ["description", "props"],
+      "additionalProperties": false,
+      "properties": {
+        "description": { "type": "string" },
+        "props": { "type": "object" },
+        "aria": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "role": { "type": "string" },
+            "label": { "type": "string" }
+          }
+        },
+        "slots": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "deprecated": { "type": "boolean" },
+        "x-sunset": { "type": "string", "format": "date" }
+      }
+    },
+    "layoutType": {
+      "oneOf": [
+        {
+          "title": "Slot-based layout",
+          "type": "object",
+          "required": ["description", "slots"],
+          "additionalProperties": false,
+          "properties": {
+            "description": { "type": "string" },
+            "slots": {
+              "type": "array",
+              "items": { "type": "string" },
+              "minItems": 1
+            }
+          }
+        },
+        {
+          "title": "Zone-based layout",
+          "type": "object",
+          "required": ["description", "zones"],
+          "additionalProperties": false,
+          "properties": {
+            "description": { "type": "string" },
+            "zones": {
+              "type": "array",
+              "items": { "type": "string" },
+              "minItems": 1
+            }
+          }
+        }
+      ]
+    }
+  }
+}

docs/protocols/adp/schema/theme.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "theme.schema.json",
+  "title": "ADP Theme",
+  "description": "Theme configuration — preset shorthand or DTCG 2025.10 token reference",
+  "oneOf": [
+    {
+      "title": "Preset theme",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "preset": {
+          "type": "string",
+          "enum": [
+            "zinc", "slate", "stone", "gray", "neutral",
+            "red", "orange", "amber", "yellow", "lime", "green",
+            "emerald", "teal", "cyan", "sky", "blue", "indigo",
+            "violet", "purple", "fuchsia", "pink", "rose"
+          ]
+        },
+        "radius": {
+          "type": "string",
+          "enum": ["none", "sm", "md", "lg", "xl"],
+          "default": "md"
+        },
+        "darkMode": {
+          "type": "boolean",
+          "default": true
+        }
+      },
+      "required": ["preset"]
+    },
+    {
+      "title": "DTCG token reference",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tokens": {
+          "type": "string",
+          "description": "Path or URL to DTCG 2025.10 compliant tokens.json"
+        },
+        "darkMode": { "type": "boolean" }
+      },
+      "required": ["tokens"]
+    }
+  ]
+}

docs/protocols/adp/spec.md

@@ -0,0 +1,314 @@
+# Application Design Protocol (ADP) — Normative Specification
+
+**Version:** v1alpha1 (draft)  
+**Status:** Draft — not yet normative  
+**Date:** August 2026
+
+This document uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords: MUST, MUST NOT, SHOULD, MAY.
+
+---
+
+## 1. Scope
+
+ADP defines a declarative format for describing **application UI design**: site metadata, theming, navigation, reusable components, page templates, and URL routing. It does NOT define:
+
+- Server-side APIs or data models
+- Agent orchestration or workflow graphs
+- Infrastructure or deployment configuration
+- Executable code or templating logic in manifests
+
+Implementations MUST treat ADP manifests as **data**, not code.
+
+---
+
+## 2. Terminology
+
+| Term | Definition |
+|------|------------|
+| **Manifest** | A YAML or JSON document conforming to this spec |
+| **Application** | The root `kind: Application` manifest describing a complete UI |
+| **Component** | A named, reusable UI block with a `type` and `props` |
+| **Template** | A layout definition assigning components to slots or zones |
+| **Slot** | A named region within a layout (e.g. `header`, `main`) |
+| **Zone** | An ordered list of widgets in a slot (WordPress-style) |
+| **Route** | A URL pattern mapping to a template |
+| **Catalog** | Published JSON Schema defining allowed component types |
+| **Compiler** | Tool that validates and emits runtime JSON manifests |
+| **Renderer** | Runtime that consumes compiled manifests and renders UI |
+
+---
+
+## 3. Document envelope
+
+Every ADP manifest MUST include:
+
+```yaml
+schemaVersion: 1          # Integer; ADP envelope version
+apiVersion: adp.io/v1alpha1
+kind: Application         # Application | Theme | ComponentCatalog (future)
+
+metadata:
+  name: string            # Required; unique identifier
+  version: string         # SHOULD use SemVer
+  labels: object          # MAY contain key-value pairs
+  annotations: object     # MAY contain tooling metadata
+
+spec: object              # Required; kind-specific payload
+```
+
+### 3.1 Versioning policy
+
+- `schemaVersion` — integer bumped on breaking envelope changes
+- `apiVersion` — string group/version (e.g. `adp.io/v1alpha1`, `adp.io/v1`)
+- `metadata.version` — application SemVer (independent of protocol version)
+- Breaking changes MUST increment `apiVersion` (e.g. v1alpha1 → v1)
+- Deprecated fields MUST include `deprecated: true` and SHOULD include `x-sunset` date
+
+### 3.2 Authoring formats
+
+Manifests MAY be authored as YAML (`.application.yaml`) or JSON (`.application.json`). Semantics MUST be identical. Runtimes MUST NOT consume YAML directly; compilers MUST normalise to JSON before validation.
+
+---
+
+## 4. Application spec
+
+An `Application` spec MUST contain at minimum:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `site.title` | YES | Application display name |
+| `templates` | YES | At least one template |
+| `routes` | YES | At least one route |
+
+All other fields are OPTIONAL.
+
+### 4.1 Site (`spec.site`)
+
+```yaml
+site:
+  title: string           # Required
+  description: string     # Optional
+  ui: shadcn              # UI framework hint; default shadcn
+  routeBaseDocs: /docs    # Base path for documentation routes
+```
+
+### 4.2 Theme (`spec.theme`)
+
+Theme MAY use preset shorthand or reference a DTCG token file:
+
+```yaml
+theme:
+  preset: zinc            # Tailwind-style preset name
+  radius: md              # none | sm | md | lg | xl
+  darkMode: true
+  # OR
+  tokens: $yaml: ./theme.tokens.json   # DTCG 2025.10 file
+```
+
+### 4.3 Navigation
+
+ADP separates **top tab bar** from **sidebar source**:
+
+```yaml
+navigation:
+  tabs:                   # Top tab bar (Mintlify-style)
+    - tab: Documentation
+      groups:
+        - group: Getting Started
+          pages: [index, getting-started/installation]
+
+content:
+  docs:
+    dir: ./docs
+    nav:
+      mode: auto           # auto | manual — sidebar source
+      sort: filesystem
+      collapsible: true
+      maxDepth: 4
+```
+
+- **`navigation.tabs`** — top-level tab bar with grouped pages
+- **`content.docs.nav.mode: auto`** — sidebar generated from filesystem scan
+- **`content.docs.nav.mode: manual`** — sidebar driven by `navigation.tabs` groups
+- Renderers MUST honour `content.docs.nav.mode` when building sidebar (R29)
+
+### 4.4 Components (`spec.components`)
+
+```yaml
+components:
+  header_main:
+    type: Header          # MUST exist in component catalog
+    props:
+      logoText: PraisonAIUI
+```
+
+Rules:
+- Component IDs MUST be unique within the manifest
+- `type` MUST match an entry in the published component catalog
+- `props` MUST validate against the catalog JSON Schema for that type
+
+### 4.5 Templates (`spec.templates`)
+
+```yaml
+templates:
+  docs:
+    layout: ThreeColumnLayout
+    slots:
+      header: { ref: header_main }
+      left: { ref: sidebar_docs }
+      main: { type: DocContent }
+      right: null           # Explicitly hide slot
+
+  landing:
+    layout: FlexibleLayout
+    zones:
+      hero:
+        - type: HeroBanner
+          props: { title: "Welcome" }
+```
+
+Rules:
+- `layout` MUST be a known layout type in the catalog
+- Each slot value MUST be `{ ref: id }`, `{ type: ComponentType }`, or `null`
+- Zones MUST use zone names valid for `FlexibleLayout`
+- A template MUST declare either `slots` or `zones`, not both (R13)
+
+### 4.6 Routes (`spec.routes`)
+
+```yaml
+routes:
+  - match: /docs/changelog
+    template: changelog
+    slots:                  # Optional per-route slot overrides
+      right: null
+  - match: /docs/**
+    template: docs
+```
+
+Rules:
+- Routes MUST be ordered most-specific-first
+- `match` MUST be a glob pattern
+- `template` MUST reference a key in `spec.templates`
+- Renderers MUST resolve routes at runtime using compiled `route-manifest.json`
+
+### 4.7 Content (`spec.content`)
+
+```yaml
+content:
+  docs:
+    dir: ./docs
+    include: ["**/*.md", "**/*.mdx"]
+    exclude: []
+    nav:
+      mode: auto
+      sort: filesystem
+      collapsible: true
+      maxDepth: 4
+```
+
+---
+
+## 5. Component catalog
+
+Implementations MUST publish a `component-catalog.schema.json` (meta-schema) and a catalog instance such as [`catalogs/default.catalog.json`](./catalogs/default.catalog.json):
+
+```json
+{
+  "name": "adp-default-catalog",
+  "version": "1.0.0",
+  "components": {
+    "Header": {
+      "description": "Site header with logo and navigation",
+      "props": {
+        "type": "object",
+        "properties": { "logoText": { "type": "string" } },
+        "required": ["logoText"],
+        "additionalProperties": false
+      },
+      "aria": { "role": "banner" },
+      "slots": ["header"]
+    }
+  },
+  "layouts": {
+    "ThreeColumnLayout": {
+      "description": "Header + sidebar + main + TOC + footer",
+      "slots": ["header", "left", "main", "right", "footer"]
+    }
+  }
+}
+```
+
+Custom component types MUST be registered via plugin schema layers. Unknown types MUST cause validation failure in strict mode.
+
+---
+
+## 6. Compilation pipeline
+
+A conforming compiler MUST:
+
+1. Parse YAML or JSON manifest
+2. Normalise to JSON
+3. Validate against `application.schema.json` (JSON Schema 2020-12)
+4. Validate cross-reference rules (see [validation-rules.md](./validation-rules.md))
+5. Validate component props against catalog schema
+6. Emit runtime manifests:
+   - `ui-config.json` — site, components, templates, theme, navigation
+   - `route-manifest.json` — ordered routes with template refs
+   - `docs-nav.json` — filesystem-derived navigation (if mode auto)
+
+---
+
+## 7. File composition
+
+Manifests MAY include external files using Backstage-style placeholders:
+
+```yaml
+theme:
+  $yaml: ./theme.yaml
+
+navigation:
+  $yaml: ./navigation.yaml
+```
+
+Rules:
+- Paths MUST be relative to the containing manifest
+- Path traversal (`../../`) MUST be rejected
+- Supported placeholders: `$yaml:`, `$json:`, `$text:`
+
+---
+
+## 8. Extensions
+
+Vendor extensions MUST use the `x-adp-` prefix:
+
+```yaml
+spec:
+  site:
+    x-adp-customAnalytics: true
+```
+
+Implementations MUST preserve unknown `x-adp-*` fields. Non-prefixed unknown fields MUST be rejected in strict mode.
+
+---
+
+## 9. Conformance
+
+An implementation is **ADP-conformant** if and only if it:
+
+1. Accepts manifests with `apiVersion: adp.io/v1alpha1` and `kind: Application`
+2. Validates all MUST-level requirements in this spec and validation-rules.md
+3. Rejects manifests with unknown fields in strict mode
+4. Emits runtime JSON manifests from valid Application specs
+5. Resolves routes to templates at render time
+
+---
+
+## 10. Related documents
+
+- [Research report](../application-design-protocol-report.md)
+- [Implementation status](./implementation-status.md)
+- [PraisonAIUI mapping](./aiui-mapping.md)
+- [JSON Schema: application](./schema/application.schema.json)
+- [JSON Schema: component catalog](./schema/component-catalog.schema.json)
+- [JSON Schema: theme](./schema/theme.schema.json)
+- [Examples](./examples/)

docs/protocols/adp/validation-rules.md

@@ -0,0 +1,115 @@
+# ADP Validation Rules
+
+Cross-reference validation rules for Application Design Protocol manifests. These constraints cannot be expressed in JSON Schema alone and MUST be enforced by conforming compilers.
+
+Rules use RFC 2119 keywords: MUST, MUST NOT, SHOULD, MAY.
+
+Inspired by AWP validation rules R1–R32 pattern.
+
+---
+
+## Envelope rules
+
+| Rule | Level | Description |
+|------|-------|-------------|
+| **R1** | MUST | `schemaVersion` MUST equal `1` for `apiVersion: adp.io/v1alpha1` |
+| **R2** | MUST | `kind` MUST be `Application` for root manifests |
+| **R3** | MUST | `metadata.name` MUST be unique within a deployment scope |
+| **R4** | MUST NOT | Unknown top-level fields outside `x-adp-*` namespace in strict mode |
+
+## Component rules
+
+| Rule | Level | Description |
+|------|-------|-------------|
+| **R5** | MUST | Every `spec.components` entry MUST have a unique ID |
+| **R6** | MUST | Every component `type` MUST exist in the published component catalog |
+| **R7** | MUST | Component `props` MUST validate against catalog JSON Schema for that type |
+| **R8** | MUST NOT | A component ID be referenced by `ref:` unless it exists in `spec.components` |
+| **R9** | SHOULD | Unused components (defined but never referenced) SHOULD emit a warning |
+
+## Template rules
+
+| Rule | Level | Description |
+|------|-------|-------------|
+| **R10** | MUST | Every `spec.templates` entry MUST declare a valid `layout` from the catalog |
+| **R11** | MUST | Slot names in `templates.*.slots` MUST be valid for the declared layout |
+| **R12** | MUST | Zone names in `templates.*.zones` MUST be valid for `FlexibleLayout` |
+| **R13** | MUST | Each template MUST declare either `slots` or `zones`, not both |
+| **R14** | MUST | Inline slot `{ type: X }` types MUST exist in the component catalog |
+| **R15** | MUST | Slot `{ ref: id }` MUST resolve to a component in `spec.components` |
+
+## Route rules
+
+| Rule | Level | Description |
+|------|-------|-------------|
+| **R16** | MUST | Every route `template` MUST reference a key in `spec.templates` |
+| **R17** | MUST | Routes MUST be ordered most-specific-first (longer/more precise patterns before wildcards) |
+| **R18** | MUST | Route slot overrides MUST use valid slot names for the target template's layout |
+| **R19** | SHOULD | At least one route SHOULD match the site root or docs base path |
+
+## Content and navigation rules
+
+| Rule | Level | Description |
+|------|-------|-------------|
+| **R20** | MUST | If `content.docs.dir` is declared, the directory MUST exist at compile time |
+| **R21** | MUST | If `content.docs.nav.mode` is `manual`, `navigation.tabs` MUST be non-empty |
+| **R22** | SHOULD | If `content.docs.nav.mode` is `auto`, a content source MUST be declared |
+
+Navigation model:
+
+- **`navigation.tabs`** — top tab bar (Mintlify-style)
+- **`content.docs.nav.mode`** — sidebar source: `auto` (filesystem scan) or `manual` (use `navigation.tabs` groups)
+
+## File include rules
+
+| Rule | Level | Description |
+|------|-------|-------------|
+| **R23** | MUST NOT | `$yaml:`, `$json:`, or `$text:` paths traverse outside the project root |
+| **R24** | MUST | Included files MUST parse as valid YAML/JSON/text respectively |
+| **R25** | MUST NOT | Circular file includes (A includes B includes A) |
+
+## Theme rules
+
+| Rule | Level | Description |
+|------|-------|-------------|
+| **R26** | MUST | If `theme.tokens` is declared, the referenced file MUST exist and validate against DTCG 2025.10 |
+| **R27** | MUST NOT | Both `theme.preset` and `theme.tokens` be declared simultaneously |
+
+## Renderer conformance (target — not yet implemented in PraisonAIUI)
+
+These rules define the target behaviour for ADP-conformant renderers. See [implementation-status.md](./implementation-status.md).
+
+| Rule | Level | Description |
+|------|-------|-------------|
+| **R28** | MUST | Renderers MUST resolve the active template from `route-manifest.json` at runtime |
+| **R29** | MUST | Renderers MUST honour `content.docs.nav.mode` when building sidebar |
+| **R30** | MUST | Renderers MUST apply ARIA roles from catalog for each rendered component |
+
+---
+
+## Validation pipeline order
+
+```
+1. Parse YAML/JSON
+2. Resolve $yaml/$json/$text includes (R23–R25)
+3. JSON Schema validate (application.schema.json)
+4. Cross-ref rules R1–R27
+5. Component props validate against catalog (R6–R7)
+6. Emit runtime manifests
+7. Runtime conformance R28–R30 (renderer responsibility)
+```
+
+## Error format
+
+Validation failures MUST report:
+
+```json
+{
+  "rule": "R8",
+  "path": "spec.templates.docs.slots.header.ref",
+  "message": "Component ref 'missing_header' not found in spec.components",
+  "severity": "error"
+}
+```
+
+Warnings (R9) use `"severity": "warning"`.

docs/protocols/application-design-protocol-report.md

@@ -0,0 +1,427 @@
+# Application Design Protocol (ADP) — Research Report
+
+**Version:** 1.0 (draft)  
+**Date:** August 2026  
+**Scope:** UI, layout, navigation, theming — declarative application design from text manifests  
+**Status:** Research and recommendation; not yet a published standard
+
+---
+
+## 1. Executive summary
+
+There is no single existing standard for **designing full application UI from a declarative text file**. Instead, the problem is addressed in fragments:
+
+- **Docs-site generators** (Mintlify, PraisonAIUI, Hugo) declare navigation and layout in config files.
+- **Form libraries** (JSON Forms, RJSF) declare layout trees from JSON Schema.
+- **Agent UI protocols** (A2UI, AG-UI) declare streaming component surfaces for LLM-generated UI.
+- **Catalog standards** (OpenUI, Backstage) declare component metadata without runtime layout.
+- **Design token standards** (DTCG 2025.10) declare theming without structure.
+
+**Recommendation:** Define an **Application Design Protocol (ADP)** that synthesises proven patterns from 46 surveyed standards into a UI-only manifest format.
+
+PraisonAIUI already implements approximately 60% of this model. ADP formalises, extends, and publishes what exists today.
+
+---
+
+## 2. Problem statement
+
+### 2.1 What we need
+
+A protocol that lets a developer (or LLM) describe an application's visual design — pages, navigation, components, themes, routes — in **one or more text files**, without writing application code.
+
+### 2.2 What exists today (fragmented)
+
+| Need | Who solves it | Gap |
+|------|---------------|-----|
+| Docs site from config | Mintlify, PraisonAIUI, Docusaurus | No shared spec; Mintlify uses JSON, others use YAML or JS |
+| Component catalog | OpenUI, A2UI | No layout or routing |
+| Layout trees | JSON Forms uiSchema | Forms only, not app shells |
+| Theming | DTCG, Material 3 | Tokens only, no pages |
+| Agent-generated UI | A2UI | Runtime streaming, not human-authored static sites |
+| Software metadata | Backstage | Catalog entities, not UI composition |
+
+### 2.3 Design goals for ADP
+
+1. **Human-readable** — editable without IDE plugins
+2. **LLM-safe** — structural schema rejects unknown fields
+3. **Portable** — same manifest renders on any ADP-compliant runtime
+4. **Validatable** — fail fast at build time, not in the browser
+5. **Extensible** — plugins add catalog entries, not inline code
+6. **Accessible** — ARIA hints required in component catalog
+
+---
+
+## 3. Standards landscape — 46 protocols in 10 categories
+
+Each entry describes **how UI/layout/navigation is declared** — the primary comparison dimension.
+
+### Category A: Web platform baseline (5)
+
+| Standard | Format | How UI/layout/navigation is declared | Schema | Versioning |
+|----------|--------|--------------------------------------|--------|------------|
+| **HTML + CSS** | `.html` + `.css` | Semantic elements; CSS Flexbox/Grid; `<nav>` + links | Living spec grammar | Browser Baseline |
+| **Web Components + DSD** | HTML + JS | Custom element tree; slots; Declarative Shadow DOM | DOM IDL | Platform flags |
+| **WAI-ARIA + APG** | HTML attributes | Landmarks, widget roles, keyboard patterns | WAI-ARIA 1.2 | Rec track |
+| **DTCG Design Tokens** | JSON | Token groups: `$value`, `$type`, `{alias}` refs — **no layout** | DTCG 2025.10 | Date editions |
+| **OpenUI** | YAML/JSON | Component catalog: `components{id: props}` — **no layout tree** | Prop definitions | Per-library version |
+
+### Category B: Schema-driven forms and layout (3)
+
+| Standard | Format | How UI/layout/navigation is declared | Schema | Versioning |
+|----------|--------|--------------------------------------|--------|------------|
+| **JSON Forms** | JSON Schema + UI Schema | `VerticalLayout`, `Control`, `Categorization` with `scope` pointers | JSON Schema + uiSchema | Package SemVer |
+| **RJSF** | JSON Schema + uiSchema | Schema-tree mirroring; `ui:widget`, `ui:options` | React convention | Package SemVer |
+| **Google A2UI** | JSONL stream | Flat adjacency-list; `createSurface`; catalog-constrained types | JSON Schema catalog | v0.9.1 / v1.0 RC |
+
+### Category C: Docs-site generators (6)
+
+| Standard | Format | How UI/layout/navigation is declared | Schema | Versioning |
+|----------|--------|--------------------------------------|--------|------------|
+| **Mintlify** | JSON (`docs.json`) | `navigation.groups[].pages[]`; `$schema` URL; `$ref` splitting | Published JSON Schema URL | Platform |
+| **PraisonAIUI** | YAML | `components` → `templates{layout, slots, zones}` → `routes` | Pydantic (internal) | `schemaVersion: 1` |
+| **Docusaurus** | JS config | `themeConfig.navbar`, plugin sidebar config | TypeScript types | Package SemVer |
+| **Hugo** | TOML/YAML | `menu.main[]`, theme selection | Hugo schema | Release train |
+| **Jekyll** | YAML | Frontmatter per page; `_data/` nav | Conventions | SemVer |
+| **Gatsby** | JS/TS | `siteMetadata` + `plugins[]` | JS object | Major versions |
+
+### Category D: Native declarative UI — reference only (5)
+
+| Standard | Format | Serialised wire format? | Navigation model |
+|----------|--------|-------------------------|------------------|
+| **Jetpack Compose** | Kotlin | No | `NavHost` + routes |
+| **SwiftUI** | Swift | No | `NavigationStack` |
+| **Flutter** | Dart | No | `Router` / `Navigator` |
+| **Qt QML** | `.qml` | Yes | `StackView`, bindings |
+| **XAML** | XML | Yes (dialect-fragmented) | `Frame`, `NavigationView` |
+
+### Category E: Design systems (2)
+
+| Standard | Format | Theming model |
+|----------|--------|---------------|
+| **Material Design 3** | DTCG JSON | reference → system → component token tiers |
+| **Bootstrap 5.3** | SCSS → CSS vars | Sass maps → `--bs-*` custom properties |
+
+### Category F: Design-to-code bridges — not source-of-truth (3)
+
+| Standard | Output | Why not ADP source |
+|----------|--------|-------------------|
+| **Figma MCP** | React+Tailwind context | Proprietary; bridge only |
+| **Webflow export** | HTML/CSS/JS ZIP | No schema; paid export |
+| **Framer export** | React bundles | Platform lock-in |
+
+### Category G: Component documentation (1)
+
+| Standard | Format | Navigation |
+|----------|--------|------------|
+| **Storybook CSF 3** | TS modules | Sidebar via `title` path hierarchy |
+
+### Category H: Configuration and packaging (12)
+
+| Standard | Format | Composition mechanism | ADP borrow |
+|----------|--------|----------------------|------------|
+| **Kubernetes CRD** | YAML | `apiVersion/kind/spec`; structural OpenAPI | Structural validation |
+| **Helm** | YAML + templates | Subcharts; values merge; `values.schema.json` | Defaults + overrides |
+| **Backstage catalog** | YAML | `$yaml:`/`$json:` includes; relation graph | Envelope + includes |
+| **OpenAPI 3.1** | YAML/JSON | `$ref`, `components` registry | JSON Schema foundation |
+| **AsyncAPI 3.x** | YAML/JSON | Channels → messages | Future event UI |
+| **JSON Schema 2020-12** | JSON | `$ref`, `$defs`, conditionals | Validation dialect |
+| **CloudEvents** | JSON envelope | Fixed envelope + opaque payload | Future event wrapper |
+| **Docker Compose** | YAML | Multi-file merge; profiles | Override stacking |
+| **CUE** | CUE | Unify schema + data | Power-user compile layer |
+| **Jsonnet** | Jsonnet → JSON | `import` + merge | Theme variants |
+| **Pkl** | `.pkl` | `amends`, mixins | Typed config model |
+| **OCI Artifact** | JSON manifest | Multi-layer blobs | Bundle packaging |
+
+### Category I: Agent and workflow protocols (7)
+
+| Standard | Format | UI/state declaration | ADP borrow |
+|----------|--------|---------------------|------------|
+| **MCP** | JSON-RPC | Tool schemas — no UI layout | Future widget actions |
+| **AG-UI** | Streaming JSON | EventType enum; snapshots + deltas | Streaming model |
+| **A2A** | Proto → JSON-RPC | Agent Cards | Transport |
+| **AWP** | Multi-file YAML | 7 layers; rules R1–R32 | Layer + validation model |
+| **LangGraph** | workflow.yaml | Graph nodes + edges | Layout graph |
+| **AutoGen** | ComponentModel JSON | `{provider, type, version, config}` | Pluggable components |
+| **CrewAI** | JSONC/YAML | Agent arrays — weak schema | Anti-pattern |
+
+### Category J: Application packaging (2)
+
+| Standard | Format | Application declaration |
+|----------|--------|------------------------|
+| **OAM** | YAML | `Application` with `components[]`, `traits[]` |
+| **CNAB** | bundle.json | Parameters, credentials, actions |
+
+---
+
+## 4. How they do it — mechanism comparison matrix
+
+| Mechanism | Standards | How it works | ADP |
+|-----------|-----------|--------------|-----|
+| **Envelope document** | K8s, Backstage, OAM, AWP | `apiVersion` + `kind` + `metadata` + `spec` | Adopt |
+| **Component registry + ref** | PraisonAIUI, OpenUI | Named map; templates use `ref:` | Adopt |
+| **Layout + slots** | PraisonAIUI, JSON Forms | Layout type + named regions | Adopt (unified) |
+| **Route → template** | PraisonAIUI, Flutter | URL glob → template | Adopt |
+| **Navigation tree** | Mintlify, Storybook | Hierarchical groups → pages | Adopt |
+| **Design token file** | DTCG, Material 3 | Token JSON with aliases | Adopt |
+| **Catalog allowlist** | A2UI, OpenUI | Closed component vocabulary | Adopt |
+| **Schema + uiSchema split** | JSON Forms, RJSF | Data vs presentation | Partial |
+| **Streaming surfaces** | A2UI, AG-UI | Incremental JSON updates | Future |
+| **Layered spec** | AWP, Helm | Separate files merged at compile | Adopt |
+| **File includes** | Backstage, Mintlify | `$yaml:` / `$ref` external files | Adopt |
+| **Structural pruning** | K8s CRD | Reject unknown fields | Adopt |
+| **Validation rules R1–Rn** | AWP | Cross-ref beyond JSON Schema | Adopt |
+| **JS executable config** | Docusaurus, Gatsby | Code config | Reject |
+| **Visual canvas** | Figma, Webflow | Proprietary designer | Reject |
+| **Code-only UI** | Compose, SwiftUI | No wire format | Out of scope |
+
+---
+
+## 5. Side-by-side: four closest analogues
+
+| Dimension | PraisonAIUI | Mintlify | A2UI | Backstage |
+|-----------|-------------|----------|------|-----------|
+| **Authoring format** | YAML | JSON | JSON (stream) | YAML |
+| **Envelope** | `schemaVersion` only | Flat JSON | Message `version` | `apiVersion/kind/metadata/spec` |
+| **Navigation** | `navigation.tabs[]` + filesystem | `navigation.groups[]` | N/A | N/A (metadata catalog) |
+| **Components** | `components{id: type, props}` | N/A | Catalog + adjacency list | Entity kinds |
+| **Layout** | `templates{layout, slots, zones}` | Theme only | Surfaces | N/A |
+| **Routes** | `routes{match, template}` | Page paths in nav | N/A | N/A |
+| **Schema published** | Pydantic only | `$schema` URL | JSON Schema catalog | JSON Schema per kind |
+| **Runtime** | React SPA | Hosted platform | Any renderer | Catalog API |
+| **Primary use** | Docs sites | Docs sites | Agent-generated UI | Software inventory |
+
+**Synthesis:** ADP combines PraisonAIUI's composition model, Mintlify's schema publishing, A2UI's catalog allowlist, and Backstage's envelope and file includes.
+
+---
+
+## 6. YAML vs alternatives — structured debate
+
+### 6.1 The assumption
+
+YAML is the best authoring format for application design manifests.
+
+### 6.2 Counter-evidence
+
+**Mintlify** — the closest commercial docs-site analogue — uses **JSON** (`docs.json`) with a published `$schema` URL for IDE autocomplete. This works well for flat-to-moderately-nested config but becomes verbose for deep layout trees.
+
+**A2UI** uses **JSON** as both authoring and wire format because LLMs emit structured JSON reliably and ambiguity is unacceptable at runtime.
+
+**Docusaurus and Gatsby** use **JavaScript/TypeScript** config for programmatic power — but this sacrifices portability and LLM generation safety.
+
+### 6.3 Format comparison
+
+| Format | Strengths | Weaknesses for ADP |
+|--------|-----------|-------------------|
+| **YAML** | Comments; readable nesting; LLM-friendly; PraisonAIUI continuity | Ambiguous typing; merge key footguns; no native DRY |
+| **JSON** | Unambiguous; `$schema` IDE support; Mintlify-proven | No comments; verbose for layout trees |
+| **TOML** | Clear flat tables (Hugo) | Poor for nested templates/zones |
+| **CUE / Jsonnet / Pkl** | Typed composition without templating | Learning curve; not LLM-default |
+| **HCL** | Modules, expressions | Ecosystem-bound; overkill for UI-only |
+| **JS/TS** | Full programmatic power | Not portable; not LLM-safe |
+
+### 6.4 Recommendation
+
+```
+Author (human/LLM) → YAML (default) or JSON (alternate)
+        ↓
+   ADP compiler/validator (JSON Schema 2020-12)
+        ↓
+   Normalised JSON manifest (runtime)
+        ↓
+   UI renderer (catalog-constrained)
+```
+
+- **Primary authoring:** YAML — best for nested `templates` / `zones` trees
+- **Alternate authoring:** JSON — for teams preferring Mintlify-style `$schema` tooling
+- **Never at runtime:** YAML — always compile to JSON before serve
+- **Composition:** `$yaml:` file includes (Backstage), not Helm Go templates
+- **Power users:** Optional CUE/Jsonnet compiles to YAML before validation
+
+**Verdict:** YAML remains the recommended default, but ADP MUST accept JSON as an equivalent authoring format with identical semantics.
+
+---
+
+## 7. ADP design principles
+
+1. **Declarative, not executable** — manifests describe intent; runtimes render; no inline code or templating logic in core spec.
+2. **Schema-first** — JSON Schema 2020-12 is canonical; YAML is authoring convenience.
+3. **Structural strictness** — unknown fields rejected in strict mode (K8s CRD pattern).
+4. **Catalog allowlist** — component `type` must exist in published catalog (A2UI pattern).
+5. **Envelope consistency** — every document uses `apiVersion`, `kind`, `metadata`, `spec`.
+6. **Separation of concerns** — theme, navigation, components, templates, routes are distinct spec sections.
+7. **Compile, don't interpret** — YAML → validated JSON manifest → static assets at build time.
+8. **Accessibility by default** — catalog entries include ARIA role hints (WAI-ARIA pattern).
+9. **Versioned protocol** — `schemaVersion` integer + `apiVersion` string; breaking changes bump version.
+10. **Extension namespace** — `x-adp-*` prefix reserved; plugins register catalog layers.
+11. **File composition** — `$yaml:` includes for modular configs (Backstage pattern).
+12. **Route-driven rendering** — URL resolution selects template; no hardcoded layout in renderer.
+
+---
+
+## 8. Proposed ADP document model
+
+```yaml
+schemaVersion: 1
+apiVersion: adp.io/v1alpha1
+kind: Application
+
+metadata:
+  name: my-docs-site
+  version: "1.0.0"
+  labels: {}
+
+spec:
+  site:
+    title: "My Site"
+    description: "..."
+  theme:
+    preset: zinc          # or DTCG token ref
+    radius: md
+    darkMode: true
+  navigation:
+    mode: auto            # auto | manual
+    tabs: [...]
+  components:
+    header_main:
+      type: Header
+      props: { logoText: "..." }
+  templates:
+    docs:
+      layout: ThreeColumnLayout
+      slots:
+        header: { ref: header_main }
+        main: { type: DocContent }
+  routes:
+    - match: "/docs/**"
+      template: docs
+  content:
+    docs:
+      dir: "./docs"
+```
+
+### Data flow
+
+```
+application.yaml → Parse → JSON Schema validate → Cross-ref rules (R1–R30)
+        → Compile → ui-config.json + route-manifest.json + docs-nav.json
+        → React / static renderer
+```
+
+---
+
+## 9. PraisonAIUI alignment and gaps
+
+### Already aligned
+
+| PraisonAIUI today | ADP equivalent |
+|-------------------|----------------|
+| `schemaVersion: 1` | `schemaVersion` + `apiVersion` |
+| `components` + `ref:` | `spec.components` + slot refs |
+| `templates.layout` + `slots` | `spec.templates` |
+| `routes` | `spec.routes` |
+| `site.theme` | `spec.theme` |
+| Compiler → JSON manifests | ADP compile pipeline |
+| Pydantic validation | JSON Schema + cross-ref rules |
+
+### Gaps to close
+
+| Gap | ADP fix |
+|-----|---------|
+| No published JSON Schema | Publish `application.schema.json` |
+| `navigation.tabs` compiled but not rendered | Mandate runtime consumption in spec |
+| `route-manifest.json` not used for routing | Mandate route-driven template resolution |
+| Dual slots + zones models | Unified: zones = ordered slot arrays |
+| Closed hardcoded component types | Published `component-catalog.schema.json` |
+| No envelope (`kind`, `metadata`) | Add Backstage-style envelope |
+
+---
+
+## 10. Migration path
+
+Existing `aiui.template.yaml` files remain valid. Migration steps:
+
+1. Add `apiVersion: adp.io/v1alpha1` and `kind: Application` (optional during transition).
+2. Wrap top-level keys under `spec:` (compiler accepts both shapes during v1alpha1).
+3. Rename `site` fields unchanged; map `navigation`, `templates`, `routes` as-is.
+4. Publish catalog; register custom component types via plugin schema layers.
+
+See [adp/aiui-mapping.md](./adp/aiui-mapping.md) for field-by-field mapping.
+
+---
+
+## 11. Open questions
+
+1. **Should ADP standardise layout type names** (`ThreeColumnLayout`) or allow runtime-defined layouts?
+2. **Should navigation support both filesystem-auto and manual tabs** in one spec, or require a mode switch?
+3. **Should agent-driven surfaces (A2UI) be a separate `kind: Surface`** or embedded in Application?
+4. **Should theme reference DTCG token files directly** or use simplified preset shorthand?
+
+---
+
+## 12. Appendix A — Standards index
+
+| # | Standard | URL |
+|---|----------|-----|
+| 1 | A2UI | https://a2ui.org/ |
+| 2 | AG-UI | https://docs.ag-ui.com/ |
+| 3 | AWP | https://github.com/veegee82/agent-workflow-protocol |
+| 4 | AsyncAPI | https://www.asyncapi.com/ |
+| 5 | Backstage catalog | https://backstage.io/docs/features/software-catalog/descriptor-format |
+| 6 | Bootstrap | https://getbootstrap.com/ |
+| 7 | CloudEvents | https://cloudevents.io/ |
+| 8 | CNAB | https://cnab.io/ |
+| 9 | CrewAI | https://docs.crewai.com/ |
+| 10 | CUE | https://cuelang.org/ |
+| 11 | Docusaurus | https://docusaurus.io/ |
+| 12 | DTCG Design Tokens | https://www.designtokens.org/ |
+| 13 | Figma Code Connect | https://developers.figma.com/docs/code-connect/ |
+| 14 | Framer | https://www.framer.com/ |
+| 15 | Gatsby | https://www.gatsbyjs.com/ |
+| 16 | Helm | https://helm.sh/ |
+| 17 | Hugo | https://gohugo.io/ |
+| 18 | Jekyll | https://jekyllrb.com/ |
+| 19 | JSON Forms | https://jsonforms.io/ |
+| 20 | JSON Schema | https://json-schema.org/ |
+| 21 | Kubernetes CRD | https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ |
+| 22 | LangGraph | https://langchain-ai.github.io/langgraph/ |
+| 23 | Material Design 3 | https://m3.material.io/ |
+| 24 | MCP | https://modelcontextprotocol.io/ |
+| 25 | Mintlify | https://mintlify.com/docs |
+| 26 | OAM | https://oam.dev/ |
+| 27 | OCI Artifact | https://opencontainers.org/ |
+| 28 | OpenAPI | https://www.openapis.org/ |
+| 29 | OpenUI | https://openuispec.org/ |
+| 30 | Pkl | https://pkl-lang.org/ |
+| 31 | PraisonAIUI | https://github.com/MervinPraison/PraisonAIUI |
+| 32 | RJSF | https://rjsf-team.github.io/react-jsonschema-form/ |
+| 33 | Storybook CSF | https://storybook.js.org/docs/api/csf |
+| 34 | W3C ARIA APG | https://www.w3.org/WAI/ARIA/apg/ |
+| 35 | Web Components | https://web.dev/articles/declarative-shadow-dom |
+| 36 | Webflow | https://webflow.com/ |
+| 37 | AutoGen | https://microsoft.github.io/autogen/ |
+| 38 | A2A | https://google.github.io/A2A/ |
+| 39 | Jsonnet | https://jsonnet.org/ |
+| 40 | Docker Compose | https://docs.docker.com/compose/ |
+| 41 | Qt QML | https://doc.qt.io/qt-6/qmlapplications.html |
+| 42 | XAML | https://learn.microsoft.com/en-us/windows/apps/develop/platform/xaml/xaml-overview |
+| 43 | Jetpack Compose | https://developer.android.com/develop/ui/compose |
+| 44 | SwiftUI | https://developer.apple.com/xcode/swiftui/ |
+| 45 | HTML + CSS | https://html.spec.whatwg.org/ |
+| 46 | Flutter | https://flutter.dev/ |
+
+---
+
+## 13. Conclusion
+
+ADP is feasible and largely prefigured by PraisonAIUI's existing architecture. The research across 46 standards yields a clear synthesis:
+
+- **Envelope** from Backstage/K8s
+- **Composition** from PraisonAIUI (components → templates → routes)
+- **Catalog** from A2UI/OpenUI
+- **Theming** from DTCG
+- **Validation** from AWP (structural schema + R-rules)
+- **Authoring** in YAML (default) with JSON alternate (Mintlify pattern)
+
+**Status:** Research draft — see [adp/implementation-status.md](./adp/implementation-status.md) for implementation gaps.
+
+The draft spec, JSON Schema files, and example manifests are published alongside this report in [`docs/protocols/adp/`](./adp/).

examples/python/10-feature-showcase/app.py

@@ -25,6 +25,7 @@ from praisonaiui.server import create_app
 
 # Use shared seed data helper
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from _shared.console import safe_print as print
 from _shared.seed_data import seed_demo_data
 
 seed_demo_data()

examples/python/11-ui-integration/app.py

@@ -20,6 +20,7 @@ import sys
 
 # Use shared seed data helper
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from _shared.console import safe_print as print
 from _shared.seed_data import seed_demo_data
 
 

examples/python/13-real-dashboard/app.py

@@ -26,6 +26,7 @@ import time
 import praisonaiui as aiui
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '_shared'))
+from console import safe_print as print
 from stream_bridge import StreamBridge
 
 try:

examples/python/14-all-features/app.py

@@ -4,9 +4,15 @@ Demonstrates ALL 16 PraisonAIUI features with real API calls.
 Run: aiui run app.py
 """
 
+import os
+import sys
+
 from starlette.testclient import TestClient
 from praisonaiui.server import create_app
 
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from _shared.console import safe_print as print
+
 
 def test_all_features():
     """Test all 16 feature APIs with real data."""

examples/python/16-gateway-integration/app.py

@@ -44,15 +44,18 @@ import sys
 # ── Import praisonaiui ──────────────────────────────────────
 import praisonaiui as aiui
 
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from _shared.console import icon, safe_print
+
 # ── Check gateway availability ──────────────────────────────
 try:
     from praisonaiui.integration import AIUIGateway
     from praisonaiagents import Agent
     GATEWAY_OK = True
 except ImportError as e:
-    print(f"⚠️  Gateway dependencies missing: {e}")
-    print("   Install with: pip install praisonai praisonaiagents")
-    print("   Falling back to standalone mode.")
+    safe_print(f"{icon('⚠️', '[WARN]')}  Gateway dependencies missing: {e}")
+    safe_print("   Install with: pip install praisonai praisonaiagents")
+    safe_print("   Falling back to standalone mode.")
     GATEWAY_OK = False
 
 # ── Set dashboard style ─────────────────────────────────────
@@ -149,15 +152,15 @@ def _register_agents_in_dashboard():
             "model": agent_def["model"],
             "icon": agent_def["icon"],
         })
-        print(f"   ✓ Dashboard: {agent_def['icon']} {agent_def['name']}")
+        safe_print(f"   {icon('✓', '[OK]')} Dashboard: {agent_def['name']}")
 
 
 # ── Main ────────────────────────────────────────────────────
 async def main():
     host = os.getenv("HOST", "127.0.0.1")
     if GATEWAY_OK:
-        print("🚀 Starting with Gateway mode (full execution + streaming)")
-        print()
+        safe_print(f"{icon('🚀', '[START]')} Starting with Gateway mode (full execution + streaming)")
+        safe_print()
 
         # Create the gateway
         gateway = AIUIGateway(
@@ -174,22 +177,22 @@ async def main():
                 self_reflect=False,
             )
             gateway.register_agent(agent, agent_id=agent_def["agent_id"])
-            print(f"   ✓ Gateway:   {agent_def['icon']} {agent_def['name']} ({agent_def['model']})")
+            safe_print(f"   {icon('✓', '[OK]')} Gateway:   {agent_def['name']} ({agent_def['model']})")
 
         # ── Register agents in dashboard CRUD storage ───────
         _register_agents_in_dashboard()
 
-        print()
-        print(f"   Dashboard:  http://localhost:8083")
-        print(f"   WebSocket:  ws://localhost:8083/ws")
-        print(f"   Inspector:  http://localhost:8083 → 🔍 Feature Inspector")
-        print()
+        safe_print()
+        safe_print("   Dashboard:  http://localhost:8083")
+        safe_print("   WebSocket:  ws://localhost:8083/ws")
+        safe_print(f"   Inspector:  http://localhost:8083 {icon('→', '->')} {icon('🔍', '')} Feature Inspector")
+        safe_print()
 
         # Start the gateway — this runs the full server
         await gateway.start()
     else:
         # Fallback to standalone mode (same as example 15)
-        print("📦 Starting in standalone mode (CRUD only, no agent execution)")
+        safe_print(f"{icon('📦', '[INFO]')} Starting in standalone mode (CRUD only, no agent execution)")
         from praisonaiui.server import create_app
         import uvicorn
 

examples/python/17-three-column-demo/app.py

@@ -26,15 +26,18 @@ import sys
 
 import praisonaiui as aiui
 
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from _shared.console import icon, safe_print
+
 # ── Check gateway availability ──────────────────────────────
 try:
     from praisonaiui.integration import AIUIGateway
     from praisonaiagents import Agent
     GATEWAY_OK = True
 except ImportError as e:
-    print(f"⚠️  Gateway dependencies not found: {e}")
-    print("   Install with: pip install praisonai praisonaiagents")
-    print("   Falling back to standalone mode (REST APIs only).\n")
+    safe_print(f"{icon('⚠️', '[WARN]')}  Gateway dependencies not found: {e}")
+    safe_print("   Install with: pip install praisonai praisonaiagents")
+    safe_print("   Falling back to standalone mode (REST APIs only).\n")
     GATEWAY_OK = False
 
 aiui.set_style("dashboard")
@@ -115,7 +118,7 @@ def _register_agents_in_dashboard():
             "model": agent_def["model"],
             "icon": agent_def["icon"],
         })
-        print(f"   ✓ Agent: {agent_def['icon']} {agent_def['name']}")
+        safe_print(f"   {icon('✓', '[OK]')} Agent: {agent_def['name']}")
 
 
 # ── Main ────────────────────────────────────────────────────
@@ -125,8 +128,8 @@ async def main():
     host = os.getenv("HOST", "127.0.0.1")
 
     if GATEWAY_OK:
-        print("🚀 Starting with Gateway mode (full execution + streaming)")
-        print()
+        safe_print(f"{icon('🚀', '[START]')} Starting with Gateway mode (full execution + streaming)")
+        safe_print()
 
         gateway = AIUIGateway(host=host, port=port)
 
@@ -139,32 +142,32 @@ async def main():
                 reflection=False,
             )
             gateway.register_agent(agent, agent_id=agent_def["agent_id"])
-            print(f"   ✓ Gateway:  {agent_def['icon']} {agent_def['name']} ({agent_def['model']})")
+            safe_print(f"   {icon('✓', '[OK]')} Gateway:  {agent_def['name']} ({agent_def['model']})")
 
         # Also register in dashboard CRUD
         _register_agents_in_dashboard()
 
-        print()
-        print(f"   Dashboard:  http://localhost:{port}")
-        print(f"   Explorer:   http://localhost:{port} → 🔬 Feature Explorer")
-        print(f"   WebSocket:  ws://localhost:{port}/ws")
-        print()
+        safe_print()
+        safe_print(f"   Dashboard:  http://localhost:{port}")
+        safe_print(f"   Explorer:   http://localhost:{port} {icon('→', '->')} {icon('🔬', '')} Feature Explorer")
+        safe_print(f"   WebSocket:  ws://localhost:{port}/ws")
+        safe_print()
 
         await gateway.start()
     else:
         # Standalone: REST APIs only, no agent execution
-        print("📦 Starting in standalone mode (REST APIs only, no agent execution)")
+        safe_print(f"{icon('📦', '[INFO]')} Starting in standalone mode (REST APIs only, no agent execution)")
         from praisonaiui.server import create_app
         import uvicorn
 
         _register_agents_in_dashboard()
 
         app = create_app()
-        print()
-        print(f"   Dashboard:  http://localhost:{port}")
-        print(f"   Explorer:   http://localhost:{port} → 🔬 Feature Explorer")
-        print(f"   Note:       POST endpoints may fail without gateway")
-        print()
+        safe_print()
+        safe_print(f"   Dashboard:  http://localhost:{port}")
+        safe_print(f"   Explorer:   http://localhost:{port} {icon('→', '->')} {icon('🔬', '')} Feature Explorer")
+        safe_print("   Note:       POST endpoints may fail without gateway")
+        safe_print()
 
         config = uvicorn.Config(app, host=host, port=port, log_level="info")
         server = uvicorn.Server(config)

examples/python/18-full-chat/app.py

@@ -25,9 +25,13 @@ Usage:
 
 import asyncio
 import os
+import sys
 
 import praisonaiui as aiui
 
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from _shared.console import icon, safe_print
+
 # ── Check gateway availability ──────────────────────────────
 try:
     from praisonaiagents import Agent
@@ -35,9 +39,9 @@ try:
     from praisonaiui.integration import AIUIGateway
     GATEWAY_OK = True
 except ImportError as e:
-    print(f"⚠️  Gateway dependencies not found: {e}")
-    print("   Install with: pip install praisonai praisonaiagents")
-    print("   Falling back to standalone mode (REST APIs only).\n")
+    safe_print(f"{icon('⚠️', '[WARN]')}  Gateway dependencies not found: {e}")
+    safe_print("   Install with: pip install praisonai praisonaiagents")
+    safe_print("   Falling back to standalone mode (REST APIs only).\n")
     GATEWAY_OK = False
 
 aiui.set_style("dashboard")
@@ -127,7 +131,7 @@ def _register_agents_in_dashboard():
             "model": agent_def["model"],
             "icon": agent_def["icon"],
         })
-        print(f"   ✓ Agent: {agent_def['icon']} {agent_def['name']}")
+        safe_print(f"   {icon('✓', '[OK]')} Agent: {agent_def['name']}")
 
 
 # ── Main ────────────────────────────────────────────────────
@@ -137,8 +141,8 @@ async def main():
     host = os.getenv("HOST", "127.0.0.1")
 
     if GATEWAY_OK:
-        print("🚀 Starting with Gateway mode (full execution + streaming)")
-        print()
+        safe_print(f"{icon('🚀', '[START]')} Starting with Gateway mode (full execution + streaming)")
+        safe_print()
 
         gateway = AIUIGateway(host=host, port=port)
 
@@ -151,21 +155,21 @@ async def main():
                 reflection=False,
             )
             gateway.register_agent(agent, agent_id=agent_def["agent_id"])
-            print(f"   ✓ Gateway:  {agent_def['icon']} {agent_def['name']} ({agent_def['model']})")
+            safe_print(f"   {icon('✓', '[OK]')} Gateway:  {agent_def['name']} ({agent_def['model']})")
 
         # Also register in dashboard CRUD
         _register_agents_in_dashboard()
 
-        print()
-        print(f"   Dashboard:  http://localhost:{port}")
-        print(f"   Explorer:   http://localhost:{port} → 🔬 Feature Explorer")
-        print(f"   WebSocket:  ws://localhost:{port}/ws")
-        print()
+        safe_print()
+        safe_print(f"   Dashboard:  http://localhost:{port}")
+        safe_print(f"   Explorer:   http://localhost:{port} {icon('→', '->')} {icon('🔬', '')} Feature Explorer")
+        safe_print(f"   WebSocket:  ws://localhost:{port}/ws")
+        safe_print()
 
         await gateway.start()
     else:
         # Standalone: REST APIs only, no agent execution
-        print("📦 Starting in standalone mode (REST APIs only, no agent execution)")
+        safe_print(f"{icon('📦', '[INFO]')} Starting in standalone mode (REST APIs only, no agent execution)")
         import uvicorn
 
         from praisonaiui.server import create_app
@@ -173,11 +177,11 @@ async def main():
         _register_agents_in_dashboard()
 
         app = create_app()
-        print()
-        print(f"   Dashboard:  http://localhost:{port}")
-        print(f"   Explorer:   http://localhost:{port} → 🔬 Feature Explorer")
-        print("   Note:       POST endpoints may fail without gateway")
-        print()
+        safe_print()
+        safe_print(f"   Dashboard:  http://localhost:{port}")
+        safe_print(f"   Explorer:   http://localhost:{port} {icon('→', '->')} {icon('🔬', '')} Feature Explorer")
+        safe_print("   Note:       POST endpoints may fail without gateway")
+        safe_print()
 
         config = uvicorn.Config(app, host=host, port=port, log_level="info")
         server = uvicorn.Server(config)

examples/python/20-email-bot/app.py

@@ -32,6 +32,9 @@ import asyncio
 import os
 import sys
 
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from _shared.console import icon, safe_print
+
 # ── Check prerequisites ─────────────────────────────────────────────
 
 try:
@@ -40,8 +43,8 @@ try:
     SDK_OK = True
 except ImportError:
     SDK_OK = False
-    print("⚠️  Missing dependencies. Install with:")
-    print("   pip install praisonai[email] praisonaiagents")
+    safe_print(f"{icon('⚠️', '[WARN]')}  Missing dependencies. Install with:")
+    safe_print("   pip install praisonai[email] praisonaiagents")
     sys.exit(1)
 
 
@@ -68,8 +71,8 @@ agent = Agent(
 async def run_simple():
     """Start email bot with automatic env var resolution."""
     bot = Bot("email", agent=agent)
-    print(f"📧 Starting email bot for: {os.getenv('EMAIL_ADDRESS', '(not set)')}")
-    print("   Listening for new emails... (Ctrl+C to stop)")
+    safe_print(f"{icon('📧', '[EMAIL]')} Starting email bot for: {os.getenv('EMAIL_ADDRESS', '(not set)')}")
+    safe_print("   Listening for new emails... (Ctrl+C to stop)")
     await bot.start()
 
 
@@ -96,9 +99,9 @@ async def run_with_handlers():
     @bot.on_message
     async def log_email(message):
         subject = message.metadata.get("subject", "(no subject)")
-        print(f"📨 From: {message.sender.username}")
-        print(f"   Subject: {subject}")
-        print(f"   Preview: {message.text[:100]}...")
+        safe_print(f"{icon('📨', '[MSG]')} From: {message.sender.username}")
+        safe_print(f"   Subject: {subject}")
+        safe_print(f"   Preview: {message.text[:100]}...")
 
     # Custom command: emails with subject starting with "/status"
     @bot.on_command("status")
@@ -118,11 +121,11 @@ async def run_with_handlers():
             reply_to=message.message_id,
         )
 
-    print(f"📧 Starting email bot with custom handlers")
-    print(f"   Email: {bot._email_address}")
-    print(f"   Poll interval: {config.polling_interval}s")
-    print(f"   Allowed senders: {'all' if not config.allowed_users else config.allowed_users}")
-    print("   Listening... (Ctrl+C to stop)")
+    safe_print(f"{icon('📧', '[EMAIL]')} Starting email bot with custom handlers")
+    safe_print(f"   Email: {bot._email_address}")
+    safe_print(f"   Poll interval: {config.polling_interval}s")
+    safe_print(f"   Allowed senders: {'all' if not config.allowed_users else config.allowed_users}")
+    safe_print("   Listening... (Ctrl+C to stop)")
     await bot.start()
 
 
@@ -131,17 +134,17 @@ async def run_with_handlers():
 async def run_probe():
     """Test email server connectivity."""
     bot = Bot("email", agent=agent)
-    print("🔍 Testing email server connectivity...")
+    safe_print(f"{icon('🔍', '[PROBE]')} Testing email server connectivity...")
     result = await bot.probe()
 
-    print(f"\n   Connection: {'✅ OK' if result.ok else '❌ FAILED'}")
-    print(f"   Platform:   {result.platform}")
+    safe_print(f"\n   Connection: {icon('✅', '[OK]') + ' OK' if result.ok else icon('❌', '[FAIL]') + ' FAILED'}")
+    safe_print(f"   Platform:   {result.platform}")
     if result.bot_username:
-        print(f"   Email:      {result.bot_username}")
+        safe_print(f"   Email:      {result.bot_username}")
     if result.elapsed_ms:
-        print(f"   Latency:    {result.elapsed_ms:.0f}ms")
+        safe_print(f"   Latency:    {result.elapsed_ms:.0f}ms")
     if result.error:
-        print(f"   Error:      {result.error}")
+        safe_print(f"   Error:      {result.error}")
 
 
 # ── Main ────────────────────────────────────────────────────────────

examples/python/21-email-channel/app.py

@@ -42,7 +42,9 @@ import sys
 # ── Imports ─────────────────────────────────────────────────────────
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "..", "src"))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
+from _shared.console import icon, safe_print
 from praisonaiui.server import create_app
 import uvicorn
 
@@ -91,11 +93,11 @@ def seed_email_channel():
         })
         if r.status_code in (200, 201):
             channel_id = r.json().get("id", "unknown")
-            print(f"   ✅ Email channel registered: {channel_id}")
+            safe_print(f"   {icon('✅', '[OK]')} Email channel registered: {channel_id}")
         else:
-            print(f"   ⚠️  Channel registration: {r.status_code} — {r.json()}")
+            safe_print(f"   {icon('⚠️', '[WARN]')}  Channel registration: {r.status_code} - {r.json()}")
     else:
-        print("   ✓ Email channel already exists")
+        safe_print(f"   {icon('✓', '[OK]')} Email channel already exists")
 
     # Also seed other channels for comparison in dashboard
     for name, platform in [("Discord #general", "discord"), ("Telegram Support", "telegram")]:
@@ -106,7 +108,7 @@ def seed_email_channel():
                 "platform": platform,
                 "config": {},
             })
-            print(f"   ✓ Seeded {platform} channel")
+            safe_print(f"   {icon('✓', '[OK]')} Seeded {platform} channel")
 
 
 # ── Verify email platform support ──────────────────────────────────
@@ -122,8 +124,8 @@ def verify_email_support():
     if r.status_code == 200:
         platforms = r.json().get("platforms", [])
         email_supported = "email" in platforms
-        print(f"   Supported platforms: {platforms}")
-        print(f"   Email supported: {'✅ Yes' if email_supported else '❌ No — add email to SUPPORTED_PLATFORMS'}")
+        safe_print(f"   Supported platforms: {platforms}")
+        safe_print(f"   Email supported: {icon('✅', '[OK]') + ' Yes' if email_supported else icon('❌', '[X]') + ' No - add email to SUPPORTED_PLATFORMS'}")
         return email_supported
     return False
 
@@ -137,51 +139,51 @@ def test_channel_api():
     app = create_app()
     client = TestClient(app)
 
-    print("\n📋 Channel API Test")
-    print("=" * 40)
+    safe_print(f"\n{icon('📋', '[TEST]')} Channel API Test")
+    safe_print("=" * 40)
 
     # List channels
     r = client.get("/api/channels")
     channels = r.json().get("channels", [])
-    print(f"   GET /api/channels: {len(channels)} channels")
+    safe_print(f"   GET /api/channels: {len(channels)} channels")
     for ch in channels:
-        icon = "📧" if ch.get("platform") == "email" else "💬"
-        print(f"      {icon} {ch.get('name', '?')} ({ch.get('platform', '?')})")
+        ch_icon = icon("📧", "[email]") if ch.get("platform") == "email" else icon("💬", "[chat]")
+        safe_print(f"      {ch_icon} {ch.get('name', '?')} ({ch.get('platform', '?')})")
 
     # Get email channel status
     email_ch = next((ch for ch in channels if ch.get("platform") == "email"), None)
     if email_ch:
         ch_id = email_ch.get("id")
         r = client.get(f"/api/channels/{ch_id}/status")
-        print(f"   GET /api/channels/{ch_id}/status: {r.json()}")
+        safe_print(f"   GET /api/channels/{ch_id}/status: {r.json()}")
 
-    print()
+    safe_print()
 
 
 # ── Main ────────────────────────────────────────────────────────────
 
 if __name__ == "__main__":
-    print("📧 PraisonAIUI — Email Channel Integration")
-    print("=" * 50)
-    print()
+    safe_print(f"{icon('📧', '[EMAIL]')} PraisonAIUI - Email Channel Integration")
+    safe_print("=" * 50)
+    safe_print()
 
     if "--test" in sys.argv:
         # Test mode: verify APIs + seed data
-        print("🔍 Verifying email platform support...")
+        safe_print(f"{icon('🔍', '[VERIFY]')} Verifying email platform support...")
         verify_email_support()
-        print()
-        print("🌱 Seeding email channel...")
+        safe_print()
+        safe_print(f"{icon('🌱', '[SEED]')} Seeding email channel...")
         seed_email_channel()
         test_channel_api()
     else:
         # Run the dashboard
-        print("🌱 Seeding channels...")
+        safe_print(f"{icon('🌱', '[SEED]')} Seeding channels...")
         seed_email_channel()
-        print()
+        safe_print()
 
         app = create_app()
-        print(f"✅ Dashboard at http://localhost:8084")
-        print(f"   Channels: http://localhost:8084/api/channels")
-        print(f"   Platforms: http://localhost:8084/api/channels/platforms")
+        safe_print(f"{icon('✅', '[OK]')} Dashboard at http://localhost:8084")
+        safe_print("   Channels: http://localhost:8084/api/channels")
+        safe_print("   Platforms: http://localhost:8084/api/channels/platforms")
         host = os.getenv("HOST", "127.0.0.1")
         uvicorn.run(app, host=host, port=8084, log_level="info")

examples/python/22-agentmail-bot/app.py

@@ -33,6 +33,9 @@ import asyncio
 import os
 import sys
 
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from _shared.console import icon, safe_print
+
 # ── Check prerequisites ─────────────────────────────────────────────
 
 try:
@@ -41,8 +44,8 @@ try:
     SDK_OK = True
 except ImportError:
     SDK_OK = False
-    print("⚠️  Missing dependencies. Install with:")
-    print("   pip install praisonai agentmail praisonaiagents")
+    safe_print(f"{icon('⚠️', '[WARN]')}  Missing dependencies. Install with:")
+    safe_print("   pip install praisonai agentmail praisonaiagents")
     sys.exit(1)
 
 
@@ -69,9 +72,9 @@ agent = Agent(
 async def run_simple():
     """Start agentmail bot with automatic env var resolution."""
     bot = Bot("agentmail", agent=agent)
-    print(f"📩 Starting AgentMail bot")
-    print(f"   API key: {'✅ set' if os.getenv('AGENTMAIL_API_KEY') else '❌ not set'}")
-    print("   Listening for new emails... (Ctrl+C to stop)")
+    safe_print(f"{icon('📩', '[MAIL]')} Starting AgentMail bot")
+    safe_print(f"   API key: {icon('✅', '[OK]') + ' set' if os.getenv('AGENTMAIL_API_KEY') else icon('❌', '[X]') + ' not set'}")
+    safe_print("   Listening for new emails... (Ctrl+C to stop)")
     await bot.start()
 
 
@@ -99,9 +102,9 @@ async def run_with_handlers():
     @bot.on_message
     async def log_email(message):
         subject = message.metadata.get("subject", "(no subject)")
-        print(f"📨 From: {message.sender.username}")
-        print(f"   Subject: {subject}")
-        print(f"   Preview: {message.text[:100]}...")
+        safe_print(f"{icon('📨', '[MSG]')} From: {message.sender.username}")
+        safe_print(f"   Subject: {subject}")
+        safe_print(f"   Preview: {message.text[:100]}...")
 
     # Custom command: emails with subject starting with "/status"
     @bot.on_command("status")
@@ -121,10 +124,10 @@ async def run_with_handlers():
             reply_to=message.message_id,
         )
 
-    print(f"📩 Starting AgentMail bot with custom handlers")
-    print(f"   Email: {bot.email_address or '(will be assigned on start)'}")
-    print(f"   Poll interval: {config.polling_interval}s")
-    print("   Listening... (Ctrl+C to stop)")
+    safe_print(f"{icon('📩', '[MAIL]')} Starting AgentMail bot with custom handlers")
+    safe_print(f"   Email: {bot.email_address or '(will be assigned on start)'}")
+    safe_print(f"   Poll interval: {config.polling_interval}s")
+    safe_print("   Listening... (Ctrl+C to stop)")
     await bot.start()
 
 
@@ -136,30 +139,30 @@ async def run_inbox_demo():
         token=os.environ.get("AGENTMAIL_API_KEY", ""),
     )
 
-    print("📩 AgentMail Inbox Lifecycle Demo")
-    print("=" * 50)
+    safe_print(f"{icon('📩', '[MAIL]')} AgentMail Inbox Lifecycle Demo")
+    safe_print("=" * 50)
 
     # Create inbox
-    print("\n1. Creating inbox...")
+    safe_print("\n1. Creating inbox...")
     inbox = await bot.create_inbox(domain=os.getenv("AGENTMAIL_DOMAIN"))
-    print(f"   ✅ Created: {inbox.get('email_address', 'unknown')}")
-    print(f"   ID: {inbox.get('id', 'unknown')}")
+    safe_print(f"   {icon('✅', '[OK]')} Created: {inbox.get('email_address', 'unknown')}")
+    safe_print(f"   ID: {inbox.get('id', 'unknown')}")
 
     # List inboxes
-    print("\n2. Listing inboxes...")
+    safe_print("\n2. Listing inboxes...")
     inboxes = await bot.list_inboxes()
-    print(f"   Found: {len(inboxes)} inbox(es)")
+    safe_print(f"   Found: {len(inboxes)} inbox(es)")
     for ib in inboxes:
-        print(f"      📧 {ib.get('email_address', '?')} (id: {ib.get('id', '?')})")
+        safe_print(f"      {icon('📧', '[EMAIL]')} {ib.get('email_address', '?')} (id: {ib.get('id', '?')})")
 
     # Delete inbox
     inbox_id = inbox.get("id", "")
     if inbox_id:
-        print(f"\n3. Deleting inbox {inbox_id}...")
+        safe_print(f"\n3. Deleting inbox {inbox_id}...")
         deleted = await bot.delete_inbox(inbox_id)
-        print(f"   {'✅ Deleted' if deleted else '❌ Failed to delete'}")
+        safe_print(f"   {icon('✅', '[OK]') + ' Deleted' if deleted else icon('❌', '[X]') + ' Failed to delete'}")
 
-    print("\n✅ Inbox lifecycle complete")
+    safe_print(f"\n{icon('✅', '[OK]')} Inbox lifecycle complete")
 
 
 # ── Probe: Test connectivity ────────────────────────────────────────
@@ -167,17 +170,17 @@ async def run_inbox_demo():
 async def run_probe():
     """Test AgentMail API connectivity."""
     bot = Bot("agentmail", agent=agent)
-    print("🔍 Testing AgentMail API connectivity...")
+    safe_print(f"{icon('🔍', '[PROBE]')} Testing AgentMail API connectivity...")
     result = await bot.probe()
 
-    print(f"\n   Connection: {'✅ OK' if result.ok else '❌ FAILED'}")
-    print(f"   Platform:   {result.platform}")
+    safe_print(f"\n   Connection: {icon('✅', '[OK]') + ' OK' if result.ok else icon('❌', '[FAIL]') + ' FAILED'}")
+    safe_print(f"   Platform:   {result.platform}")
     if result.bot_username:
-        print(f"   Email:      {result.bot_username}")
+        safe_print(f"   Email:      {result.bot_username}")
     if result.elapsed_ms:
-        print(f"   Latency:    {result.elapsed_ms:.0f}ms")
+        safe_print(f"   Latency:    {result.elapsed_ms:.0f}ms")
     if result.error:
-        print(f"   Error:      {result.error}")
+        safe_print(f"   Error:      {result.error}")
 
 
 # ── Main ────────────────────────────────────────────────────────────

examples/python/23-agentmail-channel/app.py

@@ -40,7 +40,9 @@ import sys
 # ── Imports ─────────────────────────────────────────────────────────
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "..", "src"))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
+from _shared.console import icon, safe_print
 from praisonaiui.server import create_app
 import uvicorn
 
@@ -88,11 +90,11 @@ def seed_agentmail_channel():
         })
         if r.status_code in (200, 201):
             channel_id = r.json().get("id", "unknown")
-            print(f"   ✅ AgentMail channel registered: {channel_id}")
+            safe_print(f"   {icon('✅', '[OK]')} AgentMail channel registered: {channel_id}")
         else:
-            print(f"   ⚠️  Channel registration: {r.status_code} — {r.json()}")
+            safe_print(f"   {icon('⚠️', '[WARN]')}  Channel registration: {r.status_code} - {r.json()}")
     else:
-        print("   ✓ AgentMail channel already exists")
+        safe_print(f"   {icon('✓', '[OK]')} AgentMail channel already exists")
 
     # Also seed email + telegram for comparison in dashboard
     for name, platform in [("Support Email", "email"), ("Telegram Support", "telegram")]:
@@ -103,7 +105,7 @@ def seed_agentmail_channel():
                 "platform": platform,
                 "config": {},
             })
-            print(f"   ✓ Seeded {platform} channel")
+            safe_print(f"   {icon('✓', '[OK]')} Seeded {platform} channel")
 
 
 # ── Verify agentmail platform support ──────────────────────────────
@@ -120,9 +122,9 @@ def verify_agentmail_support():
         platforms = r.json().get("platforms", [])
         am_supported = "agentmail" in platforms
         email_supported = "email" in platforms
-        print(f"   Supported platforms: {platforms}")
-        print(f"   email supported: {'✅ Yes' if email_supported else '❌ No'}")
-        print(f"   agentmail supported: {'✅ Yes' if am_supported else '❌ No'}")
+        safe_print(f"   Supported platforms: {platforms}")
+        safe_print(f"   email supported: {icon('✅', '[OK]') + ' Yes' if email_supported else icon('❌', '[X]') + ' No'}")
+        safe_print(f"   agentmail supported: {icon('✅', '[OK]') + ' Yes' if am_supported else icon('❌', '[X]') + ' No'}")
         return am_supported
     return False
 
@@ -136,51 +138,51 @@ def test_channel_api():
     app = create_app()
     client = TestClient(app)
 
-    print("\n📋 Channel API Test")
-    print("=" * 40)
+    safe_print(f"\n{icon('📋', '[TEST]')} Channel API Test")
+    safe_print("=" * 40)
 
     # List channels
     r = client.get("/api/channels")
     channels = r.json().get("channels", [])
-    print(f"   GET /api/channels: {len(channels)} channels")
+    safe_print(f"   GET /api/channels: {len(channels)} channels")
     for ch in channels:
-        icon = {"email": "📧", "agentmail": "📩"}.get(ch.get("platform", ""), "💬")
-        print(f"      {icon} {ch.get('name', '?')} ({ch.get('platform', '?')})")
+        ch_icon = {"email": icon("📧", "[email]"), "agentmail": icon("📩", "[mail]")}.get(ch.get("platform", ""), icon("💬", "[chat]"))
+        safe_print(f"      {ch_icon} {ch.get('name', '?')} ({ch.get('platform', '?')})")
 
     # Get agentmail channel status
     am_ch = next((ch for ch in channels if ch.get("platform") == "agentmail"), None)
     if am_ch:
         ch_id = am_ch.get("id")
         r = client.get(f"/api/channels/{ch_id}/status")
-        print(f"   GET /api/channels/{ch_id}/status: {r.json()}")
+        safe_print(f"   GET /api/channels/{ch_id}/status: {r.json()}")
 
-    print()
+    safe_print()
 
 
 # ── Main ────────────────────────────────────────────────────────────
 
 if __name__ == "__main__":
-    print("📩 PraisonAIUI — AgentMail Channel Integration")
-    print("=" * 50)
-    print()
+    safe_print(f"{icon('📩', '[MAIL]')} PraisonAIUI - AgentMail Channel Integration")
+    safe_print("=" * 50)
+    safe_print()
 
     if "--test" in sys.argv:
         # Test mode: verify APIs + seed data
-        print("🔍 Verifying agentmail platform support...")
+        safe_print(f"{icon('🔍', '[VERIFY]')} Verifying agentmail platform support...")
         verify_agentmail_support()
-        print()
-        print("🌱 Seeding agentmail channel...")
+        safe_print()
+        safe_print(f"{icon('🌱', '[SEED]')} Seeding agentmail channel...")
         seed_agentmail_channel()
         test_channel_api()
     else:
         # Run the dashboard
-        print("🌱 Seeding channels...")
+        safe_print(f"{icon('🌱', '[SEED]')} Seeding channels...")
         seed_agentmail_channel()
-        print()
+        safe_print()
 
         app = create_app()
-        print(f"✅ Dashboard at http://localhost:8084")
-        print(f"   Channels: http://localhost:8084/api/channels")
-        print(f"   Platforms: http://localhost:8084/api/channels/platforms")
+        safe_print(f"{icon('✅', '[OK]')} Dashboard at http://localhost:8084")
+        safe_print("   Channels: http://localhost:8084/api/channels")
+        safe_print("   Platforms: http://localhost:8084/api/channels/platforms")
         host = os.getenv("HOST", "127.0.0.1")
         uvicorn.run(app, host=host, port=8084, log_level="info")

examples/python/_shared/console.py

@@ -0,0 +1,40 @@
+"""Cross-platform console output for examples.
+
+Legacy Windows consoles default stdout to a non-UTF code page (cp1252/cp437)
+that cannot encode emoji such as U+1F680. Calling ``print`` with those
+characters raises ``UnicodeEncodeError`` and crashes the example before the
+server starts. These helpers mirror the ``_supports_unicode``/``_icon`` pattern
+in ``praisonaiui.cli`` so examples degrade to ASCII instead of crashing while
+preserving emoji on UTF-aware terminals.
+
+Usage:
+    from _shared.console import safe_print, icon
+
+    safe_print(f"{icon('🚀', '[START]')} Starting gateway...")
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+
+def supports_unicode() -> bool:
+    try:
+        encoding = sys.stdout.encoding or ""
+    except Exception:
+        return False
+    return "utf" in encoding.lower()
+
+
+def icon(symbol: str, fallback: str) -> str:
+    return symbol if supports_unicode() else fallback
+
+
+def safe_print(*args: Any, **kwargs: Any) -> None:
+    sep = kwargs.pop("sep", " ")
+    text = sep.join(str(a) for a in args)
+    try:
+        print(text, **kwargs)
+    except UnicodeEncodeError:
+        print(text.encode("ascii", errors="replace").decode("ascii"), **kwargs)

examples/python/meeting-agent/.env.example

@@ -0,0 +1,34 @@
+# Meeting Agent example — copy to .env and fill in. Never commit real secrets.
+
+# Used by the PraisonAI agent for summarization/embeddings.
+OPENAI_API_KEY=
+
+# Optional: enable Slack summary delivery via the built-in SlackChannelAdapter.
+SLACK_BOT_TOKEN=
+SLACK_APP_TOKEN=
+
+# Local dev server port for `python app.py`.
+MEETING_AGENT_PORT=8000
+
+# ── Recall.ai (EU workspace: Praison) ───────────────────────────────────────
+# Region must match dashboard: eu-central-1 (Frankfurt).
+RECALL_REGION=eu-central-1
+# Optional: your Recall workspace ID (shown in the config-status API only; the
+# API key already scopes requests to a workspace).
+RECALL_WORKSPACE_ID=
+
+# REST API key from Recall dashboard (Developers → API Keys). Server-side only.
+RECALL_API_KEY=
+
+# Workspace verification secret (whsec_…) from Recall MCP or dashboard.
+RECALL_WEBHOOK_VERIFICATION_SECRET=
+
+# Stable public HTTPS backend URL (reserved ngrok domain in dev). Required for
+# webhooks and Google Calendar V2 OAuth callback forwarding.
+PUBLIC_API_BASE_URL=
+
+# Bot display name in meetings.
+RECALL_BOT_NAME=Praison Meeting Agent
+
+# Calendar V2: when true (default), eligible future events with video links get bots.
+CALENDAR_AUTO_RECORD=true

examples/python/meeting-agent/README.md

@@ -0,0 +1,115 @@
+# Meeting Agent (Phase 1 upload + Phase 2 Recall.ai live bots)
+
+A PraisonAIUI example that wires the dashboard to **PraisonAI-Tools** meeting
+tools for upload → transcribe → summarize → index → search, plus **Recall.ai**
+Meeting Bots for live Zoom / Meet / Teams capture.
+
+## What this example includes
+
+| Page | Built from |
+|------|-----------|
+| Upload | `POST /api/meetings/upload` (audio → Phase 1 pipeline) |
+| Live bot | `POST /api/recall/bots` — send a Recall bot to a meeting URL |
+| Meetings | dashboard table backed by `list_meetings` |
+| Meeting detail | transcript / summary / action items + live status |
+| Calendar | Calendar V2 setup instructions + status API |
+| Chat | meeting agent with `search_meetings` + optional `schedule_recall_bot` tool |
+
+## Recall.ai workspace
+
+This integration targets your Recall workspace in **EU (Frankfurt)** by default:
+
+- Workspace ID: set `RECALL_WORKSPACE_ID` to your own (optional — the API key
+  already scopes requests to a workspace)
+- API region: `eu-central-1`
+
+Follow the [Recall onboarding guide](https://docs.recall.ai/docs/agent-quickstarts) via Recall MCP (`recall://guides/onboarding`) for credential and webhook setup.
+
+## Run
+
+```bash
+cp .env.example .env   # set OPENAI_API_KEY + Recall vars (server-side only)
+pip install praisonai-tools[meeting] httpx
+aiui run app.py
+# or
+python app.py          # honours MEETING_AGENT_PORT
+python app.py --smoke  # non-binding Recall boundary smoke
+```
+
+## Schedule a live bot
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/recall/bots \
+  -H "Content-Type: application/json" \
+  -d '{"meeting_url":"https://zoom.us/j/123456789","title":"Standup"}'
+```
+
+Flow: **Create Bot** → webhooks (`bot.*`, `recording.done`, `transcript.done`) →
+async Recall transcription → Phase 1 summarize + index → dashboard `ready`.
+
+## Webhooks (required)
+
+Set `PUBLIC_API_BASE_URL` to a stable **HTTPS** backend URL (reserved ngrok
+domain in dev — not localhost). Register in Recall:
+
+- URL: `{PUBLIC_API_BASE_URL}/webhooks/recall`
+- Events: `bot.joining_call`, `bot.in_call_recording`, `bot.done`, `bot.fatal`,
+  `recording.done`, `transcript.done`, `transcript.failed`, `transcript.data`
+- Calendar (Part B): `calendar.sync_events`, `calendar.update` on the same URL
+
+Use Recall MCP `create_webhook_endpoint` or the dashboard. Verify with
+`send_test_webhook_endpoint`.
+
+## Google Calendar V2
+
+Default **CALENDAR_AUTO_RECORD=true** schedules bots for eligible future events
+with video links once Calendar V2 is connected.
+
+1. Set `PUBLIC_API_BASE_URL` (HTTPS tunnel).
+2. Run Recall MCP `start_calendar_integration_setup` with
+   `production_redirect_uri={PUBLIC_API_BASE_URL}/api/recall/calendar/callback`.
+3. Bootstrap the app: `POST /api/recall/calendar/setup/bootstrap` with
+   `setup_id` and `regional_callback_uri` from MCP.
+4. Complete Google OAuth per `recall://guides/calendar-v2-setup-google`.
+
+**Recording opt-in:** calendar sync ≠ automatic recording for every meeting;
+this app uses `CALENDAR_AUTO_RECORD` (default on). Set `false` to disable
+auto-schedule while keeping calendar connected.
+
+## Environment
+
+See `.env.example`:
+
+| Variable | Purpose |
+|----------|---------|
+| `OPENAI_API_KEY` | Summaries, embeddings, chat |
+| `RECALL_REGION` | `eu-central-1` |
+| `RECALL_API_KEY` | Recall REST API (backend only) |
+| `RECALL_WEBHOOK_VERIFICATION_SECRET` | Webhook signature verification |
+| `PUBLIC_API_BASE_URL` | Public HTTPS origin for webhooks + calendar callback |
+| `CALENDAR_AUTO_RECORD` | Auto-schedule bots from calendar (default `true`) |
+
+Never commit real secrets. Reuse the existing REST key (`Mervin Praison`) when
+its purpose is clear; otherwise create a purpose-named key via Recall MCP.
+
+## Phase 2 Part B — live transcript + calendar auto-schedule
+
+| Feature | API |
+|---------|-----|
+| Live transcript (SSE) | `GET /api/meetings/{id}/live-transcript` (`Accept: text/event-stream`) |
+| Live transcript (poll) | Same URL, default JSON |
+| Upcoming calendar events | `GET /api/recall/calendar/upcoming?hours=24` |
+| Manual calendar sync | `POST /api/recall/calendar/sync` `{"calendar_id":"..."}` |
+| Agent tool | `get_upcoming_meetings(hours=24)` in chat when Recall is configured |
+
+Every new bot schedule **automatically** attaches `recording_config.realtime_endpoints`
+pointing at `{PUBLIC_API_BASE_URL}/webhooks/recall` with `transcript.data` — no Recall
+dashboard toggle for live transcript. Requires `PUBLIC_API_BASE_URL` in `.env`.
+
+## Tests
+
+From repo root:
+
+```bash
+pytest tests/unit/test_meeting_agent_example.py tests/unit/test_meeting_agent_pipeline.py tests/unit/test_meeting_agent_recall.py tests/unit/test_meeting_agent_part_b.py -v
+```

examples/python/meeting-agent/aiui.template.yaml

@@ -0,0 +1,46 @@
+# Meeting Agent — PraisonAIUI example config (PAI-MEET-UI, issue #260)
+# Composes existing features (attachments, knowledge, chat, Slack) via YAML.
+# Run with: aiui run app.py
+
+site:
+  title: Meeting Agent
+  description: Upload meetings, browse summaries and action items, ask questions.
+  logo: "🗓️"
+  theme:
+    preset: slate
+    darkMode: true
+    radius: md
+
+style: dashboard
+
+layout:
+  mode: dashboard
+
+dashboard:
+  sidebar: true
+  pageHeader: true
+
+pages:
+  - upload
+  - meetings
+  - meeting-detail
+  - chat
+
+chat:
+  enabled: true
+  name: Meeting Assistant
+  features:
+    streaming: true
+    reasoning: true
+    tools: true
+    fileUpload: true
+    feedback: true
+  input:
+    placeholder: "Ask about a past meeting..."
+  starters:
+    - label: "What did we decide about billing?"
+      message: "What did we decide about billing?"
+      icon: "🔎"
+    - label: "List open action items"
+      message: "List open action items and their owners"
+      icon: "✅"

examples/python/meeting-agent/app.py

@@ -0,0 +1,733 @@
+"""Meeting Agent — PraisonAIUI example with Phase 1 upload pipeline + Recall.ai live bots.
+
+Composes existing PraisonAIUI features plus PraisonAI-Tools meeting tools:
+
+  - Upload API          → POST /api/meetings/upload (transcribe → summarize → index)
+  - Live bot API        → POST /api/recall/bots (Recall Meeting Bot join)
+  - Recall webhooks     → POST /webhooks/recall (verified, async processing)
+  - Calendar callback   → GET /api/recall/calendar/callback (Calendar V2 OAuth)
+  - Meetings list       → dashboard page backed by ``list_meetings``
+  - Meeting detail      → latest stored meeting (transcript / summary / actions)
+  - Chat                → PraisonAI Agent with ``search_meetings`` + meeting tools
+  - Slack delivery      → optional via SlackChannelAdapter
+
+Run:
+    aiui run app.py
+    python app.py
+    python smoke_recall.py   # non-binding integration smoke
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import praisonaiui as aiui
+from praisonaiui.server import create_app
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+_EXAMPLE_DIR = Path(__file__).resolve().parent
+if str(_EXAMPLE_DIR) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLE_DIR))
+
+
+def _load_local_env() -> None:
+    """Load ``.env`` from the example dir when vars are not already set."""
+    env_path = _EXAMPLE_DIR / ".env"
+    if not env_path.is_file():
+        return
+    for raw in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip()
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+_load_local_env()
+
+aiui.set_custom_js(_EXAMPLE_DIR / "plugin.js")
+
+from pipeline import retry_pipeline, run_ingest_pipeline
+from recall_routes import (
+    api_meeting_live_transcript,
+    api_recall_bot_status,
+    api_recall_calendar_bootstrap,
+    api_recall_calendar_callback,
+    api_recall_calendar_status,
+    api_recall_calendar_sync,
+    api_recall_calendar_upcoming,
+    api_recall_cancel_bot,
+    api_recall_config_status,
+    api_recall_schedule_bot,
+    webhook_recall,
+)
+
+CHAT_SYSTEM_PROMPT = (
+    "You are a meeting assistant. For any question about past meetings, decisions, "
+    "owners, or action items you MUST call the search_meetings tool first and answer "
+    "only from the retrieved transcripts and summaries. Never answer historical "
+    "questions from memory. Cite every claim with a citation chip showing the meeting "
+    "title linked to its detail page."
+)
+
+# Fallback demo rows for Slack block-shape tests and offline dashboard preview.
+SAMPLE_MEETINGS: list[dict] = [
+    {
+        "id": "m-1001",
+        "title": "Q3 Planning Kickoff",
+        "date": "2026-07-01",
+        "status": "Ready",
+        "duration": "48m",
+        "transcript": "Alice: Let's align on Q3 goals...\nBob: Priorities are onboarding and billing.",
+        "summary": "Team aligned on Q3 priorities: onboarding revamp and billing reliability.",
+        "actions": [
+            {"task": "Draft onboarding spec", "owner": "Alice", "due": "2026-07-08"},
+            {"task": "Audit billing retries", "owner": "Bob", "due": "2026-07-10"},
+        ],
+    },
+]
+
+_agent: Any | None = None
+
+
+def _recall_schedule_tool():
+    from praisonai_tools.tools.decorator import tool
+
+    from meeting_integrations.recall.service import schedule_recall_bot as _schedule
+
+    @tool
+    def schedule_recall_bot(meeting_url: str, title: str = "") -> dict:
+        """Schedule a Recall.ai bot to join a meeting URL (Zoom, Meet, Teams)."""
+        return _schedule(meeting_url, title)
+
+    return schedule_recall_bot
+
+
+def _upcoming_meetings_tool():
+    from praisonai_tools.tools.decorator import tool
+
+    from meeting_integrations.recall.calendar_service import list_upcoming_calendar_meetings
+
+    @tool
+    def get_upcoming_meetings(hours: int = 24) -> list[dict]:
+        """List upcoming calendar events with video links and bot schedule status."""
+        return list_upcoming_calendar_meetings(hours=hours)
+
+    return get_upcoming_meetings
+
+
+def _load_meeting_tools():
+    """Lazy-load meeting tools (keeps import-time deps light)."""
+    from praisonai_tools.tools.meeting_tools import (
+        extract_action_items,
+        get_meeting,
+        index_meeting,
+        list_meetings,
+        save_meeting,
+        search_meetings,
+        summarize_transcript,
+        transcribe_file,
+    )
+
+    tools = [
+        transcribe_file,
+        save_meeting,
+        get_meeting,
+        list_meetings,
+        summarize_transcript,
+        extract_action_items,
+        index_meeting,
+        search_meetings,
+    ]
+    if os.getenv("RECALL_API_KEY"):
+        tools.append(_recall_schedule_tool())
+        tools.append(_upcoming_meetings_tool())
+    return tools
+
+
+def get_agent():
+    """Return the meeting agent (created lazily on first chat)."""
+    global _agent
+    if _agent is not None:
+        return _agent
+    try:
+        from praisonaiagents import Agent
+    except ImportError as exc:
+        raise ImportError(
+            "praisonaiagents required. Install with: pip install praisonai"
+        ) from exc
+
+    _agent = Agent(
+        name="Meeting Assistant",
+        instructions=CHAT_SYSTEM_PROMPT,
+        model="gpt-4o-mini",
+        tools=_load_meeting_tools(),
+    )
+    # Default loop guard kills chat after 120s while search_meetings runs.
+    from praisonaiagents.escalation.loop_guard import LoopGuard, LoopGuardConfig
+
+    max_turn_sec = float(os.getenv("MEETING_AGENT_LOOP_GUARD_MAX_SEC", "600"))
+    _agent._loop_guard = LoopGuard(
+        LoopGuardConfig(enabled=True, max_time_per_turn=max_turn_sec)
+    )
+    return _agent
+
+
+def _sync_stale_recall_status(record: dict[str, Any]) -> dict[str, Any]:
+    """Refresh Recall bot status for meetings still marked joining/scheduled."""
+    meta = record.get("metadata") or {}
+    live = (meta.get("live_status") or "").lower()
+    bot_id = meta.get("recall_bot_id")
+    if not bot_id or live in ("ready", "failed", "cancelled", "processing"):
+        return record
+    if live not in ("joining", "scheduled", "waiting_room", "live", "ended", ""):
+        return record
+    if not os.getenv("RECALL_API_KEY"):
+        return record
+    try:
+        from meeting_integrations.recall.client import RecallClient
+        from meeting_integrations.recall.config import load_recall_settings
+        from pipeline import merge_meeting_metadata
+
+        bot = RecallClient(load_recall_settings()).get_bot(str(bot_id))
+        changes = bot.get("status_changes") or []
+        status = (changes[-1].get("code") if changes else bot.get("status") or "").lower()
+        meeting_id = record.get("meeting_id", "")
+        patch: dict[str, Any] = {}
+        if status == "in_waiting_room":
+            patch = {
+                "live_status": "waiting_room",
+                "status": "Scheduled",
+                "error": (
+                    "Bot is in the Google Meet waiting room — admit "
+                    "'Praison Meeting Agent' to start recording."
+                ),
+            }
+        elif status in ("done", "call_ended") and not (bot.get("recordings") or []):
+            patch = {
+                "live_status": "failed",
+                "status": "failed",
+                "error": "Meeting ended but bot never recorded (likely not admitted from waiting room).",
+            }
+        elif status == "done" and (bot.get("recordings") or []):
+            patch = {"live_status": "processing"}
+        if patch and meeting_id:
+            merge_meeting_metadata(meeting_id, patch)
+            meta = {**meta, **patch}
+            record = {**record, "metadata": meta}
+    except Exception:
+        pass
+    return record
+
+
+def _record_to_view(record: dict[str, Any]) -> dict[str, Any]:
+    """Normalise a tool meeting record for dashboard rendering."""
+    meta = record.get("metadata") or {}
+    actions = meta.get("action_items") or []
+    return {
+        "id": record.get("meeting_id", ""),
+        "title": record.get("title", "Untitled"),
+        "date": (record.get("created_at") or "")[:10],
+        "status": meta.get("status", "Ready").replace("ready", "Ready").title(),
+        "live_status": meta.get("live_status") or "",
+        "recall_bot_id": meta.get("recall_bot_id") or "",
+        "meeting_url": meta.get("meeting_url") or record.get("source") or "",
+        "duration": _format_duration(meta.get("duration_seconds")),
+        "transcript": meta.get("transcript") or "",
+        "summary": meta.get("summary") or "",
+        "error": meta.get("error") or "",
+        "actions": [
+            {
+                "task": a.get("description", ""),
+                "owner": a.get("owner") or "—",
+                "due": a.get("due_date") or "—",
+            }
+            for a in actions
+            if isinstance(a, dict)
+        ],
+    }
+
+
+def _format_duration(seconds: Any) -> str:
+    if not seconds:
+        return "—"
+    try:
+        total = int(float(seconds))
+    except (TypeError, ValueError):
+        return "—"
+    minutes, secs = divmod(total, 60)
+    return f"{minutes}m {secs}s" if minutes else f"{secs}s"
+
+
+def _list_meeting_views() -> list[dict[str, Any]]:
+    try:
+        from praisonai_tools.tools.meeting_tools import list_meetings
+
+        rows = list_meetings.__wrapped__(limit=50, offset=0)
+        if rows and isinstance(rows[0], dict) and "error" in rows[0]:
+            return SAMPLE_MEETINGS
+        rows = [_sync_stale_recall_status(r) for r in rows]
+        views = [_record_to_view(r) for r in rows]
+        return views or SAMPLE_MEETINGS
+    except ImportError:
+        return SAMPLE_MEETINGS
+
+
+def _meeting(meeting_id: str) -> dict | None:
+    try:
+        from praisonai_tools.tools.meeting_tools import get_meeting
+
+        record = get_meeting.__wrapped__(meeting_id)
+        if "error" not in record:
+            return _record_to_view(record)
+    except ImportError:
+        pass
+    return next((m for m in SAMPLE_MEETINGS if m["id"] == meeting_id), None)
+
+
+def _pick_detail_meeting(meetings: list[dict[str, Any]]) -> dict[str, Any]:
+    """Prefer an in-progress live meeting for the detail view."""
+    for live in ("live", "joining", "waiting_room"):
+        for m in meetings:
+            if (m.get("live_status") or "").lower() == live:
+                return m
+    return meetings[0] if meetings else SAMPLE_MEETINGS[0]
+
+
+def _status_variant(status: str) -> str:
+    return {
+        "Ready": "default",
+        "Indexing": "secondary",
+        "Summarizing": "secondary",
+        "Transcribing": "secondary",
+        "Uploading": "secondary",
+        "Error": "destructive",
+        "Failed": "destructive",
+        "Scheduled": "secondary",
+        "Live": "default",
+        "Processing": "secondary",
+    }.get(status, "outline")
+
+
+aiui.set_style("dashboard")
+aiui.set_branding(title="Meeting Agent", logo="🗓️")
+aiui.set_pages(
+    ["upload", "live-bot", "meetings", "meeting-detail", "calendar", "chat"]
+)
+aiui.set_dashboard(sidebar=True, page_header=True)
+aiui.set_chat_features(file_upload=True, feedback=True)
+
+
+async def _emit_pipeline_chat_result(result: dict[str, Any]) -> None:
+    """Surface pipeline progress/errors via standard chat status events."""
+    if result.get("status") == "ready":
+        await aiui.say(
+            f"✅ **{result.get('title', 'Meeting')}** is ready. "
+            f"Indexed {result.get('chunks_indexed', 0)} chunk(s)."
+        )
+        return
+    if "error" in result:
+        await aiui.say(f"❌ {result['error']}")
+        meeting_id = result.get("meeting_id")
+        if meeting_id:
+            await aiui.action_buttons(
+                [
+                    {
+                        "name": "retry-meeting",
+                        "label": "Retry",
+                        "payload": {"meeting_id": meeting_id},
+                    }
+                ]
+            )
+        return
+    await aiui.say(str(result))
+
+
+async def _chat_run_pipeline(fn, *args: Any) -> None:
+    await aiui.think("Running meeting pipeline...")
+    result = await asyncio.to_thread(fn, *args)
+    await _emit_pipeline_chat_result(result)
+
+
+@aiui.reply
+async def on_message(message: str):
+    """Chat: Q&A via meeting agent; retry failed uploads via chat commands."""
+    text = str(message).strip()
+    lower = text.lower()
+
+    if lower.startswith("retry meeting "):
+        meeting_id = text.split(maxsplit=2)[-1].strip()
+        await _chat_run_pipeline(retry_pipeline, meeting_id)
+        return
+    if lower.startswith("/retry "):
+        meeting_id = text.split(maxsplit=1)[-1].strip()
+        await _chat_run_pipeline(retry_pipeline, meeting_id)
+        return
+
+    if not os.getenv("OPENAI_API_KEY"):
+        await aiui.say("Set `OPENAI_API_KEY` to chat with the meeting assistant.")
+        return
+
+    await aiui.think("Searching meetings before answering...")
+    agent = get_agent()
+    response = await asyncio.to_thread(agent.chat, text)
+    await aiui.say(str(response))
+
+
+def _register_retry_action() -> None:
+    from praisonaiui.actions import register_action_callback
+
+    async def _on_retry_meeting(action) -> None:
+        meeting_id = (action.payload or {}).get("meeting_id", "")
+        if not meeting_id:
+            await aiui.say("Missing meeting id for retry.")
+            return
+        await _chat_run_pipeline(retry_pipeline, meeting_id)
+
+    register_action_callback("retry-meeting", _on_retry_meeting)
+
+
+_register_retry_action()
+
+
+@aiui.page("upload", title="Upload", icon="⬆️", group="Meetings", order=1)
+async def upload_page():
+    steps = ["Uploading", "Transcribing", "Summarizing", "Indexing", "Ready"]
+    return aiui.layout(
+        [
+            aiui.text("Drop an audio or transcript file to add a meeting."),
+            aiui.alert(
+                "POST a multipart file to /api/meetings/upload with field ``file`` "
+                "(optional ``title``). Supported: mp3, mp4, wav, webm, m4a, ogg.",
+                variant="info",
+                title="Upload API",
+            ),
+            aiui.code_block(
+                'curl -F "[email protected]" -F "title=Weekly standup" '
+                "http://127.0.0.1:8000/api/meetings/upload",
+                language="bash",
+            ),
+            aiui.card("Processing pipeline", footer=" → ".join(steps)),
+            aiui.text(
+                "On error the pipeline surfaces a retry action via the standard "
+                "chat status events; no bespoke state machine lives in the UI. "
+                "In Chat, send ``retry meeting <id>`` or click **Retry** when offered."
+            ),
+        ]
+    )
+
+
+@aiui.page("live-bot", title="Live bot", icon="🤖", group="Meetings", order=2)
+async def live_bot_page():
+    port = os.environ.get("MEETING_AGENT_PORT", "8000")
+    return aiui.layout(
+        [
+            aiui.text(
+                "Send a Recall.ai Meeting Bot to a Zoom, Google Meet, or Teams URL. "
+                "Real-time ``transcript.data`` chunks stream during the call; when the "
+                "call ends, the Phase 1 summarize + index pipeline runs on the full transcript."
+            ),
+            aiui.alert(
+                "Requires RECALL_API_KEY, RECALL_WEBHOOK_VERIFICATION_SECRET, and "
+                "PUBLIC_API_BASE_URL (HTTPS tunnel). Register ``transcript.data`` on the "
+                "same /webhooks/recall endpoint for live captions.",
+                variant="info",
+                title="Recall credentials",
+            ),
+            aiui.code_block(
+                'curl -X POST http://127.0.0.1:'
+                f"{port}/api/recall/bots "
+                '-H "Content-Type: application/json" '
+                '-d \'{"meeting_url":"https://zoom.us/j/123456789","title":"Standup"}\'',
+                language="bash",
+            ),
+            aiui.text(
+                "Live transcript SSE: ``GET /api/meetings/{meeting_id}/live-transcript`` "
+                "with ``Accept: text/event-stream``. Poll fallback: same URL without SSE."
+            ),
+        ]
+    )
+
+
+@aiui.page("calendar", title="Calendar", icon="📅", group="Meetings", order=5)
+async def calendar_page():
+    upcoming: list[dict[str, Any]] = []
+    status_note = "Set RECALL_API_KEY to load calendar status."
+    if os.getenv("RECALL_API_KEY"):
+        try:
+            from meeting_integrations.recall.calendar_service import list_upcoming_calendar_meetings
+
+            upcoming = list_upcoming_calendar_meetings(hours=48)
+            status_note = f"{len(upcoming)} upcoming event(s) with video links (48h window)."
+        except Exception as exc:  # noqa: BLE001
+            status_note = f"Calendar API unavailable: {exc}"
+
+    rows = [
+        [
+            e.get("title", "—"),
+            str(e.get("start", ""))[:16],
+            e.get("platform") or "—",
+            "Yes" if e.get("bot_scheduled") else "No",
+        ]
+        for e in upcoming[:10]
+    ]
+    return aiui.layout(
+        [
+            aiui.text(
+                "Google Calendar V2 auto-schedules Recall bots for eligible future "
+                "events with video links when CALENDAR_AUTO_RECORD=true (default)."
+            ),
+            aiui.alert(status_note, variant="info", title="Calendar status"),
+            aiui.table(
+                headers=["Title", "Start", "Platform", "Bot scheduled"],
+                rows=rows or [["—", "—", "—", "—"]],
+            ),
+            aiui.alert(
+                "Complete Calendar V2 setup via Recall MCP, bootstrap OAuth callback, "
+                "then register calendar webhooks (calendar.sync_events, calendar.update) "
+                "on /webhooks/recall.",
+                variant="info",
+                title="Setup",
+            ),
+            aiui.code_block(
+                "GET /api/recall/calendar/status\n"
+                "GET /api/recall/calendar/upcoming?hours=24\n"
+                "POST /api/recall/calendar/sync {\"calendar_id\":\"...\"}",
+                language="bash",
+            ),
+        ]
+    )
+
+
+@aiui.page("meetings", title="Meetings", icon="📋", group="Meetings", order=3)
+async def meetings_page():
+    meetings = _list_meeting_views()
+    rows = [
+        [
+            m["title"],
+            m["date"],
+            m["status"],
+            m.get("live_status") or "—",
+            m["id"],
+            m["duration"],
+        ]
+        for m in meetings
+    ]
+    return aiui.layout(
+        [
+            aiui.metric("Meetings", value=len(meetings)),
+            aiui.table(
+                headers=["Title", "Date", "Status", "Live", "ID", "Duration"],
+                rows=rows,
+            ),
+        ]
+    )
+
+
+@aiui.page("meeting-detail", title="Meeting detail", icon="📝", group="Meetings", order=4)
+async def meeting_detail_page():
+    meetings = _list_meeting_views()
+    meeting = _pick_detail_meeting(meetings)
+    action_rows = [[a["task"], a["owner"], a["due"]] for a in meeting["actions"]]
+    live = (meeting.get("live_status") or "").lower()
+    header: list[Any] = [
+        aiui.text(meeting["title"]),
+        aiui.badge(meeting["status"], variant=_status_variant(meeting["status"])),
+        aiui.text(f"ID: {meeting['id']}"),
+    ]
+    if live:
+        variant = "default" if live == "live" else "outline"
+        header.append(aiui.badge(live.title(), variant=variant))
+    body: list[Any] = []
+    if meeting.get("error"):
+        body.append(aiui.alert(meeting["error"], variant="warning"))
+    if live == "live":
+        body.append(
+            aiui.alert(
+                "Live transcript auto-refreshes every 3 seconds on this page.",
+                variant="info",
+                title="Live",
+            )
+        )
+    return aiui.layout(
+        header
+        + body
+        + [
+            aiui.tabs(
+                [
+                    {
+                        "label": "Transcript",
+                        "children": [aiui.code_block(meeting["transcript"] or "(empty)", language="text")],
+                    },
+                    {
+                        "label": "Summary",
+                        "children": [aiui.text(meeting["summary"] or "(not summarised yet)")],
+                    },
+                    {
+                        "label": "Action items",
+                        "children": [
+                            aiui.table(
+                                headers=["Task", "Owner", "Due"],
+                                rows=action_rows or [["—", "—", "—"]],
+                            )
+                        ],
+                    },
+                ]
+            ),
+        ]
+    )
+
+
+def _slack_adapter():
+    """Construct a Slack adapter only when tokens are configured (lazy slack_sdk)."""
+    bot = os.environ.get("SLACK_BOT_TOKEN", "")
+    app_token = os.environ.get("SLACK_APP_TOKEN", "")
+    if not bot or not app_token:
+        return None
+    from praisonaiui.features.platform_adapters.slack import SlackChannelAdapter
+
+    return SlackChannelAdapter({"bot_token": bot, "app_token": app_token})
+
+
+def _summary_blocks(meeting: dict) -> list[dict]:
+    action_lines = "\n".join(
+        f"• {a['task']} — {a['owner']} (due {a['due']})" for a in meeting["actions"]
+    ) or "• (none)"
+    return [
+        {"type": "header", "text": {"type": "plain_text", "text": meeting["title"]}},
+        {"type": "section", "text": {"type": "mrkdwn", "text": f"*Date:* {meeting['date']}"}},
+        {"type": "section", "text": {"type": "mrkdwn", "text": meeting["summary"]}},
+        {"type": "section", "text": {"type": "mrkdwn", "text": f"*Action items*\n{action_lines}"}},
+        {
+            "type": "context",
+            "elements": [{"type": "mrkdwn", "text": f"Dashboard: /meeting-detail#{meeting['id']}"}],
+        },
+    ]
+
+
+async def post_meeting_summary(meeting_id: str, channel_id: str) -> bool:
+    """Deliver a meeting summary to Slack (/meeting-summary <id>)."""
+    meeting = _meeting(meeting_id)
+    if meeting is None:
+        return False
+    adapter = _slack_adapter()
+    if adapter is None:
+        return False
+    await adapter.start()
+    try:
+        await adapter.send_message(
+            channel_id,
+            meeting["summary"],
+            blocks=_summary_blocks(meeting),
+        )
+    finally:
+        await adapter.stop()
+    return True
+
+
+async def api_meetings_upload(request: Request) -> JSONResponse:
+    """Accept multipart upload and run the ingest pipeline."""
+    form = await request.form()
+    upload = form.get("file")
+    title = str(form.get("title") or "").strip() or None
+    if upload is None or not getattr(upload, "filename", None):
+        return JSONResponse({"error": "file field is required"}, status_code=400)
+
+    suffix = Path(upload.filename).suffix.lower() or ".bin"
+    from pipeline import AUDIO_SUFFIXES
+
+    if suffix not in AUDIO_SUFFIXES:
+        return JSONResponse(
+            {"error": f"Unsupported file type: {suffix}. Allowed: {sorted(AUDIO_SUFFIXES)}"},
+            status_code=400,
+        )
+
+    data = await upload.read()
+    if not data:
+        return JSONResponse({"error": "empty file"}, status_code=400)
+
+    uploads_dir = Path(tempfile.gettempdir()) / "praisonai_meeting_uploads"
+    uploads_dir.mkdir(parents=True, exist_ok=True)
+    dest = uploads_dir / f"{os.urandom(8).hex()}{suffix}"
+    dest.write_bytes(data)
+
+    result = await asyncio.to_thread(run_ingest_pipeline, str(dest), title)
+    if "error" in result and result.get("meeting_id"):
+        result["retry_hint"] = f"retry meeting {result['meeting_id']}"
+        result["retry_url"] = f"/api/meetings/{result['meeting_id']}/retry"
+    status = 200 if result.get("status") == "ready" else 400 if "error" in result else 500
+    return JSONResponse(result, status_code=status)
+
+
+async def api_meeting_retry(request: Request) -> JSONResponse:
+    meeting_id = request.path_params["meeting_id"]
+    result = await asyncio.to_thread(retry_pipeline, meeting_id)
+    if "error" in result and result.get("meeting_id"):
+        result["retry_hint"] = f"retry meeting {result['meeting_id']}"
+    status = 200 if result.get("status") == "ready" else 400 if "error" in result else 500
+    return JSONResponse(result, status_code=status)
+
+
+async def api_meetings_list(_request: Request) -> JSONResponse:
+    return JSONResponse({"meetings": _list_meeting_views()})
+
+
+async def api_meeting_detail(request: Request) -> JSONResponse:
+    meeting_id = request.path_params["meeting_id"]
+    meeting = _meeting(meeting_id)
+    if meeting is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    return JSONResponse(meeting)
+
+
+app = create_app()
+_meeting_routes = [
+        Route("/api/meetings/upload", api_meetings_upload, methods=["POST"]),
+        Route("/api/meetings/{meeting_id}/retry", api_meeting_retry, methods=["POST"]),
+        Route("/api/meetings", api_meetings_list, methods=["GET"]),
+        Route("/api/meetings/{meeting_id}", api_meeting_detail, methods=["GET"]),
+        Route("/api/recall/bots", api_recall_schedule_bot, methods=["POST"]),
+        Route("/api/recall/bots/{meeting_id}", api_recall_bot_status, methods=["GET"]),
+        Route("/api/recall/bots/{meeting_id}/cancel", api_recall_cancel_bot, methods=["POST"]),
+        Route("/api/recall/config", api_recall_config_status, methods=["GET"]),
+        Route("/webhooks/recall", webhook_recall, methods=["POST"]),
+        Route("/api/recall/calendar/callback", api_recall_calendar_callback, methods=["GET"]),
+        Route(
+            "/api/recall/calendar/setup/bootstrap",
+            api_recall_calendar_bootstrap,
+            methods=["POST"],
+        ),
+        Route("/api/recall/calendar/status", api_recall_calendar_status, methods=["GET"]),
+        Route("/api/recall/calendar/upcoming", api_recall_calendar_upcoming, methods=["GET"]),
+        Route("/api/recall/calendar/sync", api_recall_calendar_sync, methods=["POST"]),
+        Route(
+            "/api/meetings/{meeting_id}/live-transcript",
+            api_meeting_live_transcript,
+            methods=["GET"],
+        ),
+    ]
+# Prepend so custom /api/* routes win over the SPA catch-all from create_app().
+app.routes[0:0] = _meeting_routes
+
+
+if __name__ == "__main__":
+    if "--smoke" in sys.argv:
+        from smoke_recall import run_smoke
+
+        run_smoke()
+        raise SystemExit(0)
+
+    import uvicorn
+
+    host = os.environ.get("HOST", "127.0.0.1")
+    port = int(os.environ.get("MEETING_AGENT_PORT", "8000"))
+    uvicorn.run(app, host=host, port=port)

examples/python/meeting-agent/meeting_integrations/__init__.py

@@ -0,0 +1 @@
+"""Meeting-agent integrations (Recall.ai, etc.)."""

examples/python/meeting-agent/meeting_integrations/recall/__init__.py

@@ -0,0 +1,13 @@
+"""Recall.ai Meeting Bot integration for the meeting-agent example."""
+
+from meeting_integrations.recall.client import RecallClient
+from meeting_integrations.recall.config import RecallSettings, load_recall_settings
+from meeting_integrations.recall.verify import VerificationError, verify_request_from_recall
+
+__all__ = [
+    "RecallClient",
+    "RecallSettings",
+    "VerificationError",
+    "load_recall_settings",
+    "verify_request_from_recall",
+]

examples/python/meeting-agent/meeting_integrations/recall/calendar.py

@@ -0,0 +1,33 @@
+"""Calendar V2 OAuth callback forwarding for Recall-hosted setup."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+FORWARD_PARAMS = ("state", "code", "error", "recall_calendar_setup_probe")
+
+
+def forward_calendar_callback(
+    *,
+    regional_callback_uri: str,
+    query_params: dict[str, str],
+) -> tuple[int, str]:
+    """Forward allowed query params to Recall's regional callback URI."""
+    filtered = {k: v for k, v in query_params.items() if k in FORWARD_PARAMS and v}
+    if not filtered.get("state") and "recall_calendar_setup_probe" not in filtered:
+        return 400, "missing state"
+
+    url = regional_callback_uri
+    if filtered:
+        url = f"{url}?{urlencode(filtered)}"
+
+    logger.info("Forwarding calendar callback to Recall (state redacted)")
+    with httpx.Client(timeout=30.0, follow_redirects=True) as client:
+        response = client.get(url)
+    return response.status_code, response.text[:500]

examples/python/meeting-agent/meeting_integrations/recall/calendar_service.py

@@ -0,0 +1,261 @@
+"""Google Calendar V2 sync and auto-schedule via Recall Calendar API."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from meeting_integrations.recall.client import RecallAPIError, RecallClient
+from meeting_integrations.recall.config import RecallSettings
+from meeting_integrations.recall.store import RecallStore
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_iso(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        normalized = value.replace("Z", "+00:00")
+        if normalized.endswith("+0000"):
+            normalized = normalized[:-5] + "+00:00"
+        return datetime.fromisoformat(normalized)
+    except ValueError:
+        return None
+
+
+def _event_title(event: dict[str, Any]) -> str:
+    raw = event.get("raw") or {}
+    if isinstance(raw, dict):
+        summary = raw.get("summary") or raw.get("subject")
+        if summary:
+            return str(summary)
+    return "Calendar meeting"
+
+
+def _deduplication_key(event: dict[str, Any]) -> str:
+    start = str(event.get("start_time") or "")
+    url = str(event.get("meeting_url") or "")
+    return f"{start}-{url}"
+
+
+def is_eligible_for_auto_record(event: dict[str, Any]) -> bool:
+    """Return True when Recall should schedule a bot for this calendar event."""
+    if event.get("is_deleted"):
+        return False
+    if not event.get("meeting_url"):
+        return False
+    end = _parse_iso(str(event.get("end_time") or ""))
+    if end and end < datetime.now(timezone.utc):
+        return False
+    raw = event.get("raw") or {}
+    if isinstance(raw, dict):
+        status = str(raw.get("status") or "").lower()
+        if status == "cancelled":
+            return False
+    return True
+
+
+def list_upcoming_calendar_meetings(
+    *,
+    hours: int = 24,
+    settings: RecallSettings | None = None,
+    client: RecallClient | None = None,
+) -> list[dict[str, Any]]:
+    """List upcoming Recall calendar events with video links (for UI + agent tool)."""
+    from meeting_integrations.recall.config import load_recall_settings
+
+    settings = settings or load_recall_settings()
+    client = client or RecallClient(settings)
+
+    try:
+        events = client.list_calendar_events(is_deleted=False)
+    except RecallAPIError as exc:
+        logger.warning("Calendar events unavailable: %s", exc)
+        return []
+
+    now = datetime.now(timezone.utc)
+    horizon = now + timedelta(hours=max(1, hours))
+
+    rows: list[dict[str, Any]] = []
+    for event in events:
+        if not is_eligible_for_auto_record(event):
+            continue
+        start = _parse_iso(str(event.get("start_time") or ""))
+        if start and start > horizon:
+            continue
+        bots = event.get("bots") or []
+        rows.append(
+            {
+                "event_id": event.get("id"),
+                "title": _event_title(event),
+                "start": event.get("start_time"),
+                "end": event.get("end_time"),
+                "platform": (event.get("meeting_platform") or {}).get("name")
+                if isinstance(event.get("meeting_platform"), dict)
+                else event.get("meeting_platform"),
+                "meeting_url": event.get("meeting_url"),
+                "bot_scheduled": bool(bots),
+                "calendar_id": event.get("calendar_id"),
+            }
+        )
+
+    rows.sort(key=lambda r: str(r.get("start") or ""))
+    return rows
+
+
+def _ensure_local_meeting_for_event(
+    event: dict[str, Any],
+    *,
+    settings: RecallSettings,
+) -> str:
+    """Create or reuse a local meeting row for a calendar event."""
+    event_id = str(event.get("id") or "")
+    if RecallStore.is_event_scheduled(event_id):
+        row = RecallStore.get_scheduled_bot(event_id)
+        if row and row.get("meeting_id"):
+            return str(row["meeting_id"])
+
+    from praisonai_tools.tools.meeting_tools import save_meeting
+
+    title = _event_title(event)
+    url = str(event.get("meeting_url") or "")
+    saved = save_meeting.__wrapped__(
+        title=title,
+        source=url,
+        metadata={
+            "status": "scheduled",
+            "live_status": "scheduled",
+            "meeting_url": url,
+            "source": "calendar",
+            "recall_calendar_event_id": event_id,
+        },
+    )
+    if "error" in saved:
+        raise RecallAPIError(0, saved["error"])
+    return str(saved["meeting_id"])
+
+
+def sync_calendar_events(
+    calendar_id: str,
+    *,
+    updated_since: str | None = None,
+    settings: RecallSettings,
+    client: RecallClient | None = None,
+    auto_record: bool | None = None,
+) -> dict[str, Any]:
+    """Fetch changed calendar events and schedule/remove bots per policy."""
+    client = client or RecallClient(settings)
+    should_record = (
+        settings.calendar_auto_record if auto_record is None else auto_record
+    )
+
+    events = client.list_calendar_events(
+        calendar_id=calendar_id,
+        updated_at_gte=updated_since,
+    )
+
+    scheduled = 0
+    removed = 0
+    skipped = 0
+    errors: list[str] = []
+
+    for event in events:
+        event_id = str(event.get("id") or "")
+        if not event_id:
+            continue
+
+        eligible = is_eligible_for_auto_record(event) and should_record
+        has_bots = bool(event.get("bots"))
+
+        if not eligible:
+            if has_bots and (event.get("is_deleted") or not should_record):
+                try:
+                    client.remove_bot_from_calendar_event(event_id)
+                    removed += 1
+                except RecallAPIError as exc:
+                    errors.append(f"{event_id}: remove failed: {exc.detail}")
+            else:
+                skipped += 1
+            continue
+
+        if RecallStore.is_event_scheduled(event_id) and has_bots:
+            skipped += 1
+            continue
+
+        try:
+            meeting_id = _ensure_local_meeting_for_event(event, settings=settings)
+            bot_config = client.build_bot_config(
+                meeting_id=meeting_id,
+                title=_event_title(event),
+            )
+            updated = client.schedule_bot_for_calendar_event(
+                event_id,
+                deduplication_key=_deduplication_key(event),
+                bot_config=bot_config,
+            )
+            bot_id = None
+            bots = updated.get("bots") or []
+            if bots and isinstance(bots[0], dict):
+                bot_id = bots[0].get("bot_id") or bots[0].get("id")
+            RecallStore.record_scheduled_bot(event_id, meeting_id, bot_id)
+            from pipeline import merge_meeting_metadata
+
+            merge_meeting_metadata(
+                meeting_id,
+                {
+                    "recall_calendar_event_id": event_id,
+                    "recall_bot_id": bot_id,
+                    "status": "scheduled",
+                    "live_status": "scheduled",
+                },
+            )
+            scheduled += 1
+        except RecallAPIError as exc:
+            logger.warning("Calendar schedule failed for %s: %s", event_id, exc.detail)
+            errors.append(f"{event_id}: {exc.detail}")
+
+    return {
+        "calendar_id": calendar_id,
+        "fetched": len(events),
+        "scheduled": scheduled,
+        "removed": removed,
+        "skipped": skipped,
+        "errors": errors,
+    }
+
+
+def process_calendar_webhook(
+    event_type: str,
+    payload: dict[str, Any],
+    *,
+    settings: RecallSettings,
+    client: RecallClient | None = None,
+) -> None:
+    """Handle Recall Calendar V2 webhooks (calendar.update, calendar.sync_events)."""
+    data = payload.get("data") or {}
+    if not isinstance(data, dict):
+        return
+
+    calendar_id = str(data.get("calendar_id") or "")
+    if not calendar_id:
+        logger.warning("Calendar webhook %s missing calendar_id", event_type)
+        return
+
+    if event_type == "calendar.update":
+        logger.info("Calendar %s updated — refresh status in UI", calendar_id)
+        return
+
+    if event_type == "calendar.sync_events":
+        updated_since = str(data.get("last_updated_ts") or "") or None
+        result = sync_calendar_events(
+            calendar_id,
+            updated_since=updated_since,
+            settings=settings,
+            client=client,
+        )
+        logger.info("Calendar sync %s: %s", calendar_id, result)
+        return
+
+    logger.debug("Ignoring calendar webhook event %s", event_type)

examples/python/meeting-agent/meeting_integrations/recall/client.py

@@ -0,0 +1,290 @@
+"""Minimal Recall.ai REST client (EU region, v1.11)."""
+
+from __future__ import annotations
+
+import json
+import logging
+import random
+import time
+from typing import Any
+
+import httpx
+
+from meeting_integrations.recall.config import RecallSettings
+
+logger = logging.getLogger(__name__)
+
+
+class RecallAPIError(RuntimeError):
+    """Recall API returned a non-success response."""
+
+    def __init__(self, status_code: int, detail: str):
+        super().__init__(detail)
+        self.status_code = status_code
+        self.detail = detail
+
+
+class RecallClient:
+    """HTTP client for Recall Meeting Bots and async transcription."""
+
+    def __init__(self, settings: RecallSettings):
+        self._settings = settings
+        self._base = settings.api_base.rstrip("/")
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": self._settings.api_key,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        max_attempts: int = 4,
+    ) -> dict[str, Any]:
+        url = f"{self._base}{path}"
+        last_error: Exception | None = None
+        for attempt in range(max_attempts):
+            try:
+                with httpx.Client(timeout=30.0) as client:
+                    response = client.request(
+                        method,
+                        url,
+                        headers=self._headers(),
+                        json=json_body,
+                    )
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt + 1 >= max_attempts:
+                    raise RecallAPIError(0, str(exc)) from exc
+                time.sleep(min(2**attempt + random.random(), 8))
+                continue
+
+            if response.status_code == 429:
+                retry_after = response.headers.get("Retry-After")
+                delay = float(retry_after) if retry_after else min(2**attempt, 30)
+                time.sleep(delay + random.random())
+                continue
+
+            if response.status_code in {503, 507} and attempt + 1 < max_attempts:
+                time.sleep(min(2**attempt + random.random(), 8))
+                continue
+
+            if response.status_code >= 400:
+                detail = response.text[:500] or response.reason_phrase
+                raise RecallAPIError(response.status_code, detail)
+
+            if not response.content:
+                return {}
+            return response.json()
+
+        raise RecallAPIError(0, str(last_error or "request failed"))
+
+    def create_bot(
+        self,
+        *,
+        meeting_url: str,
+        meeting_id: str,
+        title: str,
+        join_at: str | None = None,
+        enable_realtime_transcription: bool = True,
+    ) -> dict[str, Any]:
+        """Schedule a Recall bot; attach local meeting_id in metadata for webhook routing."""
+        body: dict[str, Any] = {
+            "meeting_url": meeting_url,
+            "bot_name": self._settings.bot_name,
+            "metadata": {"meeting_id": meeting_id, "title": title},
+        }
+        if join_at:
+            body["join_at"] = join_at
+        if enable_realtime_transcription:
+            recording_config = self._settings.realtime_recording_config()
+            if recording_config:
+                body["recording_config"] = recording_config
+                logger.info(
+                    "Live transcript enabled for meeting_id=%s → %s",
+                    meeting_id,
+                    self._settings.webhook_url,
+                )
+            else:
+                logger.warning(
+                    "Live transcript skipped for meeting_id=%s — set PUBLIC_API_BASE_URL",
+                    meeting_id,
+                )
+        logger.info(
+            "Creating Recall bot for meeting_id=%s (url redacted)",
+            meeting_id,
+        )
+        return self._request("POST", "/api/v1/bot/", json_body=body)
+
+    def build_bot_config(
+        self,
+        *,
+        meeting_id: str,
+        title: str,
+        enable_realtime_transcription: bool = True,
+    ) -> dict[str, Any]:
+        """Bot config payload for Calendar V2 schedule-bot requests."""
+        config: dict[str, Any] = {
+            "bot_name": self._settings.bot_name,
+            "metadata": {"meeting_id": meeting_id, "title": title},
+        }
+        if enable_realtime_transcription:
+            recording_config = self._settings.realtime_recording_config()
+            if recording_config:
+                config["recording_config"] = recording_config
+        return config
+
+    def get_bot(self, bot_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/bot/{bot_id}/")
+
+    def cancel_bot(self, bot_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/api/v1/bot/{bot_id}/leave_call/")
+
+    def create_async_transcript(self, recording_id: str) -> dict[str, Any]:
+        body = {
+            "provider": {"recallai_async": {"language_code": "auto"}},
+            "diarization": {"use_separate_streams_when_available": True},
+        }
+        return self._request(
+            "POST",
+            f"/api/v1/recording/{recording_id}/create_transcript/",
+            json_body=body,
+        )
+
+    def get_transcript(self, transcript_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/transcript/{transcript_id}/")
+
+    @staticmethod
+    def extract_recording_id(payload: dict[str, Any]) -> str | None:
+        data = payload.get("data") or {}
+        if isinstance(data, dict):
+            recording = data.get("recording") or {}
+            if isinstance(recording, dict) and recording.get("id"):
+                return str(recording["id"])
+            inner = data.get("data") or {}
+            if isinstance(inner, dict):
+                rec = inner.get("recording") or {}
+                if isinstance(rec, dict) and rec.get("id"):
+                    return str(rec["id"])
+        return None
+
+    @staticmethod
+    def extract_transcript_id(payload: dict[str, Any]) -> str | None:
+        data = payload.get("data") or {}
+        if isinstance(data, dict):
+            transcript = data.get("transcript") or {}
+            if isinstance(transcript, dict) and transcript.get("id"):
+                return str(transcript["id"])
+        return None
+
+    @staticmethod
+    def extract_bot_id(payload: dict[str, Any]) -> str | None:
+        data = payload.get("data") or {}
+        if isinstance(data, dict):
+            bot = data.get("bot") or {}
+            if isinstance(bot, dict) and bot.get("id"):
+                return str(bot["id"])
+        return None
+
+    @staticmethod
+    def extract_meeting_id_from_bot_metadata(payload: dict[str, Any]) -> str | None:
+        data = payload.get("data") or {}
+        if not isinstance(data, dict):
+            return None
+        bot = data.get("bot") or {}
+        if not isinstance(bot, dict):
+            return None
+        metadata = bot.get("metadata") or {}
+        if isinstance(metadata, dict):
+            mid = metadata.get("meeting_id")
+            return str(mid) if mid else None
+        return None
+
+    @staticmethod
+    def download_json(url: str) -> Any:
+        with httpx.Client(timeout=60.0) as client:
+            response = client.get(url)
+            response.raise_for_status()
+            return response.json()
+
+    def list_calendars(self, *, status: str | None = "connected") -> list[dict[str, Any]]:
+        params: dict[str, str] = {}
+        if status:
+            params["status"] = status
+        results: list[dict[str, Any]] = []
+        cursor: str | None = None
+        while True:
+            query = dict(params)
+            if cursor:
+                query["cursor"] = cursor
+            path = "/api/v2/calendars/"
+            if query:
+                from urllib.parse import urlencode
+
+                path = f"{path}?{urlencode(query)}"
+            page = self._request("GET", path)
+            batch = page.get("results") or []
+            if isinstance(batch, list):
+                results.extend(item for item in batch if isinstance(item, dict))
+            cursor = page.get("next")
+            if not cursor:
+                break
+        return results
+
+    def list_calendar_events(
+        self,
+        *,
+        calendar_id: str | None = None,
+        updated_at_gte: str | None = None,
+        is_deleted: bool | None = False,
+    ) -> list[dict[str, Any]]:
+        from urllib.parse import urlencode
+
+        params: dict[str, str] = {}
+        if calendar_id:
+            params["calendar_id"] = calendar_id
+        if updated_at_gte:
+            params["updated_at__gte"] = updated_at_gte
+        if is_deleted is not None:
+            params["is_deleted"] = "true" if is_deleted else "false"
+
+        results: list[dict[str, Any]] = []
+        cursor: str | None = None
+        while True:
+            query = dict(params)
+            if cursor:
+                query["cursor"] = cursor
+            path = f"/api/v2/calendar-events/?{urlencode(query)}" if query else "/api/v2/calendar-events/"
+            page = self._request("GET", path)
+            batch = page.get("results") or []
+            if isinstance(batch, list):
+                results.extend(item for item in batch if isinstance(item, dict))
+            cursor = page.get("next")
+            if not cursor:
+                break
+        return results
+
+    def schedule_bot_for_calendar_event(
+        self,
+        event_id: str,
+        *,
+        deduplication_key: str,
+        bot_config: dict[str, Any],
+    ) -> dict[str, Any]:
+        body = {
+            "deduplication_key": deduplication_key,
+            "bot_config": bot_config,
+        }
+        return self._request(
+            "POST",
+            f"/api/v2/calendar-events/{event_id}/bot/",
+            json_body=body,
+        )
+
+    def remove_bot_from_calendar_event(self, event_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/api/v2/calendar-events/{event_id}/bot/")

examples/python/meeting-agent/meeting_integrations/recall/config.py

@@ -0,0 +1,100 @@
+"""Recall.ai runtime configuration — credentials stay server-side only."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlparse
+
+
+class RecallConfigError(ValueError):
+    """Raised when required Recall settings are missing or invalid."""
+
+
+@dataclass(frozen=True)
+class RecallSettings:
+    """Validated Recall workspace settings injected into the API client."""
+
+    region: str
+    api_key: str
+    webhook_verification_secret: str
+    public_api_base_url: str
+    workspace_id: str
+    bot_name: str
+    calendar_auto_record: bool
+
+    @property
+    def api_base(self) -> str:
+        return f"https://{self.region}.recall.ai"
+
+    @property
+    def webhook_url(self) -> str:
+        return f"{self.public_api_base_url.rstrip('/')}/webhooks/recall"
+
+    @property
+    def calendar_callback_url(self) -> str:
+        return f"{self.public_api_base_url.rstrip('/')}/api/recall/calendar/callback"
+
+    def realtime_recording_config(self) -> dict[str, Any] | None:
+        """Recording config with live ``transcript.data`` webhooks (no dashboard toggle)."""
+        if not self.public_api_base_url:
+            return None
+        return {
+            "transcript": {
+                "provider": {
+                    "recallai_streaming": {
+                        "mode": "prioritize_low_latency",
+                        "language_code": "en",
+                    }
+                },
+                "diarization": {
+                    "use_separate_streams_when_available": True,
+                },
+            },
+            "realtime_endpoints": [
+                {
+                    "type": "webhook",
+                    "url": self.webhook_url,
+                        "events": ["transcript.data", "transcript.partial_data"],
+                }
+            ],
+        }
+
+
+def _require(name: str) -> str:
+    value = os.getenv(name, "").strip()
+    if not value:
+        raise RecallConfigError(f"{name} is required for Recall integration")
+    return value
+
+
+def load_recall_settings(*, require_public_url: bool = False) -> RecallSettings:
+    """Load Recall settings from the process environment."""
+    region = os.getenv("RECALL_REGION", "eu-central-1").strip() or "eu-central-1"
+    public_url = os.getenv("PUBLIC_API_BASE_URL", "").strip()
+    if require_public_url and not public_url:
+        raise RecallConfigError(
+            "PUBLIC_API_BASE_URL is required (stable HTTPS backend URL for webhooks "
+            "and calendar OAuth callback forwarding)"
+        )
+    if public_url:
+        parsed = urlparse(public_url)
+        if parsed.scheme not in {"https", "http"} or not parsed.netloc:
+            raise RecallConfigError("PUBLIC_API_BASE_URL must be an absolute http(s) URL")
+        if parsed.hostname in {"localhost", "127.0.0.1"}:
+            raise RecallConfigError(
+                "PUBLIC_API_BASE_URL must not be localhost; use a reserved tunnel domain"
+            )
+
+    auto_record = os.getenv("CALENDAR_AUTO_RECORD", "true").strip().lower()
+    return RecallSettings(
+        region=region,
+        api_key=_require("RECALL_API_KEY"),
+        webhook_verification_secret=_require("RECALL_WEBHOOK_VERIFICATION_SECRET"),
+        public_api_base_url=public_url,
+        workspace_id=os.getenv("RECALL_WORKSPACE_ID", "").strip(),
+        bot_name=os.getenv("RECALL_BOT_NAME", "Praison Meeting Agent").strip()
+        or "Praison Meeting Agent",
+        calendar_auto_record=auto_record not in {"0", "false", "no", "off"},
+    )

examples/python/meeting-agent/meeting_integrations/recall/live.py

@@ -0,0 +1,83 @@
+"""In-process live transcript fan-out for SSE subscribers."""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class LiveTranscriptState:
+    """Latest live transcript snapshot for a meeting."""
+
+    lines: list[str] = field(default_factory=list)
+    text: str = ""
+    live_status: str = ""
+
+
+_lock = threading.Lock()
+_states: dict[str, LiveTranscriptState] = {}
+_subscribers: dict[str, list[threading.Event]] = defaultdict(list)
+
+
+def get_live_state(meeting_id: str) -> LiveTranscriptState | None:
+    with _lock:
+        return _states.get(meeting_id)
+
+
+def publish_live_chunk(
+    meeting_id: str,
+    *,
+    line: str,
+    full_text: str,
+    live_status: str = "live",
+) -> None:
+    """Record a new utterance and notify SSE waiters."""
+    with _lock:
+        state = _states.setdefault(meeting_id, LiveTranscriptState())
+        if line:
+            state.lines.append(line)
+        state.text = full_text
+        state.live_status = live_status
+        waiters = list(_subscribers.get(meeting_id, []))
+    for event in waiters:
+        event.set()
+
+
+def set_live_status(meeting_id: str, live_status: str) -> None:
+    with _lock:
+        state = _states.setdefault(meeting_id, LiveTranscriptState())
+        state.live_status = live_status
+        waiters = list(_subscribers.get(meeting_id, []))
+    for event in waiters:
+        event.set()
+
+
+def wait_for_update(meeting_id: str, timeout: float = 25.0) -> LiveTranscriptState | None:
+    """Block until the meeting transcript changes or timeout (for SSE long-poll)."""
+    event = threading.Event()
+    with _lock:
+        _subscribers[meeting_id].append(event)
+        state = _states.get(meeting_id)
+    event.wait(timeout=timeout)
+    with _lock:
+        subs = _subscribers.get(meeting_id, [])
+        if event in subs:
+            subs.remove(event)
+        return _states.get(meeting_id)
+
+
+def snapshot_for_api(meeting_id: str, record: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Merge in-memory live state with persisted meeting metadata."""
+    meta = (record or {}).get("metadata") or {}
+    live = get_live_state(meeting_id)
+    text = (live.text if live and live.text else meta.get("transcript")) or ""
+    return {
+        "meeting_id": meeting_id,
+        "live_status": (live.live_status if live and live.live_status else meta.get("live_status"))
+        or "",
+        "transcript": text,
+        "line_count": len([ln for ln in text.splitlines() if ln.strip()]),
+    }

examples/python/meeting-agent/meeting_integrations/recall/processor.py

@@ -0,0 +1,226 @@
+"""Async Recall webhook event processing."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from meeting_integrations.recall.client import RecallAPIError, RecallClient
+from meeting_integrations.recall.config import RecallSettings
+from meeting_integrations.recall.store import RecallStore, webhook_event_key
+from meeting_integrations.recall.transcript import transcript_data_to_line, transcript_download_to_text
+
+logger = logging.getLogger(__name__)
+
+
+def _speaker_prefix(line: str) -> str:
+    if ":" in line:
+        return line.split(":", 1)[0] + ":"
+    return ""
+
+
+def _upsert_live_transcript(meeting_id: str, line: str, *, partial: bool = False) -> str:
+    """Merge one live caption line; partial updates replace the last same-speaker line."""
+    from praisonai_tools.tools.meeting_tools import get_meeting
+    from meeting_integrations.recall.live import publish_live_chunk
+    from pipeline import _metadata_lock
+
+    # Hold the merge lock across the read too: streaming transcript events are
+    # dispatched one-thread-each, so an unsynchronized read-append-write would
+    # let concurrent captions clobber each other and drop lines.
+    with _metadata_lock:
+        record = get_meeting.__wrapped__(meeting_id)
+        meta = record.get("metadata") or {} if isinstance(record, dict) else {}
+        existing = str(meta.get("transcript") or "")
+        lines = existing.splitlines()
+        prefix = _speaker_prefix(line)
+
+        if lines and lines[-1] == line:
+            full = existing
+        elif partial and lines and prefix and lines[-1].startswith(prefix):
+            lines[-1] = line
+            full = "\n".join(lines)
+        elif not partial and lines and prefix and lines[-1].startswith(prefix):
+            # Final utterance replaces the in-progress partial for this speaker.
+            lines[-1] = line
+            full = "\n".join(lines)
+        else:
+            full = f"{existing}\n{line}".strip() if existing else line
+
+        _merge_metadata(
+            meeting_id,
+            {"transcript": full, "live_status": "live", "status": "live"},
+        )
+    publish_live_chunk(meeting_id, line=line, full_text=full, live_status="live")
+    return full
+
+
+def _append_live_transcript(meeting_id: str, line: str) -> str:
+    return _upsert_live_transcript(meeting_id, line, partial=False)
+
+
+def _merge_metadata(meeting_id: str, patch: dict[str, Any]) -> None:
+    from pipeline import merge_meeting_metadata
+
+    merge_meeting_metadata(meeting_id, patch)
+
+
+def _resolve_meeting_id(payload: dict[str, Any], bot_id: str | None) -> str | None:
+    meeting_id = RecallClient.extract_meeting_id_from_bot_metadata(payload)
+    if meeting_id:
+        return meeting_id
+    if not bot_id:
+        return None
+    try:
+        from praisonai_tools.tools.meeting_tools import list_meetings
+
+        rows = list_meetings.__wrapped__(limit=200, offset=0)
+        for row in rows:
+            if not isinstance(row, dict):
+                continue
+            meta = row.get("metadata") or {}
+            if meta.get("recall_bot_id") == bot_id:
+                return row.get("meeting_id")
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Could not resolve meeting by bot_id: %s", exc)
+    return None
+
+
+def process_recall_webhook(
+    event_type: str,
+    payload: dict[str, Any],
+    *,
+    settings: RecallSettings,
+    client: RecallClient | None = None,
+) -> None:
+    """Handle a verified Recall webhook (runs off the request thread)."""
+    event_key = webhook_event_key(event_type, payload)
+    if not RecallStore.mark_event_processed(event_key, event_type):
+        logger.info("Skipping duplicate Recall event %s", event_type)
+        return
+
+    client = client or RecallClient(settings)
+    bot_id = RecallClient.extract_bot_id(payload)
+    meeting_id = _resolve_meeting_id(payload, bot_id)
+
+    if event_type == "bot.joining_call" and meeting_id:
+        _merge_metadata(meeting_id, {"live_status": "joining", "recall_bot_id": bot_id})
+        return
+
+    if event_type == "bot.in_waiting_room" and meeting_id:
+        _merge_metadata(
+            meeting_id,
+            {
+                "live_status": "waiting_room",
+                "status": "Scheduled",
+                "error": "Bot is in the meeting waiting room — admit 'Praison Meeting Agent' to record.",
+            },
+        )
+        return
+
+    if event_type == "bot.in_call_recording" and meeting_id:
+        _merge_metadata(meeting_id, {"live_status": "live", "status": "live", "error": ""})
+        from meeting_integrations.recall.live import set_live_status
+
+        set_live_status(meeting_id, "live")
+        return
+
+    if event_type == "transcript.data" and meeting_id:
+        line = transcript_data_to_line(payload)
+        if line:
+            _append_live_transcript(meeting_id, line)
+        return
+
+    if event_type == "transcript.partial_data" and meeting_id:
+        line = transcript_data_to_line(payload)
+        if line:
+            _upsert_live_transcript(meeting_id, line, partial=True)
+        return
+
+    if event_type == "bot.call_ended" and meeting_id:
+        _merge_metadata(meeting_id, {"live_status": "ended"})
+        from meeting_integrations.recall.live import set_live_status
+
+        set_live_status(meeting_id, "ended")
+        return
+
+    if event_type == "bot.fatal" and meeting_id:
+        sub = ((payload.get("data") or {}).get("data") or {}).get("sub_code")
+        _merge_metadata(
+            meeting_id,
+            {
+                "live_status": "failed",
+                "status": "failed",
+                "error": f"Recall bot fatal: {sub or 'unknown'}",
+            },
+        )
+        return
+
+    if event_type == "bot.done" and meeting_id:
+        _merge_metadata(meeting_id, {"live_status": "processing"})
+        return
+
+    if event_type == "recording.done":
+        recording_id = RecallClient.extract_recording_id(payload)
+        if not recording_id:
+            logger.warning("recording.done without recording id")
+            return
+        if meeting_id:
+            _merge_metadata(meeting_id, {"recall_recording_id": recording_id})
+            started_at = ((payload.get("data") or {}).get("recording") or {}).get("started_at")
+            completed_at = ((payload.get("data") or {}).get("recording") or {}).get("completed_at")
+            if started_at and completed_at:
+                try:
+                    from datetime import datetime
+
+                    fmt = "%Y-%m-%dT%H:%M:%S.%f%z"
+                    start = datetime.strptime(started_at.replace("Z", "+0000"), fmt)
+                    end = datetime.strptime(completed_at.replace("Z", "+0000"), fmt)
+                    _merge_metadata(
+                        meeting_id,
+                        {"duration_seconds": int((end - start).total_seconds())},
+                    )
+                except (TypeError, ValueError):
+                    pass
+        try:
+            client.create_async_transcript(recording_id)
+            logger.info("Started async transcript for recording %s", recording_id)
+        except RecallAPIError as exc:
+            logger.error("create_async_transcript failed: %s", exc)
+            if meeting_id:
+                _merge_metadata(
+                    meeting_id,
+                    {"status": "failed", "error": f"Transcript start failed: {exc}"},
+                )
+        return
+
+    if event_type == "transcript.failed" and meeting_id:
+        _merge_metadata(
+            meeting_id,
+            {"status": "failed", "error": "Recall transcript generation failed"},
+        )
+        return
+
+    if event_type == "transcript.done":
+        transcript_id = RecallClient.extract_transcript_id(payload)
+        if not transcript_id:
+            logger.warning("transcript.done without transcript id")
+            return
+        if not meeting_id:
+            logger.warning("transcript.done without meeting_id")
+            return
+        try:
+            artifact = client.get_transcript(transcript_id)
+            download_url = (artifact.get("data") or {}).get("download_url")
+            if not download_url:
+                raise RecallAPIError(0, "missing transcript download_url")
+            raw = client.download_json(download_url)
+            text = transcript_download_to_text(raw)
+            if not text.strip():
+                raise RecallAPIError(0, "empty transcript")
+            from pipeline import run_post_transcript_pipeline
+
+            run_post_transcript_pipeline(meeting_id, text)
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("Post-transcript pipeline failed")
+            _merge_metadata(meeting_id, {"status": "failed", "error": str(exc)})

examples/python/meeting-agent/meeting_integrations/recall/service.py

@@ -0,0 +1,138 @@
+"""High-level Recall bot scheduling used by API routes and the agent."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from meeting_integrations.recall.client import RecallAPIError, RecallClient
+from meeting_integrations.recall.config import RecallConfigError, RecallSettings, load_recall_settings
+
+logger = logging.getLogger(__name__)
+
+_MEETING_URL_RE = re.compile(r"^https?://", re.I)
+
+
+def schedule_recall_bot(
+    meeting_url: str,
+    title: str = "",
+    *,
+    join_at: str | None = None,
+    settings: RecallSettings | None = None,
+    client: RecallClient | None = None,
+) -> dict[str, Any]:
+    """Persist local intent, create the Recall bot, and store the returned bot id."""
+    url = (meeting_url or "").strip()
+    if not _MEETING_URL_RE.match(url):
+        return {"error": "meeting_url must be an http(s) URL"}
+
+    meeting_title = (title or "Live meeting").strip() or "Live meeting"
+
+    try:
+        settings = settings or load_recall_settings()
+    except RecallConfigError as exc:
+        return {"error": str(exc)}
+
+    from praisonai_tools.tools.meeting_tools import save_meeting
+
+    saved = save_meeting.__wrapped__(
+        title=meeting_title,
+        source=url,
+        metadata={
+            "status": "scheduled",
+            "live_status": "scheduled",
+            "meeting_url": url,
+            "source": "recall",
+        },
+    )
+    if "error" in saved:
+        return saved
+
+    meeting_id = saved["meeting_id"]
+    api = client or RecallClient(settings)
+
+    try:
+        bot = api.create_bot(
+            meeting_url=url,
+            meeting_id=meeting_id,
+            title=meeting_title,
+            join_at=join_at,
+        )
+    except RecallAPIError as exc:
+        from pipeline import merge_meeting_metadata
+
+        merge_meeting_metadata(
+            meeting_id,
+            {
+                "status": "failed",
+                "live_status": "failed",
+                "error": f"Recall create bot failed: {exc.detail}",
+            },
+        )
+        return {
+            "meeting_id": meeting_id,
+            "error": f"Recall create bot failed: {exc.detail}",
+        }
+
+    bot_id = bot.get("id")
+    from pipeline import merge_meeting_metadata
+
+    merge_meeting_metadata(
+        meeting_id,
+        {
+            "recall_bot_id": bot_id,
+            "status": "scheduled",
+            "live_status": "scheduled",
+            "meeting_url": url,
+        },
+    )
+
+    realtime = settings.realtime_recording_config() is not None
+    logger.info("Scheduled Recall bot %s for meeting %s", bot_id, meeting_id)
+    return {
+        "meeting_id": meeting_id,
+        "recall_bot_id": bot_id,
+        "status": "scheduled",
+        "live_status": "scheduled",
+        "title": meeting_title,
+        "meeting_url": url,
+        "realtime_transcript_enabled": realtime,
+        "realtime_webhook_url": settings.webhook_url if realtime else None,
+    }
+
+
+def cancel_recall_bot(
+    meeting_id: str,
+    *,
+    settings: RecallSettings | None = None,
+    client: RecallClient | None = None,
+) -> dict[str, Any]:
+    """Cancel a scheduled or in-call Recall bot."""
+    from praisonai_tools.tools.meeting_tools import get_meeting
+    from pipeline import merge_meeting_metadata
+
+    record = get_meeting.__wrapped__(meeting_id)
+    if "error" in record:
+        return record
+
+    bot_id = (record.get("metadata") or {}).get("recall_bot_id")
+    if not bot_id:
+        return {"error": "No Recall bot linked to this meeting", "meeting_id": meeting_id}
+
+    try:
+        settings = settings or load_recall_settings()
+    except RecallConfigError as exc:
+        return {"error": str(exc)}
+
+    api = client or RecallClient(settings)
+    try:
+        api.cancel_bot(str(bot_id))
+    except RecallAPIError as exc:
+        return {"meeting_id": meeting_id, "error": str(exc)}
+
+    merge_meeting_metadata(
+        meeting_id,
+        {"live_status": "cancelled", "status": "cancelled"},
+    )
+    return {"meeting_id": meeting_id, "recall_bot_id": bot_id, "status": "cancelled"}

examples/python/meeting-agent/meeting_integrations/recall/store.py

@@ -0,0 +1,213 @@
+"""Persist Recall webhook idempotency and calendar setup state."""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from contextlib import closing
+from pathlib import Path
+from typing import Any
+
+from meeting_integrations.recall.client import RecallClient
+
+
+def _state_db_path() -> str:
+    env = os.getenv("PRAISONAI_MEETINGS_DIR")
+    base = Path(env) if env else Path.home() / ".praisonai" / "meetings"
+    base.mkdir(parents=True, exist_ok=True)
+    return str(base / "recall_state.db")
+
+
+def _connect() -> sqlite3.Connection:
+    conn = sqlite3.connect(_state_db_path())
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS recall_webhook_events (
+            event_key TEXT PRIMARY KEY,
+            event_type TEXT NOT NULL,
+            processed_at TEXT NOT NULL
+        )
+        """
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS recall_calendar_setup (
+            setup_id TEXT PRIMARY KEY,
+            platform TEXT NOT NULL,
+            state_json TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        )
+        """
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS recall_scheduled_bots (
+            event_id TEXT PRIMARY KEY,
+            meeting_id TEXT NOT NULL,
+            bot_id TEXT,
+            scheduled_at TEXT NOT NULL
+        )
+        """
+    )
+    return conn
+
+
+def webhook_event_key(event_type: str, payload: dict[str, Any]) -> str:
+    """Build a stable idempotency key from webhook metadata."""
+    data = payload.get("data") or {}
+
+    # Streaming transcript events fire many times per bot — never dedupe on bot_id alone.
+    if event_type in ("transcript.data", "transcript.partial_data"):
+        inner = data.get("data") if isinstance(data, dict) else {}
+        bot_id = RecallClient.extract_bot_id(payload) or ""
+        if isinstance(inner, dict):
+            words = inner.get("words")
+            if isinstance(words, list) and words:
+                first = words[0] if isinstance(words[0], dict) else {}
+                last = words[-1] if isinstance(words[-1], dict) else {}
+                word_text = " ".join(
+                    w.get("text", "") for w in words if isinstance(w, dict)
+                ).strip()
+                return (
+                    f"{event_type}:{bot_id}:"
+                    f"{first.get('start', first.get('start_time', ''))}:"
+                    f"{last.get('end', last.get('end_time', ''))}:"
+                    f"{word_text}"
+                )
+            text = str(inner.get("text") or "").strip()
+            start = inner.get("start") or inner.get("start_time") or ""
+            end = inner.get("end") or inner.get("end_time") or ""
+            speaker = inner.get("speaker") or inner.get("speaker_name") or ""
+            return f"{event_type}:{bot_id}:{start}:{end}:{speaker}:{text}"
+        return f"{event_type}:{json.dumps(payload, sort_keys=True)}"
+
+    for part in (
+        payload.get("id"),
+        data.get("id") if isinstance(data, dict) else None,
+    ):
+        if part:
+            return f"{event_type}:{part}"
+    bot_id = RecallStore.extract_bot_id(payload)
+    recording_id = RecallStore.extract_recording_id(payload)
+    transcript_id = RecallStore.extract_transcript_id(payload)
+    suffix = bot_id or recording_id or transcript_id or json.dumps(payload, sort_keys=True)
+    return f"{event_type}:{suffix}"
+
+
+class RecallStore:
+    """SQLite-backed Recall integration state."""
+
+    @staticmethod
+    def extract_bot_id(payload: dict[str, Any]) -> str | None:
+        from meeting_integrations.recall.client import RecallClient
+
+        return RecallClient.extract_bot_id(payload)
+
+    @staticmethod
+    def extract_recording_id(payload: dict[str, Any]) -> str | None:
+        from meeting_integrations.recall.client import RecallClient
+
+        return RecallClient.extract_recording_id(payload)
+
+    @staticmethod
+    def extract_transcript_id(payload: dict[str, Any]) -> str | None:
+        from meeting_integrations.recall.client import RecallClient
+
+        return RecallClient.extract_transcript_id(payload)
+
+    @staticmethod
+    def mark_event_processed(event_key: str, event_type: str) -> bool:
+        """Claim an event for processing; return False if already processed.
+
+        Uses an atomic ``INSERT OR IGNORE`` so concurrent duplicate webhook
+        deliveries (Svix retries/fan-out) cannot both pass the check — the
+        second insert is ignored and reports zero changed rows.
+        """
+        from datetime import datetime, timezone
+
+        with closing(_connect()) as conn, conn:
+            cursor = conn.execute(
+                """
+                INSERT OR IGNORE INTO recall_webhook_events
+                    (event_key, event_type, processed_at)
+                VALUES (?, ?, ?)
+                """,
+                (event_key, event_type, datetime.now(timezone.utc).isoformat()),
+            )
+            return cursor.rowcount > 0
+
+    @staticmethod
+    def save_calendar_setup(setup_id: str, platform: str, state: dict[str, Any]) -> None:
+        from datetime import datetime, timezone
+
+        with closing(_connect()) as conn, conn:
+            conn.execute(
+                """
+                INSERT INTO recall_calendar_setup (setup_id, platform, state_json, updated_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(setup_id) DO UPDATE SET
+                    platform = excluded.platform,
+                    state_json = excluded.state_json,
+                    updated_at = excluded.updated_at
+                """,
+                (
+                    setup_id,
+                    platform,
+                    json.dumps(state, sort_keys=True),
+                    datetime.now(timezone.utc).isoformat(),
+                ),
+            )
+
+    @staticmethod
+    def get_calendar_setup(setup_id: str) -> dict[str, Any] | None:
+        with closing(_connect()) as conn:
+            row = conn.execute(
+                "SELECT state_json FROM recall_calendar_setup WHERE setup_id = ?",
+                (setup_id,),
+            ).fetchone()
+        if not row:
+            return None
+        return json.loads(row[0])
+
+    @staticmethod
+    def record_scheduled_bot(event_id: str, meeting_id: str, bot_id: str | None) -> None:
+        from datetime import datetime, timezone
+
+        with closing(_connect()) as conn, conn:
+            conn.execute(
+                """
+                INSERT INTO recall_scheduled_bots (event_id, meeting_id, bot_id, scheduled_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(event_id) DO NOTHING
+                """,
+                (event_id, meeting_id, bot_id, datetime.now(timezone.utc).isoformat()),
+            )
+
+    @staticmethod
+    def is_event_scheduled(event_id: str) -> bool:
+        with closing(_connect()) as conn:
+            row = conn.execute(
+                "SELECT 1 FROM recall_scheduled_bots WHERE event_id = ?",
+                (event_id,),
+            ).fetchone()
+        return row is not None
+
+    @staticmethod
+    def get_scheduled_bot(event_id: str) -> dict[str, Any] | None:
+        with closing(_connect()) as conn:
+            row = conn.execute(
+                """
+                SELECT event_id, meeting_id, bot_id, scheduled_at
+                FROM recall_scheduled_bots WHERE event_id = ?
+                """,
+                (event_id,),
+            ).fetchone()
+        if not row:
+            return None
+        return {
+            "event_id": row[0],
+            "meeting_id": row[1],
+            "bot_id": row[2],
+            "scheduled_at": row[3],
+        }

examples/python/meeting-agent/meeting_integrations/recall/transcript.py

@@ -0,0 +1,62 @@
+"""Convert Recall transcript download payloads to plain text."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def transcript_data_to_line(payload: dict[str, Any]) -> str:
+    """Flatten a verified ``transcript.data`` webhook payload to one line."""
+    data = payload.get("data") or {}
+    if not isinstance(data, dict):
+        return ""
+
+    inner = data.get("data") or data
+    if not isinstance(inner, dict):
+        return ""
+
+    words = inner.get("words")
+    if isinstance(words, list) and words:
+        text = " ".join(
+            w.get("text", "") for w in words if isinstance(w, dict)
+        ).strip()
+    else:
+        text = str(inner.get("text") or "").strip()
+
+    if not text:
+        return ""
+
+    speaker = inner.get("speaker") or inner.get("speaker_name")
+    participant = inner.get("participant")
+    if not speaker and isinstance(participant, dict):
+        speaker = participant.get("name")
+    return f"{speaker}: {text}" if speaker else text
+
+
+def transcript_download_to_text(data: Any) -> str:
+    """Flatten Recall transcript JSON into a readable multi-line string."""
+    if isinstance(data, str):
+        return data.strip()
+    if not isinstance(data, list):
+        return str(data)
+
+    lines: list[str] = []
+    for item in data:
+        if not isinstance(item, dict):
+            continue
+        speaker = item.get("speaker") or item.get("speaker_name")
+        participant = item.get("participant")
+        if not speaker and isinstance(participant, dict):
+            speaker = participant.get("name")
+        words = item.get("words")
+        if isinstance(words, list) and words:
+            text = " ".join(
+                w.get("text", "") for w in words if isinstance(w, dict)
+            ).strip()
+        else:
+            text = str(item.get("text") or "").strip()
+        if not text:
+            continue
+        prefix = f"{speaker}: " if speaker else ""
+        lines.append(f"{prefix}{text}")
+    return "\n".join(lines)

examples/python/meeting-agent/meeting_integrations/recall/verify.py

@@ -0,0 +1,48 @@
+"""Verify incoming Recall webhook and callback requests."""
+
+from __future__ import annotations
+
+import base64
+import hmac
+import hashlib
+
+
+class VerificationError(ValueError):
+    """Signature verification failed."""
+
+
+def verify_request_from_recall(
+    *,
+    secret: str,
+    headers: dict[str, str],
+    payload: str | None,
+) -> None:
+    """Verify Recall/Svix-style webhook signatures on the raw request body."""
+    if not secret or not secret.startswith("whsec_"):
+        raise VerificationError("Verification secret is missing or invalid")
+
+    lowered = {k.lower(): v for k, v in headers.items()}
+    msg_id = lowered.get("webhook-id") or lowered.get("svix-id")
+    msg_timestamp = lowered.get("webhook-timestamp") or lowered.get("svix-timestamp")
+    msg_signature = lowered.get("webhook-signature") or lowered.get("svix-signature")
+
+    if not msg_id or not msg_timestamp or not msg_signature:
+        raise VerificationError("Missing webhook id, timestamp, or signature")
+
+    key = base64.b64decode(secret.removeprefix("whsec_"))
+    payload_str = payload or ""
+    to_sign = f"{msg_id}.{msg_timestamp}.{payload_str}"
+    expected_sig = base64.b64encode(
+        hmac.new(key, to_sign.encode("utf-8"), hashlib.sha256).digest()
+    ).decode("ascii")
+
+    for versioned_sig in msg_signature.split(" "):
+        if "," not in versioned_sig:
+            continue
+        version, signature = versioned_sig.split(",", 1)
+        if version != "v1":
+            continue
+        if hmac.compare_digest(signature, expected_sig):
+            return
+
+    raise VerificationError("No matching signature found")

examples/python/meeting-agent/pipeline.py

@@ -0,0 +1,295 @@
+"""Meeting ingest pipeline — upload → transcribe → summarize → index.
+
+Uses PraisonAI-Tools meeting tools with lazy imports so the UI app stays
+lightweight at import time. Updates meeting metadata in SQLite between steps.
+Status lives in meeting metadata (tools layer), not in UI state.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import threading
+from contextlib import closing
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Serializes metadata read-modify-write. Webhooks are dispatched one-thread-each
+# (asyncio.to_thread), so concurrent transcript events would otherwise clobber
+# each other's appends. Reentrant so callers can hold it across their own
+# read + merge (see processor._upsert_live_transcript).
+_metadata_lock = threading.RLock()
+
+AUDIO_SUFFIXES = {".mp3", ".mp4", ".m4a", ".wav", ".webm", ".ogg", ".mpeg", ".mpga"}
+_MEETING_ID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    re.I,
+)
+
+
+def merge_meeting_metadata(meeting_id: str, patch: dict[str, Any]) -> dict[str, Any]:
+    """Merge keys into a meeting's metadata blob."""
+    from praisonai_tools.tools import meeting_tools as mt
+
+    with _metadata_lock:
+        record = mt.get_meeting.__wrapped__(meeting_id)
+        if "error" in record:
+            return record
+        meta = {**(record.get("metadata") or {}), **patch}
+        try:
+            with closing(mt._connect()) as conn, conn:
+                conn.execute(
+                    "UPDATE meetings SET metadata = ? WHERE meeting_id = ?",
+                    (json.dumps(meta, sort_keys=True), meeting_id),
+                )
+        except Exception as exc:  # noqa: BLE001
+            logger.error("merge_meeting_metadata failed: %s", exc)
+            return {"error": str(exc)}
+    return {"meeting_id": meeting_id, "metadata": meta}
+
+
+def _pipeline_from_transcribe(
+    meeting_id: str,
+    file_path: str,
+    meeting_title: str,
+) -> dict[str, Any]:
+    """Shared tail: transcribe → summarize → index for a known meeting_id."""
+    from praisonai_tools.tools.meeting_tools import (
+        extract_action_items,
+        index_meeting,
+        summarize_transcript,
+        transcribe_file,
+    )
+
+    path = Path(file_path)
+    if not path.exists():
+        merge_meeting_metadata(
+            meeting_id,
+            {"status": "failed", "error": f"File not found: {file_path}"},
+        )
+        return {"meeting_id": meeting_id, "error": f"File not found: {file_path}"}
+
+    merge_meeting_metadata(
+        meeting_id,
+        {"status": "transcribing", "file_path": str(path), "error": None},
+    )
+
+    transcript_result = transcribe_file.__wrapped__(str(path))
+    if "error" in transcript_result:
+        merge_meeting_metadata(
+            meeting_id,
+            {"status": "failed", "error": transcript_result["error"]},
+        )
+        return {"meeting_id": meeting_id, **transcript_result}
+
+    transcript = transcript_result.get("text", "")
+    segments = transcript_result.get("segments") or []
+    merge_meeting_metadata(
+        meeting_id,
+        {
+            "status": "summarizing",
+            "transcript": transcript,
+            "segments": segments,
+            "duration_seconds": transcript_result.get("duration_seconds"),
+            "language": transcript_result.get("language"),
+        },
+    )
+
+    summary_result = summarize_transcript.__wrapped__(transcript)
+    if "error" in summary_result:
+        merge_meeting_metadata(
+            meeting_id,
+            {"status": "failed", "error": summary_result["error"]},
+        )
+        return {"meeting_id": meeting_id, **summary_result}
+
+    actions_result = extract_action_items.__wrapped__(transcript)
+    if "error" in actions_result:
+        merge_meeting_metadata(
+            meeting_id,
+            {"status": "failed", "error": actions_result["error"]},
+        )
+        return {"meeting_id": meeting_id, **actions_result}
+
+    merge_meeting_metadata(
+        meeting_id,
+        {
+            "status": "indexing",
+            "summary": summary_result.get("summary", ""),
+            "decisions": summary_result.get("decisions", []),
+            "topics": summary_result.get("topics", []),
+            "key_quotes": summary_result.get("key_quotes", []),
+            "action_items": actions_result.get("action_items", []),
+        },
+    )
+
+    index_result = index_meeting.__wrapped__(
+        meeting_id,
+        transcript=transcript,
+        segments=segments,
+    )
+    if "error" in index_result:
+        merge_meeting_metadata(
+            meeting_id,
+            {"status": "failed", "error": index_result["error"]},
+        )
+        return {"meeting_id": meeting_id, **index_result}
+
+    merge_meeting_metadata(meeting_id, {"status": "ready", "error": None})
+
+    return {
+        "meeting_id": meeting_id,
+        "status": "ready",
+        "title": meeting_title,
+        "summary": summary_result.get("summary", ""),
+        "action_items": actions_result.get("action_items", []),
+        "chunks_indexed": index_result.get("chunks_indexed", 0),
+    }
+
+
+def run_ingest_pipeline(
+    file_path: str,
+    title: str | None = None,
+    *,
+    meeting_id: str | None = None,
+) -> dict[str, Any]:
+    """Run the full Phase 1 pipeline for an audio/video upload."""
+    from praisonai_tools.tools.meeting_tools import get_meeting, save_meeting
+
+    path = Path(file_path)
+    if not path.exists():
+        return {"error": f"File not found: {file_path}"}
+
+    meeting_title = (title or path.stem).strip() or "Untitled meeting"
+
+    if meeting_id:
+        record = get_meeting.__wrapped__(meeting_id)
+        if "error" in record:
+            return record
+        if title:
+            meeting_title = title
+        elif record.get("title"):
+            meeting_title = record["title"]
+    else:
+        saved = save_meeting.__wrapped__(
+            title=meeting_title,
+            source=str(path),
+            metadata={"status": "transcribing", "file_path": str(path)},
+        )
+        if "error" in saved:
+            return saved
+        meeting_id = saved["meeting_id"]
+
+    return _pipeline_from_transcribe(meeting_id, str(path), meeting_title)
+
+
+def run_post_transcript_pipeline(
+    meeting_id: str,
+    transcript: str,
+    *,
+    segments: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Run summarize → index for a Recall (or other) transcript without transcribe step."""
+    from praisonai_tools.tools.meeting_tools import (
+        extract_action_items,
+        get_meeting,
+        index_meeting,
+        summarize_transcript,
+    )
+
+    record = get_meeting.__wrapped__(meeting_id)
+    if "error" in record:
+        return record
+
+    meeting_title = record.get("title") or "Untitled meeting"
+    merge_meeting_metadata(
+        meeting_id,
+        {
+            "status": "summarizing",
+            "transcript": transcript,
+            "segments": segments or [],
+            "source": "recall",
+            "live_status": "ready",
+            "error": None,
+        },
+    )
+
+    summary_result = summarize_transcript.__wrapped__(transcript)
+    if "error" in summary_result:
+        merge_meeting_metadata(
+            meeting_id,
+            {"status": "failed", "error": summary_result["error"]},
+        )
+        return {"meeting_id": meeting_id, **summary_result}
+
+    actions_result = extract_action_items.__wrapped__(transcript)
+    if "error" in actions_result:
+        merge_meeting_metadata(
+            meeting_id,
+            {"status": "failed", "error": actions_result["error"]},
+        )
+        return {"meeting_id": meeting_id, **actions_result}
+
+    merge_meeting_metadata(
+        meeting_id,
+        {
+            "status": "indexing",
+            "summary": summary_result.get("summary", ""),
+            "decisions": summary_result.get("decisions", []),
+            "topics": summary_result.get("topics", []),
+            "key_quotes": summary_result.get("key_quotes", []),
+            "action_items": actions_result.get("action_items", []),
+        },
+    )
+
+    index_result = index_meeting.__wrapped__(
+        meeting_id,
+        transcript=transcript,
+        segments=segments or [],
+    )
+    if "error" in index_result:
+        merge_meeting_metadata(
+            meeting_id,
+            {"status": "failed", "error": index_result["error"]},
+        )
+        return {"meeting_id": meeting_id, **index_result}
+
+    merge_meeting_metadata(meeting_id, {"status": "ready", "error": None})
+
+    return {
+        "meeting_id": meeting_id,
+        "status": "ready",
+        "title": meeting_title,
+        "summary": summary_result.get("summary", ""),
+        "action_items": actions_result.get("action_items", []),
+        "chunks_indexed": index_result.get("chunks_indexed", 0),
+    }
+
+
+def retry_pipeline(meeting_id: str) -> dict[str, Any]:
+    """Re-run ingest for a failed meeting using its stored file path."""
+    if not meeting_id or not _MEETING_ID_RE.match(meeting_id):
+        return {"error": "invalid meeting_id", "meeting_id": meeting_id}
+
+    from praisonai_tools.tools.meeting_tools import get_meeting
+
+    record = get_meeting.__wrapped__(meeting_id)
+    if "error" in record:
+        return record
+
+    meta = record.get("metadata") or {}
+    file_path = meta.get("file_path") or record.get("source")
+    if not file_path:
+        return {
+            "meeting_id": meeting_id,
+            "error": "No uploaded file stored for this meeting",
+        }
+
+    return run_ingest_pipeline(
+        str(file_path),
+        title=record.get("title"),
+        meeting_id=meeting_id,
+    )

examples/python/meeting-agent/plugin.js

@@ -0,0 +1,57 @@
+/**
+ * Meeting Agent dashboard hooks — auto-refresh live transcript on meeting-detail.
+ */
+(function () {
+  'use strict';
+
+  let pollTimer = null;
+
+  function stopPolling() {
+    if (pollTimer) {
+      clearInterval(pollTimer);
+      pollTimer = null;
+    }
+  }
+
+  async function refreshLiveTranscript() {
+    const host = document.querySelector('[data-page="meeting-detail"]');
+    if (!host) return;
+
+    const code = host.querySelector('.db-code-block code');
+    if (!code) return;
+
+    try {
+      const meetingsRes = await fetch('/api/meetings');
+      if (!meetingsRes.ok) return;
+      const meetingsJson = await meetingsRes.json();
+      const meetings = meetingsJson.meetings || [];
+      const live = meetings.find((m) =>
+        ['live', 'joining', 'waiting_room'].includes(String(m.live_status || '').toLowerCase())
+      );
+      if (!live || !live.id) return;
+
+      const snapRes = await fetch(`/api/meetings/${live.id}/live-transcript`);
+      if (!snapRes.ok) return;
+      const snap = await snapRes.json();
+      const text = snap.transcript || '(empty)';
+      if (code.textContent !== text) {
+        code.textContent = text;
+      }
+    } catch (_err) {
+      /* ignore transient network errors */
+    }
+  }
+
+  function startPolling() {
+    stopPolling();
+    refreshLiveTranscript();
+    pollTimer = setInterval(refreshLiveTranscript, 3000);
+  }
+
+  window.addEventListener('aiui:page-change', (event) => {
+    stopPolling();
+    if (event.detail && event.detail.pageId === 'meeting-detail') {
+      startPolling();
+    }
+  });
+})();

examples/python/meeting-agent/poll_live_transcript.ps1

@@ -0,0 +1,61 @@
+# Poll live transcript for a meeting (Part B dev test).
+# Usage:
+#   .\poll_live_transcript.ps1
+#   .\poll_live_transcript.ps1 -MeetingId "aecf34bc-7194-4123-9c67-a298b56011da"
+#   .\poll_live_transcript.ps1 -IntervalSec 2
+
+param(
+    [string]$MeetingId = "",
+    [int]$Port = 8000,
+    [int]$IntervalSec = 3
+)
+
+$ErrorActionPreference = "Stop"
+$base = "http://127.0.0.1:$Port"
+
+if (-not $MeetingId) {
+    $meetings = Invoke-RestMethod -Uri "$base/api/meetings"
+    $live = $meetings.meetings | Where-Object { @("live","joining","waiting_room") -contains ($_.live_status).ToLower() } | Select-Object -First 1
+    if ($live) {
+        $MeetingId = $live.id
+    } elseif ($meetings.meetings.Count -gt 0) {
+        $MeetingId = $meetings.meetings[0].id
+    } else {
+        throw "No meetings found. Schedule a bot first."
+    }
+}
+
+$url = "$base/api/meetings/$MeetingId/live-transcript"
+
+Write-Host "Polling $url every ${IntervalSec}s (Ctrl+C to stop)"
+Write-Host ""
+
+$lastCount = -1
+$lastText = ""
+
+while ($true) {
+    try {
+        $r = Invoke-RestMethod -Uri $url -TimeoutSec 10
+        $count = [int]$r.line_count
+        $status = $r.live_status
+        $text = [string]$r.transcript
+
+        if ($count -ne $lastCount -or $text -ne $lastText) {
+            $ts = Get-Date -Format "HH:mm:ss"
+            Write-Host "[$ts] live_status=$status  lines=$count"
+            if ($text) {
+                Write-Host "---"
+                Write-Host $text
+                Write-Host "---"
+            } else {
+                Write-Host "(empty transcript)"
+            }
+            Write-Host ""
+            $lastCount = $count
+            $lastText = $text
+        }
+    } catch {
+        Write-Host "[$(Get-Date -Format 'HH:mm:ss')] ERROR: $($_.Exception.Message)"
+    }
+    Start-Sleep -Seconds $IntervalSec
+}

examples/python/meeting-agent/recall_routes.py

@@ -0,0 +1,337 @@
+"""Recall.ai HTTP routes for the meeting-agent example."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from typing import Any
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse, PlainTextResponse, Response, StreamingResponse
+
+from meeting_integrations.recall.calendar import forward_calendar_callback
+from meeting_integrations.recall.calendar_service import (
+    list_upcoming_calendar_meetings,
+    process_calendar_webhook,
+    sync_calendar_events,
+)
+from meeting_integrations.recall.config import RecallConfigError, load_recall_settings
+from meeting_integrations.recall.live import snapshot_for_api, wait_for_update
+from meeting_integrations.recall.processor import process_recall_webhook
+from meeting_integrations.recall.service import cancel_recall_bot, schedule_recall_bot
+from meeting_integrations.recall.store import RecallStore
+from meeting_integrations.recall.verify import VerificationError, verify_request_from_recall
+
+logger = logging.getLogger(__name__)
+
+_calendar_regional_uri: str | None = None
+
+# asyncio keeps only weak references to tasks, so a bare create_task() can be
+# garbage-collected mid-flight and silently drop a webhook event. Hold a strong
+# reference until each background task finishes.
+_background_tasks: set[asyncio.Task] = set()
+
+
+def _dispatch_background(coro) -> None:
+    task = asyncio.create_task(coro)
+    _background_tasks.add(task)
+    task.add_done_callback(_background_tasks.discard)
+
+
+def set_calendar_regional_callback_uri(uri: str | None) -> None:
+    global _calendar_regional_uri
+    _calendar_regional_uri = uri
+
+
+async def api_recall_schedule_bot(request: Request) -> JSONResponse:
+    try:
+        body = await request.json()
+    except json.JSONDecodeError:
+        return JSONResponse({"error": "invalid JSON body"}, status_code=400)
+
+    meeting_url = str(body.get("meeting_url") or "").strip()
+    title = str(body.get("title") or "").strip()
+    join_at = body.get("join_at")
+    join_at_str = str(join_at).strip() if join_at else None
+
+    result = await asyncio.to_thread(
+        schedule_recall_bot,
+        meeting_url,
+        title,
+        join_at=join_at_str,
+    )
+    status = 201 if result.get("recall_bot_id") else 400 if "error" in result else 500
+    return JSONResponse(result, status_code=status)
+
+
+async def api_recall_cancel_bot(request: Request) -> JSONResponse:
+    meeting_id = request.path_params["meeting_id"]
+    result = await asyncio.to_thread(cancel_recall_bot, meeting_id)
+    status = 200 if "error" not in result else 400
+    return JSONResponse(result, status_code=status)
+
+
+async def api_recall_bot_status(request: Request) -> JSONResponse:
+    meeting_id = request.path_params["meeting_id"]
+    try:
+        from praisonai_tools.tools.meeting_tools import get_meeting
+
+        record = get_meeting.__wrapped__(meeting_id)
+    except ImportError:
+        return JSONResponse({"error": "meeting tools unavailable"}, status_code=503)
+    if "error" in record:
+        return JSONResponse(record, status_code=404)
+    meta = record.get("metadata") or {}
+    return JSONResponse(
+        {
+            "meeting_id": meeting_id,
+            "title": record.get("title"),
+            "status": meta.get("status"),
+            "live_status": meta.get("live_status"),
+            "recall_bot_id": meta.get("recall_bot_id"),
+            "meeting_url": meta.get("meeting_url"),
+            "transcript_preview": (meta.get("transcript") or "")[:500],
+        }
+    )
+
+
+async def webhook_recall(request: Request) -> Response:
+    raw = (await request.body()).decode("utf-8")
+    try:
+        settings = load_recall_settings()
+    except RecallConfigError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=503)
+
+    headers = {k: v for k, v in request.headers.items()}
+    try:
+        verify_request_from_recall(
+            secret=settings.webhook_verification_secret,
+            headers=headers,
+            payload=raw,
+        )
+    except VerificationError:
+        return JSONResponse({"error": "invalid signature"}, status_code=401)
+
+    try:
+        payload = json.loads(raw) if raw else {}
+    except json.JSONDecodeError:
+        return JSONResponse({"error": "invalid JSON"}, status_code=400)
+
+    event_type = str(payload.get("event") or payload.get("type") or "unknown")
+    if event_type.startswith("calendar."):
+        _dispatch_background(
+            asyncio.to_thread(
+                process_calendar_webhook,
+                event_type,
+                payload,
+                settings=settings,
+            )
+        )
+        return PlainTextResponse("ok", status_code=200)
+
+    _dispatch_background(
+        asyncio.to_thread(process_recall_webhook, event_type, payload, settings=settings)
+    )
+    return PlainTextResponse("ok", status_code=200)
+
+
+async def api_recall_calendar_callback(request: Request) -> Response:
+    if not _calendar_regional_uri:
+        return JSONResponse(
+            {
+                "error": "Calendar callback not configured. Bootstrap setup via "
+                "POST /api/recall/calendar/setup/bootstrap with regional_callback_uri "
+                "from Recall MCP start_calendar_integration_setup."
+            },
+            status_code=503,
+        )
+    params = dict(request.query_params)
+    status, body = await asyncio.to_thread(
+        forward_calendar_callback,
+        regional_callback_uri=_calendar_regional_uri,
+        query_params=params,
+    )
+    return PlainTextResponse(body, status_code=status)
+
+
+async def api_recall_calendar_bootstrap(request: Request) -> JSONResponse:
+    try:
+        body = await request.json()
+    except json.JSONDecodeError:
+        return JSONResponse({"error": "invalid JSON"}, status_code=400)
+
+    setup_id = str(body.get("setup_id") or "").strip()
+    platform = str(body.get("platform") or "google_calendar").strip()
+    regional_uri = str(body.get("regional_callback_uri") or "").strip()
+    state = body.get("state") if isinstance(body.get("state"), dict) else {}
+
+    if not setup_id or not regional_uri:
+        return JSONResponse(
+            {"error": "setup_id and regional_callback_uri are required"},
+            status_code=400,
+        )
+
+    set_calendar_regional_callback_uri(regional_uri)
+    RecallStore.save_calendar_setup(
+        setup_id,
+        platform,
+        {
+            **state,
+            "regional_callback_uri": regional_uri,
+            "platform": platform,
+        },
+    )
+    callback_url = "(set PUBLIC_API_BASE_URL)"
+    if os.getenv("PUBLIC_API_BASE_URL", "").strip():
+        try:
+            callback_url = load_recall_settings().calendar_callback_url
+        except RecallConfigError:
+            pass
+    return JSONResponse(
+        {
+            "setup_id": setup_id,
+            "callback_url": callback_url,
+            "status": "bootstrapped",
+        }
+    )
+
+
+async def api_recall_calendar_status(_request: Request) -> JSONResponse:
+    auto_record = os.getenv("CALENDAR_AUTO_RECORD", "true").strip().lower() not in {
+        "0",
+        "false",
+        "no",
+        "off",
+    }
+    public_url = os.getenv("PUBLIC_API_BASE_URL", "").strip()
+    calendars: list[dict[str, Any]] = []
+    try:
+        from meeting_integrations.recall.client import RecallClient
+
+        settings = load_recall_settings()
+        calendars = RecallClient(settings).list_calendars(status="connected")
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("Could not list calendars: %s", exc)
+
+    return JSONResponse(
+        {
+            "calendar_v2": {
+                "auto_record_eligible_events": auto_record,
+                "connected_calendars": len(calendars),
+                "calendars": [
+                    {
+                        "id": c.get("id"),
+                        "platform": c.get("platform"),
+                        "email": c.get("platform_email") or c.get("email"),
+                        "status": c.get("status"),
+                    }
+                    for c in calendars
+                    if isinstance(c, dict)
+                ],
+                "callback_configured": bool(_calendar_regional_uri),
+                "public_api_base_url_set": bool(public_url),
+                "webhook_events": ["calendar.sync_events", "calendar.update"],
+                "next_step": (
+                    "Register calendar webhooks on the same /webhooks/recall URL, "
+                    "then complete Google Calendar V2 OAuth via Recall MCP."
+                ),
+            }
+        }
+    )
+
+
+async def api_recall_calendar_upcoming(request: Request) -> JSONResponse:
+    hours = int(request.query_params.get("hours", "24"))
+    try:
+        rows = await asyncio.to_thread(list_upcoming_calendar_meetings, hours=hours)
+    except RecallConfigError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=503)
+    except Exception as exc:  # noqa: BLE001
+        return JSONResponse({"error": str(exc)}, status_code=502)
+    return JSONResponse({"events": rows, "hours": hours})
+
+
+async def api_recall_calendar_sync(request: Request) -> JSONResponse:
+    try:
+        body = await request.json()
+    except json.JSONDecodeError:
+        body = {}
+    calendar_id = str(body.get("calendar_id") or request.query_params.get("calendar_id") or "").strip()
+    if not calendar_id:
+        return JSONResponse({"error": "calendar_id is required"}, status_code=400)
+    try:
+        settings = load_recall_settings()
+        result = await asyncio.to_thread(
+            sync_calendar_events,
+            calendar_id,
+            updated_since=body.get("updated_at__gte"),
+            settings=settings,
+        )
+    except RecallConfigError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=503)
+    except Exception as exc:  # noqa: BLE001
+        return JSONResponse({"error": str(exc)}, status_code=502)
+    return JSONResponse(result)
+
+
+async def api_meeting_live_transcript(request: Request) -> Response:
+    meeting_id = request.path_params["meeting_id"]
+    accept = request.headers.get("accept", "")
+    try:
+        from praisonai_tools.tools.meeting_tools import get_meeting
+
+        record = get_meeting.__wrapped__(meeting_id)
+    except ImportError:
+        return JSONResponse({"error": "meeting tools unavailable"}, status_code=503)
+    if "error" in record:
+        return JSONResponse(record, status_code=404)
+
+    if "text/event-stream" not in accept:
+        return JSONResponse(snapshot_for_api(meeting_id, record))
+
+    async def event_stream():
+        last_text = ""
+        while True:
+            try:
+                from praisonai_tools.tools.meeting_tools import get_meeting
+
+                record = get_meeting.__wrapped__(meeting_id)
+            except ImportError:
+                break
+            snap = snapshot_for_api(meeting_id, record)
+            text = snap.get("transcript") or ""
+            live = (snap.get("live_status") or "").lower()
+            if text != last_text:
+                yield f"data: {json.dumps(snap)}\n\n"
+                last_text = text
+            if live not in ("live", "joining", "waiting_room", "scheduled", ""):
+                break
+            await asyncio.to_thread(wait_for_update, meeting_id, 25.0)
+
+    return StreamingResponse(event_stream(), media_type="text/event-stream")
+
+
+async def api_recall_config_status(_request: Request) -> JSONResponse:
+    try:
+        settings = load_recall_settings()
+        configured = True
+    except RecallConfigError as exc:
+        settings = None
+        configured = False
+        error = str(exc)
+    else:
+        error = None
+
+    return JSONResponse(
+        {
+            "configured": configured,
+            "error": error,
+            "region": settings.region if settings else os.getenv("RECALL_REGION"),
+            "workspace_id": settings.workspace_id if settings else None,
+            "webhook_url": settings.webhook_url if settings and settings.public_api_base_url else None,
+            "bot_name": settings.bot_name if settings else None,
+        }
+    )
+

examples/python/meeting-agent/recover_recall_meeting.py

@@ -0,0 +1,133 @@
+"""Recover a Recall meeting when webhooks missed (stale tunnel URL).
+
+Usage:
+    py -3.13 recover_recall_meeting.py <meeting_id> [bot_id]
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+_EXAMPLE_DIR = Path(__file__).resolve().parent
+if str(_EXAMPLE_DIR) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLE_DIR))
+
+
+def _load_env() -> None:
+    import os
+
+    env_path = _EXAMPLE_DIR / ".env"
+    if not env_path.is_file():
+        return
+    for raw in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip()
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+def _duration_seconds(started_at: str | None, completed_at: str | None) -> int | None:
+    if not started_at or not completed_at:
+        return None
+    try:
+        fmt = "%Y-%m-%dT%H:%M:%S.%f%z"
+        start = datetime.strptime(started_at.replace("Z", "+0000"), fmt)
+        end = datetime.strptime(completed_at.replace("Z", "+0000"), fmt)
+        return int((end - start).total_seconds())
+    except (TypeError, ValueError):
+        return None
+
+
+def recover(meeting_id: str, bot_id: str | None = None) -> dict:
+    from meeting_integrations.recall.client import RecallClient
+    from meeting_integrations.recall.config import load_recall_settings
+    from meeting_integrations.recall.transcript import transcript_download_to_text
+    from pipeline import merge_meeting_metadata, run_post_transcript_pipeline
+    from praisonai_tools.tools.meeting_tools import get_meeting
+
+    _load_env()
+    settings = load_recall_settings()
+    client = RecallClient(settings)
+
+    record = get_meeting.__wrapped__(meeting_id)
+    if "error" in record:
+        raise SystemExit(record["error"])
+
+    meta = record.get("metadata") or {}
+    bot_id = bot_id or meta.get("recall_bot_id")
+    if not bot_id:
+        raise SystemExit("No recall_bot_id — pass bot_id as second argument")
+
+    bot = client.get_bot(str(bot_id))
+    recordings = bot.get("recordings") or []
+    if not recordings:
+        raise SystemExit("Bot has no recordings yet")
+
+    rec_wrap = recordings[0].get("recording") or recordings[0]
+    recording_id = rec_wrap.get("id")
+    if not recording_id:
+        raise SystemExit("Missing recording id on bot")
+
+    duration = _duration_seconds(rec_wrap.get("started_at"), rec_wrap.get("completed_at"))
+    merge_meeting_metadata(
+        meeting_id,
+        {
+            "recall_bot_id": bot_id,
+            "recall_recording_id": recording_id,
+            "live_status": "processing",
+            "status": "transcribing",
+            **({"duration_seconds": duration} if duration else {}),
+        },
+    )
+
+    transcript_id = None
+    for _ in range(30):
+        bot = client.get_bot(str(bot_id))
+        recs = bot.get("recordings") or []
+        if recs:
+            rec = recs[0].get("recording") or recs[0]
+            shortcuts = rec.get("media_shortcuts") or {}
+            tr = shortcuts.get("transcript")
+            if isinstance(tr, dict) and tr.get("id"):
+                transcript_id = str(tr["id"])
+                break
+            artifacts = recs[0].get("transcript_artifacts") or rec.get("transcript_artifacts") or []
+            if artifacts:
+                transcript_id = str(artifacts[0].get("id") or "")
+                if transcript_id:
+                    break
+        if not transcript_id:
+            print("Starting async transcript…")
+            client.create_async_transcript(str(recording_id))
+            time.sleep(10)
+        else:
+            break
+
+    if not transcript_id:
+        raise SystemExit("Timed out waiting for transcript — webhook may still deliver it")
+
+    artifact = client.get_transcript(transcript_id)
+    download_url = (artifact.get("data") or {}).get("download_url")
+    if not download_url:
+        raise SystemExit("Transcript ready but no download_url")
+
+    raw = client.download_json(download_url)
+    text = transcript_download_to_text(raw)
+    if not text.strip():
+        raise SystemExit("Transcript download was empty")
+
+    result = run_post_transcript_pipeline(meeting_id, text)
+    print("Recovered:", result)
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        raise SystemExit("Usage: recover_recall_meeting.py <meeting_id> [bot_id]")
+    recover(sys.argv[1], sys.argv[2] if len(sys.argv) > 2 else None)

examples/python/meeting-agent/smoke_recall.py

@@ -0,0 +1,87 @@
+"""Non-binding smoke checks for Recall integration boundaries."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+from starlette.testclient import TestClient
+
+_EXAMPLE_DIR = Path(__file__).resolve().parent
+_REPO_SRC = _EXAMPLE_DIR.parents[2] / "src"
+for _p in (_EXAMPLE_DIR, str(_REPO_SRC)):
+    if str(_p) not in sys.path:
+        sys.path.insert(0, str(_p))
+
+
+def _sign_payload(secret: str, body: str) -> dict[str, str]:
+    key = base64.b64decode(secret.removeprefix("whsec_"))
+    msg_id = "msg_smoke_test"
+    timestamp = "1700000000"
+    to_sign = f"{msg_id}.{timestamp}.{body}"
+    signature = base64.b64encode(
+        hmac.new(key, to_sign.encode("utf-8"), hashlib.sha256).digest()
+    ).decode("ascii")
+    return {
+        "webhook-id": msg_id,
+        "webhook-timestamp": timestamp,
+        "webhook-signature": f"v1,{signature}",
+    }
+
+
+def run_smoke() -> None:
+    os.environ.setdefault("RECALL_REGION", "eu-central-1")
+    os.environ.setdefault("RECALL_API_KEY", "smoke-test-key")
+    os.environ.setdefault("RECALL_WEBHOOK_VERIFICATION_SECRET", "whsec_" + base64.b64encode(b"smoke-secret-key-32-bytes-long!!").decode())
+    os.environ.setdefault("RECALL_WORKSPACE_ID", "smoke-workspace")
+    os.environ.setdefault("PUBLIC_API_BASE_URL", "https://smoke.example.test")
+
+    import app as meeting_app  # noqa: WPS433
+    from meeting_integrations.recall.config import load_recall_settings
+    from meeting_integrations.recall.verify import verify_request_from_recall
+
+    settings = load_recall_settings()
+    assert settings.api_key == "smoke-test-key"
+
+    body = json.dumps({"event": "bot.joining_call", "data": {"bot": {"id": "b1", "metadata": {"meeting_id": "m1"}}}})
+    headers = _sign_payload(settings.webhook_verification_secret, body)
+    verify_request_from_recall(
+        secret=settings.webhook_verification_secret,
+        headers=headers,
+        payload=body,
+    )
+
+    client = TestClient(meeting_app.app)
+    assert client.get("/health").status_code == 200
+
+    bad = client.post("/webhooks/recall", content=body, headers={"webhook-id": "x"})
+    assert bad.status_code == 401
+
+    ok = client.post("/webhooks/recall", content=body, headers=headers)
+    assert ok.status_code == 200
+
+    with patch(
+        "recall_routes.schedule_recall_bot",
+        return_value={
+            "meeting_id": "m-smoke",
+            "recall_bot_id": "bot-smoke",
+            "status": "scheduled",
+        },
+    ):
+        schedule = client.post(
+            "/api/recall/bots",
+            json={"meeting_url": "https://zoom.us/j/123", "title": "Smoke"},
+        )
+    assert schedule.status_code == 201
+
+    print("Recall smoke checks passed")
+
+
+if __name__ == "__main__":
+    run_smoke()

examples/python/meeting-agent/start_dev.ps1

@@ -0,0 +1,112 @@
+# Start meeting-agent (Part B) + Cloudflare tunnel for Recall webhooks.
+# Usage: .\start_dev.ps1
+# Optional: $env:TEST_MEETING_URL = "https://meet.google.com/..." ; .\start_dev.ps1 -ScheduleBot
+
+param(
+    [switch]$ScheduleBot,
+    [string]$MeetingUrl = $env:TEST_MEETING_URL,
+    [int]$Port = 8000
+)
+
+$ErrorActionPreference = "Stop"
+$Root = Split-Path -Parent $MyInvocation.MyCommand.Path
+Set-Location $Root
+
+function Load-DotEnv {
+    $envFile = Join-Path $Root ".env"
+    if (-not (Test-Path $envFile)) { return }
+    Get-Content $envFile | ForEach-Object {
+        $line = $_.Trim()
+        if (-not $line -or $line.StartsWith("#") -or $line -notmatch "=") { return }
+        $key, $value = $line -split "=", 2
+        if ($key -and -not [string]::IsNullOrWhiteSpace($key) -and -not (Get-Item "Env:$key" -ErrorAction SilentlyContinue)) {
+            Set-Item -Path "Env:$key" -Value $value.Trim()
+        }
+    }
+}
+
+function Test-PortListening([int]$p) {
+    try {
+        $r = Invoke-WebRequest -Uri "http://127.0.0.1:$p/api/recall/config" -UseBasicParsing -TimeoutSec 2
+        return $r.StatusCode -eq 200
+    } catch { return $false }
+}
+
+function Update-PublicUrl([string]$baseUrl) {
+    $envFile = Join-Path $Root ".env"
+    $content = Get-Content $envFile -Raw
+    if ($content -match "PUBLIC_API_BASE_URL=.*") {
+        $newContent = $content -replace "PUBLIC_API_BASE_URL=.*", "PUBLIC_API_BASE_URL=$baseUrl"
+    } else {
+        $newContent = $content.TrimEnd() + "`nPUBLIC_API_BASE_URL=$baseUrl`n"
+    }
+    Set-Content -Path $envFile -Value $newContent -NoNewline
+    $env:PUBLIC_API_BASE_URL = $baseUrl
+    Write-Host "Updated .env PUBLIC_API_BASE_URL=$baseUrl"
+}
+
+Load-DotEnv
+$env:MEETING_AGENT_PORT = "$Port"
+
+if (-not (Test-PortListening $Port)) {
+    Write-Host "Starting meeting-agent on port $Port..."
+    Start-Process -FilePath "py" -ArgumentList "-3.13", "app.py" -WorkingDirectory $Root -WindowStyle Minimized
+    $deadline = (Get-Date).AddSeconds(45)
+    while ((Get-Date) -lt $deadline) {
+        if (Test-PortListening $Port) { break }
+        Start-Sleep -Seconds 2
+    }
+    if (-not (Test-PortListening $Port)) {
+        throw "App did not become ready on http://127.0.0.1:$Port"
+    }
+    Write-Host "App ready: http://127.0.0.1:$Port"
+} else {
+    Write-Host "App already running on port $Port"
+}
+
+$public = $env:PUBLIC_API_BASE_URL
+try {
+    $null = Invoke-WebRequest -Uri "$public/api/recall/config" -UseBasicParsing -TimeoutSec 5
+    Write-Host "Tunnel OK: $public"
+} catch {
+    Write-Host "Starting Cloudflare tunnel (quick tunnel - URL may change)..."
+    $log = Join-Path $Root ".tunnel.log"
+    $logErr = "${log}.err"
+    if (Test-Path $log) { Remove-Item $log -Force }
+    if (Test-Path $logErr) { Remove-Item $logErr -Force }
+    Start-Process -FilePath "cloudflared" -ArgumentList "tunnel", "--url", "http://127.0.0.1:$Port" `
+        -RedirectStandardOutput $log -RedirectStandardError $logErr -WindowStyle Minimized
+    $deadline = (Get-Date).AddSeconds(90)
+    $newUrl = $null
+    while ((Get-Date) -lt $deadline -and -not $newUrl) {
+        Start-Sleep -Seconds 2
+        foreach ($path in @($logErr, $log)) {
+            if (-not (Test-Path $path)) { continue }
+            $match = Select-String -Path $path -Pattern "https://[a-z0-9-]+\.trycloudflare\.com" | Select-Object -First 1
+            if ($match) {
+                $newUrl = $match.Matches[0].Value
+                break
+            }
+        }
+    }
+    if (-not $newUrl) { throw "Could not read tunnel URL from $logErr (or $log). Check cloudflared is installed." }
+    Update-PublicUrl $newUrl
+    Write-Host "Tunnel ready: $newUrl"
+    Write-Host "If Recall webhook URL changed, update it in Recall dashboard Webhooks"
+}
+
+$config = Invoke-RestMethod -Uri "http://127.0.0.1:$Port/api/recall/config"
+Write-Host "Recall configured: $($config.configured)"
+
+if ($ScheduleBot) {
+    if (-not $MeetingUrl) {
+        Write-Host "No TEST_MEETING_URL - skip bot schedule. Set env TEST_MEETING_URL or pass -MeetingUrl"
+    } else {
+        $body = @{ meeting_url = $MeetingUrl; title = "Part B live transcript test" } | ConvertTo-Json
+        $result = Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:$Port/api/recall/bots" `
+            -ContentType "application/json" -Body $body
+        Write-Host "Bot scheduled:" ($result | ConvertTo-Json -Compress)
+    }
+}
+
+Write-Host "Done. Dashboard: http://127.0.0.1:$Port"

examples/python/voice-agent/.env.example

@@ -0,0 +1,51 @@
+# Voice Agent — local secrets. Never commit.
+
+OPENAI_API_KEY=
+
+VOICE_AGENT_PORT=8001
+
+# LLM for voice assistant (synced to provider on setup / start_dev)
+VOICE_AGENT_MODEL=gpt-4o-mini
+
+# Voice telephony provider
+VOICE_API_BASE=
+VOICE_PRIVATE_API_KEY=
+VOICE_PUBLIC_API_KEY=
+VOICE_SERVER_URL_SECRET=
+VOICE_ASSISTANT_ID=
+VOICE_PHONE_NUMBER_ID=
+
+# Phase 2 — browser web talk (provider web SDK)
+# VOICE_WEB_SDK_URL=https://esm.sh/@vapi-ai/[email protected]
+# VOICE_WEB_SDK_GLOBAL=VoiceWebClient
+
+# Dynamic assistant (assistant-request returns inline config + agent tools)
+# VOICE_DYNAMIC_ASSISTANT=true
+# VOICE_AGENT_EXTRA_TOOLS=meeting_search
+
+# ElevenLabs Speech Engine — OpenAI tool calling on the sidecar LLM path
+# VOICE_SPEECH_USE_TOOLS=true
+
+# Cross-call memory — stable browser user id → PraisonAI session reload
+# VOICE_MEMORY_ENABLED=true
+# VOICE_MEMORY_HISTORY_LIMIT=20
+# VOICE_MEMORY_USE_KNOWLEDGE=true
+
+# OpenAI Realtime (browser speech-to-speech — higher audio token cost; keep demos short)
+# REALTIME_MODEL=gpt-realtime-2.1-mini
+# REALTIME_VOICE=marin
+# REALTIME_REASONING_EFFORT=low
+# REALTIME_INSTRUCTIONS=You are a helpful voice assistant. Keep replies to one or two short sentences.
+# REALTIME_FIRST_MESSAGE=
+
+# ElevenLabs Speech Engine (Phase 3 — browser voice, BYO LLM)
+# ELEVENLABS_API_KEY=
+# SPEECH_ENGINE_ID=          # auto-written by setup_speech_engine.py
+# SPEECH_ENGINE_PUBLIC_URL=  # auto-written — dedicated tunnel for sidecar :8002
+# SPEECH_ENGINE_PORT=8002
+# SPEECH_ENGINE_FIRST_MESSAGE=Hello! How can I help you today?
+# ELEVENLABS_VOICE_ID=          # Praison/custom voice from ElevenLabs dashboard
+
+# Public HTTPS URL for provider webhook (Cloudflare tunnel)
+# cloudflared tunnel --url http://127.0.0.1:8001
+PUBLIC_API_BASE_URL=

examples/python/voice-agent/README.md

@@ -0,0 +1,118 @@
+# Voice Agent example — PraisonAIUI
+
+Phone and web voice agents using an external telephony/voice platform for STT/TTS/calls and PraisonAI for tools + dashboard.
+
+## Quick start
+
+```powershell
+cd examples/python/voice-agent
+copy .env.example .env
+# Fill VOICE_API_BASE, VOICE_PRIVATE_API_KEY, VOICE_ASSISTANT_ID, etc.
+
+# Fully automatic (app + tunnel + provider config):
+.\setup_all.ps1
+
+# Or step by step:
+.\start_dev.ps1
+```
+
+Dashboard: http://127.0.0.1:8001
+
+## Provider setup
+
+1. Create an **assistant** with tools `get_current_time` and `echo_message`
+2. Set **webhook URL** to `{PUBLIC_API_BASE_URL}/webhooks/voice`
+3. Set **webhook secret header** `X-Voice-Webhook-Secret` → same as `VOICE_SERVER_URL_SECRET` in `.env`
+4. Add a phone number and copy `VOICE_PHONE_NUMBER_ID`
+
+Or run `py -3.13 setup_voice_provider.py` after `start_dev.ps1`.
+
+## API
+
+| Route | Method | Purpose |
+|-------|--------|---------|
+| `/api/voice/calls` | POST | Outbound call `{ "customer_number": "+1..." }` |
+| `/api/voice/calls` | GET | List stored calls |
+| `/api/voice/calls/{id}` | GET | Call detail + transcript |
+| `/api/voice/calls/{id}/live-transcript` | GET | SSE live transcript stream |
+| `/api/voice/web-config` | GET | Browser talk widget config |
+| `/webhooks/voice` | POST | Provider webhooks (tool-calls, transcript, end-of-call) |
+| `/api/voice/config` | GET | Config status |
+| `/api/voice/doctor` | GET | Voice stack health checks (.env, ports, APIs, tunnel) |
+
+## Phase 2 features
+
+- **Live transcript** — `GET /api/voice/calls/{id}/live-transcript` (SSE); **Call detail** page uses `plugin.js` + EventSource
+- **Dynamic assistant** — set `VOICE_DYNAMIC_ASSISTANT=true` so `assistant-request` returns inline config with agent tool names
+- **Agent tools** — `tool-calls` run through `integrations/voice/agent_runner.py` (same registry as dashboard chat)
+- **Web talk** — **Web talk** page loads provider web SDK from `VOICE_WEB_SDK_URL` / `VOICE_WEB_SDK_GLOBAL`
+- **Chat bridge** — final transcript lines and end-of-call summaries appear in **Chat** sidebar as `📞 Call …` sessions
+
+Optional: `VOICE_AGENT_EXTRA_TOOLS=meeting_search` adds meeting search when `praisonai_tools` is installed.
+
+## Cross-call memory (PraisonAI sessions)
+
+Stable browser `voice-user-id` (localStorage) maps to `voice-user-{id}` PraisonAI session folder. Prior turns reload on new calls/restarts when `VOICE_MEMORY_ENABLED=true` (default).
+
+| Route | Purpose |
+|-------|---------|
+| `/api/voice/memory/attach-user` | ElevenLabs — attach user before conversation starts |
+| `/api/voice/memory/bind` | Bind `call_id` + `user_id` |
+| `/api/voice/memory/resolve?user_id=` | Resolve Praison session id |
+
+Knowledge base entries are injected into voice prompts when available.
+
+## Call detail UI (PraisonAIUI components)
+
+Call detail uses server-built components (`code_block`, `badge`, `key_value_list`, `tabs`) via `GET /api/voice/calls/{id}/ui`. Live SSE updates the transcript code block. Mic/WebRTC talk pages still use minimal `plugin.js`.
+
+## End-of-call summary & analytics
+
+When a session ends (ElevenLabs, GPT Realtime, or telephony webhook), `integrations/voice/call_finalize.py`:
+
+- Generates a one-sentence summary (OpenAI) when the provider did not send one
+- Stores **duration** and **turn count** in call metadata
+- Posts the summary to the **Chat** sidebar via the chat bridge
+
+**Voice calls** table shows Duration and Turns. **Config** page runs the voice doctor (`GET /api/voice/doctor` or `py -3.13 doctor.py`).
+
+## MCP manager
+
+The dashboard **MCP** page lists configured Model Context Protocol servers (`GET /api/mcp/servers`) and supports connect/disconnect from the UI.
+
+## Phase 3 — ElevenLabs Speech Engine
+
+Bring-your-own-LLM browser voice ([Speech Engine docs](https://elevenlabs.io/docs/overview/capabilities/speech-engine)):
+
+```powershell
+pip install -r requirements-voice.txt
+# Add ELEVENLABS_API_KEY to .env
+.\start_dev.ps1 -Restart
+```
+
+- **ElevenLabs talk** page — WebRTC client, token from `/api/voice/speech-engine/token`
+- **Speech Engine sidecar** (`speech_engine_sidecar.py` on port **8002**) — official SDK WebSocket server
+- **Dedicated tunnel** — `SPEECH_ENGINE_PUBLIC_URL` → `wss://…/ws` (separate from dashboard tunnel)
+- **`setup_speech_engine.py`** — registers the public WebSocket URL with ElevenLabs
+
+| Route | Purpose |
+|-------|---------|
+| `/api/voice/speech-engine/config` | Client config |
+| `/api/voice/speech-engine/token` | Browser conversation token |
+| `/ws` | Speech Engine WebSocket (ElevenLabs → your server) |
+
+## Architecture
+
+External platform handles voice pipeline (phone, STT, TTS, turn-taking). This app handles:
+
+- **tool-calls** → PraisonAI agent tools (`integrations/voice/agent_runner.py`)
+- **transcript** / **end-of-call-report** → SQLite store, SSE hub, chat bridge
+- **assistant-request** → default `VOICE_ASSISTANT_ID` or dynamic inline assistant
+
+Same pattern as `examples/python/meeting-agent` (Recall webhooks).
+
+## Tests
+
+```bash
+pytest tests/unit/test_voice_agent.py -v
+```

examples/python/voice-agent/app.py

@@ -0,0 +1,285 @@
+"""Voice Agent — PraisonAIUI example with telephony webhooks.
+
+  - Outbound calls     → POST /api/voice/calls
+  - Provider webhooks  → POST /webhooks/voice (tool-calls, transcript, end-of-call)
+  - Dashboard          → Calls list + live call detail + web talk + chat bridge
+
+Run:
+    cd examples/python/voice-agent
+    pip install httpx
+    copy .env.example .env
+    .\\start_dev.ps1
+    python app.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import praisonaiui as aiui
+from praisonaiui.server import create_app
+from starlette.routing import Route, WebSocketRoute
+
+from memory_routes import (
+    api_voice_memory_attach_user,
+    api_voice_memory_bind,
+    api_voice_memory_config,
+    api_voice_memory_for_call,
+    api_voice_memory_resolve,
+)
+from realtime_routes import (
+    api_realtime_config,
+    api_realtime_end,
+    api_realtime_new_call,
+    api_realtime_session,
+    api_realtime_transcript,
+)
+from speech_engine_routes import (
+    api_speech_engine_config,
+    api_speech_engine_token,
+    speech_engine_websocket,
+)
+from voice_routes import (
+    api_voice_call_detail,
+    api_voice_call_detail_ui,
+    api_voice_config_status,
+    api_voice_create_call,
+    api_voice_doctor,
+    api_voice_list_calls,
+    api_voice_live_transcript,
+    api_voice_web_config,
+    webhook_voice,
+)
+
+_EXAMPLE_DIR = Path(__file__).resolve().parent
+if str(_EXAMPLE_DIR) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLE_DIR))
+
+
+def _load_local_env() -> None:
+    env_path = _EXAMPLE_DIR / ".env"
+    if not env_path.is_file():
+        return
+    for raw in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip()
+        if key:
+            os.environ[key] = value
+
+
+_load_local_env()
+
+aiui.set_pages(
+    [
+        "chat",
+        "voice-calls",
+        "call-detail",
+        "web-talk",
+        "eleven-talk",
+        "realtime-talk",
+        "mcp",
+        "config",
+    ]
+)
+aiui.set_style("dashboard")
+aiui.set_custom_js(_EXAMPLE_DIR / "plugin.js")
+
+
+def get_agent():
+    from integrations.voice.agent_runner import get_voice_agent
+
+    return get_voice_agent()
+
+
+aiui.register_agent("voice-assistant", get_agent())
+
+
+@aiui.on_app_startup
+async def _start_voice_chat_bridge() -> None:
+    from integrations.voice.chat_bridge import start_chat_bridge_worker
+
+    start_chat_bridge_worker()
+
+
+@aiui.reply
+async def on_message(message: str):
+    """Chat with the voice demo agent."""
+    from integrations.voice.tools import demo_tool_reply
+
+    text = str(message).strip()
+    if not text:
+        return
+
+    demo = demo_tool_reply(text)
+    if demo is not None:
+        await aiui.say(demo)
+        return
+
+    if not os.getenv("OPENAI_API_KEY"):
+        await aiui.say(
+            "Set `OPENAI_API_KEY` for open-ended chat. "
+            'Demo without API key: "What time is it?" or "Echo hello world".'
+        )
+        return
+    await aiui.think("Running voice assistant...")
+    agent = get_agent()
+    response = await asyncio.to_thread(agent.chat, text)
+    await aiui.say(str(response))
+
+
+def _list_calls() -> list[dict[str, Any]]:
+    from integrations.voice.call_finalize import analytics_for_record
+    from integrations.voice.store import VoiceCallStore
+
+    rows = VoiceCallStore.list_calls()
+    out: list[dict[str, Any]] = []
+    for r in rows:
+        analytics = analytics_for_record(r)
+        out.append(
+            {
+                "id": r["call_id"],
+                "status": r["status"],
+                "customer_number": r.get("customer_number") or "—",
+                "transcript_preview": (r.get("transcript") or "")[:120],
+                "duration": analytics.get("duration") or "—",
+                "turn_count": analytics.get("turn_count") or 0,
+                "updated_at": r.get("updated_at") or "",
+            }
+        )
+    return out
+
+
+def _pick_call(calls: list[dict[str, Any]]) -> dict[str, Any]:
+    live = next((c for c in calls if "progress" in (c.get("status") or "").lower()), None)
+    return live or (calls[0] if calls else {"id": "—", "status": "none", "customer_number": "—", "transcript_preview": ""})
+
+
+@aiui.page("voice-calls", title="Voice calls", icon="📞", group="Voice", order=1)
+async def voice_calls_page():
+    calls = _list_calls()
+    rows = [
+        [c["id"], c["customer_number"], c["status"], c["duration"], str(c["turn_count"]), c["updated_at"]]
+        for c in calls
+    ]
+    return aiui.layout(
+        [
+            aiui.text("Outbound and inbound voice calls via telephony provider"),
+            aiui.table(
+                headers=["Call ID", "Customer", "Status", "Duration", "Turns", "Updated"],
+                rows=rows or [["—", "—", "—", "—", "—", "—"]],
+            ),
+            aiui.alert(
+                "Open **Call detail** for live transcript (SSE). "
+                "Voice sessions also appear in **Chat** sidebar as 📞 entries.",
+                variant="info",
+                title="Phase 2",
+            ),
+        ]
+    )
+
+
+@aiui.page("call-detail", title="Call detail", icon="🎙️", group="Voice", order=2)
+async def call_detail_page():
+    """Server fallback — plugin.js registerView overrides with live SSE + UI components."""
+    from integrations.voice.call_detail_ui import build_call_detail_layout
+    from integrations.voice.store import VoiceCallStore
+
+    calls = _list_calls()
+    picked = _pick_call(calls)
+    record = VoiceCallStore.get_call(picked["id"]) if picked.get("id") and picked["id"] != "—" else None
+    if record:
+        return build_call_detail_layout(record)
+    return aiui.layout(
+        [
+            aiui.alert(
+                "No calls yet. Start from ElevenLabs talk, GPT Realtime, or Web talk.",
+                variant="info",
+                title="Call detail",
+            ),
+        ]
+    )
+
+
+@aiui.page("web-talk", title="Web talk", icon="🎤", group="Voice", order=3)
+async def web_talk_page():
+    return aiui.layout(
+        [
+            aiui.text("Browser voice widget — client view loads from plugin.js"),
+            aiui.alert(
+                "Set VOICE_PUBLIC_API_KEY, VOICE_ASSISTANT_ID, VOICE_WEB_SDK_URL, and "
+                "VOICE_WEB_SDK_GLOBAL in .env.",
+                variant="info",
+                title="Web SDK",
+            ),
+        ]
+    )
+
+
+@aiui.page("eleven-talk", title="ElevenLabs talk", icon="🗣️", group="Voice", order=4)
+async def eleven_talk_page():
+    return aiui.layout(
+        [
+            aiui.text("Browser voice via ElevenLabs Speech Engine — loads from plugin.js"),
+            aiui.alert(
+                "Set ELEVENLABS_API_KEY, run setup_speech_engine.py after start_dev.ps1, "
+                "then click Start conversation.",
+                variant="info",
+                title="Speech Engine",
+            ),
+        ]
+    )
+
+
+@aiui.page("realtime-talk", title="GPT Realtime", icon="⚡", group="Voice", order=5)
+async def realtime_talk_page():
+    return aiui.layout(
+        [
+            aiui.text("Browser voice via OpenAI gpt-realtime-2.1-mini — loads from plugin.js"),
+            aiui.alert(
+                "Set OPENAI_API_KEY and REALTIME_MODEL=gpt-realtime-2.1-mini.",
+                variant="warning",
+                title="OpenAI Realtime",
+            ),
+        ]
+    )
+
+
+app = create_app()
+app.routes[0:0] = [
+    Route("/api/voice/calls", api_voice_create_call, methods=["POST"]),
+    Route("/api/voice/calls", api_voice_list_calls, methods=["GET"]),
+    Route("/api/voice/calls/{call_id}", api_voice_call_detail, methods=["GET"]),
+    Route("/api/voice/calls/{call_id}/ui", api_voice_call_detail_ui, methods=["GET"]),
+    Route("/api/voice/calls/{call_id}/live-transcript", api_voice_live_transcript, methods=["GET"]),
+    Route("/api/voice/config", api_voice_config_status, methods=["GET"]),
+    Route("/api/voice/doctor", api_voice_doctor, methods=["GET"]),
+    Route("/api/voice/web-config", api_voice_web_config, methods=["GET"]),
+    Route("/api/voice/speech-engine/config", api_speech_engine_config, methods=["GET"]),
+    Route("/api/voice/speech-engine/token", api_speech_engine_token, methods=["GET"]),
+    Route("/api/voice/memory/config", api_voice_memory_config, methods=["GET"]),
+    Route("/api/voice/memory/bind", api_voice_memory_bind, methods=["POST"]),
+    Route("/api/voice/memory/attach-user", api_voice_memory_attach_user, methods=["POST"]),
+    Route("/api/voice/memory/resolve", api_voice_memory_resolve, methods=["GET"]),
+    Route("/api/voice/memory/for-call", api_voice_memory_for_call, methods=["GET"]),
+    Route("/api/voice/realtime/config", api_realtime_config, methods=["GET"]),
+    Route("/api/voice/realtime/new-call", api_realtime_new_call, methods=["POST"]),
+    Route("/api/voice/realtime/session", api_realtime_session, methods=["POST"]),
+    Route("/api/voice/realtime/transcript", api_realtime_transcript, methods=["POST"]),
+    Route("/api/voice/realtime/end", api_realtime_end, methods=["POST"]),
+    Route("/webhooks/voice", webhook_voice, methods=["POST"]),
+    WebSocketRoute("/ws", speech_engine_websocket),
+]
+
+if __name__ == "__main__":
+    import uvicorn
+
+    host = os.environ.get("HOST", "127.0.0.1")
+    port = int(os.environ.get("VOICE_AGENT_PORT", "8001"))
+    uvicorn.run(app, host=host, port=port)

examples/python/voice-agent/doctor.py

@@ -0,0 +1,41 @@
+"""CLI for voice-agent stack diagnostics."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+_EXAMPLE_DIR = Path(__file__).resolve().parent
+if str(_EXAMPLE_DIR) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLE_DIR))
+
+
+def _load_local_env() -> None:
+    env_path = _EXAMPLE_DIR / ".env"
+    if not env_path.is_file():
+        return
+    for raw in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip()
+        if key:
+            os.environ[key] = value
+
+
+def main() -> int:
+    _load_local_env()
+    from integrations.voice.doctor import run_voice_doctor
+
+    app_port = int(os.getenv("VOICE_AGENT_PORT", "8001"))
+    sidecar_port = int(os.getenv("SPEECH_ENGINE_SIDECAR_PORT", "8002"))
+    report = run_voice_doctor(app_port=app_port, sidecar_port=sidecar_port)
+    print(json.dumps(report, indent=2))
+    return 1 if report["summary"]["failed"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

examples/python/voice-agent/integrations/__init__.py

@@ -0,0 +1 @@
+"""Voice agent integrations."""

examples/python/voice-agent/integrations/voice/__init__.py

@@ -0,0 +1 @@
+"""Voice telephony provider integration."""

examples/python/voice-agent/integrations/voice/agent_runner.py

@@ -0,0 +1,171 @@
+"""Run voice tool-calls through the PraisonAI agent tool registry."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Callable
+
+from integrations.voice.tools import execute_tool, register_tool
+
+_agent: Any | None = None
+_session_agents: dict[str, Any] = {}
+
+
+def _tool_name(tool: Any) -> str | None:
+    for attr in ("name", "__name__"):
+        value = getattr(tool, attr, None)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    fn = getattr(tool, "func", None) or getattr(tool, "function", None)
+    if fn is not None:
+        return _tool_name(fn)
+    return None
+
+
+def _build_voice_agent(*, session_id: str | None = None):
+    from praisonaiagents import Agent
+    from praisonaiagents.config.feature_configs import MemoryConfig
+    from praisonaiagents.escalation.loop_guard import LoopGuard, LoopGuardConfig
+
+    from integrations.voice.session_memory import memory_enabled
+    from integrations.voice.tools import echo_message, get_current_time
+
+    register_tool("get_current_time", get_current_time)
+    register_tool("echo_message", echo_message)
+
+    tools: list[Any] = [get_current_time, echo_message]
+    extra = os.getenv("VOICE_AGENT_EXTRA_TOOLS", "").strip()
+    if extra == "meeting_search":
+        try:
+            from praisonai_tools.tools.meeting_tools import search_meetings
+
+            tools.append(search_meetings)
+            register_tool("search_meetings", search_meetings)
+        except ImportError:
+            pass
+
+    memory_cfg = None
+    if memory_enabled() and session_id:
+        memory_cfg = MemoryConfig(
+            history=True,
+            session_id=session_id,
+            history_limit=int(os.getenv("VOICE_MEMORY_HISTORY_LIMIT", "20")),
+        )
+
+    agent = Agent(
+        name="Voice Assistant",
+        instructions=(
+            "You help with voice and phone agent demos. "
+            "Use tools when the caller asks for the time, wants a message echoed, "
+            "or asks about past meetings."
+        ),
+        model=os.getenv("VOICE_AGENT_MODEL", "gpt-4o-mini"),
+        tools=tools,
+        memory=memory_cfg or False,
+    )
+    max_turn_sec = float(os.getenv("VOICE_AGENT_LOOP_GUARD_MAX_SEC", "600"))
+    agent._loop_guard = LoopGuard(LoopGuardConfig(enabled=True, max_time_per_turn=max_turn_sec))
+
+    for tool in tools:
+        name = _tool_name(tool)
+        if name:
+            register_tool(name, _callable_tool(tool))
+    return agent
+
+
+def get_voice_agent(session_id: str | None = None):
+    """Lazy-load the voice assistant (optionally bound to a PraisonAI session)."""
+    global _agent
+    if session_id:
+        cached = _session_agents.get(session_id)
+        if cached is not None:
+            return cached
+        agent = _build_voice_agent(session_id=session_id)
+        _session_agents[session_id] = agent
+        return agent
+    if _agent is not None:
+        return _agent
+    _agent = _build_voice_agent()
+    return _agent
+
+
+def _callable_tool(tool: Any) -> Callable[..., Any]:
+    fn = getattr(tool, "func", None) or getattr(tool, "run", None) or tool
+    return fn  # type: ignore[return-value]
+
+
+def execute_voice_tool(
+    name: str,
+    parameters: dict[str, Any] | None,
+    *,
+    session_id: str | None = None,
+) -> str:
+    """Execute via agent tool registry, then fall back to static registry."""
+    params = parameters or {}
+    agent = get_voice_agent(session_id)
+    for tool in agent.tools or []:
+        tname = _tool_name(tool)
+        if tname != name:
+            continue
+        fn = _callable_tool(tool)
+        try:
+            result = fn(**params)
+        except TypeError:
+            try:
+                result = fn(params)
+            except Exception as exc:  # noqa: BLE001
+                return json.dumps({"error": str(exc)})
+        except Exception as exc:  # noqa: BLE001
+            return json.dumps({"error": str(exc)})
+        if isinstance(result, str):
+            return result
+        return json.dumps(result)
+    return execute_tool(name, params)
+
+
+def list_registered_tool_names() -> list[str]:
+    agent = get_voice_agent()
+    names: list[str] = []
+    for tool in agent.tools or []:
+        tname = _tool_name(tool)
+        if tname:
+            names.append(tname)
+    return names
+
+
+def build_assistant_request_response(settings: Any) -> dict[str, Any]:
+    """Return provider assistant config for dynamic assistant-request events."""
+    if settings.default_assistant_id and not os.getenv("VOICE_DYNAMIC_ASSISTANT", "").lower() in (
+        "1",
+        "true",
+        "yes",
+    ):
+        return {"assistantId": settings.default_assistant_id}
+
+    tool_names = list_registered_tool_names()
+    assistant: dict[str, Any] = {
+        "name": "Praison Voice Assistant",
+        "firstMessage": os.getenv("VOICE_FIRST_MESSAGE", "Hello! How can I help you today?"),
+        "model": {
+            "provider": os.getenv("VOICE_MODEL_PROVIDER", "openai"),
+            "model": os.getenv("VOICE_AGENT_MODEL", "gpt-4o-mini"),
+            "messages": [
+                {
+                    "role": "system",
+                    "content": (
+                        "You are a helpful voice assistant. When asked for the time, call get_current_time. "
+                        "When asked to repeat or echo text, call echo_message with the message parameter. "
+                        "Available tools: "
+                        + ", ".join(tool_names or ["get_current_time", "echo_message"])
+                    ),
+                }
+            ],
+        },
+    }
+    if settings.webhook_url and settings.server_url_secret:
+        assistant["server"] = {
+            "url": settings.webhook_url,
+            "headers": {"X-Voice-Webhook-Secret": settings.server_url_secret},
+        }
+    return {"assistant": assistant}

examples/python/voice-agent/integrations/voice/call_detail_ui.py

@@ -0,0 +1,57 @@
+"""Build PraisonAIUI components for the call detail page."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import praisonaiui as aiui
+
+
+def build_call_detail_layout(record: dict[str, Any]) -> dict[str, Any]:
+    """Return dashboard component tree for call detail (code_block + metadata)."""
+    from integrations.voice.call_finalize import analytics_for_record
+
+    metadata = record.get("metadata") or {}
+    analytics = analytics_for_record(record)
+    transcript = (record.get("transcript") or "").strip() or "(empty — waiting for speech…)"
+    summary = (record.get("summary") or "").strip() or "(not available yet)"
+    status = str(record.get("status") or "unknown")
+
+    kv_items: list[dict[str, str]] = [
+        {"label": "Call ID", "value": str(record.get("call_id") or "—")},
+        {"label": "Status", "value": status},
+        {"label": "Customer", "value": str(record.get("customer_number") or "—")},
+    ]
+    if metadata.get("user_id"):
+        kv_items.append({"label": "User ID", "value": str(metadata["user_id"])})
+    if metadata.get("praison_session_id"):
+        kv_items.append({"label": "Memory session", "value": str(metadata["praison_session_id"])})
+    kv_items.append({"label": "Duration", "value": str(analytics.get("duration") or "—")})
+    kv_items.append({"label": "Turns", "value": str(analytics.get("turn_count") or 0)})
+
+    return aiui.layout(
+        [
+            aiui.text("Live voice call transcript and metadata"),
+            aiui.badge(status, variant="default"),
+            aiui.definition_list(kv_items, title="Call metadata"),
+            aiui.alert(
+                "Transcript updates live via SSE. Final lines use PraisonAIUI code blocks.",
+                variant="info",
+                title="Live feed",
+            ),
+            aiui.tabs(
+                [
+                    {
+                        "label": "Transcript",
+                        "children": [
+                            aiui.code_block(transcript, language="text"),
+                        ],
+                    },
+                    {
+                        "label": "Summary",
+                        "children": [aiui.text(summary)],
+                    },
+                ]
+            ),
+        ]
+    )

examples/python/voice-agent/integrations/voice/call_finalize.py

@@ -0,0 +1,126 @@
+"""End-of-call summary, analytics, and chat bridge on session close."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from datetime import datetime, timezone
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def count_turns(transcript: str) -> int:
+    """Count user/agent lines in stored transcript."""
+    turns = 0
+    for line in (transcript or "").splitlines():
+        text = line.strip()
+        if text.startswith("user:") or text.startswith("agent:") or text.startswith("assistant:"):
+            turns += 1
+    return turns
+
+
+def duration_seconds(created_at: str | None, ended_at: str | None) -> int | None:
+    if not created_at or not ended_at:
+        return None
+    try:
+        start = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+        end = datetime.fromisoformat(ended_at.replace("Z", "+00:00"))
+        return max(0, int((end - start).total_seconds()))
+    except ValueError:
+        return None
+
+
+def format_duration(seconds: int | None) -> str:
+    if seconds is None:
+        return "—"
+    if seconds < 60:
+        return f"{seconds}s"
+    minutes, rem = divmod(seconds, 60)
+    return f"{minutes}m {rem}s"
+
+
+async def generate_call_summary(transcript: str) -> str:
+    """One-sentence LLM summary for call detail + chat sidebar."""
+    text = (transcript or "").strip()
+    if not text:
+        return "Empty call — no conversation captured."
+    api_key = os.getenv("OPENAI_API_KEY", "").strip()
+    if not api_key:
+        lines = [ln.strip() for ln in text.splitlines() if ln.strip()]
+        preview = " · ".join(lines[:3])
+        return f"Call covered: {preview[:240]}"
+
+    from openai import AsyncOpenAI
+
+    client = AsyncOpenAI(api_key=api_key)
+    try:
+        response = await asyncio.wait_for(
+            client.chat.completions.create(
+                model=os.getenv("VOICE_AGENT_MODEL", "gpt-4o-mini"),
+                messages=[
+                    {
+                        "role": "system",
+                        "content": (
+                            "Summarize this voice call in one concise sentence for a dashboard. "
+                            "Mention main topic and outcome only."
+                        ),
+                    },
+                    {"role": "user", "content": text[:6000]},
+                ],
+                max_tokens=80,
+            ),
+            timeout=15.0,
+        )
+        summary = (response.choices[0].message.content or "").strip()
+        return summary or "Call completed."
+    except Exception:  # noqa: BLE001
+        logger.exception("Call summary generation failed")
+        return "Call completed — summary unavailable."
+
+
+async def finalize_call(call_id: str, *, status: str) -> None:
+    """Persist analytics, optional summary, and notify chat bridge."""
+    from integrations.voice.chat_bridge import enqueue_call_summary
+    from integrations.voice.store import VoiceCallStore
+
+    record = VoiceCallStore.get_call(call_id)
+    if not record:
+        return
+
+    transcript = (record.get("transcript") or "").strip()
+    metadata: dict[str, Any] = dict(record.get("metadata") or {})
+    ended_at = datetime.now(timezone.utc).isoformat()
+    metadata["ended_at"] = ended_at
+    metadata["turn_count"] = count_turns(transcript)
+    metadata["duration_sec"] = duration_seconds(record.get("created_at"), ended_at)
+
+    summary = (record.get("summary") or "").strip()
+    if not summary and transcript:
+        summary = await generate_call_summary(transcript)
+
+    VoiceCallStore.upsert_call(
+        call_id,
+        status=status,
+        summary=summary or None,
+        metadata=metadata,
+    )
+    enqueue_call_summary(call_id, summary or "(no summary)", status)
+
+
+def analytics_for_record(record: dict[str, Any]) -> dict[str, Any]:
+    """Derived analytics for API + dashboard tables."""
+    metadata = record.get("metadata") or {}
+    transcript = record.get("transcript") or ""
+    turns = metadata.get("turn_count")
+    if turns is None:
+        turns = count_turns(transcript)
+    duration_sec = metadata.get("duration_sec")
+    if duration_sec is None:
+        duration_sec = duration_seconds(record.get("created_at"), metadata.get("ended_at"))
+    return {
+        "turn_count": turns,
+        "duration_sec": duration_sec,
+        "duration": format_duration(duration_sec if isinstance(duration_sec, int) else None),
+    }

examples/python/voice-agent/integrations/voice/chat_bridge.py

@@ -0,0 +1,150 @@
+"""Bridge voice call events into Chat UI sessions (sidebar + history)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import queue
+import threading
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_bridge_queue: queue.Queue[dict[str, Any]] = queue.Queue(maxsize=512)
+_worker_lock = threading.Lock()
+_worker_task: asyncio.Task[None] | None = None
+
+
+def voice_session_id(call_id: str) -> str:
+    return f"voice-{call_id}"
+
+
+def enqueue_transcript(call_id: str, role: str, text: str, *, final: bool) -> None:
+    if not call_id or not text.strip():
+        return
+    _enqueue(
+        {
+            "kind": "transcript",
+            "call_id": call_id,
+            "role": role,
+            "text": text.strip(),
+            "final": final,
+        }
+    )
+
+
+def enqueue_call_summary(call_id: str, summary: str, status: str) -> None:
+    if not call_id:
+        return
+    _enqueue(
+        {
+            "kind": "summary",
+            "call_id": call_id,
+            "summary": summary.strip(),
+            "status": status,
+        }
+    )
+
+
+def _enqueue(item: dict[str, Any]) -> None:
+    try:
+        _bridge_queue.put_nowait(item)
+    except queue.Full:
+        logger.warning("Voice chat bridge queue full; dropping event")
+
+
+async def _ensure_session(call_id: str) -> str:
+    from praisonaiui.server import _datastore
+
+    session_id = voice_session_id(call_id)
+    existing = await _datastore.get_session(session_id)
+    if existing is None:
+        await _datastore.create_session(session_id)
+        await _datastore.update_session(
+            session_id,
+            platform="voice",
+            icon="📞",
+            title=f"📞 Call {call_id[:8]}",
+        )
+    return session_id
+
+
+async def _process_item(item: dict[str, Any]) -> None:
+    from praisonaiui.features.chat import get_chat_manager
+    from praisonaiui.server import _datastore
+
+    call_id = str(item.get("call_id") or "")
+    if not call_id:
+        return
+    session_id = await _ensure_session(call_id)
+    mgr = get_chat_manager()
+
+    if item.get("kind") == "transcript":
+        role = str(item.get("role") or "unknown")
+        text = str(item.get("text") or "")
+        final = bool(item.get("final"))
+        if not final:
+            await mgr.broadcast(
+                session_id,
+                {
+                    "type": "voice_transcript_partial",
+                    "session_id": session_id,
+                    "call_id": call_id,
+                    "role": role,
+                    "content": text,
+                },
+            )
+            return
+        content = f"**{role}:** {text}"
+        await _datastore.add_message(
+            session_id,
+            {"role": "user" if role == "user" else "assistant", "content": content, "platform": "voice"},
+        )
+        await mgr.broadcast(
+            session_id,
+            {
+                "type": "voice_transcript",
+                "session_id": session_id,
+                "call_id": call_id,
+                "role": role,
+                "content": text,
+            },
+        )
+        return
+
+    if item.get("kind") == "summary":
+        summary = str(item.get("summary") or "(call ended)")
+        status = str(item.get("status") or "ended")
+        content = f"**Call {status}**\n\n{summary}"
+        await _datastore.add_message(session_id, {"role": "assistant", "content": content, "platform": "voice"})
+        await mgr.broadcast(
+            session_id,
+            {
+                "type": "voice_call_ended",
+                "session_id": session_id,
+                "call_id": call_id,
+                "status": status,
+                "summary": summary,
+            },
+        )
+
+
+async def run_chat_bridge_worker() -> None:
+    while True:
+        try:
+            item = await asyncio.to_thread(_bridge_queue.get, True, 1.0)
+        except queue.Empty:
+            continue
+        try:
+            await _process_item(item)
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("Voice chat bridge error: %s", exc)
+
+
+def start_chat_bridge_worker() -> None:
+    global _worker_task
+    with _worker_lock:
+        if _worker_task is not None and not _worker_task.done():
+            return
+        loop = asyncio.get_running_loop()
+        _worker_task = loop.create_task(run_chat_bridge_worker())

examples/python/voice-agent/integrations/voice/client.py

@@ -0,0 +1,76 @@
+"""Minimal voice provider REST client."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from integrations.voice.config import VoiceSettings
+
+logger = logging.getLogger(__name__)
+
+
+class VoiceAPIError(RuntimeError):
+    def __init__(self, status_code: int, detail: str):
+        super().__init__(detail)
+        self.status_code = status_code
+        self.detail = detail
+
+
+class VoiceClient:
+    """HTTP client for voice provider calls and assistants."""
+
+    def __init__(self, settings: VoiceSettings):
+        self._settings = settings
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._settings.api_key}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        import httpx  # lazy: optional dependency for the example (pip install httpx)
+
+        url = f"{self._settings.api_base.rstrip('/')}{path}"
+        with httpx.Client(timeout=30.0) as client:
+            response = client.request(method, url, headers=self._headers(), json=json_body)
+        if response.status_code >= 400:
+            raise VoiceAPIError(response.status_code, response.text[:500] or response.reason_phrase)
+        if not response.content:
+            return {}
+        data = response.json()
+        return data if isinstance(data, dict) else {"data": data}
+
+    def create_call(
+        self,
+        *,
+        customer_number: str,
+        assistant_id: str | None = None,
+        phone_number_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        assistant_id = assistant_id or self._settings.default_assistant_id
+        phone_number_id = phone_number_id or self._settings.default_phone_number_id
+        if not assistant_id:
+            raise VoiceAPIError(0, "assistant_id is required (set VOICE_ASSISTANT_ID or pass explicitly)")
+        if not phone_number_id:
+            raise VoiceAPIError(0, "phone_number_id is required (set VOICE_PHONE_NUMBER_ID or pass explicitly)")
+        body: dict[str, Any] = {
+            "assistantId": assistant_id,
+            "phoneNumberId": phone_number_id,
+            "customer": {"number": customer_number},
+        }
+        if metadata:
+            body["metadata"] = metadata
+        return self._request("POST", "/call", json_body=body)
+
+    def get_call(self, call_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/call/{call_id}")