From source files to useful answers

1. Start with a small, clear source

A useful source identifies one product or topic and states supported facts directly. Keep names, model identifiers and variants distinct. Do not fill an unknown field with a guess just to make a record look complete.

A Markdown file is a practical starting point. For an illustrative scarf, the entire source can be short:

# Harbor Scarf

  Material: acrylic
  Care: hand wash

This is example data, not an actual product listing. It supports a material answer and a care instruction. It does not establish recycled content, price, stock, certification or suitability for a particular use.

Download the example Markdown file. Keep API credentials and personal information out of knowledge files.

2. Save, publish, then verify

The store's source files are authoritative. The search index is a derived view used to find relevant candidates. In the current V3 workflow, an upload can succeed while its status remains pending_directory_publish.

Publication is a separate operator step. After publication, verify the active index and ask a representative question. A storage receipt proves that a file was saved; it does not prove that the assistant selected it or that the answer is correct.

Start with an exact product name, then try a normal user phrasing. Inspect the returned source references and the answer together. A response without the expected source deserves investigation, even when the text sounds plausible.

3. Keep follow-up context, not unsupported assumptions

After asking what the scarf is made of, a user may ask, "Can I machine wash it?" The application can send the prior user and assistant turns through the documented context fields. This helps identify what "it" refers to without making the conversation history the product's source of truth.

For this example, the supported instruction is hand wash. The source does not confirm machine washing is safe. Good context handling preserves the subject; it does not invent the missing detail.

The Ask reference contains the implemented request structure. Keep the context within documented size limits and avoid forwarding unrelated conversation history.

4. Turn useful gaps into a review task

Now consider "Is the acrylic recycled?" The source does not provide that information. This is a possible content gap, not permission to generate a certification or claim that the product has no recycled material.

Missing provides a place to record the question, review relevant sources, and decide whether more information should be collected. Current records are manual. Automatic Ask-to-Missing logging is not enabled. Your authorized integration can decide when a review task is appropriate.

An empty search is not a complete inventory audit. In particular, a service outage must not be converted into a missing-product event. Preserve the difference between no bounded candidates, an unavailable index, and a confirmed source gap.

5. Maintain sources with revision checks

When new evidence arrives, update the source rather than patching only a displayed answer. Replacement uses the observed revision so another update cannot be silently overwritten. A conflict calls for a fresh read and review, not a forced retry.

Deletion has separate safeguards. Production deletion is disabled until recoverable storage and permissions are verified. Archiving a Missing task does not delete a source, erase retained versions, or satisfy a privacy-erasure request.

After a source change, repeat publication and the representative question check. The full-store builder is not an incremental customer-ingestion queue, and upload does not include an unlimited background rebuild.

6. Connect through a small trusted backend

A site can keep its existing frontend and use an application server or serverless function for authorized API calls. This avoids operating the retrieval pipeline in the browser while keeping account keys away from visitors.

Provisioned credentials and permissions determine the accessible store. A caller-supplied slug is not authorization. Never substitute a different tenant when the intended store is unavailable.

Ask is metered in tokens under the configured policy. Missing, Add and Delete are data operations that do not themselves call AI; their proposed request pricing is separate. Publication and storage are separate costs and capabilities. Read the pricing boundaries before building a paid workflow.

Begin with a question you can check

Choose one small collection, one supported answer and one known gap. Make those paths understandable first. Then expand the sources, language coverage and application experience using the same evidence and permission boundaries.

The guide describes implemented preview contracts. Customer access and production source management remain controlled; a local test is not a public-service activation.