# Getting started

Maplith builds a **data-ontology map** of your business from the systems you
already use — what objects exist (customers, invoices, orders…), how they
relate across systems, where the joins actually verify, and where they do not.
The map is **metadata only**: your files are read once and deleted after the
run; what Maplith keeps is the map, which may quote example values and evidence.

## 1. Sign up and upload

Sign in at [app.maplith.com](https://app.maplith.com) — a workspace is created
for you. Upload export files from your systems (CSV, Excel, JSON — the formats
your systems' own export buttons produce). Exports from two or three systems
that should agree with each other give the most interesting maps. Written
procedures — a returns policy, reorder rules — are worth including as
Markdown or PDF: to a scan they are files like any other, and they are what a
playbook can be drafted from. A decision record (an ADR, a policy, a
decision log) is read as a document but is not drafted from: it says why
something was decided, not how to do the work. Maplith reads the rules it
states instead, each restated in a sentence and anchored to the objects,
fields and processes it applies to. An object's or process's page shows them
under **Rules that apply here**, an agent working there is told them with
its task, and Rules & know-how › From your documents lists every record that states a rule, with its rules, its
status and what it supersedes. The record itself is not drawn on the map.

**Before starting work:** start from your task with `get_task_context`: pass
the task's description and the objects, files or URLs it is about as `task`,
a signal's id, or a support case. A task or a signal comes with its applicable
decision statements; for a case, read the named objects' rules with
`get_object`. Follow the rules and their conditions; open the source record
only when a rule is unclear. Decision statements are also searchable with `search`.

Every rule a record
states is kept. A policy, a staff handbook, an SOP or a supplier agreement is read for its rules
the same way, in English or Danish, and each document is shown with its role: foundation,
policy, procedure, agreement or decision record. A data file is never read for rules, and an
export without such a document costs nothing extra. Each rule also says, where the document
does, whom it applies to, the exceptions it names, and from and until when it holds. A rule past
its end date is handed to agents marked no longer in force; Rules & know-how › From your documents shows it as ran out, and a newer
version of the document that extends it brings it back. A mail or chat thread that announces a
rule ("from today, every refund needs a second approver") is read the same way, one
thread at a time, and shown as correspondence under the mailbox or channel and its date, never
its subject; a thread that announces no rule is never read for rules. With data handling set to
samples only, Maplith reads samples first and more of a thread only where a rule is likely. A rule that names something your map does not hold yet is listed in Rules & know-how › From your documents under **Not placed yet**, with what it names, and a finding lists those names so
you can add the export that holds them; the next scan places the rule. Each rule also says the
situation it binds in — the action being taken, such as delete, share outside or charge or pay, or
any situation — so an agent reads first the rules for what it is about to do. Maplith reads it from
the rule's own wording; an admin who sees the whole map can correct it in Rules & know-how › From your documents, and a
correction stays through later scans for as long as the rule's wording in its document is unchanged. A rule that several of your
records state in the same words is handed to an agent, and shown on the pages where it applies, once,
with the records that also state it (the first five by name); in Rules & know-how › From your documents every record still
lists its own rules. What your business follows decides, not a record's status line: a rule from a
record still marked as a draft is handed to an agent like any other. No rule is left out: one that
something explicitly ended (a rejected or withdrawn record, your mark that it is replaced, or a later
record that says it replaces it, given beside it) is handed over marked no longer in force, with
what replaces it. A later date alone replaces nothing: Rules & know-how › From your documents points the later
rule out, and an admin who sees the whole map can mark the older one replaced, or keep any rule
current. Every rule stays listed in Rules & know-how › From your documents.

A draft or unstated record can raise one review finding when an active playbook
or accepted record explicitly names it as authority, or a clear requirement is
borne out by declared structure and fully counted data. A record still awaiting
a decision after 30 days raises an age-based question; age alone is not proof
that anyone follows it. A workspace admin who sees the whole map can choose
**Accepted** or **Rejected** in Rules & know-how › From your documents. Maplith keeps the file's status
and the workspace's choice separately, carries the choice across scans, and
closes that record's review finding. Individual rules keep any explicit
**Still current** or **Replaced** choice you made for them. Helpdesk conversations are read too, Intercom's
first: its Conversations API and cloud-storage export (JSON or JSONL) and its
CSV exports (the conversation dataset from Reports, the older export with one
message to a row, and the Contacts and Companies lists), flattened into tables
like any other export.

While you are there, protect your account: under **Account security** in the
account menu you can add an authenticator app, and Maplith then asks for its
code each time you sign in. See [Security & access model](/docs/security).

## 2. Review, then build

Your browser checks the selection against the upload caps (300 files and
1 GB per upload; any file but a CSV or TSV up to 50 MB) before anything is
sent, and says what to do when a file or the whole upload is too large. A
text export over 5 MB (CSV, JSON, a mailbox) is compressed in your browser
first, so the caps count its compressed size (a CSV usually shrinks to a
quarter of its size or less), and it is read under its own name. Another
file still over 50 MB compressed is best split by period.

A CSV or TSV over 48 MB needs no splitting by hand: your browser cuts it into
parts between rows (never inside one, even where a cell runs over several
lines), repeats the header row on every part, compresses each part and
records a SHA-256 checksum of it, and sends the parts a few at a time ("orders.csv
— part 7 of 14"). A part that does not get through is sent again on its own,
and if the upload stops, **Resume upload** sends only the parts that are
missing (for up to about two hours, while the upload's links are valid).
Before the build, Maplith checks every part's size and checksum and that
the parts fit together, and puts the table back together into exactly the
file you chose; if anything does not match, the build stops and says so,
rather than building a map from part of your data. Your map shows the one
file, never its parts.

The files then go straight to storage, with a progress line, and Maplith
reads only the shape of your upload (file names, sizes, count of systems)
and shows what it recognised.
Then you build. CSV, Excel (.xlsx), PDF (text layer, first 100 pages), JSON,
mailbox archives, transcripts and Markdown are read; a scanned PDF without a
text layer cannot be read, and Data sources › Scans lists it as unreadable. A
.zip or .gz file (orders.csv.gz, a zipped export folder) is unpacked before
the build and what it holds is read like the rest, so a large CSV history
fits under the per-file cap; unpacked, one build reads up to 1 GB, and
an archive inside an archive is not unpacked. A larger upload takes longer to
build (a 1 GB order export adds a few minutes of reading), but the map's
model work, and its cost, does not grow with the number of rows. Images, audio, video and an
archive inside an archive are never sent to the model: Maplith reads the first few bytes to see what the file is, stops there,
and writes a note beside it saying what it found. The file itself is uploaded
and stored with the rest until the build is done, like everything else you
send. Data sources › Scans lists what could not be read, by name.

## 3. The scan

The scan discovers objects (with their row count and their grain — what one
row of each is: one column, or two where the file is lines of something, such
as an order's lines or a voucher's postings; where Maplith cannot tell for
sure it asks you in Data sources › Scans instead of guessing), fields (each with an explicit PII flag and, where its column is in the
export, a role — identifier, dimension, measure or attribute — derived from
the export's own columns),
relations
that carry a name, a direction, a cardinality and — wherever the join could be
tested against your own data — an executable join spec and a verification rate,
processes from event-like data, grounded metrics, and
**findings** — documented discrepancies between your systems, each with
evidence and a recommendation. Typical duration: minutes, not hours.

Joins between CSV exports are **measured, not guessed**: the engine compares
the values of column pairs across your files and publishes a join with its
direction, its cardinality and both coverage rates; the model is asked
what to call it. Matching values are not enough where both columns count
1, 2, 3 …, because every table numbered that way would match: such a join
also needs column names that say so, such as `customer_id` and the customer
file's `id`, and a join the model proposes between two such columns says that
its coverage is no evidence. Before anything is sent to the model, Maplith tries to mask
email local parts, Danish CPR numbers, IBANs, card numbers, the names of people
in your export's own name columns, and the masking terms you switch on under
Settings › Privacy & masking — a best-effort safeguard, not a guarantee. You decide what your
export contains.

## 4. Explore — and serve it to your agents

The map is yours to browse in the app, and — this is the point — to serve to
AI agents over [MCP](/docs/mcp) with [scoped keys](/docs/agent-keys). Agents
get small, verified answers about your data landscape instead of guessing over
raw exports.

**The home** opens with what needs you: one row per thing waiting — terms to
confirm, findings to decide, agent requests to approve, playbook drafts to review —
each with one button, and the sidebar shows the same counts beside the pages
where you can act. Below it, your map at a glance and, where the assistant is
open to you, a box to ask about it. Until you are set up, the **Getting
started** guide shows the next step; close it for 14 days or for good from the
home, the sidebar or a step's note, and bring it back from the account menu.

**Findings** are something you decide; agents do the work. The ones that need
a decision are listed most impact first and grouped by kind: twenty findings
of one kind are one row, "Approve 20 fixes", and each still has its own
suggested fix when you unfold the group. **Approve fix** hands the finding and
its suggested fix to your agents: the one that may act carries it out with the
access you gave it, and one that asks before acting still asks. With no agent
that may act yet, the approval is kept and waits for one; an admin connects
one, or lets one act, in Agents & access. **Not a problem**
dismisses it, with **Undo**; under **More** are **I’ll do it myself**, **Ask
about this**, **Hand to a specific agent**, **Copy for your agent** and the
steps the map supports, such as making it a rule or **Write how agents fix
this**. After approving, the finding shows who has it: waiting for an agent,
with the agent, fixed (the next scan confirms it), or back with you when the
agent needs you. The filters To decide, Waiting for an agent, In progress,
Handled by agents and Decided add up to All; Handled by agents shows what
agents tested or fixed in the last 14 days, day by day. Joins Maplith could
not test are not asked of you where an agent may test them: your agent counts
the keys in its own systems, and you see the result under Handled by agents.
Maplith also says where your data points out of its sight: a system your files
show you use, and key columns that point at records no object on the map
holds. Each of those findings says how to bring the missing records in:
upload an export of the system, have your agent read it, or connect it under
Data sources › Systems where Maplith has its own connector for it.

**In English, whatever language your files are in.** Maplith writes its own
text in English: findings, object and field descriptions, metrics and
playbooks, even when every export is in Danish or another language. Where it
uses your own words, such as a status value or a phrase from a document, it
quotes them exactly as written. Wherever Maplith shows its own text about your
business, those quotes are marked as yours, with a dotted underline and the
label "From your files, as written".
A finding an earlier scan wrote in another language is reworded in English on
a later scan; its status and history stay as they were. A rewording that
cannot keep every figure, name, masked value and quotation exactly is not
used, and after two such attempts the finding keeps its earlier wording until
its text changes. Object and
relationship descriptions from a source that has not been scanned since, and
the titles of signals already raised, keep their earlier wording until that
source is scanned again.

**Test the map with your agent before you rely on it.** A scan built the map
from exports, and nobody has checked it yet against how your business really
works. Connect your agent and ask it to test the map with you — it proposes
realistic scenarios from the map, you add the cases and exceptions that
matter, and it runs each one hop by hop. The docs prompt
`maplith-test-the-map` walks it through this.

## 5. Keep it steady: glossary and history

A map your agents build on must not change under them. Under Business map › Glossary you
confirm what your business calls things — a term's name, its
files, its grain and the joins between terms — and a later scan never renames,
re-grains or removes what you confirmed; where it disagrees it raises a
**proposal** for you to decide. Questions about what one row means stay beside the right term even when your map combines several sources.

**Maplith confirms what your data proves.** After every scan Maplith confirms,
on its own evidence, a term built from a file of its own that nothing on the
map contradicts, and a join tested against your rows where at least 95% of
them find their match. It also clears up its own leftovers, such as an exact
copy of a metric that stays on the map. Each of these is recorded as Maplith's
decision, never a person's, with the evidence it rested on. You correct
afterwards: unpin a term, change it, or reject a join, and it becomes yours —
Maplith never confirms it again, and never touches what you confirmed. A join
you set, confirm or reject on a term Maplith confirmed, or on one of its files,
makes that term yours too, and so does marking a key of its files **Not a
join**. So does rejecting a change a scan proposes to something Maplith
confirmed: you kept it as it is, so it is yours.

The Glossary and each object's page say **confirmed by Maplith** on what the
build confirmed, with what it checked: the files and rows behind a term, and
the share of rows that found their key behind a join. What Maplith confirmed
stays as it is on a later scan, just like what you confirmed: when a scan
disagrees with it — a new name, a new key, a renamed export, or something the
scan no longer finds — Business map › Glossary asks you, and you decide. A join
nobody has confirmed that the scan could not test against your rows, or that
fewer than 95% of rows reach, is listed as a finding, so you know which
links an agent should not rely on yet.

What is left has no decision yet, and you do not have to go through it item by
item: the Glossary groups it by the pattern it shares — say,
terms whose rows each have a key of their own, or joins where every row reaches
the other side — shows what was measured for each, and lets you tick and confirm
several at once. Each one is still your decision, recorded as yours, and what
needs a closer look is listed on its own with the reason. The same applies to
everything else agents rely on: what a scan adds applies, what it would remove becomes a proposal with its
evidence. Every scan is kept as a version, and an admin can make an older one
the current map again — as a new version, recorded in the map's history, and
agents read it from the map's version (`get_map_overview`).

**Build the map one upload at a time.** Maplith reads from an upload's files
which systems it holds: a folder is a system; files at the top that share a
first word (`shopify_orders.csv`, `shopify_customers.csv`) are one, and so
are files a system's own export names; the other files at the top are one
system together, "Uploaded files", until an upload of other loose files that
share no name with them, which is a system of its own. A single folder
wrapping a whole export is
looked through, and dates or counters in names are ignored, so this week's
`exports_2026-10-15` is last week's `exports_2026-10-08` again. An upload
updates exactly its systems. The systems you uploaded before stay as they are,
with their joins and findings, and Maplith asks you nothing about them. When a
new system calls something by a name an earlier system already uses, both stay
on the map: the earlier keeps the name, and the new one gets a name of its own
(`customer_2`). In Business map › Glossary you can confirm it under the name your
business uses, or, once both are confirmed, merge the two. If a
new export of a system lacks a file the last one had, Maplith keeps what was
built from it and proposes the removal for you to decide; it never removes it
on its own. When Maplith recognised the system only by its file names (a
folder under a new name, or the files without their folder), it updates what
those files hold and keeps the rest of the system exactly as it was, with
nothing proposed: a file name is not proof that the whole system was exported
again. Each system you upload is listed under Data sources › Scans, and the to-dos in your Inbox show the ones that were uploaded once and are not kept fresh, with how
to keep each fresh.

**Nothing leaves your map unless you ask.** When the source of something on
the map stops arriving (a file missing from an export, or a connection that no
longer delivers a table), Maplith keeps it, with everything built on it.
It may be legacy that still works, and Maplith cannot tell. It is marked
**not maintained** on Business map › Atlas and on its page, with how long since its source
was last seen and the step that brings it back: reconnect, upload the file
again, or, if it is gone for good, accept the removal in Business map › Glossary.
Not-maintained objects lower how far an agent can trust the map until you do
one or the other.

**How far your agents can trust the map.** Home shows **Map confidence**, a
score from 0 to 100 that your agent is given too. Maplith counts it from what
the map holds, never by a guess: joins that did not hold or were never tested,
open questions, terms a scan contradicts and objects no longer maintained.
If you see the whole map, the card also says how the last scan scored
against the scan before it of the same source. Each item below the score says what raises it and
links to the section where you settle it; your agent is given the same item as one question to ask you,
with the same choices. When fewer than half the joins were tested against your data, the score
says it rests on few measurements, and testing the joins with your agent
comes first. Business map › Atlas and each object page mark the joins the score counts:
a join the last scan contradicts is drawn bold in oxide and marked
**Contradicted**, one Maplith is not sure of is dashed and marked **Not
sure**, and both link to the Glossary where your team settles them. An object
Maplith is not sure is the same as before, because a scan saw it split from
or merge with an earlier one and gave it a new identity, has a dotted outline
on Business map › Atlas and is marked **Identity not sure** on its page; it counts as an
open question until a workspace admin who sees the whole map answers **It is a
new object** there. Only you remove things: by accepting a removal, or by
switching off **Keep what a scan stops finding** under Settings › Data & retention
stability, which lets every scan remove what it does not find at once. When a
system splits or merges a table, the old object stays until a person accepts its structural proposal, then is retired as the predecessor
of the new ones, not removed as something that is gone.

**When a new file uses an existing name.** A name alone never hands an object
to a new file. When an export renames a file (`orders.csv` becomes
`order.csv`), the old object keeps its files, fields and joins, and Maplith
asks one question while the new file waits for the answer. For an unconfirmed
object, **Use file on next scan** records the choice, which also holds for the
next dated export of the same file, and the next scan builds the object's
measurements afresh. If you say no, the new file is another object: it stays
on the map under a name of its own (`order_2`), and the old object stays
until you remove it. A file from another system or source that happens to use
an existing or confirmed name is another object too, kept under a name of its
own; Maplith never moves a confirmed term to another system's file. When
several files could be the replacement, nothing is guessed: each stays as the
scan built it, and you choose the precise file in the term editor. Where a
file is named by a CPR number, Maplith cannot tell one scan's file from the
next, because it tries to mask the number in what it stores. An unconfirmed
object on such a file follows its name: it is updated from the file the scan
read, and no question is asked. A confirmed term on such a file is not
matched to the new scan's file: the term keeps what the last map had and is
reported missing, and the new file appears under a numbered name
(`payslip_2`) until a person decides.

**Every join in one table.** In Business map › Glossary, **Joins as a table** lists
every join of your map once: from which object to which, the column on each
side, how many left-file rows reach the other side, the cardinality, how sure Maplith is
and why, and your decision. Sort by any of them, filter by object, system,
decision or strength, and an admin confirms (**Right key**), rejects
(**Wrong**) or undoes a decision (**Forget**) row by row — the same decision
as on the term's card.

Coverage names its side: `verified_rate` measures rows of `join_spec.leftFile`.
`child_coverage` measures child rows finding parents; `parent_coverage`
measures parents with children. Low parent participation is not a broken key.
A null is unknown. Older scans may report only `child_key_coverage`, for
non-blank keys; this cannot establish coverage of all child rows. Untested
hops say so, including the recorded skip reason. An inferred parent direction contradicted by measured repeats is withheld.
Your team’s confirmed shape stays pinned, with the conflicting measurement
shown for review.

**Declared, measured or guessed.** Every join and every object on your map
says what evidence stands behind it:

- **Declared**: something you shared states it, such as a foreign key in a
  database schema, a table listed in a schema export, or a relationship you
  or your agent stated. Maplith names the file and where in it, never a value
  from it.
- **Measured**: the values in your rows bear it out. Maplith counted how many
  rows find a match.
- **Guessed**: a column name or the model suggests it, and nothing declared
  or measured it. Treat it as a proposal.

A join can be declared and measured at once; that is the strongest evidence
there is. When your agent asks for a route between two objects, Maplith walks
declared and measured joins and avoids guessed ones. If only guessed joins
connect the two, the answer says so, and your agent should check those joins
in your own systems before relying on them. Your team’s own decision on a join
outranks all three, and none of them changes it.

**When a join is wrong.** Every join in Business map › Glossary and on an object's page
says what its evidence is, in plain words: the rows matched on which key, the
blank keys, and how sure Maplith is. If a join is wrong, an admin or builder
chooses **Question** and says why — the wrong columns, the wrong direction or
count, not related at all, or how it really works. **Add a missed join** names
two objects and their columns, or describes the join in a sentence. Maplith
checks its own evidence first and tells you when it is against you. Your
agent can raise the same review while it tests the map with you. Either way,
your agent is asked to count the two keys in your own systems and reports the
counts, never a row. Nothing on the map changes until an admin who
sees the whole map accepts the review; once a missed join is accepted, every
scan measures it.

**Stating how your files relate.** If you or your own assistant already know
how your files relate, say so up front — before the first scan or after. Under
**Business map › Glossary › Stated relationships** an admin who sees the whole map pastes or
uploads it, one relationship per line:

```
orders.customer_id -> customers.id (N:1)
crm/contacts.csv.email = shop/customers.csv.email
order_lines is a join table between orders and products
join table order_lines: order_id -> orders.id, product_id -> products.id
```

A side is `table.column`: the table is an object of the map or a file, the
column is the header as your export spells it (quote it when it has spaces:
`orders."Customer No"`). `->` says which side points at which; `=` says
only that the values match. A shape in brackets — `1:1`, `1:N`, `N:1`,
`N:M`, or the words `many-to-one` and so on — is checked too. Lines starting
with `#` are comments; a line Maplith cannot read is shown with its number
before anything is saved. An agent can send the same as JSON or CSV with the
`state_relationships` tool. Where a file is named by a CPR number, Maplith
tries to mask the number in what it stores, as it does for every file path:
the line is saved with the number masked and still finds its file by the rest
of the path.

Every scan checks each line against the data exactly as it checks its own
joins — how many values match on every file that holds the column, and the
shape — and shows the result beside it. Where a stated key holds, the map
uses it in place of Maplith's own guess for the same two objects. Where it
does not — the values do not match, the shape differs, a column or file is not
in the export — it stays on the list as a question for you: correct it, remove
it, or keep it as a join anyway, which makes it your confirmed join. A join you
confirmed is never changed by a stated one.

The files you share can state keys too: a database schema with its foreign
keys, for example. Maplith reads what each one declares, keeps it with the
source it came from, and checks it on every scan the same way, so a schema you
shared once still checks the data you share later. An unchanged file is not
read again. These keys are listed beside your own lines, marked as coming from
the file, and change only when you share a new version of it. Where a key a
file declares does not match the data, Maplith does not put it on the map as a
join: it raises one finding per file naming the key and the counts, because the
file may be stale, the export may be from another period, or the data may be
wrong, and you decide which. Where a file declares a different key for a join
you confirmed, your join stays, and the Glossary asks whether to use the other
key instead.

A database schema shared as a SQL file usually says in its first lines which
database wrote it (pg_dump and mysqldump do). When it does not, Maplith reads
at once every statement that means the same in PostgreSQL and MySQL, and asks
you one question in Data sources › Scans: "Is this file from PostgreSQL or
MySQL?", with the likelier one chosen from what the file looks like. The
statements that read differently in the two wait for your answer, never for a
guess, because a guess could read a value in the file as a key. Your agent may
answer it instead when the file shows the dialect clearly, and it says what
showed it; your own answer always stands over your agent's. The answer is kept
for the file, and the next scan reads the rest and adds what it declares.

Sometimes two files hold the same rows: a system's export and a spreadsheet
someone copied it into. An agent that corrects or syncs that data must fix
the original, because the copy is overwritten from it. Where one file keeps
row keys the other lost, the map says which is the original. Where nothing
in the files tells them apart, Maplith does not guess: agents are told the
direction is unknown and to ask you first, and Data sources › Scans asks you one
question, "Which file holds the original?", with a suggestion chosen for you.
Your agent may answer it after checking your systems, and it says what it
read; your own answer always stands over your agent's. The answer is kept
across rescans. Maplith reads this from the files only, never from a
warehouse pipeline.

## 6. From the map to the work

Your own assistant can ask once how long a playbook usually takes you by hand.
You can give your own number, skip the question or change your answer later.
Only your personal assistant connection can save your answer; a shared key
cannot speak for a person. Maplith never estimates the minutes or shows them
as a claim of savings.


- **Signals** say what changed; **rules** you write from the map's own names
  say what matters to you, judged per product or per order. See
  [Signals & rules](/docs/signals-and-rules).
- `get_task_context` equips an agent for one signal in one call, including
  the **playbooks** your people wrote — or that Maplith drafted from your own
  procedures and an admin put in use. In Rules & know-how › Playbooks, Maplith's drafts
  come first: each shows its text and the document it was drafted from, and
  an admin who sees the whole map chooses **Approve and put in use**, edits it
  first, or rejects it. No agent is handed a draft. A playbook in use is
  anchored on the map — the object or process it is about, or a signal or an
  operation — and the object and process pages show the playbooks anchored
  there. A draft Maplith could anchor on nothing is shown as work that is not
  on your map yet, with the step to add the system that holds it.
  Maplith also **writes playbooks itself** from what a scan reads across your
  shared mailbox and chat exports, help articles, documents and decision
  records: one per process that recurs in them, anchored on the map, naming
  the files it was written from, and in use at once. Each says Maplith wrote
  it; an admin edits it or takes it out of use, and Maplith never overwrites a
  playbook a person changed, took out of use or deleted. From an **Intercom
  export** it writes one playbook per recurring case type — each tag your team
  already uses on at least five conversations, such as where-is-my-order or
  return (conversations with no tags give no types). Any of Intercom's
  conversation exports works: its API and cloud-storage files (JSON or
  JSONL), the **Dataset export** for conversations in Reports (CSV; pick the
  conversation tags column), and the older CSV with one message to a row.
  Where the export holds the team's replies, the playbook has the steps they
  show, when a person should take the case, and the route through the map from
  the conversation to what it concerns. The Dataset export holds no message
  text, so its playbooks are written from the counts, states, channels and
  times alone: they say so, and until steps are written they tell an agent to
  hand the case to a person. Nobody writes those steps by hand: upload an
  export that includes the messages and Maplith writes them, or let your own
  agent, if it can read your helpdesk, draft them from real conversations; a
  workspace admin approves the draft in Rules & know-how › Playbooks, and the same
  playbook then carries the steps. Either
  way a playbook names its sources as counts and the tag, never a
  message. Your help-center articles and saved replies are read with it when
  the export has them. From a
  **shared mailbox or a chat channel** it writes one playbook per kind of
  thread that recurs there — mails whose subjects share one pattern, such as
  "Order … shipped?", or a Slack or Teams channel your team works in — with
  the steps the replies show, when a person should take over, and its
  sources as counts: threads, messages, dates and the file, never a subject,
  a message or a sender. Read from a mailbox or channel you **connected**,
  such a playbook is wired: each scheduled scan raises a `thread_started`
  signal for every new thread of its kind nobody has answered yet (in the thread, or from the mailbox's sent mail), and the
  agent working it is handed that playbook. Read from an upload, it says
  when it starts, and Maplith cannot see a new thread arrive. Given a support case instead — the kind
  of identifier the agent holds for a customer and the kind of case — it says
  where to look that customer up, the routes to what the case is about, the
  playbooks for it, what is open on those objects, and what the agent's key
  may request.
- `ask` answers one question in plain language from the part of the map a
  key may see, citing what it rests on.
- The **action gate** decides, before an agent acts in your own systems,
  whether it may: allowed, pending a person's approval, or denied. See
  [Agent keys & policies](/docs/agent-keys).
- **Value** shows what you got: for this month, last month or the last 90
  days, how many signals that asked for work were handled, how many were not
  yet, how fast, and what the work was worth — only the amounts your agents
  or your people stated when they recorded it, per currency, never an
  estimate. Beside it, what is waiting right now (open and nobody on it, with
  the age of the oldest; planned or in progress), the kinds that came up
  most, findings no longer reported, and the signals handled most recently,
  each linked to Business map › Activity › agent work. You see what your view of the map allows:
  what agents recorded and stated is shown to admins and builders, and a
  member whose access covers part of the map counts that part. Once Maplith
  switches the monthly report on, owners and admins who see the whole map can
  also get last month's numbers by email on the 1st: switch it on or off for
  yourself on the Value detail (opened from **Home › Handled**)
  (it is on by default for the organisation's owners). The email carries
  counts and stated amounts only, never anything else from your map, and
  every one has a link that stops it.
- **What you got**, on Home, counts what came of it — never an
  estimate. It is among the sections below what needs you: open them with
  **See this month’s activity** on Home, where every section is one click
  away. Each page opens with one line on what it is
  for; how it works is under **How it works**, one click away.

## When something does not work: Tell Maplith

When a page cannot load, it offers one button, **Try again**. Pressing it
tries the page again and, at the same time, sends Maplith a report of the
error — the section, the kind of error and the app's version — so you do not
have to write one. If the page fails again, it says Maplith is working on it,
and the answer comes under **Your reports**.

Every other error in a workspace offers **Tell Maplith**. Say in a sentence what you
were trying to do (up to 1,000 characters) and add details if you like (up to
2,000); Maplith records which section of the app you were on, the kind of
error the page showed and the app's version, so you do not have to describe
them. Before it is stored, Maplith tries to mask what you wrote: the part of
an email address before the @, CPR numbers, IBANs, card numbers and your
workspace's masking terms.

**From your agent.** When a Maplith tool fails, answers wrongly or contradicts
these docs while your own agent works, the agent can report it itself, at the
moment it happens: `suggest_feature` with `kind: bug`, naming the tool,
what it expected and what it got. The report is yours: it is filed as if you
had sent it, shows under **Your reports** marked "from your agent", and the
agent gets its reference to give you. It describes the tool, never your data;
Maplith still tries to mask what the agent wrote, as above, and takes out ids.
A problem your agent already reported and is still open is not filed twice, and agents may
report a few problems per workspace per day. A key made under **Agents & access › Connections** is not tied to a person, so an agent on it tells you instead, and
you use **Tell Maplith**.

**Your reports** lists what you told Maplith from the workspace, with
Maplith's answer under each one. Only you and Maplith can read your reports:
not the other members or admins of your workspace, and not your agents. A
report is deleted with your membership or the workspace, and in any case 12
months after you sent it. See the [Processing and security
description](https://maplith.com/processing), section 2.9.

## Connectors instead of uploads

You can also connect a system directly (MCP URL + token) in Data sources › Systems — the map then rebuilds without manual exports. To serve a database or a
folder of exports from your own network, see
[Serve your data from your own network](/docs/mcp-template). GitHub connects via a
Maplith GitHub App; the [hosted agent](/docs/agent-keys) works through Maplith
Agents, the one that can write: see [The GitHub connector](/docs/github). Every
way to connect, with what each one reads and what is on the roadmap, is on the
[integrations page](/integrations).

### Metricool

Where it is offered in your workspace, an admin or builder chooses **Connect
Metricool** under Data sources › Systems, signs in to Metricool and approves read access
there. Maplith asks for Metricool's read scope only, and reads brand settings,
connected channels, posts scheduled for the next 90 days, the metric catalogue
and metric totals by period for the last 90 days through the read-only
tools of Metricool's hosted MCP server. Published posts and individual
ad campaigns are not read. Maplith never schedules,
changes or deletes a post. Metricool decides by plan what its server returns:
anything your plan does not include is listed on the scan as *not in this
Metricool plan*, and the rest is read. Metricool offers Maplith no way to
revoke its own access, so after **Remove**, revoke Maplith's access in your
Metricool account too. Until it is offered in your workspace, upload
Metricool's CSV exports in Data sources › Scans, as its
[guide](/docs/systems/metricool) describes.

### Systems you connect with a key

Some systems, Stripe among them, take a read-only key that you make in the
system itself and paste into Maplith. Where it is offered in your workspace, an
admin or builder chooses **Connect** on the system's card under Data sources › Systems,
follows the steps in the dialog (they are the system's own: where to click and
what to set to read-only) and pastes the key. Maplith checks the key before it
keeps anything; if the system does not accept it, nothing is stored and the
dialog says what to do next. The key is sealed and never shown again.

- **Read when scanned.** Maplith reads the system each time you scan it, and
  nothing arrives in between. It reads over a fixed window, such as the last 90
  days, from the one account the key belongs to.
- **Read only.** Maplith calls only a fixed list of the system's reads, never
  anything that creates, changes, schedules or deletes. If the system later
  says one of those reads can change data, Maplith stops calling it. Maplith
  tries to mask personal details such as email addresses.
- **Counted in datasets.** A dataset is one table Maplith reads, so the row
  says "6 datasets", and a scan that could not read all of them says "4 of 6
  datasets".
- **A scan that reads some of it still succeeds.** Data sources › Scans names what was
  not read and why, one line each, and what to do next. Only a rejected key, no
  answer, or nothing readable ends a scan, and then the system is marked as
  needing attention with **Fix connection**, and you can upload an export of the
  system on Scans meanwhile.
- **A scan with nothing in its window is "Nothing new".** When the system
  answers but holds no records in the window Maplith reads, the scan is marked
  Nothing new, not Failed: the connection stays Connected, the map stays as it
  was and the next scan reads again. It counts as a scan and moves the
  connection's "last scan" date, never the map's.
- **Test connection** shows what the system offers now. An admin can **Remove**
  the connection under More; a builder asks an admin to.

### Cloudflare

An admin chooses **Connect** on the Cloudflare card under Data sources › Systems,
creates a read-only API token in Cloudflare with three read permissions (Zone:
Zone Read, Account: Account Analytics Read and Zone: DMARC Management Read, with
DMARC Management turned on for the zone), and pastes the token and the zone ID.
Maplith never reads a message and never changes anything in Cloudflare. A
Cloudflare connection is not scanned into the map. It gives Maplith one thing to
do for you: the **email domain check**, on by default. Every morning Maplith
checks that mail sent as your domain is protected (SPF, DKIM and DMARC), and
raises a `dmarc_drift` signal when something needs a look.

- **Turn the check off** from the connection's **More** menu. Maplith then
  closes the check's open signals, and turning it on again checks at the next
  morning check. The setup (domains, known senders and policy steps) is kept.
- **A refused token keeps the setup.** If Cloudflare stops accepting the token,
  the connection shows **Needs attention** and the check pauses. An admin
  chooses **Replace token** on the Cloudflare row and pastes a new read-only
  token; the domains, known senders and policy steps stay as they were.
  **Remove** deletes them with the connection.

### Triple Whale

Triple Whale connections are held pending verification. A first connection lists
the available tools for review and reads no account data. The intended read plan
covers totals by period and channel, never individual orders or customer rows.
Where it is not open to your workspace yet, an admin or builder can choose
Connect on its card under Data sources › Systems to ask Maplith to set it up:
the card then says Maplith is setting it up, and Connect appears there when it
is ready. Nothing in Triple Whale changes.
See the [Triple Whale guide](/docs/md/systems/triplewhale).

### What every connector does, and does not

- **You give access once**, in the system's own consent screen or token page,
  and never paste a credential into a chat. Maplith seals it and does not show
  it again.
- **A connector reads and changes nothing.** The one that can write is the
  separate GitHub app, Maplith Agents, which you install on purpose. Your own
  agent acts in the system with its own access, and asks Maplith's action
  gate first when you have set a policy.
- **You can remove it** under Data sources › Systems. Where the system lets Maplith
  revoke its own access, Maplith does that first and says so; either way it
  deletes its copy of the credential. The map already built from the system
  stays, and is marked as no longer kept up to date.
- **Each system's guide says what is read**, with the permissions it needs
  and why: [System guides](/docs/systems), or the `maplith://systems/<system>`
  resource your agent can read.