anhedral 0.4.0 → 0.4.2

package/docs/master-stack-map.md

@@ -5,6 +5,13 @@ from skill-led planning through deterministic generation, source layout,
 connected capabilities, cloud provisioning, command-driven operations, agent
 experience, and production verification.
 
+![Anhedral master stack diagram](../assets/anhedral-cli-init.svg)
+
+The diagram is generated from `scripts/render-master-stack-map.mjs`. Change the
+content or geometry there, then run `pnpm docs:stack-map`; do not hand-edit the
+SVG. The fixed-width map below remains the detailed text and accessibility
+reference.
+
 Read top to bottom. Arrows represent lifecycle order, not runtime network calls.
 Runtime and provider connections are stated explicitly inside each stage.
 

package/docs/output-tree-contract.md

@@ -21,10 +21,10 @@ node tests/update-output-tree-contracts.js
 
 | Scenario | Apps | Features | Contract | Entries | Tree SHA-256 |
 | --- | --- | --- | --- | ---: | --- |
-| `expo-extension` | web, mobile, api, desktop, extension | database, auth, billing, storage, nativeSubscriptions, electronUpdater | deterministic golden | 145 | `ffe0feed203c4cdfaeeadba03dd2acc93855296699570d81f856b989f45cde23` |
-| `web-api-minimal` | web, api | database, auth | deterministic golden | 65 | `25303118c1ee766afbfd9a707b5b16c25ad587021a62a68238696dda7cbc4385` |
-| `api-only` | api |  | deterministic golden | 32 | `a405e93cea274273bf46605e934e4a9be21018513b04c47c83ed1b1b8c9f187e` |
-| `add-desktop-flow` | api, desktop | database, auth | deterministic golden | 67 | `d6804478404c2bb62945f6a7dbb9d1184ebe75d3594b83347cab76e785b21051` |
+| `expo-extension` | web, mobile, api, desktop, extension | database, auth, billing, storage, nativeSubscriptions, electronUpdater | deterministic golden | 150 | `4fcbb6a1bc51387abe3a5f629a6a6f83b4580da668aa00514d24471e50ef652b` |
+| `web-api-minimal` | web, api | database, auth | deterministic golden | 67 | `512f2af0a3ef250d43c24400df730488dee50bc81616dd9f58c4f4e3125aed3a` |
+| `api-only` | api |  | deterministic golden | 33 | `3d4c80296467bb735456fc2e2485889b6583e9daac8934e6c3205a0dc47ad04e` |
+| `add-desktop-flow` | api, desktop | database, auth | deterministic golden | 69 | `79e0686d8a0b50f34334b73ffc3c766cbe1a13283a0bc7dfe814c9e7d63cc75c` |
 
 ## expo-extension
 
@@ -88,6 +88,7 @@ expo-extension-sample/
 │   │   │   │   └── preload.cts
 │   │   │   └── renderer/
 │   │   │       ├── components/
+│   │   │       │   ├── item-list.tsx
 │   │   │       │   └── ui/
 │   │   │       │       └── button.tsx
 │   │   │       ├── hooks/
@@ -116,6 +117,7 @@ expo-extension-sample/
 │   │   ├── postcss.config.cjs
 │   │   ├── src/
 │   │   │   ├── components/
+│   │   │   │   ├── item-list.tsx
 │   │   │   │   └── ui/
 │   │   │   │       └── button.tsx
 │   │   │   ├── contexts/
@@ -145,7 +147,8 @@ expo-extension-sample/
 │   │   ├── app.json
 │   │   ├── babel.config.js
 │   │   ├── components/
-│   │   │   └── account-controls.tsx
+│   │   │   ├── account-controls.tsx
+│   │   │   └── item-list.tsx
 │   │   ├── components.json
 │   │   ├── eas.json
 │   │   ├── expo-env.d.ts
@@ -170,6 +173,7 @@ expo-extension-sample/
 │       │   └── page.tsx
 │       ├── components/
 │       │   ├── account-actions.tsx
