CODEX PROMPT — LUME repo production-grade restructure

lume-commerce/
├── .github/workflows/ci.yml         ← NEW: cargo test + pytest + Unity batchmode compile
├── .gitignore                       ← UPDATE: add target/, __pycache__/, Library/, Temp/, Logs/, .venv/
├── Cargo.toml                       ← REWRITE: workspace root only
├── Cargo.workspace.toml             ← NEW: declare members
├── pyproject.toml                   ← NEW: Python workspace root
├── README.md                        ← UPDATE: explain new structure
│
├── apps/
│   └── lume-rust-commerce/          ← was src/ at root
│       ├── Cargo.toml               ← MOVED from root, [package] block
│       ├── src/                     ← was /src
│       └── README.md                ← NEW: per-app docs
│
├── services/                        ← Each daemon its own pyproject.toml
│   ├── audio-pub/
│   │   ├── pyproject.toml           ← NEW
│   │   ├── audio_pub.py             ← was software/demo/audio_pub.py
│   │   ├── tests/                   ← was software/demo/tests/test_audio_pub.py + test_wire_format_golden.py
│   │   └── README.md                ← NEW
│   ├── mocopi-bridge/
│   │   ├── pyproject.toml
│   │   ├── mocopi_bridge.py         ← was software/demo/mocopi_bridge.py
│   │   ├── tests/                   ← was test_mocopi_bridge.py
│   │   └── README.md
│   ├── mocopi-synth/
│   │   ├── pyproject.toml
│   │   ├── mocopi_synth.py          ← was software/demo/mocopi_synth.py
│   │   ├── tests/                   ← was test_mocopi_synth.py
│   │   └── README.md
│   ├── sony-bridge/
│   │   ├── pyproject.toml
│   │   ├── sony_to_lumm_bridge.py   ← was software/demo/sony_to_lumm_bridge.py
│   │   ├── tests/                   ← was test_sony_to_lumm_bridge.py
│   │   └── README.md
│   └── pointcloud-pub/              ← was software/demo/pointcloud_pub.py + femto_intrinsics.py
│       ├── pyproject.toml
│       ├── pointcloud_pub.py
│       ├── femto_intrinsics.py
│       ├── tests/
│       └── README.md
│
├── packages/                        ← Shared libs, importable
│   ├── lume-protocol/               ← Versioned wire format
│   │   ├── pyproject.toml
│   │   ├── lume_protocol/
│   │   │   ├── __init__.py
│   │   │   ├── lumd.py              ← extracted LUMD encode/decode
│   │   │   ├── lumf.py              ← extracted LUMF
│   │   │   ├── lumm.py              ← extracted LUMM (currently in mocopi_bridge)
│   │   │   └── lume.py              ← extracted LUME cloud
│   │   ├── tests/
│   │   └── README.md                ← Wire format spec lives here OR in docs/protocols/
│   └── lume-tools/                  ← packet_inspector + helpers
│       ├── pyproject.toml
│       ├── lume_tools/
│       │   ├── __init__.py
│       │   ├── packet_inspector.py  ← was software/demo/lume_packet_inspector.py
│       │   └── pointcloud_probe.py  ← was software/demo/pointcloud_probe.py
│       ├── tests/                   ← was test_packet_inspector.py
│       └── README.md
│
├── viz/
│   └── lume-pcloud/                 ← was software/demo/unity/lume_pcloud/
│       ├── Assets/                  ← Unity .meta GUIDs preserved via git mv
│       ├── Packages/
│       ├── ProjectSettings/
│       └── README.md                ← was software/demo/README.md (Unity-specific)
│
├── infra/
│   ├── launchagents/                ← was software/demo/launchagents/
│   │   ├── com.lume.audio-pub-mac5.plist
│   │   ├── com.lume.sony-bridge-mac1.plist
│   │   ├── health-check.sh
│   │   └── install-mac5.sh
│   ├── nssm/                        ← was software/demo/launchagents/k11/
│   │   ├── install-services.ps1
│   │   ├── uninstall-services.ps1
│   │   ├── health-check.ps1
│   │   └── README.md
│   └── ENV-TEMPLATE.md              ← NEW: documents LUME_ROOT and other env vars
│
├── hardware/
│   ├── cad/                         ← already exists, no change
│   ├── design/                      ← already exists, no change
│   └── reference/
│       └── duncan/                  ← was software/demo/unity/lume_pcloud/Reference/Duncan/ (110MB!)
│
├── docs/
│   ├── architecture/                ← move existing ARCHITECTURE.md here, update content
│   ├── playbooks/                   ← Duncan v3 playbook from obsidian → checked-in copy
│   ├── research/                    ← gap analyses, reel evidence
│   ├── protocols/                   ← was software/demo/lume_wire_format.md
│   └── runbooks/                    ← MAC5-SMOKE-TEST, K11 runbooks, Wave 1.5 handoffs
│
├── tools/                           ← scripts that aren't services
│   ├── duncan_v3/                   ← was software/demo/duncan_v3/ (analysis scripts)
│   ├── refresh_duncan_corpus.sh     ← was software/demo/refresh_duncan_corpus.sh
│   ├── build_duncan_library.py      ← was software/demo/build_duncan_library.py
│   ├── build_duncan_analyses.py     ← was software/demo/build_duncan_analyses.py
│   └── k11-pipeline.sh              ← was software/demo/k11-pipeline.sh
│
├── scripts/                         ← already exists at root, keep as-is for admin/build
└── tests/                           ← already exists; integration tests stay top-level

