Kapa

View saved version →

---
name: kapa-check
description: Inspect Kapa source status and check knowledge retrieval. Use when the user wants to see what a project holds or diagnose thin answers.
---

# Check a Kapa project

Call list_sources for my Kapa project and show me what it holds and where each source has got to. Then ask me a question my content should answer, call search_project_knowledge with it, and show me what comes back. If the answer is thin or wrong, say what would cause that rather than declaring success.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-gaps
description: Review Kapa coverage gaps and frequent questions. Use when the user wants to identify missing documentation and prioritize new content.
---

# Review Kapa coverage gaps

Show me where my Kapa project falls short. Call list_coverage_gaps_periods for my project, then get_coverage_gaps with the most recent period id to see what people asked that my content does not cover. Do the same with list_top_questions_periods and get_top_questions for what they ask most. Summarise both and suggest what content would close the biggest gaps.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup
description: Set up a Kapa project and connect an appropriate knowledge source. Use when the user wants to begin a Kapa project or choose a source type.
---

# Set up a Kapa project

Set up my Kapa project using the kapa MCP server. Start by calling list_projects to confirm I am signed in; if it fails with an authentication error, guide me through the current host's Kapa sign-in flow, then wait for me before retrying. Ask which project if there is more than one. Then ask what I want Kapa to answer questions about, and load the matching kapa-setup-* skill for what I choose rather than working the calls out yourself. Do not pick filters for me: show the options and ask.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-confluence
description: Set up a Kapa Confluence source so a Confluence site is ingested. Use when the user wants Kapa to answer from Confluence pages or spaces.
---

# Set up Confluence

## 1. Have the user create an API token

Tell them to open https://id.atlassian.com/manage-profile/security/api-tokens
and create one. The token carries that person's own access, so the source
ingests exactly what they can see. A space missing later usually means their
account cannot read it.

## 2. Create the source

`create_confluence_source` with `project` and `name`. Keep the returned id.

## 3. Check the credential and list the spaces

`validate_confluence` with `url`, `email` and `api_token` answers whether the
credential can read the site. Do this before saving anything: a wrong token
otherwise shows up as a source that silently ingests nothing.

A false here is most often a `/wiki` suffix on the URL rather than a bad
token. Pass the site root only.

Then `list_confluence_spaces` with the same arguments shows what that account
can see. Show the user the real space names and ask which to ingest, rather
than asking them to find space keys themselves.

`list_confluence_pages` takes `space_keys_include` as well, so choose spaces
first: without it, it walks every visible space.

## 4. Configure it

`set_confluence_config` with `source_confluence`, `url`, `email` and
`api_token`.

- `url` is the site root **without `/wiki`**, such as
  `https://acme.atlassian.net`. Kapa adds `/wiki` itself, and a URL that
  already ends in it breaks ingestion.
- `email` is the Atlassian account the token belongs to. Ask for it; do not
  guess it from the user's other accounts.
- `api_token` is their secret. Ask for it, never invent one.

Use `list_confluence_spaces` to show the user what the token can see, then
ask which spaces to ingest. `space_keys_include` takes the ones they pick, or
`space_keys_exclude` drops a few from everything. Leaving both out ingests
every visible space, including internal ones.

## When it ingests nothing

The account behind the token cannot see that space. Have the user check their
own Confluence access before changing the config.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-custom-qa
description: Set up a Kapa custom question and answer source so hand-written answers are ingested. Use when the user wants to write answers directly for questions their documentation does not cover.
---

# Set up custom answers

The one source the user writes themselves. Use it when an answer exists nowhere
else, or when Kapa keeps getting something wrong and they want to correct it
directly.

## 1. Create the source

`create_custom_qa_source` with `project` and `name`. Keep the returned id.

## 2. Add the pairs

`add_custom_qa_pair` with `custom_qa_source`, `question` and `answer`. **Call it
once per pair**; there is no batch call.

Confirm the full list with the user before you start, then add them one at a
time.

## Writing them well

- Write the `question` the way a user would actually ask it, not as a heading.
  "How do I rotate an API key?" rather than "API key rotation".
- The `answer` takes Markdown.
- The same question text cannot be added twice to one source.

## After adding

Each pair ingests as it is added, so there is no separate publish step.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-discord
description: Set up a Kapa Discord source so a Discord channel's threads are ingested. Use when the user wants Kapa to answer from conversations in their Discord server.
---

# Set up Discord

No token here: Kapa runs its own Discord app. The user still has to add it to
their server.

## 1. The out-of-band setup

Tell the user to:

1. Add the Kapa Discord bot to their server.
2. Turn on **Developer Mode** in Discord: User Settings, then Advanced.
3. Right click the channel and choose **Copy Channel ID**.

Step 2 is the one people miss: without Developer Mode the Copy Channel ID
option does not appear at all.

