From 1575779007f534eaa3dbc86b1172b24646303cbe Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 18 Sep 2026 15:39:31 +0000 Subject: [PATCH] news: installation norms guide and UIL proposal (2026-09-18) Announce the general-knowledge installation architecture cluster, Unity Install Layout dual-mode proposal, and DevCentr tooling path (Install Coordinator, Ibex) for engineers shipping desktop/CLI installs. Co-authored-by: Ryan Johnson --- ...2026-09-18-installation-norms-and-uil.adoc | 90 +++++++++++++++++++ public/news/atom.xml | 11 ++- public/news/rss.xml | 11 ++- src/lib/news-posts.generated.json | 28 +++++- 4 files changed, 134 insertions(+), 6 deletions(-) create mode 100644 content/news/2026-09-18-installation-norms-and-uil.adoc diff --git a/content/news/2026-09-18-installation-norms-and-uil.adoc b/content/news/2026-09-18-installation-norms-and-uil.adoc new file mode 100644 index 0000000..44a0a63 --- /dev/null +++ b/content/news/2026-09-18-installation-norms-and-uil.adoc @@ -0,0 +1,90 @@ += Beyond FHS: installation norms that survive Windows, Linux, and connectome-fs +:description: DevCentr publishes an authoritative installation norms guide and the Unity Install Layout (UIL) proposal — good patterns vs cargo-cult FHS, Windows honesty, and a dual-mode path toward connectome-fs. +:revdate: 2026-09-18 +:keywords: news, blog, installation, FHS, UIL, Ibex, Install Coordinator, OpenShellOrg, connectome-fs, DevCentr + +If you ship desktop tools or CLIs, you have probably argued about install paths at 2 a.m. +Linux people quote FHS like scripture. +Windows people copy into `Program Files` because MSI taught them to, or they skip the ritual and drop a folder on disk because that is what actually ships. +macOS people pretend `/Applications` is universal while Homebrew lives in `/opt` and your user runs `~/.local/bin` anyway. +None of those stories is wrong in isolation. +Together they are why "just follow the standard" keeps failing across machines. + +We wrote the guide we wished existed when we started Ibex and the MSI work: **what a good install actually is**, written for engineers who are tired of cargo-cult layout and Windows exceptions treated as shameful hacks. + +== Good installs vs layout theater + +A **bad** install pattern hides assumptions: copy files somewhere "standard," mutate global `PATH` without a ledger, treat `/usr/local` as a junk drawer, or wrap every CLI in an MSI because IT once asked for one. +The user cannot tell what changed, cannot undo cleanly, and cannot point a shell or a future graph store at the result. + +A **good** install pattern **declares** what it owns: directories, registry keys, services, well-known names. +It separates **machine-wide** from **per-user** scope on purpose. +It keeps a **reversible** record when it touches shared environment (especially `PATH`). +It chooses **in-place** or **copy-out** based on the job — iterating on a dev build is not the same contract as shipping to a locked-down laptop. +It stays honest when the platform has no real standard (user-local CLI on Linux is the classic gap). + +The new encyclopedia cluster states those norms explicitly and names the anti-patterns we see in the wild — not to scold, but so installer authors stop re-learning the same bruises. + +== Why Windows often writes straight to disk + +Windows is not "broken"; it optimized for a different failure mode. +MSI's global `_MSIExecute` lock, transactional commit/rollback, and shared component ref-counting reward careful, serialized system mutation — and punish casual parallel installs with opaque dialogs. +That is why so many developer tools on Windows **write where you point them** or **append PATH in place** instead of pretending every build is an enterprise MSI. + +We already named the orchestration gap in link:https://devcentr.org/news/2026-08-29-when-unrelated-installers-still-queue[When unrelated installers still queue]. +The norms guide connects that essay to day-to-day choices: when MSI/MSIX is the right export, when a portable tree plus ledgered PATH is healthier, and why "just use WiX" is not a lifecycle strategy. + +== POSIX, SUS, and the Linux variance problem + +FHS and friends describe **conventions**, not enforceable law. +POSIX and SUS tell you a lot about process and file semantics; they do **not** give you one blessed answer for "where does this CLI live for one user on Fedora vs Ubuntu vs a corporate image." +XDG helps for config and data; tool binaries still sprawl across `/usr/bin`, `/usr/local/bin`, `~/.local/bin`, Snap flat mounts, and vendor trees. + +Pretending one layout string works everywhere is how you get fragile post-install scripts and broken tab completion. +The guide treats **variance as input** — document what you need from the host, do not assume the host shares your distro wiki habits. + +== Unity Install Layout (UIL): classic paths today, graph tomorrow + +The **Unity Install Layout (UIL)** proposal is the structural half of the same story. +UIL is a **dual-mode** contract: + +* **Classic mode** — layouts that work on today's OS trees: explicit roots, versioned side-by-side installs, well-known entrypoint names, ledgers for environment mutation. +* **Connectome mode** — the same install expressed as **addressable content** on a connectome-fs graph: editions, dependencies, and rollback as graph operations instead of only directory deletes. + +We are not claiming connectome-fs replaces `/usr` tomorrow. +We **are** claiming that if your install story cannot map to both a conventional path **and** a stable content graph, you will rewrite everything when graph-native storage stops being a research slide. + +connectome-fs (link:https://connectome-fs.github.io/[connectome-fs.github.io]) is the sibling org exploring that substrate; general-knowledge cross-links the practitioner essays without overselling readiness. + +== Why OpenShellOrg cares about shell-visible installs + +link:https://openshellorg.github.io/[OpenShellOrg] lives at the shell boundary: entrypoint dispatch, pins, and re-exec when the wrong binary answered. +That only works if installs are **visible** — on `PATH`, registered honestly, discoverable without spelunking `Program Files` or a random `~/go/bin`. + +We partner with OpenShellOrg (see link:https://devcentr.org/news/2026-07-28-partnering-with-openshellorg[We're partnering with OpenShellOrg (on purpose)]): DevCentr owns toolchain lifecycle orchestration; they refuse to let the shell lie about which host runs. +UIL and the norms guide encode the install side of that handshake — where files land, how entrypoints register, how undo works. + +== DevCentr tooling: Install Coordinator + Ibex + +Docs are the spec; tools are how we eat our own cooking. + +* link:https://github.com/dev-centr/install-coordinator[install-coordinator] — coordination layer for install claims, queues, and visibility (the direction behind smarter scheduling, not another silent MSI mutex). +* link:https://github.com/dev-centr/ibex-install-builder[ibex-install-builder] — **Ibex**: `installer.kdl`, in-place PATH with ledger, Explorer and file-manager actions, CI emit, and plugin backends (portable zip, NSIS, Inno, MSI via msi-generator, and friends). + +Ibex shipped in link:https://devcentr.org/news/2026-08-06-easy-installer-ships[August]; the norms guide explains *why* those verbs exist instead of treating them as Windows-only shortcuts. + +== Read next (general-knowledge installation cluster) + +The Antora component is `general-knowledge`; URLs follow the installation architecture cluster (rolling out on docs.devcentr.org): + +* link:https://docs.devcentr.org/general-knowledge/explanation/architecture/installation/[Installation architecture hub] +* link:https://docs.devcentr.org/general-knowledge/explanation/architecture/installation/installation-norms.html[Installation norms — authoritative guide] +* link:https://docs.devcentr.org/general-knowledge/explanation/architecture/installation/unity-install-layout.html[Unity Install Layout (UIL) proposal] +* link:https://docs.devcentr.org/general-knowledge/explanation/architecture/installation/good-vs-bad-patterns.html[Good vs bad install patterns] +* link:https://docs.devcentr.org/tools/ibex/latest/index.html[Ibex tool docs] + +If you maintain an installer, skim the norms page before the next path debate. +If you are designing storage or shell entrypoints, read UIL alongside connectome-fs and OpenShellOrg's dispatch essays — same problem, three altitudes. + +We will revise the cluster as Install Coordinator hardens and UIL stops being a proposal slide. +War stories welcome; the guide is meant to change when the field teaches us something new. diff --git a/public/news/atom.xml b/public/news/atom.xml index e736ce8..0f35fa5 100644 --- a/public/news/atom.xml +++ b/public/news/atom.xml @@ -4,8 +4,17 @@ https://devcentr.org/news - 2026-09-03T12:00:00Z + 2026-09-18T12:00:00Z News and engineering blog posts from Dev-Centr. + + Beyond FHS: installation norms that survive Windows, Linux, and connectome-fs + + https://devcentr.org/news/2026-09-18-installation-norms-and-uil + 2026-09-18T12:00:00Z + DevCentr publishes an authoritative installation norms guide and the Unity Install Layout (UIL) proposal — good patterns vs cargo-cult FHS, Windows honesty, and a dual-mode path toward connectome-fs. + + + MarkView for reading Markdown on disk diff --git a/public/news/rss.xml b/public/news/rss.xml index a6eb8c0..8b367c4 100644 --- a/public/news/rss.xml +++ b/public/news/rss.xml @@ -5,7 +5,16 @@ https://devcentr.org/news News and engineering blog posts from Dev-Centr. en-us - Thu, 03 Sep 2026 12:00:00 GMT + Fri, 18 Sep 2026 12:00:00 GMT + + Beyond FHS: installation norms that survive Windows, Linux, and connectome-fs + https://devcentr.org/news/2026-09-18-installation-norms-and-uil + https://devcentr.org/news/2026-09-18-installation-norms-and-uil + Fri, 18 Sep 2026 12:00:00 GMT + DevCentr publishes an authoritative installation norms guide and the Unity Install Layout (UIL) proposal — good patterns vs cargo-cult FHS, Windows honesty, and a dual-mode path toward connectome-fs. + blog + news + MarkView for reading Markdown on disk https://devcentr.org/news/2026-09-03-markview-for-reading-markdown-on-disk diff --git a/src/lib/news-posts.generated.json b/src/lib/news-posts.generated.json index a2252f6..43cf310 100644 --- a/src/lib/news-posts.generated.json +++ b/src/lib/news-posts.generated.json @@ -1,5 +1,25 @@ { "posts": [ + { + "slug": "2026-09-18-installation-norms-and-uil", + "title": "Beyond FHS: installation norms that survive Windows, Linux, and connectome-fs", + "description": "DevCentr publishes an authoritative installation norms guide and the Unity Install Layout (UIL) proposal — good patterns vs cargo-cult FHS, Windows honesty, and a dual-mode path toward connectome-fs.", + "date": "2026-09-18", + "tags": [ + "news", + "blog", + "installation", + "FHS", + "UIL", + "Ibex", + "Install Coordinator", + "OpenShellOrg", + "connectome-fs", + "DevCentr" + ], + "html": "
\n
\n
\n

If you ship desktop tools or CLIs, you have probably argued about install paths at 2 a.m.\nLinux people quote FHS like scripture.\nWindows people copy into Program Files because MSI taught them to, or they skip the ritual and drop a folder on disk because that is what actually ships.\nmacOS people pretend /Applications is universal while Homebrew lives in /opt and your user runs ~/.local/bin anyway.\nNone of those stories is wrong in isolation.\nTogether they are why \"just follow the standard\" keeps failing across machines.

\n
\n
\n

We wrote the guide we wished existed when we started Ibex and the MSI work: what a good install actually is, written for engineers who are tired of cargo-cult layout and Windows exceptions treated as shameful hacks.

\n
\n
\n
\n
\n

Good installs vs layout theater

\n
\n
\n

A bad install pattern hides assumptions: copy files somewhere \"standard,\" mutate global PATH without a ledger, treat /usr/local as a junk drawer, or wrap every CLI in an MSI because IT once asked for one.\nThe user cannot tell what changed, cannot undo cleanly, and cannot point a shell or a future graph store at the result.

\n
\n
\n

A good install pattern declares what it owns: directories, registry keys, services, well-known names.\nIt separates machine-wide from per-user scope on purpose.\nIt keeps a reversible record when it touches shared environment (especially PATH).\nIt chooses in-place or copy-out based on the job — iterating on a dev build is not the same contract as shipping to a locked-down laptop.\nIt stays honest when the platform has no real standard (user-local CLI on Linux is the classic gap).

\n
\n
\n

The new encyclopedia cluster states those norms explicitly and names the anti-patterns we see in the wild — not to scold, but so installer authors stop re-learning the same bruises.

\n
\n
\n
\n
\n

Why Windows often writes straight to disk

\n
\n
\n

Windows is not \"broken\"; it optimized for a different failure mode.\nMSI’s global _MSIExecute lock, transactional commit/rollback, and shared component ref-counting reward careful, serialized system mutation — and punish casual parallel installs with opaque dialogs.\nThat is why so many developer tools on Windows write where you point them or append PATH in place instead of pretending every build is an enterprise MSI.

\n
\n
\n

We already named the orchestration gap in When unrelated installers still queue.\nThe norms guide connects that essay to day-to-day choices: when MSI/MSIX is the right export, when a portable tree plus ledgered PATH is healthier, and why \"just use WiX\" is not a lifecycle strategy.

\n
\n
\n
\n
\n

POSIX, SUS, and the Linux variance problem

\n
\n
\n

FHS and friends describe conventions, not enforceable law.\nPOSIX and SUS tell you a lot about process and file semantics; they do not give you one blessed answer for \"where does this CLI live for one user on Fedora vs Ubuntu vs a corporate image.\"\nXDG helps for config and data; tool binaries still sprawl across /usr/bin, /usr/local/bin, ~/.local/bin, Snap flat mounts, and vendor trees.

\n
\n
\n

Pretending one layout string works everywhere is how you get fragile post-install scripts and broken tab completion.\nThe guide treats variance as input — document what you need from the host, do not assume the host shares your distro wiki habits.

\n
\n
\n
\n
\n

Unity Install Layout (UIL): classic paths today, graph tomorrow

\n
\n
\n

The Unity Install Layout (UIL) proposal is the structural half of the same story.\nUIL is a dual-mode contract:

\n
\n
\n
    \n
  • \n

    Classic mode — layouts that work on today’s OS trees: explicit roots, versioned side-by-side installs, well-known entrypoint names, ledgers for environment mutation.

    \n
    • \n
  • \n

    Connectome mode — the same install expressed as addressable content on a connectome-fs graph: editions, dependencies, and rollback as graph operations instead of only directory deletes.

    \n
    • \n
\n
\n
\n

We are not claiming connectome-fs replaces /usr tomorrow.\nWe are claiming that if your install story cannot map to both a conventional path and a stable content graph, you will rewrite everything when graph-native storage stops being a research slide.

\n
\n
\n

connectome-fs (connectome-fs.github.io) is the sibling org exploring that substrate; general-knowledge cross-links the practitioner essays without overselling readiness.

\n
\n
\n
\n
\n

Why OpenShellOrg cares about shell-visible installs

\n
\n
\n

OpenShellOrg lives at the shell boundary: entrypoint dispatch, pins, and re-exec when the wrong binary answered.\nThat only works if installs are visible — on PATH, registered honestly, discoverable without spelunking Program Files or a random ~/go/bin.

\n
\n
\n

We partner with OpenShellOrg (see We’re partnering with OpenShellOrg (on purpose)): DevCentr owns toolchain lifecycle orchestration; they refuse to let the shell lie about which host runs.\nUIL and the norms guide encode the install side of that handshake — where files land, how entrypoints register, how undo works.

\n
\n
\n
\n
\n

DevCentr tooling: Install Coordinator + Ibex

\n
\n
\n

Docs are the spec; tools are how we eat our own cooking.

\n
\n
\n
    \n
  • \n

    install-coordinator — coordination layer for install claims, queues, and visibility (the direction behind smarter scheduling, not another silent MSI mutex).

    \n
    • \n
  • \n

    ibex-install-builder — Ibex: installer.kdl, in-place PATH with ledger, Explorer and file-manager actions, CI emit, and plugin backends (portable zip, NSIS, Inno, MSI via msi-generator, and friends).

    \n
    • \n
\n
\n
\n

Ibex shipped in August; the norms guide explains why those verbs exist instead of treating them as Windows-only shortcuts.

\n
\n
\n
\n
\n

Read next (general-knowledge installation cluster)

\n
\n
\n

The Antora component is general-knowledge; URLs follow the installation architecture cluster (rolling out on docs.devcentr.org):

\n
\n
\n\n
\n
\n

If you maintain an installer, skim the norms page before the next path debate.\nIf you are designing storage or shell entrypoints, read UIL alongside connectome-fs and OpenShellOrg’s dispatch essays — same problem, three altitudes.

\n
\n
\n

We will revise the cluster as Install Coordinator hardens and UIL stops being a proposal slide.\nWar stories welcome; the guide is meant to change when the field teaches us something new.

\n
\n
\n
", + "source": "authored" + }, { "slug": "2026-09-03-markview-for-reading-markdown-on-disk", "title": "MarkView for reading Markdown on disk", @@ -192,7 +212,7 @@ "dlang", "dlangui" ], - "html": "
\n

A 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.

\n
\n
\n

The 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.

\n
\n
\n

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.

\n
\n
\n

Docs: UniConfig ·\nReleases: uniconfig ·\nLibrary: uniconfig-core ·\nHCI companion: When config files withhold the vocabulary.

\n
\n
\n
\n\"Split\n
\n
Figure 1. File versus panel
\n
", + "html": "
\n

A 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.

\n
\n
\n

The 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.

\n
\n
\n

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.

\n
\n
\n

Docs: UniConfig ·\nReleases: uniconfig ·\nLibrary: uniconfig-core ·\nHCI companion: When config files withhold the vocabulary.

\n
\n
\n
\n\"Split\n
\n
Figure 1. File versus panel
\n
", "source": "authored" }, { @@ -247,7 +267,7 @@ "vocabulary", "security" ], - "html": "
\n
\n
\n

Open 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.

\n
\n
\n

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.

\n
\n
\n

Practitioner lock (use this in reviews and agent prompts): API key vs token.\nProduct enforcement: Secrets Manager vocabulary.

\n
\n
\n
\n
\n

A scene from every onboarding

\n
\n
\n

Picture 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.

\n
\n
\n

That 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.

\n
\n
\n
\n
\n

What the words actually mean

\n
\n
\n

An 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.

\n
\n
\n

An 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).

