From fe668654a6d529c494a0dc0289472463dab9097b Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Wed, 11 Feb 2026 09:41:27 +0900 Subject: [PATCH] Fix: Remove duplicate h1 headings from docs Starlight renders the frontmatter title as the page heading, so having an additional h1 in the markdown body causes double headings. Removed the h1 line from all 35 doc files that had both frontmatter title and a body h1. Co-Authored-By: Claude Opus 4.6 --- docs/README.md | 2 -- docs/contributing/roadmap.md | 2 -- docs/getting-started.md | 2 -- docs/guides/README.md | 2 -- docs/guides/adding-ai-to-your-app.md | 2 -- docs/guides/extending-with-tools.md | 2 -- docs/guides/going-to-production.md | 2 -- docs/guides/rapid-prototyping.md | 2 -- docs/guides/taming-prompt-sprawl.md | 2 -- docs/making-experts/README.md | 2 -- docs/making-experts/base-skill.md | 2 -- docs/making-experts/best-practices.md | 2 -- docs/making-experts/examples.md | 2 -- docs/making-experts/publishing.md | 2 -- docs/making-experts/skills.md | 2 -- docs/making-experts/testing.md | 2 -- docs/operating-experts/deployment.md | 2 -- docs/operating-experts/isolation-by-design.md | 2 -- docs/operating-experts/observing.md | 2 -- docs/operating-experts/skill-management.md | 2 -- docs/references/cli.md | 2 -- docs/references/events.md | 2 -- docs/references/perstack-toml.md | 2 -- docs/references/providers-and-models.md | 2 -- docs/understanding-perstack/boundary-model.md | 2 -- docs/understanding-perstack/concept.md | 2 -- docs/understanding-perstack/experts.md | 2 -- docs/understanding-perstack/registry.md | 2 -- docs/understanding-perstack/runtime.md | 2 -- docs/understanding-perstack/sandbox-integration.md | 2 -- docs/using-experts/README.md | 2 -- docs/using-experts/error-handling.md | 2 -- docs/using-experts/running-experts.md | 2 -- docs/using-experts/state-management.md | 2 -- docs/using-experts/workspace.md | 2 -- 35 files changed, 70 deletions(-) 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