robot.wtf dev wiki
Changelog
Documentation
About An Otter Wiki
Toggle dark mode
Settings
Home
A - Z
Page Index
Design
Agent Workflow
Async Embedding Pipeline
Auth
CDN Read Path
Data Model
E-3 Encryption Spike
Frontend
Implementation Phases
Lambda Library Mode
Landing Page
MCP Server
Note Schema
Operations
P2-Username Summary
Phase Gates
Platform Overview
REST API
Research Wiki
Semantic Search
VPS Architecture
Dev
E-1 Cold Start Benchmarks
P1-8 E2E Test
P2-10 Summary
P2-1 Summary
P2-2 Summary
P2-3 Summary
P2-4 Summary
P2-5a Summary
P2-5b-7 Summary
P2-6 Summary
P2-8 Summary
P2-9 Summary
Phase 0 EFS Benchmarks
Phase 1 Deployment
Phase 1 Gate Results
Phase 1 Progress
Proxmox CPU Type
Underscore Filenames
V1-3 Deployment Summary
V1 SQLite Port Summary
V3 ATProto Auth Summary
V3 V5 Risk Research
V6-1 Landing Page Summary
VPS Deployment Progress
VS-1 ATProto Spike
VS-2 MCP OAuth Summary
DiagTestPage
E2ETestPage
Home
Meta
Wiki Usage Guide
Tasks
E-2 CDN Read Path
E-2 CDN Read Path ClientSide
Emergent
Launch Checklist
P1-9 MCP OAuth Discovery Routing
P1-9 MCP OAuth Routing
Phase 0
Phase 1
Phase 2
Phase 3
Phase 4
Prerequisites
VPS Phases
UserBPage
Page Index
Toggle page headings
D
Design/
Agent Workflow
Roles
Proceed Workflow (per task)
Parallelization Guide for Managers
Orchestrator Responsibilities
Question Relay Protocol
Manager Prompt Template
Invoking the Workflow
Async Embedding Pipeline
Design goals
Why not Bedrock
Architecture
Key properties
Search path
Trigger mechanism: why DynamoDB Streams over SQS
Reindex queue table
Cost model
Migration from current deployment
Open questions
Auth
User registration and login
Auth provider: WorkOS AuthKit
Wiki-level auth
MCP auth
ACL model
AAA Model (Authentication, Authorization, Accounting)
Authentication (who are you?)
Authorization (what can you do?)
Public wiki access
Per-wiki Otterwiki configuration
Otterwiki Admin Panel — Section Disposition
Accounting (resource tracking and tier enforcement)
CDN Read Path
Problem
Constraints
Fragment Model (common to all options below)
Open question for Claude Code
Option A: Thin Assembly Lambda (Recommended)
Architecture
Auth
Performance
Advantages
Disadvantages
Variant: S3 as direct CloudFront origin
Option B: Hybrid Static Content + Async Sidebar
Architecture
Auth
Performance
Advantages
Disadvantages
Open question for Claude Code
Option C: Pre-Rendered Full Pages (Static Site Generator)
Architecture
Auth
Performance
Scaling problem
Advantages
Disadvantages
Option D: Client-Side SPA Assembly
Architecture
Advantages
Disadvantages
Comparison
Recommendation
Cost Impact
Data Model
Users
Wikis
ACLs
Storage layout (EFS)
Git Storage Mechanics
EFS-backed git repos
Fallback: S3 clone-on-demand
Semantic Search (Premium)
Embedding pipeline
FAISS details
Cost estimate
URL Structure
Custom domains (premium)
Usernames
Username squatting
E-3 Encryption Spike
Problem
Storage Layers
Approaches Evaluated
1. EFS Encryption at Rest (Single KMS Key)
2. Per-Tenant SSE-KMS on S3 Fragments
3. Separate EFS Filesystems Per Tenant
4. Application-Level Encryption on EFS
5. Full Client-Side Encryption (Zero-Knowledge)
CDN Caching Interaction
KMS Cost Model at Scale
Recommendation
For Launch
Per-User KMS Becomes Viable When
Full Zero-Knowledge: Conditions for Revisiting
Precedents Referenced
Frontend
What the frontend actually is
URL Scheme
Namespace implications
Impact on existing design documents
Authentication
Cross-subdomain auth via parent-domain cookie
OAuth flow
JWT details
How the SPA knows if you're logged in
Framework
Recommendation: Svelte (not SvelteKit)
Build tooling
Bundle budget
Screens
Dashboard (/app/)
Create wiki (/app/new)
Wiki settings (/app/{slug})
Collaborators (/app/{slug}/collaborators)
MCP connection instructions (/app/{slug}/connect)
Account settings (/app/account)
Otterwiki Admin Panel Boundary
Error Handling
Static Hosting and Routing
Build and Deploy
Mobile
Upstream Contributions
Open Questions
Implementation Phases
Phase 0: EFS + Lambda + Auth proof of concept
FREE TIER (Phases 1–4)
Phase 1: Single-user serverless wiki
Phase 2: Multi-tenancy and auth
Phase 3: Frontend
Phase 4: Git remote access and launch prep
PREMIUM TIER (Phases 5+)
Phase 5: Stripe integration and premium gating
Phase 6: Semantic search
Phase 7: Deferred features (build when there's demand)
Frontend
Technology
Screens
MVP scope
API Surface
Management API (new)
Wiki API (existing, adapted)
MCP endpoint (existing, adapted)
Freemium Tiers
Deferred features (build when there's demand)
Pricing (undecided — two options)
Paid wiki perks
Lapse policy
Enforcement
Lambda Library Mode
Problem
Key Insight
Architecture: sys.modules Injection
The Replacement Module
Export Surface
Upstream Contributions
1. Lazy imports in views.py (highest value)
2. Lazy imports in wiki.py
3. Extract plugin entrypoint scan
4. Remove duplicate renderer instance
5. App factory pattern (longer-term)
Estimated Init Timeline
Current
With library mode + upstream lazy imports (PRs 1-4)
With library mode only (no upstream changes)
Breakdown of savings
Tracking Upstream Compatibility
Relationship to CDN Read Path
Open Questions
Landing Page
Design principles
Technical requirements
System font stack suggestion
Logo
Page structure
1. Header / nav
2. Hero
3. "What is this?" section
4. "How it works" section
5. FAQ section
6. Footer
Color and styling notes
What to deliver
Out of scope for initial build
MCP Server
Component 3: MCP Server
Goal
Implementation
Tools
Configuration
Tool return format and error handling
SSE endpoint
Note Schema
Note Schema
Field definitions
Cross-references: WikiLinks are the single source of truth
Page organization
Cross-referencing
Page size guidance
Complete example page
Master Index Convention
Purpose
Structure
Example
Size budget
Orphan detection
Session start protocol
Gardening sessions
Open Questions
Operations
Wiki Bootstrap Template
Initial pages
Customization
Custom template repos (premium)
Implementation
Attachment Storage
MVP approach
Future optimization: S3-backed attachment serving
Git Remote Access
Hosted Git remote
Implementation
External Git sync (premium, future)
Platform: AWS Lambda + EFS
Why AWS + EFS
Key properties
VPC networking
Known trade-offs
S3 fallback
Alternatives considered
Phase 0 validates this decision
Infrastructure as Code
Tool: Pulumi (Python)
What's managed by IaC
What's NOT managed by IaC
Repository structure
Otterwiki Fork Management
Merge strategy
Upstream relationship
Backup and Disaster Recovery
What we're protecting
Backup strategy
Recovery scenarios
Design principle
CI/CD
Pipeline
Environment strategy
Account Lifecycle
Data retention
Account deletion
GDPR
MCP Discoverability
Rate Limiting and Abuse Prevention
Open Questions
P2-Username Summary
Summary
Changes
Infrastructure (infra/components/dynamodb.py)
User Model (app/models/user.py)
Auth Middleware (app/auth/middleware.py)
Management API (app/management/routes.py)
CLI (app/cli/main.py)
Resolver (app/otterwiki/resolver.py)
Test Coverage
Branch
Phase Gates
How phase gates work
Phase 0 Gate: Proof of Concept
Exit criteria
Validation steps
Known risks to evaluate
Go/no-go decision
Phase 1 Gate: Single-User Serverless Wiki
Exit criteria
Validation steps
Known risks to evaluate
Go/no-go decision
Phase 2 Gate: Multi-Tenancy and Auth
Exit criteria
Validation steps
Known risks to evaluate
Go/no-go decision
Phase 3 Gate: Frontend
Exit criteria
Validation steps
Known risks to evaluate
Go/no-go decision
Phase 4 Gate: Launch Readiness
Exit criteria
Validation steps
Final checklist before launch
Go/no-go decision
Platform Overview
Overview
Context
Why this exists
Key users
Prior art
Architecture
Component inventory
REST API
Component 1: REST API Plugin
Goal
Implementation approach
Authentication
Commit authorship and message conventions
Endpoints
Pages
Search
Links (WikiLink graph)
Changelog
WikiLink parsing and link graph
Error responses
Example requests and responses
List pages: GET /api/v1/pages?prefix=Trends/
Read page: GET /api/v1/pages/Trends/Iran Attrition Strategy
Write page: PUT /api/v1/pages/Events/2026-03-09 Day 10
Full-text search: GET /api/v1/search?q=ballistic+missile+rationing
Semantic search: GET /api/v1/semantic-search?q=strategy+for+depleting+Gulf+air+defenses&n=3
Research Wiki
Overview
Context
What is Otterwiki?
Why this system?
Key users
Architecture
Deployment
Docker Compose
Implementation Sequence
Phase 1: Investigate plugin system (30 min)
Phase 2: REST API (core deliverable)
Phase 3: Chroma integration
Phase 4: MCP server
Phase 5: Docker compose and deployment
Success Criteria
Semantic Search
Component 2: Chroma Semantic Search Plugin
Goal
Implementation approach
ChromaDB configuration
Chunking strategy
Search result deduplication
API endpoints (added to the REST API)
Index maintenance
Fallback: periodic sync
VPS Architecture
Why this exists
Service model
Infrastructure
Server
Process model
Caddy
Why not Nginx
Authentication
Identity model
Username defaulting
ATProto OAuth (browser login)
Reference implementation
MCP OAuth (Claude.ai)
MCP protected resource metadata
Bearer tokens (Claude Code / API)
Cross-subdomain auth
Auth convergence
Migration off ATProto
Data Model
SQLite replaces DynamoDB
Tables
Storage layout
Compute
Otterwiki (WSGI)
MCP sidecar (FastMCP)
Platform API (Flask)
Auth service (Flask)
Semantic Search
Write path
Search path
Model loading strategy
Backup and Disaster Recovery
What we're protecting
Backup strategy
Recovery
Deployment
Application deployment
Initial setup
Monitoring
URL Structure
Namespace rules
What changes vs. what stays the same
Stays the same
Changes
What can be reused from existing implementation
Open Questions
Dev/
E-1 Cold Start Benchmarks
Summary
Detailed Init Breakdown (otterwiki @ 512MB)
Detailed Init Breakdown (otterwiki @ 1024MB)
Analysis
What's slow
What's NOT slow
Key insight
Comparison to Phase 0
Recommendations
Raw Log Excerpts
512MB
1024MB
P1-8 E2E Test
Status: Complete (with known gaps)
Test Results
Findings
Working
Known Gaps
Files
How to Run
Architecture Decisions
P2-10 Summary
Overview
Required Environment Variables
Test Scenarios
Design Decisions
Running
P2-1 Summary
Status: Complete
Acceptance Criteria
Files Changed
Design Decisions
Test Results
Pulumi Preview
Branch
P2-2 Summary
Deliverables
app/auth/jwt.py — Platform JWT (RS256)
app/auth/workos.py — WorkOS Integration
app/auth/middleware.py — Auth Middleware
Test Coverage (32 tests)
Design Decisions
Acceptance Criteria
P2-3 Summary
Deliverables
app/auth/permissions.py
app/auth/acl.py
app/auth/headers.py
app/models/wiki.py (modified)
tests/test_acl.py
Design Decisions
P2-4 Summary
What was built
Files
API Endpoints
Design decisions
Integration notes
Not included (future work)
P2-5a Summary
Status: Complete
Branch
Changes
New Resources (7)
Verification
Design Notes
P2-5b-7 Summary
What was built
1. app/otterwiki/resolver.py — TenantResolver WSGI middleware
2. app/otterwiki/lambda_init.py — Conditional multi-tenant wrapping
3. infra/__main__.py — Infrastructure changes
4. app/poc/mcp_server.py — Multi-tenant MCP
5. tests/test_resolver.py — 42 tests
Design decisions
P2-6 Summary
Status: Complete
Acceptance Criteria
Files Changed
Design Decisions
Test Results
P2-8 Summary
Status: Complete
Acceptance Criteria
Files Changed
Design Decisions
Test Results
Branch
P2-9 Summary
Status
Deliverables
Commands
Configuration
Architecture Decisions
Test Coverage (35 tests)
Phase 0 EFS Benchmarks
Summary
Environment
Results
Cold Start (5 invocations, forced via env var update)
Warm Read (25 invocations)
Warm Write (25 invocations)
Concurrent Reads (3 simultaneous, 5 rounds)
Concurrent Writes (5 simultaneous, 3 rounds)
Git Library Decision
Implications for Phase 1
Phase 1 Deployment
Summary
Deploy Details
E2E Test Results
Changes Made
Notes
Phase 1 Gate Results
Summary
Results
Performance
Issues Found
Corrected: /pages/{path}/links was not a bug
Fixed: P1-9 MCP OAuth Routing
Note: API auth header
Go/No-Go
Phase 1 Progress
Task Status
Architecture Decisions
apig-wsgi instead of Mangum (P1-1 / P1-3)
Zip package + Lambda layer instead of Docker (P1-3)
Single API Gateway (P1-7)
MCP on separate Lambda, no VPC (P0-7)
Plugin loading via explicit import (P1-4)
Endpoints
Also Completed (Track B / Prerequisites)
Proxmox CPU Type
Problem
Current workaround
Proper fix
Underscore Filenames
Status: Future work
Problem
Current state
Future feature
Scope
V1-3 Deployment Summary
Deliverables
Entry Points (app/)
Shared Configuration
Systemd Units (ansible/roles/deploy/files/)
Ansible Deploy Role
Requirements Added
Environment Variables
Testing
V1 SQLite Port Summary
Summary
Files Created (21 total)
Data Access Layer
Auth
WSGI Middleware
Tests
Key Schema Differences from wikibot-io
Architecture Notes
V3 ATProto Auth Summary
What Changed
Deliverables
Routes
Key Design Decisions
Schema Changes
Test Coverage
V3 V5 Risk Research
V3: ATProto OAuth Client — Risk Assessment
The cookbook demo is solid and directly usable
Scope question: RESOLVED
Remaining V3 risks
V3 verdict: LOW RISK
V5: MCP OAuth AS — Risk Assessment
What Claude.ai needs
authlib provides most of the machinery
Implementation sketch
The metadata endpoints are trivial
Remaining V5 risks
V5 verdict: MEDIUM RISK
Combined assessment
V6-1 Landing Page Summary
Status
Deliverables
Architecture
Page Structure
Design Decisions
Not Done
VPS Deployment Progress
Completed
V0: VM Infrastructure (2026-03-15)
V1: Otterwiki on Caddy (2026-03-15)
VS-1: ATProto OAuth Spike (2026-03-15)
V2: Migrate Dev Wiki (2026-03-15)
In Progress
VS-2: MCP OAuth for Claude.ai
V3: ATProto OAuth Production Auth Service
Not Started
Architecture Notes
VS-1 ATProto Spike
Status: COMPLETE — ready for manual deployment and testing
What was built
Key adaptations from cookbook demo
Files
Smoke test results
Dependencies
Deployment steps
What to watch for during manual testing
Findings for V3 production implementation
VS-2 MCP OAuth Summary
Problem
Solution
Changes
Configuration
Token Lifetimes
Schema
Branch
Test Results
DiagTestPage
E
E2ETestPage
H
Home
Active Design (robot.wtf — VPS + ATProto)
Platform
Research Wiki (single-tenant system — still current)
Process
Dev Tracking (VPS)
Archived Design (wikibot.io — AWS Serverless + Commercial)
Platform
Optimizations (Lambda-specific)
Semantic Search (AWS pipeline)
Content (still relevant for robot.wtf — tone and structure carry over)
Tasks (AWS phases)
Dev Tracking (AWS implementation)
Meta
M
Meta/
Wiki Usage Guide
What this is
Available tools
Reading
Navigating
Searching
Writing
History
Session start protocol (for phase managers)
Page conventions
Frontmatter
Page organization
Cross-references
Commit messages
Dev tracking conventions
Status pages (Dev/Phase N Status)
Summary pages (Dev/Phase N Summary)
Decision log (Dev/Decision Log)
Things to watch out for
Quick reference
T
Tasks/
E-2 CDN Read Path
Problem
Solution: Option A — Thin Assembly Lambda
Benchmarked Performance
Technical Feasibility (Validated)
Content fragment rendering
Sidebar fragment rendering
Shell template
Plugin injection points
Implementation Plan
Wave 1: Fragment Generation
Wave 2: Assembly Lambda + Infrastructure
Wave 3: Auth (Private Wikis)
Wave 4: Migration + Cutover
Open Questions
Cost
Estimated Effort
E-2 CDN Read Path ClientSide
Premise
Architecture
How It Works
1. Shell HTML (static, cached indefinitely)
2. Content fragment (per page, cached at CDN)
3. Sidebar fragment (per wiki, cached at CDN)
Content flash mitigation
Implementation Plan
Wave 1: Fragment Generation (same as Option A)
Wave 2: Infrastructure
Wave 3: Auth (Private Wikis)
Wave 4: Migration + Cutover
Comparison with Assembly Lambda Plan
When to prefer Assembly Lambda
When to prefer Client-Side Assembly
Recommendation
Emergent
Emergent Tasks
E-1: Re-Instrument Cold Start INIT Phase
E-2: CDN Caching Layer Design
Launch Checklist
Branding
OAuth Providers (WorkOS)
Google
Apple
GitHub
WorkOS
DNS / Domain
Legal
Accounts / Billing
Pre-Launch Smoke Test
P1-9 MCP OAuth Discovery Routing
Problem
Solution
Verification
Files Changed
How It Works
Commit
P1-9 MCP OAuth Routing
Problem
Root Cause
Deliverables
Acceptance Criteria
Target
Context
Notes
Phase 0
P0-1: Pulumi Scaffold
P0-2: EFS + Lambda Basic
P0-3: Git on EFS
P0-4: X-Ray Tracing
P0-5: Performance Benchmarks
P0-6: WorkOS AuthKit Setup
P0-7: FastMCP + WorkOS on Lambda
P0-8: Claude.ai MCP End-to-End
P0-9: Billing Alarm
Phase 1
P1-1: Mangum Adapter for Otterwiki
P1-2: FAISS Backend for Semantic Search
P1-3: Otterwiki on Lambda
P1-4: REST API on Lambda
P1-5: MCP Server on Lambda
P1-6: Semantic Search on Lambda
P1-7: Routing and TLS
P1-8: Phase 1 E2E Test
P1-9: Self Hosting
Phase 2
P2-1: DynamoDB Tables
P2-2: Auth Middleware
P2-3: ACL Enforcement Middleware
P2-4: Management API
P2-5: Per-Wiki Routing
P2-6: Wiki Bootstrap Template
P2-7: Otterwiki PROXY_HEADER Integration
P2-8: Admin Panel Hiding
P2-9: CLI Tool
P2-10: Phase 2 E2E Test
Phase 3
P3-1: SPA Scaffold
P3-2: Auth Flow
P3-3: Dashboard
P3-4: Wiki Settings
P3-5: MCP Connection Instructions
P3-6: Public Wiki Toggle
P3-7: Static Hosting
P3-8: Phase 3 E2E Test
Phase 4
P4-1: Git Smart HTTP
P4-2: Git Auth
P4-3: WAF Setup
P4-4: Monitoring and Alerting
P4-5: Backup Strategy
P4-6: Landing Page and Docs
P4-7: Phase 4 E2E Test
P4-8: Pre-Launch Security Review
Prerequisites
AWS
Pulumi
WorkOS (deferred — only needed for P0 Track B, P0-6 onward)
DNS
Repositories
Local Dev Environment
Agent Container (packnplay)
VPS Phases
What we're starting with
V0: VM Infrastructure — COMPLETE
VS: Auth Spikes
VS-1: ATProto OAuth Spike — COMPLETE
VS-2: MCP OAuth AS Stub — COMPLETE
Why spike before building
V1: Otterwiki on Caddy — COMPLETE
V2: Migrate dev.wikibot.io → dev.robot.wtf — PARTIAL
V3: ATProto OAuth (Browser Login) — COMPLETE
V4: Management API + Wiki Lifecycle — COMPLETE
V5: MCP OAuth AS (Claude.ai) — COMPLETE
V6: Frontend + Landing Page — COMPLETE
V7: Semantic Search + Operational Hardening — NOT STARTED
Dependency graph
What's not in scope
U
UserBPage
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9