diff --git a/README.md b/README.md index 692d3b0..cb749bd 100644 --- a/README.md +++ b/README.md @@ -2,74 +2,192 @@ 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 -share the same deck spec, style packs, and PPTX renderer. The same core contract -can later run behind `dev.slides.scottfelten.com` and `slides.scottfelten.com`. +**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` -The web UI is source-first: paste notes, drop a file, choose a file, or paste an -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. +## What Works In v0.1 -## 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 source content - -> content extraction - -> deck planning + -> text extraction + -> heuristic deck planning -> validated DeckSpec - -> brand/style pack + -> Incorta starter style pack -> PPTX renderer - -> saved artifacts + -> saved PPTX + DeckSpec JSON ``` -The LLM layer should produce structured thinking, not freehand slide design. -Renderers consume a validated `DeckSpec` and a `StylePack`. +This is deliberately local-first. It proves the core source-to-deck loop before +production hosting, auth, persistence, or full LLM orchestration. -## Quick Start +## Quick Start On MBS ```bash -npm install -npm run sample +cd /Users/tars/AgentPlane/projects/slide-factory/source/slide-factory +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 outputs/sample-incorta.pptx outputs/sample-incorta.deck.json ``` -Run the local API: +## API Smoke ```bash -npm run dev:api +curl -sS http://127.0.0.1:3025/api/health ``` -Run the web shell: +Upload a source file: ```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 -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` -- `.pdf` -- `.pptx` -- image files or pasted clipboard images +- 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 Notes +## AgentPlane Rules -- Implementation truth should live in Forgejo. +- Forgejo is implementation truth. - Runtime secrets must come from scoped projections or Model Service Gateway. -- Do not commit raw source data, tokens, refresh tokens, or customer documents. -- Google Slides generation should reuse the existing AgentPlane guidance: - copy templates, inventory native containers, fill existing object IDs, and - render thumbnails/contact sheets before handoff. +- 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. +