Add some documentation

.env.example

···
 OZONE_PDS=
 BSKY_HANDLE=
 BSKY_PASSWORD=
-HOST=127.0.0.1
-PORT=4000
-METRICS_PORT=4001
-FIREHOSE_URL=
-PLC_URL=plc.wtf
+HOST=0.0.0.0
+METRICS_PORT=4101
+FIREHOSE_URL=wss://jetstream1.us-east.fire.hose.cam/subscribe
 CURSOR_UPDATE_INTERVAL=10000
 LABEL_LIMIT=2900 * 1000
 LABEL_LIMIT_WAIT=300 * 1000
+LOG_LEVEL=info
+PLC_URL=plc.wtf

README.md

···
-# skywatch-tools
+# skywatch-automod
 
-This is a rewrite of the original skywatch-tools project in TypeScript. The original project was written in Bash. The purpose of this project is to automate the moderation by the Bluesky independent labeler skywatch.blue
+Automated moderation tooling for the Bluesky independent labeler skywatch.blue. Monitors the Bluesky firehose and applies labels based on configured moderation rules.
 
-## Installation and Setup
+## Setup
 
-To install dependencies:
+Configure environment:
 
 ```bash
-bun i
+cp .env.example .env
+# Edit .env with your credentials and configuration
 ```
 
-Modify .env.example with your own values and rename it to .env
+Required environment variables:
+- `BSKY_HANDLE` - Bluesky account handle
+- `BSKY_PASSWORD` - Account password
+- `MOD_DID` - Moderator DID
+- `OZONE_PDS` - Ozone PDS URL
+- `FIREHOSE_URL` - Jetstream firehose URL
+
+Create cursor file (optional but recommended):
+
+```bash
+touch cursor.txt
+```
+
+## Running
+
+Production:
 
 ```bash
-bun run start
+docker compose up -d
 ```
 
-To run in docker:
+Development mode with auto-reload:
 
 ```bash
-docker build -pull -t skywatch-tools .
-docker run -d -p 4101:4101 skywatch-autolabeler
+docker compose -f compose.yaml -f compose.dev.yaml up
 ```
 
-## Brief overview
+The service runs on port 4101 (metrics endpoint). Redis and Prometheus are included in the compose stack.
+
+## Authentication
+
+The application authenticates with Bluesky on startup and retries up to 3 times on failure. If all attempts fail, the application exits. Sessions are cached in `.session` (gitignored).
+
+## Testing
+
+```bash
+bun test          # Watch mode
+bun test:run      # Single run
+bun test:coverage # With coverage
+```
 
-Currently this tooling does one thing. It monitors the bluesky firehose and analyzes content for phrases which fit Skywatch's criteria for moderation. If the criteria is met, it can automatically label the content with the appropriate label.
+## How It Works
 
-In certain cases, where regexp will create too many false positives, it will flag content as a report against related to the account, so that it can be reviewed later.
+Monitors the Bluesky firehose via Jetstream and analyzes posts, profiles, and handles against configured moderation rules. When criteria are met, applies appropriate labels or creates moderation reports.
 
-For information on how to set-up your own checks, please see the [developing_checks.md](./src/developing_checks.md) file.
+For developing custom checks, see [developing_checks.md](./rules/developing_checks.md).

package.json