\n
\n
\n

Hold the analogies for a second and you can feel the difference in your hands:

\n
\n
\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
\n
\n
\n
\n
\n

How \"token\" ate the dashboard

\n
\n
\n

OAuth 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.

\n
\n
\n

So 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
    \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
\n
\n
\n

Useful product evolution.\nTerrible vocabulary.

\n
\n
\n

Under the hood you still have two architectures:

\n
\n
\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
\n
\n
\n
\n
\n

The rule we are enforcing

\n
\n
\n

Ignore the button.\nAsk three questions:

\n
\n
\n
    \n
  1. \n

    Was this pasted from a settings page, or minted by a login / client-credentials handshake?

    \n
    2. \n
  2. \n

    Does it expire in minutes or hours by design, or only when someone deletes it?

    \n
    3. \n
  3. \n

    Does it authorize a user or session, or only identify a project for metering?

    \n
    4. \n
\n
\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).

\n
\n
\n

In 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.

\n
\n
\n
\n
\n

Why Dev-Centr is picking this fight

\n
\n
\n

We 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.

\n
\n
\n

So 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.

\n
\n
\n

The costume can stay on the marketing site.\nIt does not get into our registry.

\n
\n
\n
", + "html": "
\n
\n
\n

Open 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.

\n
\n
\n

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.

