You know the argument.\nSomeone pastes the FHS paragraph about /usr/local and declares victory.\nSomeone else points at %ProgramFiles% and mutters about MSI like it is a moral failing.\nA third person lives in ~/.local/bin and refuses to explain why that is different from the first two.\nEveryone is half right.\nEveryone is also performing a standard they never read end-to-end.
I keep coming back to installs because they are where philosophy meets disk: what you claim to own, what you leave reversible, and what a shell—or a graph store five years from now—can still find without archaeology.
\nThis essay is not a shipping notice.\nIt is the craft frame behind an installation norms guide and a layout proposal (UIL) we are writing into general-knowledge.\nRead those pages when you want checklists and diagrams.\nStay here if you want the why.
\nLayout theater vs an install contract
\nA bad install, in the sense that keeps hurting users, is not always a buggy script.\nOften it is an unstated contract: files copied because \"that is where things go,\" global environment mutated without a ledger, uninstall that deletes a folder but not the PATH entry that outlived it, upgrade that assumes only one version may exist because the author never side-by-side’d anything.
\nA good install names its claims before it writes.\nMachine scope vs user scope is a design choice, not a default.\nSide-by-side versions are a feature when your CLI promises semver.\nRollback is not magic—it is knowing which registry keys, which services, which well-known names you touched.
\nThat sounds obvious written down.\nIt is rarely how installer templates behave, because templates optimize for the demo machine where /usr/local was empty and PATH was short.
The norms guide we are assembling tries to say the quiet part out loud: separate \"where files land\" from \"what the install promises to the rest of the system.\"\nLand files in a tree that matches your support story.\nPromise the environment in a record something else can read—future you, a coordinator, a shell pin resolver.
\nFHS, SUS, and the cargo-cult trap
\nThe Filesystem Hierarchy Standard is useful the way a city map is useful: it orients newcomers.\nIt is not a runtime API.\nNothing in the kernel rejects your binary because you chose opt/myvendor instead of a wiki’s favorite spelling.
POSIX and the Single UNIX Specification are deeper—they stabilize behavior engineers can rely on across systems.\nThey still do not answer the question that burns CLI authors: where does this tool live for one user on one laptop when the distro package manager, the language ecosystem, and the vendor tarball all disagree?
\nCargo-cult FHS is the habit of quoting hierarchy documents without naming claims.\nYou see it in post-install scripts that chmod +x into system directories \"because Linux,\" in Docker images that mimic a full FHS tree for a single static binary, in debates that treat /usr/local as sin or sacrament without asking who shares that prefix on the host.
Craft means treating variance as input.\nFedora’s packaging norms, Ubuntu’s Snaps, a corporate golden image, and your own ~/.local habit are different hosts.\nA layout that works is one whose assumptions are explicit—and whose undo path does not require guessing which of three PATH edits was yours.
Windows: direct-to-disk is not cheating
\nLinux people sometimes treat Windows \"portable folder plus PATH\" installs as immature.\nThat judgment skips the platform’s requirement set.
\nMSI is a transactional, serialized mutation engine with a global lock and shared component bookkeeping.\nIt exists because IT needed pessimistic safety more than parallel indie installs.\nThe _MSIExecute mutex is not stupidity; it is a coarse gate chosen before your package’s file list is known.\nWe wrote about that feeling—double-click, silence, Another installation is already in progress—in When unrelated installers still queue.
So Windows tools often write where you point them or append PATH in place with a ledger because the alternative is pretending every dev iteration is an enterprise MSI.\nThat is not avoiding adulthood.\nIt is matching the job: iterative CLI work wants reversibility and visibility, not a ref-count graph for a redistributable you never shared.
\nCraft on Windows still means the same contract: declare claims, keep undo honest, export MSI/MSIX when the deployment story requires tables and GPO—not because MSI is the only moral installer.
\nLinux variance without pretending one /usr
\nOn Linux the pain is pluralism, not absence of standards.\nXDG gives config and data homes; binaries still scatter.\nDistro packages, language-specific shims, and vendor tarballs coexist on one $PATH, and tab completion breaks in proportion to how many silent mutators ran before login.
Good craft here looks like well-known entrypoint names, versioned install roots, and environment mutation you can enumerate.\nBad craft looks like \"we picked /usr/local/bin because the README said so\" with no story for Nix users, container bind mounts, or a user who cannot sudo.
The encyclopedia cluster under installation architecture names patterns and anti-patterns so authors stop re-deriving this thread from first principles on every new tool.
\nUIL: one layout, two futures
\nThe Unity Install Layout (UIL) proposal is the structural bet I want to be wrong about in the details but right about in shape.
\nClassic mode is today: explicit roots, side-by-side versions, ledgers for PATH and registry, entrypoints a shell can see.
\nConnectome mode is tomorrow’s graph: the same install as addressable content—editions, dependencies, rollback as graph operations, not only rm -rf and hope.
connectome-fs (connectome-fs.github.io) is the sibling org exploring that substrate—content-addressed storage where dependency edges can be first-class.\nI am not claiming your next laptop boots into a graph filesystem.\nI am claiming that if your install story only maps to a directory tree, you will rewrite it when graph-native storage stops being a research slide.
\nUIL is dual-mode so we do not fork the mental model: the manifest you author for classic paths should have a straight mapping to connectome editions.\nIf that mapping is painful, the manifest is lying about what an install is.
\nProposal write-up: Unity Install Layout (UIL).\nNorms checklist: Installation norms.
\nShell visibility (why OpenShellOrg is in this essay)
\nOpenShellOrg cares about entrypoint dispatch—pins, re-exec, refusing to let the wrong Node answer when the pin said otherwise.\nThat work only succeeds when installs are honest on the shell boundary: binaries and shims on PATH, registrations that match what landed on disk, undo that does not leave a stale shim pointing at a deleted tree.
DevCentr’s toolchain lifecycle story and OpenShellOrg’s shell-boundary story are siblings, not duplicates.\nWe orchestrate pins and health; they stress-test whether the shell can trust what it launches.\nAn install layout that hides binaries deep in %ProgramFiles% without a stable entrypoint is not \"more secure\"—it is invisible, which makes dispatch guesses and user hacks more likely, not fewer.
If you care about structured shells, treat shell-visible installs as a first-class layout requirement, not a packaging afterthought.
\nTooling as hypothesis, not billboard
\nDocs should lead; tools should falsify the docs.
\nWe are exploring Install Coordinator because orchestration—claims, queues, visible waits—is the gap behind pretty wizards and ugly mutex dialogs.\nIbex is the host we use to try in-place PATH with ledgers, file-manager actions, and installer.kdl backends without pretending every artifact is MSI.\nNeither repo is the essay’s punchline.\nThey are where we test whether the norms survive contact with Windows Explorer and CI emit.
Ibex tool docs: Ibex.\nPattern comparison: Good vs bad install patterns.
\nWhat I want you to take away
\nStop asking \"where does FHS say?\" as the first question.\nAsk what this install claims, who shares those resources, how undo works, and whether a shell or a graph can find the entrypoint without spelunking.
\nIf you maintain an installer, write those answers down before the next path flamewar.\nIf you are designing storage or dispatch, read UIL alongside connectome-fs and OpenShellOrg’s essays—same human problem, different altitude.
\nThe guide will change when the field teaches us something new.\nSo will this page.\nThat is the point of inner-thought writing: the layout is a craft, not a press release.
\nA text file can store a configuration. It cannot, by itself, tell an operator which other keys exist, what the enum is, or why a default is safe. That gap is now a Dev-Centr product: UniConfig Config Panel, a schema-driven desktop surface for config files that never grew their own settings UI.
\nThe first beat is deliberately ordinary. Point the app at a .gitconfig, a dub.sdl, an EditorConfig, or a Terraform .tfvars. The same panel widgets appear: labels, descriptions, drop-downs, include checkboxes for unset schema fields. Opened files register into a left-hand tree persisted as SDLang (registry.sdl). Headless dump and validate exist for the same merge.
The engine is a separate D package, uniconfig-core, so the DevCentr suite can depend on the tree without dragging dlangui. Profiles that map filename globs onto JSON Schema ship as SDLang beside the exe. The optional Vello GPU path on the dlang-supplemental dlangui fork is documented, not required; default builds stay on dlangui’s stock backend.
Docs: UniConfig ·\nReleases: uniconfig ·\nLibrary: uniconfig-core ·\nHCI companion: When config files withhold the vocabulary.
\n![\"Split](\"https://devcentr.org/news/media/uniconfig-vocabulary-split.png\")
\nA text file can store a configuration. It cannot, by itself, tell an operator which other keys exist, what the enum is, or why a default is safe. That gap is now a Dev-Centr product: UniConfig Config Panel, a schema-driven desktop surface for config files that never grew their own settings UI.
\nThe first beat is deliberately ordinary. Point the app at a .gitconfig, a dub.sdl, an EditorConfig, or a Terraform .tfvars. The same panel widgets appear: labels, descriptions, drop-downs, include checkboxes for unset schema fields. Opened files register into a left-hand tree persisted as SDLang (registry.sdl). Headless dump and validate exist for the same merge.
The engine is a separate D package, uniconfig-core, so the DevCentr suite can depend on the tree without dragging dlangui. Profiles that map filename globs onto JSON Schema ship as SDLang beside the exe. The optional Vello GPU path on the dlang-supplemental dlangui fork is documented, not required; default builds stay on dlangui’s stock backend.
Docs: UniConfig ·\nReleases: uniconfig ·\nLibrary: uniconfig-core ·\nHCI companion: When config files withhold the vocabulary.
\n\nOpen almost any developer console and you will find the same soft lie waiting under a friendly button: Generate your API access token.\nYou click it.\nYou get a long string that never expires unless you delete it, that identifies your project or account, and that you will paste into a .env file and forget until something leaks.\nThat string is not an access token in the OAuth sense.\nIt is an API key wearing a costume stitched from marketing and Bearer-header habits.
We are done pretending the costume is the thing.\nDev-Centr’s docs and Secrets Manager now name credentials by what they do, not by what the vendor’s UI whispered while you were trying to ship.
\nPractitioner lock (use this in reviews and agent prompts): API key vs token.\nProduct enforcement: Secrets Manager vocabulary.
\nA scene from every onboarding
\nPicture a Monday standup where someone says the integration is \"using a token.\"\nHalf the room hears short-lived OAuth bearer from a login flow.\nThe other half hears the string we copied from Settings → Developers last quarter.\nNobody notices the mismatch until a rotation runbook says \"revoke the key\" and an agent helpfully tries to refresh it like a session.
\nThat is not pedantry.\nWrong nouns pick the wrong playbook: dashboard rotate versus protocol refresh; project metering versus user consent; forever-secret versus fifteen-minute claim set.
\nWhat the words actually mean
\nAn API key identifies the application or project making the request.\nIt is how a platform bills you, rates you, and attributes traffic to \"the Stripe integration\" or \"the mobile backend.\"\nIt does not prove which human is pressing the buttons inside that app.
\nAn access token—OAuth access token, JWT bearer, session token—identifies an authorized subject for a limited time.\nIt answers what this holder may do now, often with scopes and an expiry baked into the credential (or into the introspection service behind it).
\nHold the analogies for a second and you can feel the difference in your hands:
\n- \n
- \n
The API key is the project’s driver’s license. The meter knows which fleet car pulled up.
\n \n - \n
The access token is a hotel keycard. It opens these floors for this stay. Morning checkout is a feature, not a bug.
\n \n
How \"token\" ate the dashboard
\nOAuth taught a generation of engineers that scoped access arrives as an access token.\nCloud consoles borrowed the word for a different product: long-lived secrets you mint yourself, optionally with checkbox scopes, optionally revoked one-by-one without nuking the whole account.
\nSo the industry grew a middle creature—scoped API keys, often sold as personal access tokens (PATs)—and dressed it in token language because:
\n- \n
- \n
scopes made it feel like OAuth,
\n \n - \n
Bearer headers made it travel like OAuth,
\n \n - \n
and \"token\" sounded newer and safer than the grim old \"API key\" that once meant a single immortal string for the entire account.
\n \n
Useful product evolution.\nTerrible vocabulary.
\nUnder the hood you still have two architectures:
\n- \n
- \n
Scoped key / PAT — long-lived, dashboard-born, manually revoked, project- or account-bound with capability limits.
\n \n - \n
True access token — handshake-born, short TTL, subject-bound, refreshed by protocol rather than by a human with a clipboard.
\n \n
The rule we are enforcing
\nIgnore the button.\nAsk three questions:
\n- \n
- \n
Was this pasted from a settings page, or minted by a login / client-credentials handshake?
\n \n - \n
Does it expire in minutes or hours by design, or only when someone deletes it?
\n \n - \n
Does it authorize a user or session, or only identify a project for metering?
\n \n
Dashboard paste + manual revoke → API key (scoped or not).\nHandshake + TTL → access token (and keep refresh token for the minting secret, not for ordinary API calls).
\nIn Secrets Manager kinds we write that as api_key, scoped_api_key, access_token, and refresh_token.\nVendor aliases can live in notes for search.\nThey do not get to own the type field.
Why Dev-Centr is picking this fight
\nWe distribute secrets for a living—vendor → vault → local env → hosting matrix—and agents already hallucinate env names when the nouns wobble.\nIf the UI says \"token\" and the architecture says \"key,\" the agent will under-rotate forever-strings or over-store live session material.\nSecurity reviews then argue about words instead of blast radius.
\nSo the docs tell the truth, the product forces the kinds, and this post is the public notice: stop calling keys tokens just because a dashboard did.
\nThe costume can stay on the marketing site.\nIt does not get into our registry.
\nOpen almost any developer console and you will find the same soft lie waiting under a friendly button: Generate your API access token.\nYou click it.\nYou get a long string that never expires unless you delete it, that identifies your project or account, and that you will paste into a .env file and forget until something leaks.\nThat string is not an access token in the OAuth sense.\nIt is an API key wearing a costume stitched from marketing and Bearer-header habits.
We are done pretending the costume is the thing.\nDev-Centr’s docs and Secrets Manager now name credentials by what they do, not by what the vendor’s UI whispered while you were trying to ship.
\nPractitioner lock (use this in reviews and agent prompts): API key vs token.\nProduct enforcement: Secrets Manager vocabulary.
\nA scene from every onboarding
\nPicture a Monday standup where someone says the integration is \"using a token.\"\nHalf the room hears short-lived OAuth bearer from a login flow.\nThe other half hears the string we copied from Settings → Developers last quarter.\nNobody notices the mismatch until a rotation runbook says \"revoke the key\" and an agent helpfully tries to refresh it like a session.
\nThat is not pedantry.\nWrong nouns pick the wrong playbook: dashboard rotate versus protocol refresh; project metering versus user consent; forever-secret versus fifteen-minute claim set.
\nWhat the words actually mean
\nAn API key identifies the application or project making the request.\nIt is how a platform bills you, rates you, and attributes traffic to \"the Stripe integration\" or \"the mobile backend.\"\nIt does not prove which human is pressing the buttons inside that app.
\nAn access token—OAuth access token, JWT bearer, session token—identifies an authorized subject for a limited time.\nIt answers what this holder may do now, often with scopes and an expiry baked into the credential (or into the introspection service behind it).
\nHold the analogies for a second and you can feel the difference in your hands:
\n- \n
- \n
The API key is the project’s driver’s license. The meter knows which fleet car pulled up.
\n \n - \n
The access token is a hotel keycard. It opens these floors for this stay. Morning checkout is a feature, not a bug.
\n \n
How \"token\" ate the dashboard
\nOAuth taught a generation of engineers that scoped access arrives as an access token.\nCloud consoles borrowed the word for a different product: long-lived secrets you mint yourself, optionally with checkbox scopes, optionally revoked one-by-one without nuking the whole account.
\nSo the industry grew a middle creature—scoped API keys, often sold as personal access tokens (PATs)—and dressed it in token language because:
\n- \n
- \n
scopes made it feel like OAuth,
\n \n - \n
Bearer headers made it travel like OAuth,
\n \n - \n
and \"token\" sounded newer and safer than the grim old \"API key\" that once meant a single immortal string for the entire account.
\n \n
Useful product evolution.\nTerrible vocabulary.
\nUnder the hood you still have two architectures:
\n- \n
- \n
Scoped key / PAT — long-lived, dashboard-born, manually revoked, project- or account-bound with capability limits.
\n \n - \n
True access token — handshake-born, short TTL, subject-bound, refreshed by protocol rather than by a human with a clipboard.
\n \n
The rule we are enforcing
\nIgnore the button.\nAsk three questions:
\n- \n
- \n
Was this pasted from a settings page, or minted by a login / client-credentials handshake?
\n \n - \n
Does it expire in minutes or hours by design, or only when someone deletes it?
\n \n - \n
Does it authorize a user or session, or only identify a project for metering?
\n \n
Dashboard paste + manual revoke → API key (scoped or not).\nHandshake + TTL → access token (and keep refresh token for the minting secret, not for ordinary API calls).
\nIn Secrets Manager kinds we write that as api_key, scoped_api_key, access_token, and refresh_token.\nVendor aliases can live in notes for search.\nThey do not get to own the type field.
Why Dev-Centr is picking this fight
\nWe distribute secrets for a living—vendor → vault → local env → hosting matrix—and agents already hallucinate env names when the nouns wobble.\nIf the UI says \"token\" and the architecture says \"key,\" the agent will under-rotate forever-strings or over-store live session material.\nSecurity reviews then argue about words instead of blast radius.
\nSo the docs tell the truth, the product forces the kinds, and this post is the public notice: stop calling keys tokens just because a dashboard did.
\nThe costume can stay on the marketing site.\nIt does not get into our registry.
\nmsi-generator crossed the line from \"skeleton that prints a message\" to \"file you can open in an OLE/MSI viewer.\"
\nv0.2 writes a version-3 compound file, an uncompressed cabinet payload, and the core table set (Directory, Component, File, Feature, FeatureComponents, Property, Media, plus _Tables / _Columns and the string pool). MSIX gained multi-file payloads and placeholder assets so manifests stop lying about missing logos.
This is the engine Ibex’s msi / msix plugins call. It is not WiX, and we are not pretending an unsigned sample MSI is Store-ready — but the binary formats are finally real enough to iterate on.
msi-generator crossed the line from \"skeleton that prints a message\" to \"file you can open in an OLE/MSI viewer.\"
\nv0.2 writes a version-3 compound file, an uncompressed cabinet payload, and the core table set (Directory, Component, File, Feature, FeatureComponents, Property, Media, plus _Tables / _Columns and the string pool). MSIX gained multi-file payloads and placeholder assets so manifests stop lying about missing logos.
This is the engine Ibex’s msi / msix plugins call. It is not WiX, and we are not pretending an unsigned sample MSI is Store-ready — but the binary formats are finally real enough to iterate on.
DevCentr’s new install tool is out: Ibex (Install Builder EXtension). It turns \"put this folder on PATH\" and \"build an installer from this tree\" into something you can right-click or script. The CLI is ibex.
The first beat is deliberately small. Install in-place (add to PATH) means what it says — append the folder to the user PATH, keep a ledger so you can undo, and skip the copy-into-Program-Files ritual when you are iterating on a CLI. File Explorer gets a menu for it (Win11 modern when the sparse package builds; classic cascade otherwise). Linux and macOS get file-manager actions too.
\nThe second beat is the project file. installer.kdl plus plugins: portable zip always works; NSIS and Inno emit scripts and call their compilers when present; MSI/MSIX call msi-generator; AppImage gets a stub path on Linux. Optional designer GUIs are discoverable (plugins install-gui) instead of reinvented inside our IDE.
CI ships in the same cut. Edit ci-runner.sdl, run emit-ci, and get runner YAML plus CI-INSTALLER.adoc (how to enable pipelines, secrets, tags, and artifact downloads). Local build stays optional for smoke tests. Emitters in this release: GitHub Actions, GitLab CI, Azure Pipelines, Jenkins (Declarative), CircleCI, and Bitbucket Pipelines. DevCentr’s New Installer dialog can choose CI pipeline only; Explorer gets New Installer CI pipeline (--mode=emit-ci).
DevCentr picks up the same verbs — New → Installer Project, toolbar Install in-place PATH, and CLI modes — so the OS menu and the app are not two products pretending to be one.
\nDocs: Ibex · emit CI how-to · releases.
\n![\"Ibex](\"/news/media/easy-installer-standalone.webp\")
\n![\"DevCentr](\"/news/media/easy-installer-devcentr.webp\")
\nDevCentr’s new install tool is out: Ibex (Install Builder EXtension). It turns \"put this folder on PATH\" and \"build an installer from this tree\" into something you can right-click or script. The CLI is ibex.
The first beat is deliberately small. Install in-place (add to PATH) means what it says — append the folder to the user PATH, keep a ledger so you can undo, and skip the copy-into-Program-Files ritual when you are iterating on a CLI. File Explorer gets a menu for it (Win11 modern when the sparse package builds; classic cascade otherwise). Linux and macOS get file-manager actions too.
\nThe second beat is the project file. installer.kdl plus plugins: portable zip always works; NSIS and Inno emit scripts and call their compilers when present; MSI/MSIX call msi-generator; AppImage gets a stub path on Linux. Optional designer GUIs are discoverable (plugins install-gui) instead of reinvented inside our IDE.
CI ships in the same cut. Edit ci-runner.sdl, run emit-ci, and get runner YAML plus CI-INSTALLER.adoc (how to enable pipelines, secrets, tags, and artifact downloads). Local build stays optional for smoke tests. Emitters in this release: GitHub Actions, GitLab CI, Azure Pipelines, Jenkins (Declarative), CircleCI, and Bitbucket Pipelines. DevCentr’s New Installer dialog can choose CI pipeline only; Explorer gets New Installer CI pipeline (--mode=emit-ci).
DevCentr picks up the same verbs — New → Installer Project, toolbar Install in-place PATH, and CLI modes — so the OS menu and the app are not two products pretending to be one.
\nDocs: Ibex · emit CI how-to · releases.
\n\n\n