# Cicero's Hoard

## Interactive Routes

`deck_navigation` configures stable slide links, external URLs and next/previous/return actions on ordinary objects.
The editor offers the same destination selector. HTML and live sessions restore nested branch origins and click stages;
native PPTX uses editable slide relationships and last-slide-viewed return. [Contracts](docs/INTERACTIVE_NAVIGATION.md).

## Motion, Media And Linked Data

Use `deck_transitions` for common screen/native transitions, stable-object morph and per-slide overrides.
Use `media_import` and `media_get` for local or HTTP(S) audio/video, then add typed media blocks.
`deck_media_control` operates playback on the current live slide.
`dataset_link`, `dataset_links`, `dataset_bind` and `dataset_link_control` provide durable automatic local/URL
data refresh, immutable snapshots, typed visual recipes and last-good recovery. The editor exposes the same features.
The public catalogue now contains 67 tools. See [live media](docs/LIVE_MEDIA.md) and [advanced authoring](docs/ADVANCED_AUTHORING.md) for contracts and format differences.

`deck_design` runs a model-driven create/render/correct loop using the configured global model, with real image content in vision mode. External image feedback is bound to a source revision, variant and PNG hash; runs support resumption, cancellation and selective undo.
`scene_model_import` packages local GLB/glTF/ZIP resources offline, retaining textures, materials, lights and clips.
`deck_benchmark` compares complete independently authored PPTX workflows using a common native rasterizer and a fixed blind rubric. Failures, ties and regressions remain in the report; selected cases cannot establish universal superiority.

A local workspace that turns a brief and source documents into an editable presentation. You give it an objective,
an audience and the material; it proposes an outline, writes the slides with speaker notes, lets you review and
approve each slide one by one, applies a theme and exports the result. It is meant for a person and for an assistant
working together: everything is available as a REST API for the bundled UI and as MCP tools, built from the same
code, so the two cannot disagree.

## What it does

- **Your PPTX templates**: upload a reference deck on the Theme tab, or use `template_inspect` and
  `deck_template` over MCP. The editable PPTX keeps its dimensions, masters, layouts, backgrounds, logos
  and fonts. A saved snapshot survives changes to the original file. Notes and charts come from the new deck.
  Layout-to-source-slide bindings let an assistant choose precise title/body slots for unusual templates.

- **Decks**: title, brief, audience, tone, language (Spanish or English), number of slides (3 to 40) and theme.
  The status is derived, never typed: `draft` (nothing yet), `outline` (an outline exists), `review` (slides exist,
  some not approved), `ready` (every slide approved).
- **Sources**: paste text or add a `.txt`, `.md`, `.pdf`, `.docx` or `.pptx` file (text only; a scanned PDF is read by
  the family document service's OCR when that app is running). Sources are numbered and each slide can cite the sources it draws on.
- **Outline**: generated by the configured family model from the brief and numbered source excerpts, or written by hand.
  Each item has a title, a purpose, a few points and an optional layout hint.
- **Slides**: fifteen layouts including evidence, comparison and freeform composition, built from text,
  image, chart, diagram, metric, table and timeline blocks. Every slide has speaker notes.
- **Per-slide review**: approve or unapprove a slide, regenerate it with feedback, edit it by hand. Every change
  creates a revision; reverting restores an old revision as a new one. Generating slides again keeps approved slides
  and rewrites drafts.
- **No invented numbers**: the model may only use figures that appear in the sources. A chart is kept only when all
  its values appear in the sources, and `deck_check` lists every figure on a slide that no source contains. Number
  formats are compared across notations (`1.234`, `1,234`, `1.234,5`, `1,5`).
- **Automatic fitting**: text is measured and the font is stepped down until it fits, in the preview, the HTML and
  the PPTX alike (the three are drawn from one geometry). Text that cannot fit even at the smallest size is reported
  by the check instead of being clipped silently.
- **Themes**: seven built-in themes (`claro`, `oscuro`, `editorial`, `carmesi`, `pizarra`, `tecnico`, `oceano`), all
  with a contrast of at least 4.5:1 for text, muted text and accents. Fonts are ones present on Windows.
  A design system from the family design-system app can become an eighth, custom theme (`theme_from_tokens`, or the
  "Theme from a design system" picker in the theme screen): its colours, fonts and corner radius are mapped, colours
  that would not read are pulled until they reach 4.5:1 (the changes are listed), and a font that is not on Windows is
  replaced by the closest one that is. Cards in a theme with a radius are drawn with rounded corners in the preview,
  the HTML and the PPTX.
- **Exports**:
  - PPTX with real text boxes, bullet paragraphs, speaker notes and native charts (editable in the office suite),
    16:9 by default, or the attached template's size.
  - PDF, one page per slide, rendered by a local Chromium.
  - HTML, one self-contained file (styles, script and images inline) with arrow-key navigation. Speaker notes are
    left out on purpose because the file is meant to be shared.
  - Markdown, slides separated by `---`, notes as comments, charts as tables.
- **Images**: upload your own, or ask the family's image studio (Prospero's Hoard) for a picture per slide. The
  studio is optional.