+│       │   ├── item-list.tsx
 │       │   ├── subscription-status.tsx
 │       │   └── ui/
 │       │       ├── button.tsx
@@ -229,6 +233,7 @@ expo-extension-sample/
 │       └── tsconfig.json
 ├── pnpm-workspace.yaml
 ├── scripts/
+│   ├── first-run.mjs
 │   └── verify-db-migrations.mjs
 ├── turbo.json
 └── vercel.json
@@ -277,6 +282,7 @@ web-api-minimal/
 │       │   └── page.tsx
 │       ├── components/
 │       │   ├── account-actions.tsx
+│       │   ├── item-list.tsx
 │       │   └── ui/
 │       │       ├── button.tsx
 │       │       └── card.tsx
@@ -325,6 +331,7 @@ web-api-minimal/
 │       └── tsconfig.json
 ├── pnpm-workspace.yaml
 ├── scripts/
+│   ├── first-run.mjs
 │   └── verify-db-migrations.mjs
 ├── turbo.json
 └── vercel.json
@@ -377,6 +384,8 @@ api-only/
 │       │   └── index.ts
 │       └── tsconfig.json
 ├── pnpm-workspace.yaml
+├── scripts/
+│   └── first-run.mjs
 ├── turbo.json
 └── vercel.json
 ```
@@ -431,6 +440,7 @@ add-desktop-flow/
 │       │   │   └── preload.cts
 │       │   └── renderer/
 │       │       ├── components/
+│       │       │   ├── item-list.tsx
 │       │       │   └── ui/
 │       │       │       └── button.tsx
 │       │       ├── lib/
@@ -476,6 +486,7 @@ add-desktop-flow/
 │       └── tsconfig.json
 ├── pnpm-workspace.yaml
 ├── scripts/
+│   ├── first-run.mjs
 │   └── verify-db-migrations.mjs
 ├── turbo.json
 └── vercel.json

package/docs/references/manual-scaffolding.md

@@ -106,11 +106,13 @@ Create only selected branches of this tree. A bracketed condition makes the file
   apps/web/components/ui/{button.tsx,card.tsx}               [web]
   apps/web/lib/utils.ts                                     [web]
   apps/web/{lib/api.ts,hooks/use-api-client.ts}              [web + api]
+  apps/web/components/item-list.tsx                          [web + api + db]
   apps/web/components/account-actions.tsx                   [web + auth]
   apps/web/{hooks/use-entitlement.ts,components/subscription-status.tsx} [web + billing]
   apps/mobile/{package.json,app.json,tsconfig.json,expo-env.d.ts,eas.json,.env.example,.gitignore} [mobile]
   apps/mobile/app/{_layout.tsx,index.tsx}                    [mobile]
   apps/mobile/{lib/api.ts,hooks/use-api-client.ts}           [mobile + api]
+  apps/mobile/components/item-list.tsx                       [mobile + api + db]
   apps/mobile/components/account-controls.tsx               [mobile + auth]
   apps/mobile/hooks/use-entitlement.ts                      [mobile + billing]
   apps/mobile/lib/subscriptions.ts                           [native-subscriptions]
@@ -120,6 +122,7 @@ Create only selected branches of this tree. A bracketed condition makes the file
   apps/desktop/src/renderer/{main.tsx,styles.css,lib/utils.ts} [desktop]
   apps/desktop/src/renderer/components/ui/button.tsx        [desktop]
   apps/desktop/src/renderer/lib/api.ts                       [desktop + api]
+  apps/desktop/src/renderer/components/item-list.tsx         [desktop + api + db]
   apps/desktop/src/renderer/lib/auth.ts                      [desktop + auth]
   apps/desktop/src/renderer/hooks/use-entitlement.ts        [desktop + billing]
   apps/desktop/electron-builder.env.example                 [electron-updater]
@@ -133,6 +136,7 @@ Create only selected branches of this tree. A bracketed condition makes the file
   apps/extension/src/entrypoints/{background.ts,sidepanel/index.html,sidepanel/main.tsx,sidepanel/app.tsx} [extension]
   apps/extension/src/contexts/auth-context.tsx              [extension + auth]
   apps/extension/src/lib/api.ts                              [extension + api]
+  apps/extension/src/components/item-list.tsx                [extension + api + db]
   apps/extension/src/hooks/use-entitlement.ts               [extension + billing]
 ```
 
