# GI JI Cross-Platform Test Guide

This is the owner-facing test guide for the 0.12 release candidate. It keeps
customer data out of testing and makes the current platform limits explicit.

## Ground Rules

- Test with the supplied public sample files or your own non-sensitive copies.
- Do not put an OpenAI API key, a license key, a client file, or a personal
  chat transcript in a screenshot, support email, or bug report.
- Record the machine model, RAM, operating-system version, GI JI version,
  selected local models, and the exact failed step for every issue.
- Before testing a new build, keep the prior GI JI folder untouched. The install
  helper places GI JI at one fixed per-account location and re-verifies whatever
  it finds there, so move or rename a live knowledge base before installing a
  different build over it.
- If the launcher says another GI JI/Qdrant library is already using the local
  service, stop the older GI JI test folder first. Do not force the new test
  folder to reuse it: that could mix two separate libraries.
- Both OpenAI model discovery and approved Connected AI requests honor
  `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. Model discovery sends the bearer
  API key but no library content. A TLS-inspecting proxy may see that key and
  the approved question or topic and selected passages or excerpts. If a proxy
  is configured, test Connected AI only through one trusted with both.
- Plain text, Markdown, HTML, and `.docx` need no separate document reader.
  A PDF test requires Poppler's `pdftotext`; GI JI does not include OCR. Record
  a missing `pdftotext` message as setup friction, not as a successful PDF
  import.

## What A Passing Test Means

For every supported Mac release, the tester can:

1. Set GI JI up by running `GI JI Installer` once, then open GI JI from the
   folder that run named, with nothing to click past on the way.
2. Add two harmless files using **Balanced** import, including one ordinary
   `.docx` with selectable text. If `pdftotext` is installed, also import one
   text-based PDF and open a passage from it.
   Give both the same optional **Collection** (your shelf) and different
   optional **Perspectives** (each source's lens). Confirm the original titles
   and source files remain unchanged in **Your library**. On a second disposable
   pair, choose **Deeper review**, **Inside this collection**, and **Important
   differences**. Confirm the import remains private and any result appears in
   the Review inbox rather than becoming approved knowledge.
3. Ask a question whose answer is present and open the cited passage.
4. Confirm Sources only stops when a supporting answer is missing.
5. Confirm a candidate stays separate until explicitly approved.
6. On **Teach GI JI**, create one Working Knowledge draft from the two test
   sources. Choose a relationship, confirm **Private on this computer** and
   **Connected AI** have equal visible choices, and keep the private choice for
   this step. Open both cited excerpts, edit the note, choose its category, mark
   it **40-60% Supported**, and approve it with a short reason. In Guided mode,
   ask a related question and confirm the note is labelled as approved knowledge
   rather than an original source. In Sources only, confirm the note is ignored.
7. Remove one supporting test source. Confirm the working note changes to
   **Needs source review** and no longer helps answers. Do not remove a real
   source just for this test.
8. In **Your library**, choose one harmless test source and select **Find
   connections**. Confirm GI JI first shows a small local shortlist. Select
   exactly which sources to connect and choose whether to examine an agreement,
   difference, contradiction, or any useful relationship. Prepare a private
   candidate, open every supporting source/excerpt, and confirm it is still
   waiting for review. Pause it, confirm it leaves active use, resume it, then
   reject/remove the disposable candidate. This is separate from **Discover
   broad themes**, which is unavailable below 200 passages because it is for a
   large library.
9. Optional Connected AI check: use a buyer-owned API key only. Select the
   same local shortlist, choose **Connected AI**, and confirm the preview states
   the provider/model, relationship category, one request, topic, and only the
   selected excerpts. Approve once, then confirm the result is a candidate with
   source references and never an original source. Do not repeat with sensitive
   material.
10. Create a local backup, stop GI JI, restart it, and confirm the library is
   still present.
11. Confirm the Free-tier screen shows the 20-document and three-active-note
   limits, without a non-working activation form before checkout is configured.
12. Confirm Connected AI setup says that setup is not approval. A real request
   is optional and must use the tester's own key only. For a Working Knowledge
   draft, check that the preview contains only the topic and selected source
   excerpts before approving it.
13. After Freemius is configured in sandbox: activate a Personal license on one
   Mac, restart it offline, and confirm a simultaneous activation on another
   computer is refused. Deactivate the first Mac, then activate its replacement.
   Record activation counts only; GI JI does not report document, chat, or usage
   data.

## Automated Retained Seeded Acceptance

Run the portable seeded suite before the visual steps on each native platform.
It uses Python 3.10 or newer from the standard library only. Run it against a
GI JI folder the install helper has just placed, or the exact retained B6 QA
folder. Do not run it against a personal or client library.

The manifest is
`scripts/fixtures/qa/seeded-release-manifest.json`. It checksum-verifies and
imports three controlled Project Aurora files, then exercises the universal
crawler with a bounded public-domain Steiner work on Wikisource. That URL is
acceptance data only: no Wikisource- or Steiner-specific rule exists in the
production crawler. The crawler uses `path` scope, depth 1, and a hard limit of
13 content requests so the complete retained suite still fits beside the four
existing B6 documents at the Free-tier 20-document limit.

The suite then checks:

- fast, balanced, and deeper local preparation without automatic approval;
- indexed document integrity and bounded crawler coverage;
- a grounded multi-source answer with citations;
- refusal of an unsupported fact;
- a cited answer from the crawled Steiner material;
- one local Working Knowledge item that remains an unapproved candidate;
- one new backup and optional archive checksum;
- launcher restart, retained-library recovery, retained license state, and
  clearing of a session-only Connected AI key; and
- optionally, exactly two bounded Connected AI previews.

The runner has no send/approve option. It rejects keys and approval tokens,
accepts only a loopback GI JI API address, and records zero raw answers.
`--connected-previews` still sends **zero** OpenAI requests; it only checks what
GI JI would show for approval. Real OpenAI requests and license
activation/deactivation remain separate, explicitly approved QA batches.

First validate the runner without changing the app:

```bash
python3 scripts/qa-seeded-release.py --self-test
python3 scripts/qa-seeded-release.py --plan
```

On macOS or Linux, with GI JI running:

```bash
python3 scripts/qa-seeded-release.py --run \
  --app-root "/absolute/path/to/GI JI"
