Keep a backlink ledger in your repository

A backlink ledger records what you want or expect from a source page, alongside the target it should link to. Keep that intent separate from the verifier's observations. Your agent can then explain a disagreement without rewriting your expectation to match the latest fetch.

AgentLinkOps uses a local ledger contract with JSON Lines files. The examples below describe the private CLI reviewed on September 12, 2026. Public package distribution and licensing remain pending; these commands assume authorized access to that CLI. They are not instructions to install an available public package.

Separate intent from the latest result

An expected backlink can survive a failed check. The publisher may block automated requests, the network may time out, or the page may need a browser. None of those attempts tells you to erase the expectation.

The current ledger accepts three intent values: wanted, expected and retired. A wanted link represents an opportunity you care about. An expected link represents a relationship you expect to find. Retired records preserve a decision to stop treating that relationship as active intent. A verified earned placement is an outcome to describe through evidence; earned is not one of those three intent values.

That distinction prevents a common recordkeeping problem. If a single status cell mixes prospecting, outreach and verification, an agent cannot tell whether “missing” means nobody has pitched the publisher or a promised placement disappeared.

Use one complete record per line

JSON Lines requires each line to hold a valid JSON value and uses UTF-8. AgentLinkOps narrows that format to one ledger object per line. Its stable identifiers let observations refer to the same relationship after you edit a note.

This is a synthetic record using reserved example domains:

{"id":"lk_trail001","intent":"expected","source":"https://publisher.example/resources","target":"https://example.com/trail-access","scope":"exact","expect":{"anchor":"trail access guide"},"ref":"campaign/trails-2026","note":"Synthetic record for this walkthrough"}

The source is the page carrying the backlink. The target is your destination. Exact scope asks about that destination URL. Broader domain or path scopes answer different questions, so choose them deliberately instead of treating them as interchangeable shortcuts.

Keep the note short enough to explain the decision. Save longer research in a campaign document and use the reference field to connect it. Do not put credentials, private mailbox tokens or unrelated customer information inside a record that may enter version control.

Know which local file owns each fact

By default, the CLI stores links.jsonl, observations.jsonl, events.jsonl, candidates.jsonl and state.json under .linktrail/. Configuration can change those paths. The ledger owns intent; observations own dated check results; state holds such details as when entries were checked and where event feeds last resumed.

A reviewable file split lets you answer separate questions. What did we ask to watch? What did a check establish? Which changes arrived from the service? A report that combines those questions should preserve their source fields.

Version-control choices depend on the records' sensitivity and size. A team might commit a sanitized intent ledger while excluding growing observations and local state. Decide that policy before the first commit. A repository location alone does not make every generated file suitable for publication.

Review a local change before checking pages

For an authorized CLI, these commands create a ledger entry and inspect local status:

linktrail init
linktrail add --source https://publisher.example/resources --target https://example.com/trail-access --intent expected --anchor "trail access guide"
linktrail status

The domains are illustrative and do not demonstrate a real placement. Review the saved record before requesting a live check against actual URLs. linktrail check uses the local verifier and can make network requests to those source pages. Its result needs the same care as a hosted observation: unknown is still unknown.

Use the CSV import guide when the starting material is a supplier export. The CLI import command previews candidates; it does not silently add every imported row as an expected placement.

Preserve disagreements and history

Suppose your ledger expects an exact article URL, but the publisher now links to your homepage. Keep the original expectation until you decide whether that change is acceptable. The observation and the decision both matter.

If a teammate accepts the homepage link, update the target or scope with a note explaining why. A future reader should not have to infer that choice from a changed URL alone. This also helps your agent produce a useful diff instead of a list of unexplained field changes.

Hosted synchronization adds another history stream. Read cursor-based event sync before writing your own consumer, and use agent approval boundaries to decide which changes an unattended run may make. The agent workflow hub keeps these related procedures together.

Sources

1. JSON Lines · JSON Lines · Undated; accessed 2026-09-12