Knowledge base

# Building your Artisan knowledge base

Turn on every connector you have, then paste everything below the line into Claude. There is nothing to fill in. It works out who you are, finds the rest itself, and comes back at the end with the few things that are genuinely not written down anywhere.

---

You are building the knowledge for an Artisan account. It gets used on four surfaces: autonomous replies to inbound email and LinkedIn, inbound web chat, the AI AE on live calls, and outbound sequence generation.

Read this section before writing anything, because it changes what to produce.

## How Ava actually reads this

Retrieval is vector similarity over the uploaded content. Roughly five chunks come back per query, ranked on similarity alone. There is no weighting by how new a document is, what type it is, or how confident anyone was when they wrote it. A chunk either wins on similarity or it is not in the answer at all.

Three consequences drive everything below.

**Everything here is retrieved, which makes phrasing the whole job.** A sentence only reaches Ava when its chunk wins the similarity contest against the question actually asked. So a rule has to be written as the answer to a question someone asks, not as a standing instruction. "Keep replies short" reaches nothing. "Artisan does not publish prices, a scoped quote comes from the sales team" reaches every pricing question, which is exactly when it is needed.

**There is no hierarchy, so everything uploaded is treated as true.** An unverified fact competes on equal footing with a verified one. There is no confidence field to protect you. If something is not good enough to be said to a customer, it does not go in.

**The budget is about five chunks.** Short, focused, non-overlapping content wins. Near-duplicate chunks are the main way a knowledge base gets worse as it grows, because two versions of the same answer compete for the same slot and the weaker one sometimes wins.

## What you are producing

Markdown knowledge files, plus a list of objection and response pairs. Then a handover note, which never gets uploaded.

Everything Ava needs has to be expressible as a fact. There is no coaching list, no banned phrase list and no separate behavior config in this build, so a rule you cannot write as a true sentence about the company has nowhere to live. Write it as one:

- "Never quote a price" becomes "Artisan does not publish prices. A scoped quote comes from the sales team."
- "Never give a ship date" becomes "Artisan does not give release dates for unreleased features."
- "Never comment on competitor pricing" becomes "Artisan does not comment on what other vendors charge."

This is why the negative facts matter as much as the positive ones. A file that only says what the company does leaves the agent to improvise everywhere else.

**Size.** Roughly ten to twenty-five files, three hundred to nine hundred words each. Length is a symptom of duplication rather than a sign of coverage. A knowledge base three times that size is worse, not more complete, because the duplicates compete with each other for the same five slots.

## Step one: work out who you are working for

Identify the company from what you can already see. The email domain on the connected account, the CRM portal, the chat workspace, the drive account, a signature in sent mail. The domain gives you the website.

Say in one line who you have concluded you are working for and carry on. Do not wait for confirmation. If it is wrong they will say so.

Only if no connector reveals a company, ask one question: what is your website.

## Step two: read what is already in the knowledge base

Before writing anything, look at what Artisan already holds for this account, in particular the Company Intelligence page. It is generated automatically and takes precedence over everything else, and it already covers the elevator pitch, value propositions, customer segments, customers and results, proof points, competitors, buying triggers and buyer language.

Do not rewrite any of it. Two documents saying nearly the same thing is worse than one, because they split the retrieval budget between them. Check what it says, correct it where it is wrong, and then write only what it does not cover.

This step is a hard stop. If you cannot read the Company Intelligence page, because the dashboard is signed out or you have no access, say so and ask for it before writing a single knowledge file. Do not proceed by guessing which topics it probably covers and writing around them. Overlap is the main way a knowledge base degrades, and this is the one place where guessing is guaranteed to cause it.

While you are in the console, read the Gaps tab. It holds the real questions Ava has already been asked and could not answer. This is better evidence of what is missing than anything you will reconstruct from tickets or calls, because every entry is a live failure rather than an inference. Each entry has an Answer control next to it, so check whether answering a gap in place is the better route for that specific question than writing it into a file. Treat clearing the tab as a target: say at the end how many of the gaps this build answers and which ones it does not.

Also look for an existing internal do-not-say page. Most companies have one somewhere, usually a wiki page of numbers not to quote or claims not to make. It is the right spine for the negative facts, and it is usually stale in a couple of places, which is worth flagging on its own.

## Step three: go and find the rest yourself

Assume every answer exists somewhere. Check which connectors are live, say which ones you found, then sweep all of them.