Use a **forum channel**. Discord ingestion is thread oriented, so a plain text
channel is not what this is for.

## 2. Create the source

`create_discord_source` with `project` and `name`. Keep the returned id.

## 3. Check the channel

`validate_discord_channel` with `channel` confirms the Kapa bot can read it.
It answers HTTP 200 even on failure, with a `type` of `error` rather than
`channel`, so read the body rather than the status.

A failure here means the bot is not in the server, or the channel is not a
forum channel. There is no token to be wrong.

`list_discord_users` then shows who is in the channel, which is how to turn
"our support team" into the `support_user_ids` the config takes.

## 4. Configure it

`set_discord_config` with `source_discord` and `channel_id`.

One source covers one channel.

## Getting good answers out of it

- `support_user_ids` marks whose replies count as answers. Ask which people or
  roles are their support team.
- `include_only_threads_with_support_user_answers` limits ingestion to threads
  one of those people replied to. Ask whether they want that.
- `users_to_exclude` leaves out messages from these user ids, typically bots.
  `list_discord_users` turns names into ids. It lists everyone who can view
  the channel, not only people who posted.
- `thread_age` limits how far back to read, in months: `1m` to `36m`, or
  `all`.

## When it ingests nothing

The Kapa bot is not in the server, or cannot see that channel.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-discourse
description: Set up a Kapa Discourse source so a public forum is ingested. Use when the user wants Kapa to answer from their Discourse community forum.
---

# Set up Discourse

The simplest community source: a public forum needs no credential at all.

## 1. Create the source

`create_discourse_source` with `project` and `name`. Keep the returned id.

## 2. Check the forum and list what it holds

`validate_discourse_url` with `url` confirms the forum is reachable
anonymously. A failure means it is login-walled, and there is no credential
here to fix that.

`list_discourse_categories` and `list_discourse_tags` then show the real
options to offer the user. An empty tag list means the forum has tagging
turned off, so filter by category instead.

## 3. Configure it

`set_discourse_config` with `source_discourse` and `url`, the base URL of the
forum, such as `https://forum.acme.com`.

Ask which parts of the forum to read. `match_categories` and `match_tags`
take what the user picks, and leaving both out reads every topic. Use
`list_discourse_categories` and `list_discourse_tags` to show them the real
options.

Pass categories by **name or slug**, never by numeric id. An id matches
nothing, and ingestion then drops the category filter and reads the whole
forum.

## Getting good answers out of it

Forum threads contain wrong answers as well as right ones, so ask the user
how to handle that:

- `include_solved_only`: keep only topics with an accepted answer, or take
  every topic. Check first whether their forum marks solutions at all, since
  this filter leaves nothing on a forum that does not.

## When it ingests nothing

The forum is not public, or `include_solved_only` is on for a forum that does
not mark accepted answers.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-github-discussions
description: Set up a Kapa GitHub discussions source so repository discussions are ingested. Use when the user wants Kapa to answer from Q&A in GitHub Discussions.
---

# Set up GitHub discussions

Discussions are typically questions with answers, so they read closer to a
knowledge base than issues or pull requests do.

## 1. Create the source

`create_github_discussions_source` with `project` and `name`. Keep the id.

## 2. Configure it

`set_github_discussions_config` with `source_github_discussions`, `repo_owner`
and `repo_name`.

`repo_owner` and `repo_name` together make the repository path. For
`github.com/acme/docs`, the owner is `acme` and the name is `docs`.

`personal_access_token` is **required only for a private repository**. Do not
ask for one for a public repo. If you do need it, it is the user's secret: ask,
never invent one, and tell them it needs the `repo` scope.

## Check the repository first

`validate_github_discussions_repo` with `repo_owner`, `repo_name` and, for a private repo,
`personal_access_token`. It answers HTTP 200 with `false` when the repo cannot
be reached, so read the body rather than the status.

A false covers all of: the repo does not exist, it is private and the token is
missing, or the token lacks the `repo` scope. Offer those to the user rather
than guessing which.

`list_github_discussions_categories` then shows the discussion categories.

## Let the user choose the filters

Show these options and ask. Do not pick for them and do not apply a default
silently.

- `include_only_answered_discussions`: keep only discussions with an accepted
  answer, or take every discussion including unanswered ones.
- `categories`: restrict to specific categories, or leave out for all.
- `discussion_age`: how far back to read, or all history.

Say what each does, then set what they asked for.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-github-files
description: Set up a Kapa GitHub files source so documentation files in a repository are ingested. Use when the user wants Kapa to answer from Markdown or other files in a GitHub repo.
---

# Set up GitHub files

Ingests files from a repository. This is the GitHub source to use when the
repo holds documentation.

## 1. Create the source

`create_github_files_source` with `project` and `name`. Keep the returned id.

## 2. Configure it

