anhedral 0.1.10 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.3.0 - 2026-07-21
+
+### Added
+
+- Add a unified `anhedral ui add` workflow that routes DOM clients to shadcn/ui and Expo clients to React Native Reusables.
+- Add interactive starter-component selection after app surfaces and feature sets, with NativeWind or Uniwind selection for Expo.
+- Add React Native Reusables-ready Expo configuration, theme CSS, aliases, utilities, Metro integration, and portal hosting.
+- Add manifest schema v5 UI configuration and per-client component installation records.
+- Add staged provider execution, dry-run plans, duplicate-install detection, target validation, and provider routing tests.
+- Add `anhedral new <directory>` as the primary complete-stack creation flow while retaining `init` for an empty current directory.
+- Generate selection-aware `README.md`, `docs/DEVELOPMENT.md`, `docs/STACK.md`, and `SKILL.md` guidance that maps product tasks to ordinary framework source.
+- Publish the repository skill, manual scaffolding reference, conventions, and output-tree contract with the npm package.
+
+### Changed
+
+- Pin the component installer to shadcn 4.13.0 and run all provider mutations inside Anhedral transaction staging.
+- Preserve Anhedral's exact Expo SDK dependency while resolving React Native Reusables registry dependencies before the root workspace install.
+- Present Anhedral as a readable TypeScript stack generator with native Next.js, Expo, Fastify, Drizzle, Electron, and WXT conventions rather than a proprietary application runtime.
+- Use argument-vector process execution for workspace installation instead of invoking a command through a shell.
+- Remove the retired one-app compiler experiment from the production CLI and package surface.
+
+### Security
+
+- Reject symbolic-link scaffold roots before creating transaction metadata or modifying their targets.
+- Override vulnerable `shell-quote` and `sharp` dependency ranges in generated workspaces.
+
+## 0.2.1 - 2026-07-16
+
+### Added
+
+- Add integrity-checked bundled framework substrates, typed module contributions, deterministic root composers, and manifest schema v4 template provenance.
+- Add template tamper, symbolic-link, package-content, and contribution-composition regression tests.
+- Add exact-artifact portability checks at the minimum Node.js 20 and 22 releases and the pinned Node.js 24 release on macOS and Windows.
+- Add scheduled and release-gated Electron, WXT, and Expo native runtime acceptance lanes.
+- Add deterministic workflow, Renovate extraction, release declaration, registry recovery, and module-topology policy tests.
+
+### Security
+
+- Reject altered template catalogs, mismatched substrate digests, symbolic links, forbidden generated artifacts, and oversized template trees before transactional commit.
+- Scan all tracked text, built output, and final package tarballs for high-confidence secret formats before publication.
+- Clarify that public package availability grants no installation, execution, or generated-output rights without a separate written agreement.
+
+## 0.2.0 - 2026-07-15
+
+### Added
+
+- Add manifest schema v3 with deterministic module dependency resolution, file ownership, hashes, modes, and an explicit toolchain channel.
+- Add transactional `init` and `add` operations with locking, journaling, rollback, dry-run plans, and JSON output.
+- Add the `anhedral doctor` command.
+- Add deterministic output-tree contracts for representative scaffold combinations.
+
+### Changed
+
+- Generate only the dependencies, source files, environment keys, apps, and shared packages required by selected modules.
+- Align Vercel Services output with the current `services` schema and mount Fastify routes under the preserved `/api` path.
+- Refresh the verified Next.js, Expo, Clerk, Electron, WXT, Vite, and RevenueCat integration matrix.
+- Separate the side-effect-free package API from the executable CLI entry point.
+- Preserve user-owned documentation, workflows, package fields, and mergeable root configuration during incremental adds.
+- Build from a clean `dist/` directory before tests and packaging.
+- Publish one verified tarball and compare its integrity with npm before tagging.
+- Pin the release Node.js/npm packer so recovery rebuilds remain reproducible.
+- Install the exact release artifact and run its `.bin/anhedral` shim in package smoke tests.
+- Enforce an explicit npm package allowlist and artifact size policy.
+- Test the CLI on Node.js 20, 22, and 24 in CI.
+- Wire Clerk controls and token-aware API helpers into web and mobile templates, and make the desktop account action open Clerk sign-in or profile UI.
+- Bootstrap RevenueCat only for `native-subscriptions`, connect native purchases to the authenticated user, and expose a native paywall action.
+- Put pnpm overrides, build permissions, and peer policy in `pnpm-workspace.yaml`, with conflict-safe structural merges.
+- Keep public API GET requests simple by omitting unused platform and content-type headers.
+- Remove unused provider dependencies and environment placeholders from generated clients.
+- Wire Tailwind CSS v4 into generated web and desktop builds, including semantic shadcn color tokens.
+- Keep canonical module IDs and valid RFC 3986 URI schemes in generated project metadata and documentation.
+- Refresh generator-owned Node.js and pnpm policy during incremental adds when the recorded package manifest is unmodified.
+
+### Removed
+
+- Remove pre-schema-v3 manifest migration, generated-layout adoption, deprecated module aliases, and duplicate `stack.json` output. Projects must be generated with the current CLI and use canonical module IDs.
+
+### Security
+
+- Reject modified managed files and unowned path collisions before committing incremental changes.
+- Validate recovery journals, reject symlink traversal, and persist transaction intent before moving files.
+- Audit every locked CLI dependency through OSV after pnpm's retired audit endpoint became unavailable.
+- Make RevenueCat webhook processing fail closed and persist idempotency records when billing is selected.
+- Scope npm credentials to the single publish step in the protected release job.
+- Separate read-only release verification from npm publication and Git tag creation.
+- Pin GitHub Actions to verified upstream commit SHAs.
+- Default Fastify proxy trust to off, require an explicit bounded trusted-hop count, and minimize conditional Chrome permissions.
+- Reconcile exact package versions against detailed OSV advisory ranges when the batch index is over-broad.
+- Reject manifest-recorded directories and other non-regular paths during project health checks.

