# AppsChat MiniKit

AppsChat MiniKit is an SDK and mini app runtime protocol for Agent-generated mini apps.

Read first:
- ./index.html
- ./agent/index.html
- repository source doc: docs/reference/component-protocol.md
- repository source doc: docs/reference/components-and-apis.md

Machine-readable source of truth:
- ./agent-pack.json
- ./component-manifest.json
- ./api-manifest.json
- ./search-index.json

Human catalog pages:
- ./components/index.html
- ./apis/index.html

Generation workflow:
1. Read agent-pack.json first when generating or repairing a MiniApp.
2. Generate source-first MiniApps: app.js + pages/* + components/* + tests/* + miniapp.json.
3. Do not hand-edit generated artifacts such as manifest.json, app-service.js, or package zips.
4. Use defineMiniApp and definePage helpers instead of ad hoc package objects.
5. Add executable manifest.tests for primary user flows.
6. Run report/validation before packaging:
   - npm run miniapp -- report <miniapp-entry> --require-tests --json
   - npm run miniapp -- validate <miniapp-entry> --smoke --json

Component and API rules:
- Use only standard components listed in component-manifest.json.
- Declare required permissions in manifest.permissions.
- Declare every Host API call in manifest.apisUsed, including ac.* APIs required by capability components.
- Prefer basic layout, form, content, feedback, and navigation components unless the user explicitly needs canvas, diagram-view, media, camera, map, web-view, socket, or stream capabilities.
- Mermaid workflows should use code-editor + diagram-view and ac.renderMermaid; export/copy flows may use ac.captureNode and ac.setClipboardImage.
- Use ac.navigateTo, ac.redirectTo, and ac.navigateBack for navigation.
- Use ac.createSelectorQuery only for node measurement; do not use DOM APIs directly.

Runtime component cards:
- Declare reusable runtime components in manifest.components.
- Prefer manifest.chatComponents entries that reference declared components.
- Legacy chatComponents.path/page cards are compatibility-only; new interactive cards should use component mounts.
- Component cards have their own lifecycle and limited Host API scope.
- Component cards may emit events, request resize, preview/save images, copy clipboard data, open chat, open MiniApps, and call explicitly granted capability APIs.
- Component cards must not call page navigation APIs or ac.developer.*.
- Arbitrary DOM/render-tree extraction is not supported; only explicit manifest components or exports are addressable.

Official/developer APIs:
- ac.developer.* is reserved for trusted official developer assistant MiniApps.
- Ordinary MiniApps and chat component cards must not request or call ac.developer.*.
- Developer token secrets are one-time return values; never persist or display old secrets.

Quality gates and packaging:
- Keep agent-pack.json, component-manifest.json, api-manifest.json, and docs-site generated from SDK source.
- When component/API/source capability changes, rebuild and check docs/agent contracts:
  - npm run build:agent-pack
  - npm run check:agent-pack
  - npm run docs:build
  - npm run docs:check
  - npm run verify

Useful machine-readable entries:
- ./agent-pack.json
- ./component-manifest.json
- ./api-manifest.json
- ./search-index.json