```

On Windows PowerShell, from the source/QA bundle:

```powershell
py -3 scripts\qa-seeded-release.py --self-test
py -3 scripts\qa-seeded-release.py --plan
py -3 scripts\qa-seeded-release.py --run `
  --app-root "C:\absolute\path\to\GI JI"
```

If a buyer-owned OpenAI key is already held in the running app session and the
owner has approved preview-only QA, add `--connected-previews`. Never put the
key on the command line or in this repository.

The sanitized result is written under the git-ignored
`.giji-qa/evidence/seeded-release/` directory. It includes manifest and answer
hashes, counts, timings, citation/refusal booleans, backup metadata, and restart
evidence. It does not include keys, approval tokens, raw answers, or user
documents. The admitted sources and candidate remain in the test library so
the owner can immediately perform the visual checks below.

An automated pass proves only the native machine on which it ran. A macOS Intel
pass is not a Windows, Linux, or macOS ARM pass, and cross-compilation is not
native validation.

## Mac Clean-Machine Test

### Intel Mac

1. Use `GI-JI-0.12.0-mac-intel.dmg` only on an Intel Mac.
2. Open the disk image. Confirm exactly two things appear: the `GI JI` folder
   and `GI JI Installer`.
3. Double-click `GI JI Installer`. Confirm a window opens by itself and shows
   the four named steps in plain words, that it asks for no password, and that
   it names `~/Applications/GI JI` as the place GI JI will live.
4. Watch step 3 of that run. If Ollama is absent, confirm the helper downloads
   and verifies its own pinned copy rather than failing. Confirm no AI model is
   downloaded at any point, and record the wall-clock time of the whole run.
5. Confirm the run ends with the installed message, that it names the folder GI
   JI is in, and that `INFO/INSTALL-REPORT.txt` exists there.
6. Open `~/Applications/GI JI` and double-click `GI JI.command`. Confirm GI JI
   says in plain words which AI models it is missing, downloads them with
   visible progress, and opens in the browser. Record the wall-clock time of
   that download on a known connection speed. Interrupt it once and reopen GI
   JI: confirm it carries on rather than starting over.
