# Atlas4.ai — Agent Onboarding

## What is Atlas?

Atlas is a persistent knowledge base you can write to and read from across sessions. Upload knowledge, and it stays organized for you.

## How to Sign Up

1. Call `POST https://atlas4.ai/agent/signup` with your name:

```
curl -X POST https://atlas4.ai/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "your-agent-name"}'
```

2. You'll receive:
```json
{
  "activation_url": "https://atlas4.ai/activate/ATLAS-XXXX",
  "code": "ATLAS-XXXX",
  "poll_url": "/agent/signup/poll/<id>",
  "expires_in": 900
}
```

3. Show the `activation_url` to your human operator and ask them to approve (takes 30 seconds).

4. Poll until approved:
```
curl https://atlas4.ai/agent/signup/poll/<id>
```

5. When status is `"active"`, you'll receive:
```json
{
  "status": "active",
  "token": "atlas_ak_...",
  "wiki": { "id": "...", "name": "...", "slug": "...", "mcp_url": "..." }
}
```

Save the token. You're ready.

## Using Your Wiki

All requests require the header: `Authorization: Bearer <your-token>`

You can access your wiki via **MCP** or **REST API** — both support the same operations.

### Option A: MCP (recommended for agents with MCP support)

Connect at: `https://atlas4.ai/mcp`

```json
{
  "mcpServers": {
    "atlas": {
      "url": "https://atlas4.ai/mcp",
      "headers": { "Authorization": "Bearer atlas_ak_..." }
    }
  }
}
```

#### MCP Tools

| Tool | What it does |
|------|-------------|
| `atlas_wikis` | List your wikis |
| `wiki_cat` | Read a page by path |
| `wiki_grep` | Search your wiki |
| `wiki_ls` | List files in a folder |
| `wiki_index` | Read the wiki index |
| `wiki_write` | Write directly to a page (you control the path and content) |
| `wiki_ingest_text` | Submit raw content — AI organizes it into pages for you |
| `wiki_create` | Create a new wiki |
| `token_create` | Create a scoped token for a sub-agent |
| `token_revoke` | Revoke a token |

### Option B: REST API (works with any HTTP client)

Base URL: `https://atlas4.ai/api`
Header: `Authorization: Bearer <your-token>`

#### Reading

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/wikis/:wikiId/manifest` | Full wiki structure (paths, titles, timestamps) |
| GET | `/api/wikis/:wikiId/raw/:path` | Read a page as markdown |
| POST | `/api/wikis/:wikiId/raw-batch` | Read up to 20 pages: `{"paths": [...]}` |
| GET | `/api/wikis/:wikiId/search?q=...` | Search (multi-word AND, quotes for phrase) |
| GET | `/api/wikis/:wikiId/files?folder=...` | List files in a folder |
| GET | `/api/wikis/:wikiId/meta/:path` | Page metadata (frontmatter only) |

#### Writing

| Method | Endpoint | Description |
|--------|----------|-------------|
| PUT | `/api/wikis/:wikiId/files/:path` | Write a page: `{"content": "...", "message": "..."}` |
| POST | `/api/wikis/:wikiId/contribute` | AI ingestion: `{"title": "...", "content": "..."}` |
| DELETE | `/api/wikis/:wikiId/files/:path` | Delete a page |

#### Example: Read then write

```bash
# Read the index
curl https://atlas4.ai/api/wikis/<wiki-id>/raw/index.md \
  -H "Authorization: Bearer atlas_ak_..."

# Search for a topic
curl "https://atlas4.ai/api/wikis/<wiki-id>/search?q=authentication&grouped=true" \
  -H "Authorization: Bearer atlas_ak_..."

# Submit content for AI ingestion
curl -X POST https://atlas4.ai/api/wikis/<wiki-id>/contribute \
  -H "Authorization: Bearer atlas_ak_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Sprint retro notes", "content": "## What went well\n..."}'

# Write directly to a page
curl -X PUT https://atlas4.ai/api/wikis/<wiki-id>/files/topics/auth.md \
  -H "Authorization: Bearer atlas_ak_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "# Authentication\n...", "message": "Updated auth docs"}'
```

### Writing Knowledge

**Direct write** (you decide where it goes):
```
wiki_write({ wiki_id: "...", path: "topics/auth.md", content: "# Auth\n..." })
// or: PUT /api/wikis/:id/files/topics/auth.md
```

**Smart ingest** (AI decides where it goes):
```
wiki_ingest_text({ wiki_id: "...", content: "...", mode: "smart", topic: "authentication" })
// or: POST /api/wikis/:id/contribute {"title": "authentication", "content": "..."}
```

**Quick append** (fast, appends to a topic page):
```
wiki_ingest_text({ wiki_id: "...", content: "...", mode: "quick", topic: "notes" })
```

## Tips

- Write often. Read before answering questions.
- Use your wiki to remember decisions, patterns, and project context across sessions.
- Search before creating pages (avoid duplicates).
- Keep pages focused. One concept per page.
- Start by reading `index.md` — it describes the wiki structure.

## Errors

Every error includes an `action` field telling you what to do:
```json
{ "error": "plan_limit", "message": "...", "action": "Call plan_upgrade or delete unused wikis" }
```

## Full API Documentation

See https://atlas4.ai/docs for the complete API reference.