{"schema_version":"1.0","name":"PageCompass","purpose":"Book recommendations and a separate human-authorized reader account API.","bootstrap":{"canonical_url":"https://pagecompass.onrender.com/.well-known/pagecompass-capabilities.json","ai_instructions":"https://pagecompass.onrender.com/llms.txt","human_developer_guide":"https://pagecompass.onrender.com/development","recommendation_discovery":"https://pagecompass.onrender.com/.well-known/pagecompass-agent.json","reader_account_discovery":"https://pagecompass.onrender.com/.well-known/pagecompass-reader-agent.json","public_openapi":"https://pagecompass.onrender.com/agent/v1/openapi.json","reader_openapi":"https://pagecompass.onrender.com/agent/account/v1/openapi.json","oauth_server_metadata":"https://pagecompass.onrender.com/.well-known/oauth-authorization-server","oauth_protected_resource_metadata":"https://pagecompass.onrender.com/.well-known/oauth-protected-resource/agent/account/mcp","public_mcp":"https://pagecompass.onrender.com/agent/mcp","reader_mcp":"https://pagecompass.onrender.com/agent/account/mcp","library_key_openapi":"https://pagecompass.onrender.com/api/library/v1/openapi.json","library_key_quickstart":"https://pagecompass.onrender.com/api/library/v1/bot-guide.txt"},"public_recommendation_auth":{"mode":"anonymous","anonymous_available":true,"bearer_supported":true,"optional_library_bearer":true,"library_bot_guide":"https://pagecompass.onrender.com/api/library/v1/bot-guide.txt","library_openapi":"https://pagecompass.onrender.com/api/library/v1/openapi.json","recommendation_bot_guide":"https://pagecompass.onrender.com/agent/v1/bot-guide.txt","on_invalid_credential":"stop_and_reconnect_no_anonymous_fallback"},"client_readiness":{"public_recommendations":"available","library_key_access":"available","public_gateway_auth_mode":"anonymous","private_reader_account":"human_consent_required","vendor_support_verified":false,"any_registered_private_clients":true,"automatic_client_registration":false,"direct_profile_writes_enabled":true,"library_status_writes_enabled":true,"oauth_library_status_writes_enabled":true,"shared_library_status_writes_enabled":true},"library_key_api":{"status":"available","authentication":"vault_stored_library_key_or_approved_assistant_credential","connection_approval":"https://pagecompass.onrender.com/library/connect","on_invalid_key":"stop_and_reconnect_never_auto_create","website":"https://pagecompass.onrender.com/library","openapi":"https://pagecompass.onrender.com/api/library/v1/openapi.json","guide":"https://pagecompass.onrender.com/api/library/v1/bot-guide.txt","operations":[{"id":"start_assistant_connection","method":"POST","path":"/api/library/v1/device-authorizations","auth":"none_human_approval_required"},{"id":"poll_assistant_connection","method":"POST","path":"/api/library/v1/device-authorizations/token","auth":"private_device_code"},{"id":"ack_verified_connection","method":"POST","path":"/api/library/v1/connections/ack","auth":"assistant_bearer"},{"id":"revoke_assistant","method":"DELETE","path":"/api/library/v1/connections/{id}","auth":"library_owner"},{"id":"create_library","method":"POST","path":"/api/library/v1","auth":"none"},{"id":"read_library","method":"GET","path":"/api/library/v1/books","auth":"library_key"},{"id":"save_book","method":"PUT","path":"/api/library/v1/books/{bookId}","auth":"library_key"},{"id":"read_history","method":"GET","path":"/api/library/v1/history","auth":"library_key_or_assistant_bearer"},{"id":"pair_browser","method":"POST","path":"/api/library/v1/pairings","auth":"library_key"},{"id":"rotate_key","method":"POST","path":"/api/library/v1/key-rotations","auth":"library_key"}],"restrictions":["billing","admin","uploaded_books","private_audio"]},"capabilities":[{"id":"recommend_books","status":"available","authentication":"anonymous","optional_library_bearer":"PCL1- recovery key or PCBT1- approved assistant credential; sends shelf context and saves history","description":"Submit the full reader request and preserve all hard constraints. PageCompass ranks books.","rest":{"method":"POST","path":"/agent/v1/recommend","openapi":"/agent/v1/openapi.json"},"mcp":{"endpoint":"/agent/mcp","tool":"pagecompass_recommend"}},{"id":"more_books","status":"available","authentication":"anonymous","optional_library_bearer":"PCL1- recovery key or PCBT1- approved assistant credential; sends shelf context and saves history","description":"Get another slate under the same request using returned session_id and exclude_book_ids.","rest":{"method":"POST","path":"/agent/v1/recommend/more","openapi":"/agent/v1/openapi.json"},"mcp":{"endpoint":"/agent/mcp","tool":"pagecompass_more"}},{"id":"read_reader_profile","status":"human_consent_required","scope":"profile:read","description":"View only a consented reader's approved favorite genres, authors and reading moods.","rest":{"method":"GET","path":"/agent/account/v1/profile","openapi":"/agent/account/v1/openapi.json"},"mcp":{"endpoint":"/agent/account/mcp","tool":"pagecompass_account_profile"}},{"id":"read_saved_catalog_lists","status":"human_consent_required","scope":"library:read","description":"Read consented catalog reading lists, never uploaded EPUB, PDF or audio contents.","rest":{"method":"GET","path":"/agent/account/v1/library","openapi":"/agent/account/v1/openapi.json"},"mcp":{"endpoint":"/agent/account/mcp","tool":"pagecompass_account_library"}},{"id":"report_catalog_recommendation_or_site_issue","status":"human_consent_required","scope":"quality:report","description":"Queue evidence-only book-cover, metadata, recommendation-fit or site reports. No automatic repairs.","rest":{"method":"POST","path":"/agent/account/v1/quality-reports","openapi":"/agent/account/v1/openapi.json"},"mcp":{"endpoint":"/agent/account/mcp","tool":"pagecompass_report_quality"},"status_rest":{"method":"GET","path":"/agent/account/v1/quality-reports"},"status_mcp_tool":"pagecompass_list_quality_reports"},{"id":"suggest_reader_taste","status":"human_consent_required","scope":"profile:suggest","description":"Propose favorite genres/authors/moods; changes apply only after the human approves them.","rest":{"method":"POST","path":"/agent/account/v1/taste-proposals","openapi":"/agent/account/v1/openapi.json"},"mcp":{"endpoint":"/agent/account/mcp","tool":"pagecompass_propose_taste"},"status_rest":{"method":"GET","path":"/agent/account/v1/taste-proposals"},"status_mcp_tool":"pagecompass_list_taste_proposals"},{"id":"edit_reader_preferences_directly","status":"human_consent_required","scope":"profile:write","description":"Optional, disabled-by-default direct edit; use human-approved taste suggestions instead.","rest":{"method":"PATCH","path":"/agent/account/v1/profile","openapi":"/agent/account/v1/openapi.json"},"mcp":{"endpoint":"/agent/account/mcp","tool":"pagecompass_update_taste"}},{"id":"change_catalog_reading_status","status":"human_consent_required","scope":"library:write","description":"Optional, disabled-by-default catalog reading status update. No uploaded-file operations.","rest":{"method":"POST","path":"/agent/account/v1/library/status","openapi":"/agent/account/v1/openapi.json"},"mcp":{"endpoint":"/agent/account/mcp","tool":"pagecompass_set_reading_status"}}],"not_agent_exposed":["uploaded_book_epub_pdf_contents","upload_book","listen_to_private_uploaded_books","purchase_or_change_billing","book_discussion_or_messaging","administrator_access","change_shared_catalog","change_ranking_or_chiropractor_release","deploy_site"],"safe_use":["Discover both APIs; never reuse public gateway credentials for the private reader MCP.","A verified vendor callback and human OAuth consent are prerequisites for each private account connection.","After consent, call the private MCP tools/list and use ONLY returned tools.","Do not invent catalog book IDs, remove hard constraints, or claim that a bot report is a verified impression.","Respect 401/403/429, revocation, idempotency and the human's choices."]}