README: screenshots, feature overview and alpha/parity summary; docs use control port 7990

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

AGENTS.md

@@ -141,8 +141,8 @@ to `main`.
 
 ## 6. Running and looking at the app
 
-- `cargo run --release -p deckcraft -- --sample --control 7979` (sample deck + control channel).
-- Drive it: JSON lines on `127.0.0.1:7979`, e.g.
+- `cargo run --release -p deckcraft -- --sample --control 7990` (sample deck + control channel).
+- Drive it: JSON lines on `127.0.0.1:7990`, e.g.
   `{"id":1,"method":"engine.execute","params":{"command":"shape.insert","params":{"preset":"star5","rect":[100,100,200,200]}}}`
   then `{"id":2,"method":"ui.screenshot","params":{"path":"/tmp/shot.png"}}`. Methods:
   `crates/ui-egui/src/control.rs`, docs: `docs/control-protocol.md`.
@@ -150,7 +150,7 @@ to `main`.
   in `plan/powerpoint/01-observed-ui.md`.
 - Headless: `deckcraft-cli render --sample --all --scale 1 out/`,
   `deckcraft-cli run --sample --cmd 'slide.new={"title":"Hi"}' --export out.png`.
-- MCP: `deckcraft-cli mcp` (headless) or `deckcraft-cli mcp --connect 7979` (drive the app).
+- MCP: `deckcraft-cli mcp` (headless) or `deckcraft-cli mcp --connect 7990` (drive the app).
   See `docs/mcp.md`.
 - Shell gotcha on the dev machine: `mv`/`cp` are aliased interactive; use `/bin/mv -f`, `/bin/cp -f`.
 - Parallel agents: separate `CARGO_TARGET_DIR` per agent; edit only the crates you own.

ATTRIBUTION.md

