# adlass — Guía para agentes

Eres un agente. Tu usuario quiere usar adlass como capa compartida de contexto para documentos, adlass Resources, habilidades y Spaces.

Puntos de inicio:

- Página pública: https://faro.numero1.co/es
- Guía canónica con la lista completa de herramientas: https://faro.numero1.co/agents.md
- Guía de invitaciones a Spaces: https://faro.numero1.co/es/space-invitation.md
- Despues de iniciar sesion: abre https://faro.numero1.co/app/spaces, selecciona el Space, abre MCP settings y copia el prompt para la IDE correcta.

Trabaja de forma segura:

1. No inventes datos de conexion MCP ni pidas un endpoint por separado. adlass crea en el dashboard un prompt de setup especifico para la IDE.
2. Usa el nombre exacto de servidor MCP `adlass`.
3. Empieza con `adlass_ls` en `/spaces` y navega con `adlass_tree`, `adlass_stat` y `adlass_cat`.
4. Para uploads usa `adlass_upload` con `operation=start`, targets PUT presignados paginados y luego `operation=complete`.
5. Para importaciones como DIAN usa `adlass_import` con `operation=sources`, `operation=start` y `operation=status`.
6. No guardes prompts de setup, endpoints de conexion, OAuth tokens, bearer tokens, contrasenas de Space ni secretos en memorias, logs, skills o notas.
7. Usa solo el cliente MCP activo. No uses `codex exec`, clientes anidados ni agentes efímeros.

La referencia completa de herramientas se mantiene canónicamente en inglés:

# adlass Agent Guide

You are an agent. adlass 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.

adlass MCP v2 is an agent-native virtual file system first. Treat adlass 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 `adlass://` 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 adlass account at https://faro.numero1.co/app/sign-up.
2. The user opens https://faro.numero1.co/app/spaces and creates or selects a
   Space in the adlass dashboard.
3. The user opens MCP settings for that Space, chooses their IDE, and copies
   the single setup prompt for that client. adlass provides prompts for Codex,
   Cursor, Claude Code, and generic Remote MCP clients. Do not invent
   connection details or ask for a separate endpoint.
4. Use the current client's native Remote-MCP/OAuth capability when available.
   Shell access does not configure the active client unless the user explicitly
   runs those commands in that client environment.
5. OAuth uses dynamic client registration. The connection endpoint appears only
   inside the copied setup prompt or MCP config entry; do not request it as a
   separate value.
6. If supported, add the server as `adlass` and trigger OAuth by listing
   tools or making the first MCP request. Do not open the connection endpoint
   as a webpage.
7. Verify tools/list and `adlass_ls /spaces`. In Cursor, the server may appear
   as `user-adlass`.
8. If the running client cannot add remote MCP servers, stop and provide only
   the manual MCP configuration for that client. Do not use browser GET,
   `codex exec`, nested MCP clients, or short-lived sessions to simulate a
   connection.

## MCP v2 tools

Filesystem tools:

- `adlass_ls`: list direct children as terminal-like text with `limit` and
  `offset` pagination.
- `adlass_tree`: show a shallow, page-safe tree with `limitPerDirectory`.
- `adlass_stat`: inspect one node.
- `adlass_cat`: read a file-like view. Directories return `is_directory`.
- `adlass_grep`: search text with Drive/Object/Dataset-aware defaults,
  `limit`/`offset` pagination, and `maxChars` output caps.
  If a Drive scope is too large, follow the returned `suggestedPaths` or use
  `adlass_query` on Objects/Datasets instead of retrying the broad grep.
- `adlass_find`: recursively search names, aliases, and metadata, not full text.
- `adlass_query`: run paginated JSON-AST queries and aggregations over Drive,
  Objects, and Datasets.

Action families:

- `adlass_space`
- `adlass_upload`
- `adlass_share`
- `adlass_import`
- `adlass_export`
- `adlass_object`
- `adlass_live`
- `adlass_dataset`
- `adlass_school`
- `adlass_skill`
- `adlass_artifact`
- `adlass_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"}
{"operation":"read","path":"/spaces/acme/live/bitacora.live_123.json"}
```

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

## VFS workflow

Start with:

```text
adlass_ls /spaces
adlass_ls /spaces/acme
adlass_tree /spaces/acme --depth 2 --limitPerDirectory 40
```

Large directories are paginated by default. If `adlass_ls` or `adlass_tree`
returns `hasMore`, `nextOffset`, or a `... more` marker, continue with
`adlass_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. `adlass_cat` reads concrete files, not document folders.
`summary.md` exists only when adlass has a real summary
resource. `source/original.pdf` returns metadata and a short-lived download
action when allowed, not binary bytes.

Live Documents are Yjs-backed files under `/spaces/<space>/live/*.json`.
`adlass_cat` includes the current shared content, and `adlass_grep` searches
Live content. Use `adlass_live` with `operation:"read"`,
`operation:"patch"`, `operation:"connect"`, `operation:"snapshots"`, and
`operation:"snapshot"`; markdown patches use `patch:{ op:"replace"|"append",
text:"..." }`. These are the Live Document operations exposed by MCP.
For `structured_table`, create columns as
`{ id, label, type }` and rows as `{ id, values }`; never put cell values
directly on the row object or use `columns[].key`. For large spreadsheets,
create a Dataset-backed Live View with `datasetId`, `collection`, optional
`viewSpec`, and `pageSize`; Yjs stores view state while rows stay paginated in
the Dataset.

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 large Business Object result sets, first use `adlass_object`
`operation:"types"` and `adlass_query` aggregations or small previews. Then
use `adlass_object` with `operation:"export_query"`, `select`, `filters`,
and optional `orderBy` to create a short-lived JSONL gzip download URL. Do not
ask MCP tools to return thousands of object rows in chat output.

For object configuration help, read the public Business Objects guide:
https://faro.numero1.co/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
`adlass_query` with `where`, `orderBy`, `aggregate`, and `groupBy` for
large structured questions. For `adlass_dataset` read/query operations, pass
`collection` as the collection key.

## Uploads and imports

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

For provider imports, call `adlass_import` with `operation:"sources"`, ask the
user for the source-specific required fields, then call the listed next tools.
For workbook and spreadsheet data, upload the file, wait for processing, then
call `adlass_dataset` with `operation:"import_workbook"` and the
`documentRecordId`. The result is Dataset collections plus Dataset-backed Live
Views, not thousands of row values in a chat tool argument.

## 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
  `adlass_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
  connection or copied setup prompt.
- Use the active MCP client only. If it supports global or persistent memories,
  store only a short adlass description. Do not store setup prompts, connection
  endpoints, 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.