Table of Contents

πŸ‡«πŸ‡· Version franΓ§aise

NuGet publication matrix

This file is the single source of truth for which projects are published to NuGet, so the workflows (ci.yml validation, publish.yml pack + push on tag and the dev channel on green main, release.yml installers) never drift.

Status. Distribution is one Orkeon package plus thirteen opt-ins β€” fourteen packages, the list publish.yml pushes β€” guarded by the scripts/check-package-closure.py gate and pushed to NuGet.org through Trusted Publishing. The scripting naming is settled by ADR-007: the command library is Orkeon.Cli.Commands.Scripting, the orkeon tool Orkeon.Scripting.Cli.

The NuGet.org lineup

One package installs the whole framework; everything else in the lineup is an opt-in kept separate only because of what it would force on every consumer (dependency weight, native runtimes, a pre-release upstream).

PackageId Why
Orkeon The umbrella package β€” the thirteen assemblies of the core closure (Orkeon.Domain, Orkeon.Application, Orkeon.Infrastructure, Orkeon.Constants.{Llm,FileSystem,Configuration,Protocol}, Orkeon.Tools.Abstractions, Orkeon.Analysis.Abstractions, Orkeon.Rag.Abstractions, Orkeon.Analysis, Orkeon.Rag, Orkeon.Plugins) embedded in one nupkg. One install = the complete framework: agents, crews, six orchestration modes, 16 LLM providers, 6 memory stores, RAG, RaggableTree. The Clean Architecture split stays a source-layout discipline, not a distribution contract.
Orkeon.Tools The nine built-in tool families (Analysis, Code, Data, Drive, Email, EventHub, FileSystem, Rag, Web) in one nupkg. Separate from Orkeon only for dependency weight: the Data tools pull database drivers, PDF and spreadsheet libraries, the e-mail tools MailKit and MimeKit β€” dependencies a consumer who never uses them should not inherit. Depends on Orkeon.
Orkeon.Rag.Onnx, Orkeon.Rag.Onnx.Model Opt-in ONNX cross-encoder reranker pair (runtime + embedded int8 weights) β€” pushed together; native onnxruntime payload. Orkeon.Rag.Onnx depends on Orkeon; Orkeon.Rag.Onnx.Model is dependency-free (embedded resources only) and is referenced alongside it.
Orkeon.Tools.Embeddings.Local Local on-device embeddings (BGE-micro-v2 ONNX). Stays outside the umbrella because it carries a pre-release SmartComponents dependency from an archived upstream β€” putting it in Orkeon would force that pre-release on every consumer. Depends on Orkeon.
Orkeon.Constants.Cli The shared CLI vocabulary: the option names the runners accept (RunOptionNames), their exit codes (RunExitCodes) and the session-state keys (SessionStateKeys), for a tool that drives orkeon run. A zero-dependency satellite (ADR-009), packed straight from its project; Orkeon.Scripting depends on it rather than embedding it.
Orkeon.Scripting Runs a crew.ork.ts inside a .NET application, without starting a process: services.AddOrkeonScripting() then ICrewScriptRunner.RunAsync(path), relative paths resolved against the process working directory β€” see Orkeon.Hosting. Embeds Orkeon.Scripting (the Jint host, the esbuild bundler driver, the DSL typings as an embedded resource), Orkeon.Hosting (the runner bootstrap orkeon run and orkeon-host share). Separate from Orkeon because the runner host composes every built-in tool family: it depends on Orkeon, Orkeon.Tools, Orkeon.Tools.Embeddings.Local and Orkeon.Constants.Cli (so on their database drivers, MailKit and the SmartComponents pre-release), plus Jint, Microsoft.Extensions.Hosting and CommandLineParser. esbuild is not shipped, as for the tool.
Orkeon.Scripting.Cli The orkeon dotnet tool (PackAsTool; the PackageId is the install command β€” ADR-007). Publishable on NuGet.org: the iOS/Android onnxruntime natives a CLI tool can never load are excluded, in every tool package: about 187 MB with the natives of every desktop runtime (win, linux, osx), under the 250 MB nuget.org limit.
Orkeon.Compliance.Vfs The Roslyn analyzer that refuses direct System.IO in your own code (rules ORKVFS001–ORKVFS007, analyzers/dotnet/cs, DevelopmentDependency). Standalone by design: it depends on nothing from Orkeon and works in any C# project β€” add the PackageReference, build, and every File.*/Directory.* call is a diagnostic.
Orkeon.Interop.AgentFramework The bridge to Microsoft Agent Framework, both ways: an Orkeon crew as a MAF AIAgent (CrewAgent), a MAF AIAgent as the brain (WithAgentFrameworkAgent) or as a tool (WithAgentFrameworkTool) of an Orkeon agent. Separate from Orkeon because the Microsoft.Agents.AI.Abstractions dependency is a consumer's choice. Depends on Orkeon.
Orkeon.Hosting.Aspire The .NET Aspire hosting integration: AddOrkeonHost (the orkeon-host daemon) and AddOrkeonCrewRun (one orkeon run) as AppHost resources, WithOrkeonModel / WithOrkeonSetting for the ORKEON_ environment, OTLP export wired so the dashboard reads the run. Separate from Orkeon because Aspire.Hosting is an AppHost's choice. Depends on Orkeon.
Orkeon.Cli.Abstractions The contracts of the interactive runners and command registries (IConsoleAdapter, the command registry, the runner options). No Orkeon dependency: two Microsoft.Extensions abstractions only, packed straight from its project.
Orkeon.Cli.TerminalGui The Terminal.Gui v2 split-pane console (REPL + logs pane) that terminal applications build on. Separate from Orkeon for its Terminal.Gui dependency. Depends on Orkeon (which carries the Orkeon.Constants.Configuration it reads) and Orkeon.Cli.Abstractions.
Orkeon.Templates The dotnet new templates: orkeon-host (a generic host that runs a crew in its own process, shaped like the orkeon-host daemon), orkeon-plugin (an IOrkeonPlugin, one tool and its plugin.json) and orkeon-tool (a ToolBase class). PackageType=Template: no assembly, no dependency. A generated project references Orkeon (and Orkeon.Scripting for the host) at the version of the template package, written out in its project file.

