# Refert — Agent Guide Give this file to any AI coding agent (Claude Code, Cursor, Windsurf, etc.). The agent does the setup and the deployments; a non-technical person only approves. All commands in this guide are for the agent to run — the user never needs to touch a terminal. Refert is a cloud for small software: tools with a handful of users, built by an agent and shared with colleagues like a Google Doc. A tool goes from prompt → live URL in one publish command. Access is per-person ("Use" or "Edit"), and everything an agent publishes is visible to the org in a catalog with a kill switch. --- ## 1. Install the CLI npm install -g @refert/cli Verify the install (v0.3.0+ has all commands in this guide): refert --help refert --version Windows is fully supported. When spawning the CLI from scripts or other processes, call `refert.cmd` or wrap the command with `cmd /c refert ...` — the npm shim is a batch file, not an .exe, so direct process spawns (e.g. PowerShell's `Start-Process refert`) fail to resolve it. ## 2. Sign in once — browser authorization refert login The command opens the user's browser to the platform's device-authorization page (the address this guide was served from). The user signs in with Google and allows the device; the platform issues a scoped publish key directly to the CLI, which stores it on this machine. The key is never displayed. Rules for agents: - Never ask the user for an API key. Never paste a key into a prompt, an MCP config, a `.env`, or a code file. - If a command returns 401, run `refert login` again — do not work around it. - If the user asks "where's the key?": it is stored by the CLI on this machine and revocable on the platform's Settings page. - `refert logout` removes the stored credential; `refert whoami` verifies it. For CI, keys are also available on Settings and can be passed with `--key` / the `REFERT_KEY` env var; `--url` / `REFERT_URL` override the platform address. The MCP server reads the CLI login automatically. ## 3. Install the MCP extension The MCP server ships on npm as `@refert/mcp` (bin `refert-mcp`). It reuses the CLI login from step 2 — no key handling at all. Register it (the client's MCP settings, not a chat or a tool, holds the command): # Claude Code (macOS/Linux) claude mcp add refert -- npx -y @refert/mcp # Claude Code on native Windows — npx needs the cmd /c wrapper claude mcp add refert -- cmd /c npx -y @refert/mcp # Cursor / other MCP clients: same command via the client's MCP settings. Credentials resolve per request from `REFERT_KEY` / `REFERT_URL` if set, otherwise from the CLI login on this machine (`~/.refert/config.json`) — so `refert login` is the only setup step. Plain `http://` is allowed only for localhost URLs; any other host must use `https://`. What the agent gains: | MCP tool | What it does | |---|---| | `refert_whoami` | Confirms which user, org, and key the server acts as — call it first | | `refert_publish` | Publishes a tool folder → returns the live URL and version | | `refert_list_tools` | Lists the org's tools (slug, name, status, version, last active) | | `refert_logs` | Reads a tool's activity log so the agent can self-debug | | `refert_rollback` | Reverts a tool to a previous version | | `refert_preview` | Mints a 15-minute curl-able URL that renders a tool without a session | If MCP is not available, the CLI alone is sufficient — every MCP tool has a CLI equivalent. ## 4. The tool contract A tool is a plain folder. Keep it self-contained — no build step, no bundler. my-tool/ tool.json # required manifest index.html # required UI (may reference declared sibling files) style.css # optional, declare it in files and it is served in production main.js # optional server functions (server-side only, never served to the page) `tool.json`: { "name": "Renewal Pricing Calculator", "slug": "pricing-calc", "description": "Compute renewal pricing for a deal", "files": { "index.html": "index.html", "main.js": "main.js" } } **Rules:** - `slug`: lowercase letters, digits, hyphens. The run URL is `/run/{slug}` — session-gated for org members only. Any published version previews at `/run/{slug}?v=N` (server functions run that same version there). - `index.html` must work standalone (openable as a file). Use the platform bridge when present, degrade gracefully when not: - `SC.whoami()` — the current viewer - `SC.getData(key)` / `SC.setData(key, value)` — per-tool persistent storage (256 KB max per value) - `SC.call(fn, input)` — invoke a `main.js` server function - Bridge semantics: every `window.SC` method is **async** and always returns a Promise. `SC.whoami()` → `{ ok, user, org }`; `SC.getData(key)` → `{ ok, value }` (value is null for unset keys); `SC.setData(key, value)` → `{ ok }` (values over 256 KB fail); `SC.call(fn, input)` → `{ ok, result }` or `{ ok: false, error }`. Await each call exactly once — never `.then()`-chain a second one. Inside `main.js`, the `sc` second argument is also async but returns raw values: `sc.getData(key)` → the value, `sc.setData(key, value)` → throws on failure, `sc.whoami()` → `{ tool }`. - Multi-file tools: every file declared in `files` is served in production at the same relative path it has locally — `index.html` can reference `style.css` or `app.js` exactly as it does when opened as a file. `refert serve` reproduces this, so if it works locally it works deployed. - Client error reporting: failed asset loads, uncaught exceptions, and unhandled rejections on the run page are reported to the activity log automatically (`refert logs `, Activity tab). - `main.js` (optional) exports plain async functions: `exports.renewalPrice = (input) => {...}`. Runtime limits: 3s load, 10s per call, 256 KB values. No `require`, `process`, `fetch`, timers, or environment access — denied by construction. - No external API keys, no CDNs beyond fonts, no tracking. A tool that wouldn't be safe to run inside the user's company is not an Refert tool. **Platform features — never rebuild these.** A tool is just its page and its server functions. Everything else around it ships with the platform, so when a prompt asks for these, the answer is configuration or the bridge — never new code inside the tool: | If the user asks for… | The platform already provides | What the agent does | |---|---|---| | "Login, accounts, only my team can open it" | Google sign-in, org membership by email domain, session-gated run URLs | Nothing in tool code — access is a sharing concern | | "Share it with so-and-so / read-only access" | Per-person Use/Edit access: tool page → Sharing tab | Tell the user how to share; no user tables, no password screens | | "Who is viewing this" | `SC.whoami()` returns the signed-in viewer on the run page | Display it; don't build accounts | | "Remember this / save state" | `SC.getData` / `SC.setData` per-tool storage | Use the bridge; no database, no backend | | "Keep the logic off the page" | `main.js` server functions via `SC.call` | Put the logic in main.js | | "Version history / undo" | Every publish is an immutable version; `refert diff`, `refert rollback`, `/run/{slug}?v=N` previews | Iterate by publishing; never build versioning into the tool | | "Turn it off in an emergency" | Kill switch: Catalog → Control → Disable | Surface the control; don't add one to the page | | "Who changed what" | Per-tool audit log (Activity tab, `refert logs`) | Read it; don't build logging | | "Back up my data" | `refert export `; Control → Export data | Tell the user; no external sync in tool code | | "Scheduled jobs / background tasks / webhooks" | Not part of a tool: 10s call limit, no timers, no network | Say so plainly; it is outside what a tool is | If a prompt mentions auth, teams, permissions, or history, the correct response is sharing and versioning configuration — not tool code. ## 5. Create a deployment skill After setup, create a reusable skill so future sessions deploy without re-reading this guide. Create `refert-deploy/SKILL.md` with the template below (adjust to your agent's skill conventions — Claude Code: drop it in `.claude/skills/` or the user's skills directory): ``` --- name: refert-deploy description: Build and publish internal tools to Refert. Use when the user wants a small internal tool — calculator, form, tracker, dashboard, status page — deployed where their team can use it. Covers setup (CLI + MCP), scaffolding, publishing, verification, and iteration. --- # Refert Deploy ## When to use - The user wants an internal tool for a small team (roughly 2–20 users). - Prompts like "make a tool for X", "put this on refert", "ship this to the team". ## When NOT to use - Public-facing products, custom domains, user accounts, high traffic → normal hosting, not Refert. - Background jobs, queues, heavy compute (limits: 3s load / 10s call / 256 KB values). ## Platform features — never rebuild them in tool code - Accounts, sign-in, orgs, per-person sharing (Use/Edit), session-gated run URLs — access is sharing configuration, never tool code. No login screens, no user tables. - `SC.whoami()` = the signed-in viewer; `SC.getData`/`SC.setData` = per-tool storage; `SC.call` = server functions. All async. - Versioning, rollback, diff, preview URLs, audit log, kill switch, data export — all built in. - If a prompt asks for auth, teams, permissions, or history: map it to sharing and versioning instead of building it. ## Tool contract (complete — no other reference needed) A tool is a plain folder: `tool.json` plus the files it declares. `index.html` is the UI; an optional `main.js` holds server functions. { "name": "Team Kanban Board", "slug": "team-kanban", "description": "One line, shown in the catalog", "files": { "index.html": "index.html", "style.css": "style.css", "main.js": "main.js" } } - `files` maps the name the platform serves → the file on disk. Every declared file is served in production, so relative references in `index.html` (``, `