@kortix/sandbox 0.4.1

package/opencode/skills/KORTIX-pdf/scripts/fill_pdf_form_with_annotations.py

@@ -0,0 +1,107 @@
+import json
+import sys
+
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import FreeText
+
+
+
+
+def transform_from_image_coords(bbox, image_width, image_height, pdf_width, pdf_height):
+    x_scale = pdf_width / image_width
+    y_scale = pdf_height / image_height
+
+    left = bbox[0] * x_scale
+    right = bbox[2] * x_scale
+
+    top = pdf_height - (bbox[1] * y_scale)
+    bottom = pdf_height - (bbox[3] * y_scale)
+
+    return left, bottom, right, top
+
+
+def transform_from_pdf_coords(bbox, pdf_height):
+    left = bbox[0]
+    right = bbox[2]
+
+    pypdf_top = pdf_height - bbox[1]      
+    pypdf_bottom = pdf_height - bbox[3]   
+
+    return left, pypdf_bottom, right, pypdf_top
+
+
+def fill_pdf_form(input_pdf_path, fields_json_path, output_pdf_path):
+    
+    with open(fields_json_path, "r") as f:
+        fields_data = json.load(f)
+    
+    reader = PdfReader(input_pdf_path)
+    writer = PdfWriter()
+    
+    writer.append(reader)
+    
+    pdf_dimensions = {}
+    for i, page in enumerate(reader.pages):
+        mediabox = page.mediabox
+        pdf_dimensions[i + 1] = [mediabox.width, mediabox.height]
+    
+    annotations = []
+    for field in fields_data["form_fields"]:
+        page_num = field["page_number"]
+
+        page_info = next(p for p in fields_data["pages"] if p["page_number"] == page_num)
+        pdf_width, pdf_height = pdf_dimensions[page_num]
+
+        if "pdf_width" in page_info:
+            transformed_entry_box = transform_from_pdf_coords(
+                field["entry_bounding_box"],
+                float(pdf_height)
+            )
+        else:
+            image_width = page_info["image_width"]
+            image_height = page_info["image_height"]
+            transformed_entry_box = transform_from_image_coords(
+                field["entry_bounding_box"],
+                image_width, image_height,
+                float(pdf_width), float(pdf_height)
+            )
+        
+        if "entry_text" not in field or "text" not in field["entry_text"]:
+            continue
+        entry_text = field["entry_text"]
+        text = entry_text["text"]
+        if not text:
+            continue
+        
+        font_name = entry_text.get("font", "Arial")
+        font_size = str(entry_text.get("font_size", 14)) + "pt"
+        font_color = entry_text.get("font_color", "000000")
+
+        annotation = FreeText(
+            text=text,
+            rect=transformed_entry_box,
+            font=font_name,
+            font_size=font_size,
+            font_color=font_color,
+            border_color=None,
+            background_color=None,
+        )
+        annotations.append(annotation)
+        writer.add_annotation(page_number=page_num - 1, annotation=annotation)
+        
+    with open(output_pdf_path, "wb") as output:
+        writer.write(output)
+    
+    print(f"Successfully filled PDF form and saved to {output_pdf_path}")
+    print(f"Added {len(annotations)} text annotations")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 4:
+        print("Usage: fill_pdf_form_with_annotations.py [input pdf] [fields.json] [output pdf]")
+        sys.exit(1)
+    input_pdf = sys.argv[1]
+    fields_json = sys.argv[2]
+    output_pdf = sys.argv[3]
+    
+    fill_pdf_form(input_pdf, fields_json, output_pdf)

