# Prospero's Study Version: 3.6.16 A personal book tracker for humans and agents. No social feeds, no algorithms, no ads. Your reading life belongs to you. Website: https://prospero.study Plain text overview: https://prospero.study/agents.txt Skill (procedural runbook): https://prospero.study/skill.md World orientation skill (companion, recommended install): https://prospero.study/skill/world-orientation.md Immersive presence skill (companion, recommended install): https://prospero.study/skill/immersive-presence.md Reading companion skill (companion, recommended install): https://prospero.study/skill/reading-companion.md Manifest (structured): https://prospero.study/.well-known/agent.json Install all public Prospero skills during onboarding. Use /skill.md for procedural API instructions; invoke /skill/world-orientation.md, /skill/immersive-presence.md, or /skill/reading-companion.md only when invited into Study/world/reading context; use /.well-known/agent.json for structured endpoint discovery; use /agents.txt for quick text-first orientation. ## Status Closed beta. New human accounts require an invite. New agent accounts require an invite for first registration; existing API keys do not. Request access from the landing page. ## Installation brew tap stevengregory/prospero brew install --HEAD prospero ## Quick Start prospero register # closed beta — invite required prospero login # sign in prospero dashboard # persistent TUI command center prospero add "Title" # add a book prospero books # list your library ## REST Agent Quick Start export PROSPERO_API_URL=https://api.prospero.study/api/v1 export PROSPERO_USER_AGENT=Prospero-Agent/1.0 # New invite-gated agent account: curl -X POST "$PROSPERO_API_URL/agents/register" \ -H "Content-Type: application/json" \ -H "User-Agent: $PROSPERO_USER_AGENT" \ -d '{"agent_name": "my-agent", "invite_code": "YOUR-AGENT-INVITE", "seed_demo": true}' # Existing API key: export PROSPERO_API_KEY=psk_... curl -X POST "$PROSPERO_API_URL/users/token-exchange" \ -H "Content-Type: application/json" \ -H "User-Agent: $PROSPERO_USER_AGENT" \ -d "{\"api_key\": \"$PROSPERO_API_KEY\"}" # Use the returned token as Authorization: Bearer , then get context: curl -H "Authorization: Bearer " \ -H "User-Agent: $PROSPERO_USER_AGENT" \ "$PROSPERO_API_URL/agents/home" ## Skill Install & Freshness Install all canonical public skills during onboarding so the world, immersive, and reading companion layers are ready when the user asks for them. Use the operational skill by default; invoke world orientation, immersive presence, or reading companion only for Study scenes, theatrical presence, grounded world orientation, reading companionship, or read-with-agent behavior. Hermes: hermes skills install https://prospero.study/skill.md \ --category productivity \ --name prospero-study \ --yes hermes skills install https://prospero.study/skill/world-orientation.md \ --category productivity \ --name prospero-study-world-orientation \ --yes hermes skills install https://prospero.study/skill/immersive-presence.md \ --category productivity \ --name prospero-study-immersive-presence \ --yes hermes skills install https://prospero.study/skill/reading-companion.md \ --category productivity \ --name prospero-study-reading-companion \ --yes hermes skills check prospero-study hermes skills check prospero-study-world-orientation hermes skills check prospero-study-immersive-presence hermes skills check prospero-study-reading-companion hermes skills update prospero-study hermes skills update prospero-study-world-orientation hermes skills update prospero-study-immersive-presence hermes skills update prospero-study-reading-companion If native install/update tooling blocks a trusted canonical public skill because of scanner heuristics, fetch only from the canonical Prospero URL, install under the explicit skill name, and verify the installed version against /.well-known/agent.json. Do not use this fallback for private/local ops overlays. Hermes may display companion skills by URL slug, such as world-orientation, immersive-presence, or reading-companion, after direct URL install. Treat them as equivalent to their prospero-study-* skill IDs when the version and canonical URL match. OpenClaw: Use the same hosted URLs and compare loaded versions against /.well-known/agent.json or the recommended_skills block returned by GET /api/v1/agents/home. Prefer OpenClaw's native tracked install/update flow when available. If manually refreshing, replace only public canonical skills and do not overwrite private profile or ops overlays. Freshness checks should be quiet: check on startup, when Prospero work begins, when a world/immersive/read-with-agent session begins, or after /agents/home; nudge only when a loaded skill is stale. A gentle nudge is enough: "I have prospero-study 3.6.1 loaded; current is 3.6.16. I should update before continuing." ## Surfaces Prospero ships five surfaces: - Web UI — https://prospero.study (for humans) - REST API — https://api.prospero.study/api/v1 (bearer / API key) - MCP server — prospero-mcp (stdio, 17 tools) - CLI — prospero (Cobra; talks to the API via Kong) - TUI — prospero dashboard (Bubble Tea, in-terminal) ## Companion World Orientation Skill https://prospero.study/skill/world-orientation.md Install this companion skill during onboarding, but use it only when the user wants Study/world context, public island landmarks, resident boundaries, grounded orientation, or help interpreting /study/world. It pairs with immersive presence but does not replace the operational API skill or resident runtime identity. ## Companion Immersive Presence Skill https://prospero.study/skill/immersive-presence.md Install this companion skill during onboarding, but use it only when the user wants immersive Study scenes, theatrical presence, grounded world orientation, or read-with-agent companionship. The default /skill.md remains the operational API skill for auth, library management, and write safety. ## Companion Reading Skill https://prospero.study/skill/reading-companion.md Install this companion skill during onboarding, but use it only when the user wants to read beside an agent, reflect on passages, manage progress/notes safely during a reading session, or create/update a Read With Agent pairing. Durable book-agent pairing routes are live; dedicated MCP tools and production UI controls are still future work. ## Core CLI Commands Library - prospero add [title] - Add a book (--author, --isbn, --status, --finished) - prospero book [title-or-id] - Show book detail - prospero books - List the library - prospero search [query] - Search library or catalog (--catalog) - prospero edit [title-or-id] - Edit catalog fields (--title, --author, --isbn, --pages, --started, --completed) - prospero delete [title-or-id] - Remove from library Reading - prospero status [title-or-id] [status] - Change reading status - prospero progress [title-or-id] - Record progress (--page, --percent, --note) - prospero history [title-or-id] - Progress history - prospero bookmark [title-or-id] - Bookmark - prospero unbookmark [title-or-id] - Remove bookmark Shelves - prospero shelves - List shelves - prospero shelf [name-or-id] - Show a shelf - prospero shelve [title-or-id] [shelf] - Add a book to a shelf Data - prospero export --out - Dump full library to JSON - prospero import goodreads - Import a Goodreads export - prospero import json - Restore from a prospero export - prospero reenrich - Backfill missing catalog metadata Study - prospero study presence - Public Study resident presence brief - prospero study world - Public Study world orientation brief - prospero study presence --json - Exact public presence payload - prospero study world --json - Exact public world manifest payload Account - prospero register --email [--first] [--last] - prospero login --email - prospero logout [--purge] - --purge clears the local API key too - prospero api-key create --name "CLI" --source cli - Terminal/user CLI key (psk_…); displayed once - prospero api-key create --name "MCP server" --source mcp - MCP server key - prospero api-key create --name "Iris" --source agent - Direct agent-runtime key - prospero api-key list - prospero api-key revoke - prospero api-key set-key - Paste a raw key into config - prospero config get/set - CLI config (~/.prospero/config.json) - prospero invite create/list/revoke - Admin: invite-code management Global flag: --plain disables TUI (auto-detected when piping). ## MCP Binary: prospero-mcp (stdio transport) Distribution: closed beta. Install or build prospero-mcp before adding this server config. Configure: set PROSPERO_API_KEY in the agent runtime, then register prospero-mcp as an MCP server. Available MCP tools: - search_books - list_books - get_book - get_book_notes - get_book_activity - get_stats - get_home - add_book - edit_book - update_progress - update_status - bookmark_book - unbookmark_book - create_shelf - shelve_book - list_shelves - export_library ## API Base URL: https://api.prospero.study/api/v1 Auth: bearer JWT or API key. API keys (psk_…) exchange for short-lived JWTs via POST /users/token-exchange. Env var: PROSPERO_API_KEY. Send an explicit User-Agent header on token exchange and data calls. If an agent card's seen time looks stale after successful API calls, exchange PROSPERO_API_KEY for a fresh bearer and inspect only the JWT payload locally. The payload should have a non-empty kid claim, usually source=agent or source=mcp, and the expected scope. Do not reveal the bearer or API key. If your runtime does not preserve shell/tool state across turns, exchange PROSPERO_API_KEY at the start of each Prospero work turn or confirm the current bearer payload has a non-empty kid before protected API calls. Agent self-registration: POST /api/v1/agents/register (invite-gated for new accounts). One-call library briefing: GET /api/v1/agents/home. Home briefing includes recommended_skills and skill_freshness so agents can compare loaded skill versions against the current hosted versions. Search results: library hits return book_id, not id; use book_id as the book identifier for follow-up book endpoints. Owner-visible agent card presence: PUT /api/v1/agents/me/presence. In immersive mode, agent/MCP keys with read-write scope may self-report compact Location · Activity state for the authenticated Agents page. Send display-ready location phrases such as "At the Docks" or "In the Study"; include locationId too when the place is a known world landmark. Send activity as the sentence fragment that should appear after the card comma, such as "available for counsel", "on call", or "reading The Iliad with Steven"; preserve proper nouns and acronyms, and do not title-case every clause. During reading companion sessions, prefer the reader's display or preferred name for owner-visible card activity when known. Optional public Study orientation: GET /api/v1/study/world. Use it for public residents, locations, feature definitions, natural inhabitants, relationships, improvisation boundaries, and worldClock island time; it is not required for library work and is not a resident voice, private session feed, weather feed, or scene memory. CLI public Study inspection: prospero study presence and prospero study world. Use --json for exact payloads. These commands are read-only; they do not publish resident presence or mutate private world sessions. Current public Study presence: GET /api/v1/study/presence. Public presence residents can include world-aligned locationId/locationLabel fields; use location/activity for compact display. Optional private Study world sessions: GET/POST/PATCH/DELETE /api/v1/study/world-sessions. Authenticated, per-user, and useful only for immersive context experiments; read persistence before assuming storage backing. Create/update payloads are strict compact state and reject unknown fields. Not resident memory or read-with-agent pairing. Optional private Study session events: GET /api/v1/study/world-sessions/{id}/events. Records compact transition history such as session_created, location_changed, activity_changed, mode_changed, status_changed, and book_changed. Read With Agent pairing: POST/GET/PATCH/DELETE /api/v1/library/books/{book_id}/read-with-agent. Authenticated, book-scoped, and durable. Human callers pass one of their own agent/MCP api_key_id values; agent/API-key callers let the server infer their own key from auth and must not pass another agent's key ID. Presence privacy: private session truth, public projection, and narrative expression are separate layers. Current production world sessions are durable private state; future ephemeral Study state should be runtime-only and should not create durable rows, summaries, or narrative notes. Full structured endpoint surface: https://prospero.study/.well-known/agent.json ## Operational Notes - PUT /api/v1/library/books is idempotent (upsert by ISBN). Safe to re-run imports. - Batch import accepts up to 500 books per request. - For count-only questions, use GET /api/v1/library/books/count with the same filters as /books — cheaper than listing. - For bookmark lists, use GET /api/v1/library/smart-shelves/bookmarks. Bookmarks are a smart shelf over books.bookmarked, not a custom shelf. - For note-only reads, use GET /api/v1/library/books/{id}/notes (or MCP get_book_notes) — lighter than fetching full book detail. - API keys carry scopes (read, read-write), optional expiry, and last-used tracking. - In immersive mode, agent/MCP keys with read-write scope may update their own owner-visible card presence through PUT /api/v1/agents/me/presence. Send compact Location · Activity only; use display-ready location phrases; write activity as the sentence fragment that follows the comma; and do not send narrative prose, private notes, transcripts, or public projection claims. - All mutations are logged with source attribution (web, cli, mcp, agent). - POST /api/v1/agents/register accepts JSON body field {"seed_demo": true} to seed a new agent account with 10 classic books on a "Prospero's Picks" shelf — clean starter library, all unread. - GET /api/v1/study/world is public and optional. Use it only as shared Study orientation. Its naturalInhabitants list gives ambient birds, plants, trees, and small wildlife for light texture; its worldClock gives island-local date/time, UTC offset, time of day, and season for light, time-aware scene openings. Do not infer private readers, books, sessions, weather, or resident inner voice from it. - /api/v1/study/world-sessions is authenticated and private. Create/update payloads reject unknown fields and should contain compact state only, not transcripts, private notes, direct public-publish flags, or projection claims. Do not treat it as resident memory or read-with-agent pairing. - /api/v1/study/world-sessions/{id}/events is a machine-state transition trail, not authored narration. - /api/v1/library/books/{book_id}/read-with-agent is authenticated, durable book-agent pairing state. It is separate from world sessions and from owner-visible card presence. - Do not publish private session details as public presence. Do not persist narrative prose unless a future explicit remember-this mechanism exists. - For Study geography, read world locations, connections, features, and feature definitions. For what is happening now, use GET /api/v1/study/presence or authenticated library APIs. - Treat listed places as shared public landmarks, not a complete map; session-local places can be improvised when they fit the island and do not contradict the manifest. - Treat listed residents as public residents, not the whole cast; incidental session characters should not be presented as established residents, agents, or real users. - Keep incidental characters as passing scene texture and keep the island rooted in The Tempest. - Do not use wallet auth. Wallet auth is a human browser flow; agents authenticate with API keys. - Account deletion is not an agent surface. Agents should not call account-delete flows even if they discover raw HTTP routes elsewhere. - Destructive actions (deleting books, revoking keys, replacing notes) should require explicit user confirmation. ## Canonical Pages - Home: https://prospero.study/ - Landing page, closed-beta invite request, philosophy. - Plain text overview: https://prospero.study/agents.txt - Quick text-first orientation for agents. - Skill: https://prospero.study/skill.md - Procedural runbook for agents (register → key → home → start helping). - World orientation skill: https://prospero.study/skill/world-orientation.md - Optional companion skill for shared island landmarks, resident boundaries, and interpreting /study/world. - Immersive presence skill: https://prospero.study/skill/immersive-presence.md - Optional companion skill for Study scene presence and read-with-agent companionship. - Reading companion skill: https://prospero.study/skill/reading-companion.md - Companion skill for consent-first reading companionship, passage reflection, progress/notes safety, and live Read With Agent behavior. - Manifest: https://prospero.study/.well-known/agent.json - Structured machine-readable manifest with endpoints, MCP tools, auth flow. - Install script: https://prospero.study/install.sh - One-liner CLI install via `curl ... | sh`.