@feltdb/core 0.7.3 → 0.8.0

package/dist/cli/commands.js

@@ -8,12 +8,19 @@ import net from 'net';
 import { createRequire } from 'module';
 import { spawn, spawnSync } from 'child_process';
 import { randomBytes } from 'crypto';
-import { createFeltDB, diffFlowSpec, emptyFlowSpec, formatFlowSpec, InvestigationLifecycleManager, parseFlowSpec, planFlowSpecMigration, startLocalDevelopmentAuthority, validateFlowSpec } from '@feltdb/core';
+import { createInterface } from 'node:readline/promises';
+import { createFeltDB, createModuleImplementationProposal, diffFlowSpec, formatFlowSpec, InvestigationLifecycleManager, listFeltDBModules, parseFlowSpec, planFlowSpecMigration, renderProposalDiagnostic, resolveFeltDBModule, resolveModuleIntent, startLocalDevelopmentAuthority, validateFlowSpec } from '@feltdb/core';
 import { discoverWorkspace, ensureWorkspaceGitIgnored, generatePairingToken, persistPairingToken, displayWorkspaceStatus, initializeWorkspace, startPairingDiscoveryServer } from './workspace-integration.js';
 import { applicationUrlCandidate, detectApplication, discoverApplicationUrl } from './application.js';
 import { resolveApplicationLifecycle, startManagedApplication, waitForManagedApplication } from './application-lifecycle.js';
 import { createDevelopmentSession, developmentSessionEnvironment, developmentSessionSummary, transitionDevelopmentSession } from './development-session.js';
 import { openApplication, openStudio } from './browser-opening.js';
+import { publishApplication } from './publish-engine.js';
+import { applyFlowProposalAtomic, assertProposalSourcePlan, describeProposal, loadLocalDevelopmentContract, repositoryContext, reviewFlowProposal, syncGeneratedSource } from './source-sync.js';
+import { configureAiModel, generateConfiguredFlowProposal, publicAiModelConfiguration } from './ai-model-config.js';
+import { proposalService } from './proposal-client.js';
+import { resolveManagedAuthorityEnvironment } from './managed-environment.js';
+import { readManagedProjectState } from './managed-project.js';
 function loadProjectEnvironment(file = path.resolve('.env.local')) {
     if (!fs.existsSync(file))
         return;
@@ -79,11 +86,319 @@ export async function handleCommand(command, args) {
             return handleFlowDeploy(args);
         case 'publish':
             return handleManagedPublish(args);
+        case 'ai':
+            return handleAi(args);
+        case 'proposals':
+            return handleProposals(args);
+        case 'module':
+        case 'modules':
+            return handleModules(args);
+        case 'sync':
+            return handleSourceSync(args);
         case 'help':
         default:
             return handleHelp();
     }
 }
