// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
= Face Identity Kit Standard
:toc:
:toclevels: 3
:icons: font

== Purpose

This standard defines how to launch and maintain language "faces" so users feel
at home immediately.

Design rule:

*Everything turns toward the target community.*

That means syntax, errors, tooling language, examples, branding, and migration
story all match the audience's existing mental model.

== Home Criteria (Non-Negotiable)

A face is compliant only when all five criteria pass:

. Syntax Home
* Users can write in a style they already know.

. Error Home
* Errors use familiar terms, not internal compiler jargon.

. Tooling Home
* Existing workflow assumptions are preserved (CLI shape, editor flow, package
  ecosystem touchpoints).

. Cultural Home
* Naming, symbols, mascot, and examples feel native to that community.

. Proof Upgrade
* One sentence clearly states what users gain beyond familiarity.

If any one of these fails, the face is ergonomics theater.

== Naming Guardrails

Names MUST:

* End with `Script` for this family.
* Be pronounceable in one pass.
* Be distinct from active adjacent language brands.
* Support obvious mascot/visual identity.
* Have a non-awkward CLI token (`<name> check foo.ext`).

Names SHOULD:

* Signal welcome, not superiority.
* Evoke the target community's language culture.
* Keep domain and package namespace collision risk low.

Avoid names that are likely to be confused with existing brands:

* `ReasonScript` (too close to Reason/ReasonML and ReScript history)
* `RealScript` (already widely used in adjacent namespaces)

== Candidate Name Sets

These are putative candidates for community-facing variants.

=== ReScript-Adjacent Community

. `RelayScript`
* Emphasizes bridge/interoperability semantics.

. `RivetScript`
* Connotes sturdy engineering and compile-time guarantees.

. `AlloyScript`
* Signals composition of familiar JS ergonomics with stronger typing and
  ownership guarantees.

=== CoffeeScript / Ruby-JavaScript Community

. `CappauScripto` (working selection, 2026-04-12)
* Playful coffee identity with a distinctive, memorable face name.

. `CremaScript` (alternate)
* Smooth, readable, and coffee-native identity.

. `MokaScript` (alternate)
* Coffee-domain name with clear pronunciation and low ambiguity.

=== PureScript-Adjacent Community

. `AxiomScript`
* Signals lawfulness, principled semantics, and formal confidence.

. `VerityScript`
* Signals truthfulness and correctness-by-construction ethos.

. `ProofScript`
* Directly communicates theorem/proof-oriented confidence.

== Family Snapshot (Current Direction)

Canonical family direction:

* `RattleScript` - Python-facing
* `JaffaScript` - JavaScript-facing
* `PseudoScript` - pseudocode-facing
* `CappauScripto` - CoffeeScript-facing (working selection)
* PureScript-facing: `TBD` (`LucidScript` remains tentative pending final collision decision)
* ReScript-facing: `TBD` (intentionally deferred)

This standard does not force those names; it defines what any accepted name
must satisfy.

== Decision State (2026-04-12)

* CoffeeScript-facing face: `CappauScripto` (working selection)
* CoffeeScript-facing identity card: link:CAPPAUSCRIPTO-FACE-IDENTITY-CARD.adoc[CappauScripto Face Identity Card]
* CoffeeScript-facing release gate tracker: link:CAPPAUSCRIPTO-RELEASE-GATE-TRACKER.adoc[CappauScripto Release Gate Tracker]
* CoffeeScript-facing compatibility matrix: link:CAPPAUSCRIPTO-COMPATIBILITY-MATRIX.adoc[CappauScripto Compatibility Matrix]
* CoffeeScript-facing migration spec: link:CAPPAUSCRIPTO-MIGRATION-SPEC.adoc[CappauScripto Migration Spec]
* PureScript-facing face: `TBD` (`LucidScript` is tentative only)
* ReScript-facing face: intentionally deferred
* OCaml/Caml-adjacent naming: intentionally deferred

== Face Identity Card Template

Each face proposal MUST ship a one-page identity card:

[cols="1,3", options="header"]
|===
| Field | Required content

| Face name
| Product name and CLI token

| Audience
| Primary community and migration source

| Syntax promise
| Top 10 syntax mappings in one table

| Error vocabulary
| Canonical error -> face wording mapping

| Tooling promise
| Package manager/editor/CI assumptions

| Proof upgrade sentence
| Single sentence: "You keep X, gain Y"

| Mascot and visual language
| Symbol, color direction, and tone keywords

| Migration path
| "Day 0, Day 7, Day 30" onboarding flow
|===

== Beyond Sugar Adoption Playbook

This section defines how to make a face compelling without changing
AffineScript core semantics.

Goal:

*Make switching feel low-risk, high-reward, and operationally obvious.*

=== Required Adapter Layers

Each face rollout MUST include these adapter layers:

. Behavioral Compatibility Suite
* Golden tests on real migrated projects from the target community.
* Publish pass/fail matrix by feature area.

. Migration CLI + Autofix
* Provide a codemod tool (`<face>-migrate` or equivalent).
* Emit file-by-file "what changed and why" notes.

. Face-Native Library Facade
* Alias familiar package/module names and API shapes.
* Prefer wrappers over forcing immediate canonical API rewrites.

. Source-Faithful Diagnostics
* Face-native error wording plus source-map remapping to original face files.
* Keep canonical error detail available behind a verbose flag.

. Ecosystem Bridge Packs
* Ship adapters for top dependency clusters used by community X.
* Include examples that mirror common production patterns.

. IDE and Editor Parity
* Completion, hover, go-to-definition, lint, and format-on-save must meet
  baseline expectations of community X.

. Proof-Oriented Switching Artifacts
* Publish "before vs after" evidence for migration effort and defect classes.
* Include one small and one medium real-world port.

. Day-0 Starter Packs
* Template repos, quickstarts, and copy-paste examples in target dialect.
* Keep onboarding under 15 minutes to first successful run.

=== Adoption Evidence Bundle

Before claiming a face is migration-ready, publish:

[cols="1,3", options="header"]
|===
| Artifact | Minimum requirement

| Migration report
| At least 3 representative ports with explicit blocked/partial/complete status

| Compatibility dashboard
| Public matrix for syntax/features/libs/tooling parity

| Defect delta
| Quantified reduction or reclassification of critical runtime failures

| Time-to-first-success
| Measured setup and first-pass run time for a new user

| Switchback analysis
| Honest reasons users reverted, with tracked mitigation plan
|===

== Release Gate

A face name and identity are not launch-ready until:

* Face transform exists in compiler.
* Face-aware error wording exists for type/resolve/ownership errors.
* At least one face-specific fixture file exists.
* At least one face-specific E2E test suite exists.
* Identity card exists and is linked from docs.
* Migration CLI exists with documented autofix behavior.
* Compatibility suite results are published for representative projects.
* At least one ecosystem bridge pack is shipped.
* Adoption evidence bundle is published and linked.

== Compliance Note

When discussing or proposing names in planning threads, apply this kit first.
Do not pick names from aesthetics alone.
