AppSurface Search
Section Start Here
Guide

AppSurface v0.1 package chooser

Start with the package that matches the app you are building, then add optional web modules and support surfaces only when you need them.

Source of truth

View source Edit this page

Last updated

Status

v0.1 chooser

This page is generated from evaluated project metadata plus a curated manifest of what first-time AppSurface adopters should install directly.

Safe To Consume

Scope: Repository-wide. The chooser covers AppSurface's coordinated v0.1 package family, support packages, and proof-host surfaces.

Freshness: Regenerated in CI whenever the package surface or chooser guidance changes on main.

Migration: Read the pre-1.0 upgrade policy

Record

Package READMEs remain the deep reference. This chooser is the public install map for the current repo state.

  • packages/package-index.yml
  • README.md
  • releases/README.md

Generated from packages/package-index.yml and evaluated project metadata. Do not edit this file by hand.

AppSurface v0.1 is a coordinated .NET 10 package family. Start with the package that matches the app you're building, then add optional modules only when your app needs them.

All direct-install packages and tools currently target net10.0. Library package rows use dotnet package add; in .NET 10, dotnet package add and dotnet add package are equivalent. Tool rows use dotnet tool install.

Web app

Install this first for a normal ASP.NET Core app with AppSurface modules when you want the base web startup pipeline, health/readiness probes, conventional browser affordances, PWA install metadata or push-worker plumbing, or authenticated config-audit diagnostics before layering on optional UI or docs packages.

dotnet package add ForgeTrust.AppSurface.Web

What you get: Base ASP.NET Core hosting, default public /health and /ready ASP.NET Core health-check probes, pre-routing and endpoint-aware middleware composition, endpoint composition, conventional browser error-page hooks, opt-in PWA manifest/head/diagnostic/shared-worker endpoints, explicit offline behavior, push-event plumbing, an inert service-worker registration helper, opt-in authenticated config audit diagnostics endpoint mapping, and the core AppSurface web module contract.

Not included: OpenAPI generation, Scalar UI, RazorWire reactive UI, Tailwind build integration, AppSurface Docs host, browser-specific install or permission UI, push subscription persistence or delivery, broad offline route/app-data caching, automatic diagnostics exposure, or authorization policy definitions.

Read next: Package-first quickstart

Composed local proof: Product readiness lab shows how the web, auth, flow, DurableTask-facing, Aspire, and Postgres product-state pieces fit together without claiming production hosting or Durable Task storage ownership. Its paired AppHost verify profile starts local Postgres and fails if the Postgres product-state row does not become proven-locally.

Release and readiness:

