# GI JI — the guide that comes with your copy

GI JI is a knowledge tool that runs on your own computer. You give it your
documents; it reads them and answers your questions **with citations back to
your own passages**. When your documents do not contain the answer, it says so
instead of inventing one. Nothing it learns is kept until you approve it.

Your documents, the index built from them and everything GI JI learns stay on
this computer, inside the GI JI folder.

---

## 1. What is in this download

Two things, side by side:

- **GI JI** — the app folder. It holds the program, the private search index it
  uses, and, once you start working, your library.
- **GI JI Installer** — sets GI JI up on this computer. You run it once.

## 2. Set GI JI up first

Double-click the installer (`GI JI Installer` on a Mac, `GI JI Installer.exe`
on Windows, `GI JI Installer` on Linux). A window opens and works through four
steps. It asks you nothing, and it never asks for a password — it installs GI
JI for your own account only and refuses to run as an administrator.

1. **Checking your computer.** Your operating system, free disk space (it needs
   6 GiB) and memory (8 GiB is the comfortable amount). It also names the folder
   GI JI will live in.
2. **Placing and verifying the app files.** It copies the GI JI folder that
   travelled beside it, checks every single file afterwards, and starts the
   bundled private search index once to prove it really runs here.
3. **Installing and confirming Ollama.** Ollama is the free program that runs
   the private AI on your computer. If you do not already have it, GI JI
   downloads a copy for itself. It then starts Ollama, confirms it answers, and
   stops it again.
4. **Writing your install report.** A plain record of everything above, saved as
   `INFO/INSTALL-REPORT.txt` inside the installed GI JI folder.

That is the whole installer. It does not download the AI models — GI JI does
that itself the first time you open it, where you can watch it happen and try
again if something goes wrong.

At the end it tells you plainly whether GI JI is installed, and where it is. If
it stops for any reason, it saves a plain report of what happened and shows you
that file's path, so there is one file to send to support@giji.agency.

## 2a. The first time you open GI JI

GI JI needs two AI models: `bge-m3`, which reads your documents, and
`qwen2.5:3b`, which writes the answers — about 4 GB for the pair. The first time
you open GI JI it downloads them, showing you the progress as it goes. That
needs the internet this one time.

If the download is interrupted, nothing is lost: open GI JI again and it carries
on from where it stopped. You can also finish it from inside GI JI, on the
Settings → Models screen.

Where GI JI is installed:

| Computer | Folder |
|---|---|
| Mac | `Applications` inside your own home folder — `~/Applications/GI JI` |
| Windows | `%LOCALAPPDATA%\Programs\GI JI` |
| Linux | `~/.local/share/GI JI` |

If setup is interrupted — the connection drops, you close the window — run the
installer again. It keeps everything that finished and picks up only what is
missing.

## 3. What needs the internet, and for how long

Only this one-time setup. The installer downloads Ollama if you do not already
have it — about 180 MB on a Mac, about 1.5 GB on Windows, about 1.4 GB on Linux
— and GI JI downloads its two AI models (about 4 GB together) the first time you
open it.

So the whole one-time download is roughly 4.2 GB on a Mac, and roughly 5.5 GB on
Windows or 5.4 GB on Linux. On a home connection expect somewhere between ten
minutes and two hours, depending on your speed.

After that, GI JI reads your documents and answers your questions with no
internet connection at all. The one exception is Connected AI, described in
section 8 — it is optional, off until you switch it on, and asks your permission
for every single request.

## 4. Opening GI JI

Open the GI JI folder the installer told you about, and double-click:

- **Mac** — `GI JI.command`
- **Windows** — `GI JI.exe`
- **Linux** — `GIJI`

GI JI starts its private search index, waits until everything is ready, and
opens itself in your browser at `http://127.0.0.1:8080`. That address is your
own computer; nothing is published to a network.

## 5. Stopping GI JI

Use the power control at the top of the GI JI window — the round power symbol.
It reads *Turn GI JI off — stops the app and its search index*. There is no
separate stop program to find.

## 6. If GI JI says setup isn't finished

If you open GI JI and see:

```text
GI JI setup isn't finished on this computer.
Please run "GI JI Installer" first — it sets up the private AI and models.
```

that is GI JI telling you the installer has not completed on this computer yet.
Run `GI JI Installer` once and open GI JI again. Always start from
`GI JI Installer` in the download: it is what puts GI JI in the right place and
prepares the private AI. Opening GI JI directly from the download instead of
running the installer never finishes setup, whichever message you get.

