Dialog-IF · hlship · Aug 29, 2026 · Aug 29, 2026 · Aug 29, 2026 · Aug 29, 2026
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,60 @@
+# Dialog IDE manual (Antora source)
+
+This directory is a self-contained [Antora](https://antora.org) documentation component for the
+Dialog IDE VS Code extension. It is authored here, in the extension's own repository, so it stays in
+sync with the code, and is consumed by the main Dialog website's Antora build as an additional
+content source.
+
+## Layout
+
+```
+docs/
+  antora.yml                     component descriptor (name: dialog-ide, versionless)
+  modules/ROOT/
+    nav.adoc                     the manual's table of contents
+    pages/*.adoc                 one file per chapter
+    partials/*.adoc              fragments reused across chapters
+    images/                      screenshots; MANIFEST.adoc is the shot-list
+```
+
+## Wiring into the Dialog website playbook
+
+In the Dialog site's `antora-playbook.yml`, add this repo under `content.sources` with `start_path`
+set to `docs`:
+
+```yaml
+content:
+  sources:
+    # ...existing Dialog sources...
+    - url: https://github.com/hlship/dialog-ide.git
+      branches: [main]        # or a release branch/tag once one exists
+      start_path: docs
+```
+
+The component id is `dialog-ide`; cross-links from elsewhere on the site use
+`xref:dialog-ide::index.adoc[]` (and so on).
+
+## Local preview
+
+There is no committed playbook for local builds. To preview:
+
+1. `npm i -g @antora/cli@3 @antora/site-generator@3`
+2. Create a throwaway `local-playbook.yml`:
+   ```yaml
+   site:
+     title: Dialog IDE (local preview)
+     start_page: dialog-ide::index.adoc
+   content:
+     sources:
+       - url: .
+         start_path: docs
+   ui:
+     bundle:
+       url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+       snapshot: true
+   output:
+     dir: ./docs/_preview
+   ```
+3. `antora --fetch local-playbook.yml` and open `docs/_preview/index.html`.
+
+`docs/_preview/` and any local playbook are build artifacts — do not commit them.
diff --git a/docs/antora.yml b/docs/antora.yml
@@ -0,0 +1,11 @@
+name: dialog-ide
+title: Dialog IDE
+version: ~
+start_page: ROOT:index.adoc
+nav:
+  - modules/ROOT/nav.adoc
+asciidoc:
+  attributes:
+    experimental: ''
+    idprefix: ''
+    idseparator: '-'
diff --git a/docs/modules/ROOT/images/add-feelie-flow.png b/docs/modules/ROOT/images/add-feelie-flow.png
diff --git a/docs/modules/ROOT/images/add-file-picker.png b/docs/modules/ROOT/images/add-file-picker.png
diff --git a/docs/modules/ROOT/images/command-palette.png b/docs/modules/ROOT/images/command-palette.png
diff --git a/docs/modules/ROOT/images/configure-exports-wizard.png b/docs/modules/ROOT/images/configure-exports-wizard.png
diff --git a/docs/modules/ROOT/images/dialog-json-with-categories.png b/docs/modules/ROOT/images/dialog-json-with-categories.png
diff --git a/docs/modules/ROOT/images/diff-rendering.png b/docs/modules/ROOT/images/diff-rendering.png
diff --git a/docs/modules/ROOT/images/dynamic-state-chips.png b/docs/modules/ROOT/images/dynamic-state-chips.png
diff --git a/docs/modules/ROOT/images/export-success-toast.png b/docs/modules/ROOT/images/export-success-toast.png
diff --git a/docs/modules/ROOT/images/extensions-view.png b/docs/modules/ROOT/images/extensions-view.png
diff --git a/docs/modules/ROOT/images/first-skein-session.png b/docs/modules/ROOT/images/first-skein-session.png
diff --git a/docs/modules/ROOT/images/generated-dialog-json.png b/docs/modules/ROOT/images/generated-dialog-json.png
diff --git a/docs/modules/ROOT/images/hero-skein-beside-editor.png b/docs/modules/ROOT/images/hero-skein-beside-editor.png
diff --git a/docs/modules/ROOT/images/init-command-palette.png b/docs/modules/ROOT/images/init-command-palette.png
diff --git a/docs/modules/ROOT/images/keystroke-input.png b/docs/modules/ROOT/images/keystroke-input.png
diff --git a/docs/modules/ROOT/images/knot-menu-open.png b/docs/modules/ROOT/images/knot-menu-open.png
diff --git a/docs/modules/ROOT/images/marketplace-extension-page.png b/docs/modules/ROOT/images/marketplace-extension-page.png
diff --git a/docs/modules/ROOT/images/navgraph-annotated-spine-vs-branches.png b/docs/modules/ROOT/images/navgraph-annotated-spine-vs-branches.png
diff --git a/docs/modules/ROOT/images/navgraph-closeup.png b/docs/modules/ROOT/images/navgraph-closeup.png
diff --git a/docs/modules/ROOT/images/replay-all-progress.png b/docs/modules/ROOT/images/replay-all-progress.png
diff --git a/docs/modules/ROOT/images/run-skein-picker.png b/docs/modules/ROOT/images/run-skein-picker.png
diff --git a/docs/modules/ROOT/images/scaffolded-explorer-tree.png b/docs/modules/ROOT/images/scaffolded-explorer-tree.png
diff --git a/docs/modules/ROOT/images/search-results.png b/docs/modules/ROOT/images/search-results.png
diff --git a/docs/modules/ROOT/images/skein-panel-annotated.png b/docs/modules/ROOT/images/skein-panel-annotated.png
diff --git a/docs/modules/ROOT/images/status-bar-item.png b/docs/modules/ROOT/images/status-bar-item.png
diff --git a/docs/modules/ROOT/images/trace-panel-with-source-preview.png b/docs/modules/ROOT/images/trace-panel-with-source-preview.png
diff --git a/docs/modules/ROOT/images/uncovered-source-badge-quickfix.png b/docs/modules/ROOT/images/uncovered-source-badge-quickfix.png
diff --git a/docs/modules/ROOT/images/vscode-download-page.png b/docs/modules/ROOT/images/vscode-download-page.png
diff --git a/docs/modules/ROOT/images/vscode-first-window.png b/docs/modules/ROOT/images/vscode-first-window.png
diff --git a/docs/modules/ROOT/images/web-export-in-browser.png b/docs/modules/ROOT/images/web-export-in-browser.png
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -0,0 +1,16 @@
+* xref:index.adoc[Introduction]
+* Getting set up
+** xref:installing-vscode.adoc[Installing Visual Studio Code]
+** xref:installing-the-extension.adoc[Installing the Dialog IDE Extension]
+** xref:initializing-a-project.adoc[Starting a New Project]
+** xref:project-sources.adoc[Organizing Your Sources]
+* The Skein
+** xref:skein-concepts.adoc[How the Skein Works]
+** xref:creating-and-using-a-skein.adoc[Creating a Skein and Touring the Panel]
+** xref:dynamic-state-and-trace.adoc[Dynamic State and Trace]
+** xref:multiple-skeins.adoc[When to Use More Than One Skein]
+* Shipping
+** xref:building-and-exporting.adoc[Building and Releasing Your Project]
+* Advanced
+** xref:command-line-dgbuild.adoc[Command-Line Testing with dgbuild]
+** xref:troubleshooting.adoc[Troubleshooting and Known Limitations]
diff --git a/docs/modules/ROOT/pages/building-and-exporting.adoc b/docs/modules/ROOT/pages/building-and-exporting.adoc
@@ -0,0 +1,107 @@
+= Building and Releasing Your Project
+:navtitle: Building and Releasing
+
+Building turns your source into a story file a player can run: a `.zblorb`, a bare `.z8`, or an
+AAmachine `.aastory`. Dialog IDE organises this around *named export configurations* stored in
+`dialog.json`, plus a separate command that wraps a build into a complete downloadable web page.
+
+== Export configurations
+
+Run *Dialog IDE: Configure Exports...*. It is a small wizard that maintains the `exports` array in
+`dialog.json`. Each configuration has:
+
+`name`:: What you call it in the picker.
+`format`:: `zblorb`, `z8`, or `aa`. The resulting files are `.zblorb`, `.z8`, and `.aastory`
+respectively.
+`includeDebug`:: Whether to compile the `debug` sources in. Usually *no* for a release build.
+`output`:: The path to write the story file to, relative to the project root.
+`dialogcOptions`:: Optional. Extra `dialogc` flags for this configuration alone.
+
+The same wizard also sets a project-wide *default* set of `dialogc` options, stored as the
+top-level `dialogcOptions` key. Any configuration without its own options uses these, and so does
+*Export Web Page*. A common use is raising limits — `--heap 2000 --aux 1000` — for a project that
+has outgrown the defaults.
+
+The wizard cannot yet edit an existing configuration in place; to change one, remove it and add it
+again.
+
+[NOTE]
+====
+Export configurations are just data in `dialog.json` — the `exports` array, plus the top-level
+`dialogcOptions`. You can edit them directly in the editor: change an `output` path, adjust the
+options, reorder the list. The wizard is a convenience, not the only way in.
+====
+
+image::configure-exports-wizard.png["the format QuickPick (zblorb / z8 / aa) in the wizard"]
+
+== Building a story file
+
+Run *Dialog IDE: Export Dialog Project...*, pick a configuration, and it compiles with `dialogc`.
+On success it offers to reveal the output file in Finder or File Explorer. A compilation error is
+reported with its `file:line`, so you can jump straight to it.
+
+The sources handed to the compiler are expanded using that configuration's `includeDebug` setting
+and its `format`, so a file named `something.zblorb.dg` is included in a `zblorb` build and left
+out of the others (see xref:project-sources.adoc[]).
+
+image::export-success-toast.png["the 'Exported ... to ...' notification with the Reveal button"]
+
+== Cover image
+
+If a file named `cover.png` exists at the project root, a `zblorb` build embeds it automatically —
+there is nothing to configure. *Initialize Dialog Project* seeds a placeholder `cover.png`; replace
+it with your own artwork. Unlike a feelie, a missing `cover.png` is simply skipped rather than
+treated as an error.
+
+== The downloadable web page
+
+Run *Dialog IDE: Export Web Page...*. It asks which export configuration should build the story
+file, then assembles a complete web page in `out/web/`, with a matching `.zip` in `out/`. The page
+includes:
+
+* the story file, compiled fresh with the chosen configuration's settings;
+* an in-browser player powered by https://github.com/dialog-if/aamachine[AAmachine];
+* the cover image, plus a generated thumbnail;
+* the project's feelies (below);
+* if `default.skein` contains a knot labelled `WALKTHROUGH`, a walkthrough transcript running from
+the root to that knot, with any command beginning with `*` omitted.
+
+The title, author, blurb, release number, and IFID shown on the page are read live from your
+project's own `(story $)` directives via `dgdebug`.
+
+This command needs `aambundle`, from AAmachine, in addition to `dgdebug` and `dialogc` — see
+xref:installing-the-extension.adoc[].
+
+image::web-export-in-browser.png["out/web/index.html open in a browser: cover, bibliography, Play button, feelie links"]
+
+== Feelies
+
+A *feelie* is any file linked from the exported web page. The tradition is a "how to play
+interactive fiction" PDF for newcomers, but it can be anything — a map, a manual, an in-world
+document. Feelies appear only in the web export; they are not part of a `.zblorb`.
+
+Feelies are stored in `dialog.json` as a `feelies` array, each entry a `path` (relative to the
+project root) and a `name` (the link text on the page). *Initialize Dialog Project* seeds two PDFs
+and wires them in.
+
+To add one, run *Dialog IDE: Add Feelie...* and choose a file, or right-click a file in the
+Explorer and choose *Dialog IDE: Add Feelie*; either way you are then asked for a display name.
+*Dialog IDE: Remove Feelie...* takes one out again. A configured feelie whose file is missing is a
+*hard error* when you export — fix the path in `dialog.json`, or remove the entry.
+
+image::add-feelie-flow.png["the Explorer right-click menu with 'Dialog IDE: Add Feelie' highlighted"]
+
+== Story metadata
+
+The project's bibliographic details live in your source as `(story $)` directives — `(story title
+$)`, `(story author $)`, `(story blurb $)`, `(story noun $)`, `(story release $)`, and `(story ifid
+$)`. *Initialize Dialog Project* writes a starter set into `main/meta.dg`, including a generated
+IFID, which the `zblorb` format requires.
+
+This metadata surfaces in the compiled story file's bibliographic record and, for the web export,
+in the page's title, author line, description, and its closing "created with Dialog, IFID ..."
+note.
+
+== What's next
+
+xref:command-line-dgbuild.adoc[] — running tests and skein checks from a terminal or CI.
diff --git a/docs/modules/ROOT/pages/command-line-dgbuild.adoc b/docs/modules/ROOT/pages/command-line-dgbuild.adoc
@@ -0,0 +1,107 @@
+= Command-Line Testing with dgbuild
+:navtitle: Command-Line Testing with dgbuild
+
+`dgbuild` runs the same project checks the extension does — unit tests, skein replay, source
+listing — from a terminal, with no editor involved. Its purpose is scripting and continuous
+integration: gating a merge on a green test run, or rebuilding a release automatically.
+
+== What it is, and installing it
+
+`dgbuild` is a command-line tool that ships *inside* the `dialog-ide` npm package. It is named to
+sit with the rest of the toolchain — `dgdebug`, `dialogc`, `aambundle` — rather than after the
+extension.
+
+Install it globally:
+
+[source,console]
+----
+npm install -g dialog-ide
+----
+
+or run it without installing:
+
+[source,console]
+----
+npx -p dialog-ide dgbuild <command>
+----
+
+[WARNING]
+====
+Do not run plain `npx dgbuild`. There is an unrelated, older package of that name on npm, and that
+is what plain `npx dgbuild` will fetch. Always go through `-p dialog-ide`.
+====
+
+The npm package contains no binaries. `dgbuild` needs the Dialog toolchain — at least `dgdebug` —
+on your `PATH`, or a `binDir` set in `dialog.json`. Run it from the project root, or point it
+elsewhere with `-p <dir>` / `--project <dir>`.
+
+== dgbuild test
+
+Runs the project's unit tests, by invoking `dgdebug --unit-test`, and exits with `dgdebug` 's own
+exit code. It exits non-zero on any test failure — and also if `dialog.json` declares no `test`
+sources at all, since having nothing to run is treated as a failure rather than a silent pass.
+
+`--no-debug` leaves the `debug` sources out of the run (they are included by default, matching the
+extension's *Run Tests*). Anything after the options is passed straight through to `dgdebug`.
+
+[source,console]
+----
+dgbuild test
+dgbuild test --no-debug
+dgbuild test -p ./my-project -- --width 80
+----
+
+Writing the tests themselves — the `(test $)` and `(assert $)` objects — is covered in the "Testing
+and Debugging" chapter of the Dialog manual, not here.
+
+== dgbuild run-skein
+
+Replays one or more saved skeins against a fresh `dgdebug` process each, comparing every knot's
+live response to its blessed response. With no arguments it replays `default`.
+
+For each skein it prints a summary line — `name: valid/new/error (valid/new/error)` — and, when you
+pass more than one skein, a `total:` line as well. Any knots that came out in error are listed
+above the summary.
+
+It exits non-zero *only if some knot is in error*. Unblessed *new* knots do not fail the run, so if
+you want continuous integration to require every knot be blessed, bless them first. `-v` /
+`--verbose` adds the underlying `dgdebug` lifecycle logging, which is quiet by default.
+
+[source,console]
+----
+$ dgbuild run-skein
+default: 200/0/1 (valid/new/error)
+
+$ dgbuild run-skein combat parser endings
+----
+
+This is the command-line equivalent of the panel's *Replay All*.
+
+== dgbuild sources
+
+Prints the project's fully expanded source list — exactly the files the compiler would receive.
+`-d` / `--debug` and `-t` / `--test` add those categories; `-T <suffix>` / `--target <suffix>`
+filters by target suffix; `-1` / `--single-line` prints the paths colon-joined on one line, for
+feeding into another command.
+
+[source,console]
+----
+dgbuild sources -d
+dgbuild sources -1 -T zblorb
+----
+
+== In continuous integration
+
+A minimal release gate in a GitHub Actions workflow:
+
+[source,yaml]
+----
+- run: npx -p dialog-ide dgbuild test && npx -p dialog-ide dgbuild run-skein
+----
+
+The runner also needs the Dialog toolchain available — install `dgdebug` onto its `PATH`, or point
+`dialog.json`'s `binDir` at a copy you provide.
+
+== What's next
+
+xref:troubleshooting.adoc[] — known limitations and the common reasons a project will not run.