flpkit 0.8.1__tar.gz

flpkit-0.8.1/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/flpkit
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

flpkit-0.8.1/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/

flpkit-0.8.1/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.8.0
+
+- Effects are captured plugin-reference data and use the common Format patch path.
+- Validation now lives in Formats and raises `FlpError` for invalid mode, note, level, and tempo inputs.
+
+## 0.7.2
+
+- Added the captured Parametric EQ 2 mixer-effect reference.

flpkit-0.8.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Origami Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flpkit-0.8.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: flpkit
+Version: 0.8.1
+Summary: Read and write FL Studio .flp project files - a small, dependency-free library for the undocumented FLP format, with self-verifying raw-surgery writers
+Project-URL: Homepage, https://github.com/clarkipeng/flpkit
+Project-URL: Repository, https://github.com/clarkipeng/flpkit
+Project-URL: Issues, https://github.com/clarkipeng/flpkit/issues
+Project-URL: Changelog, https://github.com/clarkipeng/flpkit/blob/main/CHANGELOG.md
+Author: Origami Research
+License-Expression: MIT
+License-File: LICENSE
+Keywords: daw,fl-studio,flp,midi,music
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# flpkit
+
+Read and write FL Studio `.flp` project files - without FL Studio, without dependencies.
+
+```python
+import flpkit
+
+project = flpkit.read(path)          # ppq, tempo, channels (names + levels + automation), notes, playlist
+flpkit.set_tempo(path, 128.5)        # returns the tempo the SAVED file contains
+flpkit.write_notes(
+    path,
+    [flpkit.NoteSpec(key=60, start=0, length=1)],  # beats; velocity/pan 0..1
+    pattern=1, channel=0, mode="merge",
+)                                     # returns the notes read back from the saved file
+flpkit.set_channel_levels(path, 0, volume=0.8, pan=-0.25)
+```
+
+## Why this exists
+
+The FLP format is proprietary and undocumented.
+The existing reverse-engineered library (pyflp, GPL) has a broad *parser*, but its *serializer* rewrites bytes it shouldn't - we observed it write a wrong channel count into the file header and mangle a UTF-16 text event, producing files that parsers read back happily and **real FL Studio refuses to open**.
+
+flpkit takes the opposite approach for writing: **raw byte surgery**.
+A write patches or appends exactly the bytes that express the change and never reserializes the file, so everything the library does not model survives untouched.
+Every writer then **verifies itself**: it re-reads the saved file and field-matches the result against what was sent, raising `FlpError` instead of returning hope.
+
+## What it reads
+
+- PPQ and tempo, including the legacy pre-`156` coarse/fine word pair
+- Channels with display names (user rename → legacy name → plugin internal name) and mix levels across four format generations (`Levels` 219, word events, byte events)
+- Notes per pattern and channel (the 24-byte packed record), with correct attribution for the implicit channel 0 and pre-pattern note blobs that stock FL files contain
+- UTF-16/Latin-1 text switching keyed off the file's `FLVersion`
+- Playlist items per arrangement (pattern/audio clips: position, length, track, group), with the record stride DETECTED per blob - FL grew the record from 32 to 60 to 80 to 88 bytes across eras, and the constant `pattern_base` signature identifies the true size instead of a hardcoded list
+- Automation clips: each type-5 channel's points (position in beats from clip start, value 0..1, tension), decoded from the delta-encoded f64 records and verified point-identical to pyflp across 1,100 real blobs
+
+## What it writes
+
+- `set_tempo` - patches the tempo event in place, or appends one when the file omits it (FL expresses default tempo by omission; end-of-stream append is the placement real FL accepts)
+- `write_notes` - splices a pattern's notes blob; `mode="replace"` is scoped to the target channel (a pattern's blob holds *every* channel's notes - naive replacement destroys other channels' work)
+- `set_channel_levels` - patches pan/volume/pitch int32s inside the channel's `Levels` event; refuses legacy files rather than writing guessed units
+- `write_playlist` - splices pattern clips into an arrangement's playlist event; every new record is built from the first EXISTING record as a byte template (so the era-specific tail carries FL's own defaults), kept position-sorted the way FL writes them. Live-verified: FL Studio 2026 loads the written clips (song length grows to match) and its OWN re-save round-trips them byte-identically
+- `write_automation` - replaces the points inside an EXISTING automation channel's blob; the 17-byte header and the opaque era trailer are carried verbatim, absolute positions convert back to FL's stored x-deltas, and each point's opaque 4-byte tail rides along.
+  Feeding a channel's decoded points straight back is readback-identical; it is byte-identical for FL-authored blobs in corpus tests.
+  Creating a NEW clip is out of scope until the link bytes are decoded - a non-automation channel or a missing blob is an error, not an invitation to fabricate
+- `add_effect` and `effects_at` - splice and read captured mixer-effect references while preserving plugin state as opaque data
+
+## One engine, formats as data (0.6.0)
+
+Every writer and element reader above flows through ONE generic engine, `flpkit.codec`:
+
+```python
+from flpkit import codec
+from flpkit.formats import NotesFormat
+
+notes = codec.read(path, NotesFormat(), codec.Target(pattern=1, channel=0))
+codec.patch(path, NotesFormat(), codec.Target(pattern=1, channel=0), notes, mode="merge")
+```
+
+A `Format` (see `flpkit/formats/`) states one `.flp` element - `locate`, `encode`, `decode`, `verify` - and the engine does the rest: splice, chunk-length fixing, and verify-by-readback live in `codec.patch`, once.
+Reading `formats/notes.py` plus `codec.py` tells you everything about how notes work; the same goes for playlist, automation, levels, tempo, and effects.
+The public functions (`write_notes`, `set_tempo`, ...) are thin shims over `codec.patch`, and `tests/test_differential.py` proves the codec writes byte-identical output to the pre-0.6.0 hand-rolled writers.
+
+## Detect, don't assume
+
+Format constants are DETECTED from the file itself wherever the data carries an invariant, with hardcoded values only as logged fallbacks:
+
+- The playlist record stride is detected per blob (the constant `pattern_base` signature), never taken from a version table.
+- The note-flags word is templated from the target file's own notes; the corpus-surveyed `0x4000` covers files with none.
+- New playlist records inherit their cut-window bytes from an existing record; existing era-specific windows remain opaque.
+- Event-size overrides (event 172 is one byte on FL 2026, not the classic four) are an `event_size_overrides` argument on every public function, so a capability profile can supply a measured table for other FL versions; the built-in FL-2026 table is the once-logged fallback.
+
+## How it was verified
+
+Every byte-level fact in the source carries its evidence in a comment.
+The facts come from two directions:
+
+1. **Differential reading** against pyflp across 164 FL-authored projects (dev-only oracle; flpkit ships with zero dependencies and no GPL code).
+2. **Live FL Studio**: files written by flpkit are opened by real FL Studio 2026 (macOS) and read back over a control connection - tempo, note, and level writes are all confirmed by FL itself, not just by our own parser. The live harness lives in the parent project, [fl-studio-mcp](https://github.com/origami-research/fl-studio-mcp).
+
+One example of why the live half matters: a note-record flags field of `0` parses fine everywhere, but every note FL itself writes carries `0x4000` (surveyed: 24,435 records across FL's bundled projects, not one with `0`).
+
+## Scope, honestly
+
+flpkit models what a composition agent needs: tempo, channels, levels, notes, and captured mixer-effect references.
+It does not decode plugin state or the mixer graph: plugin tuples are captured and spliced as opaque data, while `read()` does not expose a mixer graph. Playlist reading landed in 0.2.0, automation-clip reading in 0.3.0, playlist writing in 0.4.0 (FL-2026 live-verified), automation-point writing in 0.5.0 (readback-identical; byte-identical for FL-authored corpus blobs; live FL round-trip pending).
+Automation clip CREATION (a new curve on a new target) stays out until the target-link bytes are decoded by live minimal-pair experiments.
+
+## Captured plugin references
+
+Plugin references live in `src/flpkit/data/plugins/`. The index maps a plugin name to one JSON record. Each record has `name`, `fl_build`, `kind`, `chunk_hex`, `sha256`, and `captured_on`. Capture pipelines should write that record from an FL-authored plugin tuple, hash the decoded `chunk_hex`, and add its name to the index. flpkit validates the hash before it splices the opaque tuple.
+
+## Bring your own note type
+
+`write_notes` accepts any object with `key` (MIDI int), `start`/`length` (beats), `velocity`/`pan` (0..1) attributes - `NoteSpec` is provided for convenience, but a pydantic model or your own dataclass works as-is.
+
+## License
+
+MIT.

flpkit-0.8.1/README.md

@@ -0,0 +1,98 @@
+# flpkit
+
+Read and write FL Studio `.flp` project files - without FL Studio, without dependencies.
+
+```python
+import flpkit
+
+project = flpkit.read(path)          # ppq, tempo, channels (names + levels + automation), notes, playlist
+flpkit.set_tempo(path, 128.5)        # returns the tempo the SAVED file contains
+flpkit.write_notes(
+    path,
+    [flpkit.NoteSpec(key=60, start=0, length=1)],  # beats; velocity/pan 0..1
+    pattern=1, channel=0, mode="merge",
+)                                     # returns the notes read back from the saved file
+flpkit.set_channel_levels(path, 0, volume=0.8, pan=-0.25)
+```
+
+## Why this exists
+
+The FLP format is proprietary and undocumented.
+The existing reverse-engineered library (pyflp, GPL) has a broad *parser*, but its *serializer* rewrites bytes it shouldn't - we observed it write a wrong channel count into the file header and mangle a UTF-16 text event, producing files that parsers read back happily and **real FL Studio refuses to open**.
+
+flpkit takes the opposite approach for writing: **raw byte surgery**.
+A write patches or appends exactly the bytes that express the change and never reserializes the file, so everything the library does not model survives untouched.
+Every writer then **verifies itself**: it re-reads the saved file and field-matches the result against what was sent, raising `FlpError` instead of returning hope.
+
+## What it reads
+
+- PPQ and tempo, including the legacy pre-`156` coarse/fine word pair
+- Channels with display names (user rename → legacy name → plugin internal name) and mix levels across four format generations (`Levels` 219, word events, byte events)
+- Notes per pattern and channel (the 24-byte packed record), with correct attribution for the implicit channel 0 and pre-pattern note blobs that stock FL files contain
+- UTF-16/Latin-1 text switching keyed off the file's `FLVersion`
+- Playlist items per arrangement (pattern/audio clips: position, length, track, group), with the record stride DETECTED per blob - FL grew the record from 32 to 60 to 80 to 88 bytes across eras, and the constant `pattern_base` signature identifies the true size instead of a hardcoded list
+- Automation clips: each type-5 channel's points (position in beats from clip start, value 0..1, tension), decoded from the delta-encoded f64 records and verified point-identical to pyflp across 1,100 real blobs
+
+## What it writes
+
+- `set_tempo` - patches the tempo event in place, or appends one when the file omits it (FL expresses default tempo by omission; end-of-stream append is the placement real FL accepts)
+- `write_notes` - splices a pattern's notes blob; `mode="replace"` is scoped to the target channel (a pattern's blob holds *every* channel's notes - naive replacement destroys other channels' work)
+- `set_channel_levels` - patches pan/volume/pitch int32s inside the channel's `Levels` event; refuses legacy files rather than writing guessed units
+- `write_playlist` - splices pattern clips into an arrangement's playlist event; every new record is built from the first EXISTING record as a byte template (so the era-specific tail carries FL's own defaults), kept position-sorted the way FL writes them. Live-verified: FL Studio 2026 loads the written clips (song length grows to match) and its OWN re-save round-trips them byte-identically
+- `write_automation` - replaces the points inside an EXISTING automation channel's blob; the 17-byte header and the opaque era trailer are carried verbatim, absolute positions convert back to FL's stored x-deltas, and each point's opaque 4-byte tail rides along.
+  Feeding a channel's decoded points straight back is readback-identical; it is byte-identical for FL-authored blobs in corpus tests.
+  Creating a NEW clip is out of scope until the link bytes are decoded - a non-automation channel or a missing blob is an error, not an invitation to fabricate
+- `add_effect` and `effects_at` - splice and read captured mixer-effect references while preserving plugin state as opaque data
+
+## One engine, formats as data (0.6.0)
+
+Every writer and element reader above flows through ONE generic engine, `flpkit.codec`:
+
+```python
+from flpkit import codec
+from flpkit.formats import NotesFormat
+
+notes = codec.read(path, NotesFormat(), codec.Target(pattern=1, channel=0))
+codec.patch(path, NotesFormat(), codec.Target(pattern=1, channel=0), notes, mode="merge")
+```
+
+A `Format` (see `flpkit/formats/`) states one `.flp` element - `locate`, `encode`, `decode`, `verify` - and the engine does the rest: splice, chunk-length fixing, and verify-by-readback live in `codec.patch`, once.
+Reading `formats/notes.py` plus `codec.py` tells you everything about how notes work; the same goes for playlist, automation, levels, tempo, and effects.
+The public functions (`write_notes`, `set_tempo`, ...) are thin shims over `codec.patch`, and `tests/test_differential.py` proves the codec writes byte-identical output to the pre-0.6.0 hand-rolled writers.
+
+## Detect, don't assume
+
+Format constants are DETECTED from the file itself wherever the data carries an invariant, with hardcoded values only as logged fallbacks:
+
+- The playlist record stride is detected per blob (the constant `pattern_base` signature), never taken from a version table.
+- The note-flags word is templated from the target file's own notes; the corpus-surveyed `0x4000` covers files with none.
+- New playlist records inherit their cut-window bytes from an existing record; existing era-specific windows remain opaque.
+- Event-size overrides (event 172 is one byte on FL 2026, not the classic four) are an `event_size_overrides` argument on every public function, so a capability profile can supply a measured table for other FL versions; the built-in FL-2026 table is the once-logged fallback.
+
+## How it was verified
+
+Every byte-level fact in the source carries its evidence in a comment.
+The facts come from two directions:
+
+1. **Differential reading** against pyflp across 164 FL-authored projects (dev-only oracle; flpkit ships with zero dependencies and no GPL code).
+2. **Live FL Studio**: files written by flpkit are opened by real FL Studio 2026 (macOS) and read back over a control connection - tempo, note, and level writes are all confirmed by FL itself, not just by our own parser. The live harness lives in the parent project, [fl-studio-mcp](https://github.com/origami-research/fl-studio-mcp).
+
+One example of why the live half matters: a note-record flags field of `0` parses fine everywhere, but every note FL itself writes carries `0x4000` (surveyed: 24,435 records across FL's bundled projects, not one with `0`).
+
+## Scope, honestly
+
+flpkit models what a composition agent needs: tempo, channels, levels, notes, and captured mixer-effect references.
+It does not decode plugin state or the mixer graph: plugin tuples are captured and spliced as opaque data, while `read()` does not expose a mixer graph. Playlist reading landed in 0.2.0, automation-clip reading in 0.3.0, playlist writing in 0.4.0 (FL-2026 live-verified), automation-point writing in 0.5.0 (readback-identical; byte-identical for FL-authored corpus blobs; live FL round-trip pending).
+Automation clip CREATION (a new curve on a new target) stays out until the target-link bytes are decoded by live minimal-pair experiments.
+
+## Captured plugin references
+
+Plugin references live in `src/flpkit/data/plugins/`. The index maps a plugin name to one JSON record. Each record has `name`, `fl_build`, `kind`, `chunk_hex`, `sha256`, and `captured_on`. Capture pipelines should write that record from an FL-authored plugin tuple, hash the decoded `chunk_hex`, and add its name to the index. flpkit validates the hash before it splices the opaque tuple.
+
+## Bring your own note type
+
+`write_notes` accepts any object with `key` (MIDI int), `start`/`length` (beats), `velocity`/`pan` (0..1) attributes - `NoteSpec` is provided for convenience, but a pydantic model or your own dataclass works as-is.
+
+## License
+
+MIT.

flpkit-0.8.1/RELEASING.md

@@ -0,0 +1,32 @@
+# Releasing flpkit
+
+Releases are published by GitHub Actions only. Do not create or store a PyPI
+token for this repository.
+
+## One-time PyPI setup
+
+Before the first release, sign in to PyPI as an owner and create a pending
+trusted publisher at PyPI's Publishing settings. Enter:
+
+- PyPI project name: `flpkit`
+- Owner: `clarkipeng`
+- Repository: `flpkit`
+- Workflow filename: `publish.yml`
+- Environment: `pypi`
+
+For a project that already exists, add the same GitHub trusted publisher from
+that project's Publishing settings. The pending publisher creates the project
+when the first matching workflow publishes it.
+
+## Release steps
+
+1. Confirm `scripts/check-release.sh` and `uv run pytest -q` pass.
+2. Update the version and changelog, then merge the release PR.
+3. Create and push an annotated `vX.Y.Z` tag on the merged commit.
+4. Watch the `Publish to PyPI` workflow. Its dedicated `pypi` environment
+   exchanges GitHub's OIDC identity for PyPI publishing permission and uploads
+   the distributions built from that tag.
+
+The workflow triggers only for `v*` tag pushes and has no token or manual
+upload fallback. PyPI keeps release versions immutable, so verify the version
+and artifacts before pushing the tag.

flpkit-0.8.1/TASTE.md

@@ -0,0 +1,85 @@
+# Taste
+
+How we build. Every agent reads this before writing code.
+When a judgment call comes up, this doc decides it. Briefs add context, never new taste.
+Built from 12k of my own messages (June to September 2026); every rule traces to quotes in the local taste corpus.
+
+## How to work with me
+
+- Proceed. Don't ask for permission on ordinary engineering, cleanup, or merge work. Ask only when the decision is genuinely mine: product direction, spend, irreversible external action, or a scope tradeoff evidence can't settle. Then ask a real directional question with your recommendation and its cost, never "should I continue?".
+- Terse means go. "ok", "go", "yes", "do this", "continue" are approvals, not requests for more detail.
+- An explicit hold is a hold ("don't do anything until I say so"). A request to explain is not approval to change things.
+- Tell me before I have to ask. If I'm typing "updates?", "eta?", "check", "hello?", you went quiet too long. A status says what changed, what is true now, what's running, the next action, and exactly what needs me.
+- Speak like a person. Plain speech, sentence case, short bullets, no agent-speak, no ceremony. Say what's done and what's still needed.
+- "Explain" or "wdym" means the framing failed, and usually the system is over-complicated. Rebuild the mental model from the concrete thing: what it is, its state now, the problem, the proposed change, why each non-obvious piece exists. Simplify the system, not just the sentence.
+- Show me the thing I need to decide in a form I can inspect. Give choices only at a genuine fork, with the recommended one and its cost.
+- Keep a live doc I can glance at (`doing.md`): now, waiting on me, done, known issues. Short and current.
+- Report what actually happened. When evidence overturns an earlier claim, correct every copy of the old story in the same change.
+
+## Architecture
+
+- Smallest robust architecture. If we're adding constraints and it feels complicated, that's the signal it's wrong. No framework where a function does the job.
+- One path, not branches. If a function grows if/else arms and edge-case handlers, the fix is one path with an invariant that makes the special cases impossible.
+- Constraints that make bad states impossible (a unique index, a CHECK, one transaction, a counter that only goes up) get built first. Mechanisms that interpret evidence (classifiers, heuristics, taxonomies) wait until a real incident fixes their exact shape.
+- One implementation per capability, one source of truth. When two paths overlap, keep the better one and delete the other in the same change. Replacing a path includes deleting the old one, or the change isn't done.
+- No workarounds, not even temporary. No compatibility alias, arbitrary cap, stale sentinel, or underscored dead value. Fix the invariant. Keep compatibility only when a real supported user or durable data contract requires it.
+- Fix the cause, not the symptom. Trace the real path that produced the failure, make that bad state impossible, add the one narrow proof, and leave a short diagnosis so recurrence is trivial to spot.
+- Generalize after real repetition, or when the next shared use is known and concrete. An abstraction with one caller is waste. Don't invent a framework for an imagined future.
+- Measure real things. The actual process, stored row, browser output, deployed state. Not a stand-in, cached copy, or dashboard flag. Repository text alone proves nothing is dead or working; check the databases and dashboards too.
+- Data lives on the thing it describes. A variant declares its own facts where it's constructed; shared systems read them. Question anything that centralizes unrelated decisions (one manager scoring everything, one writer, one mode switch).
+- Typed outcomes for distinct realities. Success, failure, unavailable, interrupted, and invalidated are not interchangeable empties. Never infer state by scraping text or exit codes.
+- Nothing gets orphaned, silently dropped, or marked terminal before its side effect is confirmed. One owner and one authoritative lifecycle decide the state. Silence is a failure mode.
+- Never write "couldn't run the measurement" down as "the experiment failed". Keep the missing-measurement cause distinct and recoverable.
+- Delete finished one-off jobs. A completed migration script left in the tree is a loaded gun. Net-negative PRs are good.
+
+## Configuration
+
+- Dials live next to the rules they tune, in small modules. If a value is definitional (0, 1, "always"), it's code, not config.
+- Defaults make the intended path work. Don't expose knobs that let a caller, provider, or stale environment choose a system invariant.
+- Centralize genuinely shared, user-visible budgets in one named owner. Don't centralize merely equal numbers; app-local policy stays local.
+- No config bureaucracy and no standing style nags. On-demand audits and structural gates that protect a real invariant are good. Lint tripwires about taste are not.
+
+## Process
+
+- Fix real problems before building features. Reproduce bugs end to end as a user first, and test the real user path before claiming a cause or a fix.
+- Small, specified fixes get done directly. A worker costs 30-45 minutes for any size change; dispatch only work that is genuinely long, heavy, or parallel.
+- Batch the work: read everything needed once, then write code, tests, and run the suite in one go. Fewer roundtrips, fewer tokens. Prove prerequisites cheaply before an expensive end-to-end run; a long series of dry runs is not discovery.
+- Reviews match blast radius. Kernel, schema, and seam changes get an independent adversarial review. Small fixes get one probe of the real risk plus one test that fails without the fix.
+- Every test says why it exists, especially regression guards. Test the invariant that prevented the incident, including timing and recovery boundaries. Never weaken or skip a test to look green; refactors ship with tests moved, never weakened.
+- Run the local checks the change's risk actually warrants before pushing. CI confirms; it never discovers. Measure before adding process.
+- Squash-merge, never push main directly, review PRs to zero blockers. Keep PRs draft after local gates; the reviewing manager flips ready once the exact head is merge-worthy.
+- Before saying "fixed", check every item raised and state the remaining blocker plainly.
+- Preserve completed work through a coherent checkpoint. After an interruption, continue from it; never blindly regenerate or discard valid state.
+- If something looks off inside the change you're making, fix it. Same for red tests, lint, and flakes in that scope. Outside your scope, file or flag it; never quietly bundle it in.
+
+## Docs and voice
+
+- Docs are a short, human-readable judgment surface. Lead with what and when. Changing specifics live in code, tests, issues, and memory.
+- If it reads like slop, rewrite it as what I'd actually say. Sentence case. No em dashes. Judge animation and feel from footage, not adjectives.
+
+## UI
+
+- Build around the interaction that carries the rules. A 3D scene is the hero only when the scene is how you read the game; never default to 3D because it looks good.
+- Start from the user's model of the product. Stable things stay stable; move the camera or focus when that is what the user meant.
+- One fact per surface, labeled. No duplicated information anywhere; the logo twice is a bug. Layout is hierarchy and attention direction; if an element doesn't help, cut it.
+- The control lives where the decision happens (the card is the button). Prefer direct visible choices over generic buttons and hidden state.
+- Icons come from the lucide pipeline only, never hand-authored SVG. One glyph per control, colour working inside the glyph with a contrast floor.
+- Latency is product quality. Set and test budgets for user-visible interactions in the existing harness.
+- Inspect the rendered result. A screen that works but looks wrong, overlaps, or hides the interaction is not done.
+
+## Orchestration
+
+- Multi-slice work runs through SightMesh: sol manages, terra/luna execute, one program prefix per worker, disjoint file ownership, durable handoffs, the manager reviews and merges. The coordinator writes briefs, gathers evidence, deliberates with me, oversees merges, and deploys dev.
+- Don't coordinate with finished workers or nest orchestration. Read the diff, continue from the checkpoint. Report inherited blockers with the exact evidence.
+- Never invent a release flow, CLI, endpoint, identity, or policy from a plausible name. Verify it in live code and state first.
+
+## Tools and safety
+
+- Shell-safe by default: no backticks inside double-quoted bodies; use body files or single-quoted heredocs.
+- Secrets never print, only their shape. Anything that appeared in a transcript is exposed; rotate it.
+- If you're testing on my machine, don't take over my screen. Headless only.
+
+## Models and cost
+
+- Route by cognitive risk: Fable plans and reviews kernel-class changes; sol orchestrates; terra implements and audits; luna does bounded mechanical work. GPT (codex) and Claude accounts both exist; fail over on quota or auth errors only, never on test failures.
+- Fewer roundtrips, fewer tokens. A 15-minute direct fix beats a 45-minute worker round trip.

flpkit-0.8.1/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "flpkit"
+version = "0.8.1"
+description = "Read and write FL Studio .flp project files - a small, dependency-free library for the undocumented FLP format, with self-verifying raw-surgery writers"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = []
+authors = [{ name = "Origami Research" }]
+keywords = ["fl-studio", "flp", "daw", "midi", "music"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Sound/Audio",
+]
+
+[project.urls]
+Homepage = "https://github.com/clarkipeng/flpkit"
+Repository = "https://github.com/clarkipeng/flpkit"
+Issues = "https://github.com/clarkipeng/flpkit/issues"
+Changelog = "https://github.com/clarkipeng/flpkit/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flpkit"]
+
+[dependency-groups]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "BLE", "TRY", "SIM", "PTH", "TID", "RUF"]
+ignore = ["TRY003", "E501"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

flpkit-0.8.1/scripts/check-release.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Validate the exact artifact path users receive from PyPI. No publish occurs.
+set -euo pipefail
+
+repo_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+dist_dir="$repo_root/dist"
+temp_dir=$(mktemp -d)
+trap 'rm -rf "$temp_dir"' EXIT
+
+rm -rf "$dist_dir"
+uv build --out-dir "$dist_dir" "$repo_root"
+
+sdist=$(find "$dist_dir" -maxdepth 1 -name 'flpkit-*.tar.gz' -print -quit)
+test -n "$sdist"
+rebuilt_dist="$temp_dir/rebuilt-dist"
+uv build --wheel --out-dir "$rebuilt_dist" "$sdist"
+
+wheel=$(find "$rebuilt_dist" -maxdepth 1 -name 'flpkit-*.whl' -print -quit)
+test -n "$wheel"
+venv_dir="$temp_dir/venv"
+uv venv "$venv_dir"
+uv pip install --python "$venv_dir/bin/python" "$wheel"
+
+golden="$repo_root/tests/golden/tempo-patch-in-place.flp"
+sample="$temp_dir/roundtrip.flp"
+cp "$golden" "$sample"
+(
+    cd "$temp_dir"
+    "$venv_dir/bin/python" - "$sample" <<'PY'
+from pathlib import Path
+import sys
+
+import flpkit
+
+path = Path(sys.argv[1])
+project = flpkit.read(path)
+if project.tempo is None:
+    raise RuntimeError("golden fixture must contain an explicit tempo")
+saved_tempo = flpkit.set_tempo(path, project.tempo)
+round_tripped = flpkit.read(path)
+assert round_tripped.tempo == saved_tempo
+print(f"flpkit {flpkit.__version__}: imported and round-tripped {path.name} at {saved_tempo:g} BPM")
+PY
+)