# KFX developer surface

Extend Kungfu without forking Core.

KFX packages and Profile Suites add experiences, integrations, services, actions, assessments, and domain semantics through one Core-owned registry and lifecycle authority.

Status: site-synthesis
Maturity: alpha-source-projection
Canonical human entry: https://kfx.libkungfu.dev/

Machine entries:
- https://kfx.libkungfu.dev/manifest.json
- https://kfx.libkungfu.dev/architecture.json
- https://kfx.libkungfu.dev/capability-map.json
- https://kfx.libkungfu.dev/llms.txt

Reader paths:
- Build an extension: Start from the installed, version-matched authoring kit; inspect, scaffold, validate, build, qualify, and package inert bytes before requesting native admission. Sources: authoring-kit
- Understand the architecture: Trace provider-owned semantics through package facets, Core control-plane decisions, admitted contributions, and host-native presentation. Sources: kfx-contract, surface-parity-adr
- Audit trust and lifecycle: Inspect immutable source, maturity, non-claims, admission inputs, capability grants, Warrants, and receipts before relying on a package. Sources: lifecycle-adr, trust-admission-adr

Architecture nodes:
- author-provider / Author / provider [actor; source-defined-alpha; site-synthesis]: Owns extension source, package identity, declared facets, capabilities, and contribution semantics. Sources: kfx-contract
- package-suite / KFX package / Profile Suite [package; source-defined-alpha; upstream-fact]: Immutable content closure that may carry one package or a Suite of required and optional members. Sources: kfx-contract, profile-suite-adr
- view-facet / View [facet; source-defined-alpha; upstream-fact]: Host-rendered experience facet with declared entrypoint and capabilities. Sources: kfx-contract
- adapter-facet / Adapter [facet; source-defined-alpha; upstream-fact]: Integration facet for declared targets and managed Python or Node entrypoints. Sources: kfx-contract
- service-facet / Service [facet; source-defined-alpha; upstream-fact]: Process-isolated service facet with explicit runtime, host contract, and capabilities. Sources: kfx-contract, authoring-kit
- action-facet / Action [facet; source-defined-alpha; upstream-fact]: Surface-neutral intent and operation semantics retained by a Profile Suite. Sources: kfx-contract, surface-parity-adr
- assessment-facet / Assessment [facet; source-defined-alpha; upstream-fact]: Purpose-bound evidence and policy evaluation, not a lifecycle mutation or capability grant. Sources: kfx-contract, trust-admission-adr
- profile-facet / Profile [facet; source-defined-alpha; upstream-fact]: Domain semantic closure over members, facts, actions, views, policies, and qualification references. Sources: kfx-contract, profile-suite-adr
- core-registry / Core registry + semantic graph [control-plane; implemented-exact-source; reference-implementation]: Indexes providers, extension points, contributions, dependencies, versions, trust, and capability roots. Sources: kfx-contract, native-registry
- core-admission / Admission assessment [control-plane; implemented-exact-source; reference-implementation]: Evaluates exact package, dependency, KFD, Buildchain, policy, and purpose-bound inputs without mutating lifecycle. Sources: kfx-contract, trust-admission-adr
- core-capability / Capability + Warrant boundary [control-plane; implemented-exact-source; reference-implementation]: Intersects declarations with Core and workspace policy, required approvals, exact authorization roots, and Work/Warrant evidence. Sources: kfx-contract, trust-admission-adr
- core-lifecycle / Transactional lifecycle [control-plane; implemented-exact-source; reference-implementation]: One fenced Core writer owns plan, authorize, apply, rollback, and history over immutable package roots. Sources: kfx-contract, native-registry, lifecycle-adr
- core-receipt / Receipt + retained facts [control-plane; implemented-exact-source; reference-implementation]: Applied or refused outcomes retain exact authority, capability, lifecycle, and evidence dependencies. Sources: kfx-contract, native-registry, lifecycle-adr
- admitted-contribution / Admitted semantic contribution [projection; implemented-exact-source; reference-implementation]: A Core-resolved contribution plan that preserves provider ownership and exact authority roots. Sources: kfx-contract, surface-parity-adr
- gui-surface / GUI [surface; qualified-upstream-scope; reference-implementation]: Host-native visual projection of the admitted semantic contribution. Sources: surface-parity-adr
- tui-surface / TUI [surface; qualified-upstream-scope; reference-implementation]: Host-native terminal UI projection of the same admitted semantics. Sources: surface-parity-adr
- cli-surface / CLI [surface; qualified-upstream-scope; reference-implementation]: Human command projection over the same Core-owned plan and receipt contract. Sources: surface-parity-adr
- agent-surface / Agent [surface; qualified-upstream-scope; reference-implementation]: Machine-readable projection over the same contribution, action, authority, and receipt identity. Sources: surface-parity-adr, profile-suite-adr
- kfd-evidence / KFD assessment evidence [trust-evidence; purpose-bound-evidence; upstream-fact]: Fresh, purpose-bound assessment facts may inform admission but do not authorize mutation or execution. Sources: kfx-contract, trust-admission-adr
- buildchain-evidence / Buildchain exact-artifact evidence [trust-evidence; exact-artifact-evidence; upstream-fact]: Verifier result and provenance roots bind the exact source, dependencies, build plan, toolchain, artifact, and qualification evidence. Sources: kfx-contract, trust-admission-adr

