Author Extension¶

Extension note: The Author extension is optional and must be enabled in your configuration. Core VIBE runs without it.

The Author extension lets you create and edit VIBE templates directly in the browser. Instead of editing config.yml and template files by hand, you use a visual workspace with live preview, drag-and-drop question ordering, and structural editing tools that write Jinja syntax for you.

Enabling the Author Extension¶

Add vibe.author to your extensions list and grant author access:

# config.yml
extensions:
  - vibe.author

# For local development:
dev_settings:
  author: true

In production, author access is controlled via PASETO tokens with an author grant. See Session Context — Production: PASETO Token Configuration for token setup.

Workspace directory¶

To create new templates, configure a workspace directory:

author:
  workspace: templates/drafts/

This must point to a writable directory on the filesystem. Templates created through the Author UI are placed here with status: draft so they are hidden from regular users until published.

The Workspace¶

Navigate to /author/<template_id>/ to open a template for editing. The workspace has two main areas:

Left column (split into two resizable sections):

• Questions — A list of all questions defined in config.yml. Each question is a collapsible card showing its ID, type, and label. You can add, edit, delete, and reorder questions here.
• Template source — A plain-text editor showing the template content (Markdown with Jinja syntax, or a projected text view for DOCX templates). A toolbar provides shortcuts for formatting and variable insertion.

Right column:

• Interview preview — An embedded live interview that runs the template as a real VIBE interview. You can fill in sample answers and see the rendered document update in real time. Changes to questions or template content automatically refresh this preview.

Both the vertical split (questions vs. editor) and the horizontal split (left vs. right columns) are resizable. Your layout preferences are saved in the browser.

Managing Questions¶

Adding a question¶

Click Add question below the question list. A new blank question card appears in edit mode. Fill in:

• Label (required) — The text shown to the user during the interview
• Question ID — Auto-generated from the label as a Python-valid identifier (e.g., "Client name" becomes client_name). You can override this.
• Type — Choose from: text, textarea, bool, tristate, number, amount, date, select, radio, multichoice, period

Type-specific fields appear based on your selection (options for select/radio/multichoice, min/max for number, currencies for amount, etc.).

Editing a question¶

Click a question card to expand it, then click Edit to enter edit mode. Changes are saved automatically when you modify any field — there is no save button. The preview updates immediately.

Deleting a question¶

Expand a question card, click Delete, and confirm. The question is removed from config.yml.

Reordering questions¶

Drag questions by their handle (the grip icon) to change the order. You can also use Alt+↑ / Alt+↓ to move the focused question card. The new order is saved to config.yml immediately.

Advanced fields¶

Each question card shows the most common fields by default. Click Advanced to reveal less-common settings such as placeholder, none_label, and type-specific constraints. Advanced fields are hidden by default to keep the UI uncluttered.

Read-only questions¶

Some question types (list, structured, computable, assisted) are displayed but cannot be edited through the Author UI. Edit these directly in config.yml.

Editing Template Content¶

Markdown templates¶

The template source editor is a plain-text area where you write Markdown with Jinja2 syntax. Changes are auto-saved when you stop typing, and the preview refreshes.

The toolbar provides shortcuts for common formatting:

An asterisk (*) appears next to the section title when you have unsaved changes. Changes are auto-saved after a short pause — the indicator disappears once the save completes.

DOCX templates¶

DOCX templates display a projected text view of the document content. Each paragraph appears as editable text when its underlying OOXML structure is simple enough for safe editing. Paragraphs with complex formatting (fields, bookmarks, drawings, etc.) appear as read-only blocks to prevent accidental data loss.

Edits to the projected text are mapped back to the DOCX XML and saved to the .docx file. The original formatting, styles, and structure are preserved.

A non-editable blocks indicator in the toolbar shows a count of read-only blocks. Click it to see a list of the skipped paragraphs (e.g. tables, drawings, fields) so you know exactly what could not be projected.

Open in Word¶

DOCX templates can be edited directly in Microsoft Word alongside (or instead of) the browser editor. Click Open in Word in the toolbar to launch Word with the current .docx file.

How it works¶

1. VIBE creates a short-lived editing session and opens Word using the ms-word: URI scheme.
2. Word connects to a built-in WebDAV server inside VIBE and loads the file.
3. While Word has the file open, the browser editor is disabled to prevent conflicting edits.
4. VIBE polls for changes every few seconds. When Word saves, the updated file is picked up automatically and the preview refreshes.
5. Click Done editing in Word to close the session, release the lock, and re-enable the browser editor.

