How-to Guides

Use RazorWire form interactions when a server-rendered form needs small local mechanics without page-specific JavaScript: reveal or disable conditional fields, add one-dimensional model-bound rows, duplicate draft rows, and remove rows while keeping ASP.NET Core model binding predictable.

RazorWire's first-party browser assets are authored in TypeScript and delivered through the same package paths that hosts already use. The package also carries an exact, byte-copied Turbo runtime under its own custody checks. Application code does not need to move RazorWire script URLs, globals, custom events, DOM hooks, CSS hooks, or island strategy names.

RazorWire page navigation enhances same-page section links without turning your page into a client-side app. Use it when a server-rendered page already has normal anchors and sections, but needs active section state, reduced-motion-aware navigation, optional compact panel close behavior, and Turbo/frame lifecycle cleanup.

When using RazorWire Turbo Streams to replace or update parts of a page that contain forms, the original Anti-Forgery token hidden input may be lost. To prevent `400 Bad Request` errors on subsequent form submissions, ensure the token is included in your updated HTML.

Use RazorWire Behavior Kit when a server-rendered app needs small app-authored JavaScript that follows RazorWire's page lifecycle. Behavior Kit is for progressive enhancement, not for replacing your frontend architecture.

Hybrid hosting keeps static pages cheap while leaving RazorWire-managed live behavior on a real ASP.NET Core app. The public site can serve exported files from `https://www.example.com`, while streams, islands, and safe RazorWire forms call `https://api.example.com`.

Use RazorWire section copy when a server-rendered documentation page, reference page, or long-form article needs stable "copy link to this section" behavior without app-specific clipboard JavaScript.

See browser status pages and production error pages move from local startup policy to a named AppSurface Web behavior contract.

Configure explicit no-evidence rules, coverage evidence, resource-backed browser E2E, and release envelopes without claiming skipped tests are complete coverage.

Capture one real migration-job change across the current AppHost, deployment workflow, environment file, and OpenTofu root. Record the deployed Job and imported-provider representation, including task count, parallelism, retries, timeout, provenance labels, IAM policy, network, Cloud SQL attachment, secret reference, and service account. Values omitted by a legacy command are not AppSurface defaults.

These guidelines apply to all changes made in this repository.

Rule ID | Category | Severity | Notes --------|----------|----------|------- ASFLOWA001 | AppSurface.Flow.Authoring | Error | Generated Flow outcome is not mapped. ASFLOWA002 | AppSurface.Flow.Authoring | Error | Generated Flow target does not exist. ASFLOWA003 | AppSurface.Flow.Authoring | Error | Generated Flow target is ambiguous or incompatible. ASFLOWA004 | AppSurface.Flow.Authoring | Error | Generated Flow start node is invalid. ASFLOWA005 | AppSurface.Flow.Authoring | Error | Generated Flow authoring declaration is invalid. ASFLOWA006 | AppSurface.Flow.Authoring | Warning | Generated Flow authoring mixes generated and low-level registration.

This note is the CI-000 baseline for build-time work. It records the current PR decision path before coverage artifact changes or coverage-matrix experiments are judged by timing data.

Issue `#425` defines the design contract for future AppSurface CLI authentication. It does not add auth commands yet.

AppSurface deployment turns explicit application-topology intent into reviewable provider artifacts while leaving cloud authority with the consuming application's release workflow.

AppSurface Docs should feel like a focused documentation workspace, not a marketing site and not a generic SaaS dashboard. The UI should help people orient quickly, scan densely, and move deeper into docs with very little friction.

This note keeps the in-repo AppSurface Docs plan aligned with the phased GitHub roadmap.

AppSurface Flow is the typed long-running process surface for AppSurface. It lets package authors describe a process as a stable graph of nodes, run that graph locally for tests and examples, then map the same node outcomes into durable orchestration decisions.

Explains the OSS license boundary, commercial purchase intent, and package-readiness signals.

