@t3lnet/sceneforge 1.0.11 → 1.0.13

package/context/context-builder.ts

@@ -27,6 +27,10 @@ import {
 
 export type Stage = "actions" | "scripts" | "balance" | "rebalance" | "all";
 
+// Markers for identifying SceneForge content in existing files
+const SCENEFORGE_START_MARKER = "<!-- SCENEFORGE_CONTEXT_START -->";
+const SCENEFORGE_END_MARKER = "<!-- SCENEFORGE_CONTEXT_END -->";
+
 export interface ContextBuilderOptions {
   target: TargetTool | "all";
   stage: Stage;
@@ -50,6 +54,59 @@ export interface PreviewResult {
   content: string;
 }
 
+/**
+ * Wrap content with SceneForge markers for identification.
+ */
+function wrapWithMarkers(content: string): string {
+  return `${SCENEFORGE_START_MARKER}\n${content}\n${SCENEFORGE_END_MARKER}`;
+}
+
+/**
+ * Merge SceneForge content into an existing file.
+ * - If file doesn't exist, returns wrapped content
+ * - If file exists without markers, appends wrapped content
+ * - If file exists with markers, replaces the marked section
+ */
+async function mergeWithExisting(
+  filePath: string,
+  newContent: string
+): Promise<{ content: string; merged: boolean }> {
+  const wrappedContent = wrapWithMarkers(newContent);
+
+  try {
+    const existingContent = await fs.readFile(filePath, "utf-8");
+
+    // Check if file already has SceneForge markers
+    const startIndex = existingContent.indexOf(SCENEFORGE_START_MARKER);
+    const endIndex = existingContent.indexOf(SCENEFORGE_END_MARKER);
+
+    if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+      // Replace existing SceneForge section
+      const beforeSection = existingContent.slice(0, startIndex);
+      const afterSection = existingContent.slice(
+        endIndex + SCENEFORGE_END_MARKER.length
+      );
+      return {
+        content: beforeSection + wrappedContent + afterSection,
+        merged: true,
+      };
+    } else {
+      // Append SceneForge section to existing content
+      const separator = existingContent.trim().endsWith("-->") ? "\n\n" : "\n\n---\n\n";
+      return {
+        content: existingContent.trimEnd() + separator + wrappedContent + "\n",
+        merged: true,
+      };
+    }
+  } catch (error) {
+    // File doesn't exist, return wrapped content for new file
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { content: wrappedContent, merged: false };
+    }
+    throw error;
+  }
+}
+
 /**
  * Build context content for a specific tool and stage.
  */
