monkey-w1n5t0n 9ad1f78ddd docs: the specs disposition pass (plan §8)

Roughly 20k lines were deleted from this repo in the last week and much of the
corpus still described the pre-deletion world in the present tense. Executes
the §8 table: archive the retired, reclassify the executed, prune the stale.

  aimmersive-clone-spec      -> _archive/ with a deprecated-by note
  feedback-modes-port-spec   -> plans/, kind: plan, status: executed
  manifold-parity-features   -> plans/, kind: plan, status: active
  playground-2.0-rewrite     -> status: superseded
  engine-architecture        434 -> ~120 lines; seam + spine kept, rewritten
                             present-tense against the shipped engine/
  MAIN.md                    six contradicted claims fixed; registry resynced
  vcv-module.md              pruned to the current 8->16 contract and made the
                             single .nisps format spec
  vcv/NISPS-FORMAT.md        DELETED — documented a v1 format that no longer loads
  vcv/README.md, BUILDING.md rewritten to the real contract, menu, OSC table
  inputs/backends/dock trio  grounding sections marked historical, dead cites fixed

Two rows of the §8 table were themselves wrong, corrected here: the deleted
full-state sync lives in backends-spec.md §6.3, not vcv-module.md (which has no
§6.3), and codegen/README.md was already a MAP pointer with no port-solidjs
trigger left to remove.

Beyond the table — found by sweeping every backticked path in the changed docs
against `git ls-files`, which is how these should have been caught before:

  manifold/ONBOARDING.md documented a UI that Phase 1 deleted, as if current:
  SplitStage, ReadoutStrip, InputMini, BackendAdvanced, AltitudeNav, and a
  shot.spec.ts that does not exist. The whole stage table was keyed on a `focus`
  axis that no longer exists — selection is now sandwich > particles >
  composite. This matters more than the rest: CLAUDE.md tells every agent to
  read ONBOARDING.md first for Manifold work, so it was actively teaching a
  fiction. Rewritten against ConsoleApp.tsx.

  MAP.md claimed the input layer reduces axes to the engine arity with an
  "even/odd blend". input-layer.ts says the opposite in its own header: one
  dedicated slot per axis, 1:1, into a 32-input over-provisioned head, and
  mean-blending was removed deliberately because it diluted every source.

  AGENT-REFERENCE.md still promised TS emission "returns at P5" (landed),
  per-mode dims "become schema-real at P5" (landed at P5.3), and pointed at
  nisps::FixedBuffer (deleted).

Doc-right/code-suspect, filed rather than fixed: VCV computes derivedMean/Std/
Delta and cachedNovelty behind a live context-menu toggle that nothing reads;
vcv/plugin.json points at the MusicallyEmbodiedML org rather than this repo's
origin; and the module defaults to UDP 7001+id%64 while bridge.ts defaults to
9000, so out of the box they do not meet.

Firmware-build docs are deliberately untouched — the PlatformIO migration
lands next and rewrites all of them.

2026-07-21 20:17:58 +02:00

2.9 KiB

Raw Permalink Blame History

Building MEMLNaut VCV Plugin

Distribution & cross-platform builds: for packaging .vcvplugin files, the cross-platform CI matrix, and publishing to /next/vcv, see DISTRIBUTION.md. The official make dist target (from the SDK's plugin.mk) produces dist/<slug>-<version>-<platform>.vcvplugin.

Prerequisites

VCV Rack 2 SDK — download from https://vcvrack.com/manual/PluginDevelopmentTutorial or build from source
C++20 compiler — GCC 10+, Clang 11+, or MSVC 19.29+ (required by the nisps/ core for std::span and concepts)
GNU Make

Build Steps

# 1. Set the SDK path (adjust to your installation)
export RACK_DIR=/path/to/Rack-SDK

# 2. Build the plugin
cd vcv
make

# This produces plugin.so (Linux), plugin.dylib (macOS), or plugin.dll (Windows)

The Makefile adds -std=c++20; the shared nisps/ core is reached via relative ../../nisps/… includes from src/ (no extra -I). The VCV SDK's default -std=c++11 flag is filtered out to avoid conflicts.

Local Installation

# Option A: use the SDK's install target
make install
# Copies the plugin to ~/.local/share/Rack2/plugins-lin/ (or platform equivalent)

# Option B: manual symlink (useful during development)
ln -s $(pwd) ~/.local/share/Rack2/plugins-lin/MEMLNaut

After installing, restart VCV Rack (or use the module browser refresh if available). The MEMLNaut module appears in the module browser.

Distribution Packaging

# Build and package a .vcvplugin (SDK plugin.mk target)
make dist

# Output: dist/MEMLNaut-<version>-<platform>.vcvplugin

See DISTRIBUTION.md for the full packaging, CI matrix, and publishing workflow.

Cross-Compilation

Cross-compilation is not currently supported. Building for each platform requires the native VCV Rack SDK and a matching C++20 toolchain.

Options for multi-platform releases:

GitHub Actions CI — build on Linux, macOS, and Windows runners. The VCV SDK provides Docker images for consistent builds.
Docker — VCV provides ghcr.io/vcvrack/rack-plugin-toolchain images for cross-platform builds from a Linux host.
Manual — build natively on each target platform.

The VCV Library submission process handles multi-platform builds automatically via their CI pipeline, but we are not submitting to the Library initially.

Troubleshooting

-std=c++11 conflicts: The Makefile filters this out, but if you see C++20 errors, verify your RACK_DIR points to a v2 SDK and that your compiler supports C++20.
nisps headers not found: src/iml.hpp reaches the core via ../../nisps/… relative includes, so the plugin must be built from a full MEMLNaut-NISPS checkout (a standalone copy of vcv/ will not compile).
Plugin not appearing: Check that the built .so/.dylib/.dll is in the correct plugins directory and that plugin.json is alongside it.

2.9 KiB Raw Permalink Blame History