Dev Wiki
Dashboard
Changelog
Documentation
Toggle dark mode
Settings
Home
A - Z
Page Index
Archive
AWS Design
Async Embedding Pipeline
Auth
CDN Read Path
E-1 Cold Start Benchmarks
Implementation Phases
Lambda Library Mode
Operations
Phase 0 EFS Benchmarks
Phase Gates
Platform Overview
Semantic Search
AWS Tasks
E-2 CDN Read Path
E-2 CDN Read Path ClientSide
Launch Checklist
P1-9 MCP OAuth Discovery Routing
P1-9 MCP OAuth Routing
Phase 0
Phase 1
Phase 2
Phase 3
Phase 4
Prerequisites
Bugs
Semantic Search Background Sync
Design
Admin Panel Reenablement
Auth
Custom Domains
Dashboard Visibility Toggle
Data Model
E-3 Encryption Spike
E2E Testing
Frontend
Git HTTP Access
Implementation Workflow
Landing Page
MCP Server
Note Schema
Operations
P2-Username Summary
Per Wiki Database
Platform Overview
REST API
Research Wiki
Resolver
Semantic Search V2
Server Consolidation
VPS Architecture
Wiki Stats Plugin
did web Identity
Dev
2026-03-16 Beta User TLS Fix
Claude Code Memory Backup
Memory Bootstrap Guide
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 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
V7 Ops Hardening
VPS Deployment Progress
VS-1 ATProto Spike
VS-2 MCP OAuth Summary
DiagTestPage
E2ETestPage
Home
Meta
Wiki Usage Guide
Minsky
Agent IRC Architecture
Directed Message Routing
IRC MCP Bridge
Plans
CI CD Pipeline
Disk Usage Caps
Login Page UX
Monitoring Dashboard
Permissions Panel Implementation
Rate Limiting And Security Headers
Security Logging
Wiki To Dashboard Navigation
Security
OWASP 2025 Audit
Tasks
Disk Usage Cap
Emergent
MCP Wiki Routing
Semantic Search Architecture
Semantic Search Multi Tenant
VPS Phases
To-Do
UserBPage
irc-plugin-design-review
An Otter Wiki
Page Index
Toggle page headings
A
Archive/
AWS Design/
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
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
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
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
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 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
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
AWS 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
Launch Checklist
Branding
OAuth Providers (WorkOS)
Google
Apple
GitHub
WorkOS
DNS / Domain
Legal
Accounts / Billing
Pre-Launch Smoke Test
Security Review
Auth and access control
Input validation
Infrastructure
Data exposure
P1-9 MCP OAuth Discovery Routing
Problem
Solution
Verification
Files Changed
How It Works
Commit
P1-9 MCP OAuth Routing
Problem
Root Cause
Fix
Verification
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
DNS
Repositories
Local Dev Environment
Agent Container (packnplay)
B
Bugs/
Semantic Search Background Sync
Observed behavior
Expected behavior
Possible causes
Reproduction
Context
Environment
D
Design/
Admin Panel Reenablement
Background
Panel Status
Already working (no changes needed)
Re-enable now: Permissions panel (medium effort)
Phase 2: User Management (high effort)
Keep disabled: Mail Preferences
Implementation Order
Auth
MCP Auth
ACL Model
Authorization Flow
Public wiki access
Otterwiki Admin Panel — Section Disposition
Custom Domains
Scope
Database Schema
DNS Verification
TLS (Caddy)
Tenant Resolution
Authentication on Custom Domains
Solution: Redirect-based auth relay
Auth changes required
Relay token security
Logout
Management UI
Implementation Phases
Risks
Dashboard Visibility Toggle
Problem
Design
Mechanism
Read
Write
Staleness
Implementation
Files to change
UI placement
What NOT to do
Edge cases
Relationship to otterwiki admin panel
Data Model
Users
Wikis
ACLs
Storage layout (EFS)
Git Storage Mechanics
EFS-backed git repos
Fallback: S3 clone-on-demand
Semantic Search
Embedding pipeline (summary)
FAISS details
Cost estimate
URL Structure
Custom slugs (paid wikis)
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
E2E Testing
Current State
Blocked On
Plan After Consolidation
Step 1: Simplify conftest.py
Step 2: Add new fixtures
Step 3: Implement 11 additional tests
Auth flows (test_auth_flows.py, 3 tests)
Wiki lifecycle (test_wiki_lifecycle.py, 4 tests — already written)
Account management (test_account.py, 3 tests — already written)
MCP consent (test_account.py, 1 test — already written, marked skip)
Step 4: Verify existing test files
Step 5: Run full suite
Architecture Notes
Mock PDS
Test mode env vars
Docker vs mock
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
Git HTTP Access
Current State
What exists in otterwiki (upstream)
What exists in robot.wtf
The auth gap
Proposed Design
Reuse MCP bearer tokens for git auth
Why this works
Implementation
Read-only for v1
Access control
Use Cases
Relationship to Template Repo
Risks
Implementation Phases
Implementation Workflow
Principles
Pipeline per task
0. Setup (orchestrator, before any agents)
1. Plan (Sonnet Plan agent)
2. Implement (Sonnet agent, worktree isolation)
3. Chico review (Sonnet agent)
4. Zeppo review (Sonnet agent)
5. Fix (Sonnet agent, same worktree)
6. Re-review (Sonnet agents, mandatory if Fix made changes)
7. Verify (Sonnet agent)
8. Report
Task list structure
Agent prompts
What NOT to do
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
Initial pages
Customization
Custom template repos (premium)
Attachment Storage
MVP approach
Future optimization: external attachment storage
Git Remote Access
Hosted Git remote
Implementation
External Git sync (premium, future)
Otterwiki Fork Management
Merge strategy
Upstream relationship
Backup and Disaster Recovery
What we're protecting
Backup strategy
Design principle
Account Lifecycle
Data retention
Account deletion
GDPR
MCP Discoverability
Rate Limiting and Abuse Prevention
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
Per Wiki Database
Decision (2026-03-17)
Current State
What the resolver swaps today
Option A: Per-Request DB Swap (implementing now)
Storage layout
Mechanism
Schema initialization
Permission model
DID-as-email
Migration
Risks
Option B: Upstream Contextvars Refactor (future PR to redimp)
Core idea
What stays the same
Migration path
Phasing
Upstream pitch
Constraint
SQLite Multi-Tenant: Why It's Fine
Platform Overview
Overview
Context
Why this exists
Key users
Multi-Tenancy Model
Routing
Application Logic
Semantic Search
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
Resolver
What it does, in order
Why it's complex
The storage swap problem
The database swap problem
The multi-worker problem
The default database problem
Key data structures
Per-wiki SQLite DB (/srv/data/wikis/{slug}/wiki.db)
Auth result dict
Auth paths
Access restriction flow
Known limitations
Related pages
Semantic Search V2
Problem
Constraints
Design
Change 1: Section-aware chunking
Change 2: Return full chunk text in search results
Change 3: Configurable per-page deduplication
Change 4: Section-level read via MCP
Agent workflow after these changes
Implementation scope
Deployment notes
What this design does NOT address
Server Consolidation
Motivation
Current Architecture
Target Architecture
What Changes
New: app/platform_server.py
Removed
Modified
Unchanged
ManagementMiddleware Handling
Template Directory Structure
Database Connection Strategy
Rate Limiting
Session and Cookie
E2E Testing Impact
Implementation Sequence
Risks and Review Findings
Template migration (important)
App factory interface (resolved)
Error handlers (important)
Deployment strategy (important)
Caddyfile management (resolved)
Hardcoded service references (important)
Environment variables (important)
ProxyFix (minor)
Confirmed correct
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
Wiki Stats Plugin
Problem
Approach
Why a plugin
Why per-wiki DB (not robot.db)
Schema
Plugin hooks
otterwiki_after_page_save(pagepath, content, author)
otterwiki_after_page_delete(pagepath, author)
Setup hook
Resolver integration
Cron backstop
Open questions
Not implementing yet
did web Identity
Context
Components
1. Platform DID document (did:web:robot.wtf)
2. Per-wiki DID documents (did:web:{slug}.robot.wtf)
3. One-time login route
4. CLI bootstrap tool
5. Shared JWK utility
Files changed
Tests
Verification
Future: per-wiki keys
Dev/
2026-03-16 Beta User TLS Fix
Symptom
Root cause
Fixes deployed
1. Post-signup/login redirect (e6c5bba)
2. Private wiki auth redirect (13f4762)
3. Manual wiki creation for stranded users
Process lessons
Claude Code Memory Backup
Architecture
Repos and Tools
MCP Servers (DO NOT CONFUSE)
MCP Authentication
VPS Infrastructure
Process Rules
Agent Delegation Model
Implementation Workflow
Feedback Rules (Hard-Won Lessons)
Project Context
Per-Wiki SQLite DB (COMPLETED)
Cold Start / Performance
Shared Worktree Trial
User Preferences
Reference Pointers
Memory Bootstrap Guide
Philosophy
The Three Tiers
Tier 1: MEMORY.md (always loaded)
Tier 2: Operational rule files (loaded by scope)
Tier 3: External knowledge base (queried on demand)
Archive (cold storage)
Bootstrapping from Scratch
Step 0: Observe before writing
Step 1: Start with MEMORY.md
Step 2: Add operational rules as they emerge
Step 3: Connect an external knowledge base (if available)
Step 4: Maintain
Anti-patterns
What This System Doesn't Solve
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 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
Post-Gate: E2E Test Coverage
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
V7 Ops Hardening
Roles
backup (roles/backup/)
healthcheck (roles/healthcheck/)
logging (roles/logging/)
diskmon (roles/diskmon/)
Prerequisites
Semantic Search Switch
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
V3: ATProto OAuth Production Auth Service (2026-03-15)
V4: Management API + Wiki Lifecycle (2026-03-15)
V5: MCP OAuth AS (2026-03-15)
V6: Frontend + Landing Page (2026-03-15)
V7: Operational Hardening (2026-03-15)
Bugfixes (2026-03-16)
Semantic Search + Infrastructure (2026-03-17)
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
Platform Design
Architecture
Auth
Operations
Frontend
Semantic Search
Future / Deferred
Research Wiki (single-tenant system — still current)
Minsky (Multi-Agent Coordination)
Tasks
Dev Tracking (VPS)
Process
Archive
AWS Design (wikibot.io — Lambda/EFS/DynamoDB)
AWS Tasks (wikibot.io phases)
AWS-era Dev Summaries
Other
Meta
I
irc-plugin-design-review
Executive Summary
Findings
Critical
Important
Cosmetic
Architecture Compliance
CLIPlugin Pattern
Hook Interface
Channel Integration
Config Handling
Error Handling
split_message Algorithm
Nanobot Pattern Avoidance
Test Plan Completeness
Verification Against Codebase
Recommendations for Implementation Agent
Conclusion
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
Minsky/
Agent IRC Architecture
The problem
The idea
Org structure
Channel topology
Agent naming
Transport abstraction
MCP bridge
Design principle: conversational, not structured IPC
Tools
Message length
Configuration
Shared state: robot.wtf wiki
Agent lifecycle: long-running with shift-changes
Why the SDK, not the CLI
Polling and dispatch
Idle detection
Context monitoring
Context exhaustion and shift-changes
Git strategy
Worktree lifecycle
Branch and merge strategy
Cleanup
Architecture components
1. ergo IRCd
2. IRC MCP bridge (FastMCP)
3. Agent supervisor
Relationship to existing Agent_Workflow
MVP scope
Future: PM delegate via Claude.ai
Open questions
Resolved questions
Directed Message Routing
Problem
Design
Detection
Routing
Active nick registry
Deduplication
Channels to watch
Scope
In scope
Out of scope
Files to change
IRC MCP Bridge
Context
Implementation notes (post-build)
Why pydle over bottom
Scope
File Structure
Steps
1. Project scaffolding
2. Transport Protocol + Message
3. MemoryTransport + tests (TDD)
3. FastMCP server + tests (TDD)
5. IrcTransport (pydle)
6. Entry point
Not in scope
Verification
P
Plans/
CI CD Pipeline
Current State
Test Infrastructure Summary
Phase 1: Per-Repo CI on PR (do this session)
Template (robot.wtf)
Plugin repos (otterwiki-api, otterwiki-semantic-search)
otterwiki-mcp
otterwiki (fork)
Phase 2: Deploy Script (do this session)
Phase 3: Auto-Deploy (deferred)
Integration Testing
Task Checklist
Disk Usage Caps
Architecture
Components
1. stats table in wiki.db
2. New plugin: otterwiki-wikistats
3. Resolver changes
4. Cron backstop update
User Experience
Files to Modify
Test Plan
Open Questions
Login Page UX
1. JWT Detection and Auto-Redirect
2. Visual Redesign — Match Landing Page
Files to Modify
Test Plan
Sequencing
Monitoring Dashboard
Current State
Recommendation: Option C — /app/admin/stats page in the management UI
What to Build
What NOT to Build
Ansible Changes
Files to Touch
Out of Scope
Permissions Panel Implementation
Summary
Repos and Branches
Change 1: Otterwiki fork — Remove decorator and hide registration fields
1a. Remove @platform_mode_disabled from the route
1b. Show sidebar link in PLATFORM_MODE for permissions only
1c. Hide registration fields in PLATFORM_MODE
1d. Hide the per-user note about setting to "Admin"
1e. Handle form submission for PLATFORM_MODE
Change 2: robot.wtf resolver — Intersect permissions with per-wiki access levels
2a. New function: _apply_wiki_access_restrictions
2b. Call _apply_wiki_access_restrictions in TenantResolver.__call__
2c. Determine is_authenticated from auth path
The APPROVED Level Question
What Happens for Each User Type
ADMIN Permission Pass-Through
Test Specifications
Otterwiki fork tests
robot.wtf tests
Deployment and Independence
Open Questions
Rate Limiting And Security Headers
Phase 1: Security Headers (no module change)
Phase 2: Rate Limiting (requires xcaddy)
The problem
Rate limits by endpoint
MCP considerations
Implementation sequence
Rollback
Important notes
Security Logging
Events to Log
Auth server (app/auth_server.py)
Management middleware (app/management/routes.py)
Resolver (app/resolver.py)
Log Format
Implementation Approach
New module: app/audit.py
Call sites
IP extraction
No request ID correlation (yet)
Ansible Changes
Out of Scope (Deferred)
Wiki To Dashboard Navigation
Approach
Visual placement
Link details
Files to Modify
Test Plan
S
Security/
OWASP 2025 Audit
Executive Summary
Critical/High Findings (Fixed)
Remaining Findings (Prioritized)
High Priority (address soon)
Medium Priority
Low Priority
Methodology
T
Tasks/
Disk Usage Cap
Problem
Current limits
Proposed cap
Enforcement options
Option A: Per-write check
Option B: Tracked column
Option C: Periodic cron
Option D: Git hooks
Decision needed
Not urgent
Emergent
Emergent Tasks
E-1: Re-Instrument Cold Start INIT Phase
E-2: CDN Caching Layer Design
E-3: Client-Side Encryption / Zero-Knowledge Storage
E-4: Lambda Library Mode Implementation
E-5: Retain .pyc Files in Lambda Package
E-6: Lambda Warming Ping
MCP Wiki Routing
Problem
Root cause
Fix
Complication
Semantic Search Architecture
Current state
Issues to address
1. Multi-tenant indexing (blocking)
2. In-process embedding risks
3. Sync frequency
4. FAISS sidecar scalability
Not blocking launch
Semantic Search Multi Tenant
Problem
Immediate status
Options
Option A: Fix ChromaDB multi-tenant (more work)
Option B: Switch back to FAISS (different tradeoffs)
Option C: Hybrid — ChromaDB with explicit embedding function
Decision needed
Related
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 — PARTIAL
Dependency graph
What's not in scope
To-Do
Blocking
MCP wiki routing (bug) ✅ FIXED (2026-03-15)
Multi-tenant semantic search (bug) ✅ FIXED (2026-03-17)
Disk usage cap
Management UI usability
Landing page copy
Safety
Backup verification
SMTP alerts test
Rate limiting
Not blocking but important
FAISS index corruption risk ✅ RESOLVED (2026-03-15)
OAuth token refresh
Stale pages in wrong wiki ✅ N/A
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
