From 4b75492ea63f71d6558c4e908c0d403d97a3ce3d Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Wed, 11 Feb 2026 18:48:46 +0900 Subject: [PATCH] Docs: Fix broken internal links and add sidebar ordering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix walkthrough.md relative links (./ → ../) for cross-directory refs - Replace links to non-existent README.md files with actual first pages - Remove publishing.md link from testing.md (file removed) - Add sidebar order frontmatter to all doc pages for Starlight navigation - Remove obsolete pages: getting-started.md (replaced by getting-started/walkthrough.md), publishing.md, registry.md, and section README.md files - Remove Key features section from concept.md (duplicated navigation) - Fix guide frontmatter: order → sidebar.order for Starlight compatibility Co-Authored-By: Claude Opus 4.6 --- docs/README.md | 12 +- .../walkthrough.md} | 59 +++--- docs/guides/README.md | 19 -- docs/guides/adding-ai-to-your-app.md | 3 +- docs/guides/extending-with-tools.md | 3 +- docs/guides/going-to-production.md | 3 +- docs/guides/rapid-prototyping.md | 5 +- docs/guides/taming-prompt-sprawl.md | 3 +- docs/making-experts/README.md | 102 --------- 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 | 193 ------------------ docs/making-experts/skills.md | 2 + docs/making-experts/testing.md | 3 +- 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 | 18 +- docs/understanding-perstack/experts.md | 4 +- docs/understanding-perstack/registry.md | 103 ---------- docs/understanding-perstack/runtime.md | 2 + .../sandbox-integration.md | 2 + docs/using-experts/README.md | 20 -- 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 + 34 files changed, 85 insertions(+), 503 deletions(-) rename docs/{getting-started.md => getting-started/walkthrough.md} (80%) delete mode 100644 docs/guides/README.md delete mode 100644 docs/making-experts/README.md delete mode 100644 docs/making-experts/publishing.md delete mode 100644 docs/understanding-perstack/registry.md delete mode 100644 docs/using-experts/README.md diff --git a/docs/README.md b/docs/README.md index 865dfb57..8d3452b7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,7 @@ title: "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) +- [Getting Started →](./getting-started/walkthrough.md) - [Browse Registry →](https://platform.perstack.ai/) ## What Perstack Solves @@ -66,25 +66,23 @@ const checkpoint = await run({ ### Learn -- [Getting Started](./getting-started.md) — create your first Expert and walk through the core workflow +- [Getting Started](./getting-started/walkthrough.md) — create your first Expert and walk through the core workflow - **Understanding Perstack** - [Concept](./understanding-perstack/concept.md) — the architecture behind the runtime - [Experts](./understanding-perstack/experts.md) — what Experts are and how they work - [Runtime](./understanding-perstack/runtime.md) — execution model and event system - [Sandbox Integration](./understanding-perstack/sandbox-integration.md) — infrastructure-level isolation - [Boundary Model](./understanding-perstack/boundary-model.md) — trust boundaries between components - - [Registry](./understanding-perstack/registry.md) — publishing and discovering Experts ### Build -- **[Making Experts](./making-experts/README.md)** — complete guide to Expert definitions +- **[Making Experts](./making-experts/best-practices.md)** — complete guide to Expert definitions - [Examples](./making-experts/examples.md) — real-world use cases - [Best Practices](./making-experts/best-practices.md) — design guidelines for effective Experts - [Skills](./making-experts/skills.md) — adding MCP tools to your Experts - [Base Skill](./making-experts/base-skill.md) — built-in tools provided by the runtime - [Testing](./making-experts/testing.md) — strategies for testing Experts - - [Publishing](./making-experts/publishing.md) — share Experts via the Registry -- **[Guides](./guides/README.md)** — task-oriented walkthroughs +- **[Guides](./guides/rapid-prototyping.md)** — task-oriented walkthroughs - [Rapid Prototyping](./guides/rapid-prototyping.md) — validate ideas without writing code - [Taming Prompt Sprawl](./guides/taming-prompt-sprawl.md) — fix bloated prompts with modular Experts - [Extending with Tools](./guides/extending-with-tools.md) — give your Experts real-world capabilities via MCP @@ -93,7 +91,7 @@ const checkpoint = await run({ ### Run -- **[Using Experts](./using-experts/README.md)** — run and integrate Experts +- **[Using Experts](./using-experts/running-experts.md)** — run and integrate Experts - [Running Experts](./using-experts/running-experts.md) — CLI commands and runtime API - [Workspace](./using-experts/workspace.md) — file system layout and conventions - [State Management](./using-experts/state-management.md) — checkpoints, pausing, resuming diff --git a/docs/getting-started.md b/docs/getting-started/walkthrough.md similarity index 80% rename from docs/getting-started.md rename to docs/getting-started/walkthrough.md index f0376a06..915fe446 100644 --- a/docs/getting-started.md +++ b/docs/getting-started/walkthrough.md @@ -1,22 +1,21 @@ --- -title: "Getting Started" +title: "Walkthrough" +sidebar: + order: 1 --- -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. +This walkthrough takes you from zero to production integration. ## Prerequisites - [Node.js 22+](https://nodejs.org/) -- An LLM provider API key (see [Providers and Models](./references/providers-and-models.md)) +- An LLM provider API key (see [Providers and Models](../references/providers-and-models.md)) ```bash export ANTHROPIC_API_KEY=sk-ant-... ``` -## Step 1: Create an Expert - -> [!TIP] -> **Addresses**: Tight coupling, The developer owns everything +## Create an Expert Generate an Expert definition interactively: @@ -51,10 +50,7 @@ instruction = "Provide split routines and HIIT plans tailored to user history." You can also write `perstack.toml` manually — `create-expert` is a convenient starting point, not a requirement. -## Step 2: Run Your Expert - -> [!TIP] -> **Addresses**: Broken feedback loops +## Run Your Expert ### Interactive mode @@ -76,15 +72,12 @@ npx perstack run fitness-assistant "Start today's session" | Aspect | What Perstack Does | | --- | --- | -| **Isolation** | Each Expert has its own context window. No prompt bloat. | +| **State** | Both Experts share the workspace (`./fitness-log.md`), not conversation history. | | **Collaboration** | `fitness-assistant` delegates to `pro-trainer` autonomously. | | **Observability** | Every step is visible as a structured event. | -| **State** | Both Experts share the workspace (`./fitness-log.md`), not conversation history. | - -## Step 3: Analyze Execution +| **Isolation** | Each Expert has its own context window. No prompt bloat. | -> [!TIP] -> **Addresses**: No sustained behavior (observability) +## Analyze Execution After running an Expert, inspect what happened: @@ -106,12 +99,9 @@ Key options for deeper inspection: This matters because debugging agents across model changes, requirement changes, and prompt iterations requires visibility into every decision the agent made. `perstack log` gives you that visibility without adding instrumentation code. -See [CLI Reference](./references/cli.md#perstack-log) for the full list of options. +See [CLI Reference](../references/cli.md#perstack-log) for the full list of options. -## Step 4: Lock for Reproducibility - -> [!TIP] -> **Addresses**: No sustained behavior (reproducibility) +## Lock for Reproducibility ```bash npx perstack install @@ -128,10 +118,7 @@ This creates a `perstack.lock` file that caches tool schemas for all MCP skills. The lockfile is optional. If not present, skills are initialized at runtime as usual. -## Step 5: Integrate into Your Application - -> [!TIP] -> **Addresses**: No real isolation +## Integrate into Your Application The CLI is for prototyping. For production, integrate Experts into your application via the Execution API, sandbox providers, or runtime embedding. @@ -227,7 +214,7 @@ Perstack's isolation model maps naturally to container and serverless platforms: - Kubernetes - Cloudflare Workers -Each Expert runs in its own sandboxed environment. See [Going to Production](./guides/going-to-production.md) for the Docker setup pattern. Detailed guides for other providers are coming soon. +Each Expert runs in its own sandboxed environment. See [Going to Production](../guides/going-to-production.md) for the Docker setup pattern. Detailed guides for other providers are coming soon. ### Runtime Embedding (`@perstack/runtime`) @@ -269,16 +256,16 @@ The CLI is for prototyping. The runtime API is for production. Both use the same ## What's Next **Build more:** -- [Making Experts](./making-experts/README.md) — full `perstack.toml` guide -- [Skills](./making-experts/skills.md) — MCP integration patterns -- [Taming Prompt Sprawl](./guides/taming-prompt-sprawl.md) — break monolithic prompts into collaborating Experts +- [Making Experts](../making-experts/best-practices.md) — full `perstack.toml` guide +- [Skills](../making-experts/skills.md) — MCP integration patterns +- [Taming Prompt Sprawl](../guides/taming-prompt-sprawl.md) — break monolithic prompts into collaborating Experts **Understand the architecture:** -- [Concept](./understanding-perstack/concept.md) — why isolation and observability matter -- [Experts](./understanding-perstack/experts.md) — best practices for Expert design -- [Sandbox Integration](./understanding-perstack/sandbox-integration.md) — infrastructure-level isolation +- [Concept](../understanding-perstack/concept.md) — why isolation and observability matter +- [Experts](../understanding-perstack/experts.md) — best practices for Expert design +- [Sandbox Integration](../understanding-perstack/sandbox-integration.md) — infrastructure-level isolation **Reference:** -- [CLI Reference](./references/cli.md) — all commands and options -- [perstack.toml Reference](./references/perstack-toml.md) — complete configuration spec -- [Events](./references/events.md) — runtime event schema +- [CLI Reference](../references/cli.md) — all commands and options +- [perstack.toml Reference](../references/perstack-toml.md) — complete configuration spec +- [Events](../references/events.md) — runtime event schema diff --git a/docs/guides/README.md b/docs/guides/README.md deleted file mode 100644 index 0db884ae..00000000 --- a/docs/guides/README.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Working with Perstack" ---- - -What are you trying to do? - -| I want to... | Start here | -| ---------------------------------------------------- | --------------------------------------------------- | -| Validate an AI agent idea without writing code | [Rapid Prototyping](./rapid-prototyping.md) | -| Fix my agent's bloated prompts and confused behavior | [Taming Prompt Sprawl](./taming-prompt-sprawl.md) | -| Add AI capabilities to my existing application | [Adding AI to Your App](./adding-ai-to-your-app.md) | -| Give my agent access to web search, databases, APIs | [Extending with Tools](./extending-with-tools.md) | -| Deploy my agent safely and reliably | [Going to Production](./going-to-production.md) | - -## New to Perstack? - -If you haven't tried Perstack yet, start with [Getting Started](../getting-started.md) — you'll have an Expert running in 5 minutes. - -These guides assume you've completed the basics and want to do something specific. diff --git a/docs/guides/adding-ai-to-your-app.md b/docs/guides/adding-ai-to-your-app.md index 16308dee..9ef8f7e8 100644 --- a/docs/guides/adding-ai-to-your-app.md +++ b/docs/guides/adding-ai-to-your-app.md @@ -2,7 +2,8 @@ title: "Adding AI to Your App" description: "Embed AI capabilities into your existing application. Your app stays in control while Perstack handles execution." tags: ["integration", "container", "events"] -order: 2 +sidebar: + order: 2 --- 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. diff --git a/docs/guides/extending-with-tools.md b/docs/guides/extending-with-tools.md index 8be23671..a8ea85f9 100644 --- a/docs/guides/extending-with-tools.md +++ b/docs/guides/extending-with-tools.md @@ -2,7 +2,8 @@ title: "Extending with Tools" description: "Give your agent access to web search, databases, and APIs using MCP skills. Declare tools in TOML, the runtime handles the rest." tags: ["tools", "mcp", "skills"] -order: 3 +sidebar: + order: 3 --- 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. diff --git a/docs/guides/going-to-production.md b/docs/guides/going-to-production.md index e4d7ddf2..97936d73 100644 --- a/docs/guides/going-to-production.md +++ b/docs/guides/going-to-production.md @@ -2,7 +2,8 @@ title: "Going to Production" description: "Deploy your agent safely and reliably. Sandbox execution in containers with full observability." tags: ["deployment", "container", "production"] -order: 5 +sidebar: + order: 5 --- Your agent works in development. Now you want to deploy it for real users. diff --git a/docs/guides/rapid-prototyping.md b/docs/guides/rapid-prototyping.md index 2c8718dc..fa4f1c96 100644 --- a/docs/guides/rapid-prototyping.md +++ b/docs/guides/rapid-prototyping.md @@ -2,7 +2,8 @@ title: "Prototyping for Agent-First Apps" description: "Start with the agent, not the app. Use create-expert to go from idea to working agent in seconds, then expand to tools and applications." tags: ["beginner", "quick-start", "create-expert"] -order: 1 +sidebar: + order: 1 --- 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. @@ -129,5 +130,5 @@ At some point, your prototype will need more. The same `perstack.toml` scales ## What's next -- [Making Experts](../making-experts/README.md) — Learn the full Expert definition format +- [Making Experts](../making-experts/best-practices.md) — Learn the full Expert definition format - [Best Practices](../making-experts/best-practices.md) — Design patterns for effective Experts diff --git a/docs/guides/taming-prompt-sprawl.md b/docs/guides/taming-prompt-sprawl.md index c11feaa0..e66c1702 100644 --- a/docs/guides/taming-prompt-sprawl.md +++ b/docs/guides/taming-prompt-sprawl.md @@ -2,7 +2,8 @@ title: "Taming Prompt Sprawl" description: "Fix bloated prompts and confused agents. Split responsibilities across focused Experts using delegation." tags: ["prompts", "delegation", "architecture"] -order: 4 +sidebar: + order: 4 --- Your agent started simple. A focused prompt, clear behavior, reliable results. diff --git a/docs/making-experts/README.md b/docs/making-experts/README.md deleted file mode 100644 index 895d40e9..00000000 --- a/docs/making-experts/README.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "Making Experts" ---- - -Experts are defined in `perstack.toml`. This section covers how to define, test, and publish Experts. - -## The essentials - -Every Expert needs just two things: - -```toml -[experts."code-reviewer"] -description = "Reviews code for issues and improvements" -instruction = """ -You are a code reviewer. Analyze code for: -- Type safety and error handling -- Security vulnerabilities -- Performance issues -Provide actionable feedback with examples. -""" -``` - -- **description** — what it does (visible to delegators) -- **instruction** — how it thinks (private domain knowledge) - -That's a complete, functional Expert. Skills and delegates are optional. - -## Why TOML: Enabling domain experts - -This is the core of agent-first development: **the people with domain knowledge should define the Experts**. - -In most teams, a few "prompt-capable" engineers become bottlenecks. They're the only ones who can write and maintain agent prompts, while domain experts — who actually have the knowledge — can't contribute directly. - -Perstack breaks this bottleneck. Expert definitions are plain text that anyone can read and write: - -1. **No technical formatting knowledge required** — no indentation rules, no trailing commas, no escaping -2. **Comments for intent** — domain experts explain their reasoning inline - -That's why we use TOML. The format serves the goal: domain experts own their Experts. - -## Multiple Experts in one file - -Define related Experts together: - -```toml -[experts."researcher"] -description = "Gathers information from various sources" -instruction = "..." - -[experts."writer"] -description = "Creates polished content from research" -instruction = "..." -delegates = ["researcher"] - -[experts."editor"] -description = "Reviews and refines written content" -instruction = "..." -``` - -This pattern works well for: -- **Pipelines** — Experts that work in sequence -- **Teams** — Experts with complementary roles -- **Variants** — Similar Experts with different specializations - -## Designing delegation - -When one Expert delegates to another, only `description` is shared. The delegator never sees the delegate's `instruction`. - -``` -┌─────────────────────────────────────────────────────┐ -│ writer │ -│ ├── sees: researcher.description │ -│ └── decides: "I need research on X" │ -│ │ -│ researcher │ -│ ├── receives: "research on X" │ -│ └── uses: own instruction (private) │ -└─────────────────────────────────────────────────────┘ -``` - -This means: -- Write `description` for the delegator — what can I ask for? What will I get back? -- Write `instruction` for the Expert itself — domain knowledge, procedures, constraints - -## In this section - -- [Examples](./examples.md) — real-world use cases -- [Best Practices](./best-practices.md) — design guidelines for effective Experts -- [Skills](./skills.md) — adding MCP tools to your Experts -- [Base Skill](./base-skill.md) — built-in tools provided by the runtime -- [Testing](./testing.md) — strategies for testing Experts -- [Publishing](./publishing.md) — share Experts via the Registry -- [perstack.toml Reference](../references/perstack-toml.md) — complete field reference - -## Prerequisites - -Before making Experts, understand the core concepts: - -- [Experts](../understanding-perstack/experts.md) — what Experts are and how they work -- [Getting Started](../getting-started.md) — create your first Expert and walk through the core workflow - -For running and integrating Experts, see [Using Experts](../using-experts/README.md). diff --git a/docs/making-experts/base-skill.md b/docs/making-experts/base-skill.md index 8bc0fdf0..781004fa 100644 --- a/docs/making-experts/base-skill.md +++ b/docs/making-experts/base-skill.md @@ -1,5 +1,7 @@ --- title: "Base Skill" +sidebar: + order: 3 --- Every Expert automatically has access to `@perstack/base` — a built-in skill that provides file operations, runtime control, and other essential tools. diff --git a/docs/making-experts/best-practices.md b/docs/making-experts/best-practices.md index a02c75e0..dbe35499 100644 --- a/docs/making-experts/best-practices.md +++ b/docs/making-experts/best-practices.md @@ -1,5 +1,7 @@ --- title: "Best Practices" +sidebar: + order: 1 --- 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. diff --git a/docs/making-experts/examples.md b/docs/making-experts/examples.md index 4180be15..cf8acfb5 100644 --- a/docs/making-experts/examples.md +++ b/docs/making-experts/examples.md @@ -1,5 +1,7 @@ --- title: "Examples" +sidebar: + order: 4 --- Patterns for defining Experts. Each example highlights a specific skill type or integration approach. diff --git a/docs/making-experts/publishing.md b/docs/making-experts/publishing.md deleted file mode 100644 index 3ac9ebc1..00000000 --- a/docs/making-experts/publishing.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: "Publishing Experts" ---- - -Share your Experts with the community by publishing them to the Perstack Registry. - -## Before publishing - -Ensure your Expert is ready: - -1. **Clear description** — tells other Experts (and humans) what this Expert does and how to use it -2. **Tested locally** — run it with various queries to verify behavior -3. **Minimal skills** — only include skills the Expert actually needs -4. **Version-ready** — follow [SemVer](https://semver.org) for versioning - -## Skill requirements - -Published Experts have restrictions on MCP skills for security: - -### Allowed commands - -Only `npx` and `uvx` are permitted as skill commands: - -```toml -[experts."my-expert".skills."@some/mcp-tool"] -type = "mcpStdioSkill" -command = "npx" # ✓ allowed -packageName = "@some/mcp-tool" - -[experts."my-expert".skills."python-tool"] -type = "mcpStdioSkill" -command = "uvx" # ✓ allowed -packageName = "python-tool" -``` - -Arbitrary commands (e.g., `node`, `python`, `./script.sh`) are **not allowed** for published Experts. - -### Why this restriction? - -The registry only accepts MCP skills from trusted package registries (npm, PyPI via uvx). This provides: - -- **Supply chain security** — packages are subject to registry policies -- **Reproducibility** — same package version produces same behavior -- **Auditability** — package sources are publicly inspectable - -### Using custom commands locally - -For local development, `perstack.toml` accepts any command: - -```toml -[experts."local-expert".skills."custom"] -type = "mcpStdioSkill" -command = "node" # works locally -args = ["./my-mcp-server.js"] -``` - -These Experts work with `perstack start` and `perstack run`, but cannot be published. - -## Publishing via CLI - -Use the `perstack publish` command to publish Experts from your `perstack.toml`: - -```bash -# Publish a specific Expert -npx perstack publish my-expert - -# Interactive selection (if multiple Experts defined) -npx perstack publish - -# Validate without publishing -npx perstack publish my-expert --dry-run -``` - -### Authentication - -Add your API key to `.env`: - -```bash -PERSTACK_API_KEY=your-api-key -``` - -Obtain API keys from your organization dashboard. - -## Versioning - -The Registry uses [Semantic Versioning](https://semver.org): - -| Change type | Version bump | Example | -| ---------------------------------- | ------------ | ------------- | -| Breaking changes | MAJOR | 1.0.0 → 2.0.0 | -| New features (backward compatible) | MINOR | 1.0.0 → 1.1.0 | -| Bug fixes | PATCH | 1.0.0 → 1.0.1 | - -### Write-once immutability - -Once a version is published, it **cannot be changed**. This guarantees: -- Dependent Experts always get the same definition -- No supply chain attacks via version tampering -- Reproducible builds - -To fix a bug, publish a new version. - -## Tags - -Tags are mutable pointers to versions: - -```bash -npx perstack run @your-org/your-expert@latest "query" -npx perstack run @your-org/your-expert@stable "query" -``` - -- `latest` — automatically updated on each publish -- Custom tags (e.g., `stable`, `beta`) — manually managed - -### Managing tags via CLI - -Use the `perstack tag` command to add or update tags: - -```bash -# Interactive wizard (select Expert and version) -npx perstack tag - -# Add tags to a specific version -npx perstack tag my-expert@1.0.0 stable - -# Multiple tags -npx perstack tag my-expert@1.0.0 stable production -``` - -## Scoped names - -Expert names are scoped by organization: - -``` -@{organization}/{expert-name} -``` - -- Organization must be registered on the Platform -- Expert names: lowercase letters, numbers, hyphens - -## Status management - -Expert versions have three status levels: - -| Status | Description | -| ------------ | -------------------------- | -| `available` | Normal operation (default) | -| `deprecated` | Warns users, still works | -| `disabled` | Prevents new dependencies | - -### Managing status via CLI - -Use the `perstack status` command to change version status: - -```bash -# Interactive wizard (select Expert and version) -npx perstack status - -# Deprecate a version -npx perstack status my-expert@1.0.0 deprecated - -# Disable a version -npx perstack status my-expert@1.0.0 disabled -``` - -### Status transitions - -- `available` → `deprecated` ✓ -- `available` → `disabled` ✓ -- `deprecated` → `disabled` ✓ -- `deprecated` → `available` ✗ (cannot revert) -- `disabled` → any ✗ (terminal state) - -Versions with active dependents cannot be deleted. Use deprecation to signal migration. - -## Unpublishing - -Remove a version from the registry: - -```bash -# Interactive wizard (select Expert and version) -npx perstack unpublish - -# Direct unpublish with confirmation -npx perstack unpublish my-expert@1.0.0 --force -``` - -The `--force` flag is required when using CLI mode. - -## What's next - -- [Registry](../understanding-perstack/registry.md) — how the Registry works -- [Registry API](https://perstack.ai/api/v1/spec) — programmatic access diff --git a/docs/making-experts/skills.md b/docs/making-experts/skills.md index 6d08cc5a..62cf4e4b 100644 --- a/docs/making-experts/skills.md +++ b/docs/making-experts/skills.md @@ -1,5 +1,7 @@ --- title: "Skills" +sidebar: + order: 2 --- Skills give Experts access to external tools via MCP (Model Context Protocol). diff --git a/docs/making-experts/testing.md b/docs/making-experts/testing.md index 92f0fa28..e92e5f6b 100644 --- a/docs/making-experts/testing.md +++ b/docs/making-experts/testing.md @@ -1,5 +1,7 @@ --- title: "Testing Experts" +sidebar: + order: 5 --- Experts are probabilistic — the same query can produce different results. This guide covers strategies for testing effectively. @@ -88,5 +90,4 @@ Before publishing: ## What's next -- [Publishing](./publishing.md) — share your tested Expert - [Best Practices](./best-practices.md) — design guidelines diff --git a/docs/operating-experts/deployment.md b/docs/operating-experts/deployment.md index c8e936d2..93d3299b 100644 --- a/docs/operating-experts/deployment.md +++ b/docs/operating-experts/deployment.md @@ -1,5 +1,7 @@ --- title: "Deployment" +sidebar: + order: 1 --- Perstack runs on any Node.js environment. Choose your deployment target based on security requirements, cost, and operational preferences. diff --git a/docs/operating-experts/isolation-by-design.md b/docs/operating-experts/isolation-by-design.md index e95c8748..89342eeb 100644 --- a/docs/operating-experts/isolation-by-design.md +++ b/docs/operating-experts/isolation-by-design.md @@ -1,5 +1,7 @@ --- title: "Isolation by Design" +sidebar: + order: 4 --- Perstack is designed to run inside isolated environments. The runtime itself doesn't enforce security boundaries — your infrastructure does. diff --git a/docs/operating-experts/observing.md b/docs/operating-experts/observing.md index c104a440..04a31f5e 100644 --- a/docs/operating-experts/observing.md +++ b/docs/operating-experts/observing.md @@ -1,5 +1,7 @@ --- title: "Observing" +sidebar: + order: 2 --- Every Perstack execution produces a complete audit trail. Use events and checkpoints to monitor, debug, and verify Expert behavior. diff --git a/docs/operating-experts/skill-management.md b/docs/operating-experts/skill-management.md index 2c65ab5b..b81670c1 100644 --- a/docs/operating-experts/skill-management.md +++ b/docs/operating-experts/skill-management.md @@ -1,5 +1,7 @@ --- title: "Skill Management" +sidebar: + order: 3 --- The Perstack runtime manages three types of skills through specialized Skill Managers. Each type has different initialization behavior and security implications. diff --git a/docs/references/cli.md b/docs/references/cli.md index f9a43b5e..08eab908 100644 --- a/docs/references/cli.md +++ b/docs/references/cli.md @@ -1,5 +1,7 @@ --- title: "CLI Reference" +sidebar: + order: 2 --- ## Running Experts diff --git a/docs/references/events.md b/docs/references/events.md index 46deeb2f..99211ce6 100644 --- a/docs/references/events.md +++ b/docs/references/events.md @@ -1,5 +1,7 @@ --- title: "Events Reference" +sidebar: + order: 1 --- Perstack emits events during Expert execution for observability and state management. This document explains the event system architecture and how to consume events. diff --git a/docs/references/perstack-toml.md b/docs/references/perstack-toml.md index 665928d0..1b00b3fc 100644 --- a/docs/references/perstack-toml.md +++ b/docs/references/perstack-toml.md @@ -1,5 +1,7 @@ --- title: "perstack.toml Reference" +sidebar: + order: 3 --- - [Complete Example](#complete-example) diff --git a/docs/references/providers-and-models.md b/docs/references/providers-and-models.md index 33b04d15..3f642e80 100644 --- a/docs/references/providers-and-models.md +++ b/docs/references/providers-and-models.md @@ -1,5 +1,7 @@ --- title: "Providers and Models" +sidebar: + order: 4 --- Perstack supports multiple LLM providers. Configure via CLI options, environment variables, or `perstack.toml`. diff --git a/docs/understanding-perstack/boundary-model.md b/docs/understanding-perstack/boundary-model.md index fe764325..268a4dea 100644 --- a/docs/understanding-perstack/boundary-model.md +++ b/docs/understanding-perstack/boundary-model.md @@ -1,5 +1,7 @@ --- title: "The Boundary Model" +sidebar: + order: 4 --- [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. diff --git a/docs/understanding-perstack/concept.md b/docs/understanding-perstack/concept.md index 04f15cb0..dfbe6246 100644 --- a/docs/understanding-perstack/concept.md +++ b/docs/understanding-perstack/concept.md @@ -1,5 +1,7 @@ --- title: "Concept" +sidebar: + order: 1 --- Perstack is built on a concept called **Expert Stack** — the architecture that enables agent-first development. @@ -45,21 +47,7 @@ Expert Stack focuses on **how to define, share, and reuse** agent capabilities. Most agent frameworks optimize for building applications, not for reusing what's built. Expert Stack was designed from the ground up with reusability as a first-class concern. -Expert definitions are plain text with no framework dependency. Any agent framework can consume them through the [Registry API](https://perstack.ai/api/v1/spec). The ecosystem is open. - -## Key features - -In agent-first development, the "system" carries most of the weight — it must interpret definitions and make them work. Expert Stack provides: - -- **Experts** — modular micro-agents (the definitions) -- **Runtime** — executes Experts -- **Registry** — shares Experts -- **Sandbox Integration** — safe production execution - -- [Experts](./experts.md) -- [Runtime](./runtime.md) -- [Registry](./registry.md) -- [Sandbox Integration](./sandbox-integration.md) +Expert definitions are plain text with no framework dependency. Any agent framework can consume them through the [API](https://perstack.ai/api/v1/spec). The ecosystem is open. ## The three goals diff --git a/docs/understanding-perstack/experts.md b/docs/understanding-perstack/experts.md index 25281be2..6adb6a51 100644 --- a/docs/understanding-perstack/experts.md +++ b/docs/understanding-perstack/experts.md @@ -1,5 +1,7 @@ --- title: "Experts" +sidebar: + order: 2 --- Experts are the core building block of Perstack — modular micro-agents designed for reuse. @@ -227,6 +229,6 @@ How you organize workspace files is up to you. The runtime reserves `perstack/` Ready to build Experts? See the Making Experts guide: -- [Making Experts](../making-experts/README.md) — defining Experts in `perstack.toml` +- [Making Experts](../making-experts/best-practices.md) — defining Experts in `perstack.toml` - [Best Practices](../making-experts/best-practices.md) — design guidelines for effective Experts - [Skills](../making-experts/skills.md) — adding MCP tools to your Experts diff --git a/docs/understanding-perstack/registry.md b/docs/understanding-perstack/registry.md deleted file mode 100644 index 894b2b84..00000000 --- a/docs/understanding-perstack/registry.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "Registry" ---- - -The Perstack Registry is a community-driven ecosystem for sharing Experts — like npm, but for AI agents. - -## Definition-only - -Unlike traditional package registries (npm, PyPI) that distribute executables, the Perstack Registry stores **only Expert definitions** — plain text `perstack.toml` content. - -| Traditional Registry | Perstack Registry | -| -------------------------------- | ------------------------------ | -| Distributes binaries/executables | Distributes text definitions | -| Code runs directly | Runtime interprets definitions | -| Hard to audit | Fully transparent | - -This separation clarifies responsibilities: -- **Registry**: Manages *what* Experts do (definitions) -- **Runtime**: Controls *how* Experts execute (in sandbox) - -> [!NOTE] -> Text-based definitions can still contain malicious instructions. Registry transparency is one layer — combine with sandbox execution, environment variable control, and workspace isolation for defense in depth. - -## Using Registry Experts - -Run Experts directly from the Registry: - -```bash -npx perstack run @acme/researcher "Analyze market trends" -``` - -Or reference them as delegates in `perstack.toml`: - -```toml -[experts."my-expert"] -instruction = "Delegate research tasks to the researcher." -delegates = ["@org/researcher"] -``` - -The runtime automatically fetches and caches Registry Experts. - -> [!NOTE] -> The runtime first checks `perstack.toml` for a matching Expert key. If not found locally, it fetches from the Registry. - -## Versioning - -The Registry uses Semantic Versioning (SemVer): - -```bash -npx perstack run @acme/researcher@1.2.3 "Analyze market trends" -``` - -### Write-once immutability - -Once published, a version **cannot be changed**: -- Same version number always returns identical content -- Dependency resolution is deterministic -- No supply chain attacks via version tampering - -Without a version specifier, `latest` is used: - -```bash -npx perstack run @acme/researcher "Analyze market trends" -# equivalent to @acme/researcher@latest -``` - -## Scoped Experts - -Experts are namespaced by organization: - -``` -@{organization}/{expert-name} -``` - -Examples: -- `@acme/researcher` — public Expert from Acme org -- `@mycompany/code-reviewer` — private Expert for internal use - -## Publishing - -Publish Experts using the CLI: - -```bash -npx perstack publish my-expert -``` - -For detailed instructions, see [Publishing Experts](../making-experts/publishing.md). - -## Security - -The Registry provides several security guarantees: - -| Measure | What it prevents | -| -------------------------- | ---------------------------------------- | -| **Write-once versioning** | Version tampering, supply chain attacks | -| **Content integrity** | MITM attacks during distribution | -| **Explicit `requiredEnv`** | Unintended environment variable exposure | - -Registry security is one layer of defense. See [Sandbox Integration](./sandbox-integration.md) for the full security model. - -## API Reference - -For programmatic access, see [API Reference](https://perstack.ai/api/v1/spec). diff --git a/docs/understanding-perstack/runtime.md b/docs/understanding-perstack/runtime.md index b7432743..3094e46a 100644 --- a/docs/understanding-perstack/runtime.md +++ b/docs/understanding-perstack/runtime.md @@ -1,5 +1,7 @@ --- title: "Runtime" +sidebar: + order: 3 --- The Perstack runtime combines probabilistic LLM reasoning with deterministic state management — making agent execution predictable, reproducible, and auditable. diff --git a/docs/understanding-perstack/sandbox-integration.md b/docs/understanding-perstack/sandbox-integration.md index 754f241b..c779a4c0 100644 --- a/docs/understanding-perstack/sandbox-integration.md +++ b/docs/understanding-perstack/sandbox-integration.md @@ -1,5 +1,7 @@ --- title: "Sandbox Integration" +sidebar: + order: 5 --- ## Why sandbox-first? diff --git a/docs/using-experts/README.md b/docs/using-experts/README.md deleted file mode 100644 index fa7b945b..00000000 --- a/docs/using-experts/README.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: "Using Experts" ---- - -This section covers **running and integrating Experts** — CLI usage, state management, and error handling. - -## In this section - -- [Workspace](./workspace.md) — execution environment and file isolation -- [Running Experts](./running-experts.md) — CLI commands for running Experts -- [State Management](./state-management.md) — checkpoints, pausing, and resuming -- [Error Handling](./error-handling.md) — error recovery strategies - -## Who is this for? - -- Users who want to run Experts -- Developers integrating Experts into applications -- Anyone debugging or managing Expert execution - -For defining Experts, see [Making Experts](../making-experts/README.md). diff --git a/docs/using-experts/error-handling.md b/docs/using-experts/error-handling.md index 8eda8f1c..ecca741c 100644 --- a/docs/using-experts/error-handling.md +++ b/docs/using-experts/error-handling.md @@ -1,5 +1,7 @@ --- title: "Error Handling" +sidebar: + order: 4 --- 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. diff --git a/docs/using-experts/running-experts.md b/docs/using-experts/running-experts.md index 410a1bc6..34e2c550 100644 --- a/docs/using-experts/running-experts.md +++ b/docs/using-experts/running-experts.md @@ -1,5 +1,7 @@ --- title: "Running Experts" +sidebar: + order: 1 --- Perstack provides two commands for running Experts: `start` and `run`. diff --git a/docs/using-experts/state-management.md b/docs/using-experts/state-management.md index 95da5ecd..57721df2 100644 --- a/docs/using-experts/state-management.md +++ b/docs/using-experts/state-management.md @@ -1,5 +1,7 @@ --- title: "State Management" +sidebar: + order: 2 --- Perstack automatically saves execution state, enabling continuation and replay. diff --git a/docs/using-experts/workspace.md b/docs/using-experts/workspace.md index c88bacc3..48aba81b 100644 --- a/docs/using-experts/workspace.md +++ b/docs/using-experts/workspace.md @@ -1,5 +1,7 @@ --- title: "Workspace" +sidebar: + order: 3 --- The workspace is the isolated directory where Experts execute. All file operations are confined to this directory.