tars/slide-factory
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update v0.1 handoff README

Browse source
This commit is contained in:
Codex 2026-06-08 22:35:24 -07:00
parent 2501e86a80
commit ec8ba8dff8
1 changed files with 153 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

188
README.md
View file

@ -2,74 +2,192 @@
Slide Factory turns messy business content into brand-consistent slide decks. Slide Factory turns messy business content into brand-consistent slide decks.
The first build is intentionally local-first: a CLI, an API, and a small web UI **Current version:** v0.1 local source-upload MVP
share the same deck spec, style packs, and PPTX renderer. The same core contract **Primary dev machine:** MBS / Mac Studio
can later run behind `dev.slides.scottfelten.com` and `slides.scottfelten.com`. **Local source:** `/Users/tars/AgentPlane/projects/slide-factory/source/slide-factory`
**Forgejo:** `https://git.scottfelten.com/tars/slide-factory.git`
**Current branch:** `dev`
The web UI is source-first: paste notes, drop a file, choose a file, or paste an ## What Works In v0.1
image into the source area. The MVP extracts text from Markdown/text, PDF, and
PPTX files. Image upload starts a deck from image metadata today; vision/OCR is
reserved for the Model Service Gateway integration.
## MVP Contract 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 ```text
source content source content
-> content extraction -> text extraction
-> deck planning -> heuristic deck planning
-> validated DeckSpec -> validated DeckSpec
-> brand/style pack -> Incorta starter style pack
-> PPTX renderer -> PPTX renderer
-> saved artifacts -> saved PPTX + DeckSpec JSON
``` ```
The LLM layer should produce structured thinking, not freehand slide design. This is deliberately local-first. It proves the core source-to-deck loop before
Renderers consume a validated `DeckSpec` and a `StylePack`. production hosting, auth, persistence, or full LLM orchestration.
## Quick Start ## Quick Start On MBS
```bash ```bash
npm install cd /Users/tars/AgentPlane/projects/slide-factory/source/slide-factory
npm run sample zsh -lc "npm install"
``` ```
Outputs are written to: 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 ```text
outputs/sample-incorta.pptx outputs/sample-incorta.pptx
outputs/sample-incorta.deck.json outputs/sample-incorta.deck.json
``` ```
Run the local API: ## API Smoke
```bash ```bash
npm run dev:api curl -sS http://127.0.0.1:3025/api/health
``` ```
Run the web shell: Upload a source file:
```bash ```bash
npm run dev:web 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
``` ```
Then open: ## Repo Structure
```text ```text
http://127.0.0.1:5185 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
``` ```
Supported starter sources: ## Important Limits
- `.md`, `.markdown`, `.txt` - Image upload does not yet perform OCR or vision understanding. It creates a
- `.pdf` starter deck from image metadata and the user instructions.
- `.pptx` - PDF extraction is text-only. Scanned/image-only PDFs need future OCR.
- image files or pasted clipboard images - 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 Notes ## AgentPlane Rules
- Implementation truth should live in Forgejo. - Forgejo is implementation truth.
- Runtime secrets must come from scoped projections or Model Service Gateway. - Runtime secrets must come from scoped projections or Model Service Gateway.
- Do not commit raw source data, tokens, refresh tokens, or customer documents. - New production deploy, DNS, nginx, systemd, OAuth, secret projection, or
- Google Slides generation should reuse the existing AgentPlane guidance: provider-key work requires explicit approval.
copy templates, inventory native containers, fill existing object IDs, and - Google Slides generation should reuse:
render thumbnails/contact sheets before handoff.
```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.