Architecture relationships:
- authors: author-provider authors package-suite [source-defined-alpha] Sources: kfx-contract
- declares-view: package-suite declares view-facet [source-defined-alpha] Sources: kfx-contract
- declares-adapter: package-suite declares adapter-facet [source-defined-alpha] Sources: kfx-contract
- declares-service: package-suite declares service-facet [source-defined-alpha] Sources: kfx-contract, authoring-kit
- declares-action: package-suite closes over action-facet [source-defined-alpha] Sources: kfx-contract, profile-suite-adr
- declares-assessment: package-suite closes over assessment-facet [source-defined-alpha] Sources: kfx-contract, profile-suite-adr
- declares-profile: package-suite may define profile-facet [source-defined-alpha] Sources: kfx-contract, profile-suite-adr
- registers: package-suite is discovered and indexed by core-registry [implemented-exact-source] Sources: native-registry
- assesses-kfd: kfd-evidence informs core-admission [purpose-bound-evidence] Sources: trust-admission-adr
- assesses-buildchain: buildchain-evidence binds exact artifact for core-admission [exact-artifact-evidence] Sources: trust-admission-adr
- registry-to-admission: core-registry supplies exact graph roots to core-admission [implemented-exact-source] Sources: kfx-contract, native-registry
- admission-to-capability: core-admission constrains core-capability [implemented-exact-source] Sources: kfx-contract, trust-admission-adr
- capability-to-lifecycle: core-capability authorizes exact mutation for core-lifecycle [implemented-exact-source] Sources: kfx-contract, lifecycle-adr
- lifecycle-to-receipt: core-lifecycle emits core-receipt [implemented-exact-source] Sources: kfx-contract, native-registry
- lifecycle-to-contribution: core-lifecycle activates admitted plan as admitted-contribution [implemented-exact-source] Sources: kfx-contract, surface-parity-adr
- projects-gui: admitted-contribution projects to gui-surface [qualified-upstream-scope] Sources: surface-parity-adr
- projects-tui: admitted-contribution projects to tui-surface [qualified-upstream-scope] Sources: surface-parity-adr
- projects-cli: admitted-contribution projects to cli-surface [qualified-upstream-scope] Sources: surface-parity-adr
- projects-agent: admitted-contribution projects to agent-surface [qualified-upstream-scope] Sources: surface-parity-adr, profile-suite-adr

Capability map:
## Build
Create and qualify inert extension source and artifacts.
- authoring-lifecycle / Inspect, scaffold, validate, build, qualify, and package [available-in-installed-product; installed-product-alpha]: Version-matched offline authoring commands and SDK projection; no lifecycle authority is granted. Sources: authoring-kit
- webhook-starter / Start a service KFX [reference-starter; loopback-qualified-fixture]: Dependency-free Node webhook starter with synthetic credentials and loopback-only qualification. Sources: authoring-kit

## Connect
Join external systems through bounded adapters and services.
- adapter / Adapters [contract-defined; source-defined-alpha]: Declare targets, runtime entrypoints, and least capabilities for an integrated adapter. Sources: kfx-contract
- service / Services and webhooks [contract-and-reference-defined; installed-product-alpha]: Run process-isolated services under explicit host, network, credential, and lifecycle contracts. Sources: kfx-contract, authoring-kit

## Add
Contribute product experience and domain semantics without modifying Core.
- views / Views and experiences [contract-defined; source-defined-alpha]: Add host-rendered experiences while Core retains semantic and authority roots. Sources: kfx-contract, surface-parity-adr
- actions / Actions [profile-suite-defined; source-defined-alpha]: Declare surface-neutral operations and authorization requirements once. Sources: kfx-contract, profile-suite-adr
- assessments / Assessments [purpose-bound; implemented-exact-source]: Evaluate claims and policy at an exact evidence cut without mutating lifecycle. Sources: kfx-contract, trust-admission-adr
- profiles / Profile Suites [contract-defined; source-defined-alpha]: Package domain facts, actions, views, policies, qualification, and member closure above domain-neutral Core. Sources: kfx-contract, profile-suite-adr

## Lifecycle
Move exact content through Core-owned state transitions.
- inspect-plan / Inspect and plan [read-only; implemented-exact-source]: Resolve package closure, registry graph, trust inputs, capability diff, and exact expected roots before mutation. Sources: kfx-contract, native-registry, lifecycle-adr
- authorize-apply / Authorize and apply [warrant-required; implemented-exact-source]: Recompute exact roots and require purpose-bound capability, approval, Work, and Warrant evidence before side effects. Sources: kfx-contract, lifecycle-adr, trust-admission-adr
- operate-recover / Activate, observe, diagnose, upgrade, rollback, and remove [core-authoritative; implemented-exact-source]: One fenced writer advances lifecycle and retains applied or refused history and recovery evidence. Sources: kfx-contract, native-registry, lifecycle-adr

## Trust
Bind reliance to exact evidence without collapsing evidence into authority.
- immutable-content / Immutable package and dependency roots [required-input; implemented-exact-source]: Content identity and dependency closure are verified before they can enter Core lifecycle. Sources: kfx-contract, lifecycle-adr
- kfd-assessment / KFD purpose-bound assessment [admission-input; purpose-bound-evidence]: Fresh assessment facts can reduce policy-defined friction but cannot mint capability or mutation authority. Sources: kfx-contract, trust-admission-adr
- buildchain-attestation / Buildchain exact-artifact attestation [admission-input; exact-artifact-evidence]: Binds source, dependencies, build plan, toolchain, artifact, qualification, issuer, publisher, and verifier roots. Sources: kfx-contract, trust-admission-adr
- receipt / Capability grant, Warrant, and receipt chain [mutation-boundary; implemented-exact-source]: Exact authorization and outcome roots are retained across plan, apply, settlement, and recovery. Sources: kfx-contract, native-registry, lifecycle-adr

## Surfaces
Project one admitted semantic contribution through host-native interfaces.
- gui / GUI [host-projection; qualified-upstream-scope]: Sandboxed visual host projection; it does not own lifecycle authority. Sources: kfx-contract, surface-parity-adr
- tui / TUI [host-projection; qualified-upstream-scope]: Terminal UI projection over the same Core descriptor and roots. Sources: kfx-contract, surface-parity-adr
- cli / CLI [host-projection; qualified-upstream-scope]: Human command projection over the same plan and receipt identity. Sources: kfx-contract, surface-parity-adr
- agent / Agent [machine-projection; qualified-upstream-scope]: Machine-readable contribution, action, plan, Work/Warrant, and receipt projection. Sources: kfx-contract, surface-parity-adr, profile-suite-adr

