@warpgogol/forge 0.14.0 → 0.16.0

package/skills/fo/ef-onboard/SKILL.md

@@ -19,7 +19,7 @@ triggers:
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
 
-Guide the operator through creating a new Editframe video project within a Forge-managed workspace. The skill covers prerequisites check, discovery, scaffold, Editframe domain skills installation, domain knowledge reading, and build + preview.
+Guide the operator through creating a new Editframe video project within a Forge-managed workspace. The skill covers prerequisites check, discovery, scaffold, domain knowledge reading, and build + preview.
 
 ## Process
 
@@ -45,46 +45,33 @@ Ask the operator:
    - Website URLs to use as content source — if provided, download and cache all relevant assets locally before building
    - No existing assets — start from scratch
 
-3. **Stack preference**:
-   - Vanilla HTML/CSS/JS (simpler, no build step beyond Vite)
-   - React + TypeScript (component-based, type-safe)
-   - No preference — recommend HTML for single videos, React for templates and editors
-
-4. **Node.js/React libraries**: Ask if the operator has any libraries in mind (e.g. AnimeJS for animations, Tailwind for styling).
+3. **Node.js/React libraries**: Ask if the operator has any libraries in mind (e.g. AnimeJS for animations, Tailwind for styling).
 
 Prioritize getting all answers before starting to build. This minimizes wait time for the operator.
 
 ### 3. Scaffold
 
-Run `forge create --profile editframe-html` to scaffold the project with Forge governance (invariants, AGENTS.md templates, forge skills).
-
-The `editframe-html` profile currently targets HTML compositions only — it does not support a `--template react` flag. If the operator chose React, scaffold with `forge create --profile editframe-html`, then instruct the agent to install `@editframe/react` manually (`pnpm add @editframe/react`) after scaffold.
+Run `forge create --profile editframe` to scaffold the project with Forge governance (invariants, AGENTS.md templates, forge skills). The `editframe` profile scaffolds a React + TypeScript + Vite project with `@editframe/react` pre-configured.
 
 If `forge create` fails (missing profile, network error, permission issue), report the error to the operator and stop. Do not proceed to subsequent steps without a scaffolded project.
 
-### 4. Install Editframe domain skills
-
-Editframe publishes domain skills via `npm create @editframe`. To make them available alongside forge skills:
-
-1. Run `npm create @editframe@latest` in the project directory. This installs Editframe's domain skills to `.agents/skills/editframe-*/`.
-2. Report which skills were installed.
-3. If the command fails (network issues, npm errors, unsupported flags), fall back to referencing the online documentation: direct the agent to read `https://editframe.com/llms.txt` and `https://editframe.com/skills/composition.md` before building. Do not use unverified CLI flags — if `npm create @editframe` prompts interactively, answer the prompts based on the operator's discovery answers from Step 2.
-
-### 5. Read domain knowledge
+### 4. Read domain knowledge
 
-Before building, the agent MUST read the `editframe-composition` skill (either from `.agents/skills/editframe-composition/SKILL.md` if installed, or from `https://editframe.com/skills/composition.md`). This provides domain knowledge about:
+Before building, the agent MUST read the vendored Editframe domain skills. These are bundled with `@warpgogol/forge` and available in `.agents/skills/`:
 
-- Time model (`ef-timegroup`, modes, duration, offset)
-- Media elements (`ef-video`, `ef-audio`, `ef-image`, `ef-text`, `ef-captions`)
-- CSS animations and transitions
-- Rendering pipeline
+- **ef-composition** — time model, media elements, rendering pipeline
+- **ef-dev-server** — Vite plugin setup, local asset serving
+- **ef-editor-gui** — editor toolkit for visual composition editing
+- **ef-webhooks** — webhook notifications for render completion
+- **ef-brand-video-generator** — brand video generation templates
+- **ef-motion-design** — motion design patterns, transitions, kinetic typography
 
-The agent should also read `editframe-dev-server` if the project uses the dev server.
+The agent should also read **ef-composition-review** and **ef-render-verify** for quality assurance workflows.
 
-### 6. Build and preview
+### 5. Build and preview
 
