docs: Transform 51 README files to gold standard natural language API

.beads/daemon-error

@@ -0,0 +1,7 @@
+Error: Multiple database files found in /Users/nathanclevenger/projects/workers/.beads:
+  - beads.db
+  - issues.db
+
+Beads requires a single canonical database: beads.db
+Run 'bd init' to migrate legacy databases or manually remove old databases
+Or run 'bd doctor' for more diagnostics

.beads/last-touched

@@ -1 +1 @@
-research-zknk
+workers-1aybd

.claude/hooks/session-start.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Session start hook for Claude Code web
+# Installs beads (bd) issue tracker in fresh VM environments
+
+# Check if bd is already available
+if command -v bd &> /dev/null; then
+  echo "bd is already installed"
+  bd version
+else
+  echo "Installing bd (beads issue tracker)..."
+  npm install -g @beads/bd 2>/dev/null
+
+  # Fallback to Go if npm fails
+  if ! command -v bd &> /dev/null; then
+    if command -v go &> /dev/null; then
+      echo "npm install failed, trying Go..."
+      go install github.com/steveyegge/beads/cmd/bd@latest
+      export PATH="$PATH:$HOME/go/bin"
+    fi
+  fi
+fi
+
+# Initialize beads if not already initialized
+if [ -d .beads ]; then
+  echo "Beads database found"
+  bd prime 2>/dev/null || true
+else
+  echo "No .beads directory found - run 'bd init' to initialize"
+fi
+
+echo "bd is ready! Use 'bd ready' to see available work."
+exit 0

.claude/settings.json

@@ -5,5 +5,18 @@
     "superpowers@superpowers-marketplace": true,
     "typescript-lsp@claude-plugins-official": true,
     "agent-sdk-dev@claude-code-plugins": true
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
   }
 }

.claude/skills/workers-do.md

@@ -63,7 +63,7 @@ When using `dotdo/rpc`, use these conventional binding names:
 - `this.env.ESBUILD` - Build/transform
 - `this.env.MDX` - MDX compilation
 - `this.env.STRIPE` - Stripe operations
-- `this.env.WORKOS` - WorkOS/OAuth
+- `this.env.ORG` - Auth for AI and Humans (id.org.ai / WorkOS)
 - `this.env.CLOUDFLARE` - Cloudflare API
 
 ## Folder Structure

.dev.vars.example

@@ -0,0 +1,47 @@
+# .dev.vars.example - Local Development Secrets Template
+# Copy this file to .dev.vars and fill in your values
+# DO NOT COMMIT .dev.vars TO GIT
+
+# =============================================================================
+# CLOUDFLARE
+# =============================================================================
+# Get from: https://dash.cloudflare.com/profile/api-tokens
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_ACCOUNT_ID=
+
+# =============================================================================
+# STRIPE (payments.do)
+# =============================================================================
+# Get from: https://dashboard.stripe.com/apikeys
+STRIPE_SECRET_KEY=sk_test_
+STRIPE_PUBLISHABLE_KEY=pk_test_
+# Get from: https://dashboard.stripe.com/webhooks (create endpoint first)
+STRIPE_WEBHOOK_SECRET=whsec_
+
+# =============================================================================
+# WORKOS (org.ai)
+# =============================================================================
+# Get from: https://dashboard.workos.com/api-keys
+WORKOS_API_KEY=sk_test_
+WORKOS_CLIENT_ID=client_
+
+# =============================================================================
+# LLM PROVIDERS (llm.do)
+# =============================================================================
+# Get from: https://platform.openai.com/api-keys
+OPENAI_API_KEY=sk-
+
+# Get from: https://console.anthropic.com/settings/keys
+ANTHROPIC_API_KEY=sk-ant-
+
+# =============================================================================
+# AUTHENTICATION
+# =============================================================================
+# Generate with: openssl rand -hex 32
+JWT_SECRET=
+AUTH_SECRET=
+
+# =============================================================================
+# ENVIRONMENT
+# =============================================================================
+ENVIRONMENT=development

.gitmodules

@@ -46,3 +46,6 @@
 [submodule "rewrites/fsx"]
 	path = rewrites/fsx
 	url = https://github.com/dot-do/fsx.git
+[submodule "rewrites/bashx"]
+	path = rewrites/bashx
+	url = https://github.com/dot-do/bashx.git

ARCHITECTURE.md

@@ -103,7 +103,7 @@ this.env.JOSE        // JWT operations
 this.env.ESBUILD     // Build/transform
 this.env.MDX         // MDX compilation
 this.env.STRIPE      // Stripe operations