mkdir -p hardware/reference
git mv software/demo/unity/lume_pcloud/Reference/Duncan hardware/reference/duncan
cd software/demo && pytest -q  # must stay 139/6
cd ../..
git commit -m "[restructure-A1] move Duncan reference corpus out of Unity tree

Reference/Duncan/ (110MB of reel analyses + sidecar JSON + transcripts)
was buried inside the Unity Assets sibling. Reference data is not Unity
content — it's research corpus. Move to hardware/reference/duncan/
where future installs can ingest it without dragging it through Unity's
asset import pipeline.

Pytest 139/6 preserved."

mkdir -p infra
git mv software/demo/launchagents infra/launchagents
git commit -m "[restructure-A2] move launchagents to infra/launchagents

LaunchAgent .plist files are deployment infrastructure, not application
code. Moving to repo root infra/ to surface them and make room for
future Linux systemd, Docker, and K8s deployment artifacts.

Plist absolute paths NOT YET updated — fixed in A3.
Pytest 139/6 preserved."

git commit -m "[restructure-A3] update LaunchAgent paths for new tree layout

audio-pub-mac5 and sony-bridge-mac1 plists now point to
services/audio-pub/ and services/sony-bridge/ respectively.
install-mac5.sh paths updated.

USER ACTION REQUIRED before next reboot:
  launchctl bootout gui/$(id -u) [home-path]
  cp infra/launchagents/com.lume.audio-pub-mac5.plist [home-path]
  launchctl bootstrap gui/$(id -u) [home-path]
(repeat for sony-bridge-mac1)
"

