@hitch42/applet 0.1.1-beta.1 → 0.1.1-beta.11

package/scaffold/.agents/skills/hitch-theory/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: hitch-theory
+description: The mental model of Hitch. Read before you design, review, or explain anything that touches Hitch data, applets, access, or query cost. Use when a decision depends on what Hitch is for, what Hitch handles versus what an applet handles, how attributes and references model data, how changesets and releases move together, or who a call acts as. Pairs with hitch-applets, which holds the build procedure.
+---
+
+# Theory of Hitch
+
+This skill explains how Hitch works and why. For the build procedure, read the `hitch-applets` skill.
+
+## 1. What Hitch is
+
+Hitch is a platform for internal applications. It is not a CRM, a rostering product, a reporting product, or any other vertical. An organization builds its own rostering, job, or invoice applets on Hitch.
+
+Hitch is two layers:
+
+1. A durable data system that the organization owns: objects, attributes, records, files, identity, and grants.
+2. A governed runtime for replaceable software: applets that Hitch builds, releases, hosts, and runs.
+
+## 2. What an applet is
+
+An applet is not an app. An app is the whole machine from the old days of software: its own authentication, its own database, its own permissions, a frontend, a server, caches, a deployment pipeline, and monitoring. Every app rebuilds that machine from scratch. Every app then spends most of its life on the machine, not on the work. The organization never wanted the machine. It wanted the business logic.
+
+AI has changed the economics of software. Code is now cheap to write and cheap to change, so software can be personal to one organization, one team, and one workflow. Hitch is built for that world. Hitch flips the model. Instead of one monolithic app designed to serve many unrelated users, an organization gets a set of many applets, completely custom and personalised to its needs. An applet is the closest thing to pure business logic: one workflow, the screens it needs, and the rules that make it correct. Hitch handles everything underneath: the data and its schema, identity, permissions, files, immutable releases, hosting, schedules, and durable workflows. The author never touches the machine. The author builds only what matters to the user.
+
+Hitch takes the machine away for correctness and trust as much as for speed. Authentication, access control, schema validation, and release safety are the parts an agent gets wrong, and the parts an organization cannot afford to have wrong. Hitch handles them, so your organisation has the confidence it needs to fully adopt vibe coded software and move off of legacy SaaS systems.
+
+In practice an applet is a client-only, server-only, or full-stack application that Hitch builds, releases, hosts, and runs inside the platform trust boundary. It is not a third-party plugin.
+
+Every organization has its own tenant on Hitch. Its data, its users, its grants, and its applets all live there. When Hitch runs an applet, it runs it inside that tenant, the way AWS runs a workload inside a customer's account: the provider operates the infrastructure, but the account, the identities, and the data are the customer's. An applet sees its organization's tenant and nothing else.
+
+Applets can be used standalone via their `.app` URL or within the Hitch shell. Standalone and embedded operation use the same identity, release, routes, and theme.
+
+## 3. What Hitch handles and what an applet handles
+
+| Hitch handles                                                   | The applet handles                            |
+| --------------------------------------------------------------- | --------------------------------------------- |
+| Canonical organization records and files                        | One focused workflow and its presentation     |
+| Object and attribute schema, and references                     | Domain-specific UI composition                |
+| Validation, normalization, constraints, versions, audit         | External API adapters and translation         |
+| Organization identity, authentication, grants                   | User interactions and app-specific validation |
+| Immutable releases, schedules, the workflow engine, the runtime | Derived views and deliberate derived records  |
+| Theme delivery and platform navigation                          | Ephemeral client state                        |
+
+## 4. Why code and data are separate
+
+The organization's Hitch data is the single source of truth. An applet reads and writes that data. It does not keep its own copy.
+
+The data layer stands on its own so that every way of using it is a client of the same thing. An applet, the `hitch` command line, an MCP server for an AI agent, an API key in a script, and an import all speak to the same objects, the same schema, and the same permissions. None of them is a bridge bolted on later. The CLI and applet doors are generated from the organization's own schema. The MCP door has a fixed set of record tools and reads each object's live schema at runtime with `get_object_schema`. Each one acts as the person or applet behind it, so it sees exactly what that caller may see. The result is that a person in a browser, an agent in a chat window, and a script in a terminal all work on the same records under the same rules, and each gets the interface that suits them. Software stops being one product with one screen and becomes your organizational data with many doors.
+
+The boundary gives you:
+
+- One source of truth that many applets share.
+- One set of schema and integrity rules for every writer: applets, API keys, imports, and future code.
+- Central permissions that applet UI code cannot weaken.
+- Independent applet release and rollback with no data fork.
+- Direct user-scoped reads from the browser, with no applet server proxy.
+- One place for integrations: sync an external system into Hitch once, then let other applets use the same data.
+
+Consequences:
+
+- Do not add an applet-owned database, a parallel cache, or a copied object set. If an applet seems to need its own storage, Hitch has a gap. Raise the gap instead.
+- Code rollback is not data recovery. A release switch never moves or restores records.
+- When you install, upgrade, or remove an applet, the canonical data stays where it is.
+- A domain rule can live in applet code when it controls one workflow. If the rule must hold for every writer, express it in the schema, so Hitch enforces it for every applet, API key, and import.
+- Data normalization and UI hierarchy are separate decisions. Model distinct concepts as objects plus references when their lifecycle or permissions differ. Group them on one screen when that matches the user. Do not invent child objects to solve navigation.
+
+## 5. Attributes are schema
+
+An attribute is schema, not a free JSON field. Hitch validates each value against its type and configuration, normalizes it, stores it in the record, and indexes it when asked. A value that should be a select or a reference, but is stored as free text, cannot be grouped or filtered well later.
+
+- Types: text, rich text, integer, decimal, currency, checkbox, date, datetime, time, domain, url, email, phone, select, reference, user, organisation, attachment.
+- Cardinality is configuration, not a type. Text, select, reference, user, and attachment can be multi-value. A multi-value is an ordered array.
+- An empty attribute reads as null. A required multi-value attribute rejects an empty array.
+- Uniqueness is a real constraint, per attribute, per organization.
+- Advanced filters and sorting are opt-in per attribute with the `indexed` flag. New attributes default to off. Every attribute still supports equality and not-empty filters. Aggregating or grouping by an attribute needs no flag. Type rules still apply: a reference, user, attachment, rich text, or multi-value attribute never sorts. Do not turn the flag on for every attribute. Turn it on for the attributes a query needs.
+
+References model relationships:
+
+- A reference attribute names a target object. Cardinality on each side comes from the single or multi setting of each face.
+- A reference can expose an inverse face on the target object. One face owns and stores the edges. The other face is derived. Write the owner face only.
+- Hitch keeps the links typed, clears inbound links when a target is deleted, applies grants through the inverse, and lets you filter through either face. Do not invent a join object for a plain relationship. Use a join object only when the relationship needs its own fields or lifecycle.
+
+Special cases:
+
+- A user attribute points at a membership in the same organization. Removal of the member sweeps those values.
+- An organisation attribute points at a connected organisation; null means internal only; at most one exists per object.
+- An attachment attribute holds file IDs. Files live outside records, in their own storage. Create the file, upload it, then store the ID on the record.
+
+## 6. Changesets and releases move together
+
+All schema mutations go through a changeset: an ordered list of object and attribute operations with a stored evaluation.
+
+- A hard blocker means invalid schema or data. Examples: a unique constraint that finds duplicates, a required attribute with empty records, a tightened range with violators.
+- A soft blocker means a dependency. Examples: applets, grant conditions, or delegations that depend on the object or attribute.
+- Any blocker stops the apply. A submit with a blocker stages a pending changeset. The apply succeeds after the blocker is resolved.
+
+An applet release can bind to a pending changeset. Hitch checks the manifest against the schema the changeset will produce. A mismatch is a deploy warning, not a denial. The unresolved warning becomes a hard blocker on the changeset. A bound release does not go live on deploy. When the changeset applies, the schema and the newest bound release of each applet become active together. Schema and code change together.
+
+Adoption folds one pending changeset into another and abandons the source. The source must have no bound releases.
+
+The applet manifest lists the objects the applet uses, with create and delete flags, read-only attributes, and read-write attributes. That list is the access declaration. It caps what the applet identity can do: the object actions, and the attributes it can update. It does not change what a user can see.
+
+## 7. Identity and access
+
+Hitch enforces access control on every Hitch API call. An applet never re-implements it. A UI filter or a hidden control is convenience, never a boundary. An applet's own server procedure is applet code, so it must check the business rules it introduces. Every call carries a principal and Hitch applies that principal's grants.
+
+Principals:
+
+- A person, through a session or a personal API key. A personal API key inherits the member's capabilities.
+- An impersonated person. The target's capabilities must be a proper subset of the caller's.
+- An applet. The applet identity has no role and no bypass. Its authority is exactly the grants projected from its manifest.
+
+The organization roles are member and owner. There is no admin role. The owner holds every capability, bypasses every grant, and cannot be removed or impersonated. Capabilities are ten named org-wide powers: manage members, teams, objects, permissions, applets, and the organization; read all records; write all records; use applets; impersonate members. A capability grant goes to a team only, never to a person or to everyone. When one person needs a capability, put them in a one-person team. A caller can grant only a capability the caller holds.
+
+Object grants are the matrix: one row per object and grantee with create, read, update, and delete flags. A grantee is a team, an applet, or the default row that every member holds. A member's access is the union of the default row and their team rows. The read-all and write-all capabilities bypass object grants. Object grants set the verbs. Conditions narrow rows. Attribute grants restrict updates to protected attributes and applet writes. Reads are never masked per attribute.
+
+An object grant can delegate through one single-valued owner reference. The linked record then uses the same grantee's grant on the target object.
+
+Grant conditions scope rows to the current user. A condition path is a user attribute on the object, or one reference followed by a user attribute on the target object. A record whose user attribute is empty is invisible to that grant. An invisible record behaves as missing. A condition applies to read, update, and delete, never to create. A condition cannot compare a value, such as "where status equals X".
+
+Who a call acts as:
+
+- A client applet call acts as the current user. The manifest grants do not apply.
+- A schedule run acts as the applet, capped by the manifest.
+- A workflow run acts as whoever started it: the invoking user, or the applet when a schedule started it.
+
+Because Hitch enforces access, a client applet needs no server proxy for filtering or access control. Add a server only for secrets, external systems, schedules, workflows, or bounded fan-in.
+
+## 8. What makes a good applet
+
+A good applet:
+
+- Solves one related workflow for one clear group of users.
+- Uses the organization's existing Hitch data, not a private copy.
+- Presents the smallest useful set of decisions and actions. It does not reproduce a legacy product screen for screen.
+- Uses Hitch primitives before custom infrastructure.
+- Feels native through semantic theme tokens, shared interaction patterns, useful empty, loading, and error states, and viewport-safe layouts.
+- Has explicit access, performance, failure, and recovery behavior.
+- Can be replaced or rolled back with no move or rewrite of the canonical data.
+
+Split an applet when workflows, audiences, privileges, release cadence, or failure modes differ. Do not split because the UI has another page. A sync applet and a reporting applet are a good split. Ingestion has secrets, schedules, broad write grants, retries, and external failure modes. Reports read already-synced data with narrow grants.
+
+## 9. Product-design principles
+
+- Build to user outcomes, not to the screens or tables of an older system.
+- Start with the important nouns, relationships, permissions, and failure cases. Design screens after that.
+- Simplify critically. Defer speculative channels and infrastructure.
+- Ship the smallest complete workflow. Add nothing unrequested.
+- Treat thresholds, status rules, timing, channels, and recipients as product decisions for the user.
+- Confirm destructive or external writes. Show the target, the intended change, the stale-source check, and the outcome. A Hitch mutation and a mutation of an external source are not equivalent.
+- Record rejected designs and the reason. Do not rebuild what was deliberately cut.

