spolvero 0.3.0__tar.gz

spolvero-0.3.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+

spolvero-0.3.0/.github/copilot-instructions.md

@@ -0,0 +1,8 @@
+# Repository Instructions
+
+For Visio handoff work, use the `spolvero` CLI or Python API. Preserve source diagrams, generate previews, produce Data Visualizer workbooks for supported Mermaid flowcharts, and keep QA reports with explicit warnings.
+
+Do not claim native Visio fidelity unless the output is actually `native`. Use `semi_native`, `vector_reference`, or `raster_reference` when appropriate.
+
+For any code change in this repo, start at [docs/agents/architecture.md](../docs/agents/architecture.md) and [docs/agents/recipes.md](../docs/agents/recipes.md). To add new engines or input types see [docs/agents/extending.md](../docs/agents/extending.md).
+

spolvero-0.3.0/.github/instructions/spolvero.instructions.md

@@ -0,0 +1,16 @@
+---
+applyTo: "**/*.{md,mmd,mermaid,puml,plantuml,dot,gv,svg,png,jpg,jpeg,pdf}"
+---
+
+# Visio Handoff
+
+Use:
+
+```bash
+spolvero build INPUT --out DIR --target data-visualizer
+```
+
+Expected outputs include `manifest.json`, `README.md`, `source/`, `normalized/`, `preview/`, `visio/`, and `qa/`.
+
+For unsupported diagrams, still preserve the source and generate preview/reference artifacts with a clear `vector_reference` or `raster_reference` editability declaration.
+

spolvero-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Compile
+        run: uv run python -m compileall src tests
+      - name: Test
+        run: uv run pytest
+      - name: CLI smoke
+        run: uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data-visualizer --title "CI Smoke"
+      - name: Assert generated artifacts
+        run: uv run python -c "import json, pathlib, zipfile; root=pathlib.Path('.tmp/ci-smoke'); manifest=json.loads((root/'manifest.json').read_text()); assert manifest['schema_version']=='1.0.0'; assert len(manifest['diagrams'])==3; assert (root/'preview/diagram-001.png').read_bytes().startswith(b'\x89PNG\r\n\x1a\n'); assert zipfile.is_zipfile(root/'visio/diagram-001-data-visualizer.xlsx')"
+

spolvero-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  pypi-publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/spolvero
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false

spolvero-0.3.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+.pytest_cache/
+pytest-cache-files-*/
+.mypy_cache/
+.ruff_cache/
+.uv-cache/
+.tmp/
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.py[cod]
+*.log
+*.bak-*
+/spolvero/
+/spolvero-*/
+/sample-output/
+/generated/
+/packages/
+.codex/

spolvero-0.3.0/AGENTS.md

@@ -0,0 +1,34 @@
+# Agent Instructions
+
+Use the Python CLI first:
+
+```bash
+spolvero build INPUT --out DIR --target package-only|data-visualizer|vsdx-template|visio-com --title TITLE
+```
+
+For source checkouts, prefer `uv run spolvero ...` or `uv run python -m spolvero.cli ...`.
+
+When producing Visio handoff packages:
+
+- Preserve original source and extracted diagram source.
+- Generate normalized IR where supported.
+- Generate previews every time.
+- Use Data Visualizer workbooks for supported flowcharts and topology/TRD inputs with recognized nodes.
+- Declare editability honestly as `native`, `semi_native`, `vector_reference`, or `raster_reference`.
+- Keep QA reports and conversion logs with explicit warnings.
+- Treat Mermaid/Markdown source as canonical unless the user explicitly chooses a Visio-first lifecycle.
+
+Do not promise perfect round-trip Visio conversion. `vsdx-template` produces a real `.vsdx` for supported flowcharts when the `[vsdx]` extra is installed and otherwise falls back with a clear warning. `visio-com` is hard-gated on Windows + Visio Plan 2 + the `[com]` extra, but the native COM body is not implemented yet; it cascades through `vsdx-template` then `data-visualizer` and must not relabel delegated output as `native`.
+
+## Coding-agent docs
+
+When modifying this codebase, start with:
+
+- [HANDOFF.md](HANDOFF.md) — latest queue, migration posture, and validation commands.
+- [docs/agents/architecture.md](docs/agents/architecture.md) — module map, data flow, engine registry, conventions.
+- [docs/agents/extending.md](docs/agents/extending.md) — how to add engines, source IRs, optional renderers, and stencil kinds.
+- [docs/agents/recipes.md](docs/agents/recipes.md) — common workflows (smoke build, force engine, custom template, debug fallbacks).
+- [docs/agents/glossary.md](docs/agents/glossary.md) — vocabulary.
+- [docs/topology-ir.md](docs/topology-ir.md) — network / TRD IR reference.
+- [docs/current-state.md](docs/current-state.md) — live status and roadmap.
+- [docs/declaratus-migration.md](docs/declaratus-migration.md) — migration readiness checklist and feature split.