- **Works without a model**: when no model is reachable, the outline and the slides are built from the sources by
  fixed rules and the result says `"generator": "fallback"`. Regenerating one slide with feedback needs a model and
  says so instead of pretending.

## Visual workbench for agents

`visual_catalog` exposes versioned schemas for 14 chart types, diagrams, metrics and tables. `slide_visual_update`
replaces or appends one block while preserving other blocks, citations and notes; use `expected_revision` to
detect concurrent edits. `slide_variants` compares three compositions without changing content. `deck_scene`
reports object geometry, font sizes and click stages. `deck_present` returns the local animated presentation URL.
These use the same implementations as ordinary slide editing and export, and are available through the MCP catalogue.
See [the agent workflow](docs/AGENT_VISUALS.md) and the portable `agent-skill/SKILL.md` entrypoint.
`npm run build` packages the specialist runtimes inside the Python distribution; advanced rendering needs Node 22.13+,
but not a separate dependency install at runtime. `scripts/visual-gallery.py --output-dir <folder>` creates a
fictional-data capability gallery and, when available, native rendering evidence.

Charts support numeric X coordinates, gaps, colors, highlighted categories, units, annotations, reference lines,
and interval bounds. The engines are ECharts for chart rendering, ELK for diagram placement, and reveal.js for
local presentation playback. PPTX keeps native charts or editable evidence objects. Interval charts use filled
regions in the browser and central/lower/upper curves in PPTX. Heatmaps export as colored tables; funnels as stage
objects. Diagram nodes, connections, metric text and tables remain editable. Sources remain the authority for values.

Use `build`, `effect` and `duration_ms` on blocks for click stages. Diagram `effect: stages` builds nodes in order.
The browser and standalone HTML retain individual objects, including with attached templates. The exported PPTX
carries native slide animations and transitions written as OOXML, with no office engine needed:
`deck_animations` (or `GET|PUT|DELETE /api/decks/{id}/animations`, `.../animations/preview`, `/api/animations/catalogue`)
sets `mode` -- `builds` (only the click stages, the default), `auto` (cover zoom, title fade, chart and table wipe,
picture zoom, cards and text fly in, then the click stages), `mixed`, `none` or any of the 203 native effects --
`trigger` (after-previous or on-click), `duration`, `transition` (none or any of 48, Morph included) and
`transition_duration`, deck-wide or per slide. Footers and background shapes never animate. The animation and
transition XML comes from PPT Master (MIT, vendored in `cicero_hoard/vendor/ppt_master` with its licence) and every
export is read back with its validators. In the app, the Export tab sets the presentation-wide motion and the transitions in
its transitions panel, gives each slide its own animation in «Animations per slide» and lists what the next PPTX will
carry per slide with Check.

