@emptyos/client 0.1.0

package/skills/emptyos-computer/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: emptyos-computer
+description: Work with a personal EmptyOS computer through the external `empty` CLI. Use when an agent needs to connect to or inspect a computer; work with Things, Projects, Data, changes, sharing, or hooks; publish verified software; or enter the computer for resident-only work.
+---
+
+# EmptyOS Computer
+
+Run every `empty` command from the local terminal. The client decides whether
+the operation is local, transported over SSH, or a local/remote Git workflow.
+Use the live help as the command reference:
+
+```sh
+empty --help
+empty thing --help
+empty <command> --help
+```
+
+Use `--json` for stable results and error codes rather than parsing human text.
+
+This skill ships inside the `@emptyos/client` npm package; `empty skill
+install [--dir <path>]` copies it into a skills directory. For anything beyond
+this bootstrap, read https://emptyos.com/docs/.
+
+## Start and select a computer
+
+Inspect the selected profile and available profiles first:
+
+```sh
+empty computer show --json
+empty computers --json
+```
+
+If no computer profile exists and the user supplies an EmptyOS computer URL,
+connect through EmptyOS rather than asking for an exe.dev account or provider
+SSH access:
+
+```sh
+empty connect https://<computer-host>
+```
+
+Show the user the printed short code, SSH-key fingerprint, and approval URL.
+Wait for them to authenticate with EmptyOS, compare both values, and approve
+the request. `connect` derives the local alias from the hostname; `--as
+<alias>` chooses the local shorthand used with `--computer`. `--label <label>`
+sets this connecting client's persistent display label on the approval and
+approved-agent screens and defaults to this machine's hostname. The command
+selects the first profile automatically but preserves an existing default, so
+use `empty computer use <alias>` when the newly connected computer should
+replace that default.
+
+Use `empty --computer <alias> ...` to target a non-default profile. Use
+`empty computer add` only when the user intentionally supplies an existing SSH
+target; use `empty connect` for an EmptyOS computer URL. Profile removal is
+local client state; inspect `empty computer remove --help` before using it.
+
+## Discover the computer
+
+Start broad, then inspect the relevant object:
+
+```sh
+empty --json
+empty status --json
+empty things --json
+empty projects --json
+empty data --json
+empty changes --json
+empty commands --json
+empty hooks --json
+```
+
+`empty --json` is the compact whole-computer overview. `empty status --json`
+reports health. For focused inspection, use `empty thing describe <id> --json`,
+`empty thing logs <id> --json`, and `empty data describe <id> --json`.
+`empty commands --json` merges built-in commands with owner-authored commands
+installed on the selected computer.
+
+## Work with Things
+
+### Put a new Thing
+
+Put workstation content on the selected computer:
+
+```sh
+empty put <local-path> [--as <id>] [--name <display-name>] [--project <project-id>]
+```
+
+`put` accepts regular files, HTML pages, ready static directories, and clean
+manifested Thing repositories. For ordinary files and static sites, it
+generates the manifest and `./verify`; that check prevents import or later
+publication when the expected served file or build output is missing. Every
+manifested Thing, static or service, must provide a tracked executable
+`./verify` and may provide a tracked executable `./prepare`. Services require a
+manifest and are registered stopped. `--project` requires an existing Project
+and records membership in the initial commit.
+
+Treat a selected directory as the deployment boundary: inspect every file and
+prefer ready build output over a source repository root. EmptyOS does not scan
+for secrets. For a manifested import, the computer runs `./prepare` when
+present as trusted, unsandboxed owner code that may use the network, then runs
+`./verify` offline.
+
+### Clone and publish an existing Thing
+
+```sh
+empty clone <id>
+cd <id>
+# inspect, edit, run ./verify, and commit exactly one change
+empty put . --json
+```
+
+Treat the clone's Git-local EmptyOS binding as authoritative. Do not copy a
+checkout between computers, change its `emptyos.*` Git keys, push directly to
+the live branch, or bypass a stale-publish rejection. Fetch and rebase or
+squash onto the computer's current head, then publish again. Publication
+requires a clean checkout and exactly one verified, non-merge commit above the
+current computer head.
+
+### Inspect and control Things
+
+Use `empty thing describe <id> --json` before changing a Thing and
+`empty thing logs <id> --json` for bounded service logs. Control services through
+`empty thing start|stop|restart <id>` rather than raw process commands. Use
+`empty thing assign` and `empty thing unassign` for Project membership.
+
+`empty thing remove <id>` removes a service registration; it does not delete
+the Thing directory or associated Data. Do not treat it as content deletion.
+
+### Expose and unexpose Things
+
+Anonymous sharing is static-only. Before `empty expose <id>` or
+`empty put ... --public`, inspect every file in the declared document
+directory. Static sites and declared single files are eligible only when that
+directory is below the repository root; services and repository-root static
+Things are refused. Do not bypass a refusal by editing `visibility`.
+
+Use `empty unexpose <id>` as the immediate fail-safe to revoke anonymous
+access, including when the Thing has become invalid or otherwise ineligible.
+
+## Work with Projects
+
+Use `empty projects --json` to list Projects and
+`empty project create <id> <name...>` to create one. Use
+`empty thing assign|unassign` to change a Thing's membership.
+`empty put --project <id>` requires the Project to exist.
+
+Projects organize Things but do not change their routes, visibility, service
+identity, lifecycle, or Data associations.
+
+## Work with Data
+
+Use `empty data --json` to list registered Datasets and
+`empty data describe <id> --json` to inspect one. Use the live command
+inventory for supported Data operations rather than inventing commands or
+manifest fields.
+
+Never copy SQLite files between the workstation and computer. Keep canonical
+Data on the computer and change it only through a running Thing or an explicit
+supported computer command. Data stays outside Thing Git history, publication,
+and Undo.
+
+## Review changes and extend the computer
+
+### Status, history, and Undo
+
+Use `empty status --json` for computer health and `empty changes --json` for
+committed change records. Before `empty undo <change-id> --json`, inspect the
+exact change and confirm its target worktree is clean. Undo creates a new Git
+revert commit for one target and never changes Data.
+
+Supported mutations share the computer's mutation lock. If a command returns
+`computer-busy`, retry later instead of bypassing the lock through raw SSH or
+filesystem edits.
+
+### Commands and hooks
+
+Treat `empty commands --json` as the authoritative inventory of built-in and
+owner-authored commands. Treat `empty hooks --json` as the inventory of
+supported lifecycle events and installed hooks.
+
+`empty hook install <event> <path>` installs owner code from a path on the
+computer into the tracked platform hook directory and commits it. Inspect the
+source first. Use `empty ssh` when preparing that computer-side path; do not
+teach `put` or `clone` to install platform extensions implicitly.
+
+## Enter the computer
+
+Prefer transported `empty` commands when they cover the operation. Use
+`empty ssh` only for work that genuinely needs the resident environment;
+arguments after `--` have ordinary remote-shell semantics. Once there, read
+`~/EMPTY.md`. The installed computer contract, not this bootstrap, defines
+resident paths and capabilities.
+
+## Platform updates
+
+If a command reports that the selected computer lacks a required capability,
+inspect the platform update before retrying:
+
+```sh
+empty computer update --check --json
+empty computer update
+```
+
+The second command uses the selected profile's configured HTTPS release
+catalog when present, otherwise the official EmptyOS release catalog. Use
+`--catalog` only for an operator-selected catalog override, or `--release` for
+an immutable local artifact obtained through a trusted channel. Use
+`empty --computer <alias> computer update ...` for a non-default profile.
+
+If the owner reports that Home shows `An EmptyOS update needs your changes
+reconciled`, a signed operator update found overlapping resident changes and
+stopped before changing the installed platform. Inspect the exact official
+release first:
+
+```sh
+empty computer update --check --catalog https://release.emptyos.com/platform/v1/catalog.json --json
+```
+
+Apply only after the owner approves the inspected update. The Home advisory is
+local state, not a resident catalog poll. It remains until the resident update
+succeeds; a read-only check alone does not clear it.
+
+If apply returns `needs-reconciliation`, continue the retained transaction
+rather than starting another update. Read `retainedStage`, `conflicts`, and
+`nextCommand` from the JSON result. Enter the computer with `empty ssh`, read
+the stage's `RECONCILE.md`, and inspect the baseline, local, and incoming
+versions of every listed conflict. Edit only the detached `candidate` paths
+named by that contract; preserve the user's intent, do not edit `~/emptyos`,
+and do not commit or rebase the candidate. Run its complete test suite, then
+execute the exact `empty computer update --resume <stage-name>` command from
+the result. Resume rejects stale live state, edits outside the declared
+conflicts, changed deterministic paths, and validator failures. If a human
+encounters this state outside an agent session, tell them to continue the
+retained update from an agent instead of attempting a blind overwrite.

package/skills/emptyos-computer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EmptyOS Computer"
+  short_description: "Work safely with a personal EmptyOS computer"
+  default_prompt: "Use $emptyos-computer to inspect or change a Thing on my EmptyOS computer."