@pplethai/cli 0.1.0

package/dist/session.js

@@ -0,0 +1,29 @@
+import { loadCredentials, saveCredentials } from "./credentials.js";
+import { refresh } from "./device-flow.js";
+import { SIGN_IN_EXPIRED, SIGNED_OUT } from "./errors.js";
+import { ProvisionerClient } from "./api.js";
+/** Refresh this long before expiry, so a command doesn't die mid-flight. */
+const EXPIRY_MARGIN_MS = 60_000;
+/**
+ * The access token for this command, refreshed if it is about to expire. The
+ * only way a command gets to talk to the platform.
+ */
+export async function accessToken(deps) {
+    const stored = await loadCredentials(deps);
+    if (!stored)
+        throw SIGNED_OUT;
+    const expiring = stored.expiresAt !== null && stored.expiresAt - deps.now() < EXPIRY_MARGIN_MS;
+    if (!expiring)
+        return stored.accessToken;
+    if (stored.refreshToken) {
+        const renewed = await refresh(deps, stored.refreshToken);
+        if (renewed) {
+            await saveCredentials(deps, { ...renewed, ssoBase: deps.config.ssoBase });
+            return renewed.accessToken;
+        }
+    }
+    throw SIGN_IN_EXPIRED;
+}
+export async function client(deps) {
+    return new ProvisionerClient(deps, await accessToken(deps));
+}

package/dist/skills.js

