@hraness/ghostget 0.17.2

package/skills/ghostget/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: ghostget
+description: >-
+  Use Ghostget to give a bring-your-own coding agent bounded, local-first web
+  capabilities: capture or scrape public and signed-in web pages into Markdown;
+  archive authorized audio, video, and transcripts with verification; query
+  encrypted cached email, contacts, inbox, and messaging views; resolve a live
+  conversation, read fresh context, preview ordered message bubbles, and
+  execute an exactly authorized turn through one provider route; publish and
+  reconcile text, image, and video posts through observed installed social
+  capabilities; inspect or develop bounded provider contracts for X, LinkedIn,
+  Bluesky, Substack Notes, Threads, TikTok, Instagram, and YouTube Shorts; save
+  private native article drafts; operate reviewed Beeper messaging actions
+  across the pinned official CLI and fixed Desktop loopback operations; and build or run typed provider plugins
+  from recorded browser-session APIs or versioned provider CLIs. Trigger for web capture,
+  URL clipping, authenticated sites, social media posting or cross-posting,
+  media download or archiving, transcription, email and messaging integrations,
+  HAR-to-API workflows, browser-session API automation, semantic operations,
+  and safe provider mutations when raw HTTP, DOM control, cookies, and
+  credentials must stay outside the agent.
+---
+
+# Ghostget
+
+Ghostget supplies bounded CLI and SDK capabilities, not an agent runtime or application. Use it from the caller's own agent loop.
+
+## Install or verify Ghostget
+
+Start with `ghostget --help`. If the command is unavailable, read
+[installation and diagnostics](references/install.md) and install the pinned
+CLI before continuing when the user's request includes installing or using
+Ghostget. Never guess a source-tree command or substitute general browser
+automation.
+
+## Choose the smallest path
+
+- Capture a URL: `ghostget <url>` or `ghostget clip <url>`.
+- Read without persistence: `ghostget read <url>`.
+- Archive media: `ghostget archive <url>` or `ghostget audio|video|transcript <url>`.
+- Discover supported article embeds through the provider's bounded semantic media read, then archive each exact returned finite item separately. Do not treat a collection page as one media item or scrape its DOM to manufacture asset routes.
+- Inspect support: `ghostget plugin list`, `ghostget plugin show <id>`, and `ghostget capabilities [adapter]`.
+- Read Reddit post or community user flair choices: follow [Reddit flair](references/reddit-flair.md), including installed capability, same-account evidence, and the separate selection boundary.
+- Search public Puerto Rico rentals: `ghostget clasificados-web listings.search --input '{"location":"San Juan, PR","beds_min":2,"max_price":5500}' --json`. Keep `location` to the reviewed San Juan tokens. Neighborhood comes from street, ZIP, known address, or list-card coordinates, never from broker copy. Zillow-group and Puerto Rico MLS public search are not installed.
+- Operate Beeper: inspect `ghostget capabilities beeper-local --json`, then use
+  only its typed read or action operation with the bound local Desktop realm.
+- Export an existing WhatsApp local projection for Message Like Me: follow
+  [WhatsApp local Message Like Me export](references/whatsapp-adapter.md).
+  This route does not pair, sync, or send, and its seven-file output is private.
+- Export exact local Apple Photos contact evidence: follow
+  [Apple Photos contact evidence](references/apple-photos.md). This source has
+  no auth or network authority. Its cluster identifiers and counts are private
+  biometric-derived metadata. It does not open, copy, or ask Photos to
+  materialize referenced photo or video asset files. Its transient `VACUUM
+  INTO` copies are full private SQLite databases that can include unselected
+  columns and raw blobs; the exclusions apply only to the returned JSON.
+- Read or act on a live conversation: follow
+  [agentic messaging](references/messaging.md). Keep one exact provider route,
+  use private artifacts for prose and capability references, and never expose a
+  provider CLI or API beside Ghostget as a second action path.
+- Diagnose state: `ghostget operator doctor --json`.
+- Invoke a supported semantic operation: `ghostget invoke <adapter> <operation>` or its printed shorthand.
+- Collect exact daily social-account statistics into a checked consumer snapshot: follow [social profile statistics](references/social-profile-stats.md).
+- Export the signed-in X account's bookmarks as a bounded JSON page keyed by `post_id`: follow [X authenticated web API adapter](references/x-adapter.md#export-bookmarks).
+- Read a previously validated exact query without a provider roundtrip: repeat the subject-bound R1 invocation with `--cache-only`; omit that flag to revalidate it explicitly.
+- Read a normalized cross-provider inbox without a provider roundtrip: `ghostget omni read --input <json|@file|-> --cache-only --json`; use `--from-exact-cache` to rebuild from exact ciphertext or omit the mode to revalidate supported sources.
+- Save one private native article draft, including supported plan-bound covers, inline images, and destination-safe source-post references: inspect `articles.draft.save`, then follow [native article drafts](references/article-drafts.md). Keep a provider cover outside the body document; on an exact LinkedIn replacement, omit it only to preserve the independently read existing banner. Never substitute `articles.publish`.
+- Cross-post one exact text and optional ordered-image package: inspect every installed target schema, then follow [social cross-posting](references/cross-posting.md).
+- Cross-post one exact video package: require an observed video-capable operation for every selected target, then follow [video social cross-posting](references/cross-posting-video.md).
+- When a cross-post package uses user-supplied copy, never mark it as AI-generated. Follow [X AI disclosure](references/x-ai-disclosure.md): leave official `x` `made_with_ai` unset or `false`, prefer a Ghostget transport over the X composer, and treat a live sparkle Made with AI label as a failed publish. An explicitly authorized AI-media label outside that workflow remains a separate provider input choice.
+- Add a provider without changing Ghostget source: author a portable plugin.
+- Derive a reviewed first-party contract from authorized HAR evidence: follow [the derivation guide](references/derivation.md).
+
+Do not expose raw requests, endpoints, GraphQL, Rest.li, JavaScript, selectors, cookies, headers, storage, arbitrary paths, or unrestricted file transfer. A capability is a bounded semantic operation with an exact transport, origin, account binding, input schema, risk, side effect, and response projection.
+For a native provider CLI, do not expose argv, a shell, ambient environment,
+package-manager channels, target defaults, or plugin installation. Require an
+exact source-plugin-owned executable identity and fixed operation templates.
+
+Ghostget admits at most two locally owned fresh or profile-backed page-capture
+browsers across processes sharing its state home. Let capture wait for the
+lesser of its remaining timeout and the 30-second admission polling budget;
+queueing consumes that timeout. A bounded state helper may settle after the
+polling budget, but the browser cannot launch after deadline revalidation. Do
+not bypass the gate by spawning agent-browser directly. Explicit CDP and
+browser-live attachment skip admission because Ghostget does not own those
+browser processes. Managed provider/bootstrap and derivation sessions remain
+outside this first cap. Before parallel first use of a new state home, run
+`ghostget runs list --json` once serially. Malformed, unverifiable, and same-boot
+dead-owner claims remain occupied until their exact resources are recovered.
+Run `ghostget doctor --json`; it acquires a durable recovery lease before any
+effect and acts only when the exact private session, daemon start identity,
+launch identity, CDP endpoint, and private-root generation still match. It
+persists quiescence before journaled root removal so a crash can resume without
+weakening those proofs. Never delete a claim, kill a browser tree, or edit
+Ghostget state to bypass this fence. If any proof is missing or changes, retain
+the claim and inspect the reported category rather than treating a reboot as a
+recovery procedure.
+LinkedIn profile and organization reads and Instagram profile reads whose
+browser daemon exits naturally during finalization can settle inline without
+repeating the read or signaling the dead owner. That path still requires the
+exact pinned owner to be dead, two exact inactive session envelopes, unchanged
+private-root generations, three refused CDP connections, and a final owner,
+session, and root reproof. Unknown liveness, malformed lifecycle output,
+identity drift, root replacement, an available or indeterminate CDP endpoint,
+and durable-claim drift remain cleanup-required.
+
+## Author a portable provider
+
+Read [provider plugins](references/provider-plugins.md), [the adapter contract](references/adapter-contract.md), and [safety and state](references/safety-and-state.md). Then create an inert package:
+
+```sh
+ghostget plugin init example-web \
+  --display-name "Example" \
+  --surface example \
+  --origin https://www.example.com \
+  --operation feeds.read \
+  --output /absolute/private/example-web
+```
+
+`init` writes a strict `ghostget-plugin.json`, one self-contained Bun runtime, secret-free fixtures, and package-local agent guidance. Its operation starts `capture-required` and network-inert. Keep it that way until authorized evidence proves:
+
+1. the exact HTTPS origin and route;
+2. the current-account probe and stable subject binding;
+3. the bounded request and credential sinks;
+4. accepted status, content type, response projection, and pagination;
+5. actor, target, side effect, idempotency, and uncertainty behavior;
+6. drift and negative cases without a DOM or transport fallback.
+
+Verify the package in order:
+
+```sh
+ghostget plugin check /absolute/private/example-web --json
+ghostget plugin test /absolute/private/example-web --trust-code --json
+ghostget plugin pack /absolute/private/example-web \
+  --output /absolute/private/example-web.wrenchplugin --json
+ghostget plugin install /absolute/private/example-web.wrenchplugin \
+  --trust-code --json
+ghostget capabilities example-web --json
+```
+
+`check` is static. `test --trust-code` and `install --trust-code` explicitly authorize execution of the exact verified bundle. Process separation contains ordinary failures but is not a hostile-code sandbox: plugin code still runs as the user's OS account. Never execute an unverified authoring directory or import portable code into the host.
+
+For updates, bind the transition to the installed digest:
+
+```sh
+ghostget plugin show example-web --json
+ghostget plugin install /absolute/private/example-web.wrenchplugin \
+  --trust-code --expected-current <bundle-sha256> --json
+```
+
+Ghostget refuses update, disable, or removal while a live invocation, preview, claim, journal, recovery capsule, or linked-device lifecycle owns the bundle. Inspect blockers with `ghostget plugin doctor`, `ghostget plans list`, and `ghostget runs list`.
+
+## Configure one stable auth realm
+
+Store a locator, not copied secrets:
+
+```sh
+ghostget auth add example-main --cookie-source arc --cookie-profile "Profile 1"
+ghostget auth bind example-main --site example
+ghostget auth list --json
+```
+
+Use OAuth only for a reviewed `provider-api` plugin. Use browser cookies or a private profile only for a reviewed `web-session-api` plugin. Use a linked-device store locator for the reviewed Beeper `local-cli` binding; that locator selects the already-authorized Desktop realm, not arbitrary process authority. Never silently switch transports. A profile snapshot requires the source browser to be closed and may require `--browser-executable` plus explicit `--trust-profile-egress` because a path-backed browser has no domain-containment boundary.
+
+For Gmail/Google Contacts, prefer managed native OAuth:
+
+```sh
+ghostget auth login gmail-main --client-file /absolute/path/to/google-desktop-client.json
+```
+
+Ghostget opens the system browser, uses PKCE plus a loopback callback, verifies
+the Gmail subject, stores the refresh credential and Desktop client fields in
+a mode-restricted local JSON file, and renews access tokens. This is not an OS
+keychain or encrypted-at-rest store. The user—not browser automation—handles
+Google sign-in, account choice, warnings, and consent. Tell them that
+`gmail.readonly` is a Google restricted mailbox-read grant even though the
+relationship contract fetches metadata only. Never ask the user to paste a
+token. Confirm `accountSubject` with a one-row live `contacts.list` read before
+syncing. Use `contacts.list` with collection
+`contacts`, `other-contacts`, or `interactions`; the last requires one fixed
+whole-second `before` cutoff, accepts the prior cutoff as an optional inclusive
+`after` bound for incremental reads, and exposes message-count/timestamp
+completeness plus first-page send-as aliases for self-address exclusion without
+reading bodies.
+
+Treat each auth ID as one stable provider account. Probe and bind the current account before private reads or writes; reject missing, ambiguous, changed, or mismatched identities. Keep tokens, cookies, HAR content, profile state, messages, and attachment paths out of output, logs, receipts, and Git.
+
+## Invoke with the risk boundary intact
+
+Inspect the capability first:
+
+```sh
+ghostget capabilities example-web --json
+ghostget example-web feeds.read --input '{"limit":20}' --auth example-main --json
+ghostget example-web feeds.read --input '{"limit":20}' --auth example-main --cache-only --json
+```
+
+- `capture-required` performs no request.
+- `R1` is a reviewed read with no intended remote mutation.
+- `R2` is one bounded, normally reversible change.
+- `R3` is externally visible or consequential.
+- `R4` is blocked.
+
+Successful subject-bound R1 reads publish an encrypted exact-query snapshot.
+`--cache-only` returns that snapshot and its data revision, validation time,
+age, and freshness without opening a browser or provider connection. A normal
+R1 invocation is the explicit revalidation path. Do not rewrite cursors,
+limits, folders, or targets to manufacture a cache hit, and do not assume that
+revalidating a local linked-device projection performs a remote sync.
+
+For an omni request, list each exact `messaging.list` or `messaging.read`
+source with its adapter, auth ID, and input. Treat its shared Conversation,
+Message, and Notification union as a derivative, never as replacement evidence
+for the exact provider snapshot. Inspect every per-source normalization state.
+`retained-after-drift` means the provider's newest exact bytes failed its
+provider-owned materializer and the returned entities are deliberately the
+last good derivative. Do not hide or coerce that status. Public reasons are
+categorical; detailed drift diagnostics stay encrypted. During SWR, treat an
+`omni-merged` current view as cached data paired with the unresolved live source
+statuses that remain authoritative for display. Provider cursors stay private;
+use only the authenticated local view cursor returned by Ghostget.
+Omni v1 has no write-tag invalidation surface. Auth-incarnation, materializer,
+and plugin implementation identity changes strand prior derivatives. Exact
+query freshness advances only through explicit R1 revalidation.
+
+R2/R3 produce an exact five-minute preview. Review adapter, operation,
+transport, account, scalar input, attachment hashes and order, side effect,
+contract hash, and dispatch schedule, then run the printed `ghostget confirm
+<digest>`. A messaging turn uses its stricter private preview and same-turn
+authorization procedure in [agentic messaging](references/messaging.md).
+Never retry `pending`, `partial`, or `indeterminate` work. Reconcile from
+independently observed, secret-free evidence only when the installed exact
+contract advertises reconciliation; image-upload draft contracts deliberately
+do not. Reconciliation never repeats the original mutation.
+
+## Derive only when a contract is missing
+
+Use a managed derivation to capture the minimum authorized first-party exchange. Seal and inspect the HAR through `ghostget derive review`, finish into a private directory, and scaffold one inert operation with `ghostget plugin scaffold`. Generic derivation output is evidence, not an executable client. Implement and promote only the exact reviewed contract; never fall back to DOM clicking. See [derivation](references/derivation.md) and [the code-owned scaffold](references/code-owned-provider-scaffold.md).
+
+## Finish with evidence
+
+- Freeze built-in provider source and tests before updating durable contract
+  semantic identities. Follow [provider plugins](references/provider-plugins.md)
+  to review the semantic digest once; Ghostget derives and revalidates the exact
+  source/dependency closure automatically and has no manual hash-approval step.
+- Re-run `ghostget plugin check` and secret-free fixtures.
+- Prove exact origin, method, path, input bounds, response variants, identity binding, redirects, drift, and redaction.
+- Exercise only authorized observed operations.
+- Verify a `capture-required` operation performs no request.
+- Inspect receipts and confirm credentials and payload text are absent.
+- Remove managed HARs, profile snapshots, bootstrap state, and plan assets when their lifecycle is complete.
+- Forward-test material skill changes with a fresh agent given only this skill and an installed `ghostget` command.