@@ -20,6 +20,7 @@ deck and UI icons are original work of the DeckCraft contributors (drawn or gene
 | `assets/app-icon/deckcraft-1024.png`, `assets/app-icon/hicolor/*/apps/ai.storyteller.deckcraft.png` | DeckCraft contributors | rendered by DeckCraft from `assets/app-icon/icon-source.deckcraft` (shapes only) | MIT OR Apache-2.0 | Placeholder app icon (presentation board) until the mascot icon is drawn |
 | `assets/app-icon/deckcraft.icns`, `assets/app-icon/deckcraft.ico` | DeckCraft contributors | generated from the PNGs above by `packaging/icons.sh` (sips/iconutil, `cargo xtask ico`) | MIT OR Apache-2.0 | macOS and Windows app icons |
 | `assets/app-icon/icon-source.deckcraft` | DeckCraft contributors | made with `deckcraft-cli run` (see git history) | MIT OR Apache-2.0 | Source of the placeholder icon |
+| `docs/images/editor.png`, `docs/images/shape-format.png`, `docs/images/format-pane.png`, `docs/images/slide-sorter.png`, `docs/images/dark-mode.png`, `docs/images/sample-deck.png` | DeckCraft contributors | Screenshots of DeckCraft and slides rendered by `deckcraft-cli` from the built-in sample deck (original content; Inter font, OFL-1.1) | MIT OR Apache-2.0 | README screenshots |
 | `crates/media/tests/fixtures/tone*` (`tone.mp3`, `.m4a`, `.aac`, `.ogg`, `.opus`, `.flac`, `.wma`, `tone-alac.m4a`) | DeckCraft contributors | synthesised 0.5 s 440 Hz sine, encoded by `crates/media/tests/fixtures/make.sh` (ffmpeg as the encoder only) | CC0-1.0 | Audio decoding tests |
 | `crates/media/tests/fixtures/clip-*` (`clip-h264.mp4`, `clip-h264.mov`, `clip-hevc.mp4`, `clip-vp9.webm`, `clip-av1.mkv`) | DeckCraft contributors | 6 frames of a colour gradient generated by `make.sh` (python3), encoded by ffmpeg (x264 / x265 / libvpx / SVT-AV1 as encoders only) | CC0-1.0 | Video decoding tests |
 | `crates/media/tests/fixtures/make.sh` | DeckCraft contributors | this repository | MIT OR Apache-2.0 | Regenerates the media fixtures |

CLAUDE.md

@@ -10,7 +10,7 @@ win over anything here.
 
 ## Habits
 - Every user-visible action is a command with tests (`crates/engine/src/cmd/*`).
-- Look at UI changes: `deckcraft --sample --control 7979` + `ui.screenshot`, or
+- Look at UI changes: `deckcraft --sample --control 7990` + `ui.screenshot`, or
   `deckcraft-cli render`.
 - Commit after each landed arc (`M<n>.<k>: what`) and push to `origin main`.
 - Keep `ROADMAP.md` and `plan/STATUS.md` current.

README.md

@@ -42,6 +42,10 @@
 > filmmakers, illustrators, designers, animators, hobbyists, and people who picked up a pencil
 > last week. If you make things, you're one of us. **[Come say hi on Discord](https://discord.gg/artcraft).**
 
+<p align="center">
+  <img alt="DeckCraft editing a slide: ribbon, slide thumbnails with sections, a process diagram on the canvas, notes and status bar" src="docs/images/editor.png" width="900">
+</p>
+
 <p align="center">
   <a href="#what-works-today">What works</a> ·
   <a href="#getting-started">Getting started</a> ·
@@ -53,19 +57,42 @@
 
 ## What works today
 
-DeckCraft is in early development. Today:
+DeckCraft is in early development, heading for its first alpha (see the [roadmap](ROADMAP.md)).
+Today it can:
 
-- **Presentation model** with slide masters, eleven layouts, placeholders that inherit position and
-  formatting, themes (colour, font and effect schemes), sections, notes, comments, transitions and
-  animations.
-- **150+ preset shapes** (rectangles, basic shapes, block arrows, equation shapes, flowchart, stars
-  and banners, callouts, action buttons) with adjust handles, re-derived from scratch.
-- **Text engine**: shaping with font fallback, line breaking, bullets and numbering, indents and
-  spacing, alignment, anchoring, columns, shrink-on-overflow and resize-to-fit.
-- **Renderer** (vello_cpu): gradients, pictures with crop and corrections, outlines with dashes and
-  arrowheads, shadows, glow, soft edges, reflections, tables with styles, charts.
-- **Editing engine**: 200+ commands, undo/redo, clipboard, grouping, align and distribute, smart
-  guides, Format Painter, in-place text editing — all scriptable.
+- **Make decks**: slide masters and eleven layouts with placeholders that inherit position and
+  formatting, eight original themes with colour and font schemes, sections, notes, comments,
+  headers and footers, custom slide sizes.
+- **Draw**: 150+ preset shapes with adjust handles, connectors that stay glued to shapes, freeform,
+  curve and scribble tools, merge shapes (union, combine, fragment, intersect, subtract), gradient,
+  picture and pattern fills, outlines with dashes and arrowheads, shadows, glow, soft edges and
+  reflections.
+- **Write**: in-place text editing with full font and paragraph formatting, bullets and numbering,
+  columns, autofit, vertical text, fields and hyperlinks.
+- **Add content**: pictures with crop and corrections, tables with styles, charts, SmartArt basics,
+  audio and video (MP3, AAC, FLAC, ALAC, Ogg, Opus, WAV, AIFF; H.264, HEVC, VP9, AV1).
+- **Present**: transitions (including Morph), entrance/emphasis/exit and motion-path animations,
+  by-paragraph builds, full-screen slide show, presenter view, pen, rehearse timings, media playback.
+- **Exchange files**: open and save PowerPoint `.pptx`, export PDF (slides, notes pages, handouts
+  with selectable text), PNG/JPEG and outlines. Unsaved work is kept by AutoRecover.
+- **Automate**: 200+ commands with undo, all scriptable from the CLI, a JSON control channel and an
+  MCP server for AI agents.
+
+<table>
+  <tr>
+    <td width="50%"><img alt="A selected shape with the Shape Format tab" src="docs/images/shape-format.png"><br><sub>Shape Format contextual tab and selection handles</sub></td>
+    <td width="50%"><img alt="The Format Shape pane editing a gradient fill" src="docs/images/format-pane.png"><br><sub>Format Shape pane: gradient type, direction and stops</sub></td>
+  </tr>
+  <tr>
+    <td width="50%"><img alt="Slide Sorter view with transitions under each slide" src="docs/images/slide-sorter.png"><br><sub>Slide Sorter with each slide's transition</sub></td>
+    <td width="50%"><img alt="DeckCraft in dark mode showing a chart slide" src="docs/images/dark-mode.png"><br><sub>Dark mode, with a native chart</sub></td>
+  </tr>
+</table>
+
+<p align="center">
+  <img alt="All eight slides of the Northern Lights sample deck" src="docs/images/sample-deck.png" width="900"><br>
+  <sub>The built-in sample deck, rendered by <code>deckcraft-cli render --sample --all</code></sub>
+</p>
 
 ## Getting started
 
@@ -88,12 +115,15 @@ same verbs:
 deckcraft-cli commands format.          # list commands
 deckcraft-cli run --sample --cmd 'slide.new={"layout":"titleOnly","title":"Hello"}' --save hello.deckcraft
 deckcraft-cli mcp                       # MCP server over stdio (headless)
-deckcraft-cli mcp --connect 7979        # drive the running app (deckcraft --control 7979)
+deckcraft-cli mcp --connect 7990        # drive the running app (deckcraft --control 7990)
 ```
 
 ## Roadmap
 
-See [ROADMAP.md](ROADMAP.md) for milestones, parity estimates and what's next.
+DeckCraft covers about **79% of PowerPoint's features by breadth** (93% of the core ones) and is
+roughly **80% of the way to a first alpha**. See [ROADMAP.md](ROADMAP.md) for the alpha checklist,
+parity estimates and what's next, and [docs/parity.md](docs/parity.md) for the feature-by-feature
+scorecard.
 
 ## The Crafting Apps