Codebase grounding for AI assistants: the Provenance engine
Teaflask's Provenance engine drafts docs from your code, checks the claims code can establish, and proposes corrections for an owner to review.
Teaflask's Provenance engine grounds your in-product AI agent in your codebase. It drafts the docs the agent answers from. Releasing a doc requests checks for claims your code can establish. After a suite passes its initial run, relevant production-branch pushes can trigger re-checks. A contradiction can lead to a proposed correction for an owner to review.
What is codebase grounding?
Codebase grounding gives an AI assistant your product's source code or documentation derived from it as evidence for its answers. Separately maintained help articles can also be kept current through review or automated checks. In Teaflask, grounding is the product-specific information the agent bases its decisions on: documentation, live information from the app, and action definitions.
Docs: The meaning behind your product
What features do, which rules apply, and how workflows fit together.
Live app state: The current situation
Live information from your app or API establishes what is true for this user right now.
Action definitions: The operations on offer
Each definition describes one operation and the inputs it accepts.
The Provenance engine looks after the first of the three. It ties checkable documentation claims to code evidence and can check them again as that code changes.
How the Provenance engine checks released docs
Start by connecting a repo, drafting from it, and having an owner release the result. Release requests verification; it does not wait for a passing check. Once a suite is active, relevant production pushes can trigger checks. A contradiction may lead to a proposal, which an owner reviews. The stages below show who acts, not a sequence that runs on every change.
Build the knowledge
Read your repo
Teaflask. Connect GitHub with read-only access. Teaflask clones the repositories you select into temporary sandboxes.
Draft docs and actions
You and Brew. Ask Brew, the drafting assistant in the Teaflask dashboard, to write a doc from your code. Teaflask also discovers API actions in the same repositories.
Release
Owner. An owner reviews the draft and releases it. Agents read released docs within their knowledge scope, never drafts. Release requests verification; the content becomes current independently of whether verification succeeds.
Check for drift
Verification suite
Teaflask. Release requests executable checks for claims the connected code can establish. Each check quotes its claim and looks for evidence, such as a config value or function. The suite becomes active only after its initial run succeeds.
Push to production
You. Once a suite is active, relevant pushes to the designated production branch can trigger further checks. Nearby pushes are grouped; a check reads the branch when it runs, not necessarily the triggering commit.
Contradiction found
Teaflask. The doc moves to Needs review. Its banner summarizes the finding and can quote the affected claims.
Revision proposed
Teaflask. Teaflask can investigate the failing evidence and draft a corrected revision. The released doc stays in use meanwhile.
Approve or Dismiss
Owner. Use See what changed, then Approve to release the proposal or Dismiss to leave the released doc as it is.
A $500 rule changes in a YAML file
Take one rule your agent might repeat to a customer.
The doc says it
A released doc states that refunds over $500 require manager approval. An active verification suite covers that config-backed claim.
The code moves
A push to the production branch raises the threshold in a YAML config to $1,000.
The check fails
It quotes the sentence, looks for the value in the config, and finds a different one. The doc moves to Needs review.
A fix waits for you
Teaflask can propose a revision saying $1,000. The released doc, still saying $500, stays live until an owner releases an update.
What each verification status means
| Status | Meaning |
|---|---|
| Verified | The doc has a successful verification result. The timestamp identifies its last successful check. |
| Checking… | Verification checks are being created, or a run is in progress. |
| Needs review | A check found a contradiction, or the initial checks could not establish a passing result. Review the evidence before deciding what to change. |
| Not verifiable | There are no checkable claims, or no suitable connected code to check against. |
Some conditions show no label, such as before verification has been requested. An infrastructure error is not treated as proof that the doc is wrong, and the last successful result can stay visible. The verification docs carry the full definitions.
Re-indexing vs verification
A refreshed index makes newer code available as evidence. Index freshness alone does not establish whether a released documentation claim contradicts that code. Verification tests covered claims, not historical customer chat answers, and neither a fresh index nor a passing check guarantees a correct response.
Re-indexing: is the latest code available?
Tracks which code the system has indexed. Indexing alone does not test the claims in a separately published help article.
Verification: does code contradict this released documentation claim?
An active suite tests the claims it covers against connected code. A contradiction flags the doc; uncovered statements and past chat answers are outside that check.
What it won't verify
Four limits, stated up front, because a green label you cannot interpret is worse than none.
Business policy and concept guides
A page with no claims the connected code can establish has nothing to check. It can still be released and read, and a person keeps it current.
Every sentence on a Verified page
Verified records a successful check of the claims the suite covers. It is not a guarantee that every statement on the page was tested.
Code you have not connected
Verification needs at least one selected repository with code to inspect. A doc with nothing suitable to check against shows Not verifiable.
Replacing released docs on its own
A finding does not edit or take down the released doc, and a proposal is a proposal. Review the changes and their evidence before approving.
Grounding is not permission
Grounding decides what the agent knows. Allow, Ask and Deny decide what it may do. A doc verified against your code gives the agent a better basis for a decision, and it grants no access: every action still passes through grants, policies, validation and your own API.
Agent grants
Select which registered operations an agent can use at all.
Action policies
Allow runs without approval, Ask needs the user's approval first, Deny never runs.
Request validation
Checks the supplied arguments against the action's schema.
API authorization
Your API decides whether this user may do this to this record.
None of these controls guarantees a correct answer, which is why both layers exist. Read the grounding docs and the actions docs, or see where they sit in how Teaflask works.
Questions about codebase grounding
Which embedded AI assistant platforms ground their knowledge in the product's codebase?
Teaflask is one. Its Provenance engine drafts docs from your connected repository. Releasing a doc requests checks for claims the code can establish; a suite becomes active only after its initial run succeeds. Relevant production-branch pushes can then trigger re-checks. Ask any platform where its knowledge comes from, which released documentation claims it tests against code, what triggers checks, and whether corrections are applied or proposed. This does not verify historical chat answers or guarantee future answers.
Does the Provenance engine rewrite my docs automatically?
No. When a check finds a contradiction, Teaflask can investigate the failing evidence and propose an updated draft, but the released doc stays in use. An owner then chooses Approve, which releases that proposal, or Dismiss, which discards it. A verification finding never edits or takes down the released doc on its own.
Which branches trigger checks?
The branch you designate as production for each connected repository. Set it under Settings > Integrations > GitHub: the default branch, a detected candidate, or a custom branch name. Once a doc's suite is active, relevant pushes to that branch can trigger further checks. Nearby pushes are grouped rather than producing one check per delivery. Checks read the production branch when they run, so they can include later commits.
What if the check itself is brittle?
A failed check does not always mean the doc is wrong. When Teaflask investigates a failure, it may find that the verification suite is stale or too brittle, and it can then replace the checks without changing the doc. You can also use Re-verify on a doc with an active suite to run the existing checks on demand.
Does it work without GitHub?
The docs describe GitHub as the way to connect repositories, and verification needs at least one selected repository with code to inspect. They do not describe another code source for verification. Without a connected repository you can still write, release and read docs, but they show Not verifiable. If your code lives elsewhere, book a call.
Does verification cost extra?
Creating or repairing verification checks and drafting corrections count as agent work, and the docs note that this work waits when the account is short of funds. The pricing page lists the plans and the model rates. If a check or a correction seems stuck, look at billing first.
Go deeper
- Grounding, in the docs
What the agent bases its work on, and the controls on what it may do.
- Verification, in the docs
How checks run, how statuses read, and how to review a proposed correction.
- How Teaflask works
From your code to an assistant that works your product for your users.
- The buyer's guide to embedded AI assistants
The five kinds of product sold under the name, and eight questions to choose by.
- How to choose a code-grounded AI assistant
Four approaches to keeping knowledge in sync with code, and seven questions to put to any vendor.