---
name: ash-framework
description: Internal Ash framework guide for contributors working on discovery, compilation, runtime behavior, `.ash` artifacts, sandbox/workflow plumbing, or other implementation details behind the public authored surface.
metadata:
  author: Ash repo
  version: "0.0.1"
---

Use this skill for implementation-facing Ash work.

## When to use this skill

Use this skill when the task changes or depends on Ash internals, including:

- discovery or validation behavior
- compiler outputs and `.ash` artifacts
- Nitro host or runtime integration
- runtime loading and turn preparation
- message execution and durable session behavior
- workspace or sandbox plumbing
- build and deploy behavior tied to framework internals

If the task is primarily about how an app author uses Ash, use the `ash-agent` skill instead.

## How to use this skill

1. Read the bundled internal references before making claims.
2. Preserve the architecture boundaries listed here.
3. Use the packaged scripts when validating the repo.
4. Update public docs too when user-facing behavior changes. When writing or
   adding files under `/docs/public`, follow the format spelled out in the
   `ash-agent` skill's "Writing or updating public docs" section — each new
   file needs frontmatter (`title` + `description`), a slot in
   `/docs/public/meta.json#pages`, and an optional `url:` override if its
   filename does not match the intended site URL. Run `pnpm docs:check` to
   validate.

## Core boundaries to preserve

- discovery is filesystem-only and must not execute authored modules
- compiler output is framework-owned and inspectable
- runtime consumes compiled artifacts instead of rediscovering authored files per request
- authored dynamic code runs inside framework-owned execution boundaries
- workspace and sandbox are different runtime surfaces
- the sandbox currently uses local and Vercel backends
- message execution is durable and asynchronous

## Common mistakes to avoid

- reintroducing authored-module execution during discovery
- making request paths depend on rediscovery or recompilation
- explaining Ash purely from internal architecture when the task is user-facing
- treating `lib/` as workspace-mounted content
- adding unnecessary step boundaries for pure data reshaping work
- confusing route auth with per-run ownership controls
- forgetting that artifacts are still useful for debugging compile failures

## Preferred references

Read these bundled references in roughly this order:

1. `references/architecture.md`
2. `references/discovery-and-compilation.md`
3. `references/runtime-model.md`
4. `references/workspace-and-sandbox.md`
5. `references/quality-gates.md`

## Runtime notes

- hosted Vercel builds are detected via `VERCEL` and write host output to `.vercel/output`
- local builds write host output to `.output`
- Vercel sandbox prewarm can happen at build time when the relevant deployment environment is present
- if hosted Vercel prewarm is attempted and fails, the build should fail instead of masking it
- workspace template-preparation is independent from sandbox backend selection

## Bundled scripts

Use these packaged scripts when helpful:

- `scripts/run-framework-gates.sh` - run the expected repo quality gates
- `scripts/framework-review-checklist.sh` - print the internal review checklist

## Supporting skills

When internal work touches adjacent systems, also load the relevant specialist skills.
Use `ai-sdk` for model and tool-calling work, and `workflow` for durable orchestration behavior.

## Completion checklist

- validate the architecture boundaries above are preserved
- update public docs when public behavior changes
- run the expected quality gates before considering the work done
- ensure public API changes are documented and covered by tests