-1. Build the initial composition based on the operator's answers from Step 2. Use the discovery answers (project type, assets, stack preference, libraries) to determine composition structure, asset placement, and optional dependencies.
-2. Run `forge dev` to start the preview server (delegates to `editframe preview` per the `editframe-html` profile's `devServer.command`).
+1. Build the initial composition based on the operator's answers from Step 2. Use the discovery answers (project type, assets, libraries) to determine composition structure, asset placement, and optional dependencies.
+2. Run `forge dev` to start the preview server (delegates to `editframe preview` per the `editframe` profile's `devServer.command`).
 3. Report the localhost URL to the operator.
-4. Run `forge doctor` to check all profile invariants on the initial composition. For the `editframe-html` profile, this covers VIDEO-01 through VIDEO-09.
+4. Run `forge doctor` to check all profile invariants on the initial composition. For the `editframe` profile, this covers VIDEO-01 through VIDEO-09.
 5. Report any invariant violations and suggest fixes.

package/skills/fo/ef-render-verify/SKILL.md

@@ -18,7 +18,7 @@ A read-only verification of an Editframe render pipeline. The skill runs validat
 
 ## Scope
 
-This skill verifies render output for `.html` composition files using the `editframe-html` stack profile. It uses `forge validate`, `forge build`, and `forge determinism check` — all profile-driven commands.
+This skill verifies render output for `.tsx` composition files using the `editframe` stack profile. It uses `forge validate`, `forge build`, and `forge determinism check` — all profile-driven commands.
 
 ## Process
 
@@ -40,7 +40,7 @@ Check the render output:
 
 - Verify the output MP4 file exists at the expected path (`dist/{composition}.mp4`).
 - Check that the file size is non-zero.
-- Check that the duration matches the root `ef-timegroup`'s `duration` attribute (if ffprobe or equivalent is available).
+- Check that the duration matches the root `Timegroup`'s `duration` prop (if ffprobe or equivalent is available).
 
 ### 5. Report
 

package/skills/fo/ef-webhooks/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: ef-webhooks
+description: "Configure Editframe webhooks for render completion and file processing notifications. Use when the operator asks to set up webhooks for Editframe events."
+invocation: user
+category: fo
+concerns: read-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "set up editframe webhooks"
+  - "render completion notification"
+  - "file processing webhook"
+  - "webhook signature verification"
+source: https://editframe.com/skills/webhooks.md
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+# Webhooks
+
+Use webhooks to receive real-time HTTP POST notifications when a render completes or a file finishes processing. Use them instead of polling `getRenderProgress`/`getFileProcessingProgress`.
+
+No SDK function registers a webhook. Configure one on an API key, through the dashboard (Settings → API Keys, or `editframe.com/resource/api_keys`). Set a **Webhook URL** (must use HTTPS). Select which **Webhook Events** (topics) to receive. When you create or update the key, the dashboard generates a **Webhook Secret**, used to sign deliveries. Copy this secret and store it alongside the API key.
+
+## Handling a webhook
+
+```typescript
+import express from "express";
+import crypto from "node:crypto";
+
+const app = express();
+
+app.post("/webhooks/editframe", express.raw({ type: "*/*" }), (req, res) => {
+  const signature = req.headers["x-webhook-signature"] as string;
+  const rawBody = req.body as Buffer;
+
+  const expected = crypto
+    .createHmac("sha256", process.env.EDITFRAME_WEBHOOK_SECRET!)
+    .update(rawBody)
+    .digest("hex");
+
+  if (!crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"))) {
+    return res.status(401).send("Invalid signature");
+  }
+
+  res.status(200).send("OK");
+  const payload = JSON.parse(rawBody.toString("utf-8"));
+  processWebhookEvent(payload).catch(console.error);
+});
+```
+
+Every request carries an `X-Webhook-Signature` header: `HMAC-SHA256(webhook_secret, raw_json_body)`, hex-encoded. Verify with `crypto.timingSafeEqual`, not `===`.
+
+Use `express.raw()`, not `express.json()`. Signature verification needs the exact raw bytes. Re-serializing parsed JSON can reorder keys or change whitespace, which changes the hash and breaks verification.
+
+## Payload
+
+```typescript
+{ topic: string, data: {...} }
+```
+
+### Render topics
+
+`render.created`, `render.pending`, `render.rendering`, `render.completed`, `render.failed`
+
+`data` includes `id`, `status`, `created_at`, `completed_at`, `failed_at`, `width`, `height`, `fps`, `byte_size`, `duration_ms`, `md5`, `metadata`, `expires_at` (`null` = permanent), `download_url` (populated once complete), `error` (populated on failure).
+
+### File topics
+
+`file.created`, `file.uploading`, `file.processing`, `file.ready`, `file.failed`, `file.updated`
+
+`data` includes `id`, `type` (`video`/`image`/`caption`), `status`, `filename`, `byte_size`, `md5`, `mime_type`, `width`, `height`, `expires_at`. Editframe sends `file.updated` for a file status change that doesn't match one of the other file topics.
+
+### Legacy topics
+
+`image_file.created`, `isobmff_file.created`, `isobmff_track.created`, `unprocessed_file.created`. Do not build new integrations against these.
+
+## Delivery
+
+- Each event arrives as one HTTP POST with a JSON body.
+- Editframe retries on a fixed 10-second interval, up to 3 attempts total, with a 30-second timeout per attempt.
+- Editframe may deliver an event more than once. Key side effects off `data.id` to stay idempotent.
+- Always hash the **raw** request body for signature verification.
+
+## Testing
+
+```bash
+npx editframe webhook -t render.completed
+```
+
+This sends a real test event to the URL configured on your API key. There is no `--webhookURL` flag — the target URL always comes from the key's dashboard configuration. The dashboard's API key detail page has an equivalent "Test Webhook" button.
+
+For local development, tunnel your dev server (e.g. `ngrok http 3000`) and point the API key's Webhook URL at the tunnel URL.

package/skills/fo/fo-session-retro/SKILL.md

@@ -9,7 +9,7 @@ languagePolicy: ref(PREFERENCES.md)
 bindings:
   requires: []
   optional: [paths.invariantsFile]
-triggers: ["session retrospective", "capture insights from this session", "triage session discoveries", "Завершаем эту сессию", "Завершаем сессию", "Заканчиваем сессию", "Завершить сессию", "End session", "Wrap up", "Session end", "/session-end"]
+triggers: ["session retrospective", "capture insights from this session", "triage session discoveries", "Завершаем сессию", "/session-end"]
 ---
 
 # Session Retro
@@ -261,7 +261,7 @@ When gathering session insights, not every observation deserves to be saved. App
 
 **Do NOT save** — the observation is:
 
-- A one-off fact with no future impact (e.g. "RFC-0676 was skipped due to a duplicate"). These are historical events, not knowledge. They do not help future agents work better.
+- A one-off fact with no future impact (e.g. "an RFC was skipped due to a duplicate"). These are historical events, not knowledge. They do not help future agents work better.
 - A tool quirk already documented elsewhere (check `AGENTS.md` and existing memories first).
 - A transient state that will be irrelevant by the next session (e.g. "file X was dirty at session end").
 - A bug that was found and fixed in the same session with no broader lesson.

package/profiles/editframe-html-templates/composition.html

@@ -1,32 +0,0 @@
-<!--
-  Editframe HTML composition template
-  Copy this file to start a new composition. Editframe custom elements:
-  - ef-timegroup: groups elements into a timed sequence
-  - ef-video: video source with fit mode (contain, cover, fill)
-  - ef-audio: audio source
-  - ef-text: text overlay with positioning
-  - ef-captions: accessibility captions for speech audio
-  Run `editframe preview` to preview, `editframe render` to produce output.
--->
-<ef-timegroup duration="10s">
-  <ef-video
-    src="assets/background.mp4"
-    fit="contain"
-    duration="10s"
-  ></ef-video>
-  <ef-text
-    text="Your text here"
-    x="50%"
-    y="50%"
-    font-size="48px"
-    color="white"
-    text-align="center"
-    duration="5s"
-  ></ef-text>
-  <ef-audio
-    src="assets/narration.mp3"
-  ></ef-audio>
-  <ef-captions
-    src="assets/captions.vtt"
-  ></ef-captions>
-</ef-timegroup>