## 7. Using GI JI

**Add your documents** — *Add sources*: point GI JI at a file or a folder, or
give it a web address to read. Plain text, Markdown, HTML and `.docx` files work
as they are. A PDF must contain real text; GI JI does not read scans or
photographs of pages, and reading PDFs needs Poppler's `pdftotext` on your
computer.

When GI JI reads a website it stays inside the boundary you choose — one page,
one section of a site, or the whole site — never leaves that site, obeys the
site's own rules, keeps to a firm page limit and paces itself politely.

Choose how thoroughly to read: **Fast** makes the material searchable straight
away, **Balanced** also prepares source overviews so broad questions work, and
**Deeper review** prepares the material for finding connections between sources.
None of this changes your original files, and a running job can be stopped.

**Ask** — the *Chat* screen. The answer appears as it is written, and you can
stop it at any moment. Answers cite their sources as `[1] [2]`; click a citation
to read the original passage. A small badge on each answer says what it was
built from: **Sources only**, **Guided: sources first**, or **Sources + general
context**.

**Choose how strict GI JI is** — on the *Learning* screen. **Strict** uses your
documents alone and stops when the evidence is not there. **Guided** — the
normal setting — uses your documents first and asks before adding anything from
its own general knowledge. **Open** may add clearly marked general context.

**Teach it** — corrections, instructions and working notes. When you tell GI JI
it got something wrong, it *proposes* a lesson; nothing is learned until you
approve it. Drafts wait in the *Review inbox* with their sources attached, where
you can edit, categorise, record how far you checked them, and approve, pause or
reject them.

**Remove things** — any document can be removed on its own. Larger clean-ups
live under *Knowledge base → Maintenance and cleanup*. Removing something takes
it out of GI JI's index; your original files are never touched.

**Back up** — *Settings → Your base, backed up* writes a dated archive into the
`backups` folder inside your GI JI folder. Restoring one is not done from inside
GI JI: write to support@giji.agency and we will go through it with you.

## 8. Connected AI — optional, and always asks first

GI JI can use OpenAI to write one answer, with **your own OpenAI key and your
own OpenAI account**. It is off until you switch it on, and switching it on does
not approve anything.

When you choose it for an answer, GI JI still searches your library here on this
computer, then stops and shows you the exact question and the exact passages
that would leave the machine. Only after you approve that one request does
anything go to OpenAI. It never sends your library, your notes, your rulebook or
your conversation history. Your key is held only while GI JI is open, is never
saved into your folder or your backups, and *Forget this session key* in
Settings removes it immediately.

Every answer is labelled either **Connected AI** or **Private on this computer**,
so you always know which one you are reading.

## 9. Where your things live

Everything is inside the GI JI folder:

- `config.json` — your settings
- `data/` — the index of your documents, your notes and your rulebook
- `backups/` — the archives you create from Settings
- `bin/`, `third_party/`, `INFO/` — the program, its licences and its records

Nothing is written into the rest of your home folder. The one part that lives
outside is Ollama and its models, which is deliberate: Ollama installs itself
the way it needs to, and other programs may share it.

## 10. Free and paid

Free GI JI is the complete product, held to **20 documents** and **3 active
Working Knowledge notes**. That is enough to do the whole loop — read some
material, ask real questions, make a note, approve it, and see how it is used.

A one-time licence removes both limits. It covers one activated computer at a
time; *Deactivate this computer* in Settings releases it before you move to
another one. Activating registers a licence key and a one-way code for this
computer with the licence service and then works offline. Your documents, chats
and activity are never sent anywhere for licensing.

## 11. If something goes wrong

- **"GI JI could not prepare this question for local search."** — Ollama is not
  running, or the `bge-m3` model is missing. Run `GI JI Installer` again; it
  keeps everything that finished and picks up only what is missing.
- **"Local search is unavailable, so I could not look through your sources."** —
  close GI JI and open it again from its own launcher. If it says another
  program already holds the search index port, stop that other copy of GI JI
  first. GI JI will not mix one folder's library with another folder's index.
- **A PDF will not import** — install Poppler so `pdftotext` is available. A
  scanned or photographed PDF has no text in it and cannot be read.
- **Answers are slow** — a modest processor is the usual reason. GI JI ships
  with a small model for exactly this case.

Anything else: **support@giji.agency**. Please say which computer you are on,
how much memory it has, which version of GI JI, and the exact step that failed.
Never put your OpenAI key, your licence key or a private document into a support
message.
