1 files changed, 100 insertions, 0 deletions
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..cfa7c13
--- /dev/null
+++ b/README.org
@@ -0,0 +1,100 @@
+#+TITLE: Crumb
+#+AUTHOR: Christian Cleberg
+#+OPTIONS: toc:nil
+
+Crumb is a local-only browser history tracker. It consists of two parts: a
+WebExtension-based browser plugin and a local HTTP server. Crumb logs each
+visited web page to a plaintext file in Org-mode format.
+
+* Components
+
+- Browser extension (WebExtension API, JavaScript)
+- Local HTTP listener (Python + Flask)
+- Plaintext log file (~/.crumb/history.log)
+
+* Functionality
+
+Each time a page is loaded in the browser, the extension sends the page metadata
+to the local server. The server appends this data to a structured log file.
+
+Data captured per page:
+
+- Page title
+- URL
+- Timestamp (UTC)
+- Hostname
+- Path
+- Optional: query string, tab ID, window ID, favicon URL
+
+The log is formatted as an Org-mode file, with one top-level heading per visit
+and standard =:PROPERTIES:= metadata.
+
+* Requirements
+
+- Python 3.x
+- Flask
+- A Chromium-based or Firefox browser with extension developer mode enabled
+
+* Usage
+
+1. Start the local listener:
+
+   #+BEGIN_SRC shell
+   python3 -m venv venv
+   source ./venv/bin/activate
+   pip install -r requirements.txt
+   python server.py
+   #+END_SRC
+
+2. Load the extension into your browser:
+
+   - Enable Developer Mode
+   - Load the =crumb_extension/= directory
+
+3. Browse the web. Entries will appear in =~/.crumb/history.org=
+
+4. Search the log using:
+
+   #+BEGIN_SRC shell
+   python search.py <term>
+   #+END_SRC
+
+* Example Log Entry
+
+#+BEGIN_SRC org
+* Example Domain
+:PROPERTIES:
+:URL:       http://example.com
+:TIMESTAMP: 2025-06-04T20:31:01.123456
+:HOST:      example.com
+:PATH:      /
+:TAB:       143
+:WINDOW:    1
+:FAVICON:   https://example.com/favicon.ico
+:END:
+#+END_SRC
+
+* Preview Images
+
+Screenshots of Crumb in use.
+
+#+CAPTION: Developer Console Output
+[[./screenshots/devtools.png]]
+
+#+CAPTION: Org-Mode History Log
+[[./screenshots/history.png]]
+
+#+CAPTION: Search Utility in Terminal
+[[./screenshots/search.png]]
+
+* Limitations
+
+- Browser extensions cannot write files directly; communication requires the
+  local server.
+- History is stored in plaintext and is not encrypted. You can bolt-on a
+  third-party encryption tool, if required.
+- Data is stored locally and is never transmitted externally.
+
+* License
+
+GPL 3.0 License. See LICENSE file.