-
Notifications
You must be signed in to change notification settings - Fork 0
release: 0.0.38 with accurate Windows first-run documentation #57
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -204,13 +204,19 @@ not consume half of the visible screen. | |
| - **Workflows** — recurring resident work, next run, pause/resume, run counts, | ||
| and failures. | ||
| - **Connections** — native host-brokered Gmail and Photon configuration. | ||
| - **Notifications** — per-account global mute and mobile notification opt-in. | ||
| - **Feedback** — send a comment and optional attachments to the 1Helm team, | ||
| with privacy-bounded diagnostics included only if you check that option. | ||
| - **Audit** — retained events and hash-chain verification. | ||
| - **Domains** — local-first collaboration and optional Cloudflare domain. | ||
| - **Providers** — accounts, keys, models, routes, quotas, logs, and endpoint. | ||
| - **Skipper computers** — optional Captain-owned computers for authorized | ||
| Skipper work; these never replace resident Linux computers. | ||
| - **Members** — coworkers, access requests, and invitations. | ||
|
|
||
| Those sections are the Captain/admin view. A signed-in member who is not an | ||
| administrator sees only **Providers** and **Notifications**. | ||
|
|
||
| ## Providers, models, and routes | ||
|
|
||
| Accounts and keys form one fabric. Connect multiple ChatGPT, Claude, | ||
|
|
@@ -377,14 +383,17 @@ Source/developer deployments report that their host operator owns updates. | |
| Every host update preserves: | ||
|
|
||
| ```text | ||
| ~/Library/Application Support/1Helm-OCI-v1 | ||
| macOS: ~/Library/Application Support/1Helm-OCI-v1 | ||
| Linux: /var/lib/1helm-oci-v1 | ||
| Windows: %APPDATA%\1Helm-OCI-v1 (plus %LOCALAPPDATA%\1Helm-Runtime) | ||
| ``` | ||
|
|
||
| On macOS that directory contains databases, credentials, workspaces, resident | ||
| state, and Apple mirrors. Linux preserves the equivalent OCI-generation state | ||
| under `/var/lib/1helm-oci-v1`. The retired data roots remain untouched and are | ||
| not imported by this generation. Do not delete either current data root during | ||
| replacement. | ||
| state, and Apple mirrors. Linux and Windows preserve the equivalent | ||
| OCI-generation state; on Windows the shared WSL runtime disk lives separately | ||
| under `%LOCALAPPDATA%\1Helm-Runtime`. The retired data roots remain untouched | ||
| and are not imported by this generation. Do not delete a current data root | ||
| during replacement. | ||
|
|
||
| Before removing 1Helm, use its removal preparation flow. It is Captain-only, | ||
| requires typed confirmation, reports backend-owned resident machines, and | ||
|
|
@@ -403,6 +412,47 @@ Recovery principles: | |
|
|
||
| ## Troubleshooting | ||
|
|
||
| ### First run and installation | ||
|
|
||
| **Windows asks me to restart in the middle of setup.** That is the expected | ||
| path on a normal Windows 11 PC. WSL and VirtualMachinePlatform ship disabled; | ||
| 1Helm turns them on for you, and Windows cannot use them until it restarts. | ||
| Restart, sign back in as the same Windows user, open 1Helm, and continue — | ||
| completed steps are skipped. Nothing is lost and nothing else is required. | ||
|
|
||
| **Windows says "Windows protected your PC" when I run Setup.** Windows Setup is | ||
| not yet Authenticode signed, so SmartScreen warns about it. Choose **More info** | ||
| → **Run anyway**. Every release discloses its Authenticode status; v0.0.38 is | ||
| `NotSigned`. Only run an installer you downloaded from | ||
| [1helm.com](https://1helm.com/download/windows) or the project's GitHub | ||
| releases. | ||
|
|
||
| **A PowerShell window opened during Windows setup.** That window is the setup | ||
| itself and shows live progress. Leave it open until it finishes; closing it | ||
| early aborts the step. 1Helm mirrors the same progress in the app and writes a | ||
| log to `%APPDATA%\1Helm-OCI-v1\windows-wsl-setup.log`. | ||
|
|
||
| **Windows setup failed or stalled.** Check the PowerShell window for the error, | ||
| then use **Retry shared runtime setup** in onboarding or Settings → Channel | ||
| computers. Setup is idempotent — retrying resumes rather than starting over. | ||
| The runtime requires Windows 11 **x64**; arm64 Windows is not supported by this | ||
| build. | ||
|
Comment on lines
+435
to
+439
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- USER_GUIDE.md around the reported section ---'
sed -n '390,455p' docs/USER_GUIDE.md
printf '%s\n' '--- Settings label references ---'
rg -n -i -C 3 'Skipper computers|Channel computers|Retry shared runtime setup|shared runtime setup|Settings.*computers|computers.*Settings' . \
-g '!node_modules' -g '!dist' -g '!build'Repository: gitcommit90/1Helm Length of output: 50373 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- Settings navigation and section rendering ---'
sed -n '70,100p' src/client/settings.ts
sed -n '620,755p' src/client/settings.ts
printf '%s\n' '--- Retry-related settings labels and handlers ---'
rg -n -C 5 'Retry shared runtime setup|retry.*runtime|runtime.*retry|Channel computers' src/client/settings.ts src/client/onboarding.ts test
printf '%s\n' '--- Documentation index and computer section ---'
sed -n '195,220p' docs/USER_GUIDE.md
sed -n '330,348p' docs/USER_GUIDE.md
printf '%s\n' '--- Read-only label consistency check ---'
python3 - <<'PY'
from pathlib import Path
p = Path("src/client/settings.ts").read_text()
for label in ("Skipper computers", "Channel computers", "Retry shared runtime setup"):
print(f"{label!r}: {p.count(label)} occurrence(s)")
print("tab declaration:", '[["computers", "Skipper computers"]]' in p)
print("channel heading:", 'font-semibold text-fg" }, "Channel computers"' in p)
print("settings retry label:", "Retry shared runtime setup" in p)
PYRepository: gitcommit90/1Helm Length of output: 22900 Use the actual Settings path and action label. The sidebar label is Skipper computers. Inside it, the runtime panel is Channel computers, and the Windows button is Set up shared runtime, not Retry shared runtime setup. Update this step to match the UI. 🤖 Prompt for AI Agents |
||
|
|
||
| **macOS blocks the app or reports it is damaged.** The Mac release is Developer | ||
| ID signed, notarized, and stapled, so Gatekeeper should accept it after you | ||
| drag it to Applications. If it does not, you are almost certainly running a | ||
| partially downloaded or re-hosted copy — download the DMG again from | ||
| [1helm.com](https://1helm.com/download/macos). Do not strip quarantine | ||
| attributes or re-sign an ad-hoc build to work around a failed verification. | ||
|
Comment on lines
+441
to
+446
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win Do not attribute every Gatekeeper failure to a bad download. Gatekeeper can reject a complete official artifact for signing, notarization, policy, or system-state reasons. Replace “almost certainly” with neutral diagnostic guidance. Keep re-downloading as one troubleshooting step, and provide a support or verification path if the failure persists. Proposed wording-If it does not, you are almost certainly running a
-partially downloaded or re-hosted copy — download the DMG again from
+If it does not, verify the download source and download the DMG again from
[1helm.com](https://1helm.com/download/macos). If the failure persists,
+contact support instead of bypassing verification.🤖 Prompt for AI Agents |
||
|
|
||
| **The Linux installer refuses to run.** It requires root, a running systemd | ||
| host, `apt`, cgroup v2, and an x86-64 or arm64 CPU, and it installs Podman | ||
| rather than Docker. The error names the missing prerequisite. Follow the | ||
| [Linux install guide](https://1helm.com/manual/install-linux); check progress | ||
| with `sudo systemctl status 1helm` and `sudo journalctl -u 1helm -f`. | ||
|
|
||
| ### In the app | ||
|
|
||
| **A button highlights but Continue does nothing.** Ensure every visible question | ||
| has one selected option or typed answer. If it still fails, capture the thread | ||
| and app version; selection and the submitted answer should survive live repaints. | ||
|
|
@@ -445,7 +495,7 @@ fallback. | |
| - Operational history is locally tamper-evident. | ||
| - Mac artifacts are Developer ID signed, notarized, stapled, and Gatekeeper | ||
| verified. Linux assets are digest-verified, and Windows Authenticode status | ||
| is disclosed for every release (`NotSigned` for v0.0.31). | ||
| is disclosed for every release (`NotSigned` for v0.0.38). | ||
|
|
||
| For the detailed boundary, see [SECURITY.md](../SECURITY.md). For product intent, | ||
| see [VISION.md](VISION.md). | ||
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,7 @@ | ||
| { | ||
| "name": "1helm", | ||
| "productName": "1Helm", | ||
| "version": "0.0.37", | ||
| "version": "0.0.38", | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "package.json version:"
python3 -c 'import json; print(json.load(open("package.json", encoding="utf-8"))["version"])'
echo "Website fallback release and digest references:"
rg -n -C 8 'fallback|release|artifact|digest|sha256|0\.0\.' site/server.mjsRepository: gitcommit90/1Helm Length of output: 8059 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "Relevant package metadata and scripts:"
sed -n '1,140p' package.json
echo "Release fallback references:"
rg -n -C 4 'RELEASE_FALLBACK|SITE_RELEASE_FETCH_DISABLED|SITE_RELEASE_METADATA_JSON|latestLinuxRelease|0\.0\.30|0\.0\.38' site test* .github 2>/dev/null || true
echo "Changed-file summary:"
git diff --statRepository: gitcommit90/1Helm Length of output: 37716 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "Website release routes and fallback test:"
sed -n '80,125p' test/site.mjs
sed -n '330,430p' site/server.mjs
echo "All release metadata consumers:"
rg -n -C 3 'latestAssetUrl|latestReleaseAssets|RELEASE_PAGE|/download/|sha256|digest' site/server.mjs test/site.mjs site/public/install.sh
echo "Standalone fallback invariant check:"
python3 - <<'PY'
import json, re
from pathlib import Path
package_version = json.loads(Path("package.json").read_text())["version"]
source = Path("site/server.mjs").read_text()
tag = re.search(r'tag_name:\s*"v([^"]+)"', source).group(1)
names = re.findall(r'\["([^"]+)",\s*"([0-9a-f]{64})"\]', source)
urls = re.findall(r'releases/download/v([^/]+)/\$\{name\}', source)
print({"package_version": package_version, "fallback_version": tag})
print("fallback_asset_versions:", sorted(set(re.findall(r"1Helm-([0-9]+\.[0-9]+\.[0-9]+)-", "\n".join(n for n, _ in names)))))
print("fallback_url_versions:", sorted(set(urls)))
print("version_matches:", package_version == tag)
PYRepository: gitcommit90/1Helm Length of output: 24005 Update the website fallback metadata before publishing When GitHub release fetching fails, 🤖 Prompt for AI Agents |
||
| "private": true, | ||
| "type": "module", | ||
| "license": "AGPL-3.0-only", | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Correct the Windows feature sentence.
Line 139 says
1Helm enables both itself. State the object explicitly.Proposed fix
📝 Committable suggestion
🧰 Tools
🪛 LanguageTool
[grammar] ~139-~139: Ensure spelling is correct
Context: ... VirtualMachinePlatform turned off, and 1Helm enables both itself: - Approve the o...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Source: Linters/SAST tools