`set_github_files_config` with `source_github_files`, `repo_owner`, `repo_name`
and `file_extensions`.

`repo_owner` and `repo_name` together make the repository path. For
`github.com/acme/docs`, the owner is `acme` and the name is `docs`.

`personal_access_token` is **required only for a private repository**. Do not
ask for one for a public repo. If you do need it, it is the user's secret: ask,
never invent one, and tell them it needs the `repo` scope.

`file_extensions` is required, so ask which file types to read. `md` and
`mdx` cover most documentation; source code extensions pull in the code
itself, which some teams want and others do not.

Ask about these too:

- `include_paths`: restrict to a directory, or read the whole repository.
- `ref`: a branch or tag to read, or the default branch.

## When it ingests nothing

A private repo without a token, a `ref` that does not exist, or
`file_extensions` that match no file in the paths you restricted to.

## Check the repository first

`validate_github_files_repo` with `repo_owner`, `repo_name` and, for a private repo,
`personal_access_token`. It answers HTTP 200 with `false` when the repo cannot
be reached, so read the body rather than the status.

A false covers all of: the repo does not exist, it is private and the token is
missing, or the token lacks the `repo` scope. Offer those to the user rather
than guessing which.

`list_github_files_repo_tree` then shows the file tree, so you can show real directories and file types.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-github-issues
description: Set up a Kapa GitHub issues source so repository issues are ingested. Use when the user wants Kapa to answer from problems and solutions discussed in GitHub issues.
---

# Set up GitHub issues

## 1. Create the source

`create_github_issues_source` with `project` and `name`. Keep the returned id.

## 2. Configure it

`set_github_issues_config` with `source_github_issues`, `repo_owner` and
`repo_name`.

`repo_owner` and `repo_name` together make the repository path. For
`github.com/acme/docs`, the owner is `acme` and the name is `docs`.

`personal_access_token` is **required only for a private repository**. Do not
ask for one for a public repo. If you do need it, it is the user's secret: ask,
never invent one, and tell them it needs the `repo` scope.

## Check the repository first

`validate_github_issues_repo` with `repo_owner`, `repo_name` and, for a private repo,
`personal_access_token`. It answers HTTP 200 with `false` when the repo cannot
be reached, so read the body rather than the status.

A false covers all of: the repo does not exist, it is private and the token is
missing, or the token lacks the `repo` scope. Offer those to the user rather
than guessing which.

`list_github_issues_labels` then shows the repository's labels.

## Let the user choose the filters

Show these options and ask. Do not pick for them and do not apply a default
silently: what belongs in a knowledge base differs per team.

- `issue_state`: open, closed, or all. Closed issues carry resolutions, open
  ones carry live problems.
- `issue_age`: how far back to read, or all history.
- `labels`: restrict to specific labels, or leave out for every label.

Say what each does, then set what they asked for.

## What it is good for

Issues answer "has someone hit this before". For "how does this work", use
GitHub files against the docs instead.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-github-pull-requests
description: Set up a Kapa GitHub pull requests source so repository pull requests are ingested. Use when the user wants Kapa to answer from changes and review discussion in GitHub PRs.
---

# Set up GitHub pull requests

Pull request discussion is largely about implementation rather than usage, so
say that when offering it: it suits a team that wants change history, and
suits a user-facing assistant less well.

## 1. Create the source

`create_github_pull_requests_source` with `project` and `name`. Keep the id.

## 2. Configure it

`set_github_pull_requests_config` with `source_github_pull_requests`,
`repo_owner` and `repo_name`.

`repo_owner` and `repo_name` together make the repository path. For
`github.com/acme/docs`, the owner is `acme` and the name is `docs`.

`personal_access_token` is **required only for a private repository**. Do not
ask for one for a public repo. If you do need it, it is the user's secret: ask,
never invent one, and tell them it needs the `repo` scope.

## Check the repository first

`validate_github_pull_requests_repo` with `repo_owner`, `repo_name` and, for a private repo,
`personal_access_token`. It answers HTTP 200 with `false` when the repo cannot
be reached, so read the body rather than the status.

A false covers all of: the repo does not exist, it is private and the token is
missing, or the token lacks the `repo` scope. Offer those to the user rather
than guessing which.

`list_github_pull_requests_labels` then shows the repository's labels.

## Let the user choose the filters

Show these options and ask. Do not pick for them and do not apply a default
silently.

- `pr_state`: which states to read. Merged pull requests describe changes that
  shipped, ones closed without merging describe changes that did not, and open
  ones are still in flight.
- `pr_age`: how far back to read, or all history.
- `labels`: restrict to specific labels, or leave out for all.

Say what each does, then set what they asked for.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-google-drive
description: Set up a Kapa Google Drive source so documents in a Drive are ingested. Use when the user wants Kapa to answer from files in Google Drive or a shared drive.
---

# Set up Google Drive