How the packaging projects are built

  • The lineup nupkgs come from dedicated packaging projects under src/packaging/ β€” nine of them: the Orkeon and Orkeon.Tools umbrellas, the Orkeon.Templates content package, plus the Orkeon.Rag.Onnx.Package, Orkeon.Tools.Embeddings.Local.Package, Orkeon.Interop.AgentFramework.Package, Orkeon.Hosting.Aspire.Package, Orkeon.Scripting.Package and Orkeon.Cli.TerminalGui.Package wrappers, which pack the opt-in assemblies with a nuspec dependency on the Orkeon umbrella β€” and, for Orkeon.Scripting, on Orkeon.Tools, Orkeon.Tools.Embeddings.Local and Orkeon.Constants.Cli too, for Orkeon.Cli.TerminalGui on Orkeon.Cli.Abstractions. A dependency on a wrapper is spelled by referencing the project it wraps, whose restore name is the public id (the wrapper's own is <id>.Package); the closure gate accepts exactly that reference. The remaining lineup packages are packed straight from their own project: Orkeon.Rag.Onnx.Model (src/rag/), the orkeon tool (src/scripting/Orkeon.Scripting.Cli), the analyzer (src/analyzers/Orkeon.Compliance.Vfs), Orkeon.Constants.Cli and Orkeon.Cli.Abstractions, which depend on no other Orkeon assembly. The embedded library projects themselves are IsPackable=false and their source layout, namespaces and per-assembly PublicAPI freeze are untouched; the real opt-in projects keep normal ProjectReferences, so in-repo consumers are unaffected β€” only the wrappers carry the embed pattern below.
  • Each packaging project references its embedded project(s) with PrivateAssets="all" (keeping them out of the nuspec dependency list) and packs their DLL+XML into lib/. Because PrivateAssets="all" also stops the embedded projects' external PackageReferences from flowing into the nuspec, the union of those references is re-declared by hand in the packaging csproj.
  • scripts/check-package-closure.py (run by publish.yml right after the pack, on the tag and on the dev channel) fails the workflow if (1) a lineup package declares an Orkeon.* dependency outside the lineup β€” the NU1101 class of incident β€” (2) an umbrella's hand-declared externals drift from what its embedded projects actually require, or (3) an assembly an embedded one reaches transitively ships nowhere in the lineup. Its source half (no nupkg needed) also runs on every pull request through scripts/check-doc-claims.py, which additionally fails when a packable project is neither in the lineup nor GitHub-Packages-only, or when one of the hand-written copies of the lineup drifts.
  • publish.yml pushes Orkeon first: the other lineup packages depend on it and NuGet does not order pushes, so pushing a dependent first would expose a package whose restore fails.

Discontinued packages

The following projects are not packed under their own id (IsPackable=false): Orkeon.Domain, Orkeon.Application, Orkeon.Infrastructure, the Orkeon.Constants.{Llm,FileSystem,Configuration,Protocol} satellites, Orkeon.Analysis, Orkeon.Analysis.Abstractions, Orkeon.Rag, Orkeon.Rag.Abstractions, Orkeon.Tools.Abstractions and the nine Orkeon.Tools.<family> projects, Orkeon.Cli, Orkeon.Cli.Commands.Scripting, Orkeon.Hosting, Orkeon.Plugins. Those that the Orkeon and Orkeon.Tools umbrellas embed still ship β€” inside the umbrella's nupkg, not under their own id (Orkeon.Plugins is the thirteenth assembly of Orkeon); Orkeon.Hosting ships inside the Orkeon.Scripting package, the opt-in that carries the scripting layer.

Migration: the source code and namespaces are unchanged, so consumer code compiles as-is β€” only the install changes. Uninstall the per-layer packages and dotnet add package Orkeon (add Orkeon.Tools if you used a Orkeon.Tools.<family> package other than Embeddings.Local).

NuGet.org state

The Orkeon prefix (the bare id and Orkeon.*) is reserved on nuget.org for the owner account arion-orkeon. The per-layer packages Orkeon.Domain, Orkeon.Application and Orkeon.Infrastructure are unlisted, not deleted: a consumer pinning one still restores. A freshly pushed package is not downloadable until NuGet.org has validated it; --skip-duplicate makes a re-push a no-op.

Published to GitHub Packages

publish.yml (tag v*) packs Orkeon.sln and pushes every packable project to GitHub Packages (nuget.pkg.github.com/Orkeon) with --skip-duplicate. That is the NuGet.org lineup above plus the build-time and runner packages that stay off NuGet.org: Orkeon.ConsoleApp and Orkeon.Generators:

PackageId Tool command Source project
Orkeon.ConsoleApp orkeon-repl src/apps/Orkeon.ConsoleApp

The other dotnet tool, Orkeon.Scripting.Cli (command orkeon), is in the NuGet.org lineup above.

Dev channel: the latest main, between two tags

Once ci.yml is green on a push to main, the publish-dev job of publish.yml packs the same projects as <X.Y.Z>-<pre>.dev.<n>, n being the number of that CI run β€” so <X.Y.Z>-<pre>.dev.412 is the commit CI run #412 validated β€” and pushes them to GitHub Packages only: never NuGet.org, which can unlist a version but never delete it. scripts/prune-dev-packages.sh then deletes the older dev builds, so the feed holds every tagged release plus the latest green main, nothing in between. A tagged version is never deleted; a version that is neither tagged nor a dev build is reported, not deleted β€” the same script removes those in a one-off, reviewed run (--include-untagged, dry run first).

  • SemVer puts <X.Y.Z>-<pre>.dev.<n> above <version> and below the next pre-release, so --prerelease resolves the dev build. When the props version has no suffix (a stable release), the dev builds move to the next patch β€” 1.0.1-dev.<n> after 1.0.0 β€” because 1.0.0-dev.<n> would sort below the release.

  • A dev version lives until the next green merge. A PackageReference pinned to one keeps restoring β€” NuGet reads the version as a minimum and takes the next build up, with warning NU1603 (an error under warnings-as-errors) β€” but exact pins break: a dotnet tool manifest, a packages.lock.json in locked mode. Float (*-*, and dotnet restore --force-evaluate to move to the newest) to follow the channel; pin a tagged version for anything durable.

  • A dev build is not a release: no attestation, no SBOM, nothing on NuGet.org.

  • Two forms off a tag, one calculation. scripts/resolve-version.sh (and its PowerShell twin scripts/resolve-version.ps1) names every build that is not a release:

    Form Comes from Example
    <X.Y.Z>-<pre>.dev.<n> CI alone β€” publish.yml and apt-dev.yml, n being the CI run number <X.Y.Z>-<pre>.dev.412
    <props version>.local.<stamp> a build made from a checkout β€” scripts/package-installers.sh or .ps1 without a version, a manual run of release.yml <version>.local.202610080430

    <stamp> is the committer date of the commit built, YYYYMMDDHHMM in UTC: it orders two local builds, and a shallow clone gives the same one. Uncommitted changes do not move it. SemVer sorts a local build above every dev build of the same props version and below the next one, so a machine installed from the sources is never taken for an older build. On the commit a v* tag points to, the same scripts answer the tag's version. dotnet build is not concerned: the assemblies of a plain build carry the props version.

  • Once the feed is a source, --prerelease and floating versions resolve dev builds for every Orkeon package, the NuGet.org ones included; --version pins a release.

  • GitHub Packages requires a token even for a public repository: a personal access token (classic) with read:packages. Run the commands outside a clone of this repository β€” inside one, its nuget.config keeps nuget.org as the only source and you would get the latest tag instead.

Step by step β€” the token, both shells, checking what runs, going back to the releases: Follow main: the dev channel.

dotnet nuget add source https://nuget.pkg.github.com/Orkeon/index.json \
  --name orkeon-github \
  --username <your-github-username> \
  --password <PAT-with-read:packages> --store-password-in-clear-text

dotnet tool install -g Orkeon.Scripting.Cli   # installed already: dotnet tool update, same arguments
# in a project: <PackageReference Include="Orkeon" Version="*-*" />

Installer archives (release.yml)

On a v* tag, release.yml builds every installer artifact, smokes each onboarding channel on a real runner (Windows CLI zip, Windows service, Debian package, macOS tarball), and only then attaches everything to the GitHub Release. The pipeline is installers β†’ {smoke-windows, smoke-windows-service, smoke-deb, smoke-macos, msi} β†’ release β†’ {verify-published, apt-publish β†’ verify-apt} (the last two are described in The apt repository); behind those same five jobs, docker-image pushes the ghcr.io/orkeon/orkeon container image to GHCR (one multi-platform tag, linux/amd64 and linux/arm64, checked once pushed) in parallel with release, so a red smoke moves neither the Release nor the :latest tag. workflow_dispatch runs the same thing minus the publication (no tag, no Release to attach to). A tag carrying a pre-release segment (v<version>-<pre>) is published as a prerelease, so it never becomes the repository's latest release; a bare v<version> does. The orkeon CLI runs the examples (orkeon run crew.yaml runs the examples/ YAML crews; orkeon run script.ork.ts runs the scripting DSL).

Artifact Built by Contents Runtime
orkeon-<version>-<rid>.tar.gz / .zip package-installers.sh (default --app-set full) every launcher β€” orkeon, orkeon-slim, orkeon-repl, orkeon-host β€” + one shared esbuild + the deploy/ tree (systemd unit, SCM registration script, Dockerfile.host) mixed: orkeon-slim is framework-dependent, every other launcher (orkeon, orkeon-repl, orkeon-host) is self-contained
orkeon-cli-<version>-win-x64.zip package-installers.sh --app-set cli --rids win-x64 the orkeon CLI + install.cmd and install.ps1 self-contained
orkeon_<version>_amd64.deb / orkeon_<version>_arm64.deb package-deb.sh --arch amd64\|arm64 (reuses the linux-x64 and linux-arm64 staging trees β€” one publish, two packages per architecture) the orkeon CLI at /usr/bin/orkeon + the REPL at /usr/bin/orkeon-repl (it uses the one esbuild under /usr/lib/orkeon) self-contained; Depends on system libraries only (libicu78 down to libicu70, libssl3t64 \| libssl3, libc6 (>= 2.34)…, so Debian 12/13 and Ubuntu 22.04 to 26.04), never on dotnet-runtime-*; Recommends: orkeon-archive-keyring; ships md5sums (dpkg -V orkeon); byte-identical across two builds of the same commit (SOURCE_DATE_EPOCH)
orkeon-archive-keyring_<YYYY.MM.DD>_all.deb package-keyring-deb.sh, once per keyring version (a date, such as 2026.10.04, from installers/apt/keyring.version); later Releases attach the bytes already published, never a rebuild /usr/share/keyrings/orkeon-archive-keyring.gpg, the public key of the apt repository β€”
orkeon-<version>-win-x64.msi build-msi.ps1 (WiX, per-user scope), harvesting the extracted CLI zip the orkeon CLI, same pruned publish as the zip self-contained
orkeon-cli-<version>-osx-arm64.tar.gz / -osx-x64.tar.gz package-installers.sh --app-set cli --rids osx-arm64 osx-x64 (cross-published from the ubuntu runner) the orkeon CLI alone + install.sh (the macOS channel stays CLI-only) self-contained
orkeon-typings-<version>.tar.gz the installers job, step Package the editor typings: orkeon typings run on the orkeon of the linux-x64 staging tree, packed reproducibly (sorted names, the commit date as mtime, no gzip header) a folder of the same name holding orkeon.d.ts (the .ork.ts DSL) and orkeon-cli.d.ts (the *.cmd.ts commands), so a script project can pin and diff the typings of a release (Editor setup) β€”
SHA256SUMS the installers job's packaging scripts (package-deb.sh refreshes its own line) one line per artifact above except the MSI, plus the SBOM (orkeon-<version>.sbom.cdx.json) and the typings archive β€”
orkeon-host-<version>-win-x64.msi build-msi-service.ps1 (WiX, per-machine scope), harvesting the extracted full zip the self-contained orkeon-host publish alone, registered as the Orkeon service under NT SERVICE\Orkeon (no CLI, no wrapper, no deploy/ β€” the package registers declaratively) self-contained
SHA256SUMS.msi build-msi.ps1 then build-msi-service.ps1, in order, in the msi job the two MSIs β€”

The service host

orkeon-host ships inside the full archive (--app-set full), self-contained: a daemon supervised by systemd or the Windows SCM must not depend on a runtime someone may upgrade underneath it. It is not a dotnet tool β€” it is installed as a service, not invoked from a shell. On Windows it also ships as its own per-machine MSI (orkeon-host-<version>-win-x64.msi), a separate product from the per-user CLI MSI: the two coexist, and the package registers the service declaratively β€” same account, same paths, same recovery as the script channel.

Its deployment artifacts live in deploy/ and ship inside the full archive next to the daemon: a systemd unit (Type=notify, restart on failure β€” config errors exit 78 and do not loop, hardened), a PowerShell script registering it with the SCM, and a Dockerfile. None of the three carries a secret β€” the bot token and the API keys are named by environment variable in the configuration and provided by the machine, so a unit file or an image layer can be read by anyone without leaking anything.

What the machine needs. No artifact of this table needs .NET where its Runtime column says self-contained; what the Windows ones need from Windows is not in that column:

Artifact On the machine
orkeon-cli-<version>-win-x64.zip, orkeon-<version>-win-x64.zip nothing to install, no setting to change: install.cmd starts install.ps1 on Windows PowerShell 5.1, the one Windows ships, under an execution policy that holds for that one command. install.ps1 is written for 5.1 and for PowerShell 7, and smoke-windows installs the CLI zip under both. Windows may ask to confirm a file a browser downloaded (Unblock-File on the zip avoids it); a policy set by Group Policy overrules the launcher β€” only a signed script runs there
orkeon-<version>-win-x64.msi nothing to install. Not code-signed: SmartScreen names an unknown publisher and asks before running it
orkeon-host-<version>-win-x64.msi administrator rights (per-machine). Not code-signed either: same SmartScreen screen, and an elevation prompt without a publisher

The steps a reader follows are in Before you start.

Two checksum files rather than one: the ubuntu installers job writes SHA256SUMS before the MSI exists β€” it is built later, on windows-latest. Each checksum file is generated by the job that produced the artifact it covers.

Blocking smokes. smoke-windows (a windows-latest runner) installs orkeon-cli-*-win-x64.zip and walks the onboarding chain on it; smoke-deb (a stock ubuntu-latest image for amd64, an ubuntu-24.04-arm runner for arm64 β€” each entry refuses a runner of the other architecture) installs the .deb through apt, checks dpkg -V orkeon is silent, walks the same chain, then removes the package β€” the linux-x64 tarball smoke runs on the amd64 entry; smoke-macos (a macos-latest, Apple-silicon runner) extracts the osx-arm64 tarball, installs it with install.sh and walks the same chain before uninstalling; the msi job runs its own msiexec /i /qn β†’ orkeon doctor --json β†’ msiexec /x /qn chain, asserting the install directory, the ARP entry and the user PATH entry appear and then disappear. smoke-windows-service installs the full win-x64 zip's service channel β€” virtual account, --working-dir proven with a relative crew path, a refused configuration that stops without looping and lands in the event log β€” and the msi job smokes the service MSI the same way, plus a silent reinstall of itself. Every one of them also checks the notices of what it installed: the license, THIRD-PARTY-NOTICES.md and one licenses/<pack>/ per .NET runtime an application bundles, the runtimes being read from the payload itself (each *.runtimeconfig.json), not from a list. And each asserts the channel its install names β€” zip, msi, msi-host, deb or tarball: the INSTALL-CHANNEL file every packaging writes at the root of what it installs, read back through orkeon --version --verbose (from the file itself for the service MSI, which carries no CLI). All of them install from the job artifacts, never from the Release, so a broken payload is caught before anything is published β€” the release job needs them all.

After publication. release.yml calls release-verify.yml in its verify-published job, right after the release job of the same run (and it can be run on demand for a given tag). A release: published trigger would never fire: a Release created with the workflow's GITHUB_TOKEN starts no other workflow. It downloads the assets from the Release page, checks that every published asset has exactly one line in SHA256SUMS or SHA256SUMS.msi and every line names a published asset, verifies every checksum with no line skipped, and replays the onboarding smokes of both .deb (amd64, and arm64 on an ARM runner) and of the osx-arm64 tarball on them β€” catching an asset that an upload, a replace or a tamper made different from what the smokes above installed. The two smoke jobs check the tag out, so the smokes replayed are the tag's own: an older Release is asked what its own smokes asked of it, not what main's ask today. Run by hand on the two earliest Releases with installers, it fails by design: they predate the naming rule below, and carry no arm64 package.

smoke-macos is also the only place the Gatekeeper and code-signing story is exercised: an unsigned, quarantined or malformed native library (libtree-sitter*.dylib, onnxruntime, the esbuild binary) is killed at load time, so it fails there rather than in a user's terminal.

The .deb file name carries the tag's version (orkeon_<version>_amd64.deb), while the package's Version: field replaces - with ~ (<X.Y.Z>-<pre> becomes <X.Y.Z>~<pre>) so a pre-release sorts before its final under dpkg. The two differ on purpose: GitHub rewrites ~ in an uploaded asset name, and apt reads the file name from its index, never from the package. No asset name carries a character outside [A-Za-z0-9._-] β€” scripts/check-release-assets.sh fails the installers job, and the release job before publishing, otherwise β€” so SHA256SUMS lists every asset under the name it is published with. (The two earliest Releases with installers predate the rule: their .deb was published with . in place of ~ while their SHA256SUMS names it with ~.)

The MSI's ProductVersion drops the suffix instead: Windows Installer versions carry only three numeric fields, so build-msi.ps1 truncates <X.Y.Z>-<pre> to <X.Y.Z> for the property that <MajorUpgrade> actually compares. Nothing is silently lost β€” the full string survives in the .msi filename (orkeon-<version>-win-x64.msi) and in the ARPCOMMENTS property shown in "Installed apps".

The orkeon CLI is distributed through eight channels:

Channel Artifact Runtime Audience
NuGet dotnet tool Orkeon.Scripting.Cli (PackAsTool, command orkeon) needs .NET 10 SDK (dotnet tool install) .NET developers. Part of the NuGet.org lineup; the iOS/Android onnxruntime natives are excluded, which keeps it about 187 MB with every desktop runtime, under the 250 MB limit
Windows zip + install.cmd orkeon-cli-<version>-win-x64.zip self-contained Windows onboarding β€” the recommended channel
Windows MSI (per-user) orkeon-<version>-win-x64.msi self-contained Windows, double-click install and an "Installed apps" entry. One channel at a time: the MSI refuses to install over a zip install
Debian / Ubuntu apt repository the .deb packages below, indexed on the apt branch (channels stable, rc, dev) self-contained Debian / Ubuntu, amd64 and arm64 β€” the recommended channel: apt install, apt upgrade. See The apt repository
Debian package orkeon_<version>_amd64.deb / _arm64.deb self-contained Debian / Ubuntu without the repository (one version, no updates). Ships the orkeon-repl REPL next to the CLI
macOS tarball + install.sh orkeon-cli-<version>-osx-arm64.tar.gz / -osx-x64.tar.gz self-contained macOS onboarding today; install.sh clears the Gatekeeper quarantine attribute and ad-hoc re-signs the Mach-O files codesign -v rejects
Homebrew the same osx tarballs, via installers/homebrew/orkeon.rb self-contained macOS, once the tap exists β€” not published yet, see below
Multi-app installer archive orkeon / orkeon-slim launchers orkeon self-contained, orkeon-slim framework-dependent devs who also want the REPL or the service host

Homebrew β€” formula in the repository, tap not yet created. installers/homebrew/orkeon.rb is a binary formula: it downloads the osx tarball matching the machine's architecture (on_arm / on_intel), installs the payload under the Cellar's libexec, and writes a bin/orkeon wrapper that points ORKEON_ESBUILD_PATH at the bundled esbuild β€” the same contract as wrapper.sh.tmpl. Its test do block runs orkeon doctor rather than orkeon --version: doctor also runs the bundled esbuild and checks that the native libraries are in place, and an unconfigured LLM is only a warning there.

version and both url / sha256 pairs are generated, never hand-edited: scripts/update-homebrew-formula.sh --release <tag> (or --sums <file>) rewrites the five values from a release's SHA256SUMS and is idempotent. The file in the repository is a template: it holds the placeholder version 0.0.0 and the literal digests PLACEHOLDER_SHA256_ARM64 / PLACEHOLDER_SHA256_X64 until a release's sums are written in, so an accidental install fails verification instead of fetching something unverified.

Publishing the Orkeon/homebrew-tap repository and pushing the formula to it is a release action, not CI: brew tap orkeon/tap && brew install orkeon does not resolve before that. Submission to homebrew-core and a .pkg installer stay out of scope until the project is code-signed.

The apt repository

Debian and Ubuntu users add one source and then manage Orkeon with apt β€” the user side is Install with apt. The repository lives in this GitHub repository, in two halves:

  • The packages stay Release assets β€” the .deb files release.yml already builds, smokes and attests. Nothing is copied elsewhere.
  • The signed index lives on the orphan apt branch: one directory per channel (InRelease, Release, Release.gpg, Packages, Packages.gz, by-hash/SHA256/…), plus the binary keyring orkeon-archive-keyring.gpg at its root for the first setup. Only the workflows push to it, one commit per publication; a ruleset forbids its deletion and any force-push. It holds no .deb, so it weighs a few kilobytes.

The source reads URIs: https://github.com/Orkeon/orkeon/ and Suites: raw/apt/<channel>/ β€” a "flat" repository. apt fetches the index at …/raw/apt/<channel>/, which GitHub redirects to raw.githubusercontent.com, and resolves each package's Filename: β€” releases/download/<tag>/<asset> β€” against the same root, so the download lands on the Release asset. The cost is GitHub's rate limit on anonymous raw traffic (429): apt update treats it as a warning, a Docker build retries.

Channel Directory Receives
stable stable/ every v* tag without a pre-release segment β€” the same test that sets prerelease: on the Release. Final versions only: a release candidate never reaches it
rc rc/ every v* tag, so every package of stable is in rc too
dev dev/ the orkeon package of every green push to main, versioned <X.Y.Z>~<pre>.dev.<n>; its assets sit on the single fixed-tag prerelease apt-dev; only the three latest builds are kept. Never published to NuGet.org, never attested as a release

Each channel's Release file keeps Origin: Orkeon and Label: Orkeon for ever (a change makes every machine confirm it), sets Suite: to the source path without its trailing / and no Codename (otherwise apt warns "Conflicting distribution"), declares Architectures: amd64 arm64 and Acquire-By-Hash: yes, lists SHA-256 digests only, carries a strictly increasing Date (apt ignores an InRelease older than the one it has) and no Valid-Until. The index is generated by apt-ftparchive; the by-hash files are pruned by the publishing scripts, keeping at least three generations.

History and immutability. A channel lists every version still attached to a Release, so apt install orkeon=<version> can always go back β€” except dev, which keeps its three latest builds. A stanza, once published, never changes its digest for the same package, version and architecture: the generator refuses. release.yml never rewrites the assets of a published tag β€” it creates the Release as a draft, attaches the assets, then publishes it, and Releases are immutable β€” because a re-uploaded asset would make every machine fail with "Hash Sum mismatch".

The chain on a tag. release publishes the Release; apt-publish (GitHub environment apt-signing, the only place that holds the signing subkey, as the APT_SIGNING_KEY and APT_SIGNING_PASSPHRASE secrets, deployable from v* tags and from main, for the dev channel only) adds the new packages to rc β€” and to stable for a final version β€”, signs the index and pushes the apt branch; verify-apt then replays the installation block of the guide word for word, in fresh Debian 12 and 13 and Ubuntu 22.04, 24.04 and 26.04 containers, on amd64 and arm64: install, upgrade from the previous version, removal in the documented order. It retries while raw still serves the previous index. A weekly check compares the index with the assets, the key's expiry with the 180-day threshold, and raw's availability.

The dev chain is apt-dev.yml, started by every CI run that passes on a push to main (the guard of publish.yml's publish-dev job). It publishes the CLI set for linux-x64 and linux-arm64 only, packs the two .deb with package-deb.sh --arch, and never calls dotnet pack, publish.yml or a NuGet feed. The version is publish-dev's, with ~ for - in the Debian field: <X.Y.Z>~<pre>.dev.<CI run number>, asset orkeon_<X.Y.Z>-<pre>.dev.<n>_<arch>.deb. Then, in the apt-signing environment, scripts/apt/publish-dev.sh:

  1. creates the apt-dev prerelease if it is missing (never latest; its tag, set on the first build's commit, never moves);
  2. rebuilds dev/ from the published one, adding the new build and yanking any build that is not among the three newest, and signs it β€” a build already indexed, or older than the three kept, publishes nothing;
  3. attaches the two packages under their unique names, before the index can point to them; an asset an index already points to is never replaced;
  4. pushes dev/ to the apt branch;
  5. deletes the assets of the builds the pushed index does not list β€” never before.

The keyring package is attached once to apt-dev and its bytes reused afterwards. workflow_dispatch with publish left false builds the two packages and publishes nothing; with publish: true, from main, it publishes the newest green CI run of main. apt-dev must exist before Releases are made immutable: immutability only binds Releases created after it, and an immutable apt-dev could no longer drop old builds. Its rules are proved without network by scripts/apt/test-publish-dev.sh in CI, and apt-index.yml upgrades real apt clients from one dev build to a newer one.

Maintenance outside a tag goes through apt-maintenance.yml (workflow_dispatch, run from a tag so the environment rule admits it), with the same scripts, environment and concurrency group as apt-publish: resign signs both channels again with a newer Date; yank <package>=<version>[/<arch>] withdraws a stanza and signs again; seed <tag>… indexes assets published before the repository existed.

Procedure: extend or rotate the signing subkey

The subkey is valid two years and is extended at least six months before it expires β€” CI fails below 180 days. An expired key breaks apt update on every machine, with no fallback.

  1. On the offline machine, extend the subkey (gpg --quick-set-expire <primary fingerprint> 2y <subkey fingerprint>) β€” or, to rotate, add a new one (gpg --quick-add-key <primary fingerprint> ed25519 sign 2y).
  2. Export the public certificate, replace installers/apt/orkeon-archive-keyring.asc, change installers/apt/keyring.version, and update the keyring SHA-256 in SECURITY.md, SECURITY.fr.md and both installation pages (the CI guard checks they agree).
  3. The next Release publishes the new orkeon-archive-keyring; users receive it with apt upgrade. An extension stops here; run apt-maintenance.yml in resign mode if the index should be signed again before the next tag.
  4. For a rotation only, one Release later: the maintainer replaces APT_SIGNING_KEY with the new subkey, exported alone (gpg --export-secret-subkeys <subkey fingerprint>!). The old subkey expires, or is revoked.

Procedure: withdraw a version (yank)

  1. Run apt-maintenance.yml in yank mode, from a tag, naming <package>=<version>[/<arch>].
  2. Check that the channel's InRelease on the apt branch carries a newer Date and no longer lists the version; after an apt update, apt-cache policy orkeon no longer shows it.
  3. Only then, and only if needed, delete the asset from its Release. Any purge of Release assets starts with this procedure β€” an indexed asset that disappears turns into a 404 for every user.

Procedure: revoke the key

  1. Publish the revocation certificate (kept offline since the key was created) in SECURITY.md, SECURITY.fr.md and the installation pages.
  2. Freeze publication: no tag, no apt-maintenance.yml run, until the new key is in place.
  3. Create a new key and a new keyring, publish their fingerprint and SHA-256 as in the extension procedure, and sign the index with the new subkey. Users must download the new key themselves (the first lines of the installation block) β€” the only case where they act.

Procedure: the key has expired

Users see EXPKEYSIG on every apt update, and the channel stops updating. Extend the subkey (procedure above, step 1), publish the certificate and a new orkeon-archive-keyring version, then run apt-maintenance.yml in resign mode. A machine whose keyring is older than the extension cannot verify the new index: it reinstalls the keyring by the first lines of the installation block, or installs the new orkeon-archive-keyring_<YYYY.MM.DD>_all.deb downloaded from its Release (sudo apt install ./orkeon-archive-keyring_<YYYY.MM.DD>_all.deb).

All flavours are built from the same src/scripting/Orkeon.Scripting.Cli csproj and share the one bundled esbuild. The remaining CLI launchers stay framework-dependent β€” install.sh and install.ps1 detect that case and print the runtime install commands rather than failing at first launch.

Publish payload. Every publish of src/ and examples/ prunes the tree-sitter grammars Orkeon never loads (31 native libraries β†’ 26, on win-x64), via src/Directory.Build.targets. Opt out with -p:OrkeonPruneTreeSitterGrammars=false. Every artifact in the table above carries the pruned payload, the MSI included β€” which also keeps its WiX component GUIDs stable across upgrades.

Build-time / internal (not standalone packages)

PackageId Note
Orkeon.Generators Source generator β€” consumed at build time. GitHub Packages only.
Orkeon.Host IsPackable=false β€” ships only as the orkeon-host binary in the release archives.

How publication is wired

  • All NuGet packing and pushing lives in publish.yml (tag v*): the tag/version guard and scripts/check-release-readiness.py (CHANGELOG section cut, PublicAPI shipped), a Release build and the unit + fast tests, dotnet pack Orkeon.sln driven by IsPackable, the scripts/check-package-closure.py gate on the packed artifacts, a push of everything to GitHub Packages with --skip-duplicate (idempotent re-runs), then the NuGet.org lineup (the table above, Orkeon first) to NuGet.org. Its publish-dev job also packs every green push to main, for GitHub Packages only (see Dev channel above). ci.yml validates (build + test) and packs nothing; release.yml builds the installer archives and the container image, no NuGet packing.
  • NuGet.org auth is Trusted Publishing (OIDC) β€” no long-lived API key. A nuget.org policy (repository Orkeon/orkeon, workflow publish.yml) lets NuGet/login exchange the job's OIDC token for a short-lived key; the steps are gated on the NUGET_USER repository variable (the nuget.org profile owning the policy). Both are set up and proven β€” the per-layer pushes went through this path; if the variable ever disappears the steps emit a warning and no-op instead of failing the tag. Expanding the NuGet.org lineup is a maintainer decision recorded in this matrix first (and mirrored in check-package-closure.py's LINEUP, the workflow's push loop, the closure-gate arguments and CONTRIBUTING's release process β€” check-doc-claims.py fails when any copy disagrees), never a workflow edit made in passing.
  • publish.yml refuses a tag that does not match the src/Directory.Build.props version: a tag that re-packs an unchanged props version would make --skip-duplicate skip every push and publish nothing.
  • Provenance and SBOM. Both workflows attest what they publish with actions/attest-build-provenance (SLSA v1, signed through Sigstore's public instance and entered in its transparency log): publish.yml every *.nupkg of a tag (dev-channel builds are not attested), release.yml every archive, .deb and MSI. The ghcr.io/orkeon/orkeon image release.yml pushes to GHCR is not attested. Both generate a CycloneDX SBOM of Orkeon.sln right after the build (CycloneDX dotnet tool, pinned version, no third-party action) β€” orkeon-<version>.sbom.cdx.json β€” and cover it with the same attestation: a release asset next to the archives and a line in SHA256SUMS in release.yml, a run artefact named sbom in publish.yml. How to verify any of it, and why a nuget.org download must shed its repository signature first, is in Verify what you install.
  • Locked dependency graphs. The packages are built from locked dependency graphs: every project of Orkeon.sln outside examples/ commits a packages.lock.json next to it (Directory.Build.targets), and CI restores in locked mode (RestoreLockedMode under the CI variable), so a restore that would resolve a transitive package differently fails instead of drifting. Two restores are deliberately unlocked: the build-test-net11 lane (another SDK, to see what it resolves) and every restore with a runtime identifier β€” the per-RID dotnet publish -r of package-installers.sh/.ps1 and of Dockerfile.runners (the committed lock file records the RID-less graph): such a restore writes its own lock file under the project's intermediate folder and never rewrites the committed one. The dotnet new template content ships no lock file.
  • Version flows from src/Directory.Build.props, the single source of truth: no project overrides it, and the publish workflow's tag guard refuses any v* tag that disagrees with it. The dev channel derives its <X.Y.Z>-<pre>.dev.<n> from it, a build made from a checkout its <version>.local.<stamp> (see Dev channel above).