diff --git a/AGENTS.md b/AGENTS.md index b48565c8..065e8313 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,11 +2,9 @@ SoundCraft is a clean-room, open-source, pure-Rust digital audio workstation targeting Avid Pro Tools parity — and superiority (speed, openness, agent control). It runs natively on macOS, Windows, Linux and FreeBSD, and on the web via WASM. Siblings with the same conventions: `../photocraft` (Photoshop), `../vectorcraft` (Illustrator), `../filmcraft` (Premiere), `../lightcraft` (Lightroom), `../pdfcraft` (Acrobat), `../effectcraft` (After Effects), `../designcraft` (InDesign). -Standards and learnings shared across the crafting apps live in `../../craftrules` (checked out next to the craft-apps folder, or `storytold/craftrules`). Read its `AGENTS.md` at the start of a session, follow its standards, and contribute reusable learnings back there. Never code: repos don't share code. - ## Start every session here 1. Read `plan/STATUS.md` (current milestone, next task) and `plan/execution-plan.md`. `plan/` is gitignored (local only). Behaviour reference: `plan/protools/` (observed menu tree `menus-clean.txt` and screenshots; never committed). -2. Read `ROADMAP.md` (committed) for stage, status and the parity numbers; pick work from `docs/gaps.md`. The progress docs follow craftrules `standards/progress-docs.md`: `docs/target-app-parity.md` (assessment), `docs/gaps.md`, `docs/roadmap.md`, `docs/ui-parity.md`, `docs/file-format-parity.md`, `docs/hardware-parity.md`, `docs/plugin-parity.md`, `docs/localization-parity.md`; `docs/parity-checklist.md` is generated. Update their timestamps and revision history when you change them. +2. Read `ROADMAP.md` (committed) for stage, status and the parity numbers; pick work from `docs/gaps.md`. The progress docs are `docs/target-app-parity.md` (assessment), `docs/gaps.md`, `docs/roadmap.md`, `docs/ui-parity.md`, `docs/file-format-parity.md`, `docs/hardware-parity.md`, `docs/plugin-parity.md`, `docs/localization-parity.md`; `docs/parity-checklist.md` is generated. Update their timestamps and revision history when you change them. 3. Work autonomously; don't stop to ask unless a decision is genuinely the user's. ## ⚠️ Assets: the absolute rule @@ -22,7 +20,7 @@ Standards and learnings shared across the crafting apps live in `../../craftrule Pro Tools is installed on the dev machine and may be *observed* black-box: run it, use its UI with synthetic sessions, take screenshots by window id (`screencapture -l `), stored only under `plan/protools/screenshots/`. Never read, disassemble or copy anything inside the Pro Tools bundle; never copy Avid icons, artwork, plugin names, presets, or wording beyond feature names. Never copy GPL/AGPL/LGPL code (Ardour, Audacity, LMMS, Freeverb sources…). Our plugins have our own names. ## Never crash -People trust SoundCraft with their recordings; a crash loses takes. **This outranks feature work.** Standard: [`craftrules/standards/never-crash.md`](https://github.com/storytold/craftrules/blob/main/standards/never-crash.md). +People trust SoundCraft with their recordings; a crash loses takes. **This outranks feature work.** - No panics in non-test code: no `unwrap()`, `expect()`, `panic!`, `unreachable!`, `todo!`, `unimplemented!`; no `unsafe` (`unsafe_code = "forbid"`). - The one named exception is `soundcraft-clap-host` (`crates/clap-host`), the isolated unsafe helper crate for CLAP plugin FFI: `unsafe_code = "deny"` crate-wide, allowed only in `src/ffi.rs` with a `// SAFETY:` comment on every block, safe `Result` API. - The same exception, same rules, for `soundcraft-vst3-host` (`crates/vst3-host`), the isolated unsafe helper crate for VST3 plugin FFI (COM vtables via the `vst3` bindings, module loading, host-side COM objects). @@ -67,7 +65,7 @@ Parity is measured, not guessed: `crates/engine/catalog/menus.txt` lists the inc `cargo xtask ci` = fmt check, `clippy --workspace --all-targets -D warnings`, tests, assets, layers, wasm check. Commit after each arc of work that builds; one topic per commit. ## Release -Push to the `release` branch to build signed installers for macOS (universal DMG), Windows (x64/x86 MSI + zip), Linux (AppImage, deb, rpm, tar.gz, Flatpak; riscv64 tar.gz), FreeBSD and Web (wasm zip). Version: `cargo xtask version [set X.Y.Z]`. See `docs/release-playbook.md` and craftrules `release/playbook.md`. +Push to the `release` branch to build signed installers for macOS (universal DMG), Windows (x64/x86 MSI + zip), Linux (AppImage, deb, rpm, tar.gz, Flatpak; riscv64 tar.gz), FreeBSD and Web (wasm zip). Version: `cargo xtask version [set X.Y.Z]`. See `docs/releasing.md`. ## Roadmap `ROADMAP.md` (committed) is the one-page summary (stage, numbers, dimensions, languages, progress log); milestones live in `docs/roadmap.md`. Update both whenever a milestone lands, and close or shrink the matching `docs/gaps.md` entry. @@ -81,14 +79,11 @@ Push to the `release` branch to build signed installers for macOS (universal DMG username has a `[people.]` entry in `contributors/people.toml`. If not, ask them once whether they want to be credited by more than their username: a real name, a display name, and/or their public GitHub profile name (`sync_github_name = true`). If yes, add **only their own** entry - (copy the template at the top of the file, or run - `python3 ../../craftrules/scripts/contributors.py --add-me . --real-name "…" --sync-github-name`) + (copy the template at the top of the file) and include it in their PR, committed as them. If no, change nothing: they are credited as `@username` anyway. - Never add, edit, guess or copy anyone else's entry or name (not from git config, commit authors or GitHub profiles). Never hand-edit `contributors.json`. -- Maintainers refresh the stats with `python3 ../../craftrules/scripts/contributors.py .` (it also - re-verifies who wrote each `people.toml` entry; `--check` only verifies). ## CI workflows - Workflows in `.github/workflows/` call the shared workflows in [`storytold/craft-common-actions`](https://github.com/storytold/craft-common-actions) at `@main`, with their inputs and secrets. No other jobs: if no shared workflow does what's needed, it doesn't go here. diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 00927097..dc168fa4 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -39,14 +39,14 @@ here. The subset uses default_fonts; the parent face uses monochrome_emoji_fonts | Path | Author | Source | License | |---|---|---|---| -| `docs/brand/artcraft-logo.svg` | ArtCraft Team | craftrules `assets/brand/` | ArtCraft brand terms (`docs/brand/LICENSE-brand.txt`) | -| `docs/brand/artcraft-logo.png` | ArtCraft Team | craftrules `assets/brand/` | ArtCraft brand terms | -| `docs/brand/artcraft-logo-white.svg` | ArtCraft Team | craftrules `assets/brand/` | ArtCraft brand terms | -| `docs/brand/artcraft-logo-white.png` | ArtCraft Team | craftrules `assets/brand/` | ArtCraft brand terms | -| `docs/brand/artcraft-mark.svg` | ArtCraft Team | craftrules `assets/brand/` | ArtCraft brand terms | -| `docs/brand/artcraft-mark.png` | ArtCraft Team | craftrules `assets/brand/` | ArtCraft brand terms | -| `docs/brand/artcraft-mark-black.svg` | ArtCraft Team | craftrules `assets/brand/` | ArtCraft brand terms | -| `docs/brand/artcraft-mark-black.png` | ArtCraft Team | craftrules `assets/brand/` | ArtCraft brand terms | +| `docs/brand/artcraft-logo.svg` | ArtCraft Team | ArtCraft brand assets | ArtCraft brand terms (`docs/brand/LICENSE-brand.txt`) | +| `docs/brand/artcraft-logo.png` | ArtCraft Team | ArtCraft brand assets | ArtCraft brand terms | +| `docs/brand/artcraft-logo-white.svg` | ArtCraft Team | ArtCraft brand assets | ArtCraft brand terms | +| `docs/brand/artcraft-logo-white.png` | ArtCraft Team | ArtCraft brand assets | ArtCraft brand terms | +| `docs/brand/artcraft-mark.svg` | ArtCraft Team | ArtCraft brand assets | ArtCraft brand terms | +| `docs/brand/artcraft-mark.png` | ArtCraft Team | ArtCraft brand assets | ArtCraft brand terms | +| `docs/brand/artcraft-mark-black.svg` | ArtCraft Team | ArtCraft brand assets | ArtCraft brand terms | +| `docs/brand/artcraft-mark-black.png` | ArtCraft Team | ArtCraft brand assets | ArtCraft brand terms | | `assets/app-icon/icon.svg` | SoundCraft contributors | original (hand-placed SVG paths; placeholder app icon) | MIT OR Apache-2.0 | | `packaging/macos/dmg/` (all files) | @XusBadia | original (macOS DMG window background and layout, from the app icon; see `packaging/macos/dmg/README.md`) | MIT OR Apache-2.0 | | `assets/app-icon/soundcraft-1024.png` | SoundCraft contributors | original, rendered from `icon.svg` | MIT OR Apache-2.0 | diff --git a/assets/app-icon/README.md b/assets/app-icon/README.md index 12cea9c2..196473c9 100644 --- a/assets/app-icon/README.md +++ b/assets/app-icon/README.md @@ -1,7 +1,7 @@ # SoundCraft app icon (placeholder) **A nightingale singing**, as an engraving-style head-and-shoulders portrait in the Crafting Apps' -owl-template framing (craftrules `standards/icon-design.md`): a full-bleed colour field, the bird +owl-template framing: a full-bleed colour field, the bird in three-quarter view with its bill open and its eye on the viewer, its breast and wing running off the bottom and right edges, three song arcs leaving the bill. diff --git a/contributors/people.toml b/contributors/people.toml index 1f6e43e8..e6fab691 100644 --- a/contributors/people.toml +++ b/contributors/people.toml @@ -1,13 +1,10 @@ -# Contributor names for the About window (craftrules standards/contributors.md). +# Contributor names for the About window. # # Everyone who contributes is credited by GitHub username automatically. Anything more is up to # you: add YOUR OWN entry below, in your own PR (commit it yourself). Never add someone else; a # maintainer may add a person only when that person asked, recording where in consent_source. # -# Easiest: python3 ../../craftrules/scripts/contributors.py --add-me . \ -# [--real-name "Ada Lovelace"] [--display-name "Ada"] [--sync-github-name] -# -# Or copy this block, replacing your-github-username (every field is optional): +# Copy this block, replacing your-github-username (every field is optional): # # [people.your-github-username] # real_name = "Your Name" # shown when the viewer picks "Real name" diff --git a/crates/au-host/Cargo.toml b/crates/au-host/Cargo.toml index 122c4919..4e190104 100644 --- a/crates/au-host/Cargo.toml +++ b/crates/au-host/Cargo.toml @@ -13,7 +13,7 @@ serde.workspace = true thiserror.workspace = true log.workspace = true -# An isolated unsafe helper crate (craftrules never-crash), like soundcraft-vst3-host: this crate +# An isolated unsafe helper crate, like soundcraft-vst3-host: this crate # opts out of the workspace `unsafe_code = "forbid"` for itself only. It denies unsafe everywhere # and allows it solely on the FFI module (`src/ffi.rs`). The rest mirrors `[workspace.lints]`. [lints.rust] diff --git a/crates/au-host/src/lib.rs b/crates/au-host/src/lib.rs index 7aa3b2eb..cbb569fb 100644 --- a/crates/au-host/src/lib.rs +++ b/crates/au-host/src/lib.rs @@ -9,7 +9,7 @@ //! values are the Audio Unit's own (plain) values, ranges and units, so no mapping is needed. //! Boolean parameters become toggles, indexed ones starting at 0 become choices. //! -//! Like `soundcraft-vst3-host`, this is an isolated `unsafe` crate (craftrules never-crash): +//! Like `soundcraft-vst3-host`, this is an isolated `unsafe` crate: //! `unsafe` is denied crate-wide and allowed only in the private `ffi` module (hand-written //! AudioToolbox / CoreFoundation declarations). The public API is safe, returns //! `Result`/`Option` and never panics. Limits of in-process hosting: an Audio Unit that itself diff --git a/crates/clap-host/Cargo.toml b/crates/clap-host/Cargo.toml index 27eaf561..fa719ac7 100644 --- a/crates/clap-host/Cargo.toml +++ b/crates/clap-host/Cargo.toml @@ -25,7 +25,7 @@ harness = false clap-sys = "0.5" libloading = "0.9" -# The isolated unsafe helper crate (craftrules never-crash): this crate opts out of the workspace +# The isolated unsafe helper crate: this crate opts out of the workspace # `unsafe_code = "forbid"` for itself only. It denies unsafe everywhere and allows it solely on the # FFI module (`src/ffi.rs`). The rest mirrors `[workspace.lints]`. [lints.rust] diff --git a/crates/clap-host/src/lib.rs b/crates/clap-host/src/lib.rs index a5e042a3..7142a9ee 100644 --- a/crates/clap-host/src/lib.rs +++ b/crates/clap-host/src/lib.rs @@ -5,7 +5,7 @@ //! plugins exactly like the built-in ones. Plugin ids are `clap:`; parameter ids //! are the CLAP param ids as decimal strings, with their human names in [`PluginInfo::params`]. //! -//! This is SoundCraft's single isolated `unsafe` crate (craftrules never-crash): `unsafe` is +//! This is SoundCraft's single isolated `unsafe` crate: `unsafe` is //! denied crate-wide and allowed only in the private `ffi` module. The public API is safe, returns //! `Result`/`Option` and never panics. Limits of in-process hosting: a plugin that itself crashes //! (segfault) takes the process down with it; we cannot sandbox native code. diff --git a/crates/ui-egui/build.rs b/crates/ui-egui/build.rs index f40007fb..3116b01d 100644 --- a/crates/ui-egui/build.rs +++ b/crates/ui-egui/build.rs @@ -1,8 +1,7 @@ -//! Bake the contributor credits into the binary as static Rust tables (craftrules -//! standards/contributors.md). Nothing is read at run time. +//! Bake the contributor credits into the binary as static Rust tables. Nothing is read at run time. //! -//! - contributors/contributors.json: commit stats per GitHub username, generated by craftrules -//! scripts/contributors.py, which also marks whose people.toml entry it verified. +//! - contributors/contributors.json: commit stats per GitHub username, with a mark for whose people.toml +//! entry is verified. //! - contributors/people.toml: the names people chose for themselves. A name is used only when the //! JSON says the entry was verified (`people_entry`). //! diff --git a/crates/ui-egui/src/credits.rs b/crates/ui-egui/src/credits.rs index c22c4720..42804e02 100644 --- a/crates/ui-egui/src/credits.rs +++ b/crates/ui-egui/src/credits.rs @@ -1,6 +1,6 @@ //! The About window's credits: every contributor (GitHub login always; display and real names only //! with recorded consent) and the AI models that helped. The tables are baked into the binary by -//! build.rs from contributors/contributors.json (craftrules standards/contributors.md); nothing is +//! build.rs from contributors/contributors.json; nothing is //! read at run time. use std::cmp::Ordering; diff --git a/crates/vst3-host/Cargo.toml b/crates/vst3-host/Cargo.toml index 7a956118..284e7d54 100644 --- a/crates/vst3-host/Cargo.toml +++ b/crates/vst3-host/Cargo.toml @@ -47,7 +47,7 @@ harness = false name = "module_exit_shutdown" harness = false -# An isolated unsafe helper crate (craftrules never-crash), like soundcraft-clap-host: this crate +# An isolated unsafe helper crate, like soundcraft-clap-host: this crate # opts out of the workspace `unsafe_code = "forbid"` for itself only. It denies unsafe everywhere # and allows it solely on the FFI module (`src/ffi.rs`). The rest mirrors `[workspace.lints]`. [lints.rust] diff --git a/crates/vst3-host/src/lib.rs b/crates/vst3-host/src/lib.rs index 9c76446c..a0324f88 100644 --- a/crates/vst3-host/src/lib.rs +++ b/crates/vst3-host/src/lib.rs @@ -8,7 +8,7 @@ //! [`PluginInfo::params`]. Values are plain (display) values; the host converts to and from the //! VST3 normalized 0..1 values. Stepped parameters become toggles or choices. //! -//! Like `soundcraft-clap-host`, this is an isolated `unsafe` crate (craftrules never-crash): +//! Like `soundcraft-clap-host`, this is an isolated `unsafe` crate: //! `unsafe` is denied crate-wide and allowed only in the private `ffi` module. The public API is //! safe, returns `Result`/`Option` and never panics. Limits of in-process hosting: a plugin that //! itself crashes (segfault) takes the process down with it; we cannot sandbox native code. diff --git a/docs/contributors.md b/docs/contributors.md index bf35050d..33312ac4 100644 --- a/docs/contributors.md +++ b/docs/contributors.md @@ -1,16 +1,14 @@ # Contributors in the About window **About ▸ Contributors** credits everyone who contributed to SoundCraft, and **About ▸ Models** credits -the AI models named in `Co-Authored-By` trailers. This follows the shared craftrules standard -[`standards/contributors.md`](https://github.com/storytold/craftrules/blob/main/standards/contributors.md); -this page is the local copy of the decision. +the AI models named in `Co-Authored-By` trailers. ## Decision - Two files, both **compiled into the binary** by the UI crate's `build.rs` (nothing is read from disk or the network at run time; the web build has them too): - [`contributors/contributors.json`](../contributors/contributors.json): commit stats per GitHub - username. **Generated** by `craftrules/scripts/contributors.py`; never hand-edit. + username. Never hand-edit. - [`contributors/people.toml`](../contributors/people.toml): the names people chose for themselves. **Each contributor adds only their own entry**, in their own PR. - Each contributor gets one line: GitHub username (always), display name (opt-in, or their synced @@ -36,20 +34,5 @@ display_name = "Nickname" sync_github_name = true # use the name on your public GitHub profile as display name ``` -or, with craftrules checked out next to `craft-apps/`: - -```sh -python3 ../../craftrules/scripts/contributors.py --add-me . --real-name "Your Name" --sync-github-name -``` - -Names show after the next refresh: the script checks that each entry was committed by its own -user (or by a maintainer with a `consent_source`). Delete your entry to remove your names. - -## Refreshing (maintainers) - -```sh -python3 ../../craftrules/scripts/contributors.py . # regenerate + verify; needs git, Python 3.11+, gh -python3 ../../craftrules/scripts/contributors.py --check . # verify people.toml only -``` - -Commit the updated `contributors/contributors.json`. Git author names and emails are never recorded. +Names show for entries committed by their own user (or by a maintainer with a `consent_source`). +Delete your entry to remove your names. Git author names and emails are never recorded. diff --git a/docs/release-playbook.md b/docs/release-playbook.md deleted file mode 100644 index aafba970..00000000 --- a/docs/release-playbook.md +++ /dev/null @@ -1,9 +0,0 @@ -# Release playbook - -The release playbook shared by every crafting app lives in craftrules: -[`../craftrules/release/playbook.md`](../../craftrules/release/playbook.md) -(`storytold/craftrules`). It is the canonical copy; don't duplicate it here. - -SoundCraft's implementation (`.github/workflows/release.yml`, `packaging/`, -`cargo xtask version`) was copied from DesignCraft/PhotoCraft and renamed. SoundCraft-specific -details are in [releasing.md](releasing.md). diff --git a/docs/releasing.md b/docs/releasing.md index b877757c..0fdc3502 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -5,7 +5,7 @@ signed installers for macOS, Windows, Linux, FreeBSD and the web, then creates o **draft** GitHub Release named `SoundCraft v`. Nobody sees a draft until a maintainer publishes it. -This is SoundCraft's implementation of the shared [release playbook](release-playbook.md). +This file describes how SoundCraft is released. User-facing names say **SoundCraft**. Files, binaries and ids stay lowercase (`soundcraft---.`, `ai.storyteller.soundcraft`). @@ -208,8 +208,7 @@ are written with `umask 077` and deleted in `always()`/`finally` steps. | `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` | service principal for Azure Trusted Signing | | `AZURE_SIGNING_ENDPOINT`, `AZURE_SIGNING_ACCOUNT`, `AZURE_CERT_PROFILE` | Trusted Signing endpoint, account and profile | -`GITHUB_TOKEN` creates the release. Only the final job gets `contents: write`. Provisioning the -environment, ruleset and secrets for a new repo: craftrules `release/signing-setup.md`. +`GITHUB_TOKEN` creates the release. Only the final job gets `contents: write`. ## Icons diff --git a/docs/roadmap.md b/docs/roadmap.md index 5219a8e5..2e7eeeeb 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -18,8 +18,7 @@ Hours are Opus 5.5 agent-hours. ## Alpha gate The core workflows a Pro Tools professional does every day, checked end to end on macOS (the -main platform). Any **no** keeps SoundCraft **pre-alpha**, and those rows are the alpha checklist -(craftrules `standards/progress-docs.md`, Stages). +main platform). Any **no** keeps SoundCraft **pre-alpha**, and those rows are the alpha checklist. | Workflow | Works end to end? | Evidence | Hours to pass | |---|---|---|---:| diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md index db69e3b3..2bc915dd 100644 --- a/docs/target-app-parity.md +++ b/docs/target-app-parity.md @@ -96,7 +96,7 @@ every command is reachable from the CLI, the JSON control channel and MCP. ## Mainstream practitioner and essentials user -Both use the method in craftrules `standards/progress-docs.md`. Each multiplies a weighted depth +Both use one method. Each multiplies a weighted depth average by written-down discounts. Depths come from the [Feature areas](#feature-areas) table and the evidence there; issue numbers are `storytold/soundcraft` GitHub issues.