@@ -124,14 +181,25 @@ export async function deployContext(
         // Ensure directory exists
         await fs.mkdir(path.dirname(absolutePath), { recursive: true });
 
+        // Merge with existing content or create new
+        const { content: finalContent, merged } = await mergeWithExisting(
+          absolutePath,
+          content
+        );
+
         // Write file
-        await fs.writeFile(absolutePath, content, "utf-8");
+        await fs.writeFile(absolutePath, finalContent, "utf-8");
 
         results.push({
           tool,
           filePath: absolutePath,
           created: true,
+          skipped: false,
         });
+
+        if (merged) {
+          console.log(`  [merged] ${path.relative(outputDir, absolutePath)}`);
+        }
       } catch (error) {
         results.push({
           tool,
@@ -152,15 +220,26 @@ export async function deployContext(
           // Ensure directory exists
           await fs.mkdir(path.dirname(absolutePath), { recursive: true });
 
+          // Merge with existing content or create new
+          const { content: finalContent, merged } = await mergeWithExisting(
+            absolutePath,
+            content
+          );
+
           // Write file
-          await fs.writeFile(absolutePath, content, "utf-8");
+          await fs.writeFile(absolutePath, finalContent, "utf-8");
 
           results.push({
             tool,
             filePath: absolutePath,
             stage: stg,
             created: true,
+            skipped: false,
           });
+
+          if (merged) {
+            console.log(`  [merged] ${path.relative(outputDir, absolutePath)}`);
+          }
         } catch (error) {
           results.push({
             tool,

package/context/templates/base/cli-reference.md

@@ -104,6 +104,8 @@ sceneforge split --demo <name> [options]
 | `--demo` | Demo name (folder in output) |
 | `--output`, `-o` | Output directory |
 
+**Video Quality:** Encodes with H.264 (libx264), CRF 18, medium preset for high-quality output.
+
 ### voiceover
 Generate voiceover audio from scripts.
 
@@ -136,6 +138,8 @@ sceneforge add-audio --demo <name> [options]
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
 
+**Video Quality:** Re-encodes with H.264 (libx264), CRF 18, medium preset. Audio encoded as AAC at 192kbps.
+
 ### concat
 Concatenate step clips into final video.
 
@@ -149,6 +153,8 @@ sceneforge concat --demo <name> [options]
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
 
+**Video Quality:** Final encode with H.264 (libx264), CRF 18, medium preset. Includes `+faststart` for web streaming optimization. Audio encoded as AAC at 192kbps.
+
 ### doctor
 Run environment diagnostics.
 
@@ -176,12 +182,18 @@ sceneforge context <subcommand> [options]
 ```
 
 **Subcommands:**
-- `deploy` - Deploy context files
+- `deploy` - Deploy context files (additive - preserves existing content)
 - `list` - List deployed context
 - `remove` - Remove context files
 - `preview` - Preview context content
 - `skill` - Manage skills
 
+**Additive Deployment:**
+SceneForge uses markers to identify its content in instruction files:
+- `<!-- SCENEFORGE_CONTEXT_START -->` and `<!-- SCENEFORGE_CONTEXT_END -->`
+- Existing content outside these markers is preserved
+- Re-running deploy updates only the SceneForge section
+
 See dedicated context documentation for details.
 
 ## Output Structure
@@ -234,3 +246,27 @@ sceneforge doctor
 # Record in headed mode with slow motion
 sceneforge record -d demo.yaml -b http://localhost:3000 --headed --slowmo 500
 ```
+
+## Video Quality
+
+SceneForge uses high-quality FFmpeg encoding settings optimized for multi-pass video processing:
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| Codec | `libx264` | H.264 for broad compatibility |
+| Preset | `medium` | Balanced quality/speed tradeoff |
+| CRF | `18` | High quality (visually lossless) |
+| Audio | `aac @ 192k` | High-quality audio |
+| Flags | `+faststart` | Web streaming optimization |
+
+**Why these settings:**
+- Videos go through multiple processing stages (split → add-audio → concat)
+- Each re-encoding can degrade quality (generation loss)
+- CRF 18 preserves quality across all stages
+- Medium preset provides good compression without sacrificing quality
+
+**CRF Reference:**
+- 0 = Lossless (huge files)
+- 18 = Visually lossless (SceneForge default)
+- 23 = FFmpeg default
+- 28+ = Lower quality, smaller files

package/context/templates/stages/stage4-rebalancing.md

@@ -217,6 +217,26 @@ Aim for variance within ±500ms per step:
 - [ ] Volume consistent across steps
 - [ ] No unexpected pauses
 
+### Video Quality Check
+SceneForge uses high-quality encoding settings to preserve video fidelity:
+- [ ] Video appears sharp (no compression artifacts)
+- [ ] Colors are accurate (no banding)
+- [ ] Text is readable (no blur from compression)
+- [ ] No visible quality degradation between steps
+
+**Encoding Settings Used:**
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| Codec | `libx264` | H.264 for compatibility |
+| CRF | `18` | High quality (visually lossless) |
+| Preset | `medium` | Balanced quality/speed |
+| Audio | `aac @ 192k` | High-quality audio |
+
+**If you notice quality issues:**
+1. Ensure source recording is high quality (check `output/videos/<demo>.webm`)
+2. Re-run the pipeline to regenerate all clips
+3. Check available disk space (low space can affect encoding)
+
 ## Final Checklist
 
 - [ ] All steps have acceptable timing variance
@@ -225,4 +245,6 @@ Aim for variance within ±500ms per step:
 - [ ] No dead air or overlap issues
 - [ ] Intro provides adequate context
 - [ ] Outro concludes naturally
+- [ ] Video quality is sharp and clear
+- [ ] Audio is clear with consistent volume
 - [ ] Overall demo flows professionally

package/dist/index.cjs

@@ -2671,6 +2671,42 @@ function isValidFormat(format) {
 // context/context-builder.ts
 var fs6 = __toESM(require("fs/promises"), 1);
 var path6 = __toESM(require("path"), 1);
+var SCENEFORGE_START_MARKER = "<!-- SCENEFORGE_CONTEXT_START -->";
+var SCENEFORGE_END_MARKER = "<!-- SCENEFORGE_CONTEXT_END -->";
+function wrapWithMarkers(content) {
+  return `${SCENEFORGE_START_MARKER}
+${content}
+${SCENEFORGE_END_MARKER}`;
+}
+async function mergeWithExisting(filePath, newContent) {
+  const wrappedContent = wrapWithMarkers(newContent);
+  try {
+    const existingContent = await fs6.readFile(filePath, "utf-8");
+    const startIndex = existingContent.indexOf(SCENEFORGE_START_MARKER);
+    const endIndex = existingContent.indexOf(SCENEFORGE_END_MARKER);
+    if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+      const beforeSection = existingContent.slice(0, startIndex);
+      const afterSection = existingContent.slice(
+        endIndex + SCENEFORGE_END_MARKER.length
+      );
+      return {
+        content: beforeSection + wrappedContent + afterSection,
+        merged: true
+      };
+    } else {
+      const separator = existingContent.trim().endsWith("-->") ? "\n\n" : "\n\n---\n\n";
+      return {
+        content: existingContent.trimEnd() + separator + wrappedContent + "\n",
+        merged: true
+      };
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { content: wrappedContent, merged: false };
+    }
+    throw error;
+  }
+}
 async function buildContext(tool, stage, variables) {
   const templates = [];
   const baseTemplates = await loadTemplatesByCategory("base");
@@ -2708,12 +2744,20 @@ async function deployContext(options) {
         const filePath = getOutputPath(tool, format, outputDir);
         const absolutePath = path6.resolve(filePath);
         await fs6.mkdir(path6.dirname(absolutePath), { recursive: true });
-        await fs6.writeFile(absolutePath, content, "utf-8");
+        const { content: finalContent, merged } = await mergeWithExisting(
+          absolutePath,
+          content
+        );
+        await fs6.writeFile(absolutePath, finalContent, "utf-8");
         results.push({
           tool,
           filePath: absolutePath,
-          created: true
+          created: true,
+          skipped: false
         });
+        if (merged) {
+          console.log(`  [merged] ${path6.relative(outputDir, absolutePath)}`);
+        }
       } catch (error) {
         results.push({
           tool,
@@ -2730,13 +2774,21 @@ async function deployContext(options) {
           const filePath = getOutputPath(tool, format, outputDir, stageName);
           const absolutePath = path6.resolve(filePath);
           await fs6.mkdir(path6.dirname(absolutePath), { recursive: true });
-          await fs6.writeFile(absolutePath, content, "utf-8");
+          const { content: finalContent, merged } = await mergeWithExisting(
+            absolutePath,
+            content
+          );
+          await fs6.writeFile(absolutePath, finalContent, "utf-8");
           results.push({
             tool,
             filePath: absolutePath,
             stage: stg,
-            created: true
+            created: true,
+            skipped: false
           });
+          if (merged) {
+            console.log(`  [merged] ${path6.relative(outputDir, absolutePath)}`);
+          }
         } catch (error) {
           results.push({
             tool,