# Assist With Buying AI setup

Guide version: 2026-09-05-shopping-trips-v1
Human page: https://assistwithbuying.com/ai
Manage access: https://assistwithbuying.com/settings/ai
Full agent contract: https://assistwithbuying.com/llms-full.txt
MCP endpoint: https://assistwithbuying.com/mcp
First-party upload origin: https://assistwithbuying.com
First-party upload path: /api/ai/uploads/{capability}

Assist With Buying is the person's private durable purchase-research,
comparison, decision, and follow-through workspace. Their chosen AI searches,
reasons, and synthesizes; Buying stores Missions, options, products, dated
observations, source outcomes, comparisons, decisions, and Queue handoffs.

## Field conventions — read this first

One house style across every tool, so you can guess a field name and be right. Each
tool description repeats it, so an agent that opens any single entry learns it there.

- Free text: a general remark goes in `note`. Purpose-named text fields keep their own
  names — rationale, summary, answer, question, trigger, headline, excerpt, claim — and
  `note` is for the remark that has no better name.
- Times: epoch milliseconds, in a field named for what happened and ending `At` —
  observedAt, checkedAt, accessedAt, decidedAt, openedAt, capturedAt, askedAt, nextAt.
  Never a date string, never a bare `at`, never `observedOn`. One published exception,
  on a comparison cell and a product attribute: `asOf`, which means the same thing.
- Replay keys: every write carries a top-level `operationId` — a lowercase stable key
  of at least 8 characters. Resend a failed call with its ORIGINAL operationId and it
  replays rather than writing twice. One published exception: awb_manage_connection
  also still accepts the older spelling `opId` and honours either.
- Money: integer cents in an `...Cents` field plus an explicit three-letter currency.
  Never floats, never two currencies in one range.
- Unknown keys are refused BY NAME. Every schema is strict, so a wrong guess comes back
  as an input-validation refusal listing the unrecognized keys and any required ones you
  missed. That refusal is the correction — read it and re-send, rather than retrying the
  same shape or reporting a broken tool.

Connection rules:
- Add the remote Streamable HTTP MCP endpoint above and complete OAuth in the person's browser.
- Do not ask for an AWB API key, OAuth secret, password, user id, or workspace id.
- Anonymous requests receive a real OAuth resource challenge. Buying derives identity server-side from a verified Clerk access token on every request. JWT signatures, issuer, expiry, and OAuth access-token shape are checked; an omitted audience is accepted, and a present audience must exactly match Buying. Existing opaque Clerk tokens are verified by Clerk's issuer-hosted userinfo endpoint.
- The protected-resource document is served identically at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp, because real clients disagree about which to request. Both return the same single canonical resource URL.
- Modern MCP is stateless. Older Streamable HTTP tool-list/call requests remain compatible without a durable server session.
- Send one JSON-RPC request per call. Batched arrays are refused, because a batch cannot be checked against the person's grant as a single call.
- If tools are missing or stale, disconnect and reconnect the connector.

## Authorization: signing in is the approval, and the grant decides the rest

Signing in to Assist With Buying and allowing your client IS the approval. There
is no second screen the person must find afterwards. On your first authenticated
call, Buying records the connection and grants it the ordinary toolset for
30 days. /settings/ai is the dial the person turns after
that — to widen, narrow, extend, or revoke — not a gate they have to pass first.

The token still only proves WHO is calling. The stored grant decides WHAT, it is
re-read on every single call, and your token's own scopes are never read.

Granted by signing in:
- mission.read
- mission.write
- queue.read
- queue.write
- media.read
- media.write
- places.read
- places.contribute

NEVER GRANTED THAT WAY: nothing. Since 2026-09-01 every permission in this
vocabulary is granted by signing in.

THAT LIST IS EMPTY, and reading it as a mistake is the misreading to avoid. The
product owner's rule is that a connected AI has all of its abilities from the
moment the person signs in; a person may opt into MORE restriction, never into
capability. So do not send anybody to a permission screen to make ordinary work
possible, and do not describe a capability here as locked.

