docs: bring project overview up to date

Summarize the evidence baseline, live USB identification, open-source reuse discovery, proposed architecture, immediate offline proofs, and explicit safety boundary in the repository landing page.

README.md

@@ -4,34 +4,93 @@
 
 <h1 align="center">The Pirate Ray</h1>
 
-The Pirate Ray is Makerspace Næstved's clean-room project for learning how to
+The Pirate Ray is Makerspace Næstved's clean-room effort to build an
-interoperate with its laser equipment and, over time, building a safe desktop
+open-source, safe desktop workflow for its laser equipment. The first target
-control application.
+is the **JPT 100 W E2/M7 MOPA fiber laser** with a JCZ/EZCAD2-compatible
+controller and the currently assumed 110 x 110 mm lens.
 
-Phase 0 focuses on the **JPT 100 W E2/M7 MOPA** fiber laser with a JCZ/EZCAD2
+The destination is the useful core of a LightBurn-like workflow: import or
-controller. It is deliberately limited to documentation and offline analysis:
+create geometry, assign operations and MOPA parameters, preview and validate
-no USB capture, framing, machine commands, or laser output.
+the job, and eventually run it through independently auditable machine
+backends. The project is not trying to evade LightBurn licensing or copy its
+proprietary code or assets.
+
+## Where we are now
+
+Phase 0 has established a reproducible evidence and research baseline:
+
+- the original installer material is preserved privately with SHA-256
+  manifests and Git LFS;
+- sanitized analysis covers the EZCAD2 installation, 110/300 configurations,
+  correction data, material libraries, and relevant configuration files;
+- the physical controller has been passively identified by Windows as
+  `USBLMCV4`, USB `9588:9899`, with device revision descriptor `0005`;
+- the development computer has no compatible controller driver installed;
+- no USB endpoint has been opened and no controller command, galvo movement,
+  framing, marking, or laser output has occurred;
+- the public tests, provenance checks, leak guard, and clean-clone validation
+  pass.
+
+Phase 0 remains open while we collect the LightBurn bundle, preferences,
+known-working projects, device screenshots, machine photos, and operator notes
+directly from the actual control computer.
+
+## The important discovery
+
+We do not need to begin with a blank-sheet LightBurn clone:
+
+- [MeerK40t](https://github.com/meerk40t/meerk40t) already includes BalorMK,
+  an MIT-licensed JCZ/EZCAD2 galvo implementation with MOPA pulse width,
+  frequency control, status/abort behavior, and a mock USB connection. Its
+  source targets the same `9588:9899` USB identity observed on our controller.
+- [Rayforge](https://github.com/barebaric/rayforge) already supplies most of
+  the modern desktop product: editor, projects, geometry, LightBurn import,
+  material recipes, simulation, pre-flight checks, packaging, and an addon
+  architecture. Its job model already represents frequency and pulse width.
+
+The leading route is therefore either to use and improve MeerK40t directly or
+to build a Rayforge JCZ/Balor addon using the narrowest practical layer from
+BalorMK. This remains a proposed decision until the offline proofs in
+[ADR 0002](docs/adr/0002-reuse-rayforge-and-balormk.md) have passed.
+
+## Next steps
+
+The next work is deliberately offline and hardware-free:
+
+1. run a synthetic MOPA job through MeerK40t's mock controller;
+2. prove that an external Rayforge addon can register a binary no-device
+   driver on Windows;
+3. translate a small Rayforge operation stream into a deterministic JCZ trace
+   and compare it with BalorMK;
+4. test Rayforge's existing LightBurn import against galvo/MOPA fixtures;
+5. accept, revise, or reject the proposed reuse architecture from evidence;
+6. write and review a separate hardware protocol before any live controller
+   communication.
+
+An independent desktop application is the fallback only if both existing
+platforms fail concrete, documented requirements.
 
 ## Repository boundary
 
 This public repository contains source code, plans, decisions, tests, tools,
 and sanitized research. Raw machine data, serial numbers, LightBurn exports,
 and third-party material with unclear redistribution rights live in the
-separate private `ThePirateRay-PrivateStash` repository.
+separate private `ThePirateRay-PrivateStash` repository. Google Drive is not a
+project workspace or development destination.
 
-Start with:
+## Project map
 
 - [Project charter](docs/project-charter.md)
 - [Product and research roadmap](docs/roadmap.md)
-- [Data handling policy](docs/data-handling.md)
+- [Current Phase 0 status](docs/status/phase-0.md)
-- [LightBurn collection checklist](docs/collection/lightburn.md)
+- [Open-source reuse landscape](docs/research/open-source-landscape.md)
+- [Proposed Rayforge/BalorMK reuse decision](docs/adr/0002-reuse-rayforge-and-balormk.md)
+- [Live USB enumeration](docs/research/live-usb-enumeration-2026-10-17.md)
 - [Sanitized machine profile](docs/research/machine-profile.yaml)
 - [110/300 configuration comparison](docs/research/config-comparison.md)
-- [Open-source reuse landscape](docs/research/open-source-landscape.md)
+- [Data handling policy](docs/data-handling.md)
-- [Live USB enumeration](docs/research/live-usb-enumeration-2026-10-17.md)
+- [LightBurn collection checklist](docs/collection/lightburn.md)
 - [Repository boundary decision](docs/adr/0001-public-private-repository-boundary.md)
-- [Proposed Rayforge/BalorMK reuse decision](docs/adr/0002-reuse-rayforge-and-balormk.md)
-- [Current Phase 0 status](docs/status/phase-0.md)
 
 ## Validation
 
@@ -42,14 +101,20 @@ python -m unittest discover -s tests -v
 python scripts/check_public_repo.py .
 ```
 
-`scripts/materialize_private_drive_files.ps1` is the bounded transport used by
+The checks verify manifest integrity, public/private evidence contracts,
-the acquisition workflow. It accepts authenticated download references over
+disallowed binary types, private identifiers, local user paths, and other
-standard input, rejects path traversal, and verifies byte sizes before files
+likely data leaks. They do not certify hardware safety.
-enter PrivateStash. It never prints download credentials.
 
-For non-interactive orchestration it also accepts one UTF-8 JSON request as a
+## Safety boundary
-Base64 parameter. This prevents shell metacharacters in signed references from
+
-being interpreted as commands.
+- Simulation precedes equivalent hardware behavior.
+- Read-only precedes state change; state change precedes motion; motion
+  precedes emission.
+- Machine, source, lens, correction profile, units, and parameter ranges must
+  match before a job can be armed.
+- Unknown configuration or protocol fields are never guessed or replayed.
+- Vendor executables, DLLs, and drivers from the evidence snapshot are never
+  run as part of analysis.
 
 No project license has been selected yet. Until that decision is recorded,
 the contents are not offered under an open-source license.