AppSurface Web owns a small, composable [Progressive Web App](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps) foundation: install metadata, application-icon badging requests, explicit offline behavior, push-event plumbing, service-worker registration metadata, and privacy-safe diagnostics. Each capability is opt-in. Badging does not own an attention count or prove that an icon changed. Enabling push does not request notification permission, create a subscription, choose recipients, or send a message.

Local AppHost composition and native deployment-pipeline integration for .NET Aspire applications.

This directory contains libraries and tools for building command-line applications.

AppSurface maintains a coordinated release contract. This file explains the contribution rules that feed the public release surface.

Integrations with various dependency injection containers and advanced DI utilities.

Every deployment validation failure uses an `ASDEPLOY1xx` or Aspire-adapter `ASDEPLOY2xx` code and safe Problem, Cause, Fix, and Docs fields. Diagnostics contain identifiers when useful but must not contain parameter values, inherited environment contents, connection strings, raw secret material, or unsanitized tool output.

`DeploymentIntent` is a schema-versioned, provider-neutral snapshot of one evaluated Aspire environment and an explicit full source revision. Version 1 accepts one or more `MigrationJobIntent` values. Jobs are sorted by `DeploymentLogicalId`; duplicate ids and empty targets fail before rendering.

Generated by /office-hours on 2026-09-01 Branch: main Repo: forge-trust/AppSurface Status: APPROVED — /autoplan final gate (2026-09-02) Mode: Builder Supersedes: andrew-main-design-20260823-issue-776-evidence-coverage-core.md

Generated by /office-hours on 2026-08-19 Branch: main Repo: forge-trust/AppSurface Status: APPROVED (office-hours and autoplan, 2026-08-20) Mode: Builder Supersedes: andrew-main-design-20260813-043247-issue147-rich-authoring.md

Generated by `/office-hours` on 2026-08-23 Branch: `main` Repository: `forge-trust/AppSurface` Status: APPROVED — private-core extraction selected and autoplan-reviewed Mode: Builder Supersedes: none; the nearest `main` design is the unrelated #771 Python-docstring spike. Builds on: [contract-first EvidenceHost design](https://github.com/forge-trust/AppSurface/blob/main/docs/designs/appsurface-evidencehost-contract-first.md) and [#775](https://github.com/forge-trust/AppSurface/pull/775)

Generated by /office-hours on 2026-08-23T14:55:33-04:00 Branch: main Repo: forge-trust/AppSurface Status: APPROVED Mode: Builder Supersedes: andrew-main-design-20260821-033503.md

Generated by /office-hours and queued for /autoplan on 2026-06-21 Branch: codex/localsecrets-secret-tool-autoplan Repo: forge-trust/AppSurface Status: DRAFT Mode: Builder

Generated by `/office-hours` on 2026-08-18 Branch: `HEAD` (detached) Repo: `forge-trust/AppSurface` Status: APPROVED Mode: Builder

Generated by `/office-hours` on 2026-08-31 Branch: detached HEAD at `b34970c8` Repo: forge-trust/AppSurface Status: IMPLEMENTED Mode: Builder

This guide defines the internal, versioned W3C trace-context contract for PostgreSQL-backed durable Flow execution. It is an operational correlation feature: it is never authorization, scope routing, payload storage, or a substitute for PostgreSQL RLS.

This document is the normative persistence and processing contract for the PostgreSQL Schedule implementation. It completes the public `IDurableScheduleClient` preview contract without starting a hosted scheduler. A caller invokes one bounded `PostgreSqlDurableScheduleProcessor.ProcessDueAsync` pass from its own trusted trigger.

