# SilverFerret — tools for an owner's agent

SilverFerret is a comic-reading and authoring platform. Accounts own series; series contain episodes; episodes contain pages and cuts. Studio edits story notebooks, panel layouts, imported art, speech balloons, sound effects and watermarks. New episodes have eight B6 pages (3024 × 4299 px). Image generation and AI retouch are not connected.

Visual guide: https://silverferret.com/guidelines-for-ai-assistants
Start here: https://silverferret.com/agents.json
Complete record schema: https://silverferret.com/agents/schema.json
MCP (Streamable HTTP): https://api.silverferret.com/mcp
REST tools: https://api.silverferret.com/api/agent/call
Tool definitions: https://api.silverferret.com/api/agent/tools

When an owner gives you this URL, discover the tools and ask what they want done if no task was supplied. For a supplied task, proceed within it. Read the owner's current records, prepare changes, preview, save and verify. Keep their existing wording and stable IDs. Demonstrations belong in an explicitly named test series or Office experiment.

Authentication: use the owner's username/passcode with POST /api/auth/login. Send Content-Type: application/json, Origin: http://localhost:7837 and X-SilverFerret: 1. JSON body: {"username":"OWNER","passcode":"PASSCODE"}. The response contains a bearer token. Keep it private in process memory; never put credentials in URLs, logs or saved work. Browser sign-in alone does not authenticate a terminal agent. Logout with POST /api/auth/logout using the same headers and token.

REST: POST /api/agent/call with those headers plus Authorization: Bearer TOKEN; body {"name":"studio_list","arguments":{}}. Public library reads and discovery work without a token. Tools use the signed-in account's permissions and personal history/notes.

Editing flow: studio_list → studio_page or studio_records → studio_plan → studio_preview → studio_patch → studio_page. studio_plan accepts create_series, create_episode or edit_page and returns the exact patch and generated IDs. edit_page commands split_panel/add_row/move_edge/set_gutters/add_text/set_text/update_lettering/remove_lettering use the same models as Studio. Add text with panelId (or zero-based panelIndex), frame {x,y,width,height}, balloonStyle and optional tailTip. Geometry is normalized to its page or panel anchor. Reuse the returned patch and operationId on retries. A 409 conflict means fetch current records and re-plan with a new operationId. Full AgentPatch editing covers every schema record, including structured references and artwork placements.

MCP clients: configure the endpoint with Authorization: Bearer TOKEN. Initialize, then tools/list and tools/call. JSON responses; no SSE stream or MCP session ID. Existing owner sessions expire after 30 days. No paid API, authentication or database service is added.

Reading: library_list returns public episode/image URLs. reading_visit marks read; reading_history lists this account's recent episodes. episode_social provides comments, reactions and personal notes. Theme/language/text size remain browser preferences in Settings.