@@ -0,0 +1,86 @@
+// Platform Skills as a local overlay in each Builder App workspace.
+// Overwrites only `.claude/skills/pple-platform/`; sibling skills are left alone.
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { MANUAL_INSTALL } from "./npm.js";
+/** Where the platform Skill lands inside a Builder App workspace. */
+export const PLATFORM_SKILL_REL = path.join(".claude", "skills", "pple-platform");
+/** The only Skills path that belongs in the app's `.gitignore` (posix form). */
+export const PLATFORM_SKILL_IGNORE = `${PLATFORM_SKILL_REL.split(path.sep).join("/")}/`;
+/**
+ * Refresh the platform Skill overlay from the CLI bundle. Prints only when
+ * the managed content actually changed (first install or update).
+ */
+export async function refreshSkills(deps, appDir) {
+    const source = deps.skillsDir;
+    const entries = await fs.readdir(source).catch(() => null);
+    if (entries === null) {
+        throw new CliError("The PPLE platform Skills are missing from this installation of the CLI.", `Reinstall the CLI (\`${MANUAL_INSTALL}\`) and try again.`);
+    }
+    const destination = path.join(appDir, PLATFORM_SKILL_REL);
+    const before = await contentFingerprint(destination);
+    await replaceDir(source, destination);
+    await ensureIgnored(appDir);
+    const after = await contentFingerprint(destination);
+    if (before === after)
+        return;
+    deps.out.say(before === null ? "Installed platform Skills." : "Updated platform Skills.");
+}
+async function replaceDir(from, to) {
+    await fs.rm(to, { recursive: true, force: true });
+    await copyDir(from, to);
+}
+async function copyDir(from, to) {
+    await fs.mkdir(to, { recursive: true });
+    for (const entry of await fs.readdir(from, { withFileTypes: true })) {
+        if (entry.name === ".DS_Store")
+            continue;
+        const src = path.join(from, entry.name);
+        const dst = path.join(to, entry.name);
+        if (entry.isDirectory())
+            await copyDir(src, dst);
+        else
+            await fs.copyFile(src, dst);
+    }
+}
+/** Stable hash of every file under `dir`, or null when the tree is missing. */
+async function contentFingerprint(dir) {
+    const files = await listFiles(dir).catch(() => null);
+    if (files === null)
+        return null;
+    const hash = createHash("sha256");
+    for (const relative of files.sort()) {
+        hash.update(relative);
+        hash.update("\0");
+        hash.update(await fs.readFile(path.join(dir, relative)));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+async function listFiles(dir, prefix = "") {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (entry.name === ".DS_Store")
+            continue;
+        const relative = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+        if (entry.isDirectory()) {
+            files.push(...(await listFiles(path.join(dir, entry.name), relative)));
+        }
+        else {
+            files.push(relative);
+        }
+    }
+    return files;
+}
+async function ensureIgnored(appDir) {
+    const ignorePath = path.join(appDir, ".gitignore");
+    const existing = await fs.readFile(ignorePath, "utf8").catch(() => "");
+    const lines = existing.split("\n");
+    if (lines.some((line) => line.trim() === PLATFORM_SKILL_IGNORE))
+        return;
+    const body = existing.endsWith("\n") || existing === "" ? existing : `${existing}\n`;
+    await fs.writeFile(ignorePath, `${body}${PLATFORM_SKILL_IGNORE}\n`);
+}

package/dist/ui.js

@@ -0,0 +1,12 @@
+export function consoleOutput(write, writeError) {
+    return {
+        say(line = "") {
+            write(`${line}\n`);
+        },
+        fail(error) {
+            writeError(`${error.message}\n`);
+            if (error.hint)
+                writeError(`${error.hint}\n`);
+        },
+    };
+}

package/dist/update.js

@@ -0,0 +1,142 @@
+// The CLI keeping itself current: the daily check that rides along with
+// ordinary commands, and the words both it and `pple upgrade` use — one
+// upgrade story reaches a Builder, however they arrived at it.
+//
+// The check runs before the command the Builder typed, which is the only
+// moment an upgrade is safe: nothing is half-done yet, so the new CLI can
+// simply be handed the same command line. Everything here is written to fail
+// towards the command — a quiet npm, a missing config directory, a refused
+// upgrade all end with `pple deploy` deploying.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { installGlobally, isNewer, isNpmGlobalInstall, latestVersion, MANUAL_INSTALL, npmMessage, } from "./npm.js";
+/** About once a day, per machine — not per app, and not per command. */
+const CHECK_INTERVAL = 24 * 60 * 60 * 1000;
+/** Cadence state, beside credentials.json and well away from any app repo. */
+const STATE_FILE = "update-check.json";
+/** The Builder's own settings for this CLI, the other half of the opt-out. */
+const CONFIG_FILE = "config.json";
+/**
+ * Commands that already answer the version question themselves, or that
+ * print and exit. `upgrade` doing its own check twice would be silly; help
+ * should never touch the network.
+ */
+const UNCHECKED = new Set(["upgrade", "help", "--help", "-h"]);
+export function wantsUpdateCheck(argv) {
+    return argv.length > 0 && !UNCHECKED.has(argv[0]);
+}
+/** The one line that opens every "there's a newer pple" conversation. */
+export function announceUpdate(deps, latest) {
+    deps.out.say(`There's a newer pple (${latest}). You have ${deps.version}.`);
+}
+/**
+ * What to say about an install npm's global root doesn't hold. Installing
+ * over it would leave the Builder with two pples and no way to tell which
+ * one just ran (ADR-0007).
+ */
+export function sayOtherChannel(deps) {
+    deps.out.say("This copy of pple didn't come from npm, so updating it here");
+    deps.out.say("could leave you with two versions. Update it the way you");
+    deps.out.say(`installed it, or install it with npm:\n\n  ${MANUAL_INSTALL}`);
+}
+/** Why npm gave up, and the line the Builder can always run themselves. */
+export function manualHint(result) {
+    return `${npmMessage(result)}\n\nTry running it yourself:\n\n  ${MANUAL_INSTALL}`;
+}
+/**
+ * Look for a newer CLI, and act on it as far as this session allows. Returns
+ * an exit code when the command has already been dealt with — the CLI
+ * upgraded and re-ran it, or the Builder chose to stop — and null to let the
+ * command the Builder typed run as usual.
+ */
+export async function checkForUpdate(deps, argv) {
+    if (!(await isDue(deps)))
+        return null;
+    await recordCheck(deps);
+    const latest = await latestVersion(deps);
+    // A quiet registry is not the Builder's problem: no message, no delay
+    // tomorrow — the command simply carries on.
+    if (latest === null || !isNewer(latest, deps.version))
+        return null;
+    announceUpdate(deps, latest);
+    // The channel comes before the terminal: an install npm doesn't own can't
+    // be upgraded by anyone here, so pointing at `pple upgrade` — which would
+    // only refuse — helps nobody, attended or not.
+    if (!(await isNpmGlobalInstall(deps))) {
+        sayOtherChannel(deps);
+        deps.out.say();
+        return null;
+    }
+    if (!deps.interactive) {
+        deps.out.say("Run `pple upgrade` when you're ready.");
+        deps.out.say();
+        return null;
+    }
+    if (!(await deps.confirm("Update pple now?"))) {
+        deps.out.say();
+        return null;
+    }
+    const result = await installGlobally(deps, latest);
+    if (result.code !== 0)
+        return await afterFailedUpgrade(deps, latest, result);
+    deps.out.say(`pple is now ${latest}. Picking up where you left off…`);
+    deps.out.say();
+    return deps.reexec(argv);
+}
+/**
+ * A failed upgrade must not strand the work the Builder came to do. Say what
+ * npm said, leave them the line they can run themselves, and offer to get on
+ * with the command on the CLI they already have. Only an attended run can
+ * arrive here at all — an unattended one is never upgrading in the first
+ * place — so carrying on is a question, not a default.
+ */
+async function afterFailedUpgrade(deps, latest, result) {
+    deps.out.say(`Couldn't update pple to ${latest}.`);
+    deps.out.say(manualHint(result));
+    deps.out.say();
+    if (await deps.confirm(`Carry on with pple ${deps.version} for now?`)) {
+        deps.out.say();
+        return null;
+    }
+    deps.out.say("Stopped. Nothing has changed.");
+    return 1;
+}
+async function isDue(deps) {
+    if (!deps.updateChecks)
+        return false;
+    if (!(await configAllowsChecks(deps)))
+        return false;
+    const state = await readJson(path.join(deps.configDir, STATE_FILE));
+    if (typeof state?.lastCheckedAt !== "number")
+        return true;
+    return deps.now() - state.lastCheckedAt >= CHECK_INTERVAL;
+}
+/**
+ * Record the attempt, not the outcome: a registry that is down today should
+ * cost one request, not one per command until it comes back. Unwritable
+ * config is not worth a word to the Builder — checking again is harmless.
+ */
+async function recordCheck(deps) {
+    const state = { lastCheckedAt: deps.now() };
+    await fs
+        .mkdir(deps.configDir, { recursive: true })
+        .then(() => fs.writeFile(path.join(deps.configDir, STATE_FILE), `${JSON.stringify(state, null, 2)}\n`))
+        .catch(() => undefined);
+}
+/** `{ "updateCheck": false }` turns the check off for this machine. */
+async function configAllowsChecks(deps) {
+    const config = await readJson(path.join(deps.configDir, CONFIG_FILE));
+    return config?.updateCheck !== false;
+}
+/** Parsed JSON, or null for a file that is missing, unreadable, or malformed. */
+async function readJson(file) {
+    const raw = await fs.readFile(file, "utf8").catch(() => null);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@pplethai/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PPLEThai/pple-platform.git",
+    "directory": "cli"
+  },
+  "bin": {
+    "pple": "dist/bin.js"
+  },
+  "files": [
+    "askpass",
+    "dist",
+    "skills",
+    "templates"
+  ],
+  "scripts": {
+    "build": "npm run build:template && npm run build:skills && tsc -p tsconfig.build.json",
+    "build:template": "node scripts/bundle-template.mjs",
+    "build:skills": "node scripts/bundle-skills.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/skills/pple-platform/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: pple-platform
+description: >
+  Build Builder Apps on the PPLE Platform — the People's Party (พรรคประชาชน)
+  digital infrastructure: PPLE ID single sign-on, PPLE Today mini-apps and
+  audience-bound push notifications, the @pplethai/components design system,
+  and managed Cloudflare Workers + D1 + R2 hosting via the pple CLI. Use this
+  skill whenever a task mentions PPLE, PPLE ID, PPLE Today, mini-app,
+  พรรคประชาชน, People's Party, @pplethai packages, Builder App, party
+  internal tools, or when scaffolding, authenticating, styling, notifying, or
+  deploying any app in the PPLE ecosystem — even if the user doesn't name the
+  platform explicitly.
+---
+
+# Building on the PPLE Platform
+
+The PPLE Platform lets party workforce members (Builders) ship mini-apps
+without holding cloud or GitHub credentials. Every new **Builder App** plugs
+into three pillars on party-managed infrastructure:
+
+1. **PPLE ID** — OIDC single sign-on. End users authenticate in **PPLE Today**;
+   the mini-app receives a bearer token via the mini-app SDK and the Worker
+   validates it against the OIDC `userinfo` endpoint. Builders also use PPLE
+   ID for the Console (browser login) and `pple auth login` (device flow).
+2. **Mini-app integration** — apps run inside PPLE Today's WebView using
+   `@pplethai/pple-today-miniapp-sdk`, and send audience-bound notifications
+   (title/body, optional path-only `linkPath` into this app) through the
+   platform-provisioned notify helper.
+3. **PPLE Design System** — `@pplethai/components`, a shadcn/ui-based React
+   library with party branding. Docs: https://components.pplethai.org/
+
+## Standard tech stack (Builder Apps)
+
+Use this stack for every new Builder App unless the user is working on a
+central-team core service — uniformity is deliberate (ADR-0002):
+
+| Layer        | Choice |
+| ------------ | ------ |
+| Runtime      | One Cloudflare Worker serves `/api/*` and the React SPA |
+| Frontend     | Vite + React 19 + TypeScript + `@pplethai/components` |
+| Backend      | Hono + TypeScript on the Workers runtime |
+| Database     | D1 (SQLite) via bound queries + SQL migrations |
+| Files        | R2 |
+| Validation   | Zod schemas in `shared/` |
+| Auth         | PPLE ID (OIDC `userinfo`); local `DEV_AUTH` bypass only |
+| Notifications| Audience-bound via `src/notify.ts` (`title`/`body`, optional `linkPath`) |
+| Deploy       | `pple deploy` (platform build → tenant Worker); never personal cloud |
+
+**Not the Builder App path** (do not resurrect these for new apps): Express +
+Prisma + PostgreSQL, Docker / Cloud Build / Artifact Registry, or a separate
+Cloudflare Pages project for the SPA. Those belong to older reference apps
+and central-team services, not the Workers golden path.
+
+Source of truth for new apps:
+
+- **`pple-platform/template`** — the golden-path seed `pple init` copies.
+  Prefer this over obsolete examples (`pple-erp`, `mini-app-example`).
+
+## Which reference to read
+
+Read only the file(s) relevant to the task at hand:
+
+| Task | Read |
+| ---- | ---- |
+| Start a new app / local layout & commands | [references/project-scaffold.md](references/project-scaffold.md) |
+| Login, tokens, NOT_IN_APP, DEV_AUTH | [references/pple-id-auth.md](references/pple-id-auth.md) |
+| Mini-app SDK behavior, push notifications | [references/mini-app.md](references/mini-app.md) |
+| UI, styling, components | [references/design-system.md](references/design-system.md) |
+| Create → init → deploy on managed hosting | [references/deployment.md](references/deployment.md) |
+
+## Golden path for a new app
+
+1. **Create the app** in the Console (`console.ppleth.ai`) — one click
+   provisions the slug, Worker, D1, R2, OAuth client, and hosting.
+2. **Sign in on the machine**: `pple auth login` (PPLE ID device flow; no
+   personal cloud credentials — ADR-0005).
+3. **Scaffold locally**: `pple init <slug>` copies the golden-path template
+   and links the folder to the app.
+4. **Build** against the template helpers (`auth`, `db`, `files`, `notify`)
+   and `@pplethai/components` (see the reference files).
+5. **Ship**: `pple deploy` — the platform builds and puts the app live.
+
+## Invariants — things that are true no matter what you build
+
+- **Mini-apps authenticate through PPLE Today, not a plain browser.** In
+  production, a normal browser shows the friendly NOT_IN_APP screen. Local
+  development uses `DEV_AUTH` in `.dev.vars` only — never provisioned in
+  production. (Builders separately hold tokens from Console login and
+  `pple auth login`; that does not change how end users enter a mini-app.)
+- **Never mention git, branches, remotes, GitHub, Cloudflare accounts, or
+  personal deploy credentials** in the happy path. Talk about the app's
+  code and `pple init` / `pple deploy` only.
+- **Notifications are audience-bound** (`title` / `body`, optional
+  `linkPath` into this app only). Never send phone numbers, user ids, or
+  free-form / cross-app destinations; the platform resolves the audience and
+  joins `linkPath` to this app's entry. Wire shape lives in `src/notify.ts`.
+- **Stack is Workers + D1 + R2.** Bind D1 parameters; never concatenate SQL.
+  One Worker, same origin — no CORS between SPA and API.
+- **`DEV_AUTH` must be unset in production.** Its absence is what forces real
+  PPLE ID validation.
+- **Design tokens are CSS variables** from `@pplethai/components/styles.css`.
+  Prefer design-system components over hardcoding brand colors.

package/skills/pple-platform/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "pple-platform",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I created an app called brave-otter in the Console. Help me get it running locally and understand the project layout so I can add features with my AI agent.",
+      "expected_output": "pple auth login → pple init brave-otter; single-package Workers template (src/ Hono Worker, web/ React, shared/ Zod, migrations/ D1); npm install, .dev.vars from example, db:migrate:local, npm run dev; DEV_AUTH local bypass; no Express/Prisma/Pages scaffold",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Add a feature that sends a push notification to our users when a note is saved. Use the PPLE notification service the platform wired up.",
+      "expected_output": "Use src/notify.ts / NotificationSchema with title+body and optional path-only linkPath (self-link into this app); POST to NOTIFY_API_BASE/notifications with NOTIFY_API_KEY; no phone numbers, user ids, free-form cross-app links, or PHONE_NUMBER audience; no legacy /external/notifications/send with raw numbers",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "How do I put my changes live? Set up deployment for this Builder App.",
+      "expected_output": "pple deploy (after pple auth login); managed Workers+D1+R2; no Dockerfile, Cloud Build, Artifact Registry, or separate Cloudflare Pages project; no git/GitHub credential instructions in the happy path",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "The app should work when I open it in Chrome on my laptop. Add a normal browser login with PPLE ID.",
+      "expected_output": "Refuse browser login for the mini-app; show NOT_IN_APP in plain browsers; real tokens via PPLE Today; local DEV_AUTH only for vite dev — do not claim tokens only exist inside PPLE Today as a platform-wide absolute (Console/CLI hold Builder tokens)",
+      "files": []
+    }
+  ]
+}