\n
\n
\n

Practitioner lock (use this in reviews and agent prompts): API key vs token.\nProduct enforcement: Secrets Manager vocabulary.

\n
\n
\n
\n
\n

A scene from every onboarding

\n
\n
\n

Picture 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.

\n
\n
\n

That 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.

\n
\n
\n
\n
\n

What the words actually mean

\n
\n
\n

An 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.

\n
\n
\n

An 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).

\n
\n
\n

Hold the analogies for a second and you can feel the difference in your hands:

\n
\n
\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
\n
\n
\n
\n
\n

How \"token\" ate the dashboard

\n
\n
\n

OAuth 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.

\n
\n
\n

So 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
    \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
\n
\n
\n

Useful product evolution.\nTerrible vocabulary.

\n
\n
\n

Under the hood you still have two architectures:

\n
\n
\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
\n
\n
\n
\n
\n

The rule we are enforcing

\n
\n
\n

Ignore the button.\nAsk three questions:

\n
\n
\n
    \n
  1. \n

    Was this pasted from a settings page, or minted by a login / client-credentials handshake?

    \n
    2. \n
  2. \n

    Does it expire in minutes or hours by design, or only when someone deletes it?

    \n
    3. \n
  3. \n

    Does it authorize a user or session, or only identify a project for metering?

    \n
    4. \n
