docs: Improve and expand project documentation

api/README.md

@@ -0,0 +1,34 @@
+# Publisher Tools - API
+
+This package contains the Hono-based API server that powers the Publisher Tools. It runs on Cloudflare Workers and is responsible for fetching tool configurations, handling Open Payments, and managing probabilistic revenue sharing.
+
+## Endpoints
+
+The API exposes endpoints related to the following functionalities:
+
+*   **Tool Configuration:** Handles fetching the configuration for the monetization tools (see `src/routes/get-config.ts`).
+*   **Payments:** Manages the Open Payments flow (see `src/routes/payment.ts`).
+*   **Probabilistic Revshare:** Handles logic related to probabilistic revenue sharing (see `src/routes/probabilistic-revshare.ts`).
+
+## Development
+
+To run the API server for local development, you can use the `dev` script.
+
+**From the project root:**
+```sh
+pnpm -C api dev
+```
+
+**From this directory (`api/`):**
+```sh
+pnpm dev
+```
+
+This will start the Cloudflare Wrangler development server, which automatically reloads on file changes.
+
+### Available Scripts
+
+*   `pnpm dev`: Starts the local development server.
+*   `pnpm build`: Builds the worker for deployment without deploying it.
+*   `pnpm typecheck`: Runs the TypeScript compiler to check for type errors.
+*   `pnpm deploy`: Deploys the worker to your Cloudflare account.

cdn/README.md

@@ -0,0 +1,35 @@
+# Publisher Tools - CDN
+
+This package is responsible for building and delivering the final, browser-ready JavaScript assets (the banner and widget scripts) that publishers embed on their websites.
+
+It takes the raw source code from the `@tools/components` package, bundles it using `esbuild`, and prepares it for delivery via the Cloudflare CDN.
+
+## Build Process
+
+The core of this package is the custom build script located at `build.js`. This script uses `esbuild` to compile the TypeScript source from `src/` and the components from the `components` package into distributable files.
+
+The main entry points for the build are:
+*   `src/banner.ts`
+*   `src/widget.ts`
+
+The output is placed in the `dist/` directory.
+
+## Development
+
+To build the assets and run a local development server that simulates the CDN, use the `dev` script. This will watch for file changes in both the `cdn` and `components` packages and automatically rebuild.
+
+**From the project root:**
+```sh
+pnpm -C cdn dev
+```
+
+**From this directory (`cdn/`):**
+```sh
+pnpm dev
+```
+
+### Available Scripts
+
+*   `pnpm dev`: Runs the development build and a local server.
+*   `pnpm build`: Runs a one-time production build of all assets.
+*   `pnpm deploy`: Deploys the assets to the Cloudflare CDN.

components/README.md

