For the implemented Go session/account integration, follow Go native setup. It documents backend startup, registration, native endpoint/credential selection and actual integration checks.
The SwiftUI iOS app, Compose Android app, and native kernel, HTTP, services, query, UI and graphics packages/modules are initialized. Do not rerun project initialization commands in these existing directories.
This machine has Xcode 26.2, Swift 6.2.3, Android Studio, the Android SDK, and
XcodeGen 2.46.0. On a new Mac, install Xcode and Android Studio, select Xcode's
command-line tools, and install XcodeGen with brew install xcodegen.
Run from the repository root:
cd /Users/sj/Desktop/dev/builds/mobile-foundry
make kernel-build
make kernel-test
make http-test
make query-test
make ui-test
make graphics-test
make ios-build
make ios-test
make android-build
make android-test
make notes-checknotes-check uses Python 3 to check documentation links, mirrored module-note
directories, and native example labels. Follow the learning workflow
for reading orders and execution of complete examples.
The Android shortcuts default to Android Studio's bundled JDK and the SDK at
$HOME/Library/Android/sdk. Override them when your installation differs:
make android-build FOUNDRY_ANDROID_JAVA_HOME="/path/to/jdk" \
FOUNDRY_ANDROID_SDK="/path/to/android-sdk"The separate Daily entries are Swift ProductApp and Kotlin product. They use shared UI/Query/Kernel without catalog features. From the repository root:
make product-ios-generate
make product-ios-build
make product-ios-test
make product-android-build
make product-android-ui-test
make starter-checkiOS checks use the configured simulator; Android interaction checks require an attached emulator/device. The existing Java/SDK and iOS destination overrides apply. Each app README gives commands from its own folder and the branding edits. The Swift product has a blank signing team and needs an AppIcon before distribution. The Kotlin product has a vector launcher placeholder and no release signing configuration. To copy a new product, use the local CLI below.
From this repository root:
make cli-install
export PATH="$HOME/.local/bin:$PATH"
mobile-foundry listThen, from an existing output parent outside this checkout:
mobile-foundry doctor --platform both
mobile-foundry init canopy --platform both --app-id com.example.canopy
cd canopy
make helpUse --platform swift or kotlin to select one app, and --display-name for
branding. Add --with local-data for the persistent Library Notes example,
CRUD, observation and local Services/Data modules. Omit it for empty UI screens.
Output is PARENT/NAME; an existing destination is refused. Follow its
own SETUP.md for builds/tests. Python 3.11+ runs the generator; initialization
does not download dependencies. Add --backend go for an independent API, or use
--platform none --backend go for API-only output. --go-module selects its import
identity. Read Go starter setup.
Read CLI usage and readiness for scope.
Build the initialized package directly:
cd /Users/sj/Desktop/dev/builds/mobile-foundry/frontend/swift/packages/FoundryKernel
swift buildThe kernel implements outcomes and failures. HTTP and services are initialized
local packages too; do not rerun swift package init in their directories.
cd /Users/sj/Desktop/dev/builds/mobile-foundry/frontend/swift/packages/FoundryHTTP
swift test
cd ../FoundryServices
swift testUse make http-test at the repository root to run both platforms' HTTP and
health checks. See Organization for reserved future capabilities.
Open the initialized project:
cd /Users/sj/Desktop/dev/builds/mobile-foundry/frontend/swift/apps/FoundryCatalog
open FoundryCatalog.xcodeprojSelect the shared FoundryCatalog scheme and an iOS simulator in Xcode, then
run the app. Simulator runs do not require an Apple development team. For a
physical device, select the FoundryCatalog app target → Signing & Capabilities,
enable Automatically manage signing, and choose your Team. TestFlight requires
a team enrolled in the Apple Developer Program. See Apple's
device setup
and distribution setup.
Keep any chosen DEVELOPMENT_TEAM value in the app target's settings in
project.yml so regeneration preserves it. This working catalog records the
team selected locally in Xcode; choose your own team when reusing the blueprint.
If Xcode still shows an earlier signing error with a simulator selected, run
again and inspect the latest result before changing signing settings.
Select HTTP health in the Foundation list to try the injected scenarios. Select Notes service seam to run the same list screen against memory or an HTTP adapter with injected responses. Select Async UI patterns to explore generic loading, retained content/empty, failure, retry, and cancellation presentation. Select Tokens to inspect the V1 roles and scales. Its appearance and reduced-motion controls preview a scoped theme while keeping the catalog controls outside it.
The app links local FoundryKernel, FoundryHTTP, FoundryServices,
FoundryQuery, FoundryUI, and FoundryGraphics packages. Its initial deployment
target is iOS 17 and its bundle identifier is dev.mobilefoundry.catalog.
The asset catalog contains accent color and app icon metadata; add icon artwork
when the app's visual identity is defined.
project.yml owns the Xcode project configuration. After changing targets,
package dependencies, or build settings, regenerate from the repository root:
make ios-generateKeep the generated .xcodeproj and shared scheme versioned so a checkout can
open in Xcode directly. See XcodeGen project configuration.
The generated Info.plist declares portrait and both landscape orientations for
iPhone and all four orientations for iPad multitasking. Keep these settings in
project.yml; changing them does not update an existing archive. After a
distribution metadata fix, create a new archive with Product → Archive and
distribute that new entry from Organizer.
To build directly from the application's directory:
xcodebuild -project FoundryCatalog.xcodeproj -scheme FoundryCatalog \
-destination 'generic/platform=iOS Simulator' \
-derivedDataPath ../../../../.cache/ios \
-configuration Debug CODE_SIGNING_ALLOWED=NO -quiet buildThe simulator application is written to
.cache/ios/Build/Products/Debug-iphonesimulator/FoundryCatalog.app under the
repository root.
make ios-test runs the catalog's store tests on iPhone 17 Pro by default.
Choose another installed simulator with
make ios-test FOUNDRY_IOS_TEST_DESTINATION='platform=iOS Simulator,name=YOUR_DEVICE'.
The unit-test target is defined in project.yml and the shared scheme.
Open the Gradle project in Android Studio:
cd /Users/sj/Desktop/dev/builds/mobile-foundry/frontend/kotlin/project
open -a "Android Studio" .Select the app run configuration and an emulator or connected device. The
app retains the generated starter and adds HTTP health, Notes service seam, and
Async UI patterns, Tokens, Forms and mutations, and GPU effects destinations.
Catalog scenarios need no backend. The app already depends on
the Kotlin/JVM module :core:kernel, which implements typed outcomes and failures.
For direct terminal builds on this Mac:
export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
export ANDROID_HOME="$HOME/Library/Android/sdk"
./gradlew :core:kernel:build :core:http:build :core:services:build :core:query:build :core:ui:assembleDebug :core:graphics:assembleDebug :app:assembleDebug
./gradlew :core:kernel:test :core:http:test :core:services:test :core:query:test :core:ui:testDebugUnitTest :core:graphics:testDebugUnitTest :app:testDebugUnitTestThe wrapper uses Gradle 9.1.0. The version catalog pins Android Gradle Plugin 9.0.1, Kotlin 2.3.20, and Compose BOM 2026.03.01. Modules use a Java 17 toolchain. The app's minimum SDK is API 24, and its compile and target SDK are API 36. Review these baselines when selecting graphics capabilities.
The debug APK is app/build/outputs/apk/debug/app-debug.apk. Starter unit tests
can run on the host; instrumented UI tests require an emulator or device and
use make android-ui-test with a booted emulator or connected device.
The original generator command is retained here for reference. Use it only for
a new absent or empty project directory, not the initialized project folder:
android create --name=FoundryCatalog \
--application-id=dev.mobilefoundry.catalog \
--namespace=dev.mobilefoundry.catalog \
--output=./projectSee Android project creation commands and Compose setup.
From the repository root:
make kernel-testThis runs Swift package tests and Kotlin kernel host tests. Both read the
canonical failure fixtures from contracts/fixtures/kernel; the runtime
libraries do not load files from the checkout. make android-test also includes
all Kotlin core tests alongside the starter app tests. See
the kernel contract and each platform's
notebook for examples and evidence limits.
Open Image studio in either catalog. Drag in Compare mode to move the original/edited divider; change exposure, saturation and vignette, then choose Move image to pan or pinch to zoom. Original/Edited, Zoom and Reset controls provide native alternatives. Open Product studio to orbit/pinch the lamp, choose Porcelain/Cobalt/Bronze, reset the camera or enable Turntable. Reduce motion suppresses the turntable while controls still redraw a static scene.
Canonical assets and provenance are described in assets.
Run make assets-sync after changing the authored model or source photograph,
then make assets-check. Regenerate the iOS project after adding resource files.
The reusable graphics modules accept admitted data instead of catalog paths.
Import/export, general model loading, saved edits and backend assets are future
slices. The small internal triangle JSON is not glTF.
make graphics-test now includes five value/policy checks per native platform
and two actual Metal execution checks. make ios-test hosts both previews to
verify drawable sizing/static updates/removal. make android-ui-test reads real
surface pixels and exercises image tools, product material/camera/pinch, quality,
motion reduction, context recreation and navigation. These are simulator/emulator
checks; physical-device frame-time and thermal profiling remain open.
Open Compositor studio in either catalog. The photograph and transparent code-authored disc/ring load locally. Select Layer, Mask or Compare before dragging; pinch scales the layer. All edits also have labeled native sliders. Try Multiply and Screen, mask off/on, feather, blur and glow, Original/Composed, then Reset composition. Comparison 0 is fully composed; 1 is original.
Balanced/Economy change target resolution and submission budget. Profile redraws is opt-in; Reduce motion preview pauses it while static edits remain available. Background/removal stops repeated work. Profiles show four passes, upload/target allocation counts, estimated texture payload and CPU encode duration. Metal can supply a completed GPU interval; GLES 2 explicitly reports unavailable. These numbers are not displayed FPS or measured total VRAM.
The graphics-test target includes seven graphics value checks per platform and three actual Metal render checks. The ios-test target includes hosted compositor sizing, cache/resize/profile/removal checks; android-ui-test includes real pixels, controls/gestures/reset, profile/cache/resize, context recreation and reopening. Read the contract, learning notes, and device protocol. Import/export, arbitrary layer stacks, HDR and sustained physical-device budgets remain separate capabilities.
Open GPU effects in either catalog. Drag Ripple to move the wave center; select Orbit to steer a lit sphere and ring. Change strength or Economy/Balanced, disable Animate, then interact again. Reduce motion preview keeps animation paused even with Animate enabled. Reset focus centers touch without resetting time. Background/resume and Back/reopen exercise native resource lifetime. No backend, external assets or credentials are required.
The Effect menu/chips also expose Flow, Material, Liquid, Particles and Field. Drag Flow/Material to steer ribbons/reflection. Liquid has a supplied-progress slider and Empty/Half/Full. Particles has a playhead scrubber and Replay celebration: one finite 2.4-second burst, paused by motion/lifecycle controls. Replay is disabled with reduced motion; explicit scrubbing still works. Field starts with illustrative samples; try Clusters/Trail, Clear data, drag to set the focus, then Add at focus (maximum twelve). Field redraws on input changes and does not animate invented data. Progress/sample/playhead captions provide native text alternatives alongside the visual canvas.
make graphics-test runs shared policy/content tests and native
offscreen Metal shader/pixel checks on a Metal-capable Mac. Metal tests explicitly
skips when no Metal device is available. make ios-test adds a hosted canvas
dimension, automatic drawing, paused quality, resume and disposal check.
make android-ui-test checks actual GL surface pixels, controls, quality,
context recreation and removal on a booted emulator/device.
The iOS adapter uses Metal/MTKView; Android uses OpenGL ES 2/GLSurfaceView at the existing API 24 floor. Shader text is bundled and compiled once per attachment or recreated context. No new third-party engine is installed. Counters report submissions and target pixels, not displayed FPS or GPU time. Profile physical devices before selecting sustained performance targets. Read the contract and learning handoff. Read graphics inputs and event time to reuse these use cases with real feature data.
make http-test runs Swift HTTP/services and Kotlin HTTP/services host tests.
Both use the canonical JSON cases under contracts/fixtures/http; native
adapter tests additionally exercise cancellation, redirects and interrupted
bodies. Swift loopback tests and Kotlin MockWebServer require local test sockets.
Both catalogs offer Healthy, Unavailable, Malformed, Validation, Rate limited, and Timeout. Run again repeats the selected scenario. No backend or credentials are needed. The native transport implementations can be injected into a future connected workflow; the catalog uses deliberate fixtures.
make android-ui-testThis device-dependent target exercises Compose scenarios and request replacement. See the HTTP contract and learning notes for ownership and evidence limits.
Notes service seam offers Memory/HTTP and Content/Empty/Unavailable/Slow. The HTTP option still uses the real HTTP client and notes response admission, with catalog-only wire responses. Refresh keeps prior content while loading; Cancel loading stops owned work. The list renderer receives domain state and callbacks and constructs no service.
make http-test includes both platforms' notes service tests against shared
fixtures. make ios-test and make android-test exercise the store/ViewModel;
make android-ui-test also exercises provider switching and notes states.
See the notes/query contract. No backend,
provider account, persistent storage or credentials are needed for this example.
make query-test runs Swift and Kotlin pure query-state tests against
contracts/fixtures/query. make ios-test and make android-test retain the
notes state-owner regression checks. make android-ui-test also checks the
generic presentation matrix, callback routing, and gallery navigation.
Open Async UI patterns in either catalog to choose idle, initial loading, content, empty, refresh/failure retaining either snapshot, or internal failure. Refresh/Retry enters loading; Cancel restores content or idle. This gallery manually selects states and performs no service calls. Notes service seam exercises the same reusable UI with real feature-owned request lifetime. See the query/UI contract.
make ui-test runs Swift FoundryUI and Kotlin core/ui token tests against the
shared V1 light/dark palette and scales. make android-test also includes the
Kotlin suite. make android-ui-test checks nested themes, Material mapping,
font scaling, minimum touch bounds, catalog controls, and preserved sample state.
Open Tokens and choose System, Light, or Dark; System follows the surrounding theme. Turn on Reduce motion preview and scroll to Motion: durations become 0 / 0 / 0 ms, and Toggle position still changes the endpoint. The preview flag can request reduction but cannot override an operating-system request. Native widgets retain their own animation policy. Primary/Secondary action increments the counter, which survives appearance changes.
On the catalog home, enable Glass surfaces, then open Tokens. Surface theme defaults to App theme; choose Solid or Glass for a local comparison. Move scene changes the backdrop, Select object increments the count, and Reduce transparency preview makes the floating panel opaque while retaining the selected style. The scene and count survive theme changes. Swift additionally respects system Reduce Transparency. Android requires API 31+ for backdrop blur and falls back to a solid surface on older supported versions. These choices last for the catalog session; there is no saved cross-launch theme preference in this slice.
The deterministic Foundry Studio V1 preset uses porcelain/graphite surfaces and cobalt accents; it does not select Android wallpaper colors. The app theme delegates to the reusable FoundryTheme. Follow Styles for the token/preset/theme/component split and the contract for current behavior. Forms and mutation state remain subsequent slices.
The profiles are independent. Start whichever one the current experiment uses. Docker Desktop must be running for the two Compose profiles.
cd backend/go
AUTH_MODE=identity make devThe working API has Identity, Account, Audit and Notes with memory/PostgreSQL providers. Its go.mod is already initialized. Use the CLI to select an independent copy and its own module path; see Go starter setup and Go layout.
Supabase requires OpenSSL and Node.js on the host for one-time key generation:
cd /Users/sj/Desktop/dev/builds/mobile-foundry/backend/supabase
make up
make status
make downThe first setup generates an ignored .env. Studio and the API use
http://localhost:56321; email capture uses http://localhost:56324.
Read Supabase setup for credentials and ports.
Firebase builds its CLI and Java runtime into the emulator image:
cd /Users/sj/Desktop/dev/builds/mobile-foundry/backend/firebase
make up
make status
make downThe emulator UI uses http://localhost:4000. Auth, Firestore, and Storage use
9099, 8080, and 9199. make down allows graceful export; the next start imports
the retained data volume. Read Firebase setup
before connecting SDKs; the initial data rules deny client access.
For native connections, iOS Simulator uses 127.0.0.1, and Android Emulator
uses 10.0.2.2. Physical devices need a reachable host address and an explicit
bind change. Native SDK adapters and development-only network settings will
be added with the connected workflow.
Open Forms and mutations in either native app. No backend is required; Memory uses an instance-local store and HTTP injects wire responses through the real client/service admission path. The notes domain is an example.
- Submit an empty title: the required error appears and Title receives focus.
- Enter a title, change provider, and confirm the draft stays present. Use the keyboard Done/Return or Create note; both share guarded admission.
- Choose Field error and submit. The draft remains with a server title error. Editing clears server feedback and revalidates the touched field.
- Choose Unavailable, Timeout or Malformed and submit to inspect public feedback and missing-confirmation copy. Switch back to Success to recover.
- Choose Slow and submit. Field, submit, reset and provider/scenario controls disable during the attempt. After confirmation, New note resets the form.
- Leave during Slow, reopen, and confirm a new form remains usable. Screen exit suppresses old results; it does not promise a remote rollback.
Try the home Glass surfaces switch: the form's outer panels adopt glass over a subtle cobalt backdrop. Solid returns them to opaque surfaces; transparency reduction and unsupported blur also retain an opaque fallback. The write gallery does not update the separate Notes service seam gallery; read/write composition and persistence are later capabilities. There is no automatic retry or server idempotency guarantee.
make http-test includes command/provider fixtures; make query-test includes
mutation values. make ios-test and make android-test cover feature execution;
make android-ui-test covers actual Compose fields/IME/feedback. See
the contract and
learning handoff.
Open Studio → Open catalog → Local notes. Device storage is the default; Memory uses the same CRUD screen with transient records. Try creating/editing, canceling then confirming deletion, closing the route and relaunching the app.
make data-test
make data-ui-test # Android device/emulator required
make ios-test # iOS simulator required; includes the consumer checksSee construction and seam usage and native reading step 41. These commands exercise files/state/UI, not backend or sync behavior.
Open Studio → Open catalog → Identity and session. Device is the default.
Use alex@example.test or sam@example.test and password catalog-demo.
Sign in, close/reopen the gallery to restore, advance the manual clock by 61
seconds, renew, reject renewal and sign out. Memory discards its saved session
when the source/screen is replaced. Password drafts clear after submission/exit.
These fixture accounts do not authenticate a person or authorize Local notes.
make session-test
make session-ui-test # Android device/emulator required
make ios-test # includes actual isolated Keychain checksThe iOS simulator build/test targets use local ad-hoc signing (CODE_SIGN_IDENTITY=-).
That enables actual Keychain checks without changing distribution signing settings.
Read construction, behavior and native notebook step 42. A real authority and remote account data authorization require the next connected slice.
Open Studio → Open catalog → Live notes. Create, edit and delete a note while watching both readers. Pause the second, write again, then resume it. Device storage uses a dedicated SQLite collection; Memory lasts for the route and survives storage switches/configuration changes. Leaving the route discards it. Identity and session also shows a current-account live reader after sign-in.
make observation-test
make observation-ui-test # Android emulator/device required
make ios-generate
make ios-test # hosted reader/state-owner checksRead behavior, construction and native reading step 44. Notifications cover repository commits in this process; explicit restart or foreground resume reads current storage. This does not connect a backend.
The same Identity and session gallery now includes Account notes and an Authenticated HTTP probe while access is active. Sign in as Alex, create a note, leave an unsaved draft, then sign in as Sam. Sam has a separate collection and an empty editor. Return to Alex to reload its saved note. Advance time to close the editor, then renew to reopen it. Signing out retains Device account records; Memory retains them only until its source/gallery closes. Guest Local notes stay separate. Source selection controls credentials and account Notes together.
The probe offers Success, Unauthorized and Slow response. It uses a local wire fixture, with no network/server connection. Unauthorized is one failure and does not renew or replay automatically. Closing a lease removes its probe report.
make account-test
make ios-test
make account-ui-test # Android device/emulator requiredRead account construction, behavior and native notebook step 43. AuthenticatedHTTPClient accepts the native URLSession/OkHttp transport for a future provider. HTTPS is required by default; allowLocalHTTP explicitly permits loopback development only. This batch adds no backend/provider or remote sync.
Open Studio → Open catalog → Product shells on either native app. Choose Daily app, Workspace, Browse and collect, Canvas studio or Guided setup. Use Glass to change material; Back to shells returns to the chooser while retaining each profile's local state. Closing the whole gallery discards its fixture state.
Daily check-ins belong to their selected tab. Workspace opens project details, supports completion and shows both panes at sufficient available width. Browse filters local collections and saves them in the preview. Canvas lets you change its title/tool, add up to eight layers and count preview exports. Setup retains name/focus through back/review and clears both with Start again. These are local interactions; the canvas example does not export a file.
make ios-generate
make ios-build
make ios-test
cd frontend/kotlin/project
./gradlew :app:testDebugUnitTest
cd ../../..
make shell-ui-test # Android emulator/device requiredUse the configured JDK/SDK environment from the Android setup instructions for the direct Gradle command. Read behavior, construction and native notebook step 45.
For a separate product, use the local CLI from a directory
outside this checkout. Daily is the default; choose --profile native-workspace
for adaptive project navigation or --profile native-browse for search/detail.
Both support --platform swift, kotlin or both and a Solid/Glass header.
Their generated SETUP/Makefile includes only the selected platform commands and
shell checks. Local-data remains an optional Daily combination. Read
shell starter behavior and native
reading step 49 for ownership, verification and customization.
Run Git commands from mobile-foundry, keeping both platforms and shared
contracts in one repository. Keep native project files, dependency locks,
Gradle wrapper files, and fixture inputs versioned. Local SDK paths,
credentials, build output, and IDE user state are covered by the root
.gitignore.