tracekite-core 0.1.1__py3-none-any.whl

tracekite/_control_plane/confidence.yml

@@ -0,0 +1,259 @@
+# Confidence registry: every resolver tier's served confidence plus its
+# measured P/R row (design §8). Invariant 7: no resolver tier serves
+# `active` edges at or above the floor to an org-facing deployment without a
+# measured row. `measured: null` marks provisional values awaiting the
+# microSecEnD + adversarial-fixture calibration run (M2).
+#
+# This is the single copy. Loaded by tracekite/services/linker/base.py:load_confidence();
+# override the directory with KG_CONFIG_DIR.
+version: 1
+floor: 0.6
+fusion_cap: 0.99
+# Most contracts one call site may match before the match is declined
+# outright. A call site matching everything has matched nothing, so past this
+# the resolver counts `fanout_exceeded` and emits nothing — never a truncated
+# slice, which would read as a resolved match while hiding the ambiguity.
+fanout_cap: 32
+will_break_threshold: null   # derived from the measured table (M2), never a constant
+# Multiplier applied to an edge whose cited evidence no longer says what it
+# said (F5 re-verification). Rot ages an assertion, it does not refute it:
+# the edge is downgraded — below the floor it becomes `candidate` — and
+# never deleted.
+stale_evidence_factor: 0.7
+# Most route-table applications a single call may chain through (edge
+# gateway -> mesh -> service) before NORMALIZE declines it as unresolved.
+# Deeper chains are counted, never truncated to a partial hop.
+gateway_chain_max_hops: 3
+
+# --- R0 alias ---------------------------------------------------------------
+# built_from_config was removed with the config-filename BUILT_FROM exclusion:
+# a Spring Cloud Config repo holding customers-service.yml must never claim to
+# build that service, so no edge is ever priced at that tier.
+r0:
+  resolved_to: 0.98
+  has_alias: 0.9
+  built_from_build_context: 0.95   # descriptor points at a directory in this repo
+  built_from_app_name: 0.85        # in-code application name
+  built_from_descriptor: 0.75     # compose/k8s names it; image may build elsewhere
+  belongs_to: 0.95                 # module read off the evidence path
+
+# --- R1 compose topology (benchmark-proven 0.98-0.99) -----------------------
+# `links` entries fold into depends_on at emission (compose v1 legacy), so
+# there is no separate links tier — a priced-but-unreachable tier is exactly
+# the schema fiction Invariant 7 forbids (calibration finding).
+r1:
+  depends_on: 0.96
+  env_host: 0.95
+  # `DB_HOST=${DB_HOST:-platform-db}`: the default that runs unless an
+  # operator overrides it. Authored and citable, but strictly weaker than a
+  # literal — an override changes the answer and nothing in the repo says
+  # whether one is set — so it prices below env_host, the same way route_dev
+  # sits below route_declared.
+  env_host_default: 0.85
+
+# --- R2 kubernetes (benchmark P 0.97 / R 0.56) ------------------------------
+# DNS aliases register into R0's alias table and are priced there
+# (r0.has_alias); no edge is emitted at a dns_alias tier (calibration finding).
+r2:
+  selector_match: 0.97       # Service selector matches workload pod labels
+  env_host: 0.95             # literal env value naming an in-cluster service
+  built_from_gitops: 0.97    # ArgoCD/Flux declares the source repo
+  deployed_as: 0.97          # the manifest itself names the workload
+  policy: 0.9               # mesh/network policy joined by selector
+
+# --- R9 environment indirection ---------------------------------------------
+# Multi-environment conflicts DECLINE (r9.ambiguous_across_envs) rather than
+# emit at a lower tier — decline-don't-guess won (calibration finding).
+r9:
+  env_resolved: 0.85         # code reads VAR; a manifest defines VAR's host
+
+# --- R4 gateway route tables ------------------------------------------------
+r4:
+  route_declared: 0.98
+  route_dev: 0.7        # vite/webpack devServer proxies: real wiring, dev-only
+
+# --- R5 gRPC (globally unique proto keys; no service hint needed) -----------
+r5:
+  declared: 0.98        # the .proto itself declares the operation
+  exact: 0.95           # stub names the fully-qualified package.Service
+  service_name: 0.9     # stub names only the service; package inferred
+  calls_service: 0.9
+
+# --- R3 libraries (version-free purl keys; internal boundary gates joins) ---
+r3:
+  publishes: 0.98           # the repo's own manifest names the coordinate
+  lockfile_resolved: 0.95   # consumer pin from a lockfile/SBOM
+  manifest_declared: 0.9    # consumer range from a manifest
+
+# --- R11 agent contracts (MCP server name plays the role of a proto package) -
+r11:
+  registration: 0.95    # @mcp.tool / server.tool in the implementing repo
+  config: 0.85          # an mcp.json entry naming the server
+  card: 0.95            # .well-known/agent.json declares the skill
+  url_resolved: 0.9     # a call site's URL matches a card's URL
+
+# --- R10 datasets (identity strength varies by namespace) -------------------
+r10:
+  declared: 0.95        # a migration/ORM entity/dbt schema declares the table
+  literal: 0.9          # a distinctive-namespace name at a call site
+  inferred: 0.75        # ORM entity without an explicit table name
+
+# --- R12 ownership ----------------------------------------------------------
+r13:
+  registered: 0.85          # callback joined to the receiver's own route
+
+r12:
+  catalog: 0.95         # Backstage names owner + entity in one authored place
+  codeowners: 0.9       # path-pattern ownership; repo-level is exact
+  observability: 0.8    # a DD_TAGS team is operational, not organizational
+
+# --- R14 cross-protocol operations ------------------------------------------
+r14:
+  http_binding: 0.97    # the proto's own google.api.http declares it
+  event_schema: 0.85    # avro record name equals the rpc's qualified output
+
+# --- R6 topics (no service hint exists or is needed; the name is the key) ---
+r6:
+  declared: 0.98        # AsyncAPI/Terraform/Avro declares the destination
+  literal: 0.9          # a literal destination at a producer/consumer site
+  env_resolved: 0.85    # destination via env/config indirection (hmac join)
+  fanout: 0.95          # SNS->SQS subscription declared in IaC
+
+# --- R8 GraphQL (Type.field carries no package, so weaker than R5) ----------
+r8:
+  declared: 0.98        # the SDL declares the root field
+  federated: 0.95       # federation names the owning subgraph
+  field_name: 0.8       # field name only; no package, no federation
+
+# --- R7 http contract matching ----------------------------------------------
+r7:
+  hint_exact: 0.95      # qualified service hint + exact path template
+  hint_template: 0.85   # qualified service hint + positional template
+  # Callee named by a gateway's route table rather than by the call site.
+  # Strictly weaker than a direct hint: it assumes the route in force at link
+  # time is the one that served the call, so a stale or overridden route table
+  # would mislead. Rated below the direct tiers to keep that honest.
+  gateway_exact: 0.88
+  gateway_template: 0.80
+  exposes: 0.98         # provider-side declaration
+
+# --- Intra-repo call graph (pre-linker) -------------------------------------
+resolvers:
+  call_graph_resolver:
+    unique_match:
+      confidence: 0.9
+      measured: null          # provisional — calibration lands in M2
+    ambiguous_match:
+      confidence: 0.7
+      measured: null          # provisional — calibration lands in M2
+  # SCIP references are compiler-grade resolution; rated above the
+  # name-resolution heuristic but never 1.0 — the index can lag the tree.
+  scip_import:
+    reference:
+      confidence: 0.95
+      measured: null          # provisional — labelled index corpus pending
+
+# Resolvers not yet landed (R2 k8s, R3 library, R5 grpc, R6 topic, R9 env) add
+# their tiers here as they ship. Design §6.2 targets: r2 0.97, r3 0.6-1.0 by
+# tier, r5 high (globally unique keys), r6 0.85-0.95 literals.
+
+# --- MEASURED (generated by tools/calibrate.py; do not edit) ---
+measured:
+  corpus: fixtures-v1
+  at: '2026-07-29T22:46:58+00:00'
+  rows:
+    r0.belongs_to: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r0.built_from_app_name: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r0.built_from_build_context: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r0.built_from_descriptor: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r0.has_alias: {precision: 1.0, precision_lo: 0.4385, precision_hi: 1.0, recall: 1.0, support: 3, fp: 0}
+    r0.resolved_to: {precision: 1.0, precision_lo: 0.3424, precision_hi: 1.0, recall: 1.0, support: 2, fp: 0}
+    r1.depends_on: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r1.env_host: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r10.declared: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r10.inferred: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r10.literal: {precision: 1.0, precision_lo: 0.3424, precision_hi: 1.0, recall: 1.0, support: 2, fp: 0}
+    r11.card: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r11.config: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r11.registration: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r11.url_resolved: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r12.catalog: {precision: 1.0, precision_lo: 0.3424, precision_hi: 1.0, recall: 1.0, support: 2, fp: 0}
+    r12.codeowners: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r12.observability: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r13.registered: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r2.built_from_gitops: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r2.deployed_as: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r2.env_host: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r2.policy: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r2.selector_match: {precision: 1.0, precision_lo: 0.3424, precision_hi: 1.0, recall: 1.0, support: 2, fp: 0}
+    r3.lockfile_resolved: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r3.manifest_declared: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r3.publishes: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r4.route_declared: {precision: 1.0, precision_lo: 0.3424, precision_hi: 1.0, recall: 1.0, support: 2, fp: 0}
+    r4.route_dev: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r5.calls_service: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r5.declared: {precision: 1.0, precision_lo: 0.3424, precision_hi: 1.0, recall: 1.0, support: 2, fp: 0}
+    r5.exact: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r5.service_name: {precision: 1.0, precision_lo: 0.3424, precision_hi: 1.0, recall: 1.0, support: 2, fp: 0}
+    r6.declared: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r6.env_resolved: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r6.fanout: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r6.literal: {precision: 1.0, precision_lo: 0.3424, precision_hi: 1.0, recall: 1.0, support: 2, fp: 0}
+    r7.exposes: {precision: 1.0, precision_lo: 0.3424, precision_hi: 1.0, recall: 1.0, support: 2, fp: 0}
+    r7.gateway_exact: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r7.gateway_template: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r7.hint_exact: {precision: 1.0, precision_lo: 0.4385, precision_hi: 1.0, recall: 1.0, support: 3, fp: 0}
+    r7.hint_template: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r8.declared: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r8.federated: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r8.field_name: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+    r9.env_resolved: {precision: 1.0, precision_lo: 0.2065, precision_hi: 1.0, recall: 1.0, support: 1, fp: 0}
+derived:
+  unattributed_labels: {tp: 0, fp: 0}
+  rows:
+    r0.belongs_to: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r0.built_from_app_name: {served: 0.85, derived: 0.85, basis: prior, tp: 1, fp: 0}
+    r0.built_from_build_context: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r0.built_from_descriptor: {served: 0.75, derived: 0.75, basis: prior, tp: 1, fp: 0}
+    r0.has_alias: {served: 0.9, derived: 0.9, basis: prior, tp: 3, fp: 0}
+    r0.resolved_to: {served: 0.98, derived: 0.98, basis: prior, tp: 2, fp: 0}
+    r1.depends_on: {served: 0.96, derived: 0.96, basis: prior, tp: 1, fp: 0}
+    r1.env_host: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r10.declared: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r10.inferred: {served: 0.75, derived: 0.75, basis: prior, tp: 1, fp: 0}
+    r10.literal: {served: 0.9, derived: 0.9, basis: prior, tp: 2, fp: 0}
+    r11.card: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r11.config: {served: 0.85, derived: 0.85, basis: prior, tp: 1, fp: 0}
+    r11.registration: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r11.url_resolved: {served: 0.9, derived: 0.9, basis: prior, tp: 1, fp: 0}
+    r12.catalog: {served: 0.95, derived: 0.95, basis: prior, tp: 2, fp: 0}
+    r12.codeowners: {served: 0.9, derived: 0.9, basis: prior, tp: 1, fp: 0}
+    r12.observability: {served: 0.8, derived: 0.8, basis: prior, tp: 1, fp: 0}
+    r13.registered: {served: 0.85, derived: 0.85, basis: prior, tp: 1, fp: 0}
+    r2.built_from_gitops: {served: 0.97, derived: 0.97, basis: prior, tp: 1, fp: 0}
+    r2.deployed_as: {served: 0.97, derived: 0.97, basis: prior, tp: 1, fp: 0}
+    r2.env_host: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r2.policy: {served: 0.9, derived: 0.9, basis: prior, tp: 1, fp: 0}
+    r2.selector_match: {served: 0.97, derived: 0.97, basis: prior, tp: 2, fp: 0}
+    r3.lockfile_resolved: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r3.manifest_declared: {served: 0.9, derived: 0.9, basis: prior, tp: 1, fp: 0}
+    r3.publishes: {served: 0.98, derived: 0.98, basis: prior, tp: 1, fp: 0}
+    r4.route_declared: {served: 0.98, derived: 0.98, basis: prior, tp: 2, fp: 0}
+    r4.route_dev: {served: 0.7, derived: 0.7, basis: prior, tp: 1, fp: 0}
+    r5.calls_service: {served: 0.9, derived: 0.9, basis: prior, tp: 1, fp: 0}
+    r5.declared: {served: 0.98, derived: 0.98, basis: prior, tp: 2, fp: 0}
+    r5.exact: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r5.service_name: {served: 0.9, derived: 0.9, basis: prior, tp: 2, fp: 0}
+    r6.declared: {served: 0.98, derived: 0.98, basis: prior, tp: 1, fp: 0}
+    r6.env_resolved: {served: 0.85, derived: 0.85, basis: prior, tp: 1, fp: 0}
+    r6.fanout: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r6.literal: {served: 0.9, derived: 0.9, basis: prior, tp: 2, fp: 0}
+    r7.exposes: {served: 0.98, derived: 0.98, basis: prior, tp: 2, fp: 0}
+    r7.gateway_exact: {served: 0.88, derived: 0.88, basis: prior, tp: 1, fp: 0}
+    r7.gateway_template: {served: 0.8, derived: 0.8, basis: prior, tp: 1, fp: 0}
+    r7.hint_exact: {served: 0.95, derived: 0.95, basis: prior, tp: 3, fp: 0}
+    r7.hint_template: {served: 0.85, derived: 0.85, basis: prior, tp: 1, fp: 0}
+    r8.declared: {served: 0.98, derived: 0.98, basis: prior, tp: 1, fp: 0}
+    r8.federated: {served: 0.95, derived: 0.95, basis: prior, tp: 1, fp: 0}
+    r8.field_name: {served: 0.8, derived: 0.8, basis: prior, tp: 1, fp: 0}
+    r9.env_resolved: {served: 0.85, derived: 0.85, basis: prior, tp: 1, fp: 0}