Also building...

  • Add ForgeTrust.AppSurface.Config.LocalSecrets after Config when local development secrets need source-aware diagnostics before a remote vault exists, including trusted Linux secret-tool resolution for nonstandard installs.
  • Add ForgeTrust.AppSurface.Config.GoogleSecretManager after Config when production-like Google Cloud hosts should read mapped AppSurface config secrets from Secret Manager with fail-closed diagnostics.
  • Add ForgeTrust.AppSurface.Auth when reusable modules need host-neutral auth results or app-owned identity mapping boundaries without taking a web or persistence dependency; use the Auth adoption ladder when choosing among auth packages.
  • Add ForgeTrust.AppSurface.Auth.AspNetCore after ForgeTrust.AppSurface.Auth when ASP.NET Core host policies should flow into AppSurface auth results or Minimal API ProblemDetails responses; use the Auth adoption ladder and run the Auth Web/RazorWire proof.
  • Add ForgeTrust.AppSurface.Auth.AspNetCore.DevAuth after ForgeTrust.AppSurface.Auth.AspNetCore only for Development hosts or explicit local/proof environments that need fake local personas to prove AppSurface policy results; use the Auth adoption ladder to keep DevAuth separate from Auth.Testing.
  • Add ForgeTrust.AppSurface.Auth.AspNetCore.Oidc after ForgeTrust.AppSurface.Auth.AspNetCore when a host wants AppSurface-named cookie/OIDC schemes while preserving ASP.NET Core ownership of middleware, defaults, and provider behavior; use the Auth adoption ladder before copying OIDC proof code.
  • Add ForgeTrust.AppSurface.Auth.Aspire.Keycloak in AppHost/dev/test projects only when a real local OIDC provider proof should pair with ForgeTrust.AppSurface.Auth.AspNetCore.Oidc; use the Auth adoption ladder to keep it separate from DevAuth, OIDC registration, and Auth.Testing.
  • Add ForgeTrust.AppSurface.Auth.Testing to integration test projects when AppSurface Auth.AspNetCore policy results need deterministic personas and canonical assertions; use the Auth adoption ladder to keep Auth.Testing separate from local DevAuth runtime personas.
  • Add ForgeTrust.AppSurface.Intelligence when you want vendor-neutral product event contracts and optional host-owned analytics sinks.
  • Add ForgeTrust.AppSurface.Observability when an AppSurface app should send logs, traces, and metrics to Aspire or an OTLP collector.
  • Add ForgeTrust.AppSurface.Flow when you want generated-case typed process graphs, inferred port mapping, and local runner tests.
  • Add ForgeTrust.AppSurface.Flow.DurableTask after ForgeTrust.AppSurface.Flow when a typed process needs durable execution.
  • Add ForgeTrust.AppSurface.Workers when worker chains need durable claim, completion, and projection-repair contracts without taking a runtime or persistence dependency.
  • Add ForgeTrust.AppSurface.Workers.DurableTask after ForgeTrust.AppSurface.Workers and ForgeTrust.AppSurface.Flow.DurableTask when worker contracts should be driven by Durable Task orchestration decisions.
  • Start with ForgeTrust.AppSurface.Console for CLI commands or worker-style processes that should share AppSurface module composition.
  • Add ForgeTrust.AppSurface.Dependency.Autofac when your app already uses Autofac and your modules need Autofac-specific registrations.
  • Start with ForgeTrust.AppSurface.Aspire for distributed app-model projects and service-default composition.
  • Add ForgeTrust.AppSurface.Web.Scalar after ForgeTrust.AppSurface.Web.OpenApi when you want a hosted API reference UI.
  • Add ForgeTrust.RazorWire when you want reactive Razor UI, Turbo-style streams, server-rendered islands, lifecycle-safe app-authored root or page-lifecycle behaviors, local declarative form interactions, or passive auth-result UI projection.
  • Add ForgeTrust.RazorWire.Auth.AspNetCore after ForgeTrust.RazorWire and ForgeTrust.AppSurface.Auth.AspNetCore when Razor views should project host policy results without owning auth enforcement.
  • Add ForgeTrust.AppSurface.Web.Tailwind when you want Tailwind without a separate Node.js asset pipeline.
  • Install ForgeTrust.AppSurface.Cli when you want appsurface docs workflows, appsurface pwa verify install-readiness evidence, or private appsurface coverage run, coverage merge, and coverage gate commands without running from source; verify tool installs with appsurface --version or dotnet tool run appsurface --version for local manifests.

Package matrix

Swipe to compare package details on narrow screens.

