diff --git a/docs/README.md b/docs/README.md index 23257677..865dfb57 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,8 +2,6 @@ title: "Perstack: The Agent Runtime" --- -# Perstack: The Agent Runtime - Define AI agents as declarative **Experts** in TOML. Execute them with deterministic, event-derived tracking. Each Expert runs in its own isolated context — no shared state, no prompt bloat, full execution history. - [Getting Started →](./getting-started.md) diff --git a/docs/contributing/roadmap.md b/docs/contributing/roadmap.md index 767cd787..73810f51 100644 --- a/docs/contributing/roadmap.md +++ b/docs/contributing/roadmap.md @@ -2,8 +2,6 @@ title: "Roadmap" --- -# Roadmap - This roadmap outlines the direction of Perstack development. Priorities may shift based on community feedback and emerging requirements. > [!WARNING] diff --git a/docs/getting-started.md b/docs/getting-started.md index f0b987de..f0376a06 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,8 +2,6 @@ title: "Getting Started" --- -# Getting Started - This walkthrough takes you from zero to production integration. Each step addresses one or more of the [five structural problems](../README.md#why-perstack) in agentic app development. ## Prerequisites diff --git a/docs/guides/README.md b/docs/guides/README.md index b553c1e9..0db884ae 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -2,8 +2,6 @@ title: "Working with Perstack" --- -# Working with Perstack - What are you trying to do? | I want to... | Start here | diff --git a/docs/guides/adding-ai-to-your-app.md b/docs/guides/adding-ai-to-your-app.md index 93e6b491..16308dee 100644 --- a/docs/guides/adding-ai-to-your-app.md +++ b/docs/guides/adding-ai-to-your-app.md @@ -5,8 +5,6 @@ tags: ["integration", "container", "events"] order: 2 --- -# Adding AI to Your App - You have an existing application — maybe a web app, a CLI tool, or a backend service. You want to add AI capabilities, but you're not sure where to start. **The challenge**: Agent frameworks often want to own the entire application. They're designed for building agent-first apps, not for embedding AI into existing systems. diff --git a/docs/guides/extending-with-tools.md b/docs/guides/extending-with-tools.md index fa442070..8be23671 100644 --- a/docs/guides/extending-with-tools.md +++ b/docs/guides/extending-with-tools.md @@ -5,8 +5,6 @@ tags: ["tools", "mcp", "skills"] order: 3 --- -# Extending with Tools - Your agent can reason and generate text. But sometimes that's not enough — you need it to search the web, query a database, or call an API. **The problem**: Integrating external tools usually means writing code, managing connections, and handling errors. Each new tool is a custom integration. diff --git a/docs/guides/going-to-production.md b/docs/guides/going-to-production.md index f643d0dc..e4d7ddf2 100644 --- a/docs/guides/going-to-production.md +++ b/docs/guides/going-to-production.md @@ -5,8 +5,6 @@ tags: ["deployment", "container", "production"] order: 5 --- -# Going to Production - Your agent works in development. Now you want to deploy it for real users. **The concern**: AI agents have larger attack surfaces than typical applications. They make decisions, use tools, and interact with external systems. How do you deploy them safely? diff --git a/docs/guides/rapid-prototyping.md b/docs/guides/rapid-prototyping.md index 0b9188b0..2c8718dc 100644 --- a/docs/guides/rapid-prototyping.md +++ b/docs/guides/rapid-prototyping.md @@ -5,8 +5,6 @@ tags: ["beginner", "quick-start", "create-expert"] order: 1 --- -# Prototyping for Agent-First Apps - When you build an agent-powered app, the instinct is to start with the app — set up a project, install dependencies, write scaffolding. Then somewhere in the middle, you start figuring out what the agent should actually do. This is backwards. diff --git a/docs/guides/taming-prompt-sprawl.md b/docs/guides/taming-prompt-sprawl.md index 63c67345..c11feaa0 100644 --- a/docs/guides/taming-prompt-sprawl.md +++ b/docs/guides/taming-prompt-sprawl.md @@ -5,8 +5,6 @@ tags: ["prompts", "delegation", "architecture"] order: 4 --- -# Taming Prompt Sprawl - Your agent started simple. A focused prompt, clear behavior, reliable results. Then requirements grew. You added more capabilities, more edge cases, more instructions. Now your prompt is 50,000 tokens long — a small novel — and the agent gets confused between tasks. You're afraid to change anything because you might break something else. diff --git a/docs/making-experts/README.md b/docs/making-experts/README.md index 08a2fa05..895d40e9 100644 --- a/docs/making-experts/README.md +++ b/docs/making-experts/README.md @@ -2,8 +2,6 @@ title: "Making Experts" --- -# Making Experts - Experts are defined in `perstack.toml`. This section covers how to define, test, and publish Experts. ## The essentials diff --git a/docs/making-experts/base-skill.md b/docs/making-experts/base-skill.md index 52f8bb8a..8bc0fdf0 100644 --- a/docs/making-experts/base-skill.md +++ b/docs/making-experts/base-skill.md @@ -2,8 +2,6 @@ title: "Base Skill" --- -# Base Skill - Every Expert automatically has access to `@perstack/base` — a built-in skill that provides file operations, runtime control, and other essential tools. **No configuration needed. It's always available.** diff --git a/docs/making-experts/best-practices.md b/docs/making-experts/best-practices.md index c2f5ed53..a02c75e0 100644 --- a/docs/making-experts/best-practices.md +++ b/docs/making-experts/best-practices.md @@ -2,8 +2,6 @@ title: "Best Practices" --- -# Best Practices - These principles help you avoid common pitfalls in agent development: monoliths, complexity explosions, debugging nightmares, and fragile systems. Building a large agent head-on almost always fails. > [!NOTE] diff --git a/docs/making-experts/examples.md b/docs/making-experts/examples.md index 17a536b1..4180be15 100644 --- a/docs/making-experts/examples.md +++ b/docs/making-experts/examples.md @@ -2,8 +2,6 @@ title: "Examples" --- -# Examples - Patterns for defining Experts. Each example highlights a specific skill type or integration approach. - [GitHub Issue Bot](#github-issue-bot) diff --git a/docs/making-experts/publishing.md b/docs/making-experts/publishing.md index 5749d399..3ac9ebc1 100644 --- a/docs/making-experts/publishing.md +++ b/docs/making-experts/publishing.md @@ -2,8 +2,6 @@ title: "Publishing Experts" --- -# Publishing Experts - Share your Experts with the community by publishing them to the Perstack Registry. ## Before publishing diff --git a/docs/making-experts/skills.md b/docs/making-experts/skills.md index 4408f5b4..6d08cc5a 100644 --- a/docs/making-experts/skills.md +++ b/docs/making-experts/skills.md @@ -2,8 +2,6 @@ title: "Skills" --- -# Skills - Skills give Experts access to external tools via MCP (Model Context Protocol). | Type | Use case | diff --git a/docs/making-experts/testing.md b/docs/making-experts/testing.md index 8baadeef..92f0fa28 100644 --- a/docs/making-experts/testing.md +++ b/docs/making-experts/testing.md @@ -2,8 +2,6 @@ title: "Testing Experts" --- -# Testing Experts - Experts are probabilistic — the same query can produce different results. This guide covers strategies for testing effectively. ## Local testing diff --git a/docs/operating-experts/deployment.md b/docs/operating-experts/deployment.md index 35fd5363..c8e936d2 100644 --- a/docs/operating-experts/deployment.md +++ b/docs/operating-experts/deployment.md @@ -2,8 +2,6 @@ title: "Deployment" --- -# Deployment - Perstack runs on any Node.js environment. Choose your deployment target based on security requirements, cost, and operational preferences. ## Docker diff --git a/docs/operating-experts/isolation-by-design.md b/docs/operating-experts/isolation-by-design.md index caeeb9b1..e95c8748 100644 --- a/docs/operating-experts/isolation-by-design.md +++ b/docs/operating-experts/isolation-by-design.md @@ -2,8 +2,6 @@ title: "Isolation by Design" --- -# Isolation by Design - Perstack is designed to run inside isolated environments. The runtime itself doesn't enforce security boundaries — your infrastructure does. For the rationale behind this approach, see [Sandbox Integration](../understanding-perstack/sandbox-integration.md). diff --git a/docs/operating-experts/observing.md b/docs/operating-experts/observing.md index 63a29a7d..c104a440 100644 --- a/docs/operating-experts/observing.md +++ b/docs/operating-experts/observing.md @@ -2,8 +2,6 @@ title: "Observing" --- -# Observing - Every Perstack execution produces a complete audit trail. Use events and checkpoints to monitor, debug, and verify Expert behavior. ## Event stream diff --git a/docs/operating-experts/skill-management.md b/docs/operating-experts/skill-management.md index 2842ff27..2c65ab5b 100644 --- a/docs/operating-experts/skill-management.md +++ b/docs/operating-experts/skill-management.md @@ -2,8 +2,6 @@ title: "Skill Management" --- -# Skill Management - The Perstack runtime manages three types of skills through specialized Skill Managers. Each type has different initialization behavior and security implications. ## Skill Types diff --git a/docs/references/cli.md b/docs/references/cli.md index 6e2e6969..f9a43b5e 100644 --- a/docs/references/cli.md +++ b/docs/references/cli.md @@ -2,8 +2,6 @@ title: "CLI Reference" --- -# CLI Reference - ## Running Experts ### `perstack start` diff --git a/docs/references/events.md b/docs/references/events.md index 6b62b41d..46deeb2f 100644 --- a/docs/references/events.md +++ b/docs/references/events.md @@ -2,8 +2,6 @@ title: "Events Reference" --- -# Events Reference - Perstack emits events during Expert execution for observability and state management. This document explains the event system architecture and how to consume events. ## Event Types Overview diff --git a/docs/references/perstack-toml.md b/docs/references/perstack-toml.md index fed72def..665928d0 100644 --- a/docs/references/perstack-toml.md +++ b/docs/references/perstack-toml.md @@ -2,8 +2,6 @@ title: "perstack.toml Reference" --- -# perstack.toml Reference - - [Complete Example](#complete-example) - [Runtime Configuration](#runtime-configuration) - [Expert Definition](#expert-definition) diff --git a/docs/references/providers-and-models.md b/docs/references/providers-and-models.md index 1028df54..33b04d15 100644 --- a/docs/references/providers-and-models.md +++ b/docs/references/providers-and-models.md @@ -2,8 +2,6 @@ title: "Providers and Models" --- -# Providers and Models - Perstack supports multiple LLM providers. Configure via CLI options, environment variables, or `perstack.toml`. ## Default Model diff --git a/docs/understanding-perstack/boundary-model.md b/docs/understanding-perstack/boundary-model.md index a3aec935..fe764325 100644 --- a/docs/understanding-perstack/boundary-model.md +++ b/docs/understanding-perstack/boundary-model.md @@ -2,8 +2,6 @@ title: "The Boundary Model" --- -# The Boundary Model - [Isolation](./concept.md#isolation) is one of Perstack's three core goals. Experts are isolated from everything except their role — model access, context, tools, and dependencies are all mediated by the runtime. The **boundary model** extends this isolation to the application architecture level: **separate the application from the agent runtime**. diff --git a/docs/understanding-perstack/concept.md b/docs/understanding-perstack/concept.md index 013858cc..04f15cb0 100644 --- a/docs/understanding-perstack/concept.md +++ b/docs/understanding-perstack/concept.md @@ -2,8 +2,6 @@ title: "Concept" --- -# Concept - Perstack is built on a concept called **Expert Stack** — the architecture that enables agent-first development. > [!NOTE] diff --git a/docs/understanding-perstack/experts.md b/docs/understanding-perstack/experts.md index 76c13429..25281be2 100644 --- a/docs/understanding-perstack/experts.md +++ b/docs/understanding-perstack/experts.md @@ -2,8 +2,6 @@ title: "Experts" --- -# Experts - Experts are the core building block of Perstack — modular micro-agents designed for reuse. > [!NOTE] diff --git a/docs/understanding-perstack/registry.md b/docs/understanding-perstack/registry.md index cbdebe54..894b2b84 100644 --- a/docs/understanding-perstack/registry.md +++ b/docs/understanding-perstack/registry.md @@ -2,8 +2,6 @@ title: "Registry" --- -# Registry - The Perstack Registry is a community-driven ecosystem for sharing Experts — like npm, but for AI agents. ## Definition-only diff --git a/docs/understanding-perstack/runtime.md b/docs/understanding-perstack/runtime.md index 28e42a84..b7432743 100644 --- a/docs/understanding-perstack/runtime.md +++ b/docs/understanding-perstack/runtime.md @@ -2,8 +2,6 @@ title: "Runtime" --- -# Runtime - The Perstack runtime combines probabilistic LLM reasoning with deterministic state management — making agent execution predictable, reproducible, and auditable. ## Execution model diff --git a/docs/understanding-perstack/sandbox-integration.md b/docs/understanding-perstack/sandbox-integration.md index 62742abb..754f241b 100644 --- a/docs/understanding-perstack/sandbox-integration.md +++ b/docs/understanding-perstack/sandbox-integration.md @@ -2,8 +2,6 @@ title: "Sandbox Integration" --- -# Sandbox Integration - ## Why sandbox-first? AI agents differ fundamentally from traditional software. The same input can produce different outputs. Model updates can change behavior. Hallucinations can trigger destructive actions without any attacker involved. diff --git a/docs/using-experts/README.md b/docs/using-experts/README.md index ef712452..fa7b945b 100644 --- a/docs/using-experts/README.md +++ b/docs/using-experts/README.md @@ -2,8 +2,6 @@ title: "Using Experts" --- -# Using Experts - This section covers **running and integrating Experts** — CLI usage, state management, and error handling. ## In this section diff --git a/docs/using-experts/error-handling.md b/docs/using-experts/error-handling.md index 9753ae41..8eda8f1c 100644 --- a/docs/using-experts/error-handling.md +++ b/docs/using-experts/error-handling.md @@ -2,8 +2,6 @@ title: "Error Handling" --- -# Error Handling - Perstack is designed to recover from errors automatically when possible. Most errors are fed back to the LLM for self-correction rather than crashing the run. ## How errors are handled diff --git a/docs/using-experts/running-experts.md b/docs/using-experts/running-experts.md index b4ed690c..410a1bc6 100644 --- a/docs/using-experts/running-experts.md +++ b/docs/using-experts/running-experts.md @@ -2,8 +2,6 @@ title: "Running Experts" --- -# Running Experts - Perstack provides two commands for running Experts: `start` and `run`. ## `start` vs `run` diff --git a/docs/using-experts/state-management.md b/docs/using-experts/state-management.md index 1df62f29..95da5ecd 100644 --- a/docs/using-experts/state-management.md +++ b/docs/using-experts/state-management.md @@ -2,8 +2,6 @@ title: "State Management" --- -# State Management - Perstack automatically saves execution state, enabling continuation and replay. ## Execution hierarchy diff --git a/docs/using-experts/workspace.md b/docs/using-experts/workspace.md index f5f7f2e1..c88bacc3 100644 --- a/docs/using-experts/workspace.md +++ b/docs/using-experts/workspace.md @@ -2,8 +2,6 @@ title: "Workspace" --- -# Workspace - The workspace is the isolated directory where Experts execute. All file operations are confined to this directory. ## Default workspace