From 029fe24428825535b13f8663d14cb8b1233f47fb Mon Sep 17 00:00:00 2001 From: McAtk <16798627+atk0309@users.noreply.github.com> Date: Fri, 2 Oct 2026 10:13:39 -0700 Subject: [PATCH] Clarify solo preview installation and first practice Identical tree to locally validated 8279d49d1fa38a023a57191bdf7b5239b2d33860. References #119 and #121; consumer release gates remain open. --- .github/ISSUE_TEMPLATE/bug_report.yml | 7 +- README.md | 29 +- SECURITY.md | 16 +- SUPPORT.md | 31 +- docs/content-authoring.md | 48 ++- docs/release-candidate.md | 23 ++ docs/solo-installation.md | 361 ++++++++------------- docs/solo-maintenance.md | 105 ++++++ docs/troubleshooting.md | 81 ++++- src/app/onboarding/page.tsx | 3 +- src/components/exam/ExamApp.tsx | 12 +- src/components/exam/OnboardingWizard.tsx | 36 +- tests/unit/exam-app-resilience-ui.test.tsx | 3 + tests/unit/onboarding-wizard-ui.test.tsx | 12 +- 14 files changed, 466 insertions(+), 301 deletions(-) create mode 100644 docs/solo-maintenance.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 4e47c65..e869f72 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -37,6 +37,7 @@ body: attributes: label: Affected role options: + - Solo personal study - Student - Parent - Self-hoster or administrator @@ -48,8 +49,8 @@ body: id: environment attributes: label: Environment - description: Include browser, operating system, Node version, and hosting details that matter. - placeholder: Chromium 126, Ubuntu 24.04, Node 22... + description: Include browser and OS versions, and whether you use the solo package or a household/source install. Node version is only needed for source installs. + placeholder: Browser version, OS edition/version, solo preview or source install... validations: required: true @@ -83,4 +84,4 @@ body: id: logs attributes: label: Sanitized logs or screenshots - description: Remove secrets, email addresses, tokens, and family data before attaching anything. + description: Remove keys, cookies, launch URLs, personal paths, answers and study material. Do not attach databases, config folders or backups. diff --git a/README.md b/README.md index 2dd2d61..1330d9f 100644 --- a/README.md +++ b/README.md @@ -7,19 +7,19 @@ as a separate, more involved setup. ## Start with personal study -The new **solo launcher** runs Examify on this computer only. It opens your browser -and creates your private study profile without email, invitations or routine login. -The sample has five fixed questions and deterministic scoring, with no AI. -Choose **Try a sample exam**, then **Create your question bank** for the guided -subject → material → AI → generate/review/Apply workflow. Return anytime to add more. - -This is a **preview implementation**, not a published desktop release. Platform -packages must pass the clean-install checks before release. See the -[personal-study installation guide](docs/solo-installation.md) for the package -layout, verification and current acceptance requirements. Windows x64 and Linux -x64 packages bundle the tested Node runtime and application dependencies; they -are designed to require no manual Git, Node, pnpm, Docker or administrator setup. -macOS is outside this preview's scope. +The solo launcher opens Examify in your browser without email or routine login. +Choose **Try a sample exam** for five fixed questions and scoring that needs no AI. +Reopen Examify to resume unfinished practice or see saved results. When you are +ready, **Create your question bank** guides you through adding material, choosing +AI, generating questions and reviewing them before Apply. + +**There is no published desktop release yet.** Windows x64 and Linux x64 preview +packages bundle Node and dependencies; no Git, pnpm, Docker or administrator setup +is needed. Actual consumer OS/browser support still needs verification. macOS and +ARM are outside this preview. + +[Get the preview and try your first exam](docs/solo-installation.md) · +[Back up, upgrade or remove it](docs/solo-maintenance.md) ## Optional household setup @@ -53,7 +53,8 @@ provider. Local hosting alone does not keep AI requests local. - [Household install and first login](docs/installation.md) - [Install with your preferred AI agent](docs/agent-installation.md) - [Configure sign-in, mail and AI](docs/configuration.md) -- [Deploy, update, back up and restore](docs/operations.md) +- [Solo backup, recovery and uninstall](docs/solo-maintenance.md) +- [Household deployment, updates and backups](docs/operations.md) - [Troubleshooting](docs/troubleshooting.md) - [Add or generate questions](docs/content-authoring.md) - [Ingest CLI reference](tools/examify-ingest/README.md) diff --git a/SECURITY.md b/SECURITY.md index 0c0513b..65ae423 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -5,17 +5,29 @@ practice data, so security reports are taken seriously. ## Supported versions -Only the latest `main` is supported. There are no maintained release branches. +There is no published desktop release yet. Security fixes target the latest +`main` and its Windows/Linux x64 previews. There are no maintained release branches. +Report the affected package version and source commit or preview run when known. ## Reporting a vulnerability Please report vulnerabilities **privately** via GitHub Security Advisories: open the -repository's **Security** tab and choose **"Report a vulnerability"**. Please do not +repository's **Security** tab and choose **"Report a vulnerability"** +([private report form](https://github.com/atk0309/project_Examify/security/advisories/new)). Please do not open a public issue or PR for a security problem. Include what you can: affected route/action, reproduction steps, and impact. You should get an initial response within a week. +## Solo packages + +Keep the installation, backups, saved provider keys, browser cookies and one-use +launch URLs private. Solo is loopback-only and assumes a trusted computer; it is +not a shared-server sign-in replacement. Use the [solo guide](docs/solo-installation.md#keep-your-work-private-and-safe) +for its local-service limits and [full-folder backup instructions](docs/solo-maintenance.md). +The source-checkout commands and family-data layout below are for household +installations, not a recipe for copying solo state generations. + ## Scope notes for self-hosters - Household membership in SQLite is the credential store and privacy boundary — treat diff --git a/SUPPORT.md b/SUPPORT.md index 564b9fb..0046ea2 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,21 +1,20 @@ # Support -Thanks for using Examify. Before opening an issue, search the existing issues and check -the [installation guide](docs/installation.md) and -[troubleshooting](docs/troubleshooting.md). +For personal study, start with [Windows/Linux installation](docs/solo-installation.md) +and [troubleshooting](docs/troubleshooting.md). Shared servers have a separate +[household guide](docs/installation.md). -Use the issue form that matches your request: +There is no published desktop release yet. Current help covers the latest `main` +and its Windows/Linux x64 preview packages; there are no maintained release +branches or verified minimum consumer OS/browser versions. Support is +community-provided, with no guaranteed response time. -- **Bug report:** reproducible behavior that appears incorrect. -- **Feature request:** a concrete improvement and the problem it would solve. -- **Question:** setup, self-hosting, content-authoring, or usage help. +Search [existing issues](https://github.com/atk0309/project_Examify/issues) first, +then choose a bug report, question or feature request. Include the package version +or source commit, OS/browser version, steps to reproduce, and a short safe error +message. Packaged users do not need to install Node or pnpm to report a problem. +See [safe diagnostics](docs/troubleshooting.md#what-to-include-in-a-support-request). -Examify supports the latest `main` branch only. Community support is best-effort and -has no guaranteed response time. - -Please use the correct private or moderated channel for sensitive reports: - -- **Security vulnerabilities:** follow [`SECURITY.md`](SECURITY.md) and use GitHub's - private vulnerability-reporting flow. -- **Conduct concerns:** follow [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Never post - sensitive personal information in a public issue. +Never post keys, launch URLs, cookies, backups, databases, answers or study files. +Report vulnerabilities privately through [SECURITY.md](SECURITY.md), not a public +issue. For conduct concerns, follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). diff --git a/docs/content-authoring.md b/docs/content-authoring.md index 4ddfeb7..0372dde 100644 --- a/docs/content-authoring.md +++ b/docs/content-authoring.md @@ -1,29 +1,40 @@ # Add or generate questions -For initial family setup, use `/onboarding`. Skipped setup can be resumed through -**Finish content setup** on the parent dashboard. Once you choose Finish, the -wizard cannot be reopened; use the CLI below for later content changes. You do -not need to edit TypeScript or install the ingest CLI separately. - ## Use the setup wizard -1. Add a subject with a unique ID and a name your family recognises -2. Upload the subject's PDFs. Notes/text and images can also be placed in its - family-data subject folder using the CLI workflow below -3. Choose an AI provider and Generate. Check [provider prerequisites](configuration.md#ai-for-question-banks-and-marking) -4. Review the generated questions, answers and source references. Correct - mistakes before using them with students -5. Open Review to inspect the changes, then Apply. Generate alone does not - publish questions. Apply makes family questions available without a rebuild +**Solo:** choose **Create your question bank** on the practice page. You can return +after Finish to add more subjects or material. **Household:** use `/onboarding` +for initial setup, or **Finish content setup** on the parent dashboard if you +skipped it. After household setup is finished, use the CLI below for later changes. + +1. Add a subject with a unique ID and a name you recognise +2. Upload PDFs (up to 8 MiB each). Solo also accepts UTF-8 `.txt`/`.md` notes + (up to 1 MiB each); household text sources use the CLI workflow below. + Uploading stores them locally; it does not start generation +3. Choose an AI provider and Generate. Check [provider prerequisites](configuration.md#ai-for-question-banks-and-marking). + For a local endpoint, save its URL and model in AI settings before returning +4. Validate the draft format. This checks whether Examify can use the draft, + not whether its answers are correct +5. Open Review to inspect the planned file changes, then Apply. Generate alone does not make + questions available for practice. Apply does not need an app rebuild Cancel leaves the current subject's previous question-bank file unchanged. If generating several subjects, those already completed remain saved. Replacing existing questions requires confirmation. Reusing a built-in subject ID replaces -that entire subject; choose a new ID if you want to keep both. +that entire subject; choose a new ID to keep both. The sample remains unless you +explicitly choose to replace it. + +The wizard's Review screen shows counts and file changes, not an editor for every +question and answer. For an accuracy check before Apply, inspect the private +`content/subjects/SUBJECT_ID/bank.ir.json` in the active data folder with a local +text editor. It contains questions, answers, rubrics and source references; never +share it in a public issue. Check those against your material, especially scanned +pages and diagrams. If you change a draft, Validate and Review again before Apply. +[Solo data locations](solo-maintenance.md#find-your-files) · +[Household data locations](operations.md). -AI output is a draft. Check accuracy, difficulty and marking rubrics against the -source material, especially diagrams, tables and scanned pages. Keep source PDFs -private unless you have permission to redistribute them. +Keep uploaded material private unless you have permission to share it. Generating +questions can send it to your chosen AI provider; see [privacy](privacy.md). ## Where questions live @@ -41,7 +52,8 @@ and logs a reason. Run `pnpm examify:data verify` to check family data. ## CLI workflow -Run commands from the checkout. These examples use the default `./data` folder; +These commands are for household/source installations, not the portable solo package. +Run them from the checkout. These examples use the default `./data` folder; substitute your configured `EXAMIFY_DATA_DIR` when it is elsewhere. Use an existing family subject, or create `data/content/subjects/history/` and put your notes or images there. For PDFs, create `data/content/source-pdfs/history/` and place them diff --git a/docs/release-candidate.md b/docs/release-candidate.md index 59e5f7a..ae40e8f 100644 --- a/docs/release-candidate.md +++ b/docs/release-candidate.md @@ -90,6 +90,29 @@ ordinary-user consumer tests without development tools installed: tool/source identity and findings; a failed Dependabot update alone is not a vulnerability, and package-manager audit is not complete binary analysis +## First-run help and accessibility check + +Use the [personal-study guide](solo-installation.md) as written, with the exact +candidate artifact. Record pass/fail and safe error codes for each OS/browser: + +- Complete the sample, stop the launcher, reopen and find the saved result. + Repeat with an unfinished sample and confirm the answer and question position +- Create a bank, Apply, stop/reopen and check the new bank, earlier results and + provider configuration. Add a second subject without replacing the first +- Use only the keyboard through sample, results and authoring. Check visible + focus, file selection, AI choices, Back/Skip and confirmation dialogs +- At 200% browser zoom, check readable text and reachable controls on practice, + results and every authoring step, including long filenames and validation errors +- Check that a screen reader announces step changes, errors and completion +- Follow backup/restore and removal instructions using disposable data. Verify + that removing a shortcut does not remove data, and recovery uses a full copy +- Verify the private vulnerability-report form is available to a signed-in + reporter before public release; a link in SECURITY.md is not that verification + +Do not infer these results from unit tests, substituted browser callbacks or CI +runner names. Fix launch-blocking accessibility failures and record the remaining +limits; this is a bounded first-run check, not an accessibility certification. + Artifacts remain unsigned. Checksums establish consistency with the chosen installer; an attacker replacing both installer and archive can replace hashes. Before publication, the maintainer must approve unsigned distribution or a diff --git a/docs/solo-installation.md b/docs/solo-installation.md index ac62443..c05f41b 100644 --- a/docs/solo-installation.md +++ b/docs/solo-installation.md @@ -1,222 +1,143 @@ # Personal study on Windows and Linux -## Preview status - -This branch introduces the solo launcher and platform packaging. No release is -published by the packaging workflow. Do not treat a successful unit test, a mock -installer run or a Linux build as proof that Windows installation works. Release -readiness requires the real packaged acceptance job on each supported OS. - -Initial targets are Windows x64 and Linux x64. macOS and ARM packages are not -part of this change. Download only an explicitly versioned Examify package and -its matching installer from an authorized release or preview artifact. The -installer must verify its pinned archive digest before unpacking or execution. -There is no `latest` or moving-main executable download in this flow. - -## Use a verified preview package - -Once the platform CI job produces a passing artifact, extract that artifact into -an ordinary folder. Keep the version-pinned installer and archive together. Do -not run the unsubstituted installer templates directly from a source checkout. - -- **Windows:** open Command Prompt in that folder and run `install.cmd`. Run as - your ordinary account, not Administrator. The private default install location - is `%LOCALAPPDATA%\Examify`; use the resulting Examify shortcut to reopen it -- **Linux:** run `bash install-solo.sh --archive ./examify-VERSION-linux-x64.tar.gz` - with the actual matching archive name. The default is - `${XDG_DATA_HOME:-$HOME/.local/share}/examify`. The installer creates a desktop - application entry and a relaunch script; it does not require sudo - -Keep the launcher terminal open while practicing. Ctrl+C stops the local service; -closing the browser alone does not. Reopening the shortcut uses the existing -running instance and opens a fresh browser session safely. There is no automatic -background service or silent updater in this preview. The installer supports fresh installs and same-version repairs. Upgrade-capable -packages also support an explicit upgrade to a higher stable numeric version -(for example, `0.1.0` to `0.2.0`) using that version’s verified installer. Stop -the launcher first. The original preview format cannot be upgraded in place; -keep that installation and use a separate empty folder. A same-version preview -repair does not convert it into an upgrade-capable installation. -Existing household upgrades still use `install.sh --upgrade`. - -## What the launcher does - -- Uses the bundled, pinned Node runtime and prebuilt dependencies, including the - native SQLite binding for that OS; no manual Git, Node, pnpm or compiler setup -- Stores your data and settings separately from replaceable application versions -- Starts a loopback-only local service and opens the browser with a one-use local - launch capability, exchanged for a private session -- Provides a relaunch shortcut. Keep the launcher running during practice; stop it - normally before backing up, copying or removing an installation - -The local URL is only for this computer. Do not share the launch URL, proxy it to -the internet, bind it to a LAN address or use it as a shared school/family server. -This mode assumes a trusted personal computer. Other people using the same OS -account can access its files and running app. Browser cookies are scoped to a -host, not a TCP port: another local service on 127.0.0.1 can receive local cookies -if you browse to it. Solo is not a security boundary against hostile software or -other untrusted local services/users on the machine. Use the authenticated -household deployment behind HTTPS when stronger shared-machine isolation is -needed; separate OS accounts alone do not fix the browser host/port limitation. - -## First practice - -Choose **Try a sample exam** on the practice page. It uses the same five fixed -multiple-choice questions, choices and deterministic answer-key scoring, without -AI generation or marking. No account, email setup, -invitation, AI provider or payment is needed. Select an answer, finish the exam -and review the result. Unfinished exams autosave; reopening through the launcher -keeps your progress and offers your unfinished exam. - -**Create your question bank** opens the guided subject → material → AI → generate → review/Apply workflow. Uploading stores the -file locally. Generating questions is a separate, explicit operation: review and -Apply before generated questions become available. The built-in sample stays -available. After finishing, return to **Create your question bank** to add another subject or -material. Existing questions and progress are retained; replacement and Apply -still need explicit review. Household first-run completion keeps its existing -behavior. AI provider settings remain available from the practice page. - -The material step accepts PDFs up to 8 MB, or UTF-8 `.txt`/`.md` notes up to -1 MB. Notes must contain readable text; binary files and empty notes are refused. -Files are stored privately using safe names. Uploading a different file with the -same name retains the earlier file and adds a numbered copy. After selecting -**Local endpoint**, use **Configure endpoint URL and model** to enter both values -in AI settings, then return to the question-bank wizard. Your subjects and -uploaded material are retained while you configure the provider. - -## AI is optional - -The sample multiple-choice practice works without AI. Written-answer AI marking -and question generation require a provider you choose. Cloud providers receive -selected source material or written answers; bring your own API key or supported -account and check that provider's charges. A “local” endpoint is only local if you -actually run it on this computer. Remote endpoints and account-backed command -line tools may still send data to a cloud provider. Examify never silently switches -providers. See [privacy](privacy.md) and [configuration](configuration.md). - -### PDF support and external tools - -- **Anthropic API** and **Claude Code** send PDFs directly to their provider -- **OpenAI API** sends PDFs directly to a PDF-capable model (the default is - `gpt-4o`); the combined PDF input for one subject must be below 50 MB -- **Local endpoint** and **Codex** need the external `pdftoppm` tool for PDF-only - material. It is not bundled with this preview. UTF-8 text notes avoid that - dependency; a real local model still needs to be installed and running -- Local command execution is host-configured in household installations. The - solo launcher's private provider settings do not accept executable commands - -The offline acceptance provider used by tests is not a bundled model or a -production fallback. The tests select an actual loopback HTTP endpoint through -AI settings, upload text notes, and exercise generation, review, Apply and study. -They do not demonstrate real-model question quality or install `pdftoppm`. - -The solo UI does not load the household analytics or remote font resources. -Installing/downloading the application itself requires internet access. - -## Existing families and shared access - -Keep using [household installation and upgrades](installation.md). Solo mode -refuses to adopt an existing household database and does not migrate household -accounts into an unauthenticated shared app. Keep the data folders separate. -Household mode continues to require sign-in and mailbox proof for invitations. - -## Before a release is ready - -On clean Windows and Linux machines, verify the actual distributed package: - -1. Install as an ordinary user without Git, Node or pnpm on PATH; paths containing - spaces must work. Verify archive digest rejection before executable startup -2. Launch, open the browser, redeem the capability, and start a sample exam -3. Submit and persist a result, close/relaunch, and resume unfinished work -4. Reject forged Host, cross-origin requests, reused tokens and access to the - internal Next server without the gateway secret -5. Confirm no household setup/mail/account screens block first practice -6. Retain private data and configuration across relaunch and version replacement -7. Refuse an existing household database without changing its contents -8. Run the household and existing migration suites to guard upgrades -9. Create a subject, upload study notes, select/configure a local endpoint, - generate, review and Apply, then complete an exam from that bank. Repeat for - a second subject after completion, retaining both banks and earlier progress - -No paid AI calls or real credentials are needed for this acceptance checklist. - -## Upgrade safely - -Run the new version-pinned installer against the same installation folder, with -Examify stopped. There is no automatic download or silent downgrade. CI preview -labels and prereleases are not ordered as upgrade versions. The first public -upgrade-capable package must have a version never used by a legacy preview. - -An upgrade or upgrade-capable same-version repair: - -1. Acquires OS-released installation, launcher and database-worker locks. PID - numbers alone are never evidence that an installation is stopped -2. Preserves the entire previous data/config generation, including SQLite WAL, - material, question banks, results, provider settings and authentication secrets -3. Makes a private, hash-checked candidate copy and requires free space for twice - the copied bytes plus a 128 MiB migration reserve, after package extraction -4. Migrates and starts the actual new application against the candidate, without - opening a browser. It stops all verification workers before activation -5. Replaces one installation pointer, selecting the complete matching app and - study-state generation together. The ordinary shortcut resolves that pointer - -Migration, startup or preactivation interruption leaves the previous pair -selected. Orphan candidate folders may remain; they are never automatically -adopted or deleted. Re-running the verified installer prepares a fresh candidate. -After activation, no automatic rollback occurs: newer work might already exist. -Directly running an inactive supported version refuses to open study data. - -Use a local filesystem owned by your ordinary OS account. Network shares, -cloud-synced installation folders, links/junctions, hard-linked study files and -shared/foreign-owned state are unsupported. Keep adequate disk space; the reserve -is a safety check, not a bound on every future migration’s requirements. If a -fresh install is interrupted before it creates its installation marker, use a -new empty folder. A damaged immutable bootstrap fails closed and needs recovery -into a separate folder; repair does not overwrite its running Node executable. - -The automated checks cover process interruption. They do not simulate physical -power failure or failing storage. In particular, Windows ordinary-user Node APIs -do not provide a proven durable directory-commit guarantee; keep an independent -backup before upgrading. This feature does not claim guaranteed recovery from -sudden power loss on Windows. - -## Back up or recover a solo installation - -Stop Examify and copy the **whole installation folder** to a private location. -This retains the installation pointer, matching application/runtime, all state -generations, configuration and recovery metadata. After an upgrade, `data` and -`config` at the root can be an older snapshot: copying only those folders can -miss current work. Keep backup copies private; they include authentication -secrets and saved provider keys. Never publish or share them. - -To recover, retain the damaged installation unchanged, restore the complete -known-good backup into a separate private folder, and launch its `Examify` or -`Examify.cmd` entrypoint. Do not overlay old app files onto a newer database or -manually change just the version field. Recovery to a pre-upgrade backup loses -changes made after that snapshot; preserve the newer installation for possible -recovery of that work. Never run two copies against the same data directory. - -The retained previous generation and its matching release provide a recovery -source, not a second automatically active installation. The previous pointer is -recorded in `installation.json`, and candidate `backup-source.json` records the -source snapshot’s hashes. Advanced selective recovery requires keeping that -matched pair together in a separate folder; there is no one-click rollback or -automatic old-generation cleanup in this release. - -The `.examify-operations` databases are coordination files, outside study state. -Do not remove them while an operation is active. Stale process markers after a -crash do not require manual deletion. The household `examify:data` backup command -does not capture this complete solo layout; use the full-folder backup above. - -## Portable image behavior and release evidence - -Portable Windows/Linux builds omit Next's unused automatic image optimizer and -its Sharp/libvips dependencies. Existing practice, raw PDF/text uploads and AI -source processing retain their separate paths; optional PDF rasterization still -uses external `pdftoppm`. Portable installs do not offer automatic image resizing, -compression or format conversion. Hosted/default builds are unchanged. - -Portable artifacts remain previews until the [release gate](release-candidate.md) -is completed. CI runner coverage does not establish minimum consumer OS/browser -support. Actual shortcut/browser opening and download-warning checks are still -required. Installers are unsigned; checksums do not independently prove publisher -identity. Never disable system security to run an installer. +Examify runs on your computer and opens in your browser. Start with five fixed +sample questions: no account, email, AI provider or payment is needed. + +## Get the preview + +**There is no published desktop release yet.** Windows x64 and Linux x64 packages +are available only as expiring preview artifacts from successful +[Solo desktop preview runs](https://github.com/atk0309/project_Examify/actions/workflows/desktop-preview.yml). +Open a successful run for the commit you intend to test and download its +`examify-solo-win32-x64-COMMIT` or `examify-solo-linux-x64-COMMIT` artifact. GitHub +may require you to sign in. If the artifact has expired, ask the maintainer for a +verified replacement; do not use a guessed release URL. + +Extract the downloaded artifact into an ordinary folder. Keep its installer, +archive and checksum files together. Do not unpack the inner application archive +or run the installer templates from the source-code ZIP. The installer checks the +matching archive's pinned checksum before running it. + +These packages bundle Node and application dependencies. You do not need Git, +pnpm, Docker or a compiler. Use your ordinary account, without Administrator or +sudo. Choose local storage, not a network drive or cloud-synced folder. + +Windows needs PowerShell 5.1 or later. Linux needs Bash, tar, sha256sum and a +desktop with `xdg-open` and a default browser. No minimum consumer Windows/Linux +or browser version has been verified yet: Windows Server 2022 and Ubuntu 22.04 CI +runs are automated checks, not a consumer support claim. macOS and ARM are not +supported by this preview. + +Installers are unsigned. A checksum checks bytes, not who published them. Stop +if your browser or OS blocks the download or shows a security warning; do not +disable protection. See [download help](troubleshooting.md#download-is-blocked-or-the-checksum-does-not-match). + +## Install and open + +### Windows + +1. Open the extracted folder. It should contain `install.cmd`, `install.ps1` and + `examify-VERSION-win32-x64.zip`, all from the same artifact +2. Open an ordinary Command Prompt in that folder and run: + + ```cmd + install.cmd + ``` + +3. Keep the terminal open. Examify starts and opens your default browser + +The default location is `%LOCALAPPDATA%\Examify`. The installer adds **Examify** +to the Start menu. It uses the archive beside the installer; no release download +is needed when all three files are present. + +### Linux + +Open a terminal in the extracted folder. Run this with the **actual archive +filename** from that folder in place of `examify-VERSION-linux-x64.tar.gz`: + +```bash +bash install-solo.sh --archive ./examify-VERSION-linux-x64.tar.gz +``` + +Keep the terminal open. Examify starts and opens your default browser. The +installer adds **Examify** to your applications menu. The default location is +`${XDG_DATA_HOME:-$HOME/.local/share}/examify`. Supplying `--archive` avoids a +release download, so this also works offline after you have downloaded the files. + +## Try your first exam + +1. Select **Try a sample exam** on the practice page +2. Answer the five questions using **Next question**, select **Finish exam**, + then review your result +3. Select **Back to subjects**, start another sample, answer a question and + return with the home icon (**Back to subjects**). Your unfinished exam is saved so you can resume it + +The sample always uses the same questions and deterministic scoring. It does +not generate questions or send answers to AI. + +## Stop and come back + +Press **Ctrl+C in the launcher terminal** to stop Examify. Closing the browser +alone leaves it running. Open **Examify** from Start or your applications menu to +return; you can resume an unfinished exam and see saved results. Reopening while +it is running opens a fresh browser session in that same instance. + +If the shortcut is missing, open the installation folder and run `Examify.cmd` +on Windows or `./Examify` in a Linux terminal. Use that root entrypoint, not a +file inside `releases/`. Bookmarked launch links are single-use; reopen through +Examify instead. [Browser or startup problems](troubleshooting.md#personal-study-windowslinux-package). + +## Make your own question bank + +Choose **Create your question bank** from the practice page: + +1. Add a subject with a unique ID and a name you recognise +2. Upload a PDF (up to 8 MiB) or UTF-8 `.txt`/`.md` notes (up to 1 MiB). + Uploading only stores the file locally; it does not start generation +3. Choose and configure an AI provider. For **Local endpoint**, select + **Configure endpoint URL and model**, save both in AI settings, then return +4. Select **Generate questions**. When it finishes, choose **Validate** to open + the next screen, then **Validate** again to check the draft format. Select + **Next** for Review, then **Review plan** and inspect additions/replacements/deletions. + Select **Looks good**, then **Confirm apply** to make the bank available +5. Select **Next**, then **Back to practice** and choose your subject + +Return to **Create your question bank** to add more subjects or material. Your +existing banks and progress remain. Replacing questions needs explicit review; +the built-in sample stays available unless you explicitly replace it. **Optional AI settings** lets you change providers. +Review shows planned file changes, not a question editor; Validate does not check +answer accuracy. AI output can be wrong. [Question-bank help](content-authoring.md) +explains private draft inspection before using generated questions for study. + +### Choose AI only when you need it + +Generation and written-answer marking use the provider you choose. Cloud APIs +and account-backed tools may send material or answers to a cloud service and may +cost money. A local endpoint needs a model already running; a remote endpoint is +not private to your computer. Examify never silently switches providers. +[What leaves your computer](privacy.md). + +For a first bank, text notes avoid extra PDF tooling. Anthropic/Claude Code and +OpenAI can send PDFs directly to their provider; OpenAI needs a PDF-capable model +and less than 50 MB combined PDF input per subject. Codex and local vision +endpoints need the separate `pdftoppm` tool for PDF-only material. It is not +bundled. Local command execution is host-configured in household installations; +the solo settings do not accept executable commands. Tests use an offline +provider fixture, not a bundled model or evidence of real-model quality. + +## Keep your work private and safe + +[Back up, upgrade, recover or remove Examify](solo-maintenance.md). Back up the +whole installation folder while Examify is stopped; copying only root `data/` +can miss current work after an upgrade. Backups contain secrets and provider keys. + +The local service is for this computer only. Do not share its launch URL, expose +it through a proxy or use it as a school/family server. It assumes a trusted +personal computer: people using your OS account can access its files, and other +local services on `127.0.0.1` can receive host-scoped cookies. Separate OS accounts +do not fix that browser host/port limitation. For shared access, use the +[authenticated household setup](installation.md) behind HTTPS, with separate +data. Solo never adopts an existing household database. + +The [release checklist](release-candidate.md) tracks checks still needed before +public downloads, including real shortcut/browser opening and security warnings. diff --git a/docs/solo-maintenance.md b/docs/solo-maintenance.md new file mode 100644 index 0000000..5d580d5 --- /dev/null +++ b/docs/solo-maintenance.md @@ -0,0 +1,105 @@ +# Look after your Examify installation + +For the Windows/Linux solo preview. For household servers, use +[operations](operations.md) instead. [Back to first practice](solo-installation.md). + +## Find your files + +Unless you chose another folder, the whole installation is here: + +- Windows: `%LOCALAPPDATA%\Examify` (paste this into File Explorer) +- Linux: `${XDG_DATA_HOME:-$HOME/.local/share}/examify` + +`installation.json` selects the current application and study state. On a fresh +install, `data/` holds your database, materials and question banks, and `config/` +holds private settings. After an upgrade, the current `data/` and `config/` can +live inside the `states/` folder named by that file. Do not edit the pointer or +copy individual generations to repair an installation. + +## Back up or recover a solo installation + +Stop Examify and copy the **whole installation folder** to a private location. +This retains the installation pointer, matching application/runtime, all state +generations, configuration and recovery metadata. After an upgrade, `data` and +`config` at the root can be an older snapshot: copying only those folders can +miss current work. Keep backup copies private; they include authentication +secrets and saved provider keys. Never publish or share them. + +To recover, retain the damaged installation unchanged, restore the complete +known-good backup into a separate private folder, and launch its `Examify` or +`Examify.cmd` entrypoint. Do not overlay old app files onto a newer database or +manually change just the version field. Recovery to a pre-upgrade backup loses +changes made after that snapshot; preserve the newer installation for possible +recovery of that work. Never run two copies against the same data directory. + +The retained previous generation and its matching release provide a recovery +source, not a second automatically active installation. The previous pointer is +recorded in `installation.json`, and candidate `backup-source.json` records the +source snapshot’s hashes. Advanced selective recovery requires keeping that +matched pair together in a separate folder; there is no one-click rollback or +automatic old-generation cleanup in this release. + +The `.examify-operations` databases are coordination files, outside study state. +Do not remove them while an operation is active. Stale process markers after a +crash do not require manual deletion. The household `examify:data` backup command +does not capture this complete solo layout; use the full-folder backup above. + +## Remove the app without losing your work + +There is no uninstall command in this preview. Stop Examify with Ctrl+C first. +Keep a private copy of the **whole installation folder**, then remove its +original folder and shortcut. Keep that backup if you want to use your questions +and progress again; removing the original folder also removes the data inside it. + +- Windows: remove **Examify** from the Start menu. Its shortcut is `Examify.lnk` + in the folder opened by `shell:programs` in File Explorer +- Linux: remove `examify-solo.desktop` from + `${XDG_DATA_HOME:-$HOME/.local/share}/applications` + +Removing the shortcut alone only hides the app. To permanently remove study data +and saved provider keys too, also delete your installation copies and backups. +Emptying the Recycle Bin or Trash is irreversible through normal recovery. This +is not a secure-erasure guarantee, and deleting a saved key does not revoke it +at its provider. + +## Upgrade safely + +Run the new version-pinned installer against the same installation folder, with +Examify stopped. Legacy preview installations cannot upgrade in place: keep +them intact and use a separate empty folder. A same-version repair does not +convert that old format. There is no automatic download or silent downgrade. CI preview +labels and prereleases are not ordered as upgrade versions. The first public +upgrade-capable package must have a version never used by a legacy preview. + +An upgrade or upgrade-capable same-version repair: + +1. Acquires OS-released installation, launcher and database-worker locks. PID + numbers alone are never evidence that an installation is stopped +2. Preserves the entire previous data/config generation, including SQLite WAL, + material, question banks, results, provider settings and authentication secrets +3. Makes a private, hash-checked candidate copy and requires free space for twice + the copied bytes plus a 128 MiB migration reserve, after package extraction +4. Migrates and starts the actual new application against the candidate, without + opening a browser. It stops all verification workers before activation +5. Replaces one installation pointer, selecting the complete matching app and + study-state generation together. The ordinary shortcut resolves that pointer + +Migration, startup or preactivation interruption leaves the previous pair +selected. Orphan candidate folders may remain; they are never automatically +adopted or deleted. Re-running the verified installer prepares a fresh candidate. +After activation, no automatic rollback occurs: newer work might already exist. +Directly running an inactive supported version refuses to open study data. + +Use a local filesystem owned by your ordinary OS account. Network shares, +cloud-synced installation folders, links/junctions, hard-linked study files and +shared/foreign-owned state are unsupported. Keep adequate disk space; the reserve +is a safety check, not a bound on every future migration’s requirements. If a +fresh install is interrupted before it creates its installation marker, use a +new empty folder. A damaged immutable bootstrap fails closed and needs recovery +into a separate folder; repair does not overwrite its running Node executable. + +The automated checks cover process interruption. They do not simulate physical +power failure or failing storage. In particular, Windows ordinary-user Node APIs +do not provide a proven durable directory-commit guarantee; keep an independent +backup before upgrading. This feature does not claim guaranteed recovery from +sudden power loss on Windows. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e26911d..fa2ca4e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,8 +1,79 @@ # Troubleshooting -Start in the Examify checkout, as the user that runs the server. Keep the error -message, Node version and command you ran. Never include `.env`, outbox messages, -backup archives, student answers or study files in a public report. +## Personal study (Windows/Linux package) + +Start with the launcher window. You do not need Node, pnpm or a source checkout +to troubleshoot a packaged installation. Keep your installation folder intact. +[Install and reopen](solo-installation.md) · [Backup and recovery](solo-maintenance.md) + +### Download is blocked or the checksum does not match + +Preview artifacts expire. A missing artifact or release-download error does not +mean your computer needs developer tools. Download a complete matching artifact +from a successful run, extract it, and keep its installer and archive together. +On Linux, pass the archive filename with `--archive`; on Windows, keep +`install.cmd`, `install.ps1` and the ZIP together. + +For a checksum mismatch, download that same complete artifact again. Do not edit +the checksum, mix files from different runs or unpack and launch unchecked files. +If it still fails, report the artifact/run and safe error text. Installers are +unsigned; stop at browser, SmartScreen or organizational-policy warnings. Do not +disable security software or change system execution policy to get past them. + +### The browser did not open, or a saved link no longer works + +Choose a default browser in your OS settings. Linux also needs `xdg-open`. +Keep the launcher window open and open the **Examify** shortcut again. It creates +a fresh one-use browser session; a bookmark or copied launch link cannot do that. +If reopening fails, stop the launcher with Ctrl+C and launch again. Do not post +launch URLs or cookies in a support request. + +If the shortcut is missing, open the installation folder and run `Examify.cmd` +(Windows) or `./Examify` from a terminal (Linux). The installer prints this path. + +### Examify will not start, or says it is still running + +Use the launcher window's error, not a guessed `localhost:3000` address. Solo +chooses available local ports each time it starts; it does not need a public port +or firewall exception. Stop any Examify launcher you already opened, then retry. +Do not kill unrelated Node programs, delete lock files or expose the service to +your network. After a crash, relaunch normally; stale process markers do not need +manual deletion. + +For missing/damaged files, keep the installation and make a private backup before +repair. A verified same-version installer can repair application files, but a +damaged bootstrap needs [recovery into a separate folder](solo-maintenance.md#back-up-or-recover-a-solo-installation). +Do not delete the database to make startup succeed. A household-data refusal means +you must choose a separate solo folder, not remove the household marker. + +### My progress or question bank seems missing + +Reopen the same installation through its root launcher. A second installation +folder has separate data. After an upgrade, current data can live under `states/`; +the root `data/` may be an older snapshot. Do not move those folders around. +Generation alone does not add questions to practice: review and **Apply** first. +For unfinished practice, select the saved subject under **Continue where you left off**. [Restore a complete backup](solo-maintenance.md#back-up-or-recover-a-solo-installation) +if needed, preserving the newer installation and noting that later work will not +be in an older backup. + +### What to include in a support request + +- Package version (the `version` value in `installation.json`) and the preview + run link or source commit, if known. Do not attach the whole installation +- Windows edition/build or Linux distribution/version, x64 architecture, and + browser name/version +- What you selected or ran, what you expected, and what happened instead +- The short error code or message, with personal paths/usernames removed + +Never attach `.env`, `config/`, cookies, launch/invite URLs, backups, databases, +provider keys, answers or uploaded material. Inspect screenshots for private +content before sharing. Do not post raw logs without checking them. Use +[private security reporting](../SECURITY.md) for suspected vulnerabilities. + +## Household or source installations + +The commands below are for a source checkout, as the OS user running the server. +Packaged solo users should use the steps above instead. ## `pnpm start` cannot find package.json @@ -61,8 +132,8 @@ Turnstile key pairs. See [configuration](configuration.md) and `.env.example`. ## AI unavailable or written answers not marked -The parent dashboard names the marking provider and its readiness. The household -admin can open **AI settings** (`/settings/ai`) to change the provider and refresh +In solo mode, open **AI settings** from practice. In household mode, the parent +dashboard names the provider and its readiness, and the admin can open **AI settings** (`/settings/ai`) to change the provider and refresh readiness, including after Finish. This checks configuration and CLI sign-in, not API-key validity or a paid provider request (see [configuration](configuration.md#change-ai-after-setup)). A CLI must be installed and signed in as the same OS user that runs Examify, including diff --git a/src/app/onboarding/page.tsx b/src/app/onboarding/page.tsx index da09af6..f942a4a 100644 --- a/src/app/onboarding/page.tsx +++ b/src/app/onboarding/page.tsx @@ -20,7 +20,8 @@ export const dynamic = 'force-dynamic'; export const metadata: Metadata = { title: 'Content setup', - description: 'Add subjects, attach study files, generate BankIR, and emit the question bank.', + description: + 'Add subjects and study files, generate draft questions, and review changes before using them.', robots: { index: false, follow: false }, }; diff --git a/src/components/exam/ExamApp.tsx b/src/components/exam/ExamApp.tsx index c2e1b2c..1e067b4 100644 --- a/src/components/exam/ExamApp.tsx +++ b/src/components/exam/ExamApp.tsx @@ -286,8 +286,8 @@ function Dashboard({ question bank next.

- Choose subjects → add study material → set up optional AI → generate, review and apply - → practise. Return anytime to add more. + To make your own bank, add a subject and study material, then choose an AI provider to + generate questions. Review the changes before Apply. Return anytime to add more.