Keystone OS

⚠️ Required Reading for All Agents

• CLAUDE.md — Agent-specific guidance, monoworkstream rules, environment variables
• AGENTS.md — Manifest, route map, PR lane rules, convergence agent fleet design
• SECURITY.md — Critical security fixes, vulnerability guidelines, best practices
• QUICKSTART.md — Full startup guide (dual-boot servers, autostart setup)

Table of Contents

1. What is Keystone OS?
2. Current Capabilities
3. Release Status: v1.6
4. Σ₀ (Sigma-Zero) Architecture
5. Getting Started
6. Development Workflow
7. Project Architecture
8. Core Concepts
9. Autonomous Systems
10. Testing and Validation
11. Documentation Map
12. Contributing
13. Privacy

What is Keystone OS?

Keystone OS is an operating system for reasoning work — not a traditional OS, but an app-level platform for managing complex, multi-step cognitive tasks.

Core Operating Model

Observe → Remember → Reason → Act → Verify → Converge

Every feature must strengthen one stage of this loop. Nothing else.

Who Should Use This

• Keystone OS members (subscribers) — you get the repo, the tools, and Keystone chat, the operator console for your own copy of the system. See Keystone Chat product definition.
• Solo developers working on complex projects that need evidence-backed decision-making
• AI researchers exploring convergence dynamics, autonomous routing, and persistent memory systems
• Organizations needing local-first agent workflows with operator control and audit trails
• Dreamers & symbol workers who want a journaling tool that connects dreams to convergence records

Current Capabilities

Release Status: v1.6

1.6 Dashboard Sprint completed (2026-06-16):

• ✅ Trader Dashboard MVP (real-time data, position management, win-rate metrics)
• ✅ Creator Dashboard MVP (markdown editor, Dream Journal publishing, templates)
• ✅ Σ₀ modes fully integrated (game, story, teach with evidence chains)
• ✅ Autonomous repair system deployed (health monitoring + auto-rollback)
• ✅stalled PRs merged to master (consolidated in commit 2b2b4950)

Remaining 1.6 work:

