# Substrate

> Local-first, agent-collaborative work tracking exposed over MCP.

- [Substrate: Local-First Work Tracker for AI Coding Agents](https://docs.substrate.42.pe/index.md): Substrate stores boards, tasks, and workflow gates in your repo. Agents read and write over MCP stdio. No accounts, no cloud, no telemetry.
- [Installing Substrate: Clone, Build, Link, and Verify](https://docs.substrate.42.pe/getting-started/installation.md): Install the Substrate binary from a local clone, link it globally, and install the agent skill. Node.js 20+ required. No accounts or global config needed.
- [Quickstart: Initialize a Board and Connect an Agent](https://docs.substrate.42.pe/getting-started/quickstart.md): Initialize a .substrate/ directory, browse your board in the local inspector, connect an agent, and watch it move tasks through your workflow in minutes.
- [MCP Setup: Connect Your Agent to Substrate over stdio](https://docs.substrate.42.pe/getting-started/mcp-setup.md): Register the Substrate stdio MCP server with your agent runtime, verify the connection with whoami, and install the agent skill for Claude Code.
- [How Substrate Works: Local-First Architecture Overview](https://docs.substrate.42.pe/concepts/how-it-works.md): Learn how Substrate stores boards as code, keeps runtime state in SQLite, and exposes two surfaces: an MCP server for agents and a read-only web UI.
- [Boards, Groups, Tasks, and Comments: Substrate Data Model](https://docs.substrate.42.pe/concepts/boards-and-tasks.md): Understand how Substrate organizes work: boards, explicit group ordering, versioned tasks, threaded comments, and a full append-only event log.
- [Fields and field_schema: Types, Validation, Human-Only Gates](https://docs.substrate.42.pe/concepts/fields-and-schema.md): Define custom fields per board using field_schema, use gate fields as exit criteria, and mark human_only fields that only a human can set via the CLI.
- [Policies and Gates: Transition Guards and Conditions](https://docs.substrate.42.pe/concepts/policies-and-gates.md): Define transition guards that block group moves until conditions pass, and agent_responsibility policies that attach advisory messages without blocking.
- [Gates Walkthrough: Complete Agent Session with Real Payloads](https://docs.substrate.42.pe/concepts/gates-walkthrough.md): Follow a real eight-operation session showing task creation, blocked transitions, gate satisfaction, human-only approval, revocation, and event history.
- [Team Members: The Persona Registry and Board Bindings](https://docs.substrate.42.pe/concepts/team-members.md): Define personas in the member registry, bind them to board groups as orchestration hints, and understand what the team structure never enforces.
- [The Substrate Web UI: Read-Only Live Kanban Inspector](https://docs.substrate.42.pe/concepts/web-ui.md): Run substrate serve for a localhost kanban that auto-refreshes as agents work. Covers read-only design, port scanning from 7475, and single-owner lock.
- [The Agent Loop: Orienting and Advancing Work with Substrate](https://docs.substrate.42.pe/agents/agent-workflow.md): How an agent orients a fresh session, records work, and advances tasks using Substrate's 32 MCP tools without losing state between sessions.
- [Agent Conventions for Reliable Substrate Board Behavior](https://docs.substrate.42.pe/agents/conventions.md): The do-and-don't habits every agent must follow to keep a shared Substrate board trustworthy across multiple sessions and concurrent writers.
- [Worktrees and Fresh Clones: Avoiding the Empty-Board Problem](https://docs.substrate.42.pe/agents/worktrees-and-clones.md): Why task state does not travel with git, the startup warning Substrate emits, and three options for avoiding an empty board in a worktree or clone.
- [Authoring a Substrate: Turn Your Process into Data](https://docs.substrate.42.pe/authoring/overview.md): How to turn an existing development workflow into Substrate boards, custom fields, and gates that hold agents to the same process.
- [Mapping a Process to Substrate Groups, Fields, and Gates](https://docs.substrate.42.pe/authoring/map-a-process.md): How to translate workflow stages, per-item metadata, and exit criteria into Substrate groups, field_schema entries, and boolean gate fields.
- [Write Substrate Policies: Guards and Responsibilities](https://docs.substrate.42.pe/authoring/write-policies.md): The policy DSL for Substrate — transition guards that block moves and agent responsibilities that surface reminders at write time.
- [Validate Your Substrate Gates Before Relying on Them](https://docs.substrate.42.pe/authoring/validate-gates.md): How to prove a Substrate transition guard actually fires — using the static lint, a live probe via MCP, and dry-run check_transition.
- [Package and Publish Your Substrate Workflow as a Template](https://docs.substrate.42.pe/authoring/publish-a-template.md): How to package a Substrate workflow as a shareable template, add a substrate-template.json manifest, and apply someone else's template.
- [Back Up, Export, and Restore Your Substrate Project](https://docs.substrate.42.pe/operations/backup-and-restore.md): How to snapshot a substrate in place with backup, export it to any path, and safely restore it with import on another machine or checkout.
- [Substrate Diagnostics: Health Checks and Log Inspection](https://docs.substrate.42.pe/operations/diagnostics.md): How to use substrate diagnose and substrate logs to inspect installation health, surface errors from long-running processes, and file bug reports.
- [Upgrade Substrate: Binary, Agent Skill, and Board Files](https://docs.substrate.42.pe/operations/upgrading.md): How to pull and rebuild the Substrate binary, refresh the agent skill so it matches, and confirm your boards load cleanly after an upgrade.
- [Substrate CLI Reference — All Commands at a Glance](https://docs.substrate.42.pe/cli/overview.md): Every command available in the Substrate v0.7.0 CLI — setup, running MCP and serve, human approvals, data management, and diagnostics at a glance.
- [substrate init — Initialize a New Substrate Project](https://docs.substrate.42.pe/cli/init.md): substrate init creates a .substrate/ directory in the current project, optionally seeded from the web-delivery starter or a local template.
- [substrate add — Apply a Template to an Existing Substrate](https://docs.substrate.42.pe/cli/add.md): substrate add imports a shared workflow template into an existing .substrate/ — dry run by default, transactional when applied with --yes.
- [substrate install-skill — Refresh the Agent Skill](https://docs.substrate.42.pe/cli/install-skill.md): substrate install-skill copies the packaged agent skill into ~/.claude/skills/substrate, version-stamped to match the current binary.
- [substrate mcp — Start the MCP Server for Agent Runtimes](https://docs.substrate.42.pe/cli/mcp.md): substrate mcp starts the stdio MCP server that agent runtimes spawn. Exposes all 32 Substrate tools over stdin/stdout with no port or network.
- [substrate serve — Start the Local Read-Only Web Inspector](https://docs.substrate.42.pe/cli/serve.md): substrate serve starts a localhost read-only web inspector on port 7475. The board auto-refreshes as agents write tasks and advance work.
- [substrate pending-approval — List Human Gate Tasks](https://docs.substrate.42.pe/cli/pending-approval.md): substrate pending-approval lists every task blocked on a human_only gate across all boards, with the exact command to approve each one.
- [substrate approve — Set a Human-Only Approval Field](https://docs.substrate.42.pe/cli/approve.md): substrate approve sets a human_only field on a task — the only write channel agents cannot use, stamped with your OS username in the event log.
- [substrate unapprove — Revoke a Mistaken Human Approval](https://docs.substrate.42.pe/cli/unapprove.md): substrate unapprove revokes a mistaken human approval by deleting the field key so both exists and eq-true guards re-block the task.
- [substrate backup — Snapshot the Current Substrate](https://docs.substrate.42.pe/cli/backup.md): substrate backup writes a timestamped .tar.gz archive of your substrate into .substrate/backups/ and prints the path. No retention or pruning in v0.7.0.
- [substrate export / import — Move a Substrate Archive](https://docs.substrate.42.pe/cli/export-import.md): substrate export writes a .tar.gz of the full substrate; substrate import restores it, with safeguards against overwriting a live project.
- [substrate validate — Lint Boards, Members, and Policies](https://docs.substrate.42.pe/cli/validate.md): substrate validate lints your boards, members, and policies without starting a server. Exits non-zero on errors; advisory warnings exit 0. CI-safe.
- [substrate diagnose — Environment and Health Report](https://docs.substrate.42.pe/cli/diagnose.md): substrate diagnose prints a full health report of your Substrate installation and exits non-zero if any probe fails. Include in all bug reports.
- [substrate logs — Read Lines from the Persistent Log File](https://docs.substrate.42.pe/cli/logs.md): substrate logs prints recent lines from .substrate/logs/substrate.log, written only by long-lived mcp and serve processes. Supports -n and --errors.
- [substrate explain — Generate an HTML Workflow Map](https://docs.substrate.42.pe/cli/explain.md): substrate explain writes a self-contained HTML file with board diagrams, field schema, and policies. No database required — works in a fresh clone.
- [MCP Tool Reference: All 32 Substrate Tools Explained](https://docs.substrate.42.pe/mcp/overview.md): Substrate exposes 32 MCP tools over stdio in three families — read, task/comment writes, and substrate-edit — with shared conventions for every call.
- [Substrate MCP Read Tools: Orient and Inspect Boards](https://docs.substrate.42.pe/mcp/read-tools.md): The 13 Substrate MCP read tools — whoami, get_board_substrate, list_tasks, check_transition, and more. All return raw data, never an envelope.
- [Substrate MCP Task and Comment Write Tools (7 Total)](https://docs.substrate.42.pe/mcp/task-and-comment-tools.md): The 7 Substrate MCP write tools for tasks and comments — create, update, archive, add comments, and edit them. All return an envelope.
- [Substrate-Edit MCP Tools: Boards, Groups, Policies](https://docs.substrate.42.pe/mcp/substrate-edit-tools.md): The 12 MCP tools for editing boards, groups, policies, and project settings. Changes take effect immediately — no migration, no restart.
- [MCP Write Envelopes and Error Codes — Substrate Docs](https://docs.substrate.42.pe/mcp/envelopes-and-errors.md): The success envelope every Substrate write returns, plus all 8 error codes and how to handle version_mismatch and transition_blocked.

## Optional

- [GitHub](https://github.com/42pe/substrate)