package/scaffold/.agents/skills/react-best-practices/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: react-best-practices
+description: Client React performance guidelines. Use when writing, reviewing, or refactoring React components, client data fetching, bundles, rendering, or browser performance.
+license: MIT
+metadata:
+  version: "1.0.0"
+---
+
+# React Best Practices
+
+Performance guidance for client React applications. The rules focus on browser behavior, client data fetching, bundles, rendering, and re-renders.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Writing new React components
+- Implementing client data fetching
+- Reviewing code for performance issues
+- Refactoring existing React code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category                  | Impact      | Prefix       |
+| -------- | ------------------------- | ----------- | ------------ |
+| 1        | Eliminating Waterfalls    | CRITICAL    | `async-`     |
+| 2        | Bundle Size Optimization  | CRITICAL    | `bundle-`    |
+| 3        | Client-Side Data Fetching | MEDIUM-HIGH | `client-`    |
+| 4        | Re-render Optimization    | MEDIUM      | `rerender-`  |
+| 5        | Rendering Performance     | MEDIUM      | `rendering-` |
+| 6        | JavaScript Performance    | LOW-MEDIUM  | `js-`        |
+| 7        | Advanced Patterns         | LOW         | `advanced-`  |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-analyzable-paths` - Prefer statically analyzable imports
+- `bundle-dynamic-imports` - Use React.lazy for heavy components
+- `bundle-defer-third-party` - Split non-critical libraries from the initial bundle
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 4. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-split-combined-hooks` - Split hooks with independent dependencies
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+- `rerender-no-inline-components` - Don't define components inside components
+
+### 5. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Track async action pending state with useTransition
+- `rendering-resource-hints` - Use React DOM resource hints for preloading
+- `rendering-script-defer-async` - Use defer or async on script tags
+
+### 6. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+- `js-flatmap-filter` - Use flatMap to map and filter in one pass
+- `js-request-idle-callback` - Defer non-critical work to browser idle time
+
+### 7. Advanced Patterns (LOW)
+
+- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references

