agentlinkops 0.6.11 → 0.6.16

package/skills/agentlinkops-crm/references/portable/references/cli.md

@@ -0,0 +1,220 @@
+# Local CRM contract
+
+Version 0.2.0; SQLite schema version 4. Python 3.10+ is the only prerequisite.
+Resolve example helper paths from the plugin root for shared references, or from
+the skill directory for a standalone archive's bundled references. Choose a database
+path in the user's working directory, outside the replaceable plugin cache.
+
+```sh
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite init --workspace local-example
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite status
+python3 references/portable/scripts/agentlinkops.py templates
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite product upsert --file product.json
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite opportunity list
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite export --format json --output crm-export.json
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite export --format csv --entity placement --output placements.csv
+```
+
+`init` binds this database to exactly one workspace ID. Use an actual cloud
+workspace ID if cloud sync is planned. For a purely offline CRM, choose a
+stable local name. Workspace and cloud-origin binding cannot be silently
+changed. A separate local database is required for a different workspace.
+
+`migrate` creates a SQLite backup before applying pending migrations. It
+refuses unrelated databases, newer schema versions and changed migration
+checksums. Initialization is idempotent for the same workspace. The CLI has
+no destructive reset command. SQLite is not encrypted; rely on the user's
+device security and store the file in an appropriate location.
+
+`upsert` reads one object or an atomic array of objects from a file or stdin
+(`--file -`, the default). IDs are explicit, stable strings; updating an
+existing record changes only supplied fields. References must already exist;
+insert product, campaign/contact, opportunity, then activity/placement.
+
+| Entity | Required for a new record, plus `id` | Optional editable fields |
+|---|---|---|
+| product | `name`, `url` | `audience`, `description`, `target_pages` (URL array), `notes` |
+| campaign | `name`, `type` | `product_id`, `template_version`, `status`, `goal`, `target_url`, `notes` |
+| contact | `publisher_url` | `name`, `email`, `contact_url`, `source_url`, `observed_at`, `confidence`, `notes` |
+| opportunity | `source_url`, `target_url` | `campaign_id`, `contact_id`, `type`, `status`, `evidence` (object), `notes` |
+| activity | `kind`, `occurred_at` | `opportunity_id`, `contact_id`, `campaign_id`, `channel`, `external_message_id`, `outcome`, `notes` |
+| placement | `source_url`, `target_url` | `opportunity_id`, `project_id`, `watch_id`, `status`, `notes`, `cost_amount`, `cost_currency` |
+
+Timestamps require ISO 8601 with a timezone. Link fields require HTTP(S) URLs.
+Null clears an optional relationship ID. Passwords, API keys, tokens,
+mailbox credentials and email/message body fields are rejected. Never put
+those values into free-text notes either. Contact confidence describes the
+evidence, not a promise of email delivery.
+
+Example `product.json`:
+
+```json
+{"id":"product-example","name":"Example Resource","url":"https://example.com/","audience":"Resource-page readers","target_pages":["https://example.com/guide"]}
+```
+
+Example opportunity evidence:
+
+```json
+{"id":"opportunity-example","source_url":"https://publisher.example/resources","target_url":"https://example.com/guide","type":"resource_addition","evidence":{"source_url":"https://publisher.example/resources","observed_at":"2026-09-09T12:00:00Z","context":"Relevant resources section; candidate requires browser review."}}
+```
+
+Use `entity list --id ID` to retrieve a specific record. JSON exports preserve
+all fields, raw events, the sync cursor, disavow rules and their source provenance. They are portable data exports,
+not an automatic full-database restore format. CSV exports select one entity
+and prefix possible spreadsheet formulas with `'`; JSON is lossless.
+Export files are created with restrictive permissions and never overwritten.
+For a restorable database backup, use SQLite's backup API or the SQLite CLI
+`.backup` command; do not copy a live database file while a write is running.
+
+## Disavow lists and placement reports
+
+For user-selected disavow files, read [the disavow contract](disavow.md).
+The `disavow import/upsert/list/export` commands work offline, require an
+explicit URL-prefix property and preserve source provenance. No command
+uploads to Google or chooses rules from automated risk labels.
+
+For branded HTML output, read [the report contract](reports.md). The `report`
+command supports a project filter and optional local notes/cost fields. Notes
+and costs are excluded unless explicitly included. Record a placement cost
+as a decimal string paired with an uppercase currency label, for example
+`"cost_amount":"12.50","cost_currency":"USD"`. Clear both fields with null.
+The CLI validates decimal precision and reports each currency separately.
+It does not verify currency labels against a current exchange-rate service.
+
+Existing CRM databases require `migrate` before using version 0.2.0. Schema
+versions 3 and 4 add disavow provenance tables and optional placement cost
+fields. Existing placements, notes, event history and workspace bindings are
+preserved; the helper creates a restorable database backup before upgrading.
+
+## Connect the ledger CLI to an existing project
+
+Local ledger commands work without an account. Cloud sync uses a separate scoped
+API key. MCP OAuth credentials stay in the MCP client and cannot authorize REST.
+
+1. Open the invited account's workspace at `https://app.agentlinkops.com/app`.
+   An owner or admin selects **Agent access > Create API key**. Choose the
+   existing project and the scopes `projects:read`, `watches:read`,
+   `watches:write`, `events:read`, and `exports:create`.
+2. Save the once-shown credential in the user's secret store. Supply it through
+   `AGENTLINKOPS_API_KEY` in the CLI process environment. The ledger CLI also accepts
+   `AGENTLINKOPS_TOKEN`; if both are set, they must agree. The `LINKTRAIL_` spellings are
+   still read, with a one-line warning, during the pilot compatibility window. Never paste credentials
+   into chat, command arguments, or ledger files.
+3. Run the installed CLI from the directory containing the existing `.agentlinkops/` (or `.linktrail/`)
+   ledger. Replace the script path and IDs below with the installed package path
+   and IDs returned by `get_workspace` and `list_projects`.
+
+```sh
+node /path/to/installed/plugin/cli/agentlinkops.mjs connect --origin https://app.agentlinkops.com --workspace WORKSPACE_ID --project-id PROJECT_ID --selection selected-links.json
+node /path/to/installed/plugin/cli/agentlinkops.mjs sync --dry-run
+node /path/to/installed/plugin/cli/agentlinkops.mjs sync --pull-only
+```
+
+`selected-links.json` contains an array of existing ledger IDs, such as
+`["local-placement-1", "local-placement-2"]`. A mapping file with
+`entries: [{"local_id": "local-placement-1"}]` also works. Save an explicit
+selection when only part of an existing ledger belongs in cloud monitoring.
+
+`connect` verifies workspace identity, project access and required scopes through
+read-only REST calls. It saves connection metadata and the selection in
+`.agentlinkops/config.json`, without saving the credential or creating cloud records.
+`sync --dry-run` reads local files only and previews uploads. `sync --pull-only`
+retrieves cloud history without creating watches. After reviewing the plan, run
+`sync` when the user has authorized its proposed monitoring. A saved selection
+limits uploads; without one, sync selects expected or earned entries and pauses mapped retired
+entries. Wanted entries require `--include-wanted`.
+
+The cloud stores normalized source URLs: `https://example.com` becomes
+`https://example.com/`. Send the ledger ID as `localReference` and join returned
+rows using `local_reference`. Raw URL string equality can miss an existing watch.
+Copy watch IDs from tool results without shortening them.
+
+The Python CRM helper has its own environment settings and workspace binding,
+described in [optional cloud sync](#optional-cloud-sync). Ledger `connect` does
+not configure that helper. If account access or permission to create a credential
+is unavailable, use the existing MCP connection for cloud work and keep local
+records intact.
+
+## Optional cloud sync
+
+Set `AGENTLINKOPS_API_URL` to the actual service origin and
+`AGENTLINKOPS_API_KEY` using the shell's existing secure environment mechanism.
+Create the scoped credential in **Agent access > Create API key** as described
+[above](#connect-the-ledger-cli-to-an-existing-project). For this read-only event
+sync, select `events:read` and the projects whose events the CRM should receive.
+This toolkit does not bundle credentials or create an account. Never paste keys into chat or command-line arguments.
+
+```sh
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite sync --limit 100 --max-pages 100
+```
+
+The client requests `GET /v1/events?limit=100&cursor=...`. Production origins
+require HTTPS. Loopback HTTP is supported for local development. Redirects
+are rejected so bearer credentials never follow an endpoint redirect.
+Requests time out after 30 seconds and responses are limited to 4 MiB.
+
+Expected response:
+
+```json
+{
+  "workspace_id": "workspace-example",
+  "events": [{
+    "id": "event-example", "workspace_id": "workspace-example",
+    "cursor": "opaque-cursor", "type": "watch.state_changed",
+    "project_id": "project-example", "watch_id": "watch-example",
+    "created_at": "2026-09-09T12:00:00Z",
+    "data": {
+      "before": {"state": "unknown"},
+      "after": {"state": "present", "source_url": "https://publisher.example/resources", "target_url": "https://example.com/guide"},
+      "observation_id": "observation-example", "evidence_key": null
+    }
+  }],
+  "next_cursor": "opaque-cursor", "has_more": false
+}
+```
+
+Each page commits new events, placement overlays and its cursor in one
+transaction. Duplicate event IDs are ignored only when the payload is
+identical. A changed payload, malformed event or mismatched workspace rolls
+back the entire page. Earlier successful pages remain committed if a later
+page fails; rerunning resumes at the last committed cursor. Two concurrent
+syncs detect a cursor conflict and require a retry.
+
+Events update placement `cloud_state`, `cloud_observed_at` and
+`cloud_event_id`. Existing local `status`, `notes` and opportunity links are
+preserved. URLs follow the cloud watch snapshot. A previously unseen watch
+creates `id: cloud:<watch_id>` only when the snapshot supplies source and
+destination URLs. Partial snapshots without a URL pair and unknown event types are retained in the event
+feed for later interpretation; they do not fabricate a placement.
+
+HTTP 410 reports `CURSOR_EXPIRED` and does not advance the cursor. Preserve
+the database and export first; obtain a current watch snapshot and recover
+into a separate database before replaying retained events. Automated snapshot
+recovery is not implemented in this version. Removing the cursor alone would
+hide a history gap and is not a supported recovery procedure.
+
+All success output is JSON except requested CSV export. Errors are JSON on
+stderr with nonzero exit status. HTTP response bodies and credential values
+are never included in errors. Local operation has no telemetry.
+
+## Writer-lock recovery candidate
+
+The maintained development source adds verified-owner recovery for `sync.lock`
+and the ledger's secondary writer lock. This source acceptance is separate from
+an installed release and hosted/client acceptance. A persistent OS advisory gate
+serializes cooperating writers; valid same-user/same-boot metadata for a departed
+writer can be recovered. Marker age alone never authorizes removal. Live, reused,
+legacy empty, malformed or unverifiable markers are preserved with a refusal.
+
+Keep the local ledger, mirror and state files. Read-only `status`/`report` remain
+useful while writer ownership is unresolved. Inspect a copy; do not delete a live
+lock or signal a process you did not create. An uncertain cloud request still
+needs its original operation/readback before any write is retried; releasing a
+local lock does not prove the remote request failed.
+
+The candidate uses pinned prebuilt native assets for Darwin/Linux, with no compiler
+fallback in the package build. Actual crash and relocated-package acceptance is
+recorded for Darwin arm64; other architectures, Windows, musl and network-file
+systems require separate proof. Unsupported/native-unavailable writers fail
+closed with actionable setup diagnostics. Native lock acceptance does not enable
+Darwin OAuth custody or establish customer credentials/grants.

package/skills/agentlinkops-crm/references/portable/references/disavow.md

@@ -0,0 +1,73 @@
+# User-managed disavow lists
+
+This is an offline record/file tool. It does not evaluate whether a link
+should be disavowed, connect to Search Console, or upload a file. Record the
+user's explicit choices and their provenance.
+
+Google's documented file format uses one page URL or `domain:hostname` per
+line, UTF-8 or ASCII `.txt` files, and `#` comment lines. The limits are 2,048
+characters per URL, 100,000 lines including comments/blanks, and 2 MB. Domain
+and subdomain rules are supported; a path prefix is not a domain-wide rule.
+The tool does not support Search Console Domain properties. Uploading a new
+list replaces the list for the selected property; local merging here does
+not establish what Google currently holds. Google says most sites do not
+need disavowals. [Official format and usage guidance](https://support.google.com/webmasters/answer/2648487?hl=en),
+checked September 9, 2026.
+
+## Commands
+
+Resolve example helper paths from the plugin root for shared references, or from the skill directory for a standalone archive's bundled references. Keep the database outside the installation directory:
+
+```sh
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite migrate
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite disavow import --property https://my-product.com/ --source "User-reviewed existing list" --file existing-list.txt
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite disavow list --property https://my-product.com/
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite disavow export --property https://my-product.com/ --output reviewed-disavow.txt
+```
+
+Every command requires the exact URL-prefix property. HTTP and HTTPS remain
+separate; a subdomain or path prefix remains separate from its parent. The
+helper records this local scope; it does not verify property ownership.
+
+Imports merge rules transactionally. Any invalid line rejects the entire
+file with no new rules or source record. Duplicates reuse stable rule IDs.
+Each source retains its label, original text and SHA-256; provenance records
+the original line, line number and associated comments. Reimporting identical
+content under the same source label is idempotent. A new source label adds
+provenance without duplicating the rule. Imports never overwrite local notes
+or reactivate a rule the user disabled.
+
+To add or explicitly change a rule, prepare `rule.json` and run:
+
+```sh
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite disavow upsert --property https://my-product.com/ --source "User decision after review" --file rule.json
+```
+
+```json
+{"kind":"domain","value":"publisher.example","active":false,"notes":"User removed this rule after reviewing the source."}
+```
+
+`kind` is `domain` or `url`. `active` defaults to the existing value, or true
+for a new rule. Omitted notes are preserved. Deactivation is reversible and
+retains provenance; there is no destructive delete command.
+
+Domain normalization changes case and a terminal DNS dot only. Hostnames
+must be ASCII or already Punycode; the helper does not guess IDN conversion.
+URLs preserve path case, query strings and fragments. A path ending in `/`
+is still one exact page URL; wildcard patterns are rejected. URL credentials
+and malformed domains are rejected. UTF-8 paths, LF/CRLF and an optional UTF-8
+BOM are accepted. Original source text remains available in the full JSON
+CRM export.
+
+`.txt` exports contain active rules for one property, sorted by rule kind and
+value with stable header comments. They omit timestamps and private notes,
+so unchanged rules produce identical bytes. The export is checked against
+the documented line limit and a conservative 2,000,000-byte ceiling, and never
+overwrites an existing file. The same byte ceiling applies to imports.
+Without `--output`, it writes the same text to stdout. The local list can be
+empty; an empty export is not evidence that a Google-side list was cleared.
+
+`disavow list --active-only` filters the view. The general `export` command
+includes all disavow rules, sources and provenance in the local JSON backup.
+No monitoring result, authority metric or contact inspection automatically
+creates a rule.

package/skills/agentlinkops-crm/references/portable/references/local-crm-draft-handoff.md

@@ -0,0 +1,76 @@
+# Local Outreach CRM draft handoff
+
+Use only when the customer selects a local Outreach CRM with an existing
+`projects/<crm_project>/config.json` and `drafts/` directory. The config must contain
+that exact `project` and a `site` URL with the same hostname as the request.
+This adapter writes an inert body and companion manifest under that project's
+drafts directory. It does not write contacts, replies, suppression, send logs or
+sequence state. Native vendor APIs remain unsupported by this adapter.
+
+Resolve example helper paths from the plugin root for shared references, or from the skill directory for a standalone archive's bundled references:
+
+```sh
+python3 references/portable/scripts/outreach-crm-draft.py --crm-root /path/to/customer-crm --request request.json --body-file reviewed-body.txt
+python3 references/portable/scripts/outreach-crm-draft.py --crm-root /path/to/customer-crm --request request.json --body-file reviewed-body.txt --readback
+```
+
+`request.json` contains exactly these fields; use actual saved identities rather
+than copying the example values:
+
+```json
+{
+  "version": 1,
+  "crm_project": "customer-project",
+  "workspace_id": "saved-workspace",
+  "project_id": "saved-project",
+  "site": "https://customer.invalid",
+  "operation_id": "original-operation",
+  "original_request": {
+    "destination": "saved-service-destination",
+    "workspace_id": "saved-workspace",
+    "project_id": "saved-project",
+    "command": "saved-command",
+    "arguments": {"saved-non-secret-argument": "saved-value"},
+    "idempotency_key": "original-request-key"
+  },
+  "local_id": "saved-local-record",
+  "external_id": "saved-crm-record",
+  "observation": "unknown",
+  "reply": "unknown",
+  "suppression": "unknown",
+  "subject": "Reviewed draft subject",
+  "body_sha256": "exact-sha256-of-reviewed-body-bytes"
+}
+```
+
+Preserve the original request tuple from its checkpoint, including its exact
+non-secret arguments. Never place credentials in it. Workspace/project binding
+is customer supplied; this helper does not authenticate it against hosted grants
+or confirm that an external ID exists in CRM contacts. Its local config check
+prevents an explicit site/project mismatch, not a forged customer mapping.
+
+`observation` is `unknown`, `present`, `provisional_loss` or `confirmed_loss`;
+`reply` is `unknown`, `none` or `replied`; `suppression` is `unknown`, `clear` or
+`suppressed`. These are retained observations, not refreshed sender decisions.
+Drafts always have `send_eligible: false`, including apparently clear rows.
+Follow the qualified campaign recipe's content review before saving a real draft.
+
+The original operation and local/external identities determine one stable draft
+directory. The helper verifies the supplied UTF-8 body hash, publishes `body.txt`
+and `manifest.json`, then rereads their exact bytes. An identical retry reports
+`identical_readback`. If interrupted between files, repeat the original save;
+it completes the missing artifact without replacing the existing body. A changed
+subject, body, request or mapping at that identity refuses rather than overwrites.
+Inspect and preserve the conflicting original artifact; a legitimate new operation
+requires a separately recorded identity, not a fabricated replay key.
+
+`--readback` verifies both artifacts and refuses missing or partial saves. It does
+not create a draft directory. Keep the receipt's operation, destination directory,
+body and manifest hashes with the customer's checkpoint. Saving here is actual
+local filesystem destination readback, not a mailbox/vendor acknowledgement.
+
+Publication reuses the portable helper's cooperating-writer locking and ExFAT
+fallback. Destination symlinks are refused. This does not sandbox arbitrary local
+applications or prove power-loss durability. No email system or network dependency
+is installed. Current sender reply/suppression/quota/mailbox gates must still be
+checked by the customer's existing sender at its separately authorized send step.

package/skills/agentlinkops-crm/references/portable/references/portable-ledger-handoff.md

@@ -0,0 +1,51 @@
+# Portable ledger handoff
+
+Capability: local draft-only file. Native vendor acceptance: untested. No network
+or messages. Workspace/project identities are supplied by the customer and are
+not verified against hosted grants by this helper.
+
+Run the CLI's frozen report first:
+
+```sh
+agentlinkops report --json --as-of 2026-09-30T12:00:00Z --out report.json
+python3 references/portable/scripts/portable-handoff.py --report report.json --mapping mapping.json --out handoff.json
+```
+
+Use your own observation cutoff, rather than copying this example's date.
+`mapping.json` requires version 1, workspace_id, project_id, site (an explicit URL),
+destination `portable-file`, source_report_sha256 and records. Compute the report
+hash from JSON encoded with sorted keys, compact separators and UTF-8; the helper's
+`digest` function defines it. This local command prints the value:
+
+```sh
+python3 -c 'import hashlib,json; r=json.load(open("report.json")); print(hashlib.sha256(json.dumps(r,sort_keys=True,separators=(",",":"),ensure_ascii=False).encode()).hexdigest())'
+```
+
+Each records key is an actual local ledger ID, with
+external_id, reply (`unknown`, `none`, `replied`) and suppression (`unknown`,
+`suppressed`, `clear`). Supply these from your own tools; an empty field never
+means permission to send. Every report row needs an explicit mapping. Unknown
+customer IDs must stay unknown; do not fabricate a mapping to make export pass.
+
+The handoff carries the original report state, observation date and evidence block,
+including any hash and locator, plus a stable operation ID. Notes and optional
+commercial references are not copied. `ref` is private by default in the report;
+this helper uses your explicit mapping instead. Identical reruns read the original
+file. A different report, site or existing output refuses before replacement.
+Keep a distinct output for a new snapshot; this is a dated artifact, not a monitor.
+
+Read the saved JSON back before claiming persistence. Its destination outcome is
+`not_attempted`, and `send_eligible` remains false on every row. Passing this helper
+does not prove a CRM import or sequencer readback. Before a destination write,
+retain the exact mapping and request, then read the destination back when authorized.
+After a response-lost import, preserve its actual operation identity and unknown
+outcome; do not replace it with this file's operation ID or repeat a create to
+repair an artifact error. Keep monitoring facts apart from sent/replied/suppressed
+records. For additional guidance, select `agentlinkops agent setup --recipe qualified-campaign-handoff`
+or `agentlinkops agent setup --recipe placement-reconciliation` and read the selected
+recipe. Neither is required to prepare this local file.
+
+Resolve example helper paths from the plugin root for shared references, or from
+the skill directory for a standalone archive's bundled references. Unsupported native
+vendors, mailbox access and automatic suppression synchronization remain outside
+this helper. No account, credential or send action is installed by it.

package/skills/agentlinkops-crm/references/portable/references/reports.md

@@ -0,0 +1,53 @@
+# Branded HTML placement reports
+
+Reports are generated entirely from the local CRM. They make no network
+requests, run no additional checks, and do not imply broader backlink-index
+coverage. The output is standalone HTML with embedded styles and print
+styling; it is not a generated PDF.
+
+```sh
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite report --project project-id --brand "My Agency" --title "Placement monitoring report" --output placements.html
+```
+
+Omit `--project` only when the requested report covers every local placement.
+By default, a report includes source/destination URLs, cloud-observed state,
+observation timestamp, report timestamp and aggregate placement counts.
+It excludes local notes, local costs, contacts, outreach activity, credentials,
+disavow rules, workspace IDs and raw event payloads. URLs are the selected
+records' actual URLs; review the selection before sharing the file.
+
+`--include-notes` and `--include-costs` explicitly add those private local
+fields. Use these only when the user requests that content. Included cost
+totals are calculated separately per currency without exchange rates.
+Local CRM status is not substituted for a verified cloud observation.
+
+Record a cost with an ordinary partial placement upsert:
+
+```json
+{"id":"placement-id","cost_amount":"12.50","cost_currency":"USD"}
+```
+
+Amounts are nonnegative decimal strings with at most six decimal places,
+not JSON floating-point numbers. Both amount and currency are required for
+a newly recorded cost. The currency is an uppercase three-letter label;
+the helper does not perform a current currency-directory lookup. Updating
+other fields or synchronizing cloud events preserves local costs. Set both
+cost fields to null to clear a cost explicitly.
+
+The generator escapes all text/attributes and creates clickable links only
+for HTTP(S) URLs without credentials. It loads no external scripts, fonts,
+logos or tracking pixels. The title and brand are user-selected text labels.
+Local notes remain escaped text, even if they contain HTML.
+
+Rows have a stable ordering. Supply a fixed `--generated-at` ISO 8601
+timestamp to reproduce identical output from the same data and options:
+
+```sh
+python3 references/portable/scripts/agentlinkops.py --db ./agentlinkops.sqlite report --title "Placement report" --generated-at 2026-09-09T14:00:00Z --output reproducible.html
+```
+
+Otherwise the timestamp is the current time. Coverage reports the range of
+stored observation times separately from report generation. Unknown and
+unobserved states remain distinct from confirmed loss. Existing output files
+are never overwritten. Browser printing, PDF generation and automated report
+delivery are separate capabilities and are not performed by this helper.