# VibeDash Project and Agent Skill

Interact with the [VibeDash.app](https://vibedash.app) project management and status portal for software development teams.

## Overview

VibeDash is a modern project management and agent operations platform with:
- **Ideas** – Draft product ideas and pitch artifacts that can later become projects
- **Milestones** – Time-bound deliverables with due dates and status tracking
- **Tasks** – Development-ready work items linked to milestones
- **Tickets** – Bug reports, feature requests, and support issues from users and team members
- **Payments** – Invoice and payment tracking per project
- **GitHub Integration** – Linked repositories, PR tracking, and AI agent assignments

Additional agent-focused surfaces:
- **Agent Operating Layer** - Cursor-first PM, Autopilot Capacity, BYO agent handoff, work-item ledger, guarded merge, risk events, and skill suggestions
- **Testing Loops** - Cursor-backed verifier, QA, security, review, break-fix, docs, test-suite, and quality-streak workflows with findings and Quality Gate evidence
- **Customer Agents** - ICP configuration, source-backed Web/X prospect research, scoring, outreach openers, reports, and search-credit visibility
- **Blog Writer** - source-backed project stories, revisions, review gates, exports, destinations, and confirmed publishing

This skill enables you to read and write project data through the VibeDash REST API, `vibedash-api` proxy, MCP server, and Edge Functions.

## MCP Server

Agents that support MCP should prefer the VibeDash MCP server over raw curl calls because it provides scoped tools, current page/project context, and safer argument schemas.

```json
{
  "mcpServers": {
    "vibedash": {
      "type": "http",
      "url": "https://ezdrjodbsdzawsqxasfx.supabase.co/functions/v1/vibedash-mcp",
      "headers": {
        "Authorization": "Bearer ${VIBEDASH_API_KEY}",
        "apikey": "${VIBEDASH_API_KEY}",
        "x-vibedash-project-id": "${VIBEDASH_PROJECT_ID}",
        "x-vibedash-mcp-scopes": "pm,agent,testing,website,support,customers,blog"
      }
    }
  }
}
```

Cursor PM receives this server inline from VibeDash when a user has connected Cursor and has a full-access VibeDash API key.

`x-vibedash-mcp-scopes` is optional. If present, the MCP server only exposes tools in the requested scopes:
- `pm` - core project context, tasks, tickets, milestones, payments, ideas, meetings
- `agent` - agent capability registry, work-item status, quality snapshots, risk ledger, skill suggestions
- `testing` - findings, testing loops, legacy testing functions, and quality gates
- `website` - project site/version tools
- `support` - support widget tools
- `customers` - customer agents, research runs, prospects, reports, and search-wallet summary
- `blog` - blog settings, sources, drafts, revisions, generation, exports, destinations, and publishing

### MCP Tools

Production parity note: MCP tools include agent work-item status, quality gates, website builder, AI testing, customer research, Blog Writer, and support widget helpers in addition to core PM tools. Prefer MCP over raw REST whenever available. Tasks are scoped to projects through their `milestone_id` relationship; do not query or assume a `tasks.project_id` column.

Context and project health:
- `get_current_context` / `where_am_i` - current app route, page context, account project counts, and current project summary
- `list_projects` - projects visible to the connected user with status counts
- `get_project_summary` - project details including `start_date` and `due_date`, plus task, ticket, and milestone counts

Core project management:
- `list_tasks` - project tasks, with filters for `milestone_id`, `status`, `open_only`, `source_conversation_message_id`, and `assigned_agent`
- `list_tickets` - project tickets, with filters for `status`, `open_only`, `type`, `severity`, and `priority`
- `list_milestones` - project milestones, with status/open filters
- `list_payments` - project payments
- `replace_payment_schedule` - preview or replace the unpaid schedule with total validation; preserves paid rows by default and requires `confirm_replace: true` for a write
- `list_proposals`, `upsert_project_proposal` - read proposal versions and create/update structured commercial proposals
- `list_project_prds`, `create_project_prd`, `update_project_prd` - manage canonical versioned project PRDs
- `create_project` - create a new project; requires `confirm_create: true` after explicit user request
- `create_milestone`, `create_task`, `create_ticket`, `create_project_idea`
- `update_project` - project name, description, status, dates, client value, internal/effort cost, paid amount, or effort visibility
- `update_milestone` - milestone name, description, status, due date, effort cost, or effort visibility
- `rebaseline_project_timeline` - one-shot late-kickoff rebase: shift project start/due, open milestone dates, and unpaid payment dates by the same offset
- `update_task`, `update_task_status`, `update_ticket_status`, `update_milestone_status`
- `add_ticket_message`
- `list_board_reviewers` - multi-model PRD board reviewers (Claude / GPT-Codex / Gemini / Grok / Custom OpenRouter)
- `run_board_review` - run board consensus on PRD markdown (same as AI-Start **Board review**); requires explicit user request and a PRD body

Ideas and meeting ingestion:
- `list_project_ideas`
- `post_meeting_summary`
- `process_meeting_message`

Website/version tools:
- `list_project_sites`, `list_site_versions`, `get_site_version_html`
- `build_site_from_url`, `upload_site_html`, `redesign_site`, `edit_site_html`
- `review_site_responsiveness`, `fix_site_responsiveness`
- `archive_site_version`, `unarchive_site_version`

AI testing tools:
- `list_testing_findings`, `list_testing_loops`, `run_testing_loop`
- `run_testing_function` (legacy function-key entrypoint)
- `run_quality_gate`

Agent operating layer:
- `list_agent_capabilities` - provider/capability registry and active MCP scopes
- `get_project_agent_settings`, `update_project_agent_settings` - project-level PM provider, auto-ticket provider, enabled providers, and MCP scope settings
- `list_agent_work_items` - PM chat, testing, review, task assignment, and ticket automation ledger
- `get_agent_work_item` - one work item plus its event timeline
- `get_agent_status_snapshot` - project summary, active work, quality gate, unresolved risks, and skill suggestions
- `get_multi_project_agent_overview` - portfolio-level agent overview across accessible projects, with attention status, next actions, and recommended follow-up MCP tools
- `get_relaunch_review_candidates` - read-only Agency Portfolio PM ranking for Relaunch Review, including repo, runner, workload, active-run, and recent-review eligibility
- `start_relaunch_review`, `get_relaunch_review_status` - confirmation-gated review launch and durable progress lookup
- `get_agent_capacity_snapshot` - Autopilot Capacity settings, provider policies, usage windows, active work, and eligible task counts
- `list_autopilot_candidates` - tasks explicitly marked agent-ready with eligibility reasons
- `update_project_autopilot_settings` - enable/disable Autopilot Capacity and update provider budgets/concurrency after explicit admin/manager request
- `delegate_task_to_agent` - delegate one eligible task to Cursor direct cloud run or provider-native issue/comment handoff providers
- `delegate_pull_request_review` - dispatch the platform Agent Reviewer for an open GitHub PR using the project's VibeDash GitHub App installation
- `record_agent_usage_event` - record heuristic provider usage in weekly and rolling 5-hour windows
- `evaluate_guarded_merge` - evaluate or execute guarded PR merge gates when the project is configured for guarded merge
- `list_agent_risk_events`, `record_agent_risk_event` - risk ledger events for concrete agent actions and security concerns
- `list_skill_suggestions`, `create_skill_suggestion` - reviewable proposed improvements to skills, project instructions, MCP tools, or testing templates

Support widget tools:
- `get_support_widget_embed`, `configure_support_widget`

Customer Agent tools:
- `get_customer_dashboard`, `get_customer_wallet`
- `list_customer_agents`, `get_customer_agent`, `create_customer_agent`, `update_customer_agent`, `set_customer_agent_status`, `delete_customer_agent`
- `prepare_first_customer_agent`, `launch_first_customer_agent`, `run_customer_agent`, `cancel_customer_run`
- `list_customer_prospects`, `get_customer_run_report`

Blog Writer tools:
- `get_blog_settings`, `prepare_blog_profile`, `apply_blog_profile`, `update_blog_settings`
- `list_blog_posts`, `get_blog_post`, `create_blog_post`, `update_blog_post`, `archive_blog_post`
- `list_blog_revisions`, `preview_blog_revision`, `restore_blog_revision`
- `list_blog_runs`, `list_blog_sources`, `generate_blog_post`, `cancel_blog_run`
- `submit_blog_review`, `approve_blog_revision`, `reject_blog_revision`
- `list_blog_destinations`, `upsert_blog_destination`, `validate_blog_destination`
- `export_blog_revision`, `list_blog_publications`, `publish_blog_now`, `schedule_blog_publication`

Use write tools only after the user clearly asks to create or update something. MCP write tools run as the connected VibeDash user and enforce project access/manage checks before writing. For factual PM chat questions, call the relevant read tool first and answer from the returned data.

Credit and publication safety boundaries:
- Customer Agent launches and runs spend account-owned search credits. Call `prepare_first_customer_agent` before the first launch, explain any clarification questions or estimated spend, and pass `confirm_spend: true` only after the user explicitly approves that run.
- `cancel_customer_run` also requires explicit confirmation because cancelling an active dispatched run may commit its reserved credit. Never imply that cancellation guarantees a refund.
- `delete_customer_agent` requires `confirm_delete: true`. Explain that the agent and its retained project research will be removed before confirming deletion.
- `generate_blog_post` requires `confirm_generation: true`. Explain the generation action before confirming it.
- `archive_blog_post` requires `confirm_archive: true` because it removes the post from the active workspace.
- `update_blog_settings` requires `confirm_automation: true` when enabling `auto_publish_approved`. Explain the destination and future publishing behavior before turning automation on.
- `publish_blog_now` and `schedule_blog_publication` require `confirm_publish: true`. Preview the exact revision and identify the destination before asking for confirmation.
- Contact enrichment, contact detail unlocks, and CleanLeads actions are not exposed through MCP. They remain explicit, separately metered actions in the Customers UI.
- Admin wallet adjustments are not exposed through project MCP. They remain audited Admin-only actions. An agent may read the search/contact wallet summary but must not claim it can grant, remove, or transfer credits.
- VibeDash does not expose autonomous messaging, DMs, form submissions, campaign launch, or automated outreach through these tools.

Status values to prefer:
- Tasks: `to-do`, `in-progress`, `testing`, `revision`, `agent-assigned`, `pr-raised`, `completed`, `archived`
- Milestones: `not-started`, `in-progress`, `completed`, `overdue`
- Tickets: `open`, `in-progress`, `resolved`, `archived`
- Project ideas: `in_progress`, `prd_generated`, `project_created`, `archived` (`draft` is treated as `in_progress` by the MCP tool)

Website/version notes:
- `list_project_sites` returns site fields such as `slug`, `status`, `default_hostname`, `active_published_version`, and `settings`.
- `list_site_versions` and version mutation tools verify the version belongs to the requested project site before acting.
- Generation tools can create new site versions and may take longer than normal PM tools; use them only when the user asks for website creation, import, redesign, editing, or responsiveness work.

AI testing (Cursor) tools:
- `list_testing_findings` - security/QA/code-review findings for a project; filter by `source_type`, `severity`, `open_only`, `session_id`, or `run_id`.
- `list_testing_loops` - list Cursor-backed loop templates, including loop kind, category, default iteration cap, budget, verifier requirement, and fix support.
- `run_testing_loop` - preferred entrypoint for testing work. Requires `loop_key`; accepts `mode: report_only` or `mode: fix_with_pr`, plus optional `max_iterations`, `budget_minutes`, `suite_id`, `playwright_args`, and `starting_ref`.
- `run_testing_function` - legacy function-key entrypoint. Requires the user to connect a Cursor API key in VibeDash Settings. `function_key` values: `qa_e2e`, `regression`, `security_audit`, `code_review`, `validation`, `break_fix`, `repo_map`, `user_docs`, `test_suite`. Prefer `run_testing_loop` for new work because loop keys carry verifier and budget policy.
- `run_quality_gate` - compute a readiness gate from open findings, latest test runs, active/failed agent work, open tasks, open tickets, and milestones. Use this before claiming a project is ready to ship.

Testing loop keys:
- `build_test_fix` - loop through checks and fixes until clean or capped.
- `acceptance_verifier` - verify task/milestone acceptance criteria.
- `qa_sweep` - run realistic E2E QA and record findings.
- `regression_sweep` - inspect recent changes for broken impacted flows.
- `security_audit` - audit injection, auth/access control, secrets, RLS gaps, SSRF, and dependency exposure.
- `code_review` - senior review for correctness, validation, architecture, and regression risk.
- `break_fix` - fix open findings/failures and open a PR; this loop is fix-oriented.
- `repo_map` - map the repo and update engineering docs.
- `user_docs` - generate or update user-facing docs.
- `test_suite_builder` - create a Playwright test suite and open a PR; this loop is fix-oriented.
- `quality_streak` - rerun realistic scenarios until consecutive clean passes are achieved or the cap is hit.

Agent operating layer:
- `list_agent_capabilities` returns the available providers and capabilities. Cursor is the preferred full-surface provider for PM chat, task runner, Autopilot Capacity coordination, auto-ticket handling, testing, code review, security audit, docs, marketing plan, and slop fixer roles. Claude Code, Jules, GitHub Copilot, Hermes, OpenClaw, and Other use provider-native issue/comment handoffs when the bound repository account supports them. Codex uses the House managed sandbox for direct GitHub execution and remains explicitly blocked for non-GitHub direct execution until its runtime supports those providers.
- `get_project_agent_settings` returns project-level provider and MCP tool-scope settings. `update_project_agent_settings` can change `pm_provider`, `auto_ticket_provider`, `enabled_providers`, `mcp_scopes`, or `capability_overrides`, but only after explicit user/admin request.
- `list_agent_work_items` is the durable agent ledger. Use `active_only=true` for current work and filters like `provider`, `capability_key`, `status`, or `source_type` for handoff/status questions.
- `get_agent_work_item` returns the work item plus its event timeline, including GitHub issue/PR links when available.
- `get_multi_project_agent_overview` is the best first tool for questions like "what needs attention across my projects?", "what should I do next?", or "which project needs the agent first?". It returns a portfolio rollup, `agent_brief`, per-project quality status, test `evidence_status`, attention status (`blocked`, `needs_review`, `clear`), `attention_reasons`, `priority_score`, one ranked `primary_next_action`, supporting actions, and recommended drill-down tools.
- Portfolio reads use the `portfolio_read` MCP scope. Launching a review is isolated behind `portfolio_write`; a recommendation-only agent must never receive that write scope.
- `get_relaunch_review_candidates` is read-only. Present its ranked eligible projects and reasons to the user before any launch. Cursor uses its connected cloud account; Codex uses the VibeDash House key inside an isolated managed sandbox. Pass the confirmed `runner_provider` explicitly and use a unique idempotency key per project.
- `start_relaunch_review` is one-project-at-a-time and requires `confirm_run: true` plus a unique `idempotency_key`. If `auto_break_fix` is true, it also requires `confirm_auto_break_fix: true`. Optional `proposal_id` and `batch_id` are caller audit references, not persisted proposal proof.
- `get_agent_status_snapshot` is the best first tool for one-project questions like "what are the agents doing?", "is this project ready?", or "what needs attention here?".
- `get_agent_capacity_snapshot` is the best first tool for questions about subscription capacity, enabled providers, budgets, active Autopilot work, or whether Autopilot can pick more tasks.
- `list_autopilot_candidates` only returns tasks explicitly marked agent-ready (`agent_autopilot_enabled=true`). Autopilot should not pick arbitrary open tasks.
- `update_project_autopilot_settings` can enable/disable Autopilot, set `merge_mode`, and update provider policy rows (`enabled`, `weekly_budget_minutes`, `rolling_window_budget_minutes`, `max_concurrent`, `priority`, `paused_until`). Use only after a clear admin/manager instruction.
- `delegate_task_to_agent` dispatches a specific eligible task. `provider: "cursor"` starts a Cursor cloud implementation run with VibeDash MCP. `provider: "codex"` starts VibeDash House Codex in an isolated managed sandbox and opens a draft PR for GitHub repositories. Other handoff providers create/update an issue and comment in the configured repository provider through an account-bound connection. Every path is tracked through the agent work-item ledger.
- `delegate_pull_request_review` dispatches the provider-neutral Agent Reviewer for an open GitHub pull request already linked to a task. It uses the project's VibeDash GitHub App installation for review writes. Never substitute generic GitHub comment/review tools; if the PR is merged, closed, or already reviewed at its current head, reconcile the existing result instead of dispatching again.
- `record_agent_usage_event` records heuristic usage because most subscription providers do not expose reliable remaining allowance APIs.
- `evaluate_guarded_merge` evaluates PR merge gates and only merges when `merge=true`, guarded merge is enabled, checks are green, the PR is mergeable, and no high/critical unresolved agent risks or testing findings exist.
- `list_agent_risk_events` surfaces unresolved tool/action risk. Treat `high` or `critical` risks as blockers until reviewed. Use `record_agent_risk_event` only for concrete, reviewable risks.
- `list_skill_suggestions` surfaces reviewable learning-loop suggestions. Use `create_skill_suggestion` when a completed run reveals a reusable skill/project-instruction/MCP/testing-template improvement. Do not apply skill changes automatically; summarize them and ask the user/admin to approve.

Support widget tools:
- `get_support_widget_embed` — returns widget config, the current project-scoped public key, paste-ready keyless `embed_html`, and `preview_url`. Existing embeds resolve rotations at runtime.
- `configure_support_widget` — update widget name, position, colors, custom CSS, webhook URL, or active flag. Write only on explicit user request.

Customer Agent tools:
- Start with `get_customer_dashboard` for project-level totals and recent activity, and `get_customer_wallet` before proposing a paid run. Wallet balances belong to the paying account and can be shared by its eligible projects.
- `prepare_first_customer_agent` analyzes saved project/product context without launching a run. If it returns clarification questions, present them to the user instead of guessing material ICP details.
- `launch_first_customer_agent` is the guided "first 10 customers" path. It creates the initial agent when the preflight has enough context and starts the first standard run only with `confirm_spend: true`.
- `create_customer_agent` and `update_customer_agent` manage configuration without spending a search credit. Use `set_customer_agent_status` for active/paused state. `delete_customer_agent` requires an explicit deletion request and `confirm_delete: true`.
- `run_customer_agent` starts a configured standard or deep run only with `confirm_spend: true`. Prevent duplicate launch requests while an agent already has a running job.
- `cancel_customer_run` requires explicit confirmation. A pre-dispatch cancellation may release a reservation, while a dispatched provider run may have already consumed the credit.
- `list_customer_prospects` returns evidence-backed records and filters. Treat observed evidence separately from inferred fields, preserve source URLs and visible dates, and do not present inferred contact details as known facts.
- `get_customer_run_report` returns the stored report for a completed or partial run. Reports contain suggested openers, not proof that any outreach occurred.

Blog Writer tools:
- Start with `get_blog_settings`. For a new project, obtain approval for managed profile generation, then call `prepare_blog_profile` with `confirm_generation: true` to derive a reviewable product/audience/voice profile. Use `apply_blog_profile` only after the user approves the result. When `update_blog_settings` would enable `auto_publish_approved`, obtain explicit approval and pass `confirm_automation: true`.
- `list_blog_sources` shows the project evidence available to a post. Generated claims must stay traceable to these saved sources; never invent release details or expose private task links, secrets, customer contacts, or private repository URLs.
- `create_blog_post` and `update_blog_post` support manual drafts. `archive_blog_post` requires `confirm_archive: true`. `generate_blog_post` starts an AI generation only with `confirm_generation: true`; use `list_blog_runs` for status and `cancel_blog_run` on explicit request.
- Use `list_blog_revisions` and `preview_blog_revision` before review, export, or publication. `restore_blog_revision` changes the active draft and requires a clear user request.
- `submit_blog_review`, `approve_blog_revision`, and `reject_blog_revision` enforce the human review workflow. Do not treat a generated draft as approved.
- Use `list_blog_destinations` before proposing an output. `upsert_blog_destination` changes destination configuration, and `validate_blog_destination` checks it without publishing.
- `export_blog_revision` creates a portable artifact but does not publish it. It still requires an explicit export/download request.
- `publish_blog_now` and `schedule_blog_publication` require `confirm_publish: true`, an approved revision, and a named destination. Always show the selected revision/destination and obtain confirmation immediately before the call.
- `list_blog_publications` is the source of truth for publication status and remote receipts. Do not claim success from a queued or scheduled response.

## Lead-magnet quickstarts

These are the first actions to run after a user converts from a standalone tool funnel (`/website`, `/widget`, `/audit`). Each funnel seeds a project and hands off MCP credentials via Connect-your-agent.

### Website funnel (`/website`)

After signup the project has a cloned site draft. Typical agent flow:

1. `list_project_sites` → note `site_id`.
2. `list_site_versions` → pick the latest draft `version_id`.
3. `get_site_version_html` → inspect current HTML.
4. On user request: `redesign_site`, `edit_site_html`, `review_site_responsiveness`, or `fix_site_responsiveness`.

Example first prompt for the user's agent:

> You are connected to my VibeDash website project. List my sites and versions, show me the latest draft HTML summary, and suggest the top 3 improvements before we publish.

### Support widget funnel (`/widget`)

After signup the project has an active `feedback_widgets` row and embed snippet.

1. `get_support_widget_embed` → return the paste-ready script for the user's site.
2. `list_tickets` with `open_only=true` → triage incoming widget submissions.
3. `add_ticket_message` / `update_ticket_status` → reply and resolve.
4. `create_task` → turn recurring issues into milestone work.

Example first prompt:

> Fetch my support widget embed code and list open tickets. Draft a triage summary and reply templates for the last 5 submissions.

### Security audit funnel (`/audit`)

After signup, pre-signup findings are persisted in `testing_findings` with `source_type: security_analysis`.

1. `list_testing_findings` with `source_type: security_analysis` and `open_only=true`.
2. For each critical/high finding, offer to `create_task` under an existing milestone.
3. When the user asks to re-audit or autofix: `run_testing_loop` with `loop_key: security_audit` and `mode: fix_with_pr` (requires Cursor key + GitHub repo on the project).

Example first prompt:

> List open security findings for this project, grouped by severity. Propose which ones should become tasks first and whether we should re-run security_audit in fix_with_pr mode.

### WebMCP tools (`/webmcp/scan`)

Scan a public page for Chrome WebMCP signals. This is a Tools-hub scanner (`/webmcp/scan`), not a signup funnel and not a certification. Live demo proof is `/webmcp` + `/webmcp.json`. VibeDash does not auto-patch CMS.

```bash
vd webmcp scan https://example.com/contact
vd webmcp connect --url https://example.com/contact
```

The scan returns a readiness checklist, suggested `document.modelContext.registerTool` JS, declarative form HTML, and connect instructions for an in-page agent. Human applies snippets. Re-scan after deploy.

Example first prompt:

> Scan this page for WebMCP readiness, show the checklist gaps, and tell me how an agent can call any discovered tools on the logged-in session. Do not auto-patch the CMS and do not claim certification.

## Prerequisites

| Environment Variable | Required | Description |
|---------------------|----------|-------------|
| `VIBEDASH_API_KEY` | Yes | API key from VibeDash Settings page |
| `VIBEDASH_PROJECT_ID` | Yes | UUID of the target project |
| `VIBEDASH_API_URL` | No | API base URL (defaults to `https://ezdrjodbsdzawsqxasfx.supabase.co`) |

## Authentication

All requests require the API key in headers:

```bash
# Set your defaults
export VIBEDASH_API_URL="${VIBEDASH_API_URL:-https://ezdrjodbsdzawsqxasfx.supabase.co}"

# Headers for all requests
-H "apikey: $VIBEDASH_API_KEY" \
-H "Authorization: Bearer $VIBEDASH_API_KEY"
```

## Read Operations

### List milestones

```bash
curl -s \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  "$VIBEDASH_API_URL/rest/v1/milestones?project_id=eq.$VIBEDASH_PROJECT_ID&deleted_at=is.null&order=due_date.asc"
```

Returns: `[{"id":"uuid","name":"...","description":"...","due_date":"2026-03-01","status":"in-progress","completed_date":null,...}]`

### List tasks for a milestone

```bash
curl -s \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  "$VIBEDASH_API_URL/rest/v1/tasks?milestone_id=eq.MILESTONE_UUID&deleted_at=is.null&order=created_at.desc"
```

Returns: `[{"id":"uuid","title":"...","description":"...","status":"to-do","priority":"...","severity":"...","assigned_to":"uuid","assigned_agents":["cursor"],...}]`

### List open tickets

```bash
curl -s \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  "$VIBEDASH_API_URL/rest/v1/project_tickets?project_id=eq.$VIBEDASH_PROJECT_ID&deleted_at=is.null&status=neq.resolved&order=created_at.desc"
```

Returns: `[{"id":"uuid","title":"...","description":"...","type":"bug","status":"open","priority":"high","severity":"major",...}]`

### Get project details

```bash
curl -s \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  "$VIBEDASH_API_URL/rest/v1/projects?id=eq.$VIBEDASH_PROJECT_ID"
```

Returns: `[{"id":"uuid","name":"...","description":"...","status":"active","github_repo":"https://github.com/...","progress":42,...}]`

### List payments

```bash
curl -s \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  "$VIBEDASH_API_URL/rest/v1/payments?project_id=eq.$VIBEDASH_PROJECT_ID&order=due_date.asc"
```

### List project ideas (current API key owner)

```bash
curl -s \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  "$VIBEDASH_API_URL/functions/v1/vibedash-api/project_ideas?created_by=eq.USER_UUID&order=updated_at.desc"
```

## Write Operations

For MCP-capable agents, use `tools/call` for write operations instead of direct PostgREST RPC calls. The MCP server authenticates the VibeDash API key, checks project permissions for the connected user, and performs the write with the correct server-side context. The curl examples below are useful as API shape references and for legacy agents.

### Create a ticket

```bash
curl -s -X POST \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bug: Login page crashes on mobile",
    "description": "Steps to reproduce:\n1. Open login on iOS Safari\n2. Tap email field\n3. App crashes",
    "type": "bug",
    "severity": "major"
  }' \
  "$VIBEDASH_API_URL/functions/v1/submit-ticket/$VIBEDASH_PROJECT_ID"
```

**Ticket types:** `bug`, `feature`, `improvement`, `question`, `support`
**Severity levels:** `critical`, `major`, `moderate`, `minor`

### Add a message to a ticket

```bash
curl -s -X POST \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket_id": "TICKET_UUID",
    "message": "Investigated this issue. Root cause is a missing viewport meta tag.",
    "sender_name": "Agent"
  }' \
  "$VIBEDASH_API_URL/functions/v1/submit-message"
```

### Create a milestone

```bash
curl -s -X POST \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "p_project_id": "'$VIBEDASH_PROJECT_ID'",
    "p_name": "v2.0 Launch",
    "p_description": "Major release with new dashboard and API",
    "p_due_date": "2026-04-01",
    "p_status": "not-started"
  }' \
  "$VIBEDASH_API_URL/rest/v1/rpc/create_milestone_safe"
```

**Milestone statuses:** `not-started`, `in-progress`, `completed`, `overdue`

### Create a task

```bash
curl -s -X POST \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "p_milestone_id": "MILESTONE_UUID",
    "p_title": "Implement user authentication",
    "p_description": "Add JWT-based auth with email/password login.\n\nAcceptance criteria:\n- Login form with email + password\n- JWT token stored in httpOnly cookie\n- Protected routes redirect to login",
    "p_status": "to-do"
  }' \
  "$VIBEDASH_API_URL/rest/v1/rpc/create_task_safe"
```

**Task statuses:** `to-do`, `in-progress`, `testing`, `revision`, `agent-assigned`, `pr-raised`, `completed`, `archived`

### Create a project idea

```bash
curl -s -X POST \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{
    "name": "AI QA Copilot",
    "flow_type": "idea",
    "summary": "Automate release smoke and regression checks",
    "current_step": "q1",
    "status": "in_progress"
  }' \
  "$VIBEDASH_API_URL/functions/v1/vibedash-api/project_ideas"
```

**Idea status:** `in_progress`, `prd_generated`, `project_created`, `archived` (`draft` should be sent as `in_progress`)
**Note:** `created_by` is always bound server-side to the API key owner.

### Post a meeting summary (spawns milestone + tasks + per-user messages)

A meeting message is a special type of conversation message. Post it in two steps:

**Step 1 — Insert the meeting message** into a project conversation (use any existing `conversation_id` for the project):

```bash
curl -s -X POST \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "CONVERSATION_UUID",
    "message": "Meeting: Agentex MCP & AdSpy Strategy – 2026-02-17\n\nSource: https://fathom.video/share/...",
    "type": "meeting",
    "metadata": {
      "meeting_title": "Agentex MCP & AdSpy Strategy",
      "meeting_date": "2026-02-17",
      "source_url": "https://fathom.video/share/C2d2Bu...",
      "milestone_name": "Meeting Follow-up: Feb 17 Sprint",
      "milestone_due_date": "2026-03-10",
      "participants": ["Nathan", "Nick VD", "Big Steele"],
      "action_items": [
        {
          "title": "Send MCP URL for Agentex to Steele",
          "description": "Share the Agentex MCP URL with Steele and team. Source quote [00:53:26]",
          "assigned_to_name": "Nathan",
          "priority": "high",
          "due_date": "2026-02-18",
          "assign_to_ai": false
        },
        {
          "title": "Improve ad-list UI — clarify column layout for ad counts/likes",
          "description": "Steele feedback: the data column is too small to read at a glance [00:36:08]",
          "assigned_to_name": "Nick VD",
          "priority": "medium",
          "assign_to_ai": true
        }
      ]
    }
  }' \
  "$VIBEDASH_API_URL/rest/v1/conversation_messages"
```

Returns the inserted row including `id` — use that as `MESSAGE_UUID` in step 2.

**Step 2 — Process the meeting message** to spawn the milestone, tasks, and per-user follow-up messages:

```bash
curl -s -X POST \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_id": "MESSAGE_UUID" }' \
  "$VIBEDASH_API_URL/functions/v1/process-meeting-message"
```

Returns:
```json
{
  "success": true,
  "milestone_id": "uuid",
  "tasks": [
    { "id": "uuid", "title": "Send MCP URL...", "status": "to-do", "assigned_to": "profile-uuid", "assign_to_ai": false },
    { "id": "uuid", "title": "Improve ad-list UI...", "status": "agent-assigned", "assigned_to": null, "assign_to_ai": true }
  ],
  "spawned_messages": [
    { "id": "uuid", "recipient_name": "Nathan" },
    { "id": "uuid", "recipient_name": "Nick VD" }
  ],
  "unresolved_participants": ["Big Steele"]
}
```

**`action_items` fields:**

| Field | Required | Description |
|---|---|---|
| `title` | Yes | Task title |
| `description` | No | Task description; include source quotes and timestamps for traceability |
| `assigned_to_name` | No | Name to fuzzy-match against `profiles.name` |
| `priority` | No | `high`, `medium`, `low` (default: `medium`) |
| `due_date` | No | `YYYY-MM-DD` |
| `assign_to_ai` | No | `true` marks the task Cursor-assigned and sets `agent_autopilot_enabled: true` |

**Notes:**
- `metadata.processed` is set to `true` after Step 2; calling Step 2 twice returns a `409` conflict
- Unresolved participant names are posted as a system message in the conversation and returned in `unresolved_participants[]`
- Tasks with `assign_to_ai: true` are automatically marked agent-ready for Cursor/Autopilot pickup
- For manually created tasks, use MCP `create_task` or `update_task` with `agent_autopilot_enabled: true` only when the task has enough description/PRD context to be worked independently
- Every spawned task has `source_conversation_message_id` set — query tasks by meeting: `GET /rest/v1/tasks?source_conversation_message_id=eq.MESSAGE_UUID`

### Query tasks spawned from a meeting

```bash
curl -s \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  "$VIBEDASH_API_URL/rest/v1/tasks?source_conversation_message_id=eq.MESSAGE_UUID&deleted_at=is.null&order=created_at.asc"
```

### Update a task

```bash
curl -s -X POST \
  -H "apikey: $VIBEDASH_API_KEY" \
  -H "Authorization: Bearer $VIBEDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "p_task_id": "TASK_UUID",
    "p_title": "Implement user authentication",
    "p_description": "Updated description...",
    "p_status": "in-progress",
    "p_milestone_id": "MILESTONE_UUID"
  }' \
  "$VIBEDASH_API_URL/rest/v1/rpc/update_task_safe"
```

## Query Filters (PostgREST Syntax)

| Operator | Syntax | Example |
|----------|--------|---------|
| Equals | `eq.` | `?status=eq.active` |
| Not equals | `neq.` | `?status=neq.resolved` |
| Greater than | `gt.` | `?due_date=gt.2026-02-01` |
| Less than | `lt.` | `?due_date=lt.2026-03-01` |
| Is null | `is.null` | `?deleted_at=is.null` |
| Order ascending | `order=field.asc` | `?order=due_date.asc` |
| Order descending | `order=field.desc` | `?order=created_at.desc` |
| Limit results | `limit=N` | `?limit=10` |
| Select fields | `select=f1,f2` | `?select=id,name,status` |

## Common Workflows

### Find the project's first 10 customers

1. Call `get_customer_wallet` and explain the available search balance.
2. Call `prepare_first_customer_agent` and present any clarification questions. Do not create or run an agent until the project context is sufficient.
3. Summarize the proposed product source, ICP, provider, strategy, depth, sources, target count, and one-credit standard-run cost.
4. After the user explicitly approves the spend, call `launch_first_customer_agent` with `confirm_spend: true`.
5. Use `get_customer_agent` to report progress. When the run finishes or is partial, call `list_customer_prospects` and `get_customer_run_report`.
6. Present score dimensions, observed/inferred evidence markers, original source links, cautions, and suggested openers. Do not unlock contacts or send outreach.

### Draft and publish a project story

1. Call `get_blog_settings`. If the profile is incomplete, obtain approval for managed generation, call `prepare_blog_profile` with `confirm_generation: true`, review it with the user, then `apply_blog_profile` on approval.
2. Use `list_blog_sources` to identify the release, roadmap, task, or manual evidence for the story.
3. Create a manual draft or, after explicit generation approval, call `generate_blog_post` with `confirm_generation: true`.
4. Use `get_blog_post`, `list_blog_revisions`, and `preview_blog_revision` to review the result. Submit and approve the intended revision through the review tools.
5. For a download, call `export_blog_revision`. For external publication, list and validate the destination, state the exact revision and destination, and ask for a final confirmation.
6. Only after that confirmation, call `publish_blog_now` or `schedule_blog_publication` with `confirm_publish: true`. Verify the result through `list_blog_publications`.

### Cross-project portfolio triage (admin / multi-project users)

Use this when the connected user can see more than one project and the question is about priorities across the portfolio.

1. Call `get_multi_project_agent_overview` with `{ "limit": 25, "include_clear": false }`.
2. Read `agent_brief` first, then the one-row-per-project `top_next_actions`, then the highest `priority_score` projects.
3. Use `attention_status` and `attention_reasons` for triage. Do **not** treat `quality_status: "pass"` as "nothing to do".
4. For each surfaced project, call the first tool in `recommended_tools` (usually `get_agent_status_snapshot`, then `list_tasks`, `list_tickets`, or `run_testing_loop`).
5. Re-run with `include_clear: true` only when the user explicitly wants QA-evidence-only projects (repos with no recent test run and no open work).

For Relaunch Review recommendations, call `get_relaunch_review_candidates` with `portfolio_read`. Show the proposed projects, runner, workload, and suppression reasons. After explicit confirmation, a separately scoped `portfolio_write` agent may call `start_relaunch_review` once per selected project with a distinct idempotency key. Never infer confirmation from the candidate result.

Signal guide:
- `quality_status` = ship-readiness gate from findings, failed agent work, and recent test runs.
- `evidence_status` = latest test evidence state: `passed`, `failed`, `in_progress`, `missing`, `unknown`, or `not_applicable`. A `quality_status` of `pass` with `evidence_status: missing` is not verified; `not_applicable` means no repository is connected for testing.
- `attention_status` = operational triage signal for what needs human or agent follow-up now.
- `priority_score` = sort key for cross-project urgency.
- `primary_next_action` = the single best next action; use `additional_next_actions` for supporting work. The existing `next_actions` array remains available for compatibility.
- `missing_test_evidence` in `attention_reasons` = repo linked but no recent test run; excluded when `include_clear` is false.

### Rebaseline a late kickoff

When a client starts later than the planned `start_date`, do not edit milestone dates one by one.

1. Call `get_project_summary` and `list_milestones` / `list_payments` so you can explain the current dates.
2. Optionally call `rebaseline_project_timeline` with `dry_run: true` and `new_start_date` to preview the shifted dates.
3. After the user confirms, call `rebaseline_project_timeline` with the same `new_start_date` (omit `dry_run`, or set it false).
4. Completed milestones and paid invoices stay put unless the user explicitly asks to move those too (`include_completed_milestones` / `include_paid_payments`).
5. Summarize the new project window and the moved milestone/payment dates.

Use `update_project` or `update_milestone` only for a single date change. Use `rebaseline_project_timeline` when the whole plan should slide.

### Daily standup summary

1. Query milestones (check deadlines)
2. For each active milestone, query tasks (count completed vs total)
3. Query open tickets (count by severity)
4. Summarise: milestones on-track/at-risk, task completion %, open ticket counts

### Ticket triage

1. Query open tickets ordered by `created_at.desc`
2. For each untriaged ticket, assess severity and type
3. Create follow-up tasks for actionable tickets
4. Add triage comments to tickets

### Sprint health check

1. Query milestones with `status=eq.in-progress`
2. For each, query tasks and calculate completion percentage
3. Flag milestones with <50% completion and due within 7 days
4. Identify stale tasks (no status change in 3+ days)

### Blocker escalation

1. Identify blocked tasks or critical tickets
2. Create high-priority tickets for unresolved blockers
3. Add comments with proposed resolution paths

## Error Handling

- **401 Unauthorized**: Invalid API key – check `VIBEDASH_API_KEY` is correct
- **404 Not Found**: Invalid project ID or resource UUID
- **400 Bad Request**: Missing required fields in request body
- **409 Conflict**: Duplicate resource (e.g., ticket already exists)

All error responses return JSON: `{"error": "message"}` or `{"error": "message", "details": "..."}`

## Tips

- Always filter with `deleted_at=is.null` to exclude soft-deleted records
- Use `select=` to limit response fields and reduce payload size
- Pipe responses through `jq` for parsing: `curl ... | jq '.[] | {id, name, status}'`
- Ticket creation via `submit-ticket` auto-triggers AI agent assignment if configured
- Tasks with `assigned_agents` array are being worked on by AI coding agents