Update docs

Author: fairapps

astro.config.mjs

@@ -140,12 +140,14 @@ export default defineConfig({
           label: 'Creator Guide',
           items: [
             { label: 'Welcome', link: '/docs/' },
+            { label: 'Philosophy', link: '/docs/philosophy/' },
             { label: 'Inclusion Criteria', link: '/docs/inclusion-criteria/' },
             { label: 'Building Your App', link: '/docs/building/' },
             { label: 'Submitting Your App', link: '/docs/submitting/' },
             { label: 'Deployment & Distribution', link: '/docs/deploying/' },
             { label: 'Maintaining Your App', link: '/docs/maintenance/' },
-            { label: 'FAQ & Glossary', link: '/docs/faq/' },
+            { label: 'FAQ', link: '/docs/faq/' },
+            { label: 'Glossary', link: '/docs/glossary/' },
           ],
         },
       ],

src/components/FeatureCard.astro

@@ -3,12 +3,17 @@ interface Props {
   title: string;
   icon: string;
   color: string;
+  href?: string;
 }
 
-const { title, icon, color } = Astro.props;
+const { title, icon, color, href } = Astro.props;
+// When an href is supplied the entire card becomes a clickable link; the
+// existing .feature-card CSS already sets text-decoration: none and
+// color: inherit so anchor styling does not bleed through.
+const Tag = href ? 'a' : 'span';
 ---
 
-<span class="feature-card" data-color={color}>
+<Tag class="feature-card" data-color={color} href={href}>
   <div class="feature-card-header">
     <div class="feature-card-icon">
       <span class="material-symbols-rounded">{icon}</span>
@@ -18,5 +23,4 @@ const { title, icon, color } = Astro.props;
   <div class="feature-card-description">
     <slot />
   </div>
-  <!-- <span class="feature-card-link">Learn more <span aria-hidden="true">→</span></span> -->
-</span>
+</Tag>

src/content/docs/docs/building.md