"places.contribute" was the last permission outside that rule and joined the
defaults on 2026-09-01. The argument it had was real — a contribution lands in a
shared public directory strangers read, and nothing in this product deletes
anything — and it is answered by the shape of the write rather than by a
permission screen: the note is privacy-scrubbed, it carries no link back to the
person's Missions, and you can withdraw one you contributed.

"media.write" joined on 2026-08-29 for its own reason: this is an app for
photographing things at sales, and the assistant writing the Appraisal is the one
holding the picture of what it appraised, so splitting those across permission
tiers broke the ordinary act the product exists for. The care is enforced in the
tool rather than the tier — one photograph per call, EXIF location stripped on
ingest, a hard byte ceiling, the bytes re-read and hashed server-side, and the
file private and filed as attached by you.

What is NOT affected by any of this, and never has been: the acts no approval
this product can issue will ever allow. Those are listed further down, they are
ceilings rather than permissions, and no request, grant, or ruling reaches them.

If the person has narrowed this connection, you hold less than the list above,
and that is their decision and not a fault to route around. A connection issued
under an older starting policy and never narrowed is raised to the current
default automatically on its next call — so a permission you lacked yesterday may
simply be present today, with a line in the person's ledger saying why.

The standing rules, derived from the same constants the server enforces so this
guide cannot disagree with it:
- Signing in through OAuth and allowing the client is the approval. From that moment the connection holds mission.read, mission.write, queue.read, queue.write, media.read, media.write, places.read, places.contribute for 30 days. Buying issues and receipts that authority separately from OAuth identity.
- That baseline is the "ordinary-research" policy, version 3, decided 2026-09-01. Every grant records which policy issued it. A connection issued under an older version and never narrowed by the person is widened to the current default on its next call, and the ledger entry names both versions.
- Nothing is withheld pending a request: every permission in this vocabulary is granted by signing in. /settings/ai is where the person narrows a connection or revokes it if they want less, never where they go to unlock ordinary use.
- Attaching a photograph writes stored bytes rather than sentences, and "media.write" is nevertheless granted by signing in: this is a product for photographing things at sales, and the assistant that writes an Appraisal is the one holding the picture of what it appraised. The care that decision needs is in the tool rather than in the tier. A photograph an assistant attaches is filed as attached by that assistant, named and dated, never as one the person took; one at a time, under a hard size ceiling, with the bytes re-read and checked server-side; it lands as a private file, its location data is stripped on the way in while its capture time is kept, and nothing an assistant may call can make it public or take it back. The person removes it in the product, and narrows the permission in one click at /settings/ai.
- An assistant proposes and answers; the person decides. A suggestion is raised with awb_propose_suggestion and waits: there is no tool that accepts one, and an Appraisal never becomes a Mission by machine — growing one is the person's own action. Both omissions are deliberate.
- A verdict on an Appraisal is optional and always shown as the answering assistant's, named and dated. Buying does not certify what a thing is worth, and no answer is ever presented as Buying's own.
- A suggestion the person declined carries a standing rule with their reason and the one condition under which it may be raised again. The rule is enforced on the write, and the refusal names it. Read awb_list_suggestion_decisions before proposing rather than learning the rule by being refused.
- The token proves who is calling; the stored grant decides what they may do. The grant is re-read on every single call, and the token's own scopes are never read for authorization.
- Asking for access never changes live authority. awb_manage_connection files one exact request and returns a link for the person; only their click can approve it.
- No assistant operation narrows, widens, revokes, or renews a permission. The one authority change that is not the person's own click is Buying raising a never-narrowed connection to the current default baseline, which only ever adds what every connection now holds and is recorded in the ledger. Narrowing and revoking remain the person's alone, at /settings/ai, and a connection they narrowed is never widened back.
- Each connection lasts 30 days from the sign-in that made it, and the person renews it themselves.
- No approval this product can issue ever allows any of the following. Reveal a seller's contact details, or contact, message, or negotiate with anyone. Make an offer, spend money, or complete a purchase. Permanently delete, archive, or export your workspace. Publish your private research, or share it outside Buying. Reach another person's workspace, or any other Assist product.
- A connected client may still apply its own per-tool prompt or block policy; Buying does not override client-side approval controls.

