agentlinkops 0.5.0

package/references/cli.md

@@ -0,0 +1,198 @@
+# Local CRM contract
+
+Version 0.2.0; SQLite schema version 4. Python 3.10+ is the only prerequisite.
+Examples assume the working directory is this plugin root. Resolve paths from
+the installed plugin location when running from a skill. Choose a database
+path in the user's working directory, outside the replaceable plugin cache.
+
+```sh
+python3 scripts/agentlinkops.py --db ./agentlinkops.sqlite init --workspace local-example
+python3 scripts/agentlinkops.py --db ./agentlinkops.sqlite status
+python3 scripts/agentlinkops.py templates
+python3 scripts/agentlinkops.py --db ./agentlinkops.sqlite product upsert --file product.json
+python3 scripts/agentlinkops.py --db ./agentlinkops.sqlite opportunity list
+python3 scripts/agentlinkops.py --db ./agentlinkops.sqlite export --format json --output crm-export.json
+python3 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 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.

package/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
+
+Run from the installed plugin root and keep the database outside its cache:
+
+```sh
+python3 scripts/agentlinkops.py --db ./agentlinkops.sqlite migrate
+python3 scripts/agentlinkops.py --db ./agentlinkops.sqlite disavow import --property https://my-product.com/ --source "User-reviewed existing list" --file existing-list.txt
+python3 scripts/agentlinkops.py --db ./agentlinkops.sqlite disavow list --property https://my-product.com/
+python3 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 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/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 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 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.