package/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+## Local setup
+
+Anhedral requires Node.js 20.19+ or 22.12+ and pnpm 10.34.5.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm build
+pnpm lint
+pnpm check:security
+pnpm check:release-policy
+pnpm audit:osv
+pnpm test
+```
+
+## Before opening a pull request
+
+Run the checks relevant to the files you changed:
+
+```sh
+pnpm typecheck
+pnpm test
+pnpm test:pack
+pnpm test:packlist
+pnpm test:release-tooling
+```
+
+Changes to generated templates or dependency pins should also run:
+
+```sh
+pnpm test:deps
+pnpm test:e2e
+```
+
+The E2E test installs upstream packages in a disposable operating-system temp directory, so it requires network access and may take several minutes. It removes the workspace in a `finally` block; set `ANHEDRAL_E2E_KEEP=1` only when you intentionally need to inspect a failed or completed run.
+
+After an intentional scaffold-output change, regenerate and review the path/mode/SHA-256 contracts and generated tree documentation:
+
+```sh
+pnpm build
+node tests/update-output-tree-contracts.js
+```
+
+## Package changes
+
+- Keep the public package allowlist narrow.
+- Do not commit `dist/`, tarballs, `release-artifact/`, or temporary E2E/demo workspaces.
+- Add or update a regression test for CLI behavior and generated configuration changes.
+- Keep stable toolchain commands pinned; mutable upstream versions belong only in the `latest` lane.
+- Run the OSV audit against a newly installed representative generated lockfile when changing framework or runtime pins.
+
+## Ownership and required review
+
+Repository administrators must map the following roles to real maintainers in branch protection, the protected `npm` environment, private vulnerability reporting, and workflow-failure notifications:
+
+- **Generator owner:** core architecture, transactions, manifests, and generated-file ownership.
+- **Runtime owner:** application templates, provider integrations, and the stable dependency manifest.
+- **Release owner:** package metadata, CI workflows, registry publication, tags, and recovery.
+- **Security responder:** vulnerability intake, secret-exposure response, and supply-chain incidents.
+
+No `CODEOWNERS` file is committed until an actual GitHub user or team slug is selected. A placeholder would create false confidence without enforcing review. Require at least one appropriate owner review for generator/runtime changes and a release-owner review for `.github/workflows/`, `scripts/`, `package.json`, `renovate.json`, `SECURITY.md`, or `docs/RELEASING.md`.
+
+Scheduled Toolchain Drift failures and release-workflow failures must alert the release owner. Security-policy, secret-scan, or OSV failures must additionally alert the security responder. Configure those routes in repository notification settings and test them after changing ownership.
+
+## Releases
+
+Do not run `npm publish` from a development checkout. Version changes are reviewed before release, and CI publishes the verified tarball. See [docs/RELEASING.md](docs/RELEASING.md).
+
+This repository and package are proprietary. Public availability of an npm artifact does not grant permission to install or run it. Contributor and customer rights, including rights in generated output, come only from a separate written agreement with Anhedral, Inc.

package/LICENSE

@@ -1,22 +1,26 @@
-All Rights Reserved
-
 Copyright (c) 2026 Anhedral, Inc.
 
-   THE CONTENTS OF THIS PROJECT ARE PROPRIETARY AND CONFIDENTIAL.
-   UNAUTHORIZED COPYING, TRANSFERRING OR REPRODUCTION OF THE CONTENTS
-   OF THIS PROJECT, VIA ANY MEDIUM, IS STRICTLY PROHIBITED.
+All Rights Reserved.
+
+The contents of this project are proprietary and confidential.
+Unauthorized use, copying, modification, distribution, transfer, or
+reproduction of this project, in whole or in part and by any medium,
+is strictly prohibited except under a separate written agreement with
+Anhedral, Inc.
 
-   The receipt or possession of the source code and/or any parts thereof
-   does not convey or imply any right to use them for any purpose other
-   than the purpose for which they were provided to you.
+Receipt or possession of the source code or any portion of it does not
+convey or imply a license or any right to use it beyond the purpose for
+which Anhedral, Inc. provided it.
 
-   The software is provided "AS IS", without warranty of any kind,
-   express or implied, including but not limited to the warranties of
-   merchantability, fitness for a particular purpose and noninfringement.
-   In no event shall the authors or copyright holders be liable for any
-   claim, damages or other liability, whether in an action of contract,
-   tort or otherwise, arising from, out of or in connection with the
-   software or the use or other dealings in the software.
+Public availability of package metadata, documentation, source code, or a
+downloadable package artifact does not constitute an offer, license, or
+authorization to install or execute the software. Installation, execution,
+and any rights to use, modify, own, deploy, or distribute output generated by
+the software require a separate written agreement with Anhedral, Inc. Nothing
+in this notice expands the rights granted by such an agreement.
 
-   The above copyright notice and this permission notice shall be
-   included in all copies or substantial portions of the software.
+The software is provided "AS IS", without warranty of any kind, express
+or implied, including but not limited to the warranties of merchantability,
+fitness for a particular purpose, and noninfringement. In no event shall
+Anhedral, Inc. or its contributors be liable for any claim, damages, or
+other liability arising from, out of, or in connection with the software.

package/README.md

@@ -1,220 +1,219 @@
 # Anhedral
 
 [![npm version](https://img.shields.io/npm/v/anhedral.svg)](https://www.npmjs.com/package/anhedral)
-[![license](https://img.shields.io/npm/l/anhedral.svg)](./LICENSE)
 [![node](https://img.shields.io/node/v/anhedral.svg)](https://www.npmjs.com/package/anhedral)
 
-One command to start a production-shaped Expo, Fastify, and Chrome extension application.
+Anhedral generates a complete, production-oriented TypeScript stack whose source code stays understandable and customizable.
 
-Anhedral is an opinionated init CLI for teams that want one stable full-stack architecture instead of a menu of half-finished choices. It generates a single pnpm monorepo with an Expo app for web/iOS/Android, a Fastify API, a WXT Chrome extension, shared packages, and deployment-ready structure for Vercel, EAS, and the Chrome Web Store.
+> **Three-second version:** Start with the full TypeScript stack. Keep every escape hatch.
 
-![Anhedral init CLI](docs/anhedral-cli-init.png)
+Anhedral is not a new programming language and generated applications do not run inside a proprietary application framework. It assembles well-documented tools, connects their difficult integration boundaries, and leaves developers with ordinary Next.js, Expo Router, Fastify, Drizzle, Electron, and WXT projects.
 
-## Quick Start
+> **Proprietary software:** Public visibility of package metadata, documentation, or an npm artifact does not grant permission to install, execute, copy, modify, or distribute Anhedral. Installation and use are limited to parties covered by a separate written agreement with Anhedral, Inc. Rights in projects generated by Anhedral are also governed by that agreement.
+
+## Create an application
+
+Create the complete stack:
 
 ```sh