That starting authority is the "ordinary-research" policy, version
3. Every connection records which policy issued
it and keeps that version, so a later change to the baseline is visible rather
than retroactive.

What this means for you, concretely:
- The tool catalogue is the same for every caller. It is NOT filtered to what
  this person allowed, so seeing a tool listed is not proof you may call it. A
  call outside the grant is refused with the OAuth error "insufficient_scope"
  and the exact permission it needed, in the message and in a required_scope
  field. The refusal never carries a "scope" parameter in WWW-Authenticate,
  because these permissions are the person's product grant rather than something
  the authorization server can issue: re-running OAuth cannot get you one.
- awb_manage_connection is how you find out what you hold and ask for more. It
  is NOT a required first step. describe returns disjoint held / available to
  request / waiting for the person / legacy fields plus a revision number.
  request_access is additive only, needs a stable operationId (the older opId
  is still accepted on this one tool) and that revision,
  changes no live authority by itself, and returns a link the person clicks.
  Nothing you can call narrows, widens, renews, or revokes a permission.
- An empty tool list is not an outage and not a bug to retry around. It arrives
  with an "instructions" string saying exactly why and who can change it. Read
  that sentence and relay it. Do not reconnect repeatedly. A connection waiting
  for the person's own approval is listed exactly one tool,
  awb_manage_connection, rather than none.
- A GRANT_REQUIRED refusal is a normal, readable tool result, not a transport
  failure. Read its message and its recovery line, and relay them. Do not retry.
- A refusal that says an approval lapsed or was revoked means reconnect, not
  "this capability does not exist". Never report a lapsed approval as a broken
  feature.
- A 503 means Buying could not reach the authorization server, so your token was
  never judged. Wait and retry. Do not re-run OAuth; nothing is wrong with your
  token.
- The person may revoke or narrow a grant at any moment, and it takes effect on
  your very next request. A previously working call failing this way is expected
  behavior, not corruption. Say so plainly rather than working around it.
- Revoking is deliberate. Signing in again does not undo it; the person makes a
  new connection themselves.
- A grant may cover only selected Missions. If so, a call naming a different
  Mission is refused, and a call naming no Mission at all is also refused.
- A grant may be locked to one AI client. Another client of the same person does
  not inherit it.
- A person may switch on a barrier that holds each new AI until they approve it
  by hand. It is off by default. If it is on, you will be told you are waiting.
- Never ask a person to widen a grant merely to make a task tidier. Ask only when
  the work they actually requested cannot be done.

Grant scopes, and the tools each one covers:
- mission.read — Read your Missions and the records around them. Read your Buying brief, search your workspace, and open one Mission's options, criteria, comparison, dated observations, sources, and decisions — plus your items across every Mission, the places you have saved with your visits and your description of each, your lists and what you paid last time, and what you have already decided about earlier suggestions. Seller contact values are never included.
  Tools: awb_get_buying_brief, awb_search_workspace, awb_get_mission_context, awb_list_items, awb_get_item, awb_list_venues, awb_get_venue, awb_list_suggestion_decisions, awb_list_lists, awb_get_list, awb_list_trips, awb_get_trip
- mission.write — Save Mission research. Create and correct Missions, options, comparisons, sources, and dated decisions — including one-call complete results. Also raise a suggestion for you to decide, move an item along its lifecycle, keep a private note about a place, open a visit and write your description of a place, put things on your lists and record what they cost, open and answer an Appraisal in one call, and record what you actually did about it. Writes are replay-safe and keep their source and AI provenance.
  Tools: awb_save_mission, awb_save_option, awb_save_comparison, awb_log_sources, awb_save_decision, awb_save_complete_result, awb_propose_suggestion, awb_set_item_status, awb_create_venue, awb_add_venue_observation, awb_create_appraisal, awb_answer_appraisal, awb_log_appraisal, awb_record_outcome, awb_update_appraisal, awb_record_visit, awb_save_venue_description, awb_save_list_item, awb_record_list_price, awb_save_trip, awb_save_trip_stop, awb_add_trip_entry