@@ -148,7 +152,7 @@ Always add `build: turbo build` and `typecheck: turbo typecheck`. Set `dev` to
 the primary product loop: run the first selected client in canonical module
 order plus API when present, or API alone for a backend-only project. When the
 project has additional app surfaces, add `dev:all` to run every selected app in
-parallel. Each command uses `turbo dev --parallel` with explicit
+parallel. Each command uses `turbo run dev` with explicit
 `--filter=./apps/<surface>` arguments. Add only selected scripts:
 
 ```text
@@ -203,7 +207,7 @@ Pin current security overrides for `@vitejs/plugin-react`, `postcss`, vulnerable
 Create `turbo.json` using `https://turborepo.dev/schema.json` with:
 
 - `build.dependsOn = ["^build"]` and outputs `.next/**`, `!.next/cache/**`, `.output/**`, `dist/**`.
-- `typecheck.dependsOn = ["^build"]`.
+- `typecheck.dependsOn = ["^typecheck"]`.
 - `dev.cache = false` and `dev.persistent = true`.
 
 Ignore `node_modules`, framework/build caches, coverage, release output, every `.env` variant except `.env.example`, and `*.tsbuildinfo`. Put extension output, mobile web export, desktop release output, `apps/assets-private-proxy`, and `apps/desktop-updater-worker` in `.vercelignore`.
@@ -212,6 +216,12 @@ Create the single root `vercel.json` using `https://openapi.vercel.sh/vercel.jso
 
 Create `.github/workflows/anhedral-ci.yml` with read-only contents permission, concurrency cancellation, pinned action commit SHAs, pnpm setup, Node `22.13.0` for mobile or `20.19.0` otherwise, and frozen installation. Run `pnpm typecheck`, API coverage tests when API exists, and `pnpm build`. For database workspaces also run `pnpm verify:db`, run `pnpm db:generate`, fail on any migration diff, and fail on untracked migration artifacts.
 
+Create `scripts/first-run.mjs` and root `first-run`/`ready` scripts. `first-run`
+must copy only missing package-local environment files and never overwrite
+existing values. `ready` must identify missing files and required blank or
+placeholder variables without printing values, return nonzero when blocked,
+and treat explicitly documented optional variables as optional.
+
 Create `README.md` containing selected modules and first-run commands. Create `PRODUCTION.md` containing provider and deployment requirements from sections 8 and 9. These two files become user-owned; do not rewrite them during later manual module additions.
 
 ## 4. Create shared packages
@@ -235,6 +245,11 @@ Create `@shared/api-client` when API and at least one client surface are selecte
 - JSON parsing and Zod response validation;
 - typed methods for health/readiness and only selected auth, billing, and storage routes.
 
+When database is selected, also create user-owned item request/response
+contracts and `listItems`/`createItem` methods. Render that same feature with
+idiomatic, accessible UI in every selected client so the first end-to-end proof
+is cross-platform rather than web-only.
+
 Do not make server-only provider SDKs dependencies of clients.
 
 ### Realtime client
@@ -341,10 +356,12 @@ Run from the root:
 
 ```sh
 pnpm install
-pnpm typecheck
+pnpm first-run
+pnpm ready
 ```
 
-For a database workspace, copy its environment, generate and review the initial migration, and add it to Git before the gate:
+For a database workspace, generate and review the initial migration, and add it
+to Git before the gate:
 
 ```sh
 pnpm db:generate
@@ -356,6 +373,7 @@ pnpm db:migrate
 Then run every selected package verification, root verification, and build:
 
 ```sh
+pnpm typecheck
 pnpm verify
 pnpm build
 ```