# Senso

> The context layer for AI agents. Put your approved sources in one place, check what
> models say against them, and publish what you can stand behind.

If you are an AI agent and your user asked you to get them started with Senso, follow these
steps in order before anything else here. Run every command yourself. Ask your user only for
what needs a person: which use case they want if they have not said, creating their account,
and approving this machine in their browser. Never ask them to paste an API key into the conversation; signing in happens in
their browser, and the key goes straight to this machine.

Your user may not be technical. The first time you use one of these words with them, say what it
means in the same message, before they have to ask:

- Senso: the service behind docs.senso.ai. It keeps a team's knowledge in one place so AI
  assistants can work from it, and checks what AI search says about a company.
- Organization: a team's or company's shared space in Senso. Everything saved belongs to one,
  and colleagues can be invited into it.
- Approve or authorize: clicking a button on Senso's own site to say this computer may use their
  Senso account. No password is shared with you.
- Admin: someone allowed to manage an organization. Only an admin can approve a computer.
- Skills: instructions that teach you how to do Senso tasks.

Do not say CLI or API key to them: say the Senso tool on this computer. If your user is clearly
technical, skip the explanations.

Wherever your user has to choose, ask with your tool's multiple-choice question if it has one
(in Claude Code, AskUserQuestion), offering the options given at that point; with no such tool,
ask in plain text and list the options. If they answer with something that is not one of the
options, go by what they said.

**1. Install the Senso CLI.** Check with `senso --version`. If it is missing, install it. It
needs Node.js 22.12 or later.

```bash
npm install -g @senso-ai/cli
```

**2. Check whether this machine is already signed in.**

```bash
senso whoami --output json
```

If it exits `0`, the machine is signed in, and `orgName` in the output names the organization.
Ask your user whether that is the one they mean. Options: yes, use that organization; or no, a
different or new one. If it is, go to step 7. If not, run
`senso logout` and carry on. If it exits `3` with `"code": "unauthorized"`, the machine is not
signed in: carry on. Use `senso whoami` for this, not `senso login`, which on a machine with no
key starts an approval straight away.

**3. Ask whether they have a Senso account.** Ask your user: "Do you already have a Senso
account, or are you new to Senso?" Options: I already have an account; or I am new to Senso. If they have one, go to
step 5. If they are new, or are not sure, ask: "Did someone invite you to join their
organization on Senso, for example a colleague who sent you an invite by email? Or are you
setting up Senso for yourself?" Options: a colleague invited me; or I am setting it up for
myself.

If they were invited, they already have an account, even though they never signed up: it was
made when they were invited. Go to step 5, and tell them that when the approval page asks
them to sign in, they should use the email address they were invited at. Senso sends a one-time
code there, so there is no password. If the page asks them to choose an organization, it is the
one they were invited to.

If they are starting fresh, go to step 4.

**4. If they are starting fresh, sign them up.** Only someone starting fresh does this
step. Anyone with an account, invited or not, goes straight to step 5.

Settle the use case first, because each has its own sign-up link. Senso is used in two ways:

| Use case | What it does | Skill |
|---|---|---|
| Shared Context | One agent knows what all your other agents know. Each saves what it learns, and the next one starts from it. | `senso-shared-context` |
| Verification Loop | Find the AI search questions where competitors are named and you are not, then publish answers checked against your own documents. | `senso-verification-loop` |

If your user's request already named one of them, that is the use case: do not ask again. If it
named neither, ask them which they want to set up. Options: one per use case, each described as
above.

Then ask them to create an account with the sign-up link for their use case, and to tell you
when they have finished:

| Use case | Sign-up link |
|---|---|
| Shared Context | https://docs.senso.ai/sign-up?redirect_url=%2Fonboarding%3Fnext%3D%2Fdocs%2Fshared-context-quickstart |
| Verification Loop | https://docs.senso.ai/sign-up?redirect_url=%2Fonboarding%3Fnext%3D%2Fdocs%2Fverification-loop-quickstart |