- queue.read — See work you handed over. List the Queue items you sent to an AI and read their activity history. Nothing else in your workspace is visible through this alone.
  Tools: awb_list_capture_queue, awb_get_queue_activity
- queue.write — Work your Queue items. Claim, hold, complete, fail, release, or ask you a question about a Queue item you handed over. A Queue item never widens any other permission.
  Tools: awb_update_capture_queue_item
- media.read — Open your captured photos. Retrieve the private images attached to your Queue captures, through the protected media path rather than a public web fetch.
  Tools: awb_get_capture_image, awb_get_capture_images
- media.write — Attach a photo to work you handed over. Attach one photograph at a time to a Queue item or an Appraisal — the picture of the thing it is asking you about. It is stored privately in your workspace and filed as attached by that AI, named and dated, never as one you took. Location data is stripped on the way in; the AI cannot make a photo public or take it back afterwards, and you can remove it or turn this off whenever you like.
  Tools: awb_attach_photo
- places.read — Look up shared venues. Search the shared public directory of shops, markets, and venues. This is community data, not your private workspace.
  Tools: awb_list_public_locations
- places.contribute — Add shared venue context. Add a venue to the shared public directory and attach short privacy-scrubbed notes, or withdraw a note you contributed. Contributions carry no link back to your Missions.
  Tools: awb_find_or_create_public_location, awb_add_location_contribution, awb_withdraw_location_contribution

No grant can ever allow:
- Reveal a seller's contact details, or contact, message, or negotiate with anyone.
- Make an offer, spend money, or complete a purchase.
- Permanently delete, archive, or export your workspace.
- Publish your private research, or share it outside Buying.
- Reach another person's workspace, or any other Assist product.

The current authenticated catalog is exactly 45 tools:
awb_list_trips, awb_get_trip, awb_save_trip, awb_save_trip_stop, awb_add_trip_entry, awb_get_buying_brief, awb_search_workspace, awb_get_mission_context, awb_save_mission, awb_save_option, awb_save_comparison, awb_log_sources, awb_save_decision, awb_save_complete_result, awb_list_items, awb_get_item, awb_set_item_status, awb_list_suggestion_decisions, awb_propose_suggestion, awb_list_venues, awb_create_venue, awb_add_venue_observation, awb_get_venue, awb_record_visit, awb_save_venue_description, awb_create_appraisal, awb_answer_appraisal, awb_log_appraisal, awb_update_appraisal, awb_record_outcome, awb_list_lists, awb_get_list, awb_save_list_item, awb_record_list_price, awb_list_capture_queue, awb_get_queue_activity, awb_get_capture_image, awb_get_capture_images, awb_attach_photo, awb_update_capture_queue_item, awb_list_public_locations, awb_find_or_create_public_location, awb_add_location_contribution, awb_withdraw_location_contribution, awb_manage_connection.

First useful workflow:
1. Call awb_get_buying_brief. Besides recent Missions and Queue handoffs it
   returns grantedScopes — what this connection may actually do, read live, so
   you know before you promise — standingBrief, the compact criteria of a Mission
   the person tagged read-me-first or standing-brief, and openQuestions, the
   things the workspace is waiting to ask THEM. Ask those at a quiet moment.
2. Search before creating with awb_search_workspace. It reads Mission titles and
   goals, Item titles and summaries, and Appraisal titles, questions, answers and
   verdicts, so a record findable on the website is findable here.
3. Read an existing Mission with awb_get_mission_context before editing it. Pass
   verbosity "compact" when you need only criteria labels, target text and stable
   ids; full is the default and is what a correction needs. That
   read may carry buyerContext: standing facts the person wrote above the Mission
   — how far they will travel, what they already own, budget posture, lasting
   preferences. An item is there only because the person both lent it to this
   exact Mission and marked it readable; either alone reaches nothing. Use them
   so you stop re-asking, and treat them as the person's own words rather than
   evidence you gathered. A short or empty list is never proof they have no
   others, and no tool can write buyer context — ask them to change it at
   /context.
4. Preserve the person's accepted criteria, person-authored notes/sources, and dated
   decisions. New AI-inferred criteria remain proposals until the person confirms them.
