> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shared Workflows

> Use asks, documentation search, and account navigation across v3 accounts.

## File an ask when the account cannot resolve the work

`save_ask` records something you are waiting on Apostra to answer or
provide. It is available from every account kind because the recipient of the
ask is outside the active account.

| Type          | Use it for                                           |
| ------------- | ---------------------------------------------------- |
| `support`     | Something broken, blocking, or requiring a person    |
| `product`     | A product capability that does not exist             |
| `supply`      | Inventory a Buyer wants but cannot find              |
| `integration` | A vendor or counterparty Apostra does not connect to |
| `commercial`  | Pricing, terms, billing, or a rate-card exception    |

`type` is optional. Omit it when you do not know who should answer; do not delay
a support request while classifying it.

`subject` is reserved for `supply` and `integration`, where it names the domain
or vendor. A supply ask also needs the channel so it can be matched to
inventory. Support, product, and commercial asks carry their situation in the
title.

<Warning>
  A `supply` ask must come from a Buyer account because it becomes evidence of
  buyer demand. A Seller blocked on its own inventory should file `support`,
  not manufacture a supply request.
</Warning>

Filing an ask requires read permission so the person who encounters the problem
can report it. Filing returns an opaque Apostra `askId`; it is not a ticket
key or an internal work-system ID.

## Read and update asks

Buyer and Seller accounts can list and read asks through `search` and `get`.
Organisation accounts can file an ask and update it later when they retain its
returned `askId`, but their current catalog does not include the read tools.

List asks explicitly:

```json theme={null}
{
  "kind": "ask",
  "filter": { "askState": "open" },
  "limit": 25
}
```

Read one using the returned ID:

```json theme={null}
{ "kind": "ask", "id": "ASK_ID" }
```

Ask titles may contain customer-supplied text, so asks do not appear in an
unrelated bare search. Ask IDs are account-scoped; an ID from another account
returns the same `NOT_FOUND` result as an unknown ID.

Use `save_ask` with `id` and `requesterState` to record the requester's view:

| Requester state      | Meaning                                                   |
| -------------------- | --------------------------------------------------------- |
| `confirmed_resolved` | The requested outcome happened                            |
| `accepted`           | The answer was acknowledged without claiming satisfaction |
| `still_blocked`      | The answer did not resolve the request                    |
| `withdrawn`          | The requester no longer wants the ask pursued             |

Updating requires write permission. Only the original requester or an account
admin may withdraw; anyone with write access may report that the account is
still blocked. Title, type, and severity are fixed after filing because they
control deduplication and response handling.

An optional note replaces the requester's existing note. Omit it to keep the
current note.

## Share failure evidence safely

Text fields on `save_ask` are scanned for common bearer tokens, API keys, JWTs,
and cloud credentials. Recognized values are replaced with `[REDACTED]` before
storage, forwarding, or audit capture while surrounding IDs and error text are
preserved.

Treat this as a safety net, not permission to paste secrets. Remove credentials
before filing and rotate anything you believe was exposed.

## Search public documentation

Use `search` with `sources: ["docs"]` to find the relevant public page. A
discovery result contains a stable `document` path and citation URL:

```json theme={null}
{
  "query": "how does publisher authorization work?",
  "sources": ["docs"]
}
```

By default, `docsScope` is `caller_relevant`: public pages that apply to the
active account kind and its enabled product features rank first. Each result's
`relevance` field explains whether the page is relevant, general, or has
unknown applicability. The top-level `knowledgeRelevance.reasonCodes` field
reports missing account or feature context instead of implying that a feature
is available.

For research across every public page, opt in explicitly:

```json theme={null}
{
  "query": "how do sellers configure inventory?",
  "sources": ["docs", "specs"],
  "docsScope": "public_research"
}
```

Relevance is an information aid, not an access rule. `public_research` can
widen discovery only across the same public documentation; it cannot expose
private content, internal guidance, or customer objects. Organisation accounts
receive this documentation-only form of `search` and cannot use it to search
Buyer or Seller objects.

Before answering with an exact procedure, response field, authorization rule,
or safety step, read the selected page through the same tool:

```json theme={null}
{
  "query": "how does publisher authorization work?",
  "document": "storefront/inventory-sources/publisher-properties-coverage",
  "sources": ["docs"]
}
```

An exact-document read returns bounded relevant sections with citations.
Exact authorized reads are not hidden by relevance tags: once a caller has a
public `document` path, the same page remains readable even when it is not a
default discovery match. Arbitrary web URLs and internal repository paths are
not accepted. If the page does not establish the fact, say so instead of
repeatedly reformulating the same search.

## Move between accounts

`get_status` returns a bounded `reachableAccounts` list and marks it when
truncated. Pass a returned account ID to `switch_account`, then call
`get_status` again. Account IDs are not seller/storefront IDs.
`request_proposals` resolves its complete eligible seller cohort server-side;
do not pass account IDs or attempt to build a seller list for it.