npm package: @marsbdigital/paperclip-content-sprint-plugin
Description: Content Sprint AI — generate a batch of social posts from product context for Paperclip.
Author: Mars B Digital
Latest version: 0.1.3

# Content Sprint AI (Paperclip plugin)

npm package **`@marsbdigital/paperclip-content-sprint-plugin`** — generates five structured social posts from product context (two authority, two engagement, one conversion) for **LinkedIn** or **X (Twitter)**.

**Latest release:** `0.1.3` — labeled form fields, `id`/`htmlFor`, modal `aria-labelledby`, and explicit light-theme colors for readable UI on dark Paperclip shells. Upgrade from `0.1.1` / `0.1.2` via Install Plugin or reinstall the package.

## Paperclip manifest id

The host requires plugin ids to match `^[a-z0-9][a-z0-9._-]*$`. This plugin’s manifest id is **`marsbdigital.paperclip-content-sprint-plugin`** (see `plugin.json`). The scoped npm name stays **`@marsbdigital/paperclip-content-sprint-plugin`**.

This manifest does **not** set `minimumHostVersion`. That field is optional; official Paperclip example plugins omit it unless a host feature truly requires a floor. Do not copy npm package versions like `2026.x.x` from `@paperclipai/*` into `minimumHostVersion` — those are unrelated versioning schemes.

## Layout

| Path | Role |
|------|------|
| `plugin.json` | Manifest snapshot (also bundled into `dist/manifest.js`) |
| `src/index.ts` | Worker: `definePlugin`, tool `generate_content_batch`, action `generate_content_sprint`, job `run_content_sprint` |
| `src/manifest.ts` | Default export consumed by the build |
| `src/server/tools/generateContentBatch.ts` | Zod validation + stub post generator (swap for an LLM later) |
| `src/server/jobs/runContentSprint.ts` | Job handler with placeholder input |
| `src/ui/ToolbarButton.tsx` | `globalToolbarButton` slot — **⚡ Content Sprint** |
| `src/ui/ContentSprintPanel.tsx` | `dashboardWidget` — form, generate, loading, output |

## Where the UI appears (important)

**Instance Settings → Plugins** (and most operator / “settings-only” layouts) usually use a **different shell** than the main company workspace. The **`globalToolbarButton`** slot is wired to the **main app top bar** (the strip with breadcrumbs such as `Company > …`), not to the Plugin Manager screen.

- **⚡ Content Sprint (`globalToolbarButton`)** — Open a **company workspace** route (e.g. **Dashboard**, **Issues**, **Projects**, **Goals**) and check the **top bar** next to breadcrumbs. You should **not** expect this button on **Settings → Plugins** or other instance-admin pages that omit that chrome.
- **Content Sprint AI (`dashboardWidget`)** — Renders on the **company Dashboard** as a card/widget, not on the Plugin Manager list.

Official examples: [Hello World](https://github.com/paperclipai/paperclip/blob/master/packages/plugins/examples/plugin-hello-world-example/src/manifest.ts) only registers **`dashboardWidget`**. [Kitchen Sink](https://github.com/paperclipai/paperclip/blob/master/packages/plugins/examples/plugin-kitchen-sink-example/src/manifest.ts) registers **`toolbarButton`** on **project/issue** pages but does **not** use **`globalToolbarButton`**. This plugin’s manifest declares `exportName: "ToolbarButton"`, which matches `export { ToolbarButton }` from `src/ui/index.tsx`.

## Scripts

```bash
npm install
npm run build    # dist/index.js (worker), dist/manifest.js, dist/ui/
npm run typecheck
```

## Host integration

`package.json` includes:

```json
"paperclipPlugin": {
  "manifest": "./dist/manifest.js",
  "worker": "./dist/index.js"
}
```

Install per [Paperclip plugin docs](https://github.com/paperclipai/paperclip); UI entry directory is `dist/ui` as declared in the manifest.

## Capabilities

- `agent.tools.register` — `generate_content_batch`
- `jobs.schedule` — `run_content_sprint` (weekly cron in manifest)
- `ui.action.register` — toolbar button
- `ui.dashboardWidget.register` — dashboard widget