tracekite/_control_plane/internal_namespaces.yml

@@ -0,0 +1,29 @@
+# Which package coordinates are *ours* (design §12).
+#
+# R3 links a consumed library to its Library rendezvous only when the
+# coordinate is internal — matched here — or when some ingested repo publishes
+# it (publish-side identity beats this file). Everything else is an external
+# dependency: counted (`r3.external_skipped`), never linked, because a graph
+# where every repo depends on `lodash` answers no blast-radius question.
+#
+# Registries are informational: they qualify where internal
+# artifacts live so operators can audit the boundary; image_registries gate
+# image-identity claims (R0-R2).
+version: 1
+ecosystems:
+  maven:
+    namespaces: []          # e.g. [org.acme, com.acme]
+  npm:
+    scopes: []              # e.g. ["@acme"]
+  golang:
+    module_prefixes: []     # e.g. [github.com/acme/]
+  pypi:
+    prefixes: []            # e.g. [acme-]
+  nuget:
+    prefixes: []            # e.g. [Acme.]
+  gem:
+    prefixes: []
+  cargo:
+    prefixes: []
+registries: []              # e.g. [artifactory.acme.io, npm.pkg.github.com]
+image_registries: []

tracekite/_control_plane/promotions.yml

@@ -0,0 +1,10 @@
+# Append-only ledger of D6 human promotions, replayed by link_full so the
+# graph stays disposable (design §12, invariant 12). Entries are appended by
+# the review-queue UI (M3); never edit past entries.
+promotions: []
+# Entry shape:
+# promotions:
+#   - claim_key: "http:GET /billing/{}"
+#     target: "global:HttpContract:GET /billing/{}"
+#     promoted_by: "user@example.com"
+#     at: "2026-07-26T00:00:00Z"

tracekite/_control_plane/repos.yml

@@ -0,0 +1,9 @@
+# The roster: which repositories belong in the graph (design §12, D11).
+# The census tool can generate a first draft. auto_refresh opts a repo into
+# the M2 heartbeat (git ls-remote drift detection, 6h jittered cycle).
+repos: []
+# Example:
+# repos:
+#   - url: https://github.com/myorg/payment-service
+#     branch: main            # optional, defaults to the remote default branch
+#     auto_refresh: true      # D11 heartbeat opt-in

tracekite/_control_plane/service_aliases.yml

@@ -0,0 +1,9 @@
+# Manual alias overrides — always win over resolver output (design §12, R0).
+# Unused or conflicting entries are reported by the linker, never silently
+# dropped. Alias keys are scope-qualified: "{scope}:{name}".
+services: {}
+# Example:
+# services:
+#   payments:
+#     aliases: ["compose-project-a:payment", "prod:payment-svc", "discovery:PAYMENT-SERVICE"]
+#     repo: myorg_payment-service

tracekite/_control_plane/vendor_catalog.yml

@@ -0,0 +1,57 @@
+# Third-party services an estate calls but does not own (roadmap C2).
+#
+# A call to `api.stripe.com` is qualified — the code names a host — but no
+# internal service answers it, so the join declines and the call vanishes
+# into `r7.unmatched_qualified`. That is indistinguishable from a broken
+# internal call, and it hides a real dependency: an outage at a vendor breaks
+# the same consumers an outage at an internal service would.
+#
+# Classifying is not linking. Nothing here creates an edge; it turns an
+# anonymous decline into a named one, so "we call Stripe from three services"
+# becomes a countable fact rather than an absence.
+#
+# `suffixes` match the end of a host, case-insensitively. Keep them specific:
+# a suffix that matches too broadly would classify an internal host as a
+# vendor and hide a genuine missing edge behind a plausible label.
+version: 1
+
+vendors:
+  stripe:
+    category: payments
+    suffixes: [api.stripe.com, files.stripe.com]
+  twilio:
+    category: messaging
+    suffixes: [api.twilio.com, lookups.twilio.com, verify.twilio.com]
+  sendgrid:
+    category: messaging
+    suffixes: [api.sendgrid.com]
+  segment:
+    category: analytics
+    suffixes: [api.segment.io, cdn.segment.com]
+  aws_s3:
+    category: storage
+    suffixes: [s3.amazonaws.com, .s3.amazonaws.com]
+  aws_sqs:
+    category: queue
+    suffixes: [sqs.amazonaws.com, .queue.amazonaws.com]
+  github:
+    category: vcs
+    suffixes: [api.github.com]
+  slack:
+    category: messaging
+    suffixes: [slack.com/api, hooks.slack.com, api.slack.com]
+  datadog:
+    category: observability
+    suffixes: [api.datadoghq.com, http-intake.logs.datadoghq.com]
+  openai:
+    category: ai
+    suffixes: [api.openai.com]
+  anthropic:
+    category: ai
+    suffixes: [api.anthropic.com]
+  auth0:
+    category: identity
+    suffixes: [.auth0.com]
+  google_maps:
+    category: geo
+    suffixes: [maps.googleapis.com]

