Fábio Coutada eed5e3d468 feat: Aurélio Embroidery — the first art of the Omniscient Replica

Initial commit with:
- README.md: vision, philosophy, roadmap — from artisans to AI
- AGENTS.md: agent guide for the embroidery subsystem
- vendor-registry/registry.yaml: 14 vendors, 40+ formats, universal bridge reference
- Submodules: FlashFloppy (hw/), pyembroidery (lib/), libembroidery (lib/)

The universal embroidery machine bridge. Open-source digitizing,
machine control, and the tools to set textile creation free.

2026-08-09 01:41:34 +01:00

3.3 KiB

Raw Permalink Blame History

Aurélio Embroidery — Agent Guide

The embroidery subsystem of the Portugal Futurista platform. This repo holds the universal vendor bridge, MCP server, IDE plugins, and all knowledge needed to connect any embroidery machine to the Aurélio fleet.

Repository layout

Path	What	Language/Toolchain
`README.md`	Vision, philosophy, roadmap	—
`AGENTS.md`	This file — agent instructions	—
`vendor-registry/`	Machine vendor database (formats, connectivity, hacks)	YAML
`mcp/`	Aurélio Embroidery MCP server	Python, FastMCP
`plugins/desktop/`	Aurélio Desktop IDE plugin	TypeScript
`plugins/web/`	Aurélio Web IDE plugin	TypeScript
`hardware/universal-bridge/`	ESP32/RPi bridge firmware	C, ESP-IDF
`hw/flashfloppy/`	FlashFloppy submodule	C
`lib/pyembroidery/`	Python embroidery library submodule	Python
`lib/libembroidery/`	C embroidery library submodule	C
`lib/inkstitch/`	Ink/Stitch Inkscape extension submodule	Python
`lib/embroidermodder/`	Embroidermodder 2 submodule	C++, Qt

Philosophy

Every submodule added to this repo must be accompanied by a clear statement of why it matters — what philosophy or grand dream for society made us include it. The README.md serves as that statement. When adding new submodules, update README.md with the same pattern: one heading, one paragraph of context, one paragraph of why.

Submodule management

Submodules are pinned to specific commits. To update:

# Update all submodules to latest remote
git submodule update --remote

# Update a specific submodule
cd lib/pyembroidery && git pull origin main && cd ../..
git add lib/pyembroidery && git commit -m "chore(submodule): update pyembroidery"

Vendor registry

vendor-registry/registry.yaml is the single source of truth for all known embroidery machines. Each entry declares:

vendor: manufacturer name
models: list of model names/patterns
format: native stitch format(s)
media: how designs get into the machine (floppy, card, usb, serial, network)
interface: electrical interface type (ibmpc, shugart, custom)
jumpers: Gotek jumper configuration for floppy emulation
hacks: known community modifications
notes: quirks, gotchas, references

MCP server

The MCP server (mcp/server.py) exposes embroidery tools to the Aurélio fleet:

embroidery_convert — convert between any supported formats
embroidery_machines — list known machines from vendor registry
embroidery_preview — generate stitch preview (PNG/SVG)
embroidery_send — push design to a connected machine
embroidery_formats — list supported formats with read/write capabilities

Built on FastMCP. Loads vendor registry at startup. Uses pyembroidery for all format operations.

Build & test

# MCP server
cd mcp
pip install -r requirements.txt
python server.py

# Vendor registry validation
python -c "import yaml; yaml.safe_load(open('vendor-registry/registry.yaml'))"

replica-omnisciente/ — parent monorepo, contains this repo's context
aurelio-backend-native/ — C23/C++23 backend, may host native digitizing engine
infra/ — CDP bridge, lab gateway for hardware access

3.3 KiB Raw Permalink Blame History