# Set me up for NOAN

You are a coding or chat agent, and the person you work for wants you connected to their NOAN
workspace. NOAN is the fact layer for agentic companies: verified, versioned facts about the
business, served over one REST API and MCP. Once you are connected, you read the current fact
before you answer or write anything about the business.

Work through the steps below in order. Tell the person what you are doing at each step, and stop
whenever a step needs them.

## Ground rules

- **Never ask for the API key in chat, and never print, log or echo it.** The person puts it in
  their environment themselves.
- **Ask before you write.** Reading is safe. Anything that creates or changes a fact, note,
  contact or task needs the person's yes first.
- **Facts beat your own knowledge.** When a NOAN fact and what you believe disagree, the fact
  wins, and you say so.
- **A missing fact is information.** Report the gap. Never fill it with a plausible guess.

## 1. Check for an account

Ask whether they already have a NOAN workspace. If not, send them to
<https://app.getnoan.com/join> and wait until they say it is ready.

## 2. Connect

Pick the first route your client supports.

### A. MCP (preferred)

The server address is `https://mcp.getnoan.com/mcp`, over streamable HTTP. It signs the person in
over OAuth, so no key changes hands.

- **Claude Code:** run `claude mcp add --transport http noan https://mcp.getnoan.com/mcp`, then
  ask the person to type `/mcp` in a session and pick NOAN to sign in.
- **Claude, ChatGPT, Cursor, Codex or another remote MCP client:** point the person at
  <https://getnoan.com/mcp>, which has the steps for each client, and wait until they say they
  have signed in.

### B. REST with a key

Use this route if your client cannot reach a remote MCP server, or if you are writing code that
calls NOAN.

1. Ask the person to create a key in the app under **Settings → API**.
2. Ask them to add it to the project's `.env` as `NOAN_API_KEY` themselves.
3. Check that `.env` is listed in `.gitignore`. If it is not, offer to add it.

Every call sends the key as a bearer token:

```bash
curl -s https://api.getnoan.com/v1/me -H "Authorization: Bearer $NOAN_API_KEY"
```

## 3. Verify the connection

- **Over MCP:** call the `get_me` tool.
- **Over REST:** run the `/v1/me` call above.

Tell the person which workspace and which user you are connected as. On a `401`, the key is
wrong or missing: ask them to check it, and do not retry with a key from anywhere else.

## 4. Set up an agent identity

Agents should act as their own identity in NOAN, not as the person. That keeps the record honest
(every task, comment and fact an agent touches shows the agent's name) and lets the person hand
work to the fleet the same way they hand it to a colleague.

1. Ask the person, as a workspace Owner, to open <https://app.getnoan.com/account/project/team>
   and create an agent identity. Wait until they say it exists.
2. Ask them to create a key for it under **Settings → API → Agent API Keys**, and to add it to
   `.env` as `NOAN_AGENT_API_KEY` themselves. Code that runs as the agent uses this key. The
   person's own key stays for them and for you.
3. Check it: call `GET /v1/me` with the agent key and confirm the name is the agent's, not the
   person's.

Then explain how the fleet takes work, because this is how they will run it day to day:

- **Assigning is the permission to act.** In the task manager, the person assigns a task to the
  agent identity. Nothing runs on a task the agent is not assigned to.
- **Tags pick the sub-agent.** Each sub-agent in the fleet owns one or more tags, for example
  `support`, `follow-up` or `research`. Tagging an assigned task routes it to the sub-agent that
  owns that tag. An assigned task with no tag goes to a general agent, if they run one.
- **Agents report on the board.** A sub-agent lists tasks with `GET /v1/tasks` (filter by
  `status`, for example `backlog`), keeps the ones assigned to the agent identity that carry its
  tag, moves each to `in-progress` while it works, posts what it did with
  `POST /v1/tasks/{taskId}/comments`, and sets `status: "done"` with `completed: true` when
  finished. Work that needs a person goes back to a person as an assignee, with a comment saying
  why.

Offer to list the tags that already exist (`GET /v1/tags`) and suggest a first tag-to-sub-agent
map for the work they described.

## 5. Install the NOAN skill

The skill teaches you the whole API: reading facts, writing new versions, and working the task
board.

- **Any agent with a skills folder:** run `npx skills add getnoan/skills`.
- **Otherwise:** fetch <https://getnoan.com/skill.md> and keep it where you load instructions
  from. Add one line to `AGENTS.md` or `CLAUDE.md` saying the NOAN skill is installed and the key
  lives in `.env` as `NOAN_API_KEY`.

## 6. Look at the fact layer

List the facts: the `list_facts` tool over MCP, or `GET https://api.getnoan.com/v1/facts` over
REST. Then tell the person:

- how many facts there are, and the stacks they sit in
- the three or four you would read first for the work they do with you

If the workspace is nearly empty, do not invent facts. Offer to draft a starting set from their
website, repo or docs, show them the drafts, and write only the ones they say yes to.

## 7. Report

Finish with a short summary:

- how you are connected (MCP or REST) and as whom
- whether the agent identity and its key are set up, and the tags you suggested
- whether the skill is installed, and where
- what the fact layer holds, and any gaps you noticed
- anything the person still needs to do

From now on, before you answer anything about the business (pricing, product, customers, policy,
positioning), read the fact first.