Connects through OAuth, so the user approves it in their browser.

Unlike the other OAuth sources, the grant belongs to the **signed-in user, not
the source**, and configuring a source uses it up. Connect again for each
Google Drive source, and never run two Google Drive setups at the same time.

## 1. Create the source

`create_google_drive_source` with `project` and `name`. Keep the returned id.

## 2. Connect the Drive

`connect_google_drive` takes no arguments and returns the URL the user
approves at.

**Open that URL in the user's browser** and ask them to approve it.

## 3. Wait for the user, then check once

The approval happens in the browser, so there is nothing to poll. Ask the user
to tell you when they have approved it, then call
`check_google_drive_connection` **once**. It answers with the Google account
that approved, or nothing if they have not finished.

## 4. Choose what to ingest

`list_google_drive_folders` and `list_google_drive_files` show what the
connected account can see. Both answer with at most 20 results, so pass `name`
to search rather than expecting the whole Drive back.

Ask the user which folders or files to ingest, and use these tools to turn
their answer into ids. There is no "everything" option: the source reads only
the folders and files you name.

## 5. Configure it

`configure_google_drive` with `source_google_drive` and the ids:

- `folder_ids_include` and `file_ids_include` take what to read. They add up:
  named files are read on top of the files in named folders.
- `folder_ids_exclude` and `file_ids_exclude` drop things from a wider set.
- Pass at least one folder or file to include. With none, the configuration
  saves but ingests nothing.

No credential travels here. The connection supplies the token and the account
email, so never ask the user for either.

## What gets ingested

Google Docs, Sheets and Slides are read as documents. A file the connected
account cannot open is skipped.

## When it ingests nothing

The approving account cannot see the folders you configured. Drive permissions
belong to the person who approved, so a folder shared with the team but not
with them is invisible. Have the user check their own access before changing
the configuration.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-jira
description: Set up a Kapa Jira source so Jira issues are ingested. Use when the user wants Kapa to answer from their Jira issue history.
---

# Set up Jira

Jira Cloud only. Jira Server and Data Center are not supported.

## 1. Have the user create an API token

https://id.atlassian.com/manage-profile/security/api-tokens. The token carries
that account's own access.

## 2. Create the source

`create_jira_source` with `project` and `name`. Keep the returned id.

## 3. Check the credential and list the projects

`validate_jira` with `base_url`, `username` and `api_token`. It answers three
ways, not two: `true`, `"Unauthorized"` (the credential is wrong) or
`"Not Found"` (the URL is wrong). Tell the user which of the two they need to
fix.

Then `list_jira_projects`, `list_jira_statuses`, `list_jira_resolutions` and
`list_jira_issue_types` show the real options to choose from.

Those four answer with an empty list when something goes wrong, which looks
identical to a site with nothing in it. Trust `validate_jira` for credential
health, not an empty list.

## 4. Configure it

`set_jira_config` with `source_jira`, `base_url`, `username` and `api_token`.

- `base_url` is the site root **without `/wiki`**, such as
  `https://acme.atlassian.net`.
- `username` is the Atlassian account email the token belongs to.
- `api_token` is their secret. Ask for it, never invent one.

Ask the user how to narrow it, rather than choosing yourself:

- `ticket_age`: how far back to read by creation date, in months (`1m` to
  `36m`) or `all`. Left out, this reads every issue ever filed, which on a
  large site is a lot of content.
- `projects_include`: which project keys (such as `ENG`) to read, or all.
- `status_include`, `resolution_include` and `issuetype_include`: the names
  from the matching list tool, to read only resolved bugs, for example.
  Left out, each reads every value.

## What it holds

Jira issues are problem histories, so they answer "has this come up before"
rather than "how does this work". Tell the user that if they are choosing
between sources.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-jira-service-management
description: Set up a Kapa Jira Service Management source so service desk requests are ingested. Use when the user wants Kapa to answer from their JSM request history.
---

# Set up Jira Service Management

## 1. Have the user create an API token

https://id.atlassian.com/manage-profile/security/api-tokens.

## 2. Create the source

`create_jira_service_management_source` with `project` and `name`. Keep the id.

## 3. Check the credential and list the desks

`validate_jira_service_management` with `base_url`, `username` and `api_token`
answers `{"is_valid": bool}`. Read the message back to the user on a failure:
a bad URL, a bad credential and a permissions problem all answer the same way.

Then `list_jira_service_desks` shows the desks, and `list_jira_request_types`
the request types.

The request types cannot be scoped to one desk and carry no desk id, so names
repeat across desks. Show the whole list rather than matching on a name.

## 4. Ask whether to ingest this at all

Service desk requests often carry customer names, email addresses and private
internal comments. Ask whether that content should be ingested at all before
setting this up on a project that serves external users.

## 5. Set PII masking