This ledger records how the public surface from the original durable-contract commit was treated when the contract was rebuilt as three preview packages. The checked-in [Durable](https://github.com/forge-trust/AppSurface/blob/main/Durable/ForgeTrust.AppSurface.Durable/PublicAPI.Shipped.txt), [Provider](https://github.com/forge-trust/AppSurface/blob/main/Durable/ForgeTrust.AppSurface.Durable.Provider/PublicAPI.Shipped.txt), and [PostgreSQL](https://github.com/forge-trust/AppSurface/blob/main/Durable/ForgeTrust.AppSurface.Durable.PostgreSql/PublicAPI.Shipped.txt) snapshots are the exhaustive member-level source of truth; this ledger explains the intentional package and visibility decisions.

This ledger is the audit boundary for reconstructing the PostgreSQL Work provider on current `main`. Commit `226346bc` is evidence, not merge-ready history or an independent specification. The current [`ForgeTrust.AppSurface.Durable`](ForgeTrust.AppSurface.Durable/README.md) and [`ForgeTrust.AppSurface.Durable.Provider`](ForgeTrust.AppSurface.Durable.Provider/README.md) contracts, the [`Work protocol v1`](work-protocol-v1.md), and the [`slice 3 reference workload`](slice3-reference-workload.md) are authoritative.

This is the first-success and conformance workload for the PostgreSQL Work provider. It proves atomic acceptance, process-loss recovery, exact effect permission, stable provider identity, and safety-class handling.

This ledger is the audit boundary for reconstructing the PostgreSQL Flow engine on current `main`. Commit `456dbfa3` is evidence, not merge-ready history or an independent specification. The current [`ForgeTrust.AppSurface.Durable`](ForgeTrust.AppSurface.Durable/README.md) and [`ForgeTrust.AppSurface.Flow`](../Flow/README.md) contracts, the [`Flow protocol v1`](flow-protocol-v1.md), and the [`slice 4 reference workload`](slice4-reference-workload.md) are authoritative.

This is the first-success and conformance workload for the PostgreSQL Flow engine (slice 4). It proves atomic Flow instance creation, transition step evaluation, external event delivery, timer expiry, child Work activity integration, recovery invariants across 11 protocol boundaries, options reuse, RLS scope isolation, and operator release/disable safety. The timer-winner boundary is certified by force-terminating a separate process after the database commit; the other Flow boundaries use transaction rollback and fresh processor instances. The existing slice-3 workload separately certifies child Work process loss after an effect permit.

Every actual scheduler barrier receives a row before it is changed. Do not add a lifecycle timer or modify a fixture until the exact coverage-step baseline leaves two candidates indistinguishable.

Use this page to publish the implementation result. A safe no-change ceiling is a complete outcome.

Complete this committed record before changing any sharing or scheduler boundary. Raw local `TestResults/coverage-merged/` output remains uncommitted; each row below links the workflow run, commit SHA, command, and retained `coverage-efficiency-evidence` artifact that produced it.

Use this procedure when changing the pinned Keycloak image or releasing a new immutable image containing a registered login theme. It applies to the [Keycloak AppHost package](../README.md), not to production automation. Application CI and operators own image publication, health checks, realm mutation, rollout, and rollback.

<https://polyformproject.org/licenses/small-business/1.0.0>

Use LocalSecrets when a solo AppSurface app needs one-machine local development secrets and is not ready for a remote vault. The app keeps the same logical AppSurface config key, while LocalSecrets stores the value under the app and environment on the current machine.

Use this guide when a developer is already authorized to read a Google Secret Manager value and needs a reproducible, local integration-test clone. The `appsurface secrets transfer` workflow moves the value directly between the approved providers so it is not exposed in the terminal, a plan, a receipt, or a shell history.

LocalSecrets does not parse `.env` files directly. Move each secret into the local store using the same AppSurface config key that the app already expects.

Keep the same logical config keys when moving from `dotnet user-secrets` to LocalSecrets.

LocalSecrets is the single-machine pre-vault posture. Google Secret Manager is the remote provider for Google Cloud hosts that need team-safe storage, IAM-mediated access, and production-like source evidence.

Use this guide when a macOS AppHost reports `local-secret-migration-required`. That status means the current process can confirm that a retained legacy Keychain record is readable, but no v2 record exists yet. It is terminal by design: an AppHost never writes Keychain records during configuration resolution or claims cross-process parity before migration.

LocalSecrets is a pre-vault step. The migration ladder is:

Application-side logging, tracing, and metrics for AppSurface apps.

This dashboard is a maintainer review surface for package-index evidence. It is not a live NuGet publish, artifact, smoke-install status board, or per-version release evidence bundle; use the release cockpit and protected package workflows for per-version publish proof.

AppSurface Durable is a public-preview package family for portable durable contracts. It is split by audience:

This is the normative operation and lock manifest for Durable slice 4. It specifies observable behavior, transaction boundaries, lock hierarchy, crash recovery boundaries, and execution state transitions for the PostgreSQL Flow engine. The package starts no worker or background polling service; unit and integration tests and future hosted runtime code drive each operation deterministically.

This is the normative operation and lock manifest for Durable slice 3. It specifies observable behavior, transaction boundaries, and ordering. Internal C# and SQL may be decomposed differently, but must preserve these invariants. The package starts no worker; tests and later hosting code drive one operation at a time.

`ForgeTrust.AppSurface.Docs.ConsumerFixture` is the executable reference host for named Docs composition. It keeps the legacy `/docs` fixture path for existing browser-layout checks and exposes a separate named mode for the public/internal proof.

RazorWire helps server-rendered ASP.NET Core apps update page fragments without asking every app to invent a separate frontend runtime. That means RazorWire occasionally owns small generated UI nodes: enhancement markers, form feedback, stream connection affordances, and other package-created fragments that support RazorWire behavior.

RazorWire stream endpoints are safe by default. A request must pass channel validation, stream authorization, and single-process admission before the endpoint writes `text/event-stream`, subscribes to the hub, or consumes an admission lease.

AppSurface is pre-`v1.0.0`, but security reports still need a private path.

This ledger records the evidence used to build Schedule persistence. It prevents historical or preview-only fragments from outranking the landed Durable protocols.

This is the checked PostgreSQL Gate A proof for the public preview. It creates a one-time Work Schedule, runs one manual pass, and verifies one immutable occurrence and one accepted Work. It proves durable identity and target acceptance; external provider effects remain governed by the Work registration's provider-safety policy.

Measured on 2026-08-07 from the `codex/durable-slice-7-adoption` working tree after a clean source build. The checked-in [`warm/run.json`](https://github.com/forge-trust/AppSurface/blob/main/Durable/evidence/postgresql-slice7/warm/run.json) records the immutable head and merge-base revisions alongside the working-tree source fingerprint used for the measurement.

RazorWire auth helpers are passive UI projection. They do not authorize endpoints, sign users in, sign users out, or turn build-time identity into runtime identity. Static export treats those helpers as public artifact boundaries: protected `rw:auth-allowed` content is never written to CDN or hybrid output.

Status: Implemented and verified on the supported public Aspire surface Design: [Ordered Local Seed Extension Points](auth-aspire-keycloak-local-seeds.md)

ForgeTrust.AppSurface.Cli includes the following third-party payloads in addition to the repository license.

ForgeTrust.AppSurface.Docs includes the following third-party components in addition to the repository license.

`ForgeTrust.AppSurface.Web.Push` depends on [Lib.Net.Http.WebPush 3.3.1](https://github.com/tpeczek/Lib.Net.Http.WebPush), copyright Tomasz Pęczek, licensed under the MIT License.

ForgeTrust.AppSurface.Web.Tailwind and its retained direct companion packages include the following third-party attribution in addition to the repository license.

ForgeTrust.RazorWire includes the following third-party component in addition to the repository license.

This review records the compatibility analysis for the package-owned Turbo upgrade in AppSurface issue [#656](https://github.com/forge-trust/AppSurface/issues/656). It covers npm `@hotwired/turbo` 8.0.12 source commit [`ea54ae5a`](https://github.com/hotwired/turbo/commit/ea54ae5ad4b6b28cb62ccd62951352641ed08293) through GitHub tag [`v8.0.23`](https://github.com/hotwired/turbo/releases/tag/v8.0.23).

LocalSecrets is a local user-session feature. CI jobs, containers, service accounts, and headless Linux sessions should prefer environment variables, key-per-file, or a remote secret provider.

This directory contains libraries and tools specifically for web application development within the AppSurface ecosystem.