Before exporting, `deck_visual_review` (`POST /api/decks/{id}/visual-review`, PNGs at
`/api/decks/{id}/visual-review/slide-NN.png`) renders every slide in the browser and measures what was laid out: objects
off the slide, text whose lines leave their box, content objects covering each other, text contrast against what is really
behind it (4.5:1, 3:1 for large text), pictures that do not load, and a missing title, chart or picture for the layout.
Each finding says its fix; `fix: true` applies the one automatic fix the rules allow (minimum font size on the slides
whose text overflows) and reviews again. PDF represents the complete static state. The user can share
their local presentation window remotely; no publication is necessary.
A text box that starts on the slide and only runs past the bottom grew with its text, so it counts as overflow. In the
app, the Review tab runs the visual review, shows the capture of each flagged slide and offers the automatic fix.

## Data And Live Presentation

- `dataset_import`: immutable CSV/TSV/XLSX sources, worksheets and explicit decimal profiles.
- `dataset_get`: paginated rows, missing/numeric profiles and import warnings.
- `dataset_transform`: reproducible filters, grouping, aggregates and mixed-type sorting.
- `dataset_visual`: typed chart/table mapping, preserving missing observations and source IDs.
- `deck_live_start`: separate presenter and audience URLs, support slides and a target duration.
- `deck_live_state`: audience-safe navigation and timer state, without speaker notes.
- `deck_live_control`: stages, slide jumps, blackout, timer and main-talk boundary.

The editor includes data import/mapping, editable staged timelines, normalized `freeform`
composition and contain/cover image crop focus. Live sessions remain in local server memory;
restart a session after deck edits. Offline HTML remains independent of live sessions.
See [data and presentation workflow](docs/DATA_PRESENTATION.md) and
[capability comparison](docs/CAPABILITY_MATRIX.md) for tested behavior and remaining gaps.

## Responsible use

- **Figures.** A generated deck is a draft. The number check finds figures that are not in the sources; it cannot
  tell whether a source is right. Read the notes and the figures before presenting.
- **Sources stay local.** Documents are read on this computer. Only short numbered excerpts are sent to the model,
  through Hoard Link, to whatever backend you configured (a local one by default).
- **Local files.** Adding a file by path only accepts document types (`.txt`, `.md`, `.pdf`, `.docx`, `.pptx`) and can
  be limited to folders with `CICERO_FILE_ROOTS`.
- **Quotes.** A quote block should reproduce a quote that appears in a source. The check does not verify quotations.
- **Deletes** (a deck, a slide, a source) need an explicit confirmation, also over MCP.

## Install

Requirements: Python 3.11+ (Windows target 3.13), Node.js 22+ only to rebuild the client.

```bash
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt
python -m playwright install chromium     # only for the PDF export
python -m cicero_hoard            # http://127.0.0.1:5194
```

The built client is committed under `cicero_hoard/static`, so `npm` is only needed to change the UI (`npm install`,
`npm run build`). During UI work `python scripts/dev.py` starts the API and the Vite dev server together, and
`python scripts/launch.py` starts the app and opens it in the browser.

| variable | default | meaning |
| --- | --- | --- |
| `CICERO_PORT` / `PORT` | `5194` | port; with `PORT_STRICT=1` the app fails instead of moving to another port |
| `CICERO_DATA_DIR` | `./data` | database, `assets/`, `exports/`, `mcp-token`, `url`, `backend.json` |
| `CICERO_ALLOWED_HOSTS` | local only | extra host names the server accepts |
| `CICERO_FILE_ROOTS` | empty | folders (separated by the OS path separator) that local-file sources may come from |
| `CICERO_IMAGE_STUDIO_URL` | discovered | address of the image studio, to skip discovery |
| `CICERO_IMAGE_TIMEOUT` | `600` | seconds to wait for one render in the image studio (10-86400) |
| `CICERO_PARALLEL_SLIDES` | `3` | slides written at the same time by the model after the first one (1-8); a local server with several slots finishes a deck sooner |
| `CICERO_SLIDE_EFFORT` | `low` | reasoning effort asked of the model for each slide and rewrite (`off`, `low`, `medium`, `high`); the outline always asks `medium` |

