Make documentation generic and add CLI options

Author: Scott Kurtzeborn

GETTING-STARTED.md

@@ -1,144 +1,23 @@
 # Getting Started Guide
 
-This guide will walk you through setting up the URL shortener from scratch.
+This guide will help you set up the URL shortener for local development or production deployment.
 
-## Prerequisites
+## Quick Start
 
-- Azure subscription (free tier)
-- Cloudflare account (free tier)
-- GitHub account
-- Node.js 20+ installed
-- Azure CLI installed
-- Wrangler CLI installed (`npm install -g wrangler`)
+1. **Clone and Install**
+   ```bash
+   git clone https://github.com/yourusername/url-shortener.git
+   cd url-shortener
+   npm ci  # Install dependencies from lock file
+   ```
 
-## Step 1: Clone and Install
+2. **For Local Development** → Continue to [Local Development](#local-development) below
 
-```bash
-git clone https://github.com/kurtzeborn/url-shortener.git
-cd url-shortener
-npm ci  # Install dependencies from lock file
-```
-
-## Step 2: Azure Setup
-
-### 2.1 Create Storage Account
-
-```bash
-# Login to Azure
-az login
-
-# Create resource group
-az group create --name url-shortener-rg --location eastus
-
-# Create storage account
-az storage account create \
-  --name k61urlshortener \
-  --resource-group url-shortener-rg \
-  --location eastus \
-  --sku Standard_LRS
-
-# Get connection string (save this!)
-az storage account show-connection-string \
-  --name k61urlshortener \
-  --resource-group url-shortener-rg
-```
-
-### 2.2 Create Tables
-
-Go to Azure Portal → Storage Account → Table Storage and create:
-- `URLs`
-- `UserURLs`
-- `AllowedUsers`
-- `UserInvites`
-
-### 2.3 Add First User
-
-In Azure Portal → Table Storage → `AllowedUsers` table:
-- Click "Add Entity"
-- PartitionKey: `users`
-- RowKey: `your@email.com`
-- AddedDate: Current date/time
-- AddedBy: `system`
-
-### 2.4 Create Function App
-
-```bash
-az functionapp create \
-  --resource-group url-shortener-rg \
-  --consumption-plan-location eastus \
-  --runtime node \
-  --runtime-version 20 \
-  --functions-version 4 \
-  --name k61-url-functions \
-  --storage-account k61urlshortener
-
-# Get publish profile (save for GitHub secrets)
-az functionapp deployment list-publishing-profiles \
-  --name k61-url-functions \
-  --resource-group url-shortener-rg \
-  --xml
-```
-
-### 2.5 Create Static Web Apps
-
-```bash
-# For url.k61.dev (web app)
-az staticwebapp create \
-  --name k61-url-web \
-  --resource-group url-shortener-rg \
-  --location eastus2
-
-# Get deployment token (save for GitHub secrets)
-az staticwebapp secrets list \
-  --name k61-url-web \
-  --resource-group url-shortener-rg
-```
-
-## Step 3: Cloudflare Setup
-
-### 3.1 Add Domain to Cloudflare
-
-1. Go to Cloudflare Dashboard
-2. Click "Add a Site"
-3. Enter `k61.dev`
-4. Choose Free plan
-5. Update Namecheap nameservers to Cloudflare's
-
-### 3.2 Configure DNS
-
-Add these DNS records in Cloudflare:
-- `k61.dev` → CNAME to your Worker (will be set after deployment)
-- `url` → CNAME to Azure Static Web App (from Step 2.5)
-- `www` → CNAME to Azure Static Web App (from Step 2.5)
+3. **For Production Deployment** → See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)
 
-### 3.3 Get API Token
+---
 