Requirements¶

• Microsoft Word must be installed on the machine running the browser.
• The VIBE server must be reachable from that machine (localhost works; remote servers require the public URL configured via external_base_url in config.yml).

Configuration¶

All keys live under AUTHOR.word_integration in config.yml:

author:
  word_integration:
    token_expiry_minutes: 1440    # default: 24 hours
    lock_timeout_minutes: 10      # default: 10 minutes
    unlock_grace_seconds: 30      # default: 30 seconds
    max_file_size_mb: 50          # default: 50 MB

Interview Preview¶

The right-hand pane shows a live interview that runs your template exactly as a real user would see it. The preview maintains its own answer session separate from any user sessions, so you can fill in sample values without affecting live data.

• Any change to questions or template content automatically refreshes the preview.
• You can answer questions interactively to explore how the document renders under different conditions.
• Click Download at the bottom of the preview to render the document with your current answers and download it — useful for spot-checking the final output.
• If the template generates appendices, each one appears as a separate download link below the main document.

Selection-Based Transforms¶

Transforms let you convert plain text into Jinja template constructs without writing syntax by hand. Select text in the editor, then use a toolbar button to apply a transform.

Wrap in condition¶

Select a block of text and click the condition wrap button. A dialog appears where you provide:

• Label — Creates a new yes/no (bool) question with this label
• Question ID — Auto-generated from the label, or pick an existing bool/tristate question

The selected text is wrapped in {% if question_id %}...{% endif %}. If you chose to create a new question, it appears in the question list immediately.

Example: Selecting "This section only applies to premium clients." and wrapping with a question labeled "Premium client" produces:

{% if premium_client %}
This section only applies to premium clients.
{% endif %}

Convert to variable¶

Select text and click the interpolate button. A dialog appears where you provide:

• Label — Creates a new question with this label
• Question ID — Auto-generated from the label
• Type — The question type (defaults to text)
• Default value — Optional default answer
• Replace all — If the selected text appears multiple times, check this to replace every occurrence

The selected text is replaced with {{ question_id }}. A new question is created in config.yml.

Example: Selecting "ACME Corporation" with "Replace all" checked replaces every occurrence with {{ company_name }} and creates a text question for it.

Transform safety¶

Transforms are validated before they are applied:

• Selections that cross Jinja tag boundaries (e.g., selecting part of {{ variable }}) are rejected
• The resulting template is checked for valid Jinja syntax
• Question IDs are checked for uniqueness (auto-suffixed with _2, _3 if a collision is detected)
• Both the question definition and template content are saved atomically

Creating New Templates¶

Navigate to /author/new to create a template from scratch.

1. Enter a title — a template ID is auto-suggested as a slug
2. Choose a format:
   • Markdown (default) — Creates a blank template.md
   • DOCX — Upload a starting Word document that becomes template.docx
3. Click Create

The new template is created in the configured workspace directory with status: draft in its config.yml. Draft templates are only visible to authors in the template list. To publish, edit config.yml and remove the status: draft line (or set status: published).

Template Visibility¶

Templates with status: draft in their config.yml are hidden from non-author users. This lets you work on templates without exposing unfinished work. Any template in any source can use this mechanism — it is data-driven, not tied to which directory the template lives in.

Read-Only Templates¶

Templates loaded from git:// sources are read-only. The Author workspace displays them with a read-only indicator, and editing controls are disabled. Only file://-backed templates (including those in the workspace directory) support editing.

Config Preservation¶

When the Author UI writes to config.yml, it uses round-trip YAML parsing that preserves:

• Comments (both inline and block)
• Key ordering
• Formatting and indentation
• Blank lines between sections

This means hand-crafted comments and structure in your config.yml survive programmatic edits through the Author UI.

Validation¶

Click Validate in the toolbar to run the full VIBE template validation pipeline. Issues (errors and warnings) appear in a panel below the editor. Common issues include:

• Undefined variables referenced in the template
• Question type mismatches
• Invalid Jinja syntax
• Missing required question fields

The Author workspace also loads broken templates gracefully — if config.yml has YAML errors or the template has syntax problems, you can still open and fix them in-place rather than being locked out.