JusPrin — a long-lived fork of OrcaSlicer (open-source C++17 3D slicer, wxWidgets GUI, CMake build system).
This checkout holds two codebases: upstream OrcaSlicer (the upstream remote, SoftFever/OrcaSlicer) and the JusPrin fork's changes on top of it. Fork changes include everything under src/slic3r/GUI/JusPrin/ and the seams the fork added inside OrcaSlicer-owned files.
- Say "OrcaSlicer does X" only for behavior upstream ships. Behavior added by a fork commit is "JusPrin does X", even when it lives in an OrcaSlicer-owned file.
- Check before attributing; the file path is not enough. Run
git blameon the line, thengit branch -r --contains <sha> 'upstream/*'. No upstream branch containing the commit means the fork owns it. Rungit fetch upstreamfirst if the remote may be stale. - If you have not checked, say it is unverified whether the behavior is upstream or fork.
jusprin-devis the development branch. Start each change on a new branch from it and land the change there. It began at975c703f08, the merge of OrcaSlicer 2.5.0, and contains the earlier development branchesjusprin-newuiandui-walkthrough; start nothing new on those.mainis the stable branch and GitHub's default branch: the repository's front page, its issue forms, and the workflows GitHub runs on a schedule come from it.- Never force-push
main, so that people who cloned the repository never have to force-pull. Only in an extreme case with no other way out, and with Kenneth's yes, may an admin lift the GitHub protection that blocks force pushes and deletion. - For now
mainis also the release branch: it moves forward fromjusprin-devwhen a version is released, and releases are built from it. This may change if a separate release branch is added later.
- Never force-push
jusprin-v1holds JusPrin 1, for fixes to that version only.jusprin-v2-pocholds the experiments described below.- Take each OrcaSlicer release into
jusprin-devasagent-docs/jusprin/fork-stewardship.mdrule 10 describes.
.github/workflows/jusprin_release.yml builds a release into a draft on GitHub; its top comment says how to start it. It refuses the commit until it has all of these:
- The version, in
src/slic3r/GUI/JusPrin/Updates/Version.hpp, above every released JusPrin version. - The release notes, in
src/slic3r/GUI/JusPrin/Packaging/release-notes/<version>.md. - The Sentry secrets:
JUSPRIN_SENTRY_DSN, the project the app sends error reports and crashes to, andSENTRY_AUTH_TOKEN,SENTRY_URL,SENTRY_ORGandSENTRY_PROJECT, which upload each build's debug files and the pages' source maps. A platform's build fails unless Sentry then holds debug information with file and line for the app's own code (src/slic3r/GUI/JusPrin/Packaging/sentry_debug_files.sh) and a source map for each page as built (sentry_page_maps.shbeside it); the nightly build checks the same. - The guide,
docs/guide/, checked for that version. Runscripts/check_guide.py --ask-aion a built copy of the commit, fix every page it reports, and commit the pages with their pictures, skills anddocs/guide/checked-version.txt, asdocs/guide/README.mddescribes under "Before a release". That file names the version the check last passed for, not the commit. Ticking "Release without the guide check" on the workflow's Run workflow form skips this, and the draft's title then says so. A release started by pushing ajusprin-release/branch has no form, so it always needs the file.
Less is more. An error is expected only when the person can do something about it, such as sign in again, get more credits, update a key or check the network, and Kenneth decided what the product tells them. Every other error is unexpected: the person sees one generic sentence and a way to report the problem, and the report carries everything known, so that we can find the cause.
Kenneth, 2026-11-16: "if the error is something that user can do nothing about, just show the user a generic error message and give user a way to report a problem. On the back end though, we need to make sure we send as much info as possible to the Sentry server so that we can do root cause analysis. And that's it, nothing else." And: "When it comes to error handling, less is more."
The reporting function is report_unexpected_error (src/slic3r/GUI/JusPrin/Support/ErrorReport.hpp). This repository has no expected-errors table yet.
- Each has an entry in the expected-errors table: the cause, what the person sees, and what they can do next. A new entry needs Kenneth's yes; quote his words in the commit message.
- The test is what the person can do next. If the answer is "nothing" or only "try again later", the error is unexpected. An AI provider or our own server being slow, overloaded, down or limiting us is unexpected: the person can do nothing about any of them.
- Two causes that leave the person doing the same thing do not get separate sentences, codes or branches.
- A cause is "out of credits" or "no network". A status code, an exception type, or "the request was not valid" is not a cause.
- Each entry has a test, and each occurrence is counted.
- Handle them with normal control flow, not exceptions.
- Write no code for them. Do not catch one, give it a default value, retry it, or give it a sentence of its own. Each of those is a guess about a failure nobody understands. It hides the failure and loses where it came from.
- Let the failure stop the work and travel up unchanged.
- A failure that arrives as a value, such as a status code, stops nothing by itself. Turn it into a thrown error on the spot and stop. Keep the other side's status, request id and error text. Do not interpret it.
- One handler at the top of each entry point reports the failure through the one reporting function and tells the person "Something went wrong on our side", with nothing more specific. No other code reports.
- A tool call that fails is shown as failed in the turn's activity line, its error goes to the AI model, and the turn goes on; no dialog opens. When the failure is the app's own and not the model's mistake, it is also reported, and only if the person has turned automatic reports on.
- When our own code is on both ends, a message that is refused or cannot be read is unexpected.
- The report carries as much as is known: the other side's status, request id and error text, and the request's own facts, such as the user, the chat, the turn and the model. The person is told none of it.
- Never record a failure as a success.
- A log line is not a report: it reaches nobody.
- Catch an error only when it is an expected one and the code can recover from it, or at a boundary to translate it or add context, and then rethrow.
- Keep lower-level operations strict; the caller that owns the workflow enforces their preconditions.
- If concurrency makes an invalid state reachable, fix the ordering.
- An agent reads the changed code against these rules and asks one question wherever the code decides what happened: can the person do something about it, and did Kenneth decide what they are told?
- Do not sort unexpected failures into kinds for the person, and do not bring Kenneth a question about the wording of a failure the person can do nothing about. On 2026-11-16 the code that kept five "try again" sentences apart was deleted for this reason.
- To audit a commit range, use the
error-handlingskill (.claude/skills/error-handling/). To check production for a period, use thejusprin-production-checkskill in the tsd-enterprise repository.
Build the Release configuration unless asked otherwise.
# macOS
cmake --build build/arm64 --config Release --target all --
# Linux
cmake --build build --config Release --target all --
# Windows
cmake --build . --config Release --target ALL_BUILD -- -mNode/npm is required to build the Agent and Home pages, or configure with -DJUSPRIN_BUILD_WEB=OFF and supply the bundles.
Several agent sessions build on the same Mac at once. Without a limit, ninja runs one compile job per core plus two, so every build you start can take the whole machine. In 2026-10 one session stacked four builds in one build directory: 56 clang processes on 12 cores. It kept restarting its build to change targets and never limited the job count.
- Before starting a build, check
uptimeandpgrep -fl ninja. If the load is already above the core count, wait or build less. - Limit jobs:
cmake --build … -- -j4. - Decide the full target list before starting. Never restart a running build to add or change targets: let it finish, then build the rest.
- Run one build per build directory. Two ninja processes in one directory compete and can leave its records inconsistent.
- Stopping a build means stopping ninja.
pkill -f "cmake --build …"kills only the cmake wrapper, and ninja keeps compiling. Start long builds in their own process group (perl -e 'setpgrp(0,0); exec @ARGV' cmake --build …) and stop them withkill -- -<pgid>. Then confirm withpgrep -fl ninjabefore building again. - When a build is slow, count your own compile processes before blaming the load on other sessions.
- Reuse an existing build where the task allows. Ask before configuring a fresh full-app build the task does not require.
- Before building against a dependency folder built earlier, such as the main checkout's
deps/build/arm64, runscripts/deps_current.sh <folder>. It rebuilds the libraries whosedeps/recipe changed since that folder was built.
Catch2 framework. Tests in tests/; see tests/AGENTS.md for where a new test belongs and the conventions to follow.
cd build && ctest -C Release --output-on-failure # all tests
ctest --test-dir ./tests/libslic3r -C Release # individual suite
ctest --test-dir ./tests/fff_print -C ReleasePrinter UI without hardware: src/slic3r/GUI/JusPrin/Testing/README.md (Bambu in-process fake); Moonraker and OctoPrint: tests/printer_hosts/README.md (Docker). Isolated --datadir; do not drive another JusPrin instance.
- Docs live in
docs/; the high-level design of a subsystem goes indocs/HLSD/<subsystem>.md. - Describe the design as it stands — what the subsystem does, why it exists, and the constraints that shape it. Not the route that got there: no phases, task lists, status markers, or "before/after this PR" framing.
- Planning and investigation output (brainstorms, superpowers design and plan docs) stays in
docs/superpowers/, which is gitignored. Never commit it. - Write a doc only when the design is not evident from the code, and when a change invalidates an existing one, update it in the same PR.
- C++17, selective C++20. PascalCase classes, snake_case functions/variables
#pragma oncefor headers. Smart pointers and RAII preferred- Include what you use: include the header for every symbol a file uses, and keep headers compilable on their own. Never rely on the precompiled header or a transitive include. The
clang-tidyCI job enforces this on changed lines; run the same check locally withscripts/run_clang_tidy.sh(scripts\run_clang_tidy.ps1on Windows), which sets up everything it needs - Parallelization via TBB — be mindful of shared state
- Wording: a file or object is "opened", "imported", "loaded" or "added", never "arrived". "Arrive" is fine for messages, responses, events and lists.
AgentUI/src/wording.test.tsguards the text the model reads. - Wording the model reads calls the product "the app", never Orca or OrcaSlicer: the model speaks as the app, and a second name reads as a second program.
AgentUI/src/wording.test.tsguards this too. Log lines may name Orca. A throw may only if it never reaches the model: tool results forward save and open errors as they are, and the guard does not see those strings. - Always use
SetSizerAndFit(sizer)instead ofSetSizer(sizer)on top level window. UnlessSetSizermust be called before the full layout is built, callsizer->SetSizeHints(window)afterwards in this case.
- App startup:
src/OrcaSlicer.cpp - Slicing pipeline:
src/libslic3r/Print.cpp - All print/printer/material settings:
src/libslic3r/PrintConfig.cpp - GUI:
src/slic3r/GUI/ - Core algorithms:
src/libslic3r/(GCode/, Fill/, Support/, Geometry/, Format/, Arachne/) - Printer profiles:
resources/profiles/[manufacturer].json
- Start with
agent-docs/jusprin/README.mdfor the canonical product definition, production architecture, verification method, Orca integration guidance, and design system. - Before editing any file outside
src/slic3r/GUI/JusPrin/, readagent-docs/jusprin/fork-stewardship.md. Every line changed in an OrcaSlicer-owned file is a line this fork re-resolves at every rebase, so those changes must be small, product-neutral, additive where possible, and accompanied by the rebase evidence that document requires. - Experimental plans, probes, screenshots, logs, and temporary UI code remain on
jusprin-v2-poc. Useagent-docs/jusprin/poc-reference.mdfor exact commit and path pointers; do not cherry-pick the POC wholesale. - Curated brand and semantic UI assets live under
resources/jusprin/. - Before writing or changing any UI code, native or Agent page, follow "Writing UI code" in
agent-docs/jusprin/design-system.md: every color, radius, font, and control size comes from the token file throughShellTheme, the shell recipes, or the CSS variables. A value with no token gets a token and a guard first, never a literal. - Before designing a screen or writing any on-screen text, follow
agent-docs/jusprin/design-guidelines.md: whole-screen boards with real strings, the wording rule, and a cold-reader check on screenshots before and after building. - Temporary working docs (handoffs, findings, plans written for another agent) stay untracked: never commit them, and never add them to
.gitignoreor.git/info/exclude. Untracked files ingit statusare how Kenneth tracks work that isn't finished.
- Backward compatibility required for .3mf project files and printer profiles
- Cross-platform — all changes must work on Windows, macOS, and Linux
- Profile/format changes need version migration handling
- Dependencies built separately in
deps/build/, then linked to main app
Before opening a pull request or posting on GitHub, read CONTRIBUTING.md, including its "If you are an AI agent" section.
- Changes must not cause regressions in existing functionality, defaults, profiles, or project compatibility.
- Features gated by options must not affect existing behavior when those options are disabled.
- Changes should follow the existing code style and architecture. Architectural changes should be justified in code comments and the PR description.
- Add helper functions or utilities only when existing code cannot reasonably be reused. Avoid duplication.
- Changes to OrcaSlicer-owned files must be additive where possible. Rewriting an upstream function, or reimplementing upstream behavior beside it, needs explicit justification in the PR description.
- When an upstream line is deleted or relocated, say where it went and what a future rebase must carry into the new home.
- Keep code concise and clear. Manually simplify AI generated bloated codes before review.
- Include targeted tests or documented verification for behavior changes, especially in slicing logic, profiles, formats, and GUI defaults.
- For profile changes (
resources/profiles/<Vendor>/**), check thatversionin the siblingresources/profiles/<Vendor>.jsonwas bumped. - For new or changed UI strings, check they follow Writing translatable strings in the source: no concatenated fragments, plural forms for counts, contexts for ambiguous words.
- For translation changes (
localization/i18n/**/*.po), check that recurring terms match the Localization glossary for that language.
Catalogs live in localization/i18n/<lang>/OrcaSlicer_<lang>.po; the template is OrcaSlicer.pot.
See the Localization guide for the human-facing version of these principles.
Translators see one msgid at a time and cannot change the code around it, so each message must be complete in a single msgid. Use the wrapper that fits instead of assembling text from pieces:
- One msgid per sentence, with placeholders. Never build a message by concatenating translated fragments (
_L("A") + name + _L(" is B")) or by splicing a translated word such as_L("left")into another sentence: the translator can't reorder or inflect the parts. Writeformat(_L("%1% is too close to others"), name). - A count needs a plural form. Don't write
file(s)or leave a verb unchanged after a number. Use_L_PLURAL("%1% object", "%1% objects", n). libslic3r has no plural lookup, so word the message so it doesn't depend on a count, or build it in the GUI. - An ambiguous word needs a context. When a short string means different things in different places (verb or noun, a mode name, a CAD term), give each sense its own context with
_L_CONTEXT/_u8L_CONTEXT/L_CONTEXT. Keep the most common sense without a context so its existing translations stay valid. - Mark every user-visible string (
_L/_u8L, orLwhere it is translated later) and list new source files inlocalization/i18n/list.txt: files that aren't listed are never extracted. - Add a
// TRNcomment above a new string whose meaning or placeholders aren't obvious. - Never choose behavior by comparing translated text; compare ids or flags.
See .claude/skills/orca-translations/references/source-audit.md for the full checklist.
- Use the Localization glossary as the source of truth for recurring terms, so the same English term is always rendered the same way within a language, and terms that must stay in English (brand/product names, acronyms, materials, file formats, G-code tokens, macros/variables/identifiers) are not translated.
- If a term's established translation changes, update both the affected
.pofiles and the glossary (developer_reference/glossary/<lang>.tsvin the wiki, then regenerate) so they stay in sync. - Translate the meaning, not the words. Check what the string actually controls before translating it — English reuses one word for different things.
Flow ratio(multiplier),Flow Rate(throughput) andFlow Dynamics(pressure compensation) are three different terms;extrudermay mean the toolhead, the feeder motor, or the nozzle depending on the string. - Reuse one template per recurring message shape (
Failed to connect to …,Are you sure you want to …?), even where the English wording varies.
- Only edit
msgstr— never changemsgid, and never "fix" wrong English in the translation alone. Report the source string instead. - Preserve exactly: placeholders (
%s,%d,%1%,%zu,%%), every\n(count and position, including leading/trailing), leading/trailing spaces, HTML tags,℃, and the file's encoding and line endings. - Never reorder positional arguments in a
c-formatstring. If the msgid is%dthen%s, that order must hold — swapping them breaks at runtime. msgctxtseparates homonyms — always read it.Back/Camera Viewis the rear view of the 3D navigator, whileBack/Navigationis the go-back button;Topexists in the Alignment, Layers and Camera View senses.- When a string needs disambiguating, add context in the source (
_L_CONTEXT/_u8L_CONTEXT), don't work around it in the translation. - A literal
%inside a string xgettext flaggedpossible-c-formatwill failmsgfmt. Fix it with a// xgettext:no-c-format, no-boost-formatcomment above the string in the source — do not mangle the translation or use%%in text that is never passed through printf. - Plural entries: read
npluralsfrom the catalog'sPlural-Formsheader (it is not always 2 — ja/ko/zh/th/vi use 1, ru/cs/pl/lt use 3, uk uses 4). Each form must be genuinely inflected for its quantity; repeating one sentence across all forms is a bug in Slavic/Baltic languages, though it is correct for Turkish and Hungarian. - An entry whose
msgstrequals itsmsgidis untranslated even though it is not empty; a plural entry with any empty form is likewise incomplete. - Mark machine-produced translations with an
# AI Translatedtranslator comment. Don't add it to a human translation you didn't actually rewrite. - When you can't be sure of a machine translation's meaning or UI wording, also add
# Needs human review: <what to check>. Never usefuzzyfor this — fuzzy entries are hidden from users. - Don't reflow or re-wrap unrelated entries — keep the diff limited to the strings you changed.
scripts/run_gettext.bat --full(Windows) regenerates the template, merges every catalog and compiles the.mofiles. It must exit 0.- Or check a single catalog with
msgfmt --check-format --check-header -o <out>.mo localization/i18n/<lang>/OrcaSlicer_<lang>.po. Without--check-header, msgfmt skips the placeholder check in plural forms. - Fuzzy entries are not shown to users. If you correct one, clear its
fuzzyflag, otherwise the fix never ships.