Cursor Rules for PageGun

---
description: Manage PageGun projects, landing pages, subroutes, media, and publishing via the PageGun API. For article or blog content use the pagegun-articles skill; for documentation pages use the pagegun-docs skill.
globs: 
alwaysApply: false
---

# PageGun API Skill

Use this skill when a user wants to inspect, create, update, or publish content in PageGun.

For article/blog operations, load the `pagegun-articles` skill — it has the full article workflow, list rules, and markdown embeds.

For documentation pages, load the `pagegun-docs` skill — it has nested slugs, sidebar navigation, and docs markdown directives.

## Auth

Use the API key from `PAGEGUN_API_KEY`.

All requests must include:

```bash
Authorization: Bearer $PAGEGUN_API_KEY
```

## Base URL

```bash
https://api.pagegun.com
```

## Endpoint Split

- `/pages` is for landing pages only (`type: "page"`).
- `/articles` is for article/blog/news content (`type: "article"`).
- `/docs` is for docs content (`type: "docs"`).
- Publish and unpublish always go through `/pages/{id}/publish` and `/pages/{id}/unpublish`, regardless of content type.
- If the API returns `wrong_endpoint`, switch to the dedicated endpoint instead of retrying the same call.

## Which Endpoint to Use

| Content type | Create | Update | Publish |
|--------------|--------|--------|---------|
| Landing page | `POST /pages` | `PUT /pages/:id` | `POST /pages/:id/publish` |
| Article | `POST /articles` | `PUT /articles/:id` | `POST /pages/:id/publish` |
| Docs | `POST /docs` | `PUT /docs/:id` | `POST /pages/:id/publish` |

## Projects

```bash
GET /projects
GET /projects/{project_id}
PUT /projects/{project_id}
```

## Pages (Landing Pages)

```bash
GET /pages?project_id={project_id}
POST /pages
GET /pages/{page_id}
PUT /pages/{page_id}
POST /pages/{page_id}/publish
POST /pages/{page_id}/unpublish
```

## Subroutes

```bash
GET /subroutes?project_id={project_id}
POST /subroutes
GET /subroutes/{slug}?project_id={project_id}
PUT /subroutes/{slug}?project_id={project_id}
DELETE /subroutes/{slug}?project_id={project_id}
GET /subroutes/{slug}/pages?project_id={project_id}
```

- Articles live under subroutes like `blog`, `news`, or `changelog`.
- Docs use the `docs` subroute automatically.
- Navigation lives on the subroute config, not on individual pages.
- Updating subroute navigation republishes the sidebar.

## Authors and Media

```bash
GET /authors?project_id={project_id}
POST /authors
PUT /authors/{author_id}

GET /media?project_id={project_id}
POST /media
```

## Discovery Workflow

- If the user did not specify a project, list projects first.
- If the user did not specify a target page, use the correct list endpoint first.
- Read before write.
- Apply minimal updates instead of full-object overwrites.
- Never print or echo the raw API key.

---
description: Manage PageGun article, blog, and news content via the PageGun Articles API. Use when listing articles, creating blog posts, updating article markdown, publishing articles, or working with article markdown embeds like video.
globs: 
alwaysApply: false
---

# PageGun Articles Skill

Use the Articles API for all blog, news, and article content in PageGun.

## Auth

All requests require `Authorization: Bearer $PAGEGUN_API_KEY`. Base URL: `https://api.pagegun.com`.

## Endpoint Summary

| Action | Endpoint |
|--------|----------|
| List | `GET /articles?project_id=xxx&subroute=blog` |
| Create | `POST /articles` |
| Read | `GET /articles/{id}` |
| Update | `PUT /articles/{id}` |
| Publish | `POST /pages/{id}/publish` |
| Unpublish | `POST /pages/{id}/unpublish` |

Publish/unpublish go through `/pages`, not `/articles`.

## Article Rules

- `GET /articles` requires both `project_id` and `subroute`.
- Default list size is `50`. Pass `limit` explicitly for other sizes.
- Sorting supports `sort=published_at|created_at|updated_at|title`.
- Ordering supports `order=asc|desc`.
- For the oldest articles, use `sort=created_at&order=asc`.
- Updating an article title does not imply a slug change. Only send `slug` when the user explicitly wants the URL changed.

## List Articles

### Newest first

```bash
curl -sS "https://api.pagegun.com/articles?project_id=YOUR_PROJECT_ID&subroute=blog" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"
```

### Earliest 3 posts

```bash
curl -sS "https://api.pagegun.com/articles?project_id=YOUR_PROJECT_ID&subroute=blog&sort=created_at&order=asc&limit=3" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"
```

## Create an Article

```bash
curl -sS -X POST "https://api.pagegun.com/articles" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How We Demo Product Updates",
    "slug": "how-we-demo-product-updates",
    "subroute": "blog",
    "project_id": "YOUR_PROJECT_ID",
    "description": "A short walkthrough of our release demo workflow.",
    "markdown_content": "# How We Demo Product Updates\n\n::video[https://www.youtube.com/watch?v=dQw4w9WgXcQ]\n"
  }'
```

Useful optional fields: `slug`, `description`, `og_image_url`, `categories`, `author_id`, `locale`.

