0.2.1

Validation-harness stability since 0.2.0 — Stage 1/2 capture reliability and iOS Stage 2. Internal to the agent's NATIVEAPPTEMPLATE_VISUAL validation; no CLI flags or generated-output changes.

Fixes

• Clean-install the app before launch (clears stale per-run state) (#91)
• Settle the screen before judging — stability poll instead of a blind sleep (#92)
• Retry capture+judge on a transient render-quality fail, never on content fails (#93)
• Target the iPhone 17 Pro simulator (#94)
• Stage 2 foregrounds the app before the walk + dismisses the post-sign-in Keychain dialog (#95)
• Recover from the intermittent iOS launch error (tap "Back to Start Screen") + dismiss the paid "personal organization" modal (#96)

Validation — full matrix green at VISUAL=2 (2026-05-23)

With these fixes, the complete 3-spec × 2-edition × 2-platform matrix passes a real end-to-end NATIVEAPPTEMPLATE_VISUAL=2 run (build → rename → boot → scripted-CRUD walk → vision judge) on iPhone 17 Pro + Android emulator. Every cell: Layer 1 3/3 · Layer 2 3/3 · Layer 3 2/2 (iOS Stage 2 46/46, Android 48/48) · overall PASS.

Spec	Free	Paid
Walk-in queue	✅ iOS · Android	✅ iOS · Android
Sushi waitlist	✅ iOS · Android	✅ iOS · Android
Personal task tracker	✅ iOS · Android	✅ iOS · Android

After the queue-cell fixes landed, sushi and task tracker passed first-try on both editions with no further changes — the scripted scenario is genuinely spec- and edition-agnostic (the task tracker is a non-queue spec running the same walk).

0.2.0

First release with explicit naming overrides, plus a round of rename-pipeline and Stage 2 hardening. npx nativeapptemplate-agent now serves these.

Highlights

• --project-name="Vet Clinic" — name the generated project. Accepts a human name, PascalCase, or kebab; from it the agent derives the Pascal project name (NativeAppTemplate → VetClinic across Rails + iOS + Android), the slug / output dir (out/vet-clinic/), the DB prefix + env-bridge token, and the display name. Also on the MCP generate_app tool as projectName. (#81, #90)
• --rename From=To (repeatable) — override one of the planner's rename targets; keys on the substrate token (Shop / Shopkeeper / ItemTag), and an override matching no planned rename is reported and dropped. Also on MCP as renameOverrides. (#81)

Fixes

• --rename also syncs domain.entities[].name, so the validation report agrees with the rename plan (#82)
• Rename covers .webmanifest / .svg / .swiftformat, and skips compiled build output (app/assets/builds, public/assets) so it can't corrupt bundled JS like Turbo's visitCompleted (#83, #84)
• Layer 1 skips those build outputs too; a Stage 2 mobile-mcp failure no longer crashes the run — a report is still written (#86)
• Pin @mobilenext/mobile-mcp@0.0.54 — 0.0.55+ breaks the stdio handshake (#87)
• iOS Stage 2 dismisses the Keychain and (paid-only) notification system dialogs that were blocking the walk (#88)
• NATIVEAPPTEMPLATE_MOBILE_<platform>_DEVICE override resolves a display name → canonical device id (#89)

Known limitation

NATIVEAPPTEMPLATE_VISUAL=2 (the Stage 2 scripted-CRUD walk) is functional but capture-flaky run-to-run; a stability pass is planned. Default runs and VISUAL=1 are unaffected.

Full set: #81–#90.

v0.1.2

Patch release — first stable

Fixes two launch-blocker bugs in v0.1.1 that surfaced when running the published package via npx from a /tmp/ directory.

This is the first version that's verified-clean from a never-seen-before user cwd. v0.1.0 and v0.1.1 have been deprecated.

Install:

npx -y nativeapptemplate-agent@latest "your spec"

What changed

Bug 1 — Ruby script path resolution (src/ruby.ts)

src/ruby.ts looked for scripts/ruby/rename.rb relative to process.cwd(), not the package install directory. From /tmp/anything/, this looked for /tmp/anything/scripts/ruby/rename.rb and failed:

Error: ruby script rename.rb exited 1: ruby: No such file or directory --
       /private/tmp/nat-test3/scripts/ruby/rename.rb (LoadError)

Fix: resolve the script path relative to the module's own location via import.meta.url + fileURLToPath. Module-relative for packaged resources; cwd-relative for user-output paths (out/, tmp/trace/, tmp/screenshots/) which were already correct and stay that way.

Bug 2 — rename.rb skip-rule false-matched user cwd ancestors (scripts/ruby/rename.rb)

The renamer's skip?(path) check ran SKIP_DIR_SEGMENTS (tmp, log, build, node_modules, .git, …) against the absolute path. When the user runs from /tmp/myproject/, every file under that prefix matched tmp and got skipped — so the renamer scanned 0 files and produced 0 substitutions. The substrate was copied but never renamed, and Layer 1 reported thousands of leftover tokens.

Fix: compute the path relative to the project root before running skip checks. /tmp/myproject/out/<slug>/rails/README.md becomes out/<slug>/rails/README.md for skip-comparison purposes, no skip-segment matches, file is scanned.

Verified

End-to-end run from /tmp/nat-test4/ (a previously-broken cwd):

$ npx nativeapptemplate-agent "a personal task tracker with due dates"
nativeapptemplate-agent: received spec: a personal task tracker with due dates
=== run complete ===
result: Layer 1 3/3 pass · Layer 2 3/3 pass · Layer 3 skipped · reviewer PASS
overall: PASS

rg "Shop|Shopkeeper|ItemTag" out/task-tracker/ outside vendor/bundle/ → zero matches. Substrate fully renamed.

Deprecations

Version	Status	Reason
0.1.0	deprecated	Silent no-op when invoked via npm bin symlink.
0.1.1	deprecated	Renamer no-op when run from /tmp/ or any path containing tmp/.
0.1.2	latest	Verified clean from /tmp/.

npm install nativeapptemplate-agent (no version) now resolves to 0.1.2.

Full changelog: v0.1.1...v0.1.2

v0.1.1 — bin entry-guard fix

Warning

v0.1.1 has been deprecated. Use v0.1.2 or later. The renamer silently no-ops when run from /tmp/ or any path containing tmp/ as a directory segment, and the Ruby script path was resolved against the user's cwd instead of the package directory — so npx nativeapptemplate-agent from /tmp/anything/ failed entirely. Both bugs are fixed in v0.1.2.

npm warn deprecated nativeapptemplate-agent@0.1.1: Renamer no-op when run from /tmp/ or any path containing 'tmp/'. Use 0.1.2+.

Patch release

Fixes a launch-blocker bug in v0.1.0 where the CLI exited 0 silently when invoked via the npm bin symlink (the npx and ./node_modules/.bin/... code path).

Install:

npx -y nativeapptemplate-agent@0.1.1 "your spec"

What changed

src/index.ts entry-guard previously compared import.meta.url against process.argv[1] without resolving symlinks. When npm installs a package's bin, it symlinks node_modules/.bin/<name> to the actual entry file — so process.argv[1] was the symlink path while import.meta.url was the resolved file URL. The two never matched, the guard fell through silently, and main() was never called.

Fix: resolve both sides via realpathSync + fileURLToPath before comparing. Direct invocation (node dist/index.js) and symlink invocation (./node_modules/.bin/...) now produce identical output.

Verified

• Direct: node dist/index.js "test spec" → full output, overall: PASS, exit 0
• Symlinked: npx -y nativeapptemplate-agent@0.1.1 "test spec" from a clean directory → identical output
• npm view nativeapptemplate-agent@0.1.0 deprecated confirms 0.1.0 is deprecated with a yellow warning steering users to 0.1.1+

v0.1.0 has been deprecated

Anyone running npm install nativeapptemplate-agent@0.1.0 now sees:

npm warn deprecated nativeapptemplate-agent@0.1.0: Silent no-op when invoked via npm bin symlink. Use 0.1.1+.

The version stays available in the registry for anyone with a lockfile pin to 0.1.0, but new installs default to 0.1.1.

v0.1.0 — first release

⚠️ v0.1.0 has a launch-blocker bug — the CLI exits 0 silently when invoked via npx or any npm bin symlink. Use v0.1.1 or later instead. The 0.1.0 npm package has been deprecated; new installs of nativeapptemplate-agent default to v0.1.1+.

---

Highlights

The agent generates three coherent platform implementations from a one-sentence natural-language SaaS spec, validated end-to-end through four layers.

Validation stack:

• Layer 1 — Structural — ripgrep leftover-token scan across all three platforms
• Layer 2 — Runtime — fast-mode toolchain probe by default; real xcodebuild build + ./gradlew assembleDebug when opted in via NATIVEAPPTEMPLATE_VISUAL=1
• Layer 3 — Semantic — Opus 4.7 vision judge against captured home-screen screenshots, median-of-3 sampling per criterion, two-criterion Stage 1 rubric (substrate-leak detection + render-failure detection)
• Reviewer — OpenAPI three-way contract diff with canonical path normalization across Rails OpenAPI / iOS Request structs / Android Retrofit interfaces

Validated demo specs (overall PASS, all four layers green):

• "a walk-in clinic queue for small veterinary practices" — adapt path
• "a restaurant waitlist for casual dining" — adapt path
• "a personal task tracker with due dates" — replace path

Dual-edition support: Same code path works against the free (MIT) edition or the paid edition substrate without modification — pick which by pointing env vars at the corresponding repos. Paid-only features (org switching, invitations, role permissions) survive the rename pipeline intact.

Quickstart

export ANTHROPIC_API_KEY=sk-ant-...
export NATIVEAPPTEMPLATE_API=/path/to/nativeapptemplateapi
export NATIVEAPPTEMPLATE_IOS=/path/to/NativeAppTemplate-Free-iOS
export NATIVEAPPTEMPLATE_ANDROID=/path/to/NativeAppTemplate-Free-Android

npm run dev -- "a walk-in clinic queue for small veterinary practices"

For Layer 3 visual judging (with sim/emulator booted):

ANDROID_SERIAL=emulator-5554 NATIVEAPPTEMPLATE_VISUAL=1 \
  npm run dev -- "a walk-in clinic queue for small veterinary practices"

See README for the full validation table and screenshots.

Acknowledgments

Built with Claude Opus 4.7 + Claude Code. Substrate is the free-edition NativeAppTemplate family of repos.