package/scaffold/.agents/skills/react-best-practices/rules/advanced-effect-event-deps.md

@@ -0,0 +1,50 @@
+---
+title: Do Not Put Effect Events in Dependency Arrays
+impact: LOW
+impactDescription: avoids unnecessary effect re-runs and lint errors
+tags: advanced, hooks, useEffectEvent, dependencies, effects
+---
+
+## Do Not Put Effect Events in Dependency Arrays
+
+Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect body or subscriptions created by that effect.
+
+**Incorrect (Effect Event added as a dependency):**
+
+```tsx
+import { useEffect, useEffectEvent } from "react";
+
+function ChatRoom({ roomId, onConnected }: { roomId: string; onConnected: () => void }) {
+  const handleConnected = useEffectEvent(onConnected);
+
+  useEffect(() => {
+    const connection = createConnection(roomId);
+    connection.on("connected", handleConnected);
+    connection.connect();
+
+    return () => connection.disconnect();
+  }, [roomId, handleConnected]);
+}
+```
+
+Including the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.
+
+**Correct (depend on reactive values, not the Effect Event):**
+
+```tsx
+import { useEffect, useEffectEvent } from "react";
+
+function ChatRoom({ roomId, onConnected }: { roomId: string; onConnected: () => void }) {
+  const handleConnected = useEffectEvent(onConnected);
+
+  useEffect(() => {
+    const connection = createConnection(roomId);
+    connection.on("connected", handleConnected);
+    connection.connect();
+
+    return () => connection.disconnect();
+  }, [roomId]);
+}
+```
+
+Reference: [React useEffectEvent: Effect Event in deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)

