Readme updates (#123)

Co-authored-by: Jason Young <jky10@pm.me>

Author: Jyyjy

README.md

@@ -17,10 +17,28 @@
   ~ under the License.
 -->
 
-Apache Flagon
---------------------------------------
+# Apache Flagon
 
-Flagon includes both UserALE, an instrumentation tool for web applications, and Distill, a python library for analyzing UserALE telemetry.
+Flagon is a collection of open-source tools for user behavior analytics, including instrumentation libraries and analytics pipelines. This monorepo contains multiple Flagon products in a unified codebase.
 
-See products/ for userale and distill. This read me is under construction.
+## Repository Structure
+```text
+/examples # Integration examples
+/products
+├── userale
+│ └── packages
+│  ├── flagon-userale # JavaScript client instrumentation library
+│  └── flagon-userale-ext # Browser extension for deploying UserALE
+└── distill # Data processing toolkit (Python)
+/site # Code for https://flagon.apache.org/
+```
 
+## Products
+
+- [UserALE Core Library](./products/userale/packages/flagon-userale/README.md)
+- [UserALE Browser Extension](./products/userale/packages/flagon-userale-ext/README.md)
+- [Distill Toolkit](./products/distill/README.md)
+
+## Documentation
+
+- 📚 [Flagon Website](https://flagon.apache.org/)

products/userale/README.md

@@ -0,0 +1,13 @@
+# Flagon UserALE
+
+UserALE is a client-side instrumentation library for behavioral analytics.
+
+This directory contains two packages:
+- [`flagon-userale`](./packages/flagon-userale): Core JavaScript library
+- [`flagon-userale-ext`](./packages/flagon-userale-ext): Browser extension
+
+For details on each, see their respective READMEs.
+
+📚 [Documentation](https://flagon.incubator.apache.org/userale/)
+
+---

products/userale/packages/flagon-userale-ext/README.md

@@ -1,52 +1,80 @@
 <!--
-  ~ Licensed to the Apache Software Foundation (ASF) under one
-  ~ or more contributor license agreements.  See the NOTICE file
-  ~ distributed with this work for additional information
-  ~ regarding copyright ownership.  The ASF licenses this file
-  ~ to you under the Apache License, Version 2.0 (the
-  ~ "License"); you may not use this file except in compliance
-  ~ with the License.  You may obtain a copy of the License at
-  ~
-  ~   http://www.apache.org/licenses/LICENSE-2.0
-  ~
-  ~ Unless required by applicable law or agreed to in writing,
-  ~ software distributed under the License is distributed on an
-  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-  ~ KIND, either express or implied.  See the License for the
-  ~ specific language governing permissions and limitations
-  ~ under the License.
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements. See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership. The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+  either express or implied. See the License for the specific
+  language governing permissions and limitations under the License.
 -->
 
-This is a [Plasmo extension](https://docs.plasmo.com/) project bootstrapped with [`plasmo init`](https://www.npmjs.com/package/plasmo).
+# Flagon UserALE Browser Extension
+
+This package provides a browser extension for [Flagon UserALE](https://flagon.apache.org/userale/), enabling effortless, no-code instrumentation of websites. It captures user interactions and sends behavioral logs to a logging endpoint.
+
+The extension is built with [Plasmo](https://docs.plasmo.com/) and supports modern browser environments like Chrome and Firefox.
+
+---
 
-## Getting Started
+## Features
 
-First, run the development server:
+✅ Passive user interaction logging  
+✅ No code changes required on instrumented pages  
+✅ Configurable via extension options (logging endpoint, user ID, tool metadata)  
+✅ Supports local development and custom deployments
+
+---
+
+## Getting Started (Development)
+
+1. Install dependencies:
 
 ```bash
-pnpm dev
-# or
-npm run dev
+pnpm install
 ```
 
-Open your browser and load the appropriate development build. For example, if you are developing for the chrome browser, using manifest v3, use: `build/chrome-mv3-dev`.
+2. Start the development build:
 
-You can start editing the popup by modifying `popup.tsx`. It should auto-update as you make changes. To add an options page, simply add a `options.tsx` file to the root of the project, with a react component default exported. Likewise to add a content page, add a `content.ts` file to the root of the project, importing some module and do some logic, then reload the extension on your browser.
+```bash
+pnpm dev
+```
 
-For further guidance, [visit our Documentation](https://docs.plasmo.com/)
+3. Load the extension in your browser:
+   - **Chrome**: Visit `chrome://extensions/`, enable Developer Mode, click "Load unpacked", and select the `build/chrome-mv3-dev/` directory.
+   - **Firefox**: Visit `about:debugging`, "This Firefox", "Load Temporary Add-on", and select the `manifest.json` file in `build/firefox-mv3-dev/`.
 
-## Making production build
+---
 
-Run the following:
+## Building for Production
+
+To create a production build:
 
 ```bash
 pnpm build
-# or
-npm run build
 ```
 
-This should create a production bundle for your extension, ready to be zipped and published to the stores.
+This outputs a zipped production bundle.
+
+---
+
+## Extension Options
+
+After installing the extension, click the icon in your browser toolbar to open the **Options** page. From here you can configure:
+- **Logging Endpoint** – Where logs will be sent
+- **URL allowlist** – A regex of URL's to allow logging on
+- **OAuth Credentials** – Details of an OAuth login to authenticate with the logging endpoint.
+
+---
+
+## Resources
 
-## Submit to the webstores
+- 📚 [UserALE Documentation](https://flagon.apache.org/userale/)
 
-The easiest way to deploy your Plasmo extension is to use the built-in [bpp](https://bpp.browser.market) GitHub action. Prior to using this action however, make sure to build your extension and upload the first version to the store to establish the basic credentials. Then, simply follow [this setup instruction](https://docs.plasmo.com/framework/workflows/submit) and you should be on your way for automated submission!