agentlinkops 0.6.13 → 0.6.16

package/skills/agentlinkops-discovery/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-discovery/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-discovery/references/portable/references/discovery-handoff.md

@@ -0,0 +1,32 @@
+# From research to a checked shortlist
+
+Keep research notes beside the user's project. The graph release, source retrieval date and qualification explain why a page is on the shortlist. They do not establish a live backlink.
+
+Use `agentlinkops skill --list` to see the installed set and `agentlinkops skill agentlinkops-discovery` to read the research workflow. `agentlinkops skill` still prints the connection and evidence reference.
+
+Create a CSV with exact source and target pages:
+
+```csv
+source_url,target_url
+https://publisher.example.org/resources,https://example.com/guide
+```
+
+Preview normalization before writing:
+
+```sh
+agentlinkops import shortlist.csv --target example.com --from csv --map source=source_url,target=target_url
+```
+
+The preview is not a live check or a watch. Inspect accepted and rejected rows. For a selected opportunity that has not been earned, initialize a local ledger when needed and add it as wanted:
+
+```sh
+agentlinkops init
+agentlinkops add --source https://publisher.example.org/resources --target https://example.com/guide --intent wanted --note "Research candidate; link not yet earned"
+agentlinkops check --all --json
+```
+
+The local check includes wanted entries; `--all` rechecks the selected rows even if their cadence is not yet due. Keep observed absence separate from unknown access failures. Once the user has an earned placement, record the exact source/target pair as expected and retain the observation date and evidence.
+
+For an already connected workspace, `agentlinkops tools monitoring` and `agentlinkops describe monitor_link` expose the current hosted contract. Inspect project IDs and usage first. Enroll selected source/target pairs only when recurring monitoring is within the user's request; record the returned watch IDs. A successful import or local check alone does not create a recurring hosted job.
+
+Use the customer's brief and evidence to decide the next campaign step. For additional guidance, select `agentlinkops agent setup --skill agentlinkops-campaigns` and read that installed skill. The [CRM reference](cli.md) covers optional records when the user needs contacts and activities beside the ledger. Outreach stays in the user's chosen tool and requires their instruction.

package/skills/agentlinkops-discovery/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.