# Codex Visio Replica

> **Public Beta — v0.3.0-beta.2 · Windows only**

Codex Visio Replica is a local-first toolkit for rebuilding a supplied reference
image as editable Microsoft Visio shapes. It combines two Model Context Protocol
(MCP) servers, Visio COM/ShapeSheet rendering, a reusable Codex Skill, resumable
large-Scene execution, and measurable visual QA.

This is an unofficial community project and is not affiliated with, endorsed by,
or sponsored by Microsoft or OpenAI.

## Architecture

```mermaid
flowchart LR
    A["User-provided reference image"] --> B["visual-qa MCP"]
    B --> C["Validated Scene JSON"]
    C --> D["visio-com MCP"]
    D --> E["Editable Visio document"]
    E --> F["Local export"]
    F --> B
    G["visio-image-replica Skill"] --> B
    G --> C
    G --> D
```

All image analysis and QA run locally. Visio drawing state is owned by a
server-created COM session on a single STA worker.

## Features

- Editable shapes, text, connectors, groups, layers, and ShapeSheet cells.
- A JSON Schema-backed Scene contract with explicit coordinates and styles.
- Local-only image probing, bbox measurement, edge metrics, SSIM, pixel error,
  overlays, and difference heatmaps.
- Transactional rendering with overwrite disabled by default.
- Resumable, dependency-aware chunked rendering for large Scenes.
- A reusable `visio-image-replica` Skill with structural-first acceptance gates.
- Deterministic synthetic examples that contain no user or research data.

## Requirements

- Windows 10 or Windows 11 x64.
- Microsoft Visio desktop, installed and licensed separately by the user.
- CPython 3.11 or 3.12 x64.
- [uv](https://docs.astral.sh/uv/).
- Codex with MCP and Skill support.
- GitHub CLI is required only for release maintainers.

This project does not distribute Visio, Codex, Microsoft binaries, fonts, or
commercial stencils.

## Installation

Review [INSTALL.md](INSTALL.md), then run a no-change preflight:

```powershell
.\installer\install.ps1 -DryRun
```

After reviewing the JSON result, install without elevation:

```powershell
.\installer\install.ps1
```

The installer refuses to overwrite an existing installation, backs up affected
Codex configuration, rolls back on failure, and performs MCP and Skill checks.

## Quick start

1. Place a reference image inside the configured workspace input directory.
2. Start a Codex task from the installed project root.
3. Invoke `$visio-image-replica` and request an editable VSDX.
4. Review unresolved text, fonts, structure, and QA metrics before delivery.

The Skill never treats an embedded page-sized bitmap as an editable
reconstruction.

## Examples

- `examples/simple-flowchart`: generic start/process/decision flowchart.
- `examples/synthetic-gnn-diagram`: invented nodes and message-passing blocks.

Each example includes generation code, a Scene, a deterministic preview PNG, and
regeneration instructions. No third-party logo, institution, paper layout, or
real dataset is used.

## MCP architecture

`visual-qa-mcp` owns local raster inspection and measurable comparisons.
`visio-com-mcp` owns server-created Visio sessions and editable document state.
Both enforce workspace allowlists, reject unsafe file types, and expose annotated
MCP tools over STDIO.

## Skill workflow

The Skill runs preflight, reference analysis, Scene validation, Visio rendering,
structural QA, connector QA, visual QA, evidence-based iteration, font checks,
and guarded packaging. Structure and editability take precedence over one image
similarity score.

## Large Scene rendering

Large Scenes use dependency planning, bounded batches, checkpoints, and
resume-validation. A timed-out monolithic render is not retried unchanged.
Completed batches are preserved only when Scene, document, version, and shape
identity evidence remains consistent.

## QA metrics

The public API includes bbox errors, text/type checks, connector endpoints and
Glue semantics, Edge F1/IoU, SSIM, pixel MAE/RMSE, and generated overlays. These
metrics are evidence, not a guarantee of pixel-perfect reconstruction.

## Security model

- Windows-only COM control on one STA worker.
- Only `Visio.Application` is allowed; macro-enabled VSDM and arbitrary ProgIDs
  are rejected.
- User paths must stay inside configured roots.
- Overwrite is opt-in and never the default.
- The server tracks and cleans up only processes and documents it owns.
- Reference images, generated diagrams, logs, and credentials are excluded from
  source control.

See [SECURITY.md](SECURITY.md) and [docs/security-audit.md](docs/security-audit.md).

## Limitations

- Requires locally installed Microsoft Visio; macOS and Linux cannot run the
  Visio COM server.
- Does not guarantee absolute pixel identity or reliable recovery of illegible
  text.
- Complex freeforms, routing, fonts, and antialiasing can require iteration.
- Real Visio integration tests run only in a maintainer-controlled local
  Windows+Visio environment, not on public GitHub-hosted runners.

## Roadmap

- Harden rollback and repair telemetry.
- Expand synthetic Scene coverage.
- Improve connector and freeform diagnostics.
- Add reproducible package signing when a public signing identity is available.

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md). Do not attach private diagrams,
credentials, or customer data to public issues.

## License and trademarks

Source code is licensed under [Apache-2.0](LICENSE). Dependency notices are in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Microsoft, Microsoft Visio, Windows, OpenAI, Codex, GitHub and related marks are
trademarks of their respective owners. Their names are used only to describe
interoperability and requirements.