-pnpm dlx anhedral@latest init
+pnpm dlx anhedral@latest new my-product
+cd my-product
+pnpm dev
 ```
 
-Or with npm:
+With no module flags, `new` includes every supported application surface and backend capability. Generate a focused stack by naming only what the product needs:
 
 ```sh
-npx anhedral@latest init
+pnpm dlx anhedral@latest new my-product --web --api --db --auth
+pnpm dlx anhedral@latest new my-api --api --db
+pnpm dlx anhedral@latest new my-clients --web --mobile
 ```
 
-Use `--skip-install` when you want deterministic file generation before installing dependencies:
+`init` generates the same workspace in the current empty directory:
 
 ```sh
-pnpm dlx anhedral@latest init --skip-install
-pnpm install
+mkdir my-product && cd my-product
+pnpm dlx anhedral@latest init --web --api --db --auth
 ```
 
-## What It Generates
-
-```txt
-.
-├─ Frontend/        Expo + React Native Reusables app
-├─ Backend/         Fastify API
-├─ Extension/       WXT Chrome extension
-├─ packages/
-│  ├─ api-client/   shared typed API client
-│  ├─ config/       shared config helpers
-│  ├─ contracts/    shared Zod request/response contracts
-│  ├─ db/           Drizzle schema, Neon client, migrations
-│  └─ types/        shared TypeScript types
-├─ PRODUCTION.md    deployment checklist
-├─ turbo.json       workspace task graph
-└─ package.json     root scripts
+Interactive terminals prompt for surfaces and capabilities. CI and coding agents should pass explicit module flags.
+
+## What gets generated
+
+```text
+my-product/
+├── apps/
+│   ├── web/                    # Next.js App Router + source-owned shadcn/ui
+│   ├── mobile/                 # Expo Router + React Native Reusables
+│   ├── api/                    # Fastify routes, services, auth, providers
+│   ├── desktop/                # Electron + React
+│   ├── extension/              # WXT browser extension
+│   └── assets-private-proxy/   # Cloudflare Worker for private R2 delivery
+├── packages/
+│   ├── contracts/              # shared Zod network contracts
+│   ├── api-client/             # typed client used by every frontend
+│   ├── db/                     # Drizzle schema and reviewed migrations
+│   └── realtime/               # Ably client when billing is selected
+├── docs/
+│   ├── DEVELOPMENT.md          # task-oriented feature recipes
+│   └── STACK.md                # tool map and official documentation
+├── README.md                   # first run and where-to-write-code map
+├── PRODUCTION.md               # selection-specific release runbook
+├── SKILL.md                    # repository guidance for coding agents
+├── ANHEDRAL.md                 # generator and ownership notes
+└── anhedral.json               # modules, versions, provenance, ownership
 ```
 
-The generated app is intentionally one repository. Deploy the same Git repo as two Vercel projects:
-
-- `Frontend`: Expo web export, built with `pnpm build:web`, output to `dist`
-- `Backend`: Fastify API, built with `pnpm build`, entrypoint at `src/index.ts`
-
-The same `Frontend` source is used for native iOS and Android builds through EAS. The `Extension` source builds a WXT Chrome extension ZIP for the Chrome Web Store.
-
-## Stack
+Whole directories are omitted when their module is not selected. Generated documentation is selection-aware.
 
-Anhedral supports one carefully maintained stack:
+## Developer experience
 
-- Expo + React Native Reusables frontend
-- Fastify backend
-- WXT Chrome extension
-- Neon + Drizzle
-- Cloudflare R2/CDN
-- Clerk auth
-- RevenueCat + Stripe
-- Vercel deployment
-- pnpm workspaces + Turborepo
+Developers use each tool normally:
 
-The goal is stability. The generated project avoids framework sprawl, duplicate schemas, and separate frontend/backend/extension repositories.
+```tsx
+// apps/web/app/projects/page.tsx
+import { ProjectList } from '@/components/projects/project-list';
 
-## Why This Stack
-
-Anhedral is built around one idea: a startup should be able to launch every major client from one repository without committing to infrastructure that becomes expensive, fragmented, or hard to change later.
-
-The stack is intentionally narrow:
+export default function ProjectsPage() {
+  return <ProjectList />;
+}
+```
 
