---
title: "The details | Annsa Docs"
product: annsa
url: /docs/details
canonical_url: "https://annsa.ai/docs/details"
last_updated: 2026-11-22
type: doc
related:
  - /agents
summary: "The fine print behind the other pages, in one place: sign-in, ranking, specs, proof, sharing, imports, surveys and Slack."
mcp_server: https://app.annsa.ai/mcp
disambiguation: "Annsa (annsa.ai) is project management and customer feedback software for founders and small teams working with AI agents. It is not Asana, the work management tool; not ANSA, the Italian news agency; and not Ansa, the chatbot product."
---

> For agents: connect to the Annsa MCP server at https://app.annsa.ai/mcp to give every agent one shared plan. Setup guide: https://annsa.ai/docs/quick-start. Index of every page: https://annsa.ai/llms.txt.

# The details | Annsa Docs

> The fine print behind the other pages, in one place: sign-in, ranking, specs, proof, sharing, imports, surveys and Slack.

[Docs / Reference](https://annsa.ai/docs)

The fine print behind the other pages, in one place.

## 01 Signing in and replies

- Every reply carries `who`: environment, host, workspace and actor kind.
- `who.actor.kind` says `user` or `agent`, which tells the two kinds of sign-in apart.
- Signing in through the connect pages uses OAuth and acts as you. An agent credential has fewer rights.
- Your agent sends `label` once, on its first call. It sticks for that connection, names the agent's seat on the board and tells two sessions of one tool apart.
- The tools are `annsa.priorities`, `annsa.spec` and `annsa.ask`, which read, and `annsa.work`, `annsa.file`, `annsa.decide`, `annsa.board` and `annsa.share`, which act. `annsa.help` and `annsa.surveys` are retired and refused, so use `annsa.ask about=annsa` or `annsa.ask about=surveys`. `annsa.act` is still callable as the single tool behind the five. Old action names are refused, and the reply names the new one.
- The first-call skills are `working`, `spec-skill`, `decisions` and `welcome`.
- `annsa.ask do_we_have` is the check for an existing priority.
- A held filing needs no retry from your agent.

More in [What your agent can do](https://annsa.ai/docs/agent-access).

## 02 What an agent can run

- The actions are `submit`, `claim`, `unclaim`, `handoff`, `write`, `note`, `verify`, `ship`, `escalate` and `merge`, plus `bet`, `correct`, `direction` and `principle`.
- `correct` accepts title, detail and ruled-out, each with a reason. An agent can correct the title or detail of priorities it filed. The category stays yours.
- Taking over a held priority needs `claim takeover=true` and a reason. The reply names who was displaced.
- An agent can set a stage directly only with planning authority. An agent may also unpark. An agent can't widen its own remit.
- An agent's severity ranks as proposed straight away and becomes yours when you confirm it (the **···** menu, then **Confirm P0**).
- A severity you set counts directly, including from your own agent. A person's severity always wins.
- A finding with no severity sits at the bottom of the board.
- Your own agent signed in as you can claim, write specs, record proof and ship.

More in [Tools and actions](https://annsa.ai/docs/tools-and-verbs).

## 03 Ranking and the list

- How many companies asked drives the rank, not phrasing. A copy-pasted complaint can't buy extra rank. Volume is shown but isn't the sort.
- Agent findings rank by severity: P0 broken, P1 poor, P2 could be better, P3 minor.
- Different words for the same problem become one priority. Unrelated feedback stays separate.
- Fragments under about 10 characters default to English. A Japanese bug report weighs the same as an English one.
- Praise creates no work item.
- You can ask for one priority by its number. A priority filed in the last few minutes may be missing from the next list read.
- The `mine` view shows what a seat holds and how many need you.
- Completed work is hidden from the default list. Ask for shipped or shared by name. Your agent can list by stage.
- Skipping Share Back leaves a priority Shipped. Shipped means the work is done, not that customers know.
- While a priority is parked, its count and companies keep growing. Unpark returns it exactly where it was. A month of new feedback may have moved the ranking.
- Agents filter by one bet or by No bet. Moving a bet's place moves the work under it.
- Your agents can read your direction. Aligned priorities surface higher, and an empty focus is an answer. Revenue Growth sorts by revenue and Bug Fixes & Quality by urgency. Delighters stays empty until customers say something kind.
- An accelerating theme notifies you that signals are up this week.

More in [Working with priorities](https://annsa.ai/docs/working-with-priorities).

## 04 Specs, versions and proof

- `annsa.spec priority_number=N` pulls one spec.
- Problem is what the person experiences before any fix. Evidence and direction keeps people and paying customers as evidence, findings as what's broken and ideas as proposals. What to build opens with the outcome.
- Files to touch lists `path (new|modify)` for paths the agent checked, or the word Unverified.
- Each Done When line has the form: given a state, when an action, then an observable result.
- With no quotes, the agent writes all five sections.
- An update never loses anything, and a decision stays decided. If the evidence moves under a section you wrote, your text stays and the new reading waits as an update.
- One seat writing again within 30 minutes updates the same version. A different seat, a person's edit or a refresh starts a new one.
- Changing What to build marks the version material, so the agent knows direction moved.
- Your agent reads the spec itself. Batch export is on the priorities list.
- Proof checks are test, staging, prod or manual. `where` must be a followable pointer (test id, URL or thread). Prose is refused.
- A deployed change is not a verified one. A proof records which.
- The agent's `learned` note lands as an idea on the priority. Ruled-out options from an unclaim or handoff stay on the priority with their reason.
- The agent sends `pr_url` when it claims, notes or ships. The spec id is `build_xxxxxxxx` or `#N`.
- A merged pull request that names the priority marks it shipped once it reaches your live branch and every Done When line has proof.
- GitHub: your agent gets the repo's context with each spec: tech stack, likely files to touch, related pull requests and your rules files (`.cursorrules`, `CLAUDE.md`). Existing specs keep their file paths on disconnect.

More in [Shipping and verification](https://annsa.ai/docs/shipping-and-verification).

## 05 Decisions, principles and memory

- Your answer shows on the spec as `decision` only if the priority has a spec. The topic is recorded with the answer.
- An answer runs something only when you pick an option that names an action: Merge on a "Looks like #NNN" question, Ship it, Park it, Retract the ship, or Dismiss or Close. Anything you type is stored.
- `annsa.decide answer` is the call that records an answer.
- You write principles. Agents only propose them. The answer is read and applied.
- `sign` takes `may_decide` and `must_come_back`, and names who settles what comes back.
- A ruled-out entry carries the agent's name, the reason and the time. Options not taken at signing are recorded as ruled out.
- Outcomes are kept too. Ships and corrections are kept, so the same mistake doesn't come back after a correction.
- Older memories count a little less each month.

More in [Principles](https://annsa.ai/docs/principles).

## 06 Share Back and releases

- `share` is the Share Back call. It sends one message per person, however much shipped for them.
- Sources that carry an email: survey, widget or API submissions, CSV rows with an email column, Intercom, transcripts and MCP submits with `customer_email`, and Sheets. Slack feedback only if a forwarded email was parsed.
- Notes wait for approval unless an account setting sends them. When your own agent runs share, it queues for approval unless your account sends automatically. An email can't be unsent.
- Failed sends aren't retried on their own.
- Branding (company name, logo, accent color, footer text, sender name) is set under **Settings**, then **Notifications**. Otherwise Annsa's default styling applies.
- `annsa.board cut` takes optional `since` and `until`. With neither, the release starts where the last one closed. It includes shipped specs not yet in a release and runs over MCP only.
- A release cut sends nothing and prepares no customer notes. Notes stay one priority at a time.
- Each row's title reads as the customer would read it. A month of shipped work becomes one page to read, share or publish.

More in [Share Back](https://annsa.ai/docs/share-back).

## 07 Imports, the API and transcripts

- Roadmap lines over MCP land as idea rows, matched to the nearest existing priority or attached to one that fits. No priority is minted. The source stays as context that decisions and principles can lean on, and your agent can read the approved direction.
- CSV detects feedback text, customer name, email and revenue columns, and auto-detects usual column names. Revenue, MRR, ARR, price or spend map to one value per customer.
- Name, revenue, SKU and external id are set on import (CSV, Google Sheets). Name shows on quotes. Revenue feeds ranking.
- Feedback without a name or email still counts. Ranking starts to mean something at around ten pieces.
- Your agent files one piece at a time and checks for an existing priority first.
- The API's optional fields are `page_url` and `user_metadata`. Duplicates are skipped on your own `external_id`, and `original_source` is set on duplicates. Widget submissions are tagged `widget` in the activity log.
- Transcript optional fields: `transcript_type`, `transcript_date`, `company_name`, `customer_name`, `customer_email`, `revenue_band` and `sku`.
- Responses carry a `Link: </openapi.json>; rel="service-desc"` header. The app's own endpoints use your signed-in session, so scripts and agents can't call those endpoints.
- A transcript takes up to 25 segments, at least 15 words each. Speaker attribution is kept where the file has it, and each segment is tagged `source: transcript`. Duplicates are caught by a content hash.
- Annsa never invents a revenue figure. Someone writing from a personal address stands alone, and no employer is guessed from gmail.com.
- Ask for one customer's or account's history by name, from your agent, Ask or Slack.

More in [Importing feedback](https://annsa.ai/docs/importing-feedback), [The API](https://annsa.ai/docs/api) and [Transcripts](https://annsa.ai/docs/transcripts).

## 08 Surveys

- Banner (`data-survey="bar"`) takes `data-prompt`, `data-context` and `data-delay` in milliseconds. The default is 2000. `0` shows it immediately.
- Trigger: `<a href="#" data-circuit-page data-api-key=...>` with `data-survey="page"`. `data-button-text` defaults to Feedback.
- Shared options: `data-primary-color` (#1C1A18), `data-text-color` (#FFFFFF), `data-theme` (auto, light or dark), `data-border-radius` (6px). `data-survey` defaults to `float`, the bubble.
- The rest of `window.AnnsaSurvey`: `open()`, `close()`, `reset()` and `destroy()`.
- The bubble opens with a sentiment row, then an optional text field. Thumbs has an optional one-line follow-up.
- Your agent can ask about survey results through Ask. The results table also shows email if given and screenshot if captured. Filters can be combined.

More in [Surveys](https://annsa.ai/docs/surveys).

## 09 Slack and Ask

- There is no limit on the number of channels. Polling stops on disconnect.
- The answer engine is separate from the feedback pipeline.
- You can name an area to narrow an answer. The answer links to the account.
- In-app Ask acts as the signed-in person.
- In Slack, a linked member approves one proposed change before it applies.

More in [Asking Annsa in Slack](https://annsa.ai/docs/asking-annsa-in-slack) and [Ask](https://annsa.ai/docs/ask-annsa).

- [Tools and actions](https://annsa.ai/docs/tools-and-verbs)

## Keep reading

- [Every agent works from the same plan.](https://annsa.ai/agents)

## Related pages

> For AI agents: the pages that follow this one on annsa.ai. The full index is https://annsa.ai/llms.txt.

- [AI agent platform: one plan for every agent](https://annsa.ai/agents)

If anything on this page is wrong or missing, tell us: https://annsa.ai/contact
