{% extends "base.html" %}

{% block title %}Help{% endblock %}

{% block content %}

<div class="head"><h1>Help <small>using {{ shell.site }}</small></h1></div>

<div class="sectioned help">

<nav class="section-nav" aria-label="Sections">

  <a href="#start">Getting started</a>

  <a href="#identity">Your identity</a>

  <a href="#push">Pushing</a>

  <a href="#clone">Cloning</a>

  <a href="#proposals">Proposals</a>

  <a href="#delegate">Letting the hub act for you</a>

  <a href="#agents">AI identities</a>

  <a href="#flow">Pipelines</a>

  <a href="#keys">Keyboard</a>

  <a href="#backups">Backups</a>

  <a href="#glossary">Coming from GitHub</a>

</nav>

<div class="sections">

<section class="panel" id="start">

  <h2>Getting started</h2>

  <p>{{ shell.site }} hosts <strong>Oxygen</strong> repositories. You work with them through <code>oxy</code>, the Oxygen client; the hub shows them, reviews them and runs their pipelines. Every command below is filled in for this hub.</p>

  <ol>

    <li>Install <code>oxy</code>: build it from the <code>oxygen</code> repository with <code>cargo build --release</code> and put <code>target/release/oxy</code> on your path.</li>

    <li>Say who you are and make a signing identity (next section).</li>

    <li>{% if shell.user.is_some() %}Create a <a href="/settings/tokens">personal access token</a>{% else %}<a href="/register">Register</a>, then create a personal access token under Settings › Tokens{% endif %} with <code>repo:write</code>. It is shown once; keep it in <code>oxy</code>'s configuration, not in scripts.</li>

    <li>{% if shell.user.is_some() %}<a href="/new">Create a repository</a>{% else %}Create a repository with <strong>+ NEW</strong>{% endif %} and push to it (below). An empty repository shows the same commands, with its own address.</li>

  </ol>

  <p class="small mute"><code>oxy doctor</code> checks your identity, configuration and remotes, and says what to do about any problem.</p>

</section>

