docs(newos4): per-OS clone guide (Linux, macOS, Windows, Termux, iOS)

Served at https://newos.webx11.duckdns.org/usage.html from docs/usage.html in this
repo, so the page, the mirror and the README share one source. Covers the four
failure modes that actually bite: CRLF on Windows (core.autocrlf), missing CA
bundles, cloning into /sdcard from Termux (FUSE has no POSIX permissions), and
the read-only 403 on push.

2 files changed, 206 insertions, 0 deletions

diff --git a/README.md b/README.md
index 6753b8f..eb8ef20 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,8 @@ deployment must change them (grep `webx11.duckdns.org`).
 git clone https://newos.webx11.duckdns.org/newos4.git
 ```
 
+Per-OS setup (Linux, macOS, Windows, **Android/Termux**, iOS): <https://newos.webx11.duckdns.org/usage.html>
+
 Read-only mirror: no account, no push. A running instance lives on the WebX11 platform at
 `https://webx11.duckdns.org/spaces/newos4/` (login required). History is preserved and sanitised —
 a few paths that existed in the source tree (`backups/`, `data/`, personal profiles) are absent by design.
diff --git a/docs/usage.html b/docs/usage.html
new file mode 100644
index 0000000..d8bb495
--- /dev/null
+++ b/docs/usage.html
@@ -0,0 +1,204 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Getting newOS4 — Linux, macOS, Windows, Termux</title>
+<meta name="description" content="How to clone the newOS4 repository on Linux, macOS, Windows and Android (Termux).">
+<style>
+  :root { --bg:#0b0d10; --panel:#14171c; --line:#252b34; --text:#e6e8ec; --dim:#9aa4b2; --accent:#8b9cf7; }
+  * { box-sizing: border-box; }
+  body { margin:0; background:var(--bg); color:var(--text);
+         font:16px/1.65 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif; }
+  .wrap { max-width: 860px; margin: 0 auto; padding: 32px 20px 72px; }
+  h1 { font-size: 1.7rem; margin: 0 0 6px; letter-spacing:-.02em; }
+  .lede { color: var(--dim); margin: 0 0 26px; }
+  h2 { font-size: 1.15rem; margin: 34px 0 10px; padding-bottom: 6px; border-bottom: 1px solid var(--line); }
+  h3 { font-size: 1rem; margin: 22px 0 6px; }
+  p, li { color: var(--text); }
+  a { color: var(--accent); }
+  code { font-family: ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; font-size: .88em;
+         background: #1b2027; padding: 1px 5px; border-radius: 4px; }
+  pre { background: var(--panel); border: 1px solid var(--line); border-radius: 10px;
+        padding: 14px 16px; overflow-x: auto; margin: 10px 0 4px; }
+  pre code { background: none; padding: 0; font-size: .86rem; line-height: 1.55; display: block; }
+  .panel { background: var(--panel); border: 1px solid var(--line); border-radius: 12px;
+           padding: 18px 20px; margin: 14px 0; }
+  .os { display:grid; gap:14px; }
+  .kv { display:grid; grid-template-columns: max-content 1fr; gap: 6px 18px; margin: 8px 0 0; font-size:.9rem; }
+  .kv dt { color: var(--dim); }
+  .kv dd { margin:0; }
+  .tag { font-size:.72rem; text-transform:uppercase; letter-spacing:.08em; color:var(--dim);
+         border:1px solid var(--line); border-radius:999px; padding:2px 9px; }
+  table { width:100%; border-collapse:collapse; margin-top:10px; font-size:.9rem; }
+  th, td { text-align:left; padding:7px 10px 7px 0; border-bottom:1px solid var(--line); vertical-align:top; }
+  th { color:var(--dim); font-weight:600; }
+  .warn { border-left:3px solid #d9a441; padding-left:14px; color:#e8d3a8; margin:12px 0; }
+  footer { margin-top:44px; padding-top:14px; border-top:1px solid var(--line); color:var(--dim); font-size:.85rem; }
+</style>
+</head>
+<body>
+<div class="wrap">
+
+<h1>Getting newOS4</h1>
+<p class="lede">One public, read-only repository. Clone it on Linux, macOS, Windows or Android — no account,
+no key, no token.</p>
+
+<div class="panel">
+  <pre><code>git clone https://newos.webx11.duckdns.org/newos4.git</code></pre>
+  <p style="margin:8px 0 0;color:var(--dim);font-size:.9rem">
+    One URL for every platform. <code>…/newos4</code> (without <code>.git</code>) also works — that is cgit's
+    dumb-HTTP path and it is slower; use the <code>.git</code> form.</p>
+</div>
+
+<table>
+  <tr><th>What you get</th><th></th></tr>
+  <tr><td>Contents</td><td>310 files, ~2.3 MB, full history (182 commits), MIT licence</td></tr>
+  <tr><td>Latest tag</td><td><code>v4.6.146</code> — <a href="/newos4/refs/">see refs</a></td></tr>
+  <tr><td>Writes</td><td>none. <code>git-receive-pack</code> answers 403; there is no SSH endpoint</td></tr>
+  <tr><td>Private data</td><td>stripped from every commit before publication — see <a href="/usage.html#scope">Scope</a></td></tr>
+  <tr><td>Reading it</td><td><a href="/about/">rendered README</a> · <a href="/newos4/tree/">file tree</a> · <a href="/newos4/log/">history</a></td></tr>
+</table>
+
+<h2 id="linux">Linux</h2>
+<div class="os">
+  <div>
+    <h3>Install git, if it is missing</h3>
+    <pre><code># Debian / Ubuntu / Mint
+sudo apt update &amp;&amp; sudo apt install -y git
+
+# Fedora / RHEL
+sudo dnf install -y git
+
+# Arch / Manjaro
+sudo pacman -S --noconfirm git
+
+# Alpine
+sudo apk add git</code></pre>
+  </div>
+  <div>
+    <h3>Clone and check</h3>
+    <pre><code>git --version                       # 2.30 or newer is fine
+git clone https://newos.webx11.duckdns.org/newos4.git
+cd newos4
+git log --oneline -3
+git describe --tags                 # v4.6.146</code></pre>
+  </div>
+</div>
+<p style="color:var(--dim);font-size:.9rem">A distro without CA roots fails with
+<code>SSL certificate problem</code>: install <code>ca-certificates</code>. Behind a proxy, add
+<code>git config --global http.proxy http://host:port</code>.</p>
+
+<h2 id="macos">macOS</h2>
+<pre><code>xcode-select --install      # ships git (Apple's build is older but sufficient)
+# or: brew install git
+
+git clone https://newos.webx11.duckdns.org/newos4.git
+cd newos4 &amp;&amp; git describe --tags</code></pre>
+<p style="color:var(--dim);font-size:.9rem">If <code>git</code> opens a licence prompt, run
+<code>sudo xcodebuild -license accept</code> once. The clone lands in your working directory; nothing is
+installed system-wide.</p>
+
+<h2 id="windows">Windows</h2>
+<pre><code>winget install --id Git.Git -e --source winget
+
+# new PowerShell window, then:
+git clone https://newos.webx11.duckdns.org/newos4.git
+cd newos4
+git log --oneline -3</code></pre>
+<div class="warn">
+  <strong>Set this before cloning on Windows:</strong>
+  <code>git config --global core.autocrlf false</code>. The repository is served from a Linux host — a CRLF
+  checkout silently rewrites every shell script and JS file, and they stop working when copied back. Linux
+  and macOS default to <code>false</code>; Windows installers default to <code>true</code>.
+</div>
+<p style="color:var(--dim);font-size:.9rem">Without winget: <a href="https://git-scm.com/download/win">git-scm.com/download/win</a>
+→ “Git for Windows” → next-next-finish → “Git Bash” gives you the same commands as above. WSL2 works too and
+needs no special handling.</p>
+
+<h2 id="android">Android — Termux</h2>
+<p>Termux is a real Linux userland, so the Linux instructions apply almost unchanged. Three things differ:</p>
+<div class="os">
+  <div>
+    <h3>1. Install git in Termux</h3>
+    <pre><code>pkg update &amp;&amp; pkg upgrade -y
+pkg install -y git ca-certificates
+git --version</code></pre>
+  </div>
+  <div>
+    <h3>2. Clone into Termux's own home, not shared storage</h3>
+    <pre><code>cd ~
+git clone https://newos.webx11.duckdns.org/newos4.git
+cd newos4
+git log --oneline -3</code></pre>
+    <div class="warn">
+      Do <em>not</em> clone into <code>/sdcard</code> or <code>~/storage/…</code>: that filesystem is
+      FUSE-mounted without POSIX permissions, and git dies with
+      <code>error: unable to write file … Permission denied</code> halfway through. Clone to
+      <code>~/newos4</code> and copy files out afterwards. If you need shared storage access at all, run
+      <code>termux-setup-storage</code> once and grant the prompt.
+    </div>
+  </div>
+  <div>
+    <h3>3. Keep the session alive for a big clone</h3>
+    <pre><code>termux-wake-lock          # stops Android from freezing the download
+git clone --depth 1 https://newos.webx11.duckdns.org/newos4.git
+termux-wake-unlock</code></pre>
+    <p style="color:var(--dim);font-size:.9rem;margin:6px 0 0">
+      <code>--depth 1</code> fetches the newest tree only — much faster on mobile data. You lose history;
+      re-clone without it later if you want the full 181 commits.</p>
+  </div>
+</div>
+<p style="color:var(--dim);font-size:.9rem">Editing on the phone: <code>pkg install nano</code> or
+<code>pkg install micro</code>, then <code>nano newos4/README.md</code>. Termux's own git is a standard build, so
+<code>git status</code>, <code>git diff</code> and <code>git log</code> behave exactly as on a laptop.</p>
+
+<h2 id="ios">iPhone / iPad</h2>
+<p><a href="https://holzschu.github.io/a-Shell_iOS/">a-Shell</a> (free) includes git: run the same
+<code>git clone</code> command. <a href="https://workingcopy.app/">Working Copy</a> is a GUI alternative that can
+also clone a public HTTPS repository without an account.</p>
+
+<h2 id="updating">Updating later</h2>
+<pre><code>cd newos4
+git pull --ff-only          # the mirror only ever fast-forwards
+git describe --tags         # new tag appears when a release is published</code></pre>
+<p style="color:var(--dim);font-size:.9rem">The mirror is refreshed daily at 05:50 UTC and a new release tag is
+minted on each publish. Nothing you do locally can be pushed back — see below.</p>
+
+<h2 id="verify">Verifying what you got</h2>
+<pre><code>git -C newos4 rev-parse --short HEAD      # tip commit
+git -C newos4 tag -l                      # v4.6.146
+git -C newos4 ls-files | wc -l            # 310
+du -sh newos4/.git                       # ~2.3 MB</code></pre>
+
+<h2 id="scope">Scope, and why you cannot push</h2>
+<p>The mirror is generated from a private monorepo by
+<code>admin/scripts/publish-newos4.py</code>: it keeps only the <code>spaces/newos4</code> subtree, removes
+private paths (<code>data/</code>, <code>backups/</code>, <code>.hermes/</code>, credentials, profile JSON) from
+<strong>every commit</strong>, and scans all blobs for secrets before anything is pushed. That is why the history
+starts where it does: earlier private commits were never published.</p>
+<p>Pushing is disabled at three levels — no <code>git-receive-pack</code> route on the vhost, <code>403</code> on
+the advertisement, and <code>http.receivepack=false</code> in the repository. If you want to report a bug or ask
+for a change, email <a href="mailto:darkmotox11@gmail.com">darkmotox11@gmail.com</a>; do not send patches to a
+repository that cannot accept them.</p>
+
+<h2 id="trouble">Troubleshooting</h2>
+<table>
+  <tr><th>Symptom</th><th>Cause and fix</th></tr>
+  <tr><td><code>Repository not found</code></td><td>Wrong URL. Use <code>https://newos.webx11.duckdns.org/newos4.git</code> — the host is <code>newos.</code>, not <code>git.</code></td></tr>
+  <tr><td><code>SSL certificate problem</code></td><td>Missing CA bundle → <code>apt install ca-certificates</code> / <code>pkg install ca-certificates</code></td></tr>
+  <tr><td><code>Could not resolve host</code></td><td>Offline, or a corporate DNS that drops wildcard subdomains</td></tr>
+  <tr><td><code>403</code> on <code>git push</code></td><td>Expected — the mirror is read-only by design</td></tr>
+  <tr><td>Clone stalls on mobile</td><td><code>git clone --depth 1</code>, and <code>termux-wake-lock</code> on Android</td></tr>
+  <tr><td>Scripts arrive with CRLF</td><td><code>git config --global core.autocrlf false</code>, then re-clone</td></tr>
+</table>
+
+<footer>
+  Served from the same repository it documents ·
+  Source: <a href="/newos4/tree/docs/usage.html">docs/usage.html</a> ·
+  <a href="/about/">README</a> · MIT licence · updated 2026-11-05
+</footer>
+
+</div>
+</body>
+</html>