package/scaffold/.agents/skills/react-best-practices/rules/advanced-event-handler-refs.md

@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler);
+    return () => window.removeEventListener(event, handler);
+  }, [event, handler]);
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler);
+  useEffect(() => {
+    handlerRef.current = handler;
+  }, [handler]);
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e);
+    window.addEventListener(event, listener);
+    return () => window.removeEventListener(event, listener);
+  }, [event]);
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from "react";
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler);
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent);
+    return () => window.removeEventListener(event, onEvent);
+  }, [event]);
+}
+```
+
+`useEffectEvent` reads the latest handler without re-subscribing. The Effect Event function does not have a stable identity.

package/scaffold/.agents/skills/react-best-practices/rules/advanced-init-once.md

@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage();
+    checkAuthToken();
+  }, []);
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false;
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return;
+    didInit = true;
+    loadFromStorage();
+    checkAuthToken();
+  }, []);
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)

package/scaffold/.agents/skills/react-best-practices/rules/advanced-use-latest.md

@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState("");
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300);
+    return () => clearTimeout(timeout);
+  }, [query, onSearch]);
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from "react";
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState("");
+  const onSearchEvent = useEffectEvent(onSearch);
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300);
+    return () => clearTimeout(timeout);
+  }, [query]);
+}
+```