<section class="panel" id="identity">

  <h2>Your identity</h2>

  <p>Oxygen changes are signed. Your identity is a key pair (Ed25519 with ML-DSA-65) kept under <code>~/.config/oxy</code>; the public part travels with your changes.</p>

  {% let cmd = "oxy config --user author.name \"Your Name\"\noxy config --user author.email [email protected]\noxy identity create\noxy config --user core.sign change" %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>Link the key to your account under {% if shell.user.is_some() %}<a href="/settings/keys">Settings › Keys</a>{% else %}Settings › Keys{% endif %}: the page gives you a challenge to sign with <code>oxy identity sign-challenge</code>, which proves you hold the key. Linked keys show on your profile, and the hub can then tell which signed changes are yours.</p>

</section>

<section class="panel" id="push">

  <h2>Pushing</h2>

  {% let ca = self.ca_setup() %}

  {% if !ca.is_empty() %}

  <p>This hub uses a self-signed certificate. Save it once, and point each remote at it:</p>

  <div class="cmds"><pre><code>{{ ca }}</code></pre><button class="small" data-copy="{{ ca }}">copy</button></div>

  {% endif %}

  <p>From a checkout, add the repository as a remote, give it your token, and push:</p>

  {% let cmd = q.connect(self.repo_url().as_str()) %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>An empty repository takes its identity from the first push, so every later clone shares it. <code>oxy push {{ q.remote }}</code> sends the current bookmark; <code>oxy push {{ q.remote }} --bookmark NAME</code> another one. Tags travel with pushes.</p>

  <p class="small mute">A Git history comes across with <code>oxy git import --branch main path/to/git-checkout NAME</code>: every commit becomes a change, and the result can be pushed like any other repository.</p>

</section>

<section class="panel" id="clone">

  <h2>Cloning</h2>

  {% let cmd = self.clone_cmd() %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>Public repositories clone without a token. For private ones, and to push back, set <code>oxy config remote.origin.token YOUR-TOKEN</code>{% if q.ca_url.is_some() %} and <code>oxy config remote.origin.ca {{ q.ca_file }}</code>{% endif %} in the clone. <code>oxy pull origin</code> brings in what others pushed; there is no merge commit, because Oxygen changes combine by themselves.</p>

</section>

<section class="panel" id="proposals">

  <h2>Proposals</h2>

  <p>A proposal asks for a bookmark's changes to be added to another bookmark, like a pull request. Push your bookmark, then open one from the repository's Proposals tab, from the compare page's <strong>Propose this</strong>, or from a fork.</p>

  <ul>

    <li>A proposal is always tested and reviewed on its <strong>projected state</strong>: exactly what the target will hold once it lands. It never goes stale, and there is nothing to rebase.</li>

    <li>Review comments are anchored to lines' atoms, so they stay on the right line through later pushes.</li>

    <li>An approval can be a <strong>seal</strong>: your signature over the proposal's changes (<code>oxy seal</code>), which anyone can check offline.</li>

    <li>Land from the page, or from a client with <code>oxy proposal land URL</code>, which signs the landing with your own key.</li>

    <li>Where the site, an organisation or a repository has set up <strong>AI assistants</strong> (Settings), you can ask one to review under Reviewers, or have it draft the description; its answer is recorded as yours <em>via</em> the assistant, with an <span class="tag">agent</span> badge. Only people approve.</li>

  </ul>

</section>

<section class="panel" id="wiki">

  <h2>Wiki</h2>

  <p>A repository's wiki is Markdown pages kept as an Oxygen repository of their own: edit them under the <strong>Wiki</strong> tab (every edit is a signed change, so it needs the same delegation as editing code), or clone and push them as <code>oxy clone {{ shell.base_url }}/OWNER/NAME.wiki</code>. Pages are <code>Name.md</code> on <code>main</code>; <code>_Sidebar.md</code> is the sidebar; link between pages with <code>[Other](Other)</code>.</p>

</section>

<section class="panel" id="delegate">

  <h2>Letting the hub act for you</h2>

  <p>Edits in the browser and landings from the proposal page are changes too, and they must be signed. The hub signs them as your <strong>delegate</strong>, only if you allow it. Allowing it is a one-off step:</p>

  {% let cmd = self.delegate_cmd() %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>That makes a new version of your identity: export it in the same checkout (<code>oxy identity export</code>) and upload that file under Settings › Keys, signing the challenge there too, so the hub sees the delegation. The hub's key file is not the one to upload. You can withdraw it at any time with <code>oxy identity delegate remove</code>; a repository's trust policy still decides whether a delegated change may update a bookmark.</p>

</section>

<section class="panel" id="agents">

  <h2>AI identities</h2>

  <p>An AI agent (a coding assistant, a bot) can work on your repositories in its own name and in yours: its changes are signed, they say which agent made them, and you decide what it may do and for how long. Nothing it is given is a password or a key of yours.</p>

  <h3>Keyless agents (recommended)</h3>

  <p>A keyless agent holds no key at all. You give it a <strong>grant</strong>: a token your own key signs, valid for a time you choose. Whenever the agent signs, it makes a fresh key, the hub certifies it for ten minutes under your grant, and the key is thrown away; a stolen home holds nothing that signs by itself.</p>

  <p>On your side, name the agent and how long it may act for you (the token is printed once):</p>

  {% let cmd = "oh agent grant claude --for 30d --scope changes,seal,refs" %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>Give the agent its own oxy home (never your own), and keep the token there; it is read from standard input, so it stays out of the shell's history:</p>

  {% let cmd = self.agent_home_cmd() %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>The agent then commits and pushes with <code>OXY_HOME</code> set to its home. Its changes are authored as you and sealed <code>via agent:claude@{{ who }}</code>, which history, proposals and your profile show. <code>oh agent list</code> shows your grants; <code>oh agent revoke ID</code> ends one at once, and a grant ends by itself when its time is up.</p>

  <h3>Where it may push</h3>

  <p>A repository with a trust policy accepts an agent's work only if the policy names it. Grant the agent's subject, with this hub as the issuer, from a checkout of the repository:</p>

  {% let cmd = self.subject_grant_cmd() %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>A repository without a policy takes any signed change its token may push.</p>

  <h3>Agents with a key of their own</h3>

  <p>An agent that keeps its own identity acts for you through a <strong>delegation</strong>: from your checkout, <code>oxy identity delegate add agent.identity --scope changes --expires 7d</code>, then link your identity again under {% if shell.user.is_some() %}<a href="/settings/keys">Settings › Keys</a>{% else %}Settings › Keys{% endif %}. <code>oxy identity delegate remove KEY</code> withdraws it. Keyless grants are simpler and leave nothing behind.</p>

  <h3>Tokens, notifications and gates</h3>

  <ul>

    <li>A personal access token an agent uses can be marked <strong>agent</strong> under {% if shell.user.is_some() %}<a href="/settings/tokens">Settings › Tokens</a>{% else %}Settings › Tokens{% endif %}: proposals it opens and comments it makes reach your inbox and email like anyone else's.</li>

    <li>An approval gate is for a person: an agent's token cannot approve or reject one unless a repository's maintainers allow it under Settings › Gates & agents, and each decision still says which agent made it.</li>

    <li>Commits whose message says a skip marker (<code>[skip flow]</code>) start no pipeline run; agents should leave them out unless asked.</li>

  </ul>

</section>

<section class="panel" id="flow">

  <h2>Pipelines</h2>

  <p>Pipelines run in <strong>OxygenFlow</strong>. Put a pipeline in <code>.flow/pipeline.kdl</code> and push: each job runs in its own microVM with no network, and its result shows on the repository's Flow tab and as a check named <code>flow/JOB</code> on proposals. A site administrator enables Flow for a repository.</p>

  <p>Instead of a badge, a README can carry a <strong>state stamp</strong>:</p>

  {% let cmd = "[![flow](.flow/stamp)](.flow/run)" %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>It shows the result for the state you are looking at (a tag shows the tag's result), names that state, and carries each job's receipt hash.</p>

</section>

<section class="panel" id="keys">

  <h2>Keyboard</h2>

  <table class="list">

    <tbody>

      <tr><td><kbd>/</kbd></td><td>Search</td></tr>

      <tr><td><kbd>g</kbd> <kbd>c</kbd></td><td>The repository's code</td></tr>

      <tr><td><kbd>g</kbd> <kbd>h</kbd></td><td>History of the bookmark you are on</td></tr>

      <tr><td><kbd>g</kbd> <kbd>p</kbd></td><td>Proposals</td></tr>

      <tr><td><kbd>g</kbd> <kbd>i</kbd></td><td>Issues</td></tr>

      <tr><td><kbd>g</kbd> <kbd>b</kbd></td><td>Bookmarks</td></tr>

      <tr><td><kbd>g</kbd> <kbd>t</kbd></td><td>Trust</td></tr>

      <tr><td><kbd>y</kbd></td><td>Replace the address with a permalink to this exact state (files and trees)</td></tr>

      <tr><td>click a line number, <kbd>Shift</kbd>-click another</td><td>Select lines; copy them or a permalink to them</td></tr>

      <tr><td><kbd>?</kbd></td><td>The keyboard sheet</td></tr>

    </tbody>

  </table>

</section>

<section class="panel" id="backups">

  <h2>Backups</h2>

  <p>Under Settings › Backups (or an organisation's settings) you choose where your repositories are copied and how often. Each run copies every repository you own, its wiki, issues, proposals, releases and settings, but never a secret value. Only what changed travels, and every kept run can be restored with <code>oxygenhub admin backup restore</code>.</p>

  <p>A Google Cloud Storage bucket needs no key: the hub signs in as <code>backup:YOU</code> with a token it issues itself, which Google trusts through workload identity federation. Once per project, create a pool and an OIDC provider whose issuer is this hub's address; once per bucket, grant <code>roles/storage.objectAdmin</code> to the principal <code>…/subject/backup:YOU</code>. The exact commands are in the hub's <code>docs/backups.md</code> §6.</p>

</section>

<section class="panel" id="glossary">

  <h2>Coming from GitHub</h2>

  <table class="list glossary">

    <thead><tr><th>GitHub</th><th>Here</th><th>What is different</th></tr></thead>

    <tbody>

      <tr><td>commit</td><td><strong>change</strong></td><td>A change records edits, not a snapshot, and names the changes it depends on. Changes that do not touch the same lines combine in any order with the same result, so there are no merge commits. A change keeps its identity when it is rebased or squashed.</td></tr>

      <tr><td>commit SHA, tree</td><td><strong>state</strong></td><td>The files a set of changes makes. A state is addressed by its heads (<code>a1b2…+c3d4…</code>); checks, stamps and permalinks belong to states.</td></tr>

      <tr><td>branch</td><td><strong>bookmark</strong></td><td>A name for a state. It can have several <strong>heads</strong> (changes nothing else depends on); the tree is their union, not a conflict.</td></tr>

      <tr><td>tag</td><td><strong>tag</strong></td><td>An immutable named state, usually signed.</td></tr>

      <tr><td>merge, rebase</td><td><code>oxy merge</code>, <code>oxy pull</code></td><td>Uniting bookmarks adds the other side's changes. Nothing is rewritten and no merge change is made.</td></tr>

      <tr><td>merge conflict</td><td><strong>conflict</strong> in the state</td><td>A conflict is recorded in the history instead of blocking you. It stays visible (the Conflicts tab) until a change resolves it, and anyone can resolve it later.</td></tr>

      <tr><td>pull request</td><td><strong>proposal</strong></td><td>Reviewed and tested on its projected state. It cannot go stale, and approvals can be signed seals.</td></tr>

      <tr><td>branch protection</td><td><strong>trust policy</strong></td><td>Signed rules in the repository itself: who may move which bookmark, with how many signatures. Every client enforces them, not only the hub.</td></tr>

      <tr><td>Actions, CI badge</td><td><strong>OxygenFlow</strong>, state stamp</td><td>Jobs run in microVMs on exact states; results are receipts, and the stamp says which state they belong to.</td></tr>

      <tr><td>git submodule</td><td><strong>subrepo</strong></td><td>Another Oxygen repository pinned at a path by its heads, listed in <code>.oxymodules</code>. The pin is a change like any other, so bumping it combines with your other work instead of conflicting with it.</td></tr>

      <tr><td>Renovate, Dependabot</td><td><strong>Diffusion</strong></td><td>Built into the hub, not a bot you install. When a subrepo you pin moves on its default bookmark, the hub works out the bump, runs your checks on it and opens a proposal labelled <code>dependencies</code> with the upstream's changelog. Choose per repository under Settings › Diffusion (when the upstream is green, on every move, or off), or per subrepo in <code>.oxymodules</code>; it never lands anything for you. The Diffusion tab shows both directions: what you pin, and who pins you.</td></tr>

      <tr><td>git blame</td><td><strong>blame</strong></td><td>Exact through rebases and squashes: each line is an atom with one authoring change, so there is no "ignore revisions" file.</td></tr>

      <tr><td>fork</td><td><strong>fork</strong></td><td>A copy under your name with its own identity and bookmarks, sharing the stored objects. Its proposals go upstream as <code>you/name:bookmark</code>; the upstream's trust policy is not copied.</td></tr>

      <tr><td>personal access token</td><td><strong>token</strong></td><td>For pushing and the API. Your signing key is what proves authorship; a token only authorises.</td></tr>

    </tbody>

  </table>

</section>

</div>

</div>

{% endblock %}