chore: Created engine/ Python project with FastAPI skeleton, all depend…

- "engine/pyproject.toml"
- "engine/main.py"
- "engine/.gitignore"
- "README.md"

GSD-Task: S01/T01

.gitignore

@@ -0,0 +1,27 @@
+
+# ── GSD baseline (auto-generated) ──
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~
+.idea/
+.vscode/
+*.code-workspace
+.env
+.env.*
+!.env.example
+node_modules/
+.next/
+dist/
+build/
+__pycache__/
+*.pyc
+.venv/
+venv/
+target/
+vendor/
+*.log
+coverage/
+.cache/
+tmp/

.gsd/KNOWLEDGE.md

@@ -0,0 +1,20 @@
+# Project Knowledge
+
+Append-only register of project-specific rules, patterns, and lessons learned.
+Agents read this before every unit. Add entries when you discover something worth remembering.
+
+## Rules
+
+| # | Scope | Rule | Why | Added |
+|---|-------|------|-----|-------|
+
+## Patterns
+
+| # | Pattern | Where | Notes |
+|---|---------|-------|-------|
+
+## Lessons Learned
+
+| # | What Happened | Root Cause | Fix | Scope |
+|---|--------------|------------|-----|-------|
+| L001 | pypotrace fails to build from pip | Requires system packages: `libpotrace-dev`, `libagg-dev`, `pkg-config` | `apt-get install -y libpotrace-dev libagg-dev pkg-config` before `pip install pypotrace` | engine build, Docker |

.gsd/STATE.md

@@ -1,20 +0,0 @@
-# GSD State
-
-**Active Milestone:** M001: Kerf Engine — Raster-to-Vector Pipeline & API
-**Active Slice:** S01: Core Pipeline — Preprocessing + Vectorization
-**Phase:** executing
-**Requirements Status:** 0 active · 0 validated · 0 deferred · 0 out of scope
-
-## Milestone Registry
-- 🔄 **M001:** Kerf Engine — Raster-to-Vector Pipeline & API
-- ⬜ **M002:** M002
-- ⬜ **M003:** M003
-
-## Recent Decisions
-- None recorded
-
-## Blockers
-- None
-
-## Next Action
-Execute T01: Repository scaffolding + Engine project setup in slice S01.

.gsd/event-log.jsonl

@@ -4,3 +4,4 @@
 {"cmd":"plan-slice","params":{"milestoneId":"M001","sliceId":"S01"},"ts":"2026-03-26T03:55:00.035Z","actor":"agent","hash":"b4e65a48e7b42f57","session_id":"5b5a1848-fcbc-4200-aa49-5260215f4e78"}
 {"cmd":"plan-slice","params":{"milestoneId":"M001","sliceId":"S02"},"ts":"2026-03-26T03:55:23.088Z","actor":"agent","hash":"7990d7932192bfde","session_id":"5b5a1848-fcbc-4200-aa49-5260215f4e78"}
 {"cmd":"plan-slice","params":{"milestoneId":"M001","sliceId":"S03"},"ts":"2026-03-26T03:55:42.360Z","actor":"agent","hash":"2d5b99521edd6ccd","session_id":"5b5a1848-fcbc-4200-aa49-5260215f4e78"}
+{"cmd":"complete-task","params":{"milestoneId":"M001","sliceId":"S01","taskId":"T01"},"ts":"2026-03-26T04:07:03.179Z","actor":"agent","hash":"5a804380eb33710e","session_id":"f5306801-4a7b-4a78-9c7a-c96e61e0b90b"}

.gsd/milestones/M001/slices/S01/S01-PLAN.md

@@ -4,7 +4,7 @@
 **Demo:** After this: POST /engine/trace with a PNG logo returns valid SVG using both Potrace and VTracer modes
 
 ## Tasks
-- [ ] **T01: Repository scaffolding + Engine project setup** — 1. Create the repo directory structure at /vmPool/r/repos/xpltdco/kerf/
+- [x] **T01: Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified** — 1. Create the repo directory structure at /vmPool/r/repos/xpltdco/kerf/
 2. Set up engine/ as a Python project with pyproject.toml
 3. Pin dependencies: fastapi, uvicorn, opencv-python-headless, pypotrace, vtracer, python-multipart, Pillow
 4. Create engine/main.py with FastAPI app skeleton

.gsd/milestones/M001/slices/S01/tasks/T01-SUMMARY.md

