README.md

Minsky documentation

Implementation and operational reference for Minsky — the exocortex / principal substrate the top-level README describes. Strategic memos, position papers, and incident records live in Notion (Minsky workspace); per-task history lives in the Minsky task DB and GitHub PRs. This directory is the code-adjacent layer: setup, configuration, migration, ops, testing patterns, architecture references.

For the brand foundation (locked myth, cultural code, vocabulary), see the minsky-brand skill. For operational tokens (typography, color, motion, contrast), see brand-system.md. For the documentation taxonomy that places each artifact in its slot (ADR / RFC / position paper / engineering guide / architecture reference / etc.), see CLAUDE.md §Documentation Taxonomy.

Getting Started

• Main README — project overview, installation, and basic usage
• CONTRIBUTING.md — TypeScript dev setup, testing, and the project record stack
• CLAUDE.md — instructions for AI agents working in this codebase
• Bun Optimization Setup — disk space optimization (60-90% savings)

Core Concepts

• Domain Concepts — Core Minsky concepts (Repository, Session, Workspace)
• Theory of Operation — How cybernetic theory maps to code modules (VSM, environmental pre-delegation)
• Architecture Overview — System architecture, command registry, persistence, DI

Feature Documentation

Session Management

• Persistence Migration Guide — Postgres schema migrations and restoring session data from a JSON backup
• Persistence Troubleshooting Guide — Diagnosing and resolving Postgres persistence issues
• Postgres Persistence Configuration — Pool sizing, retry policy, and graceful shutdown for the Postgres backend

Task Management

• Multi-Backend User Guide — Complete guide to the multi-backend task system
• Multi-Backend Quick Reference — Command reference and cheat sheet
• Tasks Dependencies — Task dependency model and CLI

MCP Integration

• Shared Command Registry — How CLI and MCP interfaces share the same command definitions
• MCP Server — How to start and inspect the MCP server locally
• MCP Migration Guide — Notes on MCP method/parameter migrations
• MCP Schema Composition Guide — Schema patterns for MCP tools
• MCP Signaling Spike Findings — Findings from the mt#1315 signaling spike

Git Workflows

• PR Workflow — Pull request preparation and approval workflows

Configuration

• Configuration Guide — Configuration overview
• Configuration Validation Guide — Validation patterns
• Repository Configuration — Repository backend configuration
• GitHub App Bot Setup — Configure GitHub App bot identity (minsky-ai[bot]) for automated PR reviews
• GitHub Issues Backend Guide — GitHub Issues task backend setup

Architecture & Development

Development Workflow

• Development Workflow — Pre-commit hooks, testing, and quality gates

Testing

For all testing decisions (where to put tests, how to mock, what to test) see the testing-guide skill (.claude/skills/testing-guide/SKILL.md). Mocking utilities live in src/utils/test-utils/. Architecture-level docs:

• Test Architecture Documentation — Architecture of the test infrastructure

Architecture (subdirectory)

• docs/architecture/ — ADRs and architecture deep-dives.

Migrations

• Memory Migration — Memory subsystem migration notes
• Domain Schema Architecture — Domain schema design

Conventions

• ASCII-Only Code Symbols — see CLAUDE.md (project-wide ASCII rule)
• Variable Naming Guide — Variable naming conventions
• as unknown Prevention — Guidelines against unsafe as unknown casts
• Stale Reference Checklist — Checklist for catching stale references during edits
• Logging — Logging configuration and patterns

Operations

• Deploy Minsky to Railway — Railway deploy procedure for hosted Minsky MCP

Reference

Command Categories

• Session Management: minsky session start|list|get|delete|dir|update|pr|approve
• Task Management: minsky tasks list|get|create|status|spec|migrate
• Git Operations: minsky git clone|branch|summary|prepare-pr
• Rules Management: minsky rules list|get|create|update|search|delete
• Configuration: minsky config list|show
• Project Setup: minsky init
• MCP Server: minsky mcp start

Backend Types

• Task Backends: minsky, github-issues
• Repository Backends: local, remote, github
• Session Storage Backends: postgres only — SQLite was removed (mt#2339; see ADR-018)

Key File Locations

• Main Configuration: .minsky/config.yaml
• Task Specs: stored in the Minsky task DB (browse via mcp__minsky__tasks_*)
• Rules Directory: .cursor/rules/ (Cursor format) or .minsky/rules/ (generic)
• Session Storage: ~/.local/state/minsky/sessions/
• AI Agent Memory: ~/.claude/projects/.../memory/ (per-machine, not committed)

Contributing to Documentation

When updating documentation:

• Keep examples runnable against the current codebase. If a doc claims a tool/utility exists, verify it does.
• Update cross-references when moving content; broken links are surfaced by the stale-reference checklist.
• Prefer linking from this index over duplicating content in multiple places.
• Per-machine, ephemeral, or task-specific documentation does not belong here — that lives in tasks (DB), PRs (GitHub), or memories.

For per-cluster cleanup history, see PRs filed under mt#1319 / mt#1360.