--- name: hermes-operate-studio description: Operate and change Hermes Studio safely through its authenticated MCP/API and GitHub workflow. Use when Codex needs to inspect or change the Hermes calendar, projects, checklists, email layouts, members, approvals, publishing worker, synchronization, frontend, API, deployments, or production behavior. --- # Operate Hermes Studio Keep code, collaborative data, and production deployment on their canonical paths. Never use a service-role key, direct database mutation, SSH, or Portainer for normal work. ## Connect Prefer the authenticated Streamable HTTP MCP at `https://socialmedia.janvalellam.com.br/api/mcp`. Configure the bearer from the current user's Hermes/Supabase session or from a narrowly scoped personal token beginning with `hms_live_`; never paste either credential into source files, prompts, or logs. Read [references/openapi.yaml](references/openapi.yaml) for exact HTTP schemas or [references/llms-full.txt](references/llms-full.txt) for a self-contained operation reference. Use the bundled CLI when an MCP client is unavailable: ```bash node scripts/hermes.mjs login node scripts/hermes.mjs whoami node scripts/hermes.mjs manifest ``` The CLI authenticates with a Supabase session and refreshes it automatically. Personal tokens are intended for direct HTTPS/MCP clients and are not written to the CLI session file. To install a verified current copy from the public manifest: ```bash node hermes.mjs skills install hermes-operate-studio ``` ## Route the request - Frontend/UI: use `trismegisto639/hermes-studio`, changing only `story-editor-project/`. - API, OAuth, media proxy, worker, migrations, CLI, MCP, or this skill: use `SiteupAgencia/hermes-publisher`. - Calendar/project/email/member/approval operation: use an explicit Hermes MCP tool or the authenticated API. - Read or explain requests do not authorize writes. Production is `https://socialmedia.janvalellam.com.br`. Routes under `/api`, `/oauth`, and `/media` belong to the publisher; all other pages belong to the static Studio. ## Operate safely 1. Read the exact resource immediately before mutation. 2. Verify the current member/capabilities with `hermes_whoami` or `node scripts/hermes.mjs whoami`. 3. Use only an explicit tool or documented endpoint. Never invent a generic HTTP, SQL, or filesystem operation. 4. Supply `api_revision` as `expected_revision` for event/project mutations and `updated_at` as `expected_updated_at` for email drafts. 5. Supply a unique `Idempotency-Key` for retryable writes. Reuse it only when retrying the exact same body. 6. On `409`, preserve the remote state, reread, and decide a field-safe operation. Never replay a stale full snapshot. 7. Confirm exact IDs before destructive or externally visible actions. ## Use individual API access - A Supabase Studio session uses capabilities exclusively from the member `access_level` role. `api_access_level` never limits or disables that session. - Only personal tokens use the separate `api_access_level` scale: `nenhum`, `leitor`, `criador`, `lider`, or `admin`. The Studio role is the maximum effective PAT level. - Create and manage personal tokens only from an interactive Supabase session through `/api/access/*`. A personal token can never mint, list, or revoke tokens. - Give each token the smallest useful scopes and a 1–90 day lifetime. The raw `hms_live_` value is displayed once; store it only in the client secret store. - The server stores only SHA-256 and recalculates each PAT's effective capabilities on every request. A PAT-level downgrade applies immediately; setting `nenhum` revokes active tokens without changing Studio-session permissions. - Administrators may change levels, revoke team tokens, and inspect sanitized audit events. Audit metadata excludes Authorization, raw tokens, hashes, request bodies, response bodies, and content. Use `GET /api/projects/{projectId}` plus `POST /api/projects/{projectId}/operations` for collaborative projects. Apply one semantic operation; never replace `payload` directly. Use `GET /api/email-drafts/{templateId}` plus CAS `PUT` for email layouts. Listing email drafts intentionally omits full HTML. ## Change code 1. Fetch `main` and create a branch. 2. Preserve unrelated worktree changes. 3. Make the smallest scoped change in the correct repository. 4. Add or update regression tests. 5. Frontend: validate HTML/inline scripts and cache versions. API: run `npm ci`, `npm test`, `npm run ai:check`, and the production Docker build in CI. 6. Open a PR to `main`, wait for required checks, and use squash merge. 7. Let the merge-to-main workflow deploy. Do not ask the user to upload files or run SSH commands. 8. Watch the deploy Action and verify `/api/health`, the AI manifest, and the affected operation before reporting completion. ## Preserve collaboration data - Treat revisions, timestamps, and idempotency keys as opaque concurrency controls. - Never clear browser caches as a substitute for fixing synchronization. - Never hardcode the legacy Supabase cloud project. Authentication and data use the self-hosted Hermes origin. - Never delete tasks, comments, authorship, or publishing history when offboarding a member. Use `DELETE /api/membros/{memberId}`, which revokes access and removes only current assignments. - Approval can publish externally. Inspect the exact event, provider, target, schedule, and media before approving. ## Handle destructive or external actions - Require explicit user intent before deleting, offboarding, approving, publishing, connecting accounts, changing permissions, or sending messages. - Resolve exact IDs with a read before mutation. - Report what changed and what was preserved. - If an API returns `207`, access was revoked but cleanup is incomplete. Report each retryable scope and retry the same endpoint rather than inventing manual cleanup. ## Protect secrets - Keep service-role keys, OAuth secrets, passwords, user JWTs, personal API tokens, and VPS credentials out of repositories and output. - Never print or commit `.env`, session files, Authorization headers, or GitHub tokens. - Send bearer tokens only to the canonical Hermes HTTPS origin.