tracekite/agent_setup.py

@@ -0,0 +1,120 @@
+"""Explicit, fail-closed installation of the TraceKite agent skill.
+
+MCP clients do not share a configuration schema. Registering the server is
+therefore kept out of this module and documented per client; this installer
+only writes skill locations whose global contract is published.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+SKILL_CONTENT = """---
+name: tracekite
+description: Cross-repository dependency, caller, and impact tracing with file:line evidence. Use for "who calls this", "who breaks if I change this", "what depends on this service", "what does this endpoint reach" — and before any filesystem search for a caller or consumer that may live in another repository.
+---
+
+# TraceKite
+
+TraceKite answers dependency questions from a pre-indexed evidence graph, so
+one query replaces a repository-wide search.
+
+Its edges are joined from configuration, manifests and route tables as well as
+source, so they include callers no text search can reach: a URL built from an
+environment variable, a route registered in another language, a gateway that
+rewrites the path before forwarding it. Searching for those returns nothing
+even when the dependency is real.
+
+## Query these before searching the filesystem
+
+- `services()` — repository-backed services in the loaded graph.
+- `consumers_of(node_id)` — active incoming edges with evidence spans.
+- `trace(from_id, to_id)` — active paths between exact node IDs.
+- `deprecations()` — deprecated contracts and their active consumers.
+
+Call them inline and directly. A caller, dependency or impact question these
+tools answer should not become a grep sweep or a delegated search agent: the
+graph already holds the answer, with provenance, at a fraction of the context.
+
+## Reading a result
+
+Every edge cites `file:line` on both sides of the join. When you need
+method-level detail, open the cited location — do not re-read the file to
+rediscover what the citation already names.
+
+An empty or declined result is evidence that TraceKite could not establish the
+relationship, not an invitation to infer one. A `found: false` answer carries
+`candidates`; re-query with one of those rather than guessing an ID. Never
+assert an edge the tools did not return.
+"""
+
+
+class SkillConflictError(RuntimeError):
+    """An existing skill differs, so overwriting it would destroy user data."""
+
+
+@dataclass(frozen=True)
+class SkillTarget:
+    clients: frozenset[str]
+    relative_path: tuple[str, ...]
+    label: str
+
+
+TARGETS = (
+    SkillTarget(frozenset({"claude"}),
+                (".claude", "skills", "tracekite", "SKILL.md"),
+                "Claude Code"),
+    SkillTarget(frozenset({"codex"}),
+                (".agents", "skills", "tracekite", "SKILL.md"),
+                "Codex"),
+    SkillTarget(frozenset({"kimi"}),
+                (".kimi", "skills", "tracekite", "SKILL.md"),
+                "Kimi"),
+    SkillTarget(frozenset({"antigravity"}),
+                (".gemini", "config", "skills", "tracekite", "SKILL.md"),
+                "Antigravity"),
+)
+SUPPORTED_CLIENTS = frozenset(c for target in TARGETS for c in target.clients)
+
+
+def _selected_targets(clients: list[str] | None) -> list[SkillTarget]:
+    selected = set(clients or ["all"])
+    unknown = selected - SUPPORTED_CLIENTS - {"all"}
+    if unknown:
+        raise ValueError(f"unsupported client(s): {sorted(unknown)}")
+    if "all" in selected:
+        return list(TARGETS)
+    return [target for target in TARGETS if target.clients & selected]
+
+
+def install_skills(clients: list[str] | None = None,
+                   home: Path | None = None) -> list[tuple[Path, str]]:
+    """Install selected skills without modifying or replacing existing data."""
+    root = home or Path.home()
+    targets = [(root.joinpath(*target.relative_path), target.label)
+               for target in _selected_targets(clients)]
+
+    conflicts = [path for path, _label in targets
+                 if path.exists() and path.read_text(encoding="utf-8") !=
+                 SKILL_CONTENT]
+    if conflicts:
+        rendered = ", ".join(str(path) for path in conflicts)
+        raise SkillConflictError(
+            f"refusing to overwrite existing skill file(s): {rendered}")
+
+    for path, _label in targets:
+        if path.exists():
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(SKILL_CONTENT, encoding="utf-8")
+    return targets
+
+
+def cmd_install_skill(args) -> int:
+    targets = install_skills(getattr(args, "client", None))
+    print("Installed or verified TraceKite skill:")
+    for path, label in targets:
+        print(f"  {label}: {path}")
+    print("MCP registration is client-specific; see "
+          "docs/plugins-and-mcp-guide.md.")
+    return 0