@t3lnet/sceneforge 1.0.14 → 1.0.16

package/context/context-builder.ts

@@ -107,6 +107,42 @@ async function mergeWithExisting(
   }
 }
 
+async function writeSplitPointer(
+  tool: TargetTool,
+  stageNames: Stage[],
+  outputDir: string
+): Promise<{ filePath: string; merged: boolean }> {
+  const config = getToolConfig(tool);
+  const stageLines = stageNames.map((stage) => {
+    const friendly = formatStageName(stage);
+    const stageFile = `${config.splitFilePrefix}${getStageFileName(stage)}${config.fileExtension}`;
+    const relativePath = path.posix.join(config.splitDir, stageFile);
+    return `- ${friendly}: ${relativePath}`;
+  });
+
+  const pointerBody = [
+    "SceneForge context for this tool is split across the following stage files:",
+    "",
+    ...stageLines,
+    "",
+    `Open the stage file that matches the work you're doing, or run "npx sceneforge context preview --target ${tool} --stage <stage>" to inspect a specific stage.`,
+  ].join("\n");
+
+  const formattedPointer = formatForTool(tool, pointerBody, {
+    includeToolHeader: true,
+  });
+
+  const combinedPath = path.join(outputDir, config.combinedFile);
+  await fs.mkdir(path.dirname(combinedPath), { recursive: true });
+  const { content: finalContent, merged } = await mergeWithExisting(
+    combinedPath,
+    formattedPointer
+  );
+  await fs.writeFile(combinedPath, finalContent, "utf-8");
+
+  return { filePath: combinedPath, merged };
+}
+
 /**
  * Build context content for a specific tool and stage.
  */
@@ -210,6 +246,7 @@ export async function deployContext(
       }
     } else {
       // Generate split files for each stage
+      const deployedStages: Stage[] = [];
       for (const stg of stages) {
         try {
           const content = await buildContext(tool, stg, variables);
@@ -240,6 +277,7 @@ export async function deployContext(
           if (merged) {
             console.log(`  [merged] ${path.relative(outputDir, absolutePath)}`);
           }
+          deployedStages.push(stg);
         } catch (error) {
           results.push({
             tool,
@@ -250,6 +288,24 @@ export async function deployContext(
           });
         }
       }
+      if (deployedStages.length > 0) {
+        const pointerResult = await writeSplitPointer(
+          tool,
+          deployedStages,
+          outputDir
+        );
+        results.push({
+          tool,
+          filePath: pointerResult.filePath,
+          created: true,
+          skipped: false,
+        });
+        if (pointerResult.merged) {
+          console.log(
+            `  [merged] ${path.relative(outputDir, pointerResult.filePath)}`
+          );
+        }
+      }
     }
   }
 

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

@@ -103,8 +103,11 @@ sceneforge split --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name (folder in output) |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
 
-**Video Quality:** Encodes with H.264 (libx264), CRF 18, medium preset for high-quality output.
+**Video Quality:** Configurable via `--quality` preset or `--crf`/`--codec` flags. Default: medium preset (CRF 18, libx264).
 
 ### voiceover
 Generate voiceover audio from scripts.
@@ -137,8 +140,11 @@ sceneforge add-audio --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
 
-**Video Quality:** Re-encodes with H.264 (libx264), CRF 18, medium preset. Audio encoded as AAC at 192kbps.
+**Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Audio: AAC 192kbps.
 
 ### concat
 Concatenate step clips into final video.
@@ -152,8 +158,15 @@ sceneforge concat --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
+| `--intro` | Intro video to prepend |
+| `--outro` | Outro video to append |
+| `--music` | Background music file |
+| `--music-volume` | Music volume 0-1 (default: 0.15) |
 
-**Video Quality:** Final encode with H.264 (libx264), CRF 18, medium preset. Includes `+faststart` for web streaming optimization. Audio encoded as AAC at 192kbps.
+**Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Includes `+faststart` for web streaming. Audio: AAC 192kbps.
 
 ### doctor
 Run environment diagnostics.
@@ -249,24 +262,55 @@ 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:
+SceneForge provides configurable video quality settings via CLI flags on `split`, `add-audio`, and `concat` commands.
 
-| 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 |
+### Quality Presets
+
+| Preset | CRF | Encoding | Use Case |
+|--------|-----|----------|----------|
+| `low` | 28 | fast | Quick drafts, smaller files |
+| `medium` | 18 | medium | Default - balanced quality and size |
+| `high` | 10 | slow | Final delivery, best quality |
+
+### Supported Codecs
+
+| Codec | Name | Description |
+|-------|------|-------------|
+| `libx264` | H.264 | Excellent compatibility (default) |
+| `libx265` | H.265/HEVC | ~50% smaller files, slower encoding |
+
+### CLI Flags
+
+```bash
+--quality <preset>    # low, medium, high (default: medium)
+--crf <value>         # Override CRF (0-51, lower = better)
+--codec <codec>       # libx264 or libx265 (default: libx264)
+```
+
+### Examples
+
+```bash
+# High quality for final output
+sceneforge concat --demo my-demo --quality high
+
+# Smaller files with H.265 codec
+sceneforge concat --demo my-demo --codec libx265
+
+# Custom CRF for fine control
+sceneforge split --demo my-demo --crf 15
+```
+
+### Why Quality Matters
 
-**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
+- Higher quality settings (lower CRF) preserve fidelity across stages
+- The `high` preset (CRF 10) produces near-lossless quality
+
+### CRF Reference
 
-**CRF Reference:**
 - 0 = Lossless (huge files)
-- 18 = Visually lossless (SceneForge default)
+- 10 = Near-lossless (high preset)
+- 18 = Visually lossless (medium preset, default)
 - 23 = FFmpeg default
-- 28+ = Lower quality, smaller files
+- 28 = Lower quality (low preset)

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

@@ -218,24 +218,26 @@ Aim for variance within ±500ms per step:
 - [ ] No unexpected pauses
 
 ### Video Quality Check
-SceneForge uses high-quality encoding settings to preserve video fidelity:
+SceneForge provides configurable quality 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 |
+**Quality Presets:**
+| Preset | CRF | Encoding | Use Case |
+|--------|-----|----------|----------|
+| `low` | 28 | fast | Quick drafts |
+| `medium` | 18 | medium | Default - balanced |
+| `high` | 10 | slow | Final delivery |
+
+**CLI Flags:** `--quality`, `--crf`, `--codec` (available on split, add-audio, concat)
 
 **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)
