# acquaint.tools

The single source of truth for every surface: plain functions, flat arguments in, JSON-ready dicts out.

The CLI is `cw` over [`TOOLS`](#acquaint.tools.TOOLS); the MCP server exposes the same functions (by
`acquaint.tools:<name>` reference); the shipped skills describe these verbs. Nothing
in this module knows about any of those surfaces.

Every tool takes `data_dir` (default: `$ACQUAINT_DATA_DIR`, else `data_dir` in
`~/.config/acquaint/config.toml`, else `~/.local/share/acquaint`). Every result carries
`ok` and a one-line `summary`; long human-readable content is in `text`.

Tools never act on a guess. A name, alias, handle or email counts only when exactly one
entity has it exactly; a partial match is returned as a suggestion. `rename` and
`forget` need the exact id. Library callers with their own store use the core
functions ([`acquaint.lookup.find_entity()`](acquaint.lookup.html.md#acquaint.lookup.find_entity), `acquaint.brief.compose_brief()`, …)
with a [`Store`](acquaint.store.html.md#acquaint.store.Store).

### Module Attributes

| [`TOOLS`](#acquaint.tools.TOOLS)        | Every tool, in the order surfaces list them.                                     |
|---------------------------------------------------------------|----------------------------------------------------------------------------------|
| [`SIDE_EFFECTS`](#acquaint.tools.SIDE_EFFECTS) | What each tool changes, for surfaces that must decide what to expose or confirm. |

### Functions

| [`brief`](#acquaint.tools.brief)(person, \*[, purpose, project, ref, ...])    | Everything to know before writing to someone: card, writing style, reach, project norms, recent observations, gaps.                                                                                                                                                                                                                      |
|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`check`](#acquaint.tools.check)(text, \*[, data_dir])                        | Scan prose that names people before publishing it: conflations (one person written as two), ambiguous names, unknown names.                                                                                                                                                                                                              |
| [`digest`](#acquaint.tools.digest)(entity[, ref, data_dir])                    | The digests of an entity's conversations (notes on what each said, kept in `digests/`) and their watermarks: how far each was processed, per scope (`content`, `style`).                                                                                                                                                                 |
| [`digest_append`](#acquaint.tools.digest_append)(entity, ref, \*, heading, rows)      | Add a dated batch to a digest: a `### <heading>` block (e.g. the date range) at the end of each section named in `rows`.                                                                                                                                                                                                                 |
| [`digest_mark`](#acquaint.tools.digest_mark)(entity, ref, \*[, through, ...])       | Record that a conversation has been processed through `through` (the ISO time of the last message processed), for `scope` (`content` or `style`), and/or that it was last read at `checked` (ISO time; a quiet channel has no new message, so `through` cannot say it was looked at).                                                    |
| [`digest_new`](#acquaint.tools.digest_new)(entity, ref, \*[, archive, data_dir])   | Create the digest of one conversation (`ref`, a correspond reference) for an entity, from the template: Orientation, Takeaways, Themes, Index, Open threads, and an empty watermark.                                                                                                                                                     |
| [`digest_sweep`](#acquaint.tools.digest_sweep)(entity, channel, \*, checked[, ...])  | Record a sweep of a channel (`slack`, `whatsapp`, ...): stamp `checked` (ISO time with an offset, when the sweep read them) on the digests it read, quiet ones included.                                                                                                                                                                 |
| [`disclosure`](#acquaint.tools.disclosure)(people, \*[, projects, audience, ...])  | Who may be told what, before writing to a set of readers (ids or channel identities, plus an optional correspond `audience` record as JSON): the tier and clearance in force for each, the least clearance, which records each is cleared for, the seals, the vocabulary a gate must scan for, what each was already told, and the gaps. |
| [`forget`](#acquaint.tools.forget)(entity, \*[, confirm, data_dir])            | Remove an entity's folder and leave a salted tombstone.                                                                                                                                                                                                                                                                                  |
| [`lint`](#acquaint.tools.lint)([entity, data_dir])                           | Check records: every preference, view and rule sourced; tiers, labels and seals set by the operator; nothing POLICY.md forbids; files parse; entry files within budget.                                                                                                                                                                  |
| [`new`](#acquaint.tools.new)(kind, name, \*[, qualifier, description, ...]) | Create a person, project, org or group from its template (a readable slug id; `qualifier` separates two of the same name).                                                                                                                                                                                                               |
| [`reach`](#acquaint.tools.reach)(person, \*[, purpose, urgency, ...])         | Ordered channels for reaching someone in a context.                                                                                                                                                                                                                                                                                      |
| [`refresh_due`](#acquaint.tools.refresh_due)(entity, \*[, today, data_dir])         | Is the record due for a refresh from its corpora? Per corpus (`refresh.toml` beside `sources.md`): the watermark in `sources.md`, how many items are newer, the threshold; plus the age of the last refresh against `max_age_days` (default 7).                                                                                          |
| [`remember`](#acquaint.tools.remember)(entity, text, \*[, source, kind, ...])    | Append a dated observation (`observation`, `interaction`, `identity`, `preference`, `view`, `rule`) to an entity's log, with its source.                                                                                                                                                                                                 |
| [`rename`](#acquaint.tools.rename)(entity, to, \*[, data_dir])                 | Change an entity's id (`to` is a slug) or name and id (`to` is a name), rewriting links to it.                                                                                                                                                                                                                                           |
| [`resolve`](#acquaint.tools.resolve)(handle, \*[, data_dir])                    | Map a channel handle (`github:octocat`, `email:ada@example.org`) to the entity it belongs to, with the evidence.                                                                                                                                                                                                                         |
| [`review`](#acquaint.tools.review)(person, \*[, today, data_dir])              | Everything the store says about one person's disclosure standing, with sources and dates, to confirm when a collaboration ends, when someone changes role, or before a tier changes: tier entries, links, the default tiers and clearances reached through links, seals on records and on fact lines, and the rules that name them.      |
| [`style_lint`](#acquaint.tools.style_lint)(text, \*[, recipient, tolerance, ...])  | The deterministic half of deslop: machine-writing tells in a draft, at the recipient's tolerance and against their blocklist.                                                                                                                                                                                                            |
| [`sync_init`](#acquaint.tools.sync_init)(\*, repo[, remote_url, ...])             | Make the data root a checkout of a PRIVATE GitHub repository (created private through `gh` unless `existing_only`), with a pre-push guard.                                                                                                                                                                                               |
| [`sync_pull`](#acquaint.tools.sync_pull)(\*[, dry_run, data_dir])                 | Pull the store from its private remote, rebasing local work on top.                                                                                                                                                                                                                                                                      |
| [`sync_push`](#acquaint.tools.sync_push)([ids, message, all, ...])                | Commit, rebase onto the remote and push the store, after re-checking the remote, the guard and the visibility.                                                                                                                                                                                                                           |
| [`sync_status`](#acquaint.tools.sync_status)(\*[, check_visibility, data_dir])      | Whether the store is synced, to which repository, uncommitted changes, ahead/behind, the guard, and live visibility.                                                                                                                                                                                                                     |
| [`todo_preflight`](#acquaint.tools.todo_preflight)(project, people, \*[, data_dir])    | Before filing a meeting's todos as GitHub issues: is the project unambiguous, is every participant (comma-separated) registered and linked to it, and does it declare a meta repository that is private now? Returns the repository, each person's GitHub login, and a fix for every problem.                                            |
| [`who`](#acquaint.tools.who)(name, \*[, field, brief, data_dir])            | Look up one person, project, org or group by exact id, name, alias, handle or email.                                                                                                                                                                                                                                                     |

### Exceptions

| [`AcquaintError`](#acquaint.tools.AcquaintError)   | An expected failure with a message meant for the person or agent that asked.   |
|------------------------------------------------------------------|--------------------------------------------------------------------------------|

### *exception* acquaint.tools.AcquaintError

Bases: [`Exception`](https://docs.python.org/3/builtins/exceptions.html#Exception)

An expected failure with a message meant for the person or agent that asked.

### acquaint.tools.SIDE_EFFECTS *= {'brief': 'read', 'check': 'read', 'digest': 'read', 'digest_append': 'rewrite', 'digest_mark': 'rewrite', 'digest_new': 'create', 'digest_sweep': 'rewrite', 'disclosure': 'read', 'forget': 'destructive', 'lint': 'read', 'new': 'create', 'reach': 'read', 'refresh_due': 'read', 'remember': 'append', 'rename': 'rewrite', 'resolve': 'read', 'review': 'read', 'style_lint': 'read', 'sync_init': 'external', 'sync_pull': 'rewrite', 'sync_push': 'external', 'sync_status': 'external-read', 'todo_preflight': 'external-read', 'who': 'read'}*

What each tool changes, for surfaces that must decide what to expose or confirm.
`read` changes nothing and stays local; `append` adds to a log; `create` adds a
record; `rewrite` changes existing records; `destructive` removes data;
`external-read` queries a remote service; `external` acts on one.

### acquaint.tools.TOOLS *= [<function who>, <function resolve>, <function check>, <function reach>, <function brief>, <function remember>, <function lint>, <function new>, <function rename>, <function forget>, <function sync_init>, <function sync_push>, <function sync_pull>, <function sync_status>, <function style_lint>, <function disclosure>, <function review>, <function todo_preflight>, <function digest>, <function digest_new>, <function digest_append>, <function digest_mark>, <function digest_sweep>, <function refresh_due>]*

Every tool, in the order surfaces list them.

### acquaint.tools.brief(person, , purpose=None, project=None, ref=None, audience=None, data_dir=None)

Everything to know before writing to someone: card, writing style, reach, project norms, recent observations, gaps. With `ref` (the conversation the message goes to; correspond is asked who can read it, and an unknown audience is public) or `audience` (an audience record as JSON), it opens with the ceiling, the records not to identify, how many lines were withheld, and what they were already told.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.check(text, , data_dir=None)

Scan prose that names people before publishing it: conflations (one person written as two), ambiguous names, unknown names.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.digest(entity, ref=None, , data_dir=None)

The digests of an entity’s conversations (notes on what each said, kept in `digests/`) and their watermarks: how far each was processed, per scope (`content`, `style`). With `ref` (a correspond reference, e.g. `whatsapp:ada-lovelace`), that one digest and `since`, the time to hand to `correspond read <ref> --since` for what is new. Reads only.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.digest_append(entity, ref, , heading, rows, through=None, scope='content', force=False, data_dir=None)

Add a dated batch to a digest: a `### <heading>` block (e.g. the date range) at the end of each section named in `rows`. `rows` is JSON `{"Takeaways": ["line [at: <ISO time>]"]}`, or `section | line | anchor` rows (one per line), or `@<path>` to read either from a file. Lines under Takeaways, Themes, Index and Open threads need an `[at: …]` or `[source: …]` anchor, else nothing is written. With `through` (ISO time of the last message processed), the watermark moves in the same call.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.digest_mark(entity, ref, , through=None, checked=None, scope='content', force=False, data_dir=None)

Record that a conversation has been processed through `through` (the ISO time of the last message processed), for `scope` (`content` or `style`), and/or that it was last read at `checked` (ISO time; a quiet channel has no new message, so `through` cannot say it was looked at). Moving either back needs `force`.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.digest_new(entity, ref, , archive='correspond', data_dir=None)

Create the digest of one conversation (`ref`, a correspond reference) for an entity, from the template: Orientation, Takeaways, Themes, Index, Open threads, and an empty watermark. `archive` names where the messages themselves live (never this store).

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.digest_sweep(entity, channel, , checked, refs=None, archive='correspond', force=False, data_dir=None)

Record a sweep of a channel (`slack`, `whatsapp`, …): stamp `checked` (ISO time with an offset, when the sweep read them) on the digests it read, quiet ones included. With `refs` (conversation references `<channel>:...`, one per item or comma-separated) exactly those are stamped, each created first if it has none; without, every digest of the channel is. A digest checked later keeps that later time (see `kept_later`). `digest` then reports `swept`: the oldest `checked` per channel.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.disclosure(people, , projects=None, audience=None, today=None, data_dir=None)

Who may be told what, before writing to a set of readers (ids or channel identities, plus an optional correspond `audience` record as JSON): the tier and clearance in force for each, the least clearance, which records each is cleared for, the seals, the vocabulary a gate must scan for, what each was already told, and the gaps. `projects` limits the records to those plus people. Reads only.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.forget(entity, , confirm=False, data_dir=None)

Remove an entity’s folder and leave a salted tombstone. Needs the exact id; without `confirm`, only reports what would be removed.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.lint(entity=None, , data_dir=None)

Check records: every preference, view and rule sourced; tiers, labels and seals set by the operator; nothing POLICY.md forbids; files parse; entry files within budget.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.new(kind, name, , qualifier=None, description=None, force=False, data_dir=None)

Create a person, project, org or group from its template (a readable slug id; `qualifier` separates two of the same name).

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.reach(person, , purpose=None, urgency=None, project=None, message_type=None, topic=None, data_dir=None)

Ordered channels for reaching someone in a context. Only active addresses; returns them, sends nothing. `outcome` is `reachable`, `no_address` (a rule matched, but neither states an address nor finds a usable one recorded for its channels) or `no_channel`. Each channel’s `address_kind` is `stated`, `identity` (the person’s handle, which a conversation-addressed channel does not take) or `None`.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.refresh_due(entity, , today=None, data_dir=None)

Is the record due for a refresh from its corpora? Per corpus (`refresh.toml` beside `sources.md`): the watermark in `sources.md`, how many items are newer, the threshold; plus the age of the last refresh against `max_age_days` (default 7). `outcome` is `due` (exit 0), `not_due` (exit 1: nothing fired and everything was checked) or `unchecked` (exit 4: nothing fired, but a corpus, the config or the record could not be read; see `unchecked`). The result has the same keys whatever the outcome; a script should read `outcome` from `--json` rather than rely on the exit code alone. Reads only; never refreshes.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.remember(entity, text, , source=None, kind='observation', disclosed=None, reactivate=False, data_dir=None)

Append a dated observation (`observation`, `interaction`, `identity`, `preference`, `view`, `rule`) to an entity’s log, with its source. An `interaction` may list the records the message identified (`disclosed`: exact ids, never the text). An identity equal to an inactive one (`stale`, `retracted`, …) is refused, naming that entry and the command with which the operator can make it active again.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.rename(entity, to, , data_dir=None)

Change an entity’s id (`to` is a slug) or name and id (`to` is a name), rewriting links to it. Needs the exact id.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.resolve(handle, , data_dir=None)

Map a channel handle (`github:octocat`, `email:ada@example.org`) to the entity it belongs to, with the evidence.

`ok` is true only when an active identity on the named platform belongs to exactly
one entity. A handle without a platform (`@octocat`), a match by name only, an
inactive identity, or several owners all return `ok: false` with what was found.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.review(person, , today=None, data_dir=None)

Everything the store says about one person’s disclosure standing, with sources and dates, to confirm when a collaboration ends, when someone changes role, or before a tier changes: tier entries, links, the default tiers and clearances reached through links, seals on records and on fact lines, and the rules that name them. Not ok when an affiliation has ended while a permissive tier is still in force. Reads only.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.style_lint(text, , recipient=None, tolerance=None, data_dir=None)

The deterministic half of deslop: machine-writing tells in a draft, at the recipient’s tolerance and against their blocklist.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.sync_init(, repo, remote_url=None, existing_only=False, dry_run=False, data_dir=None)

Make the data root a checkout of a PRIVATE GitHub repository (created private through `gh` unless `existing_only`), with a pre-push guard.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.sync_pull(, dry_run=False, data_dir=None)

Pull the store from its private remote, rebasing local work on top.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.sync_push(ids=None, , message=None, all=False, allow_markers=None, dry_run=False, data_dir=None)

Commit, rebase onto the remote and push the store, after re-checking the remote, the guard and the visibility. With `ids` (records, e.g. `person:ada-lovelace`), commit only those records and leave other uncommitted records alone; without, commit everything, but a `message` must then name every record it commits unless `all`. A file holding conflict markers is refused unless its path (relative to the store, e.g. `people/ada-lovelace/PROFILE.md`) is in `allow_markers` (list every path after one flag, and put record ids before it): for a record that quotes a conflict block on purpose.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.sync_status(, check_visibility=True, data_dir=None)

Whether the store is synced, to which repository, uncommitted changes, ahead/behind, the guard, and live visibility.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.todo_preflight(project, people, , data_dir=None)

Before filing a meeting’s todos as GitHub issues: is the project unambiguous, is every participant (comma-separated) registered and linked to it, and does it declare a meta repository that is private now? Returns the repository, each person’s GitHub login, and a fix for every problem.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### acquaint.tools.who(name, , field=None, brief=False, data_dir=None)

Look up one person, project, org or group by exact id, name, alias, handle or email.

Costs scale with what you ask: `field` returns one value (`aka`, `email`,
`github`, `label`, `tier`, any frontmatter key, or a dotted fact name such as `name.full`: only a current `clear` fact is readable here, a stricter one is refused), `brief` the identity block, and the default the
whole entry file. It never guesses: no exact match, or several, returns the
candidates and `ok: false`.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)
