From 4873dc74e7096d84f586bea6b3a2636470789199 Mon Sep 17 00:00:00 2001
From: Eric Taylor <eric@taylors.life>
Date: Wed, 24 Dec 2025 11:50:53 -0500
Subject: [PATCH] docs: Update project and agent documentation.

- Document agent guidelines for asset tracking, including build commands, code style, data conventions, and security practices.
- Document project setup, features, configuration, usage, and output details for an asset tracking tool.
---
 AGENTS.md | 29 +++++++++++++++++
 README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 126 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 README.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..fb5e03d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,29 @@
+# Asset Tracker - Agent Guidelines
+
+## Build/Test Commands
+- Run asset extraction: `./extract_assets.sh`
+- Generate charts: `./chart_asset_data.sh`
+- Full pipeline with SSH agent: `./run_with_agent.sh`
+- Test individual users: Edit `user_ids.conf` to modify USER_IDS array
+
+## Code Style Guidelines
+- Use bash for shell scripts with `#!/bin/bash` shebang
+- Source configuration files with `source ./user_ids.conf`
+- Use uppercase for global variables: `USER_IDS`, `URL_TEMPLATE`, `OUTPUT_DIR`
+- Function names in lowercase with underscores: `process_user()`
+- Use local variables in functions: `local USER_ID="$1"`
+- Error checking with conditional statements and proper exit codes
+- Clean up temporary files with `rm -f`
+- Use descriptive variable names: `png_total_assets`, `temp_diamonds_on_hand`
+
+## Data Conventions
+- CSV format: `date,rank,diamonds,total_assets`
+- Date format: `"%Y-%m-%d %H:%M:%S"`
+- Remove commas from numeric values with `tr -d ','`
+- Gnuplot time format: `"%Y-%m-%d"`
+- Output PNG files: `total_assets_${USER_ID}.png`, `diamonds_on_hand_${USER_ID}.png`
+
+## Security
+- Use SSH agent for key management: `ssh-add ~/.ssh/id_ed25519`
+- Handle sensitive URLs and paths in configuration files
+- Validate file existence before processing: `[ ! -f "$input_file" ]`
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7f385c2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# Asset Tracker
+
+A Bash-based tool for tracking user assets and generating visualizations from the Prismatic Imperium game platform.
+
+## Overview
+
+This project extracts asset data from user profiles, stores it in CSV format, and generates time-series charts showing total assets and diamonds on hand over time.
+
+## Features
+
+- Automated data extraction from Prismatic Imperium user pages
+- CSV data storage with timestamps
+- Chart generation in ASCII and PNG formats
+- Multiple user support with configurable user IDs
+- Automatic deployment to web server via SSH
+
+## Prerequisites
+
+- Bash shell
+- curl for web requests
+- gnuplot for chart generation
+- SSH access to web server (for deployment)
+
+## Installation
+
+1. Clone or download the scripts to your desired location
+2. Make scripts executable:
+   ```bash
+   chmod +x extract_assets.sh chart_asset_data.sh run_with_agent.sh
+   ```
+3. Configure user IDs in `user_ids.conf`
+
+## Configuration
+
+Edit `user_ids.conf` to specify which user IDs to track:
+
+```bash
+USER_IDS=("667" "31" "744" "602" "268")
+```
+
+## Usage
+
+### Run Full Pipeline (Recommended)
+
+```bash
+./run_with_agent.sh
+```
+
+This script:
+1. Sets up SSH agent
+2. Adds SSH key for deployment
+3. Runs data extraction
+4. Generates charts
+5. Deploys to web server
+
+### Individual Steps
+
+**Extract asset data:**
+```bash
+./extract_assets.sh
+```
+
+**Generate charts:**
+```bash
+./chart_asset_data.sh
+```
+
+## Output Files
+
+### CSV Data
+- `assets_data_{USER_ID}.csv` - Time-series asset data
+- Format: `date,rank,diamonds,total_assets`
+
+### Charts
+- `total_assets_{USER_ID}.png` - Total assets over time
+- `diamonds_on_hand_{USER_ID}.png` - Diamonds on hand over time
+
+Charts are generated with:
+- Black background
+- Orange (#FE6A00) for total assets
+- Teal (#2CB9CF) for diamonds
+- White grid lines and labels
+
+## Deployment
+
+Charts are automatically copied to the web server at:
+`/var/www/erictaylor/img/asset_tracker/`
+
+## Data Processing
+
+The tool extracts numeric values from web pages, removes commas, and stores them with timestamps. Gnuplot processes the data to create visualizations with configurable date formatting and axis styling.
+
+## Security
+
+- Uses SSH agent for key management
+- Configuration files isolate sensitive paths
+- File existence validation before processing
\ No newline at end of file