+1. Re-run with `--quality high` for better fidelity
+2. Ensure source recording is high quality (check `output/videos/<demo>.webm`)
+3. Try `--codec libx265` for better compression at same quality
+4. Check available disk space (low space can affect encoding)
 
 ## Final Checklist
 

package/context/tests/context-builder.test.ts

@@ -118,7 +118,7 @@ describe("context-builder", () => {
         outputDir: tempDir,
       });
 
-      expect(results.length).toBe(1);
+      expect(results.length).toBe(2);
       expect(results[0].created).toBe(true);
 
       const splitDir = path.join(tempDir, ".claude/rules");
@@ -134,9 +134,22 @@ describe("context-builder", () => {
         outputDir: tempDir,
       });
 
-      expect(results.length).toBe(4);
+      expect(results.length).toBe(5);
       expect(results.every((r) => r.created)).toBe(true);
     });
+
+    it("updates combined file when split files are deployed", async () => {
+      await deployContext({
+        target: "claude",
+        stage: "actions",
+        format: "split",
+        outputDir: tempDir,
+      });
+
+      const claudeFile = await fs.readFile(path.join(tempDir, "CLAUDE.md"), "utf-8");
+      expect(claudeFile).toContain("split across the following stage files");
+      expect(claudeFile).toContain(".claude/rules/stage1-actions.md");
+    });
   });
 
   describe("listDeployedContext", () => {

package/dist/index.cjs

@@ -2723,6 +2723,33 @@ async function mergeWithExisting(filePath, newContent) {
     throw error;
   }
 }
+async function writeSplitPointer(tool, stageNames, outputDir) {
+  const config = getToolConfig(tool);
+  const stageLines = stageNames.map((stage) => {
+    const friendly = formatStageName(stage);
+    const stageFile = `${config.splitFilePrefix}${getStageFileName(stage)}${config.fileExtension}`;
+    const relativePath = path6.posix.join(config.splitDir, stageFile);
+    return `- ${friendly}: ${relativePath}`;
+  });
+  const pointerBody = [
+    "SceneForge context for this tool is split across the following stage files:",
+    "",
+    ...stageLines,
+    "",
+    `Open the stage file that matches the work you're doing, or run "npx sceneforge context preview --target ${tool} --stage <stage>" to inspect a specific stage.`
+  ].join("\n");
+  const formattedPointer = formatForTool(tool, pointerBody, {
+    includeToolHeader: true
+  });
+  const combinedPath = path6.join(outputDir, config.combinedFile);
+  await fs6.mkdir(path6.dirname(combinedPath), { recursive: true });
+  const { content: finalContent, merged } = await mergeWithExisting(
+    combinedPath,
+    formattedPointer
+  );
+  await fs6.writeFile(combinedPath, finalContent, "utf-8");
+  return { filePath: combinedPath, merged };
+}
 async function buildContext(tool, stage, variables) {
   const templates = [];
   const baseTemplates = await loadTemplatesByCategory("base");
@@ -2783,6 +2810,7 @@ async function deployContext(options) {
         });
       }
     } else {
+      const deployedStages = [];
       for (const stg of stages) {
         try {
           const content = await buildContext(tool, stg, variables);
@@ -2805,6 +2833,7 @@ async function deployContext(options) {
           if (merged) {
             console.log(`  [merged] ${path6.relative(outputDir, absolutePath)}`);
           }
+          deployedStages.push(stg);
         } catch (error) {
           results.push({
             tool,
@@ -2815,6 +2844,24 @@ async function deployContext(options) {
           });
         }
       }
+      if (deployedStages.length > 0) {
+        const pointerResult = await writeSplitPointer(
+          tool,
+          deployedStages,
+          outputDir
+        );
+        results.push({
+          tool,
+          filePath: pointerResult.filePath,
+          created: true,
+          skipped: false
+        });
+        if (pointerResult.merged) {
+          console.log(
+            `  [merged] ${path6.relative(outputDir, pointerResult.filePath)}`
+          );
+        }
+      }
     }
   }
   return results;