This source carries customer names, email addresses and account details, so
set masking up front. Setting it later works, since `update_source` queues the
already-ingested items to be reprocessed under the new rules, but that spends
quota re-reading everything. Doing it first avoids the second pass.

Call `update_source` with `markdown_pii_config` first, for example
`{"entities": ["EMAIL_ADDRESS", "PERSON", "PHONE_NUMBER"]}`. The available
entities are PHONE_NUMBER, EMAIL_ADDRESS, PERSON, CREDIT_CARD and IBAN_CODE.
Use `allow_list` for strings that look like PII but should stay, such as a
support alias.

Ask the user what should be redacted. Do not assume, and do not skip this
because they did not raise it.

## 6. Configure it

`set_jira_service_management_config` with `source_jira_service_management`,
`base_url`, `username` and `api_token`.

- `base_url` is the site root, such as `https://acme.atlassian.net`.
- `username` is the Atlassian account email the token belongs to.
- `api_token` is their secret. Ask for it, never invent one.

**Say what the age filter does before accepting it.** `request_age` limits how
far back requests are read, and the dashboard's own default is the last month
only. Tell the user the window you are setting and confirm it, rather than
quietly ingesting four weeks of a multi-year desk.

Ask which desks to read. `service_desk_ids_include` takes the ones the user
picks, and leaving it out reads every desk on the site. Use
`list_jira_service_desks` to show them the real names rather than asking for
ids.

Ask which request types to read as well. `request_type_ids_include` and
`request_type_ids_exclude` take ids from `list_jira_request_types`.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-notion
description: Set up a Kapa Notion source so a Notion workspace is ingested. Use when the user wants Kapa to answer from their Notion pages or databases.
---

# Set up Notion

## 1. The out-of-band setup, which is where this usually fails

Tell the user to:

1. Open https://www.notion.so/profile/integrations and create an internal
   integration.
2. Copy its internal integration secret.
3. **Open each page or database Kapa should read and share it with that
   integration**, from the page's own menu.

Step 3 is the one people miss. The token only reaches pages explicitly shared
with the integration, so a valid token with nothing shared ingests nothing and
reports no error.

## 2. Create the source

`create_notion_source` with `project` and `name`. Keep the returned id.

## 3. Check the token and list what it can see

`validate_notion_workspace` with `api_token` confirms the token works.

**A valid token does not mean it can see anything.** Always follow it with
`list_notion_pages` and `list_notion_databases`: they answer with what was
actually shared with the integration. An empty list here means step 3 of the
integration setup was skipped, not that the token is broken.

Both answer with at most 20 results, so pass `title_contains` to search.

Show the user the real page titles and ask which to ingest, rather than asking
them to find page ids themselves.

## 4. Configure it

`set_notion_config` with `source_notion` and `api_token`. The token is the
user's secret: ask for it, never invent one.

Ask whether to take everything the integration can see, or to narrow it:

- `page_ids_include` takes single pages.
- `page_ids_include_with_children` takes a page **and everything nested under
  it**, which is what to use for a section of a wiki.
- `database_ids_include` takes databases. A database brings in the pages
  connected to it.

A Notion page id is the last part of its URL: the 32 hex characters after the
title.

## When it ingests nothing

The integration has no pages shared with it. Send the user back to step 3
rather than changing the config: the token is fine.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-openapi
description: Set up a Kapa OpenAPI source so an API specification is ingested. Use when the user wants Kapa to answer questions about their API endpoints.
---

# Set up OpenAPI

## 1. Create the source

`create_openapi_source` with `project` and `name`. Keep the returned id.

## 2. Check the specification

`validate_openapi_url` with `url` confirms the document parses.

On success it answers with the spec's title and version, and **there is no
`valid` key**. A failure answers `{"valid": false}`. So treat the presence of a
title as success, not the value of `valid`.

Reading the title back to the user is a cheap way to confirm the URL points at
the spec they meant.

## 3. Configure it

`set_openapi_config` with `source_openapi` and `url`.

`url` must point at the **specification document itself**, the JSON or YAML,
not the documentation page that renders it. Swagger 2.0 and OpenAPI 3.x both
work.

Pass `linked_url` as well. It is the human-readable documentation page, and
without it answers cite the raw specification, which is not useful to a reader.

## Why this often beats crawling the same pages

API reference pages usually render their request and response schemas in the
browser, so a web crawl of them captures only a title and a line of
description. The specification is structured, so it gives cleaner coverage of
every endpoint. If the user is crawling a documentation site that includes API
reference pages, suggest excluding those paths from the crawl and adding this
source instead.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-s3
description: Set up a Kapa S3 source so files in a bucket are ingested. Use when the user wants Kapa to answer from documents stored in S3 or an S3-compatible bucket.
---

# Set up S3

Works with any S3-compatible provider, not just AWS.

## 1. Create the source

`create_s3_source` with `project` and `name`. Keep the returned id.

