# MoleculeFit AI User Manual

This document is the canonical in-app manual source. It describes the current repository and connected API, not a roadmap.

## A. Introduction

MoleculeFit AI is a peptide-first computational molecular research workstation. It connects a research question to target, protein, structure, binding-site, molecule, asynchronous computation, and analysis records. The product organizes computational hypotheses; it is not a clinical decision system.

The evidence-first philosophy is operational: records retain project scope, structure and molecule identity, execution mode, engine metadata, job lifecycle, provenance, and evidence classification when the backend supplies them. A computed result is not an experimental fact. A prediction does not prove binding, affinity, efficacy, selectivity, safety, or clinical success.

## B. Getting Started

The current deployment has no authentication or user-account model. The API therefore cannot safely provide login, logout, password reset, account roles, or user-level project ownership. Do not treat an accessible project list as authenticated access. Project scoping is a separate data concern from authentication and is not strengthened by a client-only login screen.

Open Home for the workflow overview. Projects creates computational cases. The left rail links to implemented targets, molecules, structures, jobs, results, library, evidence, comparison, tools, and preferences. Preferences stores only browser-local project scope and theme selection.

## C. First Workflow

Create a case, import or select a target, inspect available protein and structure records, select a chain and define a binding site, register a molecule, submit a supported job, and use Job Monitor to follow REQUESTED, QUEUED, PREPARING, RUNNING, ANALYSING, and terminal states. Open a result only after the API reports it available. Read provenance and evidence labels before using a result as a research hypothesis.

## D. Workspace guide

### Home and Projects

Home is the scientific landing surface and workflow map. Projects lists and creates cases through the project API. Project detail is the closest place to review the case and its jobs.

### Targets, Molecules, Peptides, Structures

Targets, Molecules, Peptides, and Structures are API-backed workspaces. Structures includes metadata and the Structure Viewer route where a real structure is available. The Peptides workspace is project-scoped and has a peptide list and a peptide page showing identity, sequence, the deterministic descriptor set (COMPUTED_RESULT), the ML representation specification, human-requested predictions (MODEL_PREDICTION, applicability domain NOT ASSESSED) and provenance. Current peptide models are development models; a prediction is a computational model output, never an experimental measurement.

### Computations, Results, Library

Computations and Job Monitor point to the jobs workspace. Results opens persisted job result views. Library exposes available records and stored artifact metadata; object storage is deployment-dependent and must not be assumed.

### Tools

Structure Viewer and Binding-Site Editor are implemented routes. Sequence Tools and Molecule Builder are planned and have no operational screen. Use the molecule and structure workspaces as the current workaround; do not infer that a planned tool exists.

### Evidence, comparison, and reports

Evidence & Literature, Compare Results, and the shadow-mode Compute Orchestrator are available routes backed by current APIs. Reports & Exports is not an operational export center in this deployment. Use the manual download and browser print actions for documentation; PDF, DOCX, and XLSX generation is not claimed without installed generators and a verified data contract.

### Profile, Team, API, Preferences

Profile, Team, and API are unavailable because there is no authentication or account model. Preferences is available for browser-local scope and theme settings. Browser-local preferences do not provide security or project isolation.

## E. Molecular concepts

A structure is a deposited or imported coordinate record with identity and metadata. A chain is a selected polymer component. A binding site is a coordinate definition, not a demonstrated biological pocket. A molecule identity is the canonical chemical record; a pose is one computed placement of that identity. Interactions are observations derived from coordinates and rules, not experimental measurements.

Keep identity separate from pose. Two poses can belong to one molecule, and identical-looking names do not establish chemical identity. Check canonical SMILES, registry identifiers when present, structure checksum, chain, coordinates, and provenance.

## F. Computation guide

Jobs are asynchronous. The job lifecycle is persisted rather than estimated: requested, queued, preparing, running, analysing, completed or failed. A fixture execution is a demonstration/test path and must remain labeled as such. A real execution must state the engine, model/version, execution mode, inputs, parameters, timestamps, and provenance available from the API.

Logs are operational evidence of execution, not proof that a scientific hypothesis is correct. Failed jobs are not completed jobs. Results must not be reconstructed from a missing artifact or an unavailable provider.

## G. Results interpretation

Docking score is an engine score, not Kd. A CNN score is a model-derived score, not experimental affinity. DiffDock confidence is a model confidence signal, not demonstrated binding. Boltz native metrics describe that model's output and limitations, not biological truth. RMSD is a geometric difference and not biological correctness. Interaction maps summarize computed geometry.

Consensus can identify agreement or disagreement among computed outputs, but consensus is not proof. Confidence is not demonstrated binding. Uncertainty should guide follow-up and triage. Every metric must be read with its units, engine, model/version, execution mode, evidence classification, and provenance.

## H. Using results practically

Use results to shortlist candidates for further review, compare poses under the same defined inputs, identify disagreement, inspect missing provenance, and design orthogonal follow-up. Do not rank candidates as clinically effective or call a score an affinity measurement. Preserve alternative poses and failed runs; deleting inconvenient outputs destroys traceability.

## I. Experimental follow-up

The platform can organize hypotheses and, where the API provides it, experimental-result records and descriptive calibration. It does not perform experiments, validate assays, calibrate a model automatically, or make clinical decisions. A sensible follow-up records assay identity, conditions, controls, replicate structure, and the relationship between the experimental observation and the prior computational hypothesis.

## J. Evidence and provenance

The application distinguishes experimental fact, computed result, model prediction, derived result, research hypothesis, and demo/simulated result. Classification is meaningful only when supported by the record. Provenance should identify inputs, engine/model version, parameters, execution mode, timestamp, and checksum or artifact reference where available.

## K. Artifact library

An artifact record and a stored binary are different. PostgreSQL remains the canonical record store; large binaries may be in configured GCS object storage. The shell reports storage availability from the API and never assumes it. Downloads must remain project-scoped, preserve checksums, and never include credentials or secrets.

## L. Troubleshooting

If a structure or molecule is missing, verify the project scope and API status before creating a duplicate. If a binding site is invalid, check chain identity, coordinate dimensions, and receptor preparation metadata. A stuck or failed job needs its persisted status and logs; do not infer completion from elapsed time. An unavailable engine means the provider is unavailable, not that a fixture result is equivalent. Browser limits affect large downloads and local storage; use the API artifact status and a supported browser.

## M. Reproducible examples

The repository contains verified fixtures and test records, including a GNINA fixture pose file and an analysis fixture structure. These are reproducibility fixtures, not claims about a real EGFR/erlotinib, TRPV1, or other project result. A real example must be run against an available API provider and cited with its returned project, structure, molecule, job, engine, version, and provenance. This manual intentionally does not fabricate those outputs.

## N. Scientific safety and limitations

Repeat the evidence boundary at every handoff: computational prediction is not experimental affinity; a score is not Kd; confidence is not binding; consensus is not proof; RMSD is not correctness. Models and engines have domain limits, input sensitivity, and failure modes. Results require expert review and experimental validation before biological or translational decisions.

## Capability matrix

The authoritative matrix is maintained at `docs/CAPABILITY_MATRIX.md` and is included in this manual's repository release. It records frontend status, backend support, API, data model, real/planned state, and limitations. The in-app viewer serves this deployable copy; `docs/user-manual/MoleculeFit_AI_User_Manual.md` is a separate repository reference and is not synchronized automatically, so update both manually where shared behavior changes.