Package Use when Install Includes Does not include Start here Release
ForgeTrust.AppSurface.Core Install this directly only when you are authoring reusable AppSurface modules or host integrations instead of starting from a web, console, or Aspire package. dotnet package add ForgeTrust.AppSurface.Core Core module abstractions, dependency graph orchestration, AppSurfaceStartup, and StartupContext. ASP.NET Core hosting, CliFx command hosting, Aspire app-model helpers, or optional integrations. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Config Add this when your AppSurface modules need strongly typed configuration primitives, source-aware audit reports, or sanitized config-diff support instead of ad hoc configuration lookups. dotnet package add ForgeTrust.AppSurface.Config AppSurfaceConfigModule, typed config objects, configuration providers, source-aware audit reports, sanitized audit diff helpers, and explicit configuration access patterns. Web hosting, UI docs, caching, LocalSecrets local machine posture, or a remote/team vault system. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Config.LocalSecrets Add this after Config when a solo or hobbyist AppSurface app needs local development secrets before adopting a remote vault. dotnet package add ForgeTrust.AppSurface.Config.LocalSecrets AppSurfaceLocalSecretsModule, OS-backed local secret store adapters, trusted Linux secret-tool resolution, fail-closed posture modes, Unix mode-bit-hardened file fallback for deterministic examples/tests, local secret identity normalization, structured source diagnostics, test seams, and the appsurface secrets workflow. Team secret sharing, CI/container secret injection, production rotation, remote vault storage, cloud secret managers, generic vault abstractions, PATH-based executable discovery, or file-fallback parity with OS credential stores. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Config.GoogleSecretManager Add this after Config when an AppSurface app running on Google Cloud should resolve explicitly mapped configuration secrets from Google Secret Manager while keeping environment variables as the emergency override. dotnet package add ForgeTrust.AppSurface.Config.GoogleSecretManager AppSurfaceGoogleSecretManagerModule, explicit logical-key to Secret Manager mappings, optional scoped convention resolver, fail-closed terminal diagnostics for claimed keys, Google client test seam, source-aware config audit integration, and UTF-8 text conversion through AppSurface Config. Secret creation, writes, deletion, rotation, IAM provisioning, Terraform or gcloud workflows, generic multi-cloud vault abstraction, mutation CLI commands, background refresh, or runtime credential minting. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Caching Add this when your modules need lightweight in-process memoization and cache policy primitives. dotnet package add ForgeTrust.AppSurface.Caching AppSurfaceCachingModule, IMemo or Memo helpers, and cache policy primitives on top of Microsoft.Extensions.Caching.Memory. Distributed caching infrastructure, web hosting, or configuration binding. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Auth Add this when authoring AppSurface modules or host integrations that need passive cross-surface auth vocabulary or durable app-user mapping contracts without depending on ASP.NET Core. dotnet package add ForgeTrust.AppSurface.Auth AppSurfaceAuthModule, AppSurfaceAuthOptions, neutral user/session/context contracts, auth outcome and reason results, durable external-subject to app-user-id mapping contracts, passive login/logout prompts, passive audit event descriptions, and reserved metadata keys. Authentication schemes or handlers, cookies, JWT/OIDC, ASP.NET Identity, authorization policies, middleware, endpoint filters, runtime auth context accessors, user stores, provisioning implementations, database schema, challenges, forbids, redirects, audit sinks, or UI. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Auth.AspNetCore Add this in an ASP.NET Core host that already owns authentication and authorization when AppSurface modules need mapped request auth context, named host-policy results, or Minimal API endpoints with AppSurface-shaped auth failure responses. dotnet package add ForgeTrust.AppSurface.Auth.AspNetCore AppSurfaceAspNetCoreAuthModule, AddAppSurfaceAspNetCoreAuth registration, AddAppSurfacePolicy policy naming, RequireSurfacePolicy Minimal API endpoint filters with fallback-policy opt-out metadata, ASP.NET Core request auth context mapping, named host-policy evaluation, AppSurfaceAuthResult mapping, ProblemDetails auth failure responses, and safe setup diagnostics. Authentication schemes or handlers, cookies, JWT/OIDC, ASP.NET Identity, authorization policy definitions, middleware insertion, ASP.NET Core authorization middleware replacement, browser challenge or forbid execution, redirects, audit sinks, RazorWire UI, or MVC/controller auth helpers. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Auth.AspNetCore.DevAuth Add this in Development-by-default ASP.NET Core hosts or explicit local/proof environments when package consumers need selectable fake personas, a visible local control page, and AppSurface policy proof without configuring an external identity provider. dotnet package add ForgeTrust.AppSurface.Auth.AspNetCore.DevAuth AppSurface DevAuth named authentication scheme, AddAppSurfaceDevAuth registration, explicit allowed environment names, MapAppSurfaceDevAuth control endpoints, AppSurfaceDevAuthMarker embeddable state overlay, seeded personas, protected persona cookie, loopback-only status JSON, startup safety diagnostics, and ASDEV diagnostic codes. Production authentication, OIDC, JWT validation, ASP.NET Identity, password handling, durable app-user mapping, user stores, tenant authority, audit sinks, deployment auth, automatic host HTML injection, RazorWire auth UI components, or Auth.Testing integration-test assertions. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Auth.AspNetCore.Oidc Add this in an ASP.NET Core web host that already chose an OpenID Connect provider and wants AppSurface-named cookie/OIDC schemes with safe defaults and diagnostics. dotnet package add ForgeTrust.AppSurface.Auth.AspNetCore.Oidc AddAppSurfaceOidcAuth registration, AppSurfaceOidcAuthOptions, named cookie and OpenID Connect schemes, authorization-code defaults, SaveTokens false by default, local-only passive login/logout prompt helpers, OIDC subject mapping handoff, event chaining, and stable safe diagnostic codes. User stores, ASP.NET Identity replacement, identity-provider hosting, OAuth/OIDC server behavior, provider SDKs, EF Core, persistence, middleware insertion, active redirects, challenge execution, sign-in or sign-out execution, silent default-scheme takeover, token storage by default, Aspire Keycloak, Dev Auth, or app-user provisioning. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Auth.Aspire.Keycloak Add this in an Aspire AppHost when package consumers need a real local Keycloak-backed AppSurface OIDC proof without making runtime web apps reference Keycloak or Aspire hosting packages. dotnet package add ForgeTrust.AppSurface.Auth.Aspire.Keycloak AddAppSurfaceKeycloak AppHost extension, deterministic local realm/client/user import generation, secret-safe OIDC configuration projection, fixed-port preflight diagnostics, multi-signal readiness probe, disposable-data default, persistent-data opt-in, and ASKEYC diagnostics. Runtime web authentication registration, identity-provider hosting in web apps, production Keycloak administration, social IdP setup, confidential-client secret lifecycle, provider SDK abstractions, tenant mapping, user provisioning, durable app-user mapping, token storage, or runtime dependency on Keycloak packages. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Auth.Testing Add this in ASP.NET Core integration tests when a consumer needs deterministic AppSurface auth personas, policy outcomes, and ProblemDetails assertions without writing a one-off fake authentication handler. dotnet package add ForgeTrust.AppSurface.Auth.Testing AddAppSurfaceTestAuth registration, WebApplicationFactory WithAppSurfaceTestAuth setup, persona registry, CreateAppSurfaceClient persona clients, request-level persona selection, explicit scheme modes, production-environment guard, stable test diagnostics, and framework-neutral AppSurface auth result and ProblemDetails assertions. Production authentication, cookies, JWT/OIDC, ASP.NET Identity, identity providers, authorization policy ownership, middleware replacement, user stores, session freshness simulation, Dev Auth runtime personas, browser login flows, or policy bypasses. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Intelligence Add this when your AppSurface modules or host integrations need product-intelligence event contracts before choosing an analytics vendor. dotnet package add ForgeTrust.AppSurface.Intelligence AppSurfaceProductIntelligenceModule, IAppSurfaceProductIntelligence, AppSurfaceProductEvent, typed product-event registry, validation, sanitization, lifecycle states, selected experimental event allowlists, sensitivity classes, and host-owned sink contracts. PostHog SDKs, OpenTelemetry exporters, analytics storage, retention policy, dashboards, browser autocapture, session replay, cookies, or request-body capture. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Observability Add this when an AppSurface app should publish operational logs, traces, and metrics to Aspire or another OTLP collector. dotnet package add ForgeTrust.AppSurface.Observability AppSurfaceObservabilityModule, OpenTelemetry logging/tracing/metrics registration, endpoint-driven OTLP exporter setup, service identity resource metadata, source and meter naming constants, and safe no-endpoint diagnostics. Aspire AppHost resources, product analytics, dashboards, request-body capture, package-specific AppSurface spans, sampling policy design, or non-OTLP exporters. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Flow Add this when your app or module needs typed input/output port flow definitions, generated-case authoring, inferred graph mapping, and local runner tests before durable hosting. dotnet package add ForgeTrust.AppSurface.Flow AppSurfaceFlowModule, FlowNodeOutcome discriminated outcome records, generated Flow authoring attributes and analyzer, IFlowTransformerNode, typed port graph inference, IFlowNode, FlowDefinition, FlowGraphBuilder, flow definition registry, and the in-memory runner. Durable persistence, timers, external-event delivery, ASP.NET endpoints, UI, Semantic Kernel, or preview C# union syntax. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Flow.DurableTask Add this after Flow when the same typed definitions need Durable Task persistence, replay, timers, and authorized resume events. dotnet package add ForgeTrust.AppSurface.Flow.DurableTask AppSurfaceFlowDurableTaskModule, durable flow runner and client services, resume-event authorization contract, timeout and late-event mapping, retry policy decisions, and context serialization validation. Durable Task worker/client hosting, storage providers, ASP.NET endpoints, authentication handlers, UI, or Semantic Kernel. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Workers Add this when an app or reusable module needs host-neutral durable worker contracts, explicit claim/completion/projection-repair outcomes, and privacy-safe repair diagnostics before choosing a runtime adapter. dotnet package add ForgeTrust.AppSurface.Workers AppSurfaceWorkersModule, durable worker projection contract, executor contract, typed envelopes, outcome and retryability enums, correlation identifiers, privacy-safe diagnostics, safe metadata validation, and bounded projection repair requests. Durable Task worker/client hosting, EF Core, Postgres, storage schemas, queue or scheduler runtimes, ASP.NET endpoints, authentication handlers, UI, Semantic Kernel, or hosted background services. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Workers.DurableTask Add this after Workers and Flow.DurableTask when durable worker chains should map claim, completion, retry, wait, timeout, stale-signal, and projection-repair outcomes to Durable Task-facing decisions. dotnet package add ForgeTrust.AppSurface.Workers.DurableTask AppSurfaceWorkersDurableTaskModule, durable worker chain runner, worker decision kinds, typed Durable Task-facing decisions, wait/timeout/late-signal helpers, and executor/projection retry policy metadata. Durable Task worker/client hosting, storage providers, EF Core, Postgres, queue runners, scheduler runtimes, ASP.NET endpoints, authentication handlers, UI, Semantic Kernel, or hosted background services. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Console Start here for CLI apps and worker-style entry points that should run through the AppSurface startup pipeline with CliFx. dotnet package add ForgeTrust.AppSurface.Console ConsoleStartup, ConsoleApp, hosted command execution, and CliFx source-generated command discovery through AppSurface modules. ASP.NET Core hosting, OpenAPI surfaces, or Razor-based UI composition. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Dependency.Autofac Add this when you need Autofac-specific registrations or container features instead of the default .NET service collection. dotnet package add ForgeTrust.AppSurface.Dependency.Autofac AppSurfaceAutofacModule and Autofac-aware service registration hooks for AppSurface modules. The default Microsoft DI container, web hosting, or command hosting by itself. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Aspire Start here for .NET Aspire app-model projects that want AppSurface-style modular composition for service defaults and distributed resources. dotnet package add ForgeTrust.AppSurface.Aspire AspireApp entry points and modular registration for distributed application resources and service defaults. ASP.NET Core web hosting, Razor UI features, or the standalone docs host. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Web Install this first for a normal ASP.NET Core app with AppSurface modules when you want the base web startup pipeline, health/readiness probes, conventional browser affordances, PWA install metadata or push-worker plumbing, or authenticated config-audit diagnostics before layering on optional UI or docs packages. dotnet package add ForgeTrust.AppSurface.Web Base ASP.NET Core hosting, default public /health and /ready ASP.NET Core health-check probes, pre-routing and endpoint-aware middleware composition, endpoint composition, conventional browser error-page hooks, opt-in PWA manifest/head/diagnostic/shared-worker endpoints, explicit offline behavior, push-event plumbing, an inert service-worker registration helper, opt-in authenticated config audit diagnostics endpoint mapping, and the core AppSurface web module contract. OpenAPI generation, Scalar UI, RazorWire reactive UI, Tailwind build integration, AppSurface Docs host, browser-specific install or permission UI, push subscription persistence or delivery, broad offline route/app-data caching, automatic diagnostics exposure, or authorization policy definitions. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Web.OpenApi Add this after the base web package when you want generated OpenAPI endpoints for an AppSurface web app. dotnet package add ForgeTrust.AppSurface.Web.OpenApi AddOpenApi wiring, endpoint explorer setup, endpoint mapping, and default OpenAPI document transforms. A hosted API reference UI or reactive Razor components. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Web.Scalar Add this after OpenAPI when you want Scalar's interactive API reference UI served by your AppSurface web app. dotnet package add ForgeTrust.AppSurface.Web.Scalar Scalar UI endpoint mapping and the OpenAPI module dependency needed to feed it. OpenAPI authoring by itself without the base web host, or reactive Razor component streaming. Package README public preview
commercial ready
notes
ForgeTrust.RazorWire Add this when you want reactive Razor fragments, Turbo-style page updates, server-sent streams, islands, lifecycle-safe app-authored root or page-lifecycle behaviors, local declarative form interactions, or passive auth-result UI projection without moving to a separate frontend app. dotnet package add ForgeTrust.RazorWire RazorWire modules, TagHelpers, stream helpers, result-bearing stream authorization, Razor fragment updates, hybrid island support, failed-form UX, page navigation, section copy, Behavior Kit root and lifecycle registrations for app-authored progressive enhancement, stable form interactions for conditional targets and one-dimensional model-bound collections, and passive auth projection helpers over ForgeTrust.AppSurface.Auth results. OpenAPI generation, API reference UI, Tailwind asset compilation, ASP.NET Core policy evaluation, authentication schemes, cookies, OIDC, ASP.NET Identity, challenge or forbid execution, redirects, DevAuth persona controls, endpoint authorization, policy definitions, or a general frontend framework. Package README public preview
commercial ready
notes
ForgeTrust.RazorWire.Auth.AspNetCore Add this in an ASP.NET Core host that already owns authentication and authorization when RazorWire auth projection helpers should render AppSurface-shaped host policy results. dotnet package add ForgeTrust.RazorWire.Auth.AspNetCore AddRazorWireAspNetCoreAuth registration and an IRazorWireAuthResultProvider adapter over IAppSurfaceAspNetCorePolicyEvaluator. Authentication schemes or handlers, cookies, JWT/OIDC, ASP.NET Identity, authorization policy definitions, middleware insertion, browser challenge or forbid execution, redirects, DevAuth persona controls, endpoint authorization, or RazorWire core UI primitives by itself. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Web.Tailwind Add this when you want Tailwind build and watch integration in an AppSurface web app without carrying a Node.js asset pipeline. dotnet package add ForgeTrust.AppSurface.Web.Tailwind Tailwind standalone CLI integration, watch mode, generated CSS output, and transitive runtime package selection for supported build hosts. JavaScript plugin ecosystems that require npm-first tooling, or direct runtime-package selection. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Cli Install this when you want repository-level AppSurface tooling from a global or local .NET tool command. dotnet tool install --global ForgeTrust.AppSurface.Cli --prerelease The appsurface .NET tool command, appsurface docs AppSurface Docs workflows, appsurface pwa verify install-readiness evidence for AppSurface Web apps, appsurface coverage run private test orchestration with managed JUnit diagnostics, appsurface coverage merge Cobertura fan-in, appsurface coverage gate private threshold enforcement, and the appsurface secrets init, set, get, list --names-only, delete, and doctor local-secret workflow. App runtime packages, hosted coverage dashboards, coverage uploads, coverage trend storage, grouped coverage runs, TRX/TUnit result parsing, RazorWire-specific export workflows, or a replacement for project package references. AppSurface CLI README public preview
commercial ready
notes

