Docs: Update documentation for multi-runtime support

[FL4TLiN3]

Overview

Review and finalize all documentation related to multi-runtime support. Most documentation was written ahead of implementation; this issue ensures everything is accurate and complete.

Background

Documentation locations:

• docs/content/using-experts/multi-runtime.mdx — Main feature documentation
• docs/content/references/cli.mdx — CLI reference
• docs/content/references/perstack-toml.mdx — Configuration reference
• docs/content/references/registry-api.mdx — Registry API reference
• packages/*/README.md — Package-specific documentation

Implementation

1. Review multi-runtime.mdx

File: docs/content/using-experts/multi-runtime.mdx

Verify:

• All CLI commands work as documented
• Example TOML configurations are valid
• Execution flow diagram is accurate
• Limitations section is complete
• Runtime-specific setup instructions are correct

Update if needed:

• CLI command examples
• Error messages
• Prerequisites
• Limitations discovered during implementation

2. Review cli.mdx

File: docs/content/references/cli.mdx

Verify:

• --runtime option documented correctly
• Available runtimes list is accurate
• Examples are valid

3. Update perstack-toml.mdx

File: docs/content/references/perstack-toml.mdx

Add runtime field to Expert definition table:

| Field     | Type               | Required | Description                               |
| --------- | ------------------ | -------- | ----------------------------------------- |
| `runtime` | string \| string[] | No       | Target runtimes (default: `["perstack"]`) |

Add example:

[experts."my-expert"]
version = "1.0.0"
runtime = ["perstack", "cursor"]
description = "Multi-runtime capable expert"
instruction = "..."

4. Update registry-api.mdx

File: docs/content/references/registry-api.mdx

Verify runtime field is documented in:

• Publish Expert request body
• Get Expert response
• Expert schema

5. Update Runtime Package README

File: packages/runtime/README.md

Add section on RuntimeAdapter:

## Multi-Runtime Support

The runtime package supports execution via external runtimes through the adapter system.

### Available Adapters

| Adapter             | Runtime       | Description                |
| ------------------- | ------------- | -------------------------- |
| `PerstackAdapter`   | `perstack`    | Built-in runtime (default) |
| `CursorAdapter`     | `cursor`      | Cursor CLI headless mode   |
| `ClaudeCodeAdapter` | `claude-code` | Claude Code CLI            |
| `GeminiAdapter`     | `gemini`      | Gemini CLI                 |

### Using Adapters

```typescript
import { getAdapter, isAdapterAvailable } from "@perstack/runtime"

if (isAdapterAvailable("cursor")) {
  const adapter = getAdapter("cursor")
  const prereqs = await adapter.checkPrerequisites()
  if (prereqs.ok) {
    const result = await adapter.run({ setting, checkpoint })
  }
}

See Multi-Runtime Support for full documentation.

### 6. Update Core Package README

**File:** `packages/core/README.md`

Add `RuntimeName` type to exports section:

```markdown
### Runtime Types

- `RuntimeName` — Union type of supported runtime names
- `runtimeNameSchema` — Zod schema for runtime name validation

7. Update Root README

File: README.md

Verify multi-runtime is mentioned in features if it's a key capability.

Affected Files

File	Change
docs/content/using-experts/multi-runtime.mdx	Review and update
docs/content/references/cli.mdx	Verify --runtime documentation
docs/content/references/perstack-toml.mdx	Add runtime field
docs/content/references/registry-api.mdx	Add runtime field
packages/runtime/README.md	Add adapter documentation
packages/core/README.md	Add RuntimeName exports
README.md	Mention multi-runtime if appropriate

Documentation Checklist

Accuracy

• All code examples compile/run
• All CLI commands work as shown
• All TOML examples are valid
• Error messages match implementation

Completeness

• All new types documented
• All new CLI options documented
• All limitations documented
• All prerequisites documented

Consistency

• Terminology consistent across docs
• Format consistent with existing docs
• Links work and point to correct locations

Acceptance Criteria

• All documentation files reviewed
• All code examples verified
• runtime field documented in perstack-toml.mdx
• RuntimeAdapter documented in runtime README
• RuntimeName documented in core README
• No broken links
• Documentation builds without errors (pnpm build in docs/)

Dependencies

All previous issues in the multi-runtime epic.

Blocked By

• Docs: Add related documentation links to runtime README #1 Core schema runtime field
• chore: version packages #2 CLI --runtime option
• Fix: maxSteps off-by-one error #3 RuntimeAdapter interface
• chore: version packages #4 Integrate adapters into CLI
• Fix: Handle individual close failures in closeSkillManagers #5 CursorAdapter
• chore: version packages #6 ClaudeCodeAdapter
• Fix: Handle file read errors gracefully in resolving file states #7 GeminiAdapter
• chore: version packages #8 Event Normalization
• Fix: Add explicit error when delegate expert not found #9 TUI Multi-Runtime
• chore: version packages #10 Registry runtime field
• Fix: Clean up managers when delegate expert not found #11 E2E Tests

Blocks

None (final issue)

Notes

This issue should be completed last, after all implementation is done and tested. The documentation review ensures everything is accurate based on actual implementation behavior.

[github-actions]

Current Status of Multi-Runtime Documentation (Issue #100)

Based on my review of the codebase, here's the current state of the documentation for multi-runtime support:

❌ Missing Documentation Files

1. docs/content/using-experts/multi-runtime.mdx - Does NOT exist
   • This is the main feature documentation file mentioned in the issue
   • The file is completely missing from the repository

❌ Missing Documentation Sections

2. docs/content/references/cli.mdx - Missing --runtime option

   • The CLI reference does not document any --runtime option
   • Current options include --provider, --model, --max-steps, etc., but no runtime selection

3. docs/content/references/perstack-toml.mdx - Missing runtime field

   • The Expert Definition section does not include a runtime field
   • Current fields: version, minRuntimeVersion, description, instruction, delegates

4. docs/content/references/registry-api.mdx - Missing runtime field

   • The Publish Expert request body does not document a runtime field
   • The Get Expert response does not show a runtime field

5. packages/runtime/README.md - Missing RuntimeAdapter documentation

   • No section on multi-runtime support or RuntimeAdapter
   • No documentation about available adapters (CursorAdapter, ClaudeCodeAdapter, GeminiAdapter)

6. packages/core/README.md - Missing RuntimeName exports

   • The exports section does not document RuntimeName type or runtimeNameSchema

🔍 Implementation Status

The multi-runtime feature has NOT been implemented yet. My search of the codebase found:

• No RuntimeAdapter interface or implementations
• No RuntimeName type or schema
• No adapter files (CursorAdapter, ClaudeCodeAdapter, GeminiAdapter)
• No --runtime CLI option

📋 Recommendation

Since the implementation doesn't exist yet, all documentation mentioned in issue #100 needs to be created from scratch once the feature is implemented. The issue correctly states that "documentation was written ahead of implementation" but it appears that documentation was never actually written - it was only planned.

The issue should be updated to reflect that this is not a documentation review task, but rather a documentation creation task that depends on completing all the implementation issues (#1-#11) first.

---

🤖 Bot Activity

✅ Done
---