From ffd5a4a22b7557723b5a1138bc73e98eafff9abc Mon Sep 17 00:00:00 2001 From: aiongg Date: Sat, 31 Oct 2026 04:17:15 +0000 Subject: [PATCH] docs: tidy agent, contributor and asset docs --- AGENTS.md | 18 ++++++------------ CLAUDE.md | 11 ++++------- README.zh-hans.md | 2 +- assets/ATTRIBUTION.md | 2 +- assets/app-icon/README.md | 5 ++--- contributors/people.toml | 7 ++----- crates/engine/src/fonts.rs | 2 +- crates/sysmem/Cargo.toml | 3 +-- crates/ui-egui/build.rs | 4 ++-- crates/ui-egui/src/dialogs/credits.rs | 2 +- docs/contributors.md | 25 ++++--------------------- docs/target-app-parity.md | 2 +- flake.nix | 2 +- 13 files changed, 27 insertions(+), 58 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4044a6563..f10fedb20 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,8 +14,7 @@ LightCraft is a clean-room, open-source, pure-Rust photo library + non-destructi 4. **Pick work** from [`docs/gaps.md`](docs/gaps.md) (ranked by user impact; `B` marks beta blockers). The row-by-row tracker is [`docs/parity-checklist.md`](docs/parity-checklist.md) (one row per feature, menu item and shortcut). When you land a feature, update its row(s) and the gap entry in the same commit, and the numbers in `ROADMAP.md` / - `docs/target-app-parity.md` when a listed gap closes (bump each doc's *Last updated* line and revision history, per - craftrules `standards/progress-docs.md`); `cargo xtask parity` (part of `ci`) checks that every `cmd:`/`ctl:` id and + `docs/target-app-parity.md` when a listed gap closes (bump each doc's *Last updated* line and revision history); `cargo xtask parity` (part of `ci`) checks that every `cmd:`/`ctl:` id and path the tracker cites still exists, and `cargo xtask parity --write` refreshes its summary. 5. Follow the autonomous operation protocol (`plan/execution-plan.md` §7). Don't stop to ask unless §7 lists the decision as the user's. @@ -32,8 +31,7 @@ and often so a crash loses minutes, not hours. People trust LightCraft with their photo libraries and edits; a crash loses their work. A malformed raw/JPEG/XMP, a bad command, control or MCP argument, a corrupt catalog or settings file, or a full disk must produce an error the user (or agent) can act on, never a panic. Don't ship a feature by adding a panic path, and fix a crash before building on top -of it. Full standard: `../craftrules/standards/never-crash.md` -([storytold/craftrules](https://github.com/storytold/craftrules/blob/main/standards/never-crash.md)). +of it. - **Non-test code never panics:** no `unwrap()`, `expect()`, `panic!`, `unreachable!`, `todo!`, `unimplemented!`, and no `unsafe`. Return the crate's error type through `Result` and `?`; use `ok_or(..)?`, `let … else`, `if let`, or a fallback (`unwrap_or…`) only where it can't silently corrupt a document. An unfinished feature returns an @@ -86,8 +84,7 @@ of it. Full standard: `../craftrules/standards/never-crash.md` (`theme::font_definitions`) and the export watermark renderer use CJK faces (picked by script) as fallbacks after Inter. Unset, `CRAFT_FONTS` is empty: everything builds, tests and runs, but Chinese and Japanese text lack glyphs. Releases always build with it (`release.yml`, `CRAFT_FONTS_REQUIRED=1`) and ship the fonts' OFL licences. Tests that need these fonts skip - without it; the FreeBSD CI job runs them with it. Rules: craftrules - [`standards/fonts.md`](https://github.com/storytold/craftrules/blob/main/standards/fonts.md). + without it; the FreeBSD CI job runs them with it. - Icons drawn in code (e.g. `crates/ui-egui/src/icons.rs`) are original work and are recorded in `assets/ATTRIBUTION.md` as such; do not trace them from Adobe icons. - Demo/test images: generated procedurally by `lightcraft-scenes`, or CC0 downloads kept in the gitignored `corpus/` with their source recorded. Screenshots of Adobe apps live only in the gitignored `plan/` and are never committed or published. - **Enforced:** `cargo xtask assets` (in `ci`) fails when an image/icon/font/sound/video/raw/ICC/XMP file is not matched @@ -113,7 +110,7 @@ of it. Full standard: `../craftrules/standards/never-crash.md` - Shell gotcha: `mv`/`cp` are aliased interactive here — use `/bin/mv -f` / `/bin/cp -f`. - Parallel agents: separate git worktrees and `CARGO_TARGET_DIR=target/agent-`; each agent uses its **own control port** (pick one in 18000–19999, never the default 7980) and its own scratch subfolder (`//`) — never `rm -rf` shared paths; delete your target dir when done (disk is shared); keep every `Cargo.toml` valid at all times (the `crates/*` glob means one broken manifest breaks everyone). - Test corpora: `cargo xtask corpus --download` into `corpus/` (gitignored, CC0 only). Never commit media. -- Shared real-file test corpora (Photoshop-authored PSDs, etc.) live in [`storytold/photocraft-corpus`](https://github.com/storytold/photocraft-corpus), explained in [craftrules `standards/test-corpora.md`](https://github.com/storytold/craftrules/blob/main/standards/test-corpora.md). Never commit large binary fixtures to this repo; fetch them pinned by commit and sha256-verified, as PhotoCraft does with `cargo xtask corpus`. +- Shared real-file test corpora (Photoshop-authored PSDs, etc.) live in [`storytold/photocraft-corpus`](https://github.com/storytold/photocraft-corpus). Never commit large binary fixtures to this repo; fetch them pinned by commit and sha256-verified, as PhotoCraft does with `cargo xtask corpus`. ## Testing & performance (do this often) - Unit/property tests next to the code; end-to-end tests drive real binaries (`crates/mcp/tests/e2e.rs`, @@ -142,20 +139,17 @@ evaluates it (`.github/workflows/nix.yml`), so the build may lag behind the work ## Contributor credits (About window) - About ▸ Contributors/Models are compiled into the binary from `contributors/contributors.json` - (commit stats; generated, never hand-edit) and `contributors/people.toml` (names people chose for + (commit stats; never hand-edit) and `contributors/people.toml` (names people chose for themselves). See `docs/contributors.md`. - **Agents working for a contributor:** when you prepare a PR, check whether your human's GitHub 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/CLAUDE.md b/CLAUDE.md index 9b384fc6c..0597cbf46 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,8 +14,7 @@ LightCraft is a clean-room, open-source, pure-Rust photo library + non-destructi 4. **Pick work** from [`docs/gaps.md`](docs/gaps.md) (ranked by user impact; `B` marks beta blockers). The row-by-row tracker is [`docs/parity-checklist.md`](docs/parity-checklist.md) (one row per feature, menu item and shortcut). When you land a feature, update its row(s) and the gap entry in the same commit, and the numbers in `ROADMAP.md` / - `docs/target-app-parity.md` when a listed gap closes (bump each doc's *Last updated* line and revision history, per - craftrules `standards/progress-docs.md`); `cargo xtask parity` (part of `ci`) checks that every `cmd:`/`ctl:` id and + `docs/target-app-parity.md` when a listed gap closes (bump each doc's *Last updated* line and revision history); `cargo xtask parity` (part of `ci`) checks that every `cmd:`/`ctl:` id and path the tracker cites still exists and that `docs/gaps.md` lists each gap once, and `cargo xtask parity --write` refreshes its summary. 5. Follow the autonomous operation protocol (`plan/execution-plan.md` §7). Don't stop to ask unless §7 lists the decision as the user's. @@ -33,8 +32,7 @@ and often so a crash loses minutes, not hours. People trust LightCraft with their photo libraries and edits; a crash loses their work. A malformed raw/JPEG/XMP, a bad command, control or MCP argument, a corrupt catalog or settings file, or a full disk must produce an error the user (or agent) can act on, never a panic. Don't ship a feature by adding a panic path, and fix a crash before building on top -of it. Full standard: `../craftrules/standards/never-crash.md` -([storytold/craftrules](https://github.com/storytold/craftrules/blob/main/standards/never-crash.md)). +of it. - **Non-test code never panics:** no `unwrap()`, `expect()`, `panic!`, `unreachable!`, `todo!`, `unimplemented!`, and no `unsafe`. Return the crate's error type through `Result` and `?`; use `ok_or(..)?`, `let … else`, `if let`, or a fallback (`unwrap_or…`) only where it can't silently corrupt a document. An unfinished feature returns an @@ -97,8 +95,7 @@ of it. Full standard: `../craftrules/standards/never-crash.md` (`theme::font_definitions`) and the export watermark renderer use CJK faces (picked by script) as fallbacks after Inter; the UI also falls back on the faces of other scripts (Thai, Arabic, …). Unset, `CRAFT_FONTS` is empty: everything builds, tests and runs, but Chinese and Japanese text lack glyphs. Releases always build with it (`release.yml`, `CRAFT_FONTS_REQUIRED=1`) and ship the fonts' OFL licences. Tests that need these fonts skip - without it; the FreeBSD CI job runs them with it. Rules: craftrules - [`standards/fonts.md`](https://github.com/storytold/craftrules/blob/main/standards/fonts.md). + without it; the FreeBSD CI job runs them with it. - Icons drawn in code (e.g. `crates/ui-egui/src/icons.rs`) are original work and are recorded in `assets/ATTRIBUTION.md` as such; do not trace them from Adobe icons. - Demo/test images: generated procedurally by `lightcraft-scenes`, or CC0 downloads kept in the gitignored `corpus/` with their source recorded. Screenshots of Adobe apps live only in the gitignored `plan/` and are never committed or published. - **Enforced:** `cargo xtask assets` (in `ci`) fails when an image/icon/font/sound/video/raw/ICC/XMP file is not matched @@ -127,7 +124,7 @@ of it. Full standard: `../craftrules/standards/never-crash.md` - Shell gotcha: `mv`/`cp` are aliased interactive here — use `/bin/mv -f` / `/bin/cp -f`. - Parallel agents: separate git worktrees and `CARGO_TARGET_DIR=target/agent-`; each agent uses its **own control port** (pick one in 18000–19999, never the default 7980) and its own scratch subfolder (`//`) — never `rm -rf` shared paths; delete your target dir when done (disk is shared); keep every `Cargo.toml` valid at all times (the `crates/*` glob means one broken manifest breaks everyone). - Test corpora: `cargo xtask corpus --download` into `corpus/` (gitignored, CC0 only). Never commit media. -- Shared real-file test corpora (Photoshop-authored PSDs, etc.) live in [`storytold/photocraft-corpus`](https://github.com/storytold/photocraft-corpus), explained in [craftrules `standards/test-corpora.md`](https://github.com/storytold/craftrules/blob/main/standards/test-corpora.md). Never commit large binary fixtures to this repo; fetch them pinned by commit and sha256-verified, as PhotoCraft does with `cargo xtask corpus`. +- Shared real-file test corpora (Photoshop-authored PSDs, etc.) live in [`storytold/photocraft-corpus`](https://github.com/storytold/photocraft-corpus). Never commit large binary fixtures to this repo; fetch them pinned by commit and sha256-verified, as PhotoCraft does with `cargo xtask corpus`. ## Testing & performance (do this often) - Unit/property tests next to the code; end-to-end tests drive real binaries (`crates/mcp/tests/e2e.rs`, diff --git a/README.zh-hans.md b/README.zh-hans.md index fa782ba10..bce9b89e6 100644 --- a/README.zh-hans.md +++ b/README.zh-hans.md @@ -392,7 +392,7 @@ CRAFT_FONTS_DIR=../craft-fonts cargo run --release -p lightcraft ``` 不指定它时，LightCraft 构建和运行的方式完全相同，只是中文和日文文字没有字形。字体从不提交到 -本仓库；见 [craftrules `standards/fonts.md`](https://github.com/storytold/craftrules/blob/main/standards/fonts.md)。 +本仓库。 **界面语言：** **编辑 → 语言**（English、简体中文、繁體中文（台灣）、日本語、Português (Brasil)、Español、Deutsch、Русский、Français）或 **设置 → 一般 → 语言**；选择立即生效并会保留。见 [docs/localization.md](docs/localization.md)。 diff --git a/assets/ATTRIBUTION.md b/assets/ATTRIBUTION.md index e5ed8090e..d95e95b41 100644 --- a/assets/ATTRIBUTION.md +++ b/assets/ATTRIBUTION.md @@ -53,4 +53,4 @@ Notes - CJK fonts (BIZ UDPGothic, BIZ UDMincho, Shippori Mincho, Noto Sans CJK SC) are not in this repository. They live in [storytold/craft-fonts](https://github.com/storytold/craft-fonts), with their licences and attribution in its `ATTRIBUTION.md`, and are embedded only in builds made with the optional `CRAFT_FONTS_DIR` build input (all official - releases). Never commit font files here; add new fonts to craft-fonts (craftrules `standards/fonts.md`). + releases). Never commit font files here; add new fonts to craft-fonts. diff --git a/assets/app-icon/README.md b/assets/app-icon/README.md index 2a6dd4b88..ff6aafd65 100644 --- a/assets/app-icon/README.md +++ b/assets/app-icon/README.md @@ -20,9 +20,8 @@ Windows and Linux files use the full-bleed tile so the lynx reads at 16-48 px. ## Provenance -The owner's original drawing, made in ArtCraft (2880 px, keyed to the three colours), vectorised with -craftrules `assets/logo-options/_tools/vectorize_tile.py`. The source drawing stays in craftrules at -`assets/app-icons/lightcraft/source.png`; `lightcraft.svg` here is the canonical artwork. Licence: +The owner's original drawing, made in ArtCraft (2880 px, keyed to the three colours) and +vectorised. `lightcraft.svg` here is the canonical artwork. Licence: `LICENSE.txt` (MIT OR Apache-2.0, like the repo). ## Files diff --git a/contributors/people.toml b/contributors/people.toml index 7518acd38..27e9f3a52 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/engine/src/fonts.rs b/crates/engine/src/fonts.rs index db9e658d0..c45f5f94b 100644 --- a/crates/engine/src/fonts.rs +++ b/crates/engine/src/fonts.rs @@ -3,7 +3,7 @@ //! Built with `CRAFT_FONTS_DIR=`, [`CRAFT_FONTS`] holds every font in its //! manifest (today: the Japanese and Simplified-Chinese UI and document fonts); otherwise it is //! empty and LightCraft uses only its own bundled fonts (Inter). Both the egui UI and the export -//! watermark renderer read it from here. See craftrules `standards/fonts.md`. +//! watermark renderer read it from here. /// A font from the optional craft-fonts build input (empty unless built with `CRAFT_FONTS_DIR`). pub struct CraftFont { diff --git a/crates/sysmem/Cargo.toml b/crates/sysmem/Cargo.toml index a7f0492c6..52ad5d206 100644 --- a/crates/sysmem/Cargo.toml +++ b/crates/sysmem/Cargo.toml @@ -6,8 +6,7 @@ license.workspace = true description = "LightCraft sysmem (L0): returns freed allocator memory to the OS. The workspace's only crate allowed `unsafe` (one FFI call)." # Opts out of the workspace lints only to keep `unsafe_code = "deny"` overridable for the single FFI -# module below; every other crate root has `#![forbid(unsafe_code)]`. See AGENTS.md and craftrules -# standards/never-crash.md ("isolated helper library crate"). +# module below; every other crate root has `#![forbid(unsafe_code)]`. See AGENTS.md. [lints.rust] unsafe_code = "deny" diff --git a/crates/ui-egui/build.rs b/crates/ui-egui/build.rs index 9d8300e8e..a0b453f24 100644 --- a/crates/ui-egui/build.rs +++ b/crates/ui-egui/build.rs @@ -12,8 +12,8 @@ //! macro's last arm. `i18n::tests::translation_gaps_report` lists the gaps per language. //! //! It also bakes the contributor credits into the binary as static Rust tables (`$OUT_DIR/credits.rs`, -//! included by `src/credits.rs`; craftrules `standards/contributors.md`): commit stats from -//! `contributors/contributors.json` (generated by craftrules `scripts/contributors.py`) and the names +//! included by `src/credits.rs`): commit stats from +//! `contributors/contributors.json` and the names //! people chose for themselves from `contributors/people.toml`. Nothing is read at run time. A //! missing or malformed file gives empty tables (or usernames only) and a warning, never a failed build. use std::{ diff --git a/crates/ui-egui/src/dialogs/credits.rs b/crates/ui-egui/src/dialogs/credits.rs index 578616068..12f857705 100644 --- a/crates/ui-egui/src/dialogs/credits.rs +++ b/crates/ui-egui/src/dialogs/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/docs/contributors.md b/docs/contributors.md index 78e234dfa..faf47dc71 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 LightCraft, 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. - [`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 @@ -39,20 +37,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/target-app-parity.md b/docs/target-app-parity.md index d72c165c4..f2edebc24 100644 --- a/docs/target-app-parity.md +++ b/docs/target-app-parity.md @@ -110,7 +110,7 @@ pure-Rust inference is proven (faces, SAM 3, denoise). ## Ready for real work, mainstream practitioner and essentials user -Three readiness numbers (craftrules `standards/progress-docs.md`). The full number is a weighted +Three readiness numbers. The full number is a weighted sum over the dimensions with written weights. Mainstream and essentials take the weighted depth of the areas their user touches, then apply written multiplicative discounts for what still stops real work. Each has its own hours to ~95%, calibrated as in [How hours are calibrated](#how-hours-are-calibrated) diff --git a/flake.nix b/flake.nix index faa7e1d2e..e6dca1419 100644 --- a/flake.nix +++ b/flake.nix @@ -14,7 +14,7 @@ # is not part of that default set and is not embedded. Official releases always build with the # default fonts; without them everything works but non-Latin text lacks glyphs. Pinned to the same # revision CI, the release workflow and the standalone packaging helpers use — bump all of them - # together (`nix flake update craft-fonts`); craftrules standards/fonts.md. + # together (`nix flake update craft-fonts`). craft-fonts = { url = "github:storytold/craft-fonts/b076417b5880bd4154bd22f00695b1d28c6bea83"; flake = false;