TylerandClaude Fable 5
0f966a5fd0
Template tests / tests (pull_request) Failing after 1m26s
Phase 0 of the improvement plan (ai_prompts/prompt4.md): make the baseline reproducible and stop the test runner from masking real failures. - Pin Node >= 22.12 (engines + .nvmrc + engine-strict); every entry point fails fast with clear guidance instead of dying late with ERR_REQUIRE_ESM inside the packaging dependency graph. - electron-launcher.js is diagnostics-only: all runtime npm install/rebuild/ repair paths are removed. npm ci on the pinned toolchain is the only supported install path (README + GETTING_STARTED updated). - Refuse to silently launch unsandboxed on Linux: --no-sandbox now requires an explicit STEPFORGE_ALLOW_NO_SANDBOX/ELECTRON_DISABLE_SANDBOX opt-in and is otherwise a hard error with actionable fixes; user-namespace sandboxing is detected and preferred. - Click-capture E2E no longer converts startup crashes into "SKIPPED": the only allowed skip is the upfront absence of a display server. A missing shared library or crash now fails with the startup log. Same guard added to the startup smoke check. - GitHub CI: run on pull_request, pin Node from .nvmrc, drop the macOS matrix entry (not a support target), and audit production and full dependency trees as separate signals. Gitea CI: pull_request trigger + pinned Node. - Refresh package-lock on Node 22/npm 10 and remediate the form-data and undici advisories (npm audit: 0 vulnerabilities, prod and full tree). - Stop tracking generated machine-specific build reports (build/build_report.md, build/artifacts_manifest.json). Verified: 203 unit tests pass; repo-structure, startup-smoke, unit-workflows, sample-artifacts, and build-release checks pass locally with a real Electron launch. The click self-test now truthfully reports the pre-existing Linux arm/debounce capture failures (also red on Gitea CI main run 177) instead of hiding behind SKIPPED; that defect is scheduled for the capture-fix PR. Co-Authored-By: Claude Fable 5 <[email protected]>
106 lines
2.9 KiB
Markdown
106 lines
2.9 KiB
Markdown
# Getting Started
|
|
|
|
StepForge is a fully offline desktop app. Nothing is uploaded or synced, and
|
|
all guides stay on your machine.
|
|
|
|
# Windows installation
|
|
|
|
For the windows installation, please see [windows_installation](windows_installation.md)
|
|
|
|
# Developer install
|
|
|
|
## 1. Install
|
|
|
|
Install the pinned Node toolchain first — Node 22.12 or newer (see
|
|
`.nvmrc`; with nvm: `nvm install && nvm use`). Installs are refused on
|
|
older Nodes.
|
|
|
|
From the repository root:
|
|
|
|
```bash
|
|
npm ci
|
|
```
|
|
|
|
That installs the locked dependency tree — Electron and the local packaging
|
|
tools used by the scripts. `npm ci` is the only supported installation path;
|
|
the app never installs or repairs dependencies at runtime.
|
|
|
|
## 2. Launch the app
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
The first launch creates the local StepForge data directory. On Linux (WIP)
|
|
it is usually under `~/.local/share/stepforge`. On Windows it is usually
|
|
under `%APPDATA%/stepforge`.
|
|
|
|
## 3. Create your first guide
|
|
|
|
In the library view:
|
|
|
|
1. Click `New guide`.
|
|
2. Give the guide a clear title (more -> rename guide).
|
|
3. Open the guide to enter the editor.
|
|
|
|
You can also import a guide archive with `Import archive` if you already have
|
|
one.
|
|
|
|
## 4. Add content
|
|
|
|
There are three simple ways to start:
|
|
|
|
1. Record your workflow by clicking on the record button (reconmmended).
|
|
2. Import screenshots with the `Import` button in the editor.
|
|
3. Paste an image from the clipboard if you already copied one.
|
|
|
|
If you want to capture new screenshots, open `Quick` actions and start a
|
|
capture session. Use `Settings` to set the capture hotkey and other capture
|
|
options.
|
|
|
|
## 5. Edit the guide
|
|
|
|
The editor is split into three panes:
|
|
|
|
1. Steps on the left
|
|
2. Editing canvas in the center
|
|
3. Properties on the right
|
|
|
|
Use the canvas tools to add shapes, arrows, text, blur, highlight, numbers,
|
|
and crops. Use the right pane to edit the step title, description, and
|
|
annotation details.
|
|
|
|
## 6. Save and export
|
|
|
|
Use these actions from the top bar:
|
|
|
|
1. `Save` writes the guide to disk.
|
|
2. `Export` opens format choices such as JSON, Markdown, HTML, PDF, GIF,
|
|
image bundle, DOCX, and PPTX.
|
|
3. `Linked` shows archive details when a guide is linked to a shared `.sfgz`
|
|
file.
|
|
|
|
If you want to find commands quickly, press `Ctrl+/` for Quick Actions.
|
|
|
|
## Useful shortcuts
|
|
|
|
1. `Ctrl+/` opens Quick Actions
|
|
2. `Ctrl+S` saves the current guide
|
|
3. `Ctrl+Z` undoes the last edit
|
|
4. `Ctrl+Shift+Z` redoes the last edit
|
|
5. `Alt+Up` and `Alt+Down` move the selected step
|
|
|
|
## If something is missing
|
|
|
|
1. Open `Settings` to review capture, export, and editor options.
|
|
2. Run `npm run sample` to generate a sample guide and exported examples.
|
|
3. Run `bash scripts/verify.sh` to check the full offline workflow.
|
|
|
|
## Optional builds
|
|
|
|
1. `bash scripts/build-release.sh` assembles the offline release layout.
|
|
2. `npm run package:windows` creates the Windows installer `.exe` in
|
|
`releases/`.
|
|
3. `bash scripts/package-linux.sh` creates Linux release artifacts (WIP;
|
|
local only).
|