Cargora Quickstart, as shipped in the download

CARGORA — QUICKSTART
====================

REQUIREMENTS
------------
  - PHP 8.0+ with extensions: pdo, pdo_sqlite (or pdo_mysql), fileinfo, curl
  - MySQL 5.7+ OR SQLite 3 (SQLite requires no extra setup)
  - An API key for OpenAI, Anthropic, or Ollama (set after install, or during)
  - A web server (Apache with mod_rewrite, or Nginx with try_files)


SHARED HOSTING / CPANEL (RECOMMENDED FOR MOST BUYERS)
------------------------------------------------------
1. Upload the contents of the `app/` folder to your web root (e.g. public_html/)
   or a subdirectory (e.g. public_html/cargora/).

2. Make sure these directories are writable by PHP:
     data/
     data/uploads/

   Via cPanel File Manager: right-click -> Permissions -> set to 755 or 775.

3. Visit https://yourdomain.com/install/ in your browser.

4. Fill in the installer:
     - Database: choose MySQL (fill in host/name/user/pass) or SQLite (no setup)
     - Company name and base currency
     - LLM provider and API key (or leave blank to configure later in Settings)
     - Admin email + password

5. The installer writes config.php and redirects you to the login page.

6. Log in and go to Settings to verify or update your LLM provider and API key.

7. Click "New Document", pick the type, upload a PO/slip/note, then click Extract.


VPS / SELF-HOSTED
-----------------
Requirements same as above. Apache example:

  <VirtualHost *:80>
    DocumentRoot /var/www/cargora/app
    <Directory /var/www/cargora/app>
      AllowOverride All
      Require all granted
    </Directory>
  </VirtualHost>

Run the web installer as above, or use the CLI seeder:

  php bin/demo.php    # loads demo data (login: admin@cargora.app with the one-time password it prints)


DOCKER (QUICK TEST)
-------------------
  docker run --rm -p 8080:8080 \
    -v "$(pwd):/var/www/html" \
    -w /var/www/html \
    php:8.3-cli \
    php -S 0.0.0.0:8080 router.php

  Then visit http://localhost:8080/install/


RECONCILIATION WORKFLOW
-----------------------
  1. Add a purchase order (type "Purchase Order") and extract it.
  2. Add the matching packing slip or delivery note and extract it.
  3. Go to "Reconcile", pick the PO and the slip, and click Reconcile.
  4. Review the side-by-side report: quantity deltas, price mismatches,
     SKUs missing on the slip, and SKUs shipped but not ordered.
  5. Export the report to CSV for your records or ERP import.


POST-INSTALL SECURITY CHECKLIST
--------------------------------
  [ ] config.php is protected (the .htaccess does this automatically)
  [ ] data/ is not web-accessible (.htaccess blocks it automatically)
  [ ] Use HTTPS in production
  [ ] Keep PHP updated


LOOKING AFTER IT (from 4.0)
---------------------------
  * Updates: open Updates in the menu, save your license key once, press Check for updates.
    Reaching 4.0 from 3.x is the last update by hand: replace the files; config.php and data/ stay.
  * Sample data: the installer offers to start with a sample; remove it later with one click.
  * Backups: "Back up once a day by itself" is on by default (/restore); add an S3-compatible bucket there for
    a copy somewhere else. The Health page (/health) says whether all of this is working.
  * On Nginx: use the server block in the manual ("On Nginx: keep data/ private", https://ownware.io/p/cargora/manual);
    it opens the installer and keeps data/ private.
  * One-line install for technical owners:
    curl -fsSL https://ownware.io/install.sh | sh -s -- cargora <your license key>

NOTES
-----
  * Extraction accuracy depends on the model you choose. GPT-4o and
    Claude 3 Sonnet/Opus give the best results on line-item tables.
  * Images (PNG, JPEG, WebP) work reliably across all providers.
  * PDFs work best with Anthropic (native document support). Other
    providers treat PDFs as best-effort.
  * The review page lets you correct any field before exporting or reconciling.
  * Export formats: CSV (spreadsheet-ready) and JSON (developer-friendly).
  * No API calls are ever made without your explicit click on "Extract".


NEW IN 2.0
----------
  * REST API + signed webhooks .... "API & Webhooks" in the sidebar; see API.md
  * Discrepancy alerts ............ Settings -> Email notifications (your own SMTP);
                                    a clean reconciliation stays silent
  * Review stamp .................. accepting an extraction now records who/when
  * Two-factor authentication ..... "Security" in the sidebar
  * One-click backup .............. Security -> Backups (JSON, plus the raw DB on SQLite)
  * Dark mode ..................... the "Theme" toggle at the bottom of the sidebar
  * Uptime ping ................... GET /healthz  (no login required)

  Document upload stays in the browser by design - see the "Two deliberate omissions"
  section of API.md.

  Upgrading from 1.x: overwrite the app files and open the site once. The new tables
  and columns are added automatically; your data is untouched. Back up first anyway.