5. Research with your own authorized capabilities outside Buying.
6. Prefer awb_save_complete_result to save the Mission, products/options,
   dated observations, comparison, sources, optional decision, and optional
   claimed Queue outcome in one approval. It reports a per-item result for every
   option, so one approval covers a whole working pass.
7. Use the granular save tools for partial work and corrections.

Note that awb_save_complete_result needs the queue.write permission as well as
mission.write when it carries a queue field. If only the Mission permission is
granted, save the Mission result without the queue field.

Queue is supporting continuity, not the whole product. Its states are needs_you,
working, waiting_for_ai, and done. A claim is a coordination lease and never
grants messaging, contact reveal, payment, purchase, deletion, or publication
authority — and never widens a grant. A Mission-scoped handoff includes missionId
and compact missionContext; read that exact Mission before research and save the
result only there. Buying rejects a Queue closeout aimed at a different Mission.
Prefer awb_get_capture_images for several queued photos and
awb_get_capture_image for one; do not web-fetch private file URLs first. Both
take an optional purpose, and what you say you are looking for is shown to the
person beside the record that you looked.

## Attaching a photograph

awb_attach_photo attaches ONE photograph to a Queue item or an Appraisal. It
needs media.write, which signing in has granted since 2026-08-29 — check
grantedScopes in the brief rather than assuming, because the person may have
narrowed it. When you ask them to take the picture, ask them to put a hand or a
shoe in the frame for scale: a photograph with nothing to size the object
against is the commonest reason an identification comes back wrong, and it
cannot be fixed once they have walked away.

- Prefer the three-step flow: mode begin_upload returns a short-lived single-file
  PUT URL on https://assistwithbuying.com and an uploadRef, you PUT
  the bytes yourself, then mode finish_upload attaches. It never redirects to
  Backblaze. Never echo, save, log, or narrate that URL: it is a write capability,
  not information.
- finish_upload makes the server re-read the stored object and verify its exact
  length, SHA-256, first-bytes format, and storage version before anything is
  attached. What you declared the type to be is never trusted.
- inline imageBase64 stays available for small compatibility cases and is capped
  well below the endpoint's own request limit. It is not the normal path.
- One photograph per call, and one operationId per photograph. Resend a failure with its
  ORIGINAL operationId: a retry of one that actually landed replays rather than storing
  the picture twice. If photo six of ten fails, the first five stay attached. (This field
  was named opId until 2026-08-29; it now matches every other write.)
- For several photographs, preflight every file's byte length and lowercase SHA-256
  first. Run no more than 3 independent
  begin/PUT/finish lanes at once, keep every operationId/uploadRef/URL/byte stream paired,
  and retry only failed lanes with their original operationIds.
- GPS coordinates a camera embedded are stripped on ingest for every grant —
  where somebody lives is their disclosure to make, and you have not been told
  it — while capture time is kept, because it is part of what makes a picture
  evidence.
- The file is recorded as attached BY YOU, named and dated, never as one the
  person took. It lands private: you cannot make it public, share it, or take it
  back. Only they can, in the product. Attach what is worth keeping.

Every media read and every attach is recorded per connection and shown to the
person at /settings/ai as "what your AI looked at", with your stated purpose if
you sent one. That record is theirs: it travels in their portable export and is
never part of a share.

## Permission layers and upload recovery

1. Buying identity and OAuth consent prove the person and create the connection.
2. Buying grants and record checks decide which workspace records and actions the connection may reach.
3. Buying keeps separate confirmation for destructive, public, sharing, payment, permission, and outside-world actions; current tools do not perform those actions.
4. The AI client controls whether it can read a local file selected on the person's machine.
5. The AI client, account, or organization controls whether its code-execution sandbox may send the upload HTTP PUT.

Upload sequence:
1. Preflight the entire photo set first: calculate the exact byte length and lowercase SHA-256 for every file before opening any upload session.
2. For each file, call awb_attach_photo with mode begin_upload and its own stable operationId. The returned uploadUrl stays on https://assistwithbuying.com and never redirects to Backblaze.
3. PUT that file's exact bytes to its own uploadUrl with the returned Content-Type and Content-Length.
4. Call awb_attach_photo with mode finish_upload, pairing the same operationId, uploadRef, target, and targetId.
5. Use at most three independent lanes at once. Never cross a file's operationId, uploadRef, uploadUrl, bytes, or finish call with another lane; retry only failed lanes with their original operationIds.