**This sweep is read only.** Nothing is sent, drafted, replied to, posted, scheduled or deleted. No CRM record, ticket, document or calendar entry is created or modified. You are reading a company's live systems to write about them, and every tool call in this phase is a read.

**Run the sweep in parallel.** Split it across subagents by source rather than working through it serially, or this takes an hour instead of ten minutes. A reasonable split is one agent on the public web, one on email, one on the internal tools such as chat, docs and issue trackers, and one on the support desk, CRM and call notes. Give each one the topic list below rather than a vague brief.

**If a tool errors twice, stop and move on.** Record it in the handover as a source not reached. Do not keep retrying a broken connector or work around it with a different tool that has the same problem.

Sources to sweep:

**The website, always.** Every page. Product and pricing, about, case studies, blog, help center, FAQ, careers listings (they describe the product better than marketing does), terms and privacy, everything in the footer. Works with no connectors and is usually a third of the content.

**Past conversations with Claude.** Search previous chats for the company, product, positioning, pricing, competitors, customers, launches. People explain their business to Claude and forget they did.

**Email.** Sent mail is the best writing sample there is. The answers already given to prospects, the decks attached to outbound, the pricing emails, the security questionnaires already filled in. Look for repeated phrasing, because a sentence someone has typed forty times is already the right answer.

**CRM.** Deal notes, close reasons on lost deals, competitor fields. Lost deals tell you more than won ones. Count the reasons, and read the notes behind the reasons, because "no budget" is usually four different objections wearing one label.

**Support and shared inboxes.** Rank topics by volume. The top ten are the ten questions this has to answer well.

**Calls and meeting notes.** Discovery calls give you the questions in the prospect's own words. Take the phrasing verbatim rather than translating it into marketing language.

**Docs, wikis, chat, issue trackers, changelogs.** Specs, enablement, price sheets, contract templates. Changelogs are how you tell a live capability from a planned one, which matters more than anything else here.

**Public sources.** Review sites, marketplace listings, LinkedIn, job posts, press, competitor comparison pages.

Search each source at least twice with different terms before concluding something is not there. Most misses are vocabulary mismatches.

Work out from evidence rather than asking: what they sell, business type, who they sell to, size, languages, regions, and whether they are regulated.

**What never comes out of the sweep and into a file.** These files get read out to prospects and customers. No individual employees' personal details, no HR or personnel matters, no other customers' confidential information, no internal cost, margin or vendor pricing, no security detail that is not already in their public trust material.

## Step four: write, and log every hole as you go

Draft everything you can. Do not upload a placeholder and do not mark a file as unverified, because nothing downstream reads that marker and the chunk gets used anyway.

Keep two running lists while you write.

**Conflicts.** Anywhere two sources disagree. A number that appears three different ways, a policy the site states one way and support states another, a timeline the sales team and the delivery team describe differently. Record every version, every source, and which one the weight of evidence favors.

**Gaps.** Anywhere a question a customer would obviously ask has no answer anywhere you looked. Record what the question is and every place you searched for it.

Both lists get resolved with the person in step five. Neither is a handover artifact by default. A knowledge base that ships without an answer to one of the ten most common questions is not finished, it is a draft with a note attached, and the note will not be read before the next prospect asks.

## Step five: settle every conflict and fill every gap

Work through both lists with the person until each item is answered or explicitly deferred. Do not carry unresolved items into the handover as a matter of course. The point of this step is that the knowledge base ships accurate and complete rather than shipping with a list of things it gets wrong.

There is no cap on how many items you raise, because a conflict you did not raise becomes a wrong answer sent to a customer. There are hard rules on how you raise them.

**Every item arrives as a decision, not a research task.** Never hand over a blank. For a conflict, give every version you found, where each came from, and the one the evidence favors, so the reply can be a single word. For a gap, say exactly where you already looked, so they can see it is not findable and not spend ten minutes checking.

**One decision per numbered item. Never bundle two.** An item asking "which price may Ava say, and is there actually a free trial?" gets answered on the price and goes quiet on the trial, and the quiet half then gets inferred and shipped as fact. Split them, number them separately, and at the end of each round list anything that came back unanswered and ask again.

A conflict should read like this:

> **Warm-up duration.** Support says 14 days. The onboarding SOP and the security material say two to three weeks. A rep told a customer "a couple of days" last week. One customer reported over a month.
> Recommend two to three weeks, which three of four sources support.
> Confirm, or give the right number.

A gap should read like this:

> **Mailbox-to-volume ratio.** Not in the help center, the onboarding SOP, Slack, or sent mail. Two internal figures contradict each other. What is the real ratio?

