# Marketing Framework API

This folder is the machine-readable side of the Club 52 Marketing Framework module. It's plain static files, so anything that can make an HTTP request (or read a file) can use it — no server code, no keys.

## Files

| File | What it is | Who uses it |
|---|---|---|
| `framework.json` | **Canonical source of truth.** Mission, lanes, rules, workflows, idea backlog, changelog. | AI agents, scripts, anything programmatic |
| `agent-reference.md` | The framework formatted as a drop-in system prompt with agent rules and an output format. | Paste into any AI agent's instructions, or have the agent fetch it |
| `framework.js` | The exact same data as `framework.json`, wrapped in `window.CLUB52_FRAMEWORK` so the interface (`../index.html`) works even opened straight from disk. | The module's own UI only |
| `log.php` | The shared team log API — team-wide weekly mix counts, published-post log, and idea submissions. Reads are public; writes need the `X-Team-Key` header. | The UI's shared mode + AI agents |

**Server-only files (never in the local deploy folder, never overwrite):** `teamkey.php` (the team key) and `data/` (`published-log.json`, `ideas.json` — the live team data). Deploys via `scp -r marketing` leave them untouched because they don't exist locally; keep it that way.

**Keep-in-sync rule:** `framework.json` and `framework.js` must always carry identical data. When updating the framework, change both (asking Claude to make the change handles this automatically). Drift check — run from this folder; must print `SYNC OK`:

```
node -e "global.window={};const fs=require('fs');eval(fs.readFileSync('framework.js','utf8'));const a=window.CLUB52_FRAMEWORK,b=JSON.parse(fs.readFileSync('framework.json','utf8'));const s=o=>Array.isArray(o)?o.map(s):(o&&typeof o==='object'?Object.keys(o).sort().reduce((r,k)=>(r[k]=s(o[k]),r),{}):o);console.log(JSON.stringify(s(a))===JSON.stringify(s(b))?'SYNC OK':'DRIFT DETECTED')"
```

The version in `agent-reference.md`'s header must also match `framework.json`'s `version` on every bump.

## Using it with AI agents

**Option A — paste:** Copy `agent-reference.md` into the agent's system prompt / custom instructions.

**Option B — fetch (once deployed):** Point the agent at the live URL so it always has the current version:

```
Before drafting any Club 52 marketing content, fetch
https://hq.club52poker.com/marketing/api/framework.json and follow its lanes, rules,
and test questions. Declare one lane per piece and run its test.
```

**Option C — code:**

```js
const fw = await fetch("https://hq.club52poker.com/marketing/api/framework.json").then(r => r.json());
const lane = fw.lanes.find(l => l.id === "education");
```

Replace `https://hq.club52poker.com` with wherever the HQ deploy lives (VPS web root `/var/www/hq` → this folder serves at `/marketing/api/`).

## Write API (team key required)

Writes go to `log.php` with an `X-Team-Key` header. The key lives server-side in `teamkey.php`; ask Mike for it. Examples:

```bash
# Log a published post (updates the team-wide weekly mix)
curl -X POST https://hq.club52poker.com/marketing/api/log.php \
  -H "Content-Type: application/json" -H "X-Team-Key: KEY" \
  -d '{"action":"publish","lane":"entertainment","title":"All-in reel","by":"mike"}'

# Undo the latest entry for a lane this week
curl -X POST ... -d '{"action":"retract","lane":"entertainment"}'

# Submit an idea to the shared board
curl -X POST ... -d '{"action":"idea","lane":"community","title":"Dealer spotlight","notes":"...","by":"mike"}'

# Reads are public:
curl https://hq.club52poker.com/marketing/api/log.php?action=mix
curl "https://hq.club52poker.com/marketing/api/log.php?action=log&limit=20"
curl https://hq.club52poker.com/marketing/api/log.php?action=ideas
```

Weeks run Monday–Sunday (America/Chicago). The UI's "This Week's Mix" and idea board use these same endpoints automatically when online; humans are asked for the team key once and it's remembered per browser.

## Expanding the module

- **New idea:** add an object to `ideas` (`lane`, `title`, `notes`, `status`).
- **New workflow:** add an object to `workflows` (`id`, `name`, `description`, `steps[]`).
- **Lane changes:** edit the lane's entry — the interface re-renders from data automatically.
- **Weekly targets:** tune `weeklyTargets` to change the goals in the interface's "This Week's Mix" tracker.
- **Any change:** bump `version`, set `updated`, and add a `changelog` entry.

The interface at `../index.html` renders 100% from this data, so expanding the API expands the UI for free.