takomi 2.1.32 → 2.1.34

package/.pi/extensions/takomi-runtime/ui.ts

@@ -27,6 +27,8 @@ export type RuntimeHudState = {
   activeSessionId?: string;
   launchMode?: string;
   subagentsEnabled?: boolean;
+  modeSource?: "idle" | "manual" | "model" | "board";
+  modeReason?: string;
 };
 
 type Tone = "accent" | "warning" | "success" | "error" | "muted" | "dim" | "thinkingMinimal";
@@ -70,24 +72,30 @@ function badge(theme: Theme, label: string, tone: Tone): string {
 }
 
 export function renderRuntimeStatus(theme: Theme, state: RuntimeHudState): string {
+  const source = state.modeSource ?? "idle";
+  if (!state.enabled) return [theme.fg("accent", "Takomi"), theme.fg("dim", "off")].join(" ");
+  if (source === "idle") return [theme.fg("accent", "Takomi"), theme.fg("dim", "idle")].join(" ");
+
   const primary = state.stage ?? state.role;
   const stageBadge = badge(theme, primary, stageTone(state.stage));
-  const auto = state.autoOrch ? theme.fg("accent", "auto") : theme.fg("dim", "manual");
-  const gate = state.launchMode === "manual" ? theme.fg("warning", "review-gate") : theme.fg("accent", "auto-gate");
+  const sourceLabel = source === "manual" ? theme.fg("warning", "manual") : theme.fg("success", source);
+  const role = state.stage && state.role !== state.stage ? theme.fg("dim", state.role) : "";
   const plan = state.planMode ? theme.fg("warning", "plan") : theme.fg("dim", "direct");
-  const subagents = state.subagentsEnabled === false ? theme.fg("error", "subagents:off") : theme.fg("dim", "subagents:on");
-  return [theme.fg("accent", "Takomi"), stageBadge, theme.fg("dim", `role:${state.role}`), auto, gate, plan, subagents].join(" ");
+  const gate = state.launchMode === "manual" ? theme.fg("warning", "review-gate") : "";
+  const subagents = state.subagentsEnabled === false ? theme.fg("error", "subagents:off") : "";
+  return [theme.fg("accent", "Takomi"), sourceLabel, stageBadge, role, gate || plan, subagents].filter(Boolean).join(" ");
 }
 
 export function renderRuntimeWidget(theme: Theme, state: RuntimeHudState): string[] {
-  if (!state.enabled) return [];
+  if (!state.enabled || (state.modeSource ?? "idle") === "idle") return [];
   const primary = state.stage ?? state.role;
+  const sourceLabel = state.modeSource === "manual" ? theme.fg("warning", "manual") : theme.fg("success", state.modeSource ?? "model");
   const parts = [
     theme.fg("accent", "Takomi"),
+    sourceLabel,
     badge(theme, primary, stageTone(state.stage)),
-    theme.fg("dim", `role:${state.role}`),
-    state.autoOrch ? theme.fg("accent", "auto") : theme.fg("dim", "manual"),
-    state.launchMode === "manual" ? theme.fg("warning", "review-gate") : theme.fg("accent", "auto-gate"),
+    state.stage && state.role !== state.stage ? theme.fg("dim", `role:${state.role}`) : "",
+    state.launchMode === "manual" ? theme.fg("warning", "review-gate") : "",
     state.planMode ? theme.fg("warning", "plan") : theme.fg("dim", "direct"),
     state.subagentsEnabled === false ? theme.fg("error", "subagents:off") : theme.fg("dim", "subagents:on"),
     state.workflow ? theme.fg("dim", `wf:${state.workflow}`) : "",
@@ -115,7 +123,7 @@ export class TakomiFooterComponent implements Component {
     this.unsubscribeBranchChange();
   }
 
-  invalidate(): void {}
+  invalidate(): void { }
 
   render(width: number): string[] {
     const state = this.getState();
@@ -141,8 +149,7 @@ export class TakomiFooterComponent implements Component {
       .filter(([key]) => key !== "takomi-runtime")
       .map(([, value]) => value)
       .filter(Boolean);
-    const runtimeStatus = renderRuntimeStatus(this.theme, state);
-    const left = [runtimeStatus, ...extensionStatuses].join(this.theme.fg("dim", "  |  "));
+    const left = extensionStatuses.join(this.theme.fg("dim", "  |  "));
     const branch = this.footerData.getGitBranch();
     const rightText = [this.ctx.model?.id || "no-model", branch ? `git:${branch}` : ""].filter(Boolean).join(" | ");
     const right = this.theme.fg("dim", rightText);

package/.pi/extensions/takomi-subagents/index.ts

@@ -44,6 +44,7 @@ const SubagentParameters = Type.Object({
   tasks: Type.Optional(Type.Array(TaskSchema, { description: "Parallel subagent tasks" })),
   confirmLaunch: Type.Optional(Type.Boolean({ description: "Required to launch immediately in manual Takomi launch mode" })),
   previewOnly: Type.Optional(Type.Boolean({ description: "Return the delegation plan without launching" })),
+  clarify: Type.Optional(Type.Boolean({ description: "Show the native pi-subagents TUI to preview/edit before execution. Especially useful for chains; requires an interactive Pi TUI." })),
   chain: Type.Optional(Type.Array(TaskSchema, { description: "Sequential chain of subagent tasks" })),
   agentScope: Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("project"), Type.Literal("both")])),
   confirmProjectAgents: Type.Optional(Type.Boolean({ description: "Prompt before running project-local agents. Default: true." })),
@@ -59,6 +60,7 @@ function registerSubagentTool(pi: ExtensionAPI): void {
     promptGuidelines: [
       "Use this tool during orchestration when a specialist should handle a task.",
       "Use tasks for independent parallel work and chain for dependent handoffs with {previous}.",
+      "Set clarify=true when the user asks to preview/edit a subagent run in the native Pi TUI before launch.",
       "Use model, fallbackModels, and thinking only when deliberate; otherwise let the agent/profile defaults apply.",
       "If review sends work back to the same agent, reuse the same conversationId for continuity.",
       "If a launch is blocked, cancelled, paused, or review-gated, do not retry automatically; wait for the user's next prompt. Use overrideUserBlock only after explicit user approval.",

package/.pi/extensions/takomi-subagents/native-render.ts

@@ -30,15 +30,37 @@ export function renderTakomiSubagentCall(params: TakomiSubagentToolParams, theme
   );
 }
 
+function resultText(result: ToolResult): string {
+  return typeof (result as any)?.content === "string"
+    ? (result as any).content
+    : Array.isArray((result as any)?.content)
+      ? (result as any).content.map((part: any) => part?.text ?? "").filter(Boolean).join("\n")
+      : JSON.stringify((result as any)?.details ?? {}, null, 2);
+}
+
+function summarizeCollapsedResult(text: string, status: string, theme: Theme): string {
+  const policyMatch = text.match(/Required policies:\n((?:- .+\n?)+)/);
+  const policies = policyMatch?.[1]
+    ?.split("\n")
+    .map((line) => line.replace(/^[-\s]+/, "").trim())
+    .filter(Boolean) ?? [];
+  const lineCount = text ? text.split(/\r?\n/).length : 0;
+  const label = policies.length > 0
+    ? `policy context loaded: ${policies.join(", ")}`
+    : `${lineCount} result line${lineCount === 1 ? "" : "s"} hidden`;
+  const icon = status === "failed" ? "⚠" : "✓";
+  const color = status === "failed" ? "warning" : "success";
+  return `${theme.fg(color, `${icon} takomi_subagent ${status}`)}${theme.fg("dim", ` · ${label} (ctrl+o to expand)`)}`;
+}
+
 export function renderTakomiSubagentResult(result: ToolResult, options: { expanded?: boolean; isPartial?: boolean }, theme: Theme, context: any): any {
   const native = renderNativeSubagentResult(result, options, theme, context);
   if (native) return native;
 
   const status = (result as any)?.isError ? "failed" : "completed";
-  const text = typeof (result as any)?.content === "string"
-    ? (result as any).content
-    : Array.isArray((result as any)?.content)
-      ? (result as any).content.map((part: any) => part?.text ?? "").filter(Boolean).join("\n")
-      : JSON.stringify((result as any)?.details ?? {}, null, 2);
+  const text = resultText(result);
+  if (!options.expanded && !options.isPartial) {
+    return new Text(summarizeCollapsedResult(text, status, theme), 0, 0);
+  }
   return new Text(`${theme.fg("toolTitle", theme.bold(`takomi_subagent ${status}`))}\n${text || "No result content."}`, 0, 0);
 }

package/.pi/extensions/takomi-subagents/pi-subagents-engine.ts

@@ -186,7 +186,7 @@ function toSubagentParams(params: TakomiSubagentToolParams, rootCwd: string, dis
     cwd: rootCwd,
     context: "fresh" as const,
     async: false,
-    clarify: false,
+    clarify: params.clarify === true,
     includeProgress: true,
     sessionDir: stableConversationSessionDir(rootCwd, tasks),
   };

package/.pi/extensions/takomi-subagents/tool-runner.ts

@@ -28,6 +28,7 @@ export type TakomiSubagentToolParams = Partial<TakomiSubagentToolTask> & {
   chain?: TakomiSubagentToolTask[];
   confirmLaunch?: boolean;
   previewOnly?: boolean;
+  clarify?: boolean;
   agentScope?: TakomiAgentScope;
   confirmProjectAgents?: boolean;
   overrideUserBlock?: boolean;

package/assets/.agent/skills/photo-book-builder/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: photo-book-builder
+description: >
+  Automates high-resolution photo book creation, including chronological sorting, orientation balancing (landscape vs. portrait), print-ready full-bleed masonry layout generation, and cover art upscaling. Use this skill when asked to: (1) Organize a set of photos into chronological pages, (2) Generate 12" x 30" open spreads (9000 x 3600 px at 300 DPI) with exact gutter margins (150 px vertical center gutter) and custom margins, (3) Create or assemble full-bleed masonry grid layouts, (4) Upscale front, back, or briefcase box covers using high-quality LANCZOS interpolation.
+---
+
+# Photo Book Builder
+
+This skill provides a complete system for organizing, structuring, and generating print-ready, high-resolution photo books. It is designed for 12" × 30" open spreads (15" × 12" closed book size) at 300 DPI, enforcing strict gutter margins to prevent content from being lost in the binding.
+
+## Core Capabilities
+
+The photo book builder relies on four main stages:
+
+```mermaid
+graph TD
+    A[Stage 1: Prep & Organize] -->|organize_photos.py| B[Page Folders & Mapping JSON]
+    B --> C[Stage 2 & 3: Layout Generation]
+    C -->|create_full_bleed_layouts.py| D[9000x3600 px Print Spreads]
+    E[Stage 4: Cover Upscaling] -->|upscale_covers.py| F[Print-Ready Cover JPEGs]
+```
+
+---
+
+## Stage-by-Stage Workflow
+
+### Stage 1: Preparation & Balanced Page Sorting
+Chronological sequence must be preserved at a macro level, but photos should be scrambled within local windows (chunks) to balance the number of landscape ("L") and portrait ("P") images per page folder.
+*   **Target Pages**: 20 page folders (`page 1` to `page 20`).
+*   **Balanced Distribution**: Target 11 or 12 photos per page (e.g. 9 Landscapes and 2-3 Portraits per page).
+*   **JSON Map**: A mapping file `photo_organization_map.json` is generated to track which photos belong to which page.
+
+**Execution**:
+Run the organizer script, specifying the source folder containing the flat list of JPEG images and the target output directory:
+```bash
+python scripts/organize_photos.py --dir "path/to/photos" --out "path/to/workspace" --seed 42
+```
+*Note: If running on Windows, use `python -Xutf8` to avoid console encoding issues with status output.*
+
+---
+
+### Stage 2: Grid Layout & Coordinates
+Spreads are generated at $9000 \times 3600$ px (300 DPI). Each page half gets an active grid area of $4275 \times 3300$ px after subtracting margins and gutter seams:
+*   **Outer Margins**: 150 px top, bottom, and outside edges.
+*   **Vertical Center Gutter**: 150 px total gutter seam (no image content between $x = 4425$ and $x = 4575$).
+*   **Image Gaps**: 40 px spacing horizontally and vertically.
+
+Layout configurations are determined dynamically based on photo counts and orientations:
+*   **Template 5A (5 Photos: 4L, 1P)**: One large landscape col, one portrait + landscape col.
+*   **Template 6A (6 Photos: 5L, 1P)**: Two landscape rows (4 total), one portrait + landscape col.
+*   **Template 6B (6 Photos: 4L, 2P)**: Two large landscape rows (2 total), one double-portrait + double-landscape col.
+
+For a complete coordinate reference and details on column configurations, see [layout_templates.md](references/layout_templates.md).
+
+---
+
+### Stage 3: Spread Assembly & Rendering
+The layout compiler reads the page directories, detects photo orientations on the fly, applies the coordinate grids, crops photos to fill cells (using centered LANCZOS fit-scale), and merges them into $9000 \times 3600$ px JPEG spreads.
+*   **Page Swapping**: Alternating layout orientation avoids monotonous designs. Left page columns swap if `page_num % 2 == 0`, and right page columns swap if `page_num % 3 == 0`.
+
+**Execution**:
+Compile the print-ready layouts:
+```bash
+python scripts/create_full_bleed_layouts.py --workspace-dir "path/to/workspace" --out-dir "path/to/output/layouts" --quality 95
+```
+
+---
+
+### Stage 4: Cover Art Upscaling
+AI-generated cover art and presentation box lid files need to be upscaled to final high-resolution print dimensions using high-quality LANCZOS interpolation.
+*   **Front/Back Cover size**: $4500 \times 3600$ px.
+*   **Presentation Briefcase Box size**: $4950 \times 4050$ px.
+
+**Execution**:
+Upscale cover background textures or complete cover designs:
+```bash
+python scripts/upscale_covers.py --src "path/to/cover.png" --out "path/to/upscaled_cover.jpg" --width 4500 --height 3600 --quality 95
+```
+
+---
+
+## Revert Option
+If you need to restart the process or undo the page folder classification, run the revert tool to move photos back to the root workspace directory and remove empty page folders:
+```bash
+python scripts/revert_organization.py --workspace-dir "path/to/workspace"
+```
+
+## Bundled Resources
+
+*   **Scripts**:
+    *   [organize_photos.py](file:///C:/Users/johno/.gemini/config/skills/photo-book-builder/scripts/organize_photos.py) - Groups and balances photo directories.
+    *   [create_full_bleed_layouts.py](file:///C:/Users/johno/.gemini/config/skills/photo-book-builder/scripts/create_full_bleed_layouts.py) - Assembles masonry grid pages into print-ready spreads.
+    *   [upscale_covers.py](file:///C:/Users/johno/.gemini/config/skills/photo-book-builder/scripts/upscale_covers.py) - General-purpose upscaling script.
+    *   [revert_organization.py](file:///C:/Users/johno/.gemini/config/skills/photo-book-builder/scripts/revert_organization.py) - Restores files back to flat source directories.
+*   **References**:
+    *   [layout_templates.md](file:///C:/Users/johno/.gemini/config/skills/photo-book-builder/references/layout_templates.md) - Exact coordinates, dimensions, and grid cells.

package/assets/.agent/skills/photo-book-builder/references/layout_templates.md

@@ -0,0 +1,72 @@
+# Photo Book Layout Grid Templates Reference
+
+This reference documents the exact coordinate maps, margins, gaps, and cell dimensions for the 12" × 30" (9000 × 3600 px at 300 DPI) full-bleed masonry layout spreads.
+
+## Page Dimensions
+*   **Total Spread Canvas**: $9000 \times 3600$ pixels.
+*   **Page Halves**: 
+    *   **Left Page (Page A)**: $x \in [0, 4500]$, $y \in [0, 3600]$
+    *   **Right Page (Page B)**: $x \in [4500, 9000]$, $y \in [0, 3600]$
+*   **Outer Margins**: Exactly **150 pixels** on the top, bottom, and outside edges of each page half.
+*   **Gaps Between Images**: Exactly **40 pixels** horizontally and vertically.
+*   **Center Seam Gutter**: Exactly **150 pixels** total (no image placed between $x = 4425$ and $x = 4575$).
+*   **Active Page Half Grid Size**: $4275 \times 3300$ pixels.
+    *   Left Page active $x$ range: $[150, 4425]$
+    *   Right Page active $x$ range: $[4575, 8850]$
+    *   Active $y$ range: $[150, 3450]$
+
+---
+
+## Column Configurations & Dimensions
+
+To cover the active area completely without vertical white spaces, we use three specific column widths:
+*   **Large Landscape Column**: $2550$ px wide.
+*   **Medium Landscape Column**: $1350$ px wide (only when paired with a $2550$ px column).
+*   **Narrow Landscape / Portrait Column**: $1685$ px wide.
+*   **Symmetric Double-Portrait Column**: $2118$ / $2117$ px wide.
+
+---
+
+## Template Layouts
+
+### Template 5A (5 Photos: 4 Landscapes, 1 Portrait)
+*   **Column A (2550 px wide)**:
+    *   Row 1: 1 Large Landscape ($2550 \times 1630$ px)
+    *   Row 2: 2 Small Landscapes side-by-side ($1255 \times 1630$ px each)
+*   **Column B (1685 px wide)**:
+    *   Row 1: 1 Portrait ($1685 \times 2480$ px)
+    *   Row 2: 1 Panoramic Landscape ($1685 \times 780$ px)
+*   *Sum of widths*: $2550 + 1685 + 40 \text{ (gap)} = 4275$ px.
+*   *Sum of heights*: 
+    *   Col A: $1630 + 1630 + 40 = 3300$ px.
+    *   Col B: $2480 + 780 + 40 = 3300$ px.
+
+### Template 6A (6 Photos: 5 Landscapes, 1 Portrait)
+*   **Column A (2550 px wide)**:
+    *   Row 1: 2 Small Landscapes side-by-side ($1255 \times 1630$ px each)
+    *   Row 2: 2 Small Landscapes side-by-side ($1255 \times 1630$ px each)
+*   **Column B (1685 px wide)**:
+    *   Row 1: 1 Portrait ($1685 \times 2480$ px)
+    *   Row 2: 1 Panoramic Landscape ($1685 \times 780$ px)
+*   *Sum of widths*: $2550 + 1685 + 40 \text{ (gap)} = 4275$ px.
+*   *Sum of heights*: $3300$ px.
+
+### Template 6B (6 Photos: 4 Landscapes, 2 Portraits)
+*   **Column A (2118 px wide)**:
+    *   Row 1: 1 Large Landscape ($2118 \times 1630$ px)
+    *   Row 2: 1 Large Landscape ($2118 \times 1630$ px)
+*   **Column B (2117 px wide)**:
+    *   Row 1: 2 Portraits side-by-side ($1038 \times 1630$ px each)
+    *   Row 2: 2 Landscapes side-by-side ($1038 \times 1630$ px each)
+*   *Sum of widths*: $2118 + 2117 + 40 \text{ (gap)} = 4275$ px.
+*   *Sum of heights*: $3300$ px.
+
+---
+
+## Deterministic Page Swapping
+
+To vary the page designs dynamically across the book:
+*   Swap Left Page columns if `page_num % 2 == 0`.
+*   Swap Right Page columns if `page_num % 3 == 0`.
+
+When swapping a column layout, Column B's starting $x$ coordinate is placed at the outer margin, and Column A's starting $x$ coordinate is placed after it.

package/assets/.agent/skills/photo-book-builder/scripts/create_full_bleed_layouts.py

@@ -0,0 +1,212 @@
+import os
+import json
+import argparse
+from PIL import Image, ImageDraw
+
+def fit_image(image_path, target_w, target_h):
+    with Image.open(image_path) as img:
+        img_w, img_h = img.size
+        scale = max(target_w / img_w, target_h / img_h)
+        new_w = int(img_w * scale)
+        new_h = int(img_h * scale)
+        resized = img.resize((new_w, new_h), Image.Resampling.LANCZOS)
+        
+        left = (new_w - target_w) // 2
+        top = (new_h - target_h) // 2
+        right = left + target_w
+        bottom = top + target_h
+        
+        return resized.crop((left, top, right, bottom))
+
+def get_page_cells(is_left, count, landscapes, portraits, swap_cols):
+    cells = []
+    offset = 0 if is_left else 4500
+    start_x_offset = 150 if is_left else 75
+    
+    if count == 5:
+        # 4L, 1P -> Template 5A
+        # Col 1: width 2550. Col 2: width 1685. Gap 40.
+        if not swap_cols:
+            col1_x = offset + start_x_offset
+            col2_x = offset + start_x_offset + 2550 + 40
+        else:
+            col2_x = offset + start_x_offset
+            col1_x = offset + start_x_offset + 1685 + 40
+            
+        # Left Col (2550 wide)
+        cells.append((landscapes[0], (col1_x, 150, 2550, 1630)))
+        cells.append((landscapes[1], (col1_x, 1820, 1255, 1630)))
+        cells.append((landscapes[2], (col1_x + 1255 + 40, 1820, 1255, 1630)))
+        # Right Col (1685 wide)
+        cells.append((portraits[0], (col2_x, 150, 1685, 2480)))
+        cells.append((landscapes[3], (col2_x, 2670, 1685, 780)))
+        
+    elif count == 6 and len(portraits) == 1:
+        # 5L, 1P -> Template 6A
+        # Col 1: width 2550. Col 2: width 1685. Gap 40.
+        if not swap_cols:
+            col1_x = offset + start_x_offset
+            col2_x = offset + start_x_offset + 2550 + 40
+        else:
+            col2_x = offset + start_x_offset
+            col1_x = offset + start_x_offset + 1685 + 40
+            
+        # Left Col (2550 wide)
+        cells.append((landscapes[0], (col1_x, 150, 1255, 1630)))
+        cells.append((landscapes[1], (col1_x + 1255 + 40, 150, 1255, 1630)))
+        cells.append((landscapes[2], (col1_x, 1820, 1255, 1630)))
+        cells.append((landscapes[3], (col1_x + 1255 + 40, 1820, 1255, 1630)))
+        # Right Col (1685 wide)
+        cells.append((portraits[0], (col2_x, 150, 1685, 2480)))
+        cells.append((landscapes[4], (col2_x, 2670, 1685, 780)))
+        
+    elif count == 6 and len(portraits) == 2:
+        # 4L, 2P -> Template 6B
+        # Col 1: width 2118. Col 2: width 2117. Gap 40.
+        if not swap_cols:
+            col1_x = offset + start_x_offset
+            col2_x = offset + start_x_offset + 2118 + 40
+        else:
+            col2_x = offset + start_x_offset
+            col1_x = offset + start_x_offset + 2117 + 40
+            
+        # Left Col (2118 wide)
+        cells.append((landscapes[0], (col1_x, 150, 2118, 1630)))
+        cells.append((landscapes[1], (col1_x, 1820, 2118, 1630)))
+        # Right Col (2117 wide)
+        cells.append((portraits[0], (col2_x, 150, 1038, 1630)))
+        cells.append((portraits[1], (col2_x + 1038 + 40, 150, 1038, 1630)))
+        cells.append((landscapes[2], (col2_x, 1820, 1038, 1630)))
+        cells.append((landscapes[3], (col2_x + 1038 + 40, 1820, 1038, 1630)))
+        
+    return cells
+
+def generate_layouts(workspace_dir, out_dir, quality=95):
+    os.makedirs(out_dir, exist_ok=True)
+    
+    # Load photo organization mapping
+    map_path = os.path.join(workspace_dir, "photo_organization_map.json")
+    if not os.path.exists(map_path):
+        print(f"Error: Organization map '{map_path}' not found! Run organization step first.")
+        return
+        
+    with open(map_path, "r") as f:
+        pages = json.load(f)
+        
+    canvas_w = 9000
+    canvas_h = 3600
+    
+    for p_str, page_files in pages.items():
+        p = int(p_str)
+        print(f"Generating optimized full-bleed print spread for Page {p}...")
+        
+        # Analyze photo orientations on the fly
+        orientations = {}
+        for filename in page_files:
+            img_path = os.path.join(workspace_dir, f"page {p}", filename)
+            if not os.path.exists(img_path):
+                # Fallback check at root level of workspace
+                img_path = os.path.join(workspace_dir, filename)
+                
+            try:
+                with Image.open(img_path) as img:
+                    w, h = img.size
+                    orientations[filename] = "L" if w > h else "P"
+            except Exception as e:
+                print(f"Warning: Could not open {filename} to determine orientation: {e}")
+                orientations[filename] = "L" # default fallback
+                
+        l_files = [f for f in page_files if orientations.get(f, "L") == "L"]
+        p_files = [f for f in page_files if orientations.get(f, "L") == "P"]
+        
+        # Determine total photos for layout selection
+        total_photos = len(page_files)
+        
+        # Distribute photos between left and right pages
+        if total_photos == 11:
+            left_count = 5
+            # Left gets 4L, 1P
+            left_l = l_files[:4]
+            left_p = p_files[:1]
+            # Right gets 5L, 1P
+            right_l = l_files[4:]
+            right_p = p_files[1:]
+        elif total_photos == 12:
+            left_count = 6
+            if len(p_files) >= 3:
+                # 9L, 3P distribution
+                # Left gets 5L, 1P (Template 6A)
+                left_l = l_files[:5]
+                left_p = p_files[:1]
+                # Right gets 4L, 2P (Template 6B)
+                right_l = l_files[5:]
+                right_p = p_files[1:]
+            else:
+                # If we don't have enough portraits for a 6B template on the right,
+                # fallback or adapt. Let's assume standard distribution:
+                # Left gets 5L, 1P (Template 6A)
+                left_l = l_files[:5]
+                left_p = p_files[:1] if p_files else []
+                # Right gets 4L, 2P (Template 6B) if possible, otherwise adjust counts
+                right_l = l_files[5:]
+                right_p = p_files[1:] if len(p_files) > 1 else p_files
+        else:
+            # Fallback for unexpected photo count per page
+            print(f"Warning: Page {p} has {total_photos} photos (expected 11 or 12). Making standard splits...")
+            left_count = total_photos // 2
+            # distribute list evenly
+            left_l = l_files[:len(l_files)//2]
+            left_p = p_files[:len(p_files)//2]
+            right_l = l_files[len(l_files)//2:]
+            right_p = p_files[len(p_files)//2:]
+            
+        left_swap = (p % 2 == 0)
+        right_swap = (p % 3 == 0)
+        
+        left_cells = get_page_cells(is_left=True, count=left_count, landscapes=left_l, portraits=left_p, swap_cols=left_swap)
+        right_cells = get_page_cells(is_left=False, count=6, landscapes=right_l, portraits=right_p, swap_cols=right_swap)
+        
+        # Create canvas with a light background
+        canvas = Image.new("RGB", (canvas_w, canvas_h), "#F4F4F6")
+        
+        # Render Left Page
+        for filename, (x, y, w, h) in left_cells:
+            img_path = os.path.join(workspace_dir, f"page {p}", filename)
+            if not os.path.exists(img_path):
+                img_path = os.path.join(workspace_dir, filename)
+            try:
+                fitted = fit_image(img_path, w, h)
+                canvas.paste(fitted, (x, y))
+            except Exception as e:
+                print(f"Error drawing {filename} on left page {p}: {e}")
+                draw = ImageDraw.Draw(canvas)
+                draw.rectangle([x, y, x + w, y + h], fill="#CCCCCC")
+                
+        # Render Right Page
+        for filename, (x, y, w, h) in right_cells:
+            img_path = os.path.join(workspace_dir, f"page {p}", filename)
+            if not os.path.exists(img_path):
+                img_path = os.path.join(workspace_dir, filename)
+            try:
+                fitted = fit_image(img_path, w, h)
+                canvas.paste(fitted, (x, y))
+            except Exception as e:
+                print(f"Error drawing {filename} on right page {p}: {e}")
+                draw = ImageDraw.Draw(canvas)
+                draw.rectangle([x, y, x + w, y + h], fill="#CCCCCC")
+                
+        # Save layout spread
+        output_path = os.path.join(out_dir, f"page_{p:02d}_layout.jpg")
+        canvas.save(output_path, "JPEG", quality=quality)
+        print(f"Saved layout to {output_path}")
+        
+    print("\nAll optimized full-bleed print layouts successfully created!")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Generate full-bleed print spreads for the photo book.")
+    parser.add_argument("--workspace-dir", required=True, help="Directory containing page folders and organization map.")
+    parser.add_argument("--out-dir", required=True, help="Directory where generated layout spreads should be saved.")
+    parser.add_argument("--quality", type=int, default=95, help="JPEG export quality (default: 95).")
+    args = parser.parse_args()
+    
+    generate_layouts(args.workspace_dir, args.out_dir, args.quality)

package/assets/.agent/skills/photo-book-builder/scripts/organize_photos.py

@@ -0,0 +1,99 @@
+import os
+import shutil
+import random
+import json
+import argparse
+from PIL import Image
+
+def organize_photos(directory, output_dir, seed=42):
+    # Set seed for reproducible/stable randomness
+    random.seed(seed)
+    
+    # 1. Find all jpeg files in the source directory
+    all_files = [f for f in os.listdir(directory) if f.lower().endswith(('.jpg', '.jpeg'))]
+    all_files.sort() # chronological sort by filename
+    
+    if not all_files:
+        print(f"Error: No JPEG images found in {directory}!")
+        return
+        
+    # 2. Classify by orientation
+    landscapes = []
+    portraits = []
+    
+    for f in all_files:
+        filepath = os.path.join(directory, f)
+        try:
+            with Image.open(filepath) as img:
+                w, h = img.size
+                if w > h:
+                    landscapes.append(f)
+                else:
+                    portraits.append(f)
+        except Exception as e:
+            print(f"Error reading {f}: {e}")
+            
+    print(f"Found {len(landscapes)} landscapes and {len(portraits)} portraits.")
+    
+    # Initialize pages (pages 1 to 20)
+    pages = {i: [] for i in range(1, 21)}
+    
+    # 3. Distribute landscapes
+    chunk_size = 20
+    for i in range(0, len(landscapes), chunk_size):
+        chunk = landscapes[i:i+chunk_size]
+        random.shuffle(chunk)
+        if len(chunk) == chunk_size:
+            for page_idx, filename in enumerate(chunk):
+                pages[page_idx + 1].append(filename)
+        else:
+            chosen_pages = random.sample(range(1, 21), len(chunk))
+            for page_num, filename in zip(chosen_pages, chunk):
+                pages[page_num].append(filename)
+                
+    # 4. Distribute portraits
+    for i in range(0, len(portraits), chunk_size):
+        chunk = portraits[i:i+chunk_size]
+        random.shuffle(chunk)
+        if len(chunk) == chunk_size:
+            for page_idx, filename in enumerate(chunk):
+                pages[page_idx + 1].append(filename)
+        else:
+            chosen_pages = random.sample(range(1, 21), len(chunk))
+            for page_num, filename in zip(chosen_pages, chunk):
+                pages[page_num].append(filename)
+                
+    # 5. Verify & Print Proposed Distribution
+    print("\n--- Proposed Distribution ---")
+    for page_num in range(1, 21):
+        files = pages[page_num]
+        l_count = sum(1 for f in files if f in landscapes)
+        p_count = sum(1 for f in files if f in portraits)
+        print(f"Page {page_num}: {len(files)} photos (Landscapes: {l_count}, Portraits: {p_count})")
+        
+    # Save the mapping as JSON in the output directory
+    os.makedirs(output_dir, exist_ok=True)
+    mapping_path = os.path.join(output_dir, 'photo_organization_map.json')
+    with open(mapping_path, 'w') as f:
+        json.dump(pages, f, indent=4)
+        
+    # Create page folders and move files
+    print("\nMoving files into page folders...")
+    for page_num, files in pages.items():
+        page_dir = os.path.join(output_dir, f"page {page_num}")
+        os.makedirs(page_dir, exist_ok=True)
+        for filename in files:
+            src = os.path.join(directory, filename)
+            dst = os.path.join(page_dir, filename)
+            shutil.move(src, dst)
+            
+    print("Organization complete!")
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description="Sort photos chronologically into 20 balanced page folders.")
+    parser.add_argument("--dir", default=".", help="Source directory containing unorganized photos.")
+    parser.add_argument("--out", default=".", help="Output directory where page folders will be created.")
+    parser.add_argument("--seed", type=int, default=42, help="Random seed for stable reproducibility.")
+    args = parser.parse_args()
+    
+    organize_photos(args.dir, args.out, args.seed)