spolvero-0.3.0/CLAUDE.md

@@ -0,0 +1,6 @@
+# Claude Code Instructions
+
+Follow the shared repository guidance in `AGENTS.md`.
+
+For Claude Code project skill installs, copy or symlink `adapters/claude/.claude/skills/spolvero/` into the target project and keep the CLI available with either an installed package or `uv run spolvero`.
+

spolvero-0.3.0/HANDOFF.md

@@ -0,0 +1,29 @@
+# Handoff
+
+Latest durable queue for `spolvero`.
+
+## Current State
+
+- Core goal is unchanged: package docs-as-code diagrams into Visio-friendly handoff artifacts with honest editability declarations.
+- `main` should remain ready for a fresh-history Declaratus import from the GitHub ZIP export.
+- Generated package output, local smoke packages, and external review material belong under ignored `.tmp/` or another local-only path.
+- The bundled `src/spolvero/templates/minimal_flowchart.vsdx` is the only approved tracked `.vsdx` template. It is derived from the BSD-licensed `vsdx` Python package fixture and documented in `src/spolvero/templates/LICENSE.txt`.
+
+## Migration Readiness Commands
+
+```bash
+uv run spolvero hygiene --report .tmp/migration-hygiene.md
+uv run spolvero inspect-vsdx src/spolvero/templates/minimal_flowchart.vsdx --report .tmp/minimal-flowchart-vsdx.md
+uv run pytest -rs
+uv run python -m compileall src tests
+uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data-visualizer
+uv run spolvero build tests/fixtures/sample-trd.topology.json --out .tmp/topology-json-smoke --target data-visualizer --title "Topology JSON Smoke"
+git diff --check
+```
+
+## Next Work Queue
+
+1. Keep the hygiene gate green as docs and fixtures change.
+2. Use `docs/declaratus-migration.md` as the readiness checklist before creating the Declaratus repo.
+3. Defer Declaratus-specific templates, stencils, branded scenarios, topology `.vsdx` generation, and true COM-native output until after migration.
+4. Recreate `.tmp` smoke packages in the new repo from committed fixtures instead of copying local outputs.