Terminal recovery:
- upload_incomplete: finish saw no stored bytes yet; complete the existing PUT and retry finish while the session is live.
- session_expired: stop using that capability and begin a new session; an expired session is never revived.
- operation_conflict: the operationId belongs to different bytes or metadata; reuse the original bytes, or use a new operationId only for genuinely new content.
- invalid_image: replace or re-encode the bytes; do not blame storage or retry unchanged bytes.
- media_unavailable: stop and wait for the product operator; never fall back to an old store.
- grant or record refusal: reconnect or ask the person for the named Buying authority; changing a client network allowlist cannot grant product access.
- client network block: stop minting expiring sessions until that client's outbound-network policy is corrected; reconnecting OAuth does not change it.

Claude-specific observation (2026-09-02):
For Claude code execution, allow only assistwithbuying.com in Settings → Capabilities when the first-party upload PUT is blocked. All domains also works but is broader and unnecessary. Start a new Cowork conversation after changing the setting. This controls Claude's outbound HTTP request, not Buying OAuth or grants. Never allowlist Backblaze.
This is dated troubleshooting evidence, not a claim that Claude has completed Buying's full deployed lifecycle.
Sources:
- https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude
- https://support.claude.com/en/articles/13455879-use-claude-cowork-on-team-and-enterprise-plans

## Items, places, Appraisals, and suggestions

Missions are not the whole product. Four surfaces sit beside them, reached by
twelve of the tools. All twelve are covered by mission.read and mission.write, because each
one reads or writes the person's own private workspace, carries your provenance,
and can be corrected by whoever wrote it — the same test every other default
write passes. awb_list_venues is deliberately NOT under places.read: that
permission is defined as community data, and this listing carries the person's
private places as well.

- Items are Findings seen outside one Mission. awb_list_items pages across the
  whole workspace with a status or category filter, awb_get_item returns one with
  its evidence and its entire append-only status history, and awb_set_item_status
  records what has happened to it. History is appended, never overwritten, and the
  row says an AI moved it. Marking something purchased is bookkeeping about what
  the person already did; the call never spends money or completes a purchase.