7. Complete the passing test above, then use GI JI's in-app power control.
   Confirm the app and this folder's search index stop cleanly.
8. Double-click `GI JI.command` again. Confirm it starts and the test library
   remains intact.
9. Separately, double-click `GI JI.command` inside the `GI JI` folder on the
   disk image itself, before any install. The disk image cannot be written to,
   so the launcher stops there and GI JI itself never starts. Confirm it
   explains plainly that GI JI is running from a read-only disk and needs to be
   copied onto the Mac first, rather than failing obscurely — as a dialog when
   one can be shown, otherwise as that same sentence in the terminal. This is
   deliberately *not* the "setup isn't finished" message, which only appears
   once GI JI is in a writable folder. Record which of the two you saw, and if
   it was a dialog, record exactly what it offered and where it said it would
   put GI JI.

### Apple Silicon Mac

Repeat the same process with `GI-JI-0.12.0-mac-arm64.dmg` on an M-series
Mac. This is a required release gate even when the build was produced on an
Intel Mac. Record whether the selected local model feels usable, but do not
change the product claim to "fast" from one machine result.

## Linux Technical Validation

Linux is a technical package and a useful test environment, not the first
commercial storefront release.

1. Use a clean Linux x86-64 machine with a browser installed. Ollama is required;
   Poppler's `pdftotext` is additionally required for PDF import. The package
   includes its native search index.
2. Extract `GI-JI-0.12.0-linux-amd64.tar.gz`. Confirm the extracted folder holds
   exactly the `GI JI` folder and `GI JI Installer`.
3. Run the install helper once:

   ```bash
   "./GI JI Installer"
   ```

4. Confirm it works through the same four named steps, installs to
   `~/.local/share/GI JI`, installs and confirms Ollama, and ends with the
   installed message naming that folder. It must not download any AI model.
5. Start GI JI from its top-level executable inside that folder:

   ```bash
   ./GIJI
   ```

   Confirm the bundled search index starts and the browser opens.
6. Run the same passing test using harmless files.
7. Use GI JI's in-app power control and confirm the app and this folder's
   search index stop. Record any dependency or launcher friction as a Linux
   packaging issue, not a customer-release claim.

## Windows Portable Technical Test

Windows now has a portable clean-machine test package, but it is still
**experimental and not a customer storefront release**. It is not yet a signed
MSIX installer and must not be sold or uploaded to Microsoft Store.

1. Use a clean Windows 11 x64 machine.
2. Choose **Extract All** for `GI-JI-0.12.0-windows-amd64.zip` and extract the
   complete package into a new writable folder. Confirm it holds exactly the
   `GI JI` folder and `GI JI Installer.exe`. Double-click:

   ```text
   GI JI Installer.exe
   ```

3. Because this test build is unsigned, confirm the package keeps its honest
   warning and use **More info → Run anyway** if SmartScreen appears.
4. Confirm the helper works through the same four named steps, asks for no
   administrator password, installs to `%LOCALAPPDATA%\Programs\GI JI`,
   installs and confirms Ollama, and ends with the installed message naming that
   folder. It must not download any AI model. Confirm GI JI, its search index,
   and Ollama remain on loopback. If the PDF check is used, install Poppler first and record
   the exact method; GI JI does not bundle `pdftotext` in this build.
5. Open the installed folder and double-click `GI JI.exe`. Confirm GI JI opens
   in the browser.
6. Run the same harmless-file tests above, including restart, backup, and a
   copied-folder check. Activation must identify the same Windows installation
   after restart and must refuse a copied license cache on another computer.
7. Use GI JI's in-app power control. Confirm it stops the app and this folder's
   search index; there is no separate stop script in the package.
8. Record setup friction, path-with-spaces behavior, the install helper's
   download times, antivirus warnings, browser opening, backup/restore, and
   removal of the installed folder.

Windows becomes sellable only after code signing, activation-transfer testing,
an uninstallable MSIX/store package, and a second clean-machine pass.

## Report Template

Use this exact outline in a support email or note:

```text
GI JI version:
Machine and CPU:
RAM and operating system:
Selected local models:
Test step:
Expected result:
Actual result:
Exact error or screenshot (with private data removed):
Can the test continue? yes/no
```