\n
\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).

\n
\n
\n

In 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.

\n
\n
\n
\n
\n

Why Dev-Centr is picking this fight

\n
\n
\n

We 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.

\n
\n
\n

So 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.

\n
\n
\n

The costume can stay on the marketing site.\nIt does not get into our registry.

\n
\n
\n
", "source": "authored" }, { @@ -282,7 +302,7 @@ "packaging", "DevCentr" ], - "html": "
\n

msi-generator crossed the line from \"skeleton that prints a message\" to \"file you can open in an OLE/MSI viewer.\"

\n
\n
\n

v0.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.

\n
\n
\n

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.

\n
\n
\n

Release: v0.2.0 · docs: component.

\n
", + "html": "
\n

msi-generator crossed the line from \"skeleton that prints a message\" to \"file you can open in an OLE/MSI viewer.\"

\n
\n
\n

v0.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.

\n
\n
\n

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.

\n
\n
\n

Release: v0.2.0 · docs: component.

\n
", "source": "authored" }, { @@ -300,7 +320,7 @@ "CI", "DevCentr" ], - "html": "
\n

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.

\n
\n
\n

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.

\n
\n
\n

The 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.

\n
\n
\n

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).

\n
\n
\n

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.

\n
\n
\n

Docs: Ibex · emit CI how-to · releases.

\n
\n
\n
\n\"Ibex\n
\n
Figure 1. Idealized Ibex project UI
\n
\n
\n
\n\"DevCentr\n
\n
Figure 2. DevCentr extension surface
\n
", + "html": "
\n

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.

\n
\n
\n

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.

\n
\n
\n

The 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.

\n
\n
\n

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).

\n
\n
\n

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.

\n
\n
\n

Docs: Ibex · emit CI how-to · releases.

\n
\n
\n
\n\"Ibex\n
\n
Figure 1. Idealized Ibex project UI
\n
\n
\n
\n\"DevCentr\n
\n
Figure 2. DevCentr extension surface
\n
", "source": "authored" }, {