- awb_list_venues returns the shared directory plus the person's own places, each
  row saying which it is. awb_create_venue adds a place to the person's own list —
  workspace-private, never a directory entry — and hands back the venueId a note
  needs; publishing to the shared directory stays a separate, permissioned act.
  awb_add_venue_observation keeps a note that is always
  workspace-private, even on a shared entry, and nothing moves it into the shared
  listing: the sentence in note, its time in observedAt, and optionally a structured
  price — item, amountCents, currency, the unit it was priced by, and the containerSize
  it came in. Buying works out a per-gallon or per-cubic-foot equivalent server-side at
  entry, using published nursery trade sizes (a #15 can is about 12.7 gallons, not 15),
  and returns the price it stored. A container it cannot convert yields NO unit price:
  report that absence rather than working one out yourself. Write the sentence in note
  either way — the price sits beside it, never instead of it.
  awb_add_location_contribution remains the separate, permissioned,
  anonymized path into the community directory.
- awb_log_appraisal is the fast path and the one to reach for when the person is
  standing in front of something: it opens an Appraisal and answers it in ONE
  call. Following the multi-call flow once took six round trips before somebody in
  a stranger's garage saw a number. awb_create_appraisal parks a question they are
  genuinely leaving open; awb_answer_appraisal answers one already waiting. All
  three take askingPrice — integer cents plus a currency, what the tag said, never
  a valuation — and venueHint, free text like "garage sale, Tucson, 8/29", so
  resolving a place never delays an answer; a real venue can be attached later and
  the hint is kept either way. A verdict and a confidence are OPTIONAL — passing
  neither is the ordinary case — and whatever you store is displayed attributed to
  you, named and dated. Buying does not certify what a thing is worth. There is no
  tool that grows an Appraisal into a Mission; the person decides that.
- awb_record_outcome writes down what they actually did: bought, walked,
  negotiated, or undecided, with pricePaid when there is a number. Without it
  nothing ever checks an appraisal against reality. A second recording never
  overwrites the first — every one is kept with its time and who made it. You are
  writing down their decision, not making one.
- awb_update_appraisal fills in what was learned after the question was logged:
  the tag price read late, intent (curious or want — the flag that keeps real
  leads from drowning in the fun ones), the booth or dealer number, a venue, or a
  venue hint. Only the fields sent change; the question, answer, verdict, and
  outcomes are never touched. The three appraisal writes take intent and booth up
  front too. In a multi-dealer venue, awb_add_venue_observation also takes booth,
  discountPercent (that booth's standing markdown; the newest note per booth
  stands) and comeBack (a reason to return); awb_list_venues takes a name query
  and returns each place's boothDiscounts to apply and its comeBackFor marks.
- awb_get_venue reads one place in full: the person's long description of it,
  their visits (each carrying what was appraised and noted on it), recent notes
  and appraisals, booth discounts, and come-back marks. awb_record_visit opens
  or closes a visit; pass its visitId on appraisal and note writes to file them
  on it. awb_save_venue_description replaces the person's own long-form story
  of a place — read the venue first and pass its version. All workspace-private.
- Lists the person names themselves, with price history per item. awb_list_lists
  lists them and, with a query, also searches item names, so "what do I usually
  pay for pineapple?" is one call: the matching items carry the last confirmed
  price, a reading against their own history (high, low, about usual — and how
  many prices it stands on), and the cheapest places. awb_get_list reads one
  list with its items and trips. awb_save_list_item puts a thing on a list,
  creating the list by name if needed; the same thing again never makes a
  second record. awb_record_list_price appends a dated price and overwrites
  nothing. A price read off a receipt goes with source "receipt" and counts for
  nothing until the person confirms it on the page; no tool confirms.
- awb_propose_suggestion raises ONE suggestion with its trigger, evidence, lettered
  options each carrying the consequence of choosing it, and your recommendation.
  THERE IS NO ACCEPT TOOL. It waits on the person's page; nothing starts, nothing
  is claimed, and no AI is dispatched by raising one. Cite a line that argues
  against your own recommendation when there is one. A subject the person declined
  is suppressed, and the refusal names the rule, their reason, and the one
  condition under which asking again is reasonable — read
  awb_list_suggestion_decisions first so you learn a rule from the record instead
  of from a refusal.

## Current, Partial, and Later

Current in this source release: the 45-tool stateless OAuth MCP endpoint,
server-derived identity and workspace isolation, product-owned grants enforced on
every call with immediate revocation, a caller-invariant tool catalogue with
per-call insufficient_scope challenges, an append-only authority ledger, bounded reads,
replay-safe Mission writes, append-only observations/sources/decisions, Queue
leases, inline private images, and Mission/Finding/Queue web reads of AI changes.
The desk loads at most 20 recent decisions and 50 recent source checks;
append-only older records remain stored.

Partial: client compatibility. A scripted lifecycle harness re-proves the server's
side of the contract on every deployment — anonymous challenge, scope-filtered
listing, bounded read, idempotent write, cross-owner refusal, malformed and
replayed requests, revoke denial, reconnect, and synthetic cleanup. What it does
not prove is any particular AI client's own environment. Earlier dated production
acceptances (2026-08-12 through 2026-08-14) proved the Mission, Queue, save,
render, and cleanup lifecycle, but they predate the grant boundary and are not a
current compatibility claim for any named client. No client is named as supported
until it completes the full lifecycle under grants in its own environment.

Later: seller contact reveal, external messages, offers, reservations, payments,
purchases, permanent delete, export through MCP, publication of private research,
portfolio-wide or cross-product grants, and collaboration.

## A chat assistant with connectors (Standards-based)
Fit: Desktop or web assistants that let you add a custom MCP connector
The simplest shape. If your assistant has a Connectors, Apps, or Custom integrations screen that accepts a remote MCP URL, that is the whole setup.

Steps:
1. In your assistant's settings, find Connectors (sometimes Apps, Integrations, or Custom connectors) and add a custom one.
2. Paste the MCP server URL above. Leave any client ID and client secret fields blank — Buying does not use them.
3. Choose Connect, sign in with your Assist With Buying account, and click Allow. That creates the ordinary 30-day Buying grant; there is no second permission screen.
4. Ask it to call awb_get_buying_brief. Buying rechecks the stored grant on every tool call.
Good to know:
- Some assistants expose the add-connector flow only on desktop or web, even when the phone app can use a connector once it exists.
- Set the connector up from your assistant's settings, not by asking it in chat to connect itself.
- Many assistants ask you to approve each tool call. You can usually pre-approve a connector you trust; your Buying grant still limits what it can reach.

## A terminal or CLI agent (Standards-based)
Fit: Command-line coding and research agents
Most terminal agents add a remote MCP server with one command, then run a separate login step that opens your browser.

Steps:
1. Add the endpoint as a remote HTTP MCP server, using whatever the agent calls that (often an `mcp add` command).
2. Run the agent's login or authenticate step for that server, complete browser sign-in, and click Allow. That is the Buying approval.
The shape most CLI agents use:
<agent> mcp add assistwithbuying --url https://assistwithbuying.com/mcp
<agent> mcp login assistwithbuying
Good to know:
- Do not pass an Authorization header. Leaving it off is what triggers the OAuth flow.
- Authentication is usually a separate step from adding the server.

## A code editor with agent mode (Standards-based)
Fit: Editors that read an MCP config file
Editors normally take a JSON config entry and then show a sign-in prompt next to the server once it is added.

Steps:
1. Add an HTTP MCP server entry like the snippet below to the editor's MCP config.
2. Use the sign-in prompt the editor shows next to that server entry, approve in the browser, and click Allow.
3. Switch the assistant into its agent mode; tool use is usually unavailable in plain chat modes.
MCP config entry:
{
  "mcpServers": {
    "assistwithbuying": {
      "type": "http",
      "url": "https://assistwithbuying.com/mcp"
    }
  }
}
Good to know:
- Just the URL. Do not add a static Authorization header.
- On a managed or company seat, an administrator may have to allow MCP servers first.

## A client without built-in OAuth (Bridge required)
Fit: Clients that speak MCP but cannot do the OAuth flow themselves
Some clients support MCP but not remote OAuth. A local bridge can complete the sign-in on their behalf.

Steps:
1. Configure the client to launch a community OAuth bridge pointed at the endpoint, as below.
2. Run the client. The bridge opens a browser window for sign-in the first time.
Local OAuth bridge:
{
  "mcpServers": {
    "assistwithbuying": {
      "command": "npx",
      "args": ["-y", "mcp-remote@0.1.29", "https://assistwithbuying.com/mcp"]
    }
  }
}
Good to know:
- A bridge is a third-party tool running on your machine and handling your tokens. Prefer a client with native OAuth where you have the choice.
- Pin a version rather than letting it float.
- Admin-hosted clients are usually configured centrally, not per person.

What any client must support:
- Remote MCP over Streamable HTTP — not SSE, and not a local stdio server.
- OAuth 2.1 with PKCE, completed in the person's own browser. Buying issues no API key and takes no client secret.
- Reading the tool list fresh after connecting, and after Buying deploys, rather than caching it forever.
- Showing tool results, including refusals, to the person rather than swallowing them.

Operational boundaries:
- Buying never runs the AI, spends money, contacts a seller, or makes a purchase.
- Normal MCP context withholds seller-contact values.
- The connector cannot delete or publish private workspace research. Places is the narrow public exception: with the places.contribute permission and explicit confirmAnonymizedShare, it can create a public location, add a short privacy-scrubbed note, and withdraw only that same person's contribution.
- Record blocked, gated, failed, partial, and empty source checks honestly.
- Keep products separate from offers and asking prices separate from sold prices.
- Use integer cents, explicit currency, dated observations, and stable keys.
- A person can always work with you by hand instead, through the Queue and copy-and-paste. Connecting is a convenience, never a requirement.