spolvero-0.3.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: spolvero
+Version: 0.3.0
+Summary: Package docs-as-code diagrams into Visio-friendly handoff artifacts.
+Author: Spolvero maintainers
+License: MIT
+Keywords: data-visualizer,diagram,handoff,mermaid,visio
+Requires-Python: >=3.11
+Provides-Extra: com
+Requires-Dist: pywin32>=306; (platform_system == 'Windows') and extra == 'com'
+Provides-Extra: topology
+Requires-Dist: pyyaml>=6.0; extra == 'topology'
+Provides-Extra: vsdx
+Requires-Dist: vsdx>=0.5; extra == 'vsdx'
+Description-Content-Type: text/markdown
+
+# Spolvero
+
+`spolvero` turns docs-as-code diagrams into a Visio handoff package with preserved source, normalized IR, SVG/PNG previews, Data Visualizer workbooks for Mermaid flowcharts and topology inputs, QA reports, and explicit editability declarations.
+
+The package treats source diagrams as canonical unless a project deliberately moves to a Visio-first workflow. Native Visio generation is intentionally conservative: the Data Visualizer workbook is the default cross-platform path, the `vsdx-template` engine produces a real `.vsdx` when the `[vsdx]` extra is installed, and `visio-com` currently probes Windows/Visio availability before cascading to downstream engines. Every engine records fallback downgrades in the manifest; `native` is reserved for future COM-created shapes/connectors.
+
+See [docs/using-the-package.md](docs/using-the-package.md) for what to do with the handoff folder once it has been generated.
+
+## Quick Start
+
+```bash
+spolvero build input.md --out ./handoff --target data-visualizer
+```
+
+From a checkout without installation:
+
+```bash
+uv run spolvero build tests/fixtures/sample.md --out .tmp/sample-output --target data-visualizer
+```
+
+Python usage:
+
+```python
+from pathlib import Path
+
+from spolvero import build_package
+
+build_package(Path("input.md"), Path("handoff"), "data-visualizer", title="Review")
+```
+
+## Repository Layout
+
+- `src/spolvero/`: neutral Python library and CLI.
+- `src/spolvero/schemas/`: versioned manifest and IR schemas.
+- `skills/codex/spolvero/`: Codex-installable skill bundle generated from canonical docs and wrappers.
+- `adapters/`: Claude Code, GitHub Copilot, and generic agent install notes/instruction files.
+- `tests/`: pytest coverage for extraction, Mermaid parsing, schemas, artifacts, adapters, and CLI smoke builds.
+
+## Validation
+
+```bash
+uv run pytest
+uv run python -m compileall src tests
+uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data-visualizer
+```
+
+Generated packages are intentionally ignored by git.
+
+Migration hygiene checks are also available:
+
+```bash
+uv run spolvero hygiene --report .tmp/migration-hygiene.md
+uv run spolvero inspect-vsdx src/spolvero/templates/minimal_flowchart.vsdx --report .tmp/minimal-flowchart-vsdx.md
+```
+
+See [docs/declaratus-migration.md](docs/declaratus-migration.md) for the fresh-history Declaratus import checklist.
+
+## Optional Extras
+
+The core install is stdlib-only. Each extra unlocks one optional engine or input format and is feature-detected at runtime so it never blocks the default path.
+
+```bash
+pip install spolvero            # stdlib-only default
+pip install 'spolvero[vsdx]'     # vsdx-template engine (cross-platform)
+pip install 'spolvero[topology]' # YAML topology inputs (PyYAML)
+pip install 'spolvero[com]'      # visio-com engine (Windows + Visio Plan 2)
+```
+
+A Mermaid CLI (`mmdc`) on `PATH` is auto-detected for higher-fidelity Mermaid previews. Set `SPOLVERO_DISABLE_MMDC=1` to force the built-in renderer.
+
+## Targets and Editability
+
+| Target | Engine | Flowchart editability | Notes |
+|---|---|---|---|
+| `package-only` | `internal_preview` | `vector_reference` | Skips workbook generation. Even Mermaid flowcharts and topology IRs are downgraded to a vector reference because no Visio handoff artifact is produced. |
+| `data-visualizer` | `data_visualizer_xlsx` | `semi_native` | Default semi-native path. Generates a Visio Data Visualizer workbook for supported Mermaid flowcharts and topology IRs with recognized nodes. Empty/failed topology parses are downgraded to reference previews with no empty workbook. |
+| `vsdx-template` | `vsdx_template_mutation` | `semi_native` (real `.vsdx`) | Mutates a template via the [`vsdx`] extra to produce a real `.vsdx` for supported flowcharts. Use `--template PATH` to override the bundled template. Unsupported inputs and missing extras/templates cascade with clear warnings. |
+| `visio-com` | `visio_com_automation` | delegated output editability | Probes Visio Plan 2 / Professional via COM (Windows + [`com`] extra), then currently delegates through `vsdx-template` and `data-visualizer`. A future true COM-native path will be the only source of `native` output. |
+
+The manifest always records both `requested_engine` and `actual_engine` so engine fallbacks are visible without parsing warning strings.
+
+## Inputs
+
+- Mermaid flowchart (`.mmd`, fenced ` ```mermaid ` in Markdown) — primary input; full IR + workbook.
+- Mermaid sequence diagrams, PlantUML, Graphviz DOT, SVG, PNG, JPG, PDF — packaged as references with previews.
+- Topology: `*.topology.yaml`, `*.topology.yml`, `*.topology.json`, or fenced ` ```topology ` blocks. Raw source accepts node-level `container` and `containers[].members`; normalized IR resolves memberships into node `container`. Stencil kinds: `router`, `switch`, `firewall`, `load_balancer`, `server`, `database`, `storage`, `client`, `cloud`, `internet`, `application`, `service`, `actor`, `datastore`, `external_system`. Container kinds: `subnet`, `zone`, `region`, `environment`, `vpc`, `system`, `boundary`.
+
+## The name
+
+Spolvero (Italian, *spol-VEH-roh*) is the Renaissance pouncing technique: an artist pricks holes along the lines of a finished drawing, then dusts pigment through them to transfer the design onto a wall or panel. The pricked cartoon is a deliberate intermediate — made for transfer, distinct from the original. This tool works the same way: it produces a transfer-ready rendering of a source diagram for the Visio surface, while the source stays canonical.

spolvero-0.3.0/README.md

@@ -0,0 +1,90 @@
+# Spolvero
+
+`spolvero` turns docs-as-code diagrams into a Visio handoff package with preserved source, normalized IR, SVG/PNG previews, Data Visualizer workbooks for Mermaid flowcharts and topology inputs, QA reports, and explicit editability declarations.
+
+The package treats source diagrams as canonical unless a project deliberately moves to a Visio-first workflow. Native Visio generation is intentionally conservative: the Data Visualizer workbook is the default cross-platform path, the `vsdx-template` engine produces a real `.vsdx` when the `[vsdx]` extra is installed, and `visio-com` currently probes Windows/Visio availability before cascading to downstream engines. Every engine records fallback downgrades in the manifest; `native` is reserved for future COM-created shapes/connectors.
+
+See [docs/using-the-package.md](docs/using-the-package.md) for what to do with the handoff folder once it has been generated.
+
+## Quick Start
+
+```bash
+spolvero build input.md --out ./handoff --target data-visualizer
+```
+
+From a checkout without installation:
+
+```bash
+uv run spolvero build tests/fixtures/sample.md --out .tmp/sample-output --target data-visualizer
+```
+
+Python usage:
+
+```python
+from pathlib import Path
+
+from spolvero import build_package
+
+build_package(Path("input.md"), Path("handoff"), "data-visualizer", title="Review")
+```
+
+## Repository Layout
+
+- `src/spolvero/`: neutral Python library and CLI.
+- `src/spolvero/schemas/`: versioned manifest and IR schemas.
+- `skills/codex/spolvero/`: Codex-installable skill bundle generated from canonical docs and wrappers.
+- `adapters/`: Claude Code, GitHub Copilot, and generic agent install notes/instruction files.
+- `tests/`: pytest coverage for extraction, Mermaid parsing, schemas, artifacts, adapters, and CLI smoke builds.
+
+## Validation
+
+```bash
+uv run pytest
+uv run python -m compileall src tests
+uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data-visualizer
+```
+
+Generated packages are intentionally ignored by git.
+
+Migration hygiene checks are also available:
+
+```bash
+uv run spolvero hygiene --report .tmp/migration-hygiene.md
+uv run spolvero inspect-vsdx src/spolvero/templates/minimal_flowchart.vsdx --report .tmp/minimal-flowchart-vsdx.md
+```
+
+See [docs/declaratus-migration.md](docs/declaratus-migration.md) for the fresh-history Declaratus import checklist.
+
+## Optional Extras
+
+The core install is stdlib-only. Each extra unlocks one optional engine or input format and is feature-detected at runtime so it never blocks the default path.
+
+```bash
+pip install spolvero            # stdlib-only default
+pip install 'spolvero[vsdx]'     # vsdx-template engine (cross-platform)
+pip install 'spolvero[topology]' # YAML topology inputs (PyYAML)
+pip install 'spolvero[com]'      # visio-com engine (Windows + Visio Plan 2)
+```
+
+A Mermaid CLI (`mmdc`) on `PATH` is auto-detected for higher-fidelity Mermaid previews. Set `SPOLVERO_DISABLE_MMDC=1` to force the built-in renderer.
+
+## Targets and Editability
+
+| Target | Engine | Flowchart editability | Notes |
+|---|---|---|---|
+| `package-only` | `internal_preview` | `vector_reference` | Skips workbook generation. Even Mermaid flowcharts and topology IRs are downgraded to a vector reference because no Visio handoff artifact is produced. |
+| `data-visualizer` | `data_visualizer_xlsx` | `semi_native` | Default semi-native path. Generates a Visio Data Visualizer workbook for supported Mermaid flowcharts and topology IRs with recognized nodes. Empty/failed topology parses are downgraded to reference previews with no empty workbook. |
+| `vsdx-template` | `vsdx_template_mutation` | `semi_native` (real `.vsdx`) | Mutates a template via the [`vsdx`] extra to produce a real `.vsdx` for supported flowcharts. Use `--template PATH` to override the bundled template. Unsupported inputs and missing extras/templates cascade with clear warnings. |
+| `visio-com` | `visio_com_automation` | delegated output editability | Probes Visio Plan 2 / Professional via COM (Windows + [`com`] extra), then currently delegates through `vsdx-template` and `data-visualizer`. A future true COM-native path will be the only source of `native` output. |
+
+The manifest always records both `requested_engine` and `actual_engine` so engine fallbacks are visible without parsing warning strings.
+
+## Inputs
+
+- Mermaid flowchart (`.mmd`, fenced ` ```mermaid ` in Markdown) — primary input; full IR + workbook.
+- Mermaid sequence diagrams, PlantUML, Graphviz DOT, SVG, PNG, JPG, PDF — packaged as references with previews.
+- Topology: `*.topology.yaml`, `*.topology.yml`, `*.topology.json`, or fenced ` ```topology ` blocks. Raw source accepts node-level `container` and `containers[].members`; normalized IR resolves memberships into node `container`. Stencil kinds: `router`, `switch`, `firewall`, `load_balancer`, `server`, `database`, `storage`, `client`, `cloud`, `internet`, `application`, `service`, `actor`, `datastore`, `external_system`. Container kinds: `subnet`, `zone`, `region`, `environment`, `vpc`, `system`, `boundary`.
+
+## The name
+
+Spolvero (Italian, *spol-VEH-roh*) is the Renaissance pouncing technique: an artist pricks holes along the lines of a finished drawing, then dusts pigment through them to transfer the design onto a wall or panel. The pricked cartoon is a deliberate intermediate — made for transfer, distinct from the original. This tool works the same way: it produces a transfer-ready rendering of a source diagram for the Visio surface, while the source stays canonical.

spolvero-0.3.0/adapters/claude/.claude/skills/spolvero/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: spolvero
+description: Build Visio handoff packages from Mermaid, Markdown diagram fences, PlantUML, Graphviz/DOT, or reference artifacts with source preservation, previews, normalized IR, Data Visualizer workbooks, QA reports, and editability declarations.
+---
+
+# Spolvero
+
+Use the neutral CLI:
+
+```bash
+spolvero build input.md --out ./spolvero --target data-visualizer
+```
+
+For source checkouts:
+
+```bash
+uv run spolvero build input.md --out ./spolvero --target data-visualizer
+```
+
+Core rules:
+
+- Preserve the original input and extracted diagram source.
+- Generate previews every time.
+- Generate normalized IR where supported.
+- Use Data Visualizer workbooks for Mermaid flowcharts and topology/TRD inputs with recognized nodes when semi-native Visio handoff is requested.
+- Never promise perfect round-trip conversion.
+- Declare editability as `native`, `semi_native`, `vector_reference`, or `raster_reference`.
+- Tell the user which artifact to open first and whether durable edits belong in source or only in Visio.
+
+Optional extras (default install is stdlib-only):
+
+- `[vsdx]` enables the cross-platform `vsdx-template` engine (real `.vsdx` output).
+- `[topology]` enables YAML topology / TRD inputs.
+- `[com]` enables the Windows-only `visio-com` probe path; current output delegates downstream and preserves delegated editability.
+
+The manifest always records `requested_engine` and `actual_engine`; report fallbacks honestly.
+

spolvero-0.3.0/adapters/claude/CLAUDE.md

@@ -0,0 +1,12 @@
+# Claude Code Project Instructions
+
+Follow the shared agent guidance in `AGENTS.md` when present. For Visio handoff work, use the `spolvero` CLI and keep source diagrams canonical unless the user explicitly asks for a Visio-first lifecycle.
+
+The supported command shape is:
+
+```bash
+spolvero build INPUT --out DIR --target package-only|data-visualizer|vsdx-template|visio-com --title TITLE
+```
+
+Declare editability as `native`, `semi_native`, `vector_reference`, or `raster_reference`, and call out any manual Visio review that remains.
+

spolvero-0.3.0/adapters/claude/INSTALL.md

@@ -0,0 +1,21 @@
+# Claude Code Adapter Install
+
+Copy or symlink this adapter into a project that uses Claude Code project skills:
+
+```bash
+cp -R adapters/claude/.claude ./
+cp adapters/claude/CLAUDE.md ./CLAUDE.md
+```
+
+Keep the CLI available with an installed package:
+
+```bash
+uv tool install .
+```
+
+Or run from a checkout:
+
+```bash
+uv run spolvero build input.md --out spolvero --target data-visualizer
+```
+

spolvero-0.3.0/adapters/copilot/.github/copilot-instructions.md

@@ -0,0 +1,8 @@
+# Repository Instructions
+
+For Visio handoff work, use the `spolvero` CLI or Python API. Preserve source diagrams, generate previews, produce Data Visualizer workbooks for supported Mermaid flowcharts, and keep QA reports with explicit warnings.
+
+Do not claim native Visio fidelity unless the output is actually `native`. Use `semi_native`, `vector_reference`, or `raster_reference` when appropriate.
+
+Optional extras unlock additional engines: `[vsdx]` for the cross-platform `vsdx-template` engine, `[topology]` for YAML topology / TRD inputs, and `[com]` for the Windows-only `visio-com` engine. The default install is stdlib-only and always works.
+

spolvero-0.3.0/adapters/copilot/.github/instructions/spolvero.instructions.md

@@ -0,0 +1,16 @@
+---
+applyTo: "**/*.{md,mmd,mermaid,puml,plantuml,dot,gv,svg,png,jpg,jpeg,pdf}"
+---
+
+# Visio Handoff
+
+Use:
+
+```bash
+spolvero build INPUT --out DIR --target data-visualizer
+```
+
+Expected outputs include `manifest.json`, `README.md`, `source/`, `normalized/`, `preview/`, `visio/`, and `qa/`.
+
+For unsupported diagrams, still preserve the source and generate preview/reference artifacts with a clear `vector_reference` or `raster_reference` editability declaration.
+

spolvero-0.3.0/adapters/copilot/INSTALL.md

@@ -0,0 +1,11 @@
+# GitHub Copilot Adapter Install
+
+Copy these files into a repository that should expose Visio handoff guidance to GitHub Copilot:
+
+```bash
+cp adapters/copilot/.github/copilot-instructions.md .github/copilot-instructions.md
+cp adapters/copilot/.github/instructions/spolvero.instructions.md .github/instructions/spolvero.instructions.md
+```
+
+Keep `AGENTS.md` in the repository root for generic agent compatibility.
+

spolvero-0.3.0/adapters/generic/AGENTS.md

@@ -0,0 +1,19 @@
+# Generic Agent Adapter
+
+This adapter is CLI-first and product-neutral.
+
+```bash
+spolvero build INPUT --out DIR --target package-only|data-visualizer|vsdx-template|visio-com --title TITLE
+```
+
+Rules:
+
+- Preserve original source and extracted source.
+- Generate preview artifacts every time.
+- Generate normalized IR for supported diagrams.
+- Use Data Visualizer workbooks for supported Mermaid flowcharts and topology/TRD inputs with recognized nodes.
+- Record warnings and manual review steps in QA output.
+- Declare editability as `native`, `semi_native`, `vector_reference`, or `raster_reference`.
+- Do not invent product-specific API integration without a concrete harness contract.
+
+Optional extras (default install is stdlib-only): `[vsdx]` for the cross-platform `vsdx-template` engine, `[topology]` for YAML topology/TRD inputs, `[com]` for the Windows-only `visio-com` probe path. Current `visio-com` output delegates downstream and must preserve delegated editability.

spolvero-0.3.0/docs/agent-usage.md

@@ -0,0 +1,17 @@
+# Agent Usage
+
+This project is harness-neutral. The reliable contract is the CLI and Python entrypoint:
+
+```bash
+spolvero build INPUT --out DIR --target data-visualizer --title "Package title"
+```
+
+```python
+from spolvero import build_package
+
+build_package("input.md", "spolvero", "data-visualizer", title="Package title")
+```
+
+Adapters in `adapters/` provide thin instruction files for Codex, Claude Code, GitHub Copilot, and generic agents. No product-specific API integration is included until a concrete harness contract is available.
+
+Always tell users which generated artifact to open first and whether durable edits should go back to source or live only in Visio.