Skip to content

Index

Developer Overview

This section is for VIBE core developers and people exploring how to extend VIBE beyond template authoring. It complements the template author documentation by explaining the internal architecture and linking to the generated API reference.

  • Audience: core maintainers, extension authors, advanced integrators
  • Focus: subsystem overview, extension points, and API docs

What’s here

  • Extension Guide (preview): early outline of supported extension surfaces and patterns.
  • API Reference: generated from the source using mkdocstrings (static, no imports).

Local preview

  1. Install: uv sync --group docs
  2. Configure: edit zensical.toml
  3. Serve: python doc/build_docs.py serve
  4. Build: python doc/build_docs.py build (outputs public/).
  5. If you are working on prose only, or Rodney/Chrome is unavailable, add --skip-screenshots.

The docs builder keeps ```example-file and ```screenshot-script blocks in the checked-in Markdown source, generates API reference pages, executes screenshot blocks, and writes a temporary generated docs tree under .doc-build/ before invoking Zensical.

Screenshot Blocks

Documentation pages can embed reusable file examples with fenced example-file blocks and runnable screenshot instructions with fenced screenshot-script blocks.

\`\`\`example-file
id: foundation-config
path: config.yml
language: yaml

questions:
  client_name:
    type: text
    label: What is the client's name?
\`\`\`

The docs builder renders example-file blocks back to ordinary syntax-highlighted code blocks for readers, but also makes them available to later screenshot blocks in the same page.

\`\`\`screenshot-script
use foundation-config
open http://127.0.0.1:5001/
screenshot
\`\`\`

You can also define another reusable file and combine them into a temporary embedded template interview:

\`\`\`example-file
id: foundation-template
path: template.md
language: markdown

# Agreement

Hello {{ client_name }}
\`\`\`

\`\`\`screenshot-script
use foundation-config
use foundation-template
start-interview
screenshot-el '#question-client_name'
\`\`\`

Required example-file metadata:

  • id: stable name used by use <id>
  • path: file path to create in the temporary template bundle
  • language: syntax highlighter for the rendered code block

Currently supported inline file blocks inside screenshot-script:

  • config: | -> writes config.yml
  • template: | -> writes template.md

Supported built-in commands:

  • use <id>
  • open <url>
  • start-interview
  • screenshot
  • screenshot-el <selector>

Any other command line in the block is passed through to Rodney, so waits and interactions can be expressed using Rodney's own command set.

Conventions and style

API docs render best with concise, Google‑style docstrings and meaningful type hints. See CODING_CONVENTIONS.md for guidance and the docstring expectations used by the generator.