Immutable sources:
- kfx-contract [alpha-source-contract]: https://github.com/kungfu-systems/kungfu/blob/c40f7a1a4149140558c655fa940d923bcc3c4154/framework/kfx/kungfu-kfx.contract.json sha256:4c17dddae597d19eb9ead4d3767669e3f8343a3b41cc9deb42c8eb5ff08a514d
- native-registry [implemented-exact-source]: https://github.com/kungfu-systems/kungfu/blob/c40f7a1a4149140558c655fa940d923bcc3c4154/framework/core/src/libkungfu/src/runtime/kfx/native_registry.cpp sha256:98881b2110239f54706b05da88d8a847442b82782a32805aaa6d65faa9b21808
- authoring-kit [installed-product-alpha]: https://github.com/kungfu-systems/kungfu/blob/c40f7a1a4149140558c655fa940d923bcc3c4154/framework/core/src/python/kungfu/kfx_authoring_assets/contract.json sha256:567ffd02c294aacd15e9ea8eb0e1d566c5703e9ec1c1fb81fa32bba781f7d346
- lifecycle-adr [accepted-implemented-upstream]: https://github.com/kungfu-systems/kungfu/blob/c40f7a1a4149140558c655fa940d923bcc3c4154/docs/adr/KF-ADR-019f86da-4f90-73f3-b027-c343b2bc8bcc.md sha256:f175aa649773c0bc24b0eabdba24d7e973e3e050523f7467ca87b042b7cd23cc
- surface-parity-adr [accepted-implemented-upstream]: https://github.com/kungfu-systems/kungfu/blob/c40f7a1a4149140558c655fa940d923bcc3c4154/docs/adr/KF-ADR-019f86da-4f90-72df-add3-948f3ae38c3a.md sha256:f0c68bf2c2e80af8465f5247fb8cab9b2e636c8872c9ab7023b3986a758cca1e
- trust-admission-adr [accepted-implemented-upstream]: https://github.com/kungfu-systems/kungfu/blob/c40f7a1a4149140558c655fa940d923bcc3c4154/docs/adr/KF-ADR-019f86da-4f90-7d6c-926a-ddd27dbde8ab.md sha256:cca8bdeee7d6e50f4507ada6e4122cfca2b35099c7ba3a9780d9785c55cce912
- profile-suite-adr [accepted-implemented-upstream]: https://github.com/kungfu-systems/kungfu/blob/c40f7a1a4149140558c655fa940d923bcc3c4154/docs/adr/KF-ADR-019f86da-4f90-7f46-b195-3af6228d17b1.md sha256:cb4225f9e967d814585bd4b58ccba858147e8df124842d032240e75314431847

Source boundary:
This page is a Site-owned reader synthesis of immutable Kungfu sources. Kungfu owns KFX schemas, commands, admission, capabilities, lifecycle, receipts, and qualification. The Site does not redefine or requalify them.

Adoption boundary:
This first surface uses exact Git sources and introduces no unpublished npm dependency. A later upstream-generated KFX Site Bundle may replace this projection after its own protected release and adoption gates.

Non-claims:
- This Site projection is not a KFX specification, Release Passport, Warrant, capability grant, installation receipt, or qualification result.
- An authored or locally qualified package is not installed, activated, production-admitted, or safe for every workspace.
- KFD evidence and Buildchain attestations are admission inputs; neither creates ambient runtime authority.
- The exact upstream sources record their own qualification scope. This Site change does not rerun or widen that scope, promise stable APIs, or claim new platform support.
- Presentation hosts do not own registry, admission, capability, lifecycle, or receipt authority.
- A contribution being discoverable, authored, qualified, installed, activated, or running are distinct states.
- Provider identity, first-party placement, Product roles, KFD fitness, or Buildchain provenance does not create ambient authority.
- Capability presence does not imply capability grant, activation, production admission, or universal safety.
- Maturity labels describe the exact cited source scope; they are not a new Site qualification verdict.