Import Guidelines

A person never starts a Wisent product from an empty state. Every product finds what the person already keeps in other tools, files, applications and service accounts, shows it without sensitive values, moves it with one command (and the same operation in its desktop, web and mobile clients), and, where the source keeps working, switches it over to the product instead of leaving two copies. This page is the one sources contract every product adopts; existing import commands stay as entries into the same adapters, with their current answers.

Adapters and their steps

Every source is an adapter with an identifier IMP-<PRODUCT>-<NN>, one source per identifier. Kinds: E an export file, D an application's database or directory on disk, S a system store (keychain, credential manager, Secret Service, device contacts and health), F a tool or project configuration file, A a service API reached with the person's permission, W content on the web the person names.

1. discover: whether the source is on this machine or account and what it holds (names, counts, date range, format version), never a value; recognized by structure (schema, header, columns, key format), never by a list of words.
2. preview: what would be created, what is already there, what conflicts; writes nothing.
3. import: writes only through the product's one write path, idempotently; the same source record a second time adds nothing.
4. release: only after a confirmed import; the source stops being a second copy (redirect, helper, removal of the value, or a mark in the source).
5. sync: the same adapter incrementally from a cursor, for sources that keep living.
6. forget: removes everything one adapter, or one import, brought in.

Commands

• <product> sources [--all]: adapters that fit this system, each with its discovery.
• <product> sources discover|preview <adapter> [--path P] [--account role:R] [--select …] [--map FILE].
• <product> sources import <adapter> [--select …] [--map FILE] [--on-conflict keep|replace|ask] --yes.
• <product> sources release|forget <adapter> [--import ID] --yes, sources sync <adapter> [--once|--watch], sources resolve <record> --keep product|source, sources log.
• <product> gui: a loopback browser importer for products with no application, as las gui already serves.
• <product> doctor --check import-sources: every source that still keeps data outside the product, with the command that moves it.
• The same operations over the product API: GET /v1/sources, POST /v1/sources/{discover,preview,import,release,sync,resolve,forget}, GET /v1/sources/log. Clients use only the API.
• Every command takes --scope organization for an administrator importing every member of an organization through the source's administrative API; each record lands in its own member's space.

Answers

discover answers adapter, source, kind, found, format (name, version), where, counts, range and blocked (a declared cause and its fix when the source is there but cannot be read). preview answers would_create, already_there, conflicts, handed_to (data another product owns, by its Stado family, with whether the family resolved), mapping and consent. import answers import_id, created, updated, unchanged, skipped, handed_to and cursor. Every count is counted from what was read; sensitive fields (passwords, message bodies, health values) appear only as counts.

Provenance, mapping and sync

• Every imported record keeps provenance: adapter, import id, the record's id in the source, when it was read, the format version, and the administrator for an organization import.
• Fields recognized by the source's structure are mapped in preview; a model reached through Stado's inference alternatives may propose a mapping for unknown columns, always shown and confirmed, and the same screen works without it. A confirmed mapping is kept per source.
• sync reads only changes after its cursor, source to product. A record changed on one side only takes that side. A field changed on both sides stays as the product holds it and is listed as a conflict until a person resolves it. A record deleted in the source is marked, never deleted, in the product; a record deleted in the product is not brought back unless it changes in the source, which makes it a conflict. Writing back to a source only for adapters that declare it, with separate consent.

Ownership between products

A product imports only its own domain. Data of another domain found on the way goes to the owning product through Stado's alternatives (stado capabilities resolve <family> --consumer <product>): secrets to Skarbiec, mail to Skrzynka, messages to Most, transcripts of conversations with AI to Transcript Lake, contacts to Kupiec. When the family does not resolve, that part is skipped with its reason in preview and the rest imports. Credentials for kind A sources are read from Skarbiec by role tag; an import never asks for a token to be pasted. No import waits on Brama.

Declared causes

• sources.adapter-unknown, sources.not-found, sources.format-version-unknown (names the version read and the versions known), sources.consent-missing, sources.credentials-missing (names the role to tag), sources.legal-review-missing, sources.release-before-import, sources.conflicts-open, and sources.family-unresolved (a warning in preview, never a refusal of the rest).

Privacy, law and release

• Import of the person's own data for the purpose they chose (data portability). Third parties' data only as the copy the person already holds, never enriched without a separate basis, with its scope shown in preview. Special categories (health) only after explicit consent recorded in the product.
• An adapter for health, legal matters, third parties' messages and contacts, introductions, account automation through Weles, direct reads of application databases, or organization imports enters a release only with a lawyer's written approval recorded for that adapter version; without it the release check refuses.
• An import log records who imported what, when, from which adapter, how many records and under which consent, without content.

Formats, export and drift

• One parser per shared format in the wisent-formats library, linked as a library, so services stay independent; a product moving to it removes its own parser in the same change.
• Every open format a product imports, it also exports, and every adapter is tested export, import into an empty state, same state.
• Each adapter has a weekly Probierz journey on a fresh export from a company test account; a failure records an Oko defect for the owning product with the adapter identifier and the format version it refused.
• Discovery counts, with the person's consent and never names or values, go to the onboarding domain as import-source-discovered, so the order in which adapters are written follows what people actually have.

Completion gate

An adapter is complete when discovery on a real test export, file, database or account names the source, its format version and correct counts; preview writes nothing; import writes once and a second import adds nothing; unknown versions and every failure are declared causes; the export round trip holds; release follows a confirmed import; forget removes the import; CLI, application or gui, mobile client where the source exists on a phone, and documentation agree on every platform the source exists on; its Probierz journey runs weekly; handed-off data goes through the owning product's family; and, where required, its legal approval is recorded.