The model comes from Hoard Link (`data/backend.json` or the Hoard environment variables); the model name can also be
chosen in Settings.

## Shared Hoard Link code

The plumbing is the shared commons of Hoard Link (vendored in `cicero_hoard/hoard_link/`): the launcher (one instance per
port, logs in `data/logs/`), the request guard, the error envelope, the stable `mcp-token`, the SQLite layer, ULID ids
(decks made with older versions keep their 12-character ids), the agent catalogue with the 20 KB result cap, the Word and
text readers with the zip-bomb guard, the chunker, the browser launcher for the PDF export and the MCP bridge.

## MCP

`mcp_server.py` is the shared Hoard Link stdio bridge. It never opens the database: it reads `data/mcp-token`, fetches the tool list
from the running app and forwards each call. When the app is not running it starts it (`CICERO_BRIDGE_AUTOSTART=0`
turns that off; the slow tools publish how long the bridge waits for them). Register it in any MCP client:

```json
{"mcpServers": {"cicero": {"command": "python", "args": ["/path/to/cicero/mcp_server.py"],
  "env": {"CICERO_URL": "http://127.0.0.1:5194", "CICERO_TOKEN_FILE": "/path/to/cicero/data/mcp-token"}}}}
```

`faustus-plugin.json` describes the same setup for the Faustus workspace.

### Tools

| tool | what it does |
| --- | --- |
| `cicero_status` | health, counts, model and PDF availability |
| `deck_create`, `deck_list`, `deck_get`, `deck_update`, `deck_delete` | decks; `deck_get` returns a summary unless `detail=full`; delete needs `confirm=true` |
| `source_add`, `source_list`, `source_get`, `source_remove` | sources from pasted text or a local file; paged reading; removal needs `confirm=true` |
| `outline_generate`, `outline_update` | generate the outline or replace it by hand |
| `slides_generate` | write the slides from the outline; approved slides are kept |
| `slide_get`, `slide_update`, `slide_add`, `slide_delete`, `slides_reorder` | read, edit, add, remove (`confirm=true`) and reorder slides |
| `slide_regenerate` | rewrite one slide following feedback (needs a model) |
| `slide_approve` | approve or unapprove a slide |
| `slide_revert` | list a slide's revisions, or restore one as a new revision |
| `deck_check` | review: overflow, figures not in the sources, missing notes, unapproved slides |
| `deck_theme` | list the themes (built-in and made from design systems) or apply one |
| `template_inspect`, `deck_template` | inspect a local PPTX, attach it with optional per-layout bindings, read the attachment, or detach it with `clear=true` |
| `theme_from_tokens` | make a theme from a design system (`tokens_id`, `mode` light or dark, optional `deck_id` to apply it); without `tokens_id` it lists the design systems |
| `deck_export` | export to `pptx`, `pdf`, `html` or `md`; returns the file path and the download URL |
| `deck_animations` | native animations and transitions of the exported PPTX: get, set, reset, preview, list |
| `deck_visual_review` | render every slide in the browser, keep a PNG of each and check hard rules before exporting; `fix` applies the minimum font size where text overflows |
| `deck_visual_lab` | create content-preserving composition variants, render native MCP images, compare measured constraints, correct custom frames, apply and benchmark against an explicit baseline |
| `deck_poll` | create, vote, open/close, reset and recover local audience poll rounds; obtain a slide block |
| `slide_collaborate` | merge persistent Yjs text, stable objects, nested fields and identity order; publish local presence |
| `dataset_connect` | connect a local SQL read query or optional spreadsheet adapter to the scheduled immutable snapshot worker |
| `slide_image` | generate a picture for a slide with the image studio |
| `asset_import` | copy an existing local PNG/JPEG/WEBP figure; use its returned asset ID in an image block; repeated imports reuse the image within this deck |
| `slides_add` | atomic draft batches with a reusable batch key; retrying identical content returns the original IDs |
| `slide_edit_text` | edit one title, subtitle, note or bullet while preserving the other blocks |
| `slide_set_image` | add or replace one imported figure or its caption; preserve all other blocks and notes; identical retries keep the revision |
| `deck_rehearsal` | plan time slots and estimate speaking duration from notes; no claim of measured rehearsal |

