@hypercubed/kody-os
Minimal shared Human/Agent OS shell — ReKindle-style blank slate for browser-first use.
Files
kody-os operations
This file is the operations runbook for an agent working on a kody-os install: install, update, absorb, overwrite, restore, and remove apps, and add a brand-new app. The Store renders one-line prompts that point here; the procedure lives here, not in the prompt.
How to read this file
- A catalog folder URL names an app: its last segment is the app id, and the folder holds
RECIPE.md(the install recipe) anddefinition.json(the catalog definition). Follow the recipe to install; readdefinition.jsonto compare versions. - A catalog base is the directory containing
catalog.json. The public base ishttps://raw.githubusercontent.com/Hypercubed/kody-os/main/catalog/; a pinned tag replacesmainwith the tag. - References of the form
package:<slug>#…use the reader's own package slug, rendered by the prompt. This file names no slug.
Shared rules
These apply to every operation below.
- Ask the user before writing when anything is missing or ambiguous.
- Never publish or change the package source. These operations change installed apps and their state, never the package itself.
- Verify after every write:
list_apps, andexport_appwhere the operation writes a definition. - On definition replacement, state for surviving fields carries forward; dropped fields reset to
initial.
Working without an App Store
These operations are package MCP functions; the Store is only one UI that renders prompts for them. They work with no App Store installed.
The catalog base rules: an explicit catalogBase parameter wins; with none, the installed Store's declared base is used; with neither, the call is refused with a no-catalog-source error naming the app id and writes nothing. So with no Store installed, pass the base explicitly.
Prefer the store_* variants for Store-managed installs and updates: they record the install snapshot that makes rows read up-to-date. The plain install_from_catalog / update_from_catalog do not record snapshots.
Install
Follow the recipe (RECIPE.md in the folder), or call store_install_from_catalog(id, undefined, catalogBase). install_from_catalog(id, undefined, catalogBase) is the generic form without a snapshot. Verify with list_apps (and get_app_state). Recipe-only apps have no JSON install path: follow the recipe. Ask before installing if any detail is missing or ambiguous.
Update
store_update_from_catalog(id, undefined, catalogBase). update_from_catalog(id) takes no base parameter — it resolves the installed Store's declared base and refuses without one. Verify by exporting / list_apps.
Absorb
Merge the catalog changes into an installed definition, keeping local customizations. Take a backup first with backup(name) so the absorb can be undone. Read the installed definition with export_app(id) and the catalog definition with get_catalog_definition(id, catalogBase?). Compare the two field by field, keep local customizations and take the catalog changes. Show the merge plan (every field kept, taken, and in conflict) and ask before writing anything, and ask which value to keep for any field in conflict. Then write the merged definition with absorb_from_catalog(id, definition, catalogBase?) at the catalog version. Verify afterwards by exporting the app again and confirming the stored definition matches the merged one.
The absorb is refused, with no write, unless the app is installed, is in the catalog, and its status is behind-modified, modified-current, or absorbed-behind; and unless the merged definition's catalogVersion equals the catalog's.
Overwrite
store_update_from_catalog(id, undefined, catalogBase) with an explicit confirmation — it discards local definition changes. Export first if keeping them. Same call as Update; the difference is confirmation and the row's status.
Restore
Same call as Update / Overwrite (store_update_from_catalog with an explicit base, or update_from_catalog when a Store is installed). It restores the catalog copy. Export first if keeping local edits. Ask first.
Remove
remove_app(id) — deletes the definition, state, registry entry, install snapshot, and pinned / hidden / recent / homepage references. Verify with list_apps. Ask before removing if anything is missing or ambiguous.
Add a new app
Adding a brand-new app is authoring, not a store operation. Follow the adding-an-app skill in this same package: .agents/skills/adding-an-app/SKILL.md.