-this.env.WORKOS      // WorkOS/OAuth
+this.env.ORG         // Auth for AI and Humans (id.org.ai)
 this.env.CLOUDFLARE  // Cloudflare API
 ```
 
@@ -371,20 +371,185 @@ The CLI deploys to Workers for Platforms for multi-tenant hosting:
 
 ## primitives/ Submodule
 
-Git submodule from `github.com/dot-org-ai/primitives.org.ai`:
+Git submodule from `github.com/dot-org-ai/primitives.org.ai`. This is a **separate monorepo** containing AI primitives that are shared across projects.
 
+### Structure
+
+```
+primitives/
+├── packages/              # 19 npm packages (AI primitives)
+│   ├── ai-functions/      # Core AI function primitives (AI(), ai(), ai.do(), etc.)
+│   ├── ai-database/       # AI-powered database interface (DB(), db.list(), etc.)
+│   ├── ai-workflows/      # Event-driven workflows (Workflow(), on(), every())
+│   ├── ai-providers/      # LLM provider interfaces
+│   ├── ai-experiments/    # A/B testing & experiments
+│   ├── ai-evaluate/       # Eval framework
+│   ├── ai-tests/          # Test utilities
+│   ├── ai-props/          # AI component props
+│   ├── ai4/               # AI SDK v4 compatibility
+│   ├── autonomous-agents/ # Agent(), Role(), Team()
+│   ├── business-as-code/  # Business(), Vision(), Goals()
+│   ├── digital-workers/   # Role(), Team(), Goals()
+│   ├── digital-products/  # Product(), App(), API(), Site()
+│   ├── digital-tools/     # Tool interface & registry
+│   ├── digital-tasks/     # Task = Function + metadata, queues
+│   ├── human-in-the-loop/ # Human(), approve(), ask()
+│   ├── language-models/   # Model selection & routing
+│   ├── services-as-software/ # Service(), deliver(), subscribe()
+│   └── config/            # Shared ESLint/TypeScript config
+│
+├── types/                 # primitives.org.ai - comprehensive type definitions
+│   ├── core/              # Thing, Noun, Verb, Event, Action, Domain
+│   ├── org/               # Database, Function, Goal, Plan, Workflow
+│   ├── app/               # App, API, CLI, Dashboard, SDK
+│   ├── business/          # Business, Agent, Human
+│   ├── product/           # Product, Feature, Epic, Story, Bug
+│   ├── service/           # Service, SaaS
+│   ├── finance/           # Account, Transaction, Invoice
+│   ├── hr/                # Employee, Department, Performance
+│   ├── sales/             # Lead, Opportunity, Pipeline
+│   ├── ops/               # Inventory, Warehouse, Fulfillment
+│   ├── legal/             # Contract, Compliance, Audit
+│   ├── marketing/         # Campaign, Audience, Content
+│   ├── support/           # Ticket, SLA, KnowledgeBase
+│   ├── auth/              # User, Session, Role, Permission
+│   ├── collab/            # Message, Channel, Meeting
+│   ├── analytics/         # Metric, Dashboard, Report
+│   ├── equity/            # Investor, Share, CapTable
+│   ├── engineering/       # Sprint, Release, Deployment
+│   └── governance/        # Board, Advisor, Founder
+│
+├── content/               # MDX documentation content (26 items)
+│   ├── function/          # Function documentation
+│   ├── database/          # Database documentation
+│   ├── workflow/          # Workflow documentation
+│   └── ...                # Domain-specific content
+│
+├── examples/              # Real-world business examples (12 examples)
+│   ├── saas/              # B2B SaaS analytics (CloudMetrics)
+│   ├── api-business/      # Developer API platform (APIHub)
+│   ├── directory/         # Software tools directory (TechDirectory)
+│   ├── marketplace/       # Freelance marketplace (TalentHub)
+│   ├── startup-studio/    # Venture builder (VentureForge)
+│   └── vc-firm/           # Enterprise VC (Catalyst Ventures)
+│
+├── site/                  # Fumadocs documentation site (Next.js)
+│   ├── app/               # Next.js app router
+│   ├── content/           # Site-specific content
+│   └── lib/               # Site utilities
+│
+├── tools/                 # Git submodule (tools.org.ai)
+├── pnpm-workspace.yaml    # Workspace: packages/*, examples, site
+├── turbo.json             # Turborepo build config
+└── package.json           # Root package (private: true)
 ```
-primitives/packages/
-├── ai-database/          # Database interfaces
-├── ai-functions/         # Function interfaces
-├── ai-workflows/         # Workflow interfaces
-├── ai-providers/         # Provider interfaces
-├── digital-workers/      # Worker interfaces
-├── autonomous-agents/    # Agent interfaces
-└── ...                   # 19 total interface packages
+
+### Relationship with workers.do
+
+The primitives submodule integrates with workers.do in three ways:
+
+#### 1. Workspace Integration
+
+The root `pnpm-workspace.yaml` includes primitives packages:
+
+```yaml
+packages:
+  - 'primitives/packages/*'  # All 19 primitive packages
+```
+
+This means all primitives packages are part of the workers.do workspace and can be referenced with `workspace:*`:
+
+```json
+// primitives/packages/ai-database/package.json
+{
+  "dependencies": {
+    "ai-functions": "workspace:*",
+    "rpc.do": "workspace:*"
+  }
+}
+```
+
+#### 2. Type Re-exports
+
+The `packages/types/` directory in workers.do re-exports types from primitives:
+
+```typescript
+// packages/types/ai.ts
+export type {
+  AIFunctionDefinition,
+  AIGenerateOptions,
+  AIClient,
+  // ... 30+ types
+} from 'ai-functions'
+
+// packages/types/database.ts
+export type {
+  ThingFlat, ThingExpanded,
+  DBClient, DBClientExtended,
+  // ... 50+ types
+} from 'ai-database'
+```
+
+This provides:
+- Centralized type management in `@dotdo/types`
+- RPC-enhanced versions (e.g., `RpcAIClient` with pipelining)
+- Platform-specific extensions
+
+#### 3. Package Naming
+
+| primitives package | npm name | Purpose |
+|--------------------|----------|---------|
+| `ai-functions` | `ai-functions` | Core AI primitives |
+| `ai-database` | `ai-database` | Database interfaces |
+| `ai-workflows` | `ai-workflows` | Workflow definitions |
+| `types/` | `primitives.org.ai` | Comprehensive business types |
+
+### Using Primitives
+
+**In workers.do packages:**
+```typescript
+// Direct import from primitives package
+import { AI, ai } from 'ai-functions'
+import { DB, db } from 'ai-database'
+import { Workflow, on } from 'ai-workflows'
+
+// Or via @dotdo/types for platform integration
+import type { RpcAIClient, RpcPromise } from '@dotdo/types'
+```
+
+**In external projects (via npm):**
+```typescript
+// Install published packages
+import { AI } from 'ai-functions'
+import { DB } from 'ai-database'
+import type { Thing, Action } from 'primitives.org.ai'
+import type { Employee } from 'primitives.org.ai/hr'
+```
+
+### Why a Submodule?
+
+1. **Shared Core** - Primitives define platform-agnostic AI interfaces usable across projects
+2. **Independent Versioning** - primitives.org.ai has its own release cycle and changelogs
+3. **Documentation Site** - The `site/` folder powers https://primitives.org.ai
+4. **Business-as-Code** - The `types/` package provides comprehensive business domain modeling
+5. **Examples** - Real-world business templates demonstrate patterns
+
+### Key Dependencies
+
+Primitives packages reference workers.do packages via workspace:
+
+```
+ai-functions  ──► rpc.do (workspace:*)
+              ──► language-models (workspace:^)
+              ──► ai-providers (workspace:^)
+
+ai-database   ──► ai-functions (workspace:*)
+              ──► rpc.do (workspace:*)
 ```
 
-These TypeScript interfaces define contracts that `dotdo` and workers implement.
+This creates a bidirectional relationship where:
+- Primitives provide **interfaces and implementations**
+- workers.do provides **RPC transport** (`rpc.do`) and **platform bindings**
 
 ## Build System
 

CLAUDE.md

@@ -359,6 +359,22 @@ export const myworkflow = Workflow({
 - `wrangler` - Cloudflare CLI
 - `typescript` - Type checking
 
+## Secrets Management
+
+For local development, copy `.dev.vars.example` to `.dev.vars` and fill in your values:
+
+```bash
+cp .dev.vars.example .dev.vars
+```
+
+For production, use `wrangler secret put`:
+
+```bash
+wrangler secret put STRIPE_SECRET_KEY --env production
+```
+
+CI/CD uses GitHub Secrets with the `cloudflare/wrangler-action`. See `docs/SECRETS-MANAGEMENT.md` for full documentation.
+
 ## Beads Issue Tracking
 
 This project uses Beads for issue tracking:
@@ -380,6 +396,7 @@ bd sync --from-main   # Sync with main branch
 - `teams/README.md` - Teams documentation
 - `workflows/README.md` - Workflows documentation
 - `ARCHITECTURE.md` - Technical deep-dive
+- `docs/SECRETS-MANAGEMENT.md` - Secrets and environment variables
 
 ## The Hero