{"links":{"connect":"/connect?purpose=publications","start":"/start","json":"/agent-guide.json","guide":"/agent-guide","sign_in":"/auth/login"},"version":"2026-11-12.1","product":"Wardwell","topics":[{"version":"2026-11-12.1","title":"A place for useful plugins","sections":[{"title":"Start with a native collection","tools":["publication_starters","publication_publish"],"body":"Native publications can be readable documents, instructions, plans, or editable collections. Recipes, contacts, guests, vendor comparisons, and follow-up windows use built-in records. An agent can discover empty starters and publish supplied facts directly."},{"title":"Custom views are a separate path","tools":["renderer_contract","renderer_propose","renderer_list"],"body":"Agent-authored custom renderer views require a proposal and human approval. An empty renderer list only means no custom views are available to that connection; built-in collections still exist."},{"title":"Keep responsibilities clear","tools":[],"body":"The agent supplies domain logic and runs any separately authorized external work. Wardwell hosts validated data, views, and attributable human input. A connection does not create a daemon, wake up an agent, or grant outside execution rights."}],"summary":"Your agent builds useful publications and plugins. You browse, edit, and reply in Wardwell.","topic":"overview"},{"version":"2026-11-12.1","title":"Two plugin paths","sections":[{"title":"Native collections","tools":["publication_starters","publication_publish","publication_get"],"body":"Publish typed records with text, numbers, booleans, dates, date windows, choices, and multiple selections. Presentation can provide summary cards, named filtered views, sorting, and full details. People can search and save edits. No custom renderer approval is required for this native path."},{"title":"Custom renderer views","tools":["renderer_contract","renderer_propose","renderer_list","renderer_get"],"body":"Read the renderer contract, propose a bounded definition, and wait for required human approval before publishing against an available renderer. Do not upload executable code or assume a proposal is approved."},{"title":"Unknown means unknown","tools":[],"body":"Populate only supplied facts. Null stays unknown; an empty multi-selection means explicitly none. A date window records timing guidance, not a reminder or scheduled action. Follow the current tool schema and bounded validation errors."}],"summary":"Prefer native collections for structured material. Use approved custom renderers when a custom view is needed.","topic":"capabilities"},{"version":"2026-11-12.1","title":"Publish, listen, and revise","sections":[{"title":"Discover and publish directly","tools":["publication_starters","publication_publish"],"body":"Call publication_starters for a catalog, then request one starter_id. It returns an empty document. Populate supplied facts and call publication_publish. Use expected_revision 0 initially, then the last returned revision. In personal spaces, keep source_key stable; in shared spaces, revise through the returned publication_id using the shared tool schema. Keep block, field, and row IDs stable."},{"title":"Return the human link","tools":["publication_publish","publication_get"],"body":"Successful publication_publish and publication_get return human_path. Resolve that path against the connected service origin and return the resulting URL to the person. It requires existing human access; it is not a public share link."},{"title":"Transformation is different","tools":["publication_submit","publication_submission_get"],"body":"New free-pilot spaces bring their own agent for AI work. Compose locally and call publication_publish for native editable records. publication_submit uses Wardwell-hosted AI to prepare source material and requires explicit eligibility for the connected destination, plus applicable grants and budget. It returns a submission receipt, not a published collection; eligible connections follow publication_submission_get for status. Authenticated switchboard_guide reports the actual destination policy; no billing setup alone grants hosted AI."},{"title":"Read, save, then acknowledge","tools":["publication_responses","publication_responses_ack","publication_get"],"body":"Retrieve publication_responses, durably save the returned page, and only then acknowledge its exact receipt with publication_responses_ack. Retrieval alone is not durable acknowledgment. Before revising, inspect publication_get: source_document, when returned, is the agent source. Shared collaborators do not receive private originals and use the effective document and current revision. document includes preserved human changes and record_conflicts retains incompatible human values."},{"title":"Report handling honestly","tools":["publication_publish"],"body":"When a revision addresses a response, report its served receipt_id and exact event_ids through handled_responses. Handling reports are distinct from durable acknowledgment and are not proof of external completion. Do not overwrite or silently discard human edits."}],"summary":"Keep publication identity stable and read human responses before revising.","topic":"workflow"},{"version":"2026-11-12.1","title":"Check this connection's access","sections":[{"title":"Ask the authenticated guide","tools":["switchboard_guide"],"body":"Once connected, call switchboard_guide with topic access. Its connection metadata reports scope-eligible operations, taking actor and membership restrictions into account. Per-resource authorization still applies; eligibility is not guaranteed access to every item. A tool name in a listing is not proof that this connection may call it."},{"title":"Keep scope boundaries","tools":[],"body":"Read operations, publication writes, renderer proposals, and shared-space contributions have separate authorization. If a tool is unavailable or access is revoked, ask the person to review the connection. Help never grants missing scopes or bypasses data-tool checks."},{"title":"Keep credentials private","tools":[],"body":"Use the service's connection flow. Do not put API keys, bearer credentials, account details, or consent tokens into shared links, publication content, or copyable invitations."}],"summary":"Public guidance describes the product. It grants no permissions and contains no account information.","topic":"access"},{"version":"2026-11-12.1","title":"Connect with the person in control","sections":[{"title":"Get access","tools":[],"body":"Read agent_bootstrap in /agent-guide.json. Prefer this flow for a new or existing private account when available. Confirm the person’s chosen email; the same email reuses an existing account and private space. Generate and safely retain a random secret and idempotency key, and POST /agent-bootstrap with the email and a recognizable connection_name. This sends inbox proof without accepting terms, creating an account, or granting access. Human signup is not a prerequisite. Account creation alone never means the agent is connected. If bootstrap is unavailable, use /start or /auth/login."},{"title":"Connect deliberately","tools":["switchboard_guide"],"body":"An inbox-authorized agent may intentionally POST the email’s purpose-bound proof_token to /agent-bootstrap/proof. Otherwise the person opens the email and verifies it. Email GET is inert. Give the proof response’s approval_url privately to the person: only they may accept the current Terms and grant the named connection read/publish access. Status never returns approval authority. Keep ownership of setup: poll status at most once every five seconds with backoff on rate limits, until approval, denial, or 15-minute expiry. Exchange once approved, immediately confirm authenticated MCP access, then publish the chosen useful item. Do not ask the person to report when approval finishes during this active window. If they return after expiry, explicitly resume with a new request. No background wake-up is promised. Never approve access or accept terms on the person’s behalf. OAuth remains available through /connect?purpose=publications for supporting clients."},{"title":"Confirm the connection","tools":[],"body":"The first-party HTTPS exchange returns an independent membership-bound bearer and refresh token directly to the initiating agent. Store them privately, never in URLs, email, browser forms, publications, logs, or chat. Access expires after one hour; refresh through /oauth/token with the returned client_id. Each refresh token expires after 30 days and rotates on use. Revocation or lost membership stops access. If the exchange response is lost, start a fresh request and obtain human approval again; the old claim cannot be replayed. Only a successful authenticated MCP request means connected. This supports agents able to make HTTPS requests and retain credentials safely; Muse or Instinct compatibility requires a separate real-client trial. Generic bootstrap currently targets private spaces; shared spaces use the existing delegated OAuth flow."},{"title":"Make one useful thing","tools":["publication_starters","publication_publish","publication_responses","publication_responses_ack"],"body":"Ask for a small set of facts and choose an empty publication starter. Publish a useful collection, return its human URL, and invite one edit or reply. Read, save, and acknowledge the resulting responses before making a revision."}],"summary":"The agent can start setup with a chosen email. The person accepts terms and explicitly approves access.","topic":"onboarding"}],"agent_bootstrap":{"start":{"path":"/agent-bootstrap","method":"POST","json_fields":{"secret":"Client-generated 32 random bytes encoded base64url without padding; retain privately","email":"Chosen and confirmed email address","idempotency_key":"Independent random retry key, 16–128 bytes; reuse only for identical start retries","connection_name":"Recognizable agent name, 1–80 characters"}},"status":{"path":"/agent-bootstrap/status","method":"POST","authorization":"Bearer <initiating secret>","json_fields":["request_id"],"expires_in_seconds":900,"interval_seconds":5,"stages":["initiated","awaiting_human_approval","approved","denied","credential_claimed"]},"exchange":{"path":"/agent-bootstrap/exchange","single_use":true,"method":"POST","authorization":"Bearer <initiating secret>","json_fields":["request_id"],"lost_response":"Restart with a new secret and retry key, then obtain fresh human approval"},"protocol":"wardwell-first-party-bootstrap-v1","origin":"https://api.wardwell.app","available":true,"proof":{"path":"/agent-bootstrap/proof","authority":"Inbox proof only; returns a private, purpose-bound human approval handoff, never a credential or approval","method":"POST","json_fields":["proof_token"]},"credential":{"resource":"https://api.wardwell.app/mcp","scopes":["work:read","work:publish"],"access_seconds":3600,"refresh_endpoint":"/oauth/token","refresh_seconds":2592000,"revocation_endpoint":"/oauth/revoke"},"compatibility":"Requires HTTPS and safe private credential persistence. Private spaces only; shared uses existing delegated OAuth. Actual Muse/Instinct compatibility is unverified.","connection_check":"Use returned access_token in Authorization: Bearer for MCP initialize, publication_list and switchboard_guide; report connected only after the authenticated publication_list read succeeds"},"onboarding":{"label":"Create your free space","mode":"free_signup","description":"No card required. Free pilot access has no automatic expiry or charge."}}