···
 {
-  "name": "skywatch-tools",
-  "version": "1.3.0",
+  "name": "skywatch-automod",
+  "version": "2.0.2",
   "type": "module",
   "scripts": {
     "start": "npx tsx src/main.ts",

rules/developing_checks.md

···
+# Developing Moderation Checks
+
+This guide explains how to configure moderation rules for skywatch-automod.
+
+## Overview
+
+Moderation checks are defined in TypeScript files in the `rules/` directory. Each check uses regular expressions to match content and specifies what action to take when a match is found.
+
+## Check Types
+
+### Post Content Checks
+
+File: `rules/posts.ts`
+
+Monitors post text and embedded URLs for matches.
+
+```typescript
+import type { Checks } from "../src/types.js";
+
+export const POST_CHECKS: Checks[] = [
+  {
+    label: "spam",
+    comment: "Spam content detected in post",
+    reportAcct: false,
+    commentAcct: false,
+    toLabel: true,
+    check: new RegExp("buy.*followers", "i"),
+  },
+];
+```
+
+### Handle Checks
+
+File: `rules/handles.ts`
+
+Monitors user handles for pattern matches.
+
+```typescript
+export const HANDLE_CHECKS: Checks[] = [
+  {
+    label: "impersonation",
+    comment: "Potential impersonation detected",
+    reportAcct: true,
+    commentAcct: false,
+    toLabel: false,
+    check: new RegExp("official.*support", "i"),
+  },
+];
+```
+
+### Profile Checks
+
+File: `rules/profiles.ts`
+
+Monitors profile display names and descriptions.
+
+```typescript
+export const PROFILE_CHECKS: Checks[] = [
+  {
+    label: "spam-profile",
+    comment: "Spam content in profile",
+    reportAcct: false,
+    commentAcct: false,
+    toLabel: true,
+    displayName: true,  // Check display name
+    description: true,  // Check description
+    check: new RegExp("follow.*back", "i"),
+  },
+];
+```
+
+### Account Age Checks
+
+File: `rules/accountAge.ts`
+
+Labels accounts created after a specific date when they interact with monitored content.
+
+```typescript
+import type { AccountAgeCheck } from "../src/types.js";
+
+export const ACCOUNT_AGE_CHECKS: AccountAgeCheck[] = [
+  {
+    monitoredDIDs: ["did:plc:abc123"],
+    anchorDate: "2025-01-15",
+    maxAgeDays: 7,
+    label: "new-account-spam",
+    comment: "New account replying to monitored user",
+    expires: "2025-02-15",  // Optional expiration
+  },
+];
+```
+
+### Account Threshold Checks
+
+File: `rules/accountThreshold.ts`
+
+Applies account-level labels when an account accumulates multiple post-level violations within a time window.
+
+```typescript
+import type { AccountThresholdConfig } from "../src/types.js";
+
+export const ACCOUNT_THRESHOLD_CONFIGS: AccountThresholdConfig[] = [
+  {
+    labels: ["spam", "scam"],  // Trigger on either label
+    threshold: 3,
+    accountLabel: "repeat-offender",
+    accountComment: "Account exceeded spam threshold",
+    windowDays: 7,
+    reportAcct: true,
+    commentAcct: false,
+    toLabel: true,
+  },
+];
+```
+
+## Check Configuration Fields
+
+### Basic Fields (Required)
+
+- `label` - Label to apply (string)
+- `comment` - Comment for the moderation action (string)
+- `reportAcct` - Create account report (boolean)
+- `commentAcct` - Add comment to account (boolean)
+- `toLabel` - Apply the label (boolean)
+- `check` - Regular expression pattern (RegExp)
+
+### Optional Fields
+
+- `language` - Language codes to restrict check to (string[])
+- `description` - Check profile descriptions (boolean)
+- `displayName` - Check profile display names (boolean)
+- `reportPost` - Create post report instead of just labeling (boolean)
+- `duration` - Label duration in hours (number)
+- `whitelist` - RegExp to exclude from matching (RegExp)
+- `ignoredDIDs` - DIDs to skip checking (string[])
+- `starterPacks` - Filter by starter pack membership (string[])
+- `knownVectors` - Known attack vectors for tracking (string[])
+
+## Examples
+
+### Language-Specific Check
+
+```typescript
+{
+  language: ["spa"],
+  label: "spam-es",
+  comment: "Spanish spam detected",
+  reportAcct: false,
+  commentAcct: false,
+  toLabel: true,
+  check: new RegExp("comprar seguidores", "i"),
+}
+```
+
+### Temporary Label
+
+```typescript
+{
+  label: "review-needed",
+  comment: "Content flagged for review",
+  reportAcct: true,
+  commentAcct: false,
+  toLabel: false,
+  duration: 24,  // Label expires after 24 hours
+  check: new RegExp("suspicious.*pattern", "i"),
+}
+```
+
+### Whitelist Exception
+
+```typescript
+{
+  label: "blocked-term",
+  comment: "Blocked term used",
+  reportAcct: false,
+  commentAcct: false,
+  toLabel: true,
+  check: new RegExp("\\bterm\\b", "i"),
+  whitelist: new RegExp("legitimate.*context", "i"),
+}
+```
+
+### Ignored DIDs
+
+```typescript
+{
+  label: "blocked-term",
+  comment: "Blocked term used",
+  reportAcct: false,
+  commentAcct: false,
+  toLabel: true,
+  check: new RegExp("\\bterm\\b", "i"),
+  ignoredDIDs: [
+    "did:plc:trusted123",
+    "did:plc:verified456",
+  ],
+}
+```
+
+## Global Configuration
+
+### Allowlist
+
+File: `rules/constants.ts`
+
+DIDs in the global allowlist bypass all checks.
+
+```typescript
+export const GLOBAL_ALLOW: string[] = [
+  "did:plc:trusted123",
+  "did:plc:verified456",
+];
+```
+
+### Link Shorteners
+
+Pattern to match URL shorteners for special handling.
+
+```typescript
+export const LINK_SHORTENER = new RegExp(
+  "bit\\.ly|tinyurl\\.com|goo\\.gl",
+  "i"
+);
+```
+
+## Best Practices
+
+### Regular Expressions
+
+- Use word boundaries (`\\b`) to avoid partial matches
+- Test patterns thoroughly to minimize false positives
+- Use case-insensitive matching (`i` flag) when appropriate
+- Escape special regex characters
+
+### Action Selection
+
+- `toLabel: true` - Apply label immediately (use for clear violations)
+- `reportAcct: true` - Create report for manual review (use for ambiguous cases)
+- `commentAcct: true` - Create comment on account (probably can be depreciated)
+
+### Performance
+
+- Keep regex patterns simple and efficient
+- Use language filters to reduce unnecessary checks
+- Leverage whitelists instead of complex negative lookaheads
+
+### Testing
+
+After modifying rules:
+
+```bash
+bun test:run
+```
+
+Test specific rule modules:
+
+```bash
+bun test src/rules/posts/tests/
+```
+
+## Deployment
+
+Rules are mounted as a volume in docker compose:
+
+```yaml
+volumes:
+  - ./rules:/app/rules
+```
+
+Changes require automod rebuild:
+
+```bash
+docker compose up -d --build automod
+```