stacks-native

# Native Stacks capabilities Start with the native feature that already owns the behavior. Read the selected subsystem skill before implementing its API. [CATALOG.md](CATALOG.md) maps every core package to task guidance and its current source entrypoint; browse the relevant section rather than loading the whole reference. ## Choose a workflow | Need | Native workflow | |---|---| | Persist a new entity and expose CRUD | `stacks-models`, `stacks-migrations`, `stacks-orm`, `stacks-actions`, `stacks-router` | | Extend a built-in model without forking it | `extendModel`, then model-driven migration generation | | Typed requests and an inferred API client | `Action.validations`, directly registered actions, `createTypedRouter` and `createTypedClient` | | Authenticate or authorize rows | `stacks-auth`, model API ownership, middleware, policies and gates | | Render interactive pages and validate forms | `stacks-stx`, `stacks-composables`, `stacks-forms`, `stacks-ui` | | Queue work or run it later | `stacks-jobs`, `stacks-queue`, `stacks-scheduler` | | Send mail, notifications, SMS or push | `stacks-mail`, `stacks-email`, `stacks-notifications`, `stacks-sms`, `stacks-push` | | Publish CMS pages or run commerce | `stacks-cms`, `stacks-commerce`, `stacks-payments` | | Build sites, newsletters, charts or media | `stacks-sites`, `stacks-newsletter`, `stacks-charts`, `stacks-image`, `stacks-audio`, `stacks-video` | | Paginate, cache, search or store files | `stacks-pagination`, `stacks-cache`, `stacks-search-engine`, `stacks-storage` | | Enable an optional bundle or run an experiment | `stacks-features` for framework bundles, `stacks-feature-flags` for user-targeted flags | | Build, deploy or operate an app | `stacks-build`, `stacks-deploy`, `stacks-cloud`, `stacks-server`, `stacks-buddy` | ## Model-first implementation Declare schema, validators, fillable fields, relationships, traits, and ownership in `app/Models/`. `defineModel()` produces the query surface immediately; `useApi` registers CRUD at runtime. It does not require generated ORM classes or generated action files. Add a custom Action only when the behavior differs from the native CRUD contract. Run `./buddy generate:migrations`, review the SQL and dialect snapshot, then run it again to confirm no further diff. Apply with `./buddy migrate`. Keep models, generated migrations, and the snapshot together in review. `migrate:fresh` destroys tables and is a separate development operation. See [RECIPES.md](RECIPES.md) for an end-to-end native tracer bullet and the cases that require an action, job, policy, or explicit route. ## Important boundaries - Before adding imports in app code, consult the context-specific names in `storage/framework/auto-imports/RUNTIME.md` at the project root. Use listed runtime helpers directly; read `stacks-auto-imports` for initialization and module boundaries. Generation refreshes the inventory for this app. - `app/` overrides framework defaults. Use `extendModel` for additive model changes; an ordinary override replaces the definition. - Generated CRUD defaults to authenticated routes. Ownership and policies govern rows separately; unscoped writes may be withheld by the default row-scoping policy. Do not weaken that policy to make an example work. - Transactional queries use the supplied `tx` handle. Model calls do not automatically join that transaction's connection. - Optional bundles control model/migration/view selection. Route mounting has its own registry and default-bundle selection; a package being installed does not mean every route is public or mounted. - Browser declarations, stx eager bindings, demand-inline bindings, and explicit imported composables are different surfaces. Read `stacks-auto-imports` before using an unfamiliar bare name. - Use request-time subpath exports when available. Tooling barrels may load migrations, config discovery, or native modules that a handler does not need. - A typed configuration or exported adapter is not proof of provider support. [CAPABILITIES.md](CAPABILITIES.md) is generated from the driver evidence registry, including partial and experimental limits. ## Completion and freshness Use the subsystem's actual signatures and retained tests, and verify the requested behavior. Run pickier through buddy, relevant tests, and the proper typecheck. UI changes also complete the design preflight. Within the framework repository, the native catalog and driver reference are generated by `./buddy docs:native-skills`; `./buddy docs:native-skills:check` detects missing package guidance and stale references. That check establishes coverage and source freshness, not semantic correctness of every prose sentence.