## 2. Configure it

`set_s3_config` with `source_s3`, `bucket_name`, `endpoint_url`,
`aws_access_key_id` and `aws_secret_access_key`.

- `endpoint_url` is **required even for plain AWS**, such as
  `https://s3.us-east-1.amazonaws.com`. Agents habitually omit it.
- `region_name` is needed by most providers. Use `us-east-1` when the provider
  has no regions.
- `prefix` limits the source to one folder, such as `docs`, with no leading or
  trailing slash. Leaving it out ingests the whole bucket.

Both keys are the user's secrets: ask for them, never invent them. Mention
that the credential only ever needs read access to that one bucket, so they
can scope it accordingly if they want to.

## 3. Check the bucket before saving

`validate_s3_config` with the bucket, endpoint and keys confirms Kapa can
reach it. It answers `{"is_valid": bool, "message": str}`.

**Show the message on a failure before blaming the keys.** It runs three
checks: the endpoint and bucket, the credential's permissions, and whether an
`index.json` in the bucket is well formed. A malformed `index.json` reads
identically to a bad credential unless the message is read. That file is
optional and maps objects to public URLs for citations.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-slack
description: Set up a Kapa Slack source so a Slack channel's threads are ingested. Use when the user wants Kapa to answer from conversations in their Slack workspace.
---

# Set up Slack

## 1. The out-of-band setup, which is where this usually fails

Tell the user to:

1. Create a Slack app at https://api.slack.com/apps and install it to the
   workspace.
2. Copy its **bot token**, which starts `xoxb-`.
3. **Invite the bot into the channel.** A bot that is not a member reads
   nothing, and a private channel requires it.

Step 3 is the one people miss.

## 2. Get the channel id

`channel_id` is the id, not the name. In Slack, open the channel, choose View
channel details, and copy the id at the bottom. It starts with `C`.

## 3. Create the source

`create_slack_source` with `project` and `name`. Keep the returned id.

## 4. Check the token and the channel

`validate_slack_token` with `bot_token` confirms the token itself.

`validate_slack_channel` with `channel` and `bot_token` confirms the bot can
actually read that channel, which is the step that catches a bot that was
never invited. It answers HTTP 200 even on failure, with a `type` of `error`
rather than `channel`, so read the body rather than the status.

`list_slack_users` then shows who is in the channel, which is how to turn "our
support team" into the `support_user_ids` the config takes.

## 5. Configure it

`set_slack_config` with `source_slack`, `channel_id` and `bot_token`. The token
is the user's secret: ask for it, never invent one.

One source covers one channel, so set up several for several channels.

## Getting good answers out of it

Community threads contain wrong answers as well as right ones.

- `support_user_ids` marks whose replies count as answers. This is how Kapa
  tells a maintainer's answer from a guess, so ask which people are their
  support team.
- `include_only_threads_with_support_user_answers` limits ingestion to threads
  one of those people replied to. Ask whether they want that.
- `users_to_exclude` leaves out messages from these user ids, typically bots.
  `list_slack_users` turns names into ids.
- `thread_age` limits how far back to read, in months: `1m` to `36m`, or
  `all`. Old threads often describe versions that no longer exist.

## When it ingests nothing

The bot was never invited to the channel. Check that before changing the config.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-web-crawl
description: Set up a Kapa web crawl source so a documentation site is ingested. Use when the user wants Kapa to answer from a website, documentation site or sitemap.
---

# Set up a web crawl

Three things happen in order: find the right pages, extract the right text from
them, then ingest. The first two are free and repeatable, the third spends the
team's quota. So judge the first two before doing the third.

A source cannot be ingested until it has been previewed with the exact
configuration you intend to ingest with. Changing the crawl config retires the
preview, so a change means previewing again.

## 1. Create the source

`create_web_crawl_source` with `project` and `name`. Name it after the site, such as
"Acme docs". Keep the returned source id.

## 2. Say what to crawl

`set_crawl_config` with `source_scrape` (the source id) and `urls_start`, the
pages the crawl begins from.

- `urls_include` and `urls_exclude` narrow it. Use them when the site holds
  content the user does not want answered from, such as a blog or a changelog.
- `enable_sitemap` follows the site's sitemap. It describes one site, so it only
  applies with a single start URL.
- `render_js` is for a site that builds its content in the browser. It is
  slower, so leave it off until a preview shows thin pages.

Start URLs must be public `http://` or `https://` addresses. A private or
loopback host is rejected, since the crawler cannot reach it.

## 3. Preview the crawl

`preview_crawl` with the source `id` and `page_limit: 50`. Nothing is ingested
and no quota is spent.

Then `get_crawl_status` until it leaves `PENDING` and `IN_PROGRESS`. `SUCCESS`
means it finished, `FAILURE` carries the reason. Poll every couple of seconds
rather than in a tight loop.