Support and proof-host surfaces

Support and runtime packages

  • ForgeTrust.AppSurface.Web.Tailwind.Runtime.linux-arm64: Tailwind standalone runtime for Linux Arm64 build hosts. Restore it transitively through ForgeTrust.AppSurface.Web.Tailwind instead of installing it directly. Release: support runtime; not applicable; notes.
  • ForgeTrust.AppSurface.Web.Tailwind.Runtime.linux-x64: Tailwind standalone runtime for Linux x64 build hosts. Restore it transitively through ForgeTrust.AppSurface.Web.Tailwind instead of installing it directly. Release: support runtime; not applicable; notes.
  • ForgeTrust.AppSurface.Web.Tailwind.Runtime.osx-arm64: Tailwind standalone runtime for macOS Arm64 build hosts. Restore it transitively through ForgeTrust.AppSurface.Web.Tailwind instead of installing it directly. Release: support runtime; not applicable; notes.
  • ForgeTrust.AppSurface.Web.Tailwind.Runtime.osx-x64: Tailwind standalone runtime for macOS x64 build hosts. Restore it transitively through ForgeTrust.AppSurface.Web.Tailwind instead of installing it directly. Release: support runtime; not applicable; notes.
  • ForgeTrust.AppSurface.Web.Tailwind.Runtime.win-x64: Tailwind standalone runtime for Windows x64 build hosts. Restore it transitively through ForgeTrust.AppSurface.Web.Tailwind instead of installing it directly. Release: support runtime; not applicable; notes.