-| Choice | Why Anhedral uses it |
-| --- | --- |
-| Expo | One React Native codebase targets web browsers, iOS, and Android. Compared with separate web and native apps, Expo keeps product iteration faster and avoids rebuilding shared screens, auth flows, and client logic three times. |
-| React Native Reusables | It brings shadcn-style primitives to React Native and Expo without locking the app into a heavy design system. Compared with bespoke component scaffolds, it gives teams accessible primitives they can replace or extend as the product becomes specific. |
-| Fastify | Fastify is small, fast, TypeScript-friendly, and works well as a central API layer on Vercel. Compared with pushing logic into many frontend routes, serverless functions, or client SDK calls, a Fastify backend centralizes auth, billing, storage, database access, webhooks, and internal APIs in one place. |
-| TypeScript | The whole stack shares types, contracts, and API clients. Compared with untyped template code, this catches frontend/backend drift before deploy and makes the generated app safer to evolve. |
-| Zod contracts | Request and response schemas live in shared packages. Compared with duplicating interfaces across clients, Zod lets the backend validate inputs while the frontend parses responses from the same source of truth. |
-| Neon + Drizzle | Neon gives serverless Postgres that can start free and scale with usage; Drizzle keeps schema and queries close to TypeScript. Compared with proprietary document databases or opaque ORMs, this keeps the data layer portable, SQL-native, and easy to inspect. |
-| Cloudflare R2/CDN | R2 provides S3-compatible object storage without S3-style egress fees. Compared with storing files in the database or coupling uploads to one app client, signed storage routes give every client the same upload/download primitive. |
-| Clerk | Clerk handles modern auth across web, native, and extension clients. Compared with hand-rolled auth, it removes a high-risk surface area while still letting the backend own authorization decisions. |
-| RevenueCat + Stripe | RevenueCat coordinates native subscriptions and Stripe web billing behind one entitlement model. Compared with separate payment implementations per platform, the backend can ask one question: what is this user allowed to access? |
-| WXT | WXT gives the Chrome extension a modern TypeScript/Vite workflow and supports the Side Panel API. Compared with hand-maintained manifest scaffolds, it reduces extension build and packaging mistakes. |
-| Vercel | Vercel deploys the Expo web app and Fastify API from the same Git repository with separate project roots. Compared with manually wiring CI/CD early, teams get preview deployments and production deploys from normal commits. |
+```ts
+// packages/contracts/src/projects.ts
+import { z } from 'zod';
 
-Every part of the stack can be started on free tiers and scales automatically as traffic grows. That matters because the first production architecture should not force a team to choose between moving quickly and being able to handle success.
+export const ProjectSchema = z.object({ id: z.string(), name: z.string() });
+export const ProjectListSchema = z.array(ProjectSchema);
+```
 
-The bigger advantage is architectural: Anhedral creates all target clients plus one backend that can serve internal and external requests. Product logic, auth decisions, subscription entitlements, storage access, database writes, and webhooks have a central home. That helps startups avoid the common failure mode where every client invents its own rules, and the team later cannot respond quickly when the product needs to shift.
+```ts
+// apps/api/src/routes/projects.ts
+import { db } from '@shared/db';
+import { projects } from '@shared/db/schema';
 
-## Local Development
+export async function listProjects() {
+  return db.select().from(projects);
+}
+```
 
-From the generated project root:
+The convention is a conventional vertical flow, not an Anhedral DSL:
 
-```sh
-pnpm install
-pnpm dev
+```text
+contracts -> database/service -> Fastify route -> typed API client -> frontend
 ```
 
-Run one surface at a time:
-
-```sh
-pnpm dev:frontend
-pnpm dev:backend
-pnpm dev:extension
+- Write web product code under `apps/web` using Next.js conventions.
+- Write mobile product code under `apps/mobile` using Expo Router conventions.
+- Write backend routes and services under `apps/api` using Fastify conventions.
+- Write tables and queries under `packages/db` using Drizzle conventions.
+- Share only network contracts and client-safe packages with frontends.
+- Import the underlying framework directly whenever its API is the right tool.
+
+## The stack
+
+| Concern | Default | Why Anhedral includes it |
+| --- | --- | --- |
+| Web | Next.js + Vercel | App Router, React server rendering, routing, deployment |
+| Native | Expo Router | One TypeScript application for iOS and Android |
+| API | Fastify | Typed validation, structured logging, plugin boundaries |
+| Database | Neon + Drizzle | Managed Postgres with TypeScript schema and SQL-like queries |
+| Authentication | Clerk | Connected frontend and backend identity/session flows |
+| UI | shadcn/ui + React Native Reusables | Accessible source code the application owns |
+| Storage | private Cloudflare R2 | Signed uploads and controlled asset delivery |
+| Billing/realtime | RevenueCat + Ably | Durable entitlements and client invalidation |
+| Desktop | Electron | Predictable cross-platform TypeScript desktop runtime |
+| Extension | WXT | Browser-extension entrypoints, builds, and packaging |
+| Workspace | pnpm + Turborepo | Strict dependencies and dependency-aware tasks |
+
+Anhedral does **not** generate or require local Postgres. Database-enabled projects use a managed Neon connection through `DATABASE_URL`; teams should use isolated Neon branches or projects for development, preview, and production.
+
+## Commands
+
+```text
+anhedral new <directory> [modules...]    Generate a new readable workspace
+anhedral init [modules...]               Generate in the current empty directory
+anhedral add <module...>                 Add connected stack capabilities
+anhedral ui add <component...>           Add source-owned UI components
+anhedral doctor                          Check ownership and generator drift
 ```
 
-Verify before deployment:
+Useful examples:
 
 ```sh
-pnpm verify
-pnpm verify:frontend
-pnpm verify:backend
-pnpm verify:extension
+anhedral add storage --dry-run
+anhedral add desktop extension
+anhedral ui add button dialog
+anhedral ui add data-table --target web --dry-run
+anhedral doctor --json
 ```
 
-Database workflow:
+`--dry-run` builds the complete plan without changing the project. `--json` emits machine-readable output. `--verbose` streams child-tool diagnostics.
+
+Application lifecycle commands remain visible in the generated root `package.json`:
 
 ```sh
+pnpm dev
+pnpm dev:web
+pnpm dev:api
+pnpm typecheck
+pnpm verify
+pnpm build
 pnpm db:generate
 pnpm db:migrate
 ```
 
