{% 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="#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>Then link your identity again under Settings › Keys, so the hub sees the delegation. 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="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 %}