anhedral 0.4.1 → 0.4.2

package/dist/templates/shared.d.ts

@@ -1,2 +1,2 @@
-import type { ProjectOptions } from '../scaffold.js';
+import type { ProjectOptions } from '../project.js';
 export declare function scaffoldSharedPackages(root: string, options: ProjectOptions): void;

package/dist/templates/shared.js

@@ -108,14 +108,18 @@ export const realtimeOutbox = pgTable('realtime_outbox', {
 ` : '';
     writeFile(path.join(dir, 'src/generated-schema.ts'), `import { integer, jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core';
 ${storageTables}${billingTables}`);
-    writeFile(path.join(dir, 'src/app-schema.ts'), `import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';
+    const itemOwnerColumn = options.features.auth ? "  userId: text('user_id').notNull(),\n" : '';
+    const itemIndexes = options.features.auth
+        ? "}, (table) => [\n  index('items_user_created_at_idx').on(table.userId, table.createdAt),\n]"
+        : '\n}';
+    writeFile(path.join(dir, 'src/app-schema.ts'), `import { ${options.features.auth ? 'index, ' : ''}pgTable, text, timestamp } from 'drizzle-orm/pg-core';
 
 // Product-owned tables belong here. Anhedral never rewrites this file after creation.
 export const items = pgTable('items', {
   id: text('id').primaryKey(),
-  name: text('name').notNull(),
+${itemOwnerColumn}  name: text('name').notNull(),
   createdAt: timestamp('created_at').defaultNow().notNull(),
-});
+${itemIndexes});
 `);
     writeFile(path.join(dir, 'src/schema.ts'), `export * from './generated-schema';
 export * from './app-schema';
@@ -420,6 +424,62 @@ export class ApiClient {
 }
 `;
 }
+function appContractSource(options) {
+    if (!options.features.database) {
+        return `// Product-owned network contracts belong here.
+// Anhedral never rewrites this file after creation.
+export {};
+`;
+    }
+    return `import { z } from 'zod';
+
+// A complete starter feature: edit or replace it with your product model.
+export const ItemSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().trim().min(1).max(120),
+  createdAt: z.string().datetime(),
+});
+export const ItemListSchema = z.array(ItemSchema);
+export const CreateItemRequestSchema = z.object({
+  name: z.string().trim().min(1).max(120),
+}).strict();
+
+export type Item = z.infer<typeof ItemSchema>;
+export type CreateItemRequest = z.infer<typeof CreateItemRequestSchema>;
+`;
+}
+function appApiClientSource(options) {
+    if (!options.features.database) {
+        return `// Product-owned API client helpers belong here.
+// Anhedral never rewrites this file after creation.
+export {};
+`;
+    }
+    return `import {
+  CreateItemRequestSchema,
+  ItemListSchema,
+  ItemSchema,
+  type CreateItemRequest,
+} from '@shared/contracts';
+import { ApiClient } from './generated';
+
+export type { Item } from '@shared/contracts';
+
+// These calls complete the starter feature across contracts, API, database, and clients.
+export function listItems(client: ApiClient, init: RequestInit = {}) {
+  return client.request('/items', init, ItemListSchema);
+}
+
+export function createItem(client: ApiClient, input: CreateItemRequest, init: RequestInit = {}) {
+  const body = CreateItemRequestSchema.parse(input);
+  return client.request('/items', {
+    ...init,
+    method: 'POST',
+    body: JSON.stringify(body),
+  }, ItemSchema);
+}
+`;
+}
 function writeApiPackages(root, options) {
     if (!options.apps.api)
         return;
@@ -444,10 +504,7 @@ function writeApiPackages(root, options) {
         }, null, 2) + '\n');
         writeTsConfig(dir);
         writeFile(path.join(dir, 'src/generated.ts'), source);
-        writeFile(path.join(dir, 'src/app.ts'), `// Product-owned ${name === 'contracts' ? 'network contracts' : 'API client helpers'} belong here.
-// Anhedral never rewrites this file after creation.
-export {};
-`);
+        writeFile(path.join(dir, 'src/app.ts'), name === 'contracts' ? appContractSource(options) : appApiClientSource(options));
         writeFile(path.join(dir, 'src/index.ts'), `export * from './generated';
 export * from './app';
 `);

package/dist/templates/web.d.ts

@@ -1,2 +1,2 @@
-import type { ProjectOptions } from '../scaffold.js';
+import type { ProjectOptions } from '../project.js';
 export declare function scaffoldWeb(root: string, options: ProjectOptions): Promise<void>;

package/dist/templates/web.js

@@ -137,10 +137,10 @@ function normalizeWebApiBaseUrl(value: string): string {
   if (candidate.startsWith('//') || candidate.includes('\\\\')) {
     throw new Error('NEXT_PUBLIC_API_URL must be a single-slash root-relative path or an absolute URL');
   }
-  if (typeof window === 'undefined') {
-    throw new Error('A root-relative NEXT_PUBLIC_API_URL can only be resolved in the browser');
-  }
-  return normalizeApiBaseUrl(new URL(candidate, window.location.origin).toString(), 'NEXT_PUBLIC_API_URL');
+  // Client components also render during Next.js builds. The server-only origin is
+  // never requested; hydration recreates the client with the browser's real origin.
+  const origin = typeof window === 'undefined' ? 'http://localhost' : window.location.origin;
+  return normalizeApiBaseUrl(new URL(candidate, origin).toString(), 'NEXT_PUBLIC_API_URL');
 }
 
 function apiBaseUrl(): string {
@@ -148,7 +148,8 @@ function apiBaseUrl(): string {
   const candidate = configured || (process.env.NODE_ENV === 'development' ? 'http://localhost:8787/api' : '/api');
   const normalized = normalizeWebApiBaseUrl(candidate);
   const url = new URL(normalized);
-  if (process.env.NODE_ENV === 'production' && url.protocol !== 'https:') {
+  const loopback = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]';
+  if (process.env.NODE_ENV === 'production' && url.protocol !== 'https:' && !loopback) {
     throw new Error('NEXT_PUBLIC_API_URL must use https: in production');
   }
   return normalized;
@@ -161,8 +162,8 @@ export function createApiClient(getToken?: () => Promise<string | null>) {
   });
 }
 `);
-    if (options.apps.api && options.features.auth) {
-        writeFile(path.join(dir, 'hooks/use-api-client.ts'), `'use client';
+    if (options.apps.api) {
+        writeFile(path.join(dir, 'hooks/use-api-client.ts'), options.features.auth ? `'use client';
 
 import { useAuth } from '@clerk/nextjs';
 import { useMemo } from 'react';
@@ -172,6 +173,120 @@ export function useApiClient() {
   const { getToken } = useAuth();
   return useMemo(() => createApiClient(() => getToken()), [getToken]);
 }
+` : `'use client';
+
+import { useMemo } from 'react';
+import { createApiClient } from '@/lib/api';
+
+export function useApiClient() {
+  return useMemo(() => createApiClient(), []);
+}
+`);
+    }
+    if (options.apps.api && options.features.database) {
+        const authImport = options.features.auth ? "import { useAuth } from '@clerk/nextjs';\n" : '';
+        const authState = options.features.auth ? '  const { isLoaded, isSignedIn, userId } = useAuth();\n' : '';
+        const identityState = options.features.auth
+            ? '  const identity = isLoaded && isSignedIn ? userId ?? null : null;\n'
+            : "  const identity = 'public';\n";
+        const authGuard = options.features.auth
+            ? `  if (!isLoaded || (isSignedIn && !userId)) return <p className="text-sm text-muted-foreground">Loading account…</p>;
+  if (!isSignedIn) return <p className="text-sm text-muted-foreground">Sign in to use the working starter feature.</p>;
+
+`
+            : '';
+        writeFile(path.join(dir, 'components/item-list.tsx'), `'use client';
+
+import { createItem, listItems, type Item } from '@shared/api-client';
+${authImport}import * as React from 'react';
+import { useApiClient } from '@/hooks/use-api-client';
+import { Button } from '@/components/ui/button';
+
+export function ItemList() {
+${authState}${identityState}  const api = useApiClient();
+  const [items, setItems] = React.useState<Item[]>([]);
+  const [loadedIdentity, setLoadedIdentity] = React.useState<string | null>(null);
+  const [name, setName] = React.useState('');
+  const [status, setStatus] = React.useState<'loading' | 'ready' | 'saving'>('loading');
+  const [error, setError] = React.useState<string | null>(null);
+  const identityRef = React.useRef(identity);
+  const visibleItems = loadedIdentity === identity ? items : [];
+  const visibleError = loadedIdentity === identity ? error : null;
+  const isLoading = status === 'loading' || loadedIdentity !== identity;
+
+  React.useEffect(() => {
+    identityRef.current = identity;
+    if (!identity) return;
+    let active = true;
+    setLoadedIdentity(identity);
+    setItems([]);
+    setName('');
+    setError(null);
+    setStatus('loading');
+    void listItems(api).then((nextItems) => {
+      if (active) setItems(nextItems);
+    }).catch((cause: unknown) => {
+      if (active) setError(cause instanceof Error ? cause.message : 'Unable to load items');
+    }).finally(() => {
+      if (active) setStatus('ready');
+    });
+    return () => { active = false; };
+  }, [api, identity]);
+
+  async function submit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const nextName = name.trim();
+    if (!identity || !nextName || status !== 'ready' || loadedIdentity !== identity) return;
+    const submittedIdentity = identity;
+    setStatus('saving');
+    try {
+      const created = await createItem(api, { name: nextName });
+      if (identityRef.current !== submittedIdentity) return;
+      setItems((current) => [created, ...current]);
+      setName('');
+      setError(null);
+    } catch (cause) {
+      if (identityRef.current === submittedIdentity) {
+        setError(cause instanceof Error ? cause.message : 'Unable to create item');
+      }
+    } finally {
+      if (identityRef.current === submittedIdentity) setStatus('ready');
+    }
+  }
+
+${authGuard}  return (
+    <div className="space-y-4">
+      <form className="flex gap-2" onSubmit={(event) => void submit(event)}>
+        <label className="sr-only" htmlFor="item-name">Item name</label>
+        <input
+          id="item-name"
+          className="h-9 flex-1 rounded-md border border-input bg-background px-3 text-sm"
+          maxLength={120}
+          onChange={(event) => setName(event.target.value)}
+          placeholder="Your first item"
+          value={name}
+        />
+        <Button disabled={status !== 'ready' || loadedIdentity !== identity || !name.trim()} type="submit">
+          {status === 'saving' ? 'Adding…' : 'Add item'}
+        </Button>
+      </form>
+      {visibleError ? (
+        <p className="text-sm text-red-700" role="alert">
+          {visibleError}. Check DATABASE_URL, run pnpm db:migrate, and make sure the API is running.
+        </p>
+      ) : null}
+      {isLoading ? <p className="text-sm text-muted-foreground">Loading items…</p> : null}
+      {!isLoading && visibleItems.length === 0 && !visibleError
+        ? <p className="text-sm text-muted-foreground">Your database is connected. Add the first item.</p>
+        : null}
+      {visibleItems.length > 0 ? (
+        <ul className="divide-y rounded-md border">
+          {visibleItems.map((item) => <li className="px-3 py-2 text-sm" key={item.id}>{item.name}</li>)}
+        </ul>
+      ) : null}
+    </div>
+  );
+}
 `);
     }
     if (options.features.billing) {
@@ -185,39 +300,62 @@ import { useApiClient } from './use-api-client';
 export function useEntitlement() {
   const api = useApiClient();
   const { isLoaded, isSignedIn, userId } = useAuth();
+  const identity = isLoaded && isSignedIn ? userId : null;
   const [state, setState] = React.useState<Awaited<ReturnType<typeof api.getEntitlement>> | null>(null);
+  const [loadedIdentity, setLoadedIdentity] = React.useState<string | null>(null);
   const [error, setError] = React.useState<string | null>(null);
   const revision = React.useRef(0);
+  const identityRef = React.useRef(identity);
   const refresh = React.useCallback(async () => {
-    if (!isLoaded || !isSignedIn) return;
+    if (!identity) return;
     try {
       const next = await api.getEntitlement();
+      if (identityRef.current !== identity) return;
       revision.current = Math.max(revision.current, next.revision);
       setState(next);
+      setLoadedIdentity(identity);
       setError(null);
     } catch (cause) {
+      if (identityRef.current !== identity) return;
+      setLoadedIdentity(identity);
       setError(cause instanceof Error ? cause.message : 'Unable to load subscription');
     }
-  }, [api, isLoaded, isSignedIn]);
+  }, [api, identity]);
 
-  React.useEffect(() => { void refresh(); }, [refresh]);
+  React.useEffect(() => {
+    identityRef.current = identity;
+    revision.current = 0;
+    setState(null);
+    setLoadedIdentity(null);
+    setError(null);
+    void refresh();
+  }, [identity, refresh]);
   React.useEffect(() => {
     const onVisibility = () => { if (document.visibilityState === 'visible') void refresh(); };
     document.addEventListener('visibilitychange', onVisibility);
     return () => document.removeEventListener('visibilitychange', onVisibility);
   }, [refresh]);
   React.useEffect(() => {
-    if (!userId || !isSignedIn) return;
+    if (!identity) return;
     return subscribeToSubscriptionChanges({
-      userId,
+      userId: identity,
       getTokenRequest: () => api.getRealtimeToken(),
       onChange: (nextRevision) => {
         if (nextRevision > revision.current) void refresh();
       },
-      onError: (cause) => setError(cause.message),
+      onError: (cause) => {
+        if (identityRef.current === identity) {
+          setLoadedIdentity(identity);
+          setError(cause.message);
+        }
+      },
     });
-  }, [api, isSignedIn, refresh, userId]);
-  return { entitlement: state, error, refresh };
+  }, [api, identity, refresh]);
+  return {
+    entitlement: loadedIdentity === identity ? state : null,
+    error: loadedIdentity === identity ? error : null,
+    refresh,
+  };
 }
 `);
         writeFile(path.join(dir, 'components/subscription-status.tsx'), `'use client';
