# UnaSynQ Story Kit, one page guide

Build a full UnaSynQ story in PowerPoint, then upload it. The importer turns
your slides into sections, menus, buttons and narration automatically.

## Workflow

1. Download `UnaSynQ_Story_Kit.pptx`.
2. Duplicate the sample slides for every part of your story. Keep one Home
   Menu slide. Add one Section Page per chapter, and a Deep Dive Page for any
   section that deserves extra detail.
3. Replace the sample text and pictures with your own. Move and resize boxes
   freely, the layout carries over.
4. In the admin panel open Create, then click "Import from PowerPoint". Your
   deck becomes a draft story.
5. Review the draft in the story editor, then press Build Timeline.

## The convention

- **Slide roles.** The small caps line in the top corner names the role:
  HOME MENU (via the footer tag), SECTION PAGE, DEEP DIVE PAGE.
- **Titles.** The first normal text box on a slide is its title. It becomes
  the section title and the menu button label.
- **Footer tags.** The small line at the bottom identifies each slide:
  `story: your_story` plus one of `page: home_menu`,
  `section: <Section Title>`, or `deep_dive: <Deep Dive Title>`.
- **Audio narrative object.** The text box under this heading is spoken, not
  shown. It becomes narration audio with Speak already on.
- **Visible text.** Everything else (bullets, subtitles) is shown on screen
  exactly where you placed it.
- **Pictures.** Keep their position and size. Replace the gray placeholders
  with real photos.
- **Buttons are automatic.** The home menu gets one button per section.
  Every section gets Back to Menu and Next Section, plus Deep Dive when a
  deep dive slide points at it. You do not draw buttons.
- **Leave room for the buttons.** The importer drops menus into empty space
  near the bottom of the slide (right side first, then left, then centre).
  Keep at least one lower corner of the home slide free of text and
  pictures. If every corner is full the import still works, but the menu
  will sit on top of other content until you drag it in the editor.
- **Deep dive linking.** Put `Return target: <Section Title>` under the deep
  dive title. The dive returns there automatically when it finishes.
- **END BEHAVIOR.** A line on a section slide controls what happens when the
  section ends: `END BEHAVIOR: hold` (default, playback waits with the
  buttons available), `END BEHAVIOR: continue` (flow into the next section),
  or `END BEHAVIOR: return to <section title or menu>`.
- **Author notes.** Any SHORT ALL CAPS line, and everything below the
  PAGE BUTTONS, RETURN BEHAVIOR or MAIN MENU SECTIONS headers, is guidance
  for you and is never imported.
- **Further pages of one section.** A slide tagged `continues: <Section
  Title>` becomes another page of the section with that title (a page
  break inside the section) instead of a section of its own.

## Decks exported from the story editor

The story editor's Export button can write a PowerPoint deck in this same
convention (Format: PowerPoint). Every page of the story becomes a slide:
the stage is the dark band across the slide, objects sit on it at their
authored positions, spoken narration appears in an "Audio narrative
object" box below the band and in the speaker notes. The footer tag line
carries an extra `unasynq:` entry (the experience and section ids plus the
stage position) so the importer maps every object back to exactly where it
was. Edit the deck, then import it through Create > Import from PowerPoint.
When the deck came from one of your own experiences you are asked whether
to update that experience in place (same links, media and settings, then
Build the timeline to publish) or to create a separate new draft.

The spoken script under each slide flows in up to four columns. A very
long script shows its opening and says "continues in the speaker notes";
the notes always hold the full text and the re-import uses it.

The Include setting picks what goes into the deck:

- **Everything (re-imports fully)**, the default. Buttons and menus,
  callouts with their leader line and target dot, inputs and forms,
  shapes, tables and placeholders for videos and maps are all drawn as
  ordinary PowerPoint objects, and the story's full data (targets, timing,
  animations, variables, styling, section and story settings) is kept in
  each slide's speaker notes after the line "unasynq data". In PowerPoint
  you can move, resize, relabel or delete any object and replace pictures.
  Re-importing brings everything back: moved objects at their new place,
  edited labels and text, deleted objects gone, and everything you did not
  touch exactly as it was. Two rules: keep the notes below that "unasynq
  data" line (delete them and the slide falls back to the plain import),
  and leave object names alone in the Selection Pane (they read
  `unasynq:block=...` and are how the importer recognises each object).
  Colours and other styling changed in PowerPoint are not read back.
- **Text and pictures only** is the plain Story Kit deck described above.
  Buttons, callouts, forms and the rest are left out and listed after the
  export; a re-import regenerates the standard home menu, Back and Next
  buttons.

Portrait layouts are not exported; the deck is landscape. Tick "Page
pictures instead of editable objects" for a deck meant to be viewed rather
than edited: each slide then shows a picture of the page exactly as the
player renders it.

"Put in the file" lists the kinds of objects the export can carry: titles,
text shown on screen, spoken narration, pictures and videos, menus and
buttons, callouts, forms and inputs, shapes. Everything is ticked by
default. Untick a kind to leave it out of the file; it will not come back
on a re-import either, which makes this the quick way to produce a clean
handout deck without buttons or forms. The choice is remembered in your
browser. The same row applies to PDF and Word exports for the text kinds;
their page pictures always show the page as the player renders it.

After any export (PDF, Word or PowerPoint) the file can be downloaded or
emailed straight from the dialog: enter an address (yours is filled in) and
press Send. The email carries a download link that stays valid for seven
days, and small files (up to 4 MB) are attached as well. Large decks are
never attached, because mail servers silently drop oversized attachments.
The same link is offered in the dialog with a Copy button, so it can be
shared any other way. Emailing needs the server's mail setup, the same one
used for form submissions.

## Limits of the current importer

- PowerPoint animations, transitions, SmartArt and charts are not imported.
  Entry animations and Ken Burns effects can be added in the story editor.
- Fonts are not carried over, size, bold and colour are.
- Embedded video is not imported yet.
- Slide backgrounds import only when they are pictures.

## Spoken pacing

Inside any narration text, a blank line between paragraphs adds a short
spoken pause (about 0.7 seconds). For a longer breath, write a marker like
`[pause 2]` where you want it, up to 3 seconds. Markers never appear on
screen and are kept in place by translation.

Narration audio is generated when you press Build Timeline, after a cost
confirmation. Nothing is spent at import time.