@@ -116,6 +116,25 @@ Several points are worth noting:
 - The Swift sources are shared between platforms. Skip handles transpilation to Kotlin and Jetpack Compose. Where platform-specific code is genuinely required, the `#if SKIP` and `#if !SKIP` directives can be used to branch.
 - Fastlane metadata is checked in under `Darwin/fastlane/` and `Android/fastlane/`. The contents of these directories are described in [Submitting Your App](/docs/submitting/). The general-purpose references are the [Fastlane documentation](https://docs.fastlane.tools/) and the [Skip Fastlane deployment guide](https://skip.dev/docs/deployment/#fastlane).
 
+### Bundle identifiers {#bundle-id}
+
+Every App Fair app published through the `appfair/` fork is built with a canonical bundle identifier of `org.appfair.app.<token>`. For the `Faire-Games` token this means the production binary ships with:
+
+- **iOS** `PRODUCT_BUNDLE_IDENTIFIER` = `org.appfair.app.Faire-Games`
+- **Android** package name = `org.appfair.app.Faire_Games` (underscores replace dashes, since Java package segments cannot contain hyphens)
+
+The `Skip.env` value in the source repository is the *upstream* bundle identifier, used during local development. It can be set to anything the developer team controls — for example `com.example.fairegames` under the developer's own Apple Developer team — which is what makes it possible to sideload and run the app on a real iOS device using the developer's own signing identity. The `appfair/` fork rewrites this value to the canonical `org.appfair.app.<token>` form before signing the production binary, so the upstream bundle ID never reaches end users through the App Fair.
+
+<aside class="callout callout-caution">
+  <span class="callout-icon" style="--icon: url('/assets/icons/callout/warning.svg');" aria-hidden="true"></span>
+  <div class="callout-body">
+    <p class="callout-title">Leaving the App Fair changes the bundle identifier</p>
+    <p>Bundle identifiers are how Apple and Google decide which installed app a binary updates. An app signed with one bundle ID and an app signed with another are, from the operating system's perspective, two unrelated applications.</p>
+    <p>If a maintainer leaves the App Fair and resumes publishing the app independently under their own developer accounts, the self-published binary will use the developer's chosen bundle ID rather than <code>org.appfair.app.&lt;token&gt;</code>. Existing users who installed the app from the App Fair catalog would not receive the self-published version as an update; they would have to install it as a separate application, and the new installation would have no access to any data the prior installation stored (preferences, sync state, locally cached content, and so on). Users would effectively start fresh.</p>
+    <p>This is a one-way consequence of the publisher-of-record arrangement: the App Fair Project owns the <code>org.appfair.app.*</code> namespace, so a departing maintainer cannot take the catalog bundle ID with them.</p>
+  </div>
+</aside>
+
 ## Development workflow {#dev-loop}
 
 Day-to-day development follows a standard SwiftUI workflow:
@@ -130,7 +149,7 @@ The full development reference, including parity testing, FFI, and Kotlin intero
 
 ## Designing for the Four Cornerstones {#cornerstones-in-practice}
 
-The [four cornerstones](/docs/inclusion-criteria/#four-cornerstones) (transparent, ubiquitous, global, and accessible) are practical engineering constraints. Each is significantly easier to satisfy when designed for from the first commit than when retrofitted later. The remainder of this section translates each cornerstone into specific implementation guidance. (Transparent is handled by the project's licence and dependency choices, covered separately under [Licensing](/docs/inclusion-criteria/#licensing), so the rest of this section focuses on Ubiquitous, Global, and Accessible.)
+The [four cornerstones](/docs/philosophy/#four-cornerstones) (transparent, ubiquitous, global, and accessible) are practical engineering constraints. Each is significantly easier to satisfy when designed for from the first commit than when retrofitted later. The remainder of this section translates each cornerstone into specific implementation guidance. (Transparent is handled by the project's licence and dependency choices, covered separately under [Licensing](/docs/inclusion-criteria/#licensing), so the rest of this section focuses on Ubiquitous, Global, and Accessible.)
 
 ### Localization (Global) {#l10n}
 
@@ -202,7 +221,7 @@ Avoid background work the user has not requested. Avoid polling. Avoid burning C
 
 ### The AppFairUI components {#appfair-ui}
 
-Every App Fair app depends on the [`appfair-app`](https://github.com/appfair/appfair-app) package, which exposes the `AppFairUI` module. The dependency is added automatically by `skip create --appfair` and is mandatory for every catalog app (see [Technical requirements](/docs/inclusion-criteria/#technical-requirements)).
+Every App Fair app depends on the [`appfair-app`](https://github.com/appfair/appfair-app) package, which exposes the `AppFairUI` module. The dependency is added automatically by `skip create --appfair` and is mandatory for every catalog app.
 
 The package supplies the shared About screen, attribution metadata, third-party license rows, the "Made with Skip / Distributed through the App Fair" credits, and the `AppFairSettings` wrapper described below.
 

src/content/docs/docs/deploying.md

@@ -1,6 +1,6 @@
 ---
 title: Deployment & Distribution
-description: How the App Fair fork builds, signs, and distributes the application.
+description: How the `appfair/` fork builds, signs, and distributes the application.
 ---
 
 After a fork has been created at `github.com/appfair/<app-token>`, the application is connected to the App Fair distribution pipeline. This section describes how the pipeline operates: from the release tag through the signed binary, the app stores, and the [appfair.net](https://appfair.net) catalog.
@@ -10,7 +10,7 @@ After a fork has been created at `github.com/appfair/<app-token>`, the applicati
 Each App Fair app is associated with two repositories, both addressed by the app's [token](/docs/inclusion-criteria/#naming):
 
 - The **source repository** in the developer's GitHub organization, e.g. [`github.com/Faire-Games/Faire-Games`](https://github.com/Faire-Games/Faire-Games) for the `Faire-Games` token (published under the displayed title "Fair Games"). The developer owns this repository: source code, issue tracker, and project direction.
-- The **App Fair fork** in the [`appfair`](https://github.com/appfair) organization, e.g. [`github.com/appfair/Faire-Games`](https://github.com/appfair/Faire-Games). The App Fair owns this repository, which holds the signing credentials, store API keys, and the published release pipeline.
+- The **`appfair/` fork** in the [`appfair`](https://github.com/appfair) GitHub organization, e.g. [`github.com/appfair/Faire-Games`](https://github.com/appfair/Faire-Games). The App Fair owns this repository, which holds the signing credentials, store API keys, and the published release pipeline.
 
 This separation has two effects. The developer retains full control of the source code, including the option to discontinue the App Fair relationship and continue independently. The App Fair handles the account-bound and certificate-bound parts of mobile app distribution.
 
@@ -66,7 +66,7 @@ When a release tag (for example, `1.0.0`) is synchronized from the source reposi
 2. Builds the Android target with `skip export` and signs it with the App Fair keystore.
 3. Reads the Fastlane metadata from `Darwin/fastlane/` and `Android/fastlane/` and uploads it alongside the signed binaries to App Store Connect and the Play Console.
 4. Submits the build for review.
-5. Generates an `appindex.json` describing the release and publishes it (together with the signed binaries) as assets on the corresponding GitHub Release in the App Fair fork. The source repository is not modified by this step.
+5. Generates an `appindex.json` describing the release and publishes it (together with the signed binaries) as assets on the corresponding GitHub Release in the `appfair/` fork. The source repository is not modified by this step.
 
 Store review timing is outside the App Fair's control. Apple and Google operate their own review queues, but updates typically appear within a few days. The progress of each step can be observed in real time on the Actions tab of the fork.
 
@@ -76,7 +76,7 @@ After a release has been signed, submitted, and approved, users can install the
 
 ### The Apple App Store {#channel-app-store}
 
-The Apple App Store is the dominant channel for iPhone and iPad. App Fair releases appear there under the App Fair Project's developer name. Within the European Union, [alternative distribution channels for iOS](https://appfair.org/marketplace/) are also planned.
+The Apple App Store is the dominant channel for iPhone and iPad. App Fair releases appear there under the App Fair Project's developer name.
 
 ### The Google Play Store {#channel-play-store}
 
@@ -96,7 +96,7 @@ App Fair apps are built by their developers, but the App Fair Project appears pr
 
 This branding requirement allows users to discover the rest of the catalog from any one App Fair app.
 
-## Working Example {#example}
+## Working example {#example}
 
 The app with the [`Faire-Games`](https://github.com/Faire-Games/Faire-Games) token (published under the title "Fair Games") demonstrates the full pipeline: