Oxygen colours, a Get started walkthrough, Create Identity (0.14.0) 013fefef11e3

# Bookmarks

Bookmarks are Oxygen's branches. Because changes commute, merging two bookmarks is the union of their changes: no merge change, and a real conflict is recorded where it is, to resolve whenever you like.

# Committing

The working copy is itself a change, snapshotted as you work. **Commit** turns it into a change with your message, signed when you push. Changes keep their identity across edits, moves and rewrites.

# History

The history graph shows each change in its lane: heads glow, the working copy breathes, and a ◈ marks a change sealed on push, ✔ one signed on its own.

# Your identity

Oxygen signs what you publish. `oxy identity create` makes a key pair for you (a classical and a post-quantum half, so a signature holds up later) and records you as the author of your changes.

The secret key stays in your key directory; the hub only ever sees the public half.

# Pushing

`oxy push` sends your changes, one seal over all of them, and a signed attestation moving the bookmark. The hub checks both against the repository's trust policy.

# A repository

An Oxygen repository is a set of **changes** that commute: independent work never needs a merge. **Clone** takes one from a hub (`oxy clone URL`); **Initialize** starts one in the open folder.

## 0.14.0 (2026-09-29)

- **Oxygen colours.** The history graph draws each lane in the Oxygen mark's palette. Heads glow, and the working copy breathes (it holds still if your system asks for reduced motion). ✔ marks a change signed on its own, ◈ one sealed on push, both coloured.

  - Every colour is themeable: `oxygen.lane1`…`oxygen.lane8`, `oxygen.head`, `oxygen.workingCopy`, `oxygen.signed`, `oxygen.sealed` and `oxygen.invalid`.

  - File letters use `oxygen.added`, `oxygen.modified`, `oxygen.removed`, `oxygen.renamed`, `oxygen.conflict` and `oxygen.resolved`. They default to Git's colours, so a theme can style Oxygen apart.

- **Get started with Oxygen.** A walkthrough on the Welcome page covers creating your identity, opening or cloning a repository, committing, bookmarks, pushing and the history. Each step ticks itself off as you do it.

- **Oxygen: Create Identity…** makes your signing identity (`oxy identity create`) without a terminal.

## Colours and getting started

The history graph and the file letters use Oxygen's own themeable colours: `oxygen.lane1`…`oxygen.lane8` for the graph's lanes, plus `oxygen.head`, `oxygen.workingCopy`, `oxygen.signed`, `oxygen.sealed`, `oxygen.invalid` and `oxygen.added`/`modified`/`removed`/`renamed`/`conflict`/`resolved`. Set them under `workbench.colorCustomizations`. **Get started with Oxygen**, on the Welcome page, walks through a first repository. **Oxygen: Create Identity…** makes your signing key.

  "version": "0.14.0",

      },

      {

        "command": "oxygen.createIdentity",

        "title": "Create Identity\u2026",

        "category": "Oxygen"

        }

      }

    },

    "colors": [

      {

        "id": "oxygen.lane1",

        "description": "History graph: lane 1 (the Oxygen mark's palette).",

        "defaults": {

          "dark": "#35C7FF",

          "light": "#0A74B8",

          "highContrast": "#35C7FF",

          "highContrastLight": "#0A74B8"

        }

      },

      {

        "id": "oxygen.lane2",

        "description": "History graph: lane 2 (the Oxygen mark's palette).",

        "defaults": {

          "dark": "#3D7BFF",

          "light": "#2553C9",

          "highContrast": "#3D7BFF",

          "highContrastLight": "#2553C9"

        }

      },

      {

        "id": "oxygen.lane3",

        "description": "History graph: lane 3 (the Oxygen mark's palette).",

        "defaults": {

          "dark": "#2BD9B3",

          "light": "#0E8A70",

          "highContrast": "#2BD9B3",

          "highContrastLight": "#0E8A70"

        }

      },

      {

        "id": "oxygen.lane4",

        "description": "History graph: lane 4 (the Oxygen mark's palette).",

        "defaults": {

          "dark": "#8E7CFF",

          "light": "#5B45D6",

          "highContrast": "#8E7CFF",

          "highContrastLight": "#5B45D6"

        }

      },

      {

        "id": "oxygen.lane5",

        "description": "History graph: lane 5 (the Oxygen mark's palette).",

        "defaults": {

          "dark": "#56A8FF",

          "light": "#1F6FC2",

          "highContrast": "#56A8FF",

          "highContrastLight": "#1F6FC2"

        }

      },

      {

        "id": "oxygen.lane6",

        "description": "History graph: lane 6 (the Oxygen mark's palette).",

        "defaults": {

          "dark": "#5FE3A1",

          "light": "#1A7850",

          "highContrast": "#5FE3A1",

          "highContrastLight": "#1A7850"

        }

      },

      {

        "id": "oxygen.lane7",

        "description": "History graph: lane 7 (the Oxygen mark's palette).",

        "defaults": {

          "dark": "#5B6CFF",

          "light": "#3440B8",

          "highContrast": "#5B6CFF",

          "highContrastLight": "#3440B8"

        }

      },

      {

        "id": "oxygen.lane8",

        "description": "History graph: lane 8 (the Oxygen mark's palette).",

        "defaults": {

          "dark": "#1FB6D6",

          "light": "#0B7C93",

          "highContrast": "#1FB6D6",

          "highContrastLight": "#0B7C93"

        }

      },

      {

        "id": "oxygen.head",

        "description": "A bookmark head in the history graph.",

        "defaults": {

          "dark": "#5FE3A1",

          "light": "#1A7850",

          "highContrast": "#5FE3A1",

          "highContrastLight": "#1A7850"

        }

      },

      {

        "id": "oxygen.workingCopy",

        "description": "The working copy in the history graph.",

        "defaults": {

          "dark": "#35C7FF",

          "light": "#0A74B8",

          "highContrast": "#35C7FF",

          "highContrastLight": "#0A74B8"

        }

      },

      {

        "id": "oxygen.signed",

        "description": "A change signed by its author.",

        "defaults": {

          "dark": "#5FE3A1",

          "light": "#1A7850",

          "highContrast": "#5FE3A1",

          "highContrastLight": "#1A7850"

        }

      },

      {

        "id": "oxygen.sealed",

        "description": "A change authenticated by a seal (one signature over a push).",

        "defaults": {

          "dark": "#8E7CFF",

          "light": "#6B3FD1",

          "highContrast": "#8E7CFF",

          "highContrastLight": "#6B3FD1"

        }

      },

      {

        "id": "oxygen.invalid",

        "description": "A signature that does not verify.",

        "defaults": {

          "dark": "#FF5E7A",

          "light": "#C62D47",

          "highContrast": "#FF5E7A",

          "highContrastLight": "#C62D47"

        }

      },

      {

        "id": "oxygen.added",

        "description": "A file the working copy adds. Defaults to Git's colour; themes can set Oxygen's apart.",

        "defaults": {

          "dark": "gitDecoration.addedResourceForeground",

          "light": "gitDecoration.addedResourceForeground",

          "highContrast": "gitDecoration.addedResourceForeground",

          "highContrastLight": "gitDecoration.addedResourceForeground"

      },

      {

        "id": "oxygen.modified",

        "description": "A file the working copy changes. Defaults to Git's colour; themes can set Oxygen's apart.",

        "defaults": {

          "dark": "gitDecoration.modifiedResourceForeground",

          "light": "gitDecoration.modifiedResourceForeground",

          "highContrast": "gitDecoration.modifiedResourceForeground",

          "highContrastLight": "gitDecoration.modifiedResourceForeground"

        }

      },

      {

        "id": "oxygen.removed",

        "description": "A file the working copy removes. Defaults to Git's colour; themes can set Oxygen's apart.",

        "defaults": {

          "dark": "gitDecoration.deletedResourceForeground",

          "light": "gitDecoration.deletedResourceForeground",

          "highContrast": "gitDecoration.deletedResourceForeground",

          "highContrastLight": "gitDecoration.deletedResourceForeground"

        }

      },

      {

        "id": "oxygen.renamed",

        "description": "A file the working copy moves. Defaults to Git's colour; themes can set Oxygen's apart.",

        "defaults": {

          "dark": "gitDecoration.renamedResourceForeground",

          "light": "gitDecoration.renamedResourceForeground",

          "highContrast": "gitDecoration.renamedResourceForeground",

          "highContrastLight": "gitDecoration.renamedResourceForeground"

        }

      },

      {

        "id": "oxygen.conflict",

        "description": "A file with a conflict, or conflict markers left in it. Defaults to Git's colour; themes can set Oxygen's apart.",

        "defaults": {

          "dark": "gitDecoration.conflictingResourceForeground",

          "light": "gitDecoration.conflictingResourceForeground",

          "highContrast": "gitDecoration.conflictingResourceForeground",

          "highContrastLight": "gitDecoration.conflictingResourceForeground"

        }

      },

      {

        "id": "oxygen.resolved",

        "description": "A conflict marked resolved. Defaults to Git's colour; themes can set Oxygen's apart.",

        "defaults": {

          "dark": "gitDecoration.stageModifiedResourceForeground",

          "light": "gitDecoration.stageModifiedResourceForeground",

          "highContrast": "gitDecoration.stageModifiedResourceForeground",

          "highContrastLight": "gitDecoration.stageModifiedResourceForeground"

        }

      }

    ],

    "walkthroughs": [

      {

        "id": "oxygen.gettingStarted",

        "title": "Get started with Oxygen",

        "description": "Sign, commit, branch without merges, push and see the history of an Oxygen repository.",

        "steps": [

          {

            "id": "oxygen.identity",

            "title": "Create your identity",

            "description": "Every change you make is signed with a composite key (Ed25519 and ML-DSA-65) that names you. Make it once; every repository uses it.\n[Create Identity](command:oxygen.createIdentity)",

            "media": {

              "markdown": "walkthrough/identity.md"

            },

            "completionEvents": [

              "onCommand:oxygen.createIdentity"

            ]

          },

          {

            "id": "oxygen.repository",

            "title": "Open or clone a repository",

            "description": "Clone one from your hub, start a new one here, or open a folder that already is one.\n[Clone Repository](command:oxygen.clone)\n[Initialize Repository](command:oxygen.init)",

            "media": {

              "markdown": "walkthrough/repository.md"

            },

            "completionEvents": [

              "onContext:oxygen.hasRepository"

            ]

          },

          {

            "id": "oxygen.commit",

            "title": "Commit a change",

            "description": "Edit a file, write a message in the Source Control box and press Ctrl+Enter. There is no staging area: the change is what you see.\n[Open Source Control](command:workbench.view.scm)",

            "media": {

              "markdown": "walkthrough/commit.md"

            },

            "completionEvents": [

              "onCommand:oxygen.commit"

            ]

          },

          {

            "id": "oxygen.bookmarks",

            "title": "Bookmarks: branches without merges",

            "description": "A bookmark names a state. Switch to a new one for a piece of work (take your edits along with *carry*), and merge it back: a merge is just the union of both, with no merge change.\n[Create Bookmark](command:oxygen.createBookmark)",

            "media": {

              "markdown": "walkthrough/bookmarks.md"

            },

            "completionEvents": [

              "onCommand:oxygen.createBookmark"

            ]

          },

          {

            "id": "oxygen.push",

            "title": "Push to your hub",

            "description": "Publish your bookmark. The push seals your new changes with one signature and moves the bookmark on the hub, which runs its OxygenFlow pipeline.\n[Push](command:oxygen.push)",

            "media": {

              "markdown": "walkthrough/push.md"

            },

            "completionEvents": [

              "onCommand:oxygen.push"

            ]

          },

          {

            "id": "oxygen.history",

            "title": "See the history",

            "description": "Changes form a graph, not a line: independent work runs in its own lane, in the Oxygen colours.\n[Show History](command:oxygen.showHistory)",

            "media": {

              "markdown": "walkthrough/history.md"

            },

            "completionEvents": [

              "onCommand:oxygen.showHistory"

            ]

          }

        ]

    ]

        return new vscode.FileDecoration("‼", "conflict", new vscode.ThemeColor("oxygen.conflict"));

          return new vscode.FileDecoration("•", "contains changes", new vscode.ThemeColor("oxygen.modified"));

        Added: ["A", "added", "oxygen.added"],

        Modified: ["M", "modified", "oxygen.modified"],

        Removed: ["D", "removed", "oxygen.removed"],

        Renamed: ["R", "renamed", "oxygen.renamed"],

        ModeChanged: ["X", "mode changed", "oxygen.modified"],

        ConflictEdited: ["‼", "conflict markers remain", "oxygen.conflict"],

        Resolved: ["✔", "conflict resolved", "oxygen.resolved"],

      const [badge, tooltip, color] = letters[entry.status] ?? ["?", entry.status, "oxygen.modified"];

    vscode.commands.registerCommand("oxygen.createIdentity", () => createIdentity()),

  }

}