package/skills/pple-platform/references/deployment.md

@@ -0,0 +1,61 @@
+# Deployment (managed Workers hosting)
+
+Builder Apps run only on party-managed Cloudflare infrastructure
+(ADR-0001, ADR-0002). Builders never hold cloud or GitHub credentials
+(ADR-0005). The happy path uses the Console and the `pple` CLI — not git
+vocabulary, Docker, Cloud Build, or personal Cloudflare/Pages projects.
+
+## Happy path
+
+```bash
+# 1. Create the app in the Console (console.ppleth.ai)
+#    → slug, Worker, D1, R2, OAuth client, hosting — all provisioned
+
+pple auth login              # PPLE ID device flow on this machine
+pple init <slug>             # scaffold template + App Link (.pple/app.json)
+# …edit locally with npm run dev…
+pple deploy -m "short note"  # send changes; platform builds and goes live
+```
+
+What the Builder hears: the app's name and live URL (e.g.
+`https://brave-otter.ppleth.ai`). Not branches, remotes, registries, or
+source-control jargon.
+
+| Command | Meaning for the Builder |
+| ------- | ----------------------- |
+| `pple auth login` | Sign in with PPLE ID |
+| `pple init <slug>` | Set up this app's code on this computer |
+| `pple deploy` | Send changes and put them live |
+| `pple whoami` / `pple auth logout` | Check / forget this machine's sign-in |
+
+## What the platform owns
+
+- **Hosting**: Workers for Platforms dispatch namespace; one tenant Worker per
+  app serving API + static assets; D1 database; R2 bucket.
+- **Identity bindings**: `SSO_BASE_URL`, OAuth client env for the SPA,
+  audience-bound `NOTIFY_API_BASE` / `NOTIFY_API_KEY`.
+- **The app's code**: stored and shipped by the platform. `pple init` /
+  `pple deploy` authenticate under the hood — the Builder never configures
+  a source-control account or pastes a deploy token.
+- **Config / secrets**: set in the Console; applied as Worker bindings on the
+  **next** deploy. Secrets are write-only (set/unset, never read back).
+
+## Local vs production auth
+
+- Local: `DEV_AUTH` in `.dev.vars` (see [pple-id-auth.md](pple-id-auth.md)).
+- Production: `DEV_AUTH` must be absent. The platform never provisions it.
+
+## Archived / do-not-use for Builder Apps
+
+These were the previous golden path. Do not set them up for new Builder Apps:
+
+- Separate **Cloudflare Pages** project for a Vite SPA + Dockerized Express API
+- **Google Cloud Build** / Kaniko / Artifact Registry Docker deploys
+- Asking the Builder to sign into GitHub, create a Cloudflare account, or
+  paste long-lived deploy tokens
+- `api/Dockerfile` + `api/cloudbuild.yaml` monorepo layouts copied from
+  older Express-era apps
+
+If the user is maintaining a central-team service that still uses those
+tools, say so explicitly — that is outside the Builder App path this skill
+steers.

