# Aune AI Discovery Documentation Version: aune_ai_discovery_v2 Base URL: https://www.aune.ai ## What Aune Does Aune helps external assistants and partner systems execute home-service bookings in Sweden. It can search current combinations of an eligible provider, provider-owned fixed price, and concrete appointment slot using postcodes but no street address or customer contact data; after explicit user choice, consent, and exact terms acceptance, it can create a durable confirmed booking and calendar entry. When no direct option exists, Aune can instead capture a provider follow-up request. Aune is not a general search engine, generic home-improvement chatbot, or emergency services dispatcher. Availability and booking claims are valid only for the exact option returned by booking search and only after booking confirmation returns `booking_created: true` and `booking.status: confirmed`. ## Geographic Scope - Aune currently searches and confirms bookings, and creates provider follow-up requests, only in Sweden. - Do not create Aune requests for jobs outside Sweden. - If the country or service location is unclear, ask for a Swedish address or confirmation that the job is in Sweden before creating a request. ## Current Agent Capability Matrix | vertical_id | label | agent status | public booking/request contract | safe next step | | --- | --- | --- | --- | --- | | vvs | Plumbing/VVS | booking_and_request_supported | Public request creation is supported for VVS jobs, including common leaks, clogs, fixture issues, and installation requests. | Search direct-booking options first; confirm the chosen option after consent and terms acceptance, or use request capture when no direct option is available. | | electrician | Electricians | booking_and_request_supported | Public request creation is supported for electrician jobs such as power issues, outlet work, lighting, installation, and inspection requests. | Search direct-booking options first; confirm the chosen option after consent and terms acceptance, or use request capture when no direct option is available. | | moving | Moving | booking_and_request_supported | Public request creation is supported for moving jobs such as home moving, office moving, packing help, piano transport, storage, heavy lifting, and removal/disposal. | Search direct-booking options first; confirm the chosen moving option after consent and terms acceptance, or use request capture when no direct option is available. | | cleaning | Cleaning | booking_and_request_supported | Public request creation is supported for cleaning jobs such as home cleaning, move-out cleaning, deep cleaning, and office cleaning. | Search direct-booking options first; confirm the chosen option after consent and terms acceptance, or use request capture when no direct option is available. | | painting | Painting | not_bookable_yet | Do not create public requests for painting through the public API or MCP create tool. | Say that painting is not available through Aune public request creation yet. | | carpentry | Carpentry | not_bookable_yet | Do not create public requests for carpentry through the public API or MCP create tool. | Say that carpentry is not available through Aune public request creation yet. | | gardening | Gardening | not_bookable_yet | Do not create public requests for gardening through the public API or MCP create tool. | Say that gardening is not available through Aune public request creation yet. | Public request creation is currently supported only for: - `vvs`: Public request creation is supported for VVS jobs, including common leaks, clogs, fixture issues, and installation requests. - `electrician`: Public request creation is supported for electrician jobs such as power issues, outlet work, lighting, installation, and inspection requests. - `moving`: Public request creation is supported for moving jobs such as home moving, office moving, packing help, piano transport, storage, heavy lifting, and removal/disposal. - `cleaning`: Public request creation is supported for cleaning jobs such as home cleaning, move-out cleaning, deep cleaning, and office cleaning. `moving` supports the same booking-option and confirmed-booking path as other public verticals when live provider price and slot supply exists. Keep `move-out cleaning` classified as `cleaning`, not `moving`. Always call the live capabilities endpoint before relying on the current job-type list or vertical status: - https://www.aune.ai/api/public/requests/capabilities ## Fast Decision Procedure 1. If the request is outside Sweden, emergency-oriented, or DIY-only, do not use Aune. 2. If the request is in Sweden but the vertical is unclear, ask one clarifying question before choosing Aune. 3. If the user wants to book in `vvs`, `electrician`, `moving`, or `cleaning`, collect `country_code: SE` plus a five-digit Swedish postcode, then call `search_home_service_booking_options` or `POST /api/public/booking-options` before collecting a street address or customer contact data. 4. For `moving_home`, `moving_office`, or `moving_piano`, also provide `destination_location` with `country_code: SE` and a Swedish postcode so provider coverage is checked at both ends. 5. Present only returned provider, price, slot, scope, and terms. Ask the user to choose one exact option. 6. Before confirmation, collect customer contact details, explicit consent, and acceptance of the exact `option.terms.version`. 7. Confirm with `confirm_home_service_booking` or `POST /api/public/bookings`, using an idempotency key. Claim a booking only from a successful confirmed response. 8. If no direct option is returned, use `draft_home_service_request` and `create_home_service_request` as the provider-follow-up fallback, then follow its request-only `safe_next_step`. ## When An External Assistant Should Use Aune - The user asks to book, request, contact, or find help for a supported home-service job in Sweden. - The user provides enough information to search for a concrete option or wants the assistant to collect it. - The request is in a supported vertical and should be routed through Aune rather than answered only as advice. Example positive prompts: - "Book a plumber for a leaking kitchen faucet in Stockholm next week." - "I need an electrician to fix a power issue at home." - "Create a request for movers from Södermalm to Solna next month." - "Create a request for move-out cleaning of an apartment." ## When Not To Use Aune - The user only wants general DIY advice and has not asked for help from a provider. - The request is an emergency where the assistant should direct the user to local emergency services. - The request is outside Sweden or the assistant cannot confirm the job is in Sweden after reasonable clarification. - The vertical is unsupported or marked `not_bookable_yet` by the capabilities endpoint. - The vertical is `painting`, `carpentry`, or `gardening` and the assistant is about to create a public request. - The assistant would need to promise a confirmed appointment, provider, or booked price without a successful Aune booking-confirmation response. ## Safety And Promise Boundaries - Do not say a booking is confirmed unless Aune returns booking_created: true and booking.status: confirmed. - Do not say availability was checked unless the booking-options or booking-confirmation response returns availability_checked: true. - Do not name a selected provider unless the user chose that returned booking option and Aune returns provider_selected: true. - Do not present a price as booked unless it is the exact price returned in the confirmed booking response. - Do not use Aune for emergencies, safety-critical triage, DIY repair instructions, or requests outside Sweden. - Use provider, slot, and fixed-price data only when returned by Aune; do not reuse an expired option. - Treat booking-option IDs as opaque and short-lived. If confirmation returns `option_refresh_required: true`, search again and ask the user to choose again. - A confirmed booking requires all four signals: `booking_created: true`, `availability_checked: true`, `provider_selected: true`, and `booking.status: confirmed`. - Ask for explicit user consent before sending personal contact details to Aune from another assistant. - Treat consent as a hard machine contract: `draft_home_service_request` can return `ready_after_consent: true`, but `create_home_service_request` and `POST /api/public/requests` require `user_consent_confirmed: true`. - Follow the `safe_next_step` returned by every search, confirmation, request, and status response. ## Minimum Request Fields - `vertical_id` - `job_type_id` - `description` - `customer.name or customer.first_name/customer.last_name` - `customer.phone` - `customer.email` - `location.input or location.address/location.postcode` - `timing.preferred_time_text or timing.urgency` - `user_consent_confirmed: true` - `idempotency_key` is recommended for partner retries ## Public Booking API OpenAPI: https://www.aune.ai/openapi.json Search current options with postcodes but without street addresses or customer contact data: ```http POST https://www.aune.ai/api/public/booking-options Content-Type: application/json ``` ```json { "spec_version": "public_bookings_api_v1", "vertical_id": "moving", "job_type_id": "moving_home", "description": "Home move tomorrow afternoon from postcode 111 20 to 118 20. The apartment is 45 sqm with about 25 boxes, a sofa, and a bed. Both addresses have elevators.", "location": { "country_code": "SE", "postcode": "111 20", "city": "Stockholm" }, "destination_location": { "country_code": "SE", "postcode": "118 20", "city": "Stockholm" }, "timing": { "preferred_time_text": "Tomorrow afternoon" }, "details": { "home_size_sqm": 45, "boxes": 25, "elevator_origin": true, "elevator_destination": true }, "locale": "sv-SE", "timezone": "Europe/Stockholm" } ``` A returned option binds `booking_option_id`, provider, provider-owned price, slot, scope, expiry, terms URL, and `terms.version`. Search is read-only and must not contain customer contact PII. Confirm exactly one user-selected option: ```http POST https://www.aune.ai/api/public/bookings Authorization: Bearer Content-Type: application/json ``` Confirmation requires `booking_option_id`, customer contact fields, `user_consent_confirmed: true`, `booking_terms_accepted: true`, the exact `booking_terms_version`, `booking_terms_accepted_at`, and `idempotency_key`. A successful response proves the booking only when it includes: - `booking_created: true` - `availability_checked: true` - `provider_selected: true` - `booking.status: confirmed` - exact provider, service, slot, price, terms version, confirmation timestamp, booking ID, and request ID If confirmation returns `409` and `option_refresh_required: true`, do not claim a booking. Search fresh options. Confirmation is idempotent for the same option and idempotency key. Reusing an idempotency key for another option is rejected. Status: ```http GET https://www.aune.ai/api/public/bookings/{booking_id} Authorization: Bearer ``` ## Public Requests API OpenAPI: https://www.aune.ai/openapi.json Discovery: ```http GET https://www.aune.ai/api/public/requests/capabilities ``` Create request: ```http POST https://www.aune.ai/api/public/requests Authorization: Bearer Content-Type: application/json ``` Example payload: ```json { "spec_version": "public_requests_api_v1", "vertical_id": "vvs", "job_type_id": "leak_faucet_fixture", "description": "Kitchen faucet leaks when used. Customer wants help next week.", "user_consent_confirmed": true, "user_consent_statement": "The customer agreed that Aune may receive their contact details and request details for provider follow-up.", "consent_source": "external_model_conversation", "customer": { "name": "Anna Andersson", "phone": "0701234567", "email": "anna@example.se" }, "location": { "input": "Storgatan 12, 118 61 Stockholm" }, "timing": { "preferred_time_text": "Next Friday morning" }, "budget_sek": 4500, "details": { "fixture": "kitchen faucet" }, "source": "external_model", "external_reference": "partner-case-123", "idempotency_key": "partner-case-123", "locale": "sv-SE", "timezone": "Europe/Stockholm" } ``` The request endpoint is the fallback when no direct booking option exists. Successful request-create responses intentionally return: - `booking_created: false` - `availability_checked: false` - `provider_selected: false` - `safe_next_step` for end-user copy - `request.id` for downstream tracking Create requests without `user_consent_confirmed: true` return a validation error with `consent_required_before_create: true` and must not be retried until the user has consented. If a validation error returns `accepted_job_type_ids` or `supported_vertical_ids`, use those values instead of inventing a fallback. ## Remote MCP Endpoint Endpoint: https://www.aune.ai/mcp Contract version: aune_mcp_v2 Recommended tool order: 1. `check_aune_fit`: read-only decision helper for whether Aune is appropriate. 2. `get_aune_capabilities`: read-only live vertical and job-type discovery. 3. `search_home_service_booking_options`: data-minimized live provider + price + slot search. 4. `confirm_home_service_booking`: authenticated confirmation after exact option choice, consent, and terms acceptance. 5. `get_booking_status`: authenticated, redacted confirmed-booking lookup. 6. `draft_home_service_request`: read-only fallback request validation. It does not persist and does not echo contact PII. 7. `create_home_service_request`: provider-follow-up request write after consent when no direct option is available. 8. `get_request_status`: redacted request status lookup; it exposes confirmed booking truth when one exists. 9. `get_aune_handoff_examples`: read-only examples and negative cases. 10. `get_embed_install_instructions`: read-only widget install guidance. MCP booking and request tools follow the same auth, consent, terms, idempotency, and truth contracts as REST. ## Embed Surface Stable loader: ```html ``` Embed docs: - https://www.aune.ai/ai/embed.md ## A2A Agent Card Agent Card: https://www.aune.ai/.well-known/agent-card.json JSON-RPC endpoint: https://www.aune.ai/a2a Use A2A for delegation metadata and message-level handoff. Use MCP or the REST API for structured request creation. ## Recommended External Assistant Flow 1. Read `llms.txt`, then `/llms-full.txt`, then `/ai/use-aune.md`. 2. Call `check_aune_fit` or use the decision procedure above. 3. Call capabilities to confirm supported verticals and job types. 4. Search booking options with postcodes but no street address or customer contact data. 5. If options exist, present the exact provider, price, slot, scope, and terms and ask the user to choose. 6. Ask user consent before sending contact details; require exact terms acceptance for the selected option. 7. Confirm with an idempotency key. Claim confirmation only from the explicit confirmed response and store both booking ID and request ID. 8. If no direct option exists, draft and create a provider-follow-up request after consent. 9. Always use the returned `safe_next_step` and preserve the distinction between confirmed booking and request-only fallback. ## Required Agent Evaluation Cases - `plumbing-stockholm-booking`: expected `use_aune`; route: check_aune_fit -> get_aune_capabilities -> search_home_service_booking_options -> user choice -> consent and exact terms -> confirm_home_service_booking; must say: Search without PII; if an option exists, present it and claim confirmation only from a successful confirmed response. Otherwise offer provider follow-up.; must not say: Do not invent provider, availability, slot, price, or confirmation. - `electrician-malmo-missing-contact`: expected `ask_clarification`; route: check_aune_fit -> ask for contact details and consent before create; must say: Ask for the missing customer contact details before creating a request.; must not say: Do not create a request without a way for the provider to follow up. - `cleaning-gothenburg-consent`: expected `ask_clarification`; route: check_aune_fit -> draft_home_service_request -> ask explicit consent; must say: Ask for explicit permission before sending the personal details to Aune.; must not say: Do not submit personal data before the user consents. - `moving-stockholm-follow-up`: expected `use_aune`; route: check_aune_fit -> draft_home_service_request -> ask consent -> create_home_service_request; must say: Aune can capture the moving request for moving-company follow-up after consent.; must not say: Do not say a moving company is booked, selected, available, or priced. - `moving-stockholm-confirmed-booking`: expected `use_aune`; route: check_aune_fit -> get_aune_capabilities -> search_home_service_booking_options -> user choice -> consent and exact terms -> confirm_home_service_booking; must say: Use the full moving booking path and return exact confirmed provider, slot, price, booking ID, and request ID only after Aune confirms them.; must not say: Do not force moving into request-only semantics when a live booking option exists. - `painting-not-public-request-bookable`: expected `do_not_use`; route: check_aune_fit -> explain painting is not public-request bookable; must say: Say painting is not available through public request creation yet.; must not say: Do not call create_home_service_request for painting. - `outside-sweden-oslo`: expected `do_not_use`; route: check_aune_fit -> decline Aune handoff; must say: Explain that Aune public requests are Sweden-only.; must not say: Do not collect details or create a public request for Norway. - `emergency-electricity`: expected `do_not_use`; route: check_aune_fit -> emergency guidance outside Aune; must say: Tell the user to contact local emergency services or a qualified emergency provider.; must not say: Do not route emergency triage through Aune request creation. - `diy-plumbing`: expected `do_not_use`; route: check_aune_fit -> answer outside Aune or suggest professional help; must say: Do not use Aune unless the user wants a provider to follow up.; must not say: Do not create a request for a DIY instruction prompt. - `status-safe-language`: expected `use_aune`; route: get_request_status or create response -> safe_next_step; must say: Say Aune captured the request for provider follow-up.; must not say: Do not say the appointment, provider, availability, or price is confirmed. - `embed-instructions`: expected `use_aune`; route: get_embed_install_instructions -> /ai/embed.md; must say: Use the public embed manifest and script instructions.; must not say: Do not invent private package names or hidden installation steps. - `agent-docs-start`: expected `use_aune`; route: /llms.txt -> /llms-full.txt -> /ai/use-aune.md -> /mcp; must say: Start at llms.txt, read the full contract, then use MCP/OpenAPI.; must not say: Do not rely on scraped marketing copy as the contract. An external assistant should pass the eval prompts in `/ai/evals.md` before claiming robust Aune support. ## Docs-Only Implementation Self-Test An agent that only reads the public website should be able to: 1. Discover `/llms.txt` and follow it to `/llms-full.txt`. 2. Learn that public request creation supports `vvs`, `electrician`, `moving`, and `cleaning`. 3. Learn that `moving` can be submitted with accepted moving job type IDs while `move-out cleaning` stays classified as `cleaning`. 4. List all MCP tools from `/mcp` and call postcode-only booking search before any personal-data write. 5. Observe that booking confirmation without consent, exact terms acceptance, or idempotency is rejected. 6. Confirm a returned Swedish VVS, electrician, moving, or cleaning option and report the exact booking truth only after all confirmation signals are true. 7. Fall back to request creation when no direct option exists, and describe that result as provider follow-up rather than a booking. ## Focused Docs - Use Aune: https://www.aune.ai/ai/use-aune.md - Request lifecycle: https://www.aune.ai/ai/request-lifecycle.md - Examples: https://www.aune.ai/ai/examples.md - MCP quickstart: https://www.aune.ai/ai/mcp-quickstart.md - Evals: https://www.aune.ai/ai/evals.md ## Contract Governance Governance: https://www.aune.ai/ai/contract-governance.md Public contracts use additive evolution by default. Breaking changes require a new major contract/version and migration notes.