---
name: hosty-app-skill
description: Build, wrap, or update Hosty runtime apps. Use when creating app manifests under schemaVersion app.0.1, publishing app-feeds.0.1 feeds, configuring Docker or localCommand runtime profiles, app data directories and backups, external host-path mounts (externalMounts / catalog roots), Shell UI metadata, Hosty Core identity, app-owned MCP endpoints (interfaces.mcp), scoped app directory access, runtime-app roles, dependencies, OpenTelemetry/telemetry export (telemetry block + OTEL_* env), or validating apps with Core-managed local runtime profiles.
---

# Hosty App Skill

Use this skill to implement Hosty runtime apps in the shape expected by this repository. The supported contract is an app manifest with `schemaVersion: "app.0.1"`.

## Workflow

1. Identify whether the user wants to create a new runtime app, wrap an existing app, update an app manifest, add Hosty identity/roles, configure data/backups, or validate an app.
2. Treat `docs/features/runtime-app-manifest/feature.md`, `docs/features/domain-model/feature.md`, `docs/features/auth-gateway/feature.md`, `apps/core/src/Haas.Hosty.Core/RuntimeAppManifest.cs`, `apps/core/src/Haas.Hosty.Core/CoreLifecycleService.cs`, and `apps/demo-app` as source of truth when implementation details matter.
3. Use `apps/demo-app/manifest.json` as the manifest shape and `hosty apps install apps/demo-app --runtime dev` as the local directory install pattern.

## Running Core Guide

When working against a running Core, retrieve `get_app_development_guide` over authorized Core MCP
or `app_creation_guide` in Harness. Start with overview, then request relevant topics. The operator
CLI equivalent is `hosty --data-root <root> apps guide --topic <id> --format json`. Check the Core
version, guide revision and manifest schema before applying examples; SDK capabilities differ by
stack. These readers grant no mutation authority. Do not bypass disabled/refused MCP with a shell
bridge; an already authorized typed coordinator may use the same control reader. Repository source
and the references below remain the evidence for changes to the current implementation.

## References

- Read `references/app-manifest.md` when authoring or reviewing `manifest.json`, runtime profiles, service implementations, settings, storage, dependencies, endpoints, install/update behavior, or backups.
- Read `references/app-auth-and-users.md` when adding app identity, app-owned roles, or scoped app directory access.
- Read `references/app-manifest.md` ("MCP Interface") when adding or debugging an app's MCP endpoint — delegated- and scoped-token auth, the handshake's HTTP 202, and read-only annotations.
- Read `references/app-feeds.md` when publishing or reviewing repository-owned `feeds.json` for Marketplace discovery and Core-managed updates.
- Read `references/app-launch-mode.md` when the app has a UI, to keep it from drawing the name and page navigation a shell already renders around it.
- Read `references/demo-app-patterns.md` when validating against the repository Demo App.
- Read `references/app-implementation-checklist.md` before final verification.

## Local Validation

Use Core-managed runtime app lifecycle:

```bash
hosty core start
hosty apps install apps/demo-app --runtime dev
hosty apps start com.haas.demo-app
```

For direct endpoint probes:

```bash
TOKEN="$(hosty apps identity com.haas.demo-app --user user@docker-host.local --format token)"
curl -H "X-Docker-Host-Identity: $TOKEN" <assigned-demo-app-origin>/api/auth/identity
```