`list_preview_pages` with `source_scrape` to see what it found. **Read this
list and judge it**, since nothing else will:

- Pages the user would not want answered from mean `urls_exclude` is needed.
- A section that should be there and is not means `urls_start` or
  `urls_include` is wrong, or the site needs `render_js`.

Fix the config and preview again until the set of URLs is right. Only then move
on. A capped preview reports as much, so raise or drop the limit if 50 pages
were not representative.

To change the config, use `update_crawl_config`, not `set_crawl_config`.
`set_crawl_config` creates one and refuses a second call. `update_crawl_config`
takes the **config id**, which `get_crawl_config` returns, not the source id.

## 4. Settle the content selector

The selector picks the element holding the article text. Everything outside it,
navigation, sidebars, footers, is dropped. Getting this wrong degrades every
answer the source ever gives, and nothing errors.

1. `detect_content_selector` with the source `id`. It recognises common
   documentation platforms and answers with settings, or null if it cannot tell.
   Call it once, not in a loop: it is rate limited. Use its `selector`,
   `selectors_exclude` and `classes_exclude`, and ignore `detected_by` and
   `platform`, which are metadata and must never be saved.
2. `inspect_content_selector` with the `id` and a candidate `selector` renders
   it against real preview pages without saving. Start broad, with `main` or
   `article`, then narrow.
3. **Read the extracted text, both its start and its end.** Navigation or
   "related articles" in the output means the selector is too broad. A nearly
   empty page means it is too narrow, or the page needs `render_js`. Repeat
   until only the article remains.
4. `set_content_selector` with `source_scrape` and the selector you settled on.
   To change it later use `update_content_selector`, which takes the content
   config id rather than the source id.

Keep the headings. Kapa chunks on the breadcrumb that headings form, so a
selector that strips `h1` or `h2` quietly makes retrieval worse.

`selectors_exclude` takes full CSS selectors. Use it for things inside the
article that are not article text, such as an edit link or a banner.

## 5. Ingest

`start_crawl` reads every page it finds and spends the team's quota, so confirm
with the user first.

This is the step that populates the project. A source that is configured but
never crawled answers nothing, so do not stop at step 4.

Afterwards `get_crawl_status` follows it, and `cancel_crawl` stops it.

## Changing a source that is already live

Editing the configuration of a deployed source changes what it serves. Say so
and get the user's agreement before saving.

Extraction changes only take effect by ingesting again, so a new selector on a
live source does nothing until `start_crawl` re-runs.

## When things go wrong

**"Crawl in progress" or a 409.** A crawl is running, or approved pages are
still processing. Nothing clears it from here. Tell the user to wait, and do not
retry in a loop.

**No pages found.** Not an error, a result. The crawl config matched nothing:
check the start URLs are reachable and that the include patterns are not too
strict.

**Pages come back thin.** Their content is built in the browser. API reference
pages often are. Either turn on `render_js` and preview again, or exclude those
paths and add an OpenAPI source instead, with `create_openapi_source` and
`set_openapi_config`. A spec is structured, so it gives cleaner coverage than
any crawl of the rendered page.

**The preview will not start.** The error carries the reason. A failed preview
leaves a draft source behind, so reuse it rather than creating another.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-youtube
description: Set up a Kapa YouTube source so a channel's video transcripts are ingested. Use when the user wants Kapa to answer from their YouTube videos.
---

# Set up YouTube

## 1. Get the channel id, which is the fiddly part

`channel_id` is the raw id starting `UC`, **not a URL and not an @handle**.
There is no lookup, so a handle will simply find nothing.

If the user has a `youtube.com/channel/UC...` URL, take the `UC...` segment. If
they only have an `@handle`, tell them to open the channel and find the id in
the page source, since only the channel owner sees it directly.

## 2. Create the source

`create_youtube_source` with `project` and `name`. Keep the returned id.

## 3. Check the channel and list its playlists

`get_youtube_channel` with `channel_id` confirms the id resolves, and answers
with the channel title. Read that back to the user: it is the only way to
catch a `UC` id that is valid but not theirs.

A 404 means the id is wrong. There is no way to search by name, so ask the
user to re-copy it.

`list_youtube_playlists` then shows the real playlists to choose from.

## 4. Configure it

`set_youtube_config` with `source_youtube` and `channel_id`.

Ask whether to restrict to specific `playlists`, which matters when a channel
mixes tutorials with marketing or conference recordings. Leaving it out
ingests every video on the channel.

## What gets ingested

Transcripts only. A video with no captions contributes nothing and is skipped
silently, so a channel of caption-less videos produces an empty source with no
error. Say this to the user before setting it up.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step,
so once the config saves the source is live.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-zendesk-helpcenter
description: Set up a Kapa Zendesk Help Center source so help center articles are ingested. Use when the user wants Kapa to answer from their Zendesk knowledge base.
---