-## Provider Setup
-
-Generated projects include placeholder env values so the repository can be inspected before accounts are provisioned. Real auth, billing, uploads, native builds, and extension sign-in require provider keys.
-
-The generated `README.md` and `PRODUCTION.md` explain where every key belongs:
+Only commands relevant to selected modules are generated.
 
-- Neon: `DATABASE_URL`
-- Clerk: `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`, `VITE_CLERK_PUBLISHABLE_KEY`
-- RevenueCat + Stripe: `EXPO_PUBLIC_RC_*`, `RC_SECRET_API_KEY`, `RC_WEBHOOK_SECRET`
-- Cloudflare R2/CDN: `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET`
-- Vercel: two projects from the same Git repository, rooted at `Frontend` and `Backend`
-- EAS: native iOS and Android builds from `Frontend`
-- Chrome Web Store: WXT ZIP upload from `Extension/.output`
+## Extensibility and ownership
 
-## Deployment
+Anhedral owns initial assembly and safe structural additions. It does not own product architecture after generation.
 
-### Vercel
+- `README.md`, `PRODUCTION.md`, application features, pages, routes, services, and domain code are developer-owned.
+- Root workspace configuration is mergeable.
+- Integration substrate is recorded in `anhedral.json`; `anhedral add` refuses to overwrite modified managed files.
+- UI components are copied into the application so developers can edit them normally.
+- Provider integrations use ordinary SDKs and configuration files with no hidden control plane.
 
-Import the same GitHub repository twice:
-
-| Project | Root Directory | Build Command | Output |
-| --- | --- | --- | --- |
-| Frontend | `Frontend` | `pnpm build:web` | `dist` |
-| Backend | `Backend` | `pnpm build` | Fastify entrypoint |
-
-Enable Vercel access to source files outside each project root so workspace packages under `packages/*` resolve during builds.
-
-### EAS
-
-Use `Frontend` as the Expo project root:
+Before a structural change:
 
 ```sh
-cd Frontend
-pnpm dlx eas-cli@latest login
-pnpm dlx eas-cli@latest init
-pnpm dlx eas-cli@latest build --platform all --profile production
-pnpm dlx eas-cli@latest submit --platform all --latest --profile production
+anhedral doctor
+anhedral add <module> --dry-run
 ```
 
-### Chrome Extension
-
-```sh
-pnpm extension:zip
-```
-
-Upload `Extension/.output/*-chrome.zip` to the Chrome Web Store Developer Dashboard.
-
-## Dependency Policy
-
-`pnpm dlx anhedral@latest init` gives users the latest published Anhedral CLI, but generated projects use the dependency manifest verified for that release.
-
-Runtime dependency versions live in `src/dependencies.ts`. Generated projects also receive a `stack.json` file recording the exact stack and dependency manifest used for that init run.
+## Documentation contract
 
-This keeps generated apps reproducible while still allowing Anhedral itself to move forward quickly through verified releases.
+Every generated project teaches both humans and coding agents how to work in it:
 
-## Development
+- `README.md` answers how to run the app and where frontend/backend code goes.
+- `docs/DEVELOPMENT.md` provides end-to-end feature and common-task recipes.
+- `docs/STACK.md` maps generated files to each tool's official documentation.
+- `SKILL.md` gives coding agents concise repository-specific workflow and safety rules.
+- `PRODUCTION.md` covers only the accounts, environment, infrastructure, DNS, stores, and release steps selected for that project.
 
-Work on the CLI locally:
+The generator's exact output contract is documented in [docs/output-tree-contract.md](docs/output-tree-contract.md). Contributor architecture remains available in the [source repository](https://github.com/anhedral/anhedral-init/tree/main/docs/architecture).
 
-```sh
-pnpm install
-pnpm build
-pnpm test:all
-```
+## Module dependency rules
 
-Refresh the checked-in demo output:
+Anhedral resolves integrations as a deterministic graph:
 