**Never ask for anything reachable in a connector or on the website.** Search twice with different terms before an item earns a place on either list. Most misses are vocabulary mismatches rather than genuine absences.

**Go in rounds, not one wall of text.** Group by topic, roughly six to eight items a round, and put the ones blocking the most-asked questions first. Write each round's answers into the files before starting the next, so progress is visible and nothing gets answered twice.

**Two rounds is the limit.** After the second round, anything still unanswered stops being a question. It either drops out of the knowledge base entirely, or, where there is a safe conservative version of the fact, ships as that version and is recorded in the handover with an owner. Say plainly which of the two you did for each item. Nobody is going to work through five rounds of questions, and a build that waits for that never ships.

Also propose these two, since neither is ever findable:

**A draft list of what the company will not say**, built from their compliance pages, their industry, the disclaimers on their own site and the way their reps hedge in sent mail. Present it as a list to edit. It becomes `what-we-do-not-answer.md`.

**Whether Ava can quote a price, and to whom**, inferred from whether pricing is public and whether reps put figures in email. Ask for the condition as well as the figure, because "only for small companies" is part of the answer and has to be written into the chunk.

The gaps that usually need asking: which customers can be named out loud, why deals are actually lost when the CRM says no budget, what they have decided never to build, and who each kind of question routes to by name.

**A condition in the answer goes into the chunk.** When the answer comes back qualified, "default to X, only mention Y for small companies", "we say A unless they are in Europe", the qualifier is part of the fact and has nowhere else to live. Write it into the same sentence, in the file the question would actually retrieve. A condition parked in a different file, or left as an intention, is a condition that does not exist.

**A threshold has to be a number before it ships.** "Small companies", "larger teams", "enterprise deals" are things a person can evaluate and a retrieval chunk cannot. When a condition arrives as an adjective, ask once for the line, in headcount, revenue, volume or whatever the company actually uses, and do not write the answer until you have it.

**When their answer contradicts what you found.** This happens most often on certifications, ship dates and pricing. Say it once, in a single item: what they said, what the evidence says, where the evidence came from, and your recommendation. Then do what they decide, because it is their company and their liability. Record the disagreement in the handover with the evidence attached. Do not relitigate it across rounds, and do not quietly write your own version into a file instead.

**When they rule a topic out entirely.** Tell them once that leaving a topic out of the knowledge base does not produce silence on that topic, it produces improvisation, because the question still arrives and nothing is retrieved to answer it. Offer a single negative fact as the alternative, of the form "the company does not discuss X over email or chat, a scoped answer comes from the team." If they hold the exclusion, write nothing and record it in the handover as a deliberate hole.

**When they cannot answer.** "I don't know" and "ask someone else" are legitimate answers. When one comes back, the fact stays out of the knowledge base entirely and the item moves to the handover marked with who has to decide it. Never fill the hole with your best guess, never split the difference between two contradicting numbers, and never upload both versions and let retrieval choose. A missing answer produces an escalation, which is recoverable. A confidently wrong answer produces a wrong answer sent to a customer, which is not.

Keep going until every item on both lists is either written into a file or recorded as deferred with an owner.

## If they are regulated

Finance, healthcare, legal, insurance, defense, gambling or cannabis. Write `what-we-do-not-answer.md` first, before any other file. Every claim an agent must never make: rates, approval odds, outcomes, returns, eligibility, medical or legal advice, guarantees. Each one as a fact about what the company does not state, with what happens instead. Someone who owns compliance signs off before anything goes live.

Be honest with them about the limit here. A retrieved file is a weaker control than an enforced rule, because it only reaches the agent when it wins the similarity contest. If the platform offers a hard mechanism for prohibitions, a regulated company should use it as well as this file, not instead of it.

## The knowledge files

The console tabs are Company, Knowledge, Case studies, Customers, Gaps and Objections. You are writing into two of them.

**Knowledge** takes markdown files and almost all of the content.

**Objections is not a file upload.** It is a form with two fields, the objection and the response, added one entry at a time. So objections are produced as a list of pairs rather than as files: the objection in the prospect's own words, and a response of two to six sentences. Eight to fifteen pairs, drawn from the reasons deals are actually lost rather than from imagination. Keep them in one working file so they can be entered in order, and head each with the objection exactly as a prospect would type it. "This is more expensive than what we use now" retrieves against a real message. "The prospect raises a cost concern" does not.