@@ -0,0 +1,82 @@
+---
+id: T01
+parent: S01
+milestone: M001
+provides: []
+requires: []
+affects: []
+key_files: ["engine/pyproject.toml", "engine/main.py", "engine/.gitignore", "README.md"]
+key_decisions: []
+patterns_established: []
+drill_down_paths: []
+observability_surfaces: []
+duration: ""
+verification_result: "pip install -e .[dev] succeeded. uvicorn starts, /docs returns Swagger UI, /health returns ok."
+completed_at: 2026-03-26T04:07:03.124Z
+blocker_discovered: false
+---
+
+# T01: Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified
+
+> Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified
+
+## What Happened
+---
+id: T01
+parent: S01
+milestone: M001
+key_files:
+  - engine/pyproject.toml
+  - engine/main.py
+  - engine/.gitignore
+  - README.md
+key_decisions:
+  - (none)
+duration: ""
+verification_result: passed
+completed_at: 2026-03-26T04:07:03.137Z
+blocker_discovered: false
+---
+
+# T01: Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified
+
+**Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified**
+
+## What Happened
+
+Created engine/ directory structure with subdirectories for pipeline/, api/, and tests/fixtures/. Set up pyproject.toml with setuptools build backend, all required dependencies pinned, and dev extras. Created main.py with a FastAPI app skeleton exposing /health and /docs. Installed system C libraries for pypotrace.
+
+## Verification
+
+pip install -e .[dev] succeeded. uvicorn starts, /docs returns Swagger UI, /health returns ok.
+
+## Verification Evidence
+
+| # | Command | Exit Code | Verdict | Duration |
+|---|---------|-----------|---------|----------|
+| 1 | `pip install -e .[dev]` | 0 | pass | 45000ms |
+| 2 | `curl http://localhost:8000/docs` | 0 | pass | 500ms |
+| 3 | `curl http://localhost:8000/health` | 0 | pass | 200ms |
+
+
+## Deviations
+
+Adapted repo path from /vmPool/r/repos/xpltdco/kerf/ to working directory. Installed system packages for pypotrace.
+
+## Known Issues
+
+pypotrace requires system C deps (libpotrace-dev, libagg-dev, pkg-config) — must be in Docker image.
+
+## Files Created/Modified
+
+- `engine/pyproject.toml`
+- `engine/main.py`
+- `engine/.gitignore`
+- `README.md`
+
+
+## Deviations
+Adapted repo path from /vmPool/r/repos/xpltdco/kerf/ to working directory. Installed system packages for pypotrace.
+
+## Known Issues
+pypotrace requires system C deps (libpotrace-dev, libagg-dev, pkg-config) — must be in Docker image.

