code2app 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+<!-- template-git-repo:badges:start -->
+<p align="center">
+    <a href="https://starterdocs.vtempest.workers.dev/docs/packages/native-app-wrapper"><img src="https://img.shields.io/badge/Docs-blue?logo=ReadTheDocs&logoColor=white" alt="Documentation" /></a>
+    <br />
+    <a href="https://github.com/OpenSourceAGI/dev-tools-starter-agent/stargazers"><img src="https://img.shields.io/github/stars/OpenSourceAGI/dev-tools-starter-agent" alt="GitHub Stars" /></a>
+    <br />
+    <a href="https://github.com/OpenSourceAGI/dev-tools-starter-agent/issues"><img src="https://img.shields.io/github/issues/OpenSourceAGI/dev-tools-starter-agent?logo=github" alt="GitHub Issues" /></a>
+    <a href="https://github.com/OpenSourceAGI/dev-tools-starter-agent/pulls"><img src="https://img.shields.io/github/issues-pr/OpenSourceAGI/dev-tools-starter-agent?logo=github&label=PRs" alt="Open Pull Requests" /></a>
+    <a href="https://github.com/OpenSourceAGI/dev-tools-starter-agent/pulls?q=is%3Apr+is%3Aclosed"><img src="https://img.shields.io/github/issues-pr-closed/OpenSourceAGI/dev-tools-starter-agent?logo=github&label=PRs%20merged&color=8957e5" alt="Merged Pull Requests" /></a>
+    <a href="https://github.com/OpenSourceAGI/dev-tools-starter-agent/discussions"><img src="https://img.shields.io/github/discussions/OpenSourceAGI/dev-tools-starter-agent" alt="GitHub Discussions" /></a>
+    <a href="https://github.com/OpenSourceAGI/dev-tools-starter-agent/commits/master/"><img src="https://img.shields.io/github/last-commit/OpenSourceAGI/dev-tools-starter-agent.svg" alt="GitHub last commit" /></a>
+    <br />
+    <img src="https://img.shields.io/badge/Bun-14151A?logo=bun&logoColor=white" alt="Bun" /> <img src="https://img.shields.io/badge/Tauri-24C8D8?logo=tauri&logoColor=white" alt="Tauri" /> <img src="https://img.shields.io/badge/Vitest-6E9F18?logo=vitest&logoColor=white" alt="Vitest" />
+</p>
+<!-- template-git-repo:badges:end -->
+
+<!-- skills:install:start -->
+**🤖 Agent skill** — `npx skills@latest add https://github.com/OpenSourceAGI/dev-tools-starter-agent --skill native-app-wrapper` ([what it covers](../../skills/native-app-wrapper/SKILL.md))
+<!-- skills:install:end -->
+
+# native-app-wrapper
+
+A [Tauri](https://tauri.app) shell that turns one JSON profile into a native desktop
+(Windows/macOS/Linux) and mobile (Android/iOS) app. It packages one of two things:
+
+- **A website** (`"mode": "remote"`) — a titled window that loads the site directly, plus the
+  OS-level plumbing a plain webview doesn't get for free: a real app icon on every platform, a
+  Google-OAuth-compatible login handoff, and a fullscreen toggle.
+- **A command-line tool** (`"mode": "local"`) — a bundled HTML frontend backed by the CLI itself,
+  shipped alongside the app binary as a [Tauri sidecar](https://v2.tauri.app/develop/sidecar/), so
+  the app runs with no Node, Python, or other runtime installed on the user's machine. See
+  [`docs/LOCAL_APPS.md`](docs/LOCAL_APPS.md).
+
+`packages/about-system-info/native` is a working example of the second kind — the `about-system`
+CLI shipped as an installable desktop app for all three desktop OSes.
+
+## What this is not
+
+Not a place for app-specific UI or logic. In remote mode the wrapped site provides all of that; in
+local mode the app's own `dist/` and its sidecar do. This package's job stops at: open a window,
+register the app's identity (icon, name, bundle id) with each OS, hand a browser-based OAuth login
+back to that window, and expose the bundled CLI's output to the bundled frontend. Anything more
+belongs in the app being wrapped.
+
+## Quick start
+
+Scaffold a copy of the wrapper for your own app:
+
+```bash
+cd packages/native-app-wrapper
+node bin/cli.js init ../../apps/my-app/native --profile-file ./my-app.json
+cd ../../apps/my-app/native
+npm install
+npm run dev
+```
+
+`init` copies the wrapper's sources into the target directory, gives that copy your profile as its
+only identity, regenerates the Tauri config and Rust constants from it, renames the crate, and
+draws a placeholder icon set so the copy builds immediately. It also leaves out what the profile
+doesn't use: a desktop-only profile gets no `android:build` script, an offline CLI app gets no
+guide to browser OAuth handoffs. Nothing links back to this package afterward — the copy is a
+standalone app you can commit next to the thing it wraps, and updating it later means copying the
+changed scripts across, not re-running `init` over your own `dist/`.
+
+To work on this package itself instead, `npm run dev` here opens a window on the untouched
+`profiles/example.json` (`https://example.com`), which is what the checked-in
+`src-tauri/tauri.conf.json` is generated from.
+
+## Layout
+
+```
+native-app-wrapper/
+├── bin/cli.js             # init / configure / icons
+├── profiles/              # one JSON file = one app identity (see profiles/README.md)
+│   └── example.json        #   the template, and this package's own default
+├── scripts/
+│   ├── profile.mjs                   # loads + validates a profile; one definition of the schema
+│   ├── configure.mjs                 # profile -> tauri.conf.json, generated_config.rs, remote.json
+│   ├── build-sidecar.mjs             # profile's sidecar.build -> src-tauri/binaries/<name>-<triple>
+│   ├── generate-icons.mjs            # profile's iconSource -> full src-tauri/icons/ set (Tauri CLI)
+│   ├── generate-placeholder-icons.mjs # draws a buildable icon set with no artwork and no deps
+│   └── lib/png.mjs                   # the PNG/ICO/ICNS writers that make the above possible
+├── src-tauri/
+│   ├── src/lib.rs          # window setup, deep-link OAuth handoff, sidecar bridge, fullscreen toggle
+│   ├── capabilities/       # Tauri's permission grants (default.json + a generated remote.json)
+│   ├── icons/              # generated; checked in so a fresh clone builds
+│   └── tauri.conf.json     # generated by configure
+├── assets/icon-source.png # the 1024px master `iconSource` points at by default
+├── dist/                  # the bundled frontend (a placeholder in remote mode; the app in local mode)
+└── docs/
+    ├── BUILDING.md         # local dev/build commands and release builds
+    ├── LOCAL_APPS.md       # packaging a CLI: the sidecar bridge and the bundled frontend
+    ├── OAUTH.md            # why login needs a system browser + deep link, and how it works here
+    ├── MOBILE.md           # Android/iOS host requirements and gen/android, gen/apple
+    └── APP_STORES.md       # Microsoft Store, Mac App Store, iOS App Store, Google Play
+```
+
+## Why generated config instead of a hand-edited `tauri.conf.json`
+
+An app's identity shows up in five places that must agree: the Tauri config, the Rust deep-link
+scheme, the Rust sidecar name, the remote capability's origin scope, and the icon set. Hand-editing
+means five chances to drift. `scripts/configure.mjs` writes all of them from the profile, so the
+profile is the only file anyone edits, and CI can assert the generated files still match it.
+
+## Why a window, not a bundled copy of a remote site
+
+In remote mode, `tauri.conf.json`'s main window points its `url` straight at the profile's site over
+HTTPS — there's no local copy of the app's UI to keep in sync with the real site
+(`build.frontendDist` still points at `dist/`, an unused placeholder Tauri's bundler requires to
+exist). The tradeoff: the app needs network access to be useful, same as opening the site in a
+browser tab would. Local mode is the opposite tradeoff — everything is bundled, nothing is fetched.

package/bin/cli.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+// native-app-wrapper CLI.
+//
+//   init <dir> [--profile <name> | --profile-file <path>]
+//       Copy this wrapper into <dir> as a self-contained app, configured for
+//       one profile. The copy owns its profile from then on — nothing links
+//       back here — which is the point: a wrapped app's identity, icons, and
+//       build docs live next to the thing being wrapped, not in this package.
+//
+//   configure [--profile <name>]
+//       Regenerate the Tauri config, Rust constants, and remote capability
+//       from a profile, in place. Run by the pre* npm scripts.
+//
+//   icons [--profile <name>]
+//       Draw the dependency-free placeholder icon set (see
+//       scripts/generate-placeholder-icons.mjs); `npm run icons` instead
+//       generates a real set from the profile's iconSource via the Tauri CLI.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { configure } from "../scripts/configure.mjs";
+import { generatePlaceholderIcons } from "../scripts/generate-placeholder-icons.mjs";
+import { loadProfile, resolveProfileName } from "../scripts/profile.mjs";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// What a scaffolded copy is made of. Generated artifacts (tauri.conf.json,
+// generated_config.rs, src-tauri/icons/) are deliberately absent: `init`
+// regenerates them for the new profile instead of copying this package's, so a
+// copy can never inherit another app's identity by accident. Cargo.lock is
+// absent for the same reason — it names this package's crate, and a copy that
+// inherited it would fail its first build on a package/lock mismatch.
+const SCAFFOLD_SOURCES = [
+  "bin",
+  "scripts",
+  "src-tauri/Cargo.toml",
+  "src-tauri/build.rs",
+  "src-tauri/src/lib.rs",
+  "src-tauri/src/main.rs",
+  "src-tauri/capabilities/default.json",
+  "dist",
+  ".gitignore",
+];
+
+// Which docs a copy gets depends on what its profile actually does — an
+// offline CLI app shipping a guide to browser OAuth handoffs is noise that
+// reads as unimplemented functionality.
+function docsFor(profile) {
+  const docs = ["docs/BUILDING.md", "docs/APP_STORES.md"];
+  if (profile.mode === "local") docs.push("docs/LOCAL_APPS.md");
+  if (profile.deepLinkScheme) docs.push("docs/OAUTH.md");
+  if (profile.android || profile.ios) docs.push("docs/MOBILE.md");
+  return docs;
+}
+
+// Same idea for the npm scripts: a desktop-only profile's package.json
+// shouldn't offer android:build.
+function scriptsFor(profile, template) {
+  const scripts = { ...template };
+  if (!profile.android && !profile.ios) {
+    for (const key of Object.keys(scripts)) {
+      if (/^(pre)?(android|ios):/.test(key)) delete scripts[key];
+    }
+  }
+  if (profile.sidecar) {
+    // The bundler fails outright when no sidecar binary exists for the target
+    // triple, so building it is part of running or building the app, not a
+    // step to remember.
+    scripts["build:sidecar"] = "node scripts/build-sidecar.mjs";
+    scripts.predev = "node bin/cli.js configure && node scripts/build-sidecar.mjs";
+    scripts["prebuild:desktop"] = "node bin/cli.js configure && node scripts/build-sidecar.mjs";
+  } else {
+    delete scripts["build:sidecar"];
+  }
+  delete scripts.init;
+  return scripts;
+}
+
+function flag(argv, name) {
+  const i = argv.indexOf(name);
+  if (i === -1) return undefined;
+  const value = argv[i + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${name} needs a value`);
+  return value;
+}
+
+function fail(message) {
+  console.error(`[native-app-wrapper] ${message}`);
+  process.exit(1);
+}
+
+function slug(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/** Splits argv into positionals and flags, treating `--profile`/`--profile-file` as value flags. */
+function positionals(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--profile" || argv[i] === "--profile-file") {
+      i++; // skip the flag's value
+    } else if (!argv[i].startsWith("--")) {
+      out.push(argv[i]);
+    }
+  }
+  return out;
+}
+
+function init(argv) {
+  const [targetArg] = positionals(argv);
+  if (!targetArg) fail("init needs a target directory: init <dir> [--profile-file <path>]");
+
+  const targetDir = path.resolve(process.cwd(), targetArg);
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0 && !argv.includes("--force")) {
+    fail(`${targetDir} already exists and is not empty — pass --force to overwrite its wrapper files`);
+  }
+
+  const profileFile = flag(argv, "--profile-file");
+  const profileName = profileFile
+    ? path.basename(profileFile).replace(/\.json$/, "")
+    : (flag(argv, "--profile") ?? "example");
+
+  if (!profileFile && !existsSync(path.join(packageRoot, "profiles", `${profileName}.json`))) {
+    fail(`no profile named "${profileName}" in ${path.join(packageRoot, "profiles")}`);
+  }
+
+  const stagedProfilePath = profileFile
+    ? path.resolve(process.cwd(), profileFile)
+    : path.join(packageRoot, "profiles", `${profileName}.json`);
+
+  mkdirSync(targetDir, { recursive: true });
+  for (const entry of SCAFFOLD_SOURCES) {
+    const from = path.join(packageRoot, entry);
+    if (!existsSync(from)) continue;
+    const to = path.join(targetDir, entry);
+    mkdirSync(path.dirname(to), { recursive: true });
+    cpSync(from, to, { recursive: true });
+  }
+
+  // The copy gets exactly one profile — its own — so its scripts resolve it
+  // with no --profile flag and no ambiguity about which app this tree is.
+  mkdirSync(path.join(targetDir, "profiles"), { recursive: true });
+  cpSync(stagedProfilePath, path.join(targetDir, "profiles", `${profileName}.json`));
+  cpSync(path.join(packageRoot, "profiles", "README.md"), path.join(targetDir, "profiles", "README.md"));
+
+  const profile = loadProfile(targetDir, profileName);
+
+  for (const doc of docsFor(profile)) {
+    const to = path.join(targetDir, doc);
+    mkdirSync(path.dirname(to), { recursive: true });
+    cpSync(path.join(packageRoot, doc), to);
+  }
+
+  // package.json is rewritten rather than copied: the copy is a distinct app
+  // with its own name and version, and it must not carry this package's.
+  const template = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+  writeFileSync(
+    path.join(targetDir, "package.json"),
+    `${JSON.stringify(
+      {
+        ...template,
+        name: `${slug(profile.appName)}-native`,
+        version: profile.version,
+        description: `${profile.appName} packaged as a native desktop app (scaffolded from native-app-wrapper)`,
+        private: true,
+        bin: undefined,
+        scripts: scriptsFor(profile, template.scripts),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  const { written } = configure(targetDir, profileName);
+  const icons = generatePlaceholderIcons(targetDir, {
+    background: ["#1e293b", "#0b1220"],
+    accent: "#f8fafc",
+    ...profile.placeholderIcon,
+  });
+
+  // src-tauri/Cargo.toml's crate name is what `tauri build` names the binary,
+  // so it has to follow the copy rather than stay "native-app-wrapper".
+  const crateName = `${slug(profile.appName)}-native`;
+  const cargoPath = path.join(targetDir, "src-tauri", "Cargo.toml");
+  writeFileSync(
+    cargoPath,
+    readFileSync(cargoPath, "utf8")
+      .replace(/^name = "native-app-wrapper"$/m, `name = "${crateName}"`)
+      .replace(/^name = "native_app_wrapper_lib"$/m, `name = "${crateName.replace(/-/g, "_")}_lib"`)
+      .replace(/^description = ".*"$/m, `description = "${profile.appName} packaged as a native app"`),
+    "utf8",
+  );
+  const mainPath = path.join(targetDir, "src-tauri", "src", "main.rs");
+  writeFileSync(
+    mainPath,
+    readFileSync(mainPath, "utf8").replace("native_app_wrapper_lib::run()", `${crateName.replace(/-/g, "_")}_lib::run()`),
+    "utf8",
+  );
+  const rel = path.relative(process.cwd(), targetDir) || ".";
+  console.log(`[native-app-wrapper] scaffolded ${profile.appName} into ${rel}/`);
+  for (const entry of written) console.log(`  wrote ${entry}`);
+  console.log(`  wrote ${icons.length} placeholder icons into src-tauri/icons/`);
+  console.log(`\nNext: cd ${rel} && npm install && npm run dev`);
+}
+
+const [command, ...argv] = process.argv.slice(2);
+
+try {
+  if (command === "init") {
+    init(argv);
+  } else if (command === "configure") {
+    const rootDir = packageRoot;
+    const { profile, written } = configure(rootDir, resolveProfileName(rootDir, argv));
+    const target = profile.mode === "remote" ? profile.url : "bundled dist/ frontend";
+    console.log(`[native-app-wrapper] configured "${profile.name}" (${profile.appName} -> ${target})`);
+    for (const entry of written) console.log(`  wrote ${entry}`);
+  } else if (command === "icons") {
+    const profile = loadProfile(packageRoot, resolveProfileName(packageRoot, argv));
+    const written = generatePlaceholderIcons(packageRoot, {
+      background: ["#1e293b", "#0b1220"],
+      accent: "#f8fafc",
+      ...profile.placeholderIcon,
+    });
+    console.log(`[native-app-wrapper] drew ${written.length} placeholder icons for "${profile.name}"`);
+  } else {
+    console.log(
+      [
+        "native-app-wrapper",
+        "",
+        "  init <dir> [--profile <name>] [--profile-file <path>] [--force]",
+        "      Copy this wrapper into <dir> as a standalone app for one profile.",
+        "",
+        "  configure [--profile <name>]",
+        "      Regenerate tauri.conf.json, the Rust constants, and the remote capability.",
+        "",
+        "  icons [--profile <name>]",
+        "      Draw the placeholder icon set (no dependencies, no artwork needed).",
+      ].join("\n"),
+    );
+    process.exit(command ? 1 : 0);
+  }
+} catch (error) {
+  fail(error.message);
+}

package/dist/index.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Loading…</title>
+    <style>
+      html, body { height: 100%; margin: 0; background: #0b1220; color: #d8d8d8; font-family: system-ui, sans-serif; }
+      body { display: flex; align-items: center; justify-content: center; }
+    </style>
+  </head>
+  <body>
+    <!--
+      In remote mode this file is never shown: the main window's `url` in
+      tauri.conf.json points straight at the configured site. Tauri's bundler
+      still requires `build.frontendDist` to point at a real, non-empty
+      directory, and this doubles as the offline fallback content a future
+      retry/offline screen can build on.
+
+      In local mode this directory IS the app — replace this file with the
+      frontend you want bundled. See ../docs/LOCAL_APPS.md.
+    -->
+    <p>Loading…</p>
+  </body>
+</html>

package/docs/APP_STORES.md

@@ -0,0 +1,129 @@
+# Submitting to app stores
+
+This covers what each store needs beyond the installers `npm run build:desktop` (or a CI matrix
+like the one in `BUILDING.md`) already produces.
+None of this is automated — every store below needs an account, credentials only a human on that
+account can provision, and (for Apple) manual review — so treat this as a checklist, not a script.
+
+## Microsoft Store (Windows)
+
+Tauri does not build MSIX — it only produces the `.exe` (NSIS) and `.msi` (WiX) installers
+`build:desktop` already produces. The Microsoft Store submission type for that is an **"EXE or MSI
+app"**: the Store hosts a listing that links to your own signed installer rather than a sandboxed
+MSIX package.
+
+1. Build with a Store-specific config overlay that forces the offline WebView2 installer (Store
+   review rejects the online/evergreen bootstrapper) and code-sign the installer:
+   ```jsonc
+   // tauri.microsoftstore.conf.json (create this file, merged over tauri.conf.json)
+   { "bundle": { "windows": { "webviewInstallMode": { "type": "offlineInstaller" } } } }
+   ```
+   ```bash
+   npx tauri build --config tauri.microsoftstore.conf.json
+   ```
+2. In [Partner Center](https://partner.microsoft.com/dashboard), register the app under
+   **Apps and Games → EXE or MSI app**, using a **Publisher name distinct from the product name**
+   (Store review flags the two matching exactly), and supply the installer's silent-install flag
+   (NSIS's `/S`, applied automatically by Tauri's installer).
+3. Submit for certification. Because the Store links to an external installer, your own
+   update mechanism (Tauri's updater, once enabled — see `BUILDING.md`) is what actually
+   updates users; the Store doesn't auto-update this install type the way it would a native MSIX.
+
+A true sandboxed MSIX is possible but needs a separate third-party packaging step on top of
+Tauri's own bundler (e.g. the community `@choochmeque/tauri-windows-bundle` tool) — not something
+this wrapper sets up by default.
+
+## Mac App Store
+
+Distinct from notarized-`.dmg` distribution outside the Store (which uses a Developer ID cert and
+`notarytool`) — App Store distribution needs a **3rd Party Mac Developer Application** cert, a
+**3rd Party Mac Developer Installer** cert, **App Sandbox entitlements**, and upload as a signed
+`.pkg`, not a `.dmg`.
+
+1. `src-tauri/Entitlements.plist` (create this; not generated by `configure`) needs at least:
+   ```xml
+   <?xml version="1.0" encoding="UTF-8"?>
+   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+   <plist version="1.0">
+   <dict>
+       <key>com.apple.security.app-sandbox</key><true/>
+       <key>com.apple.security.network.client</key><true/>
+       <!-- Tauri's webview needs JIT; omitting this is a documented cause of
+            crash-on-launch after notarization. -->
+       <key>com.apple.security.cs.allow-jit</key><true/>
+       <key>com.apple.application-identifier</key><string>$TEAM_ID.$IDENTIFIER</string>
+       <key>com.apple.developer.team-identifier</key><string>$TEAM_ID</string>
+   </dict>
+   </plist>
+   ```
+   and reference it from `tauri.conf.json`'s `bundle.macOS.entitlements`.
+2. Build, sign, and upload:
+   ```bash
+   npx tauri build --bundles app --target universal-apple-darwin
+   xcrun productbuild --sign "3rd Party Mac Developer Installer: <Your Team> (TEAMID)" \
+     --component "src-tauri/target/universal-apple-darwin/release/bundle/macos/<Product Name>.app" \
+     /Applications <Product>.pkg
+   xcrun altool --upload-app --type macos --file <Product>.pkg \
+     --apiKey "$APPLE_API_KEY_ID" --apiIssuer "$APPLE_API_ISSUER"
+   ```
+   (Apple has been steering uploads toward the newer Transporter CLI / `notarytool`-adjacent
+   tooling; verify `altool`'s status against Apple's current documentation before relying on it.)
+3. In [App Store Connect](https://appstoreconnect.apple.com), register the app with a Bundle ID
+   matching `tauri.conf.json`'s `identifier` exactly, create a **Mac App Store** provisioning
+   profile (distinct from a Developer ID profile), and generate an API key (`.p8`) for CI/CLI
+   auth.
+
+## iOS App Store
+
+1. Build a signed `.ipa`: `npm run ios:build -- --export-method app-store-connect` (needs a
+   distribution certificate + provisioning profile configured in the generated Xcode project
+   first — see `MOBILE.md`). Output lands at
+   `src-tauri/gen/apple/build/arm64/*.ipa`.
+2. Upload the same way as macOS: `xcrun altool --upload-app --type ios --file *.ipa --apiKey ... --apiIssuer ...`,
+   or drag it into Xcode Organizer / the Transporter app. It lands in App Store Connect →
+   **TestFlight** automatically — internal testers get it immediately, external testers need a
+   lightweight Beta App Review first.
+3. **Read this before investing in an iOS submission**: Apple's App Store Review Guideline
+   **4.2 "Minimum Functionality"** is a real rejection risk for an app that's essentially "load a
+   website in a webview" with no native chrome —
+   > "Your app should include features, content, and UI that elevate it beyond a repackaged
+   > website... Other than catalogs, apps shouldn't primarily be marketing materials,
+   > advertisements, web clippings, content aggregators, or a collection of links."
+   ([developer.apple.com/app-store/review/guidelines](https://developer.apple.com/app-store/review/guidelines/), §4.2)
+
+   iOS reviewers test submissions manually and are noticeably stricter here than Android or
+   desktop review. To materially reduce rejection risk before submitting, this app needs to be
+   more than a URL in a box: native navigation chrome (a real tab bar / back gesture, not just
+   in-page nav), push notifications wired to APNs, a native offline-state screen instead of a
+   blank WebView on connectivity loss — enough that the app doesn't read as "open Safari to this
+   URL." This is a product/design decision for whoever owns the app, not a packaging setting —
+   flag it before committing engineering time to an iOS submission specifically.
+
+## Google Play Store (Android)
+
+1. **Format**: Google requires the **Android App Bundle** (`.aab`, not a plain `.apk`) for new
+   apps — `npm run android:build` produces one; a CI Android job can build it (see `MOBILE.md`).
+2. **Play App Signing** is mandatory for new apps on AAB: Google holds the app signing key, you
+   keep only an upload key. Enroll during your first release in
+   [Play Console](https://play.google.com/console).
+3. **Target API level** (current requirements as of this writing):
+   - New apps/updates must target **Android 16 (API 36)** by **August 31, 2026** (extension to
+     November 1, 2026 available on request in Play Console). The profile's
+     `android.minSdkVersion` is the *minimum* supported OS, unrelated to the *target* level —
+     set the target via `gen/android`'s Gradle config once you run `android:init`.
+   - Existing published apps need at least **API 35** to stay visible to users on newer Android
+     versions.
+   - Build with **NDK r28+** (see `MOBILE.md`) — Play now requires 16KB-page-aligned native
+     libraries for new apps/updates targeting recent devices, which NDK ≥28 produces automatically.
+4. Submission flow: create the app listing, enable Play App Signing, upload the signed `.aab` to
+   an internal/closed testing track first, complete the **Data Safety** form and content-rating
+   questionnaire (a remote-mode app relays OAuth data through its login handoff, and a local-mode app may read
+   system state — describe whichever applies accurately), then promote to production. Play has no equivalent to Apple's 4.2 guideline
+   strictly enforced against webview wrappers.
+
+## GitHub Releases (no store at all)
+
+The default, and what `BUILDING.md`'s CI matrix produces: desktop installers attach directly to a
+GitHub Release. No review process, no developer-account fees, works today — the tradeoff is no store discoverability and users see an
+"unidentified developer" / SmartScreen warning on first launch unless the signing secrets above
+are configured.

package/docs/BUILDING.md

@@ -0,0 +1,134 @@
+# Building
+
+Every command below is run from the app directory — either this package (which builds
+`profiles/example.json` as a smoke test) or a copy `node bin/cli.js init` scaffolded elsewhere.
+
+## Prerequisites
+
+Tauri compiles a Rust binary against the host's native webview, so each OS needs its own toolchain
+before anything here works. From [Tauri's prerequisites guide](https://v2.tauri.app/start/prerequisites/):
+
+| Host | Needs |
+|---|---|
+| **Windows** | [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (Desktop development with C++), WebView2 (preinstalled on Windows 10 1803+/11), and Rust. |
+| **macOS** | Xcode Command Line Tools (`xcode-select --install`) and Rust. |
+| **Linux** | `libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev build-essential curl wget file libssl-dev` (Debian/Ubuntu names; see the guide for Fedora/Arch), and Rust. |
+
+Plus [Rust](https://rustup.rs) 1.77.2 or newer and Node 18+ everywhere.
+
+## Local dev
+
+```bash
+npm install
+npm run dev
+```
+
+`predev` regenerates the Tauri config from the profile first, so a profile edit takes effect
+without a separate step. In remote mode the window opens on the profile's `url` — there's no local
+frontend to serve, so a dev server for the wrapped site is unrelated (to test against one, point
+the profile's `url` at `http://localhost:3000` temporarily, re-run `npm run configure`, and don't
+commit that change). In local mode the window opens on `dist/`.
+
+## Release build
+
+```bash
+npm run build:desktop
+```
+
+Output lands under `src-tauri/target/release/bundle/`:
+
+| Platform | Artifacts |
+|---|---|
+| Windows | `msi/*.msi` (WiX), `nsis/*-setup.exe` |
+| macOS | `dmg/*.dmg`, `macos/*.app` |
+| Linux | `deb/*.deb`, `rpm/*.rpm`, `appimage/*.AppImage` |
+
+**Each installer must be built on its own OS.** Tauri does not cross-compile: a Windows `.msi`
+needs a Windows host, a `.dmg` needs macOS. That's what makes a CI matrix (below) the normal way to
+produce a full set.
+
+macOS builds default to the host's architecture; add `--target universal-apple-darwin` (and
+`rustup target add x86_64-apple-darwin aarch64-apple-darwin`) for a universal binary that runs on
+both Intel and Apple Silicon.
+
+If the profile bundles a sidecar, build it **before** `build:desktop` — the bundle step fails
+outright when no binary exists for the target triple. See `LOCAL_APPS.md`.
+
+## Android / iOS
+
+See `MOBILE.md` — needs host tooling this package can't install for you. Sidecars are desktop-only,
+so a local-mode app with a `sidecar` has no mobile story; a remote-mode app does.
+
+## CI
+
+Building for three OSes means three runners. The shape that works:
+
+```yaml
+strategy:
+  matrix:
+    include:
+      - { os: windows-latest, args: "" }
+      - { os: macos-latest,   args: "--target universal-apple-darwin" }
+      - { os: ubuntu-22.04,   args: "" }
+runs-on: ${{ matrix.os }}
+steps:
+  # ... checkout, node, rust, and the Linux apt packages from the table above ...
+  - uses: tauri-apps/tauri-action@v0
+    with:
+      projectPath: <path to the app directory>
+      args: ${{ matrix.args }}
+```
+
+[`tauri-apps/tauri-action`](https://github.com/tauri-apps/tauri-action) handles the build and can
+attach the artifacts to a GitHub Release. `packages/about-system-info`'s
+`.github/workflows/about-system-desktop.yml` is a complete working instance of this, including the
+sidecar build step that has to run first.
+
+Worth asserting in CI: that `src-tauri/tauri.conf.json` and `src-tauri/src/generated_config.rs`
+still match what `configure` produces from the profile. Re-running configure and checking
+`git diff --exit-code` catches hand-edits that have drifted from the profile they're generated
+from.
+
+## Code signing
+
+Unsigned installers work, but users get an "unidentified developer" (macOS) or SmartScreen
+(Windows) warning on first launch. `tauri-action` picks up signing automatically once the relevant
+secrets exist:
+
+- **macOS**: `APPLE_CERTIFICATE`, `APPLE_CERTIFICATE_PASSWORD`, `APPLE_SIGNING_IDENTITY`, and for
+  notarization `APPLE_ID` + `APPLE_PASSWORD` + `APPLE_TEAM_ID` (or `APPLE_API_KEY`,
+  `APPLE_API_ISSUER`, `APPLE_API_KEY_PATH`).
+- **Windows**: an Authenticode certificate, configured through `bundle.windows.certificateThumbprint`
+  or a signing command.
+
+See `APP_STORES.md` for where those credentials come from.
+
+## Auto-update (off by default)
+
+`tauri-plugin-updater` is in `Cargo.toml`, but a profile with no `updater` block never registers
+it and `tauri.conf.json` gets no `plugins.updater` section. That is not the same as switching it
+off with `"active": false` — the plugin reads `pubkey` during *initialization* and panics if it
+isn't there, so an inert-looking config block is a crash on launch, not a disabled feature.
+
+To turn updates on:
+
+1. `npx @tauri-apps/cli@2 signer generate` — keep the private key, note the public key.
+2. Add to the profile:
+   ```json
+   "updater": {
+     "pubkey": "<the public key>",
+     "endpoints": ["https://github.com/<owner>/<repo>/releases/latest/download/latest.json"]
+   }
+   ```
+   and re-run `configure`. (Both fields are required; the profile validator rejects one without
+   the other.)
+3. Store the private key as a `TAURI_SIGNING_PRIVATE_KEY` secret, and its password as
+   `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` if you set one.
+4. Set `tauri-action`'s `includeUpdaterJson: true` so releases carry the `latest.json` manifest
+   the updater polls.
+
+## Cutting a release
+
+Bump `version` in the profile, run `npm run configure`, commit, then tag. The version in
+`tauri.conf.json` is what ends up in the installer's metadata and in every store listing, so the
+profile is the single place it's set.