Fábio Coutada
eed5e3d468
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.
87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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'))"
|
|
```
|
|
|
|
## Related repos in the fleet
|
|
|
|
- `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
|