package/scaffold/.agents/skills/react-best-practices/rules/async-cheap-condition-before-await.md

@@ -0,0 +1,37 @@
+---
+title: Check Cheap Conditions Before Async Flags
+impact: HIGH
+impactDescription: avoids unnecessary async work when a synchronous guard already fails
+tags: async, await, feature-flags, short-circuit, conditional
+---
+
+## Check Cheap Conditions Before Async Flags
+
+When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.
+
+This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.
+
+**Incorrect:**
+
+```typescript
+const someFlag = await getFlag();
+
+if (someFlag && someCondition) {
+  // ...
+}
+```
+
+**Correct:**
+
+```typescript
+if (someCondition) {
+  const someFlag = await getFlag();
+  if (someFlag) {
+    // ...
+  }
+}
+```
+
+This matters when `getFlag` hits the network, a feature-flag service, or `React.cache` / DB work: skipping it when `someCondition` is false removes that cost on the cold path.
+
+Keep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.

package/scaffold/.agents/skills/react-best-practices/rules/async-defer-await.md

@@ -0,0 +1,82 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId);
+
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true };
+  }
+
+  // Only this branch uses userData
+  return processUserData(userData);
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true };
+  }
+
+  // Fetch only when needed
+  const userData = await fetchUserData(userId);
+  return processUserData(userData);
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId);
+  const resource = await getResource(resourceId);
+
+  if (!resource) {
+    return { error: "Not found" };
+  }
+
+  if (!permissions.canEdit) {
+    return { error: "Forbidden" };
+  }
+
+  return await updateResourceData(resource, permissions);
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId);
+
+  if (!resource) {
+    return { error: "Not found" };
+  }
+
+  const permissions = await fetchPermissions(userId);
+
+  if (!permissions.canEdit) {
+    return { error: "Forbidden" };
+  }
+
+  return await updateResourceData(resource, permissions);
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).

package/scaffold/.agents/skills/react-best-practices/rules/async-dependencies.md

@@ -0,0 +1,48 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([fetchUser(), fetchConfig()]);
+const profile = await fetchProfile(user.id);
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from "better-all";
+
+const { user, config, profile } = await all({
+  async user() {
+    return fetchUser();
+  },
+  async config() {
+    return fetchConfig();
+  },
+  async profile() {
+    return fetchProfile((await this.$.user).id);
+  },
+});
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser();
+const profilePromise = userPromise.then((user) => fetchProfile(user.id));
+
+const [user, config, profile] = await Promise.all([userPromise, fetchConfig(), profilePromise]);
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)

package/scaffold/.agents/skills/react-best-practices/rules/async-parallel.md

@@ -0,0 +1,24 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser();
+const posts = await fetchPosts();
+const comments = await fetchComments();
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([fetchUser(), fetchPosts(), fetchComments()]);
+```