Docs and proof hosts

  • ForgeTrust.AppSurface.Docs: Reusable docs package for harvesting repository docs into an AppSurface Docs UI, with source harvesting, search, release archives, diagnostics, and the dark-family Theme Contract v1 for branded docs chrome. This is a real package, but it is a proof-host surface rather than the default first install for general AppSurface apps. Release: proof host; not applicable; notes. Start here: AppSurface Docs README
  • ForgeTrust.AppSurface.Docs.Standalone: Thin export host for serving or exporting AppSurface Docs. Treat it as a proof host and example app, not a package you install into another project. Release: proof host; not applicable; notes. Start here: Standalone host README

Not in the direct-install matrix

  • ForgeTrust.AppSurface.Flow.Generators: Private source generator and diagnostics used by ForgeTrust.AppSurface.Flow; consume it only through the packed Flow package. Release: excluded; not applicable; notes.
  • ForgeTrust.AppSurface.Web.Tailwind.Tasks: Private compiled MSBuild task used by ForgeTrust.AppSurface.Web.Tailwind; consume it only through the packed Tailwind package. Release: excluded; not applicable; notes.
  • ForgeTrust.RazorWire.Cli: Held out of the direct-install chooser until issue #171 lands real .NET tool packaging and stable install guidance. Release: excluded; not applicable; notes.

