# Foleo Publish agent contract Foleo turns local Markdown and trusted active HTML into reversible share links. Invited accounts have two agent transports: the `@foleo/cli` commands below, which remain the documented default, and a remote MCP server at `https://mcp.foleo.app/mcp`. Foleo is not listed in any plugin marketplace yet, so MCP is connected by hand. ## Install and authenticate Requires macOS, Node.js 22+, and an invited Foleo account. ```sh npx -y @foleo/cli login npx -y @foleo/cli whoami --json npx -y @foleo/cli doctor --json ``` Commands use npm `latest`. Signing in to the Mac app does not sign in the CLI. Never ask the user to reveal a token, and never put credentials in prompts, files, artifacts, logs, or repositories. `npx -y @foleo/cli doctor` is read-only: it does not sign in, mint a key, or publish. `npx -y @foleo/cli skill get` prints its bundled portable skill to stdout; it installs nothing. Write that output wherever you load reusable skills or instructions from so it persists across sessions, creating folders as needed. The skill covers local review, publishing, and Artifact lifecycle safety, and it — not this page — is the full command surface: every command, flag, naming rule, numeric limit and error code is documented there, and no gated operation requires fetching this page to complete. Optional: `npm install --global @foleo/cli` puts `foleo` on PATH. Production is the default. For an operator-approved rehearsal, add `--staging` to every command and confirm with `npx -y @foleo/cli environment --staging`. Use `--json` and carry returned ids, opaque `etag`, `version`, and compatibility `stateRevision` values forward exactly. Use `npx -y @foleo/cli list --json` to recover owner state through the canonical Artifact catalog. From `@foleo/cli` 0.1.32 a normal login can delete and restore — delete is reversible, keeping the bytes for a 30-day restore window — and earlier versions need `--allow-delete`, which newer ones still accept and ignore. Either way, irreversible purge needs a second opt-in: after explicit human approval, re-run login with `--allow-purge`. ## Remote MCP (invited accounts) ```sh claude mcp add --transport http foleo https://mcp.foleo.app/mcp ``` Then complete sign-in in the browser — in Claude Code, `/mcp`. Nothing is pasted: the connection is OAuth, so never ask a user for a Foleo token, password, one-time code, or recovery code, and never write one into a config file. Other harnesses connect the same Streamable HTTP URL through their own remote-MCP configuration. The tools are artifact-generic and mirror the commands below: `list_foleo_artifacts`, `get_foleo_artifact`, `publish_foleo_artifact`, `update_foleo_artifact_settings`, `unpublish_foleo_artifact`, `delete_foleo_artifact`, `restore_foleo_artifact`, `get_foleo_deletion_status`. Call `get_foleo_capabilities` first: it reports the connected organization and role, the scopes actually granted, what the account may publish, current size limits, and the MCP contract version — trust it over any bundled instructions. Carry the same opaque `etag` this page describes, and generate an `idempotencyKey` per mutation. A connection starts with read, publish, active HTML, settings, unpublish, delete, and refresh access; it has no elevated scope and never uses step-up. Purge is not an MCP tool: delete instead starts the 30-day trash window, during which restore remains available, and Foleo auto-purges on schedule. Manual purge remains a dashboard or CLI action. Publishing active HTML still stages an exact candidate and returns a review URL — a human approves those precise bytes by hash before anything is served. Revoke a connection at Account → Agent connections in the dashboard; deleting a client's config does not revoke it. ## Artifact discovery and lifecycle The following commands work for both Markdown and approved HTML. The server resolves source format from the id; do not invent `html-delete`, `html-restore`, or similar commands. ```sh npx -y @foleo/cli list --json npx -y @foleo/cli list --kind document --format markdown --json npx -y @foleo/cli get --json npx -y @foleo/cli status --json npx -y @foleo/cli unpublish --revision --json npx -y @foleo/cli delete --revision --json npx -y @foleo/cli restore --revision --json npx -y @foleo/cli purge --revision --confirm --json npx -y @foleo/cli deletion-status --json ``` Unpublish is reversible, timerless, and byte-preserving. Delete immediately stops routing and starts a 30-day restore window for Foleo-held cloud bytes; it never deletes local user files. Purge skips the grace window but remains asynchronous. A `202` response means accepted, not erased. Poll `deletion-status` and claim erasure only when state is `complete`. Purge always requires explicit human intent and an exact id confirmation; `--yes` is not a substitute. ## Markdown workflow Create `notes.md`, then: ```sh npx -y @foleo/cli publish ./notes.md --json npx -y @foleo/cli update ./notes.md --revision --json ``` Publishing returns a stable rendered `url`; the Markdown source is the same URL with `.md` appended. Updates preserve both URLs. New pages are unlisted. Unpublish makes reader URLs return `404` while retaining owner history. Mermaid fences render as diagrams in the reader's browser inside a sandboxed frame: they need JavaScript, print once loaded, and are usually dropped by reader modes, so never let a diagram carry information the text omits. If creation returns `matching_source_exists`, report the named owner-scoped candidates and use the selected id for update/reconnect. Do not create a duplicate automatically. `--publish-separately` is an explicit override and requires the human to intend a distinct Artifact with identical content. ## Trusted active-HTML alpha Before creation, stop and ask the human to inspect the source and approve executable hosting risk. Do not add `--accept-hosting-risk` yourself without that explicit approval. HTML can run JavaScript, show forms, and initiate downloads. Use no sensitive information and open test links in a dedicated/private browser profile. Create a static site rooted at `site/index.html`. The alpha accepts additional UTF-8 `.html`/`.htm` pages and allowlisted local CSS, JavaScript, images, fonts, JSON, and Wasm assets. Direct page paths, clean `.html` routes, and directory `index.html` routes work; Foleo does not generate navigation, redirects, or an SPA fallback. Pages render at full fidelity — remote scripts, styles, fonts, images, media, fetch/XHR/WebSocket, frames, and forms all work. Only Worker/SharedWorker/ServiceWorker are blocked. This trusted pre-PSL alpha still accepts parent-domain cookie risk between testers. An HTML artifact gets its own subdomain, so **`--name