diff --git a/README.md b/README.md index 2bb9b0dc..57a6d827 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ teams writing SOPs and runbooks, trainers and teachers, support teams answering screenshot for email addresses, card numbers, passwords, API keys and more, and blurs them. - **Send a link, not a file.** Publish any guide as a web page in one click, - hosted free on your own GitHub. [More below](#share-a-guide-with-a-link). + hosted free on your own GitHub. [More below](#share-a-guide-with-a-web-link). - **Export to what your team already uses.** PDF, Word, PowerPoint, Markdown, HTML, Confluence, Wiki.js and more, so a guide lands where people will read it. @@ -94,9 +94,6 @@ page and hands you a link to send. It's usually online in under a minute. - **The same link, always up to date.** Changed the guide? Publish again and the link stays the same. StepForge marks guides you've **edited since you shared them**, so you never send out a stale version. -- **Checked before it goes public.** Screenshots are scanned for email - addresses, passwords, keys and card numbers, and those are blurred before - anything is uploaded. - **Hard to stumble on.** Every link has a random ID, and pages ask search engines not to index them. Want links on `guides.yourdomain.com`? Point a [custom domain](docs/GITHUB_PAGES.md#use-your-own-domain) at it and @@ -106,9 +103,9 @@ page and hands you a link to send. It's usually online in under a minute. password. > [!IMPORTANT] -> Shared guides are **public**: anyone with the link can open them. The -> privacy check catches a lot, but always look over your screenshots before -> publishing. [How sharing works](docs/GITHUB_PAGES.md) +> Shared guides are **public**: anyone with the link can open them. StepForge +> blurs the private details it finds before publishing, but always look over +> your screenshots yourself. [How sharing works](docs/GITHUB_PAGES.md) ## Install @@ -119,14 +116,8 @@ page and hands you a link to send. It's usually online in under a minute. | **Fedora 44 Workstation** | DNF repository | [Fedora](docs/linux/dnf.md) | | **Other Linux** | Portable `.tar.gz` | [Linux overview](docs/linux/linux_install.md) | -Every build is also on the [Releases page](https://github.com/Twest2/StepForge/releases/latest). -The Microsoft Store updates StepForge automatically. Installing through -Chocolatey, APT or DNF keeps StepForge up to date with the rest of your system, -and with Chocolatey, **Settings → About → Update now** installs a new version -in one click. - -**Windows:** open [StepForge in the Microsoft Store](https://apps.microsoft.com/detail/9NDH81CF1HGV) -and click **Get**. +**On Windows,** get StepForge from the Microsoft Store. It needs no +administrator rights and keeps itself up to date. Get it from Microsoft @@ -174,13 +165,19 @@ sudo dnf install stepforge +Chocolatey, APT and DNF keep StepForge up to date along with the rest of your +system. Every build is also on the +[Releases page](https://github.com/Twest2/StepForge/releases/latest). + ## Your first guide in one minute 1. Open StepForge and choose **New guide**. 2. Choose **Capture → Start capture session**. StepForge steps out of the way. 3. Do the task you want to document, clicking as you normally would. -4. Stop the recording from the tray icon (Windows) or **StepForge REC** in the - GNOME top panel (Linux). +4. To stop on **Windows**, click the **red dot** beside the clock. Don't see + it? Click the **^** arrow near the clock, then the red dot. On **Linux**, + click **● StepForge REC → Stop recording** at the top right of the screen. + [More help](docs/GETTING_STARTED.md#stop-recording) 5. Tidy up titles, add annotations, then choose **Export**. The [Getting Started guide](docs/GETTING_STARTED.md) walks through recording, @@ -221,7 +218,7 @@ was recorded with StepForge. annotated images. - **Share a link.** Publish a guide as an interactive web page on your own GitHub Pages site for 1, 7 or 30 days, removed automatically when its time - is up. [See how it works](#share-a-guide-with-a-link). + is up. [See how it works](#share-a-guide-with-a-web-link). - **Publish to Confluence** (beta) on Confluence Cloud or your organization's Data Center site, including sites that need a smart card (CAC). - **Publish to Wiki.js** (beta), with the screenshots uploaded to the wiki. @@ -260,7 +257,7 @@ each optional feature sends. - [Getting started](docs/GETTING_STARTED.md): recording, editing and exporting - [AI-written guides with Ollama](docs/getting_started_with_ai.md) - [Let Claude or Codex write your guides](docs/AI_AGENTS.md) -- [Google Drive sync](docs/GOOGLE_DRIVE.md) · [OneDrive, Dropbox or Nextcloud](docs/CLOUD_ACCOUNTS.md) +- [Sync between computers](docs/CLOUD_ACCOUNTS.md) with Google Drive, OneDrive, Dropbox or Nextcloud - [Share guides on the web with GitHub Pages](docs/GITHUB_PAGES.md) - [Publish to Confluence](docs/CONFLUENCE.md) · [Publish to Wiki.js](docs/WIKIJS.md) - [Brand your exported guides](docs/BRANDING.md): logos, colors, fonts and Advanced CSS diff --git a/docs/AI_AGENTS.md b/docs/AI_AGENTS.md index b48a1ba4..617c41b5 100644 --- a/docs/AI_AGENTS.md +++ b/docs/AI_AGENTS.md @@ -13,47 +13,6 @@ window opens, and nothing runs when no agent is connected. > on your own computer through Ollama. See > [AI-written guides with Ollama](getting_started_with_ai.md). -## What an agent can and can't do - -| An agent can | An agent can't | -| --- | --- | -| List and read your guides | Change a placeholder you already have, or delete one | -| See each step's screenshot, with your blurs already filled in | Delete blurs, or see what they hide | -| Create guides, and move them to the Trash | Delete brand profiles | -| Rewrite a guide's title and description | Read anything outside your StepForge library, except a PNG you ask it to use as a screenshot, or an image or font file you ask it to add to a brand profile | -| Add, delete, and reorder steps, and make a step a substep of an earlier step | | -| Rewrite each step's title, description, and blocks, add notes, warnings, tips, and code, and delete blocks | | -| Replace a step's screenshot with a PNG file you point it to, or remove the screenshot | | -| Add guide and global placeholders, and use them as `[[Name]]` | | -| Draw on screenshots: rectangles, ovals, lines, arrows, text, callouts, numbered badges, blurs, highlights, magnifiers, and cursors. Delete what's drawn, except blurs | | -| If you allow it: make and change [brand profiles](BRANDING.md#let-an-ai-agent-set-up-your-brand), add a logo, banner or font file you point it to, and choose the active profile | | - -Most of the time an agent works around your screenshots: it writes the text, -organizes the steps, and adds annotations on top. When it does more than that, -StepForge keeps a way back. - -### Undoing what an agent did - -Before an agent deletes, moves, or adds a step, replaces or removes a -screenshot, or deletes blocks or annotations, StepForge saves a snapshot of the -guide. To undo the change, open the guide and choose **More → Backups & -snapshots**. Each agent snapshot is named for what the agent was about to do, -for example "before agent deletes step 3". **Restore** the one from just before -the change you want to undo. Restoring snapshots the guide first, so a restore -can be undone too. - -Automatic backups don't push agent snapshots out. StepForge keeps the newest 50 -agent snapshots of each guide. Text rewrites, changing substep nesting with -`update_step`, adding placeholders and drawing annotations do not create agent -snapshots; create a manual snapshot first if you want a recovery point before -those edits. - -A guide an agent deletes goes to the Trash, like one you delete. Restore it -from there. Its snapshot and Trash copy contain saved content; unsaved edits -in an open editor are not included when the agent deletes the guide. The -agent-access switch permits all the guide tools listed above; it is not a -separate approval for each deletion. - ## 1. Turn on agent access 1. Open **Settings → AI**. @@ -92,18 +51,61 @@ Record a guide in StepForge as usual, then ask your agent, for example: The agent finds the guide, looks at each step's screenshot, and rewrites the text. It uses your placeholders where their values would appear, and can add -new ones for values that repeat, such as a course code or product name. If -the guide is open in StepForge, it updates on screen within a couple of -seconds. If you're typing in the same step at that moment, your edit wins. If -the agent deleted that step, StepForge drops its pending save and shows the -remaining steps instead of recreating it. For a surviving step, changes to -different fields, blocks or annotations combine; your edit wins when both -sides changed the same field. - -Before you share the guide, read what the agent wrote. To undo a big rewrite, -use **More → Backups & snapshots**. Annotations an agent drew can be moved or -deleted like your own. If you have the guide open when an agent moves it to -the Trash, StepForge takes you back to the library. +new ones for values that repeat, such as a course code or product name. + +If the guide is open in StepForge, it updates on screen within a couple of +seconds. If you and the agent change the same thing at the same moment, your +edit wins. + +Read what the agent wrote before you share the guide. + +## What an agent can and can't do + +An agent can: + +- list and read your guides, and see each step's screenshot with your blurs + already filled in +- create guides, and move them to the Trash +- add, delete, reorder, and nest steps +- rewrite the guide's and each step's title, description, and blocks (notes, + warnings, tips, and code) +- replace a step's screenshot with a PNG file you point it to, or remove it +- add guide and global placeholders +- draw on screenshots (shapes, arrows, text, callouts, numbered badges, blurs, + highlights, magnifiers, and cursors), and delete annotations other than + blurs +- if you allow it, set up your + [brand profiles](BRANDING.md#let-an-ai-agent-set-up-your-brand) + +An agent can't: + +- delete blurs, or see what they hide +- change or delete a placeholder you already have +- delete a brand profile +- read files outside your StepForge library, except one you ask it to use as + a screenshot, logo, or font + +StepForge doesn't ask before each change: turning on agent access allows +everything above. + +## Undoing what an agent did + +Before an agent deletes, moves, or adds a step, replaces or removes a +screenshot, or deletes blocks or annotations, StepForge saves a snapshot of the +guide. Each one is named for what the agent was about to do, such as "before +agent deletes step 3". + +To undo a change, open the guide, choose **More → Backups & snapshots**, and +**Restore** the snapshot from just before it. Restoring snapshots the guide +first, so a restore can be undone too. + +Rewriting text, changing substeps, adding placeholders, and drawing +annotations don't make a snapshot. If you want a way back before those, create +a snapshot yourself first. Annotations an agent drew can be moved or deleted +like your own. + +A guide an agent deletes goes to the Trash, like one you delete. If you have +it open at the time, StepForge takes you back to the library. ## Privacy @@ -113,12 +115,8 @@ its AI provider**, such as Anthropic for Claude or OpenAI for Codex. Their privacy terms apply to that data. - Screenshots are shared with your blurs filled in, so the agent never sees - what you hid. Agents can't delete blurs. Screenshot imports must come from - outside the library; raw originals, Trash and snapshot files cannot be - imported to bypass the blurs. Replacing a screenshot keeps its blurs, - including those added by Find private details. -- An agent reads a file outside your library only when it uses one as a - screenshot or adds one to a brand profile, and only the file it names. + what you hid. Replacing a screenshot keeps its blurs, and an agent can't + swap in an unblurred copy from your library. - Agents never get the text you typed while recording, field values, or the text StepForge read from the screen. - Turning off **Let AI agents edit your guides** cuts off every connected diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index e1cc95ae..7c7ee396 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -132,14 +132,31 @@ Export dialog choice. In the profile editor, **Pick from logo** runs `core/brand-palette.js` on a small canvas drawing of the logo, and **Write with AI** asks Ollama for CSS (`core/ai-brand-css.js`, which also strips `@import` and remote `url()`s); it's shown only when `ai:status` reports AI on -and the model installed. AI agents edit guides through `core/agent-tools.js`; -each tool that deletes, moves or replaces something first calls -`createAgentSnapshot` (`core/snapshots.js`). AI agents reach profiles through -`core/agent-brand-tools.js`, behind `ai.agents.branding`. The `--mcp` process -records each change in `agent-changes.json`; the running app saves an agent's -choice of active profile itself (it holds Settings in memory) and has the -renderer draw PNG copies of SVG or JPG images agents added -(`branding:pendingRasters`). +and the model installed. + +## AI Agents (MCP) + +`stepforge --mcp` runs an MCP server over stdio for agents such as Claude Code +and Codex, gated by `ai.agents` (re-read on every request). + +- Guide tools live in `core/agent-tools.js`. Each tool that deletes, moves or + replaces something first calls `createAgentSnapshot` (`core/snapshots.js`). + Text rewrites, substep changes through `update_step`, new placeholders and + drawn annotations don't snapshot. +- Agents can't delete blurs or existing placeholders. A screenshot an agent + imports must come from outside the library, so raw originals, Trash and + snapshot files can't be used to get around blurs, and a replaced screenshot + keeps its blurs, including those from Find private details. +- When an agent deletes a guide, the snapshot and Trash copy hold the saved + content only, not unsaved edits in an open editor. If the editor has the + step an agent deleted, it drops that step's pending save instead of + recreating it; for surviving steps, edits to different fields combine and + the user's edit wins a field both changed. +- Profiles are reached through `core/agent-brand-tools.js`, behind + `ai.agents.branding`. The `--mcp` process records each change in + `agent-changes.json`; the running app saves an agent's choice of active + profile itself (it holds Settings in memory) and has the renderer draw PNG + copies of SVG or JPG images agents added (`branding:pendingRasters`). ## Shell / Core Boundary @@ -250,7 +267,7 @@ opt-in and off by default: untrusted and pass archive validation before a journaled, staged replacement that keeps a local backup. Archive compression runs one job at a time in a background worker shared with linked-archive writes and - automatic backups. See [GOOGLE_DRIVE.md](GOOGLE_DRIVE.md) and + automatic backups. See [CLOUD_ACCOUNTS.md](CLOUD_ACCOUNTS.md) and [SECURITY.md](SECURITY.md). - **Synced settings** (`core/shared-settings.js`): global placeholders, brand profiles with the assets they use, the active profile, the language and @@ -263,8 +280,12 @@ opt-in and off by default: new computer's defaults never win a merge. Per-value edit times travel in `settings.json.modifiedAt`; their local copy is `settings/shared-settings-times.json`, updated only when that value - changes. Older archives fall back to their version time. Profile field - conflicts compare the profile's `updatedAt`. + changes, so editing one value never makes another look newer. Older + archives fall back to their version time. Profile field conflicts compare + the profile's `updatedAt`. A settings version that is damaged or needs a + newer StepForge stops settings sync with an error rather than being + skipped, because a merge published without it could discard values this + build couldn't read; guide sync carries on. The base is `cloud/settings-base.json`. Incoming settings wait while the Settings dialog is open. Incoming recording shortcuts re-register the running app’s global hotkeys immediately. Every image and font is re-checked by @@ -275,6 +296,9 @@ opt-in and off by default: `core/folder-storage.js` keeps each version's details in a small `objects/.json` beside its data and names shared parts by their hash. `settings.cloud.provider` picks the one service that syncs. +- **Unused parts** are garbage-collected after a sync and by **Free up + space**, except parts uploaded in the last hour, which another computer may + still be committing a version for. The sandboxed renderer never makes network requests or sees tokens; all of these run in the main process. @@ -283,16 +307,20 @@ these run in the main process. - Archive imports validate every entry name against path traversal and absolute paths before extraction (`core/zip.js`). -- Linked guides use sidecar `*.lock-sfgz` lock files; conflicts surface a +- Linked guides use sidecar `*.lock-sfgz` lock files that record who is + saving, not who has the guide open. Saving while another client holds the + lock is refused unless the user saves anyway; conflicts surface a keep-editing / discard dialog. A linked save re-reads the shared file under the lock and three-way merges it (`core/guide-merge.js`) with the version - this library last saved or opened, kept in `history/linked-base.json`. + this library last saved or opened, kept in `history/linked-base.json`. A + value both sides changed goes to the more recent edit, the toast reports + the conflict count, and a backup is taken before each merge. - Renderer runs with `contextIsolation: true`, `nodeIntegration: false`, and `sandbox` enabled; only the preload API is exposed. - Description HTML is sanitized against an allowlist on save and again on render and export (`core/sanitize.js`). -## Workflow +## Tests and CI 1. Change core/exporter logic together with its workflow tests in `tests/unit/`. @@ -300,4 +328,22 @@ these run in the main process. 3. Run `bash tests/run_test.sh` locally. 4. Open a pull request linked to an issue; CI runs the same suite. -The full process is in [CONTRIBUTING.md](CONTRIBUTING.md). +CI is `.github/workflows/ci.yml`. The runner accepts repeatable +`--skip test_name.sh` options for checks delegated to other jobs; an unknown +name fails before any check runs. Fedora CI delegates the Debian release +build to the pinned Ubuntu package job and units to the Linux/Windows unit +jobs. Ubuntu builds the Debian package once while verifying the release +report and sample manifest, then uploads those same artifacts. Locally, the +default command still runs the complete suite. + +The Fedora build-deps installer includes Electron's system libraries for +repository checks. Its optional `--rpm-only` argument omits `dpkg` for jobs +that do not build Debian artifacts; contributor setup includes it by default. + +Fedora CI builds test RPMs with `STEPFORGE_RPM_FAST=1`, selecting level-3 +Zstandard compression with two threads. These packages contain the same +runtime files but can be larger. Normal RPM builds retain the distro's +compression defaults. A small real-RPM fixture checks both compression paths +on every Fedora PR run. + +The full contributor process is in [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/docs/BRANDING.md b/docs/BRANDING.md index 3b4264d0..9af9066c 100644 --- a/docs/BRANDING.md +++ b/docs/BRANDING.md @@ -31,13 +31,10 @@ extra CSS for web pages. Set it up once and every guide uses it. numbers**. Header and footer text can use placeholders, such as `© [[Year]] Acme Corp`. - **Watermark screenshots with the logo**, with its corner and opacity. - - **Annotation colors**: off by default, so annotations keep StepForge's - colors (red shapes, blue number badges, dark tooltips). Turn on **Use - your own annotation colors** to pick colors for **Shapes** (rectangles, - ovals, lines, arrows, text and magnifiers, and the marker on recorded - clicks), **Number badges** and **Tooltips**. New annotations start in - these colors; ones already drawn keep theirs, and you can still change - any annotation's color in the editor. Highlights stay yellow. + - **Annotation colors**: turn on **Use your own annotation colors** to + pick colors for **Shapes** (including the click marker), **Number + badges** and **Tooltips**. New annotations start in these colors; + ones already drawn keep theirs. Highlights stay yellow. - **Advanced CSS**: see [below](#advanced-css). 3. Choose **Preview** at the bottom to see a sample guide with your changes, then **Save**. @@ -263,9 +260,8 @@ An agent can: a file you upload - choose the active profile -It can't delete a profile. An SVG or JPG image an agent adds works in HTML -exports at once. The other exports need a PNG copy, which StepForge draws -within a few seconds while it's open, or the next time it starts. +It can't delete a profile. If StepForge is closed when an agent adds an SVG +or JPG image, exports other than HTML pick it up once StepForge is next open. ## Share a profile @@ -280,5 +276,5 @@ Profiles live in your data folder under `settings/branding/` (see **Settings → About → Data folder**). Logos, banners and fonts are kept beside them. An upload that no profile uses any more is deleted after a day. -With [cloud sync](GOOGLE_DRIVE.md#settings-that-sync) on, your profiles, their +With [cloud sync](CLOUD_ACCOUNTS.md#settings-that-sync) on, your profiles, their files and the active profile follow you to every computer that syncs. diff --git a/docs/CLOUD_ACCOUNTS.md b/docs/CLOUD_ACCOUNTS.md index ea871fbb..4e0116ec 100644 --- a/docs/CLOUD_ACCOUNTS.md +++ b/docs/CLOUD_ACCOUNTS.md @@ -1,39 +1,48 @@ -# Sync with OneDrive, Dropbox or Nextcloud +# Sync your guides between computers -StepForge can back up your guides and keep them in sync between your -computers with **Google Drive**, **OneDrive**, **Dropbox**, or your own -**Nextcloud or WebDAV server**. Sync is off until you sign in. +Sync keeps your StepForge library the same on every computer you use. Your +guides, with their screenshots, annotations, and text, follow you, along with +the [settings guides depend on](#settings-that-sync). -Open **Settings → Accounts** and choose a service. +Sync is **optional and off by default**. StepForge works fully offline without +it. + +## Choose a service | Service | How you sign in | Where guides are stored | | --- | --- | --- | -| Google Drive | Your Google account, in the browser | A hidden app folder only StepForge can see ([details](GOOGLE_DRIVE.md)) | -| OneDrive | Your Microsoft account (personal, work or school), in the browser | `Apps/StepForge` in your OneDrive | -| Dropbox | Your Dropbox account, in the browser | `Apps/StepForge` in your Dropbox | -| Nextcloud or WebDAV | Nextcloud: your server's own login page. Other servers: a user name and password | A `StepForge` folder in your account | +| [Google Drive](#google-drive) | Your Google account, in the browser | A hidden app folder only StepForge can see | +| [OneDrive](#onedrive-and-dropbox) | Your Microsoft account (personal, work or school), in the browser | `Apps/StepForge` in your OneDrive | +| [Dropbox](#onedrive-and-dropbox) | Your Dropbox account, in the browser | `Apps/StepForge` in your Dropbox | +| [Nextcloud or WebDAV](#nextcloud-and-other-webdav-servers) | Nextcloud: your server's own login page. Other servers: a user name and password | A `StepForge` folder in your account | + +Every service works the same way. StepForge only gets access to its own +folder, and can't see or change anything else in your account. + +## Connect + +1. Open **Settings → Accounts** and choose your service. +2. Sign in. For Nextcloud or WebDAV, type your server's address first (see + [below](#nextcloud-and-other-webdav-servers)). +3. Allow StepForge access in the browser. StepForge comes back to the front, + shows which account is connected, and starts syncing. You can close the + browser tab. +4. On your other computers, install StepForge and sign in to the **same** + account. -StepForge only gets access to its own folder. It can't see or change anything -else in your OneDrive, Dropbox, or Nextcloud. +If the browser doesn't open, or opens the wrong one, choose **Open it again** +or **copy the sign-in link** under the sign-in button and paste the link into +any browser on this computer. -When you sign in through the browser, StepForge comes back to the front once -you've allowed access. If the browser doesn't open, or opens the wrong one, -choose **Open it again** or **copy the sign-in link** under the sign-in button -and paste the link into any browser on this computer. +Changes in these settings take effect immediately. You don't need to press +**Save**. On Linux, StepForge keeps sign-ins in your desktop's keyring (GNOME Keyring, KWallet, or another Secret Service such as KeePassXC). If sign-in says it needs an operating-system credential store, make sure a keyring is installed and unlocked, then restart StepForge. -Sync works the same way on every service: versions, restoring, combining -edits from different computers, the [settings that sync](GOOGLE_DRIVE.md#settings-that-sync) -with your guides, recently deleted guides, and **Free up space** are all -described in -[Google Drive sync](GOOGLE_DRIVE.md). Every service stores only what changed -between versions, so a screenshot that appears in many versions is stored once. - -## One account at a time +### One account at a time StepForge syncs with one account at a time. Signing in to a different service switches this computer to it: @@ -44,7 +53,177 @@ switches this computer to it: - Your other computers keep syncing with the previous service until you switch them too. Switch every computer so they all see the same guides. -## Nextcloud and other WebDAV servers +## Everyday use + +There's nothing to do. StepForge uploads a guide a few seconds after you save +it and checks for changes from your other computers about every 30 seconds. + +The **sync indicator** in the top bar shows your service's name and what's +happening (waiting, syncing, up to date, or needs attention). While a guide is +uploading (↑) or downloading (↓), it shows a live counter such as +**Drive: ↓ 3.2 MB / 12.0 MB**. Click it to open the sync settings. + +> [!TIP] +> Before switching computers, wait until the indicator shows the guide is up +> to date. + +- **Sync now** starts a sync immediately. +- **Auto-sync** pauses and resumes syncing on this computer. +- **Test connection** (under **Advanced**) checks sign-in and storage access + by uploading, downloading, and deleting a small temporary file. It never + uploads a guide. + +To keep one guide on this computer only, open it, choose +**More → Guide information…**, and turn off **Include this guide in cloud +sync**. + +## How changes are handled + +- **Edits from different computers are combined.** If you edit the same + guide on two computers before they sync, StepForge puts both sets of changes + into the one guide. Changes to different steps, to different parts of a step, + or to different annotations all survive. Steps added on either computer are + kept, and a step deleted on one computer is removed unless it was edited on + the other. This isn't live co-editing. +- **When both computers changed the same thing**, such as the same step + title, the most recent change is kept. If this computer had edits that + hadn't synced yet, its earlier version is saved as a *before-sync-merge* + snapshot under **More → Backups & snapshots…**, so nothing is lost. +- **Your work isn't interrupted.** Updates from another computer wait until + you close the guide and stop recording. +- **Downloads are checked** before they replace anything, and the replaced + local copy is kept as a backup in your data folder. +- **Deleting a guide deletes it on your other computers too.** They move it + to their Trash, and one recovery copy stays in the cloud under + [Recently deleted](#manage-whats-stored). Restore it from the Trash on any + computer and it comes back everywhere. +- **Going offline is fine.** Local edits are kept and sync resumes when you're + back online. + +### Settings that sync + +These settings follow your guides across computers: + +- **Global placeholders** (**Settings → Placeholders**) +- **Brand profiles**, with their logos, banners and fonts, and which profile + is active (**Settings → Branding**) +- **Interface language** (**Settings → General → Language**) +- **Recording shortcuts** for Capture and Pause/resume + (**Settings → Capture → Hotkeys**) + +Other capture options, AI and guide storage stay on each computer. + +They're combined the same way as guides: changes made on different computers +all survive, and when two computers changed the same value, the most recent +edit wins. Deleting a placeholder or profile deletes it everywhere, unless +another computer edited it. A computer syncing for the first time adds its +placeholders and profiles to the ones already there, and its untouched +defaults never replace a choice you made on another computer. + +Changes from another computer wait while **Settings** is open and arrive when +you close it. If settings sync shows an error, usually because another +computer saved them with a newer StepForge, update StepForge on this computer. +Until then your settings are left as they are, and guides keep syncing. + +## Manage what's stored + +Your service's page in **Settings → Accounts** also lets you see and tidy up +what StepForge has stored there. Buttons use your service's name, such as +**Delete from OneDrive**. + +**Storage** shows how much space StepForge uses, split into latest versions, +previous versions, and recovery copies of deleted guides. + +**Free up space** deletes all previous versions after you confirm. The latest +version of every guide is always kept. Deleted versions can't be recovered. + +**Guides in …** (for example **Guides in Drive**) lists every guide StepForge +has stored, including ones that aren't on this computer. + +- **Versions** shows a guide's latest version and up to two previous ones. + **Restore** puts an earlier version back. Close the guide and stop any + recording first. Your current local copy is backed up before it's replaced. +- **Download** installs a guide that's only in the cloud onto this computer. +- **Delete from** your service permanently removes all of a guide's cloud + versions after confirmation. Your local copy is kept and stops syncing. + Other computers that still sync the guide may upload it again. + +**Recently deleted** holds one recovery copy of each deleted guide, which you +can restore or delete permanently. + +### How versions are stored + +Each version stores **only what changed**. A screenshot is uploaded once and +shared by every version (and every guide) that contains it, so fixing a typo +uploads a few kilobytes instead of the whole guide. Downloads work the same +way: a computer only fetches the screenshots it doesn't already have. + +Versions saved as full copies by an older StepForge keep working. **Free up +space** switches them to space-saving versions. + +> [!IMPORTANT] +> Update StepForge on **every** computer that syncs with the same account. +> Older releases can't read space-saving versions: they show a sync error for +> those guides instead of changing them. They also don't combine edits, and +> may still save separate *conflict copy* guides. + +### Make this computer the source of truth + +If your computers have drifted apart and you want one of them to win, open +**Advanced** and choose **Replace … with this computer** (for example +**Replace Drive with this computer**). After you confirm, StepForge: + +1. Deletes everything StepForge has stored with your service, including all + versions and recovery copies. +2. Uploads the guides and [settings](#settings-that-sync) on this computer. +3. Tells your other computers to move any guide that isn't on this computer + to their Trash, and to update the rest to this computer's version. + Unsynced edits on those computers are combined with this computer's version. + +**Auto-sync** must be on to use this. + +> [!WARNING] +> This can't be undone. Make sure this computer has everything you want to +> keep. + +## Limits + +- Each guide keeps its **latest version plus up to two previous versions**. + Older versions are removed automatically after a successful sync. +- A single guide can be up to **256 MB**. Very large guides on slow + connections may take more than one attempt. +- The first sync of a guide sends all of it. After that, only new or changed + files are sent. + +## Service details + +### Google Drive + +StepForge stores its files in a private, hidden area of your Drive reserved +for the app. It has no access to your documents, photos, or anything else, and +for the same reason its files don't appear in your Drive file list. The +**Storage** card in StepForge is the only place to see how much space they use. + +To remove everything StepForge stored, revoke its access under +[your Google account's third-party connections](https://myaccount.google.com/connections), +then in Google Drive open **Settings → Manage apps**, find StepForge, and +choose **Delete hidden app data**. + +### OneDrive and Dropbox + +StepForge only gets its own folder, `Apps/StepForge`. With OneDrive, personal, +work and school accounts all work. Leave the files in `Apps/StepForge` as they +are; StepForge manages them. + +To remove StepForge's access: + +- **OneDrive:** in your Microsoft account, open **Privacy → Apps and + services** and remove StepForge. Delete `Apps/StepForge` from OneDrive to + remove its files. +- **Dropbox:** open **Settings → Connected apps** and remove StepForge. Delete + `Apps/StepForge` to remove its files. + +### Nextcloud and other WebDAV servers Type your server's address, such as `cloud.example.com`, and choose **Sign in**. @@ -62,18 +241,42 @@ network (such as `192.168.1.20` or `nas.local`), where plain `http://` is allowed. The `StepForge` folder holds a `parts` folder and an `objects` folder of -files with coded names. Leave them as they are; StepForge manages them. +files with coded names. Leave them as they are; StepForge manages them. To +remove StepForge's access, revoke its app password under **Settings → +Security** in Nextcloud, and delete the `StepForge` folder. -## Disconnecting +## Disconnect **Disconnect** stops syncing on this computer and removes the saved sign-in. Your guides stay on this computer and with the service. To remove StepForge's -access completely: +access completely, see your service under [Service details](#service-details). -- **OneDrive:** in your Microsoft account, open **Privacy → Apps and - services** and remove StepForge. Delete `Apps/StepForge` from OneDrive to - remove its files. -- **Dropbox:** open **Settings → Connected apps** and remove StepForge. Delete - `Apps/StepForge` to remove its files. -- **Nextcloud:** revoke the StepForge app password under **Settings → - Security**, and delete the `StepForge` folder. +## Privacy and security + +- With Google, Microsoft, Dropbox and Nextcloud, you sign in on their own + website in your browser, so StepForge never sees your password. +- Sign-ins are stored encrypted with your operating system's credential + storage. +- Guides are sent over HTTPS and stored in your own account. They aren't + additionally encrypted by StepForge, so treat them like any other file in + that account. + +The [privacy policy](PRIVACY.md#optional-google-drive-sync) lists exactly what +is sent, and the [security overview](SECURITY.md) explains how it's protected. + +## Troubleshooting + +| Problem | What to do | +| --- | --- | +| Google sign-in finishes but StepForge says Drive access wasn't granted | Choose **Sign in with Google** again and leave the Google Drive permission ticked on Google's consent page. | +| "sign-in is unavailable in this build" | You're running a development build. Install an official release. | +| Sign-in says it needs an operating-system credential store (Linux) | Install and unlock a keyring, such as GNOME Keyring or KWallet, then restart StepForge. | +| The indicator shows *needs attention* | Open your service in **Settings → Accounts** to see the error. For sign-in problems, choose **Sign in again**. | +| A guide from another computer hasn't arrived | Make sure that computer finished syncing, then choose **Sync now**. Close the guide if it's open here. | +| Your storage is full | Choose **Free up space**, or free up space elsewhere in your account. | + +--- + +*Maintainers: see [Google sign-in](cloud_accounts_init_setup/GOOGLE_DRIVE_RELEASE.md) +and [OneDrive and Dropbox sign-in](cloud_accounts_init_setup/CLOUD_ACCOUNTS_RELEASE.md) +release configuration.* diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index a162e7ff..7fc892f0 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -31,9 +31,10 @@ CI runs the full test suite on every pull request. - Core features must work offline. No telemetry, automatic update checks, license checks, or remote fonts. The only update check is the one the user starts from **Settings → About**. -- Optional integrations (AI and Google Drive) stay **off by default**, require - explicit opt-in, and follow the [privacy policy](PRIVACY.md). Discuss any new - network feature with the maintainer before building it. +- Optional integrations (AI, cloud sync, sharing and publishing) stay **off by + default**, require explicit opt-in, and follow the + [privacy policy](PRIVACY.md). Discuss any new network feature with the + maintainer before building it. ### No new runtime dependencies @@ -141,23 +142,9 @@ scripts in `scripts/linux/` install; without them those checks are skipped. - Name and describe tests clearly so that whoever breaks one later understands what it protects. -CI is configured in `.github/workflows/ci.yml`. The runner accepts repeatable -`--skip test_name.sh` options for checks delegated to other jobs; an unknown -name fails before any check runs. Fedora CI delegates the Debian release -build to the pinned Ubuntu package job and units to the Linux/Windows unit -jobs. Ubuntu builds the Debian package once while verifying the release -report and sample manifest, then uploads those same artifacts. The default -command above still runs the complete suite locally. - -The Fedora build-deps installer includes Electron's system libraries for -repository checks. Its optional `--rpm-only` argument omits `dpkg` for jobs -that do not build Debian artifacts; contributor setup includes it by default. - -Fedora CI builds test RPMs with `STEPFORGE_RPM_FAST=1`, selecting level-3 -Zstandard compression with two threads. These packages contain the same -runtime files but can be larger. Normal RPM builds retain the distro's -compression defaults. A small real-RPM fixture checks both compression paths -on every Fedora PR run. +CI (`.github/workflows/ci.yml`) runs the same suite on Ubuntu, Fedora and +Windows. How the jobs split the work is described in +[ARCHITECTURE.md](ARCHITECTURE.md#tests-and-ci). ## Interface text and translations @@ -188,7 +175,7 @@ in `LANGUAGES`, so the Store shows StepForge as available in it. | Target | Command | Output | | --- | --- | --- | | Windows installer | `npm run package:windows` (or `pwsh scripts/package-windows.ps1`) | `releases/` | -| Microsoft Store `.appx` (Windows only) | `npm run package:windows:store` (or `npm run package:windows:store:test` for a placeholder identity). The Release workflow builds it and submits it to the Store | `releases/` | +| Microsoft Store `.appx` (Windows only) | `npm run package:windows:store`, or `npm run package:windows:store:test` for a test build with a placeholder identity | `releases/` | | Ubuntu `.deb` + portable `.tar.gz` | `npm run package:linux:deb` | `build/artifacts/` | | Fedora `.rpm` | `npm run package:linux:rpm` | `build/artifacts/x86_64/` | | Unpacked app folder | `bash scripts/build-release.sh` | `build/` | diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index e2615b5b..1c9a1fac 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -21,31 +21,57 @@ you haven't installed StepForge yet, start with the 3. Work through the task you want to document. **Each click creates a step** with a screenshot taken at the moment of the click and a marker on the spot you clicked. -4. When you're finished, stop the session: - - **Windows:** use the red StepForge icon in the system tray. - - **Linux (GNOME):** use **StepForge REC** in the top panel, or restore - StepForge from the dock. +4. When you're finished, stop the recording. StepForge is hidden at this + point, so [here's where to click](#stop-recording). StepForge reads the text around each click (with on-device OCR) and uses it to title the step, so you'll usually see titles like *Click Releases* or *Select Run anyway* without typing anything. -**Other ways to add steps** +> [!TIP] +> On first recording under GNOME Wayland you'll be asked to enable the +> StepForge extension and pick which monitors to share. Select every monitor +> you plan to click on. See [Linux recording](linux/linux_install.md#recording-on-gnome-wayland) +> for details. + +### Stop recording + +**On Windows,** look for a small **red dot** in the bottom-right corner of the +screen, in the row of icons beside the clock. + +1. Click the red dot. Recording pauses, and StepForge comes back with your + new steps. +2. Don't see it? Click the **^** arrow beside those icons to show the hidden + ones. The red dot is usually in there. +3. Still can't find it? Open StepForge from the Start menu again. That also + pauses recording and brings StepForge back. + +Right-click the red dot for more choices, such as **Pause capturing** or +**Finish session**, which ends the recording and removes the dot. + +**On Linux (GNOME),** look for **● StepForge REC** at the top right of the +screen. + +1. Click **● StepForge REC**, then choose **Stop recording**. StepForge comes + back with your new steps. +2. Or click StepForge in the dock to bring its window back, then choose + **Stop recording** at the top right of the window. + +The click that stops recording never becomes a step, but other clicks you +make while looking for it can, such as on the **^** arrow. Delete any extra +steps in the editor. To record more, choose **Start recording** at the top +right of the StepForge window. + +### Other ways to add steps | To... | Do this | | --- | --- | | Take a single screenshot | **Capture → Capture full screen**, **Capture window**, or **Capture region…** | | Capture with the keyboard | Press **Ctrl+Shift+1** (change it in **Settings → Capture → Hotkeys**) | -| Pause and resume a session | Press **Ctrl+Shift+2** | +| Pause and resume a session | Press **Ctrl+Shift+2**. StepForge stays hidden while paused | | Use an image you already have | Paste it with **Ctrl+V**, or use **Capture → Import images…** | | Add a text-only step | Choose **Add** in the steps list | -> [!TIP] -> On first recording under GNOME Wayland you'll be asked to enable the -> StepForge extension and pick which monitors to share. Select every monitor -> you plan to click on. See [Linux recording](linux/linux_install.md#recording-on-gnome-wayland) -> for details. - ## 2. Edit your steps The editor has three panes: @@ -72,21 +98,25 @@ For each step you can: - Turn on **Focused** view to zoom the exported screenshot toward the click, so readers see the relevant part of the screen instead of the whole desktop. - Start a **New page** at this step in paged formats such as PDF. -- **Replace the screenshot** when the software you documented has changed: - right-click the step and choose **Choose image…**, then pick an image - file. The step's title, description, and annotations stay, so check that - arrows and boxes still line up. Press **Ctrl+Z** to go back to the old - screenshot. A step without a screenshot gets one the same way. - To capture a fresh one instead, choose **Retake screenshot** and pick - **Full screen**, **Window** or **Region…**. StepForge hides itself for 3 - seconds so you can get the app into the right state, takes the new - screenshot and comes back. Only that step's image is replaced. It is not - available while a capture session is running. **Working with many steps at once:** choose **Select**, click one step, then **Shift-click** another to select everything in between, including substeps. A normal click toggles a single step. +### Replace or retake a screenshot + +When the software you documented changes, right-click the step: + +- **Retake screenshot** captures a new one (**Full screen**, **Window** or + **Region…**). StepForge hides for 3 seconds so you can get the app ready, + then takes the shot and comes back. +- **Choose image…** uses an image file instead. This also adds a screenshot + to a step that doesn't have one. + +The step keeps its title, description and annotations, so check that arrows +and boxes still line up. **Ctrl+Z** brings the old screenshot back. Retaking +isn't available while a capture session is running. + ## 3. Annotate screenshots Pick a tool from the toolbar above the screenshot and drag on the image. @@ -107,7 +137,7 @@ Pick a tool from the toolbar above the screenshot and drag on the image. Annotations stay editable. The original screenshot is never modified, so you can always change or remove them later. -A blur replaces what's under it with the colours around it, rather than +A blur replaces what's under it with the colors around it, rather than softening it. Nothing it covers is kept in exported or published images, so it can't be recovered from them. @@ -115,6 +145,7 @@ it can't be recovered from them. **More → Find private details…** reads every screenshot and blurs what looks private: + - email addresses, and phone and card numbers; - Social Security numbers and IP addresses; - passwords, API keys and tokens; @@ -141,12 +172,9 @@ Publishing a guide on the web always runs this check first. Choose **Export**, pick a format, and choose where to save. -If something looks unfinished, the Export dialog lists it at the top: -placeholders with no value, steps with no screenshot, and steps with no title -or one StepForge filled in automatically (such as "Screen capture"). Click an -item to go to that step, or export anyway. The Publish dialogs show the same -list. A step with no screenshot but its own text counts as a text-only step and -isn't flagged. +If something looks unfinished, such as a step with no screenshot or title, +or a placeholder with no value, the Export dialog lists it at the top. Click +an item to go to that step, or export anyway. | Format | Best for | | --- | --- | @@ -167,35 +195,23 @@ the screenshots, and updates the same page when you publish again. The Export dialog points you there when you pick either format. See [Publish to Confluence](CONFLUENCE.md) and [Publish to Wiki.js](WIKIJS.md). -Each format has options (page size, table of contents, image width, and so -on). Save your preferred options as a **template** so every guide exports the -same way. Templates can be shared with teammates as `.sfglt` files. - -**Branding** gives every export your company's look. In **Settings → Branding**, -choose **Manage** to make a brand profile: a name, your logo (PNG, JPG or SVG) -and an optional banner, primary, accent and text colors, heading and body -fonts (upload a font file to embed it in HTML), a cover style, header and footer -text with page numbers, an optional logo watermark for GIFs and image bundles, -optional colors for new annotations (shapes, number badges, tooltips), and -extra CSS for HTML. Then pick it as the **Active brand profile**, and use -**Design preview** to see a sample guide with it. HTML, GitHub Pages, PDF, Word -and PowerPoint get the full treatment; Wiki.js, Confluence and Markdown get the -logo, banner and header and footer text; JSON stays raw data. The Export dialog -can choose a different profile, or none, for one export. Profiles can be shared -as `.sfbrand` files. [Brand your exported guides](BRANDING.md) has the details, -including what Advanced CSS can style. - -Exported screenshots get alt text built from the step title (for example -"Screenshot for step 3: Click Save") in the HTML, Word, PowerPoint, Markdown -and Confluence formats, so screen readers announce more than a step number. PDFs -carry the guide title, and the author if you set one, as their document -properties. They are not tagged PDFs. - -**Placeholders** keep repeated text consistent. Define one in -**Settings → Placeholders** (for example `Product` → `Admin Portal`) and type -`[[Product]]` in any title, description or table cell. It's replaced when you -export or publish. Code blocks are left as written. -Guides can also have their own placeholders under **More → Guide placeholders…**. +**Templates.** Each format has options such as page size, table of contents +and image width. Save the ones you like as a template so every guide exports +the same way, and share it with teammates as a `.sfglt` file. + +**Branding.** A brand profile puts your logo, colors, fonts, cover, header and +footer on every export. Set one up in **Settings → Branding → Manage**. See +[Brand your exported guides](BRANDING.md). + +**Placeholders.** Define one in **Settings → Placeholders** (for example +`Product` → `Admin Portal`) and type `[[Product]]` in any title, description +or table cell. It's replaced when you export or publish (code blocks are left +as written). A single guide can have its own placeholders under +**More → Guide placeholders…**. + +**Accessibility.** Screenshots in HTML, Word, PowerPoint, Markdown and +Confluence exports get alt text from the step title, such as "Screenshot for +step 3: Click Save". PDFs aren't tagged for screen readers. ## 5. Organize your library @@ -209,11 +225,10 @@ The library is your home screen. Each one shows how long it has left. To keep them longer, or until you empty the trash yourself, use **Settings → General → Trash**. -StepForge shows its menus and messages in your system's language when it has -it: English, French, Spanish, Russian, Simplified Chinese or Japanese. The -translations other than English are in beta. To pick a different language, -use **Settings → General → Language**; StepForge reloads its window in the new -language, after saving your open guide. Exported guides stay in English. +StepForge uses your system's language if it's one of English, French, +Spanish, Russian, Simplified Chinese or Japanese (the translations are in +beta). To change it, use **Settings → General → Language**. Exported guides +stay in English. Guides live in your StepForge data folder. To keep them somewhere else, such as a larger drive, use **Settings → General → Guide storage**. StepForge copies @@ -225,14 +240,14 @@ and verifies your library before switching to the new location. images into one file. Anyone with StepForge can open it with **Import → Import a copy of a guide (.sfgz)…**. - **Linked guides** let several people work from one `.sfgz` on a shared - folder. StepForge saves back to the file and warns you if someone else is - saving it. If someone else saved since you last did, your changes are merged - with theirs instead of replacing them. + folder. StepForge saves back to the file, and if someone else saved it in + the meantime, it merges their changes with yours. - **Snapshots** are automatic backups of each guide. Open **More → Backups & snapshots…** to create one by hand or roll back. **Settings → Editor → Snapshots to keep** controls how many are kept. -- **Google Drive sync** keeps your library the same on all your computers. - See [Google Drive sync](GOOGLE_DRIVE.md). +- **Cloud sync** keeps your library the same on all your computers, with + Google Drive, OneDrive, Dropbox or Nextcloud. See + [Sync your guides between computers](CLOUD_ACCOUNTS.md). ## Keyboard shortcuts @@ -255,6 +270,10 @@ Press **Ctrl+/** for the quick-actions palette, or open ## Troubleshooting +**I can't find how to stop recording.** See [Stop recording](#stop-recording). +On Windows, the red dot is often hidden behind the **^** arrow beside the +clock. + **Clicks aren't creating steps on Linux.** Make sure you're on a GNOME Wayland session, that you logged out and back in after installing StepForge, and that you enabled the StepForge extension when prompted. If your desktop can't report @@ -271,13 +290,10 @@ with the hotkey or on a timer instead. | Windows | `%USERPROFILE%\StepForge` (`C:\Users\\StepForge`) | | Linux | `~/.local/share/stepforge` | -The exact folder is shown in **Settings → About**. You can move it under -**Settings → General → Guide storage**. Avoid folders that OneDrive, Dropbox, -Google Drive or Nextcloud sync; Guide storage warns you if you pick one. Use -StepForge's own sync (**Settings → Accounts**) to keep guides in step across -computers. -Older Windows versions used `%APPDATA%\stepforge`; a new version moves your -guides from there by itself. +The exact folder is shown in **Settings → About**, and you can move it under +**Settings → General → Guide storage**. Don't put it in a folder that +OneDrive, Dropbox, Google Drive or Nextcloud syncs: use StepForge's own sync +(**Settings → Accounts**) instead. Still stuck? [Open an issue](https://github.com/Twest2/StepForge/issues/new/choose) and include your operating system, StepForge version (from **Settings → About**), diff --git a/docs/GOOGLE_DRIVE.md b/docs/GOOGLE_DRIVE.md index b18553a6..89b0c788 100644 --- a/docs/GOOGLE_DRIVE.md +++ b/docs/GOOGLE_DRIVE.md @@ -1,221 +1,8 @@ # Sync guides with Google Drive -Google Drive sync keeps your StepForge library the same on every computer you -use. Sign in once on each machine and your guides, including screenshots, -annotations, and descriptions, follow you, along with the -[settings guides depend on](#settings-that-sync). +This page has moved. Google Drive, OneDrive, Dropbox and Nextcloud sync all +work the same way, so they're now covered on one page: +**[Sync your guides between computers](CLOUD_ACCOUNTS.md)**. -Sync is **optional and off by default**. StepForge works fully offline without it. - -Prefer another service? StepForge also syncs with OneDrive, Dropbox, and -Nextcloud or any WebDAV server; see [CLOUD_ACCOUNTS.md](CLOUD_ACCOUNTS.md). Everything -below about versions, conflicts, and freeing up space applies to all of them. - -## Connect your Google account - -1. Open **Settings → Accounts → Google Drive** and choose **Sign in with Google**. -2. Your browser opens. Pick your Google account and allow StepForge to store - its data in your Drive. If the browser doesn't open, or opens the wrong - one, choose **Open it again** or **copy the sign-in link** under the sign-in - button and paste the link into any browser on this computer. -3. StepForge comes back to the front. You'll see **Connected as** with your - email address, and your guides start syncing. You can close the browser tab. -4. On your other computer, install StepForge and sign in with the **same** - Google account. - -Changes in the Google Drive settings take effect immediately. You don't need -to press **Save**. - -> [!NOTE] -> **StepForge can only see its own files.** It uses a private, hidden area of -> your Drive reserved for the app, and has no access to your documents, -> photos, or anything else. For the same reason, StepForge's files don't appear -> in the normal Drive file list. - -## Everyday use - -There's nothing to do. StepForge uploads a guide a few seconds after you save -it and checks for changes from your other computers about every 30 seconds. - -The **Drive indicator** in the top bar shows what's happening (waiting, -syncing, up to date, or needs attention) and opens the Drive settings when -clicked. While a guide is uploading (↑) or downloading (↓), it shows a live -counter such as **Drive: ↓ 3.2 MB / 12.0 MB** with a progress line; hover it, -or open the Drive settings, to see the guide's name and the transfer speed. - -> [!TIP] -> Before switching computers, wait until the indicator shows the guide is up -> to date. - -- **Sync now** starts a sync immediately. -- **Automatically sync guides** pauses and resumes syncing on this computer. -- **Test connection** (under **Advanced**) checks sign-in and Drive access by - uploading, downloading, and deleting a small temporary file. It never - uploads a guide. - -## How changes are handled - -- **Edits from different computers are combined.** If you edit the same - guide on two computers before they sync, StepForge puts both sets of changes - into the one guide. Changes to different steps, to different parts of a step, - or to different annotations all survive. Steps added on either computer are - kept, and a step deleted on one computer is removed unless it was edited on - the other. This isn't live co-editing. -- **When both computers changed the same thing**, such as the same step - title, the change saved most recently is kept. If this computer had edits - that hadn't synced yet, its version from before the update is saved as a - *before-sync-merge* snapshot under **More → Backups & snapshots…** in the - editor, so nothing is lost. - Editing one description on both computers keeps the newer description; the - two texts aren't blended. -- **Your work isn't interrupted.** Updates from another computer wait until - you close the guide and stop recording. -- **Downloads are checked** before they replace anything, and the replaced - local copy is kept as a backup in your data folder. -- **Deleting a guide only deletes it on this computer.** The Drive copy - remains until you remove it from Drive (see below). -- **Going offline is fine.** Local edits are kept and sync resumes when you're - back online. - -### Settings that sync - -These settings follow your guides across computers: - -- **Global placeholders** (**Settings → Placeholders**) -- **Brand profiles**, with their logos, banners and fonts, and which profile - is active (**Settings → Branding**) -- **Recording shortcuts**: Capture and Pause/resume (**Settings → Capture → Hotkeys**). - Cleared shortcuts stay disabled; incoming changes take effect immediately. - -Other capture options, AI and guide storage stay on each computer. - -They're combined the same way as guides: changes to different placeholders or -fields within a brand profile on different computers all survive. A placeholder -or profile deleted on one computer is deleted on the others unless another -computer edited it. When both computers changed the same value, the most recent -edit to that value is kept; changing capture options or another placeholder -doesn't make an older choice newer. A computer syncing for the first time adds -its placeholders and profiles to the ones already in the cloud. Conflicting -explicit choices use the same newest-edit rule, including a deliberate reset -to a default. Its untouched defaults never replace a choice made on another computer. - -Changes from another computer wait while **Settings** is open, so saving it -can't undo them, and arrive when you close it. - -If a settings version is damaged or needs a newer StepForge, settings sync -shows an error and leaves the saved settings alone. Guide sync continues. -StepForge doesn't skip that settings version, because publishing a merge -without it could discard values it couldn't read. - -## Manage what's in Drive - -**Settings → Accounts → Google Drive** also lets you see and tidy up your Drive storage. - -**Storage.** StepForge's Drive folder is hidden, so this is the only place to -see how much space it uses. The bar splits usage into latest versions, -previous versions, and recovery copies of deleted guides. - -**Free up space** deletes all previous versions after you confirm. The latest -version of every guide is always kept. Deleted versions can't be recovered. -It also switches versions saved as full copies by older StepForge releases to -space-saving versions (see [How versions are stored](#how-versions-are-stored)), -and removes files no version uses any more. - -### How versions are stored - -Each version stores **only what changed**. A screenshot is uploaded once and -shared by every version (and every guide) that contains it, so fixing a typo -uploads a few kilobytes instead of the whole guide. Downloads work the same -way: a computer only fetches the screenshots it doesn't already have. - -- This is how StepForge saves every new version. There's nothing to turn on. -- Every version you can see under **Versions** can still be restored in full. -- Versions saved as full copies by an older StepForge keep working. Choose - **Free up space** to switch them over; each one is downloaded and uploaded - once. -- Files that no version uses any more are removed automatically after a - sync, and right away by **Free up space**. A file uploaded in the last hour - is left alone, in case another computer is still saving the version that - uses it. - -> [!IMPORTANT] -> Update StepForge on **every** computer that syncs with the same Google -> account. Older releases can't read space-saving versions: they show a sync -> error for those guides instead of changing them. They also don't combine -> edits, and may still save separate *conflict copy* guides. - -**Guides in Drive** lists every guide stored in Drive, including ones that -aren't on this computer. - -- **Versions** shows a guide's latest version and up to two previous ones. - **Restore** puts an earlier version back. Close the guide and stop any - recording first. Your current local copy is backed up before it's replaced. -- **Download** installs a guide that's only in Drive onto this computer. -- **Delete from Drive** permanently removes all of a guide's Drive versions - after confirmation. Your local copy is kept and stops syncing. Other computers - that still sync the guide may upload it again. - -**Recently deleted** holds recovery copies of deleted guides, which you can -restore or delete permanently. - -### Make this computer the source of truth - -If your computers have drifted apart and you want one of them to win, use -**Advanced → Replace Drive with this computer**. After confirmation, StepForge: - -1. Deletes everything StepForge has stored in Drive, including all versions - and recovery copies. -2. Uploads the guides and [settings](#settings-that-sync) on this computer. -3. Tells your other computers to move any guide that isn't on this computer - to their trash, and to update the rest to this computer's version. - Unsynced edits on those computers are combined with this computer's version. - -**Automatically sync guides** must be on to use this. - -> [!WARNING] -> Replacing Drive can't be undone. Make sure this computer has everything you -> want to keep. - -## Disconnect - -Choose **Disconnect** to sign this computer out. Syncing stops and the saved -sign-in is removed. Your guides stay on this computer and in Drive. - -To revoke StepForge's access completely, remove it from -[your Google account's third-party connections](https://myaccount.google.com/connections). - -## Limits - -- Each guide keeps its **latest version plus up to two previous versions** in - Drive. Older versions are removed automatically after a successful sync. -- A single guide can be up to **256 MB**. Very large guides on slow - connections may take more than one attempt. -- The first sync of a guide sends all of it. After that, only new or changed - files are sent. - -## Privacy and security - -- Sign-in happens in your own browser on Google's website. StepForge never sees - your Google password. -- The access token is stored encrypted using your operating system's - credential storage. -- Guides are sent over HTTPS and stored in your Google account. They aren't - additionally encrypted by StepForge, so treat them like any other file in - your Drive. - -See the [privacy policy](PRIVACY.md#optional-google-drive-sync) and -[security overview](SECURITY.md) for details. - -## Troubleshooting - -| Problem | What to do | -| --- | --- | -| Sign-in finishes but StepForge says Drive access wasn't granted | Choose **Sign in with Google** again and leave the Google Drive permission ticked on Google's consent page. | -| "Google sign-in is unavailable in this build" | You're running a development build. Install an official release. | -| The indicator shows *needs attention* | Open **Settings → Accounts → Google Drive** to see the error. For sign-in problems, choose **Sign in again**. | -| A guide from another computer hasn't arrived | Make sure that computer finished syncing, then choose **Sync now**. Close the guide if it's open here. | -| Drive is full | Choose **Free up space**, or free up space elsewhere in your Google account. | - ---- - -*Maintainers: see [Google sign-in release configuration](cloud_accounts_init_setup/GOOGLE_DRIVE_RELEASE.md).* +Google Drive's own details are under +[Service details → Google Drive](CLOUD_ACCOUNTS.md#google-drive). diff --git a/docs/PRIVACY.md b/docs/PRIVACY.md index 04df0e1c..6ed37c90 100644 --- a/docs/PRIVACY.md +++ b/docs/PRIVACY.md @@ -1,16 +1,22 @@ # Privacy **Short version:** StepForge keeps your guides on your computer. It has no -accounts, collects no analytics, and doesn't contact the internet unless you -turn on Google Drive sync, connect GitHub to share guides, point AI at a remote -server, or press **Check for updates**. If you connect an AI agent such as -Claude or Codex, that agent sends what it reads to its AI provider. +accounts and collects no analytics. It only goes online when you use one of +these optional features: + +- syncing with Google Drive, OneDrive, Dropbox or Nextcloud +- sharing a guide on GitHub Pages, or publishing it to Confluence or Wiki.js +- AI, if you point it at a server on another computer +- **Check for updates**, when you press it + +If you connect an AI agent such as Claude or Codex, that agent sends what it +reads to its AI provider. ## What StepForge never does - No telemetry, analytics, or crash reporting. - No automatic update checks, license checks, or "phoning home". -- No uploads unless you sign in to Google Drive or publish a guide to GitHub. +- No uploads, except by the optional features listed above. - No downloading code or components while it runs. ## What StepForge stores on your computer @@ -132,7 +138,7 @@ agents edit your guides** and connect an agent such as Claude Code or Codex ## Optional Google Drive sync Drive sync is **off by default**. When you sign in -([how it works](GOOGLE_DRIVE.md)): +([how it works](CLOUD_ACCOUNTS.md)): - Sign-in happens in your browser on Google's site. StepForge never sees your password. @@ -141,8 +147,8 @@ Drive sync is **off by default**. When you sign in other Drive files. - **Your whole library is uploaded**: screenshots, text, annotations, placeholders, and the capture details listed above, along with your global - placeholders, brand profiles (with their logos, banners and fonts), and - configured Capture and Pause/resume keyboard shortcuts. It + placeholders, brand profiles (with their logos, banners and fonts), interface + language, and configured Capture and Pause/resume keyboard shortcuts. It goes to that private folder in *your* Google Drive, not to StepForge or anyone else. The rest of Settings isn't uploaded. Screenshots are stored once and shared between versions, labelled with a @@ -163,7 +169,9 @@ Drive sync is **off by default**. When you sign in never uploads a guide. - Turning sync off stops transfers. **Disconnect** also removes the saved sign-in. Neither deletes guides from your computer or from Drive. Deleting a - guide locally doesn't delete it from Drive. + synced guide removes its versions from Drive and moves it to the Trash on + your other computers; one recovery copy stays in Drive until you delete it + under **Recently deleted**. - To remove everything StepForge stored in Drive, revoke its access in your [Google Account](https://myaccount.google.com/connections), then in Google Drive open **Settings → Manage apps**, find StepForge, and choose @@ -300,9 +308,7 @@ Windows deletes when you uninstall it. Older Windows versions kept the library in `%APPDATA%\stepforge`. A new version copies it to `%USERPROFILE%\StepForge` on its first start, checks the -copy, and keeps the old folder as a backup until you remove it yourself. -StepForge never deletes it automatically: another installation may still use -that folder. +copy, and keeps the old folder as a backup until you delete it yourself. **Keep the library out of folders that OneDrive, Dropbox, Google Drive or Nextcloud sync,** such as a Documents folder that OneDrive backs up. Those apps diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 85fa6b7d..c17ba5d7 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -7,16 +7,17 @@ steps to reproduce it. **Don't open a public issue or pull request** for security problems, so users aren't exposed before a fix is available. Fixes are released as a new version on every distribution channel (GitHub -Releases, Chocolatey, APT, and DNF), so keeping StepForge updated is the best -way to stay protected. +Releases, the Microsoft Store, Chocolatey, APT, and DNF), so keeping StepForge +updated is the best way to stay protected. ## Security at a glance - **Offline by default.** Capture, editing, OCR, and export make no network connections. There's no telemetry, license check, or automatic update check. -- **Opt-in networking only.** AI, Google Drive sync, and GitHub sharing are - off until you turn them on, and **Check for updates** runs only when you - press it. All are described in the [privacy policy](PRIVACY.md). +- **Opt-in networking only.** AI, cloud sync, GitHub sharing, and Confluence + and Wiki.js publishing are off until you turn them on, and **Check for + updates** runs only when you press it. All are described in the + [privacy policy](PRIVACY.md). - **Sandboxed interface.** The app's window runs in Chromium's sandbox with no direct access to your files, the network, or credentials. - **Untrusted files are validated.** Imported guides, templates, and images are @@ -94,21 +95,14 @@ checksums. - **Guides aren't encrypted at rest.** They're protected by your user account's file permissions, like any other documents. If you need to send a guide securely, encrypt the `.sfgz` with a separate tool. -- **Linked-guide locks are advisory.** When several people open the same - `.sfgz` on a shared folder, a `.lock-sfgz` file is created next to it - while someone is saving. It records who is saving, not who has the guide - open, and it isn't a security boundary: a crashed or hostile client can - remove it. Saving while someone else holds it is refused unless the user - chooses to save anyway. Each save also re-reads the shared file. If someone - else saved it since you last did, their changes and yours are merged - instead of one replacing the other, and StepForge tells you. When both of - you changed the same value, the more recently edited version wins that one - value and the toast reports the number of conflicts. Because the lock is - advisory, two saves can still run at the same moment, and the later one may - miss the other's changes until the next save merges them. A backup of the - guide is taken before each merge. +- **Linked-guide locks are advisory.** When several people share one `.sfgz` + on a shared folder, a `.lock-sfgz` file next to it marks who is + saving. It isn't a security boundary: a crashed or hostile client can remove + it. Each save re-reads the shared file and merges in anyone else's changes, + taking a backup first, but two saves at the same moment can still miss each + other's changes until the next save. - **Screenshots contain what was on screen.** Review and blur sensitive - information before sharing. - A blur's area is filled only from the pixels around it, so exported and - published images keep nothing of what it covers. Unlike a real blur or - pixelation, it can't be reversed by blurring guesses until one matches. + information before sharing. A blur fills its area only from the pixels + around it, so exported and published images keep nothing of what it covers. + Unlike a real blur or pixelation, it can't be reversed by blurring guesses + until one matches. diff --git a/docs/WIKIJS.md b/docs/WIKIJS.md index c7309c77..78524cc9 100644 --- a/docs/WIKIJS.md +++ b/docs/WIKIJS.md @@ -46,22 +46,15 @@ and then the 6-digit code from your authenticator app: shows now and choose **Verify**. You don't need a code each time you publish. StepForge keeps your Wiki.js -session, encrypted like your password, and Wiki.js renews it while you use -it. Wiki.js renews a session that's been unused for up to 14 days by default -(your administrator can change this under **Administration → Security**). +session, encrypted like your password, and Wiki.js renews it while you use it. StepForge asks for a code again when Wiki.js has ended your session, for -example after a longer break, or if an administrator signed you out: +example after about two weeks without publishing, or if an administrator +signed you out. **Publish to Wiki.js** then asks for the code and carries on, +and **Settings → Accounts → Wiki.js** shows a code field. -- **Publish to Wiki.js** asks for the code, then carries on publishing. -- **Settings → Accounts → Wiki.js** shows **Signed out on the wiki** with a - code field. - -If two-step verification is turned off for your account later, StepForge -notices the next time it signs in, and stops asking for codes. - -If your account doesn't have two-step verification set up yet and the wiki -requires it, set it up on the wiki in your browser first, then sign in here. +If the wiki requires two-step verification and you haven't set it up yet, set +it up on the wiki in your browser first, then sign in here. ## API keys @@ -122,12 +115,8 @@ those edits." - **Publish anyway** replaces the page with the guide. - **Cancel** keeps the wiki's version. -If your account can write pages but not manage them, Wiki.js doesn't tell -StepForge who made the edit, so the question leaves the name out. - -StepForge also asks before replacing a page it didn't publish from this guide. - -Tags added to the page on the wiki are kept when it's updated. +StepForge also asks before replacing a page it didn't publish from this +guide. Tags added to the page on the wiki are kept when it's updated. ## Permissions diff --git a/docs/cloud_accounts_init_setup/GOOGLE_DRIVE_RELEASE.md b/docs/cloud_accounts_init_setup/GOOGLE_DRIVE_RELEASE.md index 5a60fd7a..539aaf0a 100644 --- a/docs/cloud_accounts_init_setup/GOOGLE_DRIVE_RELEASE.md +++ b/docs/cloud_accounts_init_setup/GOOGLE_DRIVE_RELEASE.md @@ -3,7 +3,7 @@ # READ THIS If you are a user, you do not need to read any of this. This is for maintainers or AI agents to understand Google Drive integration with the app. Again, if you -are a user, please see [google_drive.md](../GOOGLE_DRIVE.md) +are a user, please see [CLOUD_ACCOUNTS.md](../CLOUD_ACCOUNTS.md) *For StepForge maintainers.* Users never need any of this: they click **Sign in with Google**, pick an account, and allow access. Never ask a user for a client @@ -112,7 +112,7 @@ registration before each release that touches sync: the other, edits flow both ways, and editing on both before syncing produces a conflict copy. - [ ] **Versions → Restore**, **Free up space**, and **Delete from Drive** - behave as described in [GOOGLE_DRIVE.md](../GOOGLE_DRIVE.md). + behave as described in [CLOUD_ACCOUNTS.md](../CLOUD_ACCOUNTS.md). - [ ] **Disconnect** stops syncing and keeps local and Drive guides. References: [OAuth for desktop apps](https://developers.google.com/identity/protocols/oauth2/native-app), diff --git a/docs/getting_started_with_ai.md b/docs/getting_started_with_ai.md index 726bbc75..79390b69 100644 --- a/docs/getting_started_with_ai.md +++ b/docs/getting_started_with_ai.md @@ -58,37 +58,25 @@ Open a guide and choose **AI ▾** in the toolbar, next to **More ▾**: | Choose | AI writes | | --- | --- | -| **Write the whole guide** | The title, description, and blocks of every step. Then it makes substeps where steps belong together and adds placeholders for values that repeat, and finally writes the guide's own title and description. | +| **Write the whole guide** | Every step's title, description, and blocks, then the guide's own title and description. It can also group steps into substeps and add placeholders for repeated values. | | **Write the whole step** | The selected step's title, description, and blocks. | | **Write the title** | The selected step's title. | | **Write the description** | The selected step's description. | -| **Write the blocks** | The selected step's notes, warnings, tips, and code. It rewrites the blocks you have and adds at most two new ones when the step needs them. | +| **Write the blocks** | The selected step's notes, warnings, tips, and code. It rewrites the blocks you have and may add up to two more. | - **Your writing is kept.** If you already wrote a title or description, AI - polishes your wording instead of replacing it with something new. It never - deletes a block. -- **You can undo a whole-guide run.** Before writing the whole guide, - StepForge saves a snapshot. To undo, choose **More → Backups & snapshots** - and restore the snapshot labeled **before AI**. Global placeholders AI added - live in **Settings → Placeholders** and stay after a restore. -- **You can undo a single-step write.** After AI writes one step, its title, - its description or its blocks, press Ctrl+Z to get your old text back. -- **AI uses your placeholders.** It sees your global placeholders and this - guide's placeholders, and writes the `[[name]]` token wherever a - placeholder's value would appear in a description or block. Titles keep - plain words, so the step list stays readable. A paragraph that holds only a - placeholder, such as `[[stepforge]]`, stays exactly where you put it. -- **AI can add placeholders.** When you write the whole guide, AI may add up to - three placeholders for specific values that appear in two or more steps, - such as a course code, product name, or web address. Most become guide - placeholders (**More → Guide placeholders**); a value about your - organization, such as its name, may become a global one - (**Settings → Placeholders**). It never changes or removes a placeholder you - already have. -- **AI can make substeps.** When you write the whole guide, AI may make a few - steps substeps of the step that starts their task, such as the clicks inside - a dialog that step opened. It never changes the order of your steps, and it - only nests one level deep, like 3.1. + polishes your wording instead of replacing it. It never deletes a block. +- **You can undo it.** After AI writes one step, press **Ctrl+Z**. Before it + writes the whole guide, StepForge saves a snapshot: to undo, open + **More → Backups & snapshots** and restore the one labeled **before AI**. + Global placeholders it added stay in **Settings → Placeholders**. +- **It uses your placeholders.** Where a placeholder's value would appear in a + description or block, AI writes `[[name]]` instead. Step titles keep plain + words. +- **It can add placeholders and substeps** when it writes the whole guide: up + to three placeholders for values that repeat, such as a product name or web + address, and one level of substeps for clicks that belong together. It never + reorders your steps or changes a placeholder you already have. - **You can stop at any time.** While AI is writing, the button shows its progress, such as **AI · 3/12**. Choose it, then **Stop writing**. diff --git a/docs/linux/linux_install.md b/docs/linux/linux_install.md index 3ec80366..39e2ff2e 100644 --- a/docs/linux/linux_install.md +++ b/docs/linux/linux_install.md @@ -37,9 +37,11 @@ Then, to record: 1. Open or create a guide and start a capture session. 2. If GNOME asks, allow the StepForge extension. 3. Choose the monitors to share. Pick every monitor you'll click on. -4. StepForge minimizes and **StepForge REC** appears in the top panel. +4. StepForge minimizes and **● StepForge REC** appears at the top right of + the screen. 5. Click through your task. Each click becomes a step. -6. Stop from **StepForge REC** or from the StepForge window. +6. To stop, click **● StepForge REC**, then **Stop recording**. StepForge + comes back with your steps. **Good to know** diff --git a/docs/windows/chocolatey.md b/docs/windows/chocolatey.md index 166ccee0..e3d463da 100644 --- a/docs/windows/chocolatey.md +++ b/docs/windows/chocolatey.md @@ -38,12 +38,12 @@ StepForge is installed for all users and appears in the Start menu. Head to The easiest way: in StepForge, open **Settings → About**, press **Check for updates**, then **Update now**. StepForge saves your work and closes, Windows -asks for administrator approval, and a PowerShell window titled **Updating -StepForge** runs `choco upgrade stepforge -y` (StepForge only, nothing else -installed through Chocolatey). When it's done, StepForge opens again as a -normal app. If you decline the approval prompt, StepForge stays open and -nothing changes. If the update fails, the window says why, shows Chocolatey's -exit code and stays open until you press Enter; Chocolatey's own log is +asks for administrator approval, and Chocolatey updates StepForge (and nothing +else). Then StepForge opens again. If you decline the approval prompt, nothing +changes. + +If the update fails, the **Updating StepForge** window says why and stays open +until you press Enter. Chocolatey's log is `C:\ProgramData\chocolatey\logs\chocolatey.log`. **Update now** appears only when StepForge is registered with Chocolatey, @@ -67,43 +67,41 @@ Updates keep your guides, settings, and Google Drive sign-in. ## Already installed from the .exe? -The setup wizard has an **Updates** page with **Keep StepForge updated with -Chocolatey**, checked by default. If Chocolatey isn't installed, it reads -**Install Chocolatey and keep StepForge updated with it**. Leave it checked -and, after the files are copied, the installer does the following (if you -install only for yourself, Windows first asks for administrator approval once; -an all-users install already has it): - -1. Installs Chocolatey, if it is missing. -2. Adds the `stepforge` feed, unless a source with that URL already exists. -3. Tells Chocolatey which StepForge version you just installed, without - running the installer again. - -After that, **Settings → About → Check for updates → Update now** updates -StepForge, and so does `choco upgrade stepforge -y`. Installed with an -older installer that has no **Updates** page? Run the latest installer once; -your guides and settings are kept. Notes: - -- **Internet access is needed**, and registering downloads the StepForge - package from the feed once. That package contains the whole installer - (about 100 MB). +The setup wizard's **Updates** page has **Keep StepForge updated with +Chocolatey**, checked by default. Leave it checked, and once the files are +copied the installer installs Chocolatey if needed, adds the StepForge feed, +and registers the version you just installed. From then on, **Update now** and +`choco upgrade stepforge -y` both work. If you install only for yourself, +Windows asks for administrator approval once. + +Installed with an older installer that has no **Updates** page? Run the latest +installer once. Your guides and settings are kept. + +Good to know: + +- **It needs internet access**, and downloads the StepForge package (about + 100 MB) from the feed once. - If you installed **only for you**, the first Chocolatey update turns it into an **all-users** install. Your guides, settings, and sign-in are kept. -- **If it doesn't work** (you decline the approval prompt, you're offline, IT - policy blocks it, or you're on a development or prerelease build that isn't - on the feed), StepForge is still installed and the wizard says so and where - the log is, normally `C:\ProgramData\StepForge\chocolatey-setup.log`. You can set it up - later with the [install steps](#install) above, or by running - `choco install stepforge --version --source=stepforge -y --skip-automation-scripts`. -- Silent installs (`/S`) skip this unless you also pass `/chocolatey`, for - example `"StepForge Setup .exe" /S /allusers /chocolatey`. Run it - from an administrator prompt, or Windows shows an approval prompt even - though the install is silent. The installer never does this when - Chocolatey itself is running it. +- **If it doesn't work** (you declined the approval prompt, you're offline, IT + policy blocks it, or it's a prerelease build that isn't on the feed), + StepForge is still installed, and the wizard tells you where the log is, + normally `C:\ProgramData\StepForge\chocolatey-setup.log`. You can set it up + later with the [install steps](#install) above. - Uninstalling from **Apps & Features** also removes StepForge from - Chocolatey, so `choco upgrade` doesn't bring it back. If StepForge was - installed only for you, Windows asks for administrator approval for this. - Silent uninstalls (`/S`) leave the Chocolatey registration alone. + Chocolatey, so `choco upgrade` doesn't bring it back. + +### For IT admins + +- Silent installs (`/S`) skip the Chocolatey setup unless you also pass + `/chocolatey`, for example + `"StepForge Setup .exe" /S /allusers /chocolatey`. Run it from an + administrator prompt, or Windows shows an approval prompt even though the + install is silent. The installer never does this when Chocolatey itself is + running it. +- Silent uninstalls (`/S`) leave the Chocolatey registration alone. +- To register an installed version with Chocolatey by hand, run + `choco install stepforge --version --source=stepforge -y --skip-automation-scripts`. ## Switching from the regular installer diff --git a/docs/windows/microsoft-store.md b/docs/windows/microsoft-store.md index 75aebf38..93eecb23 100644 --- a/docs/windows/microsoft-store.md +++ b/docs/windows/microsoft-store.md @@ -1,5 +1,13 @@ # Install StepForge from the Microsoft Store + The Microsoft Store is the recommended way to install StepForge on **Windows 10 (version 1809 or later) and Windows 11, 64-bit**. Microsoft checks and signs the package, so Windows shows no **Windows protected your @@ -60,24 +68,26 @@ Your guides come with you, and there's nothing to move by hand: installed it with Chocolatey. Your guides stay on your computer. 2. Install StepForge from the Store, as above. -Older versions kept guides in `%APPDATA%\stepforge`. The first time a new -version starts, it copies them to `%USERPROFILE%\StepForge`, checks that every -file arrived intact, and only then opens from there, with all your guides and -settings. If anything goes wrong, it keeps using the old folder, so nothing is -lost. It retries at the next start when it can safely do so. If a failed -rollback leaves two different copies, Guide storage explains how to recover -without overwriting either copy. The old folder stays as a backup until you -remove it yourself; another installation may still use it. - -If you clean up that backup, first check that no other StepForge installation -uses it. Remove only the old `library`, `settings`, `cloud` and `shared-links` -folders. Keep `library-location.json` and Electron's profile files in place. - > [!IMPORTANT] > Keep only one of the two installed. Having both gives you two StepForge > entries in the Start menu, each updating separately, and only one of them can > move your guides to the new folder. +Older versions kept guides in `%APPDATA%\stepforge`. The first time a new +version starts, it copies them to `%USERPROFILE%\StepForge`, checks the copy, +and only then switches over. If anything goes wrong, it keeps using the old +folder, so nothing is lost, and tries again next time. The old folder stays as +a backup until you delete it. + +
+Deleting the old %APPDATA%\stepforge folder + +First make sure no other StepForge installation still uses it. Then delete only +its `library`, `settings`, `cloud` and `shared-links` folders. Leave +`library-location.json` and Electron's own files in place. + +
+ ## AI agents The Store version adds a `stepforge.exe` command to your PATH, and the setup in @@ -97,4 +107,4 @@ folder if you want them gone too. | --- | --- | | StepForge isn't found in the Store | Check that you're on Windows 10 version 1809 or later, 64-bit. On a work or school PC, the Store may be turned off by your organization; use the [Windows installer](../windows_installation.md) instead. | | **Check for updates** shows a newer version, but the Store has no update yet | Microsoft checks each release before the Store offers it, which can take a day or two. Try again later. | -| **Settings → General → Guide storage** says your guides are still in `%APPDATA%\stepforge` | StepForge couldn't move them, so it keeps using that folder and nothing is lost. The message says why. It retries ordinary failures; if two different copies remain, choose an empty folder in Guide storage or combine the copies manually before trying again. If `C:\Users\\StepForge` already holds a library from the other version, uninstall one of the two, then [open an issue](https://github.com/Twest2/StepForge/issues/new/choose) if you need both libraries combined. | +| **Settings → General → Guide storage** says your guides are still in `%APPDATA%\stepforge` | StepForge couldn't move them, so it keeps using that folder and nothing is lost. The message says why, and StepForge tries again at the next start when it safely can. If `C:\Users\\StepForge` already holds guides from another StepForge install, uninstall one of the two, and [open an issue](https://github.com/Twest2/StepForge/issues/new/choose) if you need both libraries combined. | diff --git a/docs/windows_installation.md b/docs/windows_installation.md index e291cefb..5f1f41e4 100644 --- a/docs/windows_installation.md +++ b/docs/windows_installation.md @@ -82,14 +82,11 @@ users** of this computer. Installing for all users needs administrator rights. ![The install location page](steps-windows_installation/008-select-next.png) **2.6** On the **Desktop Icon** page, click **Next**. On the **Updates** -page, leave **Keep StepForge updated with Chocolatey** checked to be able to -update with **Update now** in Settings → About, or `choco upgrade stepforge`, -later (see -[Already installed from the .exe?](windows/chocolatey.md#already-installed-from-the-exe)), -then click **Install**. If you install only for yourself, Windows asks for -administrator approval once for this; if you decline, StepForge is still -installed. Installing only for yourself becomes an all-users install on the -first Chocolatey update. +page, leave **Keep StepForge updated with Chocolatey** checked so you can +update later with one click, then click **Install**. If Windows asks for +administrator approval and you decline, StepForge is still installed, just +without Chocolatey updates +([more about this option](windows/chocolatey.md#already-installed-from-the-exe)). ![The Install button](steps-windows_installation/009-select-install.png) @@ -108,21 +105,17 @@ These are for the `.exe` installer. For the Store version, see [Updates](windows/microsoft-store.md#updates) and [Uninstall](windows/microsoft-store.md#uninstall). -**To update,** open **Settings → About** and press **Check for updates**. If -you left the Chocolatey option on during setup, press **Update now**: StepForge -closes, installs the new version with Chocolatey after you approve the -administrator prompt, and opens again (or run `choco upgrade stepforge -y` -yourself, see [Update](windows/chocolatey.md#update)). Otherwise, download the +**To update,** open **Settings → About** and press **Check for updates**. +If you kept the Chocolatey option during setup, press **Update now** and +approve the administrator prompt; StepForge updates and opens again (see +[Update](windows/chocolatey.md#update)). Otherwise, download and run the newest installer from -[Releases](https://github.com/Twest2/StepForge/releases/latest) and run it; -keep **Keep StepForge updated with Chocolatey** checked to get **Update now** -from then on. Your guides and settings are kept either way. - -Earlier versions kept guides in `%APPDATA%\stepforge`. The first time -a new version starts, it moves them to `%USERPROFILE%\StepForge` by itself: -it copies them, checks the copy, and only then switches. The old copy stays -in place until you remove it yourself. Keep it if another installation still -uses that folder; StepForge never deletes it automatically. +[Releases](https://github.com/Twest2/StepForge/releases/latest). Your guides +and settings are kept either way. + +Earlier versions kept guides in `%APPDATA%\stepforge`. A new version moves +them to `%USERPROFILE%\StepForge` by itself and leaves the old folder as a +backup until you delete it. **To uninstall,** open **Settings → Apps → Installed apps**, find **StepForge**, and choose **Uninstall**. Your guides stay in