/** Make a signing identity (oxy identity create): a composite key in your

 * user key directory, and the author every repository then signs with. */

async function createIdentity(): Promise<void> {

  const name = await vscode.window.showInputBox({ prompt: "Your name, as changes will show it", ignoreFocusOut: true, validateInput: (v) => (v.trim() ? undefined : "A name") });

  if (!name) {

    return;

  }

  const email = await vscode.window.showInputBox({ prompt: "Your email", ignoreFocusOut: true, validateInput: (v) => (/.+@.+/.test(v.trim()) ? undefined : "An email address") });

  if (!email) {

    return;

  }

  const home = process.env.HOME ?? process.cwd();

  const r = await oxy.run(home, ["--plain", "identity", "create", "--name", name.trim(), "--email", email.trim()]);

  if (r.code === 0) {

    vscode.window.showInformationMessage(`Oxygen: your identity is ready: ${name.trim()} <${email.trim()}>. Changes you commit and push are signed with it.`);

    for (const repo of repositories.values()) {

      void repo.refresh();

    }

  } else {

    vscode.window.showErrorMessage(`Oxygen: could not create an identity: ${r.stderr.trim() || r.stdout.toString("utf8").trim()}`);

      edges.push(`<path class="l${(lanes.get(d)! % 8) + 1}" d="M${x},${y} C${x},${y + rowH / 2} ${x2},${y2 - rowH / 2} ${x2},${y2}" />`);

    const lane = `l${(lanes.get(c.hash)! % 8) + 1}`;

    nodes.push(`<circle class="${cls} ${lane}" cx="${x}" cy="${y}" r="${c.head ? 6 : 5}" />`);

      const sig = c.working_copy ? "" : c.signature?.status === "signed" || c.signature?.status === "sealed" ? (c.signature.revoked ? "⚠" : c.signature.status === "sealed" ? "◈" : "✔") : c.signature?.status === "invalid" ? "✖" : "·";

      const sigClass = c.signature?.revoked ? "sig-revoked" : `sig-${c.signature?.status ?? "none"}`;

        <span class="meta">${escape(c.author)} · ${timeAgo(c.when_ms)} <span class="sig ${sigClass}" title="${escape(c.signature?.status ?? "")}">${sig}</span></span>

  /* Lanes in the Oxygen mark's colours (themeable: oxygen.lane1…8). */

  ${[1, 2, 3, 4, 5, 6, 7, 8].map((n) => `.l${n} { --lane: var(--vscode-oxygen-lane${n}); }`).join("\n  ")}

  svg path { fill: none; stroke: var(--lane); stroke-width: 1.6; opacity: .85; }

  svg circle.node { fill: var(--lane); }

  svg circle.head { fill: var(--vscode-oxygen-head); stroke: var(--vscode-editor-background); stroke-width: 1.5; filter: drop-shadow(0 0 3px var(--vscode-oxygen-head)); }

  svg circle.wc { fill: var(--vscode-oxygen-workingCopy); fill-opacity: .25; stroke: var(--vscode-oxygen-workingCopy); stroke-width: 2; transform-box: fill-box; transform-origin: center; animation: breathe 2.4s ease-in-out infinite; }

  @keyframes breathe { 0%, 100% { transform: scale(1); fill-opacity: .25; } 50% { transform: scale(1.25); fill-opacity: .55; } }

  @media (prefers-reduced-motion: reduce) { svg circle.wc { animation: none; } }

  h2::after { content: ""; flex: 1; height: 2px; margin-left: 6px; background: linear-gradient(90deg, var(--vscode-oxygen-lane1), var(--vscode-oxygen-lane2), transparent); border-radius: 1px; }

  .sig-signed { color: var(--vscode-oxygen-signed); }

  .sig-sealed { color: var(--vscode-oxygen-sealed); }

  .sig-invalid, .sig-revoked { color: var(--vscode-oxygen-invalid); }

  .row:not(.wc):hover .id { text-decoration: underline; }

  .id { color: var(--vscode-oxygen-lane1); font-family: var(--vscode-editor-font-family); }

  Added: "oxygen.added",

  Modified: "oxygen.modified",

  Removed: "oxygen.removed",

  Renamed: "oxygen.renamed",

  ModeChanged: "oxygen.modified",

  ConflictEdited: "oxygen.conflict",

  Resolved: "oxygen.resolved",