-1. Cloudflare Dashboard → My Profile → API Tokens
-2. Create Token → Edit Cloudflare Workers template
-3. Save token for GitHub secrets
-
-## Step 4: GitHub Secrets
-
-Add these secrets in GitHub repository settings:
-
-### Cloudflare Worker
-- `CLOUDFLARE_API_TOKEN` - API token from Step 3.3
-- `DEFAULT_URL` - URL to redirect unknown/invalid IDs (e.g., https://url.k61.dev)
-- `AZURE_STORAGE_ACCOUNT` - Storage account name (k61urlshortener)
-- `AZURE_STORAGE_SAS` - SAS token from Azure Portal → Storage Account → Shared access signature
-- `AZURE_API_URL` - Azure Functions URL (e.g., https://k61-url-functions.azurewebsites.net)
-- `INTERNAL_API_KEY` - Generate a random secure key (e.g., `openssl rand -hex 32`)
-
-### Azure Functions
-- `AZURE_FUNCTIONAPP_NAME` - Function app name (k61-url-functions)
-- `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` - XML from Step 2.4
-
-### Azure Static Web Apps
-- `AZURE_STATIC_WEB_APPS_API_TOKEN_WEB` - Token from Step 2.5
-- `VITE_MICROSOFT_CLIENT_ID` - Microsoft Entra app registration client ID
-- `VITE_API_URL` - Azure Functions URL (e.g., https://k61-url-functions.azurewebsites.net)
-
-## Step 5: Local Development
+## Local Development
 
 ### Functions
 
@@ -159,51 +38,16 @@ npm install
 npm run dev  # Runs on http://localhost:5173
 ```
 
-### Cloudflare Worker
-
-```bash
-cd workers
-npm install
-wrangler dev  # Runs on http://localhost:8787
-```
-
-## Step 6: Deploy
-
-Push to main branch to trigger automatic deployments:
-
-```bash
-git add .
-git commit -m "Initial setup"
-git push origin main
-```
-
-GitHub Actions will automatically deploy:
-- Cloudflare Worker
-- Azure Functions
-- Web App (url.k61.dev)
-
-## Step 7: Configure Custom Domains
-
-### In Azure Portal
+---
 
-For each Static Web App:
-1. Go to Custom Domains
-2. Add domain (url.k61.dev and www.k61.dev)
-3. Follow validation instructions
+## Testing Locally
 
-### In Cloudflare
+1. Ensure Functions are running (`http://localhost:7071`)
+2. Visit web app (`http://localhost:5173`)
+3. Login with your allowlisted email
+4. Create a test shortened URL
 
-1. Ensure DNS records are set correctly
-2. Enable "Proxied" mode for k61.dev
-3. Configure Worker route: `k61.dev/*`
-
-## Testing
-
-1. Visit `https://url.k61.dev` - Should show login page
-2. Login with your allowlisted email
-3. Create a test shortened URL
-4. Visit `https://k61.dev/<id>` - Should redirect
-5. Check dashboard - Click count should increment
+---
 
 ## Troubleshooting
 
@@ -220,20 +64,4 @@ For each Static Web App:
 ### Static Web Apps not deploying
 - Check GitHub Actions logs
 - Verify deployment tokens are correct
-- Check build output in Actions
-
-## Next Steps
-
-- [x] ~~Implement Microsoft OAuth authentication~~ (Done)
-- [x] ~~Add comprehensive tests~~ (Done - 51 tests)
-- [ ] Set up monitoring/alerts
-- [ ] [Add URL analytics dashboard](https://github.com/kurtzeborn/url-shortener/issues/4)
-- [ ] [Implement custom aliases](https://github.com/kurtzeborn/url-shortener/issues/3)
-- [ ] [Add QR code generation](https://github.com/kurtzeborn/url-shortener/issues/8)
-
-## Support
-
-For issues, check:
-- GitHub Issues: https://github.com/kurtzeborn/url-shortener/issues
-- [docs/archive/PLAN.md](docs/archive/PLAN.md) for original architecture details
-- Individual component READMEs
+- Check build output in Actions

docs/API.md

@@ -1,6 +1,6 @@
 # URL Shortener API Documentation
 
-Base URL: `https://api.k61.dev` (production) or `http://localhost:7071` (development)
+Base URL: `https://<your-function-app>.azurewebsites.net` (production) or `http://localhost:7071` (development)
 
 ## Authentication
 
@@ -59,7 +59,7 @@ POST /api/urls
 ```json
 {
   "id": "aBc1",
-  "shortUrl": "https://k61.dev/aBc1",
+  "shortUrl": "https://yourdomain.com/aBc1",
   "url": "https://example.com/long/url",
   "createdAt": "2026-01-16T12:00:00.000Z",
   "clickCount": 0
@@ -87,7 +87,7 @@ GET /api/urls
   "urls": [
     {
       "id": "aBc1",
-      "shortUrl": "https://k61.dev/aBc1",
+      "shortUrl": "https://yourdomain.com/aBc1",
       "url": "https://example.com/long/url",
       "createdAt": "2026-01-16T12:00:00.000Z",
       "clickCount": 42
@@ -115,7 +115,7 @@ GET /api/urls/{id}
 ```json
 {
   "id": "aBc1",
-  "shortUrl": "https://k61.dev/aBc1",
+  "shortUrl": "https://yourdomain.com/aBc1",
   "url": "https://example.com/long/url",
   "createdAt": "2026-01-16T12:00:00.000Z",
   "clickCount": 42
@@ -140,7 +140,7 @@ PUT /api/urls/{id}
 ```json
 {
   "id": "aBc1",
-  "shortUrl": "https://k61.dev/aBc1",
+  "shortUrl": "https://yourdomain.com/aBc1",
   "url": "https://example.com/new/url",
   "updatedAt": "2026-01-16T13:00:00.000Z"
 }
@@ -229,6 +229,6 @@ X-Internal-Key: <INTERNAL_API_KEY>
 
 | Variable | Description |
 |----------|-------------|
-| `SHORT_URL_DOMAIN` | Domain for short URLs (default: `k61.dev`) |
+| `SHORT_URL_DOMAIN` | Domain for short URLs (e.g., `yourdomain.com`) |
 | `AZURE_STORAGE_CONNECTION_STRING` | Azure Table Storage connection |
 | `INTERNAL_API_KEY` | Key for internal API authentication |

docs/AUTH_SETUP.md

@@ -1,15 +1,17 @@
 # Authentication Setup Guide
 
-## Azure AD App Registration
+This guide covers Microsoft authentication configuration in detail. For the complete deployment process, see [DEPLOYMENT.md](DEPLOYMENT.md).
 
-To enable Microsoft authentication, you need to register an application in Azure AD:
+## Microsoft Entra ID App Registration
+
+To enable Microsoft authentication, you need to register an application in Microsoft Entra ID:
 
 ### Step 1: Create App Registration
 1. Go to [Azure Portal](https://portal.azure.com)
-2. Navigate to **Azure Active Directory** > **App registrations**
+2. Navigate to **Microsoft Entra ID** > **App registrations**
 3. Click **New registration**
 4. Fill in:
-   - **Name**: `URL Shortener (k61.dev)`
+   - **Name**: `URL Shortener`
    - **Supported account types**: Select one of:
      - "Personal Microsoft accounts only" (if only personal accounts)
      - "Accounts in any organizational directory and personal Microsoft accounts" (if both work and personal)
@@ -20,7 +22,7 @@ To enable Microsoft authentication, you need to register an application in Azure
 ### Step 2: Configure Redirect URIs
 After creation, go to **Authentication** and add:
 - `http://localhost:5173` (local development)
-- `https://url.k61.dev` (production)
+- `https://url.yourdomain.com` (production - replace with your actual domain)
 
 ### Step 3: Get Client ID
 1. Go to the app's **Overview** page