Complete APP.md

A complete app manifest is not long for its own sake. It is complete because a host can discover, review, project, check readiness, run, audit, upgrade, and uninstall the app without guessing.

Use docs/examples/content-factory-app/APP.md as the current fixture. The sections below explain what should be present in a production-ready package.

Required identity

manifestVersion: 0.10.0
name: content-factory-app
description: Content Factory App for knowledge building, content scenario planning, content production, and review.
version: 1.0.0
status: ready
appType: domain-app
runtimeTargets:
  - local

Identity fields let registries and hosts index the package. They should be stable and boring.

Runtime requirements

requires:
  lime:
    appRuntime: "current"
  sdk: "@lime/app-sdk"
  capabilities:
    lime.ui: "current"
    lime.storage: "current"
    lime.agent: "current"
    lime.connectors: "current"

Requirements should describe what the host must provide. They should not describe host internals.

Runtime package

runtimePackage:
  ui:
    path: ./dist/ui
  worker:
    path: ./dist/worker
  storage:
    schema: ./storage/schema.json
    migrations: ./storage/migrations

APP.md points to implementation assets; it does not contain the implementation.

Entries

entries:
  - key: dashboard
    kind: page
    title: Dashboard
    route: /dashboard
  - key: content_calendar
    kind: workflow
    title: Content calendar
    workflow: ./workflows/content-calendar.workflow.md

Entries are user-visible launch points. A complete app usually has more than one entry and is not only an expert-chat.

Storage and data boundary

storage:
  namespace: content-factory-app
  schema: ./storage/schema.json
  migrations: ./storage/migrations
  uninstallPolicy: ask

Storage must be namespaced so uninstall, export, and audit can work.

Agent runtime control

A complete app that calls lime.agent should include app.runtime.yaml or an equivalent agentRuntime field. The runtime layer declares the task event/result schema, JSON Schema structured output, runtime approval behavior, session resume/fork policy, tool discovery strategy, checkpoint scope, and observability defaults.

agentRuntime:
  agentTask:
    eventSchema: lime.agent-task-event.v1
    resultSchema: lime.agent-task-result.v1
    structuredOutput:
      type: json_schema
      schemaRef: ./artifacts/workspace-patch.schema.json
      maxValidationRetries: 2
    approval:
      behavior: host-mediated
    sessionPolicy:
      modes: [new, resume, continue, fork]
    toolDiscovery:
      mode: on_demand
    checkpointScope:
      workflowState: true
      appStorage: true
      artifacts: true
    observability:
      openTelemetryMapping: true
      exportContentByDefault: false

requirement boundary

A complete app should include independent boundary files that explain what the App owns and what requires Host, Cloud, connector, external-system, or human-decision support.

app.requirements.yaml   # requirements, MVP, non-goals, acceptance criteria
app.boundary.yaml       # App / Host / Cloud / Connector / External / Human responsibilities
app.integrations.yaml   # Host/Cloud-managed external connection needs
app.operations.yaml     # side effects, approval, dry-run, evidence

If a requirement writes, publishes, deletes, or bulk-updates external systems, app.operations.yaml must declare human approval, dry-run, idempotency, and evidence.

Dependencies and deliverables

A complete app usually declares:

• knowledgeTemplates for required and optional Knowledge slots
• skillRefs for procedural Skills
• toolRefs for external or host-provided tools
• artifactTypes for durable outputs
• evals for quality gates
• permissions for host policy
• secrets for credential slots
• overlayTemplates for tenant and workspace configuration
• requirements / boundary / integrations / operations for requirement boundaries and capability handoff

Human guide

The Markdown body should answer:

1. What problem does this app solve?
2. Which entries should users start with?
3. What setup is required?
4. What data should never be included in the official package?
5. What artifacts are created?
6. What quality gates apply?
7. How should the app be upgraded or removed?

Complete-package checklist

Area	Complete when
Manifest	Required fields and requirements are present.
Runtime package	UI, worker, storage, and workflow paths are declared when used.
Entries	Every user launch point has stable key, kind, title, and binding metadata.
Context and data	Context requirements, storage namespace, Knowledge slots, overlays, and secrets are explicit.
Policy and operations	Permissions, runtime approval, external side effects, connectors, and risky capabilities are declared.
Quality and trust	Artifact types, structured output schemas, Evidence capture, QC, and evals are connected to workflows.
Overlays	Tenant and workspace differences do not fork the package.
Provenance	Projection and runtime outputs can trace back to app version and hashes.
Cleanup	Disable, uninstall keep data, and delete data behavior is known.

Validation commands

npm run cli -- validate docs/examples/content-factory-app
npm run cli -- project docs/examples/content-factory-app
npm run cli -- readiness docs/examples/content-factory-app

A valid complete app may still return needs-setup in readiness if required Runtime, Context, Knowledge, Skill, Tool / Connector, Artifact, Evidence, Policy, or QC assets are not bound yet. That is expected.