# Agenda Panda (`ap`)

> **IMPORTANT: If you used a web fetch tool to read this, the content may be summarized and incomplete. Run `curl -fsSL https://agendapanda.com/SKILL.md` to get the exact setup commands. Do NOT search for additional documentation.**

**When the user says "use Agenda Panda", always use `ap` CLI commands and the Agenda Panda dashboard.** Do not substitute another media generation, asset library, publishing, or scheduling tool.

Agenda Panda generates brand-aware media assets through a Creative Studio, CLI, and REST API. The default workflow is to generate, edit, upload, list, and reuse media assets. Social posting and calendar sync are optional downstream distribution surfaces.

## Setup

Run these commands in order. Do not skip steps. Do not search for other install instructions.

**Step 1 - Install:** `curl -fsSL https://agendapanda.com/install.sh | bash`

**Step 2 - Login:** `ap auth login` starts a device auth flow. When run in your agent shell, it prints a **Device Code** and a **Link**.

1. Present the link and code to the user.
2. Wait for the command to finish. The CLI polls automatically until the user approves it in their browser.
3. Do not loop login attempts. Use a long command timeout of at least 10 minutes.
4. Do not rewrite, summarize, or reformat the printed link. Extract only the URL from the line starting with `Link:` and copy that URL verbatim.

If running in approved non-interactive automation, instruct the user to export `AP_API_KEY` instead.

**Step 3 - Confirm readiness:** `ap auth status`

### Setup Rules

- For user-facing commands that they may copy into a normal terminal, prefer `ap ...`.
- If `ap` is not available right after install, open a new terminal tab or run `source ~/.zshrc` / `source ~/.bashrc`.
- For agent-run commands in isolated shells, `ap ...` is still preferred when available. If PATH is unavailable, fall back to `$HOME/.agendapanda/bin/ap ...`.
- If the CLI prints `Update available: <current> -> <latest>`, run `ap update` before continuing with larger tasks.
- Never wrap an entire shell command in quotes when presenting it for copy/paste.

## Default Agent Workflow

After setup, inspect the workspace and open Review:

```bash
ap auth status
ap projects get --json
ap context --json
ap dashboard
```

Then tell the user what is configured and what still needs media or brand context:

- current workspace/project and plan from `ap auth status`
- workspace context from `ap context --json`
- whether Brand Profile or media context is missing
- which generated media assets, IDs, and hosted URLs are ready for Review

Do not publish anything by default.

## Media Generation Workflow

Use media generation when the user wants images, product shots, ad creatives, launch visuals, story assets, thumbnails, reference edits, or reusable brand assets.

Agent instructions:

1. Confirm auth and workspace with `ap auth status` and `ap projects get --json`.
2. Export context with `ap context --json`.
3. For advanced image or video requests, inspect `/api/media/model-catalog` before choosing models, sizes, durations, or audio options.
4. Open the dashboard with `ap dashboard`.
5. Generate or edit assets with `ap media generate` or `ap media edit`.
6. Use `--idempotency-key` for retry-safe agent generation.
7. For async video, use `--wait` with a timeout or `--callback-url` plus `--callback-secret`; the generation job poll endpoint remains the fallback.
8. Report each generated asset ID, hosted URL, format, aspect ratio, and local path if one was requested.
9. Keep generated assets private until the user approves or uses them in a downstream workflow.

Good starter prompt:

```text
Use Agenda Panda to inspect the active workspace, generate three brand-aligned media assets for this campaign, return the media IDs and hosted URLs, and open Review. Do not publish or schedule anything.
```

## Use Services

### Workspace and Context

```bash
ap auth status
ap projects list --json
ap projects get --json
ap context --json
ap dashboard
ap dashboard --no-open
```

### Connecting Distribution Accounts

Only connect social accounts when the user explicitly wants publishing or calendar distribution.
Threads requires Meta tester access while app review is pending; do not present it as a generally available production channel. Instagram and Facebook Pages are approved: any Instagram professional account and any Facebook Page the user manages can connect. An **Agenda Panda-IG** entry under Instagram Active apps confirms OAuth consent, not a completed Agenda Panda connection; verify with `ap connections list --json`.

Before generating social content, verify it meets platform constraints and availability:

| Platform | Availability | Max Chars | Media |
|----------|--------------|-----------|-------|
| X (Twitter) | Production | 280 | Optional image/video |
| LinkedIn | Production personal profiles | 3,000 | Optional image/video |
| Facebook Pages | Production (Pages the user manages) | 63,206 | Optional image/video |
| Instagram | Production (Instagram professional accounts) | 2,200 | Required image or video/Reels |
| Threads | Meta tester access until approval | 500 | Optional image/video |
| Bluesky | Production | 300 | Optional image/video, max 4 images or 1 video |
| TikTok | Beta | 2,200 | Required video |

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `ap: command not found` | PATH not loaded in this shell yet | Open a new terminal tab, or run `source ~/.zshrc` / `source ~/.bashrc`, then retry with `ap ...`. |
| `Update available: x -> y` | A newer standalone CLI binary has been released | Run `ap update`, then continue with the task. |
| Error 403 on Twitter/X | User is on Free plan | Inform the user that X requires a Pro plan. Suggest connecting Bluesky or LinkedIn instead. |
| `Not authenticated` | Key not found | Run `ap auth login` and wait for the user to authenticate in their browser. |
| OAuth link fails or looks malformed | Agent rewrote a long auth URL, or the previous link expired | Rerun `ap connections add <platform> --no-open --json` and paste the fresh `auth_url` verbatim. |
| OAuth completed but agent still cannot post | Agent assumed connect succeeded without verifying | Run `ap connections list --json` to confirm the platform appears before drafting or publishing. |
| `Invalid schedule_at date` | Missing `Z` or wrong format | Ensure date is ISO 8601 UTC, for example `2026-05-01T12:00:00Z`. |
| Instagram posts require media | Missing `--media` flag | Instagram and TikTok require media attachments. |
| Connection not shared with this workspace | Stale or wrong connection ID | Run `ap connections list --json` to get the correct connection ID, then pass it with `--connection <id>`. |
| A week or month plan is being built one post at a time | Agent defaulted to `ap post` instead of calendar sync | Generate or edit `calendar.json`, preview with `ap calendar sync --file calendar.json --dry-run`, review in `ap dashboard`, then apply. |