mkdir -p infra/nssm
git mv infra/launchagents/k11/* infra/nssm/
rmdir infra/launchagents/k11
git commit -m "[restructure-A4] separate K11 NSSM bundle from macOS launchagents

K11 NSSM Windows scripts and macOS LaunchAgent plists are different
deployment targets and should not share a directory. Now infra/nssm/
holds Windows production-box services; infra/launchagents/ holds
macOS dev/preview services.

USER ACTION REQUIRED on K11 before next reboot: update any path
hardcoded in install-services.ps1 if NSSM service definitions
reference repo paths."

mkdir -p viz
git mv software/demo/unity/lume_pcloud viz/lume-pcloud
rmdir software/demo/unity || true  # remove empty dir
cd viz/lume-pcloud && ls Assets/ | head -3  # verify .meta files present
cd ../..
git commit -m "[restructure-A5] move Unity project to viz/lume-pcloud

Unity project is a deployment target (visualization), not demo code.
Moving to viz/lume-pcloud/ alongside future visualization apps.

Unity .meta GUIDs preserved via git mv (GUIDs live INSIDE .meta files,
not in path-based registries — Unity will rescan but prefab/material
references stay intact).

Pytest 139/6 preserved (no Python touched)."

mkdir -p apps/lume-rust-commerce
git mv src apps/lume-rust-commerce/src
git mv Cargo.toml apps/lume-rust-commerce/Cargo.toml
# Cargo.lock stays at repo root for workspace
git commit -m "[restructure-A6] move Rust commerce app to apps/lume-rust-commerce

Single Cargo binary moves under apps/ to make room for future Rust
crates. Cargo.toml moves with src/. Cargo.lock stays at root for
workspace-wide dependency resolution (added in A8).

Build will fail until A8 lands the workspace.toml — expected."

mkdir -p services/audio-pub
git mv software/demo/audio_pub.py services/audio-pub/audio_pub.py
git mv software/demo/tests/test_audio_pub.py services/audio-pub/tests/test_audio_pub.py
# For audio-pub specifically, also move the wire format golden tests:
git mv software/demo/tests/test_wire_format_golden.py services/audio-pub/tests/test_wire_format_golden.py

git commit -m "[restructure-A7] move Python services to services/<name>/

audio_pub.py, mocopi_bridge.py, mocopi_synth.py, sony_to_lumm_bridge.py,
pointcloud_pub.py + femto_intrinsics.py move into per-service
directories with their tests adjacent.

Imports BREAK after this commit until A11 + B1 land workspace
pyproject + import path updates. Expected.

Pytest will fail with ModuleNotFoundError until B1 — known."

mkdir -p packages/lume-tools/lume_tools
mkdir -p packages/lume-tools/tests
git mv software/demo/lume_packet_inspector.py packages/lume-tools/lume_tools/packet_inspector.py
git mv software/demo/pointcloud_probe.py packages/lume-tools/lume_tools/pointcloud_probe.py
git mv software/demo/tests/test_packet_inspector.py packages/lume-tools/tests/test_packet_inspector.py
touch packages/lume-tools/lume_tools/__init__.py
git commit -m "[restructure-A8] move shared tools to packages/lume-tools

packet_inspector and pointcloud_probe are imported by multiple services.
Moving to packages/lume-tools/ makes them importable as a proper Python
package. __init__.py added.

Note: test_packet_inspector.py imports break until B1."

mkdir -p packages/lume-protocol/lume_protocol
mkdir -p packages/lume-protocol/tests
mkdir -p docs/protocols
git mv software/demo/lume_wire_format.md docs/protocols/wire_format_v1.md
touch packages/lume-protocol/lume_protocol/__init__.py
# DO NOT extract LUMD/LUMF/LUMM encode/decode functions yet — that's a
# significant refactor. Just create the skeleton; service files keep their
# inline encoders for now. B-stage handles the extraction.
git commit -m "[restructure-A9] create lume-protocol package skeleton + move wire format spec

docs/protocols/wire_format_v1.md is the canonical spec.
packages/lume-protocol/ skeleton created — encoder/decoder extraction
deferred to Stage B (one wire format per commit)."

mkdir -p tools
git mv software/demo/duncan_v3 tools/duncan_v3
git mv software/demo/refresh_duncan_corpus.sh tools/refresh_duncan_corpus.sh
git mv software/demo/build_duncan_library.py tools/build_duncan_library.py
git mv software/demo/build_duncan_analyses.py tools/build_duncan_analyses.py
git mv software/demo/k11-pipeline.sh tools/k11-pipeline.sh
git commit -m "[restructure-A10] move analysis + ops scripts to tools/

Duncan corpus builders, k11 pipeline, refresh script are
analysis/ops tools, not services or apps. tools/ at repo root
is the canonical location."

# integration tests stay at root tests/ (already exists)
git mv software/demo/tests/test_integration.py tests/integration/test_integration.py 2>/dev/null || mkdir -p tests/integration && git mv software/demo/tests/test_integration.py tests/integration/test_integration.py
git mv software/demo/tests/conftest.py tests/conftest.py 2>/dev/null  # may already exist; merge by hand if conflict

# README and handoff docs to docs/runbooks/
mkdir -p docs/runbooks
git mv software/demo/README.md docs/runbooks/lume-runtime-readme.md
git mv software/demo/MAC5-SMOKE-TEST.md docs/runbooks/mac5-smoke-test.md
git mv software/demo/CODEX-PLAN.md docs/runbooks/codex-plan.md
git mv software/demo/MAC5-CODEX-HANDOFF.md docs/runbooks/mac5-codex-handoff.md
git mv software/demo/MAC5-CODEX-HANDOFF-2026-04-26.md docs/runbooks/mac5-codex-handoff-2026-04-26.md
git mv software/demo/CODEX-FEMTO-HANDOFF.md docs/runbooks/codex-femto-handoff.md
git mv software/demo/CODEX-CONTEXT.md docs/runbooks/codex-context.md
git mv software/demo/DUNCAN-GAP-ANALYSIS.md docs/research/duncan-gap-analysis.md  # mkdir -p first

# clean up __init__.py + __pycache__ + remaining stragglers
git rm software/demo/__init__.py
rm -rf software/demo/__pycache__ software/demo/.pytest_cache software/demo/.claude software/demo/.DS_Store

# Verify empty
ls software/demo/ 2>/dev/null && echo "STILL HAS FILES — investigate" || rmdir software/demo software/

git commit -m "[restructure-A11] empty software/demo + remove software/

Final move of stragglers (handoff docs to docs/runbooks/, remaining
tests to tests/integration/, gap analysis to docs/research/).

software/ directory removed. The misleading 'demo' label is gone.

Pytest currently broken — depends on Stage B for import fixups.
Expected, will be green again at end of B1."

[project]
name = "lume-commerce"
version = "0.1.0"
requires-python = ">=3.10"

[tool.uv.workspace]
members = ["services/*", "packages/*"]

[tool.pytest.ini_options]
testpaths = ["services/*/tests", "packages/*/tests", "tests"]
python_files = ["test_*.py"]
addopts = "-q"

[project]
name = "lume-audio-pub"
version = "0.1.0"
dependencies = ["numpy>=1.26"]

[tool.setuptools.packages.find]
where = ["."]
include = ["audio_pub*"]

dependencies = [
    "numpy>=1.26",
    "lume-tools",
    "lume-protocol",
]

[tool.uv.sources]
lume-tools = { workspace = true }
lume-protocol = { workspace = true }

git commit -m "[restructure-B1] Python workspace + per-service pyproject + import fixups

Adds root pyproject.toml declaring workspace members services/*
and packages/*. Each service/package gets its own pyproject.toml.

Imports updated:
  lume_packet_inspector -> lume_tools.packet_inspector
  pointcloud_probe -> lume_tools.pointcloud_probe

pytest restored to 139 passed / 6 skipped."

[workspace]
resolver = "2"
members = ["apps/lume-rust-commerce"]

[workspace.package]
version = "0.1.0"
edition = "2021"

[workspace.dependencies]
# Hoist shared deps here over time

git commit -m "[restructure-B2] Cargo workspace + apps/lume-rust-commerce package

Root Cargo.toml is now a workspace declaring apps/lume-rust-commerce
as the first member. Apps Cargo.toml retains [package] block.
cargo build + cargo test pass."

# On K11, in PowerShell as Admin:
.\install-services.ps1 -Uninstall  # using OLD scripts first
git pull
.\install-services.ps1 -Install     # NEW scripts now active

git commit -m "[restructure-B3] update K11 NSSM service paths

NSSM service definitions previously pointed at software/demo paths.
Updated to services/audio-pub, services/mocopi-bridge, etc.

USER ACTION REQUIRED on K11 before next reboot:
  PowerShell admin: .\infra\nssm\install-services.ps1 -Uninstall
  git pull
  .\infra\nssm\install-services.ps1 -Install
"

git commit -m "[restructure-B4] update doc path references after restructure

grep -r 'software/demo' --include='*.md' caught N references.
All updated to canonical apps/services/packages/viz/infra layout."

git commit -m "[restructure-B5] verify Unity project path independence (no-op or asmdef fix)
" --allow-empty

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  rust:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo build --workspace --verbose
      - run: cargo test --workspace --verbose

  python:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11' }
      - run: pip install uv
      - run: uv sync
      - run: uv run pytest -q

  unity-compile:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: game-ci/unity-builder@v4
        with:
          targetPlatform: StandaloneOSX
          projectPath: viz/lume-pcloud
          buildName: lume-pcloud-ci
        # NOTE: needs UNITY_LICENSE secret (M-4 blocker — user grants when license activates)
        env:
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
        continue-on-error: true  # so PR can land before Unity license is set up

git commit -m "[restructure-C1] GitHub Actions CI workflow

cargo build/test for Rust workspace, pytest for Python workspace,
Unity batchmode compile for viz/lume-pcloud. Unity job
continue-on-error until UNITY_LICENSE secret is set (M-4 pending)."

git commit -m "[restructure-C2] per-service + per-app + per-package README docs

Each subdirectory now has a README explaining purpose, run instructions,
tests, and deployment target. Reduces onboarding friction for next
contributor (or your future self after a long pause)."

git commit -m "[restructure-C3] root README + ARCHITECTURE updated for new layout

Root README is now the canonical 'where things live' guide.
docs/architecture/ARCHITECTURE.md updated component paths.

Restructure complete."

# Mac1
tar czf /tmp/lume-restructured.tgz \
  --exclude='.git' --exclude='Library' --exclude='Temp' --exclude='Logs' \
  -C [home-path] lume-commerce
scp /tmp/lume-restructured.tgz mac4:/tmp/

# Mac4 (via tmux to inherit Terminal.app FDA)
ssh mac4 'tmux new-session -d -s lume-extract; tmux send-keys -t lume-extract "cd [home-path] && rm -rf lume-commerce && tar xzf /tmp/lume-restructured.tgz && touch /tmp/lume-extract.done" Enter'
# wait for /tmp/lume-extract.done
ssh mac4 'cat /tmp/lume-extract.done'

ssh mac4 'tmux new-session -d -s lume-verify; tmux send-keys -t lume-verify "ls Desktop/lume-commerce/ > /tmp/mac4-tree.txt" Enter'
ssh mac4 'cat /tmp/mac4-tree.txt'

# Hard reset to before restructure
git reset --hard 83b565e3
# Remove any new directories
rm -rf apps/ services/ packages/ viz/ infra/ tools/ pyproject.toml Cargo.workspace.toml .github/

cd [home]/Desktop/lume-commerce
rm -f .git/index.lock
git status --short  # verify clean
git log --oneline -1  # should show 83b565e3 or later
cd software/demo && pytest -q  # confirm 139/6
cd ../..

# Begin Stage A
mkdir -p hardware/reference
git mv software/demo/unity/lume_pcloud/Reference/Duncan hardware/reference/duncan
cd software/demo && pytest -q
cd ../..
git add -A
git commit -m "[restructure-A1] move Duncan reference corpus out of Unity tree
…"