Company Intelligence, Case studies, Customers and Gaps are all filled by other means, so produce nothing for them. Do not write case study files. Do not retype the customer list, which comes from a CRM import.

Start with these in Knowledge. They cover most of what gets asked.

`what-we-sell.md` — the products or services, what each does, who each is for, in the customer's words. Skip anything Company Intelligence already states well.

`fit-and-non-fit.md` — who they sell to and, more usefully, who they do not. Be blunt about bad fits.

`how-it-works.md` — the mechanics from first contact to delivered, in order. For a product, how the product works. For services, how an engagement runs. For physical goods, order to delivery to installation.

`pricing-and-terms.md` — the model, what drives the number, what is included, minimums, payment terms, and every condition attached to which figure may be said to whom.

`limits.md` — what they cannot do. Gaps, known problems, things people keep asking for, roadmap versus never. The most valuable file in the set. The failure mode on an autonomous surface is not a weak answer, it is a confident invented capability, and this is the only thing that prevents it.

`what-we-do-not-answer.md` — the questions the company deliberately does not answer over email or chat, and what happens instead. Prices outside an approved anchor, legal and contract language, security questionnaires, regulated questions, ship dates, another customer's account, anything where a wrong answer is a compliance problem rather than a support ticket. Write each as a fact about the company rather than as an instruction, so it reads correctly if it lands in a reply: "Artisan does not answer security questionnaires by email. A reviewer is put in touch with the team that owns them."

Everything in that last file hands back to the sender, meaning the rep whose mailbox, calendar or account the conversation belongs to. There is no routing table and no named owners to discover, so do not spend a round asking who owns what.

Then by business type, worked out rather than asked. Software adds integrations, security and compliance, implementation, data and privacy. Physical product adds lead times and shipping, specs and materials, warranty and returns, ordering and minimums, and channel if they sell through dealers. Services adds capabilities, scoping and rates, and team. Marketplaces need a set per side, because supply and demand ask different questions.

Multiple regions get a file per region for anything that varies. Never bury a country exception inside a general file, because the general chunk is what wins on similarity and the exception never surfaces.

## How to write a file so it retrieves

The chunk is the unit, not the file. Write so each chunk can win on its own.

- One question, one answer, one chunk. Phrase the heading the way a customer would ask it, not the way the company files it internally. "How long until it ships?" not "Fulfillment timelines."
- Two to six sentences per answer. Bullets and Q&A pairs retrieve better than paragraphs.
- Put the words a customer would actually search into the answer text, including their synonyms. If the company says "annual license" and buyers say "subscription" and "yearly plan," all three belong in the answer, because similarity is matching the query against this text and nothing else.
- Restate the noun. Never write "it" or "as described above." Assume the chunk arrives alone.
- If a fact belongs in two files, write it twice, but write it identically. Two slightly different versions of the same fact is the failure mode to avoid. Two is the limit. The same block repeated across three or more files starts crowding a single query, returning the same sentence in several of the five slots and pushing out everything else, so repeat only where the surrounding answer is genuinely different.
- Every number carries its unit and its condition in the same sentence. Half a fact is worse than none when nobody is checking.
- No frontmatter, no metadata block, no confidence marker, no source tag. Nothing reads them and they dilute the chunk.
- **Never address Ava inside a knowledge file.** A chunk goes into the prompt as plain context with nothing marking it as meta, so an instruction sitting inside it can be echoed straight to the prospect. No "route this to an account executive," no "the honest answer is," no "escalate this," no "use this case study with prospects who." State the fact and stop. Where the fact is that a topic is deal-specific, write that it is deal-specific and that a scoped answer comes from the team, as a fact about the company.
- **One second person, and it is the customer.** "You" means the person reading the reply, never Ava. Mixed voice in one knowledge base means Ava will sometimes speak in the wrong one. A heading written as the customer's own question is the one place "you" means the company, and that is fine, because it is a quoted question rather than an answer.

Plain language, short sentences, no marketing adjectives. Where the company already has a good sentence, use theirs, including their own spelling and their own name for things.

## Languages

Work out which languages they sell in from the site, the CRM and sent mail. Do not translate the files. Write natively in each language, because similarity matching runs against the text as written and translated phrasing does not match how buyers actually type. Where a fact differs by market, say so in both.

## Never upload

Anything still unresolved after step five. Anything unverified. Anything marked as a draft. Both versions of a conflict nobody settled. Case studies, the customer list, or anything else another part of the console already owns. All of these belong in the handover note instead, or nowhere.

## Before uploading

