slide-factory/README.md

# Slide Factory

Slide Factory turns messy business content into brand-consistent slide decks.

**Current version:** v0.1 local source-upload MVP  
**Primary dev machine:** MBS / Mac Studio  
**Local source:** `/Users/tars/AgentPlane/projects/slide-factory/source/slide-factory`  
**Forgejo:** `https://git.scottfelten.com/tars/slide-factory.git`  
**Current branch:** `dev`

## What Works In v0.1

The app can create an editable PPTX from:

- pasted markdown or plain text
- `.md`, `.markdown`, or `.txt` files
- `.pdf` files with extractable text
- `.pptx` files by extracting slide text
- image files or pasted clipboard images as starter context

The v0.1 deck-generation path is:

```text
source content
  -> text extraction
  -> heuristic deck planning
  -> validated DeckSpec
  -> Incorta starter style pack
  -> PPTX renderer
  -> saved PPTX + DeckSpec JSON
```

This is deliberately local-first. It proves the core source-to-deck loop before
production hosting, auth, persistence, or full LLM orchestration.

## Quick Start On MBS

```bash
cd /Users/tars/AgentPlane/projects/slide-factory/source/slide-factory
zsh -lc "npm install"
```

Run the API:

```bash
zsh -lc "SLIDE_FACTORY_PORT=3025 SLIDE_FACTORY_OUTPUT_DIR=outputs npm run dev:api"
```

Run the web app in a second terminal:

```bash
cd /Users/tars/AgentPlane/projects/slide-factory/source/slide-factory
zsh -lc "npm run dev:web"
```

Open on MBS:

```text
http://127.0.0.1:5185/
```

If using the MBA to view the MBS app, open an SSH tunnel from the MBA:

```bash
ssh -L 5185:127.0.0.1:5185 -L 3025:127.0.0.1:3025 tars-ts
```

Then open on the MBA:

```text
http://127.0.0.1:5185/
```

## Current Running Dev Server

If the previous session left the app running, the process metadata is here:

```text
/tmp/slide-factory-dev/api.pid
/tmp/slide-factory-dev/web.pid
/tmp/slide-factory-dev/api.log
/tmp/slide-factory-dev/web.log
```

Stop it with:

```bash
kill $(cat /tmp/slide-factory-dev/api.pid) $(cat /tmp/slide-factory-dev/web.pid)
```

Check ports:

```bash
lsof -nP -iTCP:3025 -sTCP:LISTEN
lsof -nP -iTCP:5185 -sTCP:LISTEN
```

## CLI Smoke

```bash
zsh -lc "npm run sample"
```

Outputs:

```text
outputs/sample-incorta.pptx
outputs/sample-incorta.deck.json
```

## API Smoke

```bash
curl -sS http://127.0.0.1:3025/api/health
```

Upload a source file:

```bash
curl -sS -X POST http://127.0.0.1:3025/api/decks/from-source \
  -F style=incorta \
  -F instructions="Create a concise executive deck." \
  -F source=@examples/customer-discovery.md
```

## Repo Structure

```text
apps/
  api/              Express API and source extraction
  cli/              Local deck creation command
  web/              React/Vite source-first UI
packages/
  core/             schemas, style loading, heuristic planner
  render-pptx/      deterministic PPTX renderer
styles/
  incorta/          starter Incorta style pack
examples/
  customer-discovery.md
docs/
  architecture.md
```

## Important Limits

- Image upload does not yet perform OCR or vision understanding. It creates a
  starter deck from image metadata and the user instructions.
- PDF extraction is text-only. Scanned/image-only PDFs need future OCR.
- The planner is heuristic. Model Service Gateway/LLM integration is not wired
  in yet.
- Generated slides are editable PPTX, but automated visual QA is still basic.
- No auth, persistence, job history, hosted route, or Google Slides mutation yet.
- Do not commit raw customer docs, transcripts, tokens, provider keys, or private
  Drive files.

## AgentPlane Rules

- Forgejo is implementation truth.
- Runtime secrets must come from scoped projections or Model Service Gateway.
- New production deploy, DNS, nginx, systemd, OAuth, secret projection, or
  provider-key work requires explicit approval.
- Google Slides generation should reuse:

```text
/Users/tars/AgentPlane/projects/google-slides
```

For branded Google Slides, use brand-safe mode: copy the template, inventory
native containers, fill existing object IDs, delete unused slides, and render
thumbnails/contact sheets for visual QA.

## Suggested Next Session

Start here:

```bash
cd /Users/tars/AgentPlane/projects/slide-factory/source/slide-factory
git status --short --branch
git pull --ff-only origin dev
zsh -lc "npm install && npm run build"
```

Recommended v0.2 priorities:

1. Add Model Service Gateway integration for source understanding and deck
   planning without raw provider keys in the app.
2. Add OCR/vision path for images and scanned PDFs.
3. Add SQLite job history and artifact metadata.
4. Add strict DeckSpec validation for external/LLM-generated specs.
5. Add PPTX visual QA: render thumbnails or PDF previews and catch overflow.
6. Add style-pack save/load workflow and template import.
7. Add Google Slides renderer using the existing template-container workflow.