Maintainer notes

  • Edit packages/package-index.yml when the public package story changes.
  • Review package readiness evidence when deciding whether the package manifest, release metadata, blockers, and dependency evidence are ready for release review.
  • Package readiness evidence is package-index review evidence. Per-version release consistency lives in releases/v{version}.evidence.json and is validated by the release cockpit.
  • Keep publish_decision and expected_dependency_package_ids in packages/package-index.yml aligned with the package artifact workflow so the chooser and release contract share one package source of truth.
  • Keep tool_command_name aligned with each published .NET tool project's ToolCommandName so package validation, pre-publish coverage proof, and post-publish smoke tests run the command users will type. Tool smoke tests install the package, run --help, then require --version to match the package SemVer exactly, including stable or prerelease labels and excluding any leading v or build metadata. The command name value must be one file-name-safe command token, not a path: no whitespace, path separators, reserved ./.. segments, trailing periods, Windows reserved device names or dotted aliases, control characters, or Windows-invalid file-name characters.
  • Run dotnet run --project tools/ForgeTrust.AppSurface.PackageIndex/ForgeTrust.AppSurface.PackageIndex.csproj -- generate after changing package classifications, package READMEs, product families, readiness blockers, or readiness notes.
  • Run dotnet run --project tools/ForgeTrust.AppSurface.PackageIndex/ForgeTrust.AppSurface.PackageIndex.csproj -- verify-packages --package-version 0.0.0-ci.local before publishing changes that affect package metadata, project references, Tailwind runtime payloads, or the packaged coverage CLI. This pre-publish workflow installs the packed ForgeTrust.AppSurface.Cli tool from local artifacts, runs coverage run, coverage merge, a passing coverage gate, and an intentionally failing coverage gate, then writes coverage-cli-consumer-proof.md and blocks the publish manifest when the consumer proof fails.
  • Run dotnet run --project tools/ForgeTrust.AppSurface.PackageIndex/ForgeTrust.AppSurface.PackageIndex.csproj -- gate before publishing rebrand or release metadata changes.
  • Keep packages/README.md.yml hand-authored so AppSurface Docs metadata, trust-bar copy, and section placement stay intentional.

