linkedin-automation-cli 1.0.0

package/docs/plans/2026-03-03-linkedin-cli-oss-publishing-plan.md

@@ -0,0 +1,1592 @@
+# LinkedIn CLI Open Source Publishing Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Prepare the LinkedIn CLI for open source publication with comprehensive testing, OSS metadata, CI/CD, and documentation.
+
+**Architecture:** Three-phase approach: (1) Critical items for basic publishing, (2) Important items for quality, (3) Nice-to-have improvements. Each phase builds incrementally with tests first.
+
+**Tech Stack:** Go 1.21+, Cobra CLI, PinchTab HTTP client, GitHub Actions, Go testing package.
+
+---
+
+## Phase 1: Critical (Must Have)
+
+### Task 1: Add MIT LICENSE File
+
+**Files:**
+- Create: `LICENSE`
+
+**Step 1: Write LICENSE file**
+
+```
+MIT License
+
+Copyright (c) 2026 Thaddeus Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+**Step 2: Commit**
+
+```bash
+git add LICENSE
+git commit -m "docs: add MIT license for open source distribution"
+```
+
+---
+
+### Task 2: Add URL Validator Tests
+
+**Files:**
+- Create: `internal/linkedin/validator_test.go`
+- Reference: `internal/linkedin/validator.go`
+
+**Step 1: Write validator tests**
+
+```go
+package linkedin
+
+import "testing"
+
+func TestValidateProfileURL(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr bool
+	}{
+		{
+			name:  "full URL with https",
+			input: "https://linkedin.com/in/john-doe",
+			want:  "https://linkedin.com/in/john-doe",
+		},
+		{
+			name:  "full URL with http",
+			input: "http://linkedin.com/in/john-doe",
+			want:  "http://linkedin.com/in/john-doe",
+		},
+		{
+			name:  "vanity URL without protocol",
+			input: "linkedin.com/in/john-doe",
+			want:  "https://linkedin.com/in/john-doe",
+		},
+		{
+			name:  "username only",
+			input: "john-doe",
+			want:  "https://linkedin.com/in/john-doe",
+		},
+		{
+			name:    "non-LinkedIn URL",
+			input:   "https://example.com/john",
+			wantErr: true,
+		},
+		{
+			name:    "URL without /in/",
+			input:   "https://linkedin.com/company/example",
+			wantErr: true,
+		},
+		{
+			name:    "empty input",
+			input:   "",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ValidateProfileURL(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ValidateProfileURL() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if got != tt.want {
+				t.Errorf("ValidateProfileURL() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestExtractProfileUsername(t *testing.T) {
+	tests := []struct {
+		name string
+		url  string
+		want string
+	}{
+		{
+			name: "full URL",
+			url:  "https://linkedin.com/in/john-doe",
+			want: "john-doe",
+		},
+		{
+			name: "URL with trailing slash",
+			url:  "https://linkedin.com/in/john-doe/",
+			want: "john-doe",
+		},
+		{
+			name: "invalid URL",
+			url:  "not-a-url",
+			want: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ExtractProfileUsername(tt.url)
+			if got != tt.want {
+				t.Errorf("ExtractProfileUsername() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+```
+
+**Step 2: Run test to verify it passes**
+
+```bash
+go test -v ./internal/linkedin/...
+```
+
+Expected: PASS
+
+**Step 3: Commit**
+
+```bash
+git add internal/linkedin/validator_test.go
+git commit -m "test: add URL validator tests"
+```
+
+---
+
+### Task 3: Add Rate Limiter Tests
+
+**Files:**
+- Create: `internal/ratelimit/limiter_test.go`
+- Reference: `internal/ratelimit/limiter.go`
+
+**Step 1: Write limiter tests**
+
+```go
+package ratelimit
+
+import (
+	"testing"
+	"time"
+
+	"github.com/thaddeus-git/linkedin-cli/internal/config"
+)
+
+func TestLimiterCheckConnection(t *testing.T) {
+	tempDir := t.TempDir()
+	mgr := &config.Manager{}
+	// Inject temp dir via reflection or helper
+
+	limits := DefaultLimits()
+	limiter := NewLimiter("test", limits, mgr)
+
+	// Test under limit
+	err := limiter.CheckConnection()
+	if err != nil {
+		t.Errorf("expected no error when under limit, got %v", err)
+	}
+}
+
+func TestLimiterCheckConnectionExceeded(t *testing.T) {
+	limits := Limits{
+		ConnectionsDaily:  20,
+		ConnectionsWeekly: 100,
+	}
+
+	state := &config.RateLimits{
+		Connections: config.RateLimit{
+			Today:      20,
+			ThisWeek:   100,
+			LastAction: time.Now(),
+		},
+	}
+
+	if state.CanConnect(limits.ConnectionsDaily, limits.ConnectionsWeekly) {
+		t.Error("should not allow connection when at limit")
+	}
+}
+
+func TestLimiterRecordConnection(t *testing.T) {
+	tempDir := t.TempDir()
+	mgr := &config.Manager{}
+
+	limiter := NewLimiter("test", DefaultLimits(), mgr)
+
+	// Record connection
+	err := limiter.RecordConnection()
+	if err != nil {
+		t.Fatalf("failed to record connection: %v", err)
+	}
+
+	// Verify recorded
+	loaded, err := mgr.LoadRateLimits("test")
+	if err != nil {
+		t.Fatalf("failed to load rate limits: %v", err)
+	}
+
+	if loaded.Connections.Today != 1 {
+		t.Errorf("expected 1 connection recorded, got %d", loaded.Connections.Today)
+	}
+}
+
+func TestLimiterGetDelay(t *testing.T) {
+	limiter := NewLimiter("test", DefaultLimits(), nil)
+
+	delay := limiter.GetDelay()
+	minDelay := time.Duration(DefaultLimits().MinDelaySeconds) * time.Second
+	maxDelay := time.Duration(DefaultLimits().MaxDelaySeconds) * time.Second
+
+	if delay < minDelay || delay > maxDelay {
+		t.Errorf("delay %v outside expected range [%v, %v]", delay, minDelay, maxDelay)
+	}
+}
+```
+
+**Step 2: Run test to verify it passes**
+
+```bash
+go test -v ./internal/ratelimit/...
+```
+
+Expected: PASS (may need to fix config manager injection)
+
+**Step 3: Commit**
+
+```bash
+git add internal/ratelimit/limiter_test.go
+git commit -m "test: add rate limiter tests"
+```
+
+---
+
+### Task 4: Add Limits Tests
+
+**Files:**
+- Create: `internal/ratelimit/limits_test.go`
+
+**Step 1: Write limits tests**
+
+```go
+package ratelimit
+
+import "testing"
+
+func TestDefaultLimits(t *testing.T) {
+	limits := DefaultLimits()
+
+	if limits.ConnectionsDaily != 20 {
+		t.Errorf("expected 20 daily connections, got %d", limits.ConnectionsDaily)
+	}
+
+	if limits.ConnectionsWeekly != 100 {
+		t.Errorf("expected 100 weekly connections, got %d", limits.ConnectionsWeekly)
+	}
+
+	if limits.MessagesDaily != 50 {
+		t.Errorf("expected 50 daily messages, got %d", limits.MessagesDaily)
+	}
+
+	if limits.MinDelaySeconds != 3 {
+		t.Errorf("expected 3s min delay, got %d", limits.MinDelaySeconds)
+	}
+
+	if limits.MaxDelaySeconds != 8 {
+		t.Errorf("expected 8s max delay, got %d", limits.MaxDelaySeconds)
+	}
+}
+
+func TestConservativeLimits(t *testing.T) {
+	limits := ConservativeLimits()
+
+	if limits.ConnectionsDaily != 10 {
+		t.Errorf("expected 10 daily connections, got %d", limits.ConnectionsDaily)
+	}
+
+	if limits.ConnectionsWeekly != 50 {
+		t.Errorf("expected 50 weekly connections, got %d", limits.ConnectionsWeekly)
+	}
+
+	if limits.MessagesDaily != 25 {
+		t.Errorf("expected 25 daily messages, got %d", limits.MessagesDaily)
+	}
+
+	if limits.MinDelaySeconds != 5 {
+		t.Errorf("expected 5s min delay, got %d", limits.MinDelaySeconds)
+	}
+
+	if limits.MaxDelaySeconds != 12 {
+		t.Errorf("expected 12s max delay, got %d", limits.MaxDelaySeconds)
+	}
+}
+```
+
+**Step 2: Run test to verify it passes**
+
+```bash
+go test -v ./internal/ratelimit/...
+```
+
+Expected: PASS
+
+**Step 3: Commit**
+
+```bash
+git add internal/ratelimit/limits_test.go
+git commit -m "test: add limits configuration tests"
+```
+
+---
+
+### Task 5: Add Version Flag
+
+**Files:**
+- Modify: `cmd/linkedin/main.go`
+- Modify: `internal/cmd/root.go`
+- Modify: `Makefile`
+
+**Step 1: Modify main.go to add version variable**
+
+```go
+package main
+
+import (
+	"github.com/thaddeus-git/linkedin-cli/internal/cmd"
+)
+
+var Version = "dev"
+
+func main() {
+	cmd.Version = Version
+	cmd.Execute()
+}
+```
+
+**Step 2: Modify root.go to add version flag**
+
+```go
+var rootCmd = &cobra.Command{
+	Use:   "linkedin",
+	Short: "LinkedIn automation CLI",
+	// ... existing Long ...
+}
+
+func init() {
+	// ... existing flags ...
+	
+	cobra.OnInitialize(initConfig)
+	rootCmd.Version = "dev" // Will be set by main
+}
+```
+
+**Step 3: Modify Makefile to build with version**
+
+```makefile
+VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
+
+build:
+	go build -ldflags "-X main.Version=$(VERSION)" -o $(BINARY_NAME) $(MAIN_PACKAGE)
+```
+
+**Step 4: Test version command**
+
+```bash
+make build
+./linkedin-cli --version
+```
+
+Expected: Output like `linkedin-cli version 0.1.0` or `linkedin-cli version dev`
+
+**Step 5: Commit**
+
+```bash
+git add cmd/linkedin/main.go internal/cmd/root.go Makefile
+git commit -m "feat: add version flag"
+```
+
+---
+
+### Task 6: Run All Tests and Verify Coverage
+
+**Step 1: Run all tests**
+
+```bash
+go test -v ./...
+```
+
+Expected: All tests PASS
+
+**Step 2: Check coverage**
+
+```bash
+go test -coverprofile=coverage.out ./...
+go tool cover -func=coverage.out
+```
+
+Expected: See coverage percentages per package
+
+**Step 3: Commit test results**
+
+```bash
+git add coverage.out
+git commit -m "test: verify all tests passing with coverage"
+```
+
+---
+
+## Phase 2: Important (Should Have)
+
+### Task 7: Create CONTRIBUTING.md
+
+**Files:**
+- Create: `CONTRIBUTING.md`
+
+**Step 1: Write CONTRIBUTING.md**
+
+```markdown
+# Contributing to LinkedIn CLI
+
+Thank you for considering contributing to LinkedIn CLI! This guide will help you get started.
+
+## Development Setup
+
+### Prerequisites
+
+- Go 1.21 or higher
+- PinchTab installed (`curl -fsSL https://pinchtab.com/install.sh | bash`)
+
+### Installation
+
+```bash
+git clone https://github.com/thaddeus-git/linkedin-cli.git
+cd linkedin-cli
+go build -o linkedin-cli ./cmd/linkedin
+```
+
+### Running Tests
+
+```bash
+go test -v ./...
+```
+
+### Running Linter
+
+```bash
+make lint
+```
+
+## Code Style
+
+- Follow Go best practices
+- Use `go fmt` and `go vet`
+- Write tests for new functionality
+- Keep functions small and focused
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests and ensure they pass
+5. Commit with clear messages
+6. Push and open a PR
+
+## Issue Reporting
+
+### Bug Reports
+
+Include:
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- Environment (OS, Go version)
+
+### Feature Requests
+
+Include:
+- Problem you're trying to solve
+- Proposed solution
+- Alternative approaches considered
+
+## Questions?
+
+Open an issue for any questions about the codebase or contribution process.
+```
+
+**Step 2: Commit**
+
+```bash
+git add CONTRIBUTING.md
+git commit -m "docs: add contributing guide"
+```
+
+---
+
+### Task 8: Create GitHub Issue Templates
+
+**Files:**
+- Create: `.github/ISSUE_TEMPLATE/bug_report.md`
+- Create: `.github/ISSUE_TEMPLATE/feature_request.md`
+
+**Step 1: Write bug report template**
+
+```markdown
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## To Reproduce
+
+Steps to reproduce the behavior:
+1. Run command '...'
+2. With options '...'
+3. See error
+
+## Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+## Actual behavior
+
+What actually happened.
+
+## Environment
+
+- OS: [e.g., macOS 14.0, Ubuntu 22.04]
+- Go version: [e.g., 1.21.0]
+- LinkedIn CLI version: [e.g., 0.1.0]
+
+## Additional context
+
+Add any other context about the problem here.
+```
+
+**Step 2: Write feature request template**
+
+```markdown
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+## Problem
+
+What problem are you trying to solve?
+
+## Proposed Solution
+
+Describe the solution you'd like.
+
+## Alternative Approaches
+
+Describe any alternative solutions or features you've considered.
+
+## Additional Context
+
+Add any other context or examples about the feature request here.
+```
+
+**Step 3: Commit**
+
+```bash
+git add .github/ISSUE_TEMPLATE/
+git commit -m "docs: add issue templates for bugs and features"
+```
+
+---
+
+### Task 9: Create PR Template
+
+**Files:**
+- Create: `.github/PULL_REQUEST_TEMPLATE.md`
+
+**Step 1: Write PR template**
+
+```markdown
+## Description
+
+Brief description of the changes in this PR.
+
+## Related Issue
+
+Link to the related issue (if applicable).
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Code quality improvements
+
+## Testing
+
+- [ ] Tests pass locally (`go test ./...`)
+- [ ] Code is formatted (`go fmt ./...`)
+- [ ] New tests added for new functionality
+
+## Checklist
+
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] New and existing tests pass locally with my changes
+
+## Additional Notes
+
+Any additional information for reviewers.
+```
+
+**Step 2: Commit**
+
+```bash
+git add .github/PULL_REQUEST_TEMPLATE.md
+git commit -m "docs: add pull request template"
+```
+
+---
+
+### Task 10: Create CI/CD Workflow
+
+**Files:**
+- Create: `.github/workflows/ci.yml`
+
+**Step 1: Write CI workflow**
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      - name: Install dependencies
+        run: go mod download
+
+      - name: Run tests
+        run: go test -v -race ./...
+
+      - name: Run tests with coverage
+        run: go test -coverprofile=coverage.out ./...
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.out
+          flags: unittests
+
+  build:
+    name: Build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        arch: [amd64, arm64]
+        exclude:
+          - os: windows-latest
+            arch: arm64
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      - name: Build
+        run: go build -o linkedin-cli ./cmd/linkedin
+        env:
+          GOOS: ${{ matrix.os == 'windows-latest' && 'windows' || (matrix.os == 'macos-latest' && 'darwin' || 'linux') }}
+          GOARCH: ${{ matrix.arch }}
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      - name: Install golangci-lint
+        uses: golangci/golangci-lint-action@v4
+        with:
+          version: latest
+```
+
+**Step 2: Commit**
+
+```bash
+git add .github/workflows/ci.yml
+git commit -m "ci: add GitHub Actions CI workflow"
+```
+
+---
+
+### Task 11: Add Structured Logging
+
+**Files:**
+- Modify: `internal/cmd/root.go`
+- Modify: `internal/cmd/auth.go`
+- Modify: `internal/cmd/connect.go`
+- Modify: `internal/cmd/message.go`
+
+**Step 1: Add slog to root.go**
+
+```go
+import (
+	"log/slog"
+	"os"
+	// ... existing imports
+)
+
+var logger *slog.Logger
+
+func init() {
+	// ... existing init ...
+	
+	// Initialize logger
+	level := slog.LevelInfo
+	if verbose {
+		level = slog.LevelDebug
+	}
+	
+	opts := &slog.HandlerOptions{Level: level}
+	logger = slog.New(slog.NewTextHandler(os.Stdout, opts))
+}
+```
+
+**Step 2: Update verbose logging in root.go**
+
+```go
+// logVerbose prints if verbose mode is enabled
+func logVerbose(format string, args ...interface{}) {
+	logger.Debug(fmt.Sprintf(format, args...))
+}
+```
+
+**Step 3: Update auth.go**
+
+```go
+// Before
+fmt.Printf("Starting authentication for profile '%s'...\n", profileName)
+logVerbose("Using PinchTab at %s", getPinchTabHost())
+
+// After
+logger.Info("starting authentication", "profile", profileName)
+logger.Debug("pinchtab host", "host", getPinchTabHost())
+```
+
+**Step 4: Test logging**
+
+```bash
+make build
+./linkedin-cli auth --profile test --verbose
+```
+
+Expected: See debug logs with `[DEBUG]` prefix
+
+**Step 5: Commit**
+
+```bash
+git add internal/cmd/*.go
+git commit -m "feat: add structured logging with slog"
+```
+
+---
+
+### Task 12: Add Rate Limit Documentation
+
+**Files:**
+- Create: `docs/RATE_LIMITS.md`
+
+**Step 1: Write rate limits documentation**
+
+```markdown
+# Rate Limits
+
+LinkedIn CLI includes built-in rate limiting to keep your LinkedIn account safe from automated detection.
+
+## Default Limits
+
+| Action | Daily Limit | Weekly Limit |
+|--------|-------------|--------------|
+| Connection requests | 20 | 100 |
+| Direct messages | 50 | N/A |
+
+## Delays
+
+Between actions, LinkedIn CLI waits a random duration:
+
+- **Default:** 3-8 seconds
+- **Conservative mode:** 5-12 seconds
+
+## Conservative Mode
+
+For new LinkedIn accounts (< 3 months), use conservative limits:
+
+```bash
+linkedin connect --profile new-account --conservative
+```
+
+This applies:
+- 10 connections/day (instead of 20)
+- 50 connections/week (instead of 100)
+- 25 messages/day (instead of 50)
+- 5-12 second delays (instead of 3-8)
+
+## How It Works
+
+1. **Tracking:** Actions are tracked per profile in `~/.linkedin-cli/ratelimit.json`
+2. **Reset:** Daily counters reset at midnight (local time)
+3. **Reset:** Weekly counters reset on Monday (ISO week)
+4. **Blocking:** Commands fail with error if limit exceeded
+
+## Viewing Rate Limits
+
+```bash
+linkedin profiles list
+```
+
+Shows rate limit status for each profile.
+
+## Safety Tips
+
+1. **Don't increase limits** - LinkedIn's detection is sophisticated
+2. **Use multiple profiles** - Distribute automation across accounts
+3. **Monitor account health** - Watch for LinkedIn warnings
+4. **Start conservative** - Begin with low volume, increase gradually
+
+## Bypassing Limits (Not Recommended)
+
+You can bypass limits with `--no-rate-limit` flag, but this risks:
+- LinkedIn account restrictions
+- Permanent bans
+- Detection as automated behavior
+
+**Use at your own risk.**
+
+## LinkedIn's Actual Limits
+
+LinkedIn doesn't publish exact limits, but community observations suggest:
+- ~100 connection requests/week for established accounts
+- Lower limits for new accounts
+- Additional behavioral detection (mouse movement, timing patterns)
+
+LinkedIn CLI uses conservative defaults based on community feedback.
+```
+
+**Step 2: Commit**
+
+```bash
+git add docs/RATE_LIMITS.md
+git commit -m "docs: add rate limits documentation"
+```
+
+---
+
+## Phase 3: Nice to Have
+
+### Task 13: Add Testable Time Handling
+
+**Files:**
+- Modify: `internal/linkedin/navigator.go`
+- Create: `internal/linkedin/sleeper.go`
+- Modify: `internal/linkedin/navigator_test.go` (from Task 14)
+
+**Step 1: Create sleeper interface**
+
+```go
+package linkedin
+
+import "time"
+
+// Sleeper abstracts time.Sleep for testability
+type Sleeper interface {
+	Sleep(time.Duration)
+}
+
+// RealSleeper uses actual time.Sleep
+type RealSleeper struct{}
+
+func (RealSleeper) Sleep(d time.Duration) {
+	time.Sleep(d)
+}
+
+// NoOpSleeper is used in tests
+type NoOpSleeper struct{}
+
+func (NoOpSleeper) Sleep(time.Duration) {}
+```
+
+**Step 2: Update Navigator struct**
+
+```go
+type Navigator struct {
+	client  *pinchtab.Client
+	sleeper Sleeper
+}
+
+func NewNavigator(client *pinchtab.Client) *Navigator {
+	return &Navigator{
+		client:  client,
+		sleeper: RealSleeper{},
+	}
+}
+```
+
+**Step 3: Update navigation methods**
+
+```go
+// Before
+time.Sleep(3 * time.Second)
+
+// After
+n.sleeper.Sleep(3 * time.Second)
+```
+
+**Step 4: Commit**
+
+```bash
+git add internal/linkedin/sleeper.go internal/linkedin/navigator.go
+git commit -m "refactor: add testable sleeper interface"
+```
+
+---
+
+### Task 14: Add Navigator Tests
+
+**Files:**
+- Create: `internal/linkedin/navigator_test.go`
+- Create: `internal/linkedin/client_mock.go`
+
+**Step 1: Create mock client**
+
+```go
+package linkedin
+
+import "github.com/thaddeus-git/linkedin-cli/internal/pinchtab"
+
+// MockPinchTabClient for testing
+type MockPinchTabClient struct {
+	SnapshotFunc    func(filter string) (*pinchtab.Snapshot, error)
+	NavigateFunc    func(url string) error
+	ClickFunc       func(ref string) error
+	TypeFunc        func(ref string, text string) error
+	GetTextFunc     func() (*pinchtab.TextResponse, error)
+	CalledMethods   map[string]int
+}
+
+func NewMockClient() *MockPinchTabClient {
+	return &MockPinchTabClient{
+		CalledMethods: make(map[string]int),
+	}
+}
+
+func (m *MockPinchTabClient) Navigate(url string) error {
+	m.CalledMethods["Navigate"]++
+	if m.NavigateFunc != nil {
+		return m.NavigateFunc(url)
+	}
+	return nil
+}
+
+func (m *MockPinchTabClient) GetSnapshot(filter string) (*pinchtab.Snapshot, error) {
+	m.CalledMethods["GetSnapshot"]++
+	if m.SnapshotFunc != nil {
+		return m.SnapshotFunc(filter)
+	}
+	return &pinchtab.Snapshot{}, nil
+}
+
+func (m *MockPinchTabClient) HumanClick(ref string) error {
+	m.CalledMethods["HumanClick"]++
+	if m.ClickFunc != nil {
+		return m.ClickFunc(ref)
+	}
+	return nil
+}
+
+func (m *MockPinchTabClient) HumanType(ref string, text string) error {
+	m.CalledMethods["HumanType"]++
+	if m.TypeFunc != nil {
+		return m.TypeFunc(ref, text)
+	}
+	return nil
+}
+
+func (m *MockPinchTabClient) GetText() (*pinchtab.TextResponse, error) {
+	m.CalledMethods["GetText"]++
+	if m.GetTextFunc != nil {
+		return m.GetTextFunc()
+	}
+	return &pinchtab.TextResponse{}, nil
+}
+```
+
+**Step 2: Write navigator tests**
+
+```go
+package linkedin
+
+import (
+	"testing"
+
+	"github.com/thaddeus-git/linkedin-cli/internal/pinchtab"
+)
+
+func TestFindConnectButton(t *testing.T) {
+	mock := NewMockClient()
+	navigator := NewNavigator(mock)
+	navigator.sleeper = NoOpSleeper{}
+
+	snapshot := &pinchtab.Snapshot{
+		Nodes: []pinchtab.Node{
+			{Ref: "e0", Role: "button", Name: "View profile"},
+			{Ref: "e1", Role: "button", Name: "Connect"},
+			{Ref: "e2", Role: "link", Name: "Message"},
+		},
+	}
+
+	button, err := navigator.FindConnectButton(snapshot)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if button.Ref != "e1" {
+		t.Errorf("expected ref e1, got %s", button.Ref)
+	}
+}
+
+func TestFindConnectButtonNotFound(t *testing.T) {
+	mock := NewMockClient()
+	navigator := NewNavigator(mock)
+
+	snapshot := &pinchtab.Snapshot{
+		Nodes: []pinchtab.Node{
+			{Ref: "e0", Role: "button", Name: "View profile"},
+			{Ref: "e1", Role: "link", Name: "Message"},
+		},
+	}
+
+	_, err := navigator.FindConnectButton(snapshot)
+	if err == nil {
+		t.Error("expected error when connect button not found")
+	}
+}
+
+func TestClickConnect(t *testing.T) {
+	mock := NewMockClient()
+	mock.SnapshotFunc = func(filter string) (*pinchtab.Snapshot, error) {
+		return &pinchtab.Snapshot{
+			Nodes: []pinchtab.Node{
+				{Ref: "e1", Role: "button", Name: "Connect"},
+			},
+		}, nil
+	}
+
+	navigator := NewNavigator(mock)
+	navigator.sleeper = NoOpSleeper{}
+
+	err := navigator.ClickConnect()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if mock.CalledMethods["GetSnapshot"] != 1 {
+		t.Errorf("expected 1 GetSnapshot call, got %d", mock.CalledMethods["GetSnapshot"])
+	}
+
+	if mock.CalledMethods["HumanClick"] != 1 {
+		t.Errorf("expected 1 HumanClick call, got %d", mock.CalledMethods["HumanClick"])
+	}
+}
+```
+
+**Step 3: Run tests**
+
+```bash
+go test -v ./internal/linkedin/...
+```
+
+Expected: All tests PASS
+
+**Step 4: Commit**
+
+```bash
+git add internal/linkedin/navigator_test.go internal/linkedin/client_mock.go
+git commit -m "test: add navigator tests with mock client"
+```
+
+---
+
+### Task 15: Update README with Badges
+
+**Files:**
+- Modify: `README.md`
+
+**Step 1: Add badges to top of README**
+
+```markdown
+# LinkedIn CLI
+
+[![CI](https://github.com/thaddeus-git/linkedin-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/thaddeus-git/linkedin-cli/actions/workflows/ci.yml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/thaddeus-git/linkedin-cli)](https://goreportcard.com/report/github.com/thaddeus-git/linkedin-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Go version](https://img.shields.io/badge/Go-1.21+-blue.svg)](https://go.dev)
+
+A CLI tool for LinkedIn automation using PinchTab...
+```
+
+**Step 2: Add "How It Works" diagram**
+
+```markdown
+## How It Works
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│  LinkedIn   │◄────│   PinchTab   │◄────│ linkedin-cli│
+│   (web)     │     │   (browser)  │     │   (CLI)     │
+└─────────────┘     └──────────────┘     └─────────────┘
+```
+
+1. **You run commands** → `linkedin connect --profile john --url ...`
+2. **CLI validates input** → Check rate limits, validate URLs
+3. **PinchTab controls browser** → Navigate, click, type
+4. **LinkedIn receives actions** → As if from human user
+```
+
+**Step 3: Add troubleshooting section**
+
+```markdown
+## Troubleshooting
+
+### "Profile not found"
+
+Run `linkedin auth --profile <name>` first to authenticate.
+
+### "Rate limit exceeded"
+
+Wait 24 hours for daily reset, or use a different profile.
+
+### "Connect button not found"
+
+- Profile may already be connected
+- Profile URL may be incorrect
+- LinkedIn may have changed their UI (report as bug)
+
+### PinchTab not starting
+
+```bash
+curl -fsSL https://pinchtab.com/install.sh | bash
+pinchtab
+```
+
+### Connection refused error
+
+Make sure PinchTab is running:
+
+```bash
+curl http://localhost:9867/health
+```
+
+Should return: `{"status":"ok"}`
+```
+
+**Step 4: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: update README with badges and troubleshooting"
+```
+
+---
+
+### Task 16: Create Architecture Documentation
+
+**Files:**
+- Create: `docs/ARCHITECTURE.md`
+
+**Step 1: Write architecture documentation**
+
+```markdown
+# Architecture
+
+This document describes the architecture of LinkedIn CLI.
+
+## Package Structure
+
+```
+linkedin-cli/
+├── cmd/linkedin/       # Application entry point
+├── internal/           # Private packages
+│   ├── cmd/           # Cobra command implementations
+│   ├── config/        # Configuration persistence
+│   ├── linkedin/      # LinkedIn page interactions
+│   ├── pinchtab/      # PinchTab HTTP client
+│   └── ratelimit/     # Rate limiting logic
+└── docs/              # Documentation
+```
+
+## Package Responsibilities
+
+### cmd/linkedin
+
+**Entry point:** `main()`
+
+**Responsibilities:**
+- Parse command-line arguments
+- Execute appropriate command
+- Handle exit codes
+
+### internal/cmd
+
+**Commands:**
+- `auth` - Authenticate LinkedIn profile
+- `connect` - Send connection request
+- `message` - Send direct message
+- `profiles` - List/remove profiles
+
+**Responsibilities:**
+- Parse command flags
+- Validate inputs
+- Execute business logic
+- Display results to user
+
+### internal/config
+
+**Types:**
+- `Manager` - Config file management
+- `Profile` - LinkedIn profile data
+- `RateLimits` - Rate limit state
+
+**Responsibilities:**
+- Read/write JSON config files
+- Manage profile metadata
+- Persist rate limit counters
+
+**Storage:**
+- `~/.linkedin-cli/profiles/<name>.json`
+- `~/.linkedin-cli/ratelimit.json`
+
+### internal/linkedin
+
+**Types:**
+- `Navigator` - Page interaction logic
+- `Selectors` - CSS selectors for LinkedIn UI
+
+**Responsibilities:**
+- Navigate to LinkedIn pages
+- Find and click buttons
+- Fill forms
+- Handle modals
+
+**Note:** These selectors are fragile and may need updates as LinkedIn changes their UI.
+
+### internal/pinchtab
+
+**Types:**
+- `Client` - HTTP API wrapper
+
+**Responsibilities:**
+- Navigate browser
+- Get accessibility snapshots
+- Click/type elements
+- Extract page text
+
+**API Endpoints Used:**
+- `POST /navigate`
+- `GET /snapshot`
+- `POST /action`
+- `GET /text`
+
+### internal/ratelimit
+
+**Types:**
+- `Limiter` - Rate limit enforcement
+- `Limits` - Limit thresholds
+
+**Responsibilities:**
+- Check if action is allowed
+- Record completed actions
+- Calculate random delays
+- Reset counters (daily/weekly)
+
+## Data Flow
+
+### Connection Request Flow
+
+```
+User → cmd/connect.go → Check rate limits
+    ↓
+ratelimit/limiter.go → Load profile state
+    ↓
+config.Manager → Read ~/.linkedin-cli/ratelimit.json
+    ↓
+If allowed → linkedin.Navigator → PinchTab.Client
+    ↓
+PinchTab API → Browser → LinkedIn
+    ↓
+Success → Record in rate limits
+```
+
+## Error Handling
+
+**Pattern:** Wrap errors with context
+
+```go
+if err := navigator.ClickConnect(); err != nil {
+    return fmt.Errorf("failed to click connect: %w", err)
+}
+```
+
+**User-facing errors:** Clear and actionable
+
+```go
+fmt.Fprintf(os.Stderr, "Error: Rate limit exceeded. Try again tomorrow.\n")
+```
+
+## Testing Strategy
+
+**Unit Tests:**
+- Config CRUD operations
+- URL validation
+- Rate limit logic
+- PinchTab client (mock HTTP)
+
+**Integration Tests:**
+- Manual test script (`test_auth.sh`)
+- Future: automated with mock LinkedIn
+
+**Test Files:**
+- `*_test.go` alongside source files
+- Mock implementations in `client_mock.go`
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `github.com/spf13/cobra` | CLI framework |
+| `log/slog` | Structured logging (Go 1.21+) |
+| PinchTab | Browser automation (external binary) |
+
+## Security Considerations
+
+1. **Credentials:** Never stored - user logs in manually
+2. **Sessions:** Stored in PinchTab's Chrome profile (`~/.pinchtab/`)
+3. **Config:** Local files only, no cloud sync
+4. **Network:** Only localhost (PinchTab) and LinkedIn.com
+
+## Future Improvements
+
+- [ ] LinkedIn selector auto-discovery
+- [ ] Proxy support
+- [ ] Multi-account rotation
+- [ ] Analytics dashboard
+- [ ] Webhook notifications
+```
+
+**Step 2: Commit**
+
+```bash
+git add docs/ARCHITECTURE.md
+git commit -m "docs: add architecture documentation"
+```
+
+---
+
+### Task 17: Add CODEOWNERS and SECURITY.md
+
+**Files:**
+- Create: `.github/CODEOWNERS`
+- Create: `docs/SECURITY.md`
+
+**Step 1: Write CODEOWNERS**
+
+```
+# Default owners
+* @thaddeus-git
+
+# Package-specific reviewers
+internal/linkedin/ @thaddeus-git
+internal/pinchtab/ @thaddeus-git
+```
+
+**Step 2: Write SECURITY.md**
+
+```markdown
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+**DO NOT create a public issue.**
+
+Email: thaddeus@example.com (replace with actual)
+
+Include:
+- Description of vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+You will receive a response within 48 hours.
+
+## Security Considerations
+
+### What This Tool Does
+
+- Automates LinkedIn browser interactions
+- Stores session cookies locally
+- Saves profile metadata
+
+### What This Tool Does NOT Do
+
+- Upload data to cloud services
+- Store LinkedIn credentials
+- Modify LinkedIn's backend
+
+### Risks
+
+1. **LinkedIn Detection:** Automation may violate LinkedIn's ToS
+2. **Account Restrictions:** LinkedIn may limit or ban accounts
+3. **Local Data:** Session cookies stored on your machine
+
+### Mitigation
+
+- Use rate limiting (enabled by default)
+- Use separate profiles for different accounts
+- Monitor account health
+- Don't exceed safe limits
+
+## Responsible Disclosure
+
+We appreciate responsible disclosure and will work with you to address security issues promptly.
+```
+
+**Step 3: Commit**
+
+```bash
+git add .github/CODEOWNERS docs/SECURITY.md
+git commit -m "docs: add CODEOWNERS and security policy"
+```
+
+---
+
+### Task 18: Final Verification and Cleanup
+
+**Step 1: Run all tests**
+
+```bash
+go test -v -cover ./...
+```
+
+Expected: All tests PASS, coverage >= 70%
+
+**Step 2: Run linter**
+
+```bash
+make lint
+```
+
+Expected: No errors (or fix them)
+
+**Step 3: Format code**
+
+```bash
+go fmt ./...
+go vet ./...
+```
+
+**Step 4: Build for all platforms**
+
+```bash
+GOOS=linux GOARCH=amd64 go build -o linkedin-cli-linux ./cmd/linkedin
+GOOS=darwin GOARCH=arm64 go build -o linkedin-cli-mac ./cmd/linkedin
+GOOS=windows GOARCH=amd64 go build -o linkedin-cli.exe ./cmd/linkedin
+```
+
+**Step 5: Commit all changes**
+
+```bash
+git add .
+git commit -m "chore: final verification and cleanup for open source release"
+```
+
+---
+
+## Verification Checklist
+
+- [ ] LICENSE file exists
+- [ ] All tests pass
+- [ ] Coverage >= 70%
+- [ ] CONTRIBUTING.md exists
+- [ ] CI workflow runs
+- [ ] --version flag works
+- [ ] README has badges
+- [ ] Issue templates exist
+- [ ] PR template exists
+- [ ] Architecture docs complete
+- [ ] Security policy exists
+
+---
+
+**Plan complete.** Open source publishing preparation is ready for implementation.