1. Every fact is verified. Nothing unconfirmed is in a file.
2. Nothing claims a capability that is not live today.
3. No file overlaps Company Intelligence or another file. Search for near-duplicate answers and merge them.
4. Every recurring support topic and every real objection has exactly one answer, in one place.
5. Every heading is a question someone would really ask, in their words.
6. Every chunk reads correctly alone.
7. Every rule is written as a fact about the company, not as an instruction. There is nowhere else for a rule to live, so a rule you could not phrase as a fact is a rule that did not ship.
8. Grep every knowledge file for instructions aimed at Ava: "route", "escalate", "rather than answering", "the honest answer", "use this with". Every hit is rewritten as a plain fact or deleted.
9. Grep every knowledge file for "you" and confirm it means the customer everywhere outside the headings.
10. Every condition attached to an answer is written into the chunk that answers it, not into a neighboring file, and every threshold is a number rather than an adjective.
11. Company Intelligence was actually read, and nothing overlaps it.
12. Every conflict and every gap from step four is either written into a file or recorded as deferred with a named owner. Every part of every bundled question got an answer. Nothing is silently dropped.
13. Nothing personal, internal or confidential to a third party is in any file.
14. The ten most common customer questions each have an answer in a file, and the Gaps tab has been worked through. Say how many gaps this build closes and which it does not.
15. If regulated, compliance has signed off.

## Deliver

The markdown knowledge files, kebab-case filenames, in a folder named Knowledge. The objection and response pairs in one working file alongside it. Write everything into the session's outputs folder, because the upload step can only reach files that have been shared with the session, and a file written somewhere else cannot be uploaded without being written again.

Then a handover note, not for upload, covering: which sources you reached and which you could not, and what you left out and why. Conflicts and gaps appear here only when step five could not settle them, and each one carries the name of whoever has to decide it. A long list in this section means step five was cut short. Deliberate holes, where the person ruled a topic out, go here too, along with any decision that contradicted the evidence, with the evidence attached.

The handover note must also carry a section titled "wrong things already said to customers." While sweeping email, chat, tickets and call notes you will find claims that contradict what is actually true: a ship date nobody committed to, a capability the product does not have, a timeline shorter than reality, a certification that is not held. For each one, record what was said, where and when it was said, who said it, what the truth is, and who needs to close the loop with that customer.

Do not treat this as a side note. It is frequently the most valuable output of the whole exercise, because a knowledge base fixes what gets said from now on and this section is the only thing that fixes what has already been said. Report it even when the list is long, and especially when it is.

Report between batches. The sweep first, then the rounds of decisions, then the files, with `what-we-do-not-answer.md` written last, once you know what every other file already covers and what is therefore left over.

## Then offer to upload it

If Claude for Chrome is connected, offer to put everything into the knowledge base rather than leaving the person to drag files in and type objections by hand. Offer, do not just start. Uploading is a form submission on their live account, so it needs an explicit yes first.

Then:

**Confirm the destination out loud before touching anything.** Say which workspace and which organization you are looking at, and wait. Multi-org accounts are common and uploading a company's knowledge into the wrong tenant is not a mistake you can quietly undo.

**Stop if they are signed out.** Ask them to sign in themselves. Never enter a password, never create an account, never work through a login screen.

**Knowledge, the file pass.** The Add button in the top right opens a menu rather than a file picker, so it is safe to click. Choose Knowledge from it, which opens a modal with a drop zone. Do not click the drop zone or the browse link, because those open a native file picker that is invisible to you and the run dies there. The hidden file input only exists once the modal is open, so find it after opening rather than before, and upload every file to that reference in one call. Then click the Upload button in the modal. Files process one at a time and a dozen files take about a minute.

**Objections, the form pass.** Each pair is entered by hand: Add, then Objection, then the objection field, then the response field, then Add. Element references regenerate every time that dialog reopens, so a reference captured on the first entry is dead on the second. Drive this pass by screen coordinates rather than references, take a screenshot after the first entry to fix the positions, and batch several entries per call once the positions are known. The dialog geometry does not change with the length of the text, because the response field scrolls rather than growing.

**Wait for processing and then verify.** Uploaded files sit in a processing state and do not appear in the table until they finish. Do not re-upload anything that has not appeared yet, because that is how you end up with every file in twice and duplicate chunks competing on every query. When it settles, read the tab back and count what is there against what you sent, and say plainly which landed and which did not.

**Report what you did not upload and why.** The handover note never goes in. Neither does anything still unresolved.