# Set up Zendesk Help Center

Connects through OAuth, so the user approves it in their browser.

## 1. Create the source

`create_zendesk_helpcenter_source` with `project` and `name`. Keep the id.

## 2. Start the connection

`connect_zendesk_helpcenter` with the source `id` and the user's `subdomain`,
the first label of their zendesk.com host. For `https://acme.zendesk.com` that
is `acme`.

It returns an `auth_url`. **Open it in the user's browser** and ask them to
approve it there.

## 3. Wait for the user, then check once

The approval happens in the browser, so there is nothing to poll. Ask the user
to tell you when they have approved it, then call
`check_zendesk_helpcenter_connection` **once**. It answers with the connection,
or null if they have not finished.

## 4. Configure what it ingests

`configure_zendesk_helpcenter` with `auth_method` set to `oauth`. Without that
the grant is never attached and the source has no credential.

`url` is the **API root, not the browser URL**. Take the part before `/hc` and
append `/api/v2`, and put the locale in `language_code`. So
`https://acme.zendesk.com/hc/en-us` becomes `url=https://acme.zendesk.com/api/v2`
and `language_code=en-us`. Putting the locale in both doubles it in every
ingested link.

Ask which parts of the help center to read. `include_categories` and
`include_sections` take what the user picks, and leaving both out reads the
whole help center.

## Notes

The grant belongs to whoever approves it, so only that person can configure the
source afterwards.

An "invalid authorization request, no such client" error is a Zendesk-side
configuration problem, not something to retry. Tell the user their Zendesk
account needs the Kapa OAuth client registered.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.

View saved version →

---
name: kapa-setup-zendesk-tickets
description: Set up a Kapa Zendesk tickets source so support tickets are ingested. Use when the user wants Kapa to answer from their Zendesk support history.
---

# Set up Zendesk tickets

Connects through OAuth, so the user approves it in their browser.

## 1. Create the source

`create_zendesk_tickets_source` with `project` and `name`. Keep the id.

## 2. Start the connection

`connect_zendesk_tickets` with the source `id` and the user's `subdomain`, the
first label of their zendesk.com host. For `https://acme.zendesk.com` that is
`acme`.

It returns an `auth_url`. **Open it in the user's browser** and ask them to
approve it there.

## 3. Wait for the user, then check once

The approval happens in the browser, so there is nothing to poll. Ask the user
to tell you when they are done, then call `check_zendesk_tickets_connection`
**once**.

## 4. Ask whether to ingest this at all

Support tickets routinely contain customer names, email addresses and account
details. Ask whether that should be ingested at all before setting this up on
a project that serves external users.

## 5. Set PII masking

This source carries customer names, email addresses and account details, so
set masking up front. Setting it later works, since `update_source` queues the
already-ingested items to be reprocessed under the new rules, but that spends
quota re-reading everything. Doing it first avoids the second pass.

Call `update_source` with `markdown_pii_config` first, for example
`{"entities": ["EMAIL_ADDRESS", "PERSON", "PHONE_NUMBER"]}`. The available
entities are PHONE_NUMBER, EMAIL_ADDRESS, PERSON, CREDIT_CARD and IBAN_CODE.
Use `allow_list` for strings that look like PII but should stay, such as a
support alias.

Ask the user what should be redacted. Do not assume, and do not skip this
because they did not raise it.

## 6. Configure what it ingests

`configure_zendesk_tickets` with `auth_method` set to `oauth` and the same
`subdomain`. Without the auth method the grant is never attached.

Show these options and ask which the user wants. Support tickets are usually
the largest source a team has, so say what each filter would leave out rather
than applying one silently.

- `ticket_age`: how far back to read, or all history.
- `statuses` and `priorities`: which tickets to read, or all of them.
- `tags`: only tickets carrying these tags. `tags_exclude` drops tickets
  instead.

## Notes

The grant belongs to whoever approves it, so only that person can configure the
source afterwards.

## Finish the job

Saving the configuration starts ingestion. There is no separate publish step.

Then call `list_sources` with `project_id` to confirm what the project holds.

## Shared Kapa workflow rules

Tools act as the connected user with that user's project permissions. Resolve the intended project and use only authorized data. Do not invent credentials, source IDs, filters, or tool results. Check the available tool schema before passing arguments.

Explain and obtain approval for ingestion and its quota cost before saving a configuration that starts ingestion or calling `start_crawl`; existing explicit approval for that exact action is sufficient. Ask the user to choose source scope and filters. Validate credentials and discover accessible content before saving. Keep credentials out of visible results, logs, and exported artifacts. Use a secure credential input if the host provides one.

For a web source, preview the exact configuration and inspect the extracted article content before ingestion. Report queued, running, failed, and completed states accurately. If uncertain about Kapa behavior, use `search_kapa_docs` when available.