Redistributed payloads

Use packages/third-party-payloads.yml when a package carries copied third-party payloads, native runtime binaries, minified browser runtimes, bundled tool payloads, or generated-first-party assets that need provenance evidence. Do not add normal NuGet dependencies to this inventory unless their files are copied into the package payload.

When adding a redistributed payload:

  1. Add or update the package-local THIRD-PARTY-NOTICES.md file and pack it at package root with <None Include="$(MSBuildProjectDirectory)\THIRD-PARTY-NOTICES.md" Pack="true" PackagePath="" />. The notice must ship the applicable license/NOTICE text itself, or it must name upstream LICENSE/NOTICE files that are packed beside the redistributed payload; component metadata and marker strings alone are not sufficient redistributed-payload evidence.
  2. Add a notices record in packages/third-party-payloads.yml with package_id, component, version, license, source_url, payload_patterns, notice_paths, and markers.
  3. Add version_source_path and version_source_contains when the repo has a deterministic source of truth such as Directory.Packages.props, Web/package.json, or Tailwind.Common.props.
  4. Use an audits record only for narrow generated-first-party evidence or provenance-backed dependency closures that are not notice records. Include applies_to, matched_rule, evidence_kind, source_paths, reviewed_on, source, and revalidate_when; add generated_paths whenever evidence_kind is generated_first_party so the waiver self-invalidates when source or generated outputs move. Audit applies_to patterns must not overlap notice-covered payload entries; the gate fails broad audits that could mask notice-required payloads.
  5. Run dotnet run --project tools/ForgeTrust.AppSurface.PackageIndex/ForgeTrust.AppSurface.PackageIndex.csproj -- verify-packages --package-version 0.0.0-ci.local and fix any ASPKG### diagnostics. Payload diagnostics use Problem/Cause/Fix/Docs wording and link back to this section, and the package report shows covered/total suspicious payload counts beside the detailed payload evidence rows.

Examples already covered by the inventory: ForgeTrust.AppSurface.Cli bundles ReportGenerator under tools/**/reportgenerator/** and audits its SDK-produced .NET tool dependency closure; Tailwind runtime packages carry native Tailwind binaries under runtimes/*/native/**; ForgeTrust.AppSurface.Web.Tailwind notices its build-task CliWrap payload; ForgeTrust.AppSurface.Docs embeds the generated MiniSearch runtime and carries THIRD-PARTY-NOTICES.md; ForgeTrust.RazorWire uses generated_first_party audit evidence for browser assets generated from first-party TypeScript.