.gsd/state-manifest.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "exported_at": "2026-03-26T03:55:42.360Z",
+  "exported_at": "2026-03-26T04:07:03.179Z",
   "milestones": [
     {
       "id": "M001",
@@ -402,19 +402,24 @@
       "milestone_id": "M001",
       "slice_id": "S01",
       "id": "T01",
-      "title": "Repository scaffolding + Engine project setup",
+      "title": "Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified",
-      "status": "pending",
+      "status": "complete",
-      "one_liner": "",
+      "one_liner": "Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified",
-      "narrative": "",
+      "narrative": "Created engine/ directory structure with subdirectories for pipeline/, api/, and tests/fixtures/. Set up pyproject.toml with setuptools build backend, all required dependencies pinned, and dev extras. Created main.py with a FastAPI app skeleton exposing /health and /docs. Installed system C libraries for pypotrace.",
-      "verification_result": "",
+      "verification_result": "pip install -e .[dev] succeeded. uvicorn starts, /docs returns Swagger UI, /health returns ok.",
       "duration": "",
-      "completed_at": null,
+      "completed_at": "2026-03-26T04:07:03.124Z",
       "blocker_discovered": false,
-      "deviations": "",
+      "deviations": "Adapted repo path from /vmPool/r/repos/xpltdco/kerf/ to working directory. Installed system packages for pypotrace.",
-      "known_issues": "",
+      "known_issues": "pypotrace requires system C deps (libpotrace-dev, libagg-dev, pkg-config) — must be in Docker image.",
-      "key_files": [],
+      "key_files": [
+        "engine/pyproject.toml",
+        "engine/main.py",
+        "engine/.gitignore",
+        "README.md"
+      ],
       "key_decisions": [],
-      "full_summary_md": "",
+      "full_summary_md": "---\nid: T01\nparent: S01\nmilestone: M001\nkey_files:\n  - engine/pyproject.toml\n  - engine/main.py\n  - engine/.gitignore\n  - README.md\nkey_decisions:\n  - (none)\nduration: \"\"\nverification_result: passed\ncompleted_at: 2026-03-26T04:07:03.137Z\nblocker_discovered: false\n---\n\n# T01: Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified\n\n**Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified**\n\n## What Happened\n\nCreated engine/ directory structure with subdirectories for pipeline/, api/, and tests/fixtures/. Set up pyproject.toml with setuptools build backend, all required dependencies pinned, and dev extras. Created main.py with a FastAPI app skeleton exposing /health and /docs. Installed system C libraries for pypotrace.\n\n## Verification\n\npip install -e .[dev] succeeded. uvicorn starts, /docs returns Swagger UI, /health returns ok.\n\n## Verification Evidence\n\n| # | Command | Exit Code | Verdict | Duration |\n|---|---------|-----------|---------|----------|\n| 1 | `pip install -e .[dev]` | 0 | pass | 45000ms |\n| 2 | `curl http://localhost:8000/docs` | 0 | pass | 500ms |\n| 3 | `curl http://localhost:8000/health` | 0 | pass | 200ms |\n\n\n## Deviations\n\nAdapted repo path from /vmPool/r/repos/xpltdco/kerf/ to working directory. Installed system packages for pypotrace.\n\n## Known Issues\n\npypotrace requires system C deps (libpotrace-dev, libagg-dev, pkg-config) — must be in Docker image.\n\n## Files Created/Modified\n\n- `engine/pyproject.toml`\n- `engine/main.py`\n- `engine/.gitignore`\n- `README.md`\n",
       "description": "1. Create the repo directory structure at /vmPool/r/repos/xpltdco/kerf/\n2. Set up engine/ as a Python project with pyproject.toml\n3. Pin dependencies: fastapi, uvicorn, opencv-python-headless, pypotrace, vtracer, python-multipart, Pillow\n4. Create engine/main.py with FastAPI app skeleton\n5. Create engine/requirements.txt or use pyproject.toml deps\n6. Add .gitignore, initial README.md\n7. Verify: pip install works, uvicorn starts the empty app",
       "estimate": "30min",
       "files": [
@@ -798,5 +803,39 @@
       "superseded_by": null
     }
   ],
-  "verification_evidence": []
+  "verification_evidence": [
+    {
+      "id": 1,
+      "task_id": "T01",
+      "slice_id": "S01",
+      "milestone_id": "M001",
+      "command": "pip install -e .[dev]",
+      "exit_code": 0,
+      "verdict": "pass",
+      "duration_ms": 45000,
+      "created_at": "2026-03-26T04:07:03.124Z"
+    },
+    {
+      "id": 2,
+      "task_id": "T01",
+      "slice_id": "S01",
+      "milestone_id": "M001",
+      "command": "curl http://localhost:8000/docs",
+      "exit_code": 0,
+      "verdict": "pass",
+      "duration_ms": 500,
+      "created_at": "2026-03-26T04:07:03.124Z"
+    },
+    {
+      "id": 3,
+      "task_id": "T01",
+      "slice_id": "S01",
+      "milestone_id": "M001",
+      "command": "curl http://localhost:8000/health",
+      "exit_code": 0,
+      "verdict": "pass",
+      "duration_ms": 200,
+      "created_at": "2026-03-26T04:07:03.124Z"
+    }
+  ]
 }

README.md

@@ -0,0 +1,26 @@
+# Kerf
+
+Modular raster-to-vector conversion engine + 2D sign/patch design canvas.
+
+## Repository Structure
+
+```
+engine/    — Kerf Engine (standalone API, Python/FastAPI)
+app/       — Kerf App frontend (React) [future]
+server/    — Kerf App backend API [future]
+docker/    — Dockerfiles and compose configs [future]
+```
+
+## Kerf Engine
+
+The engine is a self-contained FastAPI service that accepts raster images and returns clean vector output (SVG, DXF).
+
+### Quick Start
+
+```bash
+cd engine
+pip install -e ".[dev]"
+uvicorn main:app --host 0.0.0.0 --port 8000
+```
+
+API docs available at `http://localhost:8000/docs`.

engine/.gitignore

@@ -0,0 +1,2 @@
+*.egg-info/
+.eggs/

engine/main.py

@@ -0,0 +1,14 @@
+"""Kerf Engine — raster-to-vector conversion API."""
+
+from fastapi import FastAPI
+
+app = FastAPI(
+    title="Kerf Engine",
+    description="Raster-to-vector conversion pipeline with Potrace and VTracer modes",
+    version="0.1.0",
+)
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok"}

engine/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kerf-engine"
+version = "0.1.0"
+description = "Kerf Engine — raster-to-vector conversion pipeline"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "opencv-python-headless>=4.9",
+    "pypotrace>=0.3",
+    "vtracer>=0.6",
+    "python-multipart>=0.0.9",
+    "Pillow>=10.2",
+]
+
+[tool.setuptools.packages.find]
+include = ["pipeline*", "api*"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "httpx>=0.27",
+    "ruff>=0.3",
+]