anhedral 0.1.10 → 0.4.0

package/dist/workspace-config.js

@@ -0,0 +1,372 @@
+import { lstatSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { SECURITY_OVERRIDES } from './dependencies.js';
+import { writeFile } from './util.js';
+function pathEntryExists(target) {
+    try {
+        lstatSync(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export function desiredWorkspacePolicy() {
+    return {
+        overrides: { ...SECURITY_OVERRIDES },
+        onlyBuiltDependencies: ['electron', 'esbuild', 'sharp'],
+        ignoredBuiltDependencies: [
+            'browser-tabs-lock',
+            'bufferutil',
+            'core-js',
+            'electron-winstaller',
+            'spawn-sync',
+            'utf-8-validate',
+        ],
+        peerDependencyRules: {
+            ignoreMissing: ['@solana/web3.js', 'bs58', 'react-native'],
+            allowedVersions: {
+                esbuild: '>=0.25.0',
+                'utf-8-validate': '>=5.0.2',
+            },
+        },
+    };
+}
+// Managed pnpm policy intentionally supports only scalar maps and string lists. More complex YAML
+// is left untouched outside managed sections and rejected inside them instead of being guessed at.
+function sourceLines(content) {
+    const lines = [];
+    let start = 0;
+    while (start < content.length) {
+        let cursor = start;
+        while (cursor < content.length && content[cursor] !== '\n' && content[cursor] !== '\r')
+            cursor += 1;
+        const text = content.slice(start, cursor);
+        if (content[cursor] === '\r' && content[cursor + 1] === '\n')
+            cursor += 2;
+        else if (cursor < content.length)
+            cursor += 1;
+        lines.push({ text, start, end: cursor });
+        start = cursor;
+    }
+    return lines;
+}
+function workspaceNewline(content) {
+    return content.includes('\r\n') ? '\r\n' : content.includes('\r') ? '\r' : '\n';
+}
+function parseWorkspaceStringScalar(raw) {
+    const leading = /^[ \t]*/.exec(raw)?.[0].length ?? 0;
+    const valueAndComment = raw.slice(leading);
+    if (!valueAndComment)
+        return null;
+    const singleQuoted = /^'((?:[^']|'')*)'([ \t]*(?:#.*)?)$/.exec(valueAndComment);
+    if (singleQuoted) {
+        return {
+            value: singleQuoted[1].replaceAll("''", "'"),
+            tokenStart: leading,
+            tokenEnd: leading + singleQuoted[0].length - singleQuoted[2].length,
+        };
+    }
+    if (valueAndComment.startsWith("'"))
+        return null;
+    const doubleQuoted = /^("(?:[^"\\]|\\.)*")([ \t]*(?:#.*)?)$/.exec(valueAndComment);
+    if (doubleQuoted) {
+        try {
+            const value = JSON.parse(doubleQuoted[1]);
+            return typeof value === 'string'
+                ? { value, tokenStart: leading, tokenEnd: leading + doubleQuoted[1].length }
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (valueAndComment.startsWith('"'))
+        return null;
+    const comment = /[ \t]+#/.exec(valueAndComment);
+    const withoutComment = valueAndComment.slice(0, comment?.index ?? valueAndComment.length).trimEnd();
+    if (!withoutComment || /^[\[{|>&*!]/.test(withoutComment))
+        return null;
+    if (/^(?:null|~|true|false|[-+]?(?:\.inf|\.nan|0x[\da-f]+|0o[0-7]+|\d+(?:\.\d+)?(?:e[-+]?\d+)?))$/i.test(withoutComment)) {
+        return null;
+    }
+    return { value: withoutComment, tokenStart: leading, tokenEnd: leading + withoutComment.length };
+}
+function parseWorkspaceMapLine(line) {
+    const indent = /^([ \t]*)/.exec(line)?.[1] ?? '';
+    const body = line.slice(indent.length);
+    let match = /^'((?:[^']|'')*)'[ \t]*:/.exec(body);
+    let key;
+    if (match)
+        key = match[1].replaceAll("''", "'");
+    else {
+        match = /^("(?:[^"\\]|\\.)*")[ \t]*:/.exec(body);
+        if (match) {
+            try {
+                const parsed = JSON.parse(match[1]);
+                if (typeof parsed !== 'string')
+                    return null;
+                key = parsed;
+            }
+            catch {
+                return null;
+            }
+        }
+        else {
+            match = /^([^:#][^:]*?)[ \t]*:/.exec(body);
+            if (!match)
+                return null;
+            key = match[1].trim();
+            if (!key || key.includes('#'))
+                return null;
+        }
+    }
+    const restOffset = indent.length + match[0].length;
+    return { indent, key, rest: line.slice(restOffset), restOffset };
+}
+function parseWorkspaceListLine(line) {
+    const match = /^([ \t]+)-[ \t]+(.+)$/.exec(line);
+    if (!match)
+        return null;
+    const scalar = parseWorkspaceStringScalar(match[2]);
+    return scalar ? { indent: match[1], value: scalar.value } : null;
+}
+function quoteWorkspaceString(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function workspaceLineIndent(line) {
+    if (!line.trim() || line.trimStart().startsWith('#'))
+        return null;
+    return /^([ \t]*)/.exec(line)?.[1] ?? '';
+}
+function workspaceBlockAt(lines, keyLineIndex) {
+    const keyLine = lines[keyLineIndex];
+    const key = parseWorkspaceMapLine(keyLine.text);
+    if (!key)
+        throw new Error('pnpm-workspace.yaml contains an unsupported mapping key.');
+    if (key.indent.includes('\t'))
+        throw new Error('pnpm-workspace.yaml managed sections must use spaces for indentation.');
+    let sectionEndIndex = lines.length;
+    for (let index = keyLineIndex + 1; index < lines.length; index += 1) {
+        const indent = workspaceLineIndent(lines[index].text);
+        if (indent !== null && indent.length <= key.indent.length) {
+            sectionEndIndex = index;
+            break;
+        }
+    }
+    return { lines, keyLineIndex, sectionEndIndex, keyLine, key };
+}
+function findTopLevelWorkspaceBlock(content, key) {
+    const lines = sourceLines(content);
+    const matches = lines.flatMap((line, index) => {
+        const parsed = parseWorkspaceMapLine(line.text);
+        return parsed?.indent === '' && parsed.key === key ? [index] : [];
+    });
+    if (matches.length > 1)
+        throw new Error(`pnpm-workspace.yaml contains duplicate top-level ${key} keys.`);
+    return matches.length === 1 ? workspaceBlockAt(lines, matches[0]) : null;
+}
+function appendWorkspaceLines(content, offset, additions) {
+    if (additions.length === 0)
+        return content;
+    const newline = workspaceNewline(content);
+    const leading = offset > 0 && !/(?:\r\n|\n|\r)$/.test(content.slice(0, offset)) ? newline : '';
+    return `${content.slice(0, offset)}${leading}${additions.join(newline)}${newline}${content.slice(offset)}`;
+}
+function appendTopLevelWorkspaceKey(content, key) {
+    return appendWorkspaceLines(content, content.length, [`${key}:`]);
+}
+function requireWorkspaceBlockValue(block, fieldPath) {
+    if (!/^[ \t]*(?:#.*)?$/.test(block.key.rest)) {
+        throw new Error(`Conflict in ${fieldPath}: expected a block value that can be merged safely.`);
+    }
+}
+function mergeWorkspaceListBlock(content, block, desiredValues, fieldPath) {
+    requireWorkspaceBlockValue(block, fieldPath);
+    const existing = new Set();
+    let indent = `${block.key.indent}  `;
+    let insertionOffset = block.keyLine.end;
+    let foundItem = false;
+    for (let index = block.keyLineIndex + 1; index < block.sectionEndIndex; index += 1) {
+        const line = block.lines[index];
+        if (workspaceLineIndent(line.text) === null)
+            continue;
+        const parsed = parseWorkspaceListLine(line.text);
+        if (!parsed || parsed.indent.includes('\t') || parsed.indent.length <= block.key.indent.length) {
+            throw new Error(`Conflict in ${fieldPath}: expected a simple block list of strings.`);
+        }
+        if (foundItem && parsed.indent !== indent) {
+            throw new Error(`Conflict in ${fieldPath}: list items must use consistent indentation.`);
+        }
+        foundItem = true;
+        indent = parsed.indent;
+        existing.add(parsed.value);
+        insertionOffset = line.end;
+    }
+    const additions = [...new Set(desiredValues)].filter((value) => !existing.has(value));
+    return appendWorkspaceLines(content, insertionOffset, additions.map((value) => `${indent}- ${quoteWorkspaceString(value)}`));
+}
+function ensureTopLevelWorkspaceBlock(content, key) {
+    const existing = findTopLevelWorkspaceBlock(content, key);
+    if (existing)
+        return { content, block: existing };
+    const appended = appendTopLevelWorkspaceKey(content, key);
+    return { content: appended, block: findTopLevelWorkspaceBlock(appended, key) };
+}
+function mergeTopLevelWorkspaceList(content, key, desiredValues) {
+    const ensured = ensureTopLevelWorkspaceBlock(content, key);
+    return mergeWorkspaceListBlock(ensured.content, ensured.block, desiredValues, `pnpm-workspace.yaml ${key}`);
+}
+function mergeWorkspaceMapBlock(content, block, desiredValues, fieldPath, allowGeneratedUpdates) {
+    requireWorkspaceBlockValue(block, fieldPath);
+    const entries = new Map();
+    let indent = `${block.key.indent}  `;
+    let insertionOffset = block.keyLine.end;
+    let foundEntry = false;
+    for (let index = block.keyLineIndex + 1; index < block.sectionEndIndex; index += 1) {
+        const line = block.lines[index];
+        if (workspaceLineIndent(line.text) === null)
+            continue;
+        const parsed = parseWorkspaceMapLine(line.text);
+        if (!parsed || parsed.indent.includes('\t') || parsed.indent.length <= block.key.indent.length) {
+            throw new Error(`Conflict in ${fieldPath}: expected a simple string-to-string mapping.`);
+        }
+        if (foundEntry && parsed.indent !== indent) {
+            throw new Error(`Conflict in ${fieldPath}: mapping entries must use consistent indentation.`);
+        }
+        const scalar = parseWorkspaceStringScalar(parsed.rest);
+        if (!scalar)
+            throw new Error(`Conflict in ${fieldPath}: mapping values must be strings.`);
+        if (entries.has(parsed.key))
+            throw new Error(`Conflict in ${fieldPath}: duplicate mapping entry ${parsed.key}.`);
+        foundEntry = true;
+        indent = parsed.indent;
+        insertionOffset = line.end;
+        entries.set(parsed.key, { line, parsed, scalar });
+    }
+    const additions = [];
+    const replacements = [];
+    for (const [key, desiredValue] of Object.entries(desiredValues)) {
+        const existing = entries.get(key);
+        if (!existing) {
+            additions.push(`${indent}${quoteWorkspaceString(key)}: ${quoteWorkspaceString(desiredValue)}`);
+            continue;
+        }
+        if (existing.scalar.value === desiredValue)
+            continue;
+        if (!allowGeneratedUpdates) {
+            throw new Error(`Conflict in ${fieldPath}: mapping entry ${key} differs from the generated value.`);
+        }
+        replacements.push({
+            start: existing.line.start + existing.parsed.restOffset + existing.scalar.tokenStart,
+            end: existing.line.start + existing.parsed.restOffset + existing.scalar.tokenEnd,
+            value: quoteWorkspaceString(desiredValue),
+        });
+    }
+    let merged = appendWorkspaceLines(content, insertionOffset, additions);
+    for (const replacement of replacements.sort((left, right) => right.start - left.start)) {
+        merged = `${merged.slice(0, replacement.start)}${replacement.value}${merged.slice(replacement.end)}`;
+    }
+    return merged;
+}
+function mergeTopLevelWorkspaceMap(content, key, desiredValues, allowGeneratedUpdates) {
+    const ensured = ensureTopLevelWorkspaceBlock(content, key);
+    return mergeWorkspaceMapBlock(ensured.content, ensured.block, desiredValues, `pnpm-workspace.yaml ${key}`, allowGeneratedUpdates);
+}
+function directChildIndent(block, fieldPath) {
+    let childIndent = null;
+    for (let index = block.keyLineIndex + 1; index < block.sectionEndIndex; index += 1) {
+        const indent = workspaceLineIndent(block.lines[index].text);
+        if (indent === null)
+            continue;
+        if (indent.includes('\t') || indent.length <= block.key.indent.length) {
+            throw new Error(`Conflict in ${fieldPath}: expected an indented mapping.`);
+        }
+        if (childIndent === null || indent.length < childIndent.length)
+            childIndent = indent;
+    }
+    return childIndent ?? `${block.key.indent}  `;
+}
+function findDirectWorkspaceBlock(parent, key, fieldPath) {
+    const childIndent = directChildIndent(parent, fieldPath);
+    const matches = [];
+    for (let index = parent.keyLineIndex + 1; index < parent.sectionEndIndex; index += 1) {
+        const line = parent.lines[index];
+        const indent = workspaceLineIndent(line.text);
+        if (indent === null || indent.length !== childIndent.length)
+            continue;
+        const parsed = parseWorkspaceMapLine(line.text);
+        if (!parsed || parsed.indent !== childIndent) {
+            throw new Error(`Conflict in ${fieldPath}: expected a mapping of named policies.`);
+        }
+        if (parsed.key === key)
+            matches.push(index);
+    }
+    if (matches.length > 1)
+        throw new Error(`Conflict in ${fieldPath}: duplicate ${key} keys.`);
+    return matches.length === 1 ? workspaceBlockAt(parent.lines, matches[0]) : null;
+}
+function ensureDirectWorkspaceBlock(content, parentKey, key, fieldPath) {
+    let parent = findTopLevelWorkspaceBlock(content, parentKey);
+    if (!parent) {
+        content = appendTopLevelWorkspaceKey(content, parentKey);
+        parent = findTopLevelWorkspaceBlock(content, parentKey);
+    }
+    requireWorkspaceBlockValue(parent, `pnpm-workspace.yaml ${parentKey}`);
+    const existing = findDirectWorkspaceBlock(parent, key, fieldPath);
+    if (existing)
+        return { content, block: existing };
+    const indent = directChildIndent(parent, fieldPath);
+    let insertionOffset = parent.keyLine.end;
+    for (let index = parent.keyLineIndex + 1; index < parent.sectionEndIndex; index += 1) {
+        const line = parent.lines[index];
+        if (workspaceLineIndent(line.text) !== null)
+            insertionOffset = line.end;
+    }
+    content = appendWorkspaceLines(content, insertionOffset, [`${indent}${key}:`]);
+    parent = findTopLevelWorkspaceBlock(content, parentKey);
+    return { content, block: findDirectWorkspaceBlock(parent, key, fieldPath) };
+}
+function applyWorkspaceAutoInstallPeers(content, allowGeneratedUpdates) {
+    const block = findTopLevelWorkspaceBlock(content, 'autoInstallPeers');
+    if (!block) {
+        const newline = workspaceNewline(content);
+        const separator = content.length > 0 && !/(?:\r\n|\n|\r)$/.test(content) ? newline : '';
+        return `${content}${separator}autoInstallPeers: false${newline}`;
+    }
+    const scalar = /^([ \t]*)(true|false)([ \t]*(?:#.*)?)$/i.exec(block.key.rest);
+    if (!scalar)
+        throw new Error('Conflict in pnpm-workspace.yaml: autoInstallPeers must be the boolean false.');
+    for (let index = block.keyLineIndex + 1; index < block.sectionEndIndex; index += 1) {
+        if (workspaceLineIndent(block.lines[index].text) !== null) {
+            throw new Error('Conflict in pnpm-workspace.yaml: autoInstallPeers must be a scalar boolean.');
+        }
+    }
+    if (scalar[2].toLowerCase() === 'false')
+        return content;
+    if (!allowGeneratedUpdates) {
+        throw new Error('Conflict in pnpm-workspace.yaml: autoInstallPeers must be false to avoid unsafe optional peer resolution.');
+    }
+    const start = block.keyLine.start + block.key.restOffset + scalar[1].length;
+    return `${content.slice(0, start)}false${content.slice(start + scalar[2].length)}`;
+}
+function applyWorkspacePolicy(content, policy, allowGeneratedUpdates) {
+    let merged = applyWorkspaceAutoInstallPeers(content, allowGeneratedUpdates);
+    merged = mergeTopLevelWorkspaceMap(merged, 'overrides', policy.overrides, allowGeneratedUpdates);
+    merged = mergeTopLevelWorkspaceList(merged, 'onlyBuiltDependencies', policy.onlyBuiltDependencies);
+    merged = mergeTopLevelWorkspaceList(merged, 'ignoredBuiltDependencies', policy.ignoredBuiltDependencies);
+    const ignoreMissing = ensureDirectWorkspaceBlock(merged, 'peerDependencyRules', 'ignoreMissing', 'pnpm-workspace.yaml peerDependencyRules');
+    merged = mergeWorkspaceListBlock(ignoreMissing.content, ignoreMissing.block, policy.peerDependencyRules.ignoreMissing, 'pnpm-workspace.yaml peerDependencyRules.ignoreMissing');
+    const allowedVersions = ensureDirectWorkspaceBlock(merged, 'peerDependencyRules', 'allowedVersions', 'pnpm-workspace.yaml peerDependencyRules');
+    return mergeWorkspaceMapBlock(allowedVersions.content, allowedVersions.block, policy.peerDependencyRules.allowedVersions, 'pnpm-workspace.yaml peerDependencyRules.allowedVersions', allowGeneratedUpdates);
+}
+export function mergeWorkspaceFile(root, desiredPackages, policy, allowGeneratedUpdates) {
+    const filePath = path.join(root, 'pnpm-workspace.yaml');
+    const current = pathEntryExists(filePath) ? readFileSync(filePath, 'utf8') : '';
+    let merged = mergeTopLevelWorkspaceList(current, 'packages', desiredPackages);
+    merged = applyWorkspacePolicy(merged, policy, allowGeneratedUpdates);
+    if (merged !== current || !pathEntryExists(filePath))
+        writeFile(filePath, merged);
+}

package/docs/conventions.md

@@ -0,0 +1,92 @@
+# Anhedral generated-project conventions
+
+Anhedral is a deterministic stack generator. These conventions describe the readable workspace it produces; they are not a new application framework or runtime API.
+
+## Core rule
+
+Use the underlying tool's normal programming model. Anhedral decides where integrations meet and generates safe defaults, but developers write ordinary Next.js, Expo Router, Fastify, Drizzle, Electron, and WXT code.
+
+## Source ownership
+
+```text
+apps/       deployable framework applications
+packages/   client-safe or server-shared TypeScript packages
+docs/       generated stack and development guidance
+```
+
+- `apps/web`: Next.js App Router pages, layouts, components, hooks, and web utilities.
+- `apps/mobile`: Expo Router screens, layouts, native components, and hooks.
+- `apps/api`: Fastify routes, services, plugins, provider clients, and server environment validation.
+- `apps/desktop`: Electron main/preload code and sandboxed React renderer code.
+- `apps/desktop-updater-worker`: optional read-only Cloudflare Worker serving signed Electron updates from a bound private R2 bucket.
+- `apps/extension`: WXT entrypoints, extension components, background logic, and content scripts.
+- `packages/contracts`: Zod schemas for data crossing HTTP boundaries.
+- `packages/api-client`: client-safe HTTP behavior shared across frontends.
+- `packages/db`: Drizzle schema, database access, and reviewed SQL migrations.
+- `packages/realtime`: client-safe Ably subscription behavior when selected.
+
+## End-to-end feature flow
+
+```text
+Zod contract
+    -> Drizzle schema/query or server service
+    -> Fastify route
+    -> shared API client
+    -> Next.js / Expo / Electron / WXT UI
+```
+
+Routes stay thin. They authenticate, validate, call a service, and return a declared contract. Business behavior and provider SDK calls live in server services. Frontends never import API services, database connections, or server environment modules.
+
+When `electron-updater` is selected, desktop releases follow a separate delivery path: the packaged Electron main process reads generated update metadata from an HTTPS custom domain, the Worker streams known keys from its private R2 binding, and release tooling uploads signed artifacts before mutable channel metadata. Neither Cloudflare credentials nor a public bucket URL enter the desktop application.
+
+## Database
+
+Database-enabled projects use managed Neon Postgres. Anhedral does not generate local Postgres, Docker Compose, or an embedded database substitute.
+
+1. Edit the user-owned `packages/db/src/app-schema.ts`; Anhedral keeps provider tables in `generated-schema.ts`.
+2. Run `pnpm db:generate`.
+3. Review and commit generated SQL and metadata.
+4. Run `pnpm verify:db`.
+5. Apply with `pnpm db:migrate` against the intended Neon branch or project.
+
+Schema generation must not happen during an application build. Migrations are reviewed release artifacts.
+
+## Authentication and secrets
+
+Clerk owns identity and sessions. The API derives identity from a verified server session and never trusts a client-supplied user ID. Only variables with a framework's explicit public prefix may enter client bundles. Database, Clerk secret, R2, RevenueCat, Ably, cron, and provider credentials remain server-only.
+
+## UI
+
+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
+```
+
+Generated UI files are application source and can be customized. Preserve accessibility, keyboard/focus behavior, and platform conventions.
+
+## Naming
+
+- Directories and source files use lowercase kebab-case.
+- React component filenames use kebab-case and export PascalCase components.
+- Hooks start with `use-`.
+- Framework-required entrypoint names stay unchanged.
+- Shared packages use the `@shared/<name>` namespace.
+
+## 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.
+
+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`.
+
+## Verification
+
+Run the smallest relevant package check while iterating, then the generated root verification before handoff:
+
+```sh
+pnpm typecheck
+pnpm verify
+pnpm build
+anhedral doctor
+```

package/docs/master-stack-map.md

@@ -0,0 +1,192 @@
+# Anhedral master stack map
+
+This is the canonical whole-stack map for Anhedral. It shows the ordered flow
+from skill-led planning through deterministic generation, source layout,
+connected capabilities, cloud provisioning, command-driven operations, agent
+experience, and production verification.
+
+Read top to bottom. Arrows represent lifecycle order, not runtime network calls.
+Runtime and provider connections are stated explicitly inside each stage.
+
+```text
++==========================================================================================================================+
+|                                                ANHEDRAL MASTER STACK MAP                                                 |
++--------------------------------------------------------------------------------------------------------------------------+
+|OUTCOME One readable TypeScript codebase and one command surface connecting every application, cloud resource, release    |
+|path, runbook, and coding agent.                                                                                          |
+|PRINCIPLE Ordinary framework code, source ownership, and generated integration boundaries. Anhedral assembles the stack;  |
+|it is not the application runtime.                                                                                        |
++==========================================================================================================================+
+                                                             |
+                                                             v
++==========================================================================================================================+
+|                                                     1  SELECT + PLAN                                                     |
++--------------------------------------------------------------------------------------------------------------------------+
+|SKILL FIRST Install and invoke $anhedral-init. Ask for project name and custom-domain status before generating or         |
+|provisioning.                                                                                                             |
+|CREATE anhedral new <directory> | anhedral init EXTEND anhedral add <modules> | anhedral ui add <components>              |
+|INSPECT anhedral doctor AUTOMATE --dry-run | --json | --verbose | --skip-install                                          |
+|SURFACES web | mobile | api | desktop | extension                                                                         |
+|FEATURES db | auth | billing | storage | native-subscriptions | electron-updater                                          |
+|UI shadcn/ui for DOM clients | React Native Reusables for Expo | NativeWind or Uniwind                                    |
+|CLOSURE auth -> api + db | billing -> auth | storage -> auth | native-subscriptions -> mobile + billing |                 |
+|electron-updater -> desktop                                                                                               |
++==========================================================================================================================+
+                                                             |
+                                                             v
++==========================================================================================================================+
+|                                                    2  GENERATE SAFELY                                                    |
++--------------------------------------------------------------------------------------------------------------------------+
+|PIPELINE Resolve modules -> select immutable templates -> verify SHA-256 catalog -> stage files -> compose typed          |
+|contributions.                                                                                                            |
+|PIPELINE Run pinned UI providers only in staging -> record provenance and ownership -> atomic commit -> one root pnpm     |
+|install.                                                                                                                  |
+|REFUSES traversal | symlinks | nested repositories/workspaces | caches | oversized files | unowned collisions | managed   |
+|drift.                                                                                                                    |
+|OWNERSHIP Product source plus README/PRODUCTION are user-owned | root configuration is mergeable | integration substrate  |
+|is managed.                                                                                                               |
+|STATE anhedral.json records modules, versions, template/UI provenance, styling, file hashes, modes, and ownership.        |
+|WHY Deterministic, inspectable generation and safe incremental adds without replacing user work.                          |
++==========================================================================================================================+
+                                                             |
+                                                             v
++==========================================================================================================================+
+|                                       3  ONE PNPM + TURBOREPO TYPESCRIPT WORKSPACE                                       |
++--------------------------------------------------------------------------------------------------------------------------+
+|apps/web Next.js App Router + React + shadcn/ui. WHY: SSR, routing, server-first web, and source-owned UI.                |
+|apps/mobile Expo Router + React Native Reusables. WHY: one native TypeScript product for iOS and Android.                 |
+|apps/api Fastify + validation/security plugins. WHY: thin routes, services, structured logs, and explicit boundaries.     |
+|apps/desktop Electron + Vite + sandboxed React renderer. WHY: cross-platform desktop with a narrow privileged bridge.     |
+|apps/extension WXT + React + MV3 entrypoints. WHY: browser permissions, side panel/background, builds, and packaging.     |
+|apps/assets-private-proxy Cloudflare Worker + private R2 binding. WHY: controlled GET/HEAD media delivery without bucket  |
+|listing.                                                                                                                  |
+|apps/desktop-updater-worker Cloudflare Worker + private R2 binding. WHY: custom-domain Electron metadata, ranges, and     |
+|downloads.                                                                                                                |
+|packages/contracts Zod schemas. WHY: one validated network contract shared across every boundary.                         |
+|packages/api-client Typed client-safe HTTP. WHY: one request path for web, mobile, desktop, and extension.                |
+|packages/db Drizzle schema + reviewed SQL migrations. WHY: readable TypeScript schema and explicit release artifacts.     |
+|packages/realtime Ably client. WHY: scoped invalidation events while clients refetch authoritative state.                 |
++==========================================================================================================================+
+                                                             |
+                                                             v
++==========================================================================================================================+
+|                                            4  CONNECTED PRODUCT CAPABILITIES                                             |
++--------------------------------------------------------------------------------------------------------------------------+
+|REQUESTS Zod contract -> service/Drizzle query -> Fastify route -> typed API client -> every selected client.             |
+|IDENTITY Clerk sessions in clients -> verified server identity; never trust a client-supplied user ID.                    |
+|DATABASE Fastify -> Drizzle -> managed Neon Postgres with isolated dev/preview/production; no generated local Postgres.   |
+|STORAGE API presigns R2 PUT -> client uploads -> API confirms -> Worker streams confirmed assets or owner-authorized      |
+|reads.                                                                                                                    |
+|BILLING Expo purchase -> RevenueCat -> signed webhook -> Neon entitlement + transactional outbox.                         |
+|REALTIME Outbox -> scoped Ably event -> every client refetches the authoritative entitlement.                             |
+|DESKTOP UPDATE Signed native build -> artifacts then latest metadata -> private R2 -> updates.<domain> Worker ->          |
+|electron-updater.                                                                                                         |
+|SECURITY Server-only secrets | exact CORS | rate limits/headers | Electron isolation | least privilege | private buckets. |
++==========================================================================================================================+
+                                                             |
+                                                             v
++==========================================================================================================================+
+|                                            5  PROVISION + CONFIGURE THE CLOUD                                            |
++--------------------------------------------------------------------------------------------------------------------------+
+|DOMAIN Buy/confirm domain -> add Cloudflare zone -> preserve mail records -> delegate nameservers -> activate DNSSEC.     |
+|GITHUB + CI Organization repository, protected environments, pinned Actions, PR checks, branches, and release artifacts.  |
+|NEON Projects/branches per environment, pooled DATABASE_URL, backups, reviewed migrations, and controlled deploy gates.   |
+|CLERK Development/production instances, publishable/secret keys, domains, OAuth, redirects, webhooks, native and CRX IDs. |
+|CLOUDFLARE Authoritative DNS, private R2 buckets, scoped tokens, CORS/lifecycle, Worker bindings, logs, and custom        |
+|domains.                                                                                                                  |
+|VERCEL Services deployment for web/API, rewrites, environment scopes, preview/production, cron endpoints, domains, and    |
+|TLS.                                                                                                                      |
+|REVENUECAT + ABLY Products, offerings, entitlements, store credentials, signed webhook, scoped realtime, and retry cron.  |
+|EAS + STORES Expo project, credentials, internal builds, TestFlight/Play testing, metadata, privacy, review, and rollout. |
+|BROWSER STORE Stable extension ID, least host permissions, OAuth sync, privacy disclosure, trusted testing, and review.   |
+|DESKTOP Native-OS signing/notarization, electron-builder installers, private update channel, upgrade tests, and rollback. |
+|DNS app.<domain> points from Cloudflare DNS to Vercel and stays DNS-only; assets/updates are Cloudflare Worker Custom     |
+|Domains.                                                                                                                  |
+|AGENT STOPS User handles sign-in/MFA, purchases, secret generation/reveal, destructive confirmations, and final           |
+|submissions.                                                                                                              |
++==========================================================================================================================+
+                                                             |
+                                                             v
++==========================================================================================================================+
+|                                        6  GENERATED package.json COMMAND SURFACE                                         |
++--------------------------------------------------------------------------------------------------------------------------+
+|WORKSPACE dev | build | typecheck | verify WHY: run and validate exactly the selected monorepo.                           |
+|APP LOOPS dev:web | dev:mobile | dev:api | dev:desktop | dev:extension                                                    |
+|APP CHECKS verify:web | verify:mobile | verify:api | verify:desktop | verify:extension                                    |
+|VERCEL deploy:vercel:{link,preview,production,inspect,domain:inspect} WHY: connect, release, diagnose, and configure DNS. |
+|MOBILE mobile:eas:{login,init} | mobile:build:{internal,production}:{ios,android} | mobile:submit:{ios,android}           |
+|DATABASE neon:{login,project:create} | db:{generate,migrate,check,studio} | verify:db                                     |
+|STORAGE r2:{login,bucket:create,cors:list,cors:set} | assets:proxy:{check,dev,deploy} | verify:assets-proxy               |
+|UPDATES desktop:updates:{cloudflare:login,bucket:create,provision,publish}                                                |
+|UPDATES desktop:updates:worker:{check,dev,deploy,types} | desktop:updates:build:{mac,win,linux} | verify:desktop-updates  |
+|DESKTOP desktop:build | verify:desktop EXTENSION extension:zip | verify:extension                                         |
+|STRUCTURE anhedral doctor | add/ui --dry-run WHY: detect drift and preview safe structural changes.                       |
++==========================================================================================================================+
+                                                             |
+                                                             v
++==========================================================================================================================+
+|                                      7  DEVELOPER, AGENT + COMPUTER-USE EXPERIENCE                                       |
++--------------------------------------------------------------------------------------------------------------------------+
+|DOCS README.md first run/source map | docs/DEVELOPMENT.md recipes | docs/STACK.md tool map | PRODUCTION.md cloud runbook. |
+|CONTROL SKILL.md agent workflow | ANHEDRAL.md ownership notes | anhedral.json source of truth | .env.example inventories. |
+|CODING AGENT Ask name/domain -> resolve modules -> generate -> read docs/manifest -> doctor -> provision -> verify ->     |
+|hand off.                                                                                                                 |
+|SUBAGENTS Lead owns mutations; delegate docs/env inventory, read-only DNS checks, and final verification without secrets. |
+|COMPUTER USE Drive provider consoles after user authentication; configure accounts, domains, OAuth, DNS, stores, and      |
+|rollout.                                                                                                                  |
+|SECRET HANDOFF Stop before Generate/Reveal/Create; name the variable/file; user pastes directly into uncommitted          |
+|env/provider UI.                                                                                                          |
+|UI DX Source-owned components, target routing, accessibility, ordinary framework APIs, and no hidden proprietary runtime. |
+|OPERATIONS DX Exact root commands, selection-aware docs/scripts, machine-readable plans, provider ledger, and explicit    |
+|stop gates.                                                                                                               |
++==========================================================================================================================+
+                                                             |
+                                                             v
++==========================================================================================================================+
+|                                               8  VERIFY, RELEASE + OPERATE                                               |
++--------------------------------------------------------------------------------------------------------------------------+
+|LOCAL Smallest package check -> typecheck -> full verify -> build -> doctor; never weaken a failing gate.                 |
+|DATABASE Generate -> review/commit SQL -> drift gate -> controlled migrate -> health/readiness checks.                    |
+|RUNTIME API coverage, auth/CORS, billing replay/order, Ably reconnect, R2 upload/read/range/cache, Worker method/host     |
+|security.                                                                                                                 |
+|CLIENTS Next build | Expo compatibility/device checks | packaged Electron smoke/upgrade | live WXT MV3 worker in Chrome.  |
+|INFRA Confirm provider team/resource names, protected env presence, DNS answers, TLS, Vercel health, Worker bindings, and |
+|logs.                                                                                                                     |
+|CI Pinned toolchain, strict pnpm policy, allowed build scripts, OSV audit, secret scan, deterministic outputs, and        |
+|release checks.                                                                                                           |
+|RELEASES Vercel preview/prod | TestFlight/Play tracks | browser-store trusted/review | signed desktop staged update       |
+|channel.                                                                                                                  |
+|RECOVERY Transaction rollback, provider backups, database rollback plan, staged/phased rollout, telemetry, and documented |
+|owners.                                                                                                                   |
++==========================================================================================================================+
+```
+
+## Runtime connection summary
+
+```text
+web / mobile / desktop / extension
+                |
+                v
+       packages/api-client
+                |
+                v
+       Fastify API + Zod contracts
+          |         |          |
+          v         v          v
+   Clerk identity  Neon     private R2
+                    |
+                    v
+          RevenueCat entitlement
+                    |
+                    v
+               Ably event
+                    |
+                    v
+           clients refetch state
+
+signed desktop release -> private update R2 -> updates.<domain> Worker -> electron-updater
+```
+
+The runtime summary is intentionally smaller than the lifecycle map. It shows
+only application data flow; DNS, provisioning, release gates, and agent actions
+remain in the master map above.