• Testing & verification (#619)
• Local Ollama coder agent rebuild with Σ₀ grounding (#628-#632)
• Monoworkstream enforcement in CI (#637-#640)

Σ₀ (Sigma-Zero) Architecture

Keystone OS is built on Σ₀ — a mathematical framework for verifying that systems don't collapse due to ungrounded feedback loops.

The Five Σ₀ Paradoxes (Identified 2026-06-14)

What This Means

Per Σ₀ framework: systems without feedback loops collapse. Without dust (observations) flowing back through doors, routing decisions freeze into degenerate fixed points.

Current status: All five paradoxes fixed with measurement loops + feedback gates. System verified stable under stress testing (1000+ iterations).

See docs/CONVERGANCE-SIGMA0-BRIEFING.md for the full technical spec.

Auto-Deploy Infrastructure (2026-06-24)

The stable server (port 4177) uses a non-destructive deployment model that preserves uncommitted runtime data while safely deploying new code.

How It Works

1. Non-Destructive Merge — Uses git merge --ff-only origin/master instead of git reset --hard, preserving any uncommitted changes to runtime files (JSONL logs, user data, etc.)
2. Smart Restart Logic — Only restarts the server if server-side code changed (.js, .py files in lib/, routes/, etc.); documentation and data-only changes are served fresh from disk without restart
3. Health Checks — After restart, validates /api/convergence/health endpoint with 25-second timeout; if unhealthy, automatically rolls back to the previous commit
4. Scheduled Runs — Runs everyminutes via Windows scheduled task KeystoneAutoDeployStable, hydrating API keys from User-scope environment before startup

Deployment Benefits

• ✅ Safe — Uncommitted data preserved; fast rollback on failure
• ✅ Efficient — No unnecessary restarts; static assets served immediately
• ✅ Observable — Full deploy log at C:\dev\auto-deploy-stable.log
• ✅ Automated — Requires no manual intervention; health checks prevent broken deployments

WCAG AA Accessibility Compliance (2026-06-24)

All surfaces now meet WCAG 2.1 Level AA standards. Keystone OS is committed to accessibility for all users, including those using keyboard navigation and assistive technologies.

Accessibility Features

• Keyboard Focus Indicators — 2px cyan outline (outline: 2px solid var(--accent); outline-offset: 2px;) on all interactive elements, visible on hover and focus-visible states
• Semantic HTML — Proper use of <section>, <h1>-<h3> hierarchy, and structural landmarks for screen reader navigation
• ARIA Labels — aria-labelledby, aria-hidden, aria-label attributes on all interactive components
• Prefers Reduced Motion — Respects @media (prefers-reduced-motion: reduce) to disable animations for users sensitive to motion
• Forced Colors Mode — Support for high-contrast modes with @media (forced-colors: active)
• High Contrast — Support for @media (prefers-contrast: more) with increased border widths and outline visibility

Compliance Details

Per WCAG 2.1 Success Criterion 2.4.7 (Focus Visible), all keyboard-operable elements must have a visible focus indicator with minimum 3:1 contrast ratio. Keystone's cyan accent provides 5.8:1 contrast on both light and dark backgrounds.

Latest Updates (2026-06-24)

• ✅ explore.html — WCAG AA upgrade with semantic sections, focus indicators, ARIA labels, and animation preferences
• ✅ index.html — Home page tiles now support keyboard focus with smooth visual feedback
• ✅ All pages — Forced-colors and high-contrast modes fully functional

Getting Started

Fastest Start (30 seconds)

Open in browser:

https://lantern-os.net

(Requires internet; no local setup needed)

Local Development (2 minutes)

Prerequisites: Node.js 18+, Python 3.10+

# 1. Install dependencies

npm install --prefix apps/lantern-garage

python -m pip install -r requirements.txt



# 2. Start the server

node apps/lantern-garage/server.js



# 3. Open in browser

# http://127.0.0.1:4177

Full Stack (All Services)

# PowerShell: Start dual-boot (stable + dev)

make quickstart

# Opens http://127.0.0.1:4177 automatically



# Or manual startup:

# Terminal 1: Web server

node apps/lantern-garage/server.js



# Terminal 2: MCP server (optional)

python src/mcp_server/server.py



# Terminal 3: Convergence loop (optional)

python src/convergence_io_engine.py loop

See QUICKSTART.md for autostart and full configuration.

Development Workflow

Monoworkstream Rule (Critical)

Each agent gets ONE open PR lane at a time.

# CORRECT: Wait for PR #1 to merge before opening PR #2

git checkout -b auto/issue-505  # First PR

# ... make changes, open PR #505 ...

# WAIT: PR #505 merges to master

git checkout -b auto/issue-506  # Second PR

# ... make changes, open PR #506 ...



# WRONG: Open PR #505, then immediately open PR #506

# (Creates merge conflicts, violates monoworkstream)

Why? Each agent lane is guaranteed to have one open change at a time. This prevents cascading merge conflicts and keeps CI feedback clear.

Enforcement:

• Git hooks warn if you violate the rule locally
• CI will block PR merge if another PR from the same agent is open
• See AGENTS.md for lane assignments

PR Lane Assignments

PR Workflow

1. Create branch from master

   git fetch origin master

   git checkout -b auto/issue-505 origin/master

1. Make one logical change (see CONTRIBUTING.md)
2. Test locally

   npm run test:api --prefix apps/lantern-garage

   python -m pytest tests/ -q

1. Commit with Convergence Record

   git commit -m "fix: Brief description (fixes #505)



   Detailed explanation if needed.

   

   Co-Authored-By: Claude Haiku 4.5 <[email protected]>"

1. Push and open PR

   git push -u origin auto/issue-505

   gh pr create --title "fix: Brief" --body "Fixes #505"

1. Wait for CI checks to pass, then PR auto-merges when all checks green

Auto-Merge System

PRs merge automatically when:

• ✅ All CI checks pass (lint, type, tests)
• ✅ No merge conflicts
• ✅ Branch up-to-date with master
• ✅ No other open PRs from same agent

If auto-merge fails:

• Resolve merge conflicts: git rebase origin/master
• Rerun tests: npm run test:api --prefix apps/lantern-garage
• Force-push: git push -f origin <branch>

See #637 for resolution procedures.

Project Architecture

File Organization

Core Services

Core Concepts

Autonomous Systems

Keystone OS includes several autonomous systems that run without operator intervention:

1. Autonomous Repair (Health Monitoring)

File: apps/lantern-garage/lib/server-health.js

Runs everyseconds and monitors:

• Memory usage (500MB threshold → graceful reload)
• Request backlog (>50 in-flight → alert)
• Hung requests (>30s timeout → log warning)
• Circuit breakers for failing services

Status endpoints:

# Current health

curl http://localhost:4177/status/health



# Full orchestrator status

curl http://localhost:4177/status/orchestrator

2. Autonomous Deployment (Auto-Deploy)

File: apps/lantern-garage/lib/auto-deploy.js

Runs hourly and:

1. Checks for new commits on origin/master
2. Runs pre-deploy tests
3. Verifies health post-deployment
4. Auto-rolls back if tests fail
5. Logs all decisions to data/deploy-history.jsonl

Configuration:

• LANTERN_AUTO_DEPLOY=true (default) — enable auto-deploy
• LANTERN_UPDATE_CHECK_MS=3600000 (default:hour)

3. Convergence Routing (Deterministic Pattern Cache)

File: apps/lantern-garage/lib/convergence-router.js

Caches routing decisions and patterns to avoid external API calls:

• 120+ Keystone intent routes (6 agents × 20+ intents each)
• >70% cache hit rate from day 1
• Deterministic: same input → same output (testable)
• Falls back to external providers only when no cache match

Benefit: Saves 60% tokens vs. direct API calls by caching learned patterns.

4. PR Watcher (Auto-Merge Resolver)

File: apps/lantern-garage/lib/pr-watcher.js

Polls GitHub everyminutes and:

• Checks if PR is ready to merge (all CI passing, no conflicts)
• Auto-merges with squash + branch deletion
• Records merge decisions to data/deploy-history.jsonl
• Never force-pushes or overrides branch protection

Enable with: PR_WATCHER_ENABLED=1 node apps/lantern-garage/server.js

Testing and Validation

Core Checks

# Node.js API tests

npm run test:api --prefix apps/lantern-garage



# Node.js UI tests (requires Playwright)

npm run test:ui --prefix apps/lantern-garage



# Python tests

python -m pytest tests/ -q --tb=short



# Type checking

make check-node  # Node.js syntax

make check-types # Python types (mypy)

Continuous Integration

CI runs the full pytest tests suite with no --ignore excludes (the anti-entropy and audit-chain suites pass; the Discord suites self-skip via importorskip when their optional deps are absent). The canonical chat/MCP tool surface is locked by a contract test (tests/test_mcp_tool_parity.py + tests/test_tool_capability_manifest.js): the only source of truth is apps/lantern-garage/lib/tool-runner.js, and the committed fallback manifest is regenerated from it. After adding or removing a tool, regenerate the manifest so the contract tests stay green:

echo '' | node scripts/tool-runner-bridge.js generate-manifest

Convergence Validation

# Verify convergence agent fleet (36 slots)

python scripts/Test-ConvergenceAgentFleet.py



# Verify MCP connector

powershell -File .\scripts\Test-LanternMcpConnector.ps1



# Update internal RAG

powershell -File .\scripts\Update-InternalHouseRag.ps1

Local Testing with Dev Preview

# Terminal 1: Stable server (master)

node apps/lantern-garage/server.js



# Terminal 2: Dev server (your branch, auto-reload)

npm run dev --prefix apps/lantern-garage



# Test UI at:

# http://127.0.0.1:4177 (stable)

# http://127.0.0.1:4178 (dev with your changes)

Documentation Map

For Agents (Start Here)

• AGENTS.md — Manifests, route map, delegate table, monoworkstream rules
• CLAUDE.md — Agent-specific guidance, environment variables, hooks
• QUICKSTART.md — Full startup guide (dual-boot, autostart, config)

For Operators

• docs/DREAM-JOURNAL-USER-GUIDE.md — How to use the Dream Journal
• docs/DREAM-JOURNAL-API-ENDPOINTS.md — Full API reference
• docs/EXPLORE-FEED.md — Explore page: PCSF-ranked single-pane content feed (as-built, API contract, limitations)
• AUTONOMOUS-REPAIR-GUIDE.md — Health monitoring, auto-repair, deployment control

For Product & Members

• docs/KEYSTONE-PRODUCT.md — Keystone chat product definition (operator console for members) + serving contract (fast default / deep opt-in)
• docs/SIGMA0-OURO-CODER.md — the Σ₀ coding agent (sibling surface): ship changes a developer merges with confidence

For Architects

• docs/CONVERGANCE-SIGMA0-BRIEFING.md — START HERE — Σ₀ framework, immutable North Star
• docs/ANTI-COLLAPSE-HARDENING.md — CSF-native defense-in-depth: how the loop resists collapse (proven vs heuristic), the hardening plan, red-team gaps (epic #764)
• docs/RESEARCH-CANON.md — Living references for Convergencecomponents
• docs/convergence-core-mapping.md — How code aligns with architecture
• docs/TESSERACT-CONVERGENCE-LOOP.md — 20-step convergence with 4D status cube
• docs/CSF-FORMAT-SPECIFICATION.md — Convergence-Fitted Searchable format spec
• docs/PCSF-PROVIDER-CAPACITY-SAFETY-FRAME.md — Capacity routing + fallback chains

For Traders & Analysis

• docs/trading-api-reference.md — 60+ Kalshi terminal endpoints
• docs/KALSHI-CIO-LIVE-TRADER.md — Autonomous market observer (paper trading)
• experiments/ — Analysis scripts, tightband accuracy logs, regime detection

Release & Deployment

• CHANGELOG.MD — Release history with linked issues
• docs/REPO-CONTRACT.md — Scope + cleanup contract, archive migration
• docs/CLOUDFLARE-TUNNEL-DEPLOYMENT.md — Public HTTPS deployment (no port forwarding)

Troubleshooting

• docs/TROUBLESHOOTING.md — Common issues and solutions
• GitHub Issues — Search by label: bug, p0, p1, convergence, agent-task

Contributing

Before You Start

1. Read CLAUDE.md (agent-specific rules)
2. Read AGENTS.md (PR lanes, monoworkstream)
3. Check CONTRIBUTING.md (full workflow)

Quick Workflow

1. Create branch (auto/issue-505 or claude/feature-name)

2. Make ONE logical change

3. Run tests locally

4. Commit with convergence record

5. Push and open PR

6. Wait for CI → auto-merge when green

Golden Rules

• ✅ Prefer small, reviewable changes (one fix, one feature per PR)
• ✅ Test locally before pushing (run npm/pytest)
• ✅ Update receipts/manifests if you change scope
• ✅ Link related issues in PR description
• ✅ Use convergence records in commit messages
• ❌ Don't break the monoworkstream (wait for prior PR to merge)
• ❌ Don't skip hooks or safety checks (unless explicitly authorized)
• ❌ Don't commit secrets (.env, credentials, API keys)

Privacy

Keystone OS is local-first by design.

• Dream journal data and local runtime receipts stay on your machine
• No telemetry or tracking built in
• External APIs (Claude, Gemini, etc.) only called when you explicitly configure them
• .env and .env.local are gitignored
• Private folders (data/private/, data/wallet/) never synced

Configure API keys:

# Create .env.local (not committed)

echo "ANTHROPIC_API_KEY=sk-ant-..." > .env.local

echo "OPENAI_API_KEY=sk-..." >> .env.local

Or set in the UI settings drawer at runtime.

License & Attribution

©Alex Place

Keystone OS is built with:

• Node.js — Web server + API
• Python — Convergence loop, MCP, memory
• Claude / Gemini / OpenAI — Multi-provider routing
• Ollama — Local model support
• CSF/CADD — Custom memory architecture

See CONTRIBUTING.md for contributor guidelines.

Quick Links

• GitHub: https://github.com/alex-place/lantern-os
• Live Demo: https://lantern-os.net
• MCP Server: https://mcp.lantern-os.net
• Issues: github.com/alex-place/lantern-os/issues
• Contact: open a GitHub issue