Run the project — iMaistro field guide

Start at the repository root

The repository README is the source of truth for pinned versions and bootstrap commands. Read it before installing tools manually. The root mise.toml and moon project files describe the intended development environment.

Use the repository’s .agents/AGENTS.md when handing work to a coding agent. It records the boundaries and conventions that keep the project tidy.

The portable entry points are mise run deps:install, mise run lint:all, mise run test:all, and mise run build:all. The plain npm, dart, and flutter commands below assume an activated mise environment. Without activation, prefix an individual command with mise exec --.

If you extracted a source ZIP, initialize its Git metadata once with git init -b main before running moon tasks. A Git clone already has this metadata.

Workspace responsibilities

Directory	Purpose
`apps/mobile`	Flutter application and platform hosts.
`apps/marketing`	Astro marketing pages, field guide, and website demo.
`apps/download`	Separate Astro build for the `.app` download destination.
`packages/calculation`	Pure Dart domain and calculation tests.
`packages/design_tokens`	Shared source tokens and generated platform outputs.
`packages/web_ui`	Shared Astro components, brand assets, and web styles.
`vault`	Obsidian project knowledge and design documentation.
`tooling`	Repository automation and checks.

Website development

After installing the Node workspace dependencies, the native package scripts are available:

npm run dev --workspace @imaistro/marketing
npm run dev --workspace @imaistro/download

The marketing site uses port 4321 and the download site uses 4322. Both produce static builds. They share a small UI package rather than duplicating the brand, store buttons, and theme behavior.

npm run check --workspace @imaistro/marketing
npm run test --workspace @imaistro/marketing
npm run build --workspace @imaistro/marketing

Moon provides the corresponding repository-level orchestration. Use the task names documented in the root README.

Store destinations

The two store links are intentionally empty until real listings exist. Set the public build variables when ready:

PUBLIC_APP_STORE_URL
PUBLIC_PLAY_STORE_URL

The shared store component validates that destinations use HTTPS and the expected official store hostname. Empty values produce explicit Coming soon states, not invented app listings.

For a hosted review build, PUBLIC_APP_PREVIEW_URL can add a Try the app link to the marketing hero. It is empty in the normal production configuration. BASE_PATH supports mounting the download build under a path for a combined preview.

What to test

Calculation tests should use independently checked expected values. Cover dimensional errors, unit conversions, fractions, division by zero, impossible inputs, and boundary conditions for each recipe.

Persistence tests should verify actual database round trips, transactions, migrations, and backup validation. Widget and browser tests should exercise meaningful actions rather than merely checking that a title renders.

Native device testing is still required for store release. A successful web build does not prove iOS signing, Android store readiness, physical-device haptics, or screen-reader behavior.

Change one boundary at a time

When adding a helper, implement and test the domain calculation first. Then connect its inputs, result presentation, and diagram in the app. Update the guide and any source references once the behavior is stable.

Keep formulas out of widgets. Keep UI labels out of database migrations. Small feature folders help a future contributor find the right place to make a change.