## Update an Article

```bash
curl -sS -X PUT "https://api.pagegun.com/articles/ARTICLE_ID" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How We Demo Product Updates",
    "description": "Updated SEO description.",
    "markdown_content": "# How We Demo Product Updates\n\nUpdated body."
  }'
```

If the user explicitly wants a new URL, send `slug` in the update body. Otherwise leave it alone.

## Publish an Article

```bash
curl -sS -X POST "https://api.pagegun.com/pages/ARTICLE_ID/publish" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"
```

## Article Markdown

Article body lives in `markdown_content`. Use standard markdown for headings, lists, links, images, code blocks, tables, and blockquotes.

### Video Embeds

Use a single `::video[URL]` directive with the full video URL:

```markdown
::video[https://www.youtube.com/watch?v=dQw4w9WgXcQ]
```

- YouTube and Vimeo URLs are supported.
- Append `?t=1m30s` to the URL for a start timestamp.
- Raw `<iframe>` HTML is not supported.
- Use image markdown for images: `![Alt text](https://...)`

## CDN Reads

Published articles are available on the CDN:

- `https://content.pagegun.com/{project_id}/{subroute}/{slug}.enc`
- `https://content.pagegun.com/{project_id}/nav.enc`

If you just need article listings, prefer the Articles API over CDN parsing.

## Safety

- Read the article before overwriting it.
- Keep `slug` stable unless the user explicitly wants a URL change.
- Publish after every article update that should go live.
- Never print the raw API key.

---
description: Manage PageGun documentation pages via the PageGun Docs API. Use when creating docs pages, working with nested slugs, updating docs navigation/sidebar, or using docs markdown directives like cards, callouts, steps, and code tabs.
globs: 
alwaysApply: false
---

# PageGun Docs Skill

Use the Docs API for documentation pages in PageGun.

## Auth

All requests require `Authorization: Bearer $PAGEGUN_API_KEY`. Base URL: `https://api.pagegun.com`.

## Endpoint Summary

| Action | Endpoint |
|--------|----------|
| List | `GET /docs?project_id=xxx` |
| Create | `POST /docs` |
| Read | `GET /docs/{id}` |
| Update | `PUT /docs/{id}` |
| Publish | `POST /pages/{id}/publish` |
| Unpublish | `POST /pages/{id}/unpublish` |

Publish/unpublish go through `/pages`, not `/docs`.

## Create a Doc

```bash
curl -sS -X POST "https://api.pagegun.com/docs" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Authentication",
    "project_id": "YOUR_PROJECT_ID",
    "slug": "api/authentication",
    "markdown_content": "# Authentication\n\nOur API uses Bearer tokens."
  }'
```

Required fields: `title`, `project_id`, `markdown_content`.

Optional fields: `slug`, `description`, `og_image_url`, `locale`.

## Update a Doc

```bash
curl -sS -X PUT "https://api.pagegun.com/docs/DOC_ID" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Authentication",
    "markdown_content": "# Updated Authentication\n\nNew content."
  }'
```

## Publish a Doc

```bash
curl -sS -X POST "https://api.pagegun.com/pages/DOC_ID/publish?project_id=YOUR_PROJECT_ID" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"
```

## Nested Slugs

Use `/` in doc slugs for hierarchy:

```text
overview
quickstart
api/authentication
api/pages/create
guides/webhooks/setup
agents/best-practices
```

## Navigation

Docs sidebar navigation lives on the `docs` subroute:

```bash
curl -sS -X PUT "https://api.pagegun.com/subroutes/docs?project_id=YOUR_PROJECT_ID" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "navigation": {
      "groups": [
        {"group": "Getting Started", "pages": ["overview", "quickstart"]},
        {"group": "API", "pages": ["api/authentication", "api/pages/create"]}
      ]
    }
  }'
```

Updating subroute navigation republishes the sidebar.

## Docs Markdown Directives

### Cards

```markdown
:::cards
- title: Quick Start
  href: /docs/quick-start
  description: Get up and running in 5 minutes
  icon: rocket
:::
```

### Callouts

```markdown
:::callout{type="info"}
This is an informational note.
:::
```

### Steps

````markdown
:::steps
### Create an API Key

Go to Settings -> API Keys and click "Create".

### Make Your First Request

```bash
curl https://api.pagegun.com/projects \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"
```
:::
````

### Code Tabs

````markdown
:::code-tabs
```bash
curl https://api.pagegun.com/projects \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"
```

```javascript
const res = await fetch('https://api.pagegun.com/projects', {
  headers: { Authorization: `Bearer ${API_KEY}` },
})
```
:::
````

## Images in Docs

Upload via `POST /media`, then reference with standard markdown:

```bash
curl -sS -X POST "https://api.pagegun.com/media" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -F "file=@./screenshot.png" \
  -F "project_id=YOUR_PROJECT_ID" \
  -F "alt_text=Dashboard screenshot"
```

```markdown
![Dashboard screenshot](RETURNED_URL_HERE)
```

## Safety

- Use `/docs`, not `/pages`, for docs writes.
- Read the current doc before updating it.
- Publish after every doc update that should go live.
- Never print the raw API key.