README and Documentation Update

Overview

Update README and setup documentation to reflect multi-platform support (Node.js and Cloudflare Workers).

Design Decisions

• Tagline: Platform-agnostic ("A minimal AT Protocol Personal Data Server written in JavaScript")
• Quick Start: Node.js focused (simpler, no account required)
• Platform guides: Sections in README (not separate pages)
• Setup script: Single flow for both platforms
• Audience: Developers evaluating, self-hosters, contributors

README Structure

1. Header and Overview

• New tagline without Cloudflare-specific language
• Feature list with link to endpoint comparison
• Mention both platform options

2. Quick Start (Node.js)

git clone https://github.com/your/pds.js
cd pds.js && npm install
npm run dev:node
npm run setup -- --pds http://localhost:3000

3. Configuration

Environment variables table:

Variable	Required	Description
PDS_PASSWORD	Yes	Password for legacy auth and OAuth consent
JWT_SECRET	Yes	Secret for signing JWTs
PDS_DB_PATH	No	SQLite database path (default: ./pds.db)
PDS_BLOBS_DIR	No	Blob storage directory (default: ./blobs)
PORT	No	Server port (default: 3000)
HOSTNAME	No	Public hostname for the PDS
APPVIEW_URL	No	AppView URL for proxying
APPVIEW_DID	No	AppView DID for service auth
RELAY_URL	No	Relay URL for firehose notifications

4. Deploy: Node.js

• Install dependencies
• Configure environment variables
• Start server (packages/node entry or examples/node)
• Run setup script
• DNS/TLS notes (reverse proxy)
• Storage considerations

5. Deploy: Cloudflare Workers

• Prerequisites (Workers Paid plan)
• Create R2 bucket and KV namespace
• Configure wrangler.toml (including SHARED_KV binding)
• Set secrets
• Deploy
• Run setup script

6. Testing

npm test                    # Unit tests
npm run test:e2e:node       # E2E against Node.js
npm run test:e2e:cloudflare # E2E against Cloudflare
npm run test:coverage       # Coverage

7. Architecture

• Hexagonal architecture diagram
• Ports explanation:
  • ActorStoragePort (per-user data)
  • SharedStoragePort (global data)
  • BlobPort (binary storage)
  • WebSocketPort (real-time)

8. Packages

Table of all packages with descriptions:

• @pdsjs/core
• @pdsjs/node
• @pdsjs/cloudflare
• @pdsjs/storage-better-sqlite3
• @pdsjs/blobs-fs
• @pdsjs/blobs-s3

Basic usage examples for Node.js and Cloudflare.

9. Contributing

• PR requirements (tests, format, typecheck)
• Development commands
• Project structure overview

Additional Tasks

1. Update examples/cloudflare/wrangler.toml to include KV namespace binding
2. Add npm run dev:node script to package.json
3. Add npm run dev:cloudflare script to package.json
4. Update .env.example to include Node.js-specific variables

Implementation Plan

Task 1: Update package.json scripts

Add dev:node and dev:cloudflare scripts.

Task 2: Update examples/cloudflare/wrangler.toml

Add SHARED_KV binding placeholder.

Task 3: Update .env.example

Add Node.js-specific variables.

Task 4: Rewrite README.md

Replace current Cloudflare-focused README with new multi-platform version.

Verification

• Run npm test to ensure nothing broken
• Run npm run dev:node to verify script works
• Review README renders correctly