Sign-up asks for their name and email and sends a one-time code, so there is no password.
For Shared Context, sign-up then creates their organization without asking anything more, with them as its admin. For Verification Loop, sign-up then asks for their organization’s name, which is what Senso looks for in AI answers, and their website, which is optional. That creates their organization, with them as its admin. They have finished when they reach the "Shared Context Quickstart" or "Verification Loop Quickstart" page, under
"Get started building with Senso". That page shows a setup prompt; tell them they do not need to
copy it, because you are already doing what it does. If sign-up says "You already have an account
with this email", they have one: go to step 5. Do not start step 5 until they tell you
they have finished. The approval link it opens expires five minutes after it is made, which is
less time than signing up can take.

**5. Sign this machine in.** Before you run anything, tell your user in plain words what is
about to happen. The link the command opens is only good for five minutes, and that time should
not go on explanations. A Senso page will open in their browser. If it asks them to sign in, they
enter their email and the one-time code Senso sends there. It then shows their organization on a
button that says "Continue with" its name, and after that an "Authorize" button. If they want a
new organization rather than one they already have, they choose "Create a new organization" instead: a link just under the organization's name on
that page. It opens a form that asks for a name and an optional website; its "Create
organization" button makes the organization, and the approval carries on in it. Ask them to approve it only because they asked you to set Senso up. Wait until they say they
are ready, then run:

```bash
senso login --output json
```

In a shell with no terminal attached, which is how most agents run commands, this opens the
approval page in your user's browser and exits at once. Its output has `verificationUriComplete`
(the approval link, with the code already in it), `browserOpenAttempted` (whether it tried to
open the browser; it cannot tell whether a window appeared), `expiresAt` and `nextCommand`. Tell
your user the page is open, and give them the `verificationUriComplete` link in case it did
not open. Before they click "Authorize", check with them that the organization named on the
"Continue with" button is the one they want this machine signed in to. Options: yes, that is the
one; or no, a different one. If it is not, they can switch: under the label "Organization", they click the
box showing the organization's name, and pick another from the list that opens. Then, straight away, run this in the
background:

```bash
senso login --complete
```

It waits for the approval and stores the key on this machine. When it exits `0`, the machine is
signed in. Your user's browser says "Authorized" and "Return to your terminal"; tell them that
means coming back to you. In an interactive terminal, `senso login` opens the browser and waits
in the same command, and there is no second one to run.

**6. If the approval does not go through.**

| What happened | What to do |
|---|---|
| The page says "You don't have permission to authorize API access" | Your user is not an admin of that organization, which is usual for someone who was invited. Only an admin can sign a CLI in, because the key it gets has full access to the organization. Tell them so plainly, and ask which they want. Options: choose another organization where they are an admin, by clicking the box under "Organization" that shows the current name; create a new one with "Create a new organization" on that page; or ask an admin of this one to make them an admin. Waiting on an admin can take a while, so do not hold the approval open for it: ask them to tell you once an admin has confirmed the change, whenever that is. Then run step 5 again and give them the link it prints to open; reloading the approval page they already have open does not bring the request back. |
| The page says "You need an organization first" | They have an account but no organization. Ask them to choose "Create an organization" on that page; the approval carries on once it is created. |
| `senso login --complete` fails with `device_expired` | Five minutes passed. Run step 5 again for a new link. |
| `senso login --complete` fails with `device_denied` | The request was refused in the browser. Start again only if your user wants to. |
| `senso login --complete` says there is no login waiting | Run `senso login` first, and run both the same way: if one ran under `sudo`, so must the other. |

Running `senso login` again while a link is still waiting reuses that link, so your user is
never left holding a code that no longer works.

**7. Confirm, then start their use case.** Run `senso whoami --output json` and tell your user
which organization this machine is signed in to. The key lasts seven days; after that, commands
fail with an authentication error, and `senso login` repeats steps 5 and 6. Then install the
Senso skills:

```bash
senso setup
```

If the use case is not settled yet, settle it now: someone who signed in rather than signing
up has not been asked. If their request named one, that is it. Otherwise ask which they want to
set up, with one option per use case, each described as in step 4. If they are not sure, and they joined an
organization that already existed, someone on their team will know which one it uses. If they
created the organization during this setup, there is no team to ask yet: describe the two again
in plain words and help them choose. Then use its skill: `senso-shared-context` for Shared Context, or `senso-verification-loop` for Verification Loop.

Each link below is the page as markdown. Drop the .md for the page itself.

## Documentation

