Duolith docs

0161. The public name is Duolith

  • Status: Accepted (Mik, 18 Nov 2026); the rename below is done, apart from the repository's address on GitHub
  • Date: 2026-11-18
  • Decided by: Mik
  • Planning item: D1, D2

Context

Decision 0010 made "strata" a codename that must never reach a registry, and decision 0091 left every public name as a placeholder until Mik chose one. "strata" could not be kept: @strata and @stratajs on npm, the strata crate and github.com/strata belong to others, and a C UI framework and an MCP server already use the name.

Mik chose between two finalists on 18 Nov 2026, after rejecting descriptive compounds (NativePages), Astro blends (Nastro, because Astro is a trademark now owned by Cloudflare), and common English words (none is free as a bare npm name).

Decision

  1. The public name is Duolith: "two from one stone", one source that becomes a website and native apps. It is written Duolith in titles and duolith wherever a command, package or id needs one word.
  2. It was free on every channel checked on 18 Nov 2026: | Channel | Name | Result | | --- | --- | --- | | npm package | duolith | free | | npm scope | @duolith | free | | crates.io | duolith, duolith-cli | free | | GitHub | duolith | free | | Domains | duolith.dev, duolith.io | free (duolith.com is taken) | | Web search for a tool, product or company of the same name | | none found | Not checked: the VS Code Marketplace, Open VSX and JetBrains Marketplace publisher ids, and trademarks. A trademark search comes before the first publish.
  3. **The page-file extension is .duo.** Mik chose it over .duolith on 18 Nov 2026: a page is index.duo. It replaces the provisional .strata in the rename, together with the language id.
  4. **The command is duolith, and duo is a short name people add themselves.** On 19 Nov 2026 Mik chose duolith with duo as a short alias, and then, on learning that GitLab's Duo CLI (@gitlab/duo-cli) installs a duo command, chose to make it opt-in. Releases ship only duolith, and the docs, messages and generated files say duolith. The guide shows the one-line shell alias (projects.md), so nothing Duolith installs can take the place of another tool's command.
  5. Nothing is registered or published by this record. Registering the npm scope, the crate names, the GitHub organisation and the domains needs Mik's accounts, and decision 0091's dry run stays in force until he adds the publish job.

Needs Mik

  • Registering the names in his own accounts: the @duolith npm scope and the bare duolith package, the duolith and duolith-cli crates, the duolith GitHub organisation, and duolith.dev and duolith.io. Availability changes daily, so this is worth doing first.
  • The VS Code publisher and the extension's name. Recommended: publisher duolith, extension duolith-vscode, once the publisher id is confirmed free.
  • A trademark search before the first publish.

The rename

The rename is one change, as decision 0010 requires. Mik asked for it on 18 Nov 2026 and steps 1 to 4 are done; where they went beyond this list is under What the rename did.

  1. tools/release/release.yaml: product: duolith, display-name: Duolith, scope: "@duolith", the publisher and extension name, and the docs domain in place of docs.example.invalid.
  2. The uses of the codename that staging keeps today (listed by pnpm release:dry), together with the code that reads them: the language id, the page-file extension (.strata becomes .duo), the extension's setting and command ids, and the module names pages import from (@strata/client becomes @duolith/client).
  3. Crates strata-* to duolith-*, workspace packages @strata/* to @duolith/*, the strata command to duolith, strata.yaml to duolith.yaml, and diagnostics, docs, skills, packs, examples and generated files regenerated from spec/.
  4. tools/release/codename.ts and its --strict check are removed, since no codename is left to rewrite.
  5. The repository is renamed on GitHub (GitHub redirects the old address).

About 2,000 files mention the codename, so the change is mechanical but large, and it is verified by the full CI run and the conformance fixtures.

What the rename did

  • Language id and scopes. The language id is duolith (editors, the language server, code fences) and TextMate scopes end in .duolith; only the file extension is the short .duo.
  • Names that follow from the name. The hidden project folder is .duolith/, the output folder _duolith/, environment variables start DUOLITH_, and the development app ids are dev.duolith.*, after duolith.dev.
  • Grammar and highlighter packages. The placeholders of decision 0100 became @duolith/shiki, @duolith/highlightjs, @duolith/prism and tree-sitter-duolith (npm and crate), and the language's display name is Duolith.
  • Provisional, for Mik to confirm when he registers them: the VS Code publisher duolith and extension duolith-vscode, and the JetBrains plugin id dev.duolith.jetbrains with the vendor "Duolith contributors".
  • Not changed: the docs address duolith explain prints is still the reserved docs.example.invalid until the site has its address, and the repository's address on GitHub stays until Mik renames it (step 5).
  • Kept as history: decisions 0010 and 0091 and this record still say "strata" where they describe the codename. Every other record was rewritten with the rest of the repository, so its file names and commands match what a reader finds today.

Alternatives considered

OptionWhy not
Gemall (Mik's spelling of "gimmal", two linked rings)The other finalist. gemall on GitHub and gemall.io are taken, it can be read as "gem mall", and "gem" suggests Ruby gems or Gemini.
Keep "strata"Taken on npm, crates.io and GitHub, and already used by other developer tools.
NativePages and other descriptive compoundsFree everywhere, but Mik found them flat.
Nastro and other Astro blendsBuilt on a trademark in the same market.
Installing a duo command beside duolithIt is what Mik types, but GitLab's Duo CLI installs a command of the same name, and whichever came first on the search path would win. An alias a person adds is their own choice.
.duolith as the extensionNames the framework in full, as .astro and .svelte do, but Mik preferred the shorter .duo.
A common English word (Hoist, Spry, Cinch)No such word is free as a bare npm name, so each needs a js suffix on some channel.

Consequences

  • This record supersedes decision 0010's codename and its provisional .strata extension. Both stay in the repository until the rename.
  • .duo is short enough that another tool could claim it; editors pick a language by extension, so the editor shells must register it clearly.
  • Decision 0091's placeholders can be filled in, by the rename and not before.
  • Until the names are registered, someone else can still take them.