docs: add project documentation, memory, and setup guides

docs/ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# Architecture Documentation
+
+## System Overview
+
+This project serves as a bridge between Google Sheets and Shopify. It enables a two-way sync (primarily Sheets to Shopify for products) and allows managing inventory directly from a spreadsheet.
+
+### Core Flows
+
+1.  **Product Updates**:
+    - User edits a cell in the "product_inventory" sheet.
+    - `onEditQueue` trigger fires, capturing the SKU and timestamp.
+    - Edits are batched in `PropertiesService` (script properties).
+    - A time-based trigger runs `processBatchedEdits` every minute.
+    - The processing function locks the script, reads the queue, and pushes changes to Shopify via the Admin API.
+
+2.  **Order Sync**:
+    - Users can run menu commands to fetch orders from Shopify.
+    - The `Shop` class fetches orders via the REST API, handling pagination.
+    - Data is populated into specific sheets (`_orders`, `_line_items`, `_customer`, etc.).
+
+## Key Components
+
+### 1. Queue System (`src/onEditQueue.ts`)
+
+To avoid hitting Shopify API rate limits and Google Apps Script execution time limits, edits are not processed immediately.
+
+- **`onEditQueue(e)`**:
+    - Triggered on every cell edit.
+    - Checks if the edit is valid (correct sheet, valid SKU).
+    - Acquires a `DocumentLock`.
+    - Updates a JSON list in `ScriptProperties` (`pendingEdits`).
+    - Debounces edits (updates timestamp if SKU is already pending).
+
+- **`processBatchedEdits()`**:
+    - Run via time-based trigger (every 1 minute).
+    - Acquires a `ScriptLock`.
+    - Reads `pendingEdits`.
+    - Filters for edits older than `BATCH_INTERVAL_MS` (30s) to allow for multiple quick edits to the same SKU.
+    - Iterates through valid edits and calls `Product.UpdateShopifyProduct`.
+
+### 2. Shopify Integration (`src/shopifyApi.ts`)
+
+The project uses a hybrid approach for the Shopify Admin API:
+
+- **REST API**: Used primarily for fetching Orders (legacy support).
+- **GraphQL API**: Used for fetching and updating Products and Inventory.
+
+The `Shop` class handles authentication using credentials stored in the "vars" sheet.
+
+### 3. Configuration (`src/config.ts`)
+
+Configuration, including API keys, is stored in a dedicated Google Sheet named "vars". The `Config` class reads these values at runtime using a `vlookup` style helper.
+
+**Required "vars" columns:**
+- `key`: The name of the configuration variable.
+- `value`: The actual value.
+
+### 4. Global Entry Points (`src/global.ts`)
+
+Since Apps Script functions must be top-level to be triggered or attached to buttons, `src/global.ts` explicitly exposes necessary functions from the modules to the global scope.
+
+## Triggers
+
+Triggers are managed programmatically via `src/triggers.ts`. Running `reinstallTriggers` will wipe existing project triggers and set up the standard set:
+- `onEdit` -> `newSkuHandler`
+- `onEdit` -> `matchProductToShopifyOnEditHandler`
+- `onEdit` -> `onEditQueue`
+- `TimeBased (1 min)` -> `processBatchedEdits`

docs/SETUP.md

@@ -0,0 +1,57 @@
+# Setup Guide
+
+## Local Development Environment
+
+1.  **Install Node.js**
+    This project uses `fnm` to manage Node versions.
+    ```powershell
+    # Install fnm (if not installed)
+    winget install Schniz.fnm
+    # Configure environment
+    fnm env --use-on-cd | Out-String | Invoke-Expression
+    # Install Node version
+    fnm use --install-if-missing 22
+    ```
+
+2.  **Install Dependencies**
+    ```bash
+    npm install
+    npm install -g @google/clasp
+    ```
+
+3.  **Clasp Login**
+    Authenticate with Google to allow pushing code.
+    ```bash
+    clasp login
+    ```
+
+## Google Sheets Configuration
+
+1.  **Create a Google Sheet** (or use existing).
+2.  **"vars" Sheet**:
+    Create a tab named `vars` with the following columns: `key`, `value`.
+    Add the following rows:
+    - `productPhotosFolderId`: ID of the Drive folder for photos.
+    - `shopifyApiKey`: Your Shopify API Key.
+    - `shopifyApiSecretKey`: Your Shopify API Secret.
+    - `shopifyAdminApiAccessToken`: The Admin API access token.
+    - `shopifyApiURI`: e.g., `https://your-store.myshopify.com`
+    - `shopifyLocationId`: Location ID for inventory.
+    - `shopifyCountryCodeOfOrigin`: Two-letter country code (e.g., `US`).
+    - `shopifyProvinceCodeOfOrigin`: Two-letter province code (e.g., `NY`).
+
+## Deployment
+
+1.  **Build**
+    ```bash
+    npm run build
+    ```
+
+2.  **Push to Apps Script**
+    ```bash
+    npm run deploy
+    ```
+
+3.  **Install Triggers**
+    Open the Apps Script editor (Extensions > Apps Script).
+    Run the `reinstallTriggers` function manually once to set up the automation.