Results sent to an assistant are trimmed to about 20 KB with a hint to narrow the request. Approving a slide is the
person's decision: an assistant should not approve slides on its own.

### Agent sessions, reasons and undo

Every write an assistant makes through the MCP bridge (or `POST /api/agent/call`) is accountable. The web interface is not an agent and
is exempt from all of this.

- **Who.** The bridge sends the agent name and session it reads from `HOARD_AGENT_ID` / `HOARD_AGENT_SESSION` (headers `X-Agent-Id` /
  `X-Agent-Session`; a body `caller` / `_session` also works). A scoped token fixes the agent name whatever the headers say.
- **Why.** Every tool that is not read-only needs a `reason` argument of 3 to 300 characters (`400 reason_required` with a hint
  otherwise). Reading tools need none.
- **What.** Each write is a line of `data/agent_journal.jsonl` (tool, agent, session, reason, a digest and a masked summary of the
  arguments, the ids it returned, time, ok or error); the file rotates at about 5 MB. `GET /api/agent/journal?session=&agent=&limit=`
  (Bearer token) reads it, and the event `agent.write` goes to the family.
- **Undo a whole session.** `POST /api/agent/undo {"session": "...", "dry_run": true}` says what would be taken back; with
  `{"confirm": true, "reason": "..."}` it does it, newest write first. It reverses presentation creation, presentation fields and
  theme, the outline, adding and removing sources, every slide edit (text, image, regenerate, approve, revert), adding, deleting and
  reordering slides, `slides_add` batches (their receipt too, so the same batch key can be used again) and `slides_generate`. It reports
  what it could not undo: tools without a way back (`deck_delete`, `deck_export`, `asset_import`, `slide_image`, `deck_template`,
  `theme_from_tokens`, the VectorCraft and DesignCraft tools) and anything changed afterwards. It never touches another session's writes:
  if another session, or the person in the interface, edited the same slide later, that write is reported as a conflict and left as it is.
- **Profiles.** `python -m hoard_link.tokens mint --app-data-dir data --agent drafter --profile drafts` prints a token (shown once;
  the file `data/agent_tokens.json` keeps only hashes). Profiles: `read_only` (reading tools), `drafts` (also the tools that create or edit
  drafts: `deck_create`, `deck_update`, `deck_theme`, `source_add`, `slide_add`, `slides_add`, `slide_update`, `slide_edit_text`,
  `slide_set_image`, `slide_regenerate`, `slide_image`, `asset_import`, `slides_reorder`, `theme_from_tokens`; never deleting, approving,
  exporting or generating a whole deck) and `all`. A blocked call answers `403 profile_forbidden`. The Hub tab "Sesiones de agente" shows the sessions
  of every app and undoes them, and mints and revokes tokens.

## Family

Cicero works alone. Decks are addressable as `hoard://cicero/deck/<id>`. It emits `cicero.deck.created`,
`cicero.deck.deleted`, `cicero.outline.generated`, `cicero.slides.generated` and `cicero.deck.exported` on the hub
bus (ids and short titles only). Themes made from a design system emit `cicero.theme.created` and are linked to the
design system (`hoard://cicero/theme/<id>` derived from `hoard://vitruvius/tokens/<id>`); the design system is read
through the hub (`tokens_list` and `tokens_get` of the design-system app), so the hub and that app must be running,
and asking for the same design system in the same state again gives back the same theme. Pictures come from Prospero's Hoard when it runs: the studio is looked up through
`CICERO_IMAGE_STUDIO_URL`, the hub's app list, or its default local port (8815), and is used through its local REST
API, which needs no token. Slide pictures go into a studio project named "Cicero's Hoard slides" (reused, or created
the first time); each request submits one 16:9 render, waits for it and stores the resulting image in the deck. Only
loopback addresses are ever contacted.

## Development

```bash
pip install -r requirements.txt
python -m pytest -q      # no network: the model and the image studio are faked
```

