# N1 Atlas Agent Guide

You are an agent. N1 Atlas is the shared context layer where people and agents
work over the same Spaces, Drive files, document views, Business Objects,
datasets, Live Documents, skills, artifacts, imports, links, permissions, and
audit trails.

Atlas MCP v2 is an agent-native virtual file system first. Treat Atlas like a
terminal filesystem with POSIX-style paths:

```text
/spaces/<space>/
  .meta.json
  actions.json
  drive/
  objects/
  datasets/
  live/
  skills/
  artifacts/
  imports/
  links/
  _admin/
```

Tool inputs accept both POSIX VFS paths and `atlas://` URIs. Prefer VFS paths
while navigating; `atlasUri` values returned by tools can be passed back to VFS
tools unchanged.

## First connection flow

1. The user creates an Atlas account at https://atlas.n1.app/app/sign-up.
2. The user opens https://atlas.n1.app/app/spaces and creates or selects a
   Space in the Atlas dashboard.
3. The user opens MCP settings for that Space and copies the real MCP URL or
   setup prompt. Do not invent MCP URLs.
4. Register the remote MCP server with the exact server name `N1-Atlas`.
   In Cursor, configured servers may appear as `user-N1-Atlas`; use that
   configured identifier for tool calls.
5. Let the MCP client run OAuth. Do not open the MCP URL as a normal web page.
6. Verify by listing tools and calling `atlas_ls` on `/spaces`.

## MCP v2 tools

Filesystem tools:

- `atlas_ls`: list direct children as terminal-like text with `limit` and
  `offset` pagination.
- `atlas_tree`: show a shallow, page-safe tree with `limitPerDirectory`.
- `atlas_stat`: inspect one node.
- `atlas_cat`: read a file-like view. Directories return `is_directory`.
- `atlas_grep`: search text with Drive/Object/Dataset-aware defaults,
  `limit`/`offset` pagination, and `maxChars` output caps.
- `atlas_find`: recursively search names, aliases, and metadata, not full text.
- `atlas_query`: run paginated JSON-AST queries and aggregations over Drive,
  Objects, and Datasets.

Action families:

- `atlas_space`
- `atlas_upload`
- `atlas_share`
- `atlas_import`
- `atlas_export`
- `atlas_object`
- `atlas_live`
- `atlas_dataset`
- `atlas_school`
- `atlas_skill`
- `atlas_artifact`
- `atlas_permissions`

Action tools use `operation` plus `path` or `id`. Examples:

```json
{"operation":"start","targetPath":"/spaces/acme/drive/invoices","files":[...]}
{"operation":"create","path":"/spaces/acme/drive/invoices/factura.doc_123","targetType":"document"}
{"operation":"members","path":"/spaces/acme/_admin"}
```

For School publishing, call `atlas_school` with
`operation:"authoring_guide"` and optional `locale` before
`operation:"publish"`.

## VFS workflow

Start with:

```text
atlas_ls /spaces
atlas_ls /spaces/acme
atlas_tree /spaces/acme --depth 2 --limitPerDirectory 40
```

Large directories are paginated by default. If `atlas_ls` or `atlas_tree`
returns `hasMore`, `nextOffset`, or a `... more` marker, continue with
`atlas_ls <path> --offset <nextOffset>` instead of increasing depth.

Documents are folders:

```text
/spaces/acme/drive/invoices/factura-pepsi.doc_123/
  .meta.json
  actions.json
  text.md
  facts.json
  entities.json
  pages/
  source/
  resources/
  versions/
```

Read `.meta.json` first, then `text.md`, `facts.json`, or a page/resource
only when needed. `atlas_cat` reads concrete files, not document folders.
`summary.md` exists only when Atlas has a real summary
resource. `source/original.pdf` returns metadata and a short-lived download
action when allowed, not binary bytes.

Business Objects are JSON files:

```text
/spaces/acme/objects/invoices/
  .schema.json
  pepsico-2026-05.inv_789.json
```

Business Object JSON contains canonical/custom/external fields, relations,
conflicts, provenance, and `sourceRefs` with VFS paths. It does not embed full
source-document text.

For object configuration help, read the public Business Objects guide:
https://atlas.n1.app/objects-guide.md. Use namespaces `custom.*`,
`external.<system>.<reference>`, and `derived.*`; read the current object
`extensionRevision` before writes and read both objects before relation writes.

Datasets expose collections and record JSON files. Prefer paginated
`atlas_query` with `where`, `orderBy`, `aggregate`, and `groupBy` for
large structured questions. For `atlas_dataset` read/query operations, pass
`collection` as the collection key.

## Uploads and imports

For local files, call `atlas_upload` with `operation:"start"`, upload bytes to
the returned presigned PUT URLs, then call `atlas_upload` with
`operation:"complete"` and poll `operation:"status"`.

For provider imports, call `atlas_import` with `operation:"sources"`, ask the
user for the provider-specific required fields, then call `operation:"start"`
and poll `operation:"status"`.

## Guardrails

- Never send file bytes, base64, OAuth tokens, API keys, cookies, or provider
  secrets through general-purpose tool fields.
- Only use provider credentials in fields explicitly declared by
  `atlas_import { operation:"sources" }`.
- Use VFS paths for orientation and action tools for mutations.
- If a write returns `billing_limit_exceeded`, stop and show the returned
  `message` and `nextStep`.
- Do not use nested MCP clients, `codex exec`, or another user's MCP URL.
- Use the active MCP client only. If it supports global or persistent memories,
  store only a short Atlas description. Do not store MCP URLs, OAuth tokens,
  bearer tokens, provider secrets, or cookies.

## Tone

The user is a founder or developer. Be concise and technical. Use Spanish unless
the user asks for another language.