package/opencode/skills/KORTIX-plan/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: kortix-plan
+description: "Structured planning mode for complex tasks. Use when a task involves architectural decisions, multi-file changes, unfamiliar codebases, multi-phase implementations, or when the user explicitly asks to plan before executing. Provides a 5-phase workflow (Understand, Investigate, Design, Write Plan, Execute) with persistent plan files and structured todo management. Triggers on: 'plan this', 'let me think', 'how should we approach', any task requiring 3+ steps across multiple domains, or when you feel uncertain about the right approach."
+---
+
+# Plan Mode
+
+Structured planning methodology for complex tasks. Produces a persistent plan file and a phased todo list before execution begins.
+
+## When to Plan
+
+**Enter plan mode when:**
+- The task spans 3+ steps across multiple files, systems, or domains
+- Architectural or design decisions are required (new systems, major refactors, integration work)
+- The codebase or domain is unfamiliar — you need investigation before action
+- The task has dependencies between steps (order matters, one wrong move cascades)
+- The user explicitly asks to plan first ("think about this", "plan this out", "how should we approach")
+- You feel uncertain about the right approach — planning resolves uncertainty before committing
+
+**Skip planning when:**
+- The task is a single, clear operation (fix a typo, add a field, run a command)
+- You've done this exact kind of task before and the approach is obvious
+- The task has fewer than 3 steps with no ambiguity
+- The user says "just do it" or "quick fix"
+
+## The 5 Phases
+
+### Phase 1: Understand
+
+Parse intent and establish scope before touching anything.
+
+1. **Restate the goal** in one sentence. If you can't, the request is ambiguous — ask clarifying questions.
+2. **Check memory** — search `workspace/.kortix/MEMORY.md` and `workspace/.kortix/memory/` for prior context, decisions, preferences, or past work that relates.
+3. **Check for existing plans** — `glob("workspace/.kortix/plans/*.md")` to see if a related plan already exists from a prior session.
+4. **Identify constraints** — deadlines, tech stack requirements, backwards compatibility, user preferences from memory.
+5. **Define success criteria** — what does "done" look like? Be specific. Write these down.
+6. **Create initial todo list** — high-level phases only at this stage:
+
+```
+TodoWrite([
+  { id: "plan-1", content: "Phase 1: Understand requirements and context", status: "in_progress", priority: "high" },
+  { id: "plan-2", content: "Phase 2: Investigate codebase and gather information", status: "pending", priority: "high" },
+  { id: "plan-3", content: "Phase 3: Design approach and make decisions", status: "pending", priority: "high" },
+  { id: "plan-4", content: "Phase 4: Write plan file", status: "pending", priority: "high" },
+  { id: "plan-5", content: "Phase 5: Execute plan", status: "pending", priority: "high" }
+])
+```
+
+### Phase 2: Investigate
+
+Gather all information needed to make design decisions. This phase is **read-only** — do not edit project files.
+
+1. **Launch parallel investigations** — use the Task tool to dispatch explore agents or `@kortix-research` for independent questions:
+   - Codebase exploration: "Find all files related to X, understand the current architecture"
+   - Dependency analysis: "What would be affected by changing Y?"
+   - Research: "What's the best practice for Z? What libraries exist?"
+2. **Read critical files** directly — don't delegate when you need deep understanding of specific files.
+3. **Search the web** if the task involves unfamiliar tech, APIs, or patterns.
+4. **Semantic search** for related past work: `lss "relevant query" -p /workspace/.kortix/ --json -k 5`
+5. **Document findings** — note key discoveries as you go. These feed into the design phase.
+6. **Update todos** — mark Phase 2 complete, note any blockers or open questions discovered.
+
+**Key rule:** Do not start writing code or editing files during investigation. Resist the urge. Premature implementation is the enemy of good planning.
+
+### Phase 3: Design
+
+Synthesize findings into decisions. This is where you think.
+
+1. **List approaches** — for each major decision, identify 2-3 options with tradeoffs.
+2. **Decide** — pick the best approach for each. Document why. Don't present a menu to the user unless the tradeoffs are genuinely user-facing (cost, UX, timeline).
+3. **Map dependencies** — which tasks depend on others? What's the critical path? What can be parallelized?
+4. **Break down into tasks** — decompose the implementation into specific, atomic tasks. Each task should be:
+   - Independently verifiable (you can check if it worked)
+   - Small enough to complete in one focused pass
+   - Clear about what files it touches
+5. **Identify risks** — what could go wrong? What's the rollback plan?
+6. **Expand the todo list** — replace the Phase 5 placeholder with the actual task breakdown:
+
+```
+TodoWrite([
+  { id: "plan-1", content: "Phase 1: Understand requirements", status: "completed", priority: "high" },
+  { id: "plan-2", content: "Phase 2: Investigate codebase", status: "completed", priority: "high" },
+  { id: "plan-3", content: "Phase 3: Design approach", status: "completed", priority: "high" },
+  { id: "plan-4", content: "Phase 4: Write plan file", status: "in_progress", priority: "high" },
+  { id: "exec-1", content: "Create database schema for user metrics", status: "pending", priority: "high" },
+  { id: "exec-2", content: "Implement metrics collection service (depends: exec-1)", status: "pending", priority: "high" },
+  { id: "exec-3", content: "Add API endpoints for metrics retrieval (depends: exec-2)", status: "pending", priority: "medium" },
+  { id: "exec-4", content: "Build export functionality (CSV, JSON, PDF) (depends: exec-3)", status: "pending", priority: "medium" },
+  { id: "exec-5", content: "Write tests and verify end-to-end", status: "pending", priority: "high" }
+])
+```
+
+Note: use `(depends: <id>)` in the content field to express dependencies. Execute tasks in dependency order.
+
+### Phase 4: Write Plan
+
+Persist the plan as a markdown file for cross-session reference.
+
+1. **Create the plan file** at `workspace/.kortix/plans/{YYYY-MM-DD}-{slug}.md`
+   - `{slug}` = 2-4 word kebab-case summary (e.g., `user-metrics-export`, `auth-refactor`, `api-v2-migration`)
+2. **Use the standard format** (see Plan File Format below).
+3. **Present the plan** to the user with a concise summary. Wait for confirmation before executing unless the user already said "just do it."
+
+### Phase 5: Execute
+
+Work through the plan systematically.
+
+1. **Follow the todo list** — work through tasks in dependency order.
+2. **One task at a time** — mark `in_progress`, complete it, mark `completed`, then move to the next.
+3. **Verify each task** — run tests, check output, read files back. Don't mark complete until verified.
+4. **Update the plan file** if the approach changes during execution — plans are living documents, not contracts.
+5. **Update todos in real-time** — the todo list is the single source of truth for progress.
+6. **Handle blockers** — if a task can't be completed as planned:
+   - Try alternative approaches (Failure Protocol from kortix-main applies)
+   - Update the plan file with what changed and why
+   - Adjust dependent tasks as needed
+7. **Final verification** — after all tasks complete, verify the overall success criteria from Phase 1.
+8. **Update memory** — persist any learnings, decisions, or patterns worth remembering.
+
+## Plan File Format
+
+```markdown
+# Plan: {Title}
+
+**Created:** {YYYY-MM-DD}
+**Status:** draft | in-progress | completed | abandoned
+**Goal:** {One-sentence goal}
+
+## Context
+
+{What prompted this plan. Prior work, user request, relevant memory.}
+
+## Success Criteria
+
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+- [ ] {Criterion 3}
+
+## Approach
+
+{High-level approach. Key architectural decisions and why.}
+
+### Alternatives Considered
+
+- **{Alternative A}:** {Why rejected}
+- **{Alternative B}:** {Why rejected}
+
+## Task Breakdown
+
+### Phase: {Phase Name}
+- [ ] {Task 1} — {brief description}
+- [ ] {Task 2} — {brief description, depends on Task 1}
+
+### Phase: {Phase Name}
+- [ ] {Task 3} — {brief description}
+
+## Risks
+
+- **{Risk 1}:** {Mitigation}
+- **{Risk 2}:** {Mitigation}
+
+## Notes
+
+{Anything discovered during execution. Updated as work progresses.}
+```
+
+## Todo List Patterns
+
+### Naming Convention
+
+Use prefixed IDs to group related tasks:
+- `plan-{n}` — planning phase tasks
+- `exec-{n}` — execution tasks
+- `verify-{n}` — verification tasks
+- `fix-{n}` — fix/adjustment tasks added during execution
+
+### Dependency Tracking
+
+Express dependencies in the task content: `"Implement X (depends: exec-1, exec-2)"`
+
+Execute tasks in dependency order. Never start a task whose dependencies aren't completed.
+
+### Progress Updates
+
+- Mark `in_progress` when you START a task (not before)
+- Mark `completed` IMMEDIATELY when done (don't batch completions)
+- Only ONE task should be `in_progress` at a time
+- Add new tasks as discovered — plans evolve during execution
+- Cancel tasks that become unnecessary with `cancelled` status
+
+### Handling Plan Changes
+
+If execution reveals the plan needs adjustment:
+1. Update the relevant task in the todo list
+2. Add new tasks if scope expanded
+3. Cancel tasks that are no longer needed
+4. Update the plan file's Notes section with what changed and why
+5. Continue execution — don't restart planning unless the fundamental approach is wrong
+
+## Managing Existing Plans
+
+### List Plans
+```
+glob("workspace/.kortix/plans/*.md")
+```
+
+### Resume a Plan
+Read the plan file, check which tasks are incomplete, rebuild the todo list from the remaining tasks, and continue execution from where it left off.
+
+### Archive a Plan
+Update the plan file status to `completed` or `abandoned`. No need to delete — plans serve as historical reference for future similar tasks.
+
+## Integration with Subagents
+
+During Phase 2 (Investigate), dispatch parallel investigations:
+
+```
+Task(@kortix-research, "Research best practices for X. Return: key findings, recommended libraries, common pitfalls.")
+Task(explore, "Find all files in the codebase related to Y. Return: file paths, key functions, architecture overview.")
+```
+
+During Phase 5 (Execute), delegate specialist subtasks:
+
+```
+Task(@kortix-web-dev, "Build the frontend component for X. Here is the plan: {paste relevant section}. Here is the context: {paste findings from Phase 2}.")
+```
+
+Always include full context when delegating — subagents start with zero context.

package/opencode/skills/KORTIX-presentation-viewer/SKILL.md

@@ -0,0 +1,87 @@
+# KORTIX Presentation Viewer
+
+A polished slide viewer and preview server for HTML presentations (1920x1080).
+
+## Architecture
+
+The viewer consists of two parts:
+
+1. **`viewer.html`** — a self-contained HTML template that renders slides in scaled iframes with keyboard navigation, fullscreen, and a thumbnail strip.
+2. **`serve.ts`** — a lightweight Bun HTTP server that serves the presentation folder and injects the viewer at `/`.
+
+## Why a server (not just a static HTML file)?
+
+Standalone 1920x1080 HTML slides opened directly in a browser are an unscaled, scrollable mess. The viewer fixes this by loading slides into iframes and CSS-scaling them to fit any viewport.
+
+The problem: **loading `<iframe src="slide_XX.html">` does not work reliably over `file://`**. Browsers enforce CORS/sandboxing restrictions on `file://` origins — Chrome blocks cross-file iframe access, Safari has different restrictions, Firefox another set. There is no consistent way to make iframe-based viewers work from the filesystem.
+
+An HTTP server on `localhost` eliminates all of this. Iframes load cleanly, images resolve correctly, and it works identically across every browser.
+
+## In the sandbox (container)
+
+**The viewer is already running as a service inside the sandbox container.** It starts automatically on boot via s6-overlay and listens on **port 3210**.
+
+- The service watches `/workspace/presentations/` for any presentation with a `metadata.json`
+- It serves the most recently created/updated presentation at `http://localhost:3210`
+- Port 3210 is exposed in docker-compose and mapped to the host
+
+**The agent does not need to start the server manually.** It is already available. After creating slides, the agent can simply tell the user to open `http://localhost:3210` (or the equivalent sandbox URL) to preview.
+
+If the service is not running for some reason (e.g. no presentations exist yet), it will auto-start once the first presentation's `metadata.json` appears. The agent can also restart it manually:
+
+```bash
+bun run /opt/KORTIX-presentation-viewer/serve.ts /workspace/presentations/<name>
+```
+
+### Container details
+
+| Item | Value |
+|------|-------|
+| Service location | `/etc/services.d/KORTIX-presentation-viewer/run` |
+| Viewer files | `/opt/KORTIX-presentation-viewer/` |
+| Port | `3210` (mapped to host) |
+| Presentations dir | `/workspace/presentations/` |
+| Managed by | s6-overlay (auto-restart on crash) |
+
+## Local development (outside container)
+
+```bash
+bun run .opencode/skills/KORTIX-presentation-viewer/serve.ts presentations/my-deck
+```
+
+Or via the `presentation-gen` tool:
+
+```
+presentation-gen(action: "preview", presentation_name: "my-deck")
+```
+
+This starts the server at `http://localhost:3210` and auto-opens the browser.
+
+## Viewer controls
+
+| Key | Action |
+|-----|--------|
+| `→` / `Space` / `↓` | Next slide |
+| `←` / `↑` | Previous slide |
+| `Home` | First slide |
+| `End` | Last slide |
+| `F` | Toggle fullscreen |
+| `T` | Toggle thumbnail strip |
+| `?` | Toggle keyboard shortcuts |
+| `Esc` | Exit fullscreen / close panels |
+| Swipe left/right | Navigate (touch) |
+
+## How scaling works
+
+Each slide is a 1920x1080 iframe. The viewer:
+
+1. Measures the actual stage area via `getBoundingClientRect()`
+2. Computes a scale factor: `min(availWidth / 1920, availHeight / 1080)`
+3. Sets the wrapper to the **displayed pixel size** (`1920 * scale` x `1080 * scale`)
+4. Applies `transform: scale(factor)` with `transform-origin: 0 0` to each iframe
+
+This means the wrapper's DOM size matches its visual size, so flexbox centering works perfectly. The 16:9 aspect ratio is maintained at any viewport size. A 3% proportional padding keeps space around the slide.
+
+## Integration with presentation-gen
+
+The `presentation-gen` tool auto-generates a `viewer.html` in each presentation folder on every `create_slide` or `delete_slide` action. This is a static fallback for quick local file:// viewing (works in some browsers), but the server is always the recommended way to preview.

package/opencode/skills/KORTIX-presentation-viewer/serve.ts

@@ -0,0 +1,136 @@
+/**
+ * Lightweight presentation preview server.
+ *
+ * Serves a presentation folder over HTTP with a polished slide viewer.
+ * Resolves the file:// iframe/CORS issues that make raw HTML viewing broken.
+ *
+ * Usage: bun run serve.ts <presentation-dir>
+ *   e.g. bun run serve.ts presentations/marko-kraemer
+ *        PORT=4000 bun run serve.ts presentations/my-deck
+ */
+
+import { readFileSync, existsSync, statSync } from "fs";
+import { resolve, join, extname, dirname } from "path";
+import { execSync } from "child_process";
+
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".pdf": "application/pdf",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
+
+function getMime(filePath: string): string {
+  return MIME_TYPES[extname(filePath).toLowerCase()] || "application/octet-stream";
+}
+
+function serveFile(filePath: string): Response {
+  if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+    return new Response("Not found", { status: 404 });
+  }
+  const data = readFileSync(filePath);
+  return new Response(data, {
+    headers: { "Content-Type": getMime(filePath), "Cache-Control": "no-cache" },
+  });
+}
+
+const presArg = process.argv[2];
+if (!presArg) {
+  console.error("Usage: bun run serve.ts <presentation-dir>");
+  console.error("  e.g. bun run serve.ts presentations/marko-kraemer");
+  process.exit(1);
+}
+
+const presDir = resolve(presArg);
+const metaPath = join(presDir, "metadata.json");
+
+if (!existsSync(metaPath)) {
+  console.error(`Error: metadata.json not found in ${presDir}`);
+  process.exit(1);
+}
+
+const metadata = JSON.parse(readFileSync(metaPath, "utf-8"));
+const parentDir = dirname(presDir);
+const viewerTemplatePath = resolve(dirname(new URL(import.meta.url).pathname), "viewer.html");
+
+function buildViewerHtml(): string {
+  const slides = Object.entries(metadata.slides || {})
+    .map(([num, data]: [string, any]) => ({
+      number: parseInt(num),
+      title: data.title || `Slide ${num}`,
+      filename: data.filename || `slide_${String(num).padStart(2, "0")}.html`,
+    }))
+    .sort((a, b) => a.number - b.number);
+
+  const presData = JSON.stringify({
+    title: metadata.title || metadata.presentation_name || "Presentation",
+    slides,
+  });
+
+  const template = readFileSync(viewerTemplatePath, "utf-8");
+  return template
+    .replace("{{TITLE}}", metadata.title || "Presentation")
+    .replace("{{PRESENTATION_DATA}}", presData);
+}
+
+const port = parseInt(process.env.PORT || "3210");
+
+const server = Bun.serve({
+  port,
+  fetch(req) {
+    const url = new URL(req.url);
+    let pathname = decodeURIComponent(url.pathname);
+
+    if (pathname === "/" || pathname === "/index.html") {
+      const html = buildViewerHtml();
+      return new Response(html, {
+        headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache" },
+      });
+    }
+
+    if (pathname.startsWith("/../images/") || pathname.startsWith("/%2E%2E/images/")) {
+      const imgPath = join(parentDir, "images", pathname.replace(/^\/(\.\.\/|%2E%2E\/)images\//, ""));
+      return serveFile(imgPath);
+    }
+
+    if (pathname.startsWith("/images/")) {
+      const imgPath = join(parentDir, "images", pathname.replace(/^\/images\//, ""));
+      return serveFile(imgPath);
+    }
+
+    const filePath = join(presDir, pathname.slice(1));
+    return serveFile(filePath);
+  },
+});
+
+const url = `http://localhost:${server.port}`;
+console.log(`\n  Presentation Viewer`);
+console.log(`  ${metadata.title || metadata.presentation_name || "Presentation"}`);
+console.log(`  ${Object.keys(metadata.slides || {}).length} slides\n`);
+console.log(`  ${url}\n`);
+console.log(`  Press Ctrl+C to stop\n`);
+
+try {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    execSync(`open "${url}"`, { stdio: "ignore" });
+  } else if (platform === "linux") {
+    execSync(`xdg-open "${url}"`, { stdio: "ignore" });
+  } else if (platform === "win32") {
+    execSync(`start "${url}"`, { stdio: "ignore" });
+  }
+} catch {
+  /* browser auto-open is best-effort */
+}