The PDF tests run only when a Chromium is available. Documentation of the HTTP API is in `docs/API.md`.

## A real run

On a Windows PC with a local 27B model served by llama.cpp: a seven-slide sales plan for a fictional shop, from a
brief and one pasted report. The outline took 155 s; with slides written one after another each took about 75 s, which
is why they are now written three at a time. The model used only the report's figures: a bar chart of the four
quarters, the customer figures in two columns, and, after the feedback "remove the gross-margin sentence, it is not in
the report; show the 70,000 EUR breakdown as a bar chart", a slide with that exact breakdown and without the sentence.
The check reported no unsourced figure. PPTX and PDF exports were opened: native charts, speaker notes, the theme's
fonts embedded in the PDF. The image studio drew a 16:9 picture for one slide in 79 s. An assistant connected over
MCP listed the decks, ran the check and exported the PDF in four rounds. Four faults found in that run are fixed and
covered by tests: theme fonts lost in the HTML, bare thousands on native charts, a bridge that called a running app
stopped when it could not read its token, and an image call to a tool the studio does not have.

## Limits

- With an attached template, preview and HTML place interactive objects over the source branding, whose
  background is rendered by an installed local office slide engine on Windows. PDF is the native PPTX
  rendering. HTML is self-contained with click stages. Without that engine, template PDF/HTML and preview report `pdf_unavailable`.
  A rendered preview is cached by deck state. `deck_check` then reports native text bounds that exceed
  their frames; a check before rendering reports that native review is still needed.
  Source animations and transitions are not copied; authored click stages are added. Automatic slot selection is a starting point; use the
  inspected shape IDs and explicit bindings for complex reference decks.

Template bindings also accept `title_frame`, `subtitle_frame` (CSS pixel coordinates),
`title_font_points` and `chart_font_points`. These controls retain the original master and branding while
fitting longer titles and setting readable chart labels. Explicit line breaks count during text fitting.

- A picture takes as long as the studio needs to render it; the request waits up to `CICERO_IMAGE_TIMEOUT` seconds.
  If that time passes the render keeps running in the studio and is not submitted again. Only one image is taken
  per request, from a studio on this machine; images over 15 MB or not PNG, JPEG or WEBP are refused.
- The PDF export needs Chromium (`python -m playwright install chromium`, or a system Edge or Chrome). Without it,
  exporting `pdf` fails with the code `pdf_unavailable` and the other formats keep working.
- Fonts are those of the theme; a machine without them substitutes another and lines may wrap differently. The
  fitting leaves a small safety margin for that.
- Text fitting is an estimate from character widths, not a font-metrics measurement.
- Charts: bar, line and pie; one or several series (a pie uses the first).
- Speaker notes are not included in the HTML export.
- Scanned PDFs have no text and are refused with a message.

## License

See `LICENSE`.

## Draft batches for large presentations

`slides_add(deck_id, batch_key, slides)` appends several draft slides, with their notes, charts and source IDs, in one transaction. Retry the same key and content after an interrupted response to recover the original slide IDs. A reused key with different content is rejected. Existing slides and approvals are preserved; the batch does not approve slides. The whole batch rolls back if any slide fails validation.

When a slide cites specific sources, `deck_check` checks its figures against those sources. Example numbers in another source or in the brief do not count as evidence for that slide. This checks numeric presence, not the meaning of a claim; factual review remains necessary.

`slide_edit_text` changes one title, subtitle, note or bullet item without rebuilding the other blocks. Editing a bullet uses zero-based block/item indices; charts and other bullets remain intact, and the edit creates a normal draft revision.

For an existing figure, use `asset_import`, then `slide_set_image(deck_id, slide_id, asset_id, caption?)`. The first image is selected by default; `image_index` counts only image blocks, and an index equal to the image count appends. Omitted captions stay unchanged; explicit `null` clears one. Other blocks, notes, title, sources and layout are preserved. An identical retry creates no extra image or revision. Changes create draft revisions and can be undone with `slide_revert`. Optional `expected_revision` detects a concurrent edit (409 `conflict`); read the slide again before retrying.

