Roadmap

Evaluation, plan and roadmap for vibe-sketch.

The shared scope decision, confirmed on 2026-10-15, sets the boundary: publication-quality 2D drawing and reaction graphics here, detailed 3D calculation work in vibe-viewer, with input, drawing, basic cleanup and calculation workflows in both. WP 3.6/3.7 implement the sketcher side of reference-geometry and FIRE cleanup. The maintainer approved numeric IUPAC 2008 depiction conventions and RDKit’s existing ring-template API for 2D cleanup (#18), without copied template data or a new dependency. A physical 3D geometry database remains unselected.

Status (2026-10-26). 0.6.1, the template-library patch, is the latest published release (tag v0.6.1, source 5395bd1, 2026-10-25). 0.6.0 — Negishi’s Funnel remains the qualified paper baseline. It includes staged campaigns, explicit scientific reviews, accepted-artifact reaction reports and independent archived replay (#42, #66 and #109, all closed). Exact macOS ARM64 and Linux x86-64 packages passed installed acceptance; public installer, source and scientific-data hashes were verified. See the release evidence below.

QVF is the native document and result format. The bundled toolkit is QVF v0.6.0; the archive format remains QVF v1. The maintainer selected MPL-2.0 for vibe-sketcher on 2026-10-19; dependencies retain their own licences. Features accepted on later main commits do not change the immutable 0.6.0 release or establish acceptance of the next milestone. Version 0.7 remains open for the Diels–Alder ORCA check (#82) and its release qualification; checked graph naming (#2) is complete.

1. What we are building

A 2D chemical structure and reaction sketcher with ChemSketch and ChemDraw class ergonomics that does three things the existing sketchers do not do together:

  1. Publication graphics. Reaction schemes and structures exported as SVG, PNG and PDF in journal styles, plus CDXML import for co-authors who use ChemDraw and chemfig for LaTeX users.

  2. Calculation inputs. The same sketch becomes a 3D structure and a ready-to-run input for vibe-qc and ORCA, with charge, multiplicity, method, basis and solvent chosen in a side panel. More programs follow through the same writer interface.

  3. An API agents can drive. Everything the browser does, a Python SDK, a CLI, a REST API and an MCP server can do too. A human and an agent can edit the same live document.

It runs in the browser and as a desktop app. It hands 3D work to vibe-viewer and jobs to vibe-queue. There is no terminal drawing mode.

Three user stories anchor the scope:

  • The author. Draws reactants, products, arrows and conditions for a paper, numbers the compounds, exports the scheme in the journal’s style and sends the CDXML to a co-author.

  • The computational chemist. Sketches a molecule, cleans it, gets a 3D conformer, picks B3LYP/def2-TZVP with CPCM(water), exports an ORCA input or submits it through vibe-scheduler, and opens the result in vibe-view. For a reaction, one job per species and a reaction energy that lands back on the scheme.

  • The agent. Builds a document from a SMILES string or a name, lays it out, renders it, writes inputs and submits them, or edits the document a human is looking at.

Non-goals: a 3D editor (vibe-viewer has one), an electronic lab notebook, feature parity with ChemDraw, drawing in the terminal.

2. Evaluation

2.1 Plugin for vibe-viewer, or standalone?

Factor

Plugin

Standalone with a bridge

Plugin API in vibe-viewer

Does not exist yet; proposed for v3.0 in the vibe-viewer roadmap. Building the sketcher as a plugin means building that API first and coupling two release schedules.

Nothing to wait for.

UI technology

vibe-viewer is Trame: Python owns the UI state and renders Vue. A sketcher is a client-side canvas with state in the browser, the opposite model.

Plain TypeScript app over an HTTP and WebSocket API.

Install weight

A chemist drawing a scheme would install VTK and PyVista.

pip install vibesketch pulls RDKit and FastAPI, nothing 3D.

Users who want both

Served by a bridge: a Sketch button in vibe-viewer, an Open in vibe-viewer button in the sketcher, QVF in between.

Same.

Licensing freedom

Bound to vibe-viewer’s licence.

Decided separately.

Repository

Shared tracker, shared CI minutes, shared release gate.

Own repository, as requested.

Recommendation: standalone product in its own repository, integrated with vibe-viewer both ways. The bridge is cheap: vibe-viewer already builds from SMILES, exports QVF and submits to vibe-scheduler, and it has an Electron shell that can later host both products as tabs.

2.2 Build the canvas, or embed one?

A 2D chemical editor is the most expensive component: bond drawing with angle snapping, ring and chain tools, stereo wedges, charges and radicals, atom labels and abbreviations, brackets and S-groups, reaction arrows and text, selection, rotation, flipping, undo, copy and paste, and a hotkey layer that chemists already know. Candidates:

Candidate

Licence

What it is

Verdict

Ketcher (EPAM)

Apache-2.0

TypeScript and React editor; standalone mode bundles the Indigo toolkit as WebAssembly, so layout, clean-up, aromatize, CDXML, MOL/RXN, SMILES, InChI and SVG/PNG rendering work offline. Own JSON format (KET). Used by PubChem. Active 3.x releases.

Primary candidate.

OpenChemLib JS

BSD-3-Clause

Cheminformatics toolkit with a structure editor; DataWarrior lineage.

Fallback engine; editor less polished.

Kekule.js

MIT

Toolkit with an editor widget. Low recent activity.

Fallback.

JSME

BSD-3-Clause

GWT-compiled minified editor; hard to restyle.

No.

RDKit.js

BSD-3-Clause

Depiction and chemistry in WebAssembly, no editor.

Useful for rendering, not a canvas.

ChemDoodle Web Components

GPLv3 or paid

Capable, but GPL conflicts with MPL-2.0 and with any commercial route.

Excluded.

Marvin JS

Proprietary

Excluded.

Own editor

Ours

Full UX control, our design language.

Three to six times the effort of embedding, before any compute feature exists. Only if the spike fails.

Recommendation: embed Ketcher as the canvas engine behind an adapter, and own everything around it: the shell, the document format, the compute panel, the style presets, the exports and the API. The adapter is the only module that imports Ketcher, so the engine can be swapped if EPAM’s direction diverges from ours. Apache-2.0 is compatible with MPL-2.0 and with a commercial licence; a fork is permitted if ever needed.

The decision is confirmed by a time-boxed spike (WP0) with written exit criteria: bundle size and load time with Indigo WebAssembly, how far the toolbar and template library can be replaced, KET round-trip fidelity for stereo, charges, S-groups, arrows and text, the cost of hosting a React component inside our shell, and a check of the licence files as shipped.

2.3 Chemistry engine

  • RDKit (BSD-3-Clause) in Python, as a core dependency. 2D coordinates, ETKDG embedding with MMFF94 refinement, conformer ensembles, CIP stereo labels, InChI and InChIKey, formula and mass, ACS 1996 depiction style. vibe-viewer keeps RDKit optional because it is a viewer; the sketcher is a chemistry tool and should not ship without it.

  • Indigo in the browser through Ketcher’s standalone build, so drawing, clean-up and basic export work with no Python running. The release notes for Indigo 1.25 list an ACS-style reaction layout and CDX/CDXML fixes.

  • No Open Babel (GPL-2.0) and no ChemDoodle, in line with vibe-viewer’s ground rule 4. A licence check in CI enforces this.

  • Name to structure beyond the 83 built-in structures: a network fallback through the resolvers vibeqc_naming.external already wraps, and optionally OPSIN (MIT) as the [opsin] extra behind a lazy import, on a Java runtime the user provides; the desktop app bundles neither Java nor OPSIN (maintainer decision, 2026-10-23, #94).

2.4 What we reuse

From

What

How

vibe-qc

vibeqc_naming: MolecularGraph, name_from_graph, structure_from_name, smiles_from_name, NamedResult with provenance and confidence, the solids engine for later crystal work

The sketcher has explicit bonds, so it calls the graph API rather than the 3D bond perception. It becomes the first consumer that can feed CIP descriptors into the engine.

vibe-qc

Molecule, run_job, run_qcschema, solvation presets

The targets of the vibe-qc writer. The QCSchema adapter’s fail-closed stance is the model for every writer.

vibe-viewer

input_generator templates, converters.atoms_to_qvf and sdf_to_qvf, build_tools.FRAGMENTS

Copied, then generalized into the writer registry.

vibe-viewer

Electron shell: handshake JSON, managed venv, interpreter probe, updater feed, PUBLISHING.md contract

Forked as electron/, product name and feed path changed.

vibe-viewer

codenames.py, release process, changelog fragments, Sphinx toolchain, .githooks/pre-commit privacy hook, scripts/install.sh family, CI layout, strict mypy and Ruff gates

Copied as the repository skeleton on day one, so the lessons of the mypy ramp are not relearned.

qvf

qvf-writer[numpy,validate]

QVF export without depending on vibe-viewer’s VTK stack.

qc-input-library

ORCA conventions and real inputs

Golden files for the ORCA writer’s style; generated inputs can be contributed back.

vibe-scheduler

vq submit, fetch and status

Optional [queue] extra, same shape as vibe-viewer’s.

Two conditions attach. vibeqc_naming ships inside the vibe-qc wheel today, so it must become a separately installable pure-Python distribution before the sketcher can depend on it (cross-repository ask, section 5). The vibeview core package depends on PyVista and VTK, so the sketcher uses it only inside an optional [view] extra and writes QVF through qvf-writer.

2.5 The name

Decided: vibe-sketcher, package vibesketch, command vibe-sketch, document extension .vsk. The family is vibe-qc, vibe-viewer and vibe-scheduler, with packages vibeqc, vibeview and vq. The options that were weighed:

Name

Package, CLI

Notes

vibe-sketcher

vibesketch, vibe-sketch

Reads like vibe-viewer: a verb-shaped noun that says what it does. No collision with a chemist’s acronyms. Chosen.

vibe-qs

vibeqs, vibe-qs

“Quantum sketcher” is accurate but opaque to first-time visitors, and vqs sits next to vq in the shell.

vibe-ms

vibems, vibe-ms

To a chemist, MS is mass spectrometry. Avoid.

vibe-draw

vibedraw

Generic; nothing says chemistry.

Release codenames pair an organic chemist who has a named reaction with a piece of laboratory equipment. The maintainer selected Dötz’s Flask for 0.1.2 and subsequent 0.1.x patches; see the catalogue.

3. Architecture

 browser or Electron                         Python package: vibesketch
 +---------------------------------+          +----------------------------------+
 | shell  (TypeScript, Vite)       |  HTTP +  | server  (FastAPI, uvicorn)       |
 |  canvas adapter                 |  WS      |   document store, revisioned     |
 |    Ketcher + Indigo (WASM)      |<-------->|   chem      RDKit                |
 |  compute panel                  |          |   naming    vibeqc_naming        |
 |  scheme and style panel         |          |   render    SVG, PNG, PDF, chemfig|
 |  3D peek (Miew or 3Dmol)        |          |   inputs    orca, vibeqc, qcschema|
 +---------------------------------+          |   export    qvf-writer, vibe-view |
                                              |   queue     vq (optional)        |
 agents: MCP server, REST, Python SDK, CLI -->|                                  |
                                              +----------------------------------+

Four principles:

  1. API first. The browser is one client of the same API that agents use. Nothing is reachable only through a button.

  2. The document is the unit. One JSON file with a versioned schema. The canvas state (KET) is embedded verbatim for lossless round trips, and a normalized layer carries what the compute side needs: species with SMILES, InChIKey, charge, multiplicity and cached conformers; reactions with roles, arrows, conditions and yields; job specifications; style; provenance.

  3. Chemistry in Python, drawing in the browser. Indigo covers the offline canvas; everything that produces a number or a file for a calculation goes through RDKit and the writers on the server, where it is testable.

  4. Degrade without optional pieces. No vibe-qc, no vibe-scheduler, no vibe-viewer installed: the corresponding features hide behind install hints, the pattern vibe-viewer already uses.

3.1 Document model, first cut

{
  "schema": "vibe-sketch/1",
  "revision": 17,
  "canvas": {"format": "ket", "data": {}},
  "species": [
    {"id": "m1", "label": "1", "smiles": "CCO", "inchikey": "LFQSCWFLJHTTHZ-UHFFFAOYSA-N",
     "charge": 0, "multiplicity": 1,
     "name": {"value": "ethanol", "source": "vibeqc_naming", "confidence": "high"},
     "conformers": [{"method": "etkdg+mmff94", "xyz_angstrom": []}]}
  ],
  "reactions": [
    {"id": "r1", "reactants": ["m1"], "reagents": [], "products": ["m2"],
     "arrow": "forward", "conditions": ["Pd(PPh3)4, K2CO3", "dioxane, 80 C"], "yield": "87%"}
  ],
  "jobs": [
    {"species": "m1", "program": "orca",
     "spec": {"task": "opt+freq", "method": "B3LYP", "basis": "def2-TZVP", "aux_basis": "def2/J",
              "approximation": "RIJCOSX", "dispersion": "D4",
              "solvent": {"model": "CPCM", "name": "water"}, "resources": {"nprocs": 8, "maxcore_mb": 3000}}}
  ],
  "style": {"preset": "acs-1996"},
  "provenance": {"app": "vibe-sketch 0.1.0", "created": "2026-10-13T00:00:00Z", "edits": []}
}

The job specification is program neutral. Each writer maps it and refuses what it cannot express rather than guessing, the stance vibe-qc’s QCSchema adapter takes. Charge is the sum of formal charges on the drawing; multiplicity defaults from the radical count and is always editable, because the drawing cannot know the spin state of a metal centre.

3.2 API surface, version 1

  • Python SDK. Document with load, save, from_smiles, from_name, from_molfile, from_cdxml, add_species, add_reaction, layout, embed_3d, name, render, write_input, to_qvf, submit.

  • CLI. vibe-sketcher serve | desktop | render | input | convert | name | mcp.

  • REST. Documents with optimistic concurrency (If-Match on the revision), species and reaction sub-resources, render, inputs, chem/embed3d, chem/name, export/qvf, jobs/submit. OpenAPI is served, so an agent can read the contract instead of guessing it.

  • WebSocket. Document events, so the browser reflects an agent’s edit within a frame and the agent sees the human’s.

  • MCP server. The same operations as tools, so a Claude or Codex session can sketch, name, render, write inputs and submit without a browser.

Human and agent edit the same document through the server’s revision counter. The browser pushes debounced canvas changes; an agent’s patch names the revision it read; a stale patch gets a conflict and re-reads. That is enough for version 1; operational transforms are not.

3.3 Rendering

The canvas is what you see while drawing. Exports render on the server from the normalized document, so a batch of fifty schemes renders the same way from the CLI as from the button: style presets (ACS 1996 first, then RSC and Wiley), compound numbering, conditions above and below arrows, yields, multi-step layout. SVG is native; PNG through RDKit’s Cairo backend; PDF through a BSD-licensed SVG-to-PDF path chosen in the spike; CDXML through Indigo; chemfig from our own emitter.

3.4 Desktop

Electron, forked from vibe-viewer’s shell: the CLI writes a handshake file, the shell finds or creates a managed venv, probes the interpreter, starts the server on a free port and loads it. macOS first, as vibe-viewer did; the update feed lives under the same site, in its own path. Later, one shell hosts vibe-viewer and the sketcher as tabs.

3.5 Repository layout

vibe-sketch/
  AGENTS.md  CLAUDE.md  CODEX.md  CONTRIBUTING.md  LICENSE  README.md
  pyproject.toml              vibesketch: core = pydantic, rdkit, fastapi, uvicorn, qvf-writer
  schema/                     document JSON schema, versioned
  src/vibesketch/
    document/                 model, KET bridge, MOL/RXN/SDF import and export, CDXML import
    chem/                     RDKit services: layout, embed3d, stereo, properties
    naming/                   vibeqc_naming wrapper and fallbacks
    render/                   styles, SVG, PNG, PDF, chemfig
    inputs/                   registry; orca.py, vibeqc.py, qcschema.py
    server/                   FastAPI app, WebSocket, static bundle
    agent/                    MCP server
    cli.py
  web/                        TypeScript shell, Ketcher adapter, Vite build
  electron/                   desktop shell
  docs/                       Sphinx, same toolchain and theme as vibe-view
  tests/                      pytest; Playwright for the served UI
  scripts/                    install, update, release artifacts, changelog fold

Optional extras: [queue] for vq, [view] for vibe-viewer, [opsin] for OPSIN on a user-provided Java (#94), [all], [test], [dev], [docs].

4. Roadmap

Phase numbers identify work areas, not release versions. Their original durations are historical estimates, not remaining effort or release dates. Use the approved version milestones and their exit criteria to order work. Each work package names a tier so the model can be chosen: A needs architectural judgement or novel chemistry logic, B is substantial implementation against a fixed contract, C is well specified and test-anchored. Every open work package is one or more issues in the tracker, labelled with its phase and tier, and any agent may take one.

Where the work stands (2026-10-26)

WP

State

Issues

0.1 to 0.5

Done

1.1 to 1.7

Done, including hidden-pane zoom and large-structure import repairs

#7, #8 closed

1.5, names

Checked naming sends the explicit hydrogen-complete graph and RDKit CIP labels to the standalone vibeqc-naming distribution (f47b5b2); upstream vibe-qc #536 and #537 are closed. Naming stays optional, with verification and install hints

#2 closed

2.1 to 2.6

Done; browser/MCP exit and real vibe-qc, vibe-scheduler and vibe-viewer integration checks completed

#15, #16 closed

2.7

Released through 0.6.1; 0.6.0 qualified its macOS ARM64 and Linux x86-64 packages

#84, #89 and #109 closed; desktop acceptance repeats for affected packages

3.1

Scene SVG and the explicit Tidy scheme layout on main

#21 closed (51e594d), #20 closed

3.2

Journal styles and the PNG/PDF publication backend (resvg_py 0.5.0 + svg2pdf-py 1.1.0, approved 2026-10-19) merged

#23 closed (5e19bc8, merged 45358bd); #22 closed

3.3

CDXML whole-drawing import retained; QVF is the native writing format. CDXML writing and binary CDX import landed under the separately approved #95 scope, checked by automated readers and round trips; actual ChemDraw compatibility is unverified and untested, and writing is outside the 0.6 paper evaluation

#24, #95 closed

3.4

chemfig emitter on main (vibesketch.render.chemfig)

#25 closed

3.5

Batch rendering CLI and the figures chapter on main

#26 closed

3.6

FIRE minimiser and versioned reference-table cleanup, with quality and stereo fallback; two ring substituents and ring-system reference layouts added

#17 closed, #18 closed, #80

3.7

Constrained FIRE relaxation on RDKit force fields on main (vibesketch.chem.relax)

#19 closed

4.1

QVF job containers and reaction groups (queue.submit(reactions=...), runs --groups, cancel-group), with browser reaction/scheme submission, group progress and cancellation

#3 closed, #27 closed, #74

4.2

Approved optional Run.result and local strict ORCA reader; explicit result import, provenance-bound reports and derived energy figures on main

#28 closed

4.3

NEB input generation implemented: minimum-chemical-distance atom mapping, aligned complexes, ORCA NEB-TS and vibe-qc CI-NEB. In ORCA 6.1.1, the SN2 fixture completed endpoint optimization, band and TS search. The Diels–Alder endpoints converged, but its band reached the time limit without convergence; path diagnosis and complete band/TS acceptance remain open

#29 closed; #82 in verification

4.4

CSV, Markdown and booktabs LaTeX energy tables implemented through SDK, CLI, REST, MCP and browser

#30 closed

4.5

Released in 0.6.0: recipe compilation, accepted-geometry handoff, explicit retries/reviews, verified stage figures and reaction tables; original-result campaign continuation and independent archived replay accepted within the documented scientific scope

#42, #66, #109 closed

Later main, restricted-reference contract

Explicit real_restricted_cc recipe support is implemented with fail-closed channel checks. vibe-qc 0.18.1, containing its #662 fix, was published on 2026-10-26. Scientific acceptance still requires the DD-owned ethene staged replay on that runtime and a matched independent canonical reference; original rejection and retry/parent identities must remain intact

#119 open; source complete, verification pending

0.6.1, template library

303 compounds, 87 open-attachment fragments and 1,018 reaction-index entries, with the browser picker and SDK/CLI/REST/MCP interfaces, published in 0.6.1; the paper environment and fleet update remain to be recorded

#123 closed

0.7, geometry return

Identity-preserving draw/send/edit/return/reopen acceptance completed on later main; no 0.7 package release yet

#67 closed

Continuous

Formatting, accessibility, notices and release tooling implemented; maintained on each change

#6, #31, #32, #33 closed

The illustrated tutorials include drawing a reaction, exporting its publication SVG and submitting its species through vibe-scheduler to vibe-qc (#44, #46 and #48 completed). Named-reaction examples and a full feature-to-tutorial map are also complete (#53). Versions 0.4.0, 0.5.0 and 0.6.0 completed their respective release gates (#84, #89 and #109). Source landing, installed-package qualification and scientific acceptance remain distinct states.

Released 0.6 baseline

Version 0.6.0 — Negishi’s Funnel was published on 2026-10-25 at immutable tag v0.6.0, source df9a478c30181fe115663d1daa2272bf6f362f4d. The final candidate passed all seven CI jobs. Both installed platform packages passed native functional checks and the frozen 105-observation corpus: 101 passes, three expected refusals and one unchanged case per platform.

The butadiene + ethene → cyclohexene demonstration completed its accepted 24-node continuation while preserving all 12 original calculation results, failed verdicts and explicit reviews. Independent archived replay checked 36 manifests and 54 artifact files; all five interfaces (SDK, CLI, REST, MCP and browser) reproduced six report formats. Six negative controls, reaction-energy arithmetic, required figures and tables also passed.

Use the public downloads and versioned scientific data, revision 2. The data archive SHA-256 is 7aeb1113a6b8c2c284d3d0311f1c044c357a6b173b45b18aadbf16bd4d354464. Its manifest and derivation record bind the public files to accepted results; the README describes the historical pilot’s separate availability. This is a portable results dataset, not an executable copy of private orchestration. Revision 2 corrects the README’s private provenance addresses; scientific files are unchanged and the first public archive was withdrawn.

Acceptance retains important limits: butadiene and ethene keep their raw external RHF-to-UHF instability verdicts under evidence-bound restricted-sector reviews. The triples algorithm is the rotated-occupied (T1) compatibility correction, not iterative local T1. Energies are electronic only; no thermal, transition-path, unrestricted-stability or external correlated-method accuracy claim is made. The macOS package is ad-hoc signed, not notarized.

Approved releases and paper baseline (2026-10-26)

The maintainer approved the following sequence on 2026-10-18. The tracker milestones and their issues define the detailed exit criteria; no calendar deadline or release authorization is implied by this status update.

Version

Approved outcome

Release and remaining acceptance

0.2

Publication export

Scene SVG (#21), journal styles (#23), scheme PNG/PDF (#22) and batch rendering with the figures chapter (#26) shipped with 0.3.0; no separate 0.2 release was published.

0.3

Predictable geometry cleanup and scheme layout

FIRE #17, constrained 3D relaxation #19, the approved 2D reference cleanup #18 with #80, and the explicit Tidy scheme layout #20 shipped in 0.3.0.

0.4

Editable publication interchange

chemfig #25 is merged, its fixtures compiled with lualatex; CDXML import #24 with automated checks and QVF preservation. CDXML writing subsequently landed under #95’s separate scope; it is outside the 0.6 paper evaluation. ChemDraw testing and sample collection remain omitted.

0.5

Traceable reaction calculations

Released: QVF job containers, reaction groups and browser controls, strict result import, reaction-energy figures and tables. Exact installed-package qualification #89 is complete.

0.6

Staged workflows and release-paper baseline

Released: #42 scientific acceptance, #66 independent archived replay and #109 exact package/publication qualification are complete; limitations and data availability are recorded above.

0.7

Reaction paths and structure exchange

NEB generation #29 and geometry-return acceptance #67 are complete. ORCA 6.1.1 SN2 acceptance passed; #82 remains open for Diels–Alder band and TS completion after the original nonconverged run. Checked graph naming #2 is complete (f47b5b2). On 2026-10-27 the maintainer added Phase 6, nanomaterials, surfaces and electrochemistry (#137 to #146). No 0.7 release is qualified.

0.8

Usability and robustness

Large drawings/accessibility #68 and recovery/platform/security qualification #69.

0.9

Compatibility freeze and user evaluation

#70, after the earlier milestone exits.

1.0

Stable supported product

#71: complete promised gates, interfaces, documentation and immutable qualified artifacts.

The original released paper baseline is 0.6.0, with real scientific artifacts and independent replay. Its artifacts and evaluation evidence remain frozen. The maintainer additionally requires the compound, fragment and named-reaction template library (#123, !138) in a 0.6.x patch release and in the paper environment. 0.6.1, published on 2026-10-25 from 5395bd1, is that patch. It includes the 303 compounds, 87 open-attachment fragments and 1,018 reaction-index entries, their browser picker and SDK/CLI/REST/MCP interfaces. See the release and paper checklist. Updating and verifying the fleet and paper installation are still pending; publication alone does not complete them. The paper must identify the patch used for the library separately from the original 0.6.0 scientific evaluation. Inorganic/crystal authoring follows 1.0. Version scope and names remain as approved in the milestones; this reconciliation does not move their features. The one later scope change is Phase 6, added to 0.7 on 2026-10-27.

For 0.2, scene SVG (#21), journal styles (#23), whole-scheme PNG/PDF (#22) and batch rendering with the figure guide (#26) are merged. The approved optional backend remains resvg_py==0.5.0 and svg2pdf-py==1.1.0, with its documented platform and maintenance limits. Batch input/output failure continuation is covered by #75. These features shipped in 0.3.0; no separate 0.2 release was published.

Every new release needs exact candidate/package qualification: reproducible artifacts, bundled fonts, physical dimensions, DPI, notices, SDK/CLI/REST/MCP and browser behavior, plus installed desktop acceptance. #84, #89 and #109 record completed 0.4, 0.5 and 0.6 qualification respectively. A passing source suite or runtime build alone does not establish native installed-app acceptance. The latest published version is 0.6.1; preserve all published software artifacts.

GitLab milestone tracking and weekly reconciliation

Use the project’s Plan > Milestones view for release scope and completion; use the assigned issues for implementation, dependencies and acceptance evidence. The existing approved milestones are:

Target

Exact milestone title

Project-local milestone number

v0.2.0

v0.2.0 — Grignard’s Condenser

1

v0.3.0

v0.3.0 — Diels’s Burette

2

v0.4.0

v0.4.0 — Wittig’s Pipette

3

v0.5.0

v0.5.0 — Heck’s Beaker

4

v0.6.0

v0.6.0 — Negishi’s Funnel

5

v0.7.0

v0.7.0 — Suzuki’s Stirrer

6

v0.8.0

v0.8.0 — Claisen’s Crucible

7

v0.9.0

v0.9.0 — Robinson’s Retort

8

v1.0.0

v1.0.0 — Sharpless’s Balance

9

Review this roadmap and those milestones every week against current main, released tags, open and closed issues/MRs, and accepted checks. Record the review date and concrete evidence in the relevant milestone or issue; correct both the roadmap and tracker when they disagree. Preserve distinctions between implemented, validated and released work. Source landing or a zero open-issue count alone does not meet a release gate.

When all promised exit criteria have evidence, record milestone acceptance and advance the next planned feature-version target. Package version changes and tags follow the release process and its applicable checks. Do not blindly increment the semantic major digit: 0.2 through 0.9 are the approved feature releases; 1.0 retains its stability and support criteria. The paper baseline remains 0.6.x. Do not move scope or weaken unresolved gates to make a version appear complete. The 0.6 milestone is closed on its accepted release evidence; 0.7 and later milestone gates remain open.

Phase 0: decide and spike (one to two weeks)

WP

Deliverable

Exit criterion

Tier

0.1

Name, licence, hosting decided by the maintainer

Done 2026-10-13; recorded in README.md and LICENSE

maintainer

0.2

Repository skeleton copied from vibe-viewer: AGENTS.md, privacy hook, Ruff and strict mypy from the first module, CI with lint and a smoke test, changelog fragments, codename module

Green pipeline on an empty package

B

0.3

Canvas spike: Ketcher standalone inside a Vite shell, toolbar replaced, custom template, KET round trip of a stereo-bearing reaction with text and brackets

A written go/no-go against section 2.2’s criteria

A

0.4

Document schema v1 and the writer interface, with JSON schema and two toy writers

Schema validates fixtures; writers refuse unsupported specs with a reason

A

0.5

Cross-repository asks filed (section 5)

Issues exist

C

Phase 1: sketch (four to six weeks)

WP

Deliverable

Tests

Tier

1.1

Browser app: shell, canvas adapter, open and save .vsk, undo through the engine

Playwright smoke

B

1.2

Import SMILES, MOL, SDF, RXN, CDXML, and a name through structure_from_name and fallbacks

Round-trip fixtures

B

1.3

Export SVG, PNG, MOL, SMILES, InChI from the canvas and from the server

Structural SVG comparison, not pixels

B

1.4

Clean-up and layout presets: one button, predictable result

Fixture layouts

B

1.5

Properties panel: formula, mass, charge, suggested multiplicity, live IUPAC name with confidence badge

Unit tests over the naming wrapper, including the no-vibeqc-naming branch

A for the multiplicity logic, B otherwise

1.6

Python SDK, CLI and REST for everything above; OpenAPI served; WebSocket events

Contract tests generated from the OpenAPI document

B

1.7

Manual pages: quickstart, drawing, formats, API

Docs build strict

C

Exit: a chemist can draw a molecule, name it, and export a clean SVG from the browser and from the CLI, with no vibe-qc installed.

Phase 2: compute (about four weeks)

WP

Deliverable

Tests

Tier

2.1

3D embedding: ETKDG with MMFF94, stereo preserved, conformer cache in the document

Stereo round trips SMILES to 3D to CIP labels

A

2.2

ORCA writer: keyword model for method, basis, auxiliary basis, RIJCOSX, dispersion, CPCM and SMD, tasks SP, Opt, Freq, Opt+Freq, TDDFT, NMR; %pal and %maxcore; constraints

Golden files styled after qc-input-library

A for the model, B for the writer

2.3

vibe-qc writer: Python script from the vibe-viewer templates, plus QCSchema JSON

Scripts import and parse; QCSchema validates

B

2.4

QVF export through qvf-writer; Open in vibe-viewer; 3D peek in the panel

QVF conformance script passes

B

2.5

vibe-scheduler submit and status in the compute panel, optional extra

Mocked vq

B

2.6

MCP server exposing the SDK

Tool-call tests

A

2.7

Electron desktop app, macOS first; updater feed path

Packaged app opens .vsk and .qvf; first-run setup, save, notices and server shutdown pass desktop acceptance

B

Exit: sketch to ORCA input and to a vibe-qc run in two clicks or one API call; an agent does the same through MCP. Automated workflow criterion met (#15): from imported ethanol and the default B3LYP/def2-SVP settings, the browser writes ORCA input in one click, then choosing vibe-qc and submitting takes two actions. tests/test_phase2_exit.py checks the real browser, embedding, writers and server, plus the MCP tool sequence, against a stand-in queue. CI requires both tests. Real vibe-qc execution, vibe-scheduler submission and retrieval, and the vibe-viewer handoff have also been checked (#16). The reaction tutorial documents the complete draw, export and calculate workflow. Packaged acceptance completed for 0.1.2 and 0.1.3; repeat affected checks for later packages.

Phase 3: publish (about four weeks)

WP

Deliverable

Tier

3.1

Reaction schemes: arrows (forward, equilibrium, retrosynthetic, resonance), conditions, yields, compound numbering, multi-step layout

A

3.2

Style presets ACS 1996, RSC, Wiley; bond length, line width, fonts, hash spacing; PDF export

B

3.3

CDXML import fidelity and QVF preservation using automated fixtures; CDXML writing follows for 1.0 (#95), and actual ChemDraw testing is outside scope

B

3.4

chemfig emitter

A

3.5

Batch rendering CLI; docs chapter on figures for papers

C

3.6

Clean-up from a reference table: ideal bond lengths, angles and ring templates per atom environment, non-bonded repulsion, stereo kept, minimised with FIRE (Bitzek et al., 2006), following the shared scope decision

A

3.7

Constrained 3D relaxation with FIRE on RDKit force fields

B

Exit: a scheme drawn here appears in a manuscript without touching another program.

Phase 4: reactions as jobs (about four weeks)

WP

Deliverable

Tier

4.1

Job sets: one job per species in a reaction, shared specification, manifest; submit as a group

B

4.2

Results back onto the scheme: read QVF energies, compute reaction energies with the CODATA factors vibe-viewer uses, annotate the arrow

A

4.3

ORCA NEB-TS endpoints from reactant and product sketches; vibe-qc equivalent where supported

A

4.4

Reaction energy table export

C

4.5

Staged recipes, accepted-geometry handoff and retry provenance (#42); independently replayed scientific evidence (#66)

A

Phase 5: inorganic and crystals (after 1.0, scope to be decided)

  • Coordination complexes: dative and haptic bonds, metal centres with explicit oxidation state and spin, which the 2D engine only partly models. Design first.

  • A crystal builder that is a form and a 3D preview rather than a canvas: space group and Wyckoff positions or a CIF, supercell and slab through the code vibe-viewer already has, adsorbate placement from a sketched molecule, periodic inputs for vibe-qc. Names through name_solid_from_atoms. Phase 6 records the 2D side that this builder reads: surfaces and nanoparticles (#140) and formula species for solids (#142).

Phase 6: nanomaterials, surfaces and electrochemistry (in 0.7, approved 2026-10-27)

A requirements survey of about 80 papers on carbon-nanotube synthesis, surface functionalization and electroanalysis checked what vibe-sketcher can draw for this chemistry. The molecular steps already work: mechanisms with curved and half-headed arrows, radicals, polymer brackets, abbreviations and laboratory pictograms. The organic reactions in the set, such as nitroso transfer and analyte oxidations, draw today. What cannot be drawn yet is the nanotube itself, a molecule bonded to a material, an electrode reaction with its electrons, and a solid without a molecular graph. Probes on main (0ee7c49) showed:

  • an H-terminated (6,6) segment, C192H24, cannot be cleaned or rendered;

  • an attachment label (*) blocks the figure;

  • [e-] does not parse;

  • Pb²⁺ is suggested as a triplet (#147, a patch repair outside this phase).

WP

Deliverable

Issue

Tier

6.1

Parametric nanostructures: single- and multi-walled nanotubes from (n,m), length and termination; graphene sheets and ribbons; fullerenes; an atom model and an identity without InChI

#137

A

6.2

Nanostructure depiction: lattice projection, schematic tube, end-on and unrolled views, in every figure format and as one canvas object

#138

A

6.3

Labelled attachment atoms (CNT, Au, NP) in figures and round trips, as generic structures

#139

B

6.4

Surfaces, electrodes and nanoparticles as reaction partners, with anchors and monolayers

#140

A

6.5

Electrochemical half-reactions: electron participants, state labels, potentials with their reference electrode, atom and charge balance

#141

A

6.6

Formula species for non-molecular solids: oxides, carbonates, doped and variable compositions

#142

A

6.7

Catalytic-cycle layout in Tidy scheme

#143

B

6.8

Apparatus pictograms for electrochemistry and CVD

#144

C

6.9

Template-library expansion: nanocarbon models, diazonium salts, linkers, CVD precursors, analytes, polymer repeat units

#145

C

6.10

Redox-potential and surface-binding calculation recipes with explicit reference constants

#146

A

Order of work:

  • 6.3, 6.5, 6.7, 6.8 and 6.9 have no dependencies and give usable drawings early.

  • 6.1 and then 6.2 deliver the nanotubes.

  • 6.4 builds on 6.3 and 6.2, 6.6 on 6.5, and 6.10 on 6.5 and 6.4.

Periodic models (slabs, one-dimensional nanotube cells, adsorbate placement) stay in Phase 5 and in vibe-qc; Phase 6 records the information they need. No new hard dependency is proposed. The maintainer placed the whole phase in 0.7 (section 7, decision 9), so 0.7 is qualified only when every Phase 6 issue’s “Done when” holds.

Continuous tracks

Accessibility of the served UI, licence compliance check in CI, release process and codename catalogue mirrored from vibe-viewer, cross-repository pin changes announced when create_app style contracts move.

5. Cross-repository asks

Filed on 2026-10-14 (WP 0.5). A feature or decision another project owns is asked for in that project’s tracker; vibe-sketcher’s own side of each interaction is tracked here: the hand-off to vibe-viewer (#1), naming through vibeqc_naming (#2) and keeping the sketch with its result archive (#3).

  • vibe-qc. Publish vibeqc_naming as its own pure-Python distribution (vibe-qc #536). Accept explicit bonds and CIP descriptors on a MolecularGraph so systematic names can carry R/S and E/Z (vibe-qc #537). Both are closed; checked naming uses them since #2. external.name_from_rdkit is confirmed a silent no-op: RDKit has no MolToIUPACName (vibe-qc #538).

  • vibe-view. A Sketch entry point that opens the sketcher when the [sketch] extra is installed, alongside the viewer’s own name/SMILES input and 3D builder (vibe-viewer #77). Later, the v3.0 plugin API would allow true embedding.

  • qvf. Whether a result archive may carry the 2D sketch (the .vsk document, or an SVG) that produced it, so a .qvf opened months later still shows its scheme (qvf #10). Decided in qvf v0.2.0: vendor sections carry the document, and the scheme, a preview, species identity and job sets have canonical kinds, which vibe-sketcher writes (vibe-sketcher #4).

  • qc-input-library. Use as golden fixtures; contribute generated ORCA inputs back under its naming rules.

  • vibe-queue. Nothing new for phases 1 to 3.

6. Risks

Risk

Mitigation

Ketcher’s React stack is heavy or its upgrades churn our adapter

The adapter is the only import site; the spike measures bundle size; Apache-2.0 permits pinning or forking

Indigo WebAssembly load time on first open

Lazy-load Indigo; drawing works before it arrives

2D to 3D stereo errors

CIP labels compared before and after embedding in tests; refuse to export when they differ

Multiplicity guessed wrong for metals and radicals

Always visible, always editable, never silently defaulted for d-block centres

Multi-step scheme layout is hard to make beautiful

Phase 3 only after phases 1 and 2 ship; manual placement always wins over the layout engine

vibeqc_naming returns no systematic name for many drawn molecules

The confidence badge is honest; the sketcher becomes the engine’s test bed and feeds it cases

Agents and humans overwrite each other

Revisioned documents with conflict responses from day one

7. Decisions needed from the maintainer

  1. ~~The name.~~ Decided: vibe-sketcher (section 2.5).

  2. ~~The licence.~~ Decided on 2026-10-19: MPL-2.0, matching vibe-qc, vibe-viewer and vibe-scheduler. QVF remains Apache-2.0.

  3. Go or no-go on Ketcher after the Phase 0 spike. The spike recommends go, with Ketcher 3.18.0 and its separate-WebAssembly, no-render build (docs/spike_canvas.md).

  4. ~~Hosting.~~ Decided: the private GitLab project is canonical. A public mirror under the vibe-qc organisation only follows an open-source release.

  5. ~~The contributor policy.~~ Decided on 2026-10-26 under #70: the sibling projects’ terms (MPL-2.0 plus the owner’s relicensing grant), recorded with DCO 1.1 sign-off on each outside commit and an acknowledgement in the merge request; the maintainer’s and agents’ own commits are exempt. CONTRIBUTING.md, CODE_OF_CONDUCT.md and SECURITY.md carry it. External contributions open with the public mirror (decision 4).

  6. ~~The codename scheme.~~ Approved: organic chemists with named reactions plus laboratory equipment. Dötz’s Flask is selected for 0.1.2 and later 0.1.x patches. Earlier candidate artifacts retain their historical names; the codename catalogue records the transition and the approved 0.2–1.0 assignments.

  7. ~~Browser and desktop notices.~~ Approved: retain the current Indigo WASM with its exact corresponding source and full notices, including reviewed supplements for incomplete npm distributions (docs/license.md). Builds enforce this inventory. The released 0.1.3 desktop installs Python dependencies separately; main adds a self-contained macOS Python/RDKit runtime with its notice inventory. Qualify those new packaged bytes before describing the bundle as released.

  8. ~~The CI trigger policy.~~ Current policy: full gates run once on release candidates; release publishes the qualified tree. Ordinary development, merge requests and main pushes use focused owner checks instead of full CI. Before merging, check the changed behavior and its obvious consumers, record the checks and results in the commit or merge request, and satisfy the issue’s acceptance criteria. An absent or skipped pipeline is not a passing check. The documentation, versioned-wheel and desktop-feed paths are approved in docs/release_process.md. Current sketch/compute features and complete desktop delivery define the first release scope.

  9. ~~Phase 6 versions.~~ Decided on 2026-10-27: all of Phase 6, #137 to #146, is in 0.7, beside #82. The work follows the order given under Phase 6.

Sources consulted for the engine comparison