> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentlinkops.com/llms.txt > Use this file to discover all available pages before exploring further. # Local file contracts > Ledger rows, portable checks, observation mirrors and action receipt inputs. Use these contracts when another agent or script reads files produced by the [local CLI](/reference/local/index). [Configuration](/reference/local/configuration) owns their locations. Preserve unknown ledger/state fields when editing older files. ## Ledger rows `links.jsonl` contains one JSON object per line. Blank lines are ignored. IDs are unique; malformed rows are reported with line numbers and excluded from reads. Mutations refuse malformed input. | Field | Contract | | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | id | Required when reading; lk\_ followed by 4 to 32 lowercase alphanumeric characters | | intent | wanted, expected or retired | | source, target | HTTP(S) URL strings | | scope | exact, domain, subdomain or path; default exact | | expect.anchor | Optional string, at most 1000 characters | | expect.rel | Optional array of at most 20 relation tokens, each 1 to 40 letters/digits/underscore/hyphen; normalized to lowercase, deduplicated and sorted | | cadence | daily, weekly, monthly or integer seconds from 3600 to 2592000; wanted defaults weekly, expected daily | | ref | Optional string, at most 500 characters | | origin.kind | manual, import, discovery\_candidate, mention, citation, competitor or placement\_run | | origin.id, run\_id, provider, observed\_at, source\_url | Optional lineage strings, each at most 500 characters | | tags | Optional string array, deduplicated | | added, note | Optional strings | Unknown top-level and origin fields are retained. Lineage stays local; a cloud localReference is bounded and cannot replace it. ## Portable single-check artifact [check --source ... --target ...](/reference/local/check-single) returns `schema:"linktrail.local-check.v1"`, `result_id`, `input`, `checked_at`, `observation` and `provenance`. The ID is an lr\_ SHA-256 digest of normalized input and observation. `input` has source, target and scope. `provenance` records execution:"local", verifier:"linktrail-shared-verifier" and raw\_html\_included:false. | Observation field | Type and meaning | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | state | present, absent, unknown or source\_unavailable | | reason | String reason for the result | | sourceUrl, finalUrl, targetUrl | Requested source, final source and target URL strings | | targetScope | exact, domain, subdomain or path | | httpStatus | Integer or null | | checkedAt | Canonical ISO timestamp; equals artifact checked\_at | | occurrences | At most 1000 matching links | | directives | meta array of name/content strings; xRobotsTag string array; noindex/nofollow booleans; indexingStatus string | | redirects | Array of from/to URL strings and integer status | | evidence | Capture metadata described below | | robots, robotsHistory | Optional robots result and up to six robots results | | sourceResponse | Optional url, integer httpStatus, nullable contentType (up to 128 characters), nullable retryAfterSeconds and boolean challenge | | expectations | Optional nullable expectedAnchor, expectedRel, anchorMatches and relMatches; boolean satisfied | | linkSignature | Optional string | | warnings | Optional string array | | retryAfterSeconds | Optional number | Each occurrence contains href, targetUrl, anchor and context strings; rel string array; visibility:"not\_rendered"; and locator:null or an object with integer line, column and offset. A matching HTML link does not prove rendered visibility. Evidence requires method, checkerVersion, complete and fetchedAt (timestamp or null). Optional fields are bytes, nullable contentType/etag/lastModified, baseUrl, rendered, sha256, parseErrors and renderEligibility (required or comparison). Optional readiness contains requiresRender, nullable reason and possibleLoginWall, plus optional hasVisiblePassword, targetInScript, emptyAppRoot and emptyProfileRoot booleans. A robots result requires nullable allowed, reason, matchedRule and crawlDelaySeconds, plus nullable fetched. Optional fields are sourceUrl, robotsUrl, nullable httpStatus, productToken, up to five redirects and retryAfterSeconds. Nullable fields remain unknown when absent evidence cannot support a conclusion. Adoption validates the portable observation contract, matching source/target/scope, timestamp identity and result identity. Present requires complete evidence and matching occurrences. Absent requires complete evidence and no occurrences. Portable observations cannot include raw HTML, body or headers. The artifact size check is 512 KiB of serialized JSON characters. Use [adopt-result](/reference/local/adopt-result) to persist it. ## Observation mirror and activity state Observation rows contain id (ledger ID), checked\_at, state, reason, occurrences (count), complete, checker\_version, source, evidence\_key and result. Result contains verifier metadata with raw HTML removed. Deduplication uses ledger ID, checked timestamp and source. Cloud projection rows can carry projection metadata in addition to these fields. The observation mirror records changes; state.json records repeated-check activity. State version 2 holds entries, cursors and cloud mappings. Source and destination cursors remain independent. Preserve unknown state fields and let the CLI own migration; changing a cursor can skip history. ## Receipt input [receipt add](/reference/local/receipt-add) accepts a claim object: ```json theme={null} { "kind": "external", "source": "https://publisher.example.com/post", "target": "https://example.com/guide", "scope": "exact", "acted_at": "2026-09-13T12:00:00.000Z", "actor": {"role": "agent"}, "report": {"state": "claimed"}, "idempotency": "campaign-example-001" } ``` The command supplies receipt ID, declared\_at, baseline and ledger reference. `actor.role` is human or agent. `acted_at` needs a timezone. Optional ledger must identify a matching placement. Optional intent\_after defaults to expected for internal and wanted for external claims. expect, ref, tags and note follow ledger rules. An idempotency replay reuses the original claim only when its placement, kind, scope and acted\_at match. A claim remains claimed until independent observations can be read alongside it; [receipt history](/reference/local/receipt-history) reports that evidence without declaring causation. Source contracts: cli/ledger.js, cli/local-result.js, cli/mirror.js, cli/state.js and cli/receipts.js.