### Timed rehearsal planning

`deck_rehearsal(deck_id, duration_minutes, words_per_minute, pause_seconds, main_slides)` creates a per-slide schedule from speaker notes. `main_slides` selects the leading slides of the talk; the rest are listed as support. The slots sum exactly to the target, while a separate estimate reports whether the notes fit at the chosen pace, including pauses. Missing notes leave the total estimate unknown. Planning never claims an oral rehearsal has been measured and does not modify notes, revisions or approvals.

### Local VectorCraft and DesignCraft

Set `CICERO_VECTORCRAFT_CLI` and `CICERO_DESIGNCRAFT_CLI` to the installed portable executable paths. Cicero starts each app as a local headless MCP server and places its app data under Cicero's own `data/craft-runs` folder. The current real artifact tests use the verified VectorCraft 0.3.1 and DesignCraft 0.2.1 portable builds; other compatible releases are discovered at runtime. No account or remote service is required.

`craft_discover(app)` returns the full native MCP tool list and input schemas. `craft_call(app, calls)` dispatches native tools by their original names and arguments, in order, and returns the complete text or image content. This keeps the apps' existing MCP surface available through Cicero.

Tool names: `craft_discover`, `craft_call`, `vector_figure_create`, and `deck_handout_designcraft`. Discovery includes native tools, prompts, resources, and resource templates when the installed app exposes them. Dispatch accepts `kind: "tool"`, `"prompt"`, or `"resource"`; a server which does not implement an optional MCP method reports an empty inventory for that method.

`vector_figure_create(deck_id, slide_id, title, shape, fill, stroke, replace_block_index?)` creates an editable VectorCraft document, SVG, and PNG preview, stores a managed copy, and adds it to the slide as a figure. To correct an existing figure, pass its returned `block_index` as `replace_block_index`; the other blocks, title and notes remain intact. PPTX contains the SVG picture and a PNG compatibility image. The generated `.vectorcraft`, `.svg`, and `.png` files live in the deck's assets; source files are not edited.

As an alternative to environment variables, store executable paths in the local, untracked `data/craft-engines.json`: `{"vectorcraft":{"executable":"..."},"designcraft":{"executable":"..."}}`. Each `craft_call` batch opens a fresh native process. Keep dependent commands in one batch and save the native document before returning; selection and undo history do not persist between batches. Gutenberg provides persistent editorial sessions for longer publishing workflows.

The vector source is editable in VectorCraft. PPTX embeds the SVG as a picture with PNG fallback, not native shape geometry of a presentation file; the tool reports this distinction. Handouts embed placed raster frames (including PNG fallbacks for SVG assets), while chart blocks contribute text values rather than native charts.

`deck_handout_designcraft(deck_id)` creates one editable A4 DesignCraft page per slide with separate heading and body frames, then renders a PNG preview for every page. Text, speaker notes and image captions are carried over; charts contribute their values. Raster images become placed graphic frames, and VectorCraft SVG assets use their stored PNG fallback in the handout. The native project is copied and reopened before rendering, so the downloadable `.designcraft` is verified to retain its embedded images without Cicero asset links. Text that overflows fails with a clear error instead of returning an incomplete handout. The `.designcraft` file and each PNG are downloadable from the deck's export list. SVG source remains in Cicero's asset and presentation workflows; this handout does not claim editable vector content, PDF export or branded layout parity with the source deck.

## Shared Faustus assistant

The Faustus button mounts the common panel served by the configured Faustus service. Conversation storage, model choice, streaming, recovery and project memory live in Faustus. Cicero supplies its data-space identity, deck, selected slide/revision, editor selection and unsaved slide draft. Its 67 native domain tools and slide revisions remain available. Existing decks, notes, sources and manual unsaved edits are preserved. Configure CICERO_FAUSTUS_URL or the existing backend.json Faustus connection. This requires a reachable Faustus service with the shared copilot contract; no private chat/model fallback is created.