mini-a-docs

Jekyll documentation for Mini-A, with a CLI-first introduction, topic guides and a searchable public-interface reference. The Toolkit remains a separate site at https://tk.mini-a.ai/; its header and agent-documentation backlinks remain compatible.

Develop and check

bundle install
bundle exec jekyll serve --host 127.0.0.1

Build and validate before publishing:

bundle exec jekyll build --baseurl '' --destination /tmp/mini-a-docs-root
python3 scripts/validate-site.py /tmp/mini-a-docs-root
node tests/search.cjs
bundle exec jekyll build --baseurl /docs-preview --destination /tmp/mini-a-docs-project
python3 scripts/validate-site.py /tmp/mini-a-docs-project --baseurl /docs-preview

Use Ruby 3.2 (CI) or 3.3. A normal build needs neither a Mini-A checkout nor a model. Search is generated from the same rendered headings used by the pages. JavaScript enhances navigation, filtering and search; article text, links and all option records remain available without it.

Content structure

• getting-started.md: installation, one model, one task, sample input and saved output.
• guides/: everyday tasks; advanced/: deeper explanations and worked examples.
• reference/: grouped options, commands, presets, environment variables, utilities and interfaces.
• _data/reference.json: generated inventory, main revision and source fingerprints.
• _data/reference-overrides.json: reviewed corrections for conditional defaults or stale upstream prose.
• _data/features.json: capability-to-guide and source mapping.
• _data/navigation.yml: sidebar navigation; _layouts/ and _sass/docs.scss: layout.
• _data/legacy-links.json and tests/legacy-anchors.json: compatibility with the previous public site.
• _plugins/section_search.rb: section-level entries in search-data.json.

Keep existing permalinks and section IDs when moving content. Add a compatibility link at the old destination. The previous Features, Advanced and Configuration URLs are navigation hubs with their old anchors intact.

Refresh the main-branch inventory

Never extract from a feature branch or a dirty working tree. Obtain a clean snapshot of the chosen main revision and review its changes first. For example, with that revision already available in the sibling repository:

revision=$(python3 -c 'import json; print(json.load(open("_data/reference.json"))["revision"])')
snapshot=$(mktemp -d /tmp/mini-a-docs-source.XXXXXX)
git -C ../mini-a archive "$revision" | tar -x -C "$snapshot"
python3 -m pip install -r scripts/requirements.txt
python3 scripts/sync-reference.py "$snapshot" --revision "$revision"
python3 scripts/sync-reference.py "$snapshot" --revision "$revision" --check

The extractor also requires Node.js. It reads the literal registries, launcher help, runtime option names, commands, modes, environment variables and utility/MCP descriptors. It never starts Mini-A or calls a model. Review generated changes and any overrides, update the affected guides, then run the site checks. Do not remove legacy IDs to make validation pass.

The pull-request workflow checks the inventory against the pinned upstream revision and builds both root and project-prefix URL layouts. The Pages workflow validates the rendered site before uploading its artifact. Hosted checks run only after these changes are pushed.

Screenshots and examples

Capture the real UI from the pinned source using public sample data. Use separate temporary homedir, historypath and webadvancedpath, and a loopback listener. Do not capture personal conversations, startup credentials or tokens. scripts/demo-provider.py provides a deterministic Ollama-compatible fixture on 127.0.0.1:18789; set OAF_MODEL to (type: ollama, model: docs-demo, url: 'http://127.0.0.1:18789') in the isolated server process. Unset inherited model slots, OAF_MINI_A_MODE and OAF_MINI_A_LIBS first.

Fixture answers and usage numbers demonstrate transport and interface behavior, not model quality, billing or cost savings. Preserve the original image bytes and add a caption naming the demonstration. Track capture provenance and any blocked refresh in TODO.md. Existing terminal recordings are historical illustrations, not automated acceptance tests; replay is opt-in.