- [Agent Skills](https://docs.senso.ai/docs/agent-skills.md): Install the Senso skills so your agent can run the Verification Loop, keep your team's shared context, and work with your knowledge base.
- [AI Visibility Analytics](https://docs.senso.ai/docs/analytics.md): What AI models said about you — mention rate, share of voice, and the three citation metric families, with the raw counts behind every number.
- [Blog-to-Social Converter](https://docs.senso.ai/docs/blog-to-social.md): Ingest a blog post as a raw source, compile it into your knowledge base, and generate verified social content.
- [CLI Reference](https://docs.senso.ai/docs/cli-reference.md): Every Senso CLI command and flag, grouped by what you use it for.
- [Connect Your Agent](https://docs.senso.ai/docs/connect-your-agent.md): Choose what you are setting up. Each quickstart is one prompt: your agent installs Senso, signs you in and starts that use case.
- [Core Concepts](https://docs.senso.ai/docs/concepts.md): The parts of Senso and how they fit together — the knowledge base and its nodes, search, gaps, industries and prompts, the brand kit, content types, product lines, and the content Senso writes.
- [Errors](https://docs.senso.ai/docs/errors.md): Every status the Senso API returns, what causes it, and what to do about it.
- [Help-Center Crawler](https://docs.senso.ai/docs/help-center-crawler.md): Crawl a docs site, ingest every page as raw sources, compile a knowledge base, and query it from your terminal.
- [Limits](https://docs.senso.ai/docs/limits.md): Rate limits, paging, and the size and format of files you can upload.
- [OpenAI Agents SDK](https://docs.senso.ai/docs/openai-agents-sdk.md): Give an OpenAI agent one narrow tool onto your knowledge base, then verify its answer against the sources the tool actually returned.
- [Overview](https://docs.senso.ai/docs/overview.md): One source of truth for your organization. Your agents answer from it, and AI search is checked against it.
- [Permissions](https://docs.senso.ai/docs/permissions.md): What each role can do, who can reach which files and folders in your knowledge base, and what happens when access is denied.
- [Send your first API request](https://docs.senso.ai/docs/quickstart.md): Check your key, add a document to your knowledge base, and ask it a question, then retrieve the same passages for your own model.
- [Senso CLI](https://docs.senso.ai/docs/senso-cli.md): Install it, point your agent at it, and run the loop from a terminal. Commands grouped by the step they belong to.
- [Shared Context](https://docs.senso.ai/docs/shared-context.md): How a team and its agents build on each other's work in Senso — save what you learn, start from what the team knows, and settle what nobody has answered yet.
- [Shared Context Quickstart](https://docs.senso.ai/docs/shared-context-quickstart.md): Give an AI agent access to Senso, and create a knowledge base that agents can use.
- [Use Cases](https://docs.senso.ai/docs/use-cases.md): What you can do with a Senso context layer today: share it across a team and their agents, and check what AI answers against it.
- [Verification Loop](https://docs.senso.ai/docs/use-cases/verification-loop.md): Find the AI questions in your industry where a competitor is named and you are not, answer them from your own documents, and publish a page every line of which is checked against them.
- [Verification Loop Quickstart](https://docs.senso.ai/docs/verification-loop-quickstart.md): See how AI models answer questions in your industry, and publish verified answers they can cite.
- [Verify AI ads](https://docs.senso.ai/docs/use-cases/verify-ai-ads.md): Prepare campaign copy from the same sources, review every checkable claim, and test the follow-up questions a prospect will ask after the click.
- [Why Senso](https://docs.senso.ai/docs/why-senso.md): Senso answers from your own documents, checks what is said about you against them, and turns what is missing or wrong into gaps you can close.
- [Working with API Keys](https://docs.senso.ai/docs/api-keys.md): How Senso API keys work, what a key can reach, and how to create, restrict, rotate and revoke one.
- [x402 Payments](https://docs.senso.ai/docs/x402.md): Put a per-request paywall in front of your knowledge base so other people's agents can buy verified answers, no account required.

## Reference

- [OpenAPI specification](https://docs.senso.ai/specs/sdk-api.yaml): every endpoint, request and response
- [Citation metrics glossary](https://docs.senso.ai/specs/metrics-glossary.md): the canonical definition of every citation metric, with its denominator
- [API reference](https://docs.senso.ai/api-reference): the spec, rendered

## Optional

- [Full text of every page](https://docs.senso.ai/llms-full.txt)