@@ -0,0 +1,28 @@
+# Publisher Tools - Components
+
+This package contains the core, embeddable web components for the Publisher Tools, built using the [Lit](https://lit.dev/) library. These components are intended to be placed on publishers' websites.
+
+## Core Components
+
+*   **Banner:** A notification banner that can be displayed on a publisher's site. The source is located in `src/banner.ts`.
+*   **Widget:** The interactive monetization widget. Its source code is in the `src/widget/` directory.
+
+## Build Process
+
+This package contains the raw source code for the web components but does not have its own build process.
+
+The components are imported and bundled by the **`cdn`** package, which is responsible for compiling them into a browser-ready format. Please see the `cdn` package for more details on the build and delivery process.
+
+## Development
+
+The only available script is for type checking.
+
+**From the project root:**
+```sh
+pnpm -C components typecheck
+```
+
+**From this directory (`components/`):**
+```sh
+pnpm typecheck
+```

docs/env-vars.md

@@ -1,124 +1,106 @@
 # Environment Variables Setup
 
-This guide provides detailed instructions for setting up your `.dev.vars` file for local development.\
-Follow the sections below to configure each variable.
+This guide provides detailed instructions for setting up your `.dev.vars` file for local development.
 
-## Environment Variables
+First, copy the sample environment file:
 
-### Open Payments Configuration
+```sh
+cp .env.sample .dev.vars
+```
+
+Then, edit the `.dev.vars` file to set the required values as described below.
 
-These variables are required to enable Open Payments functionality:
+## Variables Summary
 
-The following are instructions for development setup. For production use, please follow the setup instructions provided by your chosen wallet.
+| Variable                | Description                                             | Required for Dev? | Example Value                               |
+| ----------------------- | ------------------------------------------------------- | :---------------: | ------------------------------------------- |
+| `OP_KEY_ID`             | UUID v4 identifier for your Open Payments key.          |        Yes        | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`      |
+| `OP_PRIVATE_KEY`        | Base64-encoded private key for signing requests.        |        Yes        | (See conversion script below)               |
+| `OP_WALLET_ADDRESS`     | The URL of your Open Payments wallet address.           |        Yes        | `https://ilp.interledger-test.dev/my-wallet`  |
+| `AWS_ACCESS_KEY_ID`     | AWS access key for S3. Not used in local dev.           |        No         | `AWS_KEY_ID`                                |
+| `AWS_SECRET_ACCESS_KEY` | AWS secret key for S3. Not used in local dev.           |        No         | `AWS_SECRET_KEY`                            |
+| `AWS_S3_ENDPOINT`       | The endpoint for the S3-compatible storage.             |        Yes        | `http://localhost:8081`                     |
+
+---
+
+## Detailed Configuration
+
+### Open Payments Configuration
+
+These variables are required to connect to an Interledger wallet for handling payments. For development, you can use the Interledger Testnet.
 
 #### `OP_KEY_ID`
 
-UUID v4 identifier for your Open Payments key
+This is the unique identifier for your API key.
 
-1. Sign up for [Interledger Testnet wallet](https://wallet.interledger-test.dev)
-2. Navigate to the developers/API keys section
-3. Generate a new key pair
-4. Copy the Key ID (UUID format)
+1.  Sign up for an [Interledger Testnet wallet](https://wallet.interledger.test.dev).
+2.  In your wallet dashboard, navigate to the **Developers** section from the side menu.
+3.  Generate a new key pair.
+4.  Copy the **Key ID** (which is in UUID format) and paste it into your `.dev.vars` file.
 
 #### `OP_PRIVATE_KEY`
 
-Base64-encoded private key for signing Open Payments requests
+This is the secret key used to sign payment requests, proving you own the wallet.
 
-1. When generating your key pair in your wallet's developer section
-2. Download or copy the private key
-3. **Important**: The private key must be converted to the format expected by the tools using the script below
+1.  When you generate a key pair, your wallet will provide a private key.
+2.  This key needs to be converted to a specific format. Use the script below to do this.
 
-**Security Note**: Never commit this value to version control
+**Security Note**: Never commit this value to version control.
 
 <details>
-<summary><b>Private Key Conversion Script</b></summary>
+<summary><b>Click to see Private Key Conversion Script</b></summary>
 
-After copying your private key, run this script to convert it to the correct format.\
-Replace `currentKey` value string with your copied private key, then use the output as your `OP_PRIVATE_KEY` value:
+Copy your private key from the wallet, paste it into the `currentKey` variable in this script, and run it (for example, in your browser's developer console). Use the output as your `OP_PRIVATE_KEY` value.
 
 ```javascript
-// Extract base64-encoded part and decode to get DER bytes
-const currentKey = ''
+// Paste your private key from the wallet here
+const currentKey = '-----BEGIN PRIVATE KEY-----\nYOUR_KEY_HERE\n-----END PRIVATE KEY-----';
+
+// This script converts the key to the required format
 const derBytes = atob(
   currentKey
     .replace('-----BEGIN PRIVATE KEY-----', '')
     .replace('-----END PRIVATE KEY-----', '')
     .replace(/\s/g, '')
-)
-
-// Convert to Uint8Array
-const bytes = new Uint8Array(derBytes.length)
+);
+const bytes = new Uint8Array(derBytes.length);
 for (let i = 0; i < derBytes.length; i++) {
-  bytes[i] = derBytes.charCodeAt(i)
+  bytes[i] = derBytes.charCodeAt(i);
 }
+const privateKey = bytes.slice(-32);
+const keyBase64 = btoa(String.fromCharCode(...privateKey));
 
-// Extract just the 32-byte key
-const privateKey = bytes.slice(-32)
-
-// Convert back to base64 for storage
-const keyBase64 = btoa(String.fromCharCode(...privateKey))
-
-console.log('New key format for direct use:')
-console.log(keyBase64)
+console.log('Your new OP_PRIVATE_KEY is:');
+console.log(keyBase64);
 ```
 
 </details>
 
 #### `OP_WALLET_ADDRESS`
 
-Your wallet address URL
-
-1. In your Interledger testnet wallet dashboard
-2. Find your wallet address
-3. Copy the payment pointer and convert it to `https://` format.
+This is the public address of your wallet where you can receive payments.
 
-### AWS Configuration
+1.  In your Interledger wallet dashboard, find your payment pointer. It will look something like `$ilp.interledger-test.dev/my-wallet`.
+2.  To get the wallet address, simply replace the `$` with `https://`.
 
-These variables configure S3 storage for configuration data:
+For example, if your payment pointer is `$ilp.interledger-test.dev/alice`, your `OP_WALLET_ADDRESS` would be `https://ilp.interledger-test.dev/alice`.
 
-#### `AWS_ACCESS_KEY_ID`
+### AWS Configuration
 
-AWS access key for S3 operations\
-**Development Note**: This key is ignored when using the local S3 simulator, so it's not required for development
+These variables are for connecting to an S3 bucket, which is used to store the configuration for the publisher tools. For local development, a simulated S3 service is used, so you don't need real AWS credentials.
 
-#### `AWS_SECRET_ACCESS_KEY`
+#### `AWS_ACCESS_KEY_ID` & `AWS_SECRET_ACCESS_KEY`
 
-AWS secret key corresponding to the access key ID\
-**Development Note**: This key is ignored when using the local S3 simulator, so it's not required for development
+For local development, these values are ignored by the local S3 simulator. You can leave the default values from `.env.sample` as they are.
 
 #### `AWS_S3_ENDPOINT`
 
-**For Development**: Use the local S3 simulator
-
-```
-AWS_S3_ENDPOINT="http://localhost:8081"
-```
-
-**For Production**: Use your actual S3 bucket endpoint
-
-```
-AWS_S3_ENDPOINT="https://your-bucket-name.s3.your-region.amazonaws.com"
-```
-
-<details>
-<summary><b>How to get real AWS keys (for production use)</b></summary>
-
-1. Sign in to the [AWS Management Console](https://aws.amazon.com/console/)
-2. Navigate to IAM (Identity and Access Management)
-3. In the left sidebar, select "Users"
-4. Click on your user or create a new user with S3 permissions
-5. Go to the "Security credentials" tab
-6. Scroll down to "Access keys" and click "Create access key"
-7. Choose "Application running outside AWS"
-8. Copy the Access key ID
+This tells the application where to find the S3 storage.
 
-Make sure to save both the Access Key ID and Secret Access Key when they are displayed, as AWS will not show the secret key again.
-
-**Required Permissions**: S3 read/write access\
-**Security Note**: Never commit this value to version control
-
-</details>
+*   **For Development**: Use the local S3 simulator, which runs on `http://localhost:8081`. This should be the default value in your `.dev.vars`.
+*   **For Production**: When deploying the application, this would be the URL of your actual S3 bucket endpoint.
 
+---
 ## Development vs Production
 
 ### Development Setup
@@ -158,3 +140,4 @@ Open the application on [localhost:3000](http://localhost:3000/tools/) try to us
 - Review the [contribution guidelines](.github/contributing.md)
 - For Web Monetization questions, visit [webmonetization.org](https://webmonetization.org/)
 - For Interledger information, see [interledger.org](https://interledger.org)
+---

frontend/README.md

@@ -0,0 +1,39 @@
+# Publisher Tools - Frontend
+
+This package is the Remix frontend application for the Publisher Tools. It provides the dashboard where publishers configure the monetization tools for their websites.
+
+## Core Features
+
+The dashboard allows users to customize and generate code for the following tools:
+
+*   **Index (`/`):** The main landing page for the tools.
+*   **Banner (`/banner`):** Configuration page for the notification banner.
+*   **Widget (`/widget`):** Configuration page for the monetization widget.
+*   **Link Tag (`/link-tag`):** Page for generating a monetized link tag.
+*   **Probabilistic Revshare (`/prob-revshare`):** UI for setting up probabilistic revenue sharing.
+*   **Payment Confirmation (`/payment-confirmation`):** A page to confirm payment status.
+
+The application also includes API routes (e.g., `api.config.$type.ts`) that are handled by the Remix server.
+
+## Development
+
+To run the frontend application for local development, use the `dev` script.
+
+**From the project root:**
+```sh
+pnpm -C frontend dev
+```
+
+**From this directory (`frontend/`):**
+```sh
+pnpm dev
+```
+
+This will start the Remix development server, typically available at `http://localhost:3000`.
+
+### Available Scripts
+
+*   `pnpm dev`: Starts the local development server.
+*   `pnpm build`: Builds the application for production.
+*   `pnpm typecheck`: Runs the TypeScript compiler to check for type errors.
+*   `pnpm deploy`: Deploys the application to Cloudflare Pages.