Build a DeepBot app

A DeepBot app is a folder. DeepBot reads its app.json, gives the Bot its skill, shows its cards in the chat when the Bot calls them, puts its pages in DeepBot (Apps), and lets the Bot run its scripts on the person's computer. The interface is plain HTML, CSS and JavaScript in a locked frame that talks to DeepBot through window.deepbot (the bridge).

my-app/
  app.json              what the app is and what it may do        (references/manifest.md)
  skill/SKILL.md        what the Bot reads: when and how to use it  (references/app-skill.md)
  ui/                   cards and pages: HTML, CSS, JS              (references/surfaces.md, bridge.md, design.md)
  scripts/              optional: programs the Bot runs             (references/scripts.md)
  listing.md            the app's page in the catalogue             (references/listing.md)
  listing/              icon, banner, screenshots for that page

Read the reference for each part before you write it:

Three complete, working apps are in examples/ (notes-board: a card and a page with files, storage, ask and openPage; quick-weather: a card that calls a web API; image-tools: a Python script plus a result card). Start from the one closest to what you build. For anything bigger than a card and a page, read references/patterns.md first.

#1. Understand the app

Ask (in one short message, only what you do not know yet):

• what the person wants to get done, and who will use it;
• what the Bot should be able to do with it, in a sentence the person would type ("make me a packing list for ...", "how much did we spend on ...");
• what the person needs to see (a result in the chat, a screen to come back to, both);
• whether it needs the internet (which services) or programs on the computer.

#2. Choose the parts

Most apps are: the Bot writes files in the app's workspace folder, then calls a card that reads them and shows them; a page shows all of them. Keep the data in files the Bot can read and write, in a format you define in the skill.

#3. Write it

1. app.json (references/manifest.md). id is permanent. Card names are tools the Bot calls: unique, show + your app's name + thing (showRecipeBox), never one of DeepBot's own (references/reserved-cards.md). Ask only for the permissions the app uses.
2. skill/SKILL.md (references/app-skill.md): when to use the app, the files and their exact format, which card to call with which arguments, what to say after.
3. The interface (references/surfaces.md, bridge.md, design.md):
   • every page includes nothing extra: DeepBot injects the bridge (window.deepbot) and the design kit (CSS variables, db-* classes) into every HTML page it serves;
   • await deepbot.ready before reading deepbot.args;
   • a card ends with deepbot.done(note) or deepbot.fail(message): the Bot hears it;
   • use the kit's colour variables so light and dark mode both work;
   • escape everything you put into HTML;
   • keep every file inside the app (no CDNs): it must work offline and pass review.
4. Scripts, if any (references/scripts.md): Python 3 by default, JSON lines out, never write into the app's own folder.
5. listing.md and listing/ (references/listing.md): description, FAQ, changelog, icon, banner, 2-6 screenshots.

#4. Test it in developer mode

In DeepBot: Apps -> Developer mode (switch, top right) -> From a folder -> the app's folder -> Link. The app loads at once, every save reloads its pages and cards, and the checks show under the app. Then:

• ask the Bot in a new conversation something that should use the app; check it calls the card with the right arguments and that the card reports done;
• open each page; switch DeepBot to dark mode (Settings) and look again;
• try the failure paths (missing file, no network): the card must say what went wrong and call deepbot.fail.

If you are DeepBot's own Bot building an app: write it in the workspace under my-apps/<id>/ (never inside DeepBot's program folder), print its full path ($env:WORKSPACE_DIR / $WORKSPACE_DIR + /my-apps/<id>), and ask the person to link that folder (Apps -> Developer mode -> From a folder). After they link it, the app's skill is yours too: test it by doing the task yourself in a new conversation.

#5. Publish (references/publish.md)

Public GitHub repository, git tag v1.0.0 && git push --tags, then submit the repository and the tag on the DeepBot site (Developers -> sign in with GitHub). Every version is reviewed; a new version needs a higher version and a new tag.

#Rules that get an app rejected

• a card with a name DeepBot already uses, or two cards with the same name;
• network calls to hosts not in permissions.network, requests from the page straight to other hosts instead of deepbot.net.fetch, or "*" without a reason;
• scripts that touch files outside the workspace or the app's own folders without the person asking, download and run code, or hide what they do;
• obfuscated or minified code without its source, executables (.exe, .dll ...);
• sending the person's data anywhere the listing does not say;
• copying another app or a name that imitates one.