package/skills/pple-platform/references/design-system.md

@@ -0,0 +1,50 @@
+# PPLE Design System (@pplethai/components)
+
+`@pplethai/components` is the party's React component library, built on
+shadcn/ui. Live docs: **https://components.pplethai.org/**
+
+Builder Apps start with the golden-path template (`pple-platform/template`),
+which already imports the library. Prefer editing that wiring over
+reinventing a design-system setup from `pple-erp` or other older apps.
+
+## Consumer setup (already in the template)
+
+```tsx
+// web/main.tsx — design-system CSS first, then local layout
+import "@pplethai/components/styles.css";
+import "./app.css";
+
+import { Button, Card, CardContent, Logo } from "@pplethai/components";
+```
+
+Package entry points:
+
+| Import | Contents |
+| ------ | -------- |
+| `@pplethai/components` | UI primitives, layout, brand (`Logo`, …), `cn()`, toasts |
+| `@pplethai/components/form` | react-hook-form helpers when you need forms |
+| `@pplethai/components/styles.css` | Brand tokens — import once |
+
+Vite note (template already pins this): the package's `"development"` export
+can point at unpublished source. Keep the template's resolve alias that pins
+the bare `@pplethai/components` import to `dist/index.js`.
+
+## Layout conventions in Builder Apps
+
+- Put **page layout** in `web/app.css` (mobile-first, safe-area padding for
+  the WebView). Do not fight the design-system stylesheet with a second
+  full Tailwind stack unless you need it.
+- Compose screens from design-system components (`Card`, `Button`, `Input`,
+  `Textarea`, `Badge`, `Alert`, …) like the demo cards in `web/App.tsx`.
+- **Colors and type** come from CSS variables in `styles.css`
+  (`--primary`, fonts, gradients). Prefer components and those tokens over
+  hardcoded hex brand colors.
+- Typography: headings **Anakotmai**, body **IBM Plex Sans Thai Looped** —
+  both arrive with `styles.css`.
+
+## Filling gaps
+
+When the library lacks a component, generate a local shadcn/ui piece into
+your app and keep tokens aligned — or stick to plain markup + `app.css`.
+Prefer `@pplethai/components` whenever an equivalent exists so apps stay
+visually consistent.