+function handleModules(args) {
+    const action = args[0] || 'list';
+    if (action === 'list') {
+        for (const module of listFeltDBModules())
+            console.log(`${module.id}\t${module.version}\t${module.compatibility.join(', ')}`);
+        return;
+    }
+    if (action === 'inspect' && args[1]) {
+        const flowPath = path.resolve('feltdb.flow');
+        const spec = args.includes('--application') && fs.existsSync(flowPath) ? parseFlowSpec(fs.readFileSync(flowPath, 'utf8')) : undefined;
+        const declaration = spec?.modules?.find(value => value.name === args[1]);
+        const module = resolveFeltDBModule(declaration ?? { name: args[1], provider: args.find((value, index) => index > 1 && !value.startsWith('--')) || 'stripe-compatible' });
+        const usage = spec?.collections.flatMap(collection => collection.fields.filter(field => field.type.startsWith(`ref ${module.id}.`)).map(field => `${collection.name}.${field.name} -> ${field.type.slice(4)}`)) ?? [];
+        console.log(JSON.stringify({ ...module, application_usage: usage }, null, 2));
+        return;
+    }
+    throw new Error('Usage: feltdb module [list|inspect <id> [provider]]');
+}
+function proposalFile(args) {
+    const value = args.find(argument => !argument.startsWith('--') && !['review', 'apply'].includes(argument));
+    if (!value)
+        throw new Error('A proposal JSON file is required');
+    return path.resolve(value);
+}
+function validateRepositoryBuild(args) {
+    const packagePath = path.resolve('package.json');
+    const projectPackage = fs.existsSync(packagePath) ? JSON.parse(fs.readFileSync(packagePath, 'utf8')) : {};
+    if (args.includes('--no-build'))
+        return;
+    const verification = ['typecheck', 'test', 'build'].filter(name => projectPackage.scripts?.[name]);
+    if (!verification.length)
+        return;
+    console.log('Validating the updated application before recording applied status…');
+    for (const name of verification) {
+        const checked = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['run', name], { cwd: process.cwd(), stdio: 'inherit' });
+        if (checked.status !== 0)
+            throw new Error(`APPLICATION_VALIDATION_FAILED: ${name} exited ${checked.status ?? 'without a status'}; repository restored and proposal remains approved`);
+        console.log(`✓ ${name} passed`);
+    }
+}
+async function handleAi(args) {
+    loadProjectEnvironment();
+    if (args[0] === 'model') {
+        const action = args[1] || 'show';
+        if (action === 'show') {
+            const model = publicAiModelConfiguration();
+            console.log(`Provider: ${model.provider}\nModel: ${model.model}\nLocation: ${model.local ? 'local browser (private)' : model.baseUrl}\nCredential: ${model.credentialConfigured ? 'configured securely' : 'not configured'}`);
+            return;
+        }
+        if (action === 'set') {
+            const option = (name) => args.includes(name) ? args[args.indexOf(name) + 1] : undefined;
+            const provider = (option('--provider') || 'local-webllm');
+            if (!['local-webllm', 'openai-compatible'].includes(provider))
+                throw new Error('Provider must be local-webllm or openai-compatible');
+            const modelName = option('--model');
+            if (!modelName)
+                throw new Error('--model is required');
+            const apiKey = args.includes('--api-key-stdin') ? fs.readFileSync(0, 'utf8').trim() : process.env.FELTDB_AI_API_KEY;
+            const configured = configureAiModel({ provider, model: modelName, baseUrl: option('--base-url'), apiKey: apiKey || undefined,
+                credentialRequired: !args.includes('--no-credential') });
+            console.log(`✓ AI model configured: ${configured.provider} / ${configured.model}`);
+            console.log(provider === 'openai-compatible' ? 'Credential is stored in the operating-system vault; Studio receives only provider metadata.' : 'Inference and prompts stay in the browser.');
+            return;
+        }
+        throw new Error('Usage: feltdb ai model [show|set --provider <local-webllm|openai-compatible> --model <id> [--base-url <url>] [--api-key-stdin|--no-credential]]');
+    }
+    if (!args.length || args.every(argument => ['--dry-run', '--preview', '--ephemeral', '--no-open'].includes(argument))) {
+        console.log('Opening the local Ask FeltDB experience. Generation stays in your browser via WebGPU.');
+        return handleStudio(args, studioUrl => console.log(`Ask FeltDB: ${studioUrl}`));
+    }
+    const action = args[0];
+    if (action === 'proposals')
+        return handleProposals(['list', ...args.slice(1)]);
+    if (action === 'proposal') {
+        const id = args[1];
+        if (!id)
+            throw new Error('Usage: feltdb ai proposal <id> [--history]');
+        return handleProposals(['get', id, ...args.slice(2)]);
+    }
+    if (action === 'approve') {
+        const id = args[1];
+        if (!id)
+            throw new Error('Usage: feltdb ai approve <id> [--yes]');
+        const client = proposalService();
+        const proposal = await client.get(id);
+        const readiness = await client.status(id);
+        if (proposal.status !== 'previewed')
+            throw new Error(`Cannot approve Proposal ${id}. Current status: ${proposal.status}. A current preview is required.`);
+        if (readiness.blockers.length)
+            throw new Error(`Cannot approve Proposal ${id}. ${readiness.blockers.join(', ')}. Regenerate the Proposal before approval.`);
+        if (!proposal.preview_id)
+            throw new Error(`Cannot approve Proposal ${id}. Preview is missing.`);
+        await client.getPreview(proposal.preview_id);
+        console.log(renderProposalDiagnostic(proposal, { readiness }).join('\n'));
+        console.log('Repository source will NOT be modified by approval.');
+        let approved = args.includes('--yes');
+        if (!approved && process.stdin.isTTY) {
+            const prompt = createInterface({ input: process.stdin, output: process.stdout });
+            approved = /^y(?:es)?$/i.test(await prompt.question('Approve this proposal? [y/N] '));
+            prompt.close();
+        }
+        if (!approved) {
+            console.log('Approval cancelled.');
+            return;
+        }
+        const value = await client.approve(id, 'cli-developer', args.includes('--approve-authorization'));
+        console.log(`✓ Proposal ${value.id} approved`);
+        return;
+    }
+    if (action === 'context') {
+        const context = await loadLocalDevelopmentContract();
+        console.log(JSON.stringify({ snapshot: context.snapshot, flowHash: context.flowHash }, null, 2));
+        return;
+    }
+    if (action === 'review') {
+        const input = JSON.parse(fs.readFileSync(proposalFile(args.slice(1)), 'utf8'));
+        const proposal = input;
+        const review = await reviewFlowProposal(proposal);
+        console.log(`\n${proposal.summary || 'FeltDB change proposal'}`);
+        for (const line of describeProposal(review))
+            console.log(`  ${line}`);
+        if (!describeProposal(review).length)
+            console.log('  No contract changes.');
+        return;
+    }
+    if (action === 'apply') {
+        const target = args.slice(1).find(value => !value.startsWith('--'));
+        if (!target)
+            throw new Error('A proposal id or JSON file is required');
+        const stored = target.startsWith('p_') ? await proposalService().get(target) : undefined;
+        const proposal = stored ? { baseContractHash: stored.base_contract_hash, baseFlowHash: stored.base_flow_hash,
+            proposedFlow: stored.proposed_flow, summary: stored.summary, changes: stored.contract_diff, warnings: stored.warnings }
+            : JSON.parse(fs.readFileSync(path.resolve(target), 'utf8'));
+        if (stored && stored.status !== 'approved')
+            throw new Error(`Cannot apply Proposal ${stored.id}. Current status: ${stored.status}. Approval is required. Run: feltdb ai approve ${stored.id}`);
+        if (!stored && !args.includes('--approve'))
+            throw new Error('Explicit approval is required: rerun with --approve');
+        const current = await loadLocalDevelopmentContract();
+        if (stored && (stored.application_id !== current.snapshot.application.application_id || stored.environment !== current.snapshot.application.environment)) {
+            throw new Error(`PROPOSAL_SCOPE_MISMATCH: ${stored.application_id}/${stored.environment} cannot apply to ${current.snapshot.application.application_id}/${current.snapshot.application.environment}`);
+        }
+        const alreadyWritten = stored && await import('@feltdb/core').then(module => module.flowSourceHash(stored.proposed_flow)) === current.flowHash;
+        if (alreadyWritten) {
+            console.log('Detected an approved proposal whose flow is already present; reconciling the interrupted application.');
+            const recoveredReview = await reviewFlowProposal({ ...proposal, baseContractHash: current.snapshot.contract_hash, baseFlowHash: current.flowHash });
+            await applyFlowProposalAtomic({ ...proposal, baseContractHash: current.snapshot.contract_hash, baseFlowHash: current.flowHash, proposedFlow: current.source }, process.cwd(), {
+                approveAuthorization: true, replaceGenerated: args.includes('--replace-generated'), verify: () => validateRepositoryBuild(args),
+            });
+            await proposalService().transition(stored.id, 'applied', 'cli-repository-applier', true);
+            console.log(`✓ Reconciled and marked ${stored.id} applied`);
+            return;
+        }
+        if (stored) {
+            const client = proposalService();
+            const readiness = await client.status(stored.id);
+            if (readiness.blockers.length)
+                throw new Error(`Cannot apply Proposal ${stored.id}. Proposal is stale: ${readiness.blockers.join(', ')}. Proposal contract: ${stored.base_contract_hash}. Current contract: ${readiness.current_contract_hash}. Regenerate the Proposal before applying.`);
+            if (!stored.preview_id)
+                throw new Error(`Cannot apply Proposal ${stored.id}. A current preview is required.`);
+            await client.getPreview(stored.preview_id);
+            assertProposalSourcePlan(stored.source_plan);
+            const repository = await repositoryContext(process.cwd(), stored.source_plan.files.map(value => value.path));
+            if (repository.dirty.length && !args.includes('--allow-dirty'))
+                throw new Error(`Cannot apply Proposal ${stored.id}. Repository conflict: ${repository.dirty.join(', ')}. Resolve the conflict and retry.`);
+        }
+        const reviewOnly = await reviewFlowProposal(proposal);
+        console.log(`\n${proposal.summary || 'FeltDB change proposal'}`);
+        for (const line of describeProposal(reviewOnly))
+            console.log(`  ${line}`);
+        console.log(`  Source impact: feltdb.flow, src/feltdb/generated-contract.ts`);
+        if (args.includes('--dry-run') || args.includes('--preview')) {
+            console.log('✓ Preview complete. No files, flow, contract, or published state were changed.');
+            return;
+        }
+        let confirmed = args.includes('--yes');
+        if (!confirmed && process.stdin.isTTY) {
+            const prompt = createInterface({ input: process.stdin, output: process.stdout });
+            confirmed = /^y(?:es)?$/i.test(await prompt.question(`Apply ${stored?.id || 'this proposal'} to repository source? [y/N] `));
+            prompt.close();
+        }
+        if (!confirmed)
+            throw new Error('Apply cancelled. Re-run with --yes for non-interactive application.');
+        const review = await applyFlowProposalAtomic(proposal, process.cwd(), {
+            allowDirty: args.includes('--allow-dirty'),
+            approveAuthorization: args.includes('--approve-authorization'),
+            replaceGenerated: args.includes('--replace-generated'),
+            verify: () => validateRepositoryBuild(args),
+        });
+        console.log(`✓ Applied validated flow proposal (${review.proposedContract.hashes.application})`);
+        for (const file of review.written)
+            console.log(`  ${file}`);
+        if (stored)
+            await proposalService().transition(stored.id, 'applied', 'cli-repository-applier', true);
+        return;
+    }
+    const developerIntent = args.filter(value => !value.startsWith('--')).join(' ').trim();
+    if (developerIntent) {
+        const resolved = resolveModuleIntent(developerIntent);
+        if (resolved) {
+            console.log('Understanding application...');
+            const current = await loadLocalDevelopmentContract();
+            console.log('✓ Application contract loaded');
+            const proposal = await createModuleImplementationProposal({ intent: developerIntent, snapshot: current.snapshot, currentFlow: current.source });
+            console.log(`✓ ${proposal.implementation?.module.name} ${proposal.implementation?.module.version} resolved`);
+            console.log(`✓ Billing owner: ${proposal.implementation?.owner}`);
+            const review = await reviewFlowProposal(proposal);
+            if (proposal.implementation?.alreadyInstalled) {
+                console.log(`${proposal.implementation.module.name} is already installed.`);
+                const missing = [...review.diff.added, ...review.diff.changed];
+                if (!missing.length) {
+                    console.log('Current implementation is complete. No proposal created.');
+                    return;
+                }
+                console.log('Missing:');
+                for (const value of missing)
+                    console.log(`  ${value}`);
+                console.log('Creating a completion proposal.');
+            }
+            console.log('Generating implementation proposal...');
+            const client = proposalService();
+            const parent = (await client.list({ status: 'applied', limit: 100 })).proposals.find(value => value.metadata?.module === resolved.module);
+            let stored = await client.create({ application_id: current.snapshot.application.application_id, environment: current.snapshot.application.environment,
+                base_contract_hash: proposal.baseContractHash, base_flow_hash: proposal.baseFlowHash, proposed_flow: proposal.proposedFlow,
+                proposal_version: 1, contract_diff: [], source_plan: { files: [] },
+                summary: proposal.summary, warnings: proposal.warnings, actor: 'cli-developer', parent_proposal_id: parent?.id, metadata: { created_from: 'module-intent', module: resolved.module, module_version: resolved.version } });
+            await client.validate(stored.id, 'feltdb-validator', review.proposedContract.manifest);
+            const preview = await client.preview(stored.id, 'cli-developer');
+            stored = preview.proposal;
+            const readiness = await client.status(stored.id);
+            console.log(renderProposalDiagnostic(stored, { readiness, preview: preview }).join('\n'));
+            console.log(`Use:\n  feltdb ai proposal ${stored.id}`);
+            return;
+        }
+    }
+    throw new Error('Usage: feltdb ai ["implement <module>"|context|proposals|proposal <id>|approve <id>|review <proposal.json>|apply <id>]');
+}
+async function handleProposals(args) {
+    loadProjectEnvironment();
+    const client = proposalService();
+    const action = args[0] || 'list';
+    const id = args[1];
+    if (action === 'list') {
+        const option = (name) => args.includes(name) ? args[args.indexOf(name) + 1] : undefined;
+        const result = await client.list({ status: option('--status'), environment: option('--environment'), limit: option('--limit') ? Number(option('--limit')) : undefined, cursor: option('--cursor') });
+        if (args.includes('--json')) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const { proposals } = result;
+        console.log('PROPOSALS');
+        for (const value of proposals)
+            console.log(`${value.id}\t${value.status.toUpperCase()}\t${value.summary}\t${value.created_at}`);
+        if (result.pagination?.nextCursor)
+            console.log(`Next: --cursor ${result.pagination.nextCursor}`);
+        if (!proposals.length)
+            console.log('No proposals.');
+        return;
+    }
+    if (!id)
+        throw new Error(`feltdb proposals ${action} requires a proposal id`);
+    if (action === 'get') {
+        const proposal = await client.get(id);
+        const [readiness, history] = await Promise.all([client.status(id), client.history(id)]);
+        const preview = proposal.preview_id ? await client.getPreview(proposal.preview_id).catch(() => undefined) : undefined;
+        const result = { proposal, readiness, preview, history: history.events };
+        if (args.includes('--json'))
+            console.log(JSON.stringify(result, null, 2));
+        else
+            console.log(renderProposalDiagnostic(proposal, { readiness, history: history.events, preview: preview }).join('\n'));
+        return;
+    }
+    if (action === 'diff') {
+        const value = await client.get(id);
+        console.log(value.contract_diff.join('\n'));
+        console.log(JSON.stringify(value.source_plan, null, 2));
+        return;
+    }
+    if (action === 'approve' || action === 'reject') {
+        const value = action === 'approve' ? await client.approve(id, 'local-developer', args.includes('--approve-authorization')) : await client.reject(id, 'local-developer');
+        console.log(`✓ ${value.id} ${value.status}`);
+        return;
+    }
+    throw new Error('Usage: feltdb proposals [list|get|diff|approve|reject] [id]');
+}
+async function handleSourceSync(args) {
+    loadProjectEnvironment();
+    const context = await loadLocalDevelopmentContract();
+    const proposal = {
+        baseContractHash: context.snapshot.contract_hash,
+        baseFlowHash: context.flowHash,
+        proposedFlow: context.source,
+        summary: 'Synchronize generated source with feltdb.flow',
+        changes: [], warnings: [],
+    };
+    const review = await reviewFlowProposal(proposal);
+    const result = syncGeneratedSource(review, process.cwd(), { replace: args.includes('--replace-generated') });
+    for (const file of result.written)
+        console.log(`✓ Synchronized ${file}`);
+}
 /**
  * Inspect the durable investigation store.
  *
@@ -234,83 +549,29 @@ async function handleFlowDeploy(args) {
     }
 }
 async function handleManagedPublish(args) {
-    loadProjectEnvironment();
-    const configPath = path.resolve('feltdb.config.json');
-    if (!fs.existsSync(configPath))
-        throw new Error('feltdb.config.json is required for publish');
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    if (config.runtime !== 'managed')
-        throw new Error('feltdb publish requires a managed runtime in feltdb.config.json');
-    const url = process.env.VITE_FELTDB_MANAGED_URL;
-    const token = process.env.VITE_FELTDB_MANAGED_API_KEY;
-    const tenantId = process.env.VITE_FELTDB_MANAGED_TENANT_ID;
-    const applicationId = process.env.VITE_FELTDB_MANAGED_APPLICATION_ID;
-    const namespace = process.env.VITE_FELTDB_MANAGED_NAMESPACE || config.namespace;
-    const environment = process.env.VITE_FELTDB_MANAGED_ENVIRONMENT || 'production';
-    const missing = [
-        ['VITE_FELTDB_MANAGED_URL', url],
-        ['VITE_FELTDB_MANAGED_API_KEY', token],
-        ['VITE_FELTDB_MANAGED_TENANT_ID', tenantId],
-        ['VITE_FELTDB_MANAGED_APPLICATION_ID', applicationId],
-        ['VITE_FELTDB_MANAGED_NAMESPACE', namespace],
-    ].filter(([, value]) => !value).map(([name]) => name);
-    if (missing.length)
-        throw new Error(`Managed publish configuration is incomplete in .env.local: ${missing.join(', ')}`);
-    const file = flowFile(args);
-    const spec = readFlowSpec(file);
-    const diagnostics = validateFlowSpec(spec).filter(value => value.severity === 'error');
-    if (diagnostics.length)
-        throw new Error(diagnostics.map(value => value.message).join('; '));
-    console.log('FeltDB Publish');
-    console.log(`Application: ${spec.app}`);
-    console.log(`Environment: ${environment}`);
-    console.log(`Namespace:   ${namespace}`);
-    console.log(`API:         ${url}`);
-    console.log('✓ Configuration loaded');
-    if (!args.includes('--no-build')) {
-        const manifestPath = path.resolve('package.json');
-        if (!fs.existsSync(manifestPath))
-            throw new Error('package.json is required to build the application');
-        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-        if (!manifest.scripts?.build)
-            throw new Error('package.json must define a build script for managed publish');
-        const build = spawnSync('npm', ['run', 'build'], { cwd: process.cwd(), stdio: 'inherit' });
-        if (build.error)
-            throw build.error;
-        if (build.status !== 0)
-            throw new Error(`Application build failed with exit code ${build.status}`);
-    }
-    console.log('✓ Build completed');
-    console.log('✓ Application validated');
-    const remote = createFeltDB({ namespace, server: { url: url, token: token } });
-    try {
-        const current = await remote.collection('_flow_apps').get(spec.app);
-        const migration = planFlowSpecMigration(current?.spec ?? emptyFlowSpec(spec.app), spec);
-        const destructive = migration.filter(value => value.safety === 'destructive');
-        if (destructive.length && !args.includes('--allow-destructive')) {
-            throw new Error(`Publish contains destructive changes (${destructive.map(value => value.target).join(', ')}); review them and rerun with --allow-destructive`);
+    const valueAfter = (flag) => { const index = args.indexOf(flag); return index >= 0 ? args[index + 1] : undefined; };
+    const confirm = async (question) => {
+        if (!process.stdin.isTTY)
+            return false;
+        const readline = await import('node:readline/promises');
+        const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            return !/^(n|no)$/i.test((await prompt.question(`${question} [Y/n] `)).trim());
         }
-        const result = await remote.deployFlowSpec(spec, current?.version ?? 0, args.includes('--allow-destructive'));
-        const publishState = {
-            tenantId,
-            applicationId,
-            namespace,
-            environment,
-            deploymentId: `${applicationId}:${environment}:${result.version}`,
-            version: result.version,
-            publishedAt: new Date().toISOString(),
-        };
-        fs.mkdirSync(path.resolve('.feltdb'), { recursive: true });
-        fs.writeFileSync(path.resolve('.feltdb/last-published.json'), `${JSON.stringify(publishState, null, 2)}\n`, { mode: 0o600 });
-        fs.writeFileSync(path.resolve('.feltdb/last-deployed.flow'), formatFlowSpec(spec));
-        console.log('✓ Published');
-        console.log(`Deployment: ${publishState.deploymentId}`);
-        console.log(`Version:    ${result.version}`);
-        console.log('Your app is live.');
-    }
-    finally {
-        await remote.close();
-    }
+        finally {
+            prompt.close();
+        }
+    };
+    await publishApplication({
+        environment: valueAfter('--environment'),
+        message: valueAfter('--message'),
+        dryRun: args.includes('--dry-run'),
+        status: args.includes('--status'),
+        yes: args.includes('--yes'),
+        approveDestructive: args.includes('--approve-destructive-changes') || args.includes('--allow-destructive'),
+        noBuild: args.includes('--no-build'),
+        confirm,
+    });
 }
 async function handleServer(args) {
     const require = createRequire(import.meta.url);
@@ -500,17 +761,41 @@ For more info, visit: https://github.com/rkendel1/feltdb
 `);
 }
 async function handleConnect(args) {
-    const url = args[0];
-    if (!url) {
-        console.error('❌ URL required');
-        console.error('Usage: feltdb connect <url>\n');
-        process.exit(1);
-    }
+    loadProjectEnvironment();
+    const managed = readManagedProjectState();
+    const projectFile = path.resolve('feltdb.config.json');
+    const project = fs.existsSync(projectFile) ? JSON.parse(fs.readFileSync(projectFile, 'utf8')) : {};
+    const url = (args[0]
+        || managed.url
+        || process.env.VITE_FELTDB_MANAGED_URL
+        || process.env.VITE_FELTDB_URL
+        || project.server?.url
+        || (project.runtime === 'browser' ? '' : 'http://localhost:7700')).replace(/\/$/, '');
+    if (!url)
+        throw new Error('This project uses the embedded browser runtime; there is no server endpoint to connect to. Run npm run dev.');
     console.log('🔗 Connecting to FeltDB Server\n');
     console.log(`URL: ${url}`);
-    console.log('Discovering node...');
-    console.log('Checking capabilities...');
     console.log('Verifying connection...\n');
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    let health;
+    try {
+        const response = await fetch(`${url}/health`, {
+            headers: process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY
+                ? { Authorization: `Bearer ${process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY}` }
+                : {},
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        health = await response.json();
+    }
+    catch (error) {
+        throw new Error(`FeltDB is not running at ${url}. Start it with npm run feltdb:studio (or the project's configured runtime command). ${error instanceof Error ? error.message : error}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
     // Store connection info
     const configDir = path.join(process.cwd(), '.feltdb');
     if (!fs.existsSync(configDir)) {
@@ -520,15 +805,16 @@ async function handleConnect(args) {
     fs.writeFileSync(connFile, JSON.stringify({
         url,
         connected: new Date().toISOString(),
-        authenticated: false,
+        authenticated: Boolean(process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY),
+        namespace: managed.namespace || project.namespace || 'default',
+        runtime: project.runtime || 'self-hosted',
     }, null, 2));
     console.log('✅ Connected to FeltDB\n');
     console.log('Endpoint:     ' + url);
-    console.log('Namespace:    default');
-    console.log('Authenticated: no');
-    console.log('Runtime:      self-hosted');
-    console.log('Peers:        0');
-    console.log('Health:       ✓\n');
+    console.log(`Namespace:    ${managed.namespace || project.namespace || 'default'}`);
+    console.log(`Authenticated: ${process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY ? 'yes' : 'no'}`);
+    console.log(`Runtime:      ${project.runtime || 'self-hosted'}`);
+    console.log(`Health:       ${health.status || 'healthy'}\n`);
     console.log('Use: feltdb status  (to check connection)\n');
 }
 async function handleExplain(args) {
@@ -561,20 +847,39 @@ async function handleStatus() {
         console.log('Fabric:        Enabled');
         console.log('Authentication: Development');
         console.log('Health:        ✓\n');
+        await displayContractStatus();
         return;
     }
     const connection = JSON.parse(fs.readFileSync(connFile, 'utf-8'));
     console.log('Connected to Server\n');
     console.log(`Endpoint:     ${connection.url}`);
-    console.log('Namespace:    default');
+    console.log(`Namespace:    ${connection.namespace || 'default'}`);
     console.log(`Authenticated: ${connection.authenticated ? 'yes' : 'no'}`);
-    console.log('Runtime:      self-hosted');
-    console.log('Storage:      durable');
-    console.log('Peers:        3');
-    console.log('Capabilities: 8');
-    console.log('Agents:       2');
-    console.log('Workflows:    5');
-    console.log('Health:       ✓\n');
+    console.log(`Runtime:      ${connection.runtime || 'self-hosted'}`);
+    try {
+        const response = await fetch(`${String(connection.url).replace(/\/$/, '')}/health`, { signal: AbortSignal.timeout(5000) });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        const health = await response.json();
+        console.log(`Health:       ${health.status || 'healthy'}\n`);
+    }
+    catch {
+        console.log('Health:       unavailable');
+        console.log('Start the configured runtime and run feltdb connect again.\n');
+    }
+    await displayContractStatus();
+}
+async function displayContractStatus() {
+    if (!fs.existsSync(path.resolve('feltdb.flow')))
+        return;
+    loadProjectEnvironment();
+    const current = await loadLocalDevelopmentContract();
+    const publishedFile = path.resolve('.feltdb/last-published.json');
+    const published = fs.existsSync(publishedFile) ? JSON.parse(fs.readFileSync(publishedFile, 'utf8')) : undefined;
+    console.log('Application contract');
+    console.log(`Source:        ${current.snapshot.contract_hash}`);
+    console.log(`Published:     ${published?.contractHash || 'unknown'}`);
+    console.log(`Drift:         ${!published?.contractHash ? 'unknown' : published.contractHash === current.snapshot.contract_hash ? 'synchronized' : 'source differs from published'}\n`);
 }
 async function handleWorkspace(args) {
     const subcommand = args[0] || 'status';
@@ -622,7 +927,7 @@ async function handleWorkspaceConnect(args) {
     console.log('   (when @feltdb/client workspace APIs are available)\n');
 }
 async function handleDev(args) {
-    var _a, _b, _c;
+    var _a;
     const projectDir = process.cwd();
     if (args.includes('--help')) {
         console.log('Usage: feltdb dev [--app-url URL] [--studio-port 7701] [--authority-port 7700] [--discovery-port 7799] [--no-open]');
@@ -675,14 +980,10 @@ async function handleDev(args) {
         ? { ...configDefaults, ...JSON.parse(fs.readFileSync(configPath, 'utf-8')) }
         : configDefaults;
     if (config.runtime === 'managed') {
-        (_a = process.env).VITE_FELTDB_URL || (_a.VITE_FELTDB_URL = process.env.VITE_FELTDB_MANAGED_URL);
-        (_b = process.env).VITE_FELTDB_API_KEY || (_b.VITE_FELTDB_API_KEY = process.env.VITE_FELTDB_MANAGED_API_KEY);
-    }
-    if (config.runtime === 'managed' && (!process.env.VITE_FELTDB_URL || !process.env.VITE_FELTDB_API_KEY)) {
-        throw new Error('Managed runtime requires VITE_FELTDB_MANAGED_URL and VITE_FELTDB_MANAGED_API_KEY in .env.local. Re-run managed setup or add your managed connection.');
+        resolveManagedAuthorityEnvironment(process.env);
     }
     const runtimeNamespace = config.runtime === 'managed'
-        ? process.env.VITE_FELTDB_MANAGED_NAMESPACE || config.namespace
+        ? readManagedProjectState(projectDir).namespace || config.namespace
         : config.namespace;
     const applicationLifecycle = resolveApplicationLifecycle(config);
     // Application URL precedence:
@@ -771,15 +1072,21 @@ async function handleDev(args) {
         if (compose.status !== 0)
             throw new Error(`docker compose failed with status ${compose.status ?? 'unknown'}`);
         selfHostedStarted = true;
-        (_c = process.env).VITE_FELTDB_URL || (_c.VITE_FELTDB_URL = 'http://127.0.0.1:7700');
+        (_a = process.env).VITE_FELTDB_URL || (_a.VITE_FELTDB_URL = 'http://127.0.0.1:7700');
     }
     if (!process.env.VITE_FELTDB_URL) {
         const authorityPort = Number(args.includes('--authority-port') ? args[args.indexOf('--authority-port') + 1] || '7700' : '7700');
         localAuthority = await startLocalDevelopmentAuthority({
-            dataDir: path.join(projectDir, '.feltdb', 'authority'),
+            dataDir: path.join(projectDir, '.feltdb-data', 'authority'),
             port: authorityPort,
+            proposalContext: () => loadLocalDevelopmentContract(projectDir),
         });
         process.env.VITE_FELTDB_URL = localAuthority.endpoint;
+        const connectionsPath = path.join(projectDir, '.feltdb', 'connections.json');
+        const connections = fs.existsSync(connectionsPath) ? JSON.parse(fs.readFileSync(connectionsPath, 'utf8')) : {};
+        fs.writeFileSync(connectionsPath, `${JSON.stringify({ ...connections, developmentAuthority: {
+                endpoint: localAuthority.endpoint, proposalAuthorityToken: localAuthority.proposalAuthorityToken,
+            } }, null, 2)}\n`, { mode: 0o600 });
     }
     const authorityUrl = process.env.VITE_FELTDB_URL;
     if (!authorityUrl)
@@ -1239,10 +1546,11 @@ async function handleStudio(args, onReady) {
     loadProjectEnvironment();
     const projectConfigPath = path.resolve('feltdb.config.json');
     const projectConfig = fs.existsSync(projectConfigPath) ? JSON.parse(fs.readFileSync(projectConfigPath, 'utf8')) : {};
+    const managedProject = readManagedProjectState();
     const projectIsManaged = projectConfig.runtime === 'managed';
     const connectUrl = args.includes('--connect')
         ? args[args.indexOf('--connect') + 1]
-        : projectIsManaged ? process.env.VITE_FELTDB_MANAGED_URL : undefined;
+        : projectIsManaged ? process.env.VITE_FELTDB_MANAGED_URL || managedProject.url : undefined;
     const port = args.includes('--port')
         ? args[args.indexOf('--port') + 1] || '7701'
         : '7701';
@@ -1252,10 +1560,16 @@ async function handleStudio(args, onReady) {
     const open = !args.includes('--no-open');
     const namespace = args.includes('--namespace')
         ? args[args.indexOf('--namespace') + 1] || 'default'
-        : projectIsManaged ? process.env.VITE_FELTDB_MANAGED_NAMESPACE || projectConfig.namespace || 'default' : 'default';
+        : projectIsManaged ? managedProject.namespace || projectConfig.namespace || 'default' : 'default';
     const runtime = args.includes('--runtime')
         ? args[args.indexOf('--runtime') + 1] || 'browser'
         : projectIsManaged ? 'managed' : connectUrl ? 'remote' : 'browser';
+    const applicationId = args.includes('--application')
+        ? args[args.indexOf('--application') + 1] || ''
+        : process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || managedProject.applicationId || '';
+    const environment = args.includes('--environment')
+        ? args[args.indexOf('--environment') + 1] || 'production'
+        : managedProject.environment || 'production';
     const appUrl = args.includes('--app-url')
         ? args[args.indexOf('--app-url') + 1]
         : undefined;
@@ -1286,9 +1600,13 @@ async function handleStudio(args, onReady) {
         console.log('⚠️  Studio application artifacts not found.');
         return;
     }
-    const projectFlow = ['feltdb.flow', ...fs.readdirSync(process.cwd()).filter(value => value.endsWith('.flow'))]
-        .map(value => path.resolve(process.cwd(), value))
-        .find((value, index, values) => values.indexOf(value) === index && fs.existsSync(value));
+    const canonicalFlow = path.resolve(process.cwd(), 'feltdb.flow');
+    const projectFlow = fs.existsSync(canonicalFlow) ? canonicalFlow : undefined;
+    const studioMutationToken = randomBytes(24).toString('hex');
+    const projectPackage = fs.existsSync(path.resolve('package.json')) ? JSON.parse(fs.readFileSync(path.resolve('package.json'), 'utf8')) : {};
+    const webllmEnabled = Boolean(projectPackage.dependencies?.['@feltdb/webllm'] || projectPackage.devDependencies?.['@feltdb/webllm']);
+    const previewOnly = args.includes('--ephemeral');
+    const proposalClient = proposalService(process.cwd(), session.authorityUrl);
     const mime = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml', '.json': 'application/json' };
     const server = http.createServer(async (request, response) => {
         const pathname = decodeURIComponent(new URL(request.url || '/', 'http://localhost').pathname);
@@ -1297,14 +1615,210 @@ async function handleStudio(args, onReady) {
             response.setHeader('Cache-Control', 'no-store');
             response.setHeader('Pragma', 'no-cache');
             const managedPublish = runtime === 'managed' ? {
-                url: process.env.VITE_FELTDB_MANAGED_URL || connectUrl || '',
-                namespace: process.env.VITE_FELTDB_MANAGED_NAMESPACE || namespace,
-                token: process.env.VITE_FELTDB_MANAGED_API_KEY || process.env.VITE_FELTDB_API_KEY || '',
-                tenantId: process.env.VITE_FELTDB_MANAGED_TENANT_ID || '',
-                applicationId: process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || '',
-                environment: process.env.VITE_FELTDB_MANAGED_ENVIRONMENT || 'production',
+                url: connectUrl || managedProject.url || '',
+                namespace: managedProject.namespace || namespace,
+                tenantId: managedProject.tenantId || '',
+                applicationId: process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || managedProject.applicationId || '',
+                environment: managedProject.environment || 'production',
+                publishEndpoint: '/_feltdb/publish',
             } : undefined;
-            response.end(JSON.stringify({ token: connectUrl ? process.env.VITE_FELTDB_API_KEY || process.env.VITE_FELTDB_MANAGED_API_KEY || '' : '', managedPublish, session }));
+            response.end(JSON.stringify({ token: connectUrl ? process.env.VITE_FELTDB_API_KEY || '' : '', managedPublish, session, sourceSync: { enabled: true, webllmEnabled, previewOnly, token: studioMutationToken, aiModel: publicAiModelConfiguration() } }));
+            return;
+        }
+        if (pathname === '/_feltdb/contract') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            try {
+                const current = await loadLocalDevelopmentContract();
+                const lastPublished = fs.existsSync(path.resolve('.feltdb/last-published.json'))
+                    ? JSON.parse(fs.readFileSync(path.resolve('.feltdb/last-published.json'), 'utf8')) : undefined;
+                let runningContract;
+                let runningSnapshot;
+                const applicationId = process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || managedProject.applicationId || lastPublished?.applicationId;
+                if (connectUrl && applicationId) {
+                    try {
+                        const endpoint = new URL('/v1/application', connectUrl);
+                        endpoint.searchParams.set('application_id', applicationId);
+                        endpoint.searchParams.set('environment', managedProject.environment || lastPublished?.environment || 'production');
+                        const headers = {};
+                        const credential = process.env.FELTDB_MANAGED_CONTROL_API_KEY || process.env.VITE_FELTDB_API_KEY;
+                        if (credential)
+                            headers.authorization = `Bearer ${credential}`;
+                        const discovered = await fetch(endpoint, { headers });
+                        if (discovered.ok) {
+                            const application = await discovered.json();
+                            runningSnapshot = application.snapshot;
+                            runningContract = runningSnapshot?.contract_hash ?? application.contract_hash;
+                        }
+                    }
+                    catch { /* Drift remains explicitly unknown while the runtime is unavailable. */ }
+                }
+                const knownContracts = [current.snapshot.contract_hash, runningContract, lastPublished?.contractHash].filter(Boolean);
+                response.end(JSON.stringify({ snapshot: runningSnapshot ?? current.snapshot, flowHash: current.flowHash, source: current.source,
+                    drift: { source: current.snapshot.contract_hash, running: runningContract, published: lastPublished?.contractHash,
+                        synchronized: new Set(knownContracts).size <= 1 } }));
+            }
+            catch (error) {
+                response.statusCode = 400;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (pathname === '/_feltdb/repository-readiness' && request.method === 'GET') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            try {
+                const proposalId = new URL(request.url || '/', 'http://localhost').searchParams.get('proposal');
+                if (!proposalId)
+                    throw new Error('proposal is required');
+                const proposal = await proposalClient.get(proposalId);
+                assertProposalSourcePlan(proposal.source_plan);
+                const local = await loadLocalDevelopmentContract();
+                const repository = await repositoryContext(process.cwd(), proposal.source_plan.files.map(value => value.path));
+                const contractMatches = local.snapshot.contract_hash === proposal.base_contract_hash;
+                const flowMatches = local.flowHash === proposal.base_flow_hash;
+                response.end(JSON.stringify({ ready: contractMatches && flowMatches && repository.dirty.length === 0,
+                    contractMatches, flowMatches, gitClean: repository.dirty.length === 0, conflicts: repository.dirty,
+                    branch: repository.branch, commit: repository.commit }));
+            }
+            catch (error) {
+                response.statusCode = 409;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (pathname === '/_feltdb/proposals/list' && request.method === 'GET') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            try {
+                response.end(JSON.stringify(await proposalClient.list()));
+            }
+            catch (error) {
+                response.statusCode = 503;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        const proposalDetail = pathname.match(/^\/_feltdb\/proposals\/(p_[A-Za-z0-9]+)$/);
+        if (proposalDetail && request.method === 'GET') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            try {
+                response.end(JSON.stringify({ proposal: await proposalClient.get(proposalDetail[1]), history: (await proposalClient.history(proposalDetail[1])).events }));
+            }
+            catch (error) {
+                response.statusCode = 404;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Studio proposes and previews. CLI applies to the repository. FeltDB validates
+        // and stores the proposal as application state. Human approves. Nothing else writes source.
+        if (pathname === '/_feltdb/proposals' || pathname === '/_feltdb/proposals/approve' || pathname === '/_feltdb/proposals/reject') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            if (request.method !== 'POST') {
+                response.statusCode = 405;
+                response.end(JSON.stringify({ error: 'POST required' }));
+                return;
+            }
+            if (request.headers['x-feltdb-studio-token'] !== studioMutationToken) {
+                response.statusCode = 403;
+                response.end(JSON.stringify({ error: 'Invalid Studio source-sync token' }));
+                return;
+            }
+            try {
+                const chunks = [];
+                for await (const chunk of request)
+                    chunks.push(Buffer.from(chunk));
+                const input = chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {};
+                if (pathname.endsWith('/approve') || pathname.endsWith('/reject')) {
+                    if (previewOnly)
+                        throw new Error('Preview-only sessions cannot approve or reject persisted proposals');
+                    if (input.confirm !== true)
+                        throw new Error('Explicit proposal confirmation is required');
+                    const proposal = await proposalClient.transition(String(input.proposalId || ''), pathname.endsWith('/approve') ? 'approved' : 'rejected', 'studio-developer', false, input.approveAuthorization === true);
+                    response.end(JSON.stringify({ status: proposal.status, proposalId: proposal.id,
+                        command: proposal.status === 'approved' ? `feltdb ai apply ${proposal.id}` : undefined }));
+                }
+                else {
+                    const proposal = input.proposal;
+                    const review = await reviewFlowProposal(proposal);
+                    const changes = describeProposal(review);
+                    let stored;
+                    if (!previewOnly) {
+                        const current = await loadLocalDevelopmentContract();
+                        stored = await proposalClient.create({ application_id: current.snapshot.application.application_id,
+                            environment: current.snapshot.application.environment, base_contract_hash: proposal.baseContractHash,
+                            base_flow_hash: proposal.baseFlowHash, proposed_flow: proposal.proposedFlow, summary: proposal.summary,
+                            proposal_version: 1, contract_diff: [], source_plan: { files: [] },
+                            warnings: proposal.warnings, actor: 'studio-developer', metadata: { model: publicAiModelConfiguration().model, created_from: 'studio' } });
+                        await proposalClient.validate(stored.id, 'feltdb-validator', review.proposedContract.manifest);
+                        stored = (await proposalClient.preview(stored.id, 'studio-developer')).proposal;
+                    }
+                    response.end(JSON.stringify({ status: 'previewed', proposalId: stored?.id ?? 'ephemeral', changes,
+                        sourcePlan: stored?.source_plan.files.map(value => value.path) ?? ['feltdb.flow', 'src/feltdb/generated-contract.ts'], previewOnly,
+                        authorizationChanges: review.authorizationChanges, migration: review.migration,
+                        contractHash: review.proposedContract.hashes.application }));
+                }
+            }
+            catch (error) {
+                response.statusCode = 400;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (pathname === '/_feltdb/ai/generate') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            if (request.method !== 'POST') {
+                response.statusCode = 405;
+                response.end(JSON.stringify({ error: 'POST required' }));
+                return;
+            }
+            if (request.headers['x-feltdb-studio-token'] !== studioMutationToken) {
+                response.statusCode = 403;
+                response.end(JSON.stringify({ error: 'Invalid Studio token' }));
+                return;
+            }
+            try {
+                const chunks = [];
+                for await (const chunk of request)
+                    chunks.push(Buffer.from(chunk));
+                const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                if (!input.intent?.trim())
+                    throw new Error('An AI change request is required');
+                const current = await loadLocalDevelopmentContract();
+                const proposal = await generateConfiguredFlowProposal({ intent: input.intent, snapshot: current.snapshot, currentFlow: current.source });
+                response.end(JSON.stringify({ proposal }));
+            }
+            catch (error) {
+                response.statusCode = 400;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (pathname === '/_feltdb/publish') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            if (request.method !== 'POST') {
+                response.statusCode = 405;
+                response.end(JSON.stringify({ error: 'POST required' }));
+                return;
+            }
+            try {
+                const chunks = [];
+                for await (const chunk of request)
+                    chunks.push(Buffer.from(chunk));
+                const input = chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {};
+                const messages = [];
+                const result = await publishApplication({ dryRun: Boolean(input.dryRun), status: Boolean(input.status), yes: true, noBuild: true, environment: input.environment, approveDestructive: Boolean(input.approveDestructive), message: input.message, log: message => messages.push(message) });
+                response.end(JSON.stringify({ status: result.status, messages, version: result.revision?.revision_number, validation: result.validation, changes: result.diff?.changes, securityChanges: result.diff?.security_changes }));
+            }
+            catch (error) {
+                response.statusCode = 400;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
             return;
         }
         if (pathname === '/_feltdb/project') {
@@ -1375,6 +1889,9 @@ async function handleStudio(args, onReady) {
     const parameters = new URLSearchParams({ namespace, runtime });
     if (connectUrl)
         parameters.set('connect', connectUrl);
+    if (applicationId)
+        parameters.set('application_id', applicationId);
+    parameters.set('environment', environment);
     if (appUrl)
         parameters.set('app', appUrl);
     if (session.workspaceId)
@@ -1406,6 +1923,24 @@ Commands:
   diff [file]           Diff FlowSpec against the last deployed model
   deploy [file]         Validate, version, and deploy FlowSpec
   publish [file]        Build and publish/update a managed application
+  ai                    Open the canonical interactive local-AI workflow
+  ai --dry-run          Open an ephemeral preview-only AI session
+  ai model show         Show the selected local or user-provided model
+  ai model set          Select WebLLM or an OpenAI-compatible model
+  ai context            Show the secret-free contract grounding snapshot
+  ai proposals          List bounded proposals [--status/--environment/--json]
+  ai proposal <id>      Show canonical proposal, readiness, preview, and history
+  ai approve <id>       Approve a current preview [--yes]
+  ai review <file>      Validate and review a WebLLM flow proposal
+  ai apply <id>         Atomically apply an approved proposal [--yes]
+  proposals             List durable FeltDB application proposals
+  module list           List deterministic FeltDB modules
+  module inspect <id>   Inspect a resolved module semantic contract
+  proposals get <id>    Show a proposal and its lifecycle history
+  proposals diff <id>   Show contract and structured source impact
+  proposals approve <id> Approve a previewed proposal
+  proposals reject <id> Reject a proposed/validated/previewed proposal
+  sync                  Regenerate owned source from feltdb.flow
   studio               Launch FeltDB Studio (developer interface)
   server               Start self-hosted FeltDB server
   keys                 Manage API keys
@@ -1423,6 +1958,7 @@ Commands:
 Studio:
   feltdb studio                              Launch local Studio
   feltdb studio --connect <url>              Connect to remote instance
+    --application <id> --environment <name>  Select one application environment
   feltdb studio --port 7701 --no-open        Start on port 7701 without opening browser
 
 Server Options:
@@ -1444,6 +1980,13 @@ Connection:
   doctor      Check system health
   help        Show this help message
 
+Publish:
+  feltdb publish --dry-run                  Validate and preview without activation
+  feltdb publish --yes                      Publish to the configured environment
+  feltdb publish --status                   Compare local and active cloud versions
+  feltdb publish --environment staging      Override the configured environment
+  feltdb publish --approve-destructive-changes --yes
+
 Inspect Sub-commands:
   feltdb inspect              Show runtime overview
   feltdb inspect peers        Show connected peers
@@ -1467,6 +2010,7 @@ Examples:
   feltdb status
   feltdb dev
   feltdb build
+  feltdb publish --dry-run
   feltdb check
   feltdb inspect
   feltdb inspect peers