proteum 2.1.3-1 → 2.1.7

package/cli/runtime/commands.ts

@@ -10,7 +10,7 @@ class InitCommand extends ProteumCommand {
     public static usage = buildUsage('init');
 
     public name = Option.String('--name', { description: 'Human-readable app name.' });
-    public description = Option.String('--description', { description: 'App description used in identity.yaml and package.json.' });
+    public description = Option.String('--description', { description: 'App description used in identity.config.ts and package.json.' });
     public identifier = Option.String('--identifier', { description: 'Application class and identity identifier.' });
     public port = Option.String('--port', { description: 'Default local router port used in .env.' });
     public url = Option.String('--url', { description: 'Default absolute URL used in .env.' });
@@ -179,19 +179,43 @@ class CheckCommand extends ProteumCommand {
     }
 }
 
+class ConnectCommand extends ProteumCommand {
+    public static paths = [['connect']];
+
+    public static usage = buildUsage('connect');
+
+    public controllers = Option.Boolean('--controllers', false, {
+        description: 'Include imported connected controllers in the output.',
+    });
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public strict = Option.Boolean('--strict', false, { description: 'Exit with failure if any connect diagnostics exist.' });
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        const args = { controllers: this.controllers, json: this.json, strict: this.strict } satisfies TArgsObject;
+
+        applyLegacyBooleanArgs('connect', this.legacyArgs, ['controllers', 'json', 'strict'], args);
+        this.setCliArgs(args);
+        await runCommandModule(() => import('../commands/connect'));
+    }
+}
+
 class DoctorCommand extends ProteumCommand {
     public static paths = [['doctor']];
 
     public static usage = buildUsage('doctor');
 
+    public contracts = Option.Boolean('--contracts', false, {
+        description: 'Run contract-focused diagnostics for generated artifacts and manifest-owned source files.',
+    });
     public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
     public strict = Option.Boolean('--strict', false, { description: 'Exit with failure if any diagnostics exist.' });
     public legacyArgs = Option.Rest();
 
     public async execute() {
-        const args = { json: this.json, strict: this.strict } satisfies TArgsObject;
+        const args = { contracts: this.contracts, json: this.json, strict: this.strict } satisfies TArgsObject;
 
-        applyLegacyBooleanArgs('doctor', this.legacyArgs, ['json', 'strict'], args);
+        applyLegacyBooleanArgs('doctor', this.legacyArgs, ['contracts', 'json', 'strict'], args);
         this.setCliArgs(args);
         await runCommandModule(() => import('../commands/doctor'));
     }
@@ -207,6 +231,7 @@ class ExplainCommand extends ProteumCommand {
     public app = Option.Boolean('--app', false, { description: 'Include the app section.' });
     public conventions = Option.Boolean('--conventions', false, { description: 'Include the conventions section.' });
     public env = Option.Boolean('--env', false, { description: 'Include the env section.' });
+    public connected = Option.Boolean('--connected', false, { description: 'Include the connected-projects section.' });
     public services = Option.Boolean('--services', false, { description: 'Include the services section.' });
     public controllers = Option.Boolean('--controllers', false, { description: 'Include the controllers section.' });
     public commands = Option.Boolean('--commands', false, { description: 'Include the commands section.' });
@@ -215,14 +240,25 @@ class ExplainCommand extends ProteumCommand {
     public diagnostics = Option.Boolean('--diagnostics', false, {
         description: 'Include the diagnostics section.',
     });
-    public legacyArgs = Option.Rest();
+    public args = Option.Rest();
 
     public async execute() {
+        const [mode = '', ...restArgs] = this.args;
+        if (mode === 'owner') {
+            this.setCliArgs({
+                json: this.json,
+                ownerQuery: restArgs.join(' ').trim(),
+            });
+            await runCommandModule(() => import('../commands/explain'));
+            return;
+        }
+
         const args = {
             json: this.json,
             all: this.all,
             app: this.app,
             conventions: this.conventions,
+            connected: this.connected,
             env: this.env,
             services: this.services,
             controllers: this.controllers,
@@ -234,8 +270,8 @@ class ExplainCommand extends ProteumCommand {
 
         applyLegacyBooleanArgs(
             'explain',
-            this.legacyArgs,
-            ['json', 'all', 'app', 'conventions', 'env', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'],
+            this.args,
+            ['json', 'all', 'app', 'conventions', 'env', 'connected', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'],
             args,
         );
         this.setCliArgs(args);
@@ -322,6 +358,121 @@ class SessionCommand extends ProteumCommand {
     }
 }
 
+class DiagnoseCommand extends ProteumCommand {
+    public static paths = [['diagnose']];
+
+    public static usage = buildUsage('diagnose');
+
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public hit = Option.String('--hit', { description: 'Issue one HTTP request before diagnosing. Defaults to the target path when it starts with /.' });
+    public method = Option.String('--method', { description: 'HTTP method used with `--hit`.' });
+    public dataJson = Option.String('--data-json', { description: 'JSON request body used with `--hit`.' });
+    public sessionEmail = Option.String('--session-email', {
+        description: 'Mint a dev session before `--hit` and attach the returned cookie.',
+    });
+    public sessionRole = Option.String('--session-role', { description: 'Require the dev session user to have this role.' });
+    public capture = Option.String('--capture', { description: 'Trace capture mode armed before `--hit`.' });
+    public logsLevel = Option.String('--logs-level', { description: 'Minimum server log level included in the diagnose response.' });
+    public logsLimit = Option.String('--logs-limit', { description: 'Maximum number of server log lines included in the diagnose response.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [target = ''] = this.args;
+
+        this.setCliArgs({
+            capture: this.capture ?? '',
+            dataJson: this.dataJson ?? '',
+            hit: this.hit ?? '',
+            json: this.json,
+            logsLevel: this.logsLevel ?? '',
+            logsLimit: this.logsLimit ?? '',
+            method: this.method ?? '',
+            port: this.port ?? '',
+            sessionEmail: this.sessionEmail ?? '',
+            sessionRole: this.sessionRole ?? '',
+            target,
+            url: this.url ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/diagnose'));
+    }
+}
+
+class PerfCommand extends ProteumCommand {
+    public static paths = [['perf']];
+
+    public static usage = buildUsage('perf');
+
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public since = Option.String('--since', { description: 'Window used by `top` and `memory`, for example `today`, `yesterday`, or `1h`.' });
+    public baseline = Option.String('--baseline', { description: 'Baseline window used by `compare`.' });
+    public target = Option.String('--target', { description: 'Target window used by `compare`.' });
+    public groupBy = Option.String('--group-by', { description: 'Aggregate by `path`, `route`, or `controller`.' });
+    public limit = Option.String('--limit', { description: 'Maximum number of rows to print.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = 'top', target = ''] = this.args;
+
+        this.setCliArgs({
+            action,
+            baseline: this.baseline ?? '',
+            groupBy: this.groupBy ?? '',
+            json: this.json,
+            limit: this.limit ?? '',
+            port: this.port ?? '',
+            since: this.since ?? '',
+            target,
+            targetWindow: this.target ?? '',
+            url: this.url ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/perf'));
+    }
+}
+
+class VerifyCommand extends ProteumCommand {
+    public static paths = [['verify']];
+
+    public static usage = buildUsage('verify');
+
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public crosspath = Option.String('--crosspath', { description: 'Override the CrossPath reference app path.' });
+    public product = Option.String('--product', { description: 'Override the Unique Domains Product reference app path.' });
+    public website = Option.String('--website', { description: 'Override the Unique Domains Website reference app path.' });
+    public crosspathPort = Option.String('--crosspath-port', { description: 'Port used for the CrossPath validation server.' });
+    public productPort = Option.String('--product-port', {
+        description: 'Port used for the Unique Domains Product validation server.',
+    });
+    public websitePort = Option.String('--website-port', {
+        description: 'Port used for the Unique Domains Website validation server.',
+    });
+    public route = Option.String('--route', { description: 'Route loaded in both apps during validation.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = 'framework-change'] = this.args;
+
+        this.setCliArgs({
+            action,
+            crosspath: this.crosspath ?? '',
+            crosspathPort: this.crosspathPort ?? '',
+            json: this.json,
+            product: this.product ?? '',
+            productPort: this.productPort ?? '',
+            route: this.route ?? '',
+            website: this.website ?? '',
+            websitePort: this.websitePort ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/verify'));
+    }
+}
+
 export const registeredCommands = {
     init: InitCommand,
     create: CreateCommand,
@@ -331,11 +482,15 @@ export const registeredCommands = {
     typecheck: TypecheckCommand,
     lint: LintCommand,
     check: CheckCommand,
+    connect: ConnectCommand,
     doctor: DoctorCommand,
     explain: ExplainCommand,
+    diagnose: DiagnoseCommand,
+    perf: PerfCommand,
     trace: TraceCommand,
     command: CommandCommand,
     session: SessionCommand,
+    verify: VerifyCommand,
 } as const;
 
 export const createCli = (version: string) => {
@@ -356,11 +511,15 @@ export const createCli = (version: string) => {
     clipanion.register(TypecheckCommand);
     clipanion.register(LintCommand);
     clipanion.register(CheckCommand);
+    clipanion.register(ConnectCommand);
     clipanion.register(DoctorCommand);
     clipanion.register(ExplainCommand);
+    clipanion.register(DiagnoseCommand);
+    clipanion.register(PerfCommand);
     clipanion.register(TraceCommand);
     clipanion.register(CommandCommand);
     clipanion.register(SessionCommand);
+    clipanion.register(VerifyCommand);
 
     return clipanion;
 };

package/cli/scaffold/index.ts

@@ -1,11 +1,11 @@
 import fs from 'fs-extra';
 import path from 'path';
 import slugify from 'slugify';
-import yaml from 'yaml';
 import { UsageError } from 'clipanion';
 
 import cli from '..';
-import { ensureProjectAgentSymlinks } from '../utils/agents';
+import { loadApplicationIdentityConfig } from '../../common/applicationConfigLoader';
+import { ensureProjectAgentSymlinks, renderProjectInstructionGitignoreBlock } from '../utils/agents';
 import { runProcess } from '../utils/runProcess';
 import {
     createClientTsconfigTemplate,
@@ -18,6 +18,7 @@ import {
     createInitSummary,
     createPackageJsonTemplate,
     createPageTemplate,
+    createProteumConfigTemplate,
     createRouteTemplate,
     createRouterConfigTemplate,
     createServerIndexTemplate,
@@ -133,16 +134,16 @@ const defaultRouteFromSegments = (segments: string[]) => {
 const resolveRootServiceLeaf = (segments: string[]) => segments[segments.length - 1];
 
 const readIdentityConfig = (appRoot: string): TIdentityConfig => {
-    const identityFilepath = path.join(appRoot, 'identity.yaml');
+    const identityFilepath = path.join(appRoot, 'identity.config.ts');
     if (!fs.existsSync(identityFilepath)) {
-        throw new UsageError(`Missing identity.yaml in ${appRoot}. Run \`proteum init\` first or target a Proteum app root.`);
+        throw new UsageError(`Missing identity.config.ts in ${appRoot}. Run \`proteum init\` first or target a Proteum app root.`);
     }
 
-    const parsed = yaml.parse(fs.readFileSync(identityFilepath, 'utf8')) as Partial<TIdentityConfig> | null;
-    const identifier = typeof parsed?.identifier === 'string' ? parsed.identifier.trim() : '';
-    const name = typeof parsed?.name === 'string' ? parsed.name.trim() : '';
+    const parsed = loadApplicationIdentityConfig(appRoot);
+    const identifier = typeof parsed.identifier === 'string' ? parsed.identifier.trim() : '';
+    const name = typeof parsed.name === 'string' ? parsed.name.trim() : '';
 
-    if (!identifier) throw new UsageError(`identity.yaml in ${appRoot} is missing a valid "identifier" field.`);
+    if (!identifier) throw new UsageError(`identity.config.ts in ${appRoot} is missing a valid "identifier" field.`);
 
     return {
         identifier,
@@ -151,7 +152,7 @@ const readIdentityConfig = (appRoot: string): TIdentityConfig => {
 };
 
 const assertProteumAppRoot = (appRoot: string) => {
-    const expectedEntries = ['package.json', 'identity.yaml', 'client', 'server'];
+    const expectedEntries = ['package.json', 'identity.config.ts', 'proteum.config.ts', 'client', 'server'];
     const missing = expectedEntries.filter((entry) => !fs.existsSync(path.join(appRoot, entry)));
     if (missing.length > 0) {
         throw new UsageError(
@@ -459,21 +460,9 @@ const createServicePlan = ({
     const configExportName = `${configFileBase}Config`;
     const relativeServiceDir = path.join('server', 'services', ...segments);
     const relativeServiceFilepath = path.join(relativeServiceDir, 'index.ts');
-    const relativeServiceConfigFilepath = path.join(relativeServiceDir, 'service.json');
     const relativeConfigFilepath = path.join('server', 'config', `${configFileBase}.ts`);
     const propertyName = serviceImportName;
 
-    const serviceJson = JSON.stringify(
-        {
-            id: `${appIdentifier}/${serviceImportName}`,
-            name: `${appIdentifier}${serviceImportName}`,
-            parent: 'app',
-            dependences: [],
-        },
-        null,
-        4,
-    ) + '\n';
-
     return {
         files: [
             {
@@ -483,10 +472,6 @@ const createServicePlan = ({
                     className,
                 }),
             },
-            {
-                relativePath: relativeServiceConfigFilepath,
-                content: serviceJson,
-            },
             {
                 relativePath: relativeConfigFilepath,
                 content: createServiceConfigTemplate({
@@ -628,13 +613,17 @@ const createInitFilePlans = (config: TScaffoldInitConfig): TScaffoldFilePlan[] =
         }),
     },
     {
-        relativePath: 'identity.yaml',
+        relativePath: 'identity.config.ts',
         content: createIdentityTemplate({
             appName: config.name,
             appIdentifier: config.identifier,
             appDescription: config.description,
         }),
     },
+    {
+        relativePath: 'proteum.config.ts',
+        content: createProteumConfigTemplate(),
+    },
     {
         relativePath: '.env',
         content: createEnvTemplate({
@@ -644,7 +633,9 @@ const createInitFilePlans = (config: TScaffoldInitConfig): TScaffoldFilePlan[] =
     },
     {
         relativePath: '.gitignore',
-        content: createGitignoreTemplate(),
+        content: createGitignoreTemplate({
+            projectInstructionGitignoreBlock: renderProjectInstructionGitignoreBlock({ coreRoot: cli.paths.core.root }),
+        }),
     },
     {
         relativePath: 'eslint.config.mjs',

package/cli/scaffold/templates.ts

@@ -227,6 +227,8 @@ export const createServerTsconfigTemplate = () => `{
     },
     "include": [
         ".",
+        "../identity.config.ts",
+        "../proteum.config.ts",
         "../var/typings",
         "../node_modules/proteum/types/global",
         "../.proteum/server/services.d.ts",
@@ -235,19 +237,27 @@ export const createServerTsconfigTemplate = () => `{
 }
 `;
 
-export const createGitignoreTemplate = () => `node_modules
-.proteum
-.cache
-bin
-dev
-var
+export const createGitignoreTemplate = ({
+    projectInstructionGitignoreBlock,
+}: {
+    projectInstructionGitignoreBlock: string;
+}) => `node_modules
+/.proteum
+/.cache
+/bin
+/dev
+/var
+/proteum.connected.json
 .env
+
+${projectInstructionGitignoreBlock}
 `;
 
 export const createEnvTemplate = ({ port, url }: { port: number; url: string }) => `ENV_NAME=local
 ENV_PROFILE=dev
 PORT=${port}
 URL=${url}
+URL_INTERNAL=${url}
 
 # Optional trace settings
 # TRACE_ENABLE=true
@@ -306,28 +316,38 @@ export const createIdentityTemplate = ({
     appName: string;
     appIdentifier: string;
     appDescription: string;
-}) => `name: ${appName}
-identifier: ${appIdentifier}
-description: ${JSON.stringify(appDescription)}
-
-author:
-    name: ${appName}
-    url: localhost
-    email: team@example.com
-
-social:
-
-language: en
-locale: en-US
-maincolor: white
-iconsPack: light
-
-web:
-    title: ${JSON.stringify(appName)}
-    titleSuffix: ${JSON.stringify(appName)}
-    fullTitle: ${JSON.stringify(appName)}
-    description: ${JSON.stringify(appDescription)}
-    version: 0.0.1
+}) => `import { Application } from 'proteum/config';
+
+export default Application.identity({
+    name: ${JSON.stringify(appName)},
+    identifier: ${JSON.stringify(appIdentifier)},
+    description: ${JSON.stringify(appDescription)},
+    author: {
+        name: ${JSON.stringify(appName)},
+        url: 'localhost',
+        email: 'team@example.com',
+    },
+    social: {},
+    language: 'en',
+    locale: 'en-US',
+    maincolor: 'white',
+    iconsPack: 'light',
+    web: {
+        title: ${JSON.stringify(appName)},
+        titleSuffix: ${JSON.stringify(appName)},
+        fullTitle: ${JSON.stringify(appName)},
+        description: ${JSON.stringify(appDescription)},
+        version: '0.0.1',
+    },
+});
+`;
+
+export const createProteumConfigTemplate = () => `import { Application } from 'proteum/config';
+
+export default Application.setup({
+    transpile: [],
+    connect: {},
+});
 `;
 
 export const createInitSummary = (result: TScaffoldResult, config: TScaffoldInitConfig) => ({

package/cli/utils/agents.ts

@@ -11,6 +11,7 @@ import { logVerbose } from '../runtime/verbose';
 - TYPES
 ----------------------------------*/
 
+type TProjectInstructionArgs = { coreRoot: string };
 type TEnsureProjectAgentSymlinksArgs = { appRoot: string; coreRoot: string };
 
 type TAgentLinkDefinition = { projectPath: string; sourcePath: string; ensureParentDir?: boolean };
@@ -19,10 +20,12 @@ type TAgentLinkDefinition = { projectPath: string; sourcePath: string; ensurePar
 - CONSTANTS
 ----------------------------------*/
 
-// Project-local AGENTS entrypoints mapped to their framework-owned source files.
+// Project-local instruction entrypoints mapped to their canonical shipped source files.
 const projectAgentLinkDefinitions: TAgentLinkDefinition[] = [
     { projectPath: 'AGENTS.md', sourcePath: 'AGENTS.md' },
     { projectPath: 'CODING_STYLE.md', sourcePath: 'CODING_STYLE.md' },
+    { projectPath: 'diagnostics.md', sourcePath: 'diagnostics.md' },
+    { projectPath: 'optimizations.md', sourcePath: 'optimizations.md' },
     { projectPath: path.join('client', 'AGENTS.md'), sourcePath: path.join('client', 'AGENTS.md') },
     { projectPath: path.join('client', 'pages', 'AGENTS.md'), sourcePath: path.join('client', 'pages', 'AGENTS.md') },
     {
@@ -32,41 +35,107 @@ const projectAgentLinkDefinitions: TAgentLinkDefinition[] = [
     { projectPath: path.join('server', 'routes', 'AGENTS.md'), sourcePath: path.join('server', 'routes', 'AGENTS.md') },
     { projectPath: path.join('tests', 'e2e', 'AGENTS.md'), sourcePath: path.join('tests', 'AGENTS.md') },
 ];
+const projectInstructionGitignoreBlockStart = '# Proteum-managed instruction symlinks';
+const projectInstructionGitignoreBlockEnd = '# End Proteum-managed instruction symlinks';
 
 /*----------------------------------
 - PUBLIC API
 ----------------------------------*/
 
 export function ensureProjectAgentSymlinks({ appRoot, coreRoot }: TEnsureProjectAgentSymlinksArgs) {
-    const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
-    const agentLinks = projectAgentLinkDefinitions.map((linkDefinition) => ({
-        ...linkDefinition,
-        sourcePath: path.join(agentSourceRoot, linkDefinition.sourcePath),
-    }));
+    ensureSymlinks(appRoot, getProjectAgentLinkDefinitions({ coreRoot }), '[agents]');
+    ensureSymlinks(appRoot, getProjectSkillLinkDefinitions({ coreRoot }), '[skills]');
+    ensureProjectInstructionGitignoreEntries({ appRoot, coreRoot });
+}
+
+export function getProjectInstructionGitignoreEntries({ coreRoot }: TProjectInstructionArgs) {
+    const entries = new Set<string>();
 
-    ensureSymlinks(appRoot, agentLinks, '[agents]');
-    ensureProjectSkillSymlinks({ appRoot, coreRoot });
+    for (const linkDefinition of [
+        ...getProjectAgentLinkDefinitions({ coreRoot }),
+        ...getProjectSkillLinkDefinitions({ coreRoot }),
+    ]) {
+        entries.add(`/${normalizeProjectPathForGitignore(linkDefinition.projectPath)}`);
+    }
+
+    return Array.from(entries);
+}
+
+export function renderProjectInstructionGitignoreBlock({ coreRoot }: TProjectInstructionArgs) {
+    return [
+        projectInstructionGitignoreBlockStart,
+        ...getProjectInstructionGitignoreEntries({ coreRoot }),
+        projectInstructionGitignoreBlockEnd,
+    ].join('\n');
 }
 
 /*----------------------------------
 - HELPERS
 ----------------------------------*/
 
-function ensureProjectSkillSymlinks({ appRoot, coreRoot }: TEnsureProjectAgentSymlinksArgs) {
+function getProjectAgentLinkDefinitions({ coreRoot }: TProjectInstructionArgs) {
+    const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
+
+    return projectAgentLinkDefinitions.map((linkDefinition) => ({
+        ...linkDefinition,
+        sourcePath: path.join(agentSourceRoot, linkDefinition.sourcePath),
+    }));
+}
+
+function getProjectSkillLinkDefinitions({ coreRoot }: TProjectInstructionArgs) {
     const frameworkSkillsRoot = path.join(coreRoot, 'skills');
-    if (!fs.existsSync(frameworkSkillsRoot)) return;
+    if (!fs.existsSync(frameworkSkillsRoot)) return [];
 
-    const skillLinks: TAgentLinkDefinition[] = fs
+    return fs
         .readdirSync(frameworkSkillsRoot, { withFileTypes: true })
         .filter((dirent) => dirent.isDirectory())
+        .sort((left, right) => left.name.localeCompare(right.name))
         .map((dirent) => ({
             projectPath: path.join('skills', dirent.name),
             sourcePath: path.join(frameworkSkillsRoot, dirent.name),
             ensureParentDir: true,
         }))
         .filter((linkDefinition) => pathEntryExists(path.join(linkDefinition.sourcePath, 'SKILL.md')));
+}
+
+function ensureProjectInstructionGitignoreEntries({ appRoot, coreRoot }: TEnsureProjectAgentSymlinksArgs) {
+    const gitignoreFilepath = path.join(appRoot, '.gitignore');
+    if (!pathEntryExists(gitignoreFilepath)) return;
+
+    const managedEntries = getProjectInstructionGitignoreEntries({ coreRoot });
+    const managedNormalizedEntries = new Set(managedEntries.map(normalizeGitignoreEntry));
+    const lines = fs.readFileSync(gitignoreFilepath, 'utf8').split(/\r?\n/);
+    const filteredLines: string[] = [];
+
+    let insideManagedBlock = false;
 
-    ensureSymlinks(appRoot, skillLinks, '[skills]');
+    for (const line of lines) {
+        const trimmedLine = line.trim();
+
+        if (trimmedLine === projectInstructionGitignoreBlockStart) {
+            insideManagedBlock = true;
+            continue;
+        }
+
+        if (trimmedLine === projectInstructionGitignoreBlockEnd) {
+            insideManagedBlock = false;
+            continue;
+        }
+
+        if (insideManagedBlock) continue;
+        if (shouldSkipLegacyManagedGitignoreLine(line, managedNormalizedEntries)) continue;
+
+        filteredLines.push(line);
+    }
+
+    const baseContent = trimTrailingBlankLines(filteredLines).join('\n');
+    const managedBlock = renderProjectInstructionGitignoreBlock({ coreRoot });
+    const nextContent = baseContent ? `${baseContent}\n\n${managedBlock}\n` : `${managedBlock}\n`;
+
+    if (nextContent === fs.readFileSync(gitignoreFilepath, 'utf8')) return;
+
+    fs.writeFileSync(gitignoreFilepath, nextContent);
+    logVerbose(`[agents] Updated ${path.relative(appRoot, gitignoreFilepath) || '.gitignore'} with Proteum-managed instruction ignore entries.`);
 }
 
 function ensureSymlinks(appRoot: string, linkDefinitions: TAgentLinkDefinition[], logPrefix: string) {
@@ -81,7 +150,7 @@ function ensureSymlinks(appRoot: string, linkDefinitions: TAgentLinkDefinition[]
 
         const sourceFilepath = linkDefinition.sourcePath;
         if (!fs.existsSync(sourceFilepath)) {
-            throw new Error(`Missing framework asset: ${sourceFilepath}`);
+            throw new Error(`Missing project instruction asset: ${sourceFilepath}`);
         }
 
         const symlinkTarget = path.relative(projectParentDir, sourceFilepath);
@@ -91,6 +160,30 @@ function ensureSymlinks(appRoot: string, linkDefinitions: TAgentLinkDefinition[]
     }
 }
 
+function normalizeProjectPathForGitignore(projectPath: string) {
+    return projectPath.replace(/\\/g, '/');
+}
+
+function normalizeGitignoreEntry(value: string) {
+    return value.trim().replace(/#.*/, '').replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+function shouldSkipLegacyManagedGitignoreLine(line: string, managedNormalizedEntries: Set<string>) {
+    const normalizedLine = normalizeGitignoreEntry(line);
+    if (!normalizedLine) return false;
+    if (line.trim().startsWith('#')) return false;
+
+    return managedNormalizedEntries.has(normalizedLine);
+}
+
+function trimTrailingBlankLines(lines: string[]) {
+    const trimmedLines = [...lines];
+
+    while (trimmedLines.length > 0 && trimmedLines[trimmedLines.length - 1].trim() === '') trimmedLines.pop();
+
+    return trimmedLines;
+}
+
 function pathEntryExists(filepath: string) {
     try {
         fs.lstatSync(filepath);

package/cli/utils/keyboard.ts

@@ -23,7 +23,15 @@ class KeyboardCommands {
     }
 
     private listen() {
+        if (!process.stdin) return;
+
         readline.emitKeypressEvents(process.stdin);
+
+        if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function') {
+            logVerbose('Keyboard shortcuts disabled because stdin is not an interactive TTY.');
+            return;
+        }
+
         process.stdin.setRawMode(true);
         process.stdin.on('keypress', async (chunk: string, key: Key) => {
             let str = key.name;