package/skills/pple-platform/references/mini-app.md

@@ -0,0 +1,74 @@
+# Mini-app integration & audience-bound notifications
+
+## Running inside PPLE Today
+
+Builder Apps ship as **mini-apps**: web apps opened in PPLE Today's WebView.
+`@pplethai/pple-today-miniapp-sdk` captures the access token — see
+[pple-id-auth.md](pple-id-auth.md). Facts that shape your design:
+
+- `sdk.init()` must complete before any other SDK call.
+- Outside PPLE Today (plain browser), show NOT_IN_APP — that is expected, not
+  an error. Locally, `DEV_AUTH` covers development.
+- The OAuth client and mini-app URL are provisioned when the app is created in
+  the Console; Builders do not register them manually with the Today team.
+- Design mobile-first; test at ~375 px width.
+
+## Push notifications (audience-bound)
+
+Builder Apps send push notifications through the helper in `src/notify.ts`.
+The privacy model is fixed by the platform:
+
+- Your code sends a `title` and `body`, plus an optional path-only self-link
+  (`linkPath`).
+- **Never** send phone numbers, user ids, or an audience list.
+- The platform resolves recipients as this app's App Users ∩ its current
+  publication-tier audience, and enforces the per-app rate limit.
+- `NOTIFY_API_BASE` and `NOTIFY_API_KEY` are provisioned bindings. The key
+  *is* the address — no app id and no recipients on the wire.
+
+### App-facing shape (`shared/api.ts`)
+
+```ts
+import { NotificationSchema } from "../shared/api";
+// { title: string, body: string, linkPath?: string }
+// linkPath must start with a single `/` (e.g. "/check-in")
+```
+
+Optional `linkPath` is a deep link into **this** app only. The platform joins
+it to the app's known entry and rejects absolute URLs, schemes, `..`, or
+anything that would leave this app. Free-form destinations that could address
+another mini app (e.g. `content.link`) are not available on this route.
+Omit `linkPath` for content-only sends — tapping then opens the notification
+centre, as before.
+
+### Wire shape (`src/notify.ts`)
+
+Keep the platform vocabulary translation in `notify.ts` only:
+
+```ts
+await fetch(`${env.NOTIFY_API_BASE}/notifications`, {
+  method: "POST",
+  headers: {
+    authorization: `Bearer ${env.NOTIFY_API_KEY}`,
+    "content-type": "application/json",
+  },
+  body: JSON.stringify({
+    content: { header: input.title, message: input.body },
+    ...(input.linkPath !== undefined ? { linkPath: input.linkPath } : {}),
+  }),
+});
+```
+
+- Missing config → fail loud (`notifications_not_configured` / 503), not silent.
+- HTTP 429 → `rate_limited`.
+- Prefer fire-and-forget from route handlers with error logging — do not fail
+  the user's primary action solely because notify is slow.
+
+### What not to do
+
+Do **not** call the legacy central-team endpoint that accepts a
+`PHONE_NUMBER` audience (`/external/notifications/send` with raw numbers).
+That path is not the Builder App contract. If you see older docs or
+`mini-app-example` code addressing phones, ignore them for new apps.
+Do **not** invent free-form link / absolute URL fields — self-links use
+`linkPath` only.