package/skills/ghostget/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ghostget"
+  short_description: "Capture, archive, and run bounded provider operations"
+  default_prompt: "Use $ghostget to capture or archive this source, work with a bounded signed-in provider, inspect or act on an exact live conversation through private messaging artifacts, cross-post social media, query cached inbox data, or author a provider plugin."

package/skills/ghostget/references/adapter-contract.md

@@ -0,0 +1,181 @@
+# Adapter contract
+
+Use a strict, secret-free manifest to select a code-owned semantic operation.
+For a signed-in site capability, prefer schema-v4 `webSession`. Use
+schema-v6 `localCli` only for an exact source-plugin-owned provider executable.
+A manifest never contains a captured request or command line.
+
+## Contents
+
+- [Transport versions](#transport-versions)
+- [Manifest identity](#manifest-identity)
+- [Semantic operation and input](#semantic-operation-and-input)
+- [Schema-v6 local CLI selector](#schema-v6-local-cli-selector)
+- [Schema-v4 selector](#schema-v4-selector)
+- [Code-owned request template](#code-owned-request-template)
+- [Dynamic token boundary](#dynamic-token-boundary)
+- [Response and identity binding](#response-and-identity-binding)
+- [Risk and dispatch](#risk-and-dispatch)
+- [Promotion and drift](#promotion-and-drift)
+
+## Transport versions
+
+- Schema version 6 selects one exact, source-plugin-owned `local-cli` contract.
+  Its binding pins the reviewed executable artifacts independently from the
+  operation's semantic `contractVersion`. It never exposes argv or a shell.
+- Schema version 5 reserves generic-site derivation work only. Version-1 `reviewedTemplate` operations must remain `capture-required`; manifest validation rejects `reviewed`, and neither state supplies an executable request. A future contract version 2 must add a current-account identity preflight and response-scope binding before generic execution can be considered.
+- Schema version 4 selects one reviewed first-party authenticated web contract and uses `web-session-api` at runtime.
+- Schema version 3 selects one reviewed official `provider-api` contract with OAuth auth.
+- Schema version 2 is a retired semantic browser-recipe grammar retained only to diagnose old files. Any schema-v1/v2 DOM operation is install- and runtime-inert: adapter validation, installation, planning, execution, and the direct recipe executor fail closed for every origin. A supported operation must use schema 6, schema 4, or an appropriate schema-3 provider contract.
+- Schema version 1 exists only for the exact archived LinkedIn migration fixture.
+
+Never retry or fall back across these transports. A browser may help schema 4 acquire session state or current dynamic material, but it does not execute the semantic action by clicking the site.
+
+## Manifest identity
+
+- Use a lowercase kebab-case `id`, semantic `version`, and short `displayName`.
+- Bind a catalogued site with the exact `surfaceId`.
+- Declare only exact HTTPS `origins`; reject paths, embedded credentials, local/private hosts, and runtime-discovered origins.
+- Keep `browserDomains` limited to hosts needed for capture or bootstrap. It does not authorize an API endpoint.
+- Keep cookies, tokens, captured authorization, account-private IDs, messages, HAR values, request templates, and local paths out of the manifest.
+
+## Semantic operation and input
+
+Use canonical outcome names such as:
+
+```text
+feeds.read
+messaging.list
+messaging.read
+messaging.send
+posts.publish
+posts.repost
+reactions.set
+threads.publish
+```
+
+Do not expose `graphql.call`, `voyager.request`, `restli.post`, `selector.click`, or another transport-shaped operation.
+
+Declare bounded typed inputs. Apply exact enums and realistic length, number, array, file-size, and media-type limits. Require every field used by the owned request contract. Keep provider identifiers opaque but syntactically bounded; do not accept an arbitrary URL when a conversation, post, user, or list ID is the actual target.
+
+Bind ordered thread items and attachment bytes into the encrypted plan before preview. The preview may show content hashes, sizes, and detected media types rather than mutable paths.
+
+## Schema-v6 local CLI selector
+
+Each operation selects one installed semantic contract:
+
+```json
+{
+  "localCli": {
+    "surface": "beeper",
+    "action": "messaging.send",
+    "contractVersion": 1,
+    "timeoutMs": 60000,
+    "maxOutputBytes": 10485760
+  }
+}
+```
+
+Require `surface` to match `surfaceId`, `action` to match the operation ID, and
+risk/input schema to match the code-owned registry. The source-plugin binding,
+not the manifest, owns the exact tool identity and fixed command template. The
+contract hash binds both, so changing reviewed executable bytes invalidates an
+old preview without pretending that an unchanged semantic projection needs a
+new `contractVersion`.
+
+Never put an executable path, argument array, environment variable, account
+default, target URL, or output path in the manifest. See
+[provider plugins](provider-plugins.md) for the source runtime boundary.
+
+## Schema-v4 selector
+
+Each operation contains one selector with no request surface:
+
+```json
+{
+  "webSession": {
+    "site": "x",
+    "action": "posts.publish",
+    "contractVersion": 1,
+    "timeoutMs": 60000,
+    "maxOutputBytes": 2097152
+  }
+}
+```
+
+Require `site` to match `surfaceId`, `action` to match the operation ID, and risk/input schema to match the code-owned registry. Store the contract hash in previews and receipts. Reject a stale confirmation after any contract change.
+
+The registry uses two public states:
+
+- `observed`: reviewed evidence and an installed runtime contract exist for the exact version.
+- `capture-required`: the semantic operation is reserved, but one or more exact exchange facts are missing or stale. Perform no request and expose no browser fallback.
+
+Do not treat `capture-required` as degraded support.
+
+## Code-owned request template
+
+Keep the first-party exchange in owned TypeScript or another reviewed executable module. Bind:
+
+- one exact HTTPS origin;
+- one fixed method from the reviewed set;
+- an origin-relative path made from fixed segments and individually encoded typed inputs;
+- fixed query names and scalar/JSON encodings;
+- a fixed JSON, form, or empty body structure;
+- fixed non-credential headers;
+- cookie acquisition through the auth layer;
+- explicitly allowed dynamic credential sources and sinks;
+- one bounded response contract.
+
+Reject redirects rather than inheriting credentials across locations. Reject unknown methods, origins, paths, query parameters, body fields, headers, or response variants. Never add an arbitrary request, header, raw GraphQL, or templated URL escape hatch.
+
+## Dynamic token boundary
+
+Resolve a current value only when the contract names its source and sink:
+
+- CSRF/XSRF may come from one exact cookie, meta field, or local/session-storage key and terminate only in one fixed CSRF/XSRF header.
+- Authorization may come from one exact storage key or a captured authorization header and terminate only in `authorization`.
+- Registered-query revisions may be discovered from current first-party assets or capture metadata by exact operation prefix; require one unique bounded match.
+
+Keep values in memory and out of plans, receipts, logs, URLs, bodies, and normalized output. Reject literals in credential-bearing headers. Reject source/sink mismatch, duplicate cookie values, malformed encoding, missing browser bootstrap, and ambiguous revisions.
+
+## Response and identity binding
+
+Declare exact successful status and content-type pairs. Bound response bytes before parsing. For JSON, project only named, typed paths and reject required-path or type drift.
+
+Add strict response bindings for every field needed to prevent confused-deputy behavior:
+
+- requested conversation, post, comment, user, list, or article identity;
+- requested desired state or created content identity;
+- actor identity for a mutation;
+- created parent/root relationships for replies, reposts, or threads.
+
+Bind the auth realm separately to the current provider account. Resolve a stable viewer/account ID through a reviewed first-party request, compare it with the realm's expected binding, and fail before private reads or dispatch when missing, ambiguous, or mismatched. Do not infer account identity from a profile path or cookie filename.
+
+## Risk and dispatch
+
+| Risk | Meaning | Execution |
+| --- | --- | --- |
+| `R1` | Reviewed read with no intended mutation | Direct |
+| `R2` | Bounded, normally reversible mutation | Exact preview and digest confirmation |
+| `R3` | Externally visible or consequential mutation | Exact preview and digest confirmation |
+| `R4` | Sensitive/high-authority action outside this boundary | Blocked |
+
+For R1, use `sideEffect: "none"`, `idempotency: "none"`, and `dedupeWindowMs: 0`. Permit only read methods and explicitly deny observed presence, seen, delivery, read-receipt, badge, and acknowledgement requests.
+
+For R2/R3, describe the remote effect, use `local-at-most-once`, and choose a 60-second-to-30-day dedupe window. Bind the complete dispatch schedule before confirmation. Messages, comments, replies, posts, reposts, quotes, and threads are R3. Likes, bookmarks, reversible reactions, and follows may be R2 when the exact create/delete desired-state contract is captured. One exact authored-item deletion may be R3 only on a reviewed surface that binds current-account ownership, an immutable target/revision, a single delete request, and independent exact absence readback. Credential, access-control, financial, bulk/untargeted deletion, account deletion, and administration actions remain R4.
+
+Mark dispatch durable immediately before the request leaves. Mark verification only after an exact response variant and target/account bindings pass. A timeout or binding failure after dispatch is `indeterminate`; a stopped multi-request schedule after verified earlier effects is `partial`. Never auto-resume either state.
+
+## Promotion and drift
+
+Promote a contract only after:
+
+1. inert HAR evidence identifies the exact first-party exchange;
+2. deterministic tests reject all undeclared request and response variations;
+3. account, actor, target, and parent bindings are explicit;
+4. secrets can reach only their reviewed header sinks;
+5. one authorized low-stakes live fixture passes through the public CLI;
+6. duplicate refusal and uncertain-result behavior pass;
+7. logs, plans, receipts, and temporary state pass a secret scan.
+
+On path, query revision, feature set, token source, request field, status, content type, projection, or binding drift, return `capture-required`. Re-capture and review a new contract version. Do not patch the request from arbitrary live traffic and do not click the DOM instead.

package/skills/ghostget/references/apple-photos.md

@@ -0,0 +1,115 @@
+# Apple Photos contact evidence
+
+Use this workflow when a local application needs exact evidence that one
+Apple Photos person cluster is linked to one Apple Contacts record. It is a
+local-source export, not a provider capability, Photos API, contact search, or
+media reader.
+
+## Run the bounded export
+
+The default source is the conventional current-account Photos library path,
+`~/Pictures/Photos Library.photoslibrary`. It does not discover or claim the
+library that Photos currently designates as the System Photo Library:
+
+```sh
+umask 077
+ghostget apple-photos export-contact-evidence --json \
+  > /absolute/private/apple-photos-contact-evidence.json
+```
+
+Select a different library only by its normalized absolute
+`.photoslibrary` directory:
+
+```sh
+ghostget apple-photos export-contact-evidence \
+  --library /absolute/private/Family.photoslibrary --json
+```
+
+There is no database-file, Contacts-root, SQL, query, output-path, network, or
+media option. The command discovers the current Apple Contacts stores from the
+fixed account root. It does not authenticate, connect, sync, download, modify,
+or ask Photos to materialize an asset.
+
+## Exact evidence boundary
+
+Ghostget accepts only owned real directories and owned single-link regular
+SQLite files within reviewed byte and count bounds. It opens each source
+read-only with trusted schemas disabled and uses SQLite `VACUUM INTO` to create
+one mode-`0600` database in a mode-`0700` operation-owned temporary directory.
+The source's device, inode, birth time, owner, type, link count, and permission
+mode must agree before and after capture. Live size and modification-time churn
+is allowed. Apple Contacts databases use the same boundary. Ghostget runs
+`quick_check`, then opens only the captured databases read-only and query-only.
+
+Relevant Core Data tables and columns have a strict schema fingerprint. Schema
+drift, SQLite integrity failure, a symlink, hardlink, owner or physical-identity
+mismatch, or size overrun fails closed. Ordinary success and handled failure
+remove the temporary captures before returning. Forced termination or a crash
+can leave an exact leased capture for a later recovery pass.
+
+The CLI serializes private local exports before inspecting a source. Its
+operation-owned snapshot directory has a process-owned,
+filesystem-identity-bound recovery lease before database bytes are copied. A
+later export reclaims only an exact directory whose owner is dead; live or
+uninspectable owners remain untouched and stop the run.
+
+The exact relationship is:
+
+```text
+ZPERSON.ZPERSONURI = ZABCDRECORD.ZUNIQUEID
+```
+
+Ghostget does not parse `ZCONTACTMATCHINGDICTIONARY` or infer a match from a
+name. Unmatched Photos people are excluded.
+
+## Output and completeness
+
+Stdout contains one strict `{ "receipt": ..., "output": ... }` JSON value.
+The schema-1 output format is `wrench.apple-photos-contact-evidence`. Each
+sorted evidence row contains:
+
+- `photosPersonId`;
+- `appleContactId`;
+- `linkedFaceCount`;
+- `linkedAssetCount`, the number of distinct `ZASSET` rows linked through the
+  detected faces;
+- `firstAssetAt` and `lastAssetAt`, or two null values when no linked asset has
+  a date.
+
+The output and receipt declare a path-free realm digest for the physical Photos
+library, the source generation, relevant Photos and Contacts schema digests,
+bounds, counts, privacy exclusions, component capture intervals, and canonical
+SHA-256 integrity. Each captured database is internally consistent within its
+interval. The export does not claim an atomic instant across Photos and
+Contacts or completed iCloud and Contacts synchronization. Absence is not
+deletion evidence.
+
+Ghostget does not open, copy, or ask Photos to materialize referenced photo or
+video asset files. A `VACUUM INTO` capture is nevertheless a full private
+Photos or Contacts SQLite database copy and can include unselected columns and
+raw blobs. The privacy exclusions apply only to the returned JSON: names,
+paths, images, encoded media, thumbnails, locations, raw blobs, credentials,
+faceprint templates, face crops, and unmatched clusters are not selected or
+projected. The returned cluster identifiers and counts
+are private biometric-derived metadata as well as relationship evidence. Keep
+the artifact outside Git and shared output paths.
+
+## Typed client
+
+Local Bun applications can invoke the installed Ghostget boundary without
+duplicating SQLite custody:
+
+```ts
+import {
+  exportApplePhotosContactEvidenceSync,
+  parseApplePhotosContactEvidenceExportResult,
+} from "@hraness/ghostget/apple-photos"
+
+const result = exportApplePhotosContactEvidenceSync()
+const checked = parseApplePhotosContactEvidenceExportResult(result)
+```
+
+Consumers should map these exact source coordinates into their own person
+model and retain the receipt. They must not read Photos or Contacts databases
+again, infer names, expose biometric-derived counts, or advance a deletion
+state from an absent relationship.