-```sh
-pnpm demo:refresh
+```text
+auth                 -> api + db
+billing              -> auth
+storage              -> auth
+native-subscriptions -> mobile + billing
 ```
 
-Validate upstream scaffold drift:
+Adding a capability brings the infrastructure it actually requires. Unselected providers do not leave dead source files or environment placeholders behind.
 
-```sh
-pnpm test:e2e:latest
-```
-
-## Release
-
-Official releases are automatic on merges to `main`. The release workflow bumps the patch version, runs the release checks, creates a release commit and tag, and publishes to npm.
+## Verification
 
-Manual fallback:
+The generator and representative public stacks are checked with:
 
 ```sh
-pnpm release:check
-npm publish --provenance=false --ignore-scripts
+pnpm typecheck
+pnpm test:all
 ```
 
-## License
-
-MIT
+Generated workspaces include their own package-level tests, full-stack `verify` command, CI workflow, production environment validation, migration drift gate, and deployment configuration.

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are made on the current development branch and released as a new npm version. Consumers should use the latest version published under the `latest` dist-tag.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use GitHub's private vulnerability reporting or security-advisory flow for this repository. If repository access is unavailable, contact the package maintainers through the owner information on the [anhedral npm package](https://www.npmjs.com/package/anhedral).
+
+Include the affected version, reproduction steps, impact, and any suggested mitigation. Please avoid accessing data that is not yours and allow maintainers time to investigate before public disclosure.
+
+## Supply-chain policy
+
+- Release artifacts are built and tested in a read-only job.
+- The exact tarball uploaded by CI is the artifact submitted to npm.
+- npm integrity is checked before and after publication.
+- npm credentials are exposed only to the publish step in the protected `npm` environment.
+- A Git tag and GitHub release are created only after npm confirms the expected artifact integrity.
+- GitHub Actions are pinned to reviewed commit SHAs, and the release Node.js/npm packer is pinned to an exact version.
+- CI queries OSV for every exact package version in `pnpm-lock.yaml` and every dependency version shipped by the generator; it fails closed if the service remains unavailable after bounded retries or reports a finding.
+- Local policy scans every tracked or non-ignored working-tree text file and built `dist/` file for high-confidence credential formats. Release jobs repeat the scan against the exact gzip tarball before it crosses the publish boundary. Placeholder examples use explicit non-secret values rather than allowlisting token-shaped strings.
+- Release declarations must be valid Semantic Versioning and have a matching `CHANGELOG.md` section. Local deterministic checks validate workflow policy and confirm every Renovate custom manager still extracts a maintained pin.
+
+Generated projects pin their stable dependency manifest, explicitly allow only required dependency build scripts, and record the selected toolchain channel in `anhedral.json`. The `latest` channel is for upstream-drift testing and is not the reproducible default.
+
+Incremental generation rejects path traversal, symbolic-link targets, unowned collisions, modified managed files, and managed-file permission drift. Transaction journals are validated before recovery, fsynced before filesystem moves, and advanced only around durable rename barriers where the host filesystem supports directory synchronization.
+
+UI component installation is an explicit networked supply-chain operation. Anhedral pins the shadcn installer version, routes Expo only to the official HTTPS React Native Reusables registry, validates component names and target paths, and runs provider mutation inside transaction staging. Provider-generated files and dependency manifests must pass ownership checks before commit. Users should review `--dry-run` output and the resulting source diff; registry content is upstream-maintained and is not part of Anhedral's immutable bundled-template catalog.
+
+## Secret response
+
+If a secret-shaped finding is real, do not merely remove it from the latest commit. Revoke or rotate the credential first, identify every log, artifact, cache, fork, and package version that may contain it, and coordinate history or artifact cleanup with the security responder. Treat false positives by changing the example to an unmistakable placeholder; do not add broad path exclusions.
+
+Anhedral is proprietary software. Security reports and public package availability do not grant permission to install, execute, or test the software outside the reporter's written agreement with Anhedral, Inc.