@@ -303,12 +441,22 @@ function writeAppFiles(dir, options) {
         ? "import { AccountActions } from '@/components/account-actions';\n"
         : '';
     const accountAction = options.features.auth
-        ? `{process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY ? (
+        ? `{process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY && !process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.includes('***') ? (
             <AccountActions />
           ) : (
             <Button variant="outline" disabled>Configure Clerk to sign in</Button>
           )}`
-        : '<Button variant="outline">View account</Button>';
+        : '';
+    const starterLink = options.apps.api && options.features.database
+        ? '<a className="inline-flex h-9 items-center justify-center rounded-md bg-primary px-4 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90" href="#starter-feature">Open starter feature</a>'
+        : '';
+    const heroActions = starterLink || accountAction
+        ? `        <div className="flex gap-3">
+          ${starterLink}
+          ${accountAction}
+        </div>
+`
+        : '';
     const clerkStyles = options.features.auth ? '@import "@clerk/ui/themes/shadcn.css";\n' : '';
     writeFile(path.join(dir, 'app/globals.css'), `@import "tailwindcss";
 ${clerkStyles}
@@ -352,7 +500,7 @@ body {
         : '';
     const providers = options.features.auth ? `function Providers({ children }: Readonly<{ children: React.ReactNode }>) {
   const publishableKey = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY;
-  if (!publishableKey) return <>{children}</>;
+  if (!publishableKey || publishableKey.includes('***')) return <>{children}</>;
   return <ClerkProvider publishableKey={publishableKey} appearance={{ theme: shadcn }}>{children}</ClerkProvider>;
 }` : `function Providers({ children }: Readonly<{ children: React.ReactNode }>) {
   return <>{children}</>;
@@ -378,11 +526,23 @@ export default function RootLayout({ children }: Readonly<{ children: React.Reac
 }
 `);
     const subscriptionImport = options.features.billing ? "import { SubscriptionStatus } from '@/components/subscription-status';\n" : '';
+    const itemListImport = options.apps.api && options.features.database ? "import { ItemList } from '@/components/item-list';\n" : '';
     const subscriptionStatus = options.features.billing
-        ? '        {process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY ? <SubscriptionStatus /> : null}\n'
+        ? "        {process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY && !process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.includes('***') ? <SubscriptionStatus /> : null}\n"
         : '';
-    writeFile(path.join(dir, 'app/page.tsx'), `${accountActionsImport}${subscriptionImport}import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
-import { Button } from '@/components/ui/button';
+    const starterContent = options.apps.api && options.features.database
+        ? options.features.auth
+            ? `{process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY && !process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.includes('***')
+            ? <ItemList />
+            : <p>Configure Clerk to activate the starter feature.</p>}`
+            : '<ItemList />'
+        : options.apps.api
+            ? 'Contracts, API access, and configuration are shared through workspace packages.'
+            : 'Add modules later with pnpm anhedral:add; user-owned source remains untouched.';
+    const starterTitle = options.apps.api && options.features.database ? 'Working starter feature' : 'Shared modules';
+    const buttonImport = options.features.auth ? "import { Button } from '@/components/ui/button';\n" : '';
+    writeFile(path.join(dir, 'app/page.tsx'), `${accountActionsImport}${subscriptionImport}${itemListImport}import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+${buttonImport}
 
 export default function Home() {
   return (
@@ -392,17 +552,14 @@ export default function Home() {
         <p className="max-w-2xl text-muted-foreground">
           ${options.apps.api ? 'Next.js + shadcn/ui web client connected to the shared Fastify API.' : 'Next.js + shadcn/ui web application.'}
         </p>
-        <div className="flex gap-3">
-          <Button>Open app</Button>
-          ${accountAction}
-        </div>
+${heroActions}
 ${subscriptionStatus}      </section>
-      <Card>
+      <Card id="starter-feature">
         <CardHeader>
-          <CardTitle>Shared modules</CardTitle>
+          <CardTitle>${starterTitle}</CardTitle>
         </CardHeader>
         <CardContent className="text-sm text-muted-foreground">
-          ${options.apps.api ? 'Contracts, API access, and configuration are shared through workspace packages.' : 'Add modules later with anhedral add; user-owned source remains untouched.'}
+          ${starterContent}
         </CardContent>
       </Card>
     </main>

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by tests/release checks. */
-export declare const GENERATOR_VERSION = "0.4.1";
+export declare const GENERATOR_VERSION = "0.4.2";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by tests/release checks. */
-export const GENERATOR_VERSION = '0.4.1';
+export const GENERATOR_VERSION = '0.4.2';

package/docs/NORTHSTAR.md

@@ -0,0 +1,114 @@
+# Anhedral DX north star
+
+## One command in. A working product foundation out.
+
+Anhedral should let a developer choose the surfaces and capabilities their idea
+needs, generate one understandable TypeScript workspace, and reach a working
+feature without first becoming an expert in every framework and provider.
+
+The generated application must feel like a project the developer wrote
+themselves:
+
+- ordinary framework source, package scripts, environment files, and tests;
+- one shared contract and API client across every selected surface;
+- working vertical slices instead of disconnected demonstrations;
+- safe, inspectable structural changes with no hidden runtime or control plane;
+- a clear path from first run to production without changing architecture; and
+- built-in scale through managed, autoscaling providers rather than custom
+  infrastructure.
+
+Anhedral succeeds when developers spend their time on the product idea, not on
+repeating setup, reconciling integrations, or reverse-engineering generated
+code.
+
+## Product principles
+
+### Fast to first value
+
+A developer should understand the choices before generation, see the resolved
+dependency closure, and know the next command when generation finishes.
+`pnpm first-run` prepares local configuration without overwriting it.
+`pnpm ready` answers whether required configuration is complete without
+revealing values. `pnpm verify` proves the source and selected integrations
+build.
+
+### Build once, ship everywhere
+
+Contracts, validation, API calls, authentication, persistence, and product
+behavior should be shared where the platforms permit it. Every selected client
+should receive an idiomatic UI for the same starter feature so the developer can
+prove the whole path on web, iOS, Android, desktop, and browser extension
+surfaces before replacing it with their idea.
+
+### Explicit composition
+
+The CLI must distinguish what the developer requested from what dependencies
+added. Interactive and automated use must produce the same canonical module
+closure. Complete-stack generation is explicit with `--all`; focused stacks
+remain first-class.
+
+### Safe evolution
+
+`add`, `ui add`, and `upgrade` must be transactional, previewable, deterministic,
+and ownership-aware. They may merge known configuration and replace unmodified
+managed substrate, but must never silently overwrite product code. `doctor`
+must explain drift and give a concrete recovery action.
+
+### Production-shaped from the start
+
+Development and production use the same package boundaries and provider
+integrations. Environment examples may contain placeholders, but generated
+applications must identify them before launch. Secrets stay server-side and
+uncommitted. Deployment guidance is specific to the selected stack and does not
+claim resources already exist.
+
+### Human and automation parity
+
+Human output should be concise and actionable. `--json` should provide one clean,
+stable document with the same resolved modules, plans, outcomes, and next steps
+for CI and coding agents. Noninteractive commands must never depend on a prompt.
+
+### Source ownership is the feature
+
+Generated product seams are user-owned and readable. Provider substrate is
+managed only where consistency and security require it. The manifest records
+the boundary, and every lifecycle command honors it.
+
+## Journey contract
+
+| Journey | The developer should experience | Acceptance signal |
+| --- | --- | --- |
+| Discover | Immediately understand cross-platform scope, modularity, cost posture, and ownership | README states the value plainly and links to exact commands |
+| Choose | See app surfaces, capabilities, dependencies, and runtime requirements before writes | Interactive confirmation and `--help` show the canonical resolved stack |
+| Create | Receive deterministic source, optional Git initialization, visible installation progress, and exact next steps | `new`, `init`, dry-run, JSON, skip-install, and Git variants are tested |
+| Configure | Safely create only missing local environment files and identify every unresolved placeholder without printing secrets | `pnpm first-run` is idempotent; `pnpm ready` returns a truthful exit status |
+| Prove | Exercise a real contract → database → API → client → UI feature on every selected surface | Focused and complete generated stacks typecheck, test, and build |
+| Develop | Know where product code belongs and use each framework normally | Generated README, development guide, stack map, and coding-agent skill agree |
+| Extend | Preview and add modules or source-owned UI without losing edits | Dry-run and apply plans are deterministic, transactional, and ownership-safe |
+| Diagnose | Understand generator drift, configuration readiness, and recovery actions | `pnpm ready` reports configuration blockers; `doctor` reports structural issues and actionable recommendations |
+| Upgrade | Move supported projects forward without replacing product seams | Upgrade is transactional, no-op when current, and tested from supported versions |
+| Ship | Follow selection-specific steps from previews to production and stores | Generated production guide and exact package scripts cover every selected target |
+| Automate | Consume stable output and releases without scraping terminal prose | JSON remains parseable; successful `main` CI prepares the next patch release |
+
+## Definition of done
+
+A change is complete only when:
+
+1. focused and complete module topologies generate deterministically;
+2. generated environment setup is idempotent and readiness checks are truthful;
+3. the shared starter feature reaches every selected compatible client;
+4. generated code typechecks, tests, builds, and passes runtime acceptance where
+   the platform is available;
+5. dry-run, JSON, no-op, failure, rollback, and recovery paths are covered;
+6. source ownership survives `add`, `ui add`, and `upgrade`;
+7. packed npm output behaves the same as repository source;
+8. security, dependency, secret, PII, source-hygiene, and release-policy checks
+   pass; and
+9. documentation describes the behavior that was actually verified.
+
+## Deliberate boundaries
+
+Anhedral does not hide provider accounts, fabricate credentials, submit paid or
+review-gated releases, run a proprietary application runtime, or own product
+code after generation. Those boundaries keep the output understandable,
+portable, and under the developer's control.

package/docs/conventions.md

@@ -60,8 +60,8 @@ Clerk owns identity and sessions. The API derives identity from a verified serve
 DOM clients use source-owned shadcn/ui components. Expo uses React Native Reusables with the selected NativeWind or Uniwind configuration.
 
 ```sh
-anhedral ui add button dialog
-anhedral ui add data-table --target web
+pnpm anhedral:ui button dialog
+pnpm anhedral:ui data-table --target web
 ```
 
 Generated UI files are application source and can be customized. Preserve accessibility, keyboard/focus behavior, and platform conventions.
@@ -76,7 +76,7 @@ Generated UI files are application source and can be customized. Preserve access
 
 ## Structural changes
 
-Run `anhedral doctor` before changing generated structure. Preview new modules or UI with `--dry-run`. Anhedral refuses managed-file drift, symlinks, and unowned collisions instead of overwriting source.
+Run `pnpm anhedral:doctor` before changing generated structure. Preview new modules or UI with `--dry-run`. Anhedral refuses managed-file drift, symlinks, and unowned collisions instead of overwriting source.
 
 Application product files are developer-owned. `README.md` and `PRODUCTION.md` become user-owned after initialization. Root configuration is mergeable. Integration substrate and generated guidance are recorded in `anhedral.json`.
 
@@ -85,8 +85,10 @@ Application product files are developer-owned. `README.md` and `PRODUCTION.md` b
 Run the smallest relevant package check while iterating, then the generated root verification before handoff:
 
 ```sh
+pnpm first-run
+pnpm ready
 pnpm typecheck
 pnpm verify
 pnpm build
-anhedral doctor
+pnpm anhedral:doctor
 ```

package/docs/engineering-principles.md

@@ -0,0 +1,88 @@
+# The Zen of Anhedral
+
+Anhedral applies the spirit of Tim Peters' *Zen of Python* to a TypeScript stack
+generator. This is an engineering policy, not a preference for Python syntax.
+The goal is generated software whose behavior, ownership, and failure modes are
+easy to see.
+
+## Working rules
+
+1. **Make the result readable.** Generated source should look like ordinary,
+   idiomatic framework code. Prefer clear names and small seams over clever
+   abstractions or compressed templates.
+2. **Make choices explicit.** Keep requested modules distinct from dependencies
+   added by resolution. Record ownership, toolchain, template provenance, and
+   planned writes. Never infer permission to replace product code.
+3. **Keep one source of truth.** Module identity and kind belong to the
+   architecture registry. Project shape belongs to the project model. CLI,
+   templates, manifests, and docs consume those definitions instead of
+   restating them.
+4. **Choose the smallest complete design.** A simple vertical slice is better
+   than a generic subsystem. Real provider complexity may be necessary, but it
+   must stay behind a narrow, named boundary.
+5. **Prefer flat control flow.** Validate early, return early, and dispatch once.
+   Split orchestration, domain rules, rendering, filesystem transactions, and
+   process execution into distinct namespaces.
+6. **Generate sparsely.** A selected stack receives what it needs. Unselected
+   apps and providers must not leave dead packages, environment variables,
+   scripts, or documentation behind.
+7. **Treat rules uniformly.** Add module dependencies and conflicts to the
+   registry; do not scatter special-case resolution across commands. Introduce
+   an exception only when the practical behavior is clearer and it is covered
+   by a regression test.
+8. **Never hide failure.** Invalid input, drift, child-process failure, partial
+   configuration, and unsafe writes must produce a useful error and nonzero
+   status. An intentionally ignored failure must be named, local, and tested.
+9. **Do not guess through ambiguity.** Reject unknown commands, conflicting
+   edits, unowned collisions, unsafe paths, and unsupported project versions.
+   Interactive choices require confirmation; noninteractive behavior must be
+   deterministic.
+10. **Provide one obvious path.** Use `new` or `init` to create, `add` for
+    modules, `ui add` for source-owned UI, `upgrade` for schema evolution, and
+    `doctor` for drift. Generated projects use `first-run`, `ready`, `verify`,
+    and then `dev`.
+11. **Ship deliberate increments.** Finish a small explainable change now when
+    its behavior is proven. Defer a broad abstraction until it has a concrete
+    caller and an acceptance test.
+12. **Make explanation a design test.** If a change cannot be summarized as
+    input → decision → observable result, simplify it before merging.
+
+## Namespace boundaries
+
+```text
+CLI parsing and presentation
+    -> architecture and project model
+    -> scaffold orchestration and transactions
+    -> templates and configuration composers
+    -> generated framework source
+```
+
+- `src/architecture/` owns module resolution, plans, manifests, and composition
+  invariants.
+- `src/project.ts` owns the template-facing project shape.
+- `src/scaffold.ts` coordinates lifecycle operations; it must not become the
+  source of domain types or embed unrelated templates.
+- `src/templates/` renders selected framework and lifecycle files.
+- `src/transaction.ts` owns safe application and rollback.
+- `src/bin.ts`, `src/cli.ts`, and `src/prompts.ts` own user input and output.
+
+Dependencies point toward the model, not back toward the orchestrator. A
+template may depend on `ProjectOptions`; it should not depend on the scaffold
+command that called it.
+
+## Review questions
+
+Before merging, answer these plainly:
+
+- Where is the single authoritative definition for this behavior?
+- What input is explicit, what is derived, and is that distinction observable?
+- Does the happy path read top-to-bottom without hidden mutation?
+- What ambiguity or failure can occur, and how does the user see it?
+- Does the change add output for an unselected module?
+- Can an existing user-owned file be overwritten or silently reclassified?
+- Is there a focused test for the rule and a broader test for the journey?
+- Can the implementation be explained in a short paragraph?
+
+Practicality still wins: duplicated literal output inside